App Builder Enterprise Application

BluePhoenix AppBuilder 2.0.3.
Enterprise Application Guide
BluePhoenix AppBuilder 2.0.3.1 Enterprise Application Guide November, 2002 Corporate Headquarters BluePhoenix Solutions Vlierwerf 7B 4704 SB Roosendaal The Netherlands +31 (0) 165 399 401 +31 (0) 165 396 308 fax www.bluephoenixsolutions.nl USA Headquarters BluePhoenix Solutions USA, Inc. 8000 Regency Parkway Cary, NC 27511 United States +1 919.380.5100 +1 919.380.5111 fax www.bluephoenixsolutions.com
1992-2002 BluePhoenix Solutions All rights reserved. BluePhoenix is a trademark of BluePhoenix Solutions. All other product and company names mentioned herein are for identification purposes only and are the property of, and may be trademarks of, their respective owners. Portions of this product may be covered by U.S. Patent Numbers 5,495,222 and 5,495,610 and various other non-U.S. patents. The software supplied with this document is the property of BluePhoenix Solutions, and is furnished under a license agreement. Neither the software nor this document may be copied or transferred by any means, electronic or mechanical, except as provided in the licensing agreement. BluePhoenix Solutions has made every effort to ensure that the information contained in this document is accurate; however, there are no representations or warranties regarding this information, including warranties of merchantability or fitness for a particular purpose. BluePhoenix Solutions assumes no responsibility for errors or omissions that may occur in this document. The information in this document is subject to change without prior notice and does not represent a commitment by BluePhoenix Solutions or its representatives.
TABLE OF CONTENTS
Table of Contents
AppBuilder 2.0.3.1 Enterprise Application Guide
Using the Enterprise Repository Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Accessing the Repository. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 ISPF/PDF Primary Option Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 System Options Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 Entities Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Using Enterprise Repository Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 List Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 Detail Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8 Pop-up Panels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10 Using the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11 Using Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11 Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13 Navigating the Enterprise Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14 ACTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14 PROJECTS Changing Your Project and Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17 ENTITY Listing Entity Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18 LE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18 LR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20 UPROF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20 Viewing Repository Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-22
Setting Enterprise Repository Security
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Using Object Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 Modifying Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Selecting a Current Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Creating Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 Updating Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 Deleting Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Summary of Access Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Using Method Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Locking Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Lock Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1
LOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 UNLOCK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 Accessing Locked Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Defining the Application Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Building Applications with the Information Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 Window View Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 Adding, Saving, and Deleting Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 ADDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 ADDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 DE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 DR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6 SA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7 SAVE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9 Maintaining Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9 ME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10 MR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10 S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10 TXE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11 TXR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11 K . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11 CO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12 Reusing Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13 EW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13 REP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14 SRCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15 Building Applications with Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16 Creating a Component to Use with a Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17 Using a Component with Another Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18 Accessing DB2 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18 Defining DB2 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19 Accessing Non-DB2 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20
Building Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Using Build Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1 ACTIVATE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 ASSIGNCU. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 BINDPKG. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 BTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4 DEACTIVE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5 DYNAMIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6 GD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6 LISTRBD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
ii
PR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9 Preparing Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9 Preparing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13 Preparing Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14 Preparing Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-16 Preparing Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-20 Preparing Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-22 Preparing Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-23 PSB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25 RB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26 RBD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-27 Relinking a Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-28 Rebinding a Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-29 Reinstalling a Rule into CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-30 RDTL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-31 RES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-32 RIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-33 STATIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-34 SUPERPR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-34 TE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-35 TRANS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-35 TS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-35 VER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-36
Writing CICS Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Designing CICS using AppBuilder Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1 Sample COBOL II Component Line Detail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 Sample COBOL II CICS Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3 Sample PL/I Component Line Detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4 Sample PL/I CICS Component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6 Component Communications Area (HPSCOMM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6 PL/I Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7 COBOL II Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8 BAL Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
Preparing CICS Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1

Understanding CICS Pseudoconversational Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1 Preparing an Entity for Multiple CICS Regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2 Using RBD to Relink a Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2 Using RBD to Reinstall a Rule to CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3 Using RIN to Reinstall Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
Table of Contents
iii
Determining Transaction IDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3 Determining DB2 Plan Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4
API for CICS (HPECAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

Using HPECAPI to Invoke AppBuilder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1 User COMMAREA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2 RULE-NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2 IV-NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2 IV-PTR/ADDRESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3 IV-FLENGTH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3 OV-NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3 OV-PTR/ADDRESS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3 OV-FLENGTH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3 HPS-USER-PARM-EYECATCHER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3 HPS-USER-PARM-FUNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 HPS-USER-PARM-SUBFUNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 HPS-USER-PARM-RET-CODE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 HPS-USER-PARM-USE-TERM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 HPS-USER-PARM-USE-TRAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5 HPS-USER-PARM-RET-TERM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5 HPS-USER-PARM-RET-TRAN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5 HPS-USER-PARM-ERR-MSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5 Interface Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5 CICS LINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5 CICS START. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7 CICS XCTL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11 CICS RETURN IMMEDIATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12
Preparing IMS Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1

Designing IMS Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1 Common IMS Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1 Writing and Processing IMS Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3 USE RULEINIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4 Run Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4 Configuring BMP and DL/I Batch Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11 IMS Actions and Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12 PSB - Generation Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12 Updating a Rules IMS Processing Details (RDTL) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13 IMS Run Control Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13 Message Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16 Rule Selection List: HPR0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18
10
Writing IMS Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

Accessing the IMS Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1 Mapping Input View Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2 Calling a PL/I Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2
iv
Sample Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2 Assembler Batch (using DB2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3 COBOL (using IMS AIB and Checkpoint Restart) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4 PL/I (Using IMS non-AIB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-9 Component Communications Area (HPSCOMM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-11
11
Using IMS Interfaces: HPECAPI and HPUCV10 . . . . . . . . . . . . . . . . . . . 11-1

Using IMS Interface Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1 LINK Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1 Function Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
12
Generating OpenCOBOL
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1
OpenCOBOL Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1 Compiler Requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1 Protocol Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2 Mapping Implementation Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2 Compatibility Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2 Configuring Middleware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2 Performance Marshaling for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-5 Host Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-5 VIEW Prepare. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6 SET Prepare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6 Rule Prepare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-7 Configuring the Initialization File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-8 Defining Options in the Initialization File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-8 OpenCOBOL Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-8 Rules Language Support and Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-9 3270 Converse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-9 Native COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-9 Large Decimals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-10 Component Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-10 Dynamic COBOL Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-10 Truncating Intermediate Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-10 TIMESTAMP Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-10 Mathematical Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-10
13
Writing Batch Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1

PL/I Component STAE Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1 Sample BAL Component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2 Sample C Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2 Sample COBOL Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3 Sample PL/I Component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4 Component Communications Area (HPSCOMM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4 PL/I Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4 COBOL II Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5 BAL Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-7 C Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-9
Table of Contents
14
Sample Batch Applications
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1
Batch DB2 Command Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1 Batch Command Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
15
Batch API for PLI and COBOL II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1

Using HPBCAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1 LINK Rule Initiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1 Static Link Initiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1 COBOL Dynamic Call Initiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-2 User Commarea. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-3 RULE-NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-3 IV-NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4 IV-PTR/ADDRESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4 IV-FLENGTH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4 OV-NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4 OV-PTR/ADDRESS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4 OV-FLENGTH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4 HPS-USER-PARM-EYECATCHER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4 HPS-USER-PARM-FUNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4 HPS-USER-PARM-SUBFUNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5 HPS-USER-PARM-RET-CODE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5 HPS-USER-PARM-USE-TERM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5 HPS-USER-PARM-USE-TRAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5 HPS-USER-PARM-RET-TERM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5 HPS-USER-PARM-RET-TRAN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5 HPS-USER-PARM-ERR-MSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5 Static Linkage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-6
16
Configuring Applications
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1
Using Configuration Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1 Understanding Configuration Objects and Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2 Setting Configuration Object Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-3 Relating Preparable Entities to a Partition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-6 Preparing for Multiple Execution Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-6 DB2 Subsystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-7 Changing the Qualifier of DB2 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-8 Changing the Owner of DB2 Plans and Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-9 Changing the Isolation Mode for DB2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-10 Using DB2 Packages and Plans. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-10 Binding with Packages and DBRMs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-11 Setting INI Variables for DB2 Qualifier/Owner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-12 INI Variables and DB2 Binds using Partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-13 INI Variables and DB2 Binds without Partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-19 Examples of DB2 INI Settings without Partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-23
vi
17
3270 Converse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1

Executing 3270 Converse in CICS and IMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1 CICS Execution Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1 IMS Execution Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2 Prerequisites for 3270 Window Painter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2 Sharing Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2 National Language Support/Multiple Language Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2 Host Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-3 Window Prepare (PR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-3 Results (RES) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-4 Preparing Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-5 Rule Prepare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-5 Hybrid Rule Execution Environments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-5 HPC7 Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-6 HPR0 Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-6 3270 Converse Application Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-6 3270 Converse Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-8 Input Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-9 Multicolumn List Box Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-10 Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-10 Error Messages for 3270 Converse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-11 Help for 3270 Converse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-12 Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-12 Memory Management Tips. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-12 Using HPECAPI in 3270 Converse Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-15 Converse Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-15 Deferred Converse Components Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-15
18
Advanced Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1

Linking Run-time Entities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1 Dynamic Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1 Static Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2 Run-time Communications Protocols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-3 LU2 vs. LU6.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-3 Passing Messages using Global Eventing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4 Posting Rule Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4 Posting Rule Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5 Receiving Rule Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5 Receiving Rule Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5 Defining Repository Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-6 UEMTH and URMTH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-6
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i
Table of Contents
vii
viii
CHAPTER
USING THE ENTERPRISE REPOSITORY INTERFACE

The enterprise repository interface of the Host Workbench lets you access the objects in an enterprise repository. You can navigate within the enterprise repository by moving from object to objectthat is, from panel to panel. To find a specific object in the repository, use one of the following methods: Select its name or system identifier from an alphabetical list of all the objects of its type in the repository Starting from one object, traverse a chain of entities and relationships connected to the object Search for an object based on its keywords You typically navigate through the repository by traversing the Information Model, panel by panel. For example, you can move from a rule to a report it converses, and you can move from a field to a view that includes that field. You can also use the repository interface to produce reports about your applications.
Accessing the Repository

Accessing the enterprise repository involves two steps: 1. 2. From the ISPF/PDF Primary Option menu (Figure 1-1), select the option for AppBuilder to display the System Options panel (Figure 1-2). From the System Options panel, select the option for the enterprise repository to display the Entities panel, which lists all the entity types in the repository (Figure 1-3).
ISPF/PDF Primary Option Menu

Access the enterprise repository through the Interactive Structured Programming Facility/Program Development Facility (ISPF/PDF) Primary Option menu (Figure 1-1). On the command line, type the letter used to access the enterprise repository and press Enter. You specify this letter when you install the AppBuilder (it is H in the example). The System Options panel is then displayed.
1-1
Figure 1-1
ISPF/PDF Primary Option Menu
System Options Panel

The System Options panel (Figure 1-2) is your entry point to the enterprise repository. The number of options available depends on your installation. To access the enterprise repository, select option 1 (ER) from the System Options panel and press Enter to display the Entities panel (Figure 1-3).
1-2
Using the Enterprise Repository Interface
Figure 1-2
System Options Panel
Entities Panel
The Entities panel (Figure 1-3) lists all entity types in the enterprise repository. Relationships are not included on the Entities panel because they pertain only to the entities they connect. You can access a particular relationship, or list of pertinent relationships, by navigating from a specific entity. The Entities panel is the first panel in the enterprise repository interface, and you can view it at any time by typing ENTITY at the command line of any repository interface panel.
1-3
Using Enterprise Repository Panels
Figure 1-3
Entities Panel

The enterprise repository interface includes three types of panels:
Table 1-1 Enterprise Repository Panel Types
List Panels Detail Panels Pop-up Panels
Display a list of either entity or relationship instances Display the attributes of a particular entity or relationship instance Solicit information needed to process repository actions; seek confirmation of actions, such as delete; and display information such as error and other messages
List Panels
There are two kinds of list panels: Entity List Panels and Relationship List Panels. To scroll the entries in a list, in addition to the default function keysF7 to scroll up, F8 to scroll downyou can also use the following standard ISPF/PDF commands: TOP, BOTTOM, UP, DOWN, and L (locate).
Entity List Panels

An entity list panel displays a list of instances of a specific entity typeall the rules in a repository, for example. To access an entity list panel: 1. Type LE next to the entity type on the Entities panel. Figure 1-4 shows Rule being selected.
1-4
Figure 1-4
Select Entity to be Listed
LE
2.
On the Action Information pop-up panel that appears (Figure 1-5 on page 1-5), specify how you want the list of instances to appearfor example, sorted by name or system ID, in ascending or descending order. Note that with your user profile, you can suppress the Action Information pop-up panel (see UPROF on page 1-20). If it is suppressed, then the list of entities is displayed as you specify in your user profile.
Figure 1-5
Setting List Specifications
An entity list panel displays in columns all attribute values of each entity instance. To display columns not visible, press F10 to scroll left, or F11 to scroll right. To display more entity instances, press F8 to scroll down or F7 to scroll up. Figure 1-6 shows an example of an entity list panel. It lists a page of rules from the enterprise repository in ascending order by name.
1-5
Figure 1-6
Entity List Panel for Rules
Relationship List Panels

A relationship list panel displays a list of relationships between a specific entity and some or all of the entities to which it is related. You normally access a relationship list panel from an entity list panel. 1. On the entity list panel, type LR in the Action field beside the entity instance whose relations you want to view and then press Enter. Figure 1-7 shows view ACCOUNT_LST being selected.
Specifying Entity Relationships
Figure 1-7
LR
2.
The Relation Options panel is displayed. Type S in the Select field for the relation type(s) you want to view and then press Enter. Figure 1-8 on page 1-7 shows a Relations Options pop-up panel on which two relationship types are selected.
1-6
Figure 1-8
Relation Options Panel
3.
A Relation List panel is displayed. If you select only one relationship, the Relation List panel looks like Figure 1-9. You can use a function key (F10 and F11) to scroll through the relationship attributes, which are shown in columns on the right side of the panel.
Relation List Showing a Single Relationship Type
Figure 1-9
If you select multiple relationships, the Relation List panel looks like Figure 1-10. When multiple relationships are displayed, the relationship attributes are not displayed because not all attributes are common to all relationships (however, you can use F10 and F11 to view the system ID or name).
1-7
Figure 1-10
Relation List Showing Multiple Relationship Types

AppBuilder Relation List for Entity View
Command ===> _______________________________________________________________
Repository: DEVRISE Entity Name: VIEWTE1
V: 1
Project: DEV
Level: 3
Action
Relation Type
Name FIELD1A FIELD1B
________ Includes Field ________ Includes Field
________ Owned-By Rule RBATCH1 ******************************* BOTTOM OF DATA ********************************
Detail Panels
For each object in the enterprise repository, you can access a detail panel that displays all of the available information about a selected entity or relationship instance. Figure 1-11 shows an entity detail panel, and Figure 1-12 shows a sample relationship detail panel for the uses-rule relationship. (The level number changes depending on when each panel is displayed. Level numbers are explained in Levels on page 1-13.) Detail panels display the available detailed information about a selected entity or relation instance. These panels are accessed using the commands: BE (browse entity) BR (browse relationship) ME (maintain entity) MR (maintain relationship) Chapter 4, Defining the Application Model provides specific information on these commands. Figure 1-11 shows an entity detail panel from a BE (browse entity) command for a Rule entity.
1-8
Figure 1-11
Detail Panel for Browsing Entities
Figure 1-12 shows a relationship detail panel from a BR (browse relation) command for an Owns View relationship.
Figure 1-12 Detail Panel for Browsing Relations
Displaying Multiple-Choice Options

If a panel contains an option for which multiple choices are possible, by default only the selected choice is displayed. For example, in Figure 1-11 on page 1-9 only choice 1IBM Mainframe (CICS)is shown for the Execution Environment option. You can use the EXPAND action to display all the choicesthe option domainas shown in Figure 1-13. Use the COLLAPSE action to display a single choice. Another way to display all the choices is to type an obviously invalid choice, such as ? in the field, which results in the panel showing the domain for that option.
1-9
Figure 1-13
Detail Panel for Maintaining Entities
More Indicator
Some panels have a More indicator in the upper right corner, indicating additional data (for example, see Figure 1-13 on page 1-10). The More indicator appears only when a fixed amount of data is displayed. The More indicator is displayed in one of three ways, as shown in Table 1-2.
Table 1-2 More Indicator Display Options Description More information is present below the current panel. To view it, press F8 to scroll down. More information is present above and below the current panel. Press F7 to scroll up, or press F8 to scroll down. More information is present above the current panel. To view it, press F7 to scroll up. Indicator More + More - + More -
Pop-up Panels
A pop-up panel is displayed in front of a list panel or detail panel. You cannot continue with the list panel or detail panel until you close the pop-up panel. There are several types of pop-up panels: Projects When you type PROJECTS at the command line, a pop-up panel lists the projects to which you have access. You can select a project as your new project, or exit to retain your current project. See PROJECTS Changing Your Project and Version. Actions When you type ACTIONS at the command line, a pop-up panel lists the actions available for a particular entity type. You can select an action you want to perform. (See ACTIONS.)
1-10
Action Information This panel is displayed whenever AppBuilder needs additional information to carry out an action. For example, when you type LE to list instances of an entity type, an action information pop-up panel allows you to tailor the list. (See LE.) When you type ADDE or ADDR to add an entity instance or entity relationship, an action information pop-up panel lets you specify information that all entities and relationships must have. See Adding, Saving, and Deleting Objects on page 4-3. Action Confirmation When you type DE or DR to delete an entity or relationship, a pop-up panel asks you to confirm the deletion.
Using the Command Line

Use the command line of an enterprise repository panel to enter an action or command string. Actions entered on the command line of a list panel are global actions that apply to the enterprise repository as a whole. Actions entered on the command line of a detail panel can be either global actions or actions specific to the object being edited. (See UPROF for more information.) To execute a TSO command or an AppBuilder action, move the cursor to the command line, type a command, and press Enter. Note
Your ISPF profile determines whether the command line is on the bottom or the top of the panel.
Using Function Keys

Function keys (PF keys) are single keys you use to issue commands, such as Refresh, Help, Exit, Cancel, Keys, and Prompt. You can also issue these commands from the command line. You can define your function keys to issue any of the following commands:
Table 1-3 Function Key Options
All methods Cancel Save
Sets any method command displayed with the Actions command Exits a full panel edit (such as ADDE or ME) without saving and returns to the previous panel Saves the data on an edit panel to the database
Table 1-4 shows the default function-key assignments. The first 12 keys are standard for ISPF. The remaining keys are specific to AppBuilder. These keys are active for the duration of the dialog; however, they may not be applicable to specific dialog panels. If a key is not available for a given panel, a Command not available message is displayed.
1-11
Table 1-4 Key F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 F15 F16 F17 F18 F19 F20 F21 F22 F23 F24
Default Function-key Commands Command Help Split End Return Rfind Rchange Backward Forward Swap Left Right Retrieve Actions Entity Collapse Expand Projects Save As Refresh All Print Clear UndoClr Cursor Description Displays help for the current panel. Splits panel into two windows. Returns you to the previous panel. Returns you to the primary entities panel. Repeats the previous Find command. Copies (repeats) changes you make to an object. Scrolls back (up) one full panel. Scrolls forward (down) one full panel. Toggles between two panels on a split panel. Scrolls the current panel to the left. Scrolls the current panel to the right. Retrieves the last user command. Displays the available action list for a given entity or relation. Displays the entity list. Collapses expanded field domains definitions, displaying only the selected type. Expands collapsed field definitions to display all domains. Displays a pop-up panel listing the projects to which an administrator has given you access. Saves the current entity as a new entity by using the existing entitys attributes as a template. Lets you undo changes before saving by restoring from the database an entitys attributes that you overtyped. Selects all possible choices from a selection list. Prints a results file to a host printer. Clears fields that users can edit. Resets all fields to the values that existed prior to executing a Clear command (F22). Places the cursor on the command line.
Use the commands listed in Table 1-5 to tailor your function key settings. The PFSHOW command is a standard ISPF command that controls whether and how function-key assignments are displayed.
1-12
Table 1-5
Commands for Tailored Function-key Settings Description Displays the settings of the function keys. This is a standard ISPF command. Turns the display of function keys off. This is a standard ISPF command. Displays a customization panel that lets you tailor which set of function keys is displayed, the number of keys to be displayed, and the number of keys displayed per line. This is a standard ISPF command. Lets you change your function key definitions to any selected set of commands. Default function keys are set the first time you enter into host dialog, so these customized key settings remain in effect in subsequent sessions. This is a standard ISPF command. Reports the current setting of the Autosave options. This is an AppBuilder command. Saves automatically when exiting any edit. Any failed edit checks are displayed, and you can correct or cancel the changes by typing CANCEL on the command line. This is an AppBuilder command. Does not save changes during edits. If you update the data, you are prompted to save or cancel the pending changes. You can leave an edit without saving changes by typing CANCEL on the command line any time prior to saving the data. This is an AppBuilder command.
Command PFSHOW ON PFSHOW OFF PFSHOW TAILOR
KEYS
AUTOSAVE AUTOSAVE ON
AUTOSAVE OFF
Levels
At the top of each panel in the repository interface is an indicator of the level of the panel. The initial Entities panel of the repository interface is at level 1. Each time you open a new panel from an active panel, the level number increases one. Each time you close a panel to return to the previous one, the level number decreases one. For example, if you issue the LE (list entities) command for a Rule entity type from the Entities panel (level 1), the panel showing the list of rule instances is at level 2. If you then issue the ME (maintain entity) command for one of the rules from the list of rule instances, the panel showing the details of that rule is at level 3. A high number of nesting levels causes the repository interfaces performance to slow.
Command Error Messages

If an error occurs or the system does not understand the command, the system displays a message directly below the command line. Refer to the Messages Reference Guide for descriptions of individual messages.
1-13
Navigating the Enterprise Repository

You can enter repository actions at the command line of any repository panel. Type ACTIONS to display a list of actions that are valid for the current panel. An action you enter at the command line is independent of the repository panel from which you enter it. For example, if you enter LR (list relationships) at a list panels command line, then even if the panel displays only one entity, the LR action does not apply to that entity. A pop-up panel prompts you for the name of the entity whose relationships you want to list. By contrast, when you type an action next to the name of an entity type or instance on a list panel, the action applies to that type or instance. This process allows you to navigate the enterprise repository using the following procedure: 1. 2. 3. List entity types in the repository. Type LE (list entity instances) next to an entity type to display a list of instances of that type. Type an action next to an entity instance, or type ACTIONS to obtain a list of available actions. Typical actions include: ME (maintain entity) to view and change the attributes of that entity instance. ADDR (add relationship) to establish a relationship between that instance and another entity instance. LR (list relationships) to list the relationships the entity instance has to other objects. From the list of relationships, you can enter MR (maintain relationship) to view and change the attributes. The process of listing objects and performing actions is repeatable. For example, you can list all the fields that a particular view contains and then for one of those fields you can list all the views that contain it. So, by alternately listing entities and their relationships you can navigate to all the entities and relationships in an enterprise repository.
ACTIONS
There are two kinds of actions available to you in the enterprise repository: Global Actions - Actions that pertain to the entire enterprise repository. Object-specific Actions - Actions that apply to a specific object. Note
In previous releases of AppBuilder, a distinction was made between methods and actions. This distinction is no longer applicablethe two terms are used interchangeably.
Global Actions
If you type ACTIONS from the command line of any panel, an Available Actions panel displays (Figure 1-14) listing all available global actions.
1-14
Figure 1-14
Global Actions Panel
Table 1-6 lists the available global actions. Global actions can also have entity-specific actions, if an object is in context.
Table 1-6 Global Actions Action ACTIONS AUTOSAVE DEBUG ENTITY INIDISP PROJECTS SRCH UPROF Lists available actions. Allows a user to turn autosave on or off. When autosave is on, changes to an object are saved when the panel on which the changes are made is closed. Displays an updatable profile of debug settings. Displays an Entity List panel listing all the entity types in the repository. Displays AppBuilder INI files in read-only mode. Displays a list of projects to which the user has access, and allows the user to change projects. Displays the Search-for-Keywords panel. Displays the users current profile settings and allows them to be changed. Description
Object-specific Actions
If you type ACTIONS next to the name of an object instance or object type on any list panel, an Available Actions panel displays listing the available actions for the selected object type or object instance. If the actions available cannot fit on one panel, you can use function keys to scroll forward to see them. Figure 1-15 shows a sample Available Actions panel listing object-specific actions.
1-15
Figure 1-15
Object-specific Actions Panel
Select an action by typing the action identifier (for example, ADDE or EW) on the command line of the pop-up panel and pressing Enter. Table 1-7 shows the object-specific actions available in an enterprise repository for developing AppBuilder applications.
Table 1-7 Object-specific Actions Action ACTIONS ACTIVATE ADDE ADDR ASSIGNCU BE BK BR BINDPKG BTXE BTXR CO DE DR DYNAMIC EW GD K LE LISTRBD LOCK LR ME Description List available actions for object type or object instance. Activate a partition. Add an entity to the repository. Add a relation. Assign a preparable entity to the active partition. Browse entity attributes. Browse object keywords Browse relation attributes Bind DB2 package Browse text for an entity Browse text for a relation Change owner Delete an entity Delete a relation Establish dynamic linkage Extended where-used report Generate DDL for a file Define keywords List entity instances List Rebuild contents Lock an entity List relation instances Maintain entity attributes
1-16
Table 1-7
Object-specific Actions (Continued) Action Description Maintain relation attributes Prepare an entity Prepare process execution environment in background. See page 5-14. Modify PSB (IMS) Rebind DB2 plan for a component Relink a rule, rebind its DB2 plan, and reinstall into CICS Update IMS processing details Refresh a panel with an objects attributes from the repository. See page 1-11. Produce report Display preparation results Reinstall a component into CICS Save as Search for keywords Establish static linkage Superprepare Test a batch entity Assign a CICS transaction code to a rule Transaction switch Define text for entity Define text for relation Run a user-written method for an entity Unlock an entity Verify a hierarchy
MR PR PRB PSB RB RBD RDTL REFRESH REP RES RIN SA SRCH STATIC SUPERPR TE TRANS TS TXE TXR UEMTH and URMTH UNLOCK VER
PROJECTS Changing Your Project and Version

Whenever you work with an enterprise repository, you must select a project to work inyour current project. Because a project exists within a version of the repository, the project you select determines the version and the objects to which you have access. The selected project is used for auditing when you create an update objects. Your access to objects depends on your cumulative authorization to the various projects. Your current project and version are displayed at the top of repository interface panels. To select a project as your current project, type PROJECTS at the command line of any repository interface panel. You are presented with a list of all the projects to which an administrator has given you access (Figure 1-16). The list shows in what version of the repository the project exists (and thus the version you can access). Enter any character next to the project to select it. For more information on projects and versions, see Chapter 2, Setting Enterprise Repository Security
1-17
Figure 1-16
Projects Selection Panel
Each time you quit working with the enterprise repository, your user profile remembers your current project the next time you use the repository interface.
ENTITY Listing Entity Types

The first panel of the enterprise repository interface is the Entities panel, which lists all the types of entities to which your current project gives you access. You can display the Entities panel at any time by typing ENTITY at any repository panels command line. Note
Your position in the Entities panel is saved in your user profile and restored the next time you log on to AppBuilder.
From the Entities panel, you can: List entities of a particular type (see LE). Add an entity instance of a particular type, or add a relationship to an entity of a particular type (see Adding, Saving, and Deleting Objects on page 4-3). List relationships of an entity of a particular type (see LR). Perform any action or method on an instance of an entity type. If you enter an action or method next to the entity type in the Entities panel, you are prompted for the name of the instance to which the action or method applies, unless prompting is turned off.
LE
Type LE (list entity instances) next to an entity type in the Entities panel to list all the instances of that type. When you press Enter, an Action Information pop-up panel appears (Figure 1-17) on which you can tailor the list of entity instances. If you simply press Enter without entering information, your list contains all instances of the entity type. For information on saving the choices you make on the Action Information panel, and for using those choices subsequently without having to retype them on the popup panel, see UPROF on page 1-20. Note
If you receive a DB2 error during the List Entity or List Relations actions, issue the REFRESH command. At the time of the error, ISPF has control of the panel and does not accept any responses from the program (see ISPF/PDF Primary Option Menu).
1-18
Tailoring the List of Entity Instances

When you list entity instances, you can tailor the list using the Action Information pop-up panel in Figure 1-17.
Figure 1-17 Action Information Pop-up Panel
After typing your choices, you can: Type SAVE from the command line to save your choices in your user profile for subsequent use. Press Enter to close the pop-up panel and cause the list to be displayed, tailored as you specified The Action information pop-up panel contains the following fields: Use Specifies whether the list is sorted by entity name or system ID. Whichever field the list is sorted by is displayed as the first column of the list. Name/System ID Determines the first entry displayed in the list of instances. If you specify a character string in this field, the first entry is the one whose name or system ID (depending on which you choose in the Use field) is greater-than-or-equal-to the string you specify. Although you can specify any length stringeven a single characterfor performance reasons you should specify more than one character to facilitate the search. No matter what entry is displayed first, you can scroll up to see earlier entries in the list. This option applies only if you set Prompt for Input on in your user profile. Sort Order Specifies whether the list is sorted in ascending or descending order. Like Name/System ID Limits the entries in the list of instances. Only instances whose name or system ID matches the pattern you specify are listed. You can use the following wild-card characters in your pattern: % _ Matches any string of zero or more characters Matches any one character
For example, entering %T3 lists only those instances whose name or system ID begins with zero or more characters followed by T3. Entering B_C lists those instances whose name or system ID begins with a B followed by exactly one character, followed by C. This option applies only if you set Prompt for Input on in your user profile.
1-19
Note that AppBuilder adds an implicit % to the end of whatever you type in this field so that all entities are listed whose name or system ID begins with the characters you type, followed by any other characters. Prompt for Input Suppresses the Action Information pop-up panels. If you choose No, the panel is not displayed subsequently. Lists are tailored according to the criteria last saved in your user profile. To view Action Information pop-up panels again, type UPROF from the command line of any repository interface panel and select Yes on the Prompt for Input field. For more information, see UPROF on page 1-20.
LR
Use the LR action to list relationship instances for any entity instance in the enterprise repository. Type LR next to an entity type in the Entities panel and the repository interface prompts you for the instance name. Or you can type LR next to the name of an instance in a list of entity instances. The Relation Options pop-up panel is displayed (Figure 1-18) that identifies all the relation types the entity instance participates in. You can select one, several, or all types for display. Type any character next to a relationship to select it. Type ALL on the command line to list all relationship entities and their relationship type for a given entity. The resulting panel is a relationship list panel.
Figure 1-18 Relation Options pop-up panel
UPROF
The User Profile panel allows you to save the information you type on an Action Information pop-up panel. Type SAVE at the command line. The information is saved in your user profile. Once saved, the repository interface pre-fills fields on subsequent Action information panels and in performing actions. On the Action Information panel that appears (Figure 1-19), specify how you want the list of instances to appearfor example, sorted by name or system ID, in ascending or descending order. To view the current values in your user profile, type UPROF at the command line of any panel.
1-20
Figure 1-19
User Profile in Action Information Panel
The user profile panel prompts you to input the following values: Use Action Name/System ID Sort Order Like Name/System ID Version Prompt for Input LR - Display Existing Relations The value of VER (Version) determines which version entities are listed and created in. This field is protected on the panel unless your current project is associated with version A (for all versions), in which case you choose a version. If your current project is not associated with version A, this field is protected because you can list and create objects only in the version with which your current project is associated. (For more information on versions and projects, see Chapter 2, Setting Enterprise Repository Security). LR displays existing relations that have been defined for the user profile.
1-21
Viewing Repository Objects
Viewing Repository Objects

A number of methods allow you to view repository objects without risk of modifying them. The following methods allow you to look at objects in read-only mode: B BE BK BR BTXE BTXR
B
The Browse Source action displays an entitys source code in read-only mode.
BE
The Browse Entity Attributes action displays an entitys attributes in read-only mode.
BK
The Browse Keywords action displays an objects keywords in read-only mode.
BR
The Browse Relationship Attributes action displays a relations attributes in read-only mode.
BTXE
The Browse Text for an Entity action displays an entitys text in read-only mode.
BTXR
The Browse Text for a Relation action displays a relations text in read-only mode.
1-22
CHAPTER
SETTING ENTERPRISE REPOSITORY SECURITY
Enterprise repository security prevents unauthorized modification of objects in the repository. Repository security includes: Using Object Security What objects in the repository you can act on Using Method Security What actions you can perform on those objects Contact your System Administrator if you need access to objects or methods that you cant access now. The next chapter, Chapter 3, Locking Objects discusses a form of object security that is under your control without administrator assistance. For detailed information and instructions on setting security parameters for your enterprise, see the Enterprise Administration Guide.
Using Object Security

Object security controls what you can do in a repository by controlling: Access type The type of access (create, read, update, delete) you have to objects in the repository Entity type The type of objects you can access
2-1
Modifying Objects
There are four kinds of actions available to modify objects in a repository: Create Read Update Delete Table 2-1 classifies all repository actions and methods by the type of access to objects required for each..
Table 2-1 Access Types Action ADDE (add entity) ADDR (add relationship) SA (save as) All actions other than those listed under Create, Update, and Delete require Read access CO (change ownership) K (define keywords) ME (maintain entity) MR (maintain relationship) P(Prepare method) S (source) TXE (define text for entity) TXR (define text for relationship) Access type Create Read
Update
Delete
DE (delete entity) DR (delete relationship) Read access depends upon both the repository version and the project.
Note
Selecting a Current Project

A project defines a subset of objects belonging to a version. Projects provide the ability to group the objects in a version according to function, security level, or whatever category you want. Typically a version contains more than one project. When you use an enterprise repository, you must select a project as your current project (see ACTIONS on page 1-14). The project you select determines your current versionthe version you are working in. When you list objects in a repository (using the LE or LR actions), you can see all the objects in the current version and have read access to all the objects in the projects in the current version that you have access to. Although most projects give you access to just one version, there is a special version that gives you access to objects in all versions of a repository. This version is called version A for all versions. If you select a project in version A, you have access (based on your authorization level) to all objects in all versions. See the Enterprise Administration Guide for detailed information about security and versioning in repositories.
2-2
Project Types
In addition to governing what you can see in a repository by granting you access to particular versions, projects determine what you can see in another way. Each project provides a view of a repository. That is, each project allows you to see only a subset of all the entity types in a repository. All the projects mentioned so far provide a development view of a repository. They allow you to see the AppBuilder entities of interest to a developer, such as rules, views, and fields. There are other types of projects that give a different view of a repository. For instance, an ADM project lets users of that project see only the entities of interest to an administrator, such as users, other projects, and groups. Like other projects, ADM projects provide a view of a particular version, or of all versions, of a repository. Only the person who installed the AppBuilder Environment, or another administrator, can give you access to an ADM project. Table 2-2 shows all the types of projects and the view of the repository that they provide.
Table 2-2 Project Type Views View type Development Information Model Administration Information Model Security Information Model Software Distribution Model Project type DEV ADM SEC SDS
Creating Objects
Except for auditors (who have only read access to repository objects), projects give you the ability to create objects as well as to read and update them. You can create an object only in your current project but you can change the project to which an object belongs using the CO (change owner) action. You can create an object in any version of the repository to which you have access. If your current project is associated with version A when you create an object, you are prompted to specify the version it is to be created in. If prompting is off, the version is determined from your user profile.
Updating Objects
The objects you can update in a version of a repository depend on the following factors: Owner Creating an object makes you the objects owner. Ownership can be changed using the CO (change owner) action. Project Your ability to update an object depends in part on what your current project is, the projects an administrator has given you access to, and the project the object you want to update belongs to. Authorization level When an administrator gives you access to a project, the administrator assigns you an authorization level in that project. An authorization level is a set of privileges relative to objects in a project. All projects have four authorization levels: programmer, analyst, project leader, auditor.
2-3
Table 2-3 shows how owner, project, and authorization level determine whether you are permitted to update an object in a version of the repository to which you have access.
Table 2-3 Update Permission Options Object you own in a project you can access yes yes yes no Someone elses object in a project you can access no yes yes no Object in a project you cant access no no no no Authorization level in project Programmer Analyst Project Leader Auditor
Deleting Objects
Table 2-4 shows how owner, project, and authorization level determine whether you are permitted to delete an object in a version of the repository to which you have access.
Table 2-4 Delete Permission Options Object you own in a project you can access yes yes yes no Someone elses object in a project you can access no no yes no Object in a project you cant access no no no no Authorization level in project Programmer Analyst Project Leader Auditor
Summary of Access Types

Table 2-5 summarizes what kind of access you can have to objects in the repository.
Table 2-5 Access Types Object you own in a project you can access CRUD CRUD CRUD R R=Read Someone elses object in a project you can access R RU RUD R U=Update Object in a project you cant access R R R R D=Delete Authorization level in project Programmer Analyst Project Leader Auditor C=Create
Note
When you don't have access to the project you can only view an entity or relation using the List Entity (LE) or List Relation (LR) action.
2-4
Using Method Security

In addition to limiting the types of access a user can have to objects in the repository, you can limit the type of objects a user can access. For example, an administrator can prohibit certain users from creating, updating, or deleting fields, even though they can create, update, and delete objects of any other entity type (as long as they satisfy the other criteria of ownership, project, and authorization level). For users of previous versions of AppBuilder, note that restricting actions by the type of entity affected replaces what was previously called Field Authority the ability to create, update, and delete fields. Setting method authority provides much greater flexibility because it allows you to perform any method on any entity type. For detailed information and instructions on using method security in your repository, refer to the Enterprise Administration Guide.
2-5
2-6
CHAPTER
LOCKING OBJECTS
For the AppBuilder developer, the security measures discussed in the previous chapter that are designed to prevent unauthorized access to repository objects may not be adequate to manage individual objects during development. Object locking provides a method for you to control security independently. You can lock objects to prevent other developers from accessing them while you are working on them. Locking prevents two users, both of whom are authorized to access the repository, from updating the same object at the same time. Without locking, one users changes will overwrite the others.
Lock Types
Table 3-1 shows the types of locks you can put on an entity.
Table 3-1 Lock type Lock Types Function Placed automatically on an entity when you download it from an enterprise repository. A Y lock lets you update or delete the entity (assuming you have authority to do so when the object is unlocked), but prevents others (except a project leader) from doing so. A Y lock gives everyone read access to the entity. The Y lock is cleared when you upload the entity with no lock. You can put a read lock on an entity with the LOCK action. A read lock prevents anyone, including you, from updating or deleting the entity. However, it lets anyone perform actions requiring read access to the entity. You can put an update lock on an entity with the LOCK action. An update lock allows you to update or delete the entity and prevents others from doing so (assuming you have authority to do so when the object is unlocked). However, your project leader can delete the object. You can put an exclusive lock on an entity with the LOCK action. An exclusive lock lets you update or delete the entity (assuming you have authority to do so when the object is unlocked), but prevents others (except a project leader) from doing so. An exclusive lock allows only the user who placed the lock, or a project leader, to perform actions requiring read access to the entity. (This has not been implemented across all of the repository actions.) Entity is unlocked. You can use the UNLOCK action to release the lock placed previously on an entity with the LOCK action. A project leader can also use the UNLOCK action to release a lock you placed on an entity.
Y (download lock)
R (read lock) U (update lock)
E (exclusive lock)
N (unlocked)
3-1
Lock Types
LOCK
Use the LOCK method to lock an entity only. Relationships are locked by parent entities. That is, locking a parent entity locks its relationships. What type of lock you can place on an entity depends on: The project to which the entity belongs Your authorization level in that project The entitys owner Table 3-2 shows what types of locks you can put on an entity that is not already locked and is in a project you can access.
Table 3-2 Locking an Entity Your object YRUE YRUE YRUE R=Read U=Update E=Exclusive Someone elses object YR YRUE YRUE Authorization level Programmer Analyst Project leader Y=Download
Also, Table 3-2 shows that you can place: A download or read lock on any entity in any project you can access An update or exclusive lock on any entity you own in a project you can access; but only an analyst or project leader can do so on an entity someone else owns No locks on an object in a project to which you dont have access Using the LOCK method displays the panel in which you can specify the type of lock to be placed.
Changing the Lock

If an entity is already locked, you can use the LOCK method to change the lock.You are authorized to place the new lock type as described in Table 3-2. A project leader can change an Update or Exclusive Update lock placed by you to a Read lock. However, the project leader cannot revert any lock placed by you to an Update or Exclusive Update lock. The project leader can only release the lock you placed.
UNLOCK
You can use the UNLOCK method if you can access the project to which the entity belongs, and you either: Placed the previous lock Are a project leader
3-2
Locking Objects
Lock Types
Accessing Locked Objects

What access users can have to locked objects was briefly described in Lock Types. Table 3-3 summarizes who can read, update, or delete a locked object. It assumes the user has the basic authority to perform the action on the unlocked object. (If a user cant access an unlocked object, the user cant access the object when its locked.) Table 3-3 summarizes the additional conditions necessary to access a locked object. (The locker is the person who locked the object.)
Table 3-3 Lock type Y R U Accessing a Locked Object Who can read Anyone Anyone Anyone Who can update Locker, if object owner Locker, if analyst Locker, if project leader No one Locker, if object owner Locker, if analyst Locker, if project leader Locker, if object owner Locker, if analyst Locker, if project leader R=Read U=Update Who can delete Locker, if object owner Locker, if project leader No one Locker, if object owner Locker, if project leader Locker, if object owner Locker, if project leader E=Exclusive
E Y=Download
Locker Project leader
When an object has a Y or U lock: Anyone with read access to the object can read it. The locker can update it if the locker owns the object or has analyst authority. The locker can delete it if the locker owns the object. When an object has an R lock: Anyone with read access to the object can read it. No one can update it as long as it is locked. No one can delete it as long as it is locked. When an object has an E lock: Only a project leader or the locker can read the object. The locker can update the object if the locker owns it or has analyst authority. The locker can delete the object if the locker owns it.
3-3
Lock Types
3-4
Locking Objects
CHAPTER
DEFINING THE APPLICATION MODEL
AppBuilder 2.0.3.1 Enterprise Applications Guide
Using AppBuilder you can write: Two-tier host/cooperative applications Started from a workstation and run partially on a workstation and partially on a mainframe. Three-tier client/server applications Started from a variety of platformsfrom workstation to midlevel to mainframeand dividing their processing among all three tiers. Workstation applications Started from a workstation and run entirely on a workstation. Mainframe applications Started from a mainframe and run entirely on a mainframe. Applications that run on a mainframe can run in the following environments: CICS1 pseudoconversational mode IMS (Information Management System) Batch
Building Applications with the Information Model

You build mainframe applications with the entities and relationships located in the Enterprise Information Model. Typical entities are rules, components, windows, files, fields, and sets. For additional detailed information, refer to the AppBuilder Information Model Reference Guide. Rules are the principal entities of an AppBuilder application because they contain the executable code. You construct rules with the elements of the AppBuilder Rules Language. For more information, refer to the Rules Language Reference Guide.
CICS (Customer Information Control System) is a family of application servers and connectors for online transaction management and connectivity from IBM. See http://www-4.ibm.com/software/ts/cics/ for more information.
4-1
Building Applications with the Information Model
To write an application, you can use either the Construction Workbench on a workstation or the Enterprise Development Workbench interface on a mainframe. For some portions of an application, you must use the Workbench on a workstation. For example, to develop a window (including 3270 windows) you must use the Window Painter, which is available only on a workstation. Drawings containing logical entities, such as entity relationship diagrams (ERD), state transition diagrams (STD), and process dependency diagrams (PDD) must be developed and maintained on the Workbench. For information on Workstation development, see the Developing Applications Guide. When you prepare an application, you must prepare it in the environment in which it is to run. For example, a rule that is to run on a workstation must be prepared on a workstation; a rule that is to run on a mainframe must be prepared on a mainframe. Table 4-1 shows the actions you use to define the objects for an AppBuilder application:.
Table 4-1 Action ADDE ADDR CO DE DR EW K ME MR REP SA SAVE SRCH TXE TXR Object Actions Options Description Add an entity to the repository Add a relation Change ownership Delete an entity Delete a relation Extended where-used report Define keywords Maintain entity attributes Maintain relation attributes Produce report Save as Save Search for keywords Define text for entity Define text for relation
Window View Limitations

The number of entities allowed in a window view cannot exceed 4025 entities. This is the accumulation of all VIEWS and FIELDS in the window view. Each occurrence of a view is included in tabulating the total entity count. For example, in the following window view setting: WINDOW-VIEW1 FIELD1 WINDOW-VIEW-DATA FIELD2 FIELD3 there will be a total of 5 entities.
4-2
Defining the Application Model
Adding, Saving, and Deleting Objects
In the following instance, the reoccurring view adds entities to the total, thus: WINDOW-VIEW1 FIELD1 WINDOW-VIEW-DATA OCCURS 50 FIELD2 FIELD3 includes a total of 152 entities.

Use the following actions to add, save, and delete repository objects: ADDE ADDR DE DR SAVE SA
ADDE
Use this action to add an entity instance to the enterprise repository. The ADDE action displays a blank entity detail panel on which you can enter attribute values for a new entity of the type on the list panel. Complete each of the required entry fields, and optional fields as needed. Type Save on the command line and press Enter. If autosave is on, pressing F3 saves the entity. Note
If a domained field is left blank, or changed to a blank, the value of the field reverts to the default domain value for the field when changes are saved.
If you navigated one or more levels into a hierarchy before issuing the ADDE action from the command line, the entity type corresponds to the original parent entity type. For example, if you navigated from a rule to a list of the relationships it has (by issuing the LR action), you can issue the ADDE action to add another rule to the repository. Figure 4-1 shows an example of the Add an Entity panel for a component.
4-3
Figure 4-1
Add an Entity Panel
Note
To view the entire panel, use the scroll up and scroll down function keys.
Required fields are displayed in reverse video. The system generates the values in protected fields, so you cannot change them. Domained fields contain a set of values from which you can select.
4-4
ADDR
Use this action to create a relationship between two entities. You can add a relationship between any two entity types, as long as that particular relationship is valid between them. For example, you can add a relationship between a function and a process (that is, function refines-into process) by applying the action to an instance of a function or a process. You typically issue the ADDR action from an entity list panels action line, which displays an Action Information panel (Figure 4-2) showing relation types the selected entity can have.
Figure 4-2 Adding a Relation in the Action Information Panel
When you select a relation type and press Enter, the Add a Relation panel is displayed, on which you can type the name of the entity you are relating to the selected entity. Type SAVE on the command line and then press Enter. When you issue the ADDR action from the command line, you are prompted for the parent and the child in the relationship. For example, if you are displaying a list of relationships for the DISPLAY_CUSTOMER rule and want to add a relationship, type ADDR on the command line or in the action column. You are prompted to identify the participants and the type of relationship for the rule entity. Note
Circular relationships are illegal in the AppBuilder Information Model (View A includes View B, View B includes View A) and result in download and execution errors. However, for performance reasons, the enterprise repository interface allows circular relationships.
DE
Use this action to delete an entity from the enterprise repository. Deleting an entity automatically deletes all its first-level relationships. The DE action is valid for every entity type. You typically issue it from an
4-5
entity list panels action line. A pop-up panel is displayed on which you confirm or cancel the Delete Entity action (see Figure 4-3).
Figure 4-3 Deleting an Entity using the Delete Options Panel
You typically issue the DR action from an action line on a relationship list panel or from the command line of a relationship detail panel. Figure 4-4 shows that when you delete entity A, you also delete the relationships (represented with dotted lines) to entities B, C, add.
Figure 4-4 Deleted Entity Example
Deleted entity A also deletes relationships to entities B, C, and D
When you issue the DE action from a panels command line or from the Available Actions panel, you specify the name of the entity to delete from the enterprise repository. An Action Information panel prompts you for the name or system ID of the specific entity instance.
DR
Use this action to delete a relationship between any two entities without deleting the entities. A pop-up panel prompts you to confirm or cancel the Delete Relationship action for a relationship instance (see Figure 4-5).
4-6
If you issue the DR action from the command line or the Available Actions panel, an Action Information pop-up panel is displayed. You must specify the name or system ID of both entities in the relationship and the relationship type to be deleted.
Figure 4-5 Deleting Relationships using the Delete Options Panel
SA
Use this action to copy the attributes and relationships associated with a particular entity instance to another entity instance of the same type. The SA action lets you quickly clone a new entity from an existing one. If a new entity shares many of an existing entitys attributes, use the SA action to avoid retyping the shared attributes. Apply the SA action to the entity instance whose attributes, relationships, text, and source you want to copy. Figure 4-6 shows an example of a Save As panel.Attributes of an entity instance are copied automatically.
Figure 4-6 Save Current Entity As Panel
4-7
For relationships, you are asked whether you want to copy the relationships this entity participates in (see Figure 4-7).
Figure 4-7 Save As Relation Options Panel
If you choose to copy the relationships, you are prompted to select from a list of relationship types (Figure 4-8) this entity participates in. Only relationships from the entity to children entities are listed. The relation types you select are copied to the new instance.
Figure 4-8 Relation Copy Options Pop-up Panel for Relation Types
Finally, you can select the individual relationship instances that the original entity instance participates in (Figure 4-9).
Figure 4-9 Relation Copy Options Pop-up Panel for Instances
4-8
SAVE
Type S next to the relationship type you want to view and press Enter. A Detailed Results pop-up panel appears, displaying a Copied or Failed message. To see an explanation of failed items, type S next to the appropriate relation that failed. Note
SA on a Window entity is not available. To clone a window, use the Window Painters Clone Facility instead of SA.
SAVE
To save the information you enter for an object during an edit session, type SAVE at the command line. You can also use the AUTOSAVE command (Table 1-5) to cause a save to be done automatically when you leave an edit session. Type AUTOSAVE ON to cause a save to be done automatically. AUTOSAVE affects the following edit actions: Maintain an Entity (ME) Add an Entity (ADDE) Add a Relation (ADDR) Source (S) Keywords (K) Add Text for Entity (TXE) Add Text for a Relation (TXR) By default, AUTOSAVE is on when you first use the repository interface.
Maintaining Objects
You can use the following actions to maintain objects in a repository: ME MR S TXE TXR K
4-9
Maintaining Objects
ME
Use the Maintain Entity Attributes action from a list panel to display any listed entitys detail panel on which you can edit the entitys attributes. Figure 4-10 shows a sample ME panel for a rule.
Figure 4-10 ME - Sample Panel
Note
If a domained field is left blank, or changed to a blank, the value of the field reverts to the default domain value for the field when changes are saved.
MR
Use the Maintain Relationship Attributes action from a list panel to display any listed relationships detail panel on which you can edit the relationships attributes. Note
If you change the name of the parent or child entity on the Maintain a Relation panel and save the changes, the repository interface creates a new relationship if the parent and child entities both exist in the repository.
S
Use the Define Source Code action to edit the source code for any of the following entities (other entities do not have source code associated with them): Component Database Form Machine Rule Section Server
4-10
Maintaining Objects
The AppBuilder environment uses the standard ISPF/PDF editing facilities. If you are not authorized to change the object, the enterprise repository lets you browse the file. Figure 4-11 shows a sample S(ource) panel for a rule.
Figure 4-11 S(ource) - Sample Panel
TXE
The Define Text for Entity action defines text for an entity to help other system developers recognize and reuse that entity. Include a brief description of the entitys purpose and the type of information it contains. Use the TXE action to begin an ISPF editor session to display or define any text that documents changes to a particular entity.
TXR
Use the Define Text for a Relationship action to help other system developers recognize and reuse that relationship by including a brief description of the relationships purpose and the type of information it contains. The TXR action begins an ISPF editor session to display or define any text that documents changes to a particular relationship.
K
The Define Keywords action allows you to name and locate entities you use in your applications. Keywords associate entity instances of different types with a particular subject. Defining consistent keywords lets you systematically search the repository for reusable objects (see SRCH.) Many organizations using the AppBuilder environment develop guidelines for defining keywords.
4-11
Maintaining Objects
Figure 4-12 shows the panel used to define keywords.

Figure 4-12 Defining Keywords
The K action lets you define keywords for your entities. A keyword describes a particular entity. You can apply the K action to any entity to assign one or more keywords that describe an object. You usually issue the K action from an entity list panel. Separate keywords by a blank and do not exceed 240 characters for all keywords for a single entity. The results from sorting by keywords are based on the INI variable setting of SORTKW in the HPSENV file.
CO
Use the Change Ownership of Entity action to change the ownership of an entity you ownthat is, an entity you created using your AppBuilder projectto another project or user ID. To issue the CO action, you must have created the entity using your user ID, or you must be an authorized project leader of the project that owns the entity. You can be attached to several groups, and the groups are attached to several projects. You can be attached to one group with Programmer authority to a project, and attached to a different group with Project Leader authority to the same project. You will get the highest authority available to you in the project. Figure 4-13 shows the Change Ownership panel.
Figure 4-13 Change Ownership Panel
Change Ownership of Object
Name . . . . . . . : AUTO_RECORDS_SYSTEM Version . . . . . : 2
Specify new Owner ID and Project ID.
Then Press ENTER.
Current Information: Owner ID . . . . . . . . . . . . . . . SS0344 Project ID . . . . . . . . . . . . . . QA
New Information: Owner ID . . . . . . . . . . . . . . . ________ Project ID . . . . . . . . . . . . . . ____
4-12
Reusing Objects
Reusing Objects
You can use the following actions to locate objects in the repository so that they can be reused: EW REP SRCH
EW
Use the Extended Where-used Report action to generate an extended where-used report for an entity. Issuing the EW action produces a printed list of all the entities that use this particular entity, all their ascendants, and in turn, their ascendants. For example, for a rule, the EW action produces a list of all the rules that use that rule and all the processes that define that rule, as well as any rules that use those rules or processes that define them, and so on, upward in a chain to the function level. For a view, you get a list of all the rules, components, windows, sections, and files that use that view, and all the entities above them, in turn, back to the function level. The EW action traverses up the repository hierarchy. You can apply this action to any type of entity except attributes, data types, identifiers, and relationships. When you use the EW action, the panel is displayed to confirm the destination printer for the EW output. For preparable entities, the output of the EW action is written to a data set in addition to being spooled to a printer. You can use the RES action to display the output on a terminal. Figure 4-14 shows a sample RES panel from which you can print or display a report.
Figure 4-14 Sample RES Panel
Repository File Browser Command ===> ______________________________________________________________
Name . . . . . . . : DVT_RULE_MVS Version . . . . . : 1 Then press ENTER .
Select one or more of the following. S=Browse P=Print D=Delete Action _ _ _ _ _ _ _ _ Method EW PREPARE PREPARE PREPARE PREPARE PREPARE PREPARE PREPARE Results File
Extended Where Used Report Job Stats / Messages AppBuilder Bindfile Results Code Generation Results Compiler Listing Link Edit Listing LU2 Installation Results Copy Results
4-13
Reusing Objects
Figure 4-15 shows a sample extended where-used report.

Figure 4-15 Sample Extended Where-used Report
Repository File Browser Command ===> ______________________________________________ Scroll ===> CSR_ --------- TEMP.NN.FF1.DVTRMVS.HMFXWU.XWU ----------- LINE 00000000 COL 001 080
Name . . . . . . . : DVT_RULE_MVS Version . . . . . : 1
********************************* TOP OF DATA **********************************
AS OF 95/02/03 12:41-------------------------------------------------- PAGE
EXTENDED WHERE-USED REPORT FOR RULE DVT_RULE_MVS -------------------------------------------------------------------------------TYPE SYSTEM-ID NAME --------- ------------------------------ -----------------------------RULE RULE RULE RULE AMXGFF AM2AFF DVTRDMV DVTRMVS NUMBER OF RULE(S) IS 4 JXL_LEX JXL_LEX2 DVT_RULE_MVS_DRIVER DVT_RULE_MVS
TYPE
SYSTEM-ID
NAME
--------- ------------------------------ -----------------------------PROCES DVTPREMV VDVT_PROCESS_EXECENV_MVS
REP
Use the Generate Report action to print information about an entity and, if you want, its children. You can generate a report from the enterprise repository for any of the following entities:
Component File Function Process Report Rule Section Set View Window
4-14
Reusing Objects
Figure 4-16 shows a report panel for a function entity.

Figure 4-16 Report Options Panel
AppBuilder Reporting Facility
Entity . . . . . . . : RULE Name . . . . . . . . Version : AUTO_RECORDS_SYSTEM
. . . . . . : 2
Type 's' to select an option or type a space to deselect. Then press ENTER.
Object Parts to Process . . . . . . . . . S S S S S S Report Output Options . . . . . . . . . . _
Entity Attributes Audit Attributes Entity Source Code View Source Text Keywords 1. Softcopy 2. Hardcopy
Printer Destination . . . . . . . . . . . ________ Defer Report for Overnight Execution . . 2 1. Yes 2. No Report Selection Options . . . . . . . . _ 1. Current Object 2. Object Hierarchy
You can include several types of information in the report. Audit information indicates which user created or modified an entity and when. View source is the C, COBOL II, or PL/I copybooks a view generates. Rule/component source refers to printing the rule and component source code. Finally, you can also include text and keywords in your report. Limiting Report Length A report can produce many pages, especially at a function or process level. To limit the number of pages, run a report at the appropriate level and include only the information you need. For example, exclude audit information, text, and keywords if you only need the source. Including unnecessary items can greatly increase the number of report pages. You can also select the Defer report for overnight execution option in the Report Options panel to schedule a long report for a more convenient time. Remember to include the address of your host printer (the default is specified in the @HPSENVn INI file).
SRCH
The Search for keywords action helps you find and reuse existing entities. As some keywords can be common to many applications, the search facility has delimiters to narrow your search efficiently. In general, multiple-keyword searches are more efficient because they yield a smaller list of entities to browse than single-keyword searches.
4-15
Building Applications with Components
Use the SRCH action to access the keyword search facility (Figure 4-17) to: Do a global search. If you enter SRCH at the command line, AppBuilder searches for entities of all types associated with the specified keywords. Search for entities of a particular type. If you enter SRCH next to an entity type in a list of entity types, AppBuilder searches for entities of that type associated with the specified keywords. Note
See K for information on entering keywords. Keyword Search Panel
Keyword Search Entity . . . . . . : GLOBAL Version . . . . . : 1
Figure 4-17
Use AND OR and parenthesis to specify search operation and precedence. per standard SQL conventions. The search is case sensitive. Example: Enclose keywords in single quotes. Press ENTER to initiate the search.
(('Keyword1%' AND '_Keyword2') OR 'Keyword3''s') 'parts' and 'model'_________________________________________ ____________________________________________________________ ____________________________________________________________ ____________________________________________________________
Note
Searches are case sensitive, for example, a search for PARTS does not find parts.
Here are some examples of the SRCH actions search rules: You can use AND, OR, and parentheses for multiple keyword searches. For example, if you type (('KEYWORD1' AND 'KEYWORD2') OR 'KEYWORD3') the system searches for entities with both keywords 1 and 2, and those with only keyword 3. An underscore represents any single character. For example, if you type KEY_, the system searches for keywords with KEY and any one additional character. For example, the system could find KEYS, but would not find KEYSTROKE. A percent sign represents any number of characters. For example, if you type KEY%, the system searches for keywords with KEY and any number of additional characters (such as KEYS, KEYWORDS, and KEYSTONE). To search for a particular keyword (such as KEY), you must embed a blank after the word. To find only KEY, type 'KEY '. If you leave out the blank space, the system interprets this as %KEY% and searches for all instances of the characters KEY.

There are two kinds of components in the AppBuilder environment: User components. Components you write. System components. Components that AppBuilder provides to perform various functions, such as error message windows for your user interface.
4-16
A user component in the AppBuilder environment is similar to a rule in that you write it to enable your application to do a specific unit of work. The major difference is that user components are written in a third-generation language (COBOL, C, PL/I, or Assembler) and AppBuilder rules are written in the Rules Language. There are three situations when you might consider a user component over a rule for your application: 1. 2. 3. For access to files that SQL cannot access. The Rules Language accesses AppBuilder-defined files through embedded SQL calls which cannot access all files, such as a DL/I database. For complex mathematical functions. The Rules Language does not support calculus; so if your application includes complex math, you must write a user component. To integrate existing code. If you have an existing module, you might to incorporate it directly into your application as a user component, rather than recode it in Rules Language.
You can write user components for the AppBuilder CICS, the AppBuilder batch, and the AppBuilder IMS environments on the host. This section describes writing host components in general. For more specific information, see the following chapters: Chapter 6, Writing CICS Components Chapter 10, Writing IMS Components Chapter 13, Writing Batch Components
Creating a Component to Use with a Rule

These procedures create a user component on the host to be used by a rule. Procedure - Creating a user component 1. 2. Type ADDE next to Component on the AppBuilder Entities panel. Press Enter. A blank component detail panel displays. Type the attributes for your component. For the Subroutine attribute, specify No. Specifying No signifies that the component is an independently preparable piece of code invoked at runtime. Specifying Yes indicates that the component is a subroutine, like a copybook or include file, but not a preparable entity. A component that a rule uses must be an independently preparable entity. 3. 4. 5. 6. After you fill in all the attribute values, type SAVE on the command line and press Enter. A message tells you that the new component is added to the repository. Add the components input and output views and their respective fields by creating them using the ADDE action with the appropriate entity type, as you did for the component itself. Add the relationships between the component and both its views. Type LE next to Component on the AppBuilder Entities panel, and press Enter to list components. Then type ADDR next to the name of the component you created, and press Enter. An Action Information panel lists the relationships a component can have. 7. 8. Select the Owns View relationship and press Enter. Type the name of the input view, select Input for the View Usage attribute, type SAVE on the command line, and press Enter. You then see a panel showing the newly created relationship.
4-17
Accessing DB2 Tables
Follow the same procedure to add the output view. 9. Add the relationships between the views and their respective fields.
10. Type S on the components action line and press Enter to define the source code for the component. You can then use the ISPF editor to code in the language you specified. 11. Type PR on the components action line and press Enter to prepare your component. 12. Add a USE COMPONENT component_name statement to the rule that calls the component. 13. Add a Rule uses Component relationship between the rule and the component. After you prepare the rule it will be able to call the new component.
Using a Component with Another Component

Not only rules can use componentsa component can use another component. There are two ways in which one component can use another: One component can invoke another at runtime. In this case, you must prepare both components separately. There must be a Component uses Component relationship between the two, and the Subroutine attribute for both components must be set to No because both components are independently preparable. Note that when one component invokes another at run time, AppBuilder is not involvedcontrol rests entirely with the components (and whatever they invoke). One component can include another at preparation time. In this case, the component is included when you prepare the including component. Prepare only the including component because it is the only independently preparable entity of the two. Set the Subroutine attribute for the including component to No because it is independently preparable. Set the Subroutine attribute for the included component to Yes because it is not independently preparable. There must be a Component uses Component relationship between the two components. The including component must contain an explicit statement including the other component such as a PL/I %INCLUDE or COBOL COPY statement. A common purpose for including one component in another is to include the declarations for a data structure. That is, the component that is included can consist of declaration statements that are common to a number of components. This can be particularly useful if you are converting an existing 3GL application to AppBuilder Rules Language and wish to reuse your data definitions.

This section describes the interaction of the AppBuilder environment with DB2 tables. Traditional application development often involves accessing data stored in host relational databases and/or files. AppBuilder applications can access your host data. AppBuilder applications typically store data in DB2 tables. The file entity with a file-type attribute of DB2 supports these tables, and the Rules Language accesses relational databases such as DB2 through SQL constructs. Reading from or writing to the physical host DB2 table is easy in the AppBuilder environment, as you can embed SQL calls in your applications appropriate host rules.
4-18
Data sets can be stored in a VSAM, BDAM or QSAM file organization. The AppBuilder environment accesses these host files through the component entity type (see Reusing Objects).
Defining DB2 Tables

You usually define files in your application during the systems prototyping phase of development. You can create your file hierarchy on your workstation using the Hierarchy Diagrammer, or you can create the file entity on the host. A file hierarchy consists of three AppBuilder entities and relationships: DB2 Table File Entities DB2 Table View Entities DB2 Table Field Entities A typical file hierarchy contains one file that owns a view with one or more fields. The sequence of the views fields is important because it is the same as the order of fields in the physical file created. After you create a file with its hierarchy of fields on your workstation, upload the file to the enterprise repository. Then, issue the Generate DDL (GD) action for that file to generate the DB2 Data Definition Language statement that can be executed to create your DB2 table. Also, apply the Prepare (PR) action to the file instance to create the DB2 DCLGEN. For more information on generating DDL and creating DB2 DCLGEN, see GD on page 5-6.
DB2 Table File Entities

When defining a file entity for a DB2 table, set the File Type attribute to DB2.
DB2 Table View Entities

Define a view, and create an owns relationship between your file entity and the new view, whose view type must be DATA.
DB2 Table Field Entities

Define your fields and create an includes relationship between the file view and each field. Make sure the sequence number on each includes relationship is correct; the sequence order of the fields in the view is the same in the DB2 table. Also, be sure to set the Nulls Indicator attribute correctly for each includes relationship between a field and the file view. When DB2 table columns are built from the fields in the file view, the value you place in the Nulls Indicator attribute is interpreted as described in Table 4-2.
Table 4-2 Y N D Nulls Indicator Attributes Nulls allowed in column Nulls not allowed in column Nulls not allowed in column with a default of zero (0) for numerical fields and spaces for string fields
4-19
Accessing Non-DB2 Files
Accessing Non-DB2 Files

To define a file for a non-DB2 host file, use the DB2 file type attribute value. Define the file view and fields and create the relationships just as you would for a DB2 table file. You can access a host file in your application using a component that enables execution of host hardware-specific actions, such as VSAM file access, under the control of AppBuilder rules-based processing. Your file-access components are programs that you can write in COBOL II, assembler, C, or PL/I. Write your component to access a data set and include the conventions for the AppBuilder communications area (HPSCOMM). Components expect input data in the format an input view defines and return output data in the format the output view defines.
4-20
CHAPTER
BUILDING APPLICATIONS
AppBuilder provides pre-defined actions that you use to define the tasks in your applications. These actions are listed here in a table, followed by detailed descriptions of each one with the elements you need to configure them.
Using Build Actions

Table 5-1 lists AppBuilder actions and descriptions used to build applications. For more information related to each action, see Chapter 16, Configuring Applications.
Table 5-1 Action ACTIVATE ASSIGNCU BINDPKG BTS DEACTIVE DYNAMIC GD LISTRBD PR PRB PSB RB RBD RDTL RES RIN STATIC SUPERPR TE TRANS Build-related Actions Description Activate a partition Assign a preparable entity to the active partition Bind DB2 package Batch Terminal Simulation (IMS only) Deactivates any Partition that was previously active Establish dynamic linkage Generate DDL for a file List Rebuild contents Prepare an entity Prepare process execution environment in background. See page 5-14. Modify PSB (IMS only) Rebind rules that use a component Relink a rule, rebind its DB2 plan, and reinstall into CICS Update IMS processing details (IMS only) Display results of a previous action Reinstall a component into CICS Establish static linkage Superprepare Test a batch rule (Batch only) Assigns a CICS transaction code to a rule
5-1
ACTIVATE
Table 5-1 Action TS VER
Build-related Actions (Continued) Description Transaction switch Verify a hierarchy
ACTIVATE
Use this action to select the partition that will be active during your online session. It must be executed prior to any other action that may need to know the active partition (ASSIGNCU). For example, you can use the ACTIVATE action to select the partition whose database you want to use during preparation. Entities belonging to a partition that are prepared while the partition is active are prepared for the DB2 subsystem specified for the partitions database. A partition remains active until you activate a different one or log off. Prerequisites None Target Entities Partition Related Actions ASSIGNCU PR RIN Customization Options In the @USRENVn INI file, PRODUCT.CFGWB must be set to Y. DEACTIVE RB GD RBD
ASSIGNCU
This action assigns the active partition to preparable entities. The active partition may be assigned to a single preparable entity, or to all preparable objects in the selected entitys hierarchy. An option is available which allows you to view the objects in the hierarchy and select specific ones for assignment. If you decide to prepare all objects in the hierarchy without viewing the list, you will be asked to confirm your request before it is executed. Figure 5-1 shows a sample ASSIGNU panel.
5-2
Building Applications
BINDPKG
Figure 5-1
Command ===>
Assign Partition Panel

Assign Partition _______________________________________________________________
Name . . . . . . . : QA_CFG0_RULE_CICS_DB2 Config. Unit . . . : QA_CFG1_CFG_CICS_DB2 Version . . . . . : 1
Select one of the following.
Then Press Enter.
Configuration Option . . . . . . . . . . _
1. Object only 2. Display selection list of preparable objects 3. All preparable objects in hierarchy
Prerequisites A partition must be activated via the ACTIVATE action, prior to running ASSIGNCU. The partition remains active until you either activate a different one or log off. Target Entities Component Process Window Input/Output
Processing step Foreground Input User-selected preparable entities Output A relationship between the partition and each preparable entity is added to the repository.
Rule Report
File Set
Related Actions ACTIVATE
BINDPKG
This action is used to execute a DB2 package bind for a rule or component. To issue a package bind on the mainframe, use the BINDPKG action of the enterprise repository. Note
This action is not available on the workstation.
The BINDPKG action is only available to rules or components whose DBMS usage is marked as DB2.
5-3
BTS
Prerequisites A logical hierarchy must exist consisting of rules, and/or components, views, and fields. A successful rule or component prepare must have been executed prior to performing a package bind (that is, a DBRM must exist). Target Entities Rule Component Input/Output
Processing step BINDIN Input Rules or components Database Request Module (DBRM) Output DB2 package bind Comments DB2 rules or components only DB2 rules or components only. This is executed only if GRANTs have been configured (PREPARE.DB2GRANT=YES in the @USRENVn INI file.)
GRANT
DML
DB2 Grant
The results of the generated rule or component BINDPKG may be viewed by using the RES action. See RES for more information. Related Actions Component PRepare Rule PRepare
BTS
This action allows you to test an IMS rule using BTS (Batch Terminal Simulation) before testing in IMS. When a rule has been prepared and the PSBs have been generated, enter BTS to start the BTS allocation. Panel HPIBTSA is displayed allowing user files and data sets to be allocated along with standard AppBuilder files and data sets. When user files have been entered and validated, they are stored in the ISPF PROFILE pool, enabling the DD and data set names to be redisplayed each time BTS is invoked. The SYSOUT and SYSPRINT options give the ability to display these outputs directly to the terminal, or to have them routed to a data set ('USERID.filename') for viewing after the BTS test. The option Enter Y for previous test run ===> enables the rerun of the previous BTS test. This is achieved by the BTS PUNCH data set being copied to the BTS input cards.
5-4
DEACTIVE
Press Enter from this panel and details of how to invoke the IMS 3270 converse RuleView application will be displayed. The rule can now be tested as if it were in IMS, allowing breakpoints at the start and end of each rule and any subordinate rules, components and windows within the frontier rule hierarchy. RuleView tests only the rule that the BTS action was entered against. This is because the BTS action builds only the rule transaction associated with this current rule. At completion of the BTS test, panel HPIBTS4 is displayed (Figure 5-2).
Figure 5-2 BTS Output
IMS BTS Output
Enter Y to Browse output datasets
BTSOUT
===>
SYSABEND ===>
PLIDUMP
===>
SYSUDUMP ===>
SYSOUT
===>
SYSPRINT ===>
SYSLOG
===>
Hit PF3
to end session. Press ENTER to continue.
This panel allows you to view all of the BTS run output directly. Enter 'Y' next to any or all of the DD output to display the data set contents. These data sets reside as 'USERID.Filename'. Prerequisites A logical hierarchy must exist consisting of rules, and components, views, and fields. The rule must have been successfully prepared, along with the entities in its hierarchy. PSBs must have been generated. Target Entities Rule Related Actions PRepare Notes The variable BTSREG in the REGIONS section of the @USRENVn INI file specifies the BTS region for BTS testing.
DEACTIVE
This action deactivates any Partition that was previously active. A partition remains active until you activate a different one or log off.
5-5
DYNAMIC
Prerequisites DEACTIVE can only be performed in a session where a partition has been activated. Target Entities Partition Related Actions ACTIVATE Customization Options In the @USRENVn INI file, PRODUCT.CFGWB must be set to Y.
DYNAMIC
This action removes any relationships between an object and the partition STATIC_LINK_DEFAULT which is provided as part of the default repository. Prerequisites None Target Entities Rule Related Actions STATIC
GD
Use the GD action on a file to generate DB2 Data Definition Language (DDL) statements defining tables, indices, and tablespaces. A database administrator can then use the DDL to create the tables and indices in the tablespaces. A table and its indices must be created before you can prepare a rule or component that references the table. As Figure 5-3 shows, the CREATE TABLE and CREATE INDEX statements that are generated by the GD action depend upon a files hierarchical structure of views and fields. A view maps to a DB2 table during DDL generation. The fields in the view map to the columns in the table. The field attributes determine the characteristics of the columns. The CREATE TABLESPACE statement that is generated depends upon settings in the @USRENVn INI file.
5-6
GD
Figure 5-3
Generating DDL
The table name in the generated CREATE TABLE DDL statement is the implementation name of the file. If the implementation name does not include the table qualifier (is not formatted qualifier.name), and if the file is or is not related to an active partition, the default qualifier is determined as described in Changing the Qualifier of DB2 Tables on page 16-8. Figure 5-4 shows a sample Generate DB2 DDL panel.
Figure 5-4 Generate DB2 DDL Panel
Generate DB2 DDL Name . . . . . . . . : BFS_TBF_DLY_TRD Version . . . . . . : 1
DB2 Information: Database . . . . . . . . . . . . . . . . ________ Tablespace . . . . . . . . . . . . . . . ________
Storage Information: Storage Media . . . . . . . . . . . . . _ 1. VCAT 2. Storage Group Storage Name . . . . . . . . . . . . . . ________ Primary Quantity . . . . . . . . . . . . 5_______ Secondary Quantity . . . . . . . . . . . 3_______
Output Partitioned Dataset Name: Data Set Name . . . . . . . . _________________________________________
Replace above member . . . . . . . . . . 2
1. Yes 2. No
Table 5-2 shows the fields on the GD panel and descriptions of each field.
Table 5-2 Field Name Version Database Tablespace Fields on the GD Panel Description This field is prefilled with the long name of the file being prepared. This field is prefilled with the version to which the file belongs. Name of the database in which the table is to be created. Name of a tablespace within the database in which the table is to be created.
5-7
GD
Table 5-2 Field
Fields on the GD Panel (Continued) Description Select either VCAT (volume catalog) or Storage Group. Specify the volume catalog name or storage group name, as appropriate. If your table is to be in a storage group, you must also specify a primary quantity. A default value, derived from the @USRENVn INI file, is prefilled in this field. If your table is to be in a storage group, you must also specify a secondary quantity. A default value, derived from the @USRENVn INI file, is prefilled in this field. Specify the name of the partitioned data set (including member name) where the DDL statements are stored. For example, 'SS0344.DEV.CNTL(FILE003)'.
Storage Media Storage Name Primary Quantity Secondary Quantity Output Partitioned Dataset Name
Prerequisites A hierarchy of file, view, and field(s) must exist before you can use the GD action on a file. The file must implement a DB2 table, and the value of the Usage attribute on the File owns View relationship must be Data View. Target Entities File Input/Output
Processing Step Foreground Input Hierarchy of file, view, fields Output DDL
Related Actions Component PRepare Rule PRepare File PRepare Customization Options Your AppBuilder administrator can change INI file settings to affect the DDL statements that are generated. These installation settings can change storage classes, bufferpools, space allocations, and other values. See the Enterprise Administration Guide for more information. Notes DDL generation does not include referential integrity references. Figure 5-5 shows how DDL generation varies depending upon the Usage attribute of the File owns View relationship.
5-8
LISTRBD
Figure 5-5
DDL and the Usage Attribute
LISTRBD
Use this action to list object counts, objects included in a rebuild package or superprepare and their status. For more information, see the Enterprise Rebuild Guide.
PR
Before running an application, you must prepare it. To prepare an application you must prepare all the rules, sets, reports, windows, files, and components that belong to it. You can prepare these entities in any order, but you must create tables that rules or components reference before you can prepare the rules or components. Use the PR action for: Preparing Components Preparing Files Preparing Reports Preparing Rules Preparing Sets Preparing Views Preparing Windows
Preparing Components
The PR action is used to generate mainframe executable code from a components hierarchy in an AppBuilder user level data set. A component is simply a program or legacy application that is defined to the AppBuilder repository and is written in a language other than the AppBuilder Rules Language. If you create a workstation component, you must use the Preparation Workbench on a workstation to prepare the component. If your component references a DB2 table you must create the table using the GD action on the file entity before you can prepare the component. Use the PR action on a file to generate a table declare statement and a data structure that matches the table. Include the table declare and data structure in
5-9
PR
your component so that it can access the DB2 table. For additional information, see Preparing Files and GD. A prepare of a component executes a dynamic prepare of all views that it is related to. The output from the dynamic view prepare is a copybook. The copybook contains generated PL/I or COBOL II data definitions generated from the components input and/or output view(s). A component may include source code that is shared by many other components. This source is defined to a component with its SUBROUTINE attribute turned on. To include the subroutine code in the main component you simply add a relationship between the two entities. A prepare of a component (SUBROUTINE=N) includes as source all components used as subroutines (SUBROUTINE=Y) that it is related to. The DCLGEN generated from the file view is expanded in the source code. The component contains SQL calls to the AppBuilder file implementation name to access the file. A COBOL component with implementation name MAINCMP could have the statement COPY VIEWIN in its source code. This statement would include the source from the generated view copybook. into MAINCMP during the components compile step. For example: /* generated view output */ 01 VIEWIN. 05 NAME PIC X(25). 05 ADDRESS PIC X(55). /* Generated COBOL II as result of Component prepare Compile (COMP) step. IDENTIFICATION DIVISION. PROGRAM-ID. . . *COPY VIEWIN. /* Note VIEWIN Source is included in this Program. */ 01 VIEWIN. 05 NAME PIC X(25). 05 ADDRESS PIC X(55). A COBOL component with implementation name MAINCMP would have the statements COPY SUBRT1 and COPY VIEWIN in its source code. This statement would include the source from AppBuilder component SUBRT1 and include the source from the generated view copybook into MAINCMP during the components compile step. /* generated view output */ 01 VIEWIN. 05 NAME PIC X(25). 05 ADDRESS PIC X(55). /* component used as subroutine source ( imp-name = SUBRT1) */ EXEC SQL SELECT RULE_ID FROM E_RULE WHERE RULE_ID = :RULE_SYSTEM_ID AND VERSION = :V; MAINCMP.
5-10
PR
This is an extract of the COBOL II source code generated from a component prepare. IDENTIFICATION DIVISION. PROGRAM-ID. . . *COPY VIEWIN. /* Note VIEWIN Source is included in this Program. */ 01 VIEWIN. 05 NAME PIC X(25). 05 ADDRESS PIC X(55). *COPY SUBRT1. /* Note SUBRT1 Source is included in this Program. */ EXEC SQL SELECT RULE_ID FROM E_RULE WHERE RULE_ID = :RULE_SYSTEM_ID AND VERSION = :V; Prerequisites Logical hierarchy consisting of components, views and fields, rules, and/or files. Target Entities Component Input/Output Figure 5-6 gives a high-level view of the steps involved in component preparation.
Figure 5-6 Component Preparation Steps
MAINCMP.
Table 5-3 gives a detailed view of the steps involved in component preparation.
Table 5-3 Component Preparation Steps Input Output AppBuilder generated hierarchy bind file. Temp data sets containing component source, generated views, and/ or components used as subroutines. Database Request Module (DBRM) and preprocessed Source. Translated CICS source. Comments
Processing step
BNDX
Component source and component hierarchy.
The temporary data sets created are used in the COMP step.
DB2PRE
AppBuilder component source. AppBuilder source or output from DB2PRE step.
For DB2 components only. For CICS components only.
TRN
5-11
PR
Table 5-3
Component Preparation Steps (Continued) Input Output from TRN step for CICS components. Output from DB2PRE or BNDX step for BATCH or IMS. Object module from COMP step. Object module from COMP step. Temporary data sets created during previous steps. Output Comments The compiler for the language of the component is invoked. The linkage editor is invoked to create a component executable. Used during RBD action and REBUILD. Copies load modules, DBRMLIB members etc., into AppBuilder user-level data sets. Perform package bind if component contains DB2 and package indicators are on. DB2 package and/or plan grant. Adds PPT entry to the CICS region(s).
Processing step
COMP
Object module.
LKEDC-CICS or IMS LKEDB -BATCH LKEDNC-CICS or IMS LKEDNB - BATCH
Loadlib member.
NCAL member.
COPYLIB
AppBuilder temporary or permanent data sets.
BINDIN
Components Database Request Module (DBRM).
DB2 bind.
GRANT LU2
SQL GRANT statements. Customized LU2 scripts.
DB2 grant. Defines program to CICS region(s).
Viewing Component Preparation Results To view the component preparation results, apply the RES action to a component to browse the assembler, C, COBOL II, or PL/I results. A results list displays with a listing for the following steps in the prepare action: Compile results DB2 BIND results COPY results Link-edit results If CICS, installation results Related Actions Rule PR Set PR File PR GD Component PR
Customization Options
The generated view copybook can be customized by your AppBuilder administrator based on installation settings. The INI variable VIEWS.VWDB2L49 causes generation of copybooks that are suitable for use as DCLGENS. The INI variable VIEWS.VWALIGN causes generation of view copybooks with alignment bytes. See Preparing Views for more information.
5-12
PR
Notes
Languages currently supported are COBOL II, PL/I, C, and Assembler. Mainframe environments currently supported are CICS, TSO, and IMS. The member name in all data sets created is the components or views implementation name. If you are creating a C include library outside of the AppBuilder mainframe environment, you should be aware of the fact that mainframe C components should have 80 byte record lengths. The logical record length of the file should not exceed 80 bytes. A component used as a subroutine cannot be prepared by itself. It must be related to a main component (SUBROUTINE=N).
Preparing Files
This action uses the DB2 utility DCLGEN to generate the data structure and table declaration from the file entity. The declarations and structures may then be included in a component that access the file. File preparation requires two steps: 1. Use the GD action on a file to create the DB2 table that the file implements. Before you can prepare a rule or component that uses DB2, first create any table that it references. The DDL generated by the GD action depends upon the relationship of the views that the file owns to the file. 2. For components, use the file PR action to create the DB2 DCLGENs. A component that references a DB2 table must include a table declaration and a corresponding data structure matching the table. This step is not needed when preparing rules because rule preparation takes care of the necessary includes. Use the RES action on a file to browse the DB2 table DCLGEN.
Prerequisites Logical hierarchy consisting of files, views, and fields:

Figure 5-7 File Preparation Hierarchy
Target Entities File entity
5-13
PR
Input/Output
Processing Step Input DB2 table name in the DB2 subsystem of the AppBuilder repository Output SQL DECLARE TABLE statement and a COBOL II or PL/I, or C data declaration for the table Comments Customize the language output by INI flags. See Enterprise Administration Reference Guide.
DCLGIN
The results of the generated file prepare may be viewed by invoking the RES action. Related Actions Rule PRepare Component PRepare GD Customization Options Project-level, version-level, and repository-level INI variables are available to set the default qualifier for DB2 commands and utilities. Each clients AppBuilder DB2 administrator will need to update the applicable @USRENVn INI file with the default qualifier. The order of precedence for the DCLGEN utilities DB2 table qualifier is determined by the setting of the PCKG INI variable. For information, see Changing the Qualifier of DB2 Tables on page 16-8.
Preparing Reports
This action is used to generate the mainframe executable code from the reports hierarchy. To prepare a report that executes on a mainframe, use the PR action of the AppBuilder mainframe repository (Figure 5-8).To prepare a report that executes on a workstation, use the preparation workbench on the workstation.
Figure 5-8 Preparing Reports
Execution Environments
The valid execution environments for AppBuilder reports are MAINFR (CICS) and mainframeBAT.
5-14
PR
Before a CICS report can be executed, it must be defined and installed in the CICS region(s). This occurs automatically when you successfully prepare a report that has an execution environment of CICS. This selection is not available to reports with an execution environment of mainframeBAT. Apply the RES (Results) action to a report to view the report preparation results. A results list displays with a listing for the following steps in the prepare action: Code generation results Compile results Link-edit results If CICS, installation results Prerequisites A successful rule prepare where the rule is related to the report. A CICS report may only be executed by a rule. A logical hierarchy must exist consisting of reports, sections, sets, views, and fields. Target Entities Report Input/Output Figure 5-9 shows a representation of the steps involved in report preparation.
Figure 5-9 Report Preparation Steps
Table 5-4 gives a detailed view of the steps involved in report preparation.
Table 5-4 Report Preparation Steps Input Report source and report hierarchy of entities. 1) Bind file. 2) Section source. Output from HPSCG step. Output from HPSCG step. Report bind file. Assembler code from SETADR step. Object module from COB step. Object module from COB step. Output AppBuilder generated hierarchy bind file. Temp data sets containing section source. COBOL II source code. AppBuilder code generation listings. Object module. Assembler code. Object module. Loadlib member. The linkage editor is invoked to create a report executable. Used during RBD action and/or REBUILD to perform static link processing. Perform a COBOL II compile. Comments The bind file data set created is used in the HPSCG step.
Processing Step
BNDX
HPSCG HPSCGLST COB SETADR SETASM LKEDC-CICS LKEDB-BATCH LKEDNC-CICS LKEDNB-BATCH
Perform code generation.
NCAL member.
5-15
PR
Table 5-4
Report Preparation Steps (Continued) Input Bind file. Output Explode the views used by the reports. Update the view records with the calculated lengths of the views. Sort the view records. Update the AppBuilder views VSAM file. Update the AppBuilder reports relationship VSAM file. AppBuilder temporary or permanent data sets. Define report to CICS region(s). Load the AppBuilder views VSAM file with view records of the report. Load the AppBuilder reports relationship VSAM file with relationship records of the report. Copy load modules, and section source into AppBuilder user-level data sets. CICS reports only. Temp view records data set. Comments
Processing Step VDEX
VLTH
Bind file. Temp view records data set. Output from SORT step. Bind file. Temporary data sets created during previous steps. Customized LU2 scripts.
SORT VWLD
RELD
COPYLIB
LU2
Related Actions Rule Prepare Notes The member name in all data sets created is the reports implementation name.
Preparing Rules
This action is used to generate a mainframe executable code from a rules hierarchy. If your rule references a DB2 table you must create the table using the Generate DDL action (GD) on the file entity before you can prepare the rule. Use the PR action on a file to generate a table declare statement and a data structure that matches the table. For information on preparing files and creating DB2 tables, see Preparing Files and GD. A prepare of a rule executes a dynamic extract of the view information required by the AppBuilder code generator. It then creates an AppBuilder bindfile that contains the entities in the rule hierarchy. The bindfile lists all rules, components, views, sets, windows, and other entities referenced by the rule being prepared. This bindfile is used with the rules source code by the AppBuilder code generator to produce COBOL II code. Before a CICS rule can be executed, a CICS transaction associated with it must be defined and installed in the CICS execution environment. This occurs automatically when you successfully prepare the rule. At installations where CICS transactions definitions persist for a limited time, you can use the RBD action to reinstall a rule whenever you want to execute it. Note
The Reinstall selection of the RBD action is not available to rules with an execution environment of mainframeBAT.
5-16
PR
The generation of a DB2 plan or package bind is dictated by the setting of several INI variables. For information, see Using DB2 Packages and Plans on page 16-10. The generation of the transaction ID is performed for rules on: CICS - CICS, mainframe, and PCCICS IMS - IMS and PCIMS For generation of CICS and IMS transaction IDs and DB2 plan names, see the Enterprise Administration Guide. For information on preparing rules, see: CICS environment - Chapter 7, Preparing CICS Applications IMS environment - Chapter 9, Preparing IMS Applications
Repreparing a Rule
During the development of an application, testing and design changes require you to reprepare the application. If the rules source is changed without changing any attributes or entities in the rules hierarchy, the generation of the rules bind file is not necessary. The panel in Figure 5-10 is displayed automatically when you prepare a rule if you prepared it previously (a bindfile already exists for the rule).
Figure 5-10 Rule Prepare Options
Rule Prepare Options __________
Name . . . . . . . . : Version . . . . . . :
DVT_RULE_CICS 1
Select the desired option.
Then press ENTER.
Preparation Options . . . . . . . . .
_ 1. Full prepare - Process rule hierarchy and source 2. Evaluate rule source only
The Rule Prepare action panel contains two options: 1. Option 1 causes a full prepare to be performed. You must use this option if you change a rules hierarchy in any of the following ways: Significant attributes or relationships Subordinate rules containing DB2 if using DB2 plans Rules input or output views Structure of the database table that it accesses Hierarchy of the window that the rule converses Attributes or hierarchy of a set it uses, if the set contains values. If you change a set that contains symbols, you need only relink the rule. Add or delete a relationship to a report entity. A new bind file must be created and new COBOL II code must be generated to reflect the changes in all of the above cases to reflect the changes.
5-17
PR
2.
Option 2 lets you omit creating a new bind file. This selection is made when the rules source code is changed and no hierarchical changes have occurred.
Prerequisites 1. 2. Physical hierarchy consisting of views, fields, and/or sub-rules, components, files, windows, sets, and reports. Successful prepare of applicable entities
Target Entities Rule Input/Output

Processing Step BNDX Input Rule source and rule hierarchy of entities. Bind file Rule source. Output from HPSCG step. Output AppBuilder generated hierarchy bind file. Temp data sets containing rule source. Source code (COBOL II on the mainframe). AppBuilder code generation listings. 1) Database Request Module (DBRM) 2) Preprocessed DB2 code. DB2 precompiler, for DB2 rules only. Comments The bind file data set created is used in the HPSCG step. This step performs code generation.
HPSCG HPSCGLST
DB2PRE
AppBuilder generated code. Output from TRN step for CICS rules. Output from DB2PRE or HPSG step for BATCH or IMS rules. Rule bind file. Assembler code from SETADR step.
COB
Object module.
Performs a COBOL II Compile.
SETADR SETASM
Assembler code. Object module. The linkage editor is invoked to create a rule executable. For execution environments CICS, PCCICS, mainframe, PCIMS, and IMS. The linkage editor is invoked to create a rule executable. For execution environments mainframeBAT and mainframe. Used during RBD action and REBUILD. For execution environments CICS, PCCICS, mainframe, PCIMS, and IMS. Used during RBD action and REBUILD. For execution environments mainframeBAT and mainframe.
LKEDC CICS or IMS
Object module from COB step.
Loadlib member.
LKEDB - BATCH
Loadlib member.
LKEDNC CICS or IMS
Temporary NCAL member.
LKEDNB BATCH
Temporary NCAL member.
VDEX
Bind file.
Explodes the views used by the rules.
5-18
PR
Processing Step VLTH SORT VWLDC
Input Bind file. Temp view records data set. Output from SORT step.
Output Update the view records with the calculated lengths of the views. Sort the view records. Update the AppBuilder views VSAM file. Update the rules relation-ship VSAM file for CICS and BATCH rules. Writes to temporary data sets for IMS. Update the AppBuilder rules source VSAM file for CICS and BATCH rules. Writes to temporary data sets for IMS. Update the AppBuilder entities view structure for CICS and BATCH rules. Writes to temporary data sets for IMS. AppBuilder temporary or permanent data sets.
Comments Temp view records data set.
Load the AppBuilder views VSAM file with view records of the rule. Load the rules relationship VSAM file with relationship records of the rule. Load the AppBuilder rules Source VSAM file with source records of the rule.
RELDC
Bind file.
SRLDC
Source.
PVWLDC
Bind file.
Load the AppBuilder entities view structure into the runtime VSAM file. Copy load modules, DBRMLIB members etc., into AppBuilder user-level data sets. Determines whether to perform IMS BMP or DL/I database update. Perform IMS BMP or DL/I database updates. Perform plan or package bind depending upon the PCKG and PKLIST INI file variables. DB2 package and/or plan grant. CICS or IMS rules only.
COPYLIB
Temporary data sets created during previous steps. TSO command to obtain status of IMS control region job. Temporary data sets created in RELDC, SRLDC, and PVWLDC job steps. Rules Database Request Module (DBRM). SQL GRANT statements. Customized LU2 scripts.
IMSSTAT
Status of IMS control region.
HPIVSAM
Updated IMS database.
BINDIN
DB2 bind.
GRANT LU2
DB2 grant. Defines rule to CICS region(s).
Viewing Rule Preparation Results Use the RES action to browse the results of a rule preparation, which vary according to the rules execution environment. When you issue the RES action, a results list is displayed for the following steps in the prepare action: Code generation results Shows any problems with the hierarchy and the results of a syntax check of the rule source code.
5-19
PR
Compile results Displays the results of the COBOL compilation. A return code of 4 is successful. Any return code higher than 4 is unsuccessful. Link results Shows the results of the link-edit step. If the previous two steps are successful, the link-edit should always be successful. DB2 results Shows the results of the DB2 bind and grant step if the rule uses DB2. The DB2 bind displays the results for several DB2 commands. The bind and grant commands must be successful. Load results If the rule runs in CICS, shows the results of the CICS transaction installation. The CICS region must be running for the CICS installation to be successful. Figure 5-11 shows sample results of preparing a rule (actual results depend upon what the rule does for example, if it uses DB2). A separate file is produced for each step of the preparation. You can browse or print each file to view the detailed results of the preparation.
Figure 5-11 Preparation Results
Prepare Result Files Command ===> ________________________________________________________________ Name . . . . . . . : DVT_RULE_BATCH Version . . . . . : 1 Then press ENTER .
Select one or more of the following. S=Browse P=Print D=Delete Action _ _ _ Method PREPARE PREPARE PREPARE Results File
Job Stats / Messages Bindfile Results Compiler Listing
_ PREPARE Link Edit Listing ****************************** BOTTOM OF DATA *******************************
Related Actions Component PRepare File PRepare GD Customization Options The INI variable VIEWS.VWALIGN causes generation of view copybooks with alignment bytes. See Preparing Views on page 5-22 for more information. Notes The member name in all data sets created is the rules implementation name.
Preparing Sets
Use the PR action to generate an AppBuilder set to be used by windows and rules. To prepare a set that executes on a mainframe, use the PR action of the AppBuilder mainframe repository. See Preparing Sets on page 17-5 for more information.
5-20
PR
When you prepare a Lookup type set or Error set, the PR action extracts the data from the repository and creates an object module that contains all the data for a set, including all languages. The object module is then link-edited and placed into the run-time load library. The load module name is the implementation name of the set. Prerequisites A logical hierarchy consisting of sets and values or symbols must exist in the repository.
Figure 5-12 Set with Symbols or Values
Target Entities Set Input/Output Figure 5-13 give a high-level view of the steps involved in set preparation.
Figure 5-13 Set Preparation Steps
Table 5-5 gives a detailed view of the steps involved in set preparation.
Table 5-5 Set Preparation Steps Input Set, and its values, or symbols. Output Set copybooks. VSAM file updates for CICS and BATCH. Temporary data set for IMS. Object module. Loadlib member. Loadlib member. Comments VSAM updates applicable to styles E and V. Applicable to set styles E and L only. Applicable to set styles E and L only. Applicable to set styles E and L only. Copy load modules, set copybooks, etc. into AppBuilder user-level data sets. Determines whether to perform IMS BMP or DL/I database updates. Processing Step
SETPR
ASM LKEDB LKEDNB
Set source. Object module from ASM step. Object module from ASM step. Temporary data sets created during previous steps. TSO command to obtain status of IMS control region job.
COPYLIB
AppBuilder temporary or permanent data sets.
IMSSTAT
Status of IMS control region job.
5-21
PR
Table 5-5
Set Preparation Steps (Continued) Input Temporary data set created in SETPR step. Customized LU2 scripts. Output Updated IMS database. Installs a set in CICS region. Comments Perform IMS BMP or DL/I database update. Applicable to set styles E, L, and V only.
Processing Step HPIVSAM LU2
You can view the results of the generated Set Prepare using the RES action (see RES). Related Actions Rule PRepare Window PRepare Notes The member name in all data sets created is the sets implementation name.
Preparing Views
You can use the PR action on a view to generate a COBOL II and PL/I copybook for documentation purposes, or for inclusion in a non-AppBuilder program. Use of this action is optional. You do not have to generate a copybook for the input or output view of a rule or component when you prepare it. AppBuilder generates a copybook automatically. You must, however, have the appropriate include statement (%INCLUDE for PL/I and COPY for COBOL II) in your component before you can successfully prepare it. You can also use the PR action to generate a copybook that you can use as input to DCLGEN for SQL table declaration. See Preparing a View for DCLGEN. Use the RES action to view the results of using PR on a view. See RES for more information. Warning
Limitations exist on the allowable number of views in a hierarchy. See Window View Limitations on page 4-2.
Prerequisites You must have a hierarchy consisting of a view and any fields or subviews that it uses. Target Entities View
5-22
PR
Input/Output
Processing Step PREPVU Input View hierarchy Output PL/I and COBOL II copybook data sets. The member name in the data set is the implementation name of the view.
Related Actions Component Prepare File PRepare Rule PRepare Customization Options The variable VIEWS.VWALIGN in the @HPSENVn INI file causes generation of view copybooks with alignment bytes.
Preparing a View for DCLGEN

If you are using PR to generate a COBOL or PL/I data declaration to include in an SQL table declaration for DCLGEN, and if your view includes VARCHAR fields, you should be aware of the fact that COBOL II requires level 49 elements for VARCHAR fields. An administrator can set the flag VIEWS.VWDB2L49 in the @HPSENVn INI file to cause view preparation to generate level 49 elements for VARCHAR fields. If VIEWS.VWDB2L49 is set to Y, then the following COBOL II structure is generated during view preparation for a VARCHAR field: 05 field-implementation-name-V. 49 field-implementation-name-LEN. 49 field-implementation-name. IF VIEWS.VWDB2L49 is set to N, then the following COBOL II structure is generated (this is the usual case): 05 field-implementation-name-LEN. 05 field-implementation-name. When using VARCHAR fields, you should ensure that field implementation names do not exceed 26 characters. Notes If you are creating a C Include library outside of the AppBuilder mainframe environment, you should be aware of the fact that mainframe C components should have 80 byte record lengths to support all translators. The logical record length of the file should not exceed 80 bytes.
Preparing Windows
This action is used to generate information to be used by AppBuilder at runtime from the windows hierarchy. To prepare a window that executes on a workstation use the preparation workbench on the
5-23
PR
workstation. To prepare a window that executes on a mainframe use the PR action of the AppBuilder mainframe repository. Note
This action is required only when 3270 Converse applications are used.
Before a window can be executed, the LU2 step (for CICS) or HPIVSAM step (for IMS) must be processed to activate the window in the CICS or IMS region. This automatically occurs when you successfully prepare the window. For more information on preparing windows, see Window Prepare (PR) on page 17-3. Prerequisites Logical hierarchy consisting of windows, views, fields, and sets. Target Entities Window Table 5-6 gives a detailed view of the steps involved in window preparation.
Table 5-6 Window Preparation Steps Input Window hierarchy. Source file from SOURCE step. PNV file from CPRS step. Output from Sort step. TSO command to obtain status of IMS control region job. Temporary data set created in WINDPR step. Output from WINDPR step. Customized LU2 scripts. Output Extracted panel and help text source. PNV file. Sorted file. Window bind file. Update run-time file. Status of IMS control region job. Updated IMS database. Update run-time file. Installs window in CICS region(s). Comments Extract source for panels and help text. Convert the window PNL to PNV format. Sort the window PNV file. Process the PNV file and create the window bind file. Determines whether to perform IMS BMP or DL/I database updates. Perform IMS BMP or DL/I database update. Build panel display output. Activates window in CICS region(s). Processing Step SOURCE CPRS SORT WINDPR
IMSSTAT
HPIVSAM DPNV LU2
Related Actions Rule PRepare Notes The member name in all data sets created is the windows implementation name
5-24
PSB
PSB
The PSB action allows you to modify the default IMS program specification block (PSB) assigned to a specific rule. All rules attached to a transaction also have a corresponding PSB. This PSB specifies which IMS databases and queues the rule uses. You need to modify the PSB only if a component within the rules hierarchy accesses an IMS database outside of the AppBuilder Environment. A rules plan name defaults to its transaction name. You must perform a PR (prepare) action before you can use the PSB action. When you issue PSB, the panel shown in Figure 5-14 is displayed.
Figure 5-14 PSB Generation Panel
IMS COMMAND===> PSB GENERATION PANEL
THE FOLLOWING OPTIONS ARE USED TO MODIFY AN IMS PSB SOURCE MODULE Rule Name AND JCL FOR THE GENERATION OF THE LOAD MODULE FOR RULE PSB Name.
1 2 3
Edit PSB Source Module SDEVM1AA PSBGEN JCL to Generate Load Module. ACBGEN JCL to Generate Application Control Block
The following choices are available in the PSB Generation panel: Edit PSB Source Module This option allows you to edit the PSB source to add any additional user databases. The position of the databases in the PSB is not important because AppBuilder IMS applications use IMS AIB calls to reference the databases by name. PSBGEN JCL to Generate Load Module This option creates a temporary file containing the JCL needed to generate three PSB load modules. These modules have the same IMS application names as those the system administrator generates. This allows a rule to run non-conversational TP, conversational, and batch. To invoke this job, enter SUB (for submit) on the command line above the JCL. ACBGEN JCL to Generate Application Control Block This option creates a temporary file containing the JCL needed to generate the application control blocks (ACBs) for the specified rule. These ACBs have the same IMS application names as those the system administrator generates. To invoke this job, enter SUB (for submit) on the command line above the JCL. If you generated a PSB, you must also generate an ACB. Prerequisites You must perform a PR action on a rule before you can use the PSB action. Target Entities Rule
5-25
RB
Related Actions Rule PRepare Platform Considerations This action is available only in an IMS environment.
RB
This action is used to rebind one or more rules that use a component. As Figure 5-15 shows, if you change a components SQL statements and reprepare it, you must rebind the DB2 plan for any rule that uses the component. This is because the plan for any rule that uses the changed component includes the changed components DBRM.
Figure 5-15 Rebinding DB2 Plans
The RB actions is applicable only to binds that use DBRMsit is not supported for AppBuilder versions that use packages. If you are using packages, use the BINDPKG action to rebuild a component. Use the RB (rebind) action to list all rules that use this component (see Figure 5-16) and select the rules whose plans are to be rebound. The RB action invokes DB2 bind to update the associated DB2 plan. Select the appropriate rules or use the keyword ALL.
Figure 5-16
Command ===> Entity . . . . . . : Name . . . . . . . : Version . . . . . : ACOMDR COMP 1
Rebind Rules Panel

ReBind Rules
Type ALL on Command Line to submit ReBinds for all rules listed or select one or more of the following rules and type SUB on Command Line to submit ReBind for selected rules. to cancel method. Action -----Rule Name --------ACOXDR Rule Long Name -----------------------------TIP_BATCH_MASTER_RULE Press PF3 or type END
ACOZDR TIP_BATCH_PLIDB2_RULE ****************************** BOTTOM OF DATA*******************************
Each rule selected for rebind must previously have successfully prepared (a DBRM must exist). Even if a rule doesnt use DB2, it has a plan associated with it if it uses a rule or component (or uses a rule or component that uses a rule) that uses DB2. This is because there is a load module associated with the rule, and that load module must have a plan associated with it that includes the DBRM for any rule it uses.
5-26
RBD
For generation of DB2 plan names, see the Enterprise Administration Guide. Prerequisites Successful rule prepares for all rules selected to be rebound. Successful component prepares for all components marked as DB2 and related to a rule selected to be rebound. Logical hierarchy consisting of rules, components, views, fields, and/or files, windows, sets, and reports. Target Entities Component entity Input/Output
Processing Step BINDIN GRANT Input Rules Database Request Module (DBRM) SQL GRANT statements Output DB2 Bind DB2 Grant Comments DB2 plan bind DB2 grant
The results of the generated component rebind may be viewed by invoking the RES action. Related Actions Rule PRepare Component PRepare Customization Options See the INI file section of the Enterprise Administration Guide for more information.
RBD
This action is used to rebuild a mainframe rule within the AppBuilder environment. The rule must previously have been successfully prepared. You can use this action for: Relinking a rule Rebinding a rule Reinstalling a rule into CICS The Rebuild facility for OpenCOBOL includes changes to the way that the VIEW, SET RULE and COMPONENT objects prepare. Only the following RBD methods are supported in this release: RELINK BIND INSTALL
5-27
RBD
Relinking a Rule
When the PR option is used to prepare a rule a dynamic link edit is performed. The RBD action can be used to change how a rules load module is linked. For a CICS rule that has already successfully prepared, RBD lets you select dynamic, static, or dynamic COBOL linking (Figure 5-17). Dynamic Linking Static Linking Dynamic COBOL Link
Figure 5-17 Relinking a CICS Rule
Rebuild Entity Name . . . . . . . : HPS_RULE_DRIVER Version . . . . . : 1
Specify Rebuild options.
Then Press ENTER.
Relink . . . . . . . . . . . . . . . . . _
1. Static 2. Dynamic 3. Dynamic COBOL 4. No
Rebind . . . . . . . . . . . . . . . . . _
1. Yes 2. No
Reinstall CICS Rule
. . . . . . . . . . _
1. Yes 2. No
For a batch rule that has already successfully prepared, RBD lets you elect static linking or dynamic linking (Figure 5-18).
Figure 5-18 Relinking a Batch Rule
Rebuild Application Rebuild Application
Name . . . . . . . : DVT_RULE_BATCH Version . . . . . : 1
Specify Rebuild options.
Then Press ENTER.
Relink . . . . . . . . . . . . . . . . . _
1. Static 2. Dynamic 3. No 2. Dynamic 3. No
Rebind . . . . . . . . . . . . . . . . . _
1. Yes 2. No
Dynamic Linking
With dynamic linking each rule has its own load module and at runtime each load module is fetched into memory only when the rule is called. Dynamic linking is useful when it is necessary to test each module separately, for example during development and testing.
5-28
RBD
Static Linking
With static linking, the rule and all other rules and components that it calls are linked into one load module. During execution, only the rule is fetched into memory, regardless of what rules or components are actually invoked. Static linking results in better performance but uses more memory than dynamic linking. The Static link option is available for all mainframe execution environments. Warning
Do not static link rules that converse windows or that use rules that converse windows. Unpredictable results may occur at runtime.
Because static linking is based on the compiler option, AppBuilder OpenCOBOL does this during the prepare phase. Lower level rules and components must be prepared before the higher level rule and components. Note
The VIEW and SET prepares must be completed before a rule or component prepares.
Dynamic COBOL Link

The Dynamic COBOL option is available for rules with execution environments of CICS, mainframe, and PCCICS.
Rebinding a Rule
When you use DB2 packages, a DB2 package bind is performed and a DB2 plan bind when you prepare a rule. The plan bind is determined by the setting of several AppBuilder INI settings. For information, see Using DB2 Packages and Plans on page 16-10. When you are using DBRMs rather than packages, the generation of a DB2 plan is performed for rules in the following two situations: 1. 2. Rules whose DBMS usage is marked as DB2. Rules that have a child rule in there rule(s) hierarchy that is marked as DB2.
Whenever you cause a DB2 plan to be rebound (by repreparing a rule), you must rebind the plan for each rule higher up in the rules hierarchy. Use the RBD action for each rule whose plan you want to rebind. The RBD action issues a DB2 Bind to update the associated DB2 plan. Figure 5-17 and Figure 518 show the panels displayed when you use the RBD action to rebind a rules DB2 plan (the same panels are used to relink and reinstall rules). As Figure 5-19 shows, if you change a rules SQL statements and reprepare it, you must rebind the DB2 plan for any rule that uses the rule (or uses a rule that uses the rule). This is because the plan for any rule that uses the changed rule includes the changed rules DBRM.
5-29
RBD
Figure 5-19
Rebinding DB2 Plans
Even if a rule doesnt use DB2, it has a plan associated with it if it uses a rule (or uses a rule that uses a rule, etc.) that uses DB2. This is because there is a load module associated with each rule, and that load module must have a plan associated with it that includes the DBRMs for any rule it uses.
Reinstalling a Rule into CICS

This selection defines the rule to the CICS region(s) defined to the AppBuilder version. Before a CICS rule can be executed, a CICS transaction associated with it must be defined and installed in the CICS execution environment. This occurs automatically when you successfully prepare the rule. At installations where CICS transactions definitions persist for a limited time, you can use the RBD action to reinstall a rule whenever you want to execute it. This selection is not available to rules with an execution environment of mainframeBAT or IMS. Prerequisites A successful rule prepare of the rule selected to be link edited, rebound, or reinstalled. Logical hierarchy consisting of views, fields, and/or rules, components, files, windows, sets, and reports. Target Entities Rule
5-30
RDTL
Input/Output
Processing Step SETADR SETASM LKEDC - CICS or IMS LKEDB - BATCH Input Rule bind file. Assembler code from SETADR step. Object module from previous rule prepare. Output Assembler code. Object module. The linkage editor is invoked to create a rule executable. Copies load modules, DBRMLIB members, etc. into AppBuilder user-level data sets. DB2 rules only. DB2 rules only. CICS only. Comments
Loadlib member. AppBuilder temporary or permanent data sets. DB2 Bind. DB2 Grant. Defines rule, to CICS region(s).
COPYLIB
Temporary data sets created during previous steps. Rules Database Request Module (DBRM). SQL GRANT statements. Customized LU2 scripts.
BINDIN GRANT LU2
The results of the generated rule RBD may be viewed by invoking the RES action. Related Actions Component PRepare File PRepare Rule PRepare GD Notes The member name in all data sets created is the rules implementation name.
RDTL
This action allows you to update the default IMS processing details for a rule that is invoked asynchronously with a USE RULE...INIT statement. AppBuilder Run Control uses these details to start a rule automatically. You may need to change the details if you change the rules region name or the rules processing mode. When you use the RDTL action, the panel shown in Figure 5-20 is displayed.
5-31
RES
Figure 5-20
Rules IMS Processing Details Panel

AppBuilder RULES IMS PROCESSING DETAILS PANEL
COMMAND===> This Panel is used only when a Rule is invoked by a USE RULE INIT function
The following options are needed to add/update the AppBuilder Rules IMS Processing details to enable the automatic processing of Rule RUNCTLM in a USE-RULE-INIT function AppBuilder Rule Name DB2 Plan/Transaction/Application Name Rules IMS Processing Type IMS Region/JCL Member Name ==>SDEVM1AA ==> TP ==> TP,BMP or DLI ==>RUNCTLM
Hit PF3 to cancel request.
Press ENTER to continue
The rule name and the DB2 plan/transaction/application name are defaults and you cannot change them. The rules IMS processing type defaults to TP. The IMS region and batch JCL members must be in the IMS job control library to enable automatic initiation. If you leave a TP rules IMS region/JCL member name blank, AppBuilder Run Control assumes that the region for the rules transaction is online. It therefore does not issue a /START REGION command. If you leave that name blank for a BMP or batch DL/I rule, AppBuilder Run Control does not automatically start the JCL member. Using the rule name for the data set name is preferred. Target Entities Rule Platform considerations This action is available only in an IMS environment.
RES
Use the RES action to display the results of the following actions: BINDPKG PR RBD VER EW RB REP
5-32
RIN
Figure 5-21 shows the panel that is displayed when you use the RES action. This panel is the same no matter which actions results you display. Only the list of files at the bottom of the panel differs depending upon the action. The RES panel allows you to either browse the results online or print them.
Figure 5-21 RES Panel
Prepare Result Files Command ===> ________________________________________________________________ Name . . . . . . . : DVT_RULE_BATCH Version . . . . . : 1 Then press ENTER .
Select one or more of the following. S=Browse P=Print D=Delete Action _ _ _ Method PREPARE PREPARE PREPARE Results File
Job Stats / Messages Bindfile Results Compiler Listing
_ PREPARE Link Edit Listing ****************************** BOTTOM OF DATA *******************************
RIN
This action is used to reinstall a mainframe component into the AppBuilder CICS regions. This selection defines the component to the CICS region(s) defined to AppBuilder. Before a CICS component can be executed, the components load module must be defined and installed in the CICS execution environment. This occurs automatically when you successfully prepare the component. At installations where CICS definitions persist for a limited time, you can use the RIN action to reinstall a component whenever you want to execute it. Note
This selection is not available to components with an execution environment of mainframeBAT, PCIMS, or IMS.
Prerequisites The component must have been successfully prepared. A logical hierarchy must exist consisting of components, views, fields, and/or components, files, windows, sets, and reports. Target Entities Component Input/Output
Processing Step LU2 Input Customized LU2 scripts. Output Defines component to CICS region(s). Comments CICS components only.
The results of the generated component reinstall may be viewed by invoking the RES action.
5-33
STATIC
Related Actions Component PRepare
STATIC
This action creates a relationship between an object and the STATIC_LINK_DEFAULT partition that is provided as part of the default repository. This action is used to maintain a relationship indicating that this rule should be statically linked automatically during the rebuild process. Notice that you can migrate the STATIC_LINK_DEFAULT partition if you add it to a migration package. If there is a relationship between a rule and this partition, the Rebuild Facility will statically link it. Migrating the STATIC_LINK_DEFAULT partition will bring over the relationships to set up the objects in the target repository for static linking. Prerequisites None Target Entities Rule Input/Output
Processing step Foreground Input User-selected rule. Output A relationship between the configuration unit STATIC_LINK_DEFAULT and the selected rule is added to the repository.
Related Actions DYNAMIC Rebuild prepare
SUPERPR
You can use this action to prepare an object and all the objects in its hierarchy. You can apply this action to a function, process, rule, or component. For more information, see the Enterprise Rebuild Guide.
5-34
TE
TE
Use the TE action to invoke the batch version of the RuleView debugger. The batch debugger combines all of the AppBuilder CICS RuleView debugger functions with the added power of ISPF scrolling and unlimited panel display nesting. You can set or reset breakpoints to enter the debugger before and after a selected rule, component, or report is called. You can set breakpoints before and after DB2 calls. You can display, change, save, retrieve, and restore views, subviews, and fields. You can also browse any rules or components source code. For more information, see Chapter 14, Sample Batch Applications. Target Entities Rule Platform Considerations Batch only
TRANS
Use the transaction assignment (TRANS) action on a rule to assign it a CICS transaction code. Used primarily for non-DB2 rules, the system generates the transaction ID. If the rule contains a DB2 plan name, the system also assigns a plan name. You can run the transaction assignment action before preparing the rule. The Transaction ID and plan name is not removed unless you change the rule type or delete it. Target Entities Rule Related Actions Rule PRepare
TS
Use the TS action on a window to display a list of fields within the window so that you can designate fields as transaction fields. When you designate a field as a transaction field, you associate a CICS or IMS transaction ID with it. At runtime, when a user enters data into the field, the transaction associated with the field is started and the data in the field is passed to the transaction. Transaction switching lets users switch from one transaction to another without being returned to the top of a process structure hierarchy. For more information, see Transaction Switching on page 17-6.
5-35
VER
Prerequisites This action applies only to 3270 Converse applications. The window must have been successfully prepared. Target Entities Window Related Actions Window PRepare
VER
Use the VER action on a rule prior to preparing it to verify that the rule hierarchy is valid. Using the VER action, an invalid hierarchy causes preparation to fail. The VER action: Parses the rule source to determine what rules, components, sets, windows, reports, and views it references and verifies that each such entity exists in the repository. Verifies, for each rule and window that the rule references, that it has only one input view, one output view, or one input/output view. Verifies that each such view includes at least one field or view. Creates a relationship between a rule and any rule, component, set, window or report it references if a relationship doesnt already exist. Deletes a relationship between a rule and a rule, component, set, window or report if the rule source does not include a statement referencing the entity.
Viewing Rule Verification Results

After using the VER action to verify a rule hierarchy, use the RES action on the rule to view the results, as in Figure 5-22. The panel displays the line number of the source-code statement that references a rule, component, set, window, or report. Messages list any relationships that are created or deleted, and any errors.
5-36
VER
Figure 5-22
Command ===>
Results of Verifying a Rule

Prepare Result Files ______________________________________________ Scroll ===> CSR_
Name . . . . . . . : TIP_BTCH_MASTER Version . . . . . : 1
********************************* TOP OF DATA ********************************** HM0406E - Rule TIP_BTCH_MASTER being processed HM0499I - 0008 RULE HM0499I - 0009 RULE HM0499I - 0010 RULE HM0499I - 0011 RULE HM0499I - 0012 RULE HM0499I - 0013 RULE HM0499I - 0014 RULE HM0499I - 0015 RULE TIP_BTCH_ASM_RULE TIP_BTCH_ASMDB2_RULE TIP_BTCH_COBOL_RULE TIP_BTCH_COBDB2_RULE TIP_mainframe_RULE TIP_BTCH_PL1_RULE TIP_BTCH_PL1DB2_RULE TIP_TEST_REPORT_RULE
HM0403I - Verify ended with no errors ******************************** BOTTOM OF DATA ********************************
Source-code line number Prerequisites A logical hierarchy must exist consisting of a rule, the rule source, and any entities to which the rule is related, directly or indirectlyother rules, components, windows, sets, views, reports. Target Entities Rule Input/Output
Processing Step Input A rule hierarchy consisting of a rule and, possibly, other rules, components, windows, sets, views, reports, and their relationships and rule source. Output A valid rule hierarchy, with some relationships possibly added, and other relationships possibly deleted from the original hierarchy.
Foreground
Related Actions Rule PRepare
5-37
VER
5-38
CHAPTER
WRITING CICS COMPONENTS
AppBuilder CICS components enable execution of host-dependent actions under the control of AppBuilder rules-based processing. These AppBuilder CICS components (written in COBOL II, assembler, PL/I, or C) are normal CICS programs that use input data in the format that an AppBuilder input view defines and return output data in the format that an AppBuilder output view defines. The executable file created when you prepare a host component written in C depends on the components execution environment attribute: If the components execution environment is PCCICS, preparation creates a PC executable file. If the components execution environment is mainframeBATCH, preparation creates an mainframe executable file.
Designing CICS using AppBuilder Rules

The design of the AppBuilder CICS environment conforms closely to normal IBM/CICS programming conventions. An AppBuilder rule, therefore, initiates an AppBuilder component in the AppBuilder CICS environment through a normal CICS link command. To facilitate this link, a CICS common storage area is defined in a format all AppBuilder CICS components follow. As in AppBuilder CICS, components are passed the address of a control block, known as a COMMAREA, that includes the names, lengths, and addresses of their input and output views as the second parameter. The first parameter is a system parameter, which is dependent on whether the component is executing in CICS, batch, or IMS. For example, in CICS, the system parameter is the CICS Execute Interface Block (DFHEIB). A COBOL II component designed for both batch and CICS should not specify a USING list on the procedure division line. The CICS translator inserts one before the compilation. You must specify the MAIN option for a PL/I component to function correctly in either environment. Preparing the input and output views generates the required view definitions for PL/I and COBOL components. For example, for a COBOL component view, a COBOL copybook is generated. This copybook is included in the Copy statement in the component code. Definitions for the COMMAREA reside in the Include libraries for each language. Components should have an Include or Copy statement for them. Two examples illustrate how to conform a PL/I and a
6-1
Designing CICS using AppBuilder Rules
COBOL II program to an AppBuilder CICS component. Both examples perform the same function moving the components input view to its output view. Sample COBOL II CICS Component Sample PL/I Component Line Detail
Sample COBOL II Component Line Detail

This first sample program is a COBOL II AppBuilder CICS component. The crucial lines of the COBOL II sample component are described here:
Line 32
Defines the structure name for the AppBuilder CICS common storage area for this component in the linkage section.
Line 33
Copies the description of the elements of the AppBuilder CICS common storage area into the linkage section.
Line 37
Copies the description of the elements of the input view for this component into the linkage section.
Line 41
Copies the description of the elements of the output view for this component into the linkage section.
Line 66
Sets the address of the input view described in the Linkage Section to the storage address contained in the IV-PTR variable, which is defined in the AppBuilder CICS common storage area for the component.
Line 67
Sets the address of the output view described in the Linkage Section to the storage address contained in the variable OV-PTR. OV-PTR has been defined in the AppBuilder CICS common storage area for the component.
Line 70
Calls the MOVE-VIEW-ROUTINE to move the input view to the output view in 1,896-byte sections.
6-2
Writing CICS Components
Sample COBOL II CICS Component

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 IDENTIFICATION DIVISION. PROGRAM-ID. CN1CTST. AUTHOR. INSTALLATION. CHANGE MANAGEMENT ARCHITECTURE. *REMARKS. THIS PROGRAM TESTS THE CICS ENVIRONMENT. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. IBM-370. OBJECT-COMPUTER. IBM-370. DATA DIVISION. WORKING STORAGE SECTION. * 77 77 * 01 01 01 01 * LENGTH VARIABLES AND COUNTER VARIABLES MOVE-BUFFER-LENGTH REMAINING-MOVE-LENGTH POINTER VARIABLES INPUT-FLOAT-ADDRESS PIC S9(8) COMP VALUE +0. INPUT-FLOAT-PTR REDEFINES INPUT-FLOAT-ADDRESS POINTER. OUTPUT-FLOAT-ADDRESS PIC S9(8) COMP VALUE +0. OUTPUT-FLOAT-PTR REDEFINES OUTPUT-FLOAT-ADDRESS POINTER. LINKAGE SECTION PIC S9(4) COMP. PIC S9(4) COMP.
LINKAGE SECTION. * APPBUILDER/CICS COMMAREA
01 DFHCOMMAREA. COPY HPSCOMM. * CN1CTST INPUT VIEW
COPY CN1CTSTI. * CN1CTST OUTPUT VIEW
COPY CN1CTSTO. * 01 FLOATING WORK AREAS INPUT-VIEW-X. 03 INPUT-VIEW-BUFFER. 05 INPUT-VIEW-CHAR
OCCURS 1 TO 1896 TIMES DEPENDING ON MOVE-BUFFER-LENGTH PIC X.
01
OUTPUT-VIEW-X.
6-3
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93
03
OUTPUT-VIEW-BUFFER. 05 OUTPUT-VIEW-CHAR
OCCURS 1 TO 1896 TIMES DEPENDING ON MOVE-BUFFER-LENGTH PIC X.
PROCEDURE DIVISION. MAINLINE SECTION. * INITIAL HOUSEKEEPING
ML-000-INITIAL-HOUSEKEEPING. MOVE IV-ADDRESS TO INPUT-FLOAT-ADDRESS. MOVE OV-ADDRESS TO OUTPUT-FLOAT-ADDRESS. MOVE IV-LENGTH TO REMAINING-MOVE-LENGTH. SET ADDRESS OF CN1CTSTI TO IV-PTR. SET ADDRESS OF CN1CTSTO TO OV-PTR. SET ADDRESS OF INPUT-VIEW-X TO INPUT-FLOAT-PTR. SET ADDRESS OF OUTPUT-VIEW-X TO OUTPUT-FLOAT-PTR. PERFORM MOVE-VIEW-ROUTINE WITH TEST AFTER UNTIL REMAINING-MOVE-LENGTH IS EQUAL TO ZERO. * EXECUTE MULTIPLE MOVES FOR DATA GREATER THAN 1896
MOVE-VIEW-ROUTINE. IF REMAINING-MOVE-LENGTH IS NOT GREATER THAN +1896 THEN MOVE REMAINING-MOVE-LENGTH TO MOVE-BUFFER-LENGTH MOVE ZEROES TO REMAINING-MOVE-LENGTH MOVE INPUT-VIEW-BUFFER TO OUTPUT-VIEW-BUFFER ELSE MOVE +1896 TO MOVE-BUFFER-LENGTH SUBTRACT +1896 FROM REMAINING-MOVE-LENGTH MOVE INPUT-VIEW-BUFFER TO OUTPUT-VIEW-BUFFER ADD +1896 TO INPUT-FLOAT-ADDRESS OUTPUT-FLOAT-ADDRESS SET ADDRESS OF INPUT-VIEW-X TO INPUT-FLOAT-PTR SET ADDRESS OF OUTPUT-VIEW-X TO OUTPUT-FLOAT-PTR END-IF. * RETURN TO CICS
ML-999-RETURN. GOBACK.
Sample PL/I Component Line Detail

The sample program is a PL/I CICS component. The significant lines of the PL/I sample component are described here:
6-4
Line 4
The PL/I component is a main procedure block that requires a single input parameter. This input parameter is the storage address of the AppBuilder CICS common storage area for this component.
Line 6
A pointer variable that contains the storage address of the AppBuilder CICS common storage area must be declared.
Line 10
A structure based on the pointer variable declared in line 6 must be defined. This structure describes the AppBuilder CICS common storage area for this component.
Line 11
Includes the description of the elements of the AppBuilder CICS common storage area.
Line 15
Declares a structure based on the pointer variable that contains the storage address of the input view for this component. This pointer variable is defined in the AppBuilder CICS common storage area.
Line 16
Includes the description of the elements of the input view for this component.
Line 20
Declares a structure based on the pointer variable that contains the storage address of the output view for this component. This pointer variable is defined in the AppBuilder CICS common storage area.
Line 21
Includes the description of the elements of the output view for this component.
Line 25
Moves the input view to the output view.
6-5
Sample PL/I CICS Component
Sample PL/I CICS Component

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 /************************************************************/ /* APPBUILDER/CICS TEST PL/I COMPONENT /************************************************************/ CN1CTST: PROCEDURE (COMPOINT) OPTIONS (MAIN) ; DCL DCL ADDR COMPOINT BUILTIN; POINTER;
/************************************************************/ /* APPBUILDER/CICS COMMAREA /************************************************************/ DCL 1 COMMAREA BASED (COMPOINT) UNALIGNED, %INCLUDE HPSCOMM;; /************************************************************/ /* INPUT VIEW FOR CN1CTST /************************************************************/ DCL 1 INPUT_VIEW BASED (IV_PTR) UNALIGNED, %INCLUDE CN1CTSTI;; /************************************************************/ /* OUTPUT VIEW FOR CN1CTST /************************************************************/ DCL 1 OUTPUT_VIEW BASED (OV_PTR) UNALIGNED, %INCLUDE CN1CTSTO;; /************************************************************/ /* EXECUTION STARTS HERE /************************************************************/ OUTPUT_VIEW = INPUT_VIEW; RETURN; END CN1CTST;
Component Communications Area (HPSCOMM)

This section describes the AppBuilder communications area for host: PL/I Components COBOL II Components BAL Components (Assembler and C Languages) The COMMAREA for each component type is kept in a copybook called HPSCOMM. The communications area is the same for CICS, IMS, and batch components.
6-6
PL/I Components
Note 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
The name of the PL/I structure and the name of the PL/I pointer variable do not necessarily have to be the same as the ones described in line 1 of the figure.
DCL 1 COMMAREA BASED(COMPOINT) UNALIGNED, 3 RULE_NAME CHAR(8), 3 RULE_COMP_NAME CHAR(8), 3 TCTUA_AREA_PTR POINTER, 3 USE_LINE_NUMBER FIXED BIN(15,0), 3 HPSCOMM_FILLER CHAR(2), 3 INPUT_VIEW, 5 IV_NAME CHAR(8), 5 IV_LENGTH FIXED BIN(15,0), 5 IV_FILLER CHAR(2), 5 IV_PTR POINTER, 3 OUTPUT_VIEW, 5 OV_NAME CHAR(8), 5 OV_LENGTH FIXED BIN(15,0), 5 OV_FILLER CHAR(2), 5 OV_PTR POINTER, 3 LOCAL_VIEW, 5 LV_NAME CHAR(12), 5 LV_LENGTH FIXED BIN(15,0), 5 LV_FILLER CHAR(2), 5 LV_PTR POINTER, 3 EXEC_ENVIRON CHAR(6), 3 START_REPORT_IND CHAR(1), 3 HPS_RULE_HANDLE_ERRORS CHAR(1), 3 HPS_VERSION_NUMBER CHAR(2), 3 /* /* /* 3 /* 3 5 5 5 5 HPS_FUNCTION FIXED BIN(15,0), USE RULE = 10 */ USE COMPONENT = 11 */ USE RULE NOWAIT = 12 */ HPS_RETURN_CODE FIXED BIN(15,0), NORMAL = 00 */ HPS_OPTIONAL_FEATURE_LIST, OPFL_NAME CHAR(8), OPFL_LENGTH FIXED BIN(15,0), OPFL_FILLER CHAR(2), OPFL_PTR POINTER;
6-7
COBOL II Components
************************************************************ * * * Classification = BluePhoenix Solutions * * * * $$NAME NAME=HPSCOMM * * * * $$VERSION ID=3.1.0,3.2.0.3.1 * * * * Date = December 20, 1989 * * * *DESCRIPTION-THIS COPYBOOK DESCRIBES APPBUILDER/CICS STANDARD* * COMMUNICATION AREA. * ************************************************************ 1 05 HPS-COMMAREA PIC X(128). 2 05 FILLER REDEFINES HPS-COMMAREA. 3 10 RULE-NAME PIC X(8). 4 10 RULE-COMP-NAME PIC X(8). 5 10 TCTUA-AREA-PTR POINTER. 6 10 TCTUA-AREA-ADDRESS REDEFINES TCTUA-AREA-PTR 7 PIC X(4). 8 10 USE-LINE-NUMBER PIC S9(4) COMP. 9 10 HPS-VERSION-NUMBER PIC X(2). 10 10 INPUT-VIEW. 11 15 IV-NAME PIC X(8). 12 15 IV-LENGTH PIC S9(4) COMP. 13 15 FILLER PIC XX. 14 15 IV-PTR POINTER. 15 15 IV-ADDRESS REDEFINES IV-PTR PIC X(4). 16 10 OUTPUT-VIEW. 17 15 OV-NAME PIC X(8). 18 15 OV-LENGTH PIC S9(4) COMP. 19 15 FILLER PIC XX. 20 15 OV-PTR POINTER. 21 15 OV-ADDRESS REDEFINES OV-PTR PIC X(4). 22 10 LOCAL-VIEW. 23 15 LV-NAME PIC X(12). 24 15 LV-LENGTH PIC S9(4) COMP. 25 15 FILLER PIC XX. 26 15 LV-PTR POINTER. 27 15 LV-ADDRESS REDEFINES LV-PTR PIC X(4). 28 10 EXEC-ENVIRON PIC X(6). 29 10 START-REPORT-IND PIC X. 30 10 HPS-RULE-HANDLE-ERRORS PIC X. 31 10 HPS-VERSION-NUMBER2 PIC XX. 32 10 HPS-FUNCTION PIC S9(4) COMP. 33 88 HPSFN-USE-RULE VALUE 10. 34 88 HPSFN-USE-COMPONENT VALUE 11. 35 88 HPSFN-USE-RULE-NOWAIT VALUE 12. 36 88 HPSFN-USE-RULE-WAIT VALUE 13. 37 88 HPSFN-USE-CONVERSE VALUE 14. 38 88 HPSFN-USE-START-TRANS VALUE 15. 39 10 HPS-RETURN-CODE PIC S9(4) COMP.
6-8
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94
88 10 15 15 15 15 15 PIC 05 05 10 15 15 15 15 10 10 15 88 88 15 10 15 15 15 15 20 88 88 88 20 88 20 20 15 10 15 15 PIC 15 15 PIC 15 15 PIC 15 15 PIC 15 15 PIC 15 15 PIC
NORMAL VALUE 00. HPS-OPTIONAL-FEATURE-LIST. OPFL-NAME PIC X(8). OPFL-LENGTH PIC S9(4) COMP. SUBHDR-LEVEL PIC 99. OPFL-PTR POINTER. OPFL-ADDRESS REDEFINES OPFL-PTR S9(8) COMP. HPS-EXTENDED-COMMAREA PIC X(384) VALUE LOW-VALUES. FILLER REDEFINES HPS-EXTENDED-COMMAREA. HPS-FLENGTH. IV-FLENGTH PIC S9(8) COMP. OV-FLENGTH PIC S9(8) COMP. LV-FLENGTH PIC S9(8) COMP. FILLER PIC X(20). HPS-CONVERSE-AREA PIC X(32). FILLER REDEFINES HPS-CONVERSE-AREA. HPS-USE-CONVERSE-OPTIONS PIC S9(4) COMP. HPS-USE-NEST VALUE +1. HPS-NOOPTION VALUE +0. FILLER PIC X(30). HPS-FEEDBACK-AREA. HPS-MESSAGE1 PIC X(80). HPS-MESSAGE2 PIC X(80). HPS-MESSAGE3 PIC X(80). HPS-ERROR-REQUEST. HPS-LOG-REQUEST PIC X. HPS-REQUEST-TO-LOG VALUE 'L'. HPS-REQUEST-TO-ABEND VALUE 'A'. HPS-REQUEST-FOR-BOTH VALUE 'B'. HPS-SEND-REQUEST PIC X. HPS-REQUEST-TO-SEND VALUE 'S'. FILLER PIC XX. HPS-ABCODE PIC X(4). FILLER PIC X(8). HPS-PRIVATE-POINTERS-AREA. CA-GLBL-PTR POINTER. CA-GLBL-ADDRESS REDEFINES CA-GLBL-PTR S9(8) COMP. CA-FIRST-PTR POINTER. CA-FIRST-ADDRESS REDEFINES CA-FIRST-PTR S9(8) COMP. CA-CURRENT-PTR POINTER. CA-CURRENT-ADDRESS REDEFINES CA-CURRENT-PTR S9(8) COMP. CA-PREV-PTR POINTER. CA-PREV-ADDRESS REDEFINES CA-PREV-PTR S9(8) COMP. CA-CVPL-PTR POINTER. CA-CVPL-ADDRESS REDEFINES CA-CVPL-PTR S9(8) COMP. CA-TWA-PTR POINTER. CA-TWA-ADDRESS REDEFINES CA-TWA-PTR S9(8) COMP.
6-9
95 96 97 98 99 100 101
15 CA-TRSA-PTR POINTER. 15 CA-TRSA-ADDRESS REDEFINES CA-TRSA-PTR PIC S9(8) COMP. 15 FILLER PIC X(04). * THE CONVERSE PRIVATE AREA CONTAINS POINTERS TO FIRST, * CURRENT AND PREVIOUS CVW'S(CONVERSE WORK AREAS) 10 HPS-CONVERSE-PRIVATE-AREA PIC X(32).
BAL Components
************************************************************ * THIS SECTION MAPS THE CALLERS COMMAREA WHICH CONTAINS APPBUILDER * STORAGE CTL ************************************************************ SPACE HPSSTGDS DSECT HPSSCNTL DS OF HPS STORAGE FACILITY CONTROL AREA HPSCRCNM DS CL8 CALLING RULE OR COMPONENT HPSRCNME DS CL8 CALLED RULE OR COMPONENT NAME HPSTCTUA DS XL4 SAVE AREA FOR TCTUA ADDRESS HPSLIN# DS XL2 USE LINE NUMBER DS XL2 FILLER SPACE ************************************************************ * THIS SECTION MAPS THE CALLERS INPUT VIEW STATUS BLOCK AREA ************************************************************ SPACE HPSIVIEW DS 0XL16 INPUT VIEW AREA HPSIVNME DS CL8 NAME OF INPUT VIEW HPSIVLEN DS H LENGTH OF INPUT VIEW HPSIVFIL DS XL2 FILLER BYTES HPSIVADR DS XL4 INPUT VIEW ADDRESS SPACE ************************************************************ * THIS SECTION MAPS THE CALLERS OUTPUT VIEW STATUS BLOCK * AREA ************************************************************ SPACE HPSOVIEW HPSOVNME HPSOVLEN HPSOVFIL HPSOVADR
DS 0XL16 OUTPUT VIEW AREA DS CL8 NAME OF OUTPUT VIEW DS H LENGTH OF OUTPUT VIEW DS XL2 FILLER BYTES DS XL4 OUTPUT VIEW ADDRESS SPACE ************************************************************ * THIS SECTION MAPS THE CALLERS LOCAL VIEW STATUS BLOCK AREA ************************************************************ SPACE HPSLVIEW DS 0XL20 LOCAL VIEW AREA HPSLVNME DS CL12 NAME OF LOCAL VIEW HPSLVLEN DS H LENGTH OF LOCAL VIEW
6-10
HPSLVFIL HPSLVADR
DS XL2 FILLER BYTES DS XL4 LOCAL VIEW ADDRESS SPACE EXECENV DS CL6 EXECUTION ENVIRONMENT DS XL2 USED FOR REPORT WRITER HPSVRM DS CL2 VERSION-RELEASE-MOD HPSFN DS H FUNCTION CODE USERULE EQU 10 USE RULE USECOMP EQU 11 USE COMPONENT ASYNCREQ EQU 12 USE RULE NOWAIT(ASYNC START) HPSRCODE DS H RETURN CODE ************************************************************ * THIS SECTION MAPS OPTIONAL FEATURES LIST CONTROL AREA ************************************************************ SPACE HPSOPIEW DS 0XL16 OPTIONAL FEATURES LIST AREA HPSOPNME DS CL8 NAME OF OPTIONAL FEATURES LIST HPSOPLEN DS H LENGTH OF OPTIONAL FEATURES LIST HPSOPFIL DS XL2 FILLER BYTES HPSOPADR DS XL4 OPTIONAL FEATURES LIST ADDRESS * HPSCNLEN EQU *-HPSSCNTL LENGTH OF THE CONTROL AREA
6-11
6-12
CHAPTER
PREPARING CICS APPLICATIONS
General instructions for preparing application files are provided in Chapter 5, Building Applications. In this section, additional platform-specific settings required for preparing CICS applications is provided. Understanding CICS Pseudoconversational Mode Preparing an Entity for Multiple CICS Regions Using RBD to Relink a Rule Using RBD to Reinstall a Rule to CICS Determining Transaction IDs Determining DB2 Plan Names Determining DB2 Plan Names
Understanding CICS Pseudoconversational Mode

AppBuilder applications that run in CICS execute in pseudoconversational mode. A pseudoconversational CICS application consists of a sequence of transactions each with a single input. Its status is passed from one transaction to the next via a storage medium other than main memory. The technique typically saves memory resources and improves message throughput because the system can process other applications while it waits for the input to a previous one. It also increases processor overhead because a transaction must be started for each input in the sequence. For techniques to minimize processor workload, see Memory Management Tips on page 17-12. A conversational CICS application consists of a single transaction with multiple inputs from the terminal. The status of the transaction is held in main storage while the processor waits for the next input. Because the transaction ties up main storage for the entire sequence of inputs, the conversational mode limits throughput and wastes memory resources.
7-1
Preparing an Entity for Multiple CICS Regions

You specify the CICS region into which an executable such as a rule, set, or window is to be installed with the implementation name attribute. This attribute now exists not only at the entity level but also at the level of a machine entity. By specifying the attribute at the machine level and relating an entity to multiple machines, each with its own implementation name (CICS region), you can prepare the same entity at different times for different regions, as illustrated in Figure 7-1. To prepare an entity in this manner, follow these steps: 1. 2. 3. Relate an entity to multiple partitions, each with its own machine. Activate the partition whose implementation name you want to use. Prepare the entity.
Figure 7-1
1. Relate entity to multiple partitions, each with its own machine Partition Partition Rule Rule Partition Partition 2. Activate a partition Partition 1 Partition Rule Rule Partition 2 Partition Machine Machine ImpName=CICS region ImpName=CICS region2 Machine Machine ImpName=CICS region ImpName=CICS region1 Machine Machine ImpName=CICS region ImpName=CICS region2 Machine Machine ImpName=CICS region 1 ImpName=CICS region
3. Prepare entity Configuration Partitionunit1 Rule Rule Partition 2 Partition Machine Machine ImpName=CICS region 2 ImpName=CICS region Machine Machine ImpName=CICS region 1 ImpName=CICS region
The partition remains active until you activate a different one or log off.
Using RBD to Relink a Rule

When you use the PR action to prepare a rule, it is dynamically linked. You can use the RBD (rebuild entity) action to change how a rules load module is linked. For a rule that has already successfully prepared, RBD lets you select dynamic linking or dynamic COBOL linking, as shown in Figure 7-2.
Figure 7-2 Relinking a CICS Rule
7-2
Preparing CICS Applications
Using RBD to Reinstall a Rule to CICS
Rebuild Entity
Name . . . . . . . : HPS_RULE_DRIVER Version . . . . . : 1 Specify Rebuild options. Then Press ENTER. Relink . . . . . . . . . . . . . . . . . _ 1. 2. 3. 4. Static Dynamic Dynamic COBOL No
Rebind . . . . . . . . . . . . . . . . . _
1. Yes 2. No 1. Yes 2. No
Reinstall CICS Rule
. . . . . . . . . . _
Using RBD to Reinstall a Rule to CICS

Before a CICS rule can be executed, a CICS transaction associated with it must be defined and installed in the CICS execution environment. This occurs automatically when you successfully prepare the rule. At installations where CICS transaction definitions do not persist for more than a day, you can use the RBD action to reinstall a rule whenever you want to execute it.
Using RIN to Reinstall Components

Before a CICS component (one with an execution environment of MAINFR or mainframe) can be executed, a CICS transaction associated with it must be installed in the CICS execution environment. Installation happens automatically when you successfully prepare the component. At installations where CICS transaction definitions do not persist for more than a day, you can use the RIN action to reinstall a component whenever you want to execute it.
Determining Transaction IDs

To determine what CICS transaction ID has been assigned to a rule, use one of the following procedures: If the rule was prepared when related to an active partition, the transaction ID is stored as the Service Name attribute of the relationship between the rule and the partition. Do an MR on page 4-10 on that relationship to see the value of the Service Name attribute. If the rule was not related to an active partition when prepared, the transaction ID is stored as an attribute of the rule. Do an ME on the rule to see the DB2 plan name.
7-3
Determining DB2 Plan Names
Determining DB2 Plan Names

To determine what DB2 plan name has been associated with a rule, you can do one of the following: If the rule was prepared when related to an active partition, the plan is stored with the relationship between the rule and the partition. Do a BR on that relationship to see the plan name. If the rule was not related to an active partition when prepared, then the DB2 plan name is stored as an attribute of the rule. Do a BE on the rule to see the DB2 plan name.
7-4
Preparing CICS Applications
CHAPTER
8
Note
API FOR CICS (HPECAPI)
You can use a standard interface called HPECAPI to invoke AppBuilder CICS applications from an mainframe/CICS application written in COBOL II. When the mainframe/CICS application calls HPECAPI, it passes the DFHEIBLK as the first parameter and the User COMMAREA as the second parameter. It copies in the COBOL copybook HCUUCOM to define the communications area between HPECAPI and the application program, and the copybook HCUUCOI to initialize the communications area.
HPECAPI is for use with CICS pseudoconversational applications.
The following sections describe in detail the CICS API: Using HPECAPI to Invoke AppBuilder User COMMAREA Interface Options
Using HPECAPI to Invoke AppBuilder

The program can invoke the AppBuilder application in any of the following ways: CICS LINK CICS START CICS START with No Expected Return CICS START with a RETURN START CICS XCTL CICS RETURN IMMEDIATE CICS RETURN IMMEDIATE, with No Expected Return CICS RETURN IMMEDIATE, with RETURN IMMEDIATE Back in the Input Message CICS RETURN IMMEDIATE, with RETURN IMMEDIATE Back to CICS COMMAREA
8-1
User COMMAREA
For details, see Interface Options. Code samples are provided for each option. Note
The maximum size of the total view that can be returned to the calling program is 32,251 bytes. This restriction is based on the half-word limit on the length of an Exec CICS START minus 516 bytes for control/header information.
User COMMAREA
The calling program copies the COBOL copybook HCUUCOM from the AppBuilder COBOL copybook library. It populates the User COMMAREA with the HCUUCOM field values described in the sections:
RULE-NAME IV-NAME IV-PTR/ADDRESS IV-FLENGTH OV-NAME OV-PTR/ADDRESS OV-FLENGTH HPS-USER-PARM-FUNC HPS-USER-PARM-RET-CODE HPS-USER-PARM-USE-TRAN HPS-USER-PARM-RET-TRAN HPS-USER-PARM-EYECATCHER HPS-USER-PARM-SUBFUNC HPS-USER-PARM-USE-TERM HPS-USER-PARM-RET-TERM HPS-USER-PARM-ERR-MSG
These include the system ID of the first rule to be invoked in the AppBuilder application, the attributes of any data views to be passed to and/or returned from the AppBuilder application, and the values appropriate to the selected interface option. The fields are listed in the order they appear in the copybook. Note
View length attributes are mandatory, even when no data are exchanged. If you are not passing data between the calling program and the AppBuilder application, set IV-FLENGTH and/or OV-FLENGTH to +0.
RULE-NAME
Specifies the eight-character system ID of the rule. For DB2 rules invoked with a CICS START or XCTL (see HPS-USER-PARM-FUNC), the field is optional; you can specify the rules transaction ID in the HPS-USER-PARM-USE-TRAN field instead. Note
If a started DB2 rule application converses a window, its probably best to specify values for both the system ID and transaction ID fields. AppBuilder 3270 Converse applications execute in pseudoconversational mode (see Chapter 17, 3270 Converse). When a rule converses a window, the transaction that initiated the rule ends, and a new transaction starts. If no transaction ID is specified, HPECAPI determines its value from a table lookup of the rules system ID. Conversely, if no system ID is specified, HPECAPI determines its value from a table lookup of the rules transaction ID. Specifying both values obviates the table lookup and should improve interface performance.
IV-NAME
Specifies the eight-character system ID of the input view. If the rule has no input view, this field is not checked.
8-2
API for CICS (HPECAPI)
User COMMAREA
IV-PTR/ADDRESS
Specifies the pointer to the input view data. If the rule has no input view, this field is not checked.
IV-FLENGTH
Specifies the length of the input view. If the rule has no input view, set this field to +0.
OV-NAME
Specifies the eight-character system ID of the output view. If the rule has no output view, this field is not checked.
OV-PTR/ADDRESS
Specifies the pointer to the output view data, unless the rule was invoked with the CICS START with RETURN START option, in which case it contains an offset; for details, see CICS START with a RETURN START on page 8-8. If the rule has no output view, this field is not checked.
OV-FLENGTH
Specifies the length of the output view. If the rule has no output view, set this field to +0.
HPS-USER-PARM-EYECATCHER
Reserved for internal use. This field is initialized by the HCUUCOI copybook.
8-3
User COMMAREA
HPS-USER-PARM-FUNC
Specifies the method by which the rule is invoked: HPS-USER-PARM-FUNC-LINK invokes the AppBuilder application via a CICS LINK to the calling program. HPS-USER-PARM-FUNC-START invokes the AppBuilder application via a CICS START, with no information returned to the calling program. HPS-USER-PARM-FUNC-START-RET invokes the AppBuilder application via a CICS START, arranging for the CICS transaction specified in the HPS-USER-PARM-RET-TRAN field to be started on completion of the application. HPS-USER-PARM-FUNC-XCTL transfers control to the AppBuilder application via the CICS XCTL command. HPS-USER-PARM-FUNC-IMMRET invokes the AppBuilder application via a CICS RETURN IMMEDIATE, with no information returned to the calling program. HPS-USER-PARM-FUNC-IR-BACKI invokes the AppBuilder application via a CICS RETURN IMMEDIATE, arranging for the CICS transaction specified in the HPS-USER-PARM-RET-TRAN field to be initiated via a CICS RETURN IMMEDIATE on the completion of the AppBuilder Rule. The return information to be passed back in the input message. HPS-USER-PARM-FUNC-IR-BACKC invokes the AppBuilder application via a CICS RETURN IMMEDIATE, arranging for the CICS transaction specified in the HPS-USER-PARM-RET-TRAN field to be initiated via a CICS RETURN IMMEDIATE on the completion of the AppBuilder Rule. The return information to be passed back in the COMMAREA.
HPS-USER-PARM-SUBFUNC
Specify any of the desired optional subfunctions. If none of the optional subfunctions is desired, then select the HPS-USER-PARM-SUBFUNC-NORMAL option. If the Fast Path feature is desired, select the HPS-USER-PARM-SUBFUNC-FASTP option. Fast Path processing performs no validation of the input view and the output view data structures. This option can be used in a production environment to reduce the execution path length. If the Default Views feature is desired, select the HPS-USER-PARMSUBFUNC-DEFVIEW option.This option will allocate and initialize the storage for the views that are required by the rule that is to be invoked.
HPS-USER-PARM-RET-CODE
Contains a zero return code on successful completion of the rule, a non-zero return code if the parameter list passed is invalid. HPS-USER-PARM-ERR-MSG contains any error message number.
HPS-USER-PARM-USE-TERM
Specifies the ID of the terminal where a rule started with the CICS START command executes (see HPSUSER-PARM-FUNC). Set the field to SPACES or LOW-VALUES to start the rule unattached to a terminal.
8-4
Interface Options
HPS-USER-PARM-USE-TRAN
Specifies the transaction ID of a rule started with the CICS START command (see HPS-USER-PARMFUNC above). This field is optional for DB2 rules; you can specify the rules system ID in the RULENAME field instead. If the rule converses a window, its usually best to specify values for both fields. For a discussion, see RULE-NAME.
HPS-USER-PARM-RET-TERM
Specifies the ID of the terminal where the CICS transaction specified in HPS-USER-PARM-RET-TRAN is started on completion of the AppBuilder application. Set the field to SPACES or LOW-VALUES to start the transaction unattached to a terminal.
HPS-USER-PARM-RET-TRAN
Specifies the ID of the transaction started on completion of the AppBuilder application, or the transaction ID of a rule invoked with the CICS XCTL command. For DB2 rules invoked with the XCTL command, this field is optional; you can specify the rules system ID in the RULE-NAME field instead.
HPS-USER-PARM-ERR-MSG
Contains the message number for any error encountered in starting the rule.
Interface Options
The value of the HPS-USER-PARM-FUNC field determines how the calling program invokes the AppBuilder application.
CICS LINK
HPS-USER-PARM-FUNC-LINK invokes the AppBuilder application via a CICS LINK to the calling program. The input and output views of the linked rule are pointed to by the IV-PTR and OV-PTR fields, respectively. If the rule accesses DB2, the transaction that initiated the calling program must be bound with the DB2 plan access. Otherwise, a DB2 plan access abend occurs. You cannot use the LINK interface to invoke a rule that converses a window, because CICS does not permit a program to issue a return with a transaction ID if the program is not at the highest level in the linkage hierarchy. The following code sample illustrates the LINK interface using the Fast Path subfunction. Rule RDIC15 has the INOUT view VIEWB.
8-5
Interface Options
IDENTIFICATION DIVISION. PROGRAM-ID. SAMLINK. AUTHOR. CHRIS DOE INSTALLATION BluePhoenix Solutions *REMARKS. SAMPLE PROGRAM FOR LINK. * ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. IBM-370. OBJECT-COMPUTER. IBM-370. DATA DIVISION. WORKING-STORAGE SECTION. 01 THISPGM PIC X(8) VALUE 'SAMLINK'. 01 HCUUCOM. COPY HCUUCOM. COPY VIEWB. * LINKAGE SECTION. * * PROCEDURE DIVISION. MAINLINE SECTION. *** * INITIALIZE. *** COPY HCUUCOI. *** * ADDRESS THE INOUT VIEW. *** CALL 'HPSADDR' USING IV-ADDRESS, VIEWB. MOVE IV-ADDRESS TO OV-ADDRESS. *** * PASS INFORMATION IN AppBuilder USER COMMAREA. *** MOVE SPACES TO WIN-MESSAGE, RULE-RETCODE. MOVE 'RDIC15' TO RULE-NAME. MOVE 'VIEWB' TO IV-NAME. MOVE 'VIEWB' TO OV-NAME. MOVE LENGTH OF VIEWB TO IV-FLENGTH. MOVE IV-FLENGTH TO OV-FLENGTH. SET HPS-USER-PARM-FUNC-LINK TO TRUE. SET HPS-USER-PARM-SUBFUNC-FASTP TO TRUE. CALL 'HPECAPI' USING DFHEIBLK, HCUUCOM. IF HPS-USER-PARM-RET-CODE-ERR THEN EXEC CICS SEND FROM(HPS-USER-PARM-ERR-MSG) LENGTH(LENGTH OF HPS-USER-PARM-ERR-MSG) ERASE END-EXEC ELSE PERFORM PROCESS-OUTPUT END-IF. GOBACK. PROCESS-OUTPUT SECTION. ***
8-6
Interface Options
* THIS IS SAMPLE CODE TO PROCESS THE OUTPUT VIEW OF THE * RULE. 'WIN-MESSAGE' IS A FIELD IN THE VIEW 'VIEWB'. *** EXEC CICS SEND FROM(WIN-MESSAGE) LENGTH(LENGTH OF WIN-MESSAGE) ERASE END-EXEC.
CICS START
An mainframe program can invoke an AppBuilder application with a CICS START in either of two ways: CICS START with No Expected Return CICS START with a RETURN START
CICS START with No Expected Return

HPS-USER-PARM-FUNC-START invokes the AppBuilder application via a CICS START, with no information returned to the calling program. You can specify in the HPS-USER-PARM-USE-TERM field that the rule be started on the originating terminal, another terminal, or as a background task. Transfer the terminal ID from the EIBTRMID field to HPS-USER-PARM-USE-TERM to start the rule on the originating terminal. Set the field to SPACES or LOW-VALUES to start the rule unattached to a terminal as a background task. The input view of the started rule is pointed to by the IV-PTR field. You cannot recover the rules output view. If the rule has a unique transaction ID associated with it, you may be able to improve interface performance by specifying both the system ID and CICS transaction ID of the rule, as described in RULE-NAME. The following code sample illustrates the START with no return interface. Rule RATTR has the INOUT view VIEWB. IDENTIFICATION DIVISION. PROGRAM-ID. SAMSNOR. AUTHOR. CHRIS DOE. DATE-WRITTEN. JUNE 1993. DATE-COMPILED. TODAY. INSTALLATION. BluePhoenix Solutions APPBUILDER CICS RU NTIME ENVIRONMENT. *REMARKS. SAMPLE PROGRAM FOR START WITH NO RETURN. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. IBM-370. OBJECT-COMPUTER. IBM-370. DATA DIVISION. WORKING-STORAGE SECTION. 01 THISPGM PIC X(8) VALUE 'SAMSNOR'. * * AppBuilder USER APPLICATION INTERFACE COMMAREA PLACED BELOW. * 01 HCUUCOM.
8-7
Interface Options
COPY HCUUCOM. * * RULES INOUT VIEW PLACED BELOW. * COPY VI EW_B. **.*. \LINK LINKAGE SECTION. **.*. \PROC PROCEDURE DIVISION. MAINLINE SECTION. * * PASS INFORMATION TO APPBUILDER USER COMMAREA. * COPY HCUUCOI. MOVE SPACES TO WIN-MESSAGE, RULE-RETCODE. CALL 'HPSADDR' USING IV-ADDRESS, VIEWB. MOVE IV-ADDRESS TO OV-ADDRESS. MOVE 'RATTR' TO RULE-NAME. MOVE 'VIEWB' TO IV-NAME. MOVE 'VIEWB' TO OV-NAME. MOVE LENGTH OF VIEWB TO IV-FLENGTH. MOVE IV-FLENGTH TO OV-FLENGTH. MOVE EIBTRMID TO HPS-USER-PARM-USE-TERM. SET HPS-USER-PARM-FUNC-START TO TRUE. SET HPS-USER-PARM-SUBFUNC-NORMAL TO TRUE. CALL 'HPECAPI' USING DFHEIBLK, HCUUCOM. IF HPS-USER-PARM-RET-CODE-ERR THEN EXEC CICS SEND FROM(HPS-USER-PARM-ERR-MSG) LENGTH(LENGTH OF HPS-USER-PARM-ERR-MSG) ERASE END-EXEC END-IF. GOBACK.
CICS START with a RETURN START

HPS-USER-PARM-FUNC-START-RET invokes the AppBuilder application via a CICS START, arranging for the CICS transaction specified in the HPS-USER-PARM-RET-TRAN field to be started on completion of the application. You can specify in the HPS-USER-PARM-USE-TERM and HPS-USERPARM-RET-TERM fields that the rule or transaction, respectively, be started on the originating terminal, another terminal, or as a background task. Transfer the terminal ID from the EIBTRMID field to HPS-USER-PARM-USE-TERM to start the rule or transaction on the originating terminal. Set the field to SPACES or LOW-VALUES to start the rule or transaction unattached to a terminal as a background task. The input view of the started rule is pointed to by the IV-PTR field. The transaction initiated on completion of the AppBuilder application can recover any data passed to it via the CICS Retrieve command. The passed data is the AppBuilder User COMMAREA followed by the output view. In this case, the field OV-PTR contains an offset from the beginning of the retrieved data to the output view, rather than a pointer to the output view.
8-8
Interface Options
If the rule has a unique transaction ID associated with it, you may be able to improve interface performance by specifying both the system ID and CICS transaction ID of the rule, as described in RULE-NAME. The following code sample illustrates the START with RETURN START interface. Rule RATTR has the INOUT view VIEWB. Note that the program itself is restarted on completion of the rule. IDENTIFICATION DIVISION. PROGRAM-ID. SAMSRET. AUTHOR. CHRIS DOE. DATE-WRITTEN. JUNE 1993. DATE-COMPILED. TODAY. INSTALLATION. BluePhoenix Solutions APPBUILDER CICS RUNTIME ENVIRONMENT. *REMARKS. SAMPLE PROGRAM FOR START WITH RETURN START. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. IBM-370. OBJECT-COMPUTER. IBM-370. DATA DIVISION. WORKING-STORAGE SECTION. 01 THISPGM PIC X(8) VALUE 'SAMSRET'. 01 MSG-VARIABLES. 03 MSG-PTR POINTER. 03 MSG-ADDRESS REDEFINES MSG-PTR PIC S9(8) COMP. 03 MSG-LEN PIC S9(4) COMP. 03 VIEW-PTR POINTER. 03 VIEW-ADDRESS REDEFINES VIEW-PTR PIC S9(8) COMP. 03 COMM-PTR POINTER. 03 COMM-ADDRESS REDEFINES COMM-PTR PIC S9(8) COMP. 01 GETMAIN-VARIABLES. 05 GETMAIN-PTR POINTER. 05 GETMAIN-ADDRESS REDEFINES GETMAIN-PTR PIC S9(8) COMP. 05 GETMAIN-FLENGTH PIC S9(8) COMP. 05 INIT-CHAR PIC X. 01 START-CODE PIC X(2). 88 STARTED-VIA-TDQ VALUE 'QD'. 88 STARTED-VIA-IC-NO-DATA VALUE 'S '. 88 STARTED-VIA-IC-WITH-DATA VALUE 'SD'. 88 STARTED-VIA-TERMINAL VALUE 'TD'. 88 STARTED-VIA-ATTACH VALUE 'U '. **.*. \LINK LINKAGE SECTION. * * RULES INPUT & OUPUT VIEW PLACED BELOW. * COPY VIEWB. * * AppBuilder USER APPLICATION INTERFACE COMMAREA PLACED BELOW. *
8-9
Interface Options
01
HCUUCOM. COPY HCUUCOM. **.*. \PROC PROCEDURE DIVISION. MAINLINE SECTION. * * CHECK HOW THIS PROGRAM WAS INITIATED, AND PROCEED ACCORDINGLY. * EXEC CICS ASSIGN STARTCODE(START-CODE) END-EXEC. IF STARTED-VIA-IC-WITH-DATA THEN PERFORM PROCESS-OUTPUT-FROM-RULE END-IF. IF STARTED-VIA-TERMINAL THEN PERFORM START-RULE GOBACK. START-RULE SECTION. * * GET STORAGE FOR INOUT VIEW AND AppBuilder USER COMMAREA. * MOVE LOW-VALUES TO INIT-CHAR. MOVE LENGTH OF VIEWB TO GETMAIN-FLENGTH. ADD LENGTH OF HCUUCOM TO GETMAIN-FLENGTH. EXEC CICS GETMAIN SET (GETMAIN-PTR) INITIMG (INIT-CHAR) FLENGTH (GETMAIN-FLENGTH) END-EXEC. MOVE GETMAIN-ADDRESS TO COMM-ADDRESS, VIEW-ADDRESS. ADD LENGTH OF HCUUCOM TO VIEW-ADDRESS. SET ADDRESS OF VIEWB TO VIEW-PTR. SET ADDRESS OF HCUUCOM TO COMM-PTR. MOVE SPACES TO WIN-MESSAGE, RULE-RETCODE. MOVE VIEW-ADDRESS TO IV-ADDRESS. MOVE IV-ADDRESS TO OV-ADDRESS. * * PASS INFORMATION TO AppBuilder USER COMMAREA. * COPY HCUUCOI. MOVE 'RATTR' TO RULE-NAME. MOVE 'VIEWB' TO IV-NAME, OV-NAME. MOVE LENGTH OF VIEWB TO IV-FLENGTH. MOVE IV-FLENGTH TO OV-FLENGTH. MOVE EIBTRMID TO HPS-USER-PARM-RET-TERM HPS-USER-PARM-USE-TERM. MOVE EIBTRNID TO HPS-USER-PARM-RET-TRAN. SET HPS-USER-PARM-FUNC-START-RET TO TRUE. SET HPS-USER-PARM-SUBFUNC-NORMAL TO TRUE. CALL 'HPECAPI' USING DFHEIBLK, HCUUCOM. IF HPS-USER-PARM-RET-CODE-ERR THEN EXEC CICS SEND FROM(HPS-USER-PARM-ERR-MSG) LENGTH(LENGTH OF HPS-USER-PARM-ERR-MSG) ERASE END-EXEC
8-10
Interface Options
END-IF. * * WE GET HERE ON THE RETURN START. * PROCESS-OUTPUT-FROM-RULE SECTION. EXEC CICS RETRIEVE SET (MSG-PTR) LENGTH (MSG-LEN) END-EXEC. MOVE MSG-ADDRESS TO COMM-ADDRESS, VIEW-ADDRESS. SET ADDRESS OF HCUUCOM TO COMM-PTR. ADD OV-OFFSET TO VIEW-ADDRESS. SET ADDRESS OF VIEWB TO VIEW-PTR. EXEC CICS SEND FROM(RULE-RETCODE) LENGTH(LENGTH OF RULE-RETCODE) ERASE END-EXEC.
CICS XCTL
HPS-USER-PARM-FUNC-XCTL transfers control to the AppBuilder application via the CICS XCTL command. If the rule accesses DB2 before it converses a window, the transaction that initiated the calling program must be bound with the DB2 plan access. Otherwise, a DB2 plan access abend occurs. The storage area that holds the input view to the AppBuilder rule must be obtained via a CICS GETMAIN and not suballocated from the application program's working storage because on a CICS XCTL, the calling program's working storage is freed across the XCTL call. The following code sample illustrates the transfer of control interface. Rule RATTR has the INOUT view VIEWB. IDENTIFICATION DIVISION. PROGRAM-ID. SAMXCTL. AUTHOR. CHRIS DOE INSTALLATION BluePhoenix Solutions *REMARKS. SAMPLE PROGRAM TO SHOW XCTL INTERFACE. * ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. IBM-370. OBJECT-COMPUTER. IBM-370. DATA DIVISION. WORKING-STORAGE SECTION. 01 THISPGM PIC X(8) VALUE 'SAMXCTL'. 01 GETMAIN-VARIABLES. 05 GETMAIN-PTR POINTER. 05 GETMAIN-ADR REDEFINES GETMAIN-PTR PIC S9(8) COMP. 05 GETMAIN-FLENGTH PIC S9(8) COMP. 05 INIT-CHAR PIC X. 01 HCUUCOM. COPY HCUUCOM.
8-11
Interface Options
* LINKAGE SECTION. COPY VIEWB. * * PROCEDURE DIVISION. MAINLINE SECTION. *** * GET STORAGE FOR INOUT VIEW AND PASS POINTER IN * AppBuilder USER COMMAREA. *** MOVE SPACES TO INIT-CHAR. MOVE LENGTH OF VIEWB TO GETMAIN-FLENGTH. EXEC CICS GETMAIN SET (GETMAIN-PTR) INITIMG (INIT-CHAR) FLENGTH (GETMAIN-FLENGTH) END-EXEC. SET ADDRESS OF VIEWB TO GETMAIN-PTR. MOVE GETMAIN-ADR TO IV-ADDRESS. MOVE IV-ADDRESS TO OV-ADDRESS. *** * PASS INFORMATION IN AppBuilder USER COMMAREA. *** COPY HCUUCOI. MOVE 'RATTR' TO RULE-NAME. MOVE 'VIEWB' TO IV-NAME. MOVE 'VIEWB' TO OV-NAME. MOVE LENGTH OF VIEWB TO IV-FLENGTH. MOVE IV-FLENGTH TO OV-FLENGTH. SET HPS-USER-PARM-FUNC-XCTL TO TRUE. CALL 'HPECAPI' USING DFHEIBLK, HCUUCOM. IF HPS-USER-PARM-RET-CODE-ERR THEN EXEC CICS SEND FROM(HPS-USER-PARM-ERR-MSG) LENGTH(LENGTH OF HPS-USER-PARM-ERR-MSG) ERASE END-EXEC END-IF. GOBACK.
CICS RETURN IMMEDIATE

An mainframe program can invoke an AppBuilder application with a CICS RETURN IMMEDIATE in any of three ways: CICS RETURN IMMEDIATE, with No Expected Return CICS RETURN IMMEDIATE, with RETURN IMMEDIATE Back in the Input Message - issued at the completion of the AppBuilder rule and returning information in the input message CICS RETURN IMMEDIATE, with RETURN IMMEDIATE Back to CICS COMMAREA - issued at completion of the AppBuilder rule and returning information in the COMMAREA
8-12
Interface Options
CICS RETURN IMMEDIATE, with No Expected Return

HPS-USER-PARM-FUNC-IMMRET invokes an AppBuilder application via a CICS RETURN IMMEDIATE, with no information returned to the calling program. The IV-PTR field points to the input view of the AppBuilder rule to which the RETURN IMMEDIATE is made. You cannot recover the rules output view. If the rule has a unique transaction ID associated with it, you may be able to improve interface performance by specifying both the system ID and CICS transaction ID of the rule, as described in RULE-NAME on page 8-2. The storage area that is used to hold the input view to the AppBuilder rule must be obtained via a CICS GETMAIN and not suballocated from the application program's working storage because on a CICS RETURN IMMEDIATE, the program's working storage is freed on completion of the original program. The application program that calls HPECAPI must be at the highest logical level (for example, you cannot have PROGRAMA LINK to PROGRAMB which calls HPECAPI with a RETURN IMMEDIATE request). This is a CICS restriction. The following sample code illustrates the RETURN IMMEDIATE with no expected return interface. AppBuilder Rule RATTR has the INOUT view VIEWB. IDENTIFICATION DIVISION. PROGRAM-ID. SAMIMRE. AUTHOR. Chris Doe. DATE-WRITTEN. January 1995. DATE-COMPILED. TODAY. INSTALLATION. BluePhoenix Solutions HPS CICS Runtime Environment. *REMARKS. Sample program: RETURN IMMEDIATE with no expected return. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. IBM-370. OBJECT-COMPUTER. IBM-370. DATA DIVISION. WORKING-STORAGE SECTION. 01 THISPGM PIC X(8) VALUE 'SAMIMRE'. 01 MSG-VARIABLES. 03 VIEW-PTR POINTER. 03 VIEW-ADDRESS REDEFINES VIEW-PTR PIC S9(8) COMP. 03 COMM-PTR POINTER. 03 COMM-ADDRESS REDEFINES COMM-PTR PIC S9(8) COMP. 01 GETMAIN-VARIABLES. 05 GETMAIN-PTR POINTER. 05 GETMAIN-ADDRESS REDEFINES GETMAIN-PTR PIC S9(8) COMP. 05 GETMAIN-FLENGTH PIC S9(8) COMP. 05 INIT-CHAR PIC X. **.*. \LINK LINKAGE SECTION. * * Rule's input and output views placed below. * COPY VIEWB. *
8-13
Interface Options
* * 01
AppBuilder user application interface COMMAREA placed below.
HCUUCOM. COPY HCUUCOM. **.*. \PROC PROCEDURE DIVISION. MAINLINE SECTION. * * Pass information to AppBuilder User COMMAREA * MOVE LOW-VALUES TO INIT-CHAR. MOVE LENGTH OF VIEWB TO GETMAIN-FLENGTH. ADD LENGTH OF HCUUCOM TO GETMAIN-FLENGTH. EXEC CICS GETMAIN SET (GETMAIN-PTR) INITIMG (INIT-CHAR) FLENGTH (GETMAIN-FLENGTH) END-EXEC. MOVE GETMAIN-ADDRESS TO COMM-ADDRESS, VIEW-ADDRESS. ADD LENGTH OF HCUUCOM TO VIEW-ADDRESS. SET ADDRESS OF HCUUCOM TO COMM-PTR. SET ADDRESS OF VIEWB TO VIEW-PTR. COPY HCUUCOI. MOVE VIEW-ADDRESS TO IV-ADDRESS, OV-ADDRESS. MOVE 'TEST1' TO WIN-MESSAGE. MOVE 'TEST2' TO RULE-RETCODE. MOVE 'RATTR' TO RULE-NAME. MOVE 'VIEWB' TO IV-NAME. MOVE 'VIEWB' TO OV-NAME. MOVE LENGTH OF VIEWB TO IV-FLENGTH. MOVE IV-FLENGTH TO OV-FLENGTH. SET HPS-USER-PARM-FUNC-IMMRET TO TRUE. CALL 'HPECAPI' USING DFHEIBLK, HCUUCOM. IF HPS-USER-PARM-RET-CODE-ERR THEN EXEC CICS SEND FROM(HPS-USER-PARM-ERR-MSG) LENGTH(LENGTH OF HPS-USER-PARM-ERR-MSG) ERASE END-EXEC END-IF. GOBACK.
CICS RETURN IMMEDIATE, with RETURN IMMEDIATE Back in the Input Message
HPS-USER-PARM-FUNC-IR-BACKM invokes an AppBuilder application via a CICS RETURN IMMEDIATE, arranging for the CICS transaction specified in the HPS-USER-PARM-RET-TRAN field to be initiated via a CICS RETURN IMMEDIATE on completion of the AppBuilder Rule. The communications areas and output view are returned in the input message and can be obtained with a CICS RECEIVE command. If the rule has a unique transaction ID associated with it, you may be able to improve interface performance by specifying both the system ID and CICS transaction ID of the rule, as described in RULE-NAME.
8-14
Interface Options
The storage area which is used to hold the input view to the AppBuilder rule must be obtained via a CICS GETMAIN and not suballocated from the application program's working storage because on a CICS RETURN IMMEDIATE, the program's working storage is freed on completion of the original program. The application program that calls HPECAPI must be at the highest logical level (for example, you cannot have PROGRAMA LINK to PROGRAMB which calls HPECAPI with a RETURN IMMEDIATE request). This is a CICS restriction. The following code sample illustrates the RETURN IMMEDIATE, with RETURN IMMEDIATE back, passing data in the input message interface. AppBuilder rule RATTR has the INOUT view VIEWB. IDENTIFICATION DIVISION. PROGRAM-ID. SAMIRBM. AUTHOR. Chris Doe. DATE-WRITTEN. February 2002. DATE-COMPILED. TODAY. INSTALLATION. BluePhoenix Solutions AppBuilder CICS Runtime Environment. *REMARKS. Sample program: RETURN IMMEDIATE with RETURN IMMEDIATE back, output view in input message. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. IBM-370. OBJECT-COMPUTER. IBM-370. DATA DIVISION. WORKING-STORAGE SECTION. 01 THISPGM PIC X(8) VALUE 'SAMIRBM'. 01 MSG-VARIABLES. 03 MSG-PTR POINTER. 03 MSG-ADDRESS REDEFINES MSG-PTR PIC S9(8) COMP. 03 MSG-LEN PIC S9(4) COMP. 03 VIEW-PTR POINTER. 03 VIEW-ADDRESS REDEFINES VIEW-PTR PIC S9(8) COMP. 03 COMM-PTR POINTER. 03 COMM-ADDRESS REDEFINES COMM-PTR PIC S9(8) COMP. 01 GETMAIN-VARIABLES. 05 GETMAIN-PTR POINTER. 05 GETMAIN-ADDRESS REDEFINES GETMAIN-PTR PIC S9(8) COMP. 05 GETMAIN-FLENGTH PIC S9(8) COMP. 05 INIT-CHAR PIC X. **.*. \LINK LINKAGE SECTION. * * AppBuilder user application interface COMMAREA placed below. * 01 HCUUCOM. COPY HCUUCOM. * * Rule's input and output views placed below. *
8-15
Interface Options
COPY VIEWB. **.*. \PROC PROCEDURE DIVISION. MAINLINE SECTION. * * Receive the input msg, if message length is less than * the size of the HCUUCOM, then assume that we are starting * off fresh. Then check if the HCUUCOM is properly * populated, then we know that this is a restart, * otherwise, assume that we are starting off fresh. * EXEC CICS RECEIVE SET (MSG-PTR) LENGTH (MSG-LEN) END-EXEC. SET ADDRESS OF HCUUCOM TO MSG-PTR. IF MSG-LEN LESS THAN LENGTH OF HCUUCOM THEN PERFORM START-RULE ELSE IF RULE-NAME NOT EQUAL TO 'RATTR' THEN PERFORM START-RULE ELSE IF IV-NAME NOT EQUAL TO 'VIEWB' THEN PERFORM START-RULE ELSE PERFORM PROCESS-OUTPUT-FROM-RULE END-IF END-IF END-IF. GOBACK. START-RULE SECTION. * * Get storage for input and output views and for the AppBuilder * User COMMAREA. * MOVE LOW-VALUES TO INIT-CHAR. MOVE LENGTH OF VIEWB TO GETMAIN-FLENGTH. ADD LENGTH OF HCUUCOM TO GETMAIN-FLENGTH. EXEC CICS GETMAIN SET (GETMAIN-PTR) INITIMG (INIT-CHAR) FLENGTH (GETMAIN-FLENGTH) END-EXEC. MOVE GETMAIN-ADDRESS TO COMM-ADDRESS, VIEW-ADDRESS. ADD LENGTH OF HCUUCOM TO VIEW-ADDRESS. SET ADDRESS OF VIEWB TO VIEW-PTR. SET ADDRESS OF HCUUCOM TO COMM-PTR. * * Pass information to AppBuilder User COMMAREA * COPY HCUUCOI. MOVE 'RATTR' TO RULE-NAME. MOVE 'VIEWB' TO IV-NAME, OV-NAME. MOVE VIEW-ADDRESS TO IV-ADDRESS, OV-ADDRESS.
8-16
Interface Options
MOVE SPACES TO RULE-RETCODE. MOVE 'TEST1' TO WIN-MESSAGE. MOVE LENGTH OF VIEWB TO IV-FLENGTH, OV-FLENGTH. MOVE EIBTRNID TO HPS-USER-PARM-RET-TRAN. SET HPS-USER-PARM-FUNC-IR-BACKI TO TRUE. CALL 'HPECAPI' USING DFHEIBLK, HCUUCOM. IF HPS-USER-PARM-RET-CODE-ERR THEN EXEC CICS SEND FROM(HPS-USER-PARM-ERR-MSG) LENGTH(LENGTH OF HPS-USER-PARM-ERR-MSG) ERASE END-EXEC END-IF. * * We get here on the return Start. * PROCESS-OUTPUT-FROM-RULE SECTION. MOVE MSG-ADDRESS TO COMM-ADDRESS, VIEW-ADDRESS. SET ADDRESS OF HCUUCOM TO COMM-PTR. ADD OV-OFFSET TO VIEW-ADDRESS. SET ADDRESS OF VIEWB TO VIEW-PTR. EXEC CICS SEND FROM(RULE-RETCODE) LENGTH(LENGTH OF RULE-RETCODE) ERASE END-EXEC.
CICS RETURN IMMEDIATE, with RETURN IMMEDIATE Back to CICS COMMAREA

HPS-USER-PARM-FUNC-IR-BACKC invokes an AppBuilder application via a CICS RETURN IMMEDIATE, arranging for the CICS transaction specified in the HPS-USER-PARM-RET-TRAN field to be initiated via a CICS RETURN IMMEDIATE on completion of the AppBuilder rule. The communications area and output view are returned in the CICS COMMAREA, which means that HCUUCOM must be specified in the Linkage Section under DFHCOMMAREA. If the rule has a unique transaction ID associated with it, you may be able to improve interface performance by specifying both the system ID and CICS transaction ID of the rule, as described in RULE-NAME. The storage area that is used to hold the input view to the AppBuilder rule must be obtained via a CICS GETMAIN and not suballocated from the application program's working storage because on a CICS RETURN IMMEDIATE, the program's working storage is freed on completion of the original program. The application program that calls HPECAPI must be at the highest logical level (for example, you cannot have PROGRAMA LINK to PROGRAMB which calls HPECAPI with a RETURN IMMEDIATE request). This is a CICS restriction. The following code sample illustrates the RETURN IMMEDIATE with RETURN IMMEDIATE back, passing the data in the COMMAREA interface. Rule RATTR has the INOUT view VIEWB. IDENTIFICATION PROGRAM-ID. AUTHOR. DATE-WRITTEN. INSTALLATION. DIVISION. SAMIRBC. Chris Doe. February 1995. BluePhoenix Solutions
8-17
Interface Options
AppBuilder CICS Runtime Environment. *REMARKS. Sample program: RETURN IMMEDIATE, with RETURN IMMEDIATE back, passing data in COMMAREA. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. IBM-370. OBJECT-COMPUTER. IBM-370. DATA DIVISION. WORKING-STORAGE SECTION. 01 THISPGM PIC X(8) VALUE 'SAMIRBC'. 01 MSG-VARIABLES. 03 MSG-PTR POINTER. 03 MSG-ADDRESS REDEFINES MSG-PTR PIC S9(8) COMP. 03 MSG-LEN PIC S9(4) COMP. 03 VIEW-PTR POINTER. 03 VIEW-ADDRESS REDEFINES VIEW-PTR PIC S9(8) COMP. 03 COMM-PTR POINTER. 03 COMM-ADDRESS REDEFINES COMM-PTR PIC S9(8) COMP. 01 GETMAIN-VARIABLES. 05 GETMAIN-PTR POINTER. 05 GETMAIN-ADDRESS REDEFINES GETMAIN-PTR PIC S9(8) COMP. 05 GETMAIN-FLENGTH PIC S9(8) COMP. 05 INIT-CHAR PIC X. **.*. \LINK LINKAGE SECTION. * * AppBuilder user application interface COMMAREA placed below. * 01 DFHCOMMAREA. COPY HCUUCOM. * * Rule's input and output views placed below. * COPY VIEWB. **.*. \PROC PROCEDURE DIVISION. MAINLINE SECTION. * * Check length of COMMAREA passed, if it is equal or * greater than the size of the HCUUCOM, then assume * that we are returning from the AppBuilder Rule. * IF EIBCALEN LESS THAN LENGTH OF DFHCOMMAREA THEN PERFORM START-RULE ELSE IF RULE-NAME NOT EQUAL TO 'RATTR' THEN PERFORM START-RULE ELSE IF IV-NAME NOT EQUAL TO 'VIEWB' THEN PERFORM START-RULE ELSE
8-18
Interface Options
PERFORM PROCESS-OUTPUT-FROM-RULE END-IF END-IF END-IF. GOBACK. START-RULE SECTION. * * Get storage for input and output views and for the AppBuilder * User COMMAREA. * MOVE LOW-VALUES TO INIT-CHAR. MOVE LENGTH OF VIEWB TO GETMAIN-FLENGTH. ADD LENGTH OF DFHCOMMAREA TO GETMAIN-FLENGTH. EXEC CICS GETMAIN SET (GETMAIN-PTR) INITIMG (INIT-CHAR) FLENGTH (GETMAIN-FLENGTH) END-EXEC. MOVE GETMAIN-ADDRESS TO COMM-ADDRESS, VIEW-ADDRESS. ADD LENGTH OF DFHCOMMAREA TO VIEW-ADDRESS. SET ADDRESS OF VIEWB TO VIEW-PTR. SET ADDRESS OF DFHCOMMAREA TO COMM-PTR. * * Pass information to AppBuilder User COMMAREA * COPY HCUUCOI. MOVE 'RATTR' TO RULE-NAME. MOVE 'VIEWB' TO IV-NAME, OV-NAME. MOVE VIEW-ADDRESS TO IV-ADDRESS, OV-ADDRESS. MOVE SPACES TO RULE-RETCODE. MOVE 'TEST1' TO WIN-MESSAGE. MOVE LENGTH OF VIEWB TO IV-FLENGTH, OV-FLENGTH. MOVE EIBTRNID TO HPS-USER-PARM-RET-TRAN. SET HPS-USER-PARM-FUNC-IR-BACKC TO TRUE. MOVE EIBTRNID TO HPS-USER-PARM-RET-TRAN. CALL 'HPECAPI' USING DFHEIBLK, DFHCOMMAREA. IF HPS-USER-PARM-RET-CODE-ERR THEN EXEC CICS SEND FROM(HPS-USER-PARM-ERR-MSG) LENGTH(LENGTH OF HPS-USER-PARM-ERR-MSG) ERASE END-EXEC END-IF. * * We get here on the return Start. * PROCESS-OUTPUT-FROM-RULE SECTION. SET VIEW-PTR TO ADDRESS OF DFHCOMMAREA. ADD OV-OFFSET TO VIEW-ADDRESS. SET ADDRESS OF VIEWB TO VIEW-PTR. EXEC CICS SEND FROM(RULE-RETCODE) LENGTH(LENGTH OF RULE-RETCODE) ERASE END-EXEC.
8-19
Interface Options
8-20
CHAPTER
PREPARING IMS APPLICATIONS
You can design AppBuilder host applications and the host portion of cooperative applications to run in either of two environments: CICS or IMS. This section describes features and requirements unique to designing applications that will execute in an IMS environment. The information in this section assumes an understanding of how IMS/ESA works.
Designing IMS Applications

Host applications run the same in IMS and CICS, with few exceptions. In IMS host applications: All rules can be AppBuilder rules. Applications can do general processing (no database access) or access a DB2 database using SQL code. A rule uses the USE RULE or USE RULEINIT statement to call another rule. AppBuilder rules can call IMS programs (user components). Applications can perform system-specific functions, as described in Chapter 10, Writing IMS Components. Use this method to access a DL/I database. To call an IMS component, a rule uses the USE COMPONENT statement. IMS programs can call AppBuilder rules. Applications provide an established user front end to call an AppBuilder rule during system conversion or testing. Use the HPECAPI interface to implement this method. Chapter 11, Using IMS Interfaces: HPECAPI and HPUCV10 describes this method and interface.
Common IMS Considerations

The following items are attributes and settings common to IMS programming for AppBuilder on the mainframe: Setting the Execution Environment Attribute Preallocating IMS PSBs and Transaction Codes Specific Preallocated Items
9-1
Designing IMS Applications
Setting the Execution Environment Attribute

To execute a rule in IMS, set the rules Execution Environment attribute to IMS or PCIMS. A rule with a PCIMS Execution Environment attribute is treated as a workstation rule when prepared on the workstation, and as an IMS rule when prepared on the host. All of the rules in Table 9-1 can be tested using RuleView. An IMS rule has one of four processing types listed in Table 9-1.
Table 9-1 IMS Processing Types Description A rule that executes as a 3270 Converse rule. A rule that executes cooperatively or is invoked by a USE RULEINIT call. A rule that is called by a USE RULEINIT statement as an IMS BMP rule requires changing the default processing type and creating the correct command language. If a rule called by a USE RULEINIT statement is an IMS batch rule, you must change the default processing type and create the correct command language. A rule that accesses an offline database must be DL/I Batch. Processing Type Online conversational (TP with an SPA) Nonconversational (TP with no SPA) Batch message processing (BMP) DL/I Batch
Note
USE RULE .... INIT, 3270 Converse and RDTL are not supported for OpenCOBOL IMS.
Preallocating IMS PSBs and Transaction Codes

In IMS, several names are associated with a rule. These include an IMS transaction code, an IMS application name, a PSB name, and an ACB name. In some cases, these names must match for IMS to find all the necessary data, while in the AppBuilder environment, on the other hand, rules are created dynamically and executable names are generated when a rule is prepared. To reconcile these conflicting requirements, your AppBuilder administrator accommodates all IMS restrictions by preallocating a number of IMS application names (PSBs) and transaction codes. When you prepare a rule that accesses a DB2 database or whose children access a DB2 or a DL/I database, the rule is assigned an IMS application name and transaction code for a cooperative processing MPP rule. For 3270 converse, the fifth byte of the application name/transaction code is changed from an M to a C. For a rule initiated by a USE RULEINIT call, you can use the RDTL command to change the processing type to BMP or DL/I Batch. Thus, you can develop database access rules for IMS and have them execute dynamically without ongoing updates to the IMS generation input. Formatting Names Preallocated names follow this format: AAAAxnaa where: AAAA = the project ID. If the project ID is less than four characters, it is right-padded with zeroes. x = the IMS processing type. It can be one of three choices: M = Online nonconversational, the default value C = Online conversational B = Batch
9-2
Preparing IMS Applications
Writing and Processing IMS Applications
(The names allocated for all three types exist simultaneously so you can prepare a rule to run in any number of modes.) n = the version number of the repository in which this rule resides aa = two uppercase alphanumeric characters (AZ, 09) that uniquely identify the instance name Thus, there can be 1,296 names for each processing type in any one repository for a project. For example, SDEVM1AA would be the first name for an MPP rule in the version 1 repository for the SDEV project, SDEVM1AC would be the third, and SDEVM199 would be the last.
Specific Preallocated Items

The AppBuilder administrator allocates the following items before any development work starts for a project: Transaction allocation control records, which the preparation process uses to assign IMS transaction and application PSBs. Transactions for stage 1 input (application and source macros). Program specification blocks, one for each IMS processing type. Application control blocks. Stub program members. IMS requires that PSB and program load modules have the same name for a TP application and AppBuilder requires that the application and transaction code be the same. The use of a stub member helps satisfy both these requirements.

The following topics provide information to help you write IMS applications using only AppBuilder rules and describe the steps for automatic processing of TP, BMP, and DL/I Batch rules: USE RULEINIT Run Control Run Control Restrictions for BMP and DL/I Batch Rules TP Rule Processing BMP Rule Processing DL/I Batch Rule Processing Configuring BMP and DL/I Batch Rules
9-3
USE RULEINIT
The USE RULEINIT function, which starts a rule asynchronously with no return, is used to invoke TP, BMP, and DL/I Batch Rules automatically. This section details the function for enabling rules and the steps necessary to automatically process IMS TP, BMP, and DL/I application rules. This includes: Automatic online IMS region START and STOPS BMP and DL/I job member STARTS Note
USE RULE ... INIT is not supported when using OpenCOBOL. Only manual batch is supported from BMP and DLI. See Configuring BMP and DL/I Batch Rules.
Figure 9-1 diagrams a USE RULEINIT statement. It shows a host frontier rule that invokes independent AppBuilder rules which in turn process either in different TP Regions or as batch rules. (See the Rules Language Reference Guide for more information on the use of the USE RULEINIT statement.)
Figure 9-1 Frontier Rule Invoking Independent AppBuilder Rules
Run Control
When a frontier rule executes a USE RULEINIT statement, a transaction is created for the called rule. At that time, the called rules IMS processing type is not known. The rules transaction is sent to Run Control. Run Control determines how the called rule should be processed and initiates it correctly. TP Rule Processing BMP Rule Processing DL/I Batch Rule Processing
Run Control Restrictions for BMP and DL/I Batch Rules

A BMP or DL/I Batch rule cannot issue a USE RULEINIT function. Do not use the USE RULEINIT function for multiple calls to a BMP or DL/I Batch rule because Run Control will start a batch job member for each call.
9-4
TP Rule Processing
Using the Rule Processing Details (RDTL) action, AppBuilder IMS TP rules can be defined according to the AppBuilder rule details DB2. Specify the rules IMS processing type as TP. If the rule runs in an independent region, AppBuilder Run Control checks to see if the region is up. If not, it will start automatically. When a region member name is not specified, Run Control assumes that the region is already online. You can also update or view the rules IMS processing details DB2 table using the supplied AppBuilder A/E process (refer to IMS Run Control Status for details.) Note
RDTL action is not supported when using OpenCOBOL.
Run Control for TP Rules Run Control reads the input transaction and determines the rules IMS processing details. If the rules region name is blank, the rules transaction gets assigned to the correct transaction queue and inserted. If the region name exists, however, there will be a check to establish whether the region is already running. A rule started by Run Control that processes in an independent region must be informed when the processing has finished. There is no automatic detection to stop the online region because a higher-level rule could be coded to repeatedly issue USE RULEINIT to the same rule, creating multiple rule transactions and preventing Run Control from determining when the last transaction has been processed. The AppBuilder-supplied component, STOP_TP_RULE_ REGION, issues a message to Run Control (achieved by passing the STOP_TP_RULE_REGION rule in the Input View) to request that the process end. When the transaction is a request to stop a rules processing region, Run Control inserts the REQUEST TO COMPLETE transaction to the rules IMS queue, and the run time will process the transaction at the end of all the USE RULE...INIT transactions. REQUEST TO COMPLETE will be the last transaction in the queue and it will reply to Run Control with the COMPLETE status transaction. This process eliminates any premature STOP transactions of the region. Procedure - Preparing and Executing a TP Rule To prepare and execute a TP rule: 1. 2. 3. 4. 5. Create the calling (TP) rule with the USE RULEINIT statement and a call to the STOP_TP_RULE_REGION component. Create the called (TP) rule. Prepare the rules. Use the RDTL action for a rule being called, to make sure the rules processing type is TP. Execute the application.
Example - TP Rule View Name Field Name VRULEST (RULE_STOP_INIT) RETURN_KEY Char(2) RULE_NAME Char(8)
DO WHILE (I <= 100) ***--- Update the rule's input view ---*** USE RULE (rule name) INIT
9-5
MAP I + 1 to I ENDDO After the rule has been called for the last time, this or another rule can issue a call to the AppBuilder system component STOP_TP_RULE_REGION to request the completion of the process. Map the rules implementation name to the Rule_Name field. MAP ABOXXV to RULE_NAME OF RULE_STOP_INIT USE COMPONENT STOP_TP_RULE_REGION Check the RETURN_KEY field; any invalid IMS return code detected by the component is put into this field.
BMP Rule Processing

For a BMP rule, create a command language member for the rule by using the supplied template HPIBM10 and add the member to the IMS job library. Then, define the rule to be batch message processing by using the RDTL action to change its IMS processing type to BMP. Indicate the name of the BMP rules command language member on the rule details panel (RDTL). Note
Run Control for BMPRules At execution, Run Control starts the BMP command language member whose name you indicated on the rule details panel automatically. For USE RULEINIT batch processing, the called AppBuilder rules input transaction is stored on the Run Control database. When Run Control submits the job, the input transaction is read as a file. At successful completion of the process, a message is sent back to Run Control to complete the process by deleting the rules transaction data from the database. Procedure - Preparing and Executing a BMP Rule To prepare and execute a BMP rule: 1. 2. 3. 4. 5. 6. 7. 8. Create the calling (TP) rule with the USE RULEINIT statement. Create the called (BMP) rule. Prepare the rules. Create the called (BMP) rules command language member and note the name. Add the command language to the member library. For the called rule use the RDTL action to change the rules processing type to BMP and add the command language member name. Use the PSB action if you want to add more non-AppBuilder database PCBs. Execute the application.
Example - BMP Rule Note

This uses a command language template for a BMP display.
9-6
//JOBCARD //* //* This step enables the Run Control program HPIRCP4 to read the //* Run Control database for a PCIO0000 transaction //* awaiting processing by this rule. If it finds one, it writes it //* to the PCIO0000 file the AppBuilder BMP driver program processes. //* //* This step is not necessary if the AppBuilder environment does not //* automatically start this command language. You only need it for a //* USE RULE...INIT process or a restart from a previous error. //* //STEP1 EXEC PGM=DFSRRC00, // PARM='BMP,HPIRCP4,HPIRCP4,,,,,,,,,,,IMS-ID' //STEPLIB DD DISP=SHR,DSN=IMS and Rule Load library //PROCLIB DD DISP=SHR,DSN=IMS Procedure Library //IMS DD DISP=SHR,DSN=IMS PSB & DBD Library, if needed //DFSSTAT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSOUT DD SYSOUT=* //SYSABOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //PCIO0000 DD DSN=&&TEMP,DISP=(NEW,KEEP), // DCB=(RECFM=FB,LRECL=1923,BLKSIZE=1923) //* Rule's System ID //RULNAME DD * RuleName //IMSERR DD SYSOUT=* //SYSLOG DD SYSOUT=* //* //* EXECUTE AppBuilder BMP rule driver program //* //STEP2 EXEC PGM=DFSRRC00, // PARM='BMP,HPIBM10(1),Rule-PSB-Load(2),,,,,,(4),,,,,IMS-ID(3)' //STEPLIB DD DISP=SHR,DSN=IMS and Rule Load library //PROCLIB DD DISP=SHR,DSN=IMS Procedure Library //IMS DD DISP=SHR,DSN=IMS PSB & DBD Library, if needed //DFSSTAT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSOUT DD SYSOUT=* //SYSABOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //IMSLOGR DD DSN=Used for Symbolic Checkpoint Restart(5) //PCIO0000 DD DSN=&&TEMP,DISP=(OLD,DELETE,DELETE) //* Rule's System ID //RULNAME DD * RuleName //IMSERR DD SYSOUT=* //SYSLOG DD SYSOUT=* /*
9-7
Notes to Line 2 of STEP2 The program name specified is the AppBuilder IMS A/E Common BMP driver routine (HPIBM10). The PSB name is the name of the batch application assigned by the AppBuilder environment. That is, the fifth byte of the application name is B for batch. The IMS system ID. The checkpoint ID if an IMS extended restart is to be performed. You must specify this card when a restart is performed and the IMS online log data set does not contain the checkpoint ID. Also note that the AppBuilder IMS rules BMP command language needs to be added to the IMS Job Library. And the PSB created by the AppBuilder environment must be updated if further nonAppBuilder database PCBs.
DL/I Batch Rule Processing

As with BMP rules, for DL/I Batch rules, you must create a command language member for the rule, use the supplied template (HPIDLI0) and add the member to the IMS job library. The IMS Batch DL/I command language member, as well as the rules IMS Processing Type, must be entered in the Rule Details table (RDTL). Note
To create a command language member for a DL/I Batch rule, you must include the extra steps: Make an IMS user database available to the DL/I program and stop it Make messages produced by the AppBuilder IMS Common Batch driver program available to the online Message Log panel Send a message back to Run Control to inform it of completion Add the completed command language member to the IMS job library Run Control for DL/I Batch Rules As with BMP, Run Control will start the DL/I job automatically. Procedure - Preparing and Executing a DL/I Batch Rule To prepare and execute a DL/I Batch rule: 1. 2. 3. 4. 5. 6. 7. Create the calling (TP) rule with the USE RULEINIT statement. Create the called (DL/I Batch) rule. Prepare the rules. Create the called (DL/I Batch) rules command language member and note the name. Add the command language to the member library. For the called rule use the RDTL action to change the rules processing type to DL/I Batch and add the command language member name. Execute the application.
9-8
Example - DL/I Batch Rule //* JOB CARD //* //* Step 1 enables the Run Control program HPIRCP4 to read the //* Run Control database for the rule's PCIO0000 transaction //* segment awaiting processing. If it finds one, it writes it to //* the PCIO0000 file the AppBuilder BMP driver program processes. //* //* This step is not necessary if the AppBuilder environment does not //* automatically start this command language. You only need it for a //* USE RULE...INIT process or a restart from a previous error. //* //STEP1 EXEC PGM=DFSRRC00. // PARM='BMP,HPIRCP4,HPIRCP4,,,,,,,,,,,(3)'See Notes //STEPLIB DD DISP=SHR,DSN=IMS RESLIB library // DD DISP=SHR,DSN=AppBuilder/IMS Application Library //PROCLIB DD DISP=SHR,DSN=IMS Procedure Library //DFSSTAT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSOUT DD SYSOUT=* //SYSABOUT DD SYSOUT=* //PCIO0000 DD DSN=&&TEMP,DISP=(NEW,KEEP), // DCB=(RECFM,LRECL=1923,BLKSIZE=1923) //* rule's System ID //RULENAME DD * RuleName //IMSERR DD SYSOUT=* //SYSLOG DD SYSOUT=* //* //* DBRecover or DBDump any user databases that this //* rule's components access //* //STEP2 EXEC PGM=DFSRRC00, // PARM='BMP,HPI100P,HPI100P,HPI100,,,,,,,,,,(3)' //STEPLIB DD IMS libraries //SYSUDUMP DD SYSOUT=* //PLIDUMP DD SYSOUT=* //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //REPORT DD SYSOUT=*,DCB=(RECFM=FB,LRECL=133,BLKSIZE=1330) //CMDIN DD * /DBD DB User_DB NOFEOV //* //* DL/I Batch rule job //* EXECUTE AppBuilder Batch DLI RULE (rule name) //* //STEP3 EXEC PGM=DFSRRC00, // PARM='DLI,HPIDLI0(1),(2),,,,,,,,,,,' //STEPLIB DD IMS Libraries //SYSUDUMP DD SYSOUT=* //SYSOUT DD SYSOUT=* //HPI001D1 DD DISP=SHR,DSN=VIEWDEF Vsam Dataset Name //PCIO0000 DD DISP=(OLD,DELETE,DELETE),DSN=&&TEMP
9-9
//RULENAME DD * Rule-Name //* //MSGFILE DD A 172 BYTE LRECL dataset, //* //* START the user databases //* //STEP3 EXEC PGM=DFSRRC00, // PARM='BMP,HPI100P,HPI100P,HPI100,,,,,,,,,,(3)' //STEPLIB DD IMS libraries //SYSUDUMP DD SYSOUT=* //PLIDUMP DD SYSOUT=* //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //REPORT DD SYSOUT=*,DCB=(RECFM=FB,LRECL=133,BLKSIZE=1330) //CMDIN DD * /STA DB User-DB //* //* Inform overall Run Control that the job has completed //* //STEP4 EXEC PGM=DFSRRC00, // PARM='BMP,HPIRCP2,HPIRCP2,,,,,,,,,,,(3)' //STEPLIB DD IMS libraries //SYSUDUMP DD SYSOUT=* //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //RULENAME DD * RULE-NAME //* //* Insert message produced by the AppBuilder batch driver into the //* error log message queue to enable online access via the //* Message Log screen. //* //STEP5 EXEC PGM=DFSRRC00, // PARM='BMP,HPIRCP3,HPIRCP3,,,,,,,,,,,(3)' //STEPLIB DD IMS libraries //SYSUDUMP DD SYSOUT=* //SYSOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //MSGFILE DD library name in STEP 2* //* Notes The program name specified is the AppBuilder IMS Common Batch driver routine (HPIDLI0) The PSB name is the batch name supplied for a BMP rule The IMS system ID
9-10
Configuring BMP and DL/I Batch Rules

The following additional information is offered to control IMS application execution: Manual Batch Rule Initiation Basic IMS Checkpoint Extended Restart and Symbolic Checkpoint Synchronization Point Call
Manual Batch Rule Initiation

You can submit batch rules manually. When a batch rule is submitted manually, the rules driver program attempts to read the PCIO0000 file input. If it finds data, it uses the data to build the input view for the rule. If there is no data but the rule has an input view, the driver program sets up an input view area initialized to the specific field types of the view. Both BMP and DL/I Batch rules can, therefore, run with or without input data, as long as the rule defines an input view. When using OpenCOBOL the rule is called directly. PCIO0000 is not invoked and therefore cannot allocate the input data for the rule. The frontier rule cannot have input or output views.
Basic IMS Checkpoint

The basic IMS checkpoint call allows you to commit database updates during the processing of a batch rule. You must put all IMS checkpoint calls and the program logic into the user component for any restart.
Extended Restart and Symbolic Checkpoint

The symbolic checkpoint allows a batch process to commit database updates, along with saved data areas to be used when the extended restart facility is invoked. The extended restart can be achieved by either the components specifying the checkpoint ID in the Work-Area of the extended restart call, or by the checkpoint ID being coded in the PARM field of the EXEC statement of the command language rules. A component must issue the extended restart and symbolic checkpoint calls. The AppBuilder driver programs are not affected by a checkpoint restart or a database commit: the driver programs do not perform updates of the AppBuilder repository. Refer to the IMS/ESA manuals for more information on checkpoints and extend restart facilities.
Synchronization Point Call

Batch rules that need to perform a database commit without using checkpoint calls or the extended restart facility can issue IMS synchronization point calls through a user component.
9-11
IMS Actions and Utilities

AppBuilder provides actions and utilities for easy IMS application development. PSB - Generation Action Updating a Rules IMS Processing Details (RDTL) IMS Run Control Status Message Log Rule Selection List: HPR0
PSB - Generation Action

The PSB action allows you to modify the default IMS program specification block (PSB) assigned to a specific rule. All rules attached to a transaction also have a corresponding PSB. This PSB specifies which IMS databases and queues the rule uses. You need to modify the PSB only if a component within the rules hierarchy accesses an IMS database outside of the AppBuilder Environment. A rules plan name defaults to its transaction name. You must perform a PR (prepare) action before you can use the PSB action. When you issue PSB, the panel shown in Figure 9-2 is displayed.
Figure 9-2 PSB Generation Panel
IMS COMMAND===> PSB GENERATION PANEL
THE FOLLOWING OPTIONS ARE USED TO MODIFY AN IMS PSB SOURCE MODULE Rule Name AND command language FOR THE GENERATION OF THE LOAD MODULE FOR RULE PSB Name.
1 2 3 Block
Edit PSB Source Module SDEVM1AA PSBGEN command language to Generate Load Module. ACBGEN command language to Generate Application Control
The following choices are available in the PSB Generation panel: Edit PSB Source Module This option allows you to edit the PSB source to add any additional user databases. The position of the databases in the PSB is not important because AppBuilder IMS applications use IMS AIB calls to reference the databases by name. PSBGEN command language to Generate Load Module This option creates a temporary file containing the command language needed to generate three PSB load modules. These modules have the same IMS application names as those the system administrator generates. This allows a rule to run non-conversational TP, conversational, and batch. To invoke this job, enter SUB (for submit) on the command line above the command language. ACBGEN command language to Generate Application Control Block
9-12
This option creates a temporary file containing the command language needed to generate the application control blocks (ACBs) for the specified rule. These ACBs have the same IMS application names as those the system administrator generates. To invoke this job, enter SUB (for submit) on the command line above the command language. If you generated a PSB, you must also generate an ACB.
Updating a Rules IMS Processing Details (RDTL)

This action allows you to update the default IMS processing details for a rule that is invoked asynchronously with a USE RULE...INIT statement. Run Control uses these details to start a rule automatically. You may need to change the details if you change the rules region name or the rules processing mode. When you use the RDTL action, the panel shown in Figure 9-3 is displayed.
Figure 9-3 Rules IMS Processing Details Panel
AppBuilder RULES IMS PROCESSING DETAILS PANEL COMMAND===> This Panel is used only when a Rule is invoked by a USE RULE INIT function
The following options are needed to add/update the AppBuilder Rules IMS Processing details to enable the automatic processing of Rule RUNCTLM in a USE-RULE-INIT function AppBuilder Rule Name DB2 Plan/Transaction/Application Name Rules IMS Processing Type IMS Region/command language Member Name ==>SDEVM1AA ==> TP TP,BMP or DLI ==> ==>RUNCTLM
The rule name and the DB2 plan/transaction/application name are defaults and you cannot change them. The rules IMS processing type defaults to TP. The IMS region and batch command language members must be in the IMS job control library to enable automatic initiation. If you leave a TP rules IMS region/command language member name blank, Run Control assumes that the region for the rules transaction is online. Therefore, it does not issue a /START REGION command. If you leave that name blank for a BMP or batch DL/I rule, Run Control does not automatically start the command language member. Using the rule name for the data set name is preferred.
IMS Run Control Status

This is an AppBuilder 3270 converse application which you can use to: Add or update a rule's IMS processing details List and delete the jobs assigned to a BMP or DLI batch rule Submit/re-submit a BMP or DLI batch rule
9-13
To start the application in IMS, type HPRC, followed by a blank.
Rule Processing Details Panel

Figure 9-4 shows the main panel of the Run Control Status application, the Rule Processing Details panel. This panel lists all IMS rules defined via the repository to the IMS Rule Processing Details table. Each rule displays its own repository-generated transaction code.
Figure 9-4 Sample IMS Rule Processing Details Panel
AppBuilder/IMS Rule Processing Details Update language Status _ _ _ _ TRAN4 BMP _ RULE1___ RULE2___ RULE3___ RULE4___ JOB4____ ________ PROCESSING ___ ________ TRAN1 TRAN2 TRAN3 TP_ TP_ DLI REGION2_ JOB3____ Processing Code Name Code Type Member Name Rule IMS Tran Proc Region/command
HPS001 I - Rule IMS Details listed successfully F2=LIST F3=EXIT F4=UPDATE F5=ADD F6=DETAILS F9=DELETE F10=SUBMIT
In Figure 9-4, RULE1 and RULE2 process as MPPs when invoked by a USE RULE...INIT. RULE2 has a region assigned, so Run Control checks and, if necessary, starts the region in order for the rule to process. RULE3 and RULE4 are batch rules. RULE3 has been defined as DLI, and RULE4 as BMP. For AppBuilder purposes the DLI and BMP definitions have no effect on run-time processing. It is only for user status purposes. RULE1, RULE2 and RULE3 have no processing status against them, so there is no outstanding requests on them. RULE4 is in a status of processing. This means a USE RULE...INIT has been issued, but either the job has not finished or it ended in error. Function Keys - Run Control Status Table 9-2 shows the function key assignments for the Run Control Status main panel.
Table 9-2 Key F2 F3 F4 F5 F6 F9 Function Keys for Run Control Status Command LIST EXIT UPDATE ADD DETAILS DELETE Description Refreshes the current list. Exits this application. To update the Processing Type and Region/command language member name, type / in the Update Code area of one or more rules and press F4. To add new rules and their processing, type / in the Update Code area of the clear input line and press F5. To view task details of a started task, type / in the Update Code area of one or more rules and press F6. Figure 9-5 shows the panel that is displayed. To delete a rule and its details from the Details panel, type / in the Update Code area of one or more rules and press F9.
9-14
Table 9-2 Key
Function Keys (Continued)for Run Control Status Command Description To submit an AppBuilder batch rule, type / in the Update Code area of one or more rules and press F10. This option is available when the processing status is blank. If a rule does not require a specific input view, it can be submitted directly without issuing a USE RULE...INIT from another rule.
F10
SUBMIT
Rule Batch Status Panel

Figure 9-5 shows a sample of the panel that is displayed when you select Details (F6) from the Run Control Status main panel for a DLI or BMP rule.
Figure 9-5 Sample Rule Batch Status Panel
Rule Batch Details
Rule IMS Processing Type BMP
RULE4
Sequence Date Time Number
Processing Status
940628 940628 940628 940628 940629 940630 940630 940707 940707
1635211 1649503 1717018 1800273 937276 905180 917409 1129133 1358529 98
37 43 49 55 22 54
PROCESSING PROCESSING PROCESSING PROCESSING PROCESSING PROCESSING PROCESSING
36 16
PROCESSING PROCESSING
HPS001 I - Rule IMS Details listed successfully
F2=LIST F3=RETURN F4=DELETE F5=SUBMIT
In the example in Figure 9-5, RULE4 has been started nine times and has not yet completed. Each of the jobs shown could have been started by other rules or from this panel. The Date, Time and Sequence for each job was extracted from the Run Control message and used as a key to the rule's batch details database segment. Note
If these jobs remain on the Run Control database an error must have occurredbecause Run Control deletes the job segments when notified of completion. Check the command language output for any possible errors. If a rule abnormally ends, the above status remains until either the rule is RESUBMITTED and completes successfully, or the job details are deleted.
Function Keys - Rule Batch Details Table 9-3 shows the function key assignments for the Rule Batch Details panel.
Table 9-3 Key F2 Function Keys for Rule Batch Details Command LIST Description Refreshes the current list.
9-15
Table 9-3 Key F3 F9 F10
Function Keys for Rule Batch Details Command RETURN DELETE SUBMIT Description Returns to the main Run Control panel. Deletes the details of the oldest job from the Run Control database. Submits this rule. If a rule does not require a specific input view, it can be submitted directly without issuing a USE RULE.......INIT from another rule.
Message Log
The Error Log (Figure 9-6) displays all error and informational messages by date and time, as they were produced during application execution. To view the Error Log in IMS, enter 'HPISEC4 ' A list of the latest messages will be generated. The most recent error message appears at the top of the list. See the Reading the Error Log, Input Field, and Function Keys - IMS Error Log sections to learn how to assess the data and use the message log window.
Figure 9-6
HPISM4 HPIERRL
AppBuilder IMS Error Log Panel

BLUEPHOENIX E R R O R APPBUILDER L O G DATE : 08/04/02 TIME : 22:14:31 MORE : - +
ABEND / ITEM MSG CODE TERM DATE TIME
PROCESS/ PROGRAM TRAN USER ID WORKST ID
----- -------- -------- -------- -------- -------- -------- -------- --------00773 HPS4004I ST02B 00772 HPS4004I ST02B 00771 HPS4004I ST02B 00770 HPS4004I ST02A 00769 HPS4404E ST02A 00768 HPS4404E ST02A 00767 HPS4404E ST02A 00766 HPS4404E ST02A 00765 HPS4404E ST02A 00764 HPS4404E ST02A 00763 HPS4404E ST02A 00762 HPS4404E ST02A 92/07/17 21:07:14 HPIUTBL 92/07/17 21:06:10 HPIUTBL 92/07/17 20:50:18 HPIUTBL 92/07/17 14:09:00 HPIUTBL 92/07/17 13:21:40 HPIPC50 92/07/16 22:32:10 HPIPC50 92/07/16 22:31:07 HPIPC50 92/07/16 22:30:35 HPIPC50 92/07/16 22:29:37 HPIPC50 92/07/16 22:29:28 HPIPC50 92/07/16 22:27:38 HPIPC50 92/07/16 22:27:26 HPIPC50 UTBL0000 UTBL0000 UTBL0000 UTBL0000 PCIO0000 PCIO0000 PCIO0000 PCIO0000 PCIO0000 PCIO0000 PCIO0000 PCIO0000 ST02B ST02B ST02B ST02A PHILIP_CO PHILIP_CO PHILIP_CO PHILIP_CO PHILIP_CO PHILIP_CO PHILIP_CO PHILIP_CO
00761 HPS4404E ST02A 92/07/16 22:23:22 HPIPC50 PCIO0000 PHILIP_CO ------------------------------------------------------------------------------ENTER ITEM NUMBER : RESPONSE : PF3 = EXIT PF5 = ERROR LOG TEXT PF8 = FORWARD IN TIME PF7 = BACK IN TIME
Reading the Error Log

Table 9-4 describes the column headings for the IMS Error Log.
Table 9-4 Column Headings in the IMS Error Log Description The key to the Error Log database. An administrator can define the number of messages the database can hold when installing the log. When the number of messages reaches the maximum, the item number is reset to 2, and any message previously assigned to that item gets replaced. The AppBuilder error message number. Column heading
ITEM
ABEND/MSG CODE
9-16
Table 9-4
Column Headings in the IMS Error Log (Continued) Description The terminal ID associated with the message. The date the message was issued. The time the message was issued. The program that issued the message. The IMS transaction ID associated with the message. The user ID associated with the message. The workstation ID associated with the message.
Column heading TERM DATE/TIME TIME PROCESS/ PROGRAM TRAN USER ID WORKST ID
Input Field
Table 9-5 describes the input field.
Table 9-5 Input Field in the IMS Error Log Description Entering a number here resets the list, putting the indicated item at the top. Column heading ENTER ITEM NUMBER
Function Keys - IMS Error Log

Table 9-6 describes the function keys in the IMS Error Log.
Table 9-6 F key F3 F8 F7 F5 Function Keys in the IMS Error Log Name Exit Forward in Time Back in Time Error Log Text Description Ends conversation. Displays more recent messages, if available. If no more are available, an information message appears in the Response field. Displays older messages, if available. If no more are available, an information message appears in the Response field. Displays the text of the error messages listed on the current page (see Figure 9-7).
Note
Figure 9-7
Press any key to return to the previous screen. AppBuilder IMS Error Log Text Panel
9-17
HPISM5 HPIERRL
BLUEPHOENIX E R R O R
APPBUILDER L O G
I M S
DATE : 08/05/02 TIME : 13:48:40
T E X T
E R R O R L O G M E S S A G E T E X T ----------------------------------------------------------------------------HPS4004I -- RPHMFD HPS4004I -- RPHMF HPS4004I -- RPHMFD HAS BEEN SETUP SUCCESSFULLY WITH TRANSID HPSTEST1 HAS BEEN SETUP SUCCESSFULLY WITH TRANSID RPHMF000 HAS BEEN SETUP SUCCESSFULLY WITH TRANSID RPHMF000
HPS4004I -- RRTUIMS HAS BEEN SETUP SUCCESSFULLY WITH TRANSID RRTUIMS0 HPS4404E -- VIEW RECORD NOT FOUND ERROR HPS4404E -- VIEW RECORD NOT FOUND ERROR HPS4404E -- VIEW RECORD NOT FOUND ERROR HPS4404E -- VIEW RECORD NOT FOUND ERROR HPS4404E -- VIEW RECORD NOT FOUND ERROR HPS4404E -- VIEW RECORD NOT FOUND ERROR HPS4404E -- VIEW RECORD NOT FOUND ERROR HPS4404E -- VIEW RECORD NOT FOUND ERROR HPS4404E -- VIEW RECORD NOT FOUND ERROR -----------------------------------------------------------------------------
ENTER = RETURN TO ERROR LOG SCREEN
Rule Selection List: HPR0

HPR0, the AppBuilder Rule Selection List facility, displays a list of IMS rules available to be tested. Invoke this facility from a 3270 terminal session with IMS using the HPR0 transaction. Running HPR0 is essentially the same using IMS or CICS. For information on testing an AppBuilder IMS application using Batch Terminal Simulation, see BTS on page 5-4.
9-18
CHAPTER
10
WRITING IMS COMPONENTS
In addition to the standard reasons for using a component, you use a component in an AppBuilder IMS application to access DL/I databases or message queues. This includes standard file access for an online TP application. The component itself can be written in COBOL, PL/I, C, or assembler. You can access an IMS component either through IMS AIB logic or through a conventional call (ASMTDLI for assembler, CBLTDLI for COBOL, or PLITDLI for PL/I). IMS AIB interface calls do not require any changes. You can directly access a database or queue by referencing the name of the Program Control Block (PCB). Warning
This release of AppBuilder does not support accessing DL/I databases directly from a rule.
The topics covered in this section are: Accessing the IMS Database Mapping Input View Parameters Calling a PL/I Component Sample Components Component Communications Area (HPSCOMM)
Accessing the IMS Database

To access an IMS database in the conventional (non-AIB) way, use the GET_IMS_PCB_ADDR system component. Call the GET_IMS_PCB_ADDR component to obtain the address of the PCB, then pass this address to your user-written component. The user component can now reference that field as an address and base the list of PCBs to it. This component is a part of the default repository. Example - Accessing the IMS Database USE COMPONENT GET_IMS_PCB_ADDR MAP IMS_PCB_LIST_ADDR OF GET_IMS_PCB_ADDR_VIEW TO PCB_BASE_ADDRESS OF USER_COMPONENT_I USE COMPONENT USER_COMPONENT
10-1
Mapping Input View Parameters
Mapping Input View Parameters

There are two parameters you must map to the input view of the component. The first is reserved for use by AppBuilder. The second is the AppBuilder Communications Area. Include these parameters in the procedure statement in a COBOL or PL/I component. Within an assembler language component, offset register 1 by 4 bytes to obtain the communications area. Refer to the COBOL, PL/I and assembler language examples in Sample Components. Note
These parameters are not addresses, therefore, the user component receives them as defined storage areas and not as pointers.
Calling a PL/I Component

When prepared, an AppBuilder rule becomes COBOL II code which makes dynamic calls. Normally, there is a PL/I interlanguage support restriction of static calls only. To make a dynamic COBOL call to a PL/I component, do the following: Within the PL/I component, specify COBOL, NOMAP for the PROCEDURE option parameters. Specify the following linkage editor control statements for the PL/I user component.
Table 10-1 IMS Linkage Editor Control Statements
CHANGE INCLUDE INCLUDE ENTRY MODE NAMDE
RDUMMY(PL/I-Component) SYSLIB(HPIBRGE) OBJECT(PL/I-Component) HPIBRGE AMODE(31) RMODE(ANY) PL/I-Component(R)
Reference Component Front-end COBOL program AppBuilder component code
The component prepare action for an IMS PL/I component will generate the correct linkage editor control statements. Follow the PL/I and COBOL II language reference and IMS manuals for interlanguage support guidelines and restrictions.
Sample Components
Component code samples for the items include: Assembler Batch (using DB2) COBOL (using IMS AIB and Checkpoint Restart) PL/I (Using IMS non-AIB)
10-2
Writing IMS Components
Sample Components
Assembler Batch (using DB2)

*ASM XOPTS(NOPROLOG,NOEPILOG) TITLE 'Test batch component linkage' SQLWSREG EQU R7 SQL Working storage base SQLCAREG EQU R8 Program dynamic storage base R0 EQU 0 R1 EQU 1 R2 EQU 2 R3 EQU 3 R4 EQU 4 R5 EQU 5 R6 EQU 6 Inout View R7 EQU 7 Program storage R8 EQU 8 SQL Working Storage R9 EQU 9 R10 EQU 10 R11 EQU 11 Commarea R12 EQU 12 Program Base R13 EQU 13 R14 EQU 14 R15 EQU 15 CTPABD CSECT * PRINT NOGEN SPACE STM R14,R12,12(R13) Save caller's registers SPACE LR R12,R15 Use 12 as base register USING CTPABD,R12 as 15 used by DB2 ST R13,SAVE13 Store Address Savearea LA R13,SAVEAREA Load DB2 savearea address L R11,4(,R1) Communication area address USING COMMAREA,R11 Notify assembler SPACE L R6,ADDRESSI Address of input view USING CTPABDI,R6 Notify assembler SPACE * * ADDRESS SQLCA STORAGE LA SQLCAREG,SQLSTOR Get address for SQL area USING SQLCADS,SQLCAREG Tell assembler * * ADDRESS SQL WORKING STORAGE LA SQLWSREG,SQLWSTOR Get SQL work area address USING SQLDSECT,SQLWSREG Tell assembler * EXEC SQL SELECT TSNAME X INTO :MESSAGE X FROM SYSIBM.SYSTABLES X WHERE CREATOR = 'SYSIBM' X AND NAME = 'SYSTABLES' * MVC RETCODE,SQLCODE Copy SQLCODE to return code CLI SQLCODE,X'00'
10-3
Sample Components
SQLERR RETURN *
BNE MVC B EQU MVC EQU
SQLERR MESSAGE,MESSOK RETURN * MESSAGE,MESSERR *
Copy OK msg to inout view
Copy ERR msg to inout view
L R13,SAVE13 LM R14,12,12(R13) SPACE BR R14 EJECT LTORG EJECT * * * MESSOK MESSERR ALIGN SQLSTOR FILLER SAVEAREA SAVE13 * COMMAREA * SQLCADS PROGRAM STATIC STORAGE DC DC DC DC DC DC DC
Restore R13 Restore caller's registers Return to caller
C'ASSEMBLER BATCH DB2 COMP OK !' C'ASSEMBLER BATCH DB2 FAILED !' D'0' CL(SQLCAL)' ' F'0' 9D'0' F'0'
DSECT COPY COMMAREA
DSECT SQL Work area DS 0D SQLWSTOR DS (SQLDLEN)C Reserve storage for SQLDESCT DS 0D * EXEC SQL INCLUDE SQLCA * SQLCAL EQU *-SQLCADS Length of required storage * CTPABDI DSECT Input Output View DS 0F MESSAGE DS CL30 RETCODE DS F SPACE END CTPABD
COBOL (using IMS AIB and Checkpoint Restart)

000100* .$.0 030393 Message Log Report Cmpnt CLOGREP.COB 1 PC 00 000200************************************************************* 000300* * 000400* Classification = BluePhoenix Solutions * 000500* (c) Copyright 2002 * 000600* *
10-4
Sample Components
000800* $$NAME NAME=CLOGREP * 000900* * 001000* $$VERSION ID=3.3.6 * 001100* * 001200* $$CALL TYPE=PROGRM NAME=&&&&&&&& ID=3.1.0* 001300* * 001400* Programmer = P. Cobley * 001500* * 001600* Date = OCT 21st 2002 * 001700* * 001800* Brief 001900* Description = Message Log database report prog.* 002000* * 002100* Detailed Description = CLOGREP writes the Message Log * 002200* database to a GSAM report file. * 002200* This component uses symbolic * 002200* check points to enable the IMS * 002500* Restart facility. * 002600* Inputs = None * 002700* * 002800* Outputs = None * 003000* * 003100* External Routines = AIBTDLI IMS routine * 003200* * 003300* COBOL Copy Used = HPIAIBI IMS Appl. Interface Block* 003400* = HPSUCOM Communications Area * 003400* = HPIEL00 Message db I/O Area * 003400* = HPIEL00H Msg db I/O Area Header * 003400* = HPIDPCB database PCB * 003400* = HPIOPCB I/O PCB * 003500* * 003600* EXEC SQL INCLUDE'S = NONE * 003700* * 003800* Modification History = * 003900* * 004000* SEQ RVML PI YYMMDD --- Description ----------------------* 004100* 000 3600 PC 921021 Created program. * 004300************************************************************* 005900 IDENTIFICATION DIVISION. 006000 PROGRAM-ID. CLOGREP. 006100 AUTHOR. P. COBLEY. 006200 INSTALLATION BluePhoenix Solutions 006300 AppBuilder IMS RUN TIME ENVIRONMENT. 006400*REMARKS. THIS PROGRAM READS THE MESSAGE LOG DATABASE AND 006500 PRODUCES A REPORT. 006600 ENVIRONMENT DIVISION. 006700 CONFIGURATION SECTION. 006800 SOURCE-COMPUTER. IBM-370. 006900 OBJECT-COMPUTER. IBM-370. 007000 DATA DIVISION. 007100 WORKING-STORAGE SECTION. 024800* IMS Call Functions 01 GU PIC X(4) VALUE 'GU '. 01 ISRT PIC X(4) VALUE 'ISRT'.
10-5
Sample Components
01 CHKP PIC X(4) VALUE 'CHKP'. 01 XRST PIC X(4) VALUE 'XRST'. 01 DLIOPEN PIC X(4) VALUE 'OPEN'. 024800* Message Log database I/O areas 024901 01 HPIEL00. 024902 COPY HPIEL00. 024903 01 ERRHEAD. 024904 COPY ERRHEAD. 024800* IMS Application Interface Blocks 024905 01 ERR-BLOCK. 024906 COPY HPIAIBI. 024907 01 REP-BLOCK. 024908 COPY HPIAIBI. 024907 01 IO-BLOCK. 024908 COPY HPIAIBI. 025500* Message Log database Segment Search Argument 025700 01 SSA1. 025800 03 FIELD PIC X(19) VALUE 025900 'HPIER00 (ERLGKEY ='. 026000 03 ERR-FILE-KEY PIC S9(9) COMP. 026100 03 RP PIC X(1) VALUE ')'. 025500* Symbolic Checkpoint Identification area 01 RESTART-WORKAREA. 03 RESTART-CHKPT PIC X(8) VALUE SPACES. 03 RES-CHKP REDEFINES RESTART-CHKPT. * Program Name 'RLOG' 05 PGM-NAME PIC X(4). * Checkpoint Counter 05 COUNTER PIC 9(4). * Database Key I/O area used to reposition after Restart 01 DB-KEY PIC S9(9) COMP VALUE 0. * Checkpoint/Restart call maximum I/O area length 01 IOAREA-LEN PIC S9(5) COMP VALUE +10000. * Length of database key used to save position 01 KEY-LEN PIC S9(5) COMP VALUE +4. * Checkpoint Frequency 01 CHECKPOINT-FREQ PIC S9(5) VALUE 10. 01 CHECKPOINT-COUNT PIC S9(4) COMP-3 VALUE 0. 01 DB-COUNT PIC S9(4) COMP-3 VALUE 0. 026200* 026300 LINKAGE SECTION. 026402* COMMUNICATION AREAS FOR PROGRAM LINKAGE 026404 01 DUMMY-A PIC X. 026402* AppBuilder Communication Area 026405 01 DFHCOMMAREA. 026406 COPY HPSUCOM. 026402* IMS Program Control Block masks 027400 01 ERR-MASK. 027500 COPY HPIDPCB. 027510 01 REP-MASK. 027520 COPY HPIDPCB. 027510 01 IO-MASK. 027520 COPY HPIOPCB. 027520 COPY VIMSPIO.
10-6
Sample Components
027700 EJECT 027800 PROCEDURE DIVISION USING DUMMY-A, DFHCOMMAREA. 028200 MAINLINE SECTION. 028300 ML-000. 028600* Initialize the IMS Application Interface Blocks SET ADDRESS OF VIMSPIO TO IV-PTR. 028700 INITIALIZE ERR-BLOCK. 028800 MOVE 'DFSAIB ' TO AIBID OF ERR-BLOCK. 028900 MOVE LENGTH OF ERR-BLOCK TO AIBLEN OF ERR-BLOCK. 029000 MOVE 'HPI006D1' TO AIBRSNM1 OF ERR-BLOCK. 029100 MOVE LENGTH OF HPIEL00 TO AIBOALEN OF ERR-BLOCK. 029200 INITIALIZE REP-BLOCK. 029300 MOVE 'DFSAIB ' TO AIBID OF REP-BLOCK. 029400 MOVE LENGTH OF REP-BLOCK TO AIBLEN OF REP-BLOCK. 029500 MOVE 'REPLOG ' TO AIBRSNM1 OF REP-BLOCK. 029600 MOVE LENGTH OF HPIEL00 TO AIBOALEN OF REP-BLOCK. 029200 INITIALIZE IO-BLOCK. 029300 MOVE 'DFSAIB ' TO AIBID OF IO-BLOCK. 029400 MOVE LENGTH OF IO-BLOCK TO AIBLEN OF IO-BLOCK. 029500 MOVE 'IOPCB ' TO AIBRSNM1 OF IO-BLOCK. 029600 MOVE 4089 TO AIBOALEN OF IO-BLOCK. 029600 MOVE SPACES TO RESTART-WORKAREA. 028600* Issue an Extended Restart call. When the DB-KEY returned 028600* is greater than 0 a Checkpoint Restart is in process. CALL 'AIBTDLI' USING XRST, IO-BLOCK, IOAREA-LEN, RESTART-WORKAREA, KEY-LEN, DB-KEY. 036010 SET ADDRESS OF IO-MASK TO AIBRSA1 OF IO-BLOCK. 036100 IF HPS-IO-STATUS-CODE OF IO-MASK NOT EQUAL ' ' THEN 036200 DISPLAY 'INVALID IMS RETURN CODE FROM XRST CALL' 036200 DISPLAY 'STATUS CODE = ', HPS-IO-STATUS-CODE 036300 GOBACK END-IF. 035600 MOVE 1 TO ERR-FILE-KEY OF SSA1. 035700 CALL 'AIBTDLI' USING GU, ERR-BLOCK, ERRHEAD, SSA1. 036010 SET ADDRESS OF ERR-MASK TO AIBRSA1 OF ERR-BLOCK. 036100 IF HPS-DB-STATUS-CODE OF ERR-MASK NOT EQUAL ' ' THEN 036200 DISPLAY 'INVALID IMS RETURN CODE FROM ERRLOG' 036200 DISPLAY 'STATUS CODE = ', HPS-DB-STATUS-CODE OF ERR-MASK 036300 GOBACK END-IF. 028600* When normal start, setup the SSA to read the first message IF DB-KEY = 0 THEN 063500 MOVE RECDNUM TO ERR-FILE-KEY OF SSA1 028600* When Restart in progress use the DB-KEY return from XRST 028600* call as the key for the SSA. This positions this program 028600* to the correct part of the Message Log DB to enable the 028600* processing to continue from where terminated in previous 028600* run. ELSE ADD 1 TO DB-KEY MOVE DB-KEY TO ERR-FILE-KEY OF SSA1 END-IF. 028600* Read the first/latest message on the Message Log database
10-7
Sample Components
063700 CALL 'AIBTDLI' USING GU, ERR-BLOCK, HPIEL00, SSA1. 028600* Initialize the first 4 bytes of the Checkpoint Identity to 028600* the program name. This allows easier identification when 028600* scanning the IMS LOG and Job output if an abend occurs. MOVE 0 TO CHECKPOINT-COUNT. 028600* Open the GSAM file 064460 CALL 'AIBTDLI' USING DLIOPEN, REP-BLOCK 064470 SET ADDRESS OF REP-MASK TO AIBRSA1 OF REP-BLOCK 064480 IF HPS-DB-STATUS-CODE OF REP-MASK NOT = ' ' THEN 064490 DISPLAY 'INVALID IMS RETURN CODE FOR REPORT' 036200 DISPLAY 'STATUS CODE = ', HPS-DB-STATUS-CODE OF REP-MASK 064500 GOBACK 064600 END-IF 064200* Reduce the Message Log DB key by 1 to read the next message SUBTRACT 1 FROM ERR-FILE-KEY OF SSA1. 064200* Process through all Message Log database records MOVE 'RLOG' TO PGM-NAME OF RESTART-WORKAREA. 064400 PERFORM WITH TEST BEFORE UNTIL ERR-FILE-KEY OF SSA1 = 064410 RECDNUM 064420 IF HPS-DB-STATUS-CODE OF ERR-MASK NOT = SPACES 064430 DISPLAY 'INVALID IMS RETURN CODE FOR ERRLOG' 036200 DISPLAY 'STATUS CODE = ', HPS-DB-STATUS-CODE OF ERR-MASK 064440 GOBACK 064450 END-IF 064200* Add the message to the GSAM file 064460 CALL 'AIBTDLI' USING ISRT, REP-BLOCK, HPIEL00 064480 IF HPS-DB-STATUS-CODE OF REP-MASK NOT = ' ' THEN 064490 DISPLAY 'INVALID IMS RETURN CODE FOR REPORT' 036200 DISPLAY 'STATUS CODE = ', HPS-DB-STATUS-CODE OF REP-MASK 064500 GOBACK 064600 END-IF 064200* Increment the Checkpoint Counter & check its value against 064200* the Checkpoint Frequency ADD 1 TO CHECKPOINT-COUNT 064200* Perform a Symbolic Checkpoint when the frequency is reached 064200* Save the DB key area & initialize the Checkpoint Counter IF CHECKPOINT-COUNT = CHECKPOINT-FREQ THEN ADD 1 TO DB-COUNT MOVE DB-COUNT TO COUNTER OF RESTART-WORKAREA MOVE 0 TO CHECKPOINT-COUNT MOVE ERR-FILE-KEY OF SSA1 TO DB-KEY CALL 'AIBTDLI' USING CHKP, IO-BLOCK, IOAREA-LEN, RESTART-WORKAREA, KEY-LEN, DB-KEY 064480 IF HPS-IO-STATUS-CODE OF IO-MASK NOT = ' ' AND 064480 HPS-IO-STATUS-CODE OF IO-MASK NOT = 'QC' 064490 DISPLAY 'INVALID IMS RETURN CODE FOR CHKP' 036200 DISPLAY 'STATUS CODE = ', HPS-IO-STATUS-CODE OF IO-MASK 064500 GOBACK END-IF
10-8
Sample Components
MOVE 'RLOG' TO PGM-NAME OF RESTART-WORKAREA END-IF * Reset the Database key to the next available message when 1 070000 IF ERR-FILE-KEY OF SSA1 = 1 THEN 070100 MOVE RECTOTAL TO ERR-FILE-KEY OF SSA1 070200 END-IF 070300 CALL 'AIBTDLI' USING GU, ERR-BLOCK, HPIEL00, SSA1 069900 SUBTRACT 1 FROM ERR-FILE-KEY OF SSA1 071800 END-PERFORM. 071900 GOBACK.
PL/I (Using IMS non-AIB)

/*$.0 030393 AppBuilder/IMS Phone Directory Comp CPHONEI.COB 1 PC00*/ /*****************************************************************/ /* */ /* Classification = BluePhoenix Solutions */ /* (c) Copyright 2002 */ /* */ /* $$NAME NAME=CPHONEI */ /* */ /* $$VERSION ID=3.3.6 */ /* */ /* $$CALL TYPE=PROGRM NAME=&&&&&&&& ID=3.1.0 */ /* */ /* Programmer = P. Cobley */ /* */ /* Date = OCT 21st 2002 */ /* */ /* Brief */ /* Description = Access the Phone Directory database */ /* */ /* Detailed Description = The Program uses the Input views */ /* fields to access the database and */ /* return the phone details. */ /* */ /* Inputs = None */ /* */ /* Outputs = None */ /* */ /* External Routines = PLITDLI IMS routine */ /* */ /* COBOL Copy Used = HPSUCOM Communications Area */ /* = HPIDPCB database PCB */ /* = HPIOPCB I/O PCB */ /* */ /* EXEC SQL INCLUDE'S = NONE */ /* */ /* Modification History = */ /* */ /* 000 3600 PC 921021 Created program. */ /* */
10-9
Sample Components
/*****************************************************************/ CPHONEI:PROC(DUMMY,DFHCOMMAREA) OPTIONS(COBOL); DCL PLIXOPT CHAR(20) VAR INIT('R,NOSTAE,NOSPIE') STATIC EXTERNAL; DCL DUMMY CHAR(1); DCL 1 DFHCOMMAREA, %INCLUDE HPSUCOM; DCL CHAR_STR CHAR(600) BASED(ADDR(DFHCOMMAREA)); DCL ADDR BUILTIN; -DCL 1 PHONE_BLOCK, %INCLUDE HPIAIBI; -DCL STG BUILTIN; -DCL 1 DBAREA, 2 DBAREA_FIRSTN CHAR(15), 2 DBAREA_LASTN CHAR(15), 2 DBAREA_DEPT CHAR(20), 2 DBAREA_PHONE CHAR(21), 2 DBAREA_ALTPHONE CHAR(21), 2 DBAREA_PAGE CHAR(21), 2 DBAREA_FILL CHAR(20); -DCL 1 SSA, 2 SSA_SEGNAME CHAR(8) INIT('PHONEDIR'), 2 SSA_LPAR CHAR(1) INIT('('), 2 SSA_FLDNAME CHAR(8) INIT('LAST'), 2 SSA_OPER CHAR(2) INIT(' ='), 2 SSA_VALUE CHAR(15), 2 SSA_RPAR CHAR(1) INIT(')'); -DCL 1 VIMSPII BASED(IV_PTR), 2 LAST_NAME CHAR(15), 2 IMS_PCB_LIST_ADDR FIXED BIN(31); -DCL PCB_ADDRESS POINTER BASED(ADDR(IMS_PCB_LIST_ADDR)); -DCL 1 VIMSPIO BASED(OV_PTR), 2 FIRST_NAME CHAR(15), 2 LAST_NAME CHAR(15), 2 DEPT_NAME CHAR(20), 2 PHONE_NUMBER CHAR(21), 2 ALTPHONE_NUMBER CHAR(21), 2 PAGE_NUMBER CHAR(21); DCL 1 PCB_PTRS BASED(PCB_ADDRESS), 3 IO_PCB PTR, 3 ALT_PCB PTR, 3 ALT_EXP_PCB PTR, 3 HPI001D1_PCB PTR, 3 PHONE_PCB PTR; -DCL 1 PHONE_PCB_MASK BASED(PHONE_PCB), %INCLUDE HPIDBPCB;; -DCL PLITDLI ENTRY EXTERNAL; -DCL K4 FIXED BIN(31) INIT(4); -DCL GU CHAR(4) INIT('GU '); SSA.SSA_VALUE = VIMSPII.LAST_NAME; CALL PLITDLI(K4,GU,PHONE_PCB_MASK,SSA) VIMSPIO.FIRST_NAME = DBAREA_FIRSTN; VIMSPIO.LAST_NAME = DBAREA_LASTN; VIMSPIO.DEPT_NAME = DBAREA_DEPT; VIMSPIO.PHONE_NUMBER = DBAREA_PHONE;
10-10
VIMSPIO.ALTPHONE_NUMBER = VIMSPIO.PAGE_NUMBER = END CPHONEI;
DBAREA_ALTPHONE; DBAREA_PAGE;

This section describes the AppBuilder Communications Area for host PL/I, COBOL II, assembler, and C components. The COMMAREA for each type of component is kept in a copybook called HPSCOMM. The communications area is the same for CICS, IMS, and batch components. To see the component code, refer to Component Communications Area (HPSCOMM) on page 13-4.
10-11
10-12
CHAPTER
11
USING IMS INTERFACES: HPECAPI AND HPUCV10
In development using the IMS interface, you may need to access an AppBuilder rule through a nonAppBuilder application, for example, if you write a front-end program to test AppBuilder rules or use an established front end to access an AppBuilder rule. To allow this, AppBuilder provides two standard application program interfaces (APIs) within the IMS environment. These interfaces, HPECAPI and HPUCV10, work analogously to the CICS version of HPECAPI. In an IMS run-time environment, an application program can perform as TP Conversational (using a Scratch Pad Area), TP MPP Non-Conversational, BMP, or Batch DL/I. AppBuilder enables all of these IMS features, and both AppBuilder and user applications can communicate with each other in all of these modes.
Using IMS Interface Functions

The functions listed in this section allow complete communications from: Client to AppBuilder AppBuilder to AppBuilder AppBuilder to user applications They include: LINK Functions Function Code Samples
LINK Functions
These functions allow a user application to link directly to a non-3270 Converse AppBuilder rule. START and continue processing Starts an AppBuilder rule with the ability to perform independently of the current application. This function, which is the same as the USE-RULE-INIT function in the AppBuilder Rules Language, enables the automatic start of an AppBuilder rule in either MPP or batch processing modes.
11-1
START IMS immediate conversational transfer Transfers from a user application to an AppBuilder frontier rule in conversational mode. (This function should only be performed on an AppBuilder 3270 converse application.) START with return IMS immediate conversational transfer Transfers from a user application to an AppBuilder frontier rule in conversational mode, and returns to the user application at the end of the frontier rule processing. (This function can be performed on any AppBuilder IMS application.) AppBuilder 3270 application to AppBuilder 3270 application IMS immediate conversational transfer Allows a user to transfer from one AppBuilder application to another directly, including passing frontier rule input views. (This is an AppBuilder 3270 Converse option.) AppBuilder 3270 application to user application IMS immediate conversational transfer Transfers from an AppBuilder 3270 Converse application to a user application.
Function Code Samples

The following COBOL II code samples show how to perform each function. Each can also be performed using PL/I, C, and 370 assembler. The communication area (COMMAREA) settings for each function are explained, followed by the COBOL II programs that issue each function. User Application to Rule LINK User Application to Rule START and Continue Processing User Application to Rule Transfer Control User Application to Rule Transfer Control with Return User Application Performing All Functions User Application to Rule Transfer Control (no input view) Immediate Transfer of Control The AppBuilder Communications Area (COMMAREA) is needed to perform all of the functions listed in the previous section. All languages supply the HCUUCOM communication area as part of the standard AppBuilder release. * .$.0 050494 User AppBuilder Commarea HCUUCOM.CPY 0 DC 03 **_*_* * HPSCPYR (c) Copyright 2002, BluePhoenix Solutions * * $$NAME NAME=HCUUCOM * * $$VERSION ID=3.7.0 * * Detailed Description = This is the standard commarea for a user * application program to initiate a * AppBuilder Rule. **_*_* 05 HPICAPI PIC X(8) VALUE 'HPICAPI '. 05 FILLER REDEFINES HPS-COMMAREA.
11-2
Using IMS Interfaces: HPECAPI and HPUCV10
10 10 10
10
10 05 05
RULE-NAME PIC X(8). FILLER PIC X(16). INPUT-VIEW. 15 IV-NAME PIC X(8). 15 FILLER PIC X(4). 15 IV-PTR POINTER. 15 IV-ADDRESS REDEFINES IV-PTR PIC S9(8) COMP. OUTPUT-VIEW. 15 OV-NAME PIC X(8). 15 FILLER PIC X(4). 15 OV-PTR POINTER. 15 OV-ADDRESS REDEFINES OV-PTR PIC S9(8) COMP. 15 OV-OFFSET REDEFINES OV-PTR PIC S9(8) COMP. FILLER PIC X(72). HPS-EXTENDED-COMMAREA PIC X(384). FILLER REDEFINES HPS-EXTENDED-COMMAREA. 10 HPS-FLENGTH. 15 IV-FLENGTH PIC S9(8) COMP. 15 OV-FLENGTH PIC S9(8) COMP. 15 FILLER PIC X(24). 10 FILLER PIC X(192). 10 HPS-USER-PARM-AREA. 15 HPS-USER-PARM-EYECATCHER. 20 FILLER PIC X(6). 20 HPS-USER-PARM-EYE-IDENTIFIER PIC X(10). 15 FILLER PIC X(16). 15 HPS-USER-PARM-PARAMETERS. 20 HPS-USER-PARM-FUNC PIC S9(4) COMP. 88 HPS-USER-PARM-FUNC-LINK VALUE 88 HPS-USER-PARM-FUNC-START-RET VALUE +5. 88 HPS-USER-PARM-FUNC-START VALUE +6. 88 HPS-USER-PARM-FUNC-XCTL VALUE +7. 88 HPS-USER-PARM-FUNC-COBDYN VALUE +8. 20 HPS-USER-PARM-SUBFUNC PIC S9(4) COMP. 88 HPS-USER-PARM-SUBFUNC-NORMAL VALUE +0. 88 HPS-USER-PARM-SUBFUNC-DEFVIEW VALUE +4. 88 HPS-USER-PARM-SUBFUNC-FASTP VALUE +5. 20 HPS-USER-PARM-RET-CODE PIC S9(4) COMP. 88 HPS-USER-PARM-RET-CODE-NORM VALUE +0. 88 HPS-USER-PARM-RET-CODE-ERR VALUE +4. 20 FILLER PIC X(10). 20 HPS-USER-PARM-USE-TERM PIC X(8). 20 HPS-USER-PARM-USE-TRAN PIC X(8). 20 HPS-USER-PARM-RET-TERM PIC X(8). 20 HPS-USER-PARM-RET-TRAN PIC X(8). 20 HPS-USER-PARM-ERR-MSG PIC X(8). 20 HPS-USER-PARM-SPA-PTR POINTER. 20 HPS-USER-PARM-SPA-ADDRESS REDEFINES HPS-USER-PARM-SPA-PTR PIC S9(8) COMP. 20 FILLER PIC X(4). 10 FILLER PIC X(64).
11-3
User Application to Rule LINK

In this example, the rule that is being linked to has an input/output view system ID name of PHIL01IO and is 80 bytes in length. * Set the Commarea Function code SET HPS-USER-PARM-FUNC-LINK TO TRUE * Set the Rule name, View names, and total character length of * each view. If the rule does not contain a view, then set that * view AppBuilder runtime, and will be rejected if invalid. MOVE 'PHIL01 ' TO RULE-NAME OF COMMAREA MOVE 'PHIL01IO' TO IV-NAME OF COMMAREA MOVE 'PHIL01IO' TO OV-NAME OF COMMAREA MOVE 80 TO IV-FLENGTH OF COMMAREA MOVE 80 TO OV-FLENGTH OF COMMAREA * Use the supplied object HPSADDR to address WORKING-STORAGE * declarations. CALL 'HPSADDR' USING IV-PTR OF COMMAREA, VIEW-AREA CALL 'HPSADDR' USING OV-PTR OF COMMAREA, VIEW-AREA MOVE 'CALLING THE PHIL01 RULE LINK' TO VIEW-AREA * Pass the address of register 1 (IMS PCB list) if the * conventional IMS DL/I interface is to be used in a lower level * component.HPIPPTR is supplied as part of the AppBuilder IMS release. CALL 'HPIPPTR' USING REG-ONE-PTR. * Call the AppBuilder Application Program Interface CALL HPECAPI USING REG-ONE-PTR, COMMAREA. IF HPS-USER-PARM-RET-CODE NOT = 0 MOVE HPS-USER-PARM-ERR-MSG TO RESPONS OF OUT-AREA ELSE MOVE VIEW-AREA TO RESPONS OF OUT-AREA END-IF
User Application to Rule START and Continue Processing

MOVE 'STARTUSE RULE INIT FUNCTION PERFORMED' TO RESPONS OF OUT-AREA SET HPS-USER-PARM-FUNC-START TO TRUE MOVE 'PHIL01 ' TO RULE-NAME OF COMMAREA MOVE 'PHIL01IO' TO IV-NAME OF COMMAREA MOVE 'PHIL01IO' TO OV-NAME OF COMMAREA MOVE 80 TO IV-FLENGTH OF COMMAREA MOVE 80 TO OV-FLENGTH OF COMMAREA * Use the supplied object HPSADDR to address WORKING-STORAGE * declarations. CALL 'HPSADDR' USING IV-PTR OF COMMAREA, VIEW-AREA CALL 'HPSADDR' USING OV-PTR OF COMMAREA, VIEW-AREA MOVE 'STARTING PHIL01 RULE' TO VIEW-AREA * * Pass the address of register 1 (IMS PCB list) if the * conventional IMS DL/I interface is to be used in * lower level * component. HPIPPTR is supplied as part of the AppBuilder IMS * release. CALL 'HPIPPTR' USING REG-ONE-PTR.
11-4
* Call the AppBuilder Application Program Interface CALL HPECAPI USING REG-ONE-PTR, COMMAREA. IF HPS-USER-PARM-RET-CODE NOT = 0 MOVE HPS-USER-PARM-ERR-MSG TO RESPONS OF OUT-AREA ELSE MOVE VIEW-AREA TO RESPONS OF OUT-AREA END-IF
User Application to Rule Transfer Control

This example shows an IMS immediate conversational transfer to an AppBuilder 3270 Converse application. For a non-conversational transfer, do not set the SPA address in the communications area. Note
The logical terminal ID is set. This tells AppBuilder runtime to transfer control and to return the conversation to that terminal. If the HPS-USER-PARM-USE-TRAN name is left blank, AppBuilder runtime will find the rules transaction code automatically. Note that the address of the SPA is also passed to the communications area.
015900 014600 014710 014720 14800 14800
015500 015920
* * * * *
* 013931 013932 013979 013935
SET HPS-USER-PARM-FUNC-START TO TRUE MOVE 'AAC8LI' TO RULE-NAME OF COMMAREA MOVE 'ZAADHLI'TO IV-NAME OF COMMAREA MOVE ' ' TO OV-NAME OF COMMAREA MOVE 50 TO IV-FLENGTH OF COMMAREA MOVE 0 TO OV-FLENGTH OF COMMAREA CALL 'HPSADDR' USING IV-PTR OF COMMAREA, VIEW-AREA MOVE 0 TO OV-ADDRESS OF COMMAREA MOVE 'HPT0' TO HPS-USER-PARM-USE -TRAN MOVE HPS-LTERM-NAME OF IO-PCB TO HPS-USER-PARM-USE-TERM CALL 'HPSADDR' USING HPS-USERPARM-SPA-PTR, SPA. MOVE 'CALLING AAC8LI RULE START' TO VIEW-AREA Pass the address of register 1 (IMS PCB list) if the conventional IMS DL/I interface is to be used in a lower level component. HPIPPTR is supplied as part of the AppBuilder IMS release. CALL 'HPIPPTR' USING REG-ONE-PTR. Call the AppBuilder Application Program Interface CALL HPECAPI USING REG-ONE-PTR, COMMAREA. IF HPS-USER-PARM-RET-CODE NOT = 0 MOVE HPS-USER-PARM-ERR-MSG TO RESPONS OF OUT-AREA ELSE MOVE '1' TO TRANSFER END-IF
11-5
User Application to Rule Transfer Control with Return

Note
In order for AppBuilder runtime to return the conversation at completion of the AppBuilder frontier rule, the return transaction HPS-USER-PARM-RET-TRAN and return terminal ID HPS-USER-PARM-RET-TERM must be set.
015900 014600 014710 014720 14800 14800 015500 015920 015920
* * * * * * 013931 013932 013979 013935
SET HPS-USER-PARM-FUNC-START TO TRUE MOVE 'AAC8LI' TO RULE-NAME OF COMMAREA MOVE 'ZAADHLI' TO IV-NAME OF COMMAREA MOVE ' ' TO OV-NAME OF COMMAREA MOVE 50 TO IV-FLENGTH OF COMMAREA MOVE 0 TO OV-FLENGTH OF COMMAREA CALL 'HPSADDR' USING IV-PTR OF COMMAREA, VIEW-AREA MOVE 0 TO OV-ADDRESS OF COMMAREA MOVE 'HPT0' TO HPS-USER-PARM-USE-TRAN MOVE 'MYTRAN' TO HPS-USER-PARM-RET-TRAN MOVE HPS-LTERM-NAME OF IO-PCB TO HPS-USER-PARM-USE-TERM MOVE HPS-LTERM-NAME OF IO-PCB TO CALL 'HPSADDR' USING HPS-USER-PARM-SPA-PTR, SPA. HPS-USER-PARM-RET-TERM MOVE 'CALLING AAC8LI RULE START' TO VIEW-AREA Pass the address of register 1 (IMS PCB list) if the conventional IMS DL/I interface is to be used in a lower level component. HPIPPTR is supplied as part of the AppBuilder IMS release. CALL 'HPIPPTR' USING REG-ONE-PTR. Call the AppBuilder Application Program Interface CALL HPECAPI USING REG-ONE-PTR, COMMAREA. IF HPS-USER-PARM-RET-CODE NOT = 0 MOVE HPS-USER-PARM-ERR-MSG TO RESPONS OF OUT-AREA ELSE MOVE '1' TO TRANSFER END-IF
User Application Performing All Functions

This program performs as IMS conversational. 000100* .$.0 091994 AppBuilder/IMS HPECAPI Test Program HPI * AEMP.COB 0 PHC 05 000200************************************************ 000300* 000400* Classification = BluePhoenix Solutions 000500* (c) Copyright 2002 000600* 000700* $$NAME NAME=HPIAEMP 000800* 000900* $$VERSION ID=5.3.1 001000*
11-6
001100* $$CALL TYPE=PROGRM * NAME=&&&&&&&& ID=3.6.0 001200* 001300* Programmer = Philip Cobley 001400* 001500* Date = March 22, 2002 001600* 001700* Brief Module = HPECAPI test program 001800* Description 001900* 002000* Detailed Description = This Program will * test the USE RULE INIT 002100* function (Start no return) and the 002200* conversational transfer to AppBuilder Rules 002300* 002400* Inputs = HPIAEM Transaction from screen 002500* 002600* Outputs = MFS Format and transactions to AppBuilder 002700* 002800* External Routines = HPECAPI * HPSADDR * HPIPPTR 002900* 003000* COBOL Copy Statements = HPIAIBI-IMS * Application Interface Block 003100* HCUUCOM - AppBuilder User Commarea 003200* HPIOPCB - IMS I/O PCB Mask 003500* 003600* EXEC SQL INCLUDE's = None 003700* 003800* Modification History = 003900* 004200************************************************ 004300 IDENTIFICATION DIVISION. 004400 PROGRAM-ID. HPIAEMP. 004500 AUTHOR. P. COBLEY. 004600 INSTALLATION BluePhoenix Solutions 004700 AppBuilder IMS RUN TIME ENVIRONMENT. 004800* REMARKS. THIS PROGRAM Calls the HPECAPI API * interface. 004900 ENVIRONMENT DIVISION. 005000 CONFIGURATION SECTION. 005100 SOURCE-COMPUTER. IBM-370. 005200 OBJECT-COMPUTER. IBM-370. 005300 DATA DIVISION. 005400 WORKING-STORAGE SECTION. 005500 77 HPECAPI PIC X(8) VALUE 'HPECAPI '. 005600 77 MOD-NAME PIC X(8) VALUE 'HPIAEMO '. 005700 77 GU PIC X(4) VALUE 'GU '. 005800 77 GN PIC X(4) VALUE 'GN '. 005900 77 ISRT PIC X(4) VALUE 'ISRT'. 005900 77 CHNG PIC X(4) VALUE 'CHNG'. 006300* 006400* This area contains the outgoing message (MOD).
11-7
006500* 006600 01 IN-AREA. 006700 03 LL PIC 9(4) COMP. 006800 03 ZZ PIC 9(4) COMP. 007200 03 TXN PIC X(8). 007210 03 PFKEY PIC X(8). 03 FILLER1 PIC X(1904). 007300* 007400* This area contains the incoming message (MID). 007500* 007600 01 OUT-AREA. 007700 03 LL PIC 9(4) COMP. 007800 03 ZZ PIC 9(4) COMP. 008600 03 RESPONS PIC X(79). 008700* 008800* IMS Variables 008900* 009000 01 IO-BLOCK. 009100 COPY HPIAIBI. 009000 01 ALT-BLOCK. 009100 COPY HPIAIBI. 009200* 009300* AppBuilder Communication areas for program linkage 009400* 009500 01 COMMAREA. 009600 COPY HCUUCOM. 009700* 009800* This area contains the SPA for an IMS transaction. 009900* 010000 01 SPA. 010100 03 HPS-SPA-LENGTH PIC 9(4) COMP. 010200 03 HPS-SPA-RESERVE-AREA PIC 9(9) COMP. 010300 03 HPS-SPA-TRANCODE PIC X(8). 010400 03 THE-REST PIC X(130). 010500* 010600* Internal Variables 010700* 010800 01 TRANSFER PIC X. 010900 01 REG-ONE-PTR POINTER. 01 NEW-TRAN PIC X(8). 010500* 010600* Rule Views 010700* 01 VIEW-AREA PIC X(80). 011500 LINKAGE SECTION. 011600* 011700* This area contains I/O PCB mask. 011800* 011900 01 IO-PCB. 012000 COPY HPIOPCB. 011900 01 ALT-PCB. 012000 COPY HPIAPCB. 012100* 012200 EJECT
11-8
012300 PROCEDURE DIVISION. 012400 MAINLINE SECTION. 012500 ML-000. 012600* 012700* Initialize AIB Structure 012800* 012810 INITIALIZE IO-BLOCK. 012810 INITIALIZE ALT-BLOCK. 012820 INITIALIZE OUT-AREA. 012830 MOVE LENGTH OF OUT-AREA TO LL OF OUT-AREA. 012900 MOVE 'DFSAIB ' TO AIBID OF IO-BLOCK. 013000 MOVE LENGTH OF IO-BLOCK TO AIBLEN OF IO-BLOCK. 013100 MOVE 'IOPCB ' TO AIBRSNM1 OF IO-BLOCK. 013200 MOVE LENGTH OF IN-AREA TO AIBOALEN OF IO-BLOCK. 012900 MOVE 'DFSAIB ' TO AIBID OF ALT-BLOCK. 013000 MOVE LENGTH OF ALT-BLOCK TO AIBLEN OF ALT-BLOCK. 013100 MOVE 'ALTPCB ' TO AIBRSNM1 OF ALT-BLOCK. 013200 MOVE LENGTH OF SPA TO AIBOALEN OF ALT-BLOCK. 013400* 013500* Get first message & SPA. * 013600* 013700 CALL 'AIBTDLI' USING GU, IO-BLOCK, SPA. 013800 SET ADDRESS OF IO-PCB TO AIBRSA1 OF IO-BLOCK. 013900 CALL 'AIBTDLI' USING GN, IO-BLOCK, IN-AREA. 013901 IF HPS-IO-STATUS-CODE OF IO-PCB NOT = ' ' 013902 INITIALIZE IN-AREA 013903 END-IF. 013904 MOVE ' ' TO TRANSFER 014220 INITIALIZE COMMAREA. CALL 'HPSADDR' USING HPS-USER-PARM-SPA-PTR, SPA. 013910 EVALUATE PFKEY * Transfer to an AppBuilder 3270 converse application 013920 WHEN 'SNR' 015900 SET HPS-USER-PARM-FUNC-START TO TRUE 014600 MOVE 'AAC8LI ' TO RULE-NAME OF COMMAREA 014710 MOVE 'ZAADHLI ' TO IV-NAME OF COMMAREA 014720 MOVE ' ' TO OV-NAME OF COMMAREA 14800 MOVE 50 TO IV-FLENGTH OF COMMAREA 14800 MOVE 0 TO OV-FLENGTH OF COMMAREA CALL 'HPSADDR' USING IV-PTR OF COMMAREA, VIEW-AREA 015500 MOVE 0 TO OV-ADDRESS OF COMMAREA 015920 MOVE 'HPT0 ' TO HPS-USER-PARM-USE-TRAN MOVE HPS-LTERM-NAME OF IO-PCB TO HPS-USER-PARM-USE-TERM MOVE 'CALLING AAC8LI RULE START' TO VIEW-AREA 013930 PERFORM CAPI-INTERFACE 013931 IF HPS-USER-PARM-RET-CODE NOT = 0 013932 MOVE HPS-USER-PARM-ERR-MSG TO RESPONS OF OUT-AREA ELSE 013979 MOVE '1' TO TRANSFER 013935 END-IF * Transfer to an AppBuilder 3270 converse application and * return after completion. 013940 WHEN 'SR'
11-9
SET HPS-USER-PARM-FUNC-START-RET TO TRUE MOVE 'AAC8LI ' TO RULE-NAME OF COMMAREA MOVE 'ZAADHLI ' TO IV-NAME OF COMMAREA MOVE ' ' TO OV-NAME OF COMMAREA MOVE 50 TO IV-FLENGTH OF COMMAREA MOVE 0 TO OV-FLENGTH OF COMMAREA CALL 'HPSADDR' USING IV-PTR OF COMMAREA, VIEW-AREA 015500 MOVE 0 TO OV-ADDRESS OF COMMAREA 015920 MOVE 'HPT0 ' TO HPS-USER-PARM-USE-TRAN 015920 MOVE 'HPIAEM ' TO HPS-USER-PARM-RET-TRAN MOVE HPS-LTERM-NAME OF IO-PCB TO HPS-USER-PARM-USE-TERM MOVE HPS-LTERM-NAME OF IO-PCB TO HPS-USER-PARM-RET-TERM MOVE 'CALLING AAC8LI RULE START RETURN' TO VIEW-AREA 013950 PERFORM CAPI-INTERFACE 013951 IF HPS-USER-PARM-RET-CODE NOT = 0 013952 MOVE HPS-USER-PARM-ERR-MSG TO RESPONS OF OUT-AREA ELSE 013979 MOVE '1' TO TRANSFER 013955 END-IF * Start an AppBuilder rule. This could be an MPP or Batch DLI. 013940 WHEN 'URI' 021100 MOVE 'PHIL01 ' TO RULE-NAME OF COMMAREA 021200 MOVE 'PHIL01IO' TO IV-NAME OF COMMAREA 021300 MOVE 'PHIL01IO' TO OV-NAME OF COMMAREA 021400 MOVE 80 TO IV-FLENGTH OF COMMAREA 14800 MOVE 80 TO OV-FLENGTH OF COMMAREA CALL 'HPSADDR' USING IV-PTR OF COMMAREA, VIEW-AREA CALL 'HPSADDR' USING OV-PTR OF COMMAREA, VIEW-AREA MOVE 'CALLING THE PHIL01 RULE ' TO VIEW-AREA 021700 SET HPS-USER-PARM-FUNC-START TO TRUE 013950 PERFORM CAPI-INTERFACE 013951 IF HPS-USER-PARM-RET-CODE NOT = 0 013952 MOVE HPS-USER-PARM-ERR-MSG TO RESPONS OF OUT-AREA ELSE 013952 MOVE 'USE RULE INIT FUNCTION PERFORMED' TO RESPONS OF OUT-AREA 013955 END-IF * Link to an AppBuilder Rule. 013940 WHEN 'LINK' 015900 SET HPS-USER-PARM-FUNC-LINK TO TRUE 021100 MOVE 'PHIL01 ' TO RULE-NAME OF COMMAREA 021200 MOVE 'PHIL01IO' TO IV-NAME OF COMMAREA 021300 MOVE 'PHIL01IO' TO OV-NAME OF COMMAREA 021400 MOVE 80 TO IV-FLENGTH OF COMMAREA 14800 MOVE 80 TO OV-FLENGTH OF COMMAREA CALL 'HPSADDR' USING IV-PTR OF COMMAREA, VIEW-AREA CALL 'HPSADDR' USING OV-PTR OF COMMAREA, VIEW-AREA MOVE 'CALLING THE PHIL01 RULE LINK' TO VIEW-AREA 013950 PERFORM CAPI-INTERFACE 013951 IF HPS-USER-PARM-RET-CODE NOT = 0 013952 MOVE HPS-USER-PARM-ERR-MSG TO RESPONS OF OUT-AREA ELSE
015900 014600 014710 014720 14800 14800
11-10
013952 013955
MOVE VIEW-AREA TO RESPONS OF OUT-AREA END-IF * Transfer to AppBuilder Ruleview. 013960 WHEN 'HPR0' 015900 SET HPS-USER-PARM-FUNC-START TO TRUE 014600 MOVE 'HPRRV20 ' TO RULE-NAME OF COMMAREA 014710 MOVE ' ' TO IV-NAME OF COMMAREA 014720 MOVE ' ' TO OV-NAME OF COMMAREA 14800 MOVE 0 TO IV-FLENGTH OF COMMAREA 14800 MOVE 0 TO OV-FLENGTH OF COMMAREA 015300 MOVE 0 TO IV-ADDRESS OF COMMAREA 015500 MOVE 0 TO OV-ADDRESS OF COMMAREA 015920 MOVE 'HPR0 ' TO HPS-USER-PARM-USE-TRAN MOVE HPS-LTERM-NAME OF IO-PCB TO HPS-USER-PARM-USE-TERM 013930 PERFORM CAPI-INTERFACE 013931 IF HPS-USER-PARM-RET-CODE NOT = 0 013932 MOVE HPS-USER-PARM-ERR-MSG TO RESPONS OF OUT-AREA ELSE 013979 MOVE '1' TO TRANSFER 013935 END-IF * View AppBuilder IMS Security Log 013960 WHEN 'HPISEC1' MOVE 'HPISEC1' TO HPS-SPA-TRANCODE MOVE SPACES TO RESPONS MOVE 'HPISEC1' TO NEW-TRAN PERFORM CONV-TRANSFER 013974 MOVE '1' TO TRANSFER * View AppBuilder IMS Message log. 013960 WHEN 'HPISEC4' MOVE 'HPISEC4' TO HPS-SPA-TRANCODE MOVE SPACES TO RESPONS MOVE 'HPISEC4' TO NEW-TRAN PERFORM CONV-TRANSFER 013974 MOVE '1' TO TRANSFER 013978 WHEN 'EXIT' 013979 MOVE '1' TO TRANSFER 013980 MOVE SPACES TO HPS-SPA-TRANCODE 013981 CALL 'AIBTDLI' USING ISRT, IO-BLOCK, SPA 013992 END-EVALUATE. 013993 IF TRANSFER = ' ' 013994 CALL 'AIBTDLI' USING ISRT, IO-BLOCK, SPA 013996 CALL 'AIBTDLI' USING ISRT, IO-BLOCK, OUT-AREA, MOD-NAME 013997 END-IF. 013998 GOBACK. 014000* 014100* Setup the AppBuilder Communications area 014200* 014210 CAPI-INTERFACE SECTION. 016200* 016300* Pass the address of register 1 if conventional IMS I/F is used 016400* 016500 CALL 'HPIPPTR' USING REG-ONE-PTR. 016600*
11-11
016700* Call the AppBuilder Application Program Interface 016800* 016900 CALL HPECAPI USING REG-ONE-PTR, COMMAREA. 018900 EXIT. CONV-TRANSFER SECTION. CALL 'AIBTDLI' USING CHNG ALT-BLOCK NEW-TRAN CALL 'AIBTDLI' USING ISRT ALT-BLOCK SPA CALL 'AIBTDLI' USING ISRT ALT-BLOCK OUT-AREA EXIT.
User Application to Rule Transfer Control (no input view)

If a user application needs to transfer control to an AppBuilder 3270 Converse application that does not contain an input view, a standard IMS conversational transfer can be performed as described in this example. 010000 01 SPA. 010100 03 HPS-SPA-LENGTH PIC 9(4) COMP. 010200 03 HPS-SPA-RESERVE-AREA PIC 9(9) COMP. 010300 03 HPS-SPA-TRANCODE PIC X(8). 010400 03 THE-REST PIC X(130). 007600 01 OUT-AREA. 007700 03 LL PIC 9(4) COMP. 007800 03 ZZ PIC 9(4) COMP. 03 RULE-SEPERATOR PIC X(2) VALUE ', ', 008600 03 RULENAME PIC X(80). 01 NEW-TRAN PIC X(8) VALUE 'HPR0 * * * * *
'.
* * * * * * * *
The SPA and transaction setup can be done in one of two ways. 1 -Just set the AppBuilder Rule's transaction code to the SPA and AppBuilder Runtime will automatically find which rule to process. MOVE 'HPR0 ' TO HPS-SPA-TRANCODE CALL 'AIBTDLI' USING CHNG ALT-BLOCK NEW-TRAN CALL 'AIBTDLI' USING ISRT ALT-BLOCK SPA 2-Set the AppBuilder Rule's transaction code in the SPA and the Rule's Implementation name in the message. A comma must be placed before the rulename to notify AppBuilder Runtime that a rulename has been supplied. This function is to enable the process of a frontier rule using a different transaction code then that defined by the AppBuilder repository at rule preparation time. MOVE 'HPR0 ' TO HPS-SPA-TRANCODE MOVE 'HPRRV20' TO RULENAME OF OUT-AREA CALL 'AIBTDLI' USING ISRT ALT-BLOCK OUT-AREA CALL 'AIBTDLI' USING CHNG ALT-BLOCK NEW-TRAN CALL 'AIBTDLI' USING ISRT ALT-BLOCK SPA
11-12
Immediate Transfer of Control

For this function there is a need of a user exit program (HPUCV10). This exit program will be invoked by AppBuilder runtime as soon as a predefined transaction code field defined in the AppBuilder window has been entered. When a code is entered in the defined transaction switch field, the user exit program HPUCV10 is called and the AppBuilder run-time processing for that 3270 converse application ends. An example of this exit program is listed below. Note that the exit routine also calls HPECAPI in order to perform a transfer of control from one AppBuilder 3270 Converse application to another. Although the program is called HPIUSER, it is link-edited as load module HPUCV10. 000100*$.0 090294 AppBuilder/IMS HPUCV10 Test Program HPIUSER.COB 0 PHC 01 000200*************************************************************** 000300* 000400* Classification = BluePhoenix Solutions 000500* (c) Copyright 2002 000600* 000700* $$NAME NAME=HPIUSER 000800* 000900* $$VERSION ID=5.3.10 001000* 001100* $$CALL TYPE=PROGRM NAME=HPSADDR ID=5.3.10 001100* TYPE=PROGRM NAME=HPICAPI ID=5.3.10 001100* TYPE=PROGRM NAME=AIBTDLI ID=5.3.10 001200* 001300* Programmer = Philip Cobley 001400* 001500* Date = August 9, 2002 001600* 001700* Brief Module = AppBuilder 3270 converse, transaction switch 001800* Description test and sample program. 001900* 002000* Detailed Description = This Program will test the * transaction switch function, where a user enters a * transaction code and/or transaction data into an AppBuilder * window. AppBuilder runtime Links to HPUCV10 (The user load * program, this program). This program will process according * to the transaction code entered. * * 1) HPR0 - A standard IMS immediate * conversational transfer to AppBuilder RuleView* * * 2) HPISEC1/4ed - An Immediate * transfer to the AppBuilder * Message display programs. * * 3) HPT0 - An Immediate transfer to * AppBuilder HPT0 3270 converse * transaction with the * transaction data specifying * the Rule Name * * 4) Other - A call to HPICAPI with
11-13
* the TXN Code being the Rule * Name and the TXN Data being * the Input View. An Immediate * transfer will be. If an error * occurs this program will * use HPICAPI to transfer * conversation back to * the Us Rule and window to * display the error message. 002300* 002400* Inputs = Transaction Code & Data 002500* 002600* Outputs = None 002700* 002800* External Routines = HPECAPI 002900* 003000* COBOL Copy Statements = HPIAIBI - IMS Application Interface * Block 003100* HPSCOMM - AppBuilder User Commarea * for HPICAPI 003100* HCUUCOM - AppBuilder User Commarea * for HPECAPI 003200* HPIAPCB - IMS I/O PCB Mask 003500* 004200*************************************************************** 004300 IDENTIFICATION DIVISION. 004400 PROGRAM-ID.HPIUSER. 004500 AUTHOR. P. COBLEY. 004600 INSTALLATION BluePhoenix Solutions 004700 AppBuilder IMS RUN TIME ENVIRONMENT. 004800*REMARKS. THIS user program is invoked by the XFER function. 004900 ENVIRONMENT DIVISION. 005000 CONFIGURATION SECTION. 005100 SOURCE-COMPUTER. IBM-370. 005200 OBJECT-COMPUTER. IBM-370. 005300 DATA DIVISION. 005400 WORKING-STORAGE SECTION. 005500 77 VERSION-NAME PIC X(16) VALUE '==HPIUSER 5.3.01'. 005500 77 HPECAPI PIC X(8) VALUE 'HPECAPI '. 005500 77 HPICAPI PIC X(8) VALUE 'HPICAPI '. 005900 77 ISRT PIC X(4) VALUE 'ISRT'. 005900 77 CHNG PIC X(4) VALUE 'CHNG'. 007300* 007400* This area is used for the message output when HPT0 is entered 007500* 007600 01 OUT-AREA. 007700 03 LL PIC 9(4) COMP. 007800 03 ZZ PIC 9(4) COMP. 008600 03 DATA-AREA PIC X(80). 008700* 008800* IMS Application Interface Alternate PCB Block 008900* 009000 01 ALT-BLOCK. 009100 COPY HPIAIBI.
11-14
* 009300* AppBuilder Communication areas for old HPICAPI 009400* 009500 01 HPICOMM. 009600 COPY HPSCOMM. * 009300* AppBuilder Communication areas for new HPECAPI 009400* 009500 01 HPECOMM. 009600 COPY HCUUCOM. 009700* 009800* This area contains the SPA for a non AppBuilder IMS * transaction. 009900* 010000 01 NONHPS-SPA. 010100 03 LL PIC 9(4) COMP. 010200 03 ZZ PIC 9(9) COMP. 010300 03 SPA-TRANCODE PIC X(8). 010400 03 THE-REST PIC X(2086). 009700* 009800* This area contains the SPA for an AppBuilder IMS * transaction. 009900* 010000 01 NEWHPS-SPA. 010100 03 LL PIC 9(4) COMP. 010200 03 ZZ PIC 9(9) COMP. 010300 03 HPS-SPA-TRANCODE PIC X(8). 010400 03 THE-REST PIC X(130). 010500* 010600* PCB pointer. Not need when using AIB 010700* 010500* 010600* Used as the Input to the User program when an error occurs 010700* 01 MESSAGE-AREA. 03 IMS-CODE PIC X(2). 03 FILLER-1 PIC X(1). 03 MESSAGE-DATA PIC X(47). 01 AAC8LI-VIEW PIC X(50). 011500 LINKAGE SECTION. 010900 01 REG-ONE-PTR POINTER. 011600* 011700*Input from AppBuilder Runtime.SPA address,Txn Code and Txndata 011800* 01 INPUT-DATA. 03 TXN-LENGTH PIC 9(4) COMP. 03 TXN-CODE-LENGTH PIC 9(4) COMP. 03 SPA-PTR POINTER. 03 SPA-ADDR REDEFINES SPA-PTR PIC S9(8) COMP. 03 TXN-CODE PIC X(8). 03 TXN-DATA-LENGTH PIC 9(4) COMP. 03 TXN-DATA PIC X(32). 011600* 011700* This area contains I/O and Alternate PCB masks.
11-15
011800* 011900 01 IO-PCB. 012000 COPY HPIOPCB. 011900 01 ALT-PCB. 012000 COPY HPIAPCB. 009700* 009800* This area contains the AppBuilder runtime IMS SPA. 009900* 010000 01 HPS-SPA. 010100 03 LL PIC 9(4) COMP. 010200 03 ZZ PIC 9(9) COMP. 010300 03 HPS-SPA-TRANCODE PIC X(8). 010400 03 THE-REST PIC X(130). 012100* 012200 EJECT 012300 PROCEDURE DIVISION USING REG-ONE-PTR INPUT-DATA. 012400 MAINLINE SECTION. 012500 ML-000. 012600* 012700* Initialize AIB Structure 012800* DISPLAY 'HPIUSER HAS BEEN CALLED'. DISPLAY 'INPUT-DATA = ' , INPUT-DATA. SET ADDRESS OF HPS-SPA TO SPA-PTR OF INPUT-DATA DISPLAY 'THE SPA = ' , HPS-SPA. 012810 INITIALIZE ALT-BLOCK. 012820 INITIALIZE OUT-AREA. 012820 INITIALIZE NONHPS-SPA 012830 MOVE LENGTH OF OUT-AREA TO LL OF OUT-AREA. 012900 MOVE 'DFSAIB ' TO AIBID OF ALT-BLOCK. 013000 MOVE LENGTH OF ALT-BLOCK TO AIBLEN OF ALT-BLOCK. 013100 MOVE 'ALTPCB ' TO AIBRSNM1 OF ALT-BLOCK. 013200 MOVE LENGTH OF NONHPS-SPA TO AIBOALEN OF ALT-BLOCK. 013200 MOVE LENGTH OF NONHPS-SPA TO LL OF NONHPS-SPA. DISPLAY TXN-CODE. EVALUATE TXN-CODE 013960 WHEN 'HPR0' DISPLAY 'BEFORE IMS CHANGE CALL' CALL 'AIBTDLI' USING CHNG ALT-BLOCK TXN-CODE OF INPUTDATA DISPLAY 'AFTER IMS CHANGE CALL' DISPLAY 'ALT-BLOCK = ' , ALT-BLOCK DISPLAY 'RETURN CODE = ' , AIBRETRN OF ALT-BLOCK DISPLAY 'REASON CODE = ' , AIBREASN OF ALT-BLOCK 038000 SET ADDRESS OF ALT-PCB TO AIBRSA1 OF ALT-BLOCK IF HPS-IO-STATUS-CODE OF ALT-PCB NOT = SPACES 013960 PERFORM ERROR-SECTION ELSE PERFORM HPS-CONV-TRANSFER END-IF 013960 WHEN 'HPISEC1' DISPLAY 'BEFORE IMS CHANGE CALL' CALL 'AIBTDLI' USING CHNG ALT-BLOCK TXN-CODE OF INPUTDATA
11-16
038000 013960
013960
038000 013960
013960 013960
038000 013960
013992 013998
013960
DISPLAY 'AFTER IMS CHANGE CALL' DISPLAY 'ALT-BLOCK = ' , ALT-BLOCK DISPLAY 'RETURN CODE = ' , AIBRETRN OF ALT-BLOCK DISPLAY 'REASON CODE = ' , AIBREASN OF ALT-BLOCK SET ADDRESS OF ALT-PCB TO AIBRSA1 OF ALT-BLOCK IF HPS-IO-STATUS-CODE OF ALT-PCB NOT = SPACES PERFORM ERROR-SECTION ELSE PERFORM NONHPS-CONV-TRANSFER END-IF WHEN 'HPISEC4' DISPLAY 'BEFORE IMS CHANGE CALL' CALL 'AIBTDLI' USING CHNG ALT-BLOCK TXN-CODE OF INPUTDATA DISPLAY 'AFTER IMS CHANGE CALL' DISPLAY 'ALT-BLOCK = ' , ALT-BLOCK DISPLAY 'RETURN CODE = ' , AIBRETRN OF ALT-BLOCK DISPLAY 'REASON CODE = ' , AIBREASN OF ALT-BLOCK SET ADDRESS OF ALT-PCB TO AIBRSA1 OF ALT-BLOCK IF HPS-IO-STATUS-CODE OF ALT-PCB NOT = SPACES PERFORM ERROR-SECTION ELSE PERFORM NONHPS-CONV-TRANSFER END-IF WHEN 'AAC8LI' PERFORM HPS-CONV-TRANSFER-WITH-VIEW WHEN OTHER DISPLAY 'BEFORE IMS CHANGE CALL' CALL 'AIBTDLI' USING CHNG ALT-BLOCK TXN-CODE OF INPUTDATA DISPLAY 'AFTER IMS CHANGE CALL' DISPLAY 'ALT-BLOCK = ' , ALT-BLOCK DISPLAY 'RETURN CODE = ' , AIBRETRN OF ALT-BLOCK DISPLAY 'REASON CODE = ' , AIBREASN OF ALT-BLOCK SET ADDRESS OF ALT-PCB TO AIBRSA1 OF ALT-BLOCK IF HPS-IO-STATUS-CODE OF ALT-PCB NOT = SPACES PERFORM ERROR-SECTION ELSE MOVE ',' TO DATA-AREA OF OUT-AREA(1:1) MOVE TXN-DATA(1:8) TO DATA-AREA OF OUT-AREA(2:8) PERFORM HPS-CONV-TRANSFER END-IF END-EVALUATE. GOBACK. HPS-CONV-TRANSFER SECTION. MOVE HPS-SPA TO NEWHPS-SPA. MOVE TXN-CODE OF INPUT-DATA TO HPS-SPA-TRANCODE OF NEWHPS-SPA. CALL 'AIBTDLI' USING ISRT ALT-BLOCK NEWHPS-SPA. IF HPS-IO-STATUS-CODE OF ALT-PCB NOT = SPACES PERFORM ERROR-SECTION END-IF. IF DATA-AREA OF OUT-AREA NOT = SPACES CALL 'AIBTDLI' USING ISRT ALT-BLOCK OUT-AREA
11-17
013960
IF HPS-IO-STATUS-CODE OF ALT-PCB NOT = SPACES PERFORM ERROR-SECTION END-IF END-IF. EXIT. NONHPS-CONV-TRANSFER SECTION. * MOVE ZZ OF HPS-SPA TO ZZ OF NONHPS-SPA. * CALL 'AIBTDLI' USING ISRT ALT-BLOCK NONHPS-SPA. * MOVE 2100 TO LL OF NONHPS-SPA. MOVE HPS-SPA TO NONHPS-SPA. MOVE TXN-CODE OF INPUT-DATA TO SPA-TRANCODE OF NONHPS-SPA. CALL 'AIBTDLI' USING ISRT ALT-BLOCK NONHPS-SPA. IF HPS-IO-STATUS-CODE OF ALT-PCB NOT = SPACES 013960 PERFORM ERROR-SECTION END-IF. EXIT. 014000* 014100* Setup the AppBuilder Communications area 014200* HPS-CONV-TRANSFER-WITH-VIEW SECTION. DISPLAY 'HPS CONV XFER WITH VIEW'. MOVE TXN-DATA TO AAC8LI-VIEW. DISPLAY 'UPDATED VIEW'. SET HPS-USER-PARM-TRANS-IMM OF HPICOMM TO TRUE 014600* MOVE 'AAC8LI ' TO RULE-NAME OF HPICOMM. 014710* MOVE 'ZAADHLI ' TO IV-NAME OF HPICOMM. 014720* MOVE ' ' TO OV-NAME OF HPICOMM. 14800* MOVE 50 TO IV-FLENGTH OF HPICOMM. 14800* MOVE 0 TO OV-FLENGTH OF HPICOMM. 015500* MOVE 0 TO OV-ADDRESS OF HPICOMM. * MOVE SPA-ADDR TO CA-SPA-ADDRESS OF HPICOMM. * CALL 'HPSADDR' USING IV-PTR OF HPICOMM, AAC8LI-VIEW. * SET HPS-USER-PARM-FUNC-START OF HPECOMM TO TRUE MOVE HPS-LTERM-NAME OF IO-PCB TO HPS-USER-PARM-USE-TERM OF HPECOMM. * MOVE HPS-LTERM-NAME OF IO-PCB TO * HPS-USER-PARM-RET-TERM OF HPECOMM. 014600 MOVE 'AAC8LI ' TO RULE-NAME OF HPECOMM. 014710 MOVE 'ZAADHLI ' TO IV-NAME OF HPECOMM. 014720 MOVE ' ' TO OV-NAME OF HPECOMM. 14800 MOVE 50 TO IV-FLENGTH OF HPECOMM. 14800 MOVE 0 TO OV-FLENGTH OF HPECOMM. 015300 MOVE 0 TO IV-ADDRESS OF HPECOMM. 015500 MOVE 0 TO OV-ADDRESS OF HPECOMM. 015920 MOVE ' ' TO HPS-USER-PARM-RET-TRAN OF HPECOMM. MOVE SPA-ADDR TO HPS-USER-PARM-SPA-ADDRESS OF HPECOMM. CALL 'HPSADDR' USING IV-PTR OF HPECOMM, AAC8LI-VIEW. * 016600* 016700* Call the AppBuilder Application Program Interface HPI for old * and HPE for new. 016800* MOVE SPACES TO THE-REST OF HPS-SPA.
11-18
016900
018900 014000* 014100* Setup the AppBuilder Communications area 014200* 014210NG FROM HPECAPI'. DISPLAY 'ERROR MESSAGE = ' , HPS-USER-PARM-ERROR-MSG. 018900 EXIT.
DISPLAY 'CALLING HPECAPI'. CALL HPECAPI USING REG-ONE-PTR, HPECOMM. DISPLAY 'RETURNING FROM HPECAPI'. DISPLAY 'ERROR MESSAGE = ' , HPS-USER-PARM-ERROR-MSG. EXIT.
11-19
11-20
CHAPTER
12
GENERATING OPENCOBOL
AppBuilder 2.0.3.1 Enterprise Application Reference Guide
AppBuilder introduces a new option for building mainframe applications developed in COBOL. The OpenCOBOL generation facility produces easy to read and understand source code that follows established standards for COBOL. It is easy to maintain and suitable for a team approach to application development because it conforms to standard COBOL functions and data formats, where possible. The OpenCOBOL generation facility does not require the use of a separate runtime, as does currentlygenerated AppBuilder COBOL. External libraries that are required by the generated COBOL are provided in the source, as well as in the compiled code. AppBuilder generates externally-callable COBOL that is able to operate outside or inside an AppBuilder environment. The following topics are covered in this section: OpenCOBOL Requirements Host Preparation Configuring the Initialization File Rules Language Support and Constraints
OpenCOBOL Requirements
The following topics describe the system and configuration requirements for OpenCOBOL: Compiler Requirement Protocol Support
Compiler Requirement
COBOL compiler for COBOL for OS/390 & VM V2R2 IBM Enterprise COBOL for z/OS & OS/390 V3R1. Note
If you are not using decimals fields greater than 18, you can use COBOL for OS/390 & VM V2R1.
12-1
Protocol Support
The host listener is available for all the protocols AppBuilder supports: MQSeries - CICS only TCP/IP - CICS only LU6.2 - CICS and IMS Note
The host listener is not available for IMS, thus TCP/IP is not supported for IMS. MQSeries is also not supported for IMS.
Mapping Implementation Names

AppBuilder client applications refer to remote rules using the rules short-name. However, COBOL programs generated from host rules use the implementation names assigned during the generation process. The host runtime maintains a table that maps the implementation name to the rules shortname. You can use this table to call OpenCOBOL rules.
Compatibility Considerations
Differences between COBOL and Rules Language require consideration for application integration. For example, for some resident Rules Language functions there are no corresponding COBOL functions. Also, there are variations in data type formats that may affect the behavior of your programs. Unsupported functions and variations in behavior are outlined in this guide and in the Rules Language Reference Guide in the sections related to each function. Where possible, provisional recommendations are provided for modifications that remove the roadblocks.
Runtime Compatibility
Because of different calling conventions and data marshaling schemes, OpenCOBOL and runtimemanaged COBOL are completely non-interoperable. These generated programs cannot invoke one another. They should be generated and maintained in completely different CICS regions.
Configuring Middleware
COBOL that is generated from the OpenCOBOL generation facility can be accessed using remote AppBuilder rules. Several differences between OpenCOBOL and existing runtime-managed COBOL require modifications in AppBuilder middleware, such as: Direct invocation Rules used in OpenCOBOL must be called directly as a standard COBOL module. This differs from the existing AppBuilder-generated COBOL requirement. Data representation The representation of the AppBuilder field types DATE, TIME, and TIMESTAMP is different from runtime-managed COBOL. The OpenCOBOL data types require a different marshaling algorithm. The host middleware must be configured for the type of COBOL module it is calling.
12-2
The following sections describe the configuration options for OpenCOBOL generation middleware: Configuring CICS Regions for COBOL Data Types Configuring IMS Regions for COBOL Data Types
Configuring CICS Regions for COBOL Data Types

The CICS region on your development host follows a process that reads the rules you have defined and responds with an action. In the middleware phase of processing, the middleware receives the trigger from either MQ or TCP/IP and the message is assembled from individual or multiple packets. After it is assembled, the data is marshaled, if necessary, and the program is called either directly or from the runtime. Due to the variations in COBOL data types, OpenCOBOL rules and runtime-managed COBOL rules must be marshaled and invoked differently. For this reason, you must configure each CICS region to contain one type of generated COBOL exclusively. The middleware then provides a flag that specifies which type of generated COBOL to invoke for each partition. Note
If both types of COBOL must operate simultaneously, two different instances of the middleware are required.
Figure 12-1 illustrates the modified host middleware run-time architecture.

Figure 12-1 Middleware Architecture for OpenCOBOL
After receiving the trigger from either MQ or TCP/IP, the message can be assembled from multiple packets. After assembly, the data is marshaled, if necessary, and the program is called either directly or through the runtime.
Configuring IMS Regions for COBOL Data Types

You cannot update the IMS DNAINI file with a transaction, as you can in CICS with NEAD. To update the INI file in IMS, first edit a sequential file (for example, HPSLE.BASE.SVI541.HPSDNAIN.VSEQ (VB 255)), then run a job that reads the sequential file, creates an assembler program, and links it as DNAINI. A sample job (INIUTIL) in the SAMP80 dataset is supplied to perform this task.
12-3
The TRACING DEBUGLVL setting is the only one used in IMS that you may need to change. In IMS tracing, the view data is not displayed, as it is in CICS using ERRORS_AND_TRACES. Client configuration for LU2 communications uses the host name as the name of the region (IMSF), the protocol is set to lu2I, and the Server_ID is set to PCIO0000. For example: DEFAULT_HOST_NAME=imsf DEFAULT_PROTOCOL=lu2i DEFAULT_SERVERID=PCIO0000 The logon and logoff scripts must be modified for IMS, since the logon panel is different than IMS and the logoff command is /rcl. Note
All IMS commands start with a slash (/).
Configuration for LU6.2, usually from a gateway, uses the host name as the LU name for the region, and typically begins with CRY, followed by the region name (for example: CRYIMSF), with the protocol set to lu62, the Server_ID set to ne20(must be lowercase), and the MODE_NAME in the [LU6.2] section set to APPCPCLM. For example: DEFAULT_HOST_NAME=CRYIMSF DEFAULT_PROTOCOL=lu62 DEFAULT_SERVERID=ne20 [LU6.2] MODE_NAME=APPCPCLM A security exit must be used to pass a valid mainframe User ID and PASSWORD. Logging On To the IMS Region To log on to a region, define the terminal to IMS. The terminal IDs from trexsna have been defined, so you must configure your emulator to connect using trexsna. Then, at the VTAM screen, you can enter the name of the region, for example: IMSF. The command to logoff IMS is /rcl. IMS requires that all terminals be defined to the region or you will receive the error message: UNABLE TO ESTABLISH SESSION. The terminals from the trexsna server have been defined to all IMS regions, so you must connect using a 3270 configuration that uses trexsna. To verify that the IMS region is ready, log on to the region and issue the following commands. /dis a command will display: REGID JOBNAME TYPE TRAN/STEP PROGRAM STATUS 1 IMC54VR1 TPE WAITING BATCHREG BMP NONE FPRGN FP NONE DBTRGN DBT NONE IMS51RC5 DBRC VTAM ACB OPEN -LOGONS ENABLED IMSLU=SEERNET.CRYIMSF APPC STATUS=ENABLED CLASS 1, 2, 3,
12-4
Host Preparation
Verify that the message processing region is running. In the example above, IMC54VR1 is the message processing region, the LU name for LU6.2 is CRYIMSF, and LU6.2 is configured and running (APPC STATUS=ENABLED). It is running and in WAITING status. If the message processing region is not started, you can start it using the command: /STA REG IMC54VR1 Issue the IMS commands: /dis prog pcio0000 /dis tran pcio0000 /dis tran hpsdi600 If any of the programs are stopped, start them with the command: /sta prog <progname> If a transaction is stopped, start it with the command: /sta tran <tran name> Finally, check that DB2 is connected to IMS by issuing the command: /dis subsys all It should show that the DB2 subsystem DSN1 is connected. When an IMS rule is prepared, there is no step that installs the program into the region, as there is in CICS prepare. The message processing region has to stop and restart, then the rule can be executed. You can stop the region by typing /STO REG 1, where 1 is the Region ID. The Region ID is listed under REGID of the output of the /DIS A command. You can then restart the message processing region by issuing the command: STA REG IMC54VR1.
Performance Marshaling for Java

Normally, the AppBuilder middleware line-representation is the AppBuilder communications platform-independent representation. In order to reduce host resource, the data can be marshaled to the hosts specification on the client. This is called performance marshaling and already exists for the current host view representation. Since there is a new representation caused by the introduction of standardized data types, an additional performance marshaling facility is available.
Host Preparation
The host preparation and Rebuild processes build the COBOL VIEW and SET copybooks, and call the OpenCOBOL code generator. AppBuilder displays a panel that allows you to define how you want to prepare the rules.
12-5
Host Preparation
Options for defining your application preparation settings include: VIEW Prepare SET Prepare Rule Prepare
VIEW Prepare
The VIEW prepare creates copybooks that can be used by components. They are built using the old-style date, time, timestamp and large decimal fields for compatibility with old applications. AppBuilder also creates a separate copybook library to prepare using the new data type formats. The prepare method gives you three options: Prepare using the old style Prepare using the new style Prepare using both styles
Creating VIEW Using COPY

The OpenCOBOL generation facility does not create the data structure for a VIEW. It uses the COPY statement to include the VIEW from the SYSLIB. In order for the compile to be successful, the VIEW prepare must run before the OpenCOBOL compile is initiated. To ensure that this step precedes the compile, you have the option to prepare VIEWs in a separate step before the compile. If the VIEW has not changed, you can choose to not prepare it.
SET Prepare
The SET prepare creates copybooks that can be used by components. In runtime-managed AppBuilder they use the old style date, time, timestamp and large decimal fields. For compatibility with standard COBOL applications, AppBuilder creates a separate copybook library to prepare using the standard format. The OpenCOBOL style includes the display value which AppBuilder retrieves from the repository. The SET prepare method has three options: prepare the old way, new way or both. You can modify the initialization (INI) configuration settings to allow comments to be included.
Creating SET Using COPY

The code generator no longer creates the data structure for a SET. Use the COPY statement to include the SET from the SYSLIB. Thus, in order for the compile to be successful the SET prepare must have run before the COBOL compiles. To ensure that this step precedes the compile, you have the option to prepare SETs in a separate step before the compile. If the SET has not changed, you can choose to not prepare it.
12-6
Host Preparation
Rule Prepare
You use the Rule prepare screen to select which type of prepare you want to perform, runtime-managed COBOL or OpenCOBOL. You can also select an option to include the VIEW and SET prepares or exclude them, as desired. During an OpenCOBOL prepare, the code generator creates the COBOL source code and the VIEW and SET copybooks. AppBuilder determines if the VIEW and SET copybooks need to be prepared using the bind file. The Bind file creation program queries the ENT_SIG_CHANGE and ENT_METHOD_STATUS to determine if the copybooks need to be created. 1. Bind File The Bind file program includes a field for both SET and VIEW that tells the code generator whether to create the copybook for the VIEW or the SET. For each VIEW and SET in the bind file where the ENT_SIG_CHANGE > ENT_METHOD_STATUS, AppBuilder turns the switch on. The code generator then generates the copybook. 2. Code Generator AppBuilder executes R2CGEN with parameters that invoke the OpenCOBOL generation. AppBuilder changes the file that holds the generated source code from a temporary sequential file to a PDS similar to the copybook files. AppBuilder code generator queries the Bind file and creates a VIEW and SET copybook for each instance in the Bind file where the creation switch is set to ON. 3. COBOL Compile If you want the rule to be dynamically linked, specify DYNAM when preparing for OpenCOBOL. This replaces the called component or rule VCON with an IGZ module, so the LE runtime will do the call instead of the called rule being statically linked into the load module. If you want the rule to be statically linked, specify NODYNAM. This requires that all subordinate rules comprising the load module must have already been prepared. If you are using OS/390 2.2 and large decimals, specify ARITH(EXTEND) or abbreviation AR(E) for the compiler option. 4. Link In OpenCOBOL, the link cards are the ENTRY statement and the INCLUDE of the object. 5. LU2 When defining a transaction program, use the rule implementation name. 6. BNDX This preparation processing step extracts the source and creates a temporary copybook file for the VIEW used by the component. AppBuilder generates the copybook using the new field types for date, time, timestamp, and large decimals. See Chapter 5, Building Applications for more details on preparation steps. The following methods are available for OpenCOBOL to generate copybooks for VIEW and SET: ENT_SIG_CHANGE ENT_METHOD_STATUS
12-7
Configuring the Initialization File
Configuring the Initialization File

The following configuration settings can be defined by modifying the initialization file. DATE, TIME, and TIMESTAMP CICS Translator
Defining Options in the Initialization File

The code generation facility uses existing AppBuilder initialization (.INI) files to define options for the generation of OpenCOBOL. For example, the generation of error checking and debug information in the generated COBOL is controlled by an INI file option. Error, debugging, trace, warning, and informational messages produced during the generation of OpenCOBOL function in the same way as in existing runtime-managed COBOL. Middleware messages, including NetEssential trace, also function the same way, whether calling OpenCOBOL or the current runtime-managed COBOL.
DATE, TIME, and TIMESTAMP

The ISO standards for DATE, TIME, and TIMESTAMP format delimiters are supported in AppBuilder development. However, you can modify these delimiter settings for a particular DB2 instance by changing them in the initialization file. IMS Support The ISO standards for DATE, TIME, and TIMESTAMP format delimiters are supported in AppBuilder development.
CICS Translator
AppBuilder provides the option for using a CICS translator based on the type of calls you want to make. If the calls are CICS or CICS/BATCH, they automatically go through the translator. If you do not want to pass DFHEIBLK and COMMAREA from the rule, set the correct parameters for the CICS translator to deny that action for those calls using the NOLINKAGE command.
OpenCOBOL Methods
The following methods are available for use in developing OpenCOBOL source code: ENT_METHOD_STATUS ENT_SIG_CHANGE ENT_METHOD_STATUS This method searches through the bind file and finds the instances where the prepare switch is set to ON for SET and VIEW and updates the ENT_METHOD_STATUS.
12-8
Rules Language Support and Constraints
ENT_SIG_CHANGE If you change a view or field, the hierarchy change stamp is updated in the ENT_SIG_CHANGE table, marking all its parents for prepare. During the Rule prepare, the code generator step prepares the VIEW, before the COBOL is compiled. If a SET changes, then the hierarchy change stamp is updated in the ENT_SIG_CHANGE table and marking all its parents for prepare. During the rule prepare, the code generator step prepares the SET before the COBOL is compiled. Note
The SET prepare step is not needed when preparing for OpenCOBOL, the Rule prepare process manages this step.

With few exceptions, all Rules Language statements and system components are supported for use with OpenCOBOL. Exceptions are listed in this section, including: 3270 Converse Native COBOL Large Decimals Component Calls Dynamic COBOL Calls Truncating Intermediate Results TIMESTAMP Function Mathematical Functions
3270 Converse
3270 Converse statements are not supported, including: Converse window Converse report
Native COBOL
Native COBOL applications that call AppBuilder rules cannot use the HPECAPI and HPBCAPI call interfaces.
12-9
Large Decimals
In AppBuilder, large decimal fields (always DEC 19-31 and configurable from 15 to18) are currently stored internally as character fields. In order to enter them into a DB2 database, the database must define the field as character. If you are currently using this procedure and want to migrate to OpenCOBOL, convert your DB2 tables to define these columns as Decimal fields; or perform the conversions manually.
Component Calls
You can use only one type of component call per hierarchy. If one component is built to use a COMMAREA, then all components must use a COMMAREA. This includes calls to AppBuilder default repository components.
Dynamic COBOL Calls

AppBuilder currently generates dynamic COBOL calls using the DYNAM compiler option for rules that do not contain any CICS. Note
The DYNAM compiler option is not supported for preparing components that contain CICS.
Truncating Intermediate Results

In previous releases, AppBuilder provided compatibility options for truncating intermediate results in mathematical expressions. In OpenCOBOL generation, only the intermediate results use COBOL rules. To ensure that you define the fields in mathematical expressions correctly, review your application. See Appendix A in the COBOL for OS/390 Programming Guide for more information.
TIMESTAMP Function
The TIMESTAMP function is not supported in OpenCOBOL because there are no COBOL or LE functions that return this information. Reconfigure applications that use TIMESTAMP to use DB2 to retrieve the timestamp.
Mathematical Functions
AppBuilder OpenCOBOL sends an error message when preparing rules that utilize the mathematical functions: CEIL, FLOOR, TRUNC, and ROUND. To program the level of mathematical precision required for your application, recode the application using fields that are defined according to COBOL rules.
12-10
CHAPTER
13
WRITING BATCH COMPONENTS
AppBuilder batch components enable execution of host-dependent actions under the control of AppBuilder rules-based processing. These AppBuilder batch components (written in COBOL II, assembler, PL/I, or C) are normal batch programs that accept input data and return output data in a format that AppBuilder views define. As in CICS, a communications area is defined in a format that all AppBuilder batch components follow. The executable file created when you prepare a host component written in C depends on the components execution environment attribute: If the execution environment is PCCICS, preparation creates a PC executable file. If the execution environment is mainframeBATCH, preparation creates an mainframe executable file. Note
You cannot prepare a C component with an execution environment of CICS.
PL/I Component STAE Option

On the mainframe, COBOL and PL/I use the STAE mechanism of the operating system to handle abends. An abend can occur if a COBOL routine with the STAE run-time option enabled calls a PL/I routine that also has the STAE enabled. To avoid abends and ensure proper execution, include the NOSTAE execution option for all batch PL/I components. The PLIXOPT string specifies the PL/I run-time options. To disable the STAE option, add the following code to batch PL/I components: DCL PLIXOPT CHAR(6) VAR INIT('NOSTAE') STATIC EXTERNAL; The following examples illustrate batch components: Sample BAL Component Sample C Component Sample COBOL Component Sample PL/I Component
13-1
Sample BAL Component

TITLE 'Test batch Component linkage' HPMBCO3 CSECT PRINT GEN SPACE STM RE,RC,12(RD) Save caller's registers LR RC,RF Program base register USING HPMBC03,RC Notify assembler ST RD,SAVEAREA+4 Save forward link LA R2,SAVEAREA Address of our area ST R2,8(RD) Save backward link LR RD,R2 Use our save area now SPACE L R1,4(,R1) Address of communication area USING COMMAREA,R1 Notify assembler SPACE L R6,ADDRESSI Address of Input View USING HPMBC03I,R6 Notify assembler SPACE L R7,ADDRESSO Address of Output View USING HPMBC03O,R7 Notify assembler SPACE MVC OUTPUT,INPUT Copy input to output SPACE L RD,SAVEAREA+4 Address caller's save area L RE,12(RD) Caller's return address LM R0,RC,20(RD) Restore registers SLR RF,RF Make return code zero BR RE Return control EJECT SAVEAREA DS 9D LTORG EJECT COMMAREA DSECT COPY COMMAREA SPACE HPMBC03I DSECT INPUT DS CL78 SPACE HPMBC03O DSECT OUTPUT DS CL78 EJECT COPY EQUATES END HPMBC0
Sample C Component
#define LENGTH 78 typedef struct { char Field(|LENGTH|); } input;
13-2
Writing Batch Components
typedef struct { char Field(|LENGTH|); } output; typedef struct { char dummy(|1|); #include <commarea> void main(argc, parmaddr) int argc; parmlist *parmaddr; { int i = LENGTH; INPUT (hpmbc04i); OUTPUT (hpmbc04o); while } (i--){ hpmbc04o->Field(|i|) = hpmbc04i->Field(|i|); }
} local;
Sample COBOL Component

IDENTIFICATION DIVISION. PROGRAM-ID. HPMBC01. AUTHOR. INSTALLATION. CHANGE MANAGEMENT ARCHITECTURE. *REMARKS. THIS PROGRAM TESTS THE HPSBATCH LINKAGE. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. IBM-370 OBJECT-COMPUTER. IBM-370 DATA DIVISION. WORKING-STORAGE SECTION. EJECT LINKAGE SECTION. 01 DUMMY. 03 DUMMY-FIELD PIC X(1). 01 DFHCOMMAREA. COPY HPSCOMM. EJECT COPY HPMBC01I. EJECT COPY HPMBC01O. EJECT PROCEDURE DIVISION USING DUMMY DFHCOMMAREA. MAINLINE SECTION **************************************************** * COPY INPUT VIEW TO OUTPUT VIEW. * **************************************************** ML-000-COPY-VIEW.
13-3
SET ADDRESS OF HPMBC01I TO IV-PTR. SET ADDRESS OF HPMBC01O TO OV-PTR. MOVE BATCH-FIELD OF HPMBC01I TO BATCH-FIELD OF HPMBC01O. ML-999-RETURN. GOBACK.
Sample PL/I Component

HPMBC02: PROCEDURE(COMMADDR) OPTIONS(MAIN); DCL COMMADDR PTR; DCL 1 COMMAREA BASED (COMMADDR) UNALIGNED, %INCLUDE HPSCOMM;; DCL 1 INPUT_VIEW BASED(IV_PTR) UNALIGNED, %INCLUDE HPMBC02I;; DCL 1 OUTPUT_VIEW BASED(OV_PTR) UNALIGNED, %INCLUDE HPMBC02O;; /**************************************************/ /* EXECUTION STARTS HERE */ /**************************************************/ OUTPUT_VIEW = INPUT_VIEW; END HPMBC02;

This section describes the PL/I, COBOL II, assembler, and C host components used for the AppBuilder communications area. The COMMAREA for each type of component is kept in a copybook called HPSCOMM. The communications area is the same for CICS, IMS, and batch components. To review the specific components code, refer to PL/I Components COBOL II Components BAL Components C Components
PL/I Components
Note 1 2 3 4 5 6 7 8
The name of the PL/I structure and the name of the PL/I pointer variable do not necessarily have to be the same as the ones described in line 1 of the example.
DCL 1 COMMAREA BASED(COMPOINT) UNALIGNED, 3 RULE_NAME CHAR(8), 3 RULE_COMP_NAME CHAR(8), 3 TCTUA_AREA_PTR POINTER, 3 USE_LINE_NUMBER FIXED BIN(15,0), 3 HPSCOMM_FILLER CHAR(2), 3 INPUT_VIEW, 5 IV_NAME CHAR(8),
13-4
9 10 11 12 13 14 15 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
5 5 5 3 5 5 5 5 3 5 5 5 5 3 3 3 3 3 /* /* /* 3 /* 3 5 5 5 5
IV_LENGTH IV_FILLER IV_PTR OUTPUT_VIEW, OV_NAME OV_LENGTH OV_FILLER OV_PTR LOCAL_VIEW, LV_NAME LV_LENGTH LV_FILLER LV_PTR EXEC_ENVIRON START_REPORT_IND HPS_RULE_HANDLE_ERRORS HPS_VERSION_NUMBER
FIXED BIN(15,0), CHAR(2), POINTER, CHAR(8), FIXED BIN(15,0), CHAR(2), POINTER, CHAR(12), FIXED BIN(15,0), CHAR(2), POINTER, CHAR(6), CHAR(1), CHAR(1), CHAR(2),
HPS_FUNCTION FIXED BIN(15,0), USE RULE = 10 */ USE COMPONENT = 11 */ USE RULE NOWAIT = 12 */ HPS_RETURN_CODE FIXED BIN(15,0), NORMAL = 00 */ HPS_OPTIONAL_FEATURE_LIST, OPFL_NAME CHAR(8), OPFL_LENGTH FIXED BIN(15,0), OPFL_FILLER CHAR(2), OPFL_PTR POINTER;
COBOL II Components
************************************************************ * * * Classification = BluePhoenix Solutions * * * * $$NAME NAME=HPSCOMM * * * * $$VERSION ID=3.1.0,3.2.0.3.1 * * * Date = December 20, 2002 * * * * DESCRIPTION - THIS COPYBOOK DESCRIBES AppBuilder/CICS * * STANDARD COMMUNICATION AREA. * ************************************************************ 1 05 HPS-COMMAREA PIC X(128). 2 05 FILLER REDEFINES HPS-COMMAREA. 3 10 RULE-NAME PIC X(8). 4 10 RULE-COMP-NAME PIC X(8). 5 10 TCTUA-AREA-PTR POINTER. 6 10 TCTUA-AREA-ADDRESS REDEFINES TCTUA-AREA-PTR 7 PIC X(4).
13-5
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62
10 10 10 15 15 15 15 15 10 15 15 15 15 15 10 15 15 15 15 15 10 10 10 10 10 88 88 88 88 88 88 10 88 10 15 15 15 15 15 PIC 05 05 10 15 15 15 15 10 10 15 88 88 15 10
USE-LINE-NUMBER PIC S9(4) COMP. HPS-VERSION-NUMBER PIC X(2). INPUT-VIEW. IV-NAME PIC X(8). IV-LENGTH PIC S9(4) COMP. FILLER PIC XX. IV-PTR POINTER. IV-ADDRESS REDEFINES IV-PTR PIC X(4). OUTPUT-VIEW. OV-NAME PIC X(8). OV-LENGTH PIC S9(4) COMP. FILLER PIC XX. OV-PTR POINTER. OV-ADDRESS REDEFINES OV-PTR PIC X(4). LOCAL-VIEW. LV-NAME PIC X(12). LV-LENGTH PIC S9(4) COMP. FILLER PIC XX. LV-PTR POINTER. LV-ADDRESS REDEFINES LV-PTR PIC X(4). EXEC-ENVIRON PIC X(6). START-REPORT-IND PIC X. HPS-RULE-HANDLE-ERRORS PIC X. HPS-VERSION-NUMBER2 PIC XX. HPS-FUNCTION PIC S9(4) COMP. HPSFN-USE-RULE VALUE 10. HPSFN-USE-COMPONENT VALUE 11. HPSFN-USE-RULE-NOWAIT VALUE 12. HPSFN-USE-RULE-WAIT VALUE 13. HPSFN-USE-CONVERSE VALUE 14. HPSFN-USE-START-TRANS VALUE 15. HPS-RETURN-CODE PIC S9(4) COMP. NORMAL VALUE 00. HPS-OPTIONAL-FEATURE-LIST. OPFL-NAME PIC X(8). OPFL-LENGTH PIC S9(4) COMP. SUBHDR-LEVEL PIC 99. OPFL-PTR POINTER. OPFL-ADDRESS REDEFINES OPFL-PTR S9(8) COMP. HPS-EXTENDED-COMMAREA PIC X(384) VALUE LOW-VALUES. FILLER REDEFINES HPS-EXTENDED-COMMAREA. HPS-FLENGTH. IV-FLENGTH PIC S9(8) COMP. OV-FLENGTH PIC S9(8) COMP. LV-FLENGTH PIC S9(8) COMP. FILLER PIC X(20). HPS-CONVERSE-AREA PIC X(32). FILLER REDEFINES HPS-CONVERSE-AREA. HPS-USE-CONVERSE-OPTIONS PIC S9(4) COMP. HPS-USE-NEST VALUE +1. HPS-NOOPTION VALUE +0. FILLER PIC X(30). HPS-FEEDBACK-AREA.
13-6
63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101
15 HPS-MESSAGE1 PIC X(80). 15 HPS-MESSAGE2 PIC X(80). 15 HPS-MESSAGE3 PIC X(80). 15 HPS-ERROR-REQUEST. 20 HPS-LOG-REQUEST PIC X. 88 HPS-REQUEST-TO-LOG VALUE 'L'. 88 HPS-REQUEST-TO-ABEND VALUE 'A'. 88 HPS-REQUEST-FOR-BOTH VALUE 'B'. 20 HPS-SEND-REQUEST PIC X. 88 HPS-REQUEST-TO-SEND VALUE 'S'. 20 FILLER PIC XX. 20 HPS-ABCODE PIC X(4). 15 FILLER PIC X(8). 10 HPS-PRIVATE-POINTERS-AREA. 15 CA-GLBL-PTR POINTER. 15 CA-GLBL-ADDRESS REDEFINES CA-GLBL-PTR PIC S9(8) COMP. 15 CA-FIRST-PTR POINTER. 15 CA-FIRST-ADDRESS REDEFINES CA-FIRST-PTR PIC S9(8) COMP. 15 CA-CURRENT-PTR POINTER. 15 CA-CURRENT-ADDRESS REDEFINES CA-CURRENT-PTR PIC S9(8) COMP. 15 CA-PREV-PTR POINTER. 15 CA-PREV-ADDRESS REDEFINES CA-PREV-PTR PIC S9(8) COMP. 15 CA-CVPL-PTR POINTER. 15 CA-CVPL-ADDRESS REDEFINES CA-CVPL-PTR PIC S9(8) COMP. 15 CA-TWA-PTR POINTER. 15 CA-TWA-ADDRESS REDEFINES CA-TWA-PTR PIC S9(8) COMP. 15 CA-TRSA-PTR POINTER. 15 CA-TRSA-ADDRESS REDEFINES CA-TRSA-PTR PIC S9(8) COMP. 15 FILLER PIC X(04). * THE CONVERSE PRIVATE AREA CONTAINS POINTERS TO FIRST, * CURRENT AND PREVIOUS CVW'S(CONVERSE WORK AREAS) 10 HPS-CONVERSE-PRIVATE-AREA PIC X(32).
BAL Components
************************************************************ * THIS SECTION MAPS THE CALLERS COMMAREA WHICH CONTAINS HPS * STORAGE CTL ************************************************************ SPACE HPSSTGDS DSECT HPSSCNTL DS OF AppBuilder STORAGE FACILITY CONTROL AREA HPSCRCNM DS CL8 CALLING RULE OR COMPONENT HPSRCNME DS CL8 CALLED RULE OR COMPONENT NAME HPSTCTUA DS XL4 SAVE AREA FOR TCTUA ADDRESS
13-7
HPSLIN#
DS XL2 USE LINE NUMBER DS XL2 FILLER SPACE ************************************************************ * THIS SECTION MAPS THE CALLERS INPUT VIEW STATUS BLOCK AREA ************************************************************ SPACE HPSIVIEW DS 0XL16 INPUT VIEW AREA HPSIVNME DS CL8 NAME OF INPUT VIEW HPSIVLEN DS H LENGTH OF INPUT VIEW HPSIVFIL DS XL2 FILLER BYTES HPSIVADR DS XL4 INPUT VIEW ADDRESS SPACE ************************************************************ * THIS SECTION MAPS THE CALLERS OUTPUT VIEW STATUS BLOCK * AREA ************************************************************ SPACE HPSOVIEW DS 0XL16 OUTPUT VIEW AREA HPSOVNME DS CL8 NAME OF OUTPUT VIEW HPSOVLEN DS H LENGTH OF OUTPUT VIEW HPSOVFIL DS XL2 FILLER BYTES HPSOVADR DS XL4 OUTPUT VIEW ADDRESS SPACE ************************************************************ * THIS SECTION MAPS THE CALLERS LOCAL VIEW STATUS BLOCK AREA ************************************************************ SPACE HPSLVIEW DS 0XL20 LOCAL VIEW AREA HPSLVNME DS CL12 NAME OF LOCAL VIEW HPSLVLEN DS H LENGTH OF LOCAL VIEW HPSLVFIL DS XL2 FILLER BYTES HPSLVADR DS XL4 LOCAL VIEW ADDRESS SPACE EXECENV DS CL6 EXECUTION ENVIRONMENT DS XL2 USED FOR REPORT WRITER HPSVRM DS CL2 VERSION-RELEASE-MOD HPSFN DS H FUNCTION CODE USERULE EQU 10 USE RULE USECOMP EQU 11 USE COMPONENT ASYNCREQ EQU 12 USE RULE NOWAIT(ASYNC START) HPSRCODE DS H RETURN CODE ************************************************************ * THIS SECTION MAPS OPTIONAL FEATURES LIST CONTROL AREA ************************************************************ SPACE HPSOPIEW DS 0XL16 OPTIONAL FEATURES LIST AREA HPSOPNME DS CL8 NAME OF OPTIONAL FEATURES LIST HPSOPLEN DS H LENGTH OF OPTIONAL FEATURES LIST HPSOPFIL DS XL2 FILLER BYTES HPSOPADR DS XL4 OPTIONAL FEATURES LIST ADDRESS * HPSCNLEN EQU *-HPSSCNTL LENGTH OF THE CONTROL AREA
13-8
C Components
typedef struct char Rule(|8|); char comp(|8|); long filler1; short line; short filler2; char namei(|8|); short lengthi; short filler3; input *addressi; char nameo(|8|); short lengtho; short filler4; output *addresso; char namel(|12|); short lengthl; short filler5; local *addressl; commarea; typedef struct char *dummy; commarea *commaddr; parmlist; #define INPUT(X) input *X = parmaddr-commaddr-addressi #define OUTPUT(X) output *X = parmaddr-commaddr-addresso
13-9
13-10
CHAPTER
14
SAMPLE BATCH APPLICATIONS
The following code samples show the command language used for AppBuilder batch DB2 and non-DB2 rules. The major difference between them is that the DB2 version runs under the DB2 command processor DSN. Substitute the variables at the time you submit the command language with the values contained in various AppBuilder-supplied INI files.
Batch DB2 Command Language

The code sample below shows the command language for AppBuilder batch DB2 rules. //SS0206R JOB (NA2,HPSD),'CHRIS D',MSGLEVEL=(1,1),NOTIFY=SS0206, // MSGCLASS=X,CLASS=1,PRTY=15 //*ROUTE PRINT RAAV // **************************************************************** //* SAMPLE BATCH DB2 JCL // **************************************************************** //RUNBATCH EXEC PGM=IKJEFT01,DYNAMNBR=50,REGION=4096K // **************************************************************** //* THE STEPLIB SHOULD CONTAIN: //* 1. THE DB2 RUNTIME LIBRARIES //* 2. THE COBOL RUNTIME LIBRARIES //* 3. THE PLI RUNTIME LIBRARIES //* 4. THE C/370 RUNTIME LIBRARIES //* 5. AppBuilder USER BATCH LOADLIB //* 6. AppBuilder BASE BATCH LOADLIB //* 7. AppBuilder BASE LOADLIB // **************************************************************** //STEPLIB DD DSN=&DB2LOAD.,DISP=SHR // DD DSN=&DB2LINK.,DISP=SHR // DD DSN=&COB2LINK.,DISP=SHR // DD DSN=&PLILINK.,DISP=SHR // DD DSN=&PLILINK2.,DISP=SHR // DD DSN=&C370LNK1.,DISP=SHR // DD DSN=&C370LNK2.,DISP=SHR
14-1
Batch Command Language
// DD DSN=&USRVQUAL..LOADBT,DISP=SHR // DD DSN=&REPQUAL..LOADBT,DISP=SHR // DD DSN=&MODQUAL..LOADBT,DISP=SHR // DD DSN=&BASEQUAL..LOADBT,DISP=SHR // DD DSN=&REPQUAL..LOADLIB,DISP=SHR // DD DSN=&MODQUAL..LOADLIB,DISP=SHR // DD DSN=&BASEQUAL..LOADLIB,DISP=SHR //**************************************************************** //* INPUT DD REQUIRED //**************************************************************** //INPUT DD DUMMY //**************************************************************** //* OUTPUT DD REQUIRED - USED FOR MESSAGES //**************************************************************** //OUTPUT DD SYSOUT=* //**************************************************************** //* USERS VIEWDEF VSAM FILE //**************************************************************** //VIEWFILE DD DSN=NAVHP.SS0009.USER1.BATCH.VIEWDEF,DISP=SHR //**************************************************************** //* ALLOCATE APPLICATION INPUT AND OUTPUT FILES HERE //* (E.G., REPORT, INPUT FILES, OUTPUT FILES) //**************************************************************** //SYSTSPRT DD SYSOUT=* //SYSABOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //CEEDUMP DD SYSOUT=* //PLIDUMP DD SYSOUT=* //**************************************************************** //* INPUT FOR RUNNING UNDER DB2: //* SYSTEM - THE DB2 SUBSYSTEM YOU ARE RUNNING UNDER //* PROG - ALWAYS EXECUTING HPSBATCH //* PLAN - PLAN NAME FOR RULE //* PARM - SYSTEM ID OF RULE //**************************************************************** //SYSTSIN DD * DSN SYSTEM(LEVEL8) RUN PROG(HPSBATCH) + PLAN(B1A1PLNB) + PARM('AAQANR') END /*

The code sample below shows the command language for AppBuilder non-DB2 batch rules. //SS0206C JOB (NA2,HPSD),'RUN PROG',CLASS=1, // NOTIFY=SS0206,MSGCLASS=X,REGION=4096K,PRTY=15 //****************************************************************
14-2
//* SAMPLE BATCH JCL //**************************************************************** //**************************************************************** //* PARM IS RULE SYSTEM ID //**************************************************************** //RUN EXEC PGM=HPSBATCH,PARM='AAMNNR' //**************************************************************** //* THE STEPLIB SHOULD CONTAIN: //* 1. THE COBOL RUNTIME LIBRARIES //* 2. THE PLI RUNTIME LIBRARIES //* 3. THE C/370 RUNTIME LIBRARIES //* 4. AppBuilder USER BATCH LOADLIB //* 5. AppBuilder BASE BATCH LOADLIB //* 6. AppBuilder BASE LOADLIB //**************************************************************** //STEPLIB DD DSN=MV.COBOLII.COB2LIB,DISP=SHR // DD DSN=MV.PLI2.SIBMLINK,DISP=SHR // DD DSN=MV.PLI2.PLILINK,DISP=SHR // DD DSN=MV.EDC.SIBMLINK,DISP=SHR // DD DSN=MV.EDC.SEDCLINK,DISP=SHR // DD DSN=SS0009.<QUALIFIERS.USRVQUAL>.<HPSRT.LOADBT> // DD DSN=SS0009.<QUALIFIERS.MODQUAL>.<HPSRT.LOADBT> // DD DSN=SS0009.<QUALIFIERS.BASEQUAL>.<HPSRT.LOADBT> // DD DSN=SS0009.BASE.BATCH.LOADLIB,DISP=SHR // DD DSN=SS0009.MOD.LOADLIB,DISP=SHR // DD DSN=SS0009.BASE.LOADLIB,DISP=SHR //**************************************************************** //* INPUT DD REQUIRED //**************************************************************** //INPUT DD DUMMY //**************************************************************** //* OUTPUT DD REQUIRED - USED FOR MESSAGES //**************************************************************** //OUTPUT DD SYSOUT=* //**************************************************************** //* USERS VIEWDEF VSAM FILE //**************************************************************** //VIEWFILE DD DSN=NAVHP.SS0009.USER1.BATCH.VIEWDEF,DISP=SHR //**************************************************************** //* ALLOCATE APPLICATION INPUT AND OUTPUT FILES HERE //* (E.G., REPORT, INPUT FILES, OUTPUT FILES) //**************************************************************** //OUTPUTF DD DSN=&&OUTPUT1,DISP=(,CATLG,DELETE), // DCB=(RECFM=FBA,LRECL=133,BLKSIZE=23408) //SYSTSPRT DD SYSOUT=* //SYSABOUT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //CEEDUMP DD SYSOUT=* //PLIDUMP DD SYSOUT=* /*
14-3
14-4
CHAPTER
15
BATCH API FOR PLI AND COBOL II
The AppBuilder batch user application interface allows user-written applications to initiate AppBuilder batch rules. This interface, available to PLI and COBOL II programs only, is similar to the AppBuilder user application interface available under CICS but with less functionality than the CICS counterpart due to limitations in the batch environment.
Using HPBCAPI
In order to utilize the AppBuilder batch interface, the application program must call the interface program HPBCAPI, passing the AppBuilder User Commarea as the second parameter. The copybook HCUUCOM is used to define the communications area between HPBCAPI and the user application program. The copybook HCUUCOI is used to properly initialize the communications area. For PL/I calling HPBCAPI, follow the PL/I and COBOL II language reference manuals for the interlanguage support guidelines and restrictions. The AppBuilder rule may be initiated in three different ways: LINK Rule Initiation Static Link Initiation COBOL Dynamic Call Initiation
LINK Rule Initiation

If initiation by an mainframe LINK is desired, the calling program must select the link function and provide the necessary view information in the commarea. Upon completion of the AppBuilder rule, control is returned to the calling program immediately after the call to HPBCAPI.
Static Link Initiation

If initiation by static link is desired, the calling program must select the link function and provide the necessary view information in the commarea in exactly the same manner as for a mainframe LINK. The static link requires a change at link edit time to bring in the AppBuilder rule object code instead of the object code for the dynamic linker (for more information, see Static Linkage.) Upon completion of the
15-1
Using HPBCAPI
AppBuilder batch rule, control is returned to the calling program immediately after the call to HPBCAPI.
COBOL Dynamic Call Initiation

If initiation by a COBOL dynamic call is desired, the calling program must select the COBOL dynamic call function and provide the necessary view information in the commarea. Upon completion of the AppBuilder batch rule, control is returned to the calling program immediately after the call to HPBCAPI. The batch program verifies that the passed information concerning the input and output views is correct so as to prevent possible errors later on in the execution of the AppBuilder rule. After the call to the interface has been thoroughly tested, the name and length checking of the input and output views is no longer necessary. At this point, you may wish to use the Fast Path option specified in the subfunction code to reduce the CPU overhead. This subfunction can be used in conjunction with any of the function codes.
Using the Fast Path Option

The Fast Path option can improve the performance of the AppBuilder Batch Rule execution in three ways: by skipping the read of the VIEWDEF file, by not freeing the storage that it has allocated, and by not releasing programs that it has loaded. The HPBCAPI program must allocate storage for internal use. This storage will not be freed under the Fast Path option, so it can be reused on repeated calls to HPBCAPI. The Fast Path option loads all of the AppBuilder rules that are dynamically called and does not release them, thus improving performance as these programs do not have to be loaded again. However, the batch job may eventually run out of storage if too many different AppBuilder rules are called. The Fast Path option keeps pointers to allocated storage and loaded programs in the AppBuilder User Commarea in areas defined as FILLER, and in the area where the terminal and transaction information is defined. Therefore, the application program must either use the same commarea on repeated calls or copy the entire commarea to another area before making any changes. The Fast Path with Checking Views option provides the same performance enhancements of the Fast Path option, but also checks the AppBuilder rule's input and output view names and lengths before attempting to execute the AppBuilder rule. This option also leaves the VIEWDEF file open until a Clean Up call is issued to prevent the overhead of opening and closing the VIEWDEF file on each iteration. Note
Since the Clean Up processing for the Fast Path and the Fast Path with Checking Views options are different, it is important to pass the proper subfunction code to HPBCAPI on a Clean Up function call.
Using the Clean Up Function

The Clean Up function code causes all previously allocated programs and storage to be released. It must be called with the same subfunction code (Fast Path or Fast Path with Checking of Views) that was used in the previous call to HPBCAPI . Obviously, a single Fast Path call to HPBCAPI followed by a Clean Up call will have no performance benefit, but many Fast Path calls to HPBCAPI for the same AppBuilder rule show a significant performance improvement. It is recommended, but not mandatory, to call
15-2
Batch API for PLI and COBOL II
User Commarea
HPBCAPI with the Clean Up function between calls to execute different AppBuilder rules to avoid running out of storage.
Using the Default Views Function

The AppBuilder batch user application interface program has been made easier to use with the Default Views subfunction. If the Default Views option is specified in the subfunction code then the interface program creates and puts default initial values (for example, SPACES for all character fields, LOWVALUES for all integer fields, ZEROS for all decimal fields, etc.) into all of the input and output fields. This option increases CPU overhead because of the need to obtain the view structure information and allocate and initialize the views. This subfunction can be used in conjunction with any of the function codes.
User Commarea
The application program must copy in the HCUUCOM copybook from your AppBuilder COBOL copybook library. All fields in this copybook must be filled in unless otherwise indicated. The copybook contains the following fields: RULE-NAME IV-NAME IV-PTR/ADDRESS IV-FLENGTH HPS-USER-PARM-EYECATCHER HPS-USER-PARM-FUNC HPS-USER-PARM-SUBFUNC HPS-USER-PARM-RET-CODE HPS-USER-PARM-USE-TERM HPS-USER-PARM-USE-TRAN HPS-USER-PARM-RET-TERM HPS-USER-PARM-RET-TRAN HPS-USER-PARM-ERR-MSG
RULE-NAME
Each AppBuilder rule has two identifiers, an 8-character rule System ID and a 30-character rule name. You must provide the 8-character System ID in this field.
15-3
User Commarea
IV-NAME
Each AppBuilder View has two identifiers, an 8-character View System ID and a 30-character View name. You must provide the 8-character Input View System ID in this field. If there is no Input View associated with this rule, this field must contain blanks, otherwise, the passed System ID must match the input view System ID associated with the specified AppBuilder rule.
IV-PTR/ADDRESS
Specifies the pointer to the Input View data. If there is no input view, this field must contain low-values.
IV-FLENGTH
Specifies the length of the Input View. If there is no input view, this field must contain low values.
OV-NAME
Each AppBuilder View has two identifiers, an 8-character View System ID and a 30-character View Name. You must provide the 8-character Output View System ID in this field. If there is no Output View associated with this rule, this field must contain blanks, otherwise, the passed System ID must match the output view associated with the specified AppBuilder rule.
OV-PTR/ADDRESS
Specifies a pointer to the Output View data. If there is no output view, this field must contain low values.
OV-FLENGTH
Specifies the length of the Output View. If there is no output view, this field must contain low values.
HPS-USER-PARM-EYECATCHER
Reserved for internal use. This field is initialized by the copybook HCUUCOI.
HPS-USER-PARM-FUNC
Specifies the method by which you wish the AppBuilder rule to be initiated. If AppBuilder rule initiation via a host LINK or via a static link is desired, select the HPS-USER-PARM-FUNC-LINK option. If AppBuilder rule initiation via COBOL dynamic call is desired, select the HPS-USER-PARM-FUNCCOBDYN option. Select the HPS-USER-PARM-FUNC-CLEANUP option to release resources which are still held due to the use of previous calls using the HPS-USER-PARM-SUBFUNC-FASTP or HPS-USERPARM-SUBFUNC-FASTPCV subfunction calls.
15-4
User Commarea
HPS-USER-PARM-SUBFUNC
Specifies any of the desired optional subfunctions. If none of the optional subfunctions are desired, then select the HPS-USER-PARM-SUBFUNC-NORMAL option. If the Fast Path feature is desired, select the HPS-USER-PARM-SUBFUNC-FASTP option. Fast Path processing performs no validation of the input view and the output view data structures. This option can be used in a production environment to reduce the execution path length. Select the HPS-USER-PARM-SUBFUNC-FASTPCV option for the performance enhancements of the Fast Path feature, but still check the input and output view data structures. If the Default Views feature is desired, select the HPS-USER-PARM-SUBFUNC-DEFVIEW option.
HPS-USER-PARM-RET-CODE
This field contains a zero response code on the successful initiation of the rule. A non-zero return code is returned if the parameter list passed is invalid. Look at the field HPS-USER-PARM-ERR-MSG for the error message number.
HPS-USER-PARM-USE-TERM
This field is not used in the AppBuilder batch interface. Do not write to this area between HBPCAPI calls if Fast Path or Fast Path with checking views is requested.
HPS-USER-PARM-USE-TRAN
HPS-USER-PARM-RET-TERM
HPS-USER-PARM-RET-TRAN
HPS-USER-PARM-ERR-MSG
This field contains an error message number if there is an error in the parameter list. If the AppBuilder rule initiated normally, this field remains unchanged.
15-5
Static Linkage
Static Linkage
The following are sample link control cards to statically link a user application program (BATLINK) to initiate AppBuilder rule 'RBATCHA', which calls subrules 'RBATCHB', 'RBATCHC', and 'RBATCHD'. Note that the modules 'RBATCHA', 'RBATCHB', RBATCHC', and 'RBATCHD' must be taken from the NCAL library. INCLUDE OBJLIB(BATLINK) REPLACE HPSLSTUB CHANGE HPSLSTUB(RBATCHA) INCLUDE SYSLIB(HPBCAPI) INCLUDE SYSLIB(RBATCHA) INCLUDE SYSLIB(RBATCHB) INCLUDE SYSLIB(RBATCHC) INCLUDE SYSLIB(RBATCHD) INCLUDE SYSLIB(HPBSTUB) MODE AMODE(31) MODE RMODE(31) NAME BATLINK(R)
15-6
CHAPTER
16
CONFIGURING APPLICATIONS
The AppBuilder Enterprise Information Model includes application configuration objects that allow you to create environment-independent code. By specifying environment-specific attributes for these configuration objects, rather than for preparable entities such as rules, you can create preparable entities that are environment independent. For example, you can relate an environment-independent rule to multiple partitions, each with its own environment-specific attributes. When you need to specify an execution environment for a rule, you use the ACTIVATE action to select the partition with the desired environment-specific attributes. If a rule is related to an active partition, it inherits the partitions attributes. When you need to change the execution environment, you simply activate another partition. You can also override a partitions attributes by specifying the same attribute on the relationship between a partition and a preparable entity. If an attribute is specified on a partition and on the relationship between a partition and a preparable entity, the attribute on the relationship takes precedence. For information on selecting a partition, see ACTIVATE on page 5-2.
Using Configuration Objects

It is possible to develop AppBuilder applications without using configuration objects, however, using configuration objects provides substantial advantages. It allows you to: Prepare an entity for different CICS regions Prepare a rule for different DB2 subsystems Prepare AppBuilder entities for different execution environments without modifying the entities Provide alternate DB2 bind parameters (qualifier, owner, and isolation mode) for AppBuilder entities Note
To enable configuration entities for a repository version, an administrator must set the CFGWB flag to Y in the @USRENVn INI file for the version.
Configuration entities work in conjunction with AppBuilder INI files. The AppBuilder administrator must ensure that the INI file settings are consistent with environment options specified using configuration entities.
16-1
Understanding Configuration Objects and Relationships

Configuration objects include the following entities and relationships: Application Configuration Groups a number of partitions, typically belonging to a single application. An application configuration has the attributes shown in Table 16-1. Partition Relates multiple preparable entities to a single machine, database, and server. A partition holds attributes common to the preparable entities related to it. A partition has the attributes shown in Table 16-2. Machine Defines the execution environment for a partition. The attributes for a machine object are shown in Table 16-3. Note
Note: A partition must be related to a machine entity before the partition can be used to prepare the entities it encapsulates.
Database Represents a DB2 subsystem. The source file attached to a database entity defines environmental variables specific to this subsystem. A database has the attributes shown in Table 16-4. Note
A partition must be related to a database entity before the partition can be used to prepare the entities it encapsulates.
Server Represents a logical collection of rules and components that perform a specific, reusable function. A server has the attributes shown in Table 16-5. Note Cell A collection of machines with a common communications protocol. A cell has the attributes shown in Table 16-6. Note
A cell entity is not used on the mainframe host. It is reserved for future use. A partition requires a related server entity on the mainframe host for compatibility with workstation applications, but is not used on the host. The server entity is reserved for future use on the host.
Preparable Entity An entity that must be prepared to be usable in an execution environment. A partition can encapsulate multiple preparable entities so they can share preparation attributes. Preparable entities are components, files, functions, processes, reports, rules, sets, and windows. Partition Encapsulates Preparable Entity
16-2
An entity that ties preparable entities to a partition that holds the attributes common to the preparable entities. You can override an attribute specified at the partition level by specifying the same attribute in the Encapsulates relationship. Figure 16-1 shows an overview of the configuration entities and their relationships to each other.
Figure 16-1 Configuration Information Model
Setting Configuration Object Attributes

This section describes the attributes of the configuration objects: Application Configuration Partition Machine Database Server Cell Encapsulates Relationship
Application Configuration
Table 16-1 lists the attributes of an application configuration.
Table 16-1 Application Configuration Attributes Attribute Name Function Name of application configuration.
16-3
Partition
Table 16-2 lists the attributes of a partition entity.
Table 16-2 Partition Attributes Attribute Name Type Implementation name Protocol Server Link Type Server Start Type Server Cell Rank Owner Qualifier Plan Name Collection ID Isolation Mode Minimum Transaction ID Maximum Transaction ID Unit of Work Function Long name of partition. Type of server such as CICS, Batch, ONC, DCE, IMS, AppBuilder. The server executable name for a statically linked server. Dynamic linking does not use this field. The supported communication protocol for this server such as TCP, LU2, LU6.2, Named Pipes, Novell SPX, NETBIOS, UDP, or N/A. Linkage type of serverdynamic or static. Type of start-up for serverforking or autostart. The server cell rank. DB2 plan owner. DB2 qualifierused as the leading qualifier of all unqualified table references in the package or plan. DB2 plan name. DB2 collection ID associated with the plan, if DB2 packages are used. DB2 isolation modeCommitted Read, Cursor Stability, Dirty Read, or Repeatable Read. Starting transaction ID assigned to this partition. Ending transaction ID assigned to this partition. Local or remote.
Machine
Table 16-3 lists the attributes of a machine entity.
Table 16-3 Machine Attributes Attribute Name Implementation name Function Long name of machine. The CICS or IMS region name represented by the VTAM applied. Execution environment for all preparable objects that are encapsulated by the partition that encapsulates this machineCICS, MS-Windows, mainframe Batch, AIX, Sun OS, HPUX, MS-Windows/NT, OS/400, CICS/OS2, CICS/6000, System V Release 4, or IMS. The operating system release. The group to which the machine belongs.
Operating System
OS Release Machine group
Database
Table 16-4 lists the attributes of a database entity.
Table 16-4 Database Attributes Attribute Name Function Name of DB2 database.
16-4
Table 16-4 Database Attributes Attribute Implementation name DBMS Type Machine Name Database Directory Path Function DB2 subsystem name. Database typeDBM, DB2, Informix, Sybase, Oracle, DB2/2, or DB2/6000. Location for DRDA supportreserved for future use. DBRM library name.
Server
Table 16-5 lists the attributes of a server entity.
Table 16-5 Server Attributes Attribute Name Implementation name Function Name of server. Name of statically linked load module generated from the collection of rules.
Cell
Table 16-6 lists the attributes of a cell entity.
Table 16-6 Cell Attributes Attribute Name Protocol Function Name of cell Type of communication protocol for this cellTCP, LU2, LU6.2, Named Pipes, Novell SPX, Netbios, UDP, or N/A.
Encapsulates Relationship
The Encapsulates relationship between a partition and a preparable entity has many of the same attributes as the partition. If an attribute is specified both at the partition level and on the relationship between a partition and a preparable entity, the attribute on the relationship overrides the attribute on the partition.
Table 16-7 Partition Encapsulates Preparable Entity Attribute Preparation Time Implementation name Service Name Significant Time Link Type Owner ID Qualifier Plan Name Collection ID Version ID Function The last time this object was prepared. Executable name. CICS/IMS transaction name. Last time of update. Linkage type of serverdynamic or static. DB2 plan owner. DB2 qualifierused as the leading qualifier of all unqualified table references in the package or plan. DB2 plan name. DB2 collection ID associated with the plan. DB2 version ID.
16-5
Preparing for Multiple Execution Environments
Table 16-7 Partition Encapsulates Preparable Entity (Continued) Attribute Isolation Mode Function DB2 isolation modeCommitted Read, Cursor Stability, Dirty Read, or Repeatable Read.
Relating Preparable Entities to a Partition

You can use either ADDR or ASSIGNCU to relate a preparable entity (component, file, function, process, report, rule, set, or window) to a partition: Use the ADDR (add relationship) action on a partition. Select the Encapsulates relationship and specify the preparable entity it encapsulates. Alternatively, you can use the ADDR action on a preparable entity by selecting the Is-Encapsulated-By partition relationship and specifying the partition that encapsulates it. Use the ASSIGNCU action on a preparable entity by relating it to the active partition. To use ASSIGNCU, first use the ACTIVATE action on a partition. The partition remains active until you either activate a different one or log off. As with ADDR, using the ASSIGNCU action establishes an Encapsulates relationship between a partition and a preparable entity. The difference between the two methods is that the ASSIGNCU action lets you relate multiple entities to a partition with one action. As Figure 16-2 shows, the ASSIGNCU action lets you relate all the entities in the hierarchy of a preparable unit to the same partition or select from among the entities in the hierarchy.
Figure 16-2 ASSIGNCU Action
Assign partition Name . . . . . . . : DB2_ERROR_HANDLE Config. Unit . . . : HPS_CICS_CONFIG Version . . . . . : 3
Select one of the following. _ 1. Selected object only
Then Press Enter.
2. Display list of preparable objects for individual selection 3. All preparable objects in the object hierarchy

You can specify an execution environment as the implementation name of a machine entity instead of specifying an execution environment for individual preparable entities. The execution environment applies to all the entities related to the activated partition to which the machine unit is related because a machine entity is common to multiple preparable entities. By relating preparable entities to different partitions that are related to different machines, you can prepare the same entities for different execution environments without changing the attributes of the entities themselves.
16-6
As Figure 16-3 shows, you use the ACTIVATE command to select the partition whose machine you want to use. Entities belonging to a partition that are prepared while the partition is active are prepared for the execution environment specified on the partitions machine. A partition remains active until you activate a different one or exit the repository. A partition on the mainframe supports the execution environments of CICS, IMS, and mainframe Batch. Note
An AppBuilder administrator must update the AppBuilder INI files to be consistent with the activated environment. Preparing Rules for Multiple Execution Environments
Figure 16-3
1. Relate rule to multiple partitions, each with its own machine partition 1 partition Rule Rule partition 2 partition partition 3 partition Machine 1 Machine Imp_Name=CICS ImpName=CICS region Machine 2 Machine Imp_Name=IMS ImpName=CICS region region Machine 3 Machine Imp_Name=Batch; ImpName=CICS region
2. ACTIVATE a partition partition 1 partition Rule Rule partition 2 partition partition 3 partition Machine 1 Machine Imp_Name=CICS ImpName=CICS region Machine 2 Machine Imp_Name=IMS ImpName=CICS region region Machine 3 Machine Imp_Name=Batch ImpName=CICS region
3. Prepare rule partition 1 partition Rule Rule partition 2 partition partition 3 partition Machine 1 Machine Imp_Name=CICS ImpName=CICS region Machine 2 Machine Imp_Name=IMS ImpName=CICS region region Machine 3 Machine Imp_Name=Batch ImpName=CICS region
The rule is prepared for a CICS execution environment because that is the environment specified in machine 1, which is tied to partition 1the active partition when the rule is prepared.
DB2 Subsystems
You can use a different DB2 subsystem for the applications in a version of a repository by specifying the subsystem ID in the @USRENVn INI file for a version. Use the DB2SUBID_ID variable to specify the DB2 subsystem ID for the version. If you dont specify a subsystem ID for a version, AppBuilder uses the value of the DB2SUBID variable in the @HPSENVn INI file as the DB2 subsystem ID for all applications in the repository.
16-7
Preparing a Rule for Multiple DB2 Subsystems

Instead of specifying a DB2 subsystem for an AppBuilder version, you can specify a DB2 subsystem as the implementation name of a database entity. By relating a rule to multiple database entities, each with its own implementation name, you can prepare the same rule for different DB2 subsystems as Figure 164 shows. Use the ACTIVATE action to select the partition whose database you want to use. Entities belonging to a partition that are prepared while the partition is active are prepared for the DB2 subsystem specified for the partitions database. A partition remains active until you activate a different one or exit the repository. In the example, the rule is prepared for DB2 subsystem 1 because that is the subsystem specified in database 1, which is tied to partition 1the active partition when the rule is prepared.
Changing the Qualifier of DB2 Tables

You can specify at the partition level a default qualifier for all unqualified tables and views your application references. This qualifier applies to the preparation of every file, rule, and component tied to a particular partition. To change the qualifier for a group of files, rules or components, simply activate a different partition, as Figure 16-4 shows.
Figure 16-4 Changing the DB2 Qualifier
1. Relate rules to multiple partitions, each with its own qualifier partition 1 partition Qualifier=name 1 Qualifier=name partition 2 partition Qualifier=name 2 Qualifier=name
Rule Rule Rule
2. ACTIVATE a partition partition 1 partition Qualifier=name 1 Qualifier=name partition 2 partition Qualifier=name 2 Qualifier=name
Rule Rule Rule
3. Prepare rules partition 1 partition Qualifier=name 1 Qualifier=name partition 2 partition Qualifier=name 2 Qualifier=name
Rule Rule Rule
16-8
In the example that Figure 16-4 illustrates, the rules are prepared using qualifier name 1 because that is the qualifier specified in partition 1 the active partition when the rule is prepared. Note
You can also specify a qualifier on the relationship between a preparable entity such as a rule and a partition. If a qualifier is specified both on the relationship and on a partition, the one specified on the relationship takes precedence. For more information on setting qualifier precedence, see Column 7 Qualifier/Owner.
Changing the Owner of DB2 Plans and Packages

You can specify at the configuration level the owner of DB2 plans and packages. This owner applies to plans and packages for every rule and component tied to a particular partition. The owner can be any valid DB2 owner or secondary authorization ID. To change the owner for a group of rules or components, activate a different partition as Figure 16-5 shows.
Figure 16-5 Changing the DB2 Owner
1. Relate rules to multiple partitions, each with its own owner partition 1 partition Owner=name 1 Qualifier=name partition 2 partition Owner=name 2 Qualifier=name
Rule Rule Rule
2. ACTIVATE a partition partition 1 partition Owner=name 1 Qualifier=name partition 2 partition Owner=name 2 Qualifier=name
Rule Rule Rule
3. Prepare rules partition 1 partition Owner=name 1 Qualifier=name partition 2 partition Owner=name 2 Qualifier=name
Rule Rule Rule
In the example that Figure 16-5 illustrates, the rules are prepared using owner name 1 because that is the owner specified in partition 1 the active partition during preparation. Note
You can also specify an owner on the relationship between a preparable entity such as a rule and a partition. If an owner is specified both on the relationship and on a partition, the one specified on the relationship takes precedence. For more information on owner precedence, see Column 7 Qualifier/ Owner.
16-9
Using DB2 Packages and Plans
Changing the Isolation Mode for DB2

You can specify the isolation mode for DB2 queries at the configuration level. To change the isolation mode for a group of rule or components, activate a different partition as shown in Figure 16-6.
Figure 16-6 Changing the Isolation Mode
1. Relate rules and components to multiple partitions partition 1 partition Isolation mode=CS Qualifier=name partition 2 partition Isolation mode=RR Qualifier=name
Rule Rule Rule
2. ACTIVATE a partition partition 1 partition Isolation mode=CS Qualifier=name partition 2 partition Isolation mode=RR Qualifier=name
Rule Rule Rule
3. Prepare rules partition 1 partition Isolation mode=CS Qualifier=name partition 2 partition Isolation mode=RR Qualifier=name
Rule Rule Rule
In the example that Figure 16-6 illustrates, the entities are prepared using isolation mode of cursor stability (CS) because that is what is specified in partition 1 the active partition. Note
You can also specify the isolation mode on the relationship between a preparable entity and a partition. If an isolation mode is specified both on the relationship and on a partition, the one specified on the relationship takes precedence.

AppBuilder offers great flexibility in the use of DB2. It allows users to: Choose to bind plans with either DBRMs or with packages Use one DB2 plan for all binds Use multiple plans Perform binds using different table qualifiers, owners, collection IDs, and other values for each project, version, repository, or partition The AppBuilder administrator determines which DB2 choices are made within a repository or repository version by setting variables in AppBuilder INI files and by setting the attributes of partitions.
16-10
It is important that an administrator consider the external system requirements prior to configuring AppBuilder. The selection of DB2 plans and packages must be carefully chosen with respect to IMS and CICS because each environment presents different system implications. In addition, the use of pool exits in a CICS/DB2 environment must be considered. AppBuilder provides the flexibility to meet the various needs of system configurations once the users needs have been determined. Table 16-8 shows the results of rule and component preparation given the settings of the same INI variables, and assuming that partitions are being used. Table 16-13 shows the results of rule and component preparation given the settings of several INI file variables, and assuming that partitions are not being used.
Binding with Packages and DBRMs

It is the AppBuilder administrators responsibility to determine whether DB2 plan binds are done using packages or DBRMs. The standards effective at a particular site may dictate which choice is made. Note
Whichever choice is made must be applied uniformly within a repository version. AppBuilder does not support binding plans with both packages and DBRMs within a single repository version.
Binding with DBRMs

If the appropriate INI variable is set (PCKG=N), AppBuilder generates a DBRM whenever you prepare a rule or component that uses DB2. In addition, during rule preparation AppBuilder generates a plan for every rule that uses DB2, or has a rule or component in its hierarchy that uses DB2. In order to bind the plan, AppBuilder traverses the rules hierarchy and includes in the bind member list all rules and components that use DB2. Note
Because the DBRM of each child rule and component is bound into the plan of each higher level rule, you must rebind each higher level rule when the DBRM of one of its children changes. For more information, see Rebinding a Rule on page 5-29.
Binding with Packages

If you use DB2 packages (PCKG=P or PCKG=V), you can use either an explicit packing list (PKLIST=E) or a packing list using wildcards (PKLIST=W). Use wildcards in a development environment because of the flexibility they offer. However, you might consider using explicit packages in a production environment because of the security benefits they offer. Using Explicit Packages If explicit packages are used, each AppBuilder rule has a plan. During rule preparation, AppBuilder generates a plan and performs a package bind for each rule or component in the rules hierarchy that uses DB2. Note
If a new child rule that uses DB2 is added to a rules hierarchy, you must rebind the plan of each higher level rule.
16-11
Using Wildcards Using DB2 packages with a wildcard packing list makes changing applications easier because you can add, delete, and modify packages in the collection of a plan without rebinding the plan. In addition, only one plan bind is required for a repository version. Binding the plan must be done by a repository administrator using the BINDPLAN action on a Repository entity in an ADM project.
Setting INI Variables for DB2 Qualifier/Owner

The DB2 administrator can set the INI variables to define the default DB2 qualifier and owner for: Versions Projects Repositories
Versions
An administrator can establish an INI file for each version of a repository. The INI file for a particular version of a repository resides in a TSO library for that repository and is named @USRENVn, where n is the version number (for example, @USRENV2). Within each @USRENVn file, the variable QUALIFIER_ID specifies the default qualifier, and OWNER_ID the DB2 owner.
Projects
Within the INI file for a version, you can establish a variable for the owner and default qualifier for each project in that version. Form the variable for the owner as follows: project name + version number + OWNER (for example, DEV1OWNER) Form the variable for the default qualifier as follows: project name + version number + QUALIFIER (for example, DEV1QUALIFER)
Repositories
The variable DB2OWNR in the @HPSENVn INI file determines the DB2 owner and indirectly the default qualifier for an entire repository. This variable is set when a repository is installed. Initially, the default qualifier is the same as DB2OWNR. An administrator can modify DB2OWNR at any time. DB2OWNR determines the owner and qualifier for an entire repository unless overridden by the INI variable for a particular version or project in a version of that repository.
16-12
INI Variables and DB2 Binds using Partitions

Heading explanations for table columns in Table 16-8 and valid values for INI variables are explained in: Column 1 PCKG Column 2 PKLIST Column 3 PLAN_NAME_ID Column 4 ONE_CICS_TRX Column 5 Results Column 6 Collection ID Column 7 Qualifier/Owner Column 8 - Plan Name Column 9 Transaction ID
Table 16-8 INI Variables and DB2 Binds using Partitions 1
PCKG
2
PKLIST
3
PLAN_ NAME_ ID
4
ONE_ CICS_ TRX
5
Results
6
Collection ID
7
Qualifier/ Owner
8
Plan Name
9
Transaction ID
1 2 3 4
N P P
N/A E W
N/A N/A required
N/A N/A version default
Bind plan unsupported Bind package Bind package Bind package, Bind plan Bind package, Bind plan Bind package Bind package
N/A
by order of precedence
generated by AppBuilder
generated by AppBuilder
by order of precedence by order of precedence version default version default version default version default
by order of precedence by order of precedence version defaults version defaults version defaults version defaults
version default version default generated by AppBuilder generated by AppBuilder version default version default
version default generated by AppBuilder version default generated by AppBuilder version default generated by AppBuilder
required
blank
ignored
version default
6 7 8
ignored
blank
required
version default
required
blank
Column 1 PCKG
PCKG is a variable in the @USRENVn INI file. Its valid values are: N P V Use DBRMs Use packages, and determine the collection ID, qualifier, and owner by order of precedence (see Column 5 Results and Column 7 Qualifier/Owner). Use packages, and use the version default for the collection ID (see Column 5 Results), and use version defaults for the qualifier and owner (see Column 7 Qualifier/Owner).
16-13
Column 2 PKLIST
PKLIST is a variable in the @USRENVn INI file. Its valid values are: E W Use explicit names in specifying package names. Use wildcards (*) for the package name in the DB2 bind PKLIST parameter.
Column 3 PLAN_NAME_ID
PLAN_NAME_ID is a variable in the @USRENVn INI file. required If you specify PCKG=P or PCKG=V, and PKLIST=W (use wildcards), you must specify a plan name for the variable PLAN_NAME_ID. AppBuilder will use this plan name for all package binds within that repository version. If you specify PCKG=V and PKLIST=E (use explicit names), AppBuilder ignores whatever value you might specify for the variable DB2_PLAN_NAME_ID. AppBuilder generates a plan name during rule preparation.
ignored
Column 4 ONE_CICS_TRX
ONE_CICS_TRX is a variable in the INI file used by the CICS region (the name of the INI file is specified as the value of the CICSREG variable in the @USRENVn INI file). version default If PCKG=P or PCKG=V, then if you specify a value for the variable ONE_CICS_TRX, AppBuilder uses this value in rule prepare for each rules CICS transaction ID. If you dont specify a value for the variable ONE_CICS_TRX, AppBuilder generates the CICS transaction ID. See the Enterprise Administration Guide for more information on how AppBuilder generates CICS transaction IDs.
blank
Column 5 Results
AppBuilder actions and results during rule and component preparation depend upon the setting of several INI variables. Bind plan Bind package If PCKG=N (use DBRMs, not packages), AppBuilder binds a plan when you prepare a rule that uses DB2. If you use packages with a wildcard for the package name (PKLIST=W), AppBuilder binds the package to a previously bound plan when you prepare a rule or component that uses DB2. The plan must have been bound previously using the BINDPLAN action. See the Enterprise Administration Guide for information on using the BINDPLAN action. If you use packages with explicit names (PKLIST=E), AppBuilder first binds packages to a collection when you prepare a rule or component, and then binds a plan in the case of rule prepare.
Bind package, Bind plan
16-14
Column 6 Collection ID
You can specify a collection ID on the relationship between a partition and a preparable entity, on a partition itself, and for version level. AppBuilder determines the default collection ID according to the order of precedence outlined in Table 16-9.
Table 16-9 Collection ID Order of Precedence Collection ID Order of Precedence 1. partition encapsulates Rule or Component You can use the Collection ID attribute on the relationship between a partition and a rule or component to specify the collection ID to be used during package binds. 2. partition AppBuilder next looks for the Collection ID attribute of the active partition to which a rule or component is related. 3. Version If you dont specify a collection ID on a partition relationship or a partition, you must specify one for a version. Use the DB2.COLLECTION_ID variable in the @USRENVn INI file to specify a default collection ID for each version of a repository. For example: DB2.COLLECTION_ID = PAYCOLL If PCKG=V (in the @USRENVn INI file), AppBuilder uses the collection ID you specify for a version. You must use the DB2.COLLECTION_ID variable in the @USRENVn INI file to specify a collection ID for each version of a repository. For example: DB2.COLLECTION_ID = PAYCOLL
(PCKG=P)
version default (PCKG=V)
Column 7 Qualifier/Owner
Qualifier/Owner refers to the DB2 qualifier and DB2 plan owner. You can specify a qualifier and owner on the relationship between a partition and a preparable entity, on a partition itself, for a version, and for a repository.
Table 16-10 Determining Qualifier/Owner Collection ID Order of Precedence AppBuilder determines the default plan and/or package owner and DB2 qualifier according to the following order of precedence: 1. partition encapsulates Preparable entity You can use the QUALIFIER and OWNER attributes of the active partition and a preparable entity to specify a qualifier and/or owner. 2. partition AppBuilder next looks for the QUALIFIER and OWNER attributes of the active partition to which a preparable entity is related. 3. File qualifier (for file entity only) If you specify a files implementation name in the form qualifier.name, AppBuilder uses the qualifier. 4. Version If you dont specify a default qualifier or owner for a project, AppBuilder looks for the default qualifier and owner you specify for a version. Use the @USRENVnINI file to specify a default qualifier and default owner for each version of a repository. Specify a default qualifier using the variable DB2.QUALIFIER_ID. For example: DB@>QUALIFIER_ID = PAYROLL Specify a default owner using the variable DB2.OWNER_ID For example: DB2.OWNER_ID = SS0100 5. Repository The variable DB2.DB2OWNR in the @HPSENVnINI file determines the DB2 plan or package owner if you dont specify one at any of the previous precedence levels. The value of DB2.DB2OWNR is also the default qualifier if none is specified at any of the previous precedence levels.
(PCKG=P or PCKG=N)
16-15
Table 16-10 Determining Qualifier/Owner Collection ID Order of Precedence If PCKG=V in the @USRENVnINI file, you must specify a default qualifier and owner for a version. AppBuilder determines the default qualifier and owner according to the following order of precedence: 1. File qualifier (for file entity only) If you specify a files implementation name in the form qualifier.name, AppBuilder uses the qualifier. 2. Version Use the @USRENVnINI file to specify a qualifier and owner for each version of a repository. Specify a qualifier using the variable DB2.QUALIFIER_ID. For example: DB2.QUALIFIER_ID = PAYROLL Specify an owner using the variable DB2.OWNER_ID. For example: DB2.OWNER_ID = SS0100
version defaults (PCKG=V)
Column 8 - Plan Name

The DB2 plan name can either be generated by AppBuilder or specified using an INI variable. generated by AppBuilder AppBuilder generates a plan name during rule preparation. version default The name is the one specified in the PLAN_NAME_ID variable in the @USRENVn INI file for the version.
Column 9 Transaction ID
The CICS transaction ID can either be generated by AppBuilder or specified as the value of an INI variable. generated by AppBuilder If you dont specify a value for the variable ONE_CICS_TRX, then AppBuilder generates the CICS transaction ID. version default The transaction ID is the one you specify in the ONE_CICS_TRX variable in the INI file used by the CICS region (the name of the INI file is specified as the value of the CICSREG variable in the @USRENVn INI file)
Examples of DB2 INI Settings using Partitions Examples of each of the DB2 INI cases are described in Table 16-8. Each of the examples assumes the hierarchy shown in Figure 16-7.
Figure 16-7 Sample Hierarchy
16-16
Row 1 Dont Use Packages, Use DBRMs

This example describes row 1 of Table 16-8 with settings as follows:
Table 16-11 DBRM Locations and Settings Location @USRENVn INI file Encapsulates relationship between a partition and a preparable entity Setting PCKG=N QUALIFIER=DEVQUAL OWNER=DEVOWNER
Note
AppBuilder binds a plan using a plan name that it generates.
Table 16-12 Actions and Results Action Result Bind Plan(PlanA) Member(RuleB, RuleC, CompA) Owner(DEVOWNER) Qualifier(DEVQUAL) Bind Plan(PlanB) Member(RuleB, RuleC, CompA) Owner(DEVOWNER) Qualifier(DEVQUAL) Bind Plan(PlanC) Member(RuleC, CompA) Owner(DEVOWNER) Qualifier(DEVQUAL)
PR on RuleA
PR on RuleB
PR on CompA
Row 3 Use Packages with Wildcards and Configuration Overrides

This example describes row 3 of Table 16-8. This case is exactly the same as row 4, with the exception that in this case a version default transaction ID is specified using the variable ONE_CICS_TRX. When you specify a transaction ID with this variable, AppBuilder uses it during all rule prepares rather than generating a transaction ID.
Row 4 Use Packages with Wildcards and Configuration Overrides

This example describes row 4 of Table 16-8, with settings as follows:
Location @USRENVn INI file Setting PCKG=P PKLIST=W QUALIFIER=DEVQUAL OWNER=DEVOWNER COLLECTION=DEVCOLL
Encapsulates relationship between a partition and a preparable entity
Note
If you use packages with a wildcard for the package name (PKLIST=W), AppBuilder binds the package to a previously-bound plan when you prepare a rule or component. The plan must have been bound previously using the BINDPLAN action. See the Enterprise Administration Guide for information on using the BINDPLAN action.
16-17
Action PR on RuleA
Result No bind Bind Package(DEVCOLL) Member(RuleB) Owner(DEVOWNER) Qualifier(DEVQUAL) Bind Package(DEVCOLL) Member(CompA) Owner(DEVOWNER) Qualifier(DEVQUAL)
PR on RuleB
PR on CompA
Row 5 Use Packages with Explicit Names

This example describes row 5 of Table 16-8. This case is exactly the same as row 6, with the exception that in this case a version default transaction ID is specified with the variable ONE_CICS_TRX. When you specify a transaction ID with this variable, AppBuilder uses it during all rule prepares rather than generating a transaction ID.

This example describes row 6 of Table 16-8, with settings in the @USRENVn INI file as follows:
PCKG=V PKLIST=E OWNER_ID=VEROWNER QUALIFIER_ID=VERQUAL COLLECTION_ID=VERCOLL
Note
If you use packages with explicit names (PKLIST=E), AppBuilder first binds packages to a collection when you prepare a rule or component, and then binds a plan in the case of rule prepare. AppBuilder generates the plan name. Result Bind Plan(PLANA) PKLIST(VERCOLL.RuleB, VERCOLL.RuleC, VERCOLL.CompA) Owner(VEROWNER) Qualifier(VERQUAL) Bind Package(VERCOLL) Member(RuleB) Owner(VEROWNER) Qualifier(VERQUAL) Bind Plan (PLANB) PKLIST(VERCOLL.RuleB, VERCOLL.RuleC, VERCOLL.CompA) Owner(VEROWNER) Qualifier(VERQUAL) Bind Package(VERCOLL) Member(CompA) Owner(VEROWNER) Qualifier(VERQUAL)
Action
PR on RuleA
PR on RuleB
PR on CompA
16-18
Row 7 Use Packages with Wildcards


This example describes row 8 of Table 16-8, with settings in the @USRENVn INI file as follows:
PCKG=V PKLIST=W OWNER_ID=VEROWNER QUALIFIER_ID=VERQUAL COLLECTION_ID=VERCOLL
Note
If you use packages with a wildcard for the package name (PKLIST=W), AppBuilder binds the package to a previously-bound plan when you prepare a rule or component. The plan must have been bound previously using the BINDPLAN action. See the Enterprise Administration Guide for information on using the BINDPLAN action.
Action PR on RuleA
Result No bind Bind Package(VERCOLL) Member(RuleB) Owner(VEROWNER) Qualifier(VERQUAL) Bind Package(VERCOLL) Member(CompA) Owner(VEROWNER) Qualifier(VERQUAL)
PR on RuleB
PR on CompA
INI Variables and DB2 Binds without Partitions

Table 16-13 shows the results of rule preparation given the settings of several INI file variables assuming that partitions are not being used. The entries in the cells are explained in the text following the table.
Table 16-13 INI Variables and DB2 Bind (non-partitioned)
1 PCKG 2 PKLIST N/A E W W 3 PLAN_NAME_ID N/A N/A required required 4 ONE_ CICS_ TRX N/A N/A version default blank 5 Results 6 Collection ID 7 Qualifier/ Owner by order of precedence 8 Plan Name generated by AppBuilder 9 Transaction ID generated by AppBuilder
1 N 2 P 3 P 4 P 5 V
Bind plan N/A unsupported Bind package Bind package
by order of by order of precedence precedence by order of by order of precedence precedence version defaults
version default version default generated by AppBuilder
version default generated by AppBuilder version default
ignored
version default
Bind version package, default Bind plan
16-19
Table 16-13 INI Variables and DB2 Bind (non-partitioned) (Continued)

1 PCKG 2 PKLIST E 3 PLAN_NAME_ID ignored 4 ONE_ CICS_ TRX blank 5 Results 6 Collection ID 7 Qualifier/ Owner version defaults version defaults version defaults 8 Plan Name generated by AppBuilder version default version default 9 Transaction ID generated by AppBuilder version default generated by AppBuilder
6 V 7 V 8 V
Bind version package, default Bind plan Bind package Bind package version default version default
W W
required required
version default blank
Column 1 PCKG
PCKG is a variable in the @USRENVn INI file. Its valid values are:
N P
Use DBRMs Use packages, and determine the collection ID, qualifier, and owner by order of precedence (see Column 1 PCKG, and Column 7 Qualifier/Owner). Use packages and the version default for the collection ID (see Column 5 Results). Use version defaults for the qualifier and owner (see Column 7 Qualifier/Owner).
Column 2 PKLIST
PKLIST is a variable in the @USRENVn INI file. Its valid values are: E W Use explicit names in specifying package names. Use wildcards (*) for the package name in the DB2 bind PKLIST parameter.
Column 3 PLAN_NAME_ID
PLAN_NAME_ID is a variable in the @USRENVn INI file. required If you specify PCKG=P or PCKG=V, and PKLIST=W (use wildcards), then you must specify a plan name for the variable PLAN_NAME_ID. AppBuilder will use this plan name for all package binds within that repository version. If you specify PCKG=V and PKLIST=E (use explicit names), then AppBuilder ignores whatever value you might specify for the variable DB2_PLAN_NAME_ID. AppBuilder generates a plan name during rule preparation.
ignored
16-20
Column 4 ONE_CICS_TRX
ONE_CICS_TRX is a variable in the INI file used by the CICS region (the name of the INI file is specified as the value of the CICSREG variable in the @USRENVn INI file). version default If PCKG=P or PCKG=V, then if you specify a value for the variable ONE_CICS_TRX, AppBuilder uses this value in rule prepare for each rules CICS transaction ID. If you dont specify a value for the variable ONE_CICS_TRX, then AppBuilder generates the CICS transaction ID.
blank
Column 5 Results
AppBuilder results during rule and component preparation depends upon the setting of several INI variables. Bind plan Bind package If PCKG=N (use DBRMs, not packages), AppBuilder binds a plan when you prepare a rule that uses DB2. If you use packages with a wildcard for the package name (PKLIST=W), AppBuilder binds the package to a previously-bound plan when you prepare a rule or component that uses DB2. The plan must have been bound previously using the BINDPLAN action. If you use packages with explicit names (PKLIST=E), AppBuilder first binds packages to a collection when you prepare a rule or component, and then binds a plan in the case of rule prepare.
Bind package, Bind plan
Column 6 Collection ID
You can specify a collection ID at both a project level and a version level. by order of precedence (PCKG=P) 1. Project You can use a variable in the @USRENVn INI file to specify a default collection ID for each project in each version of a repository. Specify a default collection ID by concatenating the project name, version number, and the word COLLECTION. For example. if project=DEV and version=1: DEV1COLLECTION = PAYCOLL 2. Version If you dont specify a collection ID for a project, you must specify one for a version. Use the DB2.COLLECTION_ID variable in the @USRENVn INI file to specify a default collection ID for each version of a repository. For example: DB2.COLLECTION_ID = PAYCOLL AppBuilder determines the default collection ID according to the following order of precedence:
16-21
version default (PCKG=V)
If PCKG=V (in the @USRENVn INI file), AppBuilder uses the collection ID you specify for a version.You must use the DB2.COLLECTION_ID variable in the @USRENVn INI file to specify a collection ID for each version of a repository. For example: DB2.COLLECTION_ID = PAYCOLL
Column 7 Qualifier/Owner
Qualifier/Owner stands for the DB2 qualifier and DB2 plan owner. You can specify a qualifier and owner at a project, version, and repository level. by order of precedence (PCKG=P or PCKG=N) AppBuilder determines the default plan owner and DB2 qualifier according to the following order of precedence: 1. File qualifier (for file entity only) If you specify a files implementation name in the form qualifier.name, AppBuilder uses the qualifier as the default qualifier. 2. Project You can use the @USRENVn INI file to specify a default qualifier and/or owner for each project in each version of a repository. Specify a default qualifier by concatenating the project name, version number, and the word QUALIFIER. For example, if project=DEV and version=1: DEV1QUALIFIER = PAYROLL Specify an owner by concatenating the project name, version number, and the word OWNER. For example, if project=DEV and version=1: DEV1OWNER = SS0100 3. Version If you dont specify a default qualifier or owner for a project, AppBuilder looks for the default qualifier and owner you specify for a version. Use the @USRENVn INI file to specify a default qualifier and owner for each version of a repository. Specify a default qualifier using the variable DB2.QUALIFIER_ID. For example: DB2.QUALIFIER_ID = PAYROLL Specify an owner using the variable DB2.OWNER_ID. For example: DB2.OWNER_ID = SS0100 4. Repository The variable DB2.DB2OWNR in the @HPSENVn INI file determines the DB2 plan or package owner if you dont specify one at either the project level or version level. The value of DB2OWNR is also the default qualifier if none is specified at the project or version level.
16-22
Column 8 Plan Name

You can either specify a DB2 plan name using an INI variable or allow AppBuilder to generate a plan name. generated by AppBuilder AppBuilder generates a plan name during rule preparation. version default The name is the one specified in the PLAN_NAME_ID variable in the @USRENVn INI file for the version.
Column 9 Transaction ID
The CICS transaction ID can either be generated by AppBuilder or specified as the value of an INI variable. generated by AppBuilder If you dont specify a value for the variable ONE_CICS_TRX, then AppBuilder generates the CICS transaction ID. See Managing Enterprise Repositories for more information on how AppBuilder generates CICS transaction IDs. version default The transaction ID is the one you specify in the ONE_CICS_TRX variable in the INI file used by the CICS region (the name of the INI file is specified as the value of the CICSREG variable in the @USRENVn INI file).
Examples of DB2 INI Settings without Partitions

The following pages present examples of each of the cases described in Table 16-13. Each of the examples assumes the hierarchy shown in Figure 16-8.
Figure 16-8 Sample Hierarchy
Row 1 Dont Use Packages, Use DBRMs

This example describes row 1 of Table 16-13, where the relevant settings in the @USRENV1 INI file are as follows:
PCKG=N DEV1OWNER=DEVOWNER DEV1QUALIFIER=DEVQUAL
16-23
Note
Action
AppBuilder binds a plan using a plan name that it generates.
Result Bind Plan(PlanA) Member(RuleB, RuleC, CompA) Owner(DEVOWNER) Qualifier(DEVQUAL) Bind Plan(PlanB) Member(RuleB, RuleC, CompA) Owner(DEVOWNER) Qualifier(DEVQUAL) Bind Plan(PlanC) Member(RuleC, CompA) Owner(DEVOWNER) Qualifier(DEVQUAL)
PR on RuleA
PR on RuleB
PR on CompA
Row 3 Use Packages with Wildcards and Project-level Overrides

This example describes row 3 of Table 16-13. This case is exactly the same as row 4, with the exception that in this case a version default transaction ID is specified using the variable ONE_CICS_TRX. When you specify a transaction ID with this variable, AppBuilder uses it during all rule prepares rather than generating a transaction ID.
Row 4 Use Packages with Wildcards and Project-level Overrides

This example describes row 4 of Table 16-13, where the settings in the @USRENV1 INI file are as follows:
PCKG=P PKLIST=W DEV1OWNER=DEVOWNER DEV1QUALIFIER=DEVQUAL DEV1COLLECTION=DEVCOLL PLAN_NAME_ID=VERPLAN
Note
If you use packages with a wildcard for the package name (PKLIST=W), AppBuilder binds the package to a previously-bound plan when you prepare a rule or component. The plan must have been bound previously using the BINDPLAN action. See Managing Enterprise Repositories for information on using the BINDPLAN action.
Action PR on RuleA
Result No bind Bind Package(DEVCOLL) Member(RuleB) Owner(DEVOWNER) Qualifier(DEVQUAL) Bind Package(DEVCOLL) Member(CompA) Owner(DEVOWNER) Qualifier(DEVQUAL)
PR on RuleB
PR on CompA
16-24


PCKG=V PKLIST=E OWNER_ID=VEROWNER QUALIFIER_ID=VERQUAL COLLECTION_ID=VERCOLL
Note
If you use packages with explicit names (PKLIST=E), AppBuilder first binds packages to a collection when you prepare a rule or component, and then binds a plan in the case of rule prepare. AppBuilder generates the plan name
Action
Result Bind Plan(PLANA) PKLIST(VERCOLL.RuleB, VERCOLL.RuleC, VERCOLL.CompA) Owner(VEROWNER) Qualifier(VERQUAL) Bind Package(VERCOLL) Member(RuleB) Owner(VEROWNER) Qualifier(VERQUAL) Bind Plan(PLANB) PKLIST(VERCOLL.RuleB, VERCOLL.RuleC, VERCOLL.CompA) Owner(VEROWNER) Qualifier(VERQUAL) Bind Package(VERCOLL) Member(CompA) Owner(VEROWNER) Qualifier(VERQUAL)
PR on RuleA
PR on RuleB
PR on CompA

16-25

PCKG=V PKLIST=W OWNER_ID=VEROWNER QUALIFIER_ID=VERQUAL COLLECTION_ID=VERCOLL
Note
If you use packages with a wildcard for the package name (PKLIST=W), AppBuilder binds the package to a previously-bound plan when you prepare a rule or component. The plan must have been bound previously using the BINDPLAN action.
Action PR on RuleA
Result No bind Bind Package(VERCOLL) Member(RuleB) Owner(VEROWNER) Qualifier(VERQUAL) Bind Package(VERCOLL) Member(CompA) Owner(VEROWNER) Qualifier(VERQUAL)
PR on RuleB
PR on CompA
16-26
CHAPTER
17
Note
3270 CONVERSE
Mainframe 3270 terminals use character-based displays that support only a subset of the controls and display characteristics available in an AppBuilder graphical user interface. For that reason, two versions of Window Painter are supported on workstations in the AppBuilder environment. The workstation Window Painter creates windows that can be executed in the OS/2, Windows, or UNIX environments. The 3270 Window Painter creates windows that can be executed on mainframe 3270 terminals with the 3270 Converse product. It supports only those controls that can be represented in a character-based display and observes restrictions on color and font identical to those imposed by the 3270 terminal.
See the Generating OpenCOBOL section Rules Language Support and Constraints on page 12-9 for information on OpenCOBOL support of 3270 converse.
Executing 3270 Converse in CICS and IMS

You can execute 3270 Converse applications in CICS or IMS transaction processing environments as described in the following sections: CICS Execution Mode IMS Execution Mode Prerequisites for 3270 Window Painter Sharing Interfaces National Language Support/Multiple Language Support
CICS Execution Mode

CICS 3270 Converse applications execute in pseudoconversational mode. Refer to Chapter 7, Preparing CICS Applications for detailed information related to CICS programming and pseudoconversational mode.
17-1
Executing 3270 Converse in CICS and IMS
IMS Execution Mode

Pseudoconversational programming is termed conversational programming in IMS. Refer to Chapter 9, Preparing IMS Applications for descriptions of the items that must be preallocated by the system administrator before IMS 3270 Converse development starts. IMS 3270 Converse applications execute the same way as pseudoconversational CICS 3270 Converse applications except that the status of the conversation is held in the Scratch Pad Area rather than CICS Temporary Storage. The design considerations in Memory Management Tips apply to 3270 Converse applications written for CICS and IMS equally.
Prerequisites for 3270 Window Painter

A window entity must exist in the current repository before you can paint its corresponding panel. Any views or fields you have defined for the window are automatically made available to the 3270 Window Painter when you open the window. The fields define the windows inputs and outputs; the views are data structures for the fields and other views. If you are designing the panel before you build your application hierarchy, a window entity is all you need to start. To map data to the panel, you must eventually define a window view for the window entity. The 3270 Window Painter will not be able to link fields with repository entities if the window entity does not have a window view. Note
You may not have more than two levels of nested views under the window view for 3270 Converse windows. If you use the WINDOW_ RETCODE field to communicate with the rule that invokes the window at runtime, it must be the first entity under the window view in the window hierarchy.
Sharing Interfaces
You can adapt workstation and 3270 interfaces to the same application by creating workstation and 3270 versions of the same window entity. If youve built a workstation version of a window, use the Copy choice in the workstation Window Painter Edit menu to copy the contents of the window to the clipboard, then use the Paste choice in the 3270 Window Painter Edit menu to create a version of the window automatically converted to observe 3270 terminal device limitations. The same procedure works in the reverse direction, 3270 to workstation.
National Language Support/Multiple Language Support

Single-byte national language characters entered in 3270 Window Painter labels and help text are displayed correctly at runtime if the code page selected on the target system matches the code page selected on the development system. End users may enter single-byte national language characters in windows executing in all supported environments. Multiple language support for date, time, currency, and numeric formats is provided for edit fields and multicolumn list box columns. For usage details, refer to the Window Painter chapter in the AppBuilder Construction Workbench Guide. For code pages that do not support the pound and yen currency symbols, the symbols are displayed as L and Y, respectively. Date, time, currency, and numeric formats are stored in external tables that can be customized on request. In general, the 3270 Window Painter works the same way as the standard workstation Window Painter. For the elements common to both tools, refer to the Development Tools Reference Guide .
17-2
3270 Converse
Host Actions
Host Actions
A 3270 panel is stored in the personal repository in a file with the name of the corresponding window entity and a .PNL extension. The .PNL file describes the position, type, color, size, and so forth of every object that appears in the panel. The following repository methods support the preparation of 3270 panels on the host. Window Prepare (PR) Results (RES)
Window Prepare (PR)

Use the PR action on a window to create the run-time data that 3270 Converse uses to manage the enduser interaction with the rules application. The PR action, when applied to a window, performs the following functions: PNL Conversion Window Bind Load PNV Load Help Text Bind PNV Display PNV
PNL Conversion
The enterprise repository stores the definition of the window object in the PNL file format. The PNL conversion function of the Window Prepare action creates an intermediate format called the PNV format that describes the window object in row and column coordinates rather than pixel coordinates. Fields described by the PNV file are sorted in row-column order, with (1,1) as upper left.
Window Bind
The PNL file contains information describing how fields are displayed. It does not contain the logical description of the view-structure used to pass data between the window and the rule. This view structure information must be extracted from the enterprise repository and bound to the window. The Window Bind extracts the view structure for the Bind PNV process to use.
Load PNV
The Load PNV process converts the PNV file to a file format that can be accessed and processed more efficiently at runtime. In addition, this process extracts and loads set information from the enterprise repository set library into the run-time file. The run-time file is a keyed-sequential (KSDS) VSAM data set. The Load PNV process deletes any previous records describing the window in the VSAM KSDS file before loading new definitions.
17-3
Host Actions
Load Help Text

The Load Help Text program opens the enterprise repository help library to determine whether help text exists for the window to be prepared. If help text exists, the Load Help Text program parses the panel and field help text and loads the help text in run-time format into the VSAM file.
Bind PNV
The Bind PNV process binds the run-time window definition to the logical view description the Window Bind process extracted. It validates each field specified for the window against the fields the logical view structure defined, and adds the definitions of the fields in the view structure to the run-time window definition. Binding the window with the logical view structure at this late stage means you can redefine the window without necessarily having to change the logical view structure. For example, a numeric output field defined in the window as 10 characters long may have a view representation of short integer or decimal (9,2). You can also change the logical view structure without necessarily having to repaint the window.
Display PNV
The Display PNV process creates a text image of the window from the run-time VSAM file and stores the image in a sequential file so you can view it when examining the results of the Window Prepare. Input fields are filled with underscores and output fields with x.
Results (RES)
Use the RES method to browse the five results files the 3270 Converse Window Prepare Method creates. The first file contains the Window Bind information extracted from the enterprise repository. The second file contains information describing the attributes of every screen field the Load and Bind PNV processes created. Table 17-1 shows these attributes.
Table 17-1 Results File Field Attributes Attribute Name Field Type Position Window Size Owning View Reference File Range Picture String Screen Occur Data Type Field Length Description Field name or text literal string Text for text fields, I/O for input/output fields, and output for output only fields Position of field in row-column coordinates Window size, in rows and columns Name of view that includes the field Name of set used to validate the field Numeric range used to validate the field Picture string used to edit the field Occurrence number of the field in an occurring view Character, integer, or decimal Field length in bytes
The Display PNV process creates the third file containing a text image of the window. The text image provides a preview of the window that will be displayed on the 3270 terminal device. The function-key
17-4
3270 Converse
Hybrid Rule Execution Environments
text line does not appear in the text window image. Instead, it is displayed in the results file after the text window image. The fourth results file contains the installation results of the prepared window in the specified region. The fifth results file contains a log of error messages issued during the PNL conversion process.
Preparing Sets
Use the PR method to prepare sets. For a Lookup type set, the prepare method extracts the relevant data from the repository and creates an object module that contains all the data for a set, including all languages. The object module is then link-edited and placed into the run-time load library. The load module name is the implementation name of the set.
Rule Prepare
The Rule Prepare Method prepares rules for execution with the 3270 Converse product. The Super Prepare Method prepares all the 3270 Converse rules, sets, and windows that occur in a specific rule hierarchy. To support the execution of host 3270 Converse rules, the system generates COBOL II code for CONVERSE WINDOW and USE RULE NEST. CONVERSE WINDOW causes the 3270 Converse product to converse the specified window to the 3270 terminal. The USE RULE NEST causes the 3270 Converse product to nest the window conversed by the rule. The Rule Prepare method generates the appropriate COBOL II code for CONVERSE WINDOW and USE RULE NEST. On successful generation, Rule Prepare invokes: The COBOL II compiler to compile the generated code The host linkage editor to create a rule executable and load the rules view definitions, source data, and relationship information into the run-time VSAM files The HPSLU2B program to define and install the rule in the specified region Note
CICS and IMS rules are dynamically linked by default. Use the Rebuild (RBD) action described in Chapter 7, Preparing CICS Applications to link them by dynamic COBOL calls. You may not statically link rules that converse windows or that use rules that converse windows.

Use the PCCICS environment to specify a rule that can execute in either the workstation or CICS environment. Use the PCIMS environment to specify a rule that can execute in either the workstation or IMS environment. To use a hybrid rule in your application, constrain the application to features both the workstation and host platforms support. A PCCICS rule cannot use a system component that supports 3270 emulation. Design 3270 Converse applications that use both PCCICS rules and CICS rules, or PCIMS and IMS rules, so hybrid rules manage the end-user interface (CLIENT services), while CICS or IMS rules manage host database access (SERVER services).
17-5
HPC7 Transaction
To test a window prepared for execution with 3270 Converse, use the HPC7 transaction. To begin the transaction, enter: HPC7,WINDOW_SYSTEM_ID on a 3270 terminal logged into the test region. The HPC7 transaction displays the text portions of the window only.
HPR0 Transaction
To test a rule prepared for execution with 3270 Converse, use the HPR0 transaction, which accesses the RuleView debugger. To begin the transaction, enter: HPR0 on a 3270 terminal logged into the test region. The debugger displays rules, windows, and components in a breakpoint selection list. When you select a window as a breakpoint, your application stops before and after the converse of the selected window, at which points you can examine and modify the data in the window view. You can also use the debugger to test host system components that perform converse functions.
3270 Converse Application Execution

To execute a 3270 Converse application, enter its transaction code. If the assigned transaction code for rule RTEST is STAA, enter: STAA
Transaction Switching
3270 Converse applications are hierarchically organized. Top-level rules can initiate subordinate rules, subordinate rules can initiate yet more subordinate rules, and so on. When users complete a transaction, they are returned to the top of the process structure, where they can traverse the hierarchy for a different rule. Transaction switching lets users switch from one transaction to another without traversing process hierarchies. Instead of being returned to the top of the hierarchy, they can move laterally in the process structure. The transaction that is initiated is determined by the code that you enter for a CICS or IMS transaction in a designated transaction field on your window. Any valid transaction code can be entered. After your window has been successfully prepared, mark a field as a transaction field in the pop-up window displayed by the TS (Transaction Switch) action. Enter the TS action for your window to display a list of fields within the window. Select the transaction and data fields that will be passed to the HPUCV10 exit routine for transaction switching.
17-6
3270 Converse
The HPUCV10 exit routine manages transaction switching. It takes the transaction data passed from 3270 Converse, reformats it into a CICS transaction, and performs a CICS Start. You can modify the HPUCV10 exit routine to determine a program name from the transaction code and perform a CICS XCTL. The HPUCV10 exit routine is as follows: *ASM XOPTS(NOPROLOG NOEPILOG) TITLE 'HPS/AE USER EXITS - CONVERSE TRANSACTION SWITCH' * .$.0 022693 CONVERSE TRAN SW USER EXIT HPUCV10.ASM 0 DM 00 **-*-* * * HPSCPYR ' (C) COPYRIGHT 2002, BluePhoenix Solutions ' * * $$NAME NAME=HPUCV10 * * $$VERSION ID=3.6.0 * * $$CALL TYPE=NONE NAME=&&&&&&&& ID=3.6.0 * * PROGRAMMER = CHRIS DOE * * DATE = DECEMBER 2, 2002 * * BRIEF DESCRIPTION = CONVERSE TRANSACTION SWITCH USER EXIT * * NOTE - THE CALLER OF THIS PROGRAM IS NOT EXPECTING A RETURN OF * CONTROL, IT WILL ABEND IF CONTROL IS RETURNED. * * INPUTS = PARM 1 -> EIB * PARM 2 -> TRAN DATA * TOT_LEN, TCODE_LEN, TCODE, DATA1_LEN, DATA1, DATA2_LEN, DATA2, * ... * * OUTPUTS = NONE * * EXTERNAL ROUTINES = * * MODIFICATION HISTORY = * .SEQ RVML PI YYMMDD --- DESCRIPTION * 01 3600 DM 921202 ORIGINAL VERSION **-*-* DFHREGS DFHEISTG DATALEN DS H TCODE DS CL4 TDATA DS CL80 DFHEIEND , END OF DYNAMIC STORAGE HPUCV10 DFHEIENT L R12,DFHEICAP @ OF PASSED DATA LH R1,0(0,R12) TOTAL LENGTH LA R12,2(0,R12) REAL START OF DATA LR R10,R12 START OF DATA
17-7
3270 Converse Module
AR R10,R1 PLUS LENGTH IS END LH R1,0(0,R12) TRANCODE LENGTH CH R1,=H'4' MAX TRANCODE LENGTH OF 4 BNH LENGOK LH R1,=H'4' RESET LENGTH LENGOK DS 0H MVC TCODE,=CL4' ' INIT TO BLANK BCTR R1,0 EX R1,MOVETC **EXEC** MVC TCODE(0),2(R12) COPY THE TRANSACTION CODE AH R12,0(0,R12) MOVE ADDR TO NEXT ELEMENT AH R12,=H'2' LEN OF LENGTH LA R9,TDATA POINT TO START OF DATA DATALOOP DS 0H CR R12,R10 COMPARE TO END BNL DATAEND LH R1,0(0,R12) BCTR R1,0 EX R1,MOVETD **EXEC** MVC 0(0,R9),2(R12) COPY SOME TRAN DATA AH R9,0(0,R12) INC DATA PTR BT LENGTH JUST ADDED AH R12,0(0,R12) MOVE ADDR TO NEXT ELEMENT AH R12,=H'2' LEN OF LENGTH B DATALOOP MOVETC MVC TCODE(0),2(R12) COPY THE TRANSACTION CODE MOVETD MVC 0(0,R9),2(R12) COPY SOME TRAN DATA DATAEND DS 0H LA R1,TDATA SR R9,R1 CALC LENGTH OF DATA STH R9,DATALEN EXEC CICS START X TRANSID(TCODE) X TERMID(EIBTRMID) X FROM(TDATA) X LENGTH(DATALEN) EXEC CICS RETURN DFHEIRET END ,

The 3270 Converse module provides all base 3270 Converse functionality. You can use system components to modify the functionality dynamically. The primary function of the 3270 Converse module is to manage 3270 screen input and output for a rule conversing a window. If necessary, the 3270 Converse module communicates the end users actions to the rule by populating the WINDOW_RETCODE field with the text string associated with the action. Before passing the users input to the rule, 3270 Converse edits and validates input fields as specified by attributes defined in the repository and the window description.
17-8
3270 Converse
When a rule converses a window, the 3270 Converse module reads the VIDTEXT VSAM file to obtain the physical attributes of the window. It uses these physical attributes to construct the 3270 data stream commands that display the window on a 3270 terminal. If the rule uses the NEST option, the 3270 Converse module does not clear the screen before displaying the next window. That is, the NEST option lets you display a pop-up window over an underlying window. You can use the SET_POPUP_POSITION component, described in the System Components manual, to change the pop-up position. Pop-up windows are distinguished from the underlying window by a border of dashes (-) and bars (|). The border appears only if there is one row above and below, and three columns to the left and right of the pop-up window on the terminal screen.
Input Fields
3270 Converse edits and validates input fields when the end user presses a function key. No data is returned to the invoking rule until all input fields have been successfully edited and validated. End users save input to a 3270 application by pressing Enter. 3270 Converse highlights fields in error with reverse video red on terminals that support color and a high-intensity display on terminals that do not support color. For each field in error, it prints an error message on line 22 of the 3270 terminal, or if the message is longer than 79 characters, in a scrollable pop-up window displayed as close to the field as possible without overlaying it. Only the following 3270 Converse functions work when there are fields in error: HELP, EXIT, PROMPT, RESTORE, QUIT, and CLEAR. All other function keys and menu choices are ignored. If an invalid character string is entered in a combo box, 3270 Converse displays a scrollable pop-up list of values from which the end user can select a valid value. The combo box is case sensitive. 3270 end users can also view the list of values by pressing the PROMPT key. As noted, editable combo boxes are supported in functionally different ways on the workstation and the host.
Input Restrictions
The tabbing order of window objects is left to right, top to bottom, and cannot be changed. 3270 end users cannot tab to a protected edit field or protected combo box. End users must enter the date or time with appropriate leading zeroes. For code pages that do not support the pound and yen currency symbols, 3270 Converse displays the symbols as L and Y, respectively.
Windows Runtime Restrictions

At runtime, 3270 Converse windows behave differently from workstation windows in the following ways: Fields with a Picture edit mask containing zero suppression and dollar signs are displayed with a floating position (that is, with no space between the dollar sign and the first numeral). On the mainframe, use of the $ sign in conjunction with + or - signs is not supported.
17-9
Multicolumn List Box Scrolling

Scrolling is provided for cases in which the length of a multicolumn list box limits the number of data items that can be displayed at one time. Pressing the default F7 or F8 keys scrolls the data displayed in a multicolumn list box up or down, respectively. 3270 Converse automatically displays the default F7 key whenever it detects an upwardly scrollable list box on the screen and the default F8 key whenever it detects a downwardly scrollable list box on the screen.
Smooth Scrolling Option

Smooth scrolling is provided for cases in which the number of database records for a given view exceeds the number of occurrences defined in the view data structure, that is, in which control must be returned to the invoking rule so it can fetch the remaining records. You enable smooth scrolling by defining a virtual list box for the view with the component SET_VIRTUAL_LISTBOX_SIZE. When the end user tries to scroll beyond the first or last occurrence defined in the view data structure, 3270 Converse returns control to the invoking rule, putting the message OUT OF RANGE HPSID of view in the WINDOW_RETCODE field. The rule can then retrieve more data. If the end user tries to scroll beyond the first or last occurrence defined in the virtual list box, 3270 Converse returns control to the invoking rule, putting the message TOP HPSID of view or BOTTOM HPSID of view, respectively, in WINDOW_RETCODE. If smooth scrolling is not enabled, any attempt to scroll beyond the first or last occurrence defined in the view data structure fails, eliciting the error message TOP OF LIST or BOTTOM OF LIST, respectively.
Function Keys
You can display 24 function keys on a 3270 terminal, in two rows. End users toggle the function-key display on or off by pressing the KEYS key. Except when 3270 Converse displays the default F7 or F8 keys for a scrollable list box, only user-defined keys and their associated text strings are displayed on the 3270 terminal. The text for the function key is displayed beside the function-key specification in the 3270 window. Its HPS ID is returned to the invoking rule when the end user presses the key at runtime. 3270 end users cannot select function keys with the cursor. Default values of function keys (Table 17-2) conform as closely as possible to CUA guidelines.
Table 17-2 3270 Function Key Default Values 3270 key F1 F2 F3 F4 F7 F8 F10 F12 F15 CLEAR ENTER Name HELP KEYS EXIT PROMPT UP DOWN MENU CANCEL END CLEAR ENTER Description CUA-reserved standard HELP key CUA-recommended standard F keys switch CUA-reserved standard EXIT key CUA-recommended standard PROMPT key CUA-recommended standard UP key CUA-recommended standard DOWN key 3270 Converse MENU key CUA-reserved standard CANCEL key AppBuilder END key for existing applications AppBuilder CLEAR key CUA-reserved standard ENTER key
17-10
3270 Converse
Table 17-2 3270 Function Key Default Values (Continued) 3270 key PA1 PA2 Name QUIT RESTORE Description 3270 Converse QUIT key 3270 Converse RESTORE key
You cannot redefine the F1, CLEAR, ENTER, PA1, and PA2 keys. Multiple keys can perform the KEYS, EXIT, CLEAR, and RESTORE functions. The HELP function displays a field help panel when the cursor is on a field, a warning message when the cursor is on a text object, and a window help panel when it is anywhere else. It displays Help for Help and Prompt Box Help, respectively, when a help panel or prompt box is displayed. The KEYS function toggles the function-key display on or off. The EXIT function sets WINDOW_RETCODE to EXIT and returns control to the invoking rule, without performing edit or validation checks. You can also assign the function to a menu bar choice. When a help panel, prompt box, or message panel is displayed, pressing F3, whether redefined or not, cancels the last such object to be displayed. Subsequently pressing F3 successively pops the stack of these objects until the underlying window is uncovered. The EXIT function is not case sensitive. When the cursor is on a combo box, the PROMPT function displays a scrollable selection list of permissible values. The PROMPT function is not case sensitive. The UP and DOWN functions scroll the data displayed in a list box or the text displayed in a help panel or message panel, up or down, respectively. Control is returned to the invoking rule only when the end user attempts to scroll beyond the first or last occurrence defined in the view data structure of a list box, as described in Multicolumn List Box Scrolling. The MENU function toggles the menu bar display on and off. The CANCEL and END functions set WINDOW_RETCODE to CANCEL and END, respectively, and return control to the invoking rule, without performing edit or validation checks. The CLEAR function restores the previous screen image. If all field inputs are valid, the ENTER function sets WINDOW_RETCODE to ENTER and returns control to the invoking rule, passing the input to it. The RESTORE function restores the window view most recently passed to 3270 Converse by the invoking rule. It can be used to undo incorrect input to a window view as long as the input has not already been passed to the rule.
Error Messages for 3270 Converse

3270 Converse displays error messages for the current window on line 22 of the 3270 terminal device, or if the message is longer than 79 characters, in a scrollable pop-up window displayed as close to the field in error as possible without overlaying it. The message remains on the screen until the next window is displayed, the same window is redisplayed, or a new message is displayed. If a pop-up window is current, single-line error messages for it appear on line 22 of the terminal screen regardless of the pop-up windows size. Any screen information overlaid by the error message is restored when the window is redisplayed.
17-11
Memory Management Tips
Help for 3270 Converse

3270 Converse supports help and extended help as defined in CUA guidelines. Help is information about a field; extended help is information about a window. Help for a field is displayed in a bordered, scrollable pop-up window positioned as close to the field as possible. Extended help is displayed in a bordered, scrollable pop-up window centered on the screen. 3270 Converse can display up to 500 lines of help text data per entity (counting blank lines), and can manage up to 32K bytes of help text data for all the entities that make up a window. Because 3270 Converse displays help text in a bordered pop-up window, it can display 72 bytes of help text data per line; any more will not be visible. The border appears only if there is one row above and below and three columns to the left and right of the pop-up window on the terminal screen.
Menus
The menu bar, including the menu bar for a pop-up window, is displayed at the top of the 3270 screen in as many rows as needed; any data overlaid by the menu bar are retained. The default F10 key toggles the display on or off. The default is on. Menu-bar choices are cursor sensitive. End users select a menu-bar choice by positioning the cursor on it and pressing Enter. To choose an item in a pull-down menu list, enter its number in the input field for the list and press Enter. You cannot have a pull-down choice display another pull-down list. When the end user selects a pull-down menu item at runtime, 3270 Converse returns its HPS ID to the invoking rule. Pull-down menus are limited to 99 choices, menu bars to 38 choices or 11 lines. Display of any menu-bar choice is limited to 28 bytes. Pull-down menus are scrollable. Advantages of Menus Vs. Function Keys There are two advantages to using menus rather than function keys to invoke application functions. The first is user-friendliness: logically grouping application functions allows is more intuitive for the end user. To produce the same effect with function keys you would have to display a pop-up selection list each time the user invoked a function. The second advantage lies in the number of application functions you can define: youre not as limited by display size. The disadvantage of menus lies in their performance: implementing menu dialogs is more costly in CPU resources than implementing function-key dialogs. Some users, moreover, prefer function keys because they can select a function with a single keystroke.

As described in Understanding CICS Pseudoconversational Mode on page 7-1, 3270 Converse applications execute in what CICS calls pseudoconversational mode and IMS calls conversational mode. In either case, the application consists of a sequence of transactions, each with a single input. Its status is passed from one component transaction to the next via some storage medium. The technique typically saves memory resources and improves message throughput because the system can process other applications while it waits for the input to a previous one. It also increases processor overhead because a
17-12
3270 Converse
transaction must be started for each input in the sequence. These sections provide tips on how to minimize processor workload: Depth of Application Hierarchy View Size Rule Modularity and Reuse Database Access Windows You may also consider using into the High Performance Memory Manager (AppBuilder HPMM), an optional memory management facility designed explicitly for pseudoconversational programming. AppBuilder HPMM reduces CPU workload and instruction path length by using operating system services that support the sharing of storage and program resources between address spaces.
Depth of Application Hierarchy

3270 Converse applications are hierarchically organized. A root program module invokes subordinate program modules via CICS links or static or dynamic COBOL calls. The deeper the hierarchy, the more CPU resources needed to manage program transfers and the more memory resources needed for program code and working storage. The most expensive option for CPU use during program transfers is the CICS link or mainframe link in IMS, because of the overhead required to initialize the COBOL II Run Unit. Static and dynamic COBOL calls differ in the amount of program code storage required. A dynamic call puts only one copy of a subordinate program module in program storage, no matter how many root modules it is linked with. A static call uses as many copies of the subordinate module as there are root modules with which it is linked. Program working storage is semi-permanent or transient. You use semi-permanent working storage over the entire sequence of transactions that make up the conversation. You use and dispose of transient working storage after each component transaction ends. Use semi-permanent working storage judiciously. The type of media you use to maintain the storage and the length of time you maintain it both affect performance. The rule of thumb is the faster the access time to the storage media, the greater the cost of the storage media and the more limited the supply. Specifically, main CPU memory is faster, more expensive, and more limited in supply than disk storage. For pseudoconversational applications, the converse of a window causes the input, output, input and output, local, and window views of each rule in the application hierarchy from the point of the converse and above to be saved in semi-permanent storage. So the closer to the root of the hierarchy the converse of the window occurs, the less semi-permanent storage the application will use.
View Size
Similarly, the smaller the size and number of views in the application, the less semi-permanent storage it will need. Internally, view storage is allocated in the working storage of the generated COBOL II code. Storage for local and work views is allocated in the owning rules working storage. Storage for input, output, and input and output views passed to a rule is allocated in the calling rules working storage, unless it is a root rule, in which case it is allocated by AppBuilder system code. So the
17-13
more rules a rule uses, the more view storage is allocated in its working storage. To reduce the storage a calling rule needs, define a common view that can be shared by multiple subordinate rules. Only the storage for a single copy of the view will be allocated in the calling rules working storage. Another method of saving view storage is to pass the same view to each yet more subordinate rule in the application hierarchy, or to as many as possible. Only the address of the view is passed to the subordinate rules that reference it. Additional copies of the view are not created at each hierarchy level. You should also consider the trade-off between memory usage and response time in determining the size of an input and output view linked to a multicolumn list box. As noted in Multicolumn List Box Scrolling on page 17-10, scrolling is provided for cases in which the length of a multicolumn list box limits the number of data items that can be displayed at one time. Records that cannot be displayed in the list box are saved in semi-permanent storage. Smooth scrolling is provided for cases in which the number of database records for a given view exceeds the number of occurrences defined in the view data structure, that is, in which control must be returned to the invoking rule so it can fetch the remaining records. The larger the view, in other words, the fewer records need to be retrieved from the database and the faster, generally speaking, the users access to the records. By the same token, the larger the view, the more semi-permanent storage you will need.
Rule Modularity and Reuse

Modular rules can be reused in multiple applications that require the same functionality. Sharing program code between applications saves storage because only one copy of the program resides in memory. At the same time, it may cause unnecessary fixed initialization overhead because code is executed to perform storage initialization, program load, fetch or search, and program linkage. Additional fixed overhead is incurred with the management of modular rules. Every module must be maintained as a unique object in multiple library data sets and the AppBuilder repository. There is no definitive formula for determining the optimal way to modularize applications. Try to hedge by designing rules so they can be split into subordinate rules or combined into inclusive rules.
Database Access
To insure the integrity of the database across the multiple transactions that make up a pseudoconversational application, a rule that accesses a database should never use a rule that converses a window. The termination of a component transaction in a pseudoconversational application causes an implicit commit of database resources. So if the rule has a cursor open on a DB2 table and uses a subordinate rule that converses a window, the converse of the window causes the database transaction to first terminate and then execute an implicit commit of all active database resources. When the conversation resumes, the application restarts after the converse of the window. When the subordinate rule returns to the inclusive rule, the DB2 cursor is no longer valid.
Windows
There is a direct relationship between the number of objects in a window and the amount of semipermanent storage it needs. You use storage not only for the objects displayed in the window initially, but for objects that may only potentially be displayed, for example, combo box text, help text, picture string text, and message text.
17-14
3270 Converse
Using HPECAPI in 3270 Converse Applications
The semi-permanent storage for a windowwhether a pop-up window or an ordinary subordinate windowis freed only when control returns to a rule at a higher level in the application hierarchy. If you need to conserve semi-permanent storage, try to minimize the number of pop-up windows you use and keep rules that converse windows at the same level in the application hierarchy. A driver rule that does not converse a window, for example, can call multiple subordinate rules at the same level in the application hierarchy. Each subordinate rule converses a window. After each converse, the storage for the window is freed when control returns to the driver rule.
Using HPECAPI in 3270 Converse Applications

You can use the standard interface called HPECAPI to invoke 3270 Converse applications from non-AppBuilder applications. The interfaces are especially useful when you want to use an existing menu setup to access 3270 Converse applications. For details, see Chapter 11, Using IMS Interfaces: HPECAPI and HPUCV10
Converse Components
Converse components are third-generation language utilities that let you dynamically modify Rules Language converse functions. A list of the components supported by 3270 Converse appears in the Rules Language Reference Guide. The Notes section at the end of each component description in that manual documents any limitations with regard to the components behavior in the 3270 environment. A converse component can be used to modify a window only if the window is in the components calling hierarchy, as shown in Figure 17-1.
Figure 17-1 Converse Component Hierarchy
Deferred Converse Components Calls

3270 Converse does not allow a converse component to manipulate the display characteristics of the next window to be conversed, regardless of where it is in the calling hierarchy. The subordinate rule can use a converse component to manipulate the display characteristics of the window conversed by the parent rule only if it does not converse its own window. The information defining a window is known only to
17-15
Converse Components
the conversing rule and any subordinate rules that do not converse their own windows. This differs from the workstation run-time environment, where converse component calls can be deferred indefinitely until the process is terminated.
17-16
3270 Converse
CHAPTER
18
ADVANCED TOPICS
This section describes information you can use to design and develop enterprise applications using advanced AppBuilder features. The topics covered include: Linking Run-time Entities Run-time Communications Protocols Passing Messages using Global Eventing Defining Repository Actions
Linking Run-time Entities

AppBuilder allows linking of executable AppBuilder entities when they use and converse one another at runtime on the host. Linked entities include rules, reports, and components. The AppBuilder environment supports two forms of linkage: dynamic and static. Dynamically linked entities are loaded individually from a load library as they are needed. Statically linked entities are combined into a single load module before the application is executed. You can call all types of executable entities dynamically or statically in the batch run-time environment. In the CICS run-time environment, you cannot statically link PL/I components. Rules prepared for pseudoconversational 3270 Converse can be linked by CICS link (dynamic) and by dynamic COBOL calls. An AppBuilder application prepared on the host is dynamically linked by default. This is necessary for testing an application with the CICS and batch RuleView facilities. Note
RuleView is not supported using OpenCOBOL generation facility.
Dynamic Linking
When you employ dynamic linkage, the AppBuilder run-time system receives control and either loads or locates the entity to be called before passing control to it. This ensures that the latest version is executed. Dynamic linking has three advantages: When you change a rules code, naturally you must reprepare it. However, any rules that dynamically use that changed rule (or report or component) need not be reprepared or relinkedas long as you have not modified the changed rules views.
18-1
Linking Run-time Entities
The run-time systems interception of the dynamic link lets you go into debug mode before and after the call. This allows you to execute your application using RuleView and analyze what is happening. Parts of an application an execution does not use are not loaded into storage, saving memory. Dynamic linkage specifies that references to one module be replaced by references to another. These references are then resolved to the replacement included in the load module instead of the original reference. Calls to the run-time systems dynamic loader interface routine replace calls to the actual subentities. There is a version of this routine for each run-time environment the AppBuilder environment supports. These characteristics make dynamic linkage ideal for use in the development and testing environment. But the overhead of invoking the run-time system at each call makes it less desirable in the production environment. Note
Dynamic linking is the default for generating your applicationall you have to do is prepare your rules, reports, and components to have a dynamically linked application. You can also select the Dynamic option when performing an RBD action. See RBD on page 5-27.
Static Linking
When static linking is employed, control passes directly from one entity to another without the run-time system intervening. You can select static linking when performing an RBD (Rebuild) action. All of the rules, reports, and components of an entire statically-linked application are bound together at link-edit time and loaded together at runtime as one module. Because it avoids the run-time overhead, static linkings better performance is ideal in the production environment. Suppose that identical code is generated when a rule uses a rule, when a rule uses a component, when a rule converses a report, or when a report invokes a system component. The most important part is the COBOL CALL statement that specifies the name of the subentity as a literal. When you compile this code with the NODYNAM option, COBOL generates a direct static external reference. Unless instructed otherwise, the linkage editor then resolves the external reference by including a copy of the subentity in the load module created. This is all you have to do to statically link batch and CICS applications.
Using Control Cards to Specify Dynamic Calls

The compiled generated code can be link-edited as is, in which case all calls to subentities are resolved statically just as they were generated. Alternatively, you can include the appropriate control cards to replace references to any or all of the subentities with dynamic calls to the run-time system. The format of a control card to change links to rule RTTH100 (System ID) from static to dynamic is as follows: REPLACE RTTH100(HPSLSTUB)
Load Libraries
Executable AppBuilder entities reside in separate load libraries, one per run-time environment (one for batch, one for CICS, and one for IMS). These libraries can contain both statically and dynamically linked applications at any one time, however, there is no provision for maintaining both a static and dynamic version of an application at the same time. The same command language can run the same application, regardless of how it is linked.
18-2
Advanced Topics
Run-time Communications Protocols
NCALLIB Libraries Another set of load libraries involved in the link-edit process are the NCALLIB libraries: one for batch, one for CICS, and one for IMS. When a rule or report is prepared, a link-edit step is included in the job to create an NCAL version of it in one or both of these libraries. The NCAL parameter is passed specifying that the linkage editor should not resolve any external references found in the module. This is the version that is statically linked to its callers. Certain subentities might need to be loaded dynamically when the application is eventually run. Replace cards are generated for them. These references are resolved to HPSLSTUB when the NCAL is included in subsequent link edits. For instance, in the CICS environment, Replace cards are not needed for a static relink. For the CICS environment, references to PL/I and C components are replaced when the NCAL module is created.
Run-time Communications Protocols

During runtime, the AppBuilder environment uses LU2 and LU6.2 protocols to regulate communications between the client and server. However, due to platform and environment limitations, LU6.2 is not available in all areas of the AppBuilder environment. The client initiates all communications between any client and an enterprise host.
LU2 vs. LU6.2

The major difference between these two communications protocols in the AppBuilder environment is that LU6.2 allows multiple conversations during one session. Usually the only limitation is that the different conversations must access that same host region. These conversations are completely transparent to the user. See the following sections for more detailed information regarding these two options: Application Development using LU2 Execution Workbench using LU6.2 Software Distribution using LU2 and LU6.2
Application Development using LU2

Only LU2 is supported during application development, in part because only one conversation is required. It is not possible, for instance, to upload to the enterprise repository using one session and to refresh using another conversation. However, you can upload or refresh using one session and access the run-time environment (CICS or IMS) using a different session. This allows for easier and more efficient testing. You can also use one session to upload and use a different session to access the host repository interface on another session. Local security parameters of TopSecret, ACF2, or RACF determine whether a separate user ID is required, or whether the same user ID is allowed multiple host sessions.
18-3
Passing Messages using Global Eventing
Execution Workbench using LU6.2

The run-time environment allows multiple conversations on a single session if the terminal emulator can be configured for LU6.2 communications. The UNIX application execution workbench supports the LU6.2 communications protocols and the Windows environment supports LU2. For planning and implementing, this implies that from one UNIX communications session, several business processes (pull-down menu choices) can be selected concurrently.
Software Distribution using LU2 and LU6.2

The Software Distribution System (SDS) supports both LU2 and LU6.2. The client initiates all communications. However, only a single conversation is required as the client polls the server on a regular basis to determine whether any orders are outstanding for that workstation.

Global eventing provides a mechanism for passing messages among rules on the same or different systems. When one rule that includes an event in its hierarchy posts a message, any rule that includes the same event in its hierarchy receives the message and can process it. Execution of a CONVERSE statement without a window or report has the effect of blocking a rule until an event is received. When an event is received, the rule begins executing the statements following the CONVERSE. Warning
Global views and CONVERSE statements are not supported for OpenCOBOL.
Using global eventing requires the following processes: Posting Rule Hierarchy Posting Rule Code Receiving Rule Hierarchy Receiving Rule Code
Posting Rule Hierarchy

Follow these steps to set up the posting rule hierarchy: 1. 2. 3. Attach a physical event to the rule and name it. On the Rule triggers Event relationship, set the trigger type attribute to Explicit_Post. Attach a view to the physical event and name it. On the Physical event owns View relationship, set the view usage attribute to work view. Attach fields to the work view to hold the data you want to pass in the message.
18-4
Advanced Topics
Posting Rule Code

Map data to the work view, and use the POST EVENT statement to send the message: MAP BALANCE_HIGH OF BALANCE_QUERY_I TO BALANCE_HIGH OF ACCOUNT_INFO OF THRESHHOLD_MET MAP BALANCE_CLOSE OF BALANCE_QUERY_I TO BALANCE_CLOSE OF ACCOUNT_INFO OF THRESHHOLD_MET POST EVENT THRESHHOLD_MET
Receiving Rule Hierarchy

Figure 18-1 shows the hierarchy for the receiving rule. Follow these steps to set up the hierarchy: 1. Attach a physical event to the rule with the same name as the physical event you attached to the posting rule. On the Rule triggers Event relationship, set the trigger type attribute to Explicit_Converse. Attach a view to the rule and name it HPS_EVENT_VIEW.
Receiving Rule Hierarchy
2.
Figure 18-1
Receiving Rule Code

Use HPS_EVENT_VIEW in the receiving rule to capture the message, just as you would for an event internal to the application. Check for the event using a standard CASEOF statement. A global event has an EVENT_NAME of whatever name you gave the physical event. The other HPS_EVENT_VIEW fields are empty. In order to handle multiple global events, the CONVERSE statement should be included inside a loop. You can use any condition to terminate the loop, including another global event, as the following example illustrates. DO WHILE EVENT_NAME OF HPS_EVENT_VIEW <> APPLICATION_CLOSED CONVERSE CASEOF EVENT_NAME OF HPS_EVENT_VIEW CASE THRESHHOLD_MET statements ENDCASE ENDDO
18-5
Defining Repository Actions
Note
You can also use a CONVERSE WINDOW statement to receive global events. A rule containing a CONVERSE WINDOW statement is unblocked upon receipt of global events as well as interface and system eventsthe statements following the CONVERSE begin executing when a global event is received.

Use the following actions to define and run your own methods supplementing the actions and methods AppBuilder supplies for an enterprise repository: UEMTH and URMTH Note
In previous releases of AppBuilder, a distinction was made between methods and actions. This distinction is no longer applicablethe two terms are used interchangeably.
UEMTH and URMTH

The UEMTH (User Entity Method) and URMTH (User Relationship Method) actions provide access to user-written software to perform custom processing on any entity or relation in the Information Model. UEMTH EXEC and URMTH EXEC are REXX Execs that AppBuilder provides for you to edit. Invoke the UEMTH and URMTH actions by typing UEMTH or URMTH next to the name of an entity or relation. The following programs provide examples of the use of these methods: Scan Program Example Option List Example
Scan Program Example

To run a scan program on the source code of a component written in C to find memory allocation (malloc) calls, use the existing UEMTH EXEC, and put a call to a locally written REXX program (called SCANCOMP) in the section for user-written code. The result should look like the following (assuming SCANCOMP is in the SYSPROC or SYSEXEC concatenation): IF XENTTYP = 'COMP' THEN %SCANCOMP COMPID LANGUAG The SCANCOMP executable file code might be: ARG COMPID LANGUAGE ADDRESS ISPEXEC /* ADDRESSING FOR ISPF COMMANDS */ "VGET (COMPLIB) SHARED" /* WEALTH OF INFO IN ISPF POOLS */ IF LANGUAGE ^= 'C' THEN RETURN 99 /* OR WHATEVER OTHER INFO NECESSARY FOR WRONG LANG */ /* INVOKE YOUR SCAN PROGRAM WITH THE COMPLIB AND COMPID AS ARGS */ RETURN 0
18-6
Advanced Topics
Option List Example

Suppose you want to provide an option list for a number of user methods for components. You can invoke a separate REXX program called COMPMTH. It is easiest to call it with no parameters and have the executables it calls retrieve whatever variables they need using a VGET routine. You can see a list of available variables in the existing UEMTH EXEC. In the local REXX program, you can display a selection panel from which a user can invoke any program, executable file, or subsequent panel. You can change or replace UEMTH and URMTH executable files as you want. Save the original files because they provide a useful list of each enterprise repository objects attributes.
18-7
18-8
Advanced Topics
Index
INDEX
Symbols
% (match string) 1-19 %INCLUDE statement 4-18 + - indicator 1-10
Numerics
3270 Converse application program interfaces 17-15 CICS support 17-1 defining 3270 windows 4-2 dual workstation/3270 interfaces 17-2 error message support 17-11 function key support 17-10 help support 17-12 host preparation actions 17-3 IMS support 17-2 input field support 17-9 menu support 17-12 modify windows with components 17-15 multicolumn list box support 17-10 National Language/Multiple Language support 17-2 pop-up window support 17-9 prerequisites for Window Painter 17-2 pseudoconversational programming 17-12 transaction switching 17-7 3270 converse CICS link 18-1 linking with COBOL calls 18-1
A
ACBGEN 9-12 application control block 5-25 access authorization levels 2-3 accessing the enterprise repository 1-1 actions listing actions 1-20 ACTIONS - list actions 1-20 ACTIVATE - Activate a configuration unit 5-2 ACTIVATE - activate partition 16-6
ADDR - add relationship 16-6 ASSIGNCU - Assign configuration unit 5-2 ASSIGNCU - assign partition 16-6 BINDPKG - Bind DB2 package 5-3 BTS - Batch Terminal Simulation 5-4 CO - change ownership 4-12 DYNAMIC - Establish dynamic linkage 5-6 ENT_METHOD_STATUS 12-8 ENT_SIG_CHANGE 12-9 ENTITY - list entity types 1-18 EW - extended where-used 4-13 GD - Generate DDL 4-19, 5-6 global 1-14 K - define keywords 4-11 LISTRBD - List rebuild contents 5-9 LR - list relationships 1-20 ME - maintain entity attributes 4-10 object-specific 1-15 PR - Prepare 5-9, 5-13, 5-16, 5-20, 5-22, 5-23 PR - Prepare reports 5-14 PROJECTS - change projects 1-17 PSB - Modify PSB 5-25 PSB - modify PSB specification 9-12 RB - Rebind component plan 5-26 RDTL - rules IMS processing details 9-13 RDTL - Update IMS processing 5-31 REP - generate report 4-14 RES - Display results 5-32 RES - view results 5-36 RIN - Reinstall a component 5-33 S - define source code 4-10 SRCH - search for keywords 4-15 STATIC - static linkage 5-34 SUPERPR - Superprepare 5-34 TE - Test batch rule 5-35 TS - Transaction switch 5-35 TXE - define text for entity 4-11 UPROF - user profile 1-20 VER - Verify 5-36 window prepare 17-3 ACTIONS - list actions 1-20 ACTIVATE
activate partition 16-6 using to select partition 16-7 ACTIVATE - Activate a configuration unit 5-2 adding objects 4-13 ADDR add relationship 16-6 API, see application program interface application program interface batch 15-1 CICS 8-1 IMS 11-1 ARITH(EXTEND) compiler options for OpenCOBOL 12-7 ASSIGNCU assign partition 16-6 ASSIGNCU - Assign configuration unit 5-2 audit information 4-15 authorization level analyst 2-4 programmer 2-4 project leader 2-4 authorization levels 2-3 AUTOSAVE 4-9
B
BAL communications 6-10, 13-7 batch application JCL 14-1 to 14-3 components BAL sample 13-2 COBOL sample 13-3 PL/I sample 13-4 IMS message processing type, see BMP processing type (IMS) IMS processing type, see DL/I batch processing type (IMS) BDAM files 4-19 Bind PNV process 17-4 BINKPKG - Bind DB2 package 5-3 BMP processing type (IMS) 9-2, 9-6 BTS - Batch Terminal Simulation 5-4
C
C communications 13-9 CICS 3270 Converse applications 17-1 application program interface 8-1 components 6-4 configuring regions for OpenCOBOL 12-3 preparing for multiple regions 7-1 region 12-3
reinstalling rules 7-3 relinking rules 7-2 RuleView usage 17-6 transactions HPR0 9-16 CICS transactions HPC7 17-6 HPR0 17-6 CO - change ownership 4-12 command line using in repository 1-11 COMMAREA 6-6, 10-11, 11-2, 13-4 communications area 6-6, 10-11, 13-4 compiler 12-1 component calls in OpenCOBOL 12-10 components BAL communications 6-10, 13-7 BAL sample (batch) 13-2 C communications 13-9 COBOL sample (batch) 13-3 COBOL sample (IMS) 10-4 creating user 4-17 PL/I and COBOL communications 6-7, 13-4 PL/I considerations in IMS 10-2 PL/I linking 18-1 PL/I sample (batch) 13-4 PL/I sample (CICS) 6-4 PL/I sample (IMS) 10-9 Subroutine attribute 4-18 configuration objects application configuration 16-2 application configuration attributes 16-3 cell 16-2 cell attributes 16-5 database 16-2 database attributes 16-4 definition 16-2 machine 16-2 machine attributes 16-4 partition 16-2 partition attributes 16-4 preparable entity 16-2 relationship of configuration unit to preparable entity 16-2 server 16-2 server attributes 16-5 conversational programming 17-1 COPY statement 4-18 copybook HCUUCOI 8-1, 8-3 HCUUCOM 8-1, 8-2, 11-2, 15-1 copybooks in standard COBOL 5-22
ii
OpenCOBOL 12-5 copying entities and relationships 4-8 creating objects 4-13
D
data types CICS 12-3 IMS 12-3 DATE, TIME, and TIMESTAMP in OpenCOBOL 12-8 DB2 4-19 binding with packages and DBRMs 16-11 changing package owner 16-9 changing the isolation mode 16-10 packages 16-9, 16-10 packages and plans 16-10 rule preparation for multiple subsystems 16-8 setting INI variables 16-12 subsystems 16-7 DBRM binding with 16-11 decimals use of in OpenCOBOL 12-10 defer report for overnight execution 4-15 deleting objects 2-4, 4-13 Display PNV process 17-4 Display PNV process 17-4 DL/I batch processing type (IMS) 9-2, 9-8, 9-11 DYNAM for dynamic links in OpenCOBOL 12-7 DYNAMIC - Establish dynamic linkage 5-6 dynamic linking 5-28, 18-1
where-used 4-13 ENTITY - list entity types 1-18 Error Log (IMS) 9-16 error message support 3270 Converse 17-11 EW - extended where-used 4-13 execution environments preparing for multiple 16-6 exit routine (HPUCV10) 17-7
F
fields displaying multiple-choice options 1-9 files VSAM 4-19 with DB2 tables 4-19 function keys default values 17-10 support in 3270 Converse 17-10 using to issue commands 1-11 functions mathematical in OpenCOBOL 12-10
G
GD - Generate DDL 5-6 global eventing passing messages among rules 18-4
H
HCUUCOI 8-1, 8-3 HCUUCOM 8-1, 8-2, 11-2, 15-1 help help function key 1-12 in 3270 Converse 17-12 High Performance Memory Manager (HPMM) 17-13 host preparation for OpenCOBOL 12-5 HPBCAPI (batch) general 15-1 User Commarea 15-3 HPC7 transaction 17-6 HPECAPI (CICS) 8-7 general 8-1 link option 8-5, 8-7 start with no return option 8-8 with return option 8-8 User Commarea 8-2 to 8-5 XCTL option 8-11 to 8-12 HPECAPI (IMS) general 11-1 start and continue 11-4
E
ENT_METHOD_STATUS 12-7 ENT_SIG_CHANGE 12-7 enterprise repository actions (see actions) methods (see actions) panels (see panels) views 2-3 entities run-time linking 18-1 Entities panel 1-3 entity attributes 4-10 changing ownership 4-12 defining text 4-11 detail panel 1-8 listing types 1-18 locking authorization 3-2
Index
iii
start link 11-4 transfer control 11-5 transfer control (no input view) 11-12 transfer control with return 11-6 HPECAPI interface 17-15 HPIBM10 9-6, 9-8 HPIDL10 9-8, 9-10 HPISEC4 9-16 HPMM AppBuilder memory manager application 17-13 HPR0 transaction 9-16, 9-18, 17-6 HPRC (IMS Run Control Status) 9-14 HPSCOMM 6-6, 10-11, 13-4 HPSUCOM 6-6, 10-11, 13-4 HPS-USER-PARM-ERR-MSG 8-5, 15-5 HPS-USER-PARM-FUNC 8-4, 15-4 HPS-USER-PARM-RET-CODE 8-4, 15-5 HPS-USER-PARM-RET-TERM 8-5, 15-5 HPS-USER-PARM-RET-TRAN 8-5, 15-5 HPS-USER-PARM-SUBFUNC 8-4, 15-5 HPS-USER-PARM-USE-TERM 8-4, 15-5 HPS-USER-PARM-USE-TRAN 8-5, 15-5 HPUCV10 11-1, 11-13, 17-7
setting for versions 16-12 initialization configuring for OpenCOBOL 12-8 INIUTIL sample IMS job 12-3 input field support in 3270 Converse 17-9 Interactive Structured Programming Facility (ISPF), see ISPF isolation mode changing for DB2 16-10 ISPF Primary Options menu 1-1 profile 1-11 IV-NAME 8-2, 15-4
J
JCL, batch application 14-1 to 14-3
K
K - define keywords 4-11 keywords defining 4-11 in report 4-15 searching for 1-14, 4-15
I
IBM COBOL compiler 12-1 implementation names mapping OpenCOBOL 12-2 IMS 3270 Converse applications 17-2 BMP processing type 9-2, 9-6 components 10-2, 10-4, 10-9 configuring regions 12-3 DL/I batch processing type 9-2, 9-8, 9-11 Error Log 9-16 execution environment 9-2 logging on to a region 12-4 logoff 12-4 message processing region 12-5 MPP processing type 9-2 not supported in OpenCOBOL 9-1 preallocated names 9-2, 9-3 processing types 9-2 protocol support 12-2 Run Control 9-4 TP processing type 9-2, 9-5 verifying regions 12-4 INI variables for DB2 Binds using Partitions 16-13 for DB2 Binds without Partitions 16-19 setting for DB2 qualifier/owner 16-12 setting for projects 16-12 setting for repositories 16-12
L
levels of panels 1-13 link-edit dynamic linking 18-1 relinking CICS rules 7-2 static linking 18-2 linking in OpenCOBOL 12-7 LISTRBD - List rebuild contents 5-9 Load Help Text process 17-4 Load PNV process 17-3 LOCK method 3-2 locking accessing locked objects 3-3 changing locks 3-2 download lock 3-1 exclusive lock 3-1 placing a lock 3-2 read lock 3-1 update lock 3-1 Lookup preparing sets 5-21 LR - list relationships 1-20
iv
LU2 application development 18-3 LU2 and LU6.2 protocol comparisons 18-3 software distribution system 18-4 LU6.2 execution workbench 18-4
M
ME - maintain entity attributes 4-10 menu advantages over function keys 17-12 in 3270 Converse 17-12 messages passing among rules 18-4 methods ENT_METHOD_STATUS 12-8 ENT_SIG_CHANGE 12-9 for OpenCOBOL 12-8 methods, also see actions MLS, see Multiple Language Support 17-2 More indicator 1-10 MPP processing type (IMS) 9-2 multicolumn list box support 3270 Converse 17-10 Multiple Language Support (MLS) 17-2
date, time, and timestamp delimiters 12-8 defining options in INI file 12-8 differences between COBOL types 12-2 dynamic calls in 12-10 dynamic links 12-7 generation 12-1 host preparation 12-5 implementation names 12-2 IMS configurations 12-3 initialization file configuration 12-8 large decimals in 12-10 linking 12-7 methods 12-7, 12-8 middleware data marshaling 12-3 not supported for IMS 9-1 protocol support 12-2 Rule prepare 12-7 Rules Language support 12-9 runtime compatibility 12-2 SET prepare 12-6 static links 12-7 truncating intermediate results 12-10 VIEW and SET copybooks 12-5 VIEW prepare 12-6 overnight execution for reports 4-15
P
packages binding with 16-11 explicit 16-11 panels Entities 1-3 entity details 1-8 entity list 1-4 pop-up 1-10 relationship details 1-8 relationship list 1-6 System Options 1-2 types in enterprise repository 1-4 PCCICS environment 17-5 PCIMS environment 17-5 performance marshaling definition 12-5 PL/I component sample 6-4 STAE option 13-1 PL/I and COBOL communications 6-7, 13-4 plan (DB2) assigning plan names 7-4 determing plan name 7-4 PNL conversion function 17-3 PNV format 17-3
N
National Language Support (NLS) 17-2 NEST option 17-9 NLS, see National Language Support (NLS) NODYNAM for static links in OpenCOBOL 12-7 NOLINKAGE in OpenCOBOL 12-8 nonconversational processing type (IMS), see MPP processing type (IMS)
O
object security 2-1 online conversational processing type (IMS), see TP processing type (IMS) OpenCOBOL CICS Translator 12-8 CICS translator options 12-8 compatibility with Rules Language 12-2 compiler options 12-7 compiler requirement 12-1 component calls 12-10 configuring CICS regions 12-3 configuring middleware 12-2
Index
pop-up panels 1-10 pop-up window support in 3270 Converse 17-9 PR - Prepare 5-9 Preparing components 5-9 Preparing files 5-13 Preparing rules 5-16 Preparing sets 5-20 Preparing views 5-22 Preparing windows 5-23 PR - Prepare reports 5-14 preallocated names (IMS) 9-2, 9-3 prepare VIEW 12-6 preparing for multiple CICS regions 7-1 preparing 3270 Converse 17-3 printing reports 4-14 processing types (IMS) 9-2 profile 1-20 program specification block See PSB project definition,selecting 2-2 project type views 2-3 projects setting INI variables 16-12 PROJECTS - change projects 1-17 prompting 1-20 protocols support for runtime 18-3 PSB 9-12 PSB - Modify PSB 5-25 PSB - modify PSB specification 9-12 PSBGEN 9-12 temporary IMS file 5-25 pseudoconversational programming 17-1, 17-12 link options 18-1
relationship detail panel 1-8 list panel 1-6 listing 1-20 recursive 4-5 REP - generate report 4-14 reports 5-14 deferring 4-15 generating 4-14 overnight 4-15 printing 4-14 where-used report 4-13 repositories setting INI variables 16-12 repository accessing 1-1 navigating 1-14 viewing 1-14 RES - Display results 5-32 results truncating in OpenCOBOL 12-10 Results (RES) 17-4 Results File Field Attributes 17-4 RIN - Reinstall a component 5-33 rule relinking 5-28 Rule Prepare 3270 methods 17-5 for OpenCOBOL 12-7 Rule Selection List facility 9-16 Rules Language constraints for OpenCOBOL 12-9 support for OpenCOBOL 12-9 RuleView dynamic linking 18-1 Run Control (IMS) 9-4
Q
QSAM files 4-19 qualifier for DB2 tables 16-8
S
S - define source code 4-10 saving objects 4-9 scrolling default function key 1-12 smooth option 17-10 scrolling a list 1-4 security deleting objects 2-4 locking objects (see locking) object security 2-1 updating objects 2-3 server attributes 16-5 SET Lookup 17-5 preparation in OpenCOBOL 12-9
R
RB - Rebind component plan 5-26 RBD rebuild for open source COBOL 5-27 RBD - rebuild 7-2, 7-3 RBD - Rebuild a rule 5-27 RDTL - rules IMS processing details 9-13 RDTL - Update IMS processing 5-31 recursive relationships 4-5 reinstalling to CICS 7-3
vi
preparing with PR method 17-5 using COPY in OpenCOBOL 12-6 SET prepare 12-6 software distribution using LU2 and LU6.2 18-4 source code defining 4-10 SRCH - search for keywords 4-15 STAE option 13-1 STATIC - static linkage 5-34 static linking 18-2 standard 5-28 Subroutine attribute 4-18 SUPERPR - Superprepare 5-34 System Options panel 1-2
using COPY in OpenCOBOL 12-6 views project types 2-3 VSAM files 4-19
W
where-used report 4-13 wildcards using in DB2 packages 16-12 Window Bind process 17-3, 17-4 Window Painter 4-2 prerequisites for 3270 Converse 17-2 Window Prepare action 17-3
T
tables (DB2) changing qualifier 16-8 TE - Test batch rule 5-35 text defining for entity 4-11 TIMESTAMP function in OpenCOBOL 12-10 TP processing type (IMS) 9-2, 9-5 transaction switching 17-7 transactions HPC7 17-6 HPR0 9-16, 17-6 trexsna for IMS OpenCOBOL 12-4 TS - Transaction switch 5-35 TSO commands Retrieve 1-12 Swap 1-12 TSO commands - executing 1-11 TXE - define text for entity 4-11
U
UNLOCK method 3-2 unlocking 3-2 updating objects 2-3 UPROF - user profile 1-20 user profile 1-20
V
VER - Verify 5-36 version 1-21 VIDTEXT VSAM file 17-9 VIEW preparation in OpenCOBOL 12-9
Index
vii

App Builder Enterprise Application

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

App Builder Enterprise Application

Uploaded by

Copyright:

Available Formats

BluePhoenix AppBuilder 2.0.3.

Enterprise Application Guide

AppBuilder 2.0.3.1 Enterprise Application Guide

Using the Enterprise Repository Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Setting Enterprise Repository Security

Locking Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

AppBuilder 2.0.3.1 Enterprise Application Guide

Defining the Application Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Building Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

AppBuilder 2.0.3.1 Enterprise Application Guide

Writing CICS Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Preparing CICS Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1

Determining Transaction IDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3 Determining DB2 Plan Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4

API for CICS (HPECAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

Preparing IMS Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1

Writing IMS Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

AppBuilder 2.0.3.1 Enterprise Application Guide

Using IMS Interfaces: HPECAPI and HPUCV10 . . . . . . . . . . . . . . . . . . . 11-1

Writing Batch Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1

Sample Batch Applications

Batch DB2 Command Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1 Batch Command Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2

Batch API for PLI and COBOL II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1

AppBuilder 2.0.3.1 Enterprise Application Guide

3270 Converse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1

Advanced Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1

AppBuilder 2.0.3.1 Enterprise Application Guide

USING THE ENTERPRISE REPOSITORY INTERFACE

Accessing the Repository

ISPF/PDF Primary Option Menu

AppBuilder 2.0.3.1 Enterprise Application Guide

Accessing the Repository

ISPF/PDF Primary Option Menu

System Options Panel

Using the Enterprise Repository Interface

Accessing the Repository

System Options Panel

AppBuilder 2.0.3.1 Enterprise Application Guide

Using Enterprise Repository Panels

Using Enterprise Repository Panels

List Panels Detail Panels Pop-up Panels

Entity List Panels

Using the Enterprise Repository Interface

Using Enterprise Repository Panels

Select Entity to be Listed

Setting List Specifications

AppBuilder 2.0.3.1 Enterprise Application Guide

Using Enterprise Repository Panels

Entity List Panel for Rules

Relationship List Panels

Using the Enterprise Repository Interface

Using Enterprise Repository Panels

Relation Options Panel

AppBuilder 2.0.3.1 Enterprise Application Guide

Using Enterprise Repository Panels

Relation List Showing Multiple Relationship Types

Command ===> _______________________________________________________________

Repository: DEVRISE Entity Name: VIEWTE1

Name FIELD1A FIELD1B

________ Includes Field ________ Includes Field

________ Owned-By Rule RBATCH1 ******************************* BOTTOM OF DATA ********************************

Using the Enterprise Repository Interface

Using Enterprise Repository Panels

Detail Panel for Browsing Entities

Includes Field Includes Field

________ Owned-By Rule RBATCH1 * BOTTOM OF DATA **