Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
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
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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
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
Table of Contents
iii
10
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
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
Table of Contents
14
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1
15
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
18
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i
Table of Contents
vii
viii
CHAPTER
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.
1-1
Figure 1-1
1-2
Figure 1-2
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
Figure 1-3
Entities Panel
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).
1-4
Figure 1-4
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
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
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
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
V: 1
Project: DEV
Level: 3
Action
Relation Type
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
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
1-9
Figure 1-13
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.
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.
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.
1-13
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
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
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
1-17
Figure 1-16
Each time you quit working with the enterprise repository, your user profile remembers your current project the next time you use the repository interface.
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
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
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
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
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.
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
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
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
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)
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.
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
E Y=Download
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
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
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
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
4-2
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.
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
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
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
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
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 ===> ______________________________________________________________
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
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
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
. . . . . . : 2
Type 's' to select an option or type a space to deselect. Then press ENTER.
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
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.
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
4-17
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.
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).
4-19
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.
5-1
ACTIVATE
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 ===>
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
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
Building Applications
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
BTSOUT
===>
SYSABEND ===>
PLIDUMP
===>
SYSUDUMP ===>
SYSOUT
===>
SYSPRINT ===>
SYSLOG
===>
Hit PF3
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
Building Applications
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
Storage Information: Storage Media . . . . . . . . . . . . . _ 1. VCAT 2. Storage Group Storage Name . . . . . . . . . . . . . . ________ Primary Quantity . . . . . . . . . . . . 5_______ Secondary Quantity . . . . . . . . . . . 3_______
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
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
Building Applications
LISTRBD
Figure 5-5
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
Building Applications
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
The temporary data sets created are used in the COMP step.
DB2PRE
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.
Loadlib member.
NCAL member.
COPYLIB
BINDIN
DB2 bind.
GRANT LU2
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
Building Applications
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.
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
Building Applications
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
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
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
Building Applications
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
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
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.
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.
Loadlib member.
LKEDB - BATCH
Loadlib member.
LKEDNB BATCH
VDEX
Bind file.
5-18
Building Applications
PR
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.
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
HPIVSAM
BINDIN
DB2 bind.
GRANT LU2
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
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
Building Applications
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
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
IMSSTAT
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.
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
Building Applications
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 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
Related Actions Rule PRepare Notes The member name in all data sets created is the windows implementation name
5-24
Building Applications
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
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
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
Building Applications
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
Relink . . . . . . . . . . . . . . . . . _
Rebind . . . . . . . . . . . . . . . . . _
1. Yes 2. No
. . . . . . . . . . _
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
Relink . . . . . . . . . . . . . . . . . _
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
Building Applications
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.
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
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.
5-30
Building Applications
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.
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
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
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
Building Applications
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
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
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.
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
Building Applications
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.
5-36
Building Applications
VER
Figure 5-22
Command ===>
********************************* 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
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
5-37
VER
5-38
Building Applications
CHAPTER
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.
6-1
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
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
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
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.
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
/************************************************************/ /* 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;
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
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
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
7-1
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.
7-2
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
. . . . . . . . . . _
7-3
7-4
CHAPTER
8
Note
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
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
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
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.
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.
8-12
Interface Options
8-13
Interface Options
* * 01
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.
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
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.
9-1
Note
USE RULE .... INIT, 3270 Converse and RDTL are not supported for OpenCOBOL IMS.
9-2
(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.
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
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.
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.
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.
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
9-11
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.
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.
9-13
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
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
RULE4
Processing Status
37 43 49 55 22 54
36 16
PROCESSING PROCESSING
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
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
----- -------- -------- -------- -------- -------- -------- -------- --------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
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
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
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 -----------------------------------------------------------------------------
9-18
CHAPTER
10
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)
10-1
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
Sample Components
10-3
Sample Components
SQLERR RETURN *
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
C'ASSEMBLER BATCH DB2 COMP OK !' C'ASSEMBLER BATCH DB2 FAILED !' D'0' CL(SQLCAL)' ' F'0' 9D'0' F'0'
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
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.
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
DBAREA_ALTPHONE; DBAREA_PAGE;
10-11
10-12
CHAPTER
11
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.
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.
11-2
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
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
015500 015920
* * * * *
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
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
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
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.
'.
* * * * * * * *
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
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 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
OpenCOBOL Requirements
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.
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
Generating OpenCOBOL
OpenCOBOL Requirements
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
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.
12-3
OpenCOBOL Requirements
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
Generating OpenCOBOL
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.
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
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.
12-6
Generating OpenCOBOL
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
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
Generating OpenCOBOL
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.
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.
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
Generating OpenCOBOL
CHAPTER
13
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.
13-1
Sample C Component
#define LENGTH 78 typedef struct { char Field(|LENGTH|); } input;
13-2
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;
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.
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
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.
14-1
// 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 /*
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
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
15-1
Using HPBCAPI
AppBuilder batch rule, control is returned to the calling program immediately after the call to HPBCAPI.
15-2
User Commarea
HPBCAPI with the Clean Up function between calls to execute different AppBuilder rules to avoid running out of storage.
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
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-RET-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-RET-TRAN
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-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.
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
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
Configuring Applications
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
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
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
Configuring Applications
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
Table 16-7 Partition Encapsulates Preparable Entity (Continued) Attribute Isolation Mode Function DB2 isolation modeCommitted Read, Cursor Stability, Dirty Read, or Repeatable Read.
2. Display list of preparable objects for individual selection 3. All preparable objects in the object hierarchy
16-6
Configuring Applications
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
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
2. ACTIVATE a partition partition 1 partition Qualifier=name 1 Qualifier=name partition 2 partition Qualifier=name 2 Qualifier=name
3. Prepare rules partition 1 partition Qualifier=name 1 Qualifier=name partition 2 partition Qualifier=name 2 Qualifier=name
16-8
Configuring Applications
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.
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
2. ACTIVATE a partition partition 1 partition Owner=name 1 Qualifier=name partition 2 partition Owner=name 2 Qualifier=name
3. Prepare rules partition 1 partition Owner=name 1 Qualifier=name partition 2 partition Owner=name 2 Qualifier=name
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
1. Relate rules and components to multiple partitions partition 1 partition Isolation mode=CS Qualifier=name partition 2 partition Isolation mode=RR Qualifier=name
2. ACTIVATE a partition partition 1 partition Isolation mode=CS Qualifier=name partition 2 partition Isolation mode=RR Qualifier=name
3. Prepare rules partition 1 partition Isolation mode=CS Qualifier=name partition 2 partition Isolation mode=RR Qualifier=name
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.
16-10
Configuring Applications
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.
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.
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
Configuring Applications
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
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.
16-14
Configuring Applications
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)
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
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
Configuring Applications
Note
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
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
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
Configuring Applications
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
1 N 2 P 3 P 4 P 5 V
by order of by order of precedence precedence by order of by order of precedence precedence version defaults
ignored
version default
16-19
6 V 7 V 8 V
Bind version package, default Bind plan Bind package Bind package version default version default
W W
required required
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
Configuring Applications
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.
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
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
Configuring Applications
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).
16-23
Note
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
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
Configuring Applications
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
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
Configuring Applications
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.
17-1
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.
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)
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
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
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.
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.
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
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 ,
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.
17-9
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.
17-11
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.
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.
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.
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
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.
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
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
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
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.
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
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.
18-3
Using global eventing requires the following processes: Posting Rule Hierarchy Posting Rule Code Receiving Rule Hierarchy Receiving Rule Code
18-4
Advanced Topics
2.
Figure 18-1
18-5
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.
18-6
Advanced Topics
18-7
18-8
Advanced Topics
Index
INDEX
AppBuilder 2.0.3.1 Enterprise Application Guide
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