z/VM V6.4 CP Exit CustomizationStandar d Parameter List Contents . 107 Standar d Exit Conditions ....

z/VM

CP Exit CustomizationVersion 6 Release 4

SC24-6176-03

IBM

Note:Before you use this information and the product it supports, read the information in “Notices” on page 315.

This edition applies to version 6, release 4, modification 0 of IBM z/VM (product number 5741-A07) and to allsubsequent releases and modifications until otherwise indicated in new editions.

This edition replaces SC24-6176-02.

© Copyright IBM Corporation 1995, 2016.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

About This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiIntended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiSyntax, Message, and Response Conventions . . . . . . . . . . . . . . . . . . . . . . . . xiiiLinks to Other Documents and Websites . . . . . . . . . . . . . . . . . . . . . . . . . xvi

How to Send Your Comments to IBM . . . . . . . . . . . . . . . . . . . . . . xvii

Summary of Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xixSC24-6176-03, z/VM Version 6 Release 4 . . . . . . . . . . . . . . . . . . . . . . . . . xix

I/O Monitor User Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xixSC24-6176-02, z/VM Version 6 Release 3 . . . . . . . . . . . . . . . . . . . . . . . . . xix

User Class Restructure (UCR) Support Removed. . . . . . . . . . . . . . . . . . . . . . xixSC24-6176-01, z/VM Version 6 Release 2 . . . . . . . . . . . . . . . . . . . . . . . . . xix

Support for z/VM Single System Image Clusters . . . . . . . . . . . . . . . . . . . . . xixSC24-6176-00, z/VM Version 6 Release 1 . . . . . . . . . . . . . . . . . . . . . . . . . xx

Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Benefits of Using CP Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Understanding the System Execution Space and CP Customization Methods . . . . . . . . . . . . . . 1

Storage Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Customizing CP Using the SYSGEN Method . . . . . . . . . . . . . . . . . . . . . . . 2Customizing CP Using the CP Exit Method . . . . . . . . . . . . . . . . . . . . . . . . 3

Loading Files into the SXS Dynamic Area. . . . . . . . . . . . . . . . . . . . . . . . . . 3Unloading Files from the SXS Dynamic Area . . . . . . . . . . . . . . . . . . . . . . . . 4Creating, Controlling, and Redefining CP Commands and Diagnose Codes . . . . . . . . . . . . . . 4Creating, Controlling, and Calling CP Exits . . . . . . . . . . . . . . . . . . . . . . . . . 4Creating, Controlling, and Using Local CP Message Repositories . . . . . . . . . . . . . . . . . . 5

Chapter 2. Migrating Your Local Modifications . . . . . . . . . . . . . . . . . . . 7Techniques for Isolating Source Modifications . . . . . . . . . . . . . . . . . . . . . . . . 7

Exploit an IBM-Defined CP Exit Point . . . . . . . . . . . . . . . . . . . . . . . . . . 7Create Your Own Exit Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Front-end an Existing Diagnose Code . . . . . . . . . . . . . . . . . . . . . . . . . . 9Front-end an Existing CP Command . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Eliminating Source Modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Command Table Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Diagnose Code Table Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Defining Linkage Attributes for New Modules. . . . . . . . . . . . . . . . . . . . . . . 10Selecting a Name for New Modules . . . . . . . . . . . . . . . . . . . . . . . . . . 11Changes to the System Common Area . . . . . . . . . . . . . . . . . . . . . . . . . 11Changes to the CP Message Repository . . . . . . . . . . . . . . . . . . . . . . . . . 11

Dynamically Loaded Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 3. Creating a Dynamically Loaded Routine . . . . . . . . . . . . . . . . 13Input Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Output Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Addressing Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Using CP Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Defining System Linkage to Your Routine . . . . . . . . . . . . . . . . . . . . . . . . . 19

© Copyright IBM Corp. 1995, 2016 iii

Discussion of the HCPPROLG Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Discussion of the HCPENTER Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Discussion of the HCPEXIT Macro. . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Discussion of the HCPCALL Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

HCPCALL TYPE=DIRECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22HCPCALL TYPE=INDIRECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Usage Note for HCPCALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Discussion of the HCPLCALL Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Discussion of the HCPLENTR Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Discussion of the HCPLEXIT Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Discussion of the HCPCONSL Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Some HCPCONSL Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Using Other Dynamically Loaded Routines . . . . . . . . . . . . . . . . . . . . . . . . . 32How Should the Routine be Named? . . . . . . . . . . . . . . . . . . . . . . . . . . . 33How Should the Linkage Attributes of the Routine be Specified? . . . . . . . . . . . . . . . . . 34How are Addresses Resolved? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Can I Add My Own CP IUCV System Service? . . . . . . . . . . . . . . . . . . . . . . . 35What Does the CPXUNLOAD ASYNCHRONOUS Operand Mean? . . . . . . . . . . . . . . . . . 36What Does the CPXLOAD CONTROL Operand Imply? . . . . . . . . . . . . . . . . . . . . 36What Happens if I Make a Programming Error? . . . . . . . . . . . . . . . . . . . . . . . 37

Chapter 4. Loading Dynamically into the System Execution Space . . . . . . . . . . 39Understanding CPXLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Using the DELAY and NODELAY Operands . . . . . . . . . . . . . . . . . . . . . . . 39Using the PERMANENT and TEMPORARY Operands . . . . . . . . . . . . . . . . . . . . 40Using the CONTROL and NOCONTROL Operands . . . . . . . . . . . . . . . . . . . . . 40Using the MP, NOMP, and NONMP Operands . . . . . . . . . . . . . . . . . . . . . . 40Using the LET and NOLET Operands . . . . . . . . . . . . . . . . . . . . . . . . . 40

How to Package Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Examples of CPXLOAD Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

CPXLOAD Example 1: Installing a New CP Command . . . . . . . . . . . . . . . . . . . . 42CPXLOAD Example 2: Installing a New Diagnose Code . . . . . . . . . . . . . . . . . . . 43CPXLOAD Example 3: Installing a New Message. . . . . . . . . . . . . . . . . . . . . . 43

Examples of CPXLOAD Directives. . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Chapter 5. Controlling a Dynamically Loaded Routine . . . . . . . . . . . . . . . 47Controlling a Dynamically Loaded CP Command Routine . . . . . . . . . . . . . . . . . . . . 47Controlling a Dynamically Loaded Diagnose Code Routine . . . . . . . . . . . . . . . . . . . 48Controlling a Dynamically Loaded CP Exit Routine . . . . . . . . . . . . . . . . . . . . . . 49Controlling a Dynamically Loaded Local Message Repository . . . . . . . . . . . . . . . . . . 50IPL Parameter NOEXITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Chapter 6. Defining and Modifying Commands and Diagnose Codes . . . . . . . . . 51CMDBKs, DGNBKs and You . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

CMDBKs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51DGNBKs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Relationship between IBM Class and User Privilege Class . . . . . . . . . . . . . . . . . . . 52

Coding Your Command and Diagnose Code . . . . . . . . . . . . . . . . . . . . . . . . 52Coding a Command Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Coding a Diagnose Code Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Defining your Command and Diagnose Code . . . . . . . . . . . . . . . . . . . . . . . . 55Defining Your Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Defining Your Diagnose Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Defining an Alias Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Modifying a Command or Diagnose Code . . . . . . . . . . . . . . . . . . . . . . . . . 59Disabling a Command or Diagnose Code . . . . . . . . . . . . . . . . . . . . . . . . . 59

Chapter 7. Defining and Using CP Message Repositories . . . . . . . . . . . . . . 61Why Use Message Repositories? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Components of a Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

iv z/VM V6.4 CP Exit Customization

Creating a Message Repository File . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Example of a Message Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Generating the Object Repository File . . . . . . . . . . . . . . . . . . . . . . . . . 63

Loading and Unloading Message Files . . . . . . . . . . . . . . . . . . . . . . . . . . 64Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Producing Messages from a Repository . . . . . . . . . . . . . . . . . . . . . . . . . . 65How Does CP Choose Which Repository to Use? . . . . . . . . . . . . . . . . . . . . . . 65Producing Messages Without Substitution . . . . . . . . . . . . . . . . . . . . . . . . 66Producing Messages With Substitution . . . . . . . . . . . . . . . . . . . . . . . . . 67Producing Messages With Column Format . . . . . . . . . . . . . . . . . . . . . . . . 68When You Cannot Use a Message Repository . . . . . . . . . . . . . . . . . . . . . . . 70

Chapter 8. Unloading Dynamically from the System Execution Space. . . . . . . . . 71What May Be Unloaded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71CPXLOAD Load ID Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72When to Use ASYNCHRONOUS and SYNCHRONOUS . . . . . . . . . . . . . . . . . . . . 72

Chapter 9. Understanding the CP Parser . . . . . . . . . . . . . . . . . . . . . 73Introduction to the Syntax Definition Macros . . . . . . . . . . . . . . . . . . . . . . . . 73Understanding How to Code for the Parser Using an Example . . . . . . . . . . . . . . . . . . 74

Step 1: Develop the Syntax Railroad Track Diagram . . . . . . . . . . . . . . . . . . . . . 74Step 2: Assign HCPCFDEF Macro to the First Token . . . . . . . . . . . . . . . . . . . . . 76Step 3: Mark Alternative Path Locations . . . . . . . . . . . . . . . . . . . . . . . . . 76Step 4: Assign HCPSTDEF Macro to Alternative Path Locations . . . . . . . . . . . . . . . . . 77Step 5: Assign HCPTKDEF Macro to Each Token . . . . . . . . . . . . . . . . . . . . . . 77Step 6: Add the Keywords for the Macros . . . . . . . . . . . . . . . . . . . . . . . . 78Step 7: Develop the Storage Area Definitions . . . . . . . . . . . . . . . . . . . . . . . 80Step 8: Develop the HCPDOSYN Macro . . . . . . . . . . . . . . . . . . . . . . . . . 81Step 9: Write the Code to Call the Parser . . . . . . . . . . . . . . . . . . . . . . . . 82Step 10: Write the Commands to Activate the Code . . . . . . . . . . . . . . . . . . . . . 83

Using the Parser to Store Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Dividing Your Syntax over Multiple Modules . . . . . . . . . . . . . . . . . . . . . . . . 86Combining ROOT=, PLBASE=, BASES=, and SYNLIST= . . . . . . . . . . . . . . . . . . . . 87Using a Post-Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Providing Additional Processing in Your Mainline Routine . . . . . . . . . . . . . . . . . . 88Providing Additional Processing in Your Post-processor. . . . . . . . . . . . . . . . . . . . 88Using a Single Syntax for a Command and for a Configuration File Statement . . . . . . . . . . . . 89

Creating Your Own Configuration File Statements . . . . . . . . . . . . . . . . . . . . . . 89Using One Syntax for Two Purposes . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Error Messages and How the Parser Handles Them . . . . . . . . . . . . . . . . . . . . . . 92Detecting Syntax Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Additional Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Chapter 10. Common and Frequent Problems . . . . . . . . . . . . . . . . . . . 95Available Diagnostic Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Common Mistakes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Command Related Problems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Diagnose Code Related Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Message Related Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Exit Point Related Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100CPXLOAD Related Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101CPUNXLOAD Related Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Miscellaneous CP Customization Errors . . . . . . . . . . . . . . . . . . . . . . . . 102

Appendix A. IBM-Defined CP Exit Points. . . . . . . . . . . . . . . . . . . . . 103Summary of IBM-Defined CP Exit Points . . . . . . . . . . . . . . . . . . . . . . . . . 104Usage Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Standard Point of Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Standard Entry Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Contents v

Standard Parameter List Contents . . . . . . . . . . . . . . . . . . . . . . . . . . 107Standard Exit Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Standard Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Additional Information about Control Entry Points . . . . . . . . . . . . . . . . . . . . . 109

CP Exit 00E0: Startup Pre-Prompt Processing . . . . . . . . . . . . . . . . . . . . . . . 112CP Exit 00E1: Startup Post-Prompt Processing . . . . . . . . . . . . . . . . . . . . . . . 117CP Exit 0FFB: Post-Authorization Command Processing . . . . . . . . . . . . . . . . . . . 122CP Exit 1100: LOGON Command Pre-Parse Processing . . . . . . . . . . . . . . . . . . . . 126CP Exit 1101: Logon Post-Parse Processing . . . . . . . . . . . . . . . . . . . . . . . . 129CP Exit 1110: VMDBK Pre-Logon Processing . . . . . . . . . . . . . . . . . . . . . . . 132CP Exit 117F: Logon Final Screening . . . . . . . . . . . . . . . . . . . . . . . . . . 134CP Exit 11C0: Logoff Initial Screening . . . . . . . . . . . . . . . . . . . . . . . . . . 136CP Exit 11FF: Logoff Final Screening . . . . . . . . . . . . . . . . . . . . . . . . . . 138CP Exit 1200: DIAL Command Initial Screening . . . . . . . . . . . . . . . . . . . . . . 140CP Exit 1201: DIAL Command Final Screening. . . . . . . . . . . . . . . . . . . . . . . 142CP Exit 1210: Messaging Commands Screening . . . . . . . . . . . . . . . . . . . . . . 144CP Exit 1230: VMRELOCATE Eligibility Checks . . . . . . . . . . . . . . . . . . . . . . 150CP Exit 1231: VMRELOCATE Destination Restart . . . . . . . . . . . . . . . . . . . . . . 152CP Exit 3FE8: SHUTDOWN Command Screening . . . . . . . . . . . . . . . . . . . . . . 154CP Exit 4400: Separator Page Data Customization. . . . . . . . . . . . . . . . . . . . . . 157CP Exit 4401: Separator Page Pre-Perforation Positioning . . . . . . . . . . . . . . . . . . . 159CP Exit 4402: Separator Page Perforation Printing or 3800 Positioning . . . . . . . . . . . . . . . 161CP Exit 4403: Separator Page Printing. . . . . . . . . . . . . . . . . . . . . . . . . . 163CP Exit 4404: Second Separator Page Positioning . . . . . . . . . . . . . . . . . . . . . . 165CP Exit 4405: Second Separator Page Printing . . . . . . . . . . . . . . . . . . . . . . . 167CP Exit 4406: Separator Page Post-Print Positioning . . . . . . . . . . . . . . . . . . . . . 169CP Exit 4407: Trailer Page Processing . . . . . . . . . . . . . . . . . . . . . . . . . . 171CP Exit Point and Module Reference . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Appendix B. Dynamic Exit Points . . . . . . . . . . . . . . . . . . . . . . . . 175Point of Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Entry Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Parameter List Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Exit Conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Appendix C. CPXLOAD Directives . . . . . . . . . . . . . . . . . . . . . . . 177CHANGE Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178EXPAND Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180INCLUDE Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181OPTIONS Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Appendix D. CP Files of Interest . . . . . . . . . . . . . . . . . . . . . . . . 187CP Control Blocks and Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187CP Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Appendix E. CP Exit Macros . . . . . . . . . . . . . . . . . . . . . . . . . . 191HCPXSERV: CP Exit Services Director. . . . . . . . . . . . . . . . . . . . . . . . . . 192

Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

MDLATENT: MDLAT Entry Definition . . . . . . . . . . . . . . . . . . . . . . . . . 202MDLATHDR: MDLAT Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209MDLATTLR: MDLAT Trailer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Appendix F. CP Parser Macros and Routines . . . . . . . . . . . . . . . . . . . 211HCPCFDEF: Command/Config File Statement Definition Macro . . . . . . . . . . . . . . . . . 212HCPDOSYN: Parser Syntax Table Generator Macro . . . . . . . . . . . . . . . . . . . . . 214HCPSTDEF: Parser State Definition Macro . . . . . . . . . . . . . . . . . . . . . . . . 216

Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

vi z/VM V6.4 CP Exit Customization

Example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

HCPTKDEF: Parser Token Definition Macro . . . . . . . . . . . . . . . . . . . . . . . 219Example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

HCPZPRPC — Parse Remainder of Command Line . . . . . . . . . . . . . . . . . . . . . 227HCPZPRPG — Parse Any GSDBK . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Pre-Processing Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Post-Processing Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Appendix G. Understanding the CP Message Repository. . . . . . . . . . . . . . 231Message Repository File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231Commenting Your Message Repository . . . . . . . . . . . . . . . . . . . . . . . . . . 231Creating a Control Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231Creating Message Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232Message Repository Idiosyncrasies . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Additional CP Message Repository Idiosyncrasies . . . . . . . . . . . . . . . . . . . . . . 234

Appendix H. Updating the CP Load List . . . . . . . . . . . . . . . . . . . . . 235General Rules for Coding an Alternate MDLAT Macro . . . . . . . . . . . . . . . . . . . . 235Creating an Alternate MDLAT Macro . . . . . . . . . . . . . . . . . . . . . . . . . . 236Coding the User Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238Generating a New CP Load List . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Appendix I. Samples of Dynamically Loaded Routines. . . . . . . . . . . . . . . 241What You Should Gain from the Sample CP Exit 1200 Routines . . . . . . . . . . . . . . . . . 242Understanding CP Exit 1200 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Understanding the Sample CP Exit 1200 Routines . . . . . . . . . . . . . . . . . . . . . . 243

Sample 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Sample 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Why Sample 2 Is Better Than Sample 1. . . . . . . . . . . . . . . . . . . . . . . . . 244Using the Sample CP Exit 1200 Routines . . . . . . . . . . . . . . . . . . . . . . . . 245Potential Improvements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245A Sample JAMTABLE SOURCE File . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Appendix J. I/O Monitor User Exit. . . . . . . . . . . . . . . . . . . . . . . . 311Call Mechanics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311Important Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Enablement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Programming Interface Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 317Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317Terms and Conditions for Product Documentation . . . . . . . . . . . . . . . . . . . . . . 317IBM Online Privacy Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

Bibliography. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321Where to Get z/VM Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321z/VM Base Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321z/VM Facilities and Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322Prerequisite Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Contents vii

||||||||||

viii z/VM V6.4 CP Exit Customization

Figures

1. Layout of the SXS Using the SYSGEN Method . . . . . . . . . . . . . . . . . . . . . . 22. Layout of the SXS Using the CP Exits Method . . . . . . . . . . . . . . . . . . . . . . 33. RULES member of DGN1FC TXTLIB . . . . . . . . . . . . . . . . . . . . . . . . . 454. Sample Repository - SPGMES REPOS . . . . . . . . . . . . . . . . . . . . . . . . . 625. Sample Assembler Code Accessing SPGMES REPOS from module HCPXXX . . . . . . . . . . . . 666. Sample Repository - JCRMES REPOS . . . . . . . . . . . . . . . . . . . . . . . . . 677. Sample Assembler Code Accessing JCRMES REPOS from module HCPXXX . . . . . . . . . . . . 688. Sample Repository - JAFMES REPOS . . . . . . . . . . . . . . . . . . . . . . . . . 689. Sample Assembler code accessing JAFMES REPOS . . . . . . . . . . . . . . . . . . . . 69

10. CP Message Record Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23211. ABCMDLAT Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

© Copyright IBM Corp. 1995, 2016 ix

x z/VM V6.4 CP Exit Customization

Tables

1. Examples of Syntax Diagram Conventions . . . . . . . . . . . . . . . . . . . . . . . xiv2. Various Linkage Decisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223. IBM Class Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524. Results if a message is found or not found in a repository. . . . . . . . . . . . . . . . . . . 665. Summary of IBM-Defined CP Exit Points . . . . . . . . . . . . . . . . . . . . . . . 1046. CPXLOAD Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1777. Legal and Illegal HCPXSERV Action/Parameter Combinations . . . . . . . . . . . . . . . . 1968. Register Contents During HCPXSERV Execution . . . . . . . . . . . . . . . . . . . . . 1979. Register Contents After HCPXSERV Completion . . . . . . . . . . . . . . . . . . . . . 197

10. Register Contents After HCPXSERV Completion Continued . . . . . . . . . . . . . . . . . 19911. Conversion types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22112. Annotated Listing for Sample CP Exit Routine 1 for CP Exit 1200 . . . . . . . . . . . . . . . 24713. Annotated Listing for Sample CP Exit Routine 2 for CP Exit 1200 . . . . . . . . . . . . . . . 26514. Annotated Listing of a Local Message Repository for Sample 2 of CP Exit 1200 . . . . . . . . . . 309

© Copyright IBM Corp. 1995, 2016 xi

xii z/VM V6.4 CP Exit Customization

About This Document

This document contains information about using CP Exits support to customize anIBM® z/VM® system. CP Exits support allows you to make nondisruptiveadditions and deletions of dynamically loaded CP routines (non-IBM-suppliedcode) to add and delete CP commands, Diagnose codes, locally developed CPmessage repositories, and CP exit routines.

This document describes the terminology, concepts, and functions of CP Exitssupport. It explains how to create and manipulate dynamically loaded routines. Italso includes reference information describing the IBM-defined exit points,CPXLOAD directives, and CP exit macros.

Intended AudienceThis information is intended only for experienced programmers who need to makelocal modifications to a z/VM system.

We recommend that you do not attempt to use the CP Exits support unless youhave the following skills:v A working knowledge of IBM Assembler Languagev Some knowledge of what the source for a CP module looks likev Some knowledge of the CP commands associated with the CP Exits support

Syntax, Message, and Response ConventionsThe following topics provide information on the conventions used in syntaxdiagrams and in examples of messages and responses.

How to Read Syntax Diagrams

Special diagrams (often called railroad tracks) are used to show the syntax ofexternal interfaces.

To read a syntax diagram, follow the path of the line. Read from left to right andtop to bottom.v The ►►─── symbol indicates the beginning of the syntax diagram.v The ───► symbol, at the end of a line, indicates that the syntax diagram is

continued on the next line.v The ►─── symbol, at the beginning of a line, indicates that the syntax diagram is

continued from the previous line.v The ───►◄ symbol indicates the end of the syntax diagram.

Within the syntax diagram, items on the line are required, items below the line areoptional, and items above the line are defaults. See the examples in Table 1 onpage xiv.

© Copyright IBM Corp. 1995, 2016 xiii

Table 1. Examples of Syntax Diagram Conventions

Syntax Diagram Convention Example

Keywords and Constants

A keyword or constant appears in uppercase letters.In this example, you must specify the itemKEYWORD as shown.

In most cases, you can specify a keyword or constantin uppercase letters, lowercase letters, or anycombination. However, some applications may haveadditional conventions for using all-uppercase orall-lowercase.

►► KEYWORD ►◄

Abbreviations

Uppercase letters denote the shortest acceptableabbreviation of an item, and lowercase letters denotethe part that can be omitted. If an item appearsentirely in uppercase letters, it cannot beabbreviated.

In this example, you can specify KEYWO, KEYWOR,or KEYWORD.

►► KEYWOrd ►◄

Symbols

You must specify these symbols exactly as theyappear in the syntax diagram.

* Asterisk: Colon, Comma= Equal Sign- Hyphen() Parentheses. Period

Variables

A variable appears in highlighted lowercase, usuallyitalics.

In this example, var_name represents a variable thatyou must specify following KEYWORD.

►► KEYWOrd var_name ►◄

Repetitions

An arrow returning to the left means that the itemcan be repeated.

A character within the arrow means that you mustseparate each repetition of the item with thatcharacter.

A number (1) by the arrow references a syntax noteat the bottom of the diagram. The syntax note tellsyou how many times the item can be repeated.

Syntax notes may also be used to explain otherspecial aspects of the syntax.

►► ▼ repeat ►◄

►► ▼

,

repeat ►◄

►► ▼(1)

repeat ►◄

Notes:

1 Specify repeat up to 5 times.

xiv z/VM V6.4 CP Exit Customization

Table 1. Examples of Syntax Diagram Conventions (continued)

Syntax Diagram Convention Example

Required Item or Choice

When an item is on the line, it is required. In thisexample, you must specify A.

When two or more items are in a stack and one ofthem is on the line, you must specify one item. Inthis example, you must choose A, B, or C.

►► A ►◄

►► ABC

►◄

Optional Item or Choice

When an item is below the line, it is optional. In thisexample, you can choose A or nothing at all.

When two or more items are in a stack below theline, all of them are optional. In this example, youcan choose A, B, C, or nothing at all.

►►A

►◄

►►ABC

►◄

Defaults

When an item is above the line, it is the default. Thesystem will use the default unless you override it.You can override the default by specifying an optionfrom the stack below the line.

In this example, A is the default. You can override Aby choosing B or C.

►►A

BC

►◄

Repeatable Choice

A stack of items followed by an arrow returning tothe left means that you can select more than oneitem or, in some cases, repeat a single item.

In this example, you can choose any combination ofA, B, or C.

►► ▼ ABC

►◄

Syntax Fragment

Some diagrams, because of their length, mustfragment the syntax. The fragment name appearsbetween vertical bars in the diagram. The expandedfragment appears in the diagram after a headingwith the same fragment name.

In this example, the fragment is named “AFragment.”

►► A Fragment ►◄

A Fragment:

A

BC

Examples of Messages and Responses

Although most examples of messages and responses are shown exactly as theywould appear, some content might depend on the specific situation. The followingnotation is used to show variable, optional, or alternative content:

xxx Highlighted text (usually italics) indicates a variable that represents thedata that will be displayed.

[ ] Brackets enclose optional text that might be displayed.

{ } Braces enclose alternative versions of text, one of which will be displayed.

About This Document xv

| The vertical bar separates items within brackets or braces.

... The ellipsis indicates that the preceding item might be repeated. A verticalellipsis indicates that the preceding line, or a variation of that line, mightbe repeated.

Links to Other Documents and WebsitesThe PDF version of this document contains links to other documents and websites.A link from this document to another document works only when both documentsare in the same directory or database, and a link to a website works only if youhave access to the Internet. A document link is to a specific edition. If a newedition of a linked document has been published since the publication of thisdocument, the linked document might not be the latest edition.

xvi z/VM V6.4 CP Exit Customization

How to Send Your Comments to IBM

We appreciate your input on this publication. Feel free to comment on the clarity,accuracy, and completeness of the information or give us any other feedback thatyou might have.

Use one of the following methods to send us your comments:1. Send an email to [email protected]. Go to IBM z/VM Reader's Comments (www.ibm.com/systems/z/os/zvm/

zvmforms/webqs.html).

Include the following information:v Your namev Your email addressv The publication title and order number:

z/VM V6.4 CP Exit CustomizationSC24-6176-03

v The topic name or page number related to your commentv The text of your comment

When you send comments to IBM®, you grant IBM a nonexclusive right to use ordistribute your comments in any way it believes appropriate without incurring anyobligation to you.

IBM or any other organizations will use the personal information that you supplyonly to contact you about the issues that you submit to IBM.

If You Have a Technical Problem

Do not use the feedback methods listed above. Instead, do one of the following:v Contact your IBM service representative.v Contact IBM technical support.v See IBM: z/VM Service Resources (www.ibm.com/vm/service/).v Go to IBM Support Portal (www.ibm.com/support/entry/portal/Overview/).

© Copyright IBM Corp. 1995, 2016 xvii

http://www.ibm.com/systems/z/os/zvm/zvmforms/webqs.html

http://www.ibm.com/vm/service/

http://www.ibm.com/support/entry/portal/Overview/

xviii z/VM V6.4 CP Exit Customization

Summary of Changes

This document contains terminology, maintenance, and editorial changes. Technicalchanges or additions to the text and illustrations are indicated by a vertical line tothe left of the change. Some product changes might be provided through serviceand might be available for some prior releases.

SC24-6176-03, z/VM Version 6 Release 4This edition includes changes to support the general availability of z/VM® V6.4.

I/O Monitor User ExitInstructions are provided for setting up an internal exit routine to monitor real I/Orequests. See Appendix J, “I/O Monitor User Exit,” on page 311.

SC24-6176-02, z/VM Version 6 Release 3This edition includes changes to support the general availability of z/VM V6.3.

User Class Restructure (UCR) Support RemovedSupport for the user class restructure (UCR) function and the OVERRIDE utilityhave been removed. Privilege classes for CP commands, DIAGNOSE codes, andother CP functions can be redefined by using MODIFY system configurationstatements and MODIFY commands.

If any UCR files exist on the system, the contents of those files will not beprocessed by CP.


Support for z/VM Single System Image ClustersA z/VM single system image (SSI) cluster is a multisystem environment in whichthe z/VM member systems can be managed as a single resource pool and runningvirtual servers (guests) can be relocated from one member to another. For moreinformation about the SSI environment and setting up SSI clusters, see z/VM: CPPlanning and Administration.

To support SSI clusters, many functions described in this document have beenupdated and new functions have been added. To use the functions that define andmaintain an SSI cluster, the IBM z/VM Single System Image Feature must belicensed and enabled.

New CP Exit 1230Information is added describing the use of CP Exit 1230 to defineinstallation-specific conditions for disallowing the relocation of virtual machinesusing the VMRELOCATE command in a single system image cluster. See “CP Exit1230: VMRELOCATE Eligibility Checks” on page 150 for details.

© Copyright IBM Corp. 1995, 2016 xix

New CP Exit 1231Information is added describing the use of CP Exit 1231 to do any necessaryprocessing before the target guest is restarted on the destination system during alive guest relocation. See “CP Exit 1231: VMRELOCATE Destination Restart” onpage 152 for details.


xx z/VM V6.4 CP Exit Customization

Chapter 1. Introduction

This section introduces you to the CP Exit support (its terminology, concepts, andfunctions) and explains how the CP Exit support can be helpful to you.

z/VM allows you to customize its control program (CP) using IBM-suppliedcommands and configuration file statements. These commands and statementscontrol the settings of various system functions. If you need to customize systemfunctions that you cannot control using commands or statements, you can addnon-IBM-supplied code (called “dynamically loaded CP routines”) to CP. Theseadditions allow you to extend the IBM-supplied system functions withoutrequiring you to generate a new CP nucleus.

This document discusses the CP Exit support (also referred to as “CP Exits”),which allows you to make nondisruptive additions and deletions of dynamicallyloaded CP routines (non-IBM-supplied code). Using CP Exits, you can add anddelete:v CP commandsv Diagnose codesv Locally-developed CP message repositoriesv CP exit routines

Benefits of Using CP ExitsUsing CP Exits gives you the ability to easily extend what your z/VM systemalready provides:v Increased system availability by:

– Eliminating the need to shut down and re-IPL z/VM to changeuser-executable code

v Reduced system generation errors by:– Eliminating the rework to local CP modifications, which are required because

IBM changed the CP source files– Reducing the time, complexity, and frequency of SYSGENs by avoiding local

CP modifications to the CP code linked during system generation– Eliminating SYSGENs for changes to local CP modifications

v Easy migration of existing z/VM customer base to the new releasesv Improved system programmer productivity by eliminating unnecessary tasks

Understanding the System Execution Space and CP CustomizationMethods

Before we can discuss how to dynamically add code to CP, you need tounderstand the layout of the address space in which CP executes. This addressspace is called the system execution space (SXS). Also, we need to compare theSYSGEN method of customizing CP (the old way) with the dynamic method ofcustomizing CP (CP Exits).

© Copyright IBM Corp. 1995, 2016 1

While explaining the layout of the SXS and the two methods of customizing CP,we will use a simple example for the CP nucleus area of the SXS and the dynamicarea of the SXS. In this example, we will ignore the following:v Other parts of the SXS located above the dynamic areav HSA (hardware system area)v Other miscellaneous areas that are not relevant to our discussion

Figure 1 and Figure 2 on page 3 show the CP nucleus at the bottom of the pictureand the SXS dynamic area at the top. The SXS dynamic area is used for all of CP'sdynamic storage requirements: CP control blocks, paging, and so forth.

Storage AddressesA central storage address reference by CP is typically termed a Host LogicalAddress, or HLA. HLAs map the SXS. CP control blocks, the CP nucleus, and filesloaded with CPXLOAD are all mapped in the SXS and are addressed by HLAs.

The SXS is not called CP Virtual Storage, even though the HLA undergoeshardware dynamic address translation (DAT) to generate a Host Real Address(HRA) and address prefixing in order to generate a Host Absolute Address (HAA).You can ignore HRAs and HAAs unless the need for such an address is explicitlystated. For example, the HRA and HAA would be used for hardware addresseslike CCW addresses. You can ignore CP Virtual Storage unless the need for such anaddress is explicitly stated. Generally, write your programs and refer to CP controlblocks just like always.

All references to storage addresses in this document are to HLAs unless otherwisestated.

Customizing CP Using the SYSGEN Method

When you add your code to CP using the SYSGEN method, it gets placed in theCP nucleus, among all of the IBM-supplied CP code. To add your code in thismanner, you must make local modifications to the CP source files. The SYSGENhandles the linkage considerations, such as resolving addresses.

┌──────────────────────────────────────────────────────────┐│ ││ │

SXS │ │Dynamic Area │ │

│ ││ ││ │├──────────────────────────────────────────────────────────┤│ ┌──────┐ ││ │ diag │ ┌──────┐ ││ └──────┘ │ diag │ ┌──────┐ ││ └──────┘ │ cmd │ │

CP Nucleus │ ┌──────┐ └──────┘ │(SXS Fixed Area) │ │ mod │ │

│ └──────┘ ┌──────┐ ││ ┌──────┐ ┌──────┐ │ mod │ ││ │ mod │ │ exit │ └──────┘ ││ └──────┘ └──────┘ │└──────────────────────────────────────────────────────────┘

Figure 1. Layout of the SXS Using the SYSGEN Method

Introduction

2 z/VM V6.4 CP Exit Customization

This method is unpleasant because you do not own or control the CP source files.Every time IBM makes a change to a source file, that change has the possibility ofcausing you to rework your code. For example, you must contend with:v Changes to module namesv Changes in sequence numberingv Changes to internal designv Modules whose source is not distributed outside IBMv Sparse documentation

At times, this unpleasantness can confront you when you apply service within arelease. After making your coding changes, you must regenerate the CP nucleus,shut z/VM down, and re-IPL, which causes an unwelcome loss of z/VM service.

Customizing CP Using the CP Exit MethodUsing the CP Exits support discussed in this document, you can dynamically addyour CP command routines, Diagnose code routines, CP exit routines and localmessage repositories to CP.

Unlike the SYSGEN method, your code and data files are stored in the SXSdynamic area, not the CP nucleus. This greatly reduces the possibility that you willhave to rework your code because IBM makes internal changes in CP source files.Your code and data files are easily added, removed, or replaced at yourconvenience, without disruption to z/VM service.

Note: The rest of this document concentrates on how to customize CP using theCP Exit method. The SYSGEN method will be mentioned only as a contrast.

Loading Files into the SXS Dynamic AreaTo place your code and data files into the SXS dynamic area, use CPXLOAD,which is available as a configuration file statement and as a command. CPXLOADenables you to load almost any text file that you could have loaded into the CPnucleus with a SYSGEN.

In order to dynamically load your files, CPXLOAD:

┌──────────────────────────────────────────────────────────┐│ ┌──────┐ ││ │ diag │ ┌──────┐ ││ └──────┘ │ diag │ ┌──────┐ │

SXS │ └──────┘ │ cmd │ │Dynamic Area │ ┌──────┐ └──────┘ │

│ │ exit │ ││ ┌──────┐ └──────┘ ││ │ exit │ ┌──────┐ ││ └──────┘ │ msgs │ ││ └──────┘ │├──────────────────────────────────────────────────────────┤│ ││ ││ │

CP Nucleus │ │(SXS Fixed Area) │ │

│ ││ │└──────────────────────────────────────────────────────────┘

Figure 2. Layout of the SXS Using the CP Exits Method

Introduction

Chapter 1. Introduction 3

1. Reads your executable code and data files from the parm disk (or if available,from any CP-accessed disk).

2. Places the data into the SXS dynamic area.3. Interconnects it with tables in the CP nucleus so that your executable code

looks like it was there all along (that is, it looks like it was bundled togetherwith the rest of the CP nucleus during a SYSGEN).

4. (Optionally) Invokes a control entry point to initialize the newly-loaded code.This may involve tasks such as setting up tables, acquiring storage, or defininglocks.

After CPXLOAD completes, your executable code becomes part of CP withoutinterrupting CP (or the rest of your z/VM system).

Unloading Files from the SXS Dynamic AreaIn addition to being able to load your routines, you can also unload the routinesyou dynamically loaded (with CPXLOAD) using the CPXUNLOAD command.(CPXUNLOAD does not have a configuration file statement counterpart.)CPXUNLOAD removes the necessary linkages so that the system can continue tooperate without interruption. As with CPXLOAD, you can invoke an optionalcontrol entry point to allow your routines to clean up before the actual files areunloaded.

Creating, Controlling, and Redefining CP Commands and DiagnoseCodes

You can assign the code that you dynamically load to a new CP command or to aDiagnose code. After loading the code, you must define the new command orDiagnose code to CP so that CP has the necessary control information to executeyour command or Diagnose code. To define a new command, use the DEFINECOMMAND or DEFINE CMD command. To define a new Diagnose code, use theDEFINE DIAGNOSE command. Without these commands, you would have to usethe SYSGEN method of system modification: coding the COMMD and DIAGNOSEmacros, reassembling the data modules, regenerating the CP nucleus, and reIPLingthe new system.

You can also redefine ("modify") existing CP commands and Diagnose codes. Withthis feature, you can dynamically change the user privilege class assigned to a CPcommand or Diagnose code. You can also change the entry point associated withthe CP command or Diagnose code and thereby change the function.

Creating, Controlling, and Calling CP ExitsIn addition to customizing CP commands and Diagnose codes, you can modify acode path by inserting code into an IBM-supplied module.

Using CP exit points allows you (or IBM) to define code transfer points. Whenenabled, these CP exit points transfer control to a CP exit routine. This minimizesthe footprint of the user code in the IBM-supplied module, thus reducing thechance for conflicts with IBM service or new release support. CP exit points aredefined during the expansion of the HCPXSERV macro at module assembly time.

The HCPXSERV macro defines the CP exit point by assigning an exit number tothe point in the code at which the HCPXSERV macro expands. You can associateyour user routines (entry points) with the CP exit point using the ASSOCIATE

Introduction


EXIT command or statement. The CP exit point processing code detects when a CPexit point is enabled and transfers control to the CP exit routine. Upon return, theroutines that you associated with the CP exit point can set a return code to affectsubsequent processing within the IBM-supplied module.

You can also define CP exit points dynamically using the DEFINE EXIT andMODIFY EXIT commands, or the DEFINE EXIT and MODIFY EXIT configurationstatements. A dynamic exit point behaves just like a formally-defined exit point,except that its ability to influence subsequent processing in the module containingthe exit point is limited.

Creating, Controlling, and Using Local CP Message RepositoriesThe code that you add to CP may need to generate messages. Just as adding codeto the IBM-supplied modules left you susceptible to possible conflicts with IBMservice changes and release changes, so does adding messages to the IBM-suppliedCP message repository. To avoid such conflicts, you can create a local CP messagerepository and identify it to the system using the ASSOCIATE MESSAGES orMSGS command or configuration file statement. This allows your code to displaymessages from your own message repositories and eliminates the possible conflictsbetween your messages and the IBM-supplied messages in the CP messagerepository.

You can also use this function to replace an existing IBM-supplied CP messagewith one that is unique to your installation. CP allows you to create and associatea local message repository with the system so that messages in your repositoryoverride the messages in IBM's repository.

Introduction

Chapter 1. Introduction 5

Chapter 2. Migrating Your Local Modifications

This section describes some common techniques that you can use to change yourlocal modifications to IBM-supplied code into CP exit points.

Local modifications to IBM-supplied code can vary greatly in scope and size. Youmay be managing several small modifications that are scattered throughout a seriesof CP modules. Or, you may have added an additional function to an existing CProutine, CP command handler, or IBM-supplied Diagnose code. And finally, youmay have written your own routine that, along with a few required sourcemodifications to existing CP routines, provides a completely new command foryour users or a new Diagnose code function for your applications.

The work required to manage source modifications to IBM-supplied code can beextensive. Installations that currently support local source modifications will wantto migrate those changes in order to take advantage of the dynamic capabilitiesthat are available for customizing your system. In some cases, very little work maybe involved. In others, you may need to rework your local modificationsignificantly to better fit into the dynamic arena. In particular, you will want toconsider:v Isolating your code additions from existing CP codev Eliminating existing source modifications whenever possiblev Modifying your own routines so that they can be dynamically loaded on your

system

Techniques for Isolating Source ModificationsThere are significant advantages to isolating your existing changes to CP sourcecode into your own modules. Removing local changes to IBM-supplied source codedrastically reduces the need to rework those changes when IBM source codechanges. In addition, removing your code changes from existing CP modules takesyou a step closer to making your functional change dynamic.

Exploit an IBM-Defined CP Exit PointA CP exit point defines a location in IBM-supplied code where a CP routine willgive control to user routines. The user routines can perform additional tasks beforereturning control back to the CP routine. The IBM-defined CP exit points are listedand described in Appendix A, “IBM-Defined CP Exit Points,” on page 103. Eachone has defined entry conditions, specific parameter list requirements, and a set ofexit conditions. By exploiting an available IBM defined CP exit point, you may beable to completely eliminate your source modifications to an existing CP routine.

Once you determine that there is a CP exit point that meets your needs, examinethe functional changes that your local modification now provides. Your goalshould be to delete changes to an existing source module and isolate the codechanges to a separate module of your own. The local modifications might have tobe enhanced so that the defined input and output parameters for the exit point aremet.

As an example, suppose that you have a local modification to the CP initializationfunction. Because of the ramifications associated with performing a CLEAN start,


you have decided to provide more control over the type of start that an operatorcan initiate. You may have added some code to existing CP source modules thatprevents an operator from requesting a CLEAN start unless an extra piece ofinformation is supplied when prompted.

Such a source modification would be a candidate for migration to the IBM definedCP exit point 00E1. This exit is driven after the operator responds to theinitialization prompt, but before CP interprets the operator's input.

Once you have isolated the code change to handle the additional validation, youcan use configuration file statements (CPXLOAD, ASSOCIATE EXIT, ASSOCIATEMESSAGES, ENABLE EXIT) to make use of this exit point and to activate yourfunctional change dynamically.

Create Your Own Exit PointThere may be times where you find that you have a functional change to anexisting CP routine and, after reviewing the list of available CP Exit points, youfind there are none that meets your needs. This does not prevent you frommigrating your source modifications so that they lend themselves to dynamiccustomization. Although in this instance you may not be able to completelyeliminate your source modification, your goal should be to minimize your changeto the IBM-supplied code as much as possible and to isolate the major portion ofyour changes to your own module.

Once you've isolated your functional changes, you could use the HCPXSERVmacro to define your own exit point within a CP source module. The HCPXSERVmacro is discussed in Appendix E, “CP Exit Macros,” on page 191.

Instead of adding a formal exit point with the HCPXSERV macro, you can definean exit point dynamically using the DEFINE EXIT command. This capability isespecially useful if you are not sure where to place an exit point. You can createone dynamically and try it out to see if its placement is appropriate. If you findthat the exit point is not in the right place, you can use the MODIFY EXITcommand to change its location or to alter the list of parameters that your exitroutine receives.

Once you determine where to place an exit point in this way, it might be prudentto use the HCPXSERV macro to create a formal exit point. That way, changes thatare made to the CP module through the service process or by new releases ofz/VM are less likely to affect the continued operation of your customizations.

However, you may decide to always install your exit points dynamically. Forexample, if you simply want to gain control whenever some entry point is called,you may be able to create dynamic exit definitions that rarely need to be changed.In this case, you can use DEFINE EXIT configuration file statements to do thisevery time the system is IPLed.

Dynamic exits provide a convenient way to collect diagnostic or other informationor to handle many situations in which the flow of control of a CP module does notneed to be changed extensively. As explained in “Standard Return Codes” on page108, a dynamic exit has only limited ways to affect the flow of the module thatcontains the exit point. Of course, in some situations a judiciously placed exit pointcan allow an exit routine to alter conditions so that the flow of control is affected,

Migrating


but this is not always possible and might reduce the long-term maintainability ofyour customization. Where dynamic exits do not meet your needs, use formalexits.

In general, you should not create exits in CP module code paths where any of thefollowing conditions hold:v PFXTMPSV or PFXBALSV is in use.v A loss of control cannot be tolerated.v R11 does not point to a VMDBK.v Early in system initialization.v Late in system termination.v Performance-sensitive code is executing.

Front-end an Existing Diagnose CodeCertain IBM-supplied Diagnose codes provide multiple services selected by asubcode passed to the Diagnose code routine. At some point, you may decide toextend the use of an IBM-supplied Diagnose code by creating a local modificationin order to add a new subcode. To do so would have required source changes tothe IBM-supplied module for the Diagnose code. This source code change, ofcourse, is what you want to avoid.

An alternative approach might be to front-end the IBM Diagnose code routine withyour own. In this way, you can add functional changes but avoid sourcemodifications to IBM code.

Suppose that you want to add subcode X'xx' to DIAGNOSE code X'14'. The logicfor your new routine would be something like this.

enterget the subcodeselectwhen( subcode = X’xx’ )

then doprocess itend

otherwisedocall the original diag x’14’ routine, HCPDRDERend

endreturn

Once you have isolated your functional change, you can use configuration filestatements or CP commands (CPXLOAD, MODIFY DIAGNOSE) to provide yourfunctional change dynamically. In particular, MODIFY DIAGNOSE can be used tochange the entry point name that will be given control to handle the Diagnosecode. This enables you to direct control to your new routine which would then callthe IBM-supplied routine if appropriate.

Front-end an Existing CP CommandYou may have local modifications on your system that add function to an existingCP command. Again, you need to examine the code changes that you have madewith the thought of isolating your change from CP source code.

Suppose that you wish to perform additional checking for some commandoperand, for example, the SYSTEM operand on a PURGE RDR command. Once

Migrating

Chapter 2. Migrating Your Local Modifications 9

again, front-ending an IBM routine enables you to perform additional processingwhile avoiding changes to CP source code. In your routine, you would parse thecommand and perform whatever additional processing you wish. If all wasacceptable, you would call the original IBM routine. The logic for your new routinewould be something like this.

entersave GSDBK fieldsparse the command, performing necessary validationif passed,then call the original command routineelse reject the command

exit

Once you have isolated your functional change, you can use configuration filestatements or CP commands (CPXLOAD, MODIFY COMMAND) to provide yourfunctional change dynamically. In particular, MODIFY COMMAND can be used tochange the entry point name that will be given control to handle the command.This enables you to direct control to your new routine which would then call theoriginal IBM routine if appropriate.

Eliminating Source ModificationsThere are ways to eliminate many of the small source modifications that you mayhave made as part of providing new commands, new Diagnose codes and newroutines for CP.

Command Table UpdatesPrior to VM/ESA® version 2, adding a new command to the system generallyinvolved using the COMMD macro to create a command table entry to one of thefollowing CP source modules:v HCPSET for a new SET subcommandv HCPQUY for a new QUERY subcommandv HCPCOM for other commands

The source modifications you have made to the command tables can be eliminatedby using the DEFINE COMMAND command or configuration file statement. Thiswill dynamically make changes to the system so that you do not have to codestatic changes in the CP routines.

Diagnose Code Table UpdatesPrior to VM/ESA version 2, adding a new user Diagnose code to the systemgenerally involved making an update to one of the following CP source modules:v HCPHVB for handling a Diagnose code in the user rangev HCPHVC for handling a Diagnose code in the IBM rangev HCPDGN for defining a Diagnose code in the IBM range

The source modifications you have made to the Diagnose code routines can beeliminated by using the DEFINE DIAGNOSE command or configuration filestatement. This will dynamically make changes to the system so that you do nothave to code static changes in the CP routines.

Defining Linkage Attributes for New ModulesYou generally define the linkage attributes for your new module by making asource modification to the IBM-supplied HCPMDLAT MACRO. To eliminate the

Migrating


need for this source modification, you can define a component ID to which yourchanged routines can belong and make use of the alternate MDLAT support. Foradditional information on using the HCPCMPID macro to define a component ID,see Chapter 3, “Creating a Dynamically Loaded Routine,” on page 13. Foradditional information on coding and using an alternate MDLAT see, Chapter 3,“Creating a Dynamically Loaded Routine,” on page 13.

Selecting a Name for New ModulesFor new modules that you may have previously created for your own use, youmost likely selected a module name that begins with the characters HCP. HCP isthe component ID that is associated with CP modules that IBM ships. Althoughyou can certainly choose to continue to use this naming convention, you will stillhave to contend with any naming conflicts that arise should the module name youhave selected be used by IBM in the future. To avoid the need to rename routinesin the future, you may want to consider defining your own 3 character componentID by using the HCPCMPID macro. You can then use your own component ID aspart of the name you select for your routine. For additional guidelines on namingnew routines, see Chapter 3, “Creating a Dynamically Loaded Routine,” on page13.

Changes to the System Common AreaThe System Common Area (SYSCM) contains system-wide values such as countersand pointers that various CP functions use. You may have made sourcemodifications to SYSCM in order to share information between your own routines.You may be able to remove your dependency on these source updates by using theComponent ID Block (CMPBK).

This control block is designed for use by user code. The HCPXSERV macroprovides functions you can use to allocate, deallocate and serialize the use of thiscontrol block. For more information on the functions provided by the HCPXSERVmacro for use with CMPBKs, see Appendix E, “CP Exit Macros,” on page 191.

Changes to the CP Message RepositoryYou may have source modifications to the CP message repository. This can varyfrom a simple change, such as rewording existing message text, to something morecomplicated that would include changes to the number and order of substitutionvariables. You may also have placed new messages in the CP message repositorythat other local modifications utilize.

By creating your own local message repositories, you can eliminate your sourcemodifications to the IBM-supplied message repository. Additional information oncreating message repositories can be found in Chapter 7, “Defining and Using CPMessage Repositories,” on page 61 as well as in Appendix G, “Understanding theCP Message Repository,” on page 231.

Dynamically Loaded RoutinesRoutines that are dynamically loaded are treated like IBM-written routines. Thismeans modules you have already developed that use standard HCPCALL linkageconventions and have dynamic saveareas can often be dynamically loaded withoutrequiring significant changes. On the other hand, routines you have developed thatare entered by some means other than a dynamic call or that use static saveareaswill probably require significant rework.

Migrating

Chapter 2. Migrating Your Local Modifications 11

As a starting point, review Chapter 3, “Creating a Dynamically Loaded Routine,”on page 13, which describes, in general, what you need to do to create dynamicallyloaded CP routines. If you already have your own CP module, and you areplanning to convert this module so that it can be dynamically loaded, here is a listof common areas to focus on:v HCPENTER should specify CALL and SAVE=DYNAMIC.v HCPCALL should specify TYPE=INDIRECT and CALLFAIL on all calls to

routines that you plan to dynamically load.v Remove adcon references in the CP nucleus to fields in routines you plan to load

dynamically.v Use HCPCONSL to display messages from a message repository.v Use HCPTRANS to translate virtual addresses to their logical, real, or absolute

counterparts. Do not use HCPTRANS to get the Host Real Address from a HostLogical Address; use the LRAG instruction.

Migrating


Chapter 3. Creating a Dynamically Loaded Routine

This section describes some common issues you should consider when creating adynamically loaded routine. As you design your dynamically loaded routine, thereare a number of issues that will arise that you must decide how to handle. Thefollowing is a list of issues for you to consider. After this list, the individual issuesare discussed in more detail to help you make your decision.

The primary question you need to ask yourself is: “How will my routine interfacewith the rest of CP?” That is:1. From where will I get my input data?v Input in registersv Input located by addresses in registersv Input in predefined locations in host storage

2. To where will I put my output data?v Output in registersv Output located by addresses in registersv Output placed into predefined locations in host storage

3. What type of addressing mode should I use?v 31-bit or 64-bit

4. What, if any, CP Services should I use?v HCPCMPIDv HCPPROLGv HCPENTERv HCPEXITv HCPCALLv HCPLCALLv HCPLENTRv HCPLEXITv HCPCONSL

5. Will I be calling other dynamically loaded routines from this routine?v HCPCALL TYPE=INDIRECT

6. How big can I make my routine?v 4 KB or more?

7. What should I name my routine?v HCPCMPIDv HCPPROLGv HCPENTER

8. What linkage attributes should I specify for my routine?v HCPCMPIDv xxxMDLAT

9. How are addresses resolved?v Address constants in the nucleus

10. Can I add my own CP IUCV System Service?


11. What does the CPXUNLOAD ASYNCHRONOUS operand mean?12. What does the CPXLOAD CONTROL operand imply?13. What happens if I make a programming error?

Input DataDeciding how to provide input data to any routine is an exercise where youattempt to decide between simplicity and flexibility. Typically, passing data inregisters is the simplest of mechanisms. There is no need for both the callingroutine and the called routine to use an elaborate parameter list.

However, passing data in registers, while simple, is also quite restrictive. Thenumber of registers available is quite limited, which in turn limits the amount ofdata and constrains data formats. For example, you might decide to pass in aregister to another routine the 4-byte disk block number of an FBA (Fixed BlockArchitecture) disk. Later, if you extend the routine's capabilities to include supportof CKD (Count-Key-Data) disks, you would need to pass a 5-byte data item (2-bytecylinder, 2-byte track, 1-byte record). The interface between the routines must nowbe made radically different, requiring one register for an FBA disk, and 2 registersfor a CKD disk. Such interface differences readily lead to programming errors.Moreover, if this interface (1 register versus 2 registers) were being changed for alarge number of routines, you might find yourself spending much time modifyinginterfaces between many related routines for the purposes of safety andconsistency, even though these other routines might not have been directly affectedby the change to the new interface.

Passing addresses of data in registers is perhaps more flexible. Then, if the lengthor the type of data changed, as in the example above, the interface would not. Theaddress would simply point to a longer data item.

You can further extend the parameter passing flexibility with a slightly morecomplicated interface where one register is used to point to a list of addresses,each of which then points to a data item. Such an interface is slightly morecomplicated, but readily extended as needs change. To help manage thiscomplexity, you can provide mapping macros and DSECTs that all related routineswould include. Management of changes to the interfaces would then be simplifiedby changes to the common mapping macros and DSECTs.

Occasionally, you find that the data items that the routine will use are inpredictable locations in storage. For example, the data may be located in a systemcontrol block (say, in SYSCM, the System Common Area or in a VMDBK). In sucha case, the routine need not be passed anything, because it can locate the dataitself. An example of such a routine is HCPSCCFD, which parses the next token ina CP command. When called, HCPSCCFD knows that the area to work with islocated by the VMDBK. The calling routine does not need to pass to HCPSCCFDany additional data. (We ignore the fact that the address of the VMDBK is inregister R11, because this fact is common to most of CP.) This interface is simplebut inflexible. If you need to extract a token from some other area that does notcontain the active CP command, you cannot use HCPSCCFD. Another routinemust be used, in this case, HCPSCCFG. Is it better to provide 2 routines(HCPSCCFD and HCPSCCFG) that do exactly the same thing but get the addressof the data area from different places? You be the judge.

When deciding how to pass data to other routines, also consider the ultimatesource of the data. If the data can be relatively stable, consider using an external

Creating Routines


repository (for example, a CMS file) to store the data. By storing the data in a waythat affords you the ability to use CMS tools (XEDIT, COPYFILE, SENDFILE,RECEIVE, etc.), you may be able to assist the distribution of the data to othersystems, which may be beneficial. For more information on standard input dataprovided to CP exit routines, see Appendix A, “IBM-Defined CP Exit Points,” onpage 103.

Output DataAll of the discussion on Input Data applies here, as well. But in addition, you mayneed to consider whether the calling routine should allocate storage for the outputdata, or whether the called routine should. And, if the called routine should, howit should return the address of the newly-allocated storage to the calling routine.

Addressing ModeThe hardware on which z/VM runs provides an addressing mode called AccessRegister mode (AR mode). CP provides macros that assist you when writingroutines that use AR mode. In AR mode, Dynamic (or, automatic) AddressTranslation (DAT) of AR-qualified addresses is a standard hardware facility. ARmode is a requirement for accessing central storage when only the Host RealAddress is available.

Address constants are created directly when you write the source code for aroutine and use the appropriate DC (Define Constant) statement or indirectly whencertain macros (for example, HCPCALL) are expanded during execution of theIBM High Level Assembler. An address constant is resolved during SYSGEN byHCPLDR when it builds the CP nucleus, during which time it determines thelocations of symbols to which the address constants refer, and during dynamicloading by CPXLOAD when it loads a file, during which time it does essentiallythe same thing as HCPLDR. After HCPLDR finishes the SYSGEN process, anyaddress constant whose target cannot be found is ignored and an error message isdisplayed; nothing is remembered regarding that unresolved address constant.After CPXLOAD finishes its load process, any address constant whose targetcannot be found is remembered so that it can be resolved by a later CPXLOADoperation.

Addresses in CP for control blocks, modules, and other “CP things” are generallyHost Logical Addresses. Addresses in CCWs, SCMBKs, Control Registers, andother “hardware things” are generally Host Real Addresses or Host AbsoluteAddresses. AR mode using the ALET provided in field PFXRSAL can be used totouch central storage using a real address.

Routines loaded by CPXLOAD are treated exactly as if they were part of the CPnucleus. Address constants to data items in a routine loaded by CPXLOAD areresolved to Host Logical Addresses by the dynamic loading process.

AttributesModules and their entry points have a number of attributes, all of which are usedby linkage macros to generate proper instruction sequences. These attributes arespecified in the HCPMDLAT macro, or the equivalent Component ID macroxxxMDLAT.

Creating Routines

Chapter 3. Creating a Dynamically Loaded Routine 15

Register StylesA CP module may have one of two register styles:v ShortReg (the default)v LongReg

ShortReg modules use 32-bit registers and LongReg modules use 64-bit registers.This module attribute is declared by the MDLATENT macro. A module's entrypoints may use different styles.

Calls between modules of different styles are supported. The name and format ofthe save area block depends on the styles of the called and calling modules.ShortReg entry points use SAVBK COPY to map their register save areas. LongRegentry points use SVGBK COPY to map their register save areas. The SVGBKprovides areas to save contiguous 64-bit general registers, and the SAVBK providesareas to save discontiguous parts of 64-bit registers. As a result, LM and STMinstructions must be used with care.

Except under extraordinary circumstances, a ShortReg module must not referenceor change the high-order four bytes of a large (64-bit) register. While in general amodule's entry points use the same register style as the module itself, the two maybe different (for example, to facilitate calls from modules that use another style). Inthis case, once the entry to the module has been effected and any parameters havebeen transformed, the bulk of the module's logic is expected to use the registerstyle declared for the module. While this is not enforced, it is good practice.

Entry points that are invoked with an indirect call (HCPCALL TYPE=INDIRECT)must be ShortReg. This includes CP Exits and dynamically loaded modules thatreplace or define new commands and Diagnose functions.

Addressing ModeAddressing Mode, or Amode, describes the settings of PSW bits 31-32. ModuleAmode attributes are:

Amode31The module and its entry points run in 31-bit addressing mode.

Amode64The module and its entry points run in 64-bit addressing mode. Thisrequires the LongReg attribute.

AmodeVARThe module is unpredictable as to whether it is in 31-bit or 64-bitaddressing mode. A default entry point attribute is required. This requiresthe LongReg attribute.

AmodeINTThe module and its entry points run in 31-bit addressing mode, except thatthe addressing mode may be changed. However, the module will ensurethat any addressing mode manipulation will not be exposed to any macroor to any other module.

There are also specific Entry Point attributes for addressing mode. See “Entry PointAttributes” on page 17.

The CP default is Amode31, which means that 31-bit addressing mode is in effecteverywhere.

Creating Routines


To assist the programmer, macros will use the Amode attribute to generate codethat does (or does not, depending on the situation) save and restore the addressingmode bits.

Translation ModeTranslation Mode, or Tmode, describes the settings of PSW bits 16-17. ModuleTmode attributes are:

TmodeSTDThe module and its entry points run in Primary Space mode and do notalter ARs.

TmodeARThe module and its entry points run in Access Register mode and do alterARs.

TmodeVARThe module is unpredictable as to whether it is in AR mode or PrimarySpace mode. A default entry point attribute is required.

TmodeINTThe module and its entry points run in Primary Space mode, except thatthe ARs may be used. However, the module will ensure that anymanipulation of ARs or of the PSW bits 16-17 will not be exposed to anymacro or to any other module.

There are also specific Entry Point attributes for translation mode. See “Entry PointAttributes.”

Historically, CP ran very nearly in the TmodeINT style, which meant that only themodule itself knew how the Access Registers were being used. Macros knewnothing, so no help was forthcoming in code generated by linkage macros.

Now, the CP default is TmodeSTD, which means that ARs are not altered by themodule. This means that a module that is using ARs can rely on them not beingaltered by any subroutine that it calls. In fact, just like modifications to generalregisters, no modifications to Access Registers should be seen by any other moduleunless disclosed as a documented interface.

To assist the programmer, macros will use the Tmode attribute to generate codethat does (or does not, depending on the situation) save and restore ARs so thatthe rule “no modifications to ARs will be exposed” is enforced across all linkagemacros.

Entry Point AttributesWhile a module's attributes are considered to be module-wide, each entry pointmay have different attributes. For example, a module may usually run with theTmodeAR attribute (that is, always in AR mode), but the module may have anentry point that is declared to be entered in Primary Space mode. This entry pointmust be declared in xxxMDLAT as TmodeSTDent. The “ent” suffix distinguishesthis as an “entry point attribute”. Although most module attributes imply defaultentry point attributes, module attributes are not entry point attributes.

The entry point attributes for addressing mode, translation mode, and register styleare:

Amode31entThe entry is in 31-bit addressing mode.

Creating Routines


Amode64entThe entry is in 64-bit addressing mode.

AmodeVARentThe entry is unpredictable as to whether it is in 31-bit or 64-bit addressingmode. The programmer must write code to handle either case.

TmodeSTDentThe entry is in Primary Space mode and will not alter ARs.

TmodeARentThe entry is in Access Register mode and will alter ARs.

TmodeVARentThe entry is unpredictable as to whether it is in AR mode or PrimarySpace mode. The programmer must write code to handle either case.

ShortRegEntThe entry will use only the low halves of the general registers. The entrymust be Amode31ent.

LongRegEntThe entry will use the entire 64 bits of the general registers.

The following table shows the implied default entry point attributes thatcorrespond to module attribute settings and defaults:

Module Attribute Implied Default Entry Point Attribute

Amode31 Amode31entAmode64 Amode64entAmodeVAR (none)AmodeINT Amode31entTmodeSTD TmodeSTDentTmodeAR TmodeARentTmodeVAR (none)TmodeINT TmodeSTDentShortReg ShortRegEntLongReg LongRegEnt

The module attributes are true everywhere throughout the module at everymacro invocation, except for HCPENTER and HCPEXIT, where only the entrypoint attributes are assumed.

This is a very subtle but important point. A combination like TmodeARTmodeSTDent means that the entry point will be in Primary Space mode, butoutside of HCPENTER and HCPEXIT every macro will be expected to be in ARmode. The entry point's HCPENTER will generate code for Primary Space mode,but no SACF SACAR instruction will be generated by the HCPENTER macro. Theprogrammer must ensure that this kind of mismatch is resolved at runtime bycoding the necessary SACF instructions, both after HCPENTER and beforeHCPEXIT.

Environment at Enter and ExitThe runtime environment at entry must match that at exit. So a TmodeARent entrypoint will be in AR mode when the HCPENTER macro finishes and must be in ARmode when the HCPEXIT macro is executed. If you change the mode for anyreason, you must reestablish the environment before HCPEXIT.

Creating Routines


Using CP ServicesAny CP service is available to a module that was loaded by CPXLOAD, as long asa simple HCPCALL--HCPEXIT protocol is used. If other mechanisms oftransferring control are attempted (for example, HCPGOTO), results are officially“unpredictable”. What this means is that such an environment is too complex topredict the outcome. Certain uses of HCPGOTO to transfer execution to thedispatcher (HCPDSP) and stacked CPEBKs to resume execution may, in fact, work.Only by exhaustive testing will you be able to determine this.

The discussion here of CP macros is not exhaustive. Only those operands that areconsidered the most likely to be used will be discussed.

Defining System Linkage to Your RoutineIn order for the standard CP linkage macros HCPPROLG, HCPENTER, HCPCALL,and HCPEXIT to generate the correct assembler instructions in your routine, youmust define the routine's linkage attributes. This is done by:1. Specifying a HCPCMPID macro at the beginning of your routine. The purpose

of the HCPCMPID macro is to specify the component ID of which your routineis a part. The component ID is then used to identify which xxxMDLAT macro(also called “alternate” MDLAT macro) is to be searched for your routine'slinkage attributes.

2. Coding a xxxMDLAT macro. The format of the xxxMDLAT macro is muchsimplified over the format of IBM's HCPMDLAT MACRO. Here is an exampleof an alternate MDLAT macro called EXTMDLAT that defines your routine thatis called EXT00E1:

MACRO&LABEL EXTMDLAT &EPNAME

MDLATHDR &EPNAMEMDLATENT EXT00E1,MODATTR=(MP,DYN),CPXLOAD=YESMDLATTLRMEXITMEND

The associated HCPCMPID macro in your routine would be coded:HCPCMPID COMPID=(EXT)

3. Placing your xxxMDLAT macro where the assembler can find it when youassemble your routine. The easiest way to do this is to place the xxxMDLATmacro right in your routine as an “in-line macro definition”. Because yourroutine should define the macro before it is used, it is best to put yourxxxMDLAT macro as the first thing in your routine's source file.Another place to put your xxxMDLAT macro is in one of the maclibs that theassembler uses when it assembles your routine. If you are using VMFHASM orVMFHLASM, place your macro in one of the maclibs that are specified on theMACS statement of the control file.

Discussion of the HCPPROLG MacroThe HCPPROLG macro establishes certain attributes for the entire module. Someof these attributes are:v The module name

The label on the HCPPROLG establishes the module name, which is also theControl Section (CSECT) name.

v REUSABLE or REENTRANT or REFRESHABLE

Creating Routines


The goal here should be REFRESHABLE. This means that CP could reload acopy of the module at any time without damage. This means that, once loaded,the module may never be altered. Unfortunately, any indirect linkage byHCPCALL causes the Indirect Call Request Block in the module to be changed.Because REFRESHABLE may be impossible, the next best choice isREENTRANT. This implies that any number of concurrent tasks may beexecuting instructions in the module simultaneously. In a multiprogramming,multiprocessing system, this should be the case. REENTRANT tends to beinterpreted as “unchanging”. This is a good interpretation. However, techniquesexist that allow changes to the module while retaining reentrancy. For simplicity,forget about this and just never change the module.REUSABLE is the next least desirable. It means that only one task may beexecuting instructions in the module at a time. After that task exits the module,another may enter it. Such serialization could seriously hamper performance andthroughput.NONREUSABLE is the least desirable. It means that only one task may executeinstructions in the module. After that task exits the module, no other may enterit.Realistically, CP treats everything as REENTRANT, so you should code to thatlevel.

v DIRECT or INDIRECTHCPCALL=DIRECT is typical throughout all of CP.HCPCALL=INDIRECT should be specified for any dynamically loaded module.For information about the meaning of direct and indirect linkage, see“Discussion of the HCPCALL Macro” on page 22.

v Base registerA module should need only one base register, and it must be R12. So, specifyBASE=(R12) on your HCPPROLG macro.

v CopyrightCopyright information may also be specified on the HCPPROLG macro. Ifspecified, instructions will be generated to store the copyright data in theresulting TEXT file so that anyone who looks at storage or at a system dumpwill see the copyright data.To specify copyright year, use the COPYR= keyword. To add textual data to thecopyright year, also include the COPYRID= keyword.

Here are some examples of HCPPROLG macros:VREPOS HCPPROLG ATTR=(REENTRANT),HCPCALL=INDIRECT, X

BASE=(R12)

JAMSAM HCPPROLG ATTR=(REENTRANT),HCPCALL=INDIRECT, XCOPYR=(1995),COPYRID=’My Copyright’, XBASE=(R12)

Discussion of the HCPENTER MacroThe HCPENTER macro defines an executable entry point into the module. Thename of the entry point is the label on the HCPENTER macro. This name muststart with the same 6 characters as the label on the HCPPROLG macro, plus 1 or 2additional characters.

Operands on the HCPENTER macro indicate what instructions should begenerated for entry into the module:

Defining System Linkage


v CALLHCPENTER can describe a number of types of entry into the module. But alldynamically loaded modules are entered as a result of an HCPCALL macro.Always specify CALL as the first operand.

v SAVE=DYNAMICCP has two types of save area control blocks:– Static– DynamicAll dynamically loaded modules must use dynamic save area control blocks.Always specify SAVE=DYNAMIC as the second operand.

Here are some examples of HCPENTER macros:VREPOSMS HCPENTER CALL,SAVE=DYNAMIC

JAMSAMDL HCPENTER CALL,SAVE=DYNAMIC

Discussion of the HCPEXIT MacroThe HCPEXIT macro defines the exit from a module. The name of the entry pointis included in an operand of the HCPEXIT macro. Also, you can direct whether thecurrent condition code should be preserved and returned to the caller. Theoperands include:v EP=

The name of the entry point that was called and for which the exit and return tothe caller is being made is specified by the EP= keyword. Multiple entry pointscan exit through a single HCPEXIT macro. If so, all would be included in theEP= list of entry points.

v SETCC=<YES|NO|0|1|2|3>The SETCC= keyword indicates how the condition code should be treated.– SETCC=YES, also the default, indicates that the present condition code should

be preserved and returned to the caller.– SETCC=NO indicates that the present condition code need not be preserved

and returned to the caller. The condition code returned to the caller isunpredictable.

– SETCC=0 indicates that condition code 0 should be set and returned to thecaller.




Using the condition code to return information to the calling program provideslimited capability because the possible values are restricted to 4 values. This mayconstrain future extensions to a routine. Serious thought should be given tousing return codes to return information to the calling program. To set a returncode of zero for the caller, place the value zero into the field SAVER15:

SLR R15,R15ST R15,SAVER15

Here are some examples of HCPEXIT macros:



HCPEXIT EP=VREPOSMS

HCPEXIT EP=(JAMSAMDL,JAMSAMLD),SETCC=NO

Discussion of the HCPCALL MacroThe HCPCALL macro can be used to call a routine by using its address or byusing its name. These two methods are called “direct” and “indirect” linkage,respectively. Direct linkage is further broken down into “call-by-attribute” and“call-by-register”.

HCPCALL TYPE=DIRECTThis is the typical method used within CP to call another routine. In fact, this is sotypical that you never even specify TYPE=DIRECT. Part of the processing of theHCPCALL macro is to identify the attributes of both the calling routine and thecalled routine, and then to generate instructions appropriate to the interfacebetween the two routines. For example, the caller might have the attribute MP,meaning that it may execute on any processor in a multiprocessor system, whilethe called routine might have the attribute NONMP, meaning that it may executeonly on the master processor. Because a switch from alternate processor to masterprocessor may be needed, based on these attributes, the HCPCALL macro willgenerate instructions to go to the appropriate entry in HCPSVC to affect thelinkage. A different set of attributes for the calling routine and the called routinewould cause HCPCALL macro to generate instructions to go to a different entry inHCPSVC.

The following table shows the various linkage decisions that the HCPCALL macromust make. Which row is chosen could depend on such details as:v The called routine's namev The called routine's addressv The calling routine's namev Keywords specified on the HCPCALL macro invocation

Table 2. Various Linkage Decisions

From= To= Trace=

MP MP NO

MP MP YES

MP NONMP NO

MP NONMP YES

NONMP MP NO

NONMP MP YES

NONMP NONMP NO

NONMP NONMP YES

Legend:From - capability of callerTo - capability of calleeSave - type of SAVBK requested by calleeTrace - trace entry is desiredMP - multiprocessor capableNONMP - not multiprocessor capable



The decision by HCPCALL will be rather automatic if the called routine isspecified by name or if the attributes of the called routine are explicitly providedto HCPCALL. If the routine name is provided, HCPCALL will use HCPMDLAT toidentify the routine's entry point attributes, and generate code accordingly. Or, ifno routine name is provided but its attributes are, HCPCALL will use the suppliedentry point attributes to generate code. These mechanisms, where the entry pointattributes can be deduced or are specified, are examples of “call-by-attribute”.

If neither a name (so attributes cannot be inferred) nor attributes are specified, andonly the address of the routine is supplied, HCPCALL will use a technique knownas “call-by-register”. HCPCALL will determine the proper linkage to use to call theroutine based on a vector of addresses provided by the called routine. The onlyrequirement is that the called routine be defined as an HCPENTERSAVE=DYNAMIC entry point.

Call-by-register can be used to call any SAVE=DYNAMIC routine. Call-by-registercannot be used to call any other routine. For these others, some form ofcall-by-attribute must be used.

Here are a few examples where TYPE=DIRECT is assumed by default:1. HCPCALL HCPCVTBD

In this example, HCPCALL knows that the linkage requirements forHCPCVTBD requires a direct branch to HCPCVTBD, without the dynamicallocation of a SAVBK. Because HCPCALL can determine all of the attributes ofthe linkage, the proper linkage will be generated.

2. L R15,=A(HCPCVTBD)HCPCALL (R15),NAME=HCPCVTBD

In this example, the address of HCPCVTBD is already in register 15, soHCPCALL can use it. And because HCPCALL knows that the routine to call isHCPCVTBD, HCPCALL can generate the remainder of the linkage instructionscorrectly. Because HCPCALL can determine all of the attributes of the linkage,the proper linkage will be generated.

3. L R15,=A(HCPCVTBD)HCPCALL (R15),ATTR=(NONE,LEAF,LRegE,AmVARe,TmVARe)

Again, the address of HCPCVTBD is already in register 15, ready to use.Because the routine's attributes are specified, HCPCALL will generate linkageinstructions correctly.Notice that the routine's attributes are entry point attributes, not moduleattributes. 'LRegE' is correct, but 'LReg' would be wrong. LongReg is not anentry point attribute.

4. L R15,=A(HCPCVTBD)HCPCALL (R15)

Again, the address of HCPCVTBD is already in register 15, ready to use.Because no attributes can be inferred, and none are specified, HCPCALL willexpect SAVE=DYNAMIC and will look for the vector of addresses in order todetermine what linkage to use. Because HCPCVTBD is not SAVE=DYNAMIC,no such vector exists. The wrong linkage protocol will result, and CP willcertainly crash.

Always ensure that HCPCALL can determine the proper entry point attributes ofthe routine that you are calling.

HCPCALL TYPE=INDIRECTThis is another typical method used within CP to call a routine. TYPE=INDIRECTis used by CP to call routines for processing the following:



v Commands, if the routine was dynamically loadedv Diagnose codes, if the routine was dynamically loadedv Exits, for all exit routines

Just like HCPCALL TYPE=DIRECT discussed above, HCPCALL TYPE=INDIRECTcan generate the proper linkage if the routine name is known. If the routine is inthe nucleus, then HCPCALL can convert the INDIRECT request to a DIRECTrequest and avoid the additional overhead of the INDIRECT request. If the name isnot supplied, or the name is not in the nucleus, then HCPCALL will generate theindirect linkage.

The protocol for indirect linkage is that register 15 contains the address of theIndirect Call Request Block (ICRBK) that names the routine that you want to call.CP will use the contents of the ICRBK to locate the linkage attributes for the calledroutine, and proceed accordingly. By specifying the name of the routine to call, youcan ensure that HCPCALL will generate the proper direct linkage to a routine inthe nucleus by using its address, or will generate the proper indirect linkage usingan ICRBK.

Because the purpose of the indirect linkage is to provide a safe calling sequenceeven if the routine being called does not exist, an additional keyword is alwaysrequired whenever TYPE=INDIRECT is specified. That additional keyword is theCALLFAIL= keyword. This keyword indicates the label for HCPCALL to branch toif the calling sequence cannot be completed. CALLFAIL= is not for the situationwhere the calling sequence was successful and the called routine returned an errorindication but is for the situation where the called routine was not entered. If thisoccurs, then register 15 can be examined to determine why the call attempt failed:

4 The target could not be called because:v It was marked for CPXUNLOAD.v It had not completed CPXLOAD.v The address translation failed.

8 Control blocks used by HCPCALL did not match; for example, the ICRBKand its ICLBK had different entry point names.

12 The attempted call was required to be performed without any loss ofcontrol of the processor, but a loss of control of the processor would havebeen necessary.

Here are a few examples where TYPE=INDIRECT is specified:1. HCPCALL HCPCVTBD,TYPE=INDIRECT,CALLFAIL=errlabel

In this example, HCPCALL knows that the linkage requirements forHCPCVTBD require a direct branch to HCPCVTBD, without the dynamicallocation of a SAVBK. Because HCPCALL can determine all of the attributes ofthe linkage, the proper linkage will be generated. Even thoughTYPE=INDIRECT was specified, HCPCALL knows that an indirect linkage isnot necessary and will generate a direct linkage.

2. L R15,=A(HCPCVTBD)HCPCALL (R15),NAME=HCPCVTBD,TYPE=INDIRECT,CALLFAIL=errlabel

In this example, the address of HCPCVTBD is already in register 15, soHCPCALL can use it. And because HCPCALL knows that the routine to call isHCPCVTBD, HCPCALL can generate the remainder of the linkage instructions.Because HCPCALL can determine all of the attributes of the linkage, the proper



linkage will be generated. Even though TYPE=INDIRECT was specified,HCPCALL knows that an indirect linkage is not necessary and will generate adirect linkage.

3. L R15,=A(HCPCVTBD)HCPCALL (R15),TYPE=INDIRECT,CALLFAIL=errlabel

In this example, HCPCALL does not know the name of the routine to call.Therefore, HCPCALL has no other choice but to generate in indirect linkage.Unfortunately because this example specifies an indirect call, HCPCALLrequires that register 15 contain the address of the ICRBK. Register 15 does not;register 15 contains the address of the HCPCVTBD entry point. This mismatchwill likely result in a CP abend.

In general, always tell HCPCALL the name of the routine that you are calling.

Usage Note for HCPCALLHCPCALL ensures that no extra positional parameters are specified. If any arefound, the following message is displayed:MNOTE 8, ’Extra positional parameter: pppppppp’

If pppppppp is blank, this message could indicate that incorrect continuation wasused on the HCPCALL invocation.

Discussion of the HCPLCALL MacroThe HCPLCALL macro provides a convenient mechanism to call a local routineinside a module. Entry to a local routine typically uses a dynamic save area block.Because HCPLCALL uses the services of HCPCALL, all of the discussion underHCPCALL applies here as well.

Here are some examples of HCPLCALL macros:1. HCPLCALL SQUEEZE

HCPLCALL knows the linkage requirements for all local routines. Register 15will be loaded with the address of SQUEEZE and the linkage will beperformed.

2. LA R15,SQUEEZEHCPLCALL (R15)

In this example, the address of SQUEEZE is already in register 15, soHCPLCALL can use it.

3. L R15,=A(SQUEEZE)HCPLCALL (R15)

In this example, the address of SQUEEZE is in register 15, and HCPLCALL willuse it.

In general, always tell HCPLCALL the name of the routine that you are calling.

Discussion of the HCPLENTR MacroThe HCPLENTR macro defines an executable entry point in the module for a localroutine. The name of the entry point is the label on the HCPLENTR macro. Thisname may start with any valid assembler language label. It does not need to berelated to the HCPPROLG or HCPENTER macros.



If no operands are specified on the HCPLENTR macro, HCPLENTR will generateentry linkage for HCPLENTR CALL,SAVE=DYNAMIC. For a stacked goto to a local entrywhere there is no need to define an external symbol, HCPLENTR GOTO should beused.

Here are some examples of HCPLENTR macros:LOOKUP HCPLENTR

Q HCPLENTR

Discussion of the HCPLEXIT MacroThe HCPLEXIT macro defines the exit from a local routine entered by HCPLENTR.The name of the entry point is not mentioned. In fact, HCPLEXIT takes nooperands. The HCPLEXIT macro expands as if the EP= keyword and SETCC=YESwere specified.

Here is the only way to write an HCPLEXIT macro:HCPLEXIT

Discussion of the HCPCONSL MacroYou should always use HCPCONSL to write a message or a response or to readinput from the terminal. There are three operations that you can request fromHCPCONSL.

In the discussions that follow, “<something>” means that you have specified avalue, but not “NONE” or any equivalent value.1. Write data or read data or both?v Write: HCPCONSL WRITEv Read: HCPCONSL READv Both: HCPCONSL PROMPTThis discussion will address only WRITE operations.

2. Writing what kind of message?HCPCONSL can generate different types of messages. CP will direct themessage based on its type. But sometimes, you need to direct the messagebecause CP does not fully meet the challenge. This extra processing is true forthe IMSG type of message.v Using the user's EMSG setting

HCPCONSL WRITE,DATATYPE=EMSG

Using the value set for EMSG, CP will format and direct the message:– For SET EMSG ON, CP will format the message to contain both the error

message heading and the error message text.– For SET EMSG OFF, CP will not generate the message.– For SET EMSG TEXT, CP will format the message to contain only the

error message text.– For SET EMSG CODE, CP will format the message to contain only the

error message heading.– For SET EMSG IUCV, CP will format the message to contain both the

error message heading and the error message text.v Overriding, partially, the user's EMSG setting



HCPCONSL WRITE,DATATYPE=FULLEMSG

CP will format the message to contain both the error message heading andthe error message text.

v Using the user's IMSG settingHCPCONSL WRITE,

DATATYPE=IMSG

Here is a situation where you need to do some extra work to make surethat the message is not generated when it should not be. Even if SET IMSGOFF is in effect, CP will still generate the message. It is up to you to checkfor IMSG OFF and, if so, not generate the message in the first place. Tocheck the IMSG setting, test the VMDBK byte VMDMLVL for the flagVMDMIMSG. If on, then the IMSG should be generated.

TM VMDMLVL,VMDMIMSG Is IMSG wanted?BZ skip ..off, the answer is noHCPCONSL WRITE,

DATATYPE=IMSG

v Writing a command response, not a messageHCPCONSL WRITE,

DATATYPE=CMNDRESP

3. Writing data that you built, or writing data from a message repositoryv Writing data that you built

HCPCONSL WRITE,DATA=’--text--’

Writing such data does lack the flexibility of using a message repository, butthis is a quick and easy method of getting a message displayed.

v Writing data that you builtHCPCONSL WRITE,

DATA=(where,length)

Writing such data still lacks the flexibility of using a message repository.The value for “where” may be a label of a storage location where the datastarts (“label”) or a register, enclosed in parentheses, that contains theaddress of the storage location where the data starts (“(Rx)”).The value for “length” (the length of the data to display, in bytes) may be aself-defining term (“8” , “X'1F'”), an absolute value (“END-START”), or aregister, enclosed in parentheses, that contains the length of the data(“(Rx)”).

HCPCONSL WRITE,DATA=(LONGMSG,(R3))

v Writing data from a message repositoryHCPCONSL WRITE,

REPOSNUM=’MSmmmmvv’

For this format, the macro expansion will use the message number valuethat has been equated to the label “MSmmmmvv”. It is suggested that thislabel and its value match so as to avoid confusion.

MS123401 EQU X’00123401’ GoodMS123401 EQU X’00777706’ Bad

v Writing data from a message repositoryHCPCONSL WRITE,

REPOSNUM=label

The message number value will be found at the 4-byte field with label“label”.

v Writing data from a message repository



HCPCONSL WRITE,REPOSNUM=(Rx)

The message number value will be found in register “Rx”.4. Getting back the message number

A standard in CP is that a failed command return a return code, and that thereturn code match the error message number that explains the error condition.For example, if a command fails and generates the following error message,then that command should end with return code 45:

HCP045E $1 not logged on

However, the error message value is defined as a hexadecimal value and thereturn code is defined as a decimal number. You could figure out one from theother, or you can let the HCPCONSL macro do it for you by using theRETMSGNUM= keyword.v Specifying the return code result by label

HCPCONSL WRITE,REPOSNUM=<something>,RETMSGNUM=label

The message number value will be converted to a return code and storedinto the 4-byte field with label “label”.

v Specifying the return code result by registerHCPCONSL WRITE,

REPOSNUM=<something>,RETMSGNUM=(Rx)

The message number value will be converted to a return code and storedinto register “Rx”.

5. Performing substitution with data from a message repositoryA message is most useful if it can identify the operand, device, user ID,location, or other data item to which the message refers. Standard messagesare frequently built as message patterns so that such identifying detail can beinserted into the message pattern in order to create the final message. Thepieces of data to be inserted are known as “substitution text”. Substitution textis composed of individual fields each separated by a X'00' byte, all terminatedby a X'FF' byte. Each of these fields can be thought of as numbered 1, 2, 3,and so on. These are then substituted into the message pattern where thesubstitution indicator (character “$” with a numeric position number, as in“$1”, “$2”, “$3”, and so on) is located.The location of the substitution text is specified by the SUBDATA= keyword.Notice that a message repository number is required for such substitution.v Specifying substitution data by label

HCPCONSL WRITE,REPOSNUM=<something>,SUBDATA=label

The substitution text will be found at the storage location named by label“label”.

v Specifying substitution data by registerHCPCONSL WRITE,

REPOSNUM=<something>,SUBDATA=(Rx)

The substitution text will be found at the storage location located by theaddress in register “Rx”.

6. Whose message repository?



You can direct CP to retrieve message patterns from a standard systemmessage repository or from a local repository. This separation is made basedon the value of the component ID specified by the HCPCONSL macro. Oncethis decision has been made, CP then selects the repository according to thelanguage ID as established by the SET CPLANGUAGE command.v IBM's message repository

HCPCONSL WRITEREPOSNUM=<something>,

HCPCONSL WRITE,COMPID=’HCP’REPOSNUM=<something>,

Both of these formats indicate that the system message repository should beused.

v Getting the message pattern from a local repositoryHCPCONSL WRITE,

COMPID=’CCC’REPOSNUM=<something>,

The component ID is the 3 characters “CCC”.v Getting the message pattern from a local repository

HCPCONSL WRITE,COMPID=(Rx)REPOSNUM=<something>,

The 3-character component ID will be found at the storage location locatedby the address in register “Rx”.

7. Sending the data where?The message generated by HCPCONSL can be directed to storage or to anyuser ID on the system.v Writing to a GSDBK

HCPCONSL WRITE,REPOSNUM=<something>,DESTINATION=GSDBK,RETGSDBKADDR=(Rx)

v Writing to the operatorHCPCONSL WRITE,

DESTINATION=’OPERATOR’

Use the CP QUERY SYSOPER command to find the current operator userid.Use the CP SET SYSOPER command to change the userid of the primarysystem operator.

v Writing to wherever the user wants (terminal, Diagnose code X'8' buffer,IUCV buffer)

HCPCONSL WRITE

HCPCONSL WRITE,DESTINATION=*

v Writing to the terminal screenHCPCONSL WRITE,

DESTINATION=TERMINAL

v Writing to another user IDHCPCONSL WRITE,

DESTINATION=(Rx)

v Writing to another user IDHCPCONSL WRITE,

DESTINATION=label



Notice that the term 'OPERATOR' is delimited by single quotes ('), but theterm TERMINAL is not.

8. Waiting or not waiting?As you generate a series of messages, you will not know when they reach theuser's terminal (it might be in HOLDING, for example). Unless you ask CP todelay your processing, you will continue to execute and will continue togenerate messages. If you continue to run and continue to generate messages,the user will not be able to stop the stream of messages. In addition to gettingthe user upset, you will have wasted system resources generating unwantedmessages.To avoid these problems, your program needs to wait periodically in order forthe HCPCONSL macro to return a return code that indicates what ishappening with the delivery of the messages. The IOWAIT= keywordprovides this ability to wait. If the destination is not the terminal, then youwill not wait.v Waiting for each I/O to complete

HCPCONSL WRITE,IOWAIT=IOCOMP

This operand indicates that you want to delay until the I/O to the terminalhas completed. This will happen for each line. This operand may slowprocessing significantly if the terminal is connected over a slow network.

v Waiting only when the screen fillsHCPCONSL WRITE,

IOWAIT=SCREENFULL

This operand indicates that you want to delay only when the terminalscreen has filled.

v Not waiting for anythingHCPCONSL WRITE

HCPCONSL WRITE,IOWAIT=NONE

This operand, or lack of an operand, indicates that you do not want todelay execution.

9. Detecting if the user wants to you stopIn order to detect that the user wants a stream of messages to stop, the userwill typically press PA1. In order to detect this event, your program musthave some IOWAIT= specified.v Placing the return code into a storage field

HCPCONSL WRITE,IOWAIT=<something>,RETCODE=label

v Placing the return code into a registerHCPCONSL WRITE,

IOWAIT=<something>,RETCODE=(Rx)

The meanings of the possible return codes are:

00 Success

04 Disconnected

08 Interrupted by user

12 I/O error

16 Not logged on



20 Soft abend occurred10. Free flowing or columnar output

Most CP messages are free flowing, there is no need to align columns of data.However, some messages or responses look better if their contents take on acolumnar arrangement. The DATAEDIT= keyword directs this decision.v Free flowing

HCPCONSL WRITE

HCPCONSL WRITE,DATAEDIT=NORMFORMAT

This indicates that the substitution text for the message pattern will causethe message pattern to be shifted as necessary to contain the substitutiondata.

v ColumnarHCPCONSL WRITE,

DATAEDIT=COLFORMAT

This indicates that the substitution text for the message pattern will notcause the message pattern to be shifted. The substitution data will overlaythe contents of the message pattern, which area should be blanks in ordernot to lose any of the data in the message pattern.

Some HCPCONSL ExamplesTo write a complete HCPCONSL macro, simply review the components discussedabove and then combine the operands for the desired attributes. Example oneincludes the item numbers from the discussion above that will be combined tomake the final HCPCONSL macro.1. Write a command response from the message repository, substituting data

located at SAVEWRK2; wait if the screen fills; return the return code to R15 sothat it can be checked by a branch table generated by HCPCASRC.

HCPCONSL WRITE, Write a command response XDATATYPE=CMNDRESP, XREPOSNUM=’MS741701’, XSUBDATA=SAVEWRK2, XIOWAIT=SCREENFULL, XRETCODE=(R15)

HCPCASRC (RC00, 00: success XRC04, 04: disconnected XRC08, 08: interrupted by user XRC12, 12: I/O error XRC16, 16: not logged on XRC20), 20: soft abend occurred XELSE=RCXX ?

2. Write an error message from local message repository whose component ID is“ABC”, with the error message in R4 so that we do not confuse anybodyreading the code into thinking IBM's message MS009904 is being issued,substituting data located by register R3; do not wait; return the messagenumber into SAVER2 so that the message number becomes the return codefrom the command.

L R4,=X’00009904’HCPCONSL WRITE, Write local error message X

COMPID=’ABC’, XDATATYPE=EMSG, XREPOSNUM=(R4), XRETMSGNUM=SAVER2, XSUBDATA=(R3)



3. After locating the VMDBK for a specific user ID, write an error message fromlocal message repository whose component ID was passed in R8 at entry to theuser ID whose address was passed in R10, with the error message in R4 so thatwe do not confuse anybody reading the code into thinking IBM's messageMS987601 is being issued, substituting data located by register R3; wait untilthe I/O completes; ignore the message number returned by the macro; returnthe return code to R15 so that it can be checked by a branch table generated byHCPCASRC.

LA R0,8 Length of uidL R1,SAVER10 Address of uidHCPCALL HCPSCVMD Find its VMDBKBNZ NOPE ..sorry, not hereLR R10,R1 Set R10 -> VMDBKL R4,=X’00987601’ Set R4 = message numberL R6,SAVER8 Set R6 -> component IDHCPCONSL WRITE, Write local error message X

COMPID=(R6), XDATATYPE=EMSG, XDESTINATION=(R10), XIOWAIT=IOCOMP, XREPOSNUM=(R4), XRETCODE=(R15), XSUBDATA=(R3)

HCPCASRC (RC00, 00: success XRC04, 04: disconnected XRC08, 08: interrupted by user XRC12, 12: I/O error XRC16, 16: not logged on XRC20), 20: soft abend occurred XELSE=RCXX ?

Using Other Dynamically Loaded RoutinesOther dynamically loaded routines can be called directly by using the HCPCALLmacro. But this can be done only if the address constant for the called routine canbe resolved by CPXLOAD, so that HCPCALL has its address. CPXLOAD canresolve the address constant only if the proper use of CPXLOAD operands wasmade.

You must remember that a dynamically loaded routine may be unloaded byCPXUNLOAD if it had been loaded originally with the CPXLOAD TEMPORARYoperand.

The following table shows if CPXLOAD can resolve the address constant. For thistable, we will assume that the address constant is in routine A and that the addressconstant refers to a location in routine R. In addition, we will refer to theCPXLOAD load ID for routine A as ID(A), and for routine R as ID(R). TheCPXLOAD load ID is important here because the same CPXLOAD load ID(mathematically, ID(A) = ID(R)) means that the two routines were loaded by thesame CPXLOAD operation, possibly selected by INCLUDE directives.

CPXLOAD for A CPXLOAD for R ID(A)::ID(R)Addressresolved?

PERMANENT PERMANENT Equal Yes

TEMP TEMP Equal Yes

PERMANENT PERMANENT Not equal Yes

PERMANENT TEMP Not equal No



CPXLOAD for A CPXLOAD for R ID(A)::ID(R)Addressresolved?

TEMP PERMANENT Not equal Yes

TEMP TEMP Not equal No

This table can be summarized to this logic:

if A and R were loaded together,then the address constant will be resolvedelse R must be PERMANENT

According to the table, certain address constants cannot be resolved, depending onhow the two routines were loaded. Actually, CPXLOAD will be rejected if addressconstant resolution is prohibited.

To avoid this problem, you can use the HCPCALL with its TYPE=INDIRECToperand. With the TYPE=INDIRECT operand, address constants are not generatedby HCPCALL for dynamically loaded routines, so the CPXLOAD restrictionsexpressed by the above table do not apply. The system overhead for usingHCPCALL TYPE=INDIRECT is slightly higher than not using TYPE=INDIRECT,but you gain significant flexibility in being able to call other dynamicallyloaded-routines, regardless of which operands were used for the CPXLOADrequest.

You can even use HCPCALL TYPE=INDIRECT to call routines in the CP nucleus.In this case, HCPCALL is smart enough to realize that the called routine is in thenucleus and that an address constant is always accepted and so the additionalsystem overhead of an indirect call can be avoided.

There are other reasons why an address constant to an external symbol might beused besides being used in HCPCALL. One such reason was alluded earlier in thediscussion of Addressing Modes: that is, to locate a data item. As shown by theabove table, address constants to external symbols in dynamically loaded routinesmay not always be accepted. Hence, you may need to use an alternative method todetermine the address of an external symbol. One such alternative method wouldbe the use of the CP routine HCPCFDSY. This routine will return the address of aexternal symbol, which can then be used with HCPCALL. You must be ready,however, for the external to vanish by execution of a CPXUNLOAD request. CPwill not prevent use of an old and obsolete address. Care must be exercised toensure that the referenced routine is not unloaded at an inopportune time.

How Should the Routine be Named?Simply for consistency, all of the following should start with the same threecharacters, “xyz”:v The module name, “xyzmmm”v The module's entry points, “xyzmmmee”v The module's external symbols, “xyzmmmff”v The xyzMDLAT macro that defines the module's attributesv Any related local message repository, xyzMES REPOS



As shown above, the first six characters for all entry points and external symbolsin a module should be the same. This rule facilitates understanding of howmodules interact and which modules contain which data.

Because the first three characters, “xyz”, could be used for so many differentpurposes (assembler external symbol, macro name, CMS file name), they should beas simple as possible. This suggests that:v “x” should be selected from the alphabetics A-Z.v “y” should be selected from the alphabetics A-Z and the numerics 0-9.v “z” should be selected from the alphabetics A-Z and the numerics 0-9.

After selecting the three beginning characters, you need to select the next threecharacters that complete the module name. Again, for simplicity and to assuregeneral acceptance by all components of z/VM, these three characters should beselected from the alphabetics A-Z and the numerics 0-9.

At this point, all six characters of the module name have been selected. Now youneed to select the final two characters for each external entry point or otherexternal symbol in the module. These two characters, like all of the others, shouldbe selected from the alphabetics A-Z and the numerics 0-9.

How Should the Linkage Attributes of the Routine be Specified?Linkage attributes for dynamically loaded routines are specified in three places:1. In the xxxMDLAT macro for the routine

The xxxMDLAT macro that you write to describe the linkage for your routineshas one MDLATENT statement for each module. The attributes for the entrypoint names in the module are generally all the same. Because they will beloaded by CPXLOAD, the attribute DYN (indicating that a dynamic SAVBKwill be allocated for each entry point when it is called) is required. A choicemust be made between attributes MP (indicates that the entry points aremultiprocessor capable) and NONMP (indicates that the entry points are onlysingle-processor, or master-processor, capable). Whichever choice is made, thatchoice must be reflected in the CPXLOAD operand or in a CPXLOADOPTIONS directive.

MDLATENT xxxmod, XMODATTR=(MP,DYN), XCPXLOAD=YES

MDLATENT xxxmod, XMODATTR=(NONMP,DYN), XCPXLOAD=YES

2. By the operands on CPXLOAD:CPXLOAD xxxmod TEXT fm MP

CPXLOAD xxxmod TEXT fm NOMP -or-CPXLOAD xxxmod TEXT fm NONMP

3. By the operands on CPXLOAD OPTIONS directives statement:OPTIONS MP

OPTIONS NOMP -or-OPTIONS NONMP

It is imperative that the linkage attributes specified by these methods agree. If theydo not, then the instructions generated by HCPCALL for one type of linkage willnot match the attributes for the other type of linkage. Results are unpredictable.



It is strongly suggested that MP always be used and that NONMP be avoided. TheNONMP attribute can provide a small degree of serialization because all modulesdefined as NONMP must run on the same processor, and only one can be runningat a time. But, if too many modules must run on the master processor, systemperformance will suffer. A better choice would be to devise a locking mechanismusing the locking services of the HCPLCK module. Then, the modules can run onother processors, freeing the master processor for other work.

The HCPXSERV macro can be used to provide this kind of serialization. See thedescription of HCPXSERV in Appendix E, “CP Exit Macros,” on page 191.

How are Addresses Resolved?As the TEXT file (it may have a different file type, depending on how VMSES/Enames things) is being read, its information regarding address constants isremembered. This information consists of:v The name of the control section (CSECT) that contains the address constantv The location of the address constant in the CSECTv The length of the address constantv The name of the external symbol that is referred to by the address constant

This discussion refers both to the SYSGEN process and to the CPXLOAD process,except where their differences are pointed out. This is a discussion of the conceptof address constant resolution, and should not be taken as a discussion ofprogramming flow. When the CSECTs are known, the saved information of addressconstants is then processed. For each address constant, a search is performed tofind the external symbol to which the address constant refers and what is theaddress of that external symbol. The address constant is then adjusted to containthe address of the location to which it refers.

After they have performed all possible address resolution, SYSGEN andCPXLOAD act differently:v SYSGEN displays a message to the terminal indicating that an address constant

could not be resolved, and then SYSGEN discards the address constantinformation.

v CPXLOAD remembers the address constant information in anticipation of afuture CPXLOAD operation defining the external symbol that was not foundthis time.

Because SYSGEN discards address constant information, address constants in thenucleus cannot be resolved or completed by a later CPXLOAD. Because there is nosaved address constant information, there is no way to know that an externalsymbol being loaded by CPXLOAD could satisfy an address constant in thenucleus.

Can I Add My Own CP IUCV System Service?CP IUCV system services are things like *MSG, *MSGALL, *SPL, *RPI, *CONFIG.To create an IUCV communication path with a CP system service, use the IUCVDirectory Control Statement described in z/VM: CP Planning and Administration. Forinformation about the standard set of CP system services, see z/VM: CPProgramming Services.



CP Exits does not provide for the definition of new CP IUCV system services. Suchan extension to the standard set of CP IUCV system services will still require asource modification to all affected CP modules.

What Does the CPXUNLOAD ASYNCHRONOUS Operand Mean?Normally, CP will process any CP command under the control of the user's VirtualMachine Definition Block (VMDBK). While processing a command, no otheractivity for that VMDBK is allowed. This means that any other command that theuser may issue is held waiting until all prior commands issued by the user havecompleted.

In a busy system, a CPXUNLOAD command may take longer than the user iswilling to wait. To complete a CPXUNLOAD request, CP must prevent all newattempts to use the module, and then wait until all present uses complete. Then,finally, CP can remove the module from storage.

To avoid such a delay, the user may use the CPXUNLOAD ASYNCHRONOUSoperand. This operand tells CP to process the command on the system's VMDBK,not on the user's VMDBK. By switching the command to the system's VMDBK, CPcan make the user's VMDBK immediately available for more commands. The userat the terminal is not delayed from doing more work.

If the CPXUNLOAD ASYNCHRONOUS operand is used by an EXEC or by aprogram, this also means that the EXEC or program continues executing beyondthe CPXUNLOAD command and may even finish. If the CPXUNLOAD processinggenerates an informational message or an error message, there is no program readyto receive it. Therefore, all messages will be sent to the user's terminal. This alsomeans that the EXEC or program will not know if the CPXUNLOAD commandsucceeded or failed.

The best use of the SYNCHRONOUS and ASYNCHRONOUS operands is:v If the user is issuing the command at the terminal, use (or allow to default to)

the ASYNCHRONOUS operand. The user may continue working while theCPXUNLOAD command continues.

v If the user is issuing the command by an EXEC or a program, use theSYNCHRONOUS operand. The EXEC or program can then look for messages orerror return code from the command and make decisions about how to proceed.

What Does the CPXLOAD CONTROL Operand Imply?Generally, you would use the CPXLOAD NOCONTROL operand. However,situations may be such that additional processing is necessary to prepare a properenvironment for the loaded routine, or to ensure safe conditions for a laterCPXUNLOAD request. This is the intent behind the use of the CONTROLoperand: to specify a routine that will provide these extra services.

The CONTROL routine is responsible for ensuring that whatever environment isrequired for the loaded routine, in fact, exists. For example, the loaded routine mayexpect that certain control blocks are allocated. The CONTROL routine can performthese allocations in anticipation of the loaded routine needing them. Then later, fora complementary CPXUNLOAD request, the control routine could cleanup anddeallocate the control blocks.



The CONTROL routine need not be loaded as part of the same CPXLOAD request.But if not, it must be part of the CP nucleus or have been loaded with theCPXLOAD PERMANENT operand.

Remember that the CONTROL routine must be suitable for use by CPXLOAD andby CPXUNLOAD. It must accept parameters and addresses as passed in registers,and must return with a proper return code in R15. Only routines specificallywritten to be CONTROL routines should be named by the CONTROL operand.

What Happens if I Make a Programming Error?All exit routines, command routines, and Diagnose code routines run assubroutines of CP. No additional “safety nets” are put in place for thisenvironment. This means that any programming errors, for example a protectionexception program check, will be treated just as if it happened in IBM CP code.The result will be a CP abend.

It is the severity of such a result that dictates that all exit routines, commandroutines, and diagnose code routines be fully tested before they are used in aproduction environment.



Chapter 4. Loading Dynamically into the System ExecutionSpace

This section describes how to load your CP routines into the dynamic area of thesystem execution space (SXS). You can load your CP routines (or modules) eitherof the following ways:v During system initialization, using the CPXLOAD configuration file statement.v During system operation, using the CPXLOAD command. (You can also use the

CPXLOAD command to reload a module that was unloaded using aCPXUNLOAD command.)

The decision to use CPXLOAD during or after initialization depends on:v When you will need to use the routine or modulev How convenient it is for you to package the files

Understanding CPXLOADTo dynamically load your CP routines into the system execution space, you mustuse either the CPXLOAD command or configuration file statement. CPXLOAD hasa wide variety of operands that you can use to tell CP the characteristics of theroutines or modules that you are loading. These operands are explained in thefollowing sections.

Using the DELAY and NODELAY OperandsThe DELAY and NODELAY operands tell CP when to load your CP routinesduring initialization. These operands have no meaning after initializationcompletes, but are included on the CPXLOAD command for the sake ofconsistency. If you specify them on a CPXLOAD command, CP ignores them.

If you specify the DELAY operand during system initialization, CP waits until afterall CPACCESS statements are processed before it processes the CPXLOADstatement. This allows you to put your CP routines on any disk to which CP willhave access. DELAY is the default.

If you specify the NODELAY operand during system initialization, CP processesthe CPXLOAD statement immediately. In this case, the CPXLOAD statement isonly guaranteed to complete successfully if you put your CP routines on the parmdisk. Until CP processes a CPACCESS statement, the parm disk is the only diskthat CP can access.

If you are not sure whether to use DELAY or NODELAY, ask yourself thefollowing questions:v Do you need to use your CP routine or module during initialization? For

example, suppose you are loading a module that you designed to be usedduring the parsing of the system configuration file (this would be true forexternal symbols specified by the EXTERNAL_SYNTAX statement).If the answer is “yes”, use NODELAY.

v Did you place your CP routine or module on a CMS minidisk other than theparm disk?If the answer is “yes”, use DELAY.


Using the PERMANENT and TEMPORARY OperandsThe PERMANENT and TEMPORARY operands tell CP whether your CP routinesor modules can be unloaded with a CPXUNLOAD command.

If you specify the PERMANENT operand, CP will not allow the files to beunloaded. This, typically, would be for a module that is fully-debugged,fully-operational, and required at all times. For example, security-related moduleson production systems would probably be loaded as permanent and dynamicallyloaded modules on test systems would probably be loaded as temporary (inpreparation for a new version or fix).

Another issue is that of address constants pointing between modules. If twodifferent modules (Q and R) are loaded by two different CPXLOAD operations,and module Q contains an address constant that refers to module R, then moduleR must have been loaded with CPXLOAD PERMANENT. If both modules Q and Rmust be loaded separately with CPXLOAD TEMPORARY operand, then one or theother module must be redesigned to eliminate the address constant. If bothmodules Q and R can be loaded together with CPXLOAD TEMPORARY operand,then neither need be redesigned, the address constant can be resolved.

Using the CONTROL and NOCONTROL OperandsUsually, no special processing is needed during loading or during unloading, soCPXLOAD NOCONTROL is appropriate. If special processing is needed beforeCPXLOAD can be declared successful, or before CPXUNLOAD may commence,CPXLOAD CONTROL could be used. The control routine must be “aware” of theCPXLOAD and the CPXUNLOAD environments, or disaster will result. Being“aware” means that the routine must be ready for the data and addresses passedin registers from the CPXLOAD or CPXUNLOAD operation.

An example of a design when CONTROL would be appropriate might be this:Suppose that the module being loaded was written to require the existence ofits Component ID Block (CMPBK) as well as certain data areas alreadyallocated and located by pointers in the CMPBK. During system operationwhen the module would be called, this structure of control blocks must alreadybe in place, even for the very first time that the module is called. In this case, acontrol routine could also be written so that when it is called during CPXLOADprocessing, this structure of control blocks could be created. Also, if aCPXUNLOAD command were issued, the control routine would get controland could “tear down” this structure of control blocks.

CONTROL gives more control over CPXLOAD and CPXUNLOAD, but must beused correctly. Indiscriminate, ill-advised use of CONTROL can cause problems.

Using the MP, NOMP, and NONMP OperandsIt is good programming practice to avoid writing master-only, meaning NOMP orNONMP, routines. Good programming practice calls for all routines in amultiprocessor system to be multiprocessor capable, meaning MP. Only if thedesign of a master-only routine cannot be made multiprocessor capable would theroutine remain master-only and be so indicated by CPXLOAD NOMP.

Using the LET and NOLET OperandsWhen a file is being loaded dynamically, the first character in each record issignificant in that it indicates the type of record processing that is required.

Loading into the SXS


v An asterisk (*) in column 1 indicates that the record is a comment and should beignored.

v The value X'02' indicates that the record is a TEXT record, which CPXLOAD willprocess.

v A blank in column 1 denotes a possible CPXLOAD directive, which will bevalidated and handled.

v Anything else in column 1 would be considered an invalid record and wouldtypically be flagged as an error.

There are some cases where finding an invalid record based on the value incolumn 1 is not actually a problem. For example, an assembler utility, such asVMFHASM or VMFHLASM, will often leave information in the TEXT file that ismeant to be ignored by a loader program. For example, here are such records froma TEXT file for HCPPTU where the VMHASM EXEC has included a record (thefirst record) that does not conform to the rules mentioned above.

G54306HP PUT UM23148 SYSTEM HUNG, ABENDMCW002 OR ABENDPAG001. N* HCPPTU G54306HP H1 FCP12H 10/22/92 15:39:00* PREREQ: NONE* CO-REQ: NONE* IF-REQ: NONE

You can control the type of checking that is done on the records in the file thatCPXLOAD processes by using LET and NOLET.v LET, which is the default, tells CP to load the specified file and to ignore records

that are either completely blank or that contain an unexpected value in the firstcolumn. This is meant to accommodate the non-comment information that canbe left in a TEXT file by an assembler utility, such as VMFHASM orVMFHLASM. It saves you the added work of editing your TEXT file to deletethese extraneous non-comment lines.

v NOLET tells CP to stop loading the file when an invalid record is detected. Youwould use NOLET in cases where you have removed all of the extraneousinformation from your text file, and therefore expect all the records to be valid.

In the example above,v LET will allow CPXLOAD to succeed,v NOLET will cause CPXLOAD to fail, because of record 1.

How to Package ModulesHow modules are written is a design decision.v One large module, written as a single CSECT, containing multiple entry points,

orv Multiple modules, each written as a single CSECT, each containing a single entry

point.

Storage for dynamically loaded modules is performed so that each CSECT isloaded into storage in its own page. A module written as a single CSECT withmultiple entry points will use less storage than multiple modules each written as asingle CSECT each with a single entry point. But, if one entry point evolves andthe CSECT exceeds 4 KB in size, difficult rework of the module may be necessaryin order to find another base register or in order to split the CSECT into multipleseparate CSECTs.


Chapter 4. Loading Dynamically into the System Execution Space 41

Once the arrangement of CSECTs has been determined, the decision must be madeabout how to package their TEXT files produced by the IBM High LevelAssembler.v Should they remain separate files loaded by separate CPXLOAD requests?v Should they remain separate files loaded by a single CPXLOAD request using

INCLUDE directives?v Should they be packaged into a single TXTLIB file but still loaded by separate

CPXLOAD requests?v Should they be packaged into a single TXTLIB file and loaded by a single

CPXLOAD request using INCLUDE directives?v Should they be packaged into a single TXTLIB file and loaded by a single

CPXLOAD request using the pattern matching capabilities of the MEMBERSoperand?

Each of these alternatives affect ease of loading and ease of distribution. There isno single packaging scheme that is right for all situations.

Examples of CPXLOAD CommandsNow that we have described what the operands on CPXLOAD mean and havegiven you information about packaging modules, suppose we take you throughsome scenarios so that you can actually use this information.

A Note about the Examples

The examples in this section show you lists of instructions. These instructionsshow you how to accomplish a task using the basic steps and the basic order inwhich those steps should be accomplished. However, each situation is differentand we cannot begin to document all of the possible variations. So, use the steps inthese examples as guidelines, not hard-and-fast rules.

CPXLOAD Example 1: Installing a New CP CommandSuppose that you want to install a new CP command routine for users withprivilege class G authority. For this example, complete the following steps in thefollowing order:1. Decide the name of the new CP command. (We will use cmd to represent the

command name that you chose.)2. Decide on the name of the new source module. (We will use fn to represent

the module name that you chose.)3. Decide on the two additional characters to add to the module name (fn) to

generate the entry point name of the command processor. (We will use ep torepresent the entry point name that you chose.)

4. Write the new module.5. Assemble the module with the IBM High Level Assembler.6. Copy the resulting TEXT file to a minidisk that will be (or is) accessed by CP.7. Make the minidisk accessible to CP using the CPACCESS command.8. Define the command using the DEFINE COMMAND command.

define command cmd enable privclass g ibmclass g epname ep

9. Decide which CPXLOAD attributes to use:v You wrote the routine to be multiprocessor capable, so use MP, the default.



v You wrote the routine such that it needs no special set up or clean upprocessing, so use NOCONTROL.

v You want to be able to load a new version of the routine, if this one needsto be replaced, so use TEMPORARY.

10. Load the TEXT file using the CPXLOAD command:cpxload fn text temp nocontrol

After completing the above steps, you will have made the new CP commandavailable to your users.

CPXLOAD Example 2: Installing a New Diagnose CodeSuppose that you want to install a new Diagnose code routine for users withprivilege class G authority. For this example, complete the following steps in thefollowing order:1. Decide on the number for the new Diagnose code. (We will use diag to

represent the Diagnose code that you chose.)2. Decide on the name of the new source module. (We will use fn to represent

the module name that you chose.)3. Decide on the two additional characters to add to the module name (fn) to

generate the entry point name of the Diagnose code processor. (We will use epto represent the entry point name that you chose.)

4. Decide on the two additional characters to add to the module name (fn) togenerate the entry point name that CP will call when the module is loaded.(We will use ct to represent the entry point name that you chose.)

5. Write the new module.6. Assemble the module with the IBM High Level Assembler.7. Copy the resulting TEXT file to a minidisk that will be (or is) accessed by CP.8. Make the minidisk accessible to CP using the CPACCESS command.9. Define the command using the DEFINE COMMAND command.

define diagnose diag enable privclass g epname ep

10. Decide which CPXLOAD attributes to use:v You wrote the routine to be multiprocessor capable, so use MP, the default.v You wrote the routine such that it needs special set up processing, so use

CONTROL.v You want this routine to be available forever and never to be unavailable.

Operation of your VM service is dependant on this Diagnose code beingavailable, so use PERMANENT.

11. Load the TEXT file with the CPXLOAD command:cpxload fn text perm control ct

After completing the above steps, you will have made the new Diagnose codeavailable to your users.

CPXLOAD Example 3: Installing a New MessageSuppose that you want to install a CP message that replaces a standard CPmessage. For this example, complete the following steps in the following order:1. Decide which message (or messages) you will be changing.2. Decide on the name of the new source module. (We will use repos to represent

the source name that you chose for your message repository.)3. Write the new message repository.



4. Assemble the module with the CMS GENMSG command.5. Copy the resulting TEXT file to a minidisk that will be (or is) accessed by CP.6. Make the minidisk accessible to CP using the CPACCESS command.7. Decide which CPXLOAD attributes to use:v Message repositories contain only data, so the MP or NONMP decision is

immaterial. It is simplest to use MP, the default.v Message repositories need no special set up or clean up processing, so use

NOCONTROL.v You want to be able to load a new version, if this one needs to be replaced,

so TEMPORARY should be used.8. Load the TEXT file with the CPXLOAD command.

CPXLOAD repos TEXT TEMP NOCONTROL

9. Associate the message repository with component ID HCP, the CP componentID, by using the ASSOCIATE MESSAGE command.

ASSOC MESSAGES COMP HCP EPNAME repos

Having completed the above steps, you will have caused CP to use your newmessage rather than the standard message.

Examples of CPXLOAD DirectivesSuppose that you have written a number of modules that, taken together, comprisethe routines for a user Diagnose code. Suppose that these routines are named likethis, with attributes as indicated.v DGA1FCEP

The initial entry for processing of your Diagnose code. This entry point willexamine the subcode parameter and route further execution as appropriate. Thisroutine is multiprocessor capable.

v DGB1FC00This is the routine that processes subcode 00. This routine is multiprocessorcapable.

v DGC1FC04This is the routine that processes subcode 04. This routine is not multiprocessorcapable and therefore must run only on the master processor.

v DGD1FC08This is the routine that processes subcode 08. This routine is multiprocessorcapable.

For the convenience of your customers (by the way, you are a vendor of this code),you have packaged these routines into members of a single TXTLIB file, namedDGN1FC TXTLIB. As another convenience to your customers, you have includedmember RULES in DGN1FC TXTLIB to contain CPXLOAD directives so that yourcustomers need not be concerned with such details, and cannot specify themerroneously.

This, then, would be the CPXLOAD command that would cause all of yourroutines to be loaded.

CPXLOAD DGN1FC TXTLIB MEMBER RULES

The RULES member of DGN1FC TXTLIB is shown below.



The operands specified on each OPTIONS directive match the descriptions above.The order of the statements in RULES is significant. The operands on eachOPTIONS directive applies to the the CSECTs that are it. Operands on subsequentOPTIONS directives override operands of previous OPTIONS directives.

Here is a description of contents of the RULES member:

Line Contents

1 This OPTIONS directive specifies that the dynamically loaded routines canbe unloaded in the future with a CPXUNLOAD command. Also, there isno control entry point associated with these dynamically loaded routines.

2-3 The routine DGA1FCEP is multiprocessor capable.

4-5 The routine DGB1FC00 is multiprocessor capable.

6-7 The routine DGC1FC04 is not multiprocessor capable.

8-9 The routine DGD1FC08 is multiprocessor capable.

For a full description of CPXLOAD directives and especially the OPTIONSdirective, refer to Appendix C, “CPXLOAD Directives,” on page 177.

RULES TEXT A1 F 80 Trunc=80 Size=9 Line=0 Col=1 Alt=0

|...+....1....+....2....+....3....+....4....+....5....+..0 * * * Top of File * * *1 OPTIONS TEMPORARY NOCONTROL2 OPTIONS MP3 INCLUDE DGN1FC TXTLIB MEMBER DGA1FCEP4 OPTIONS MP5 INCLUDE DGN1FC TXTLIB MEMBER DGB1FC006 OPTIONS NONMP7 INCLUDE DGN1FC TXTLIB MEMBER DGC1FC048 OPTIONS MP9 INCLUDE DGN1FC TXTLIB MEMBER DGD1FC0810 * * * End of File * * *

Figure 3. RULES member of DGN1FC TXTLIB



Chapter 5. Controlling a Dynamically Loaded Routine

This section shows how you can control your dynamically loaded routines. Howyou control a dynamically loaded routine depends on the reason that you loadedit: to be a CP command routine, to be a Diagnose code routine, to be a CP exitroutine, or to be a message repository.

Note: Once defined, commands, subcommands, aliases, and Diagnose codescannot be deleted. They may be altered in various appropriate ways, but theyremain in existence until a SHUTDOWN or RESTART IPL is done.

Controlling a Dynamically Loaded CP Command RoutineYou can use any of the following commands and configuration file statements tocontrol your dynamically loaded CP command routine:

DISABLE COMMAND or CMD command or statement Use DISABLE to make a CP command or subcommand or aliasunavailable. DISABLE can be undone by ENABLE.

ENABLE COMMAND or CMD command or statement Use ENABLE to resume the usability of a CP command, subcommand, oralias. By default, a new command or alias is defined initially as disabled.ENABLE may be needed to make the command, subcommand, or aliasusable.

CPXLOAD command or statement Use CPXLOAD to load one or more modules into the system executionspace. These files must be on a CMS minidisk accessed by CP.

CPXUNLOAD command Use CPXUNLOAD to remove one or more modules that were dynamicallyloaded into the system execution space by a previous CPXLOAD request.Only modules that were loaded with the TEMPORARY operand can beunloaded.

DEFINE COMMAND or CMD command or statement Use DEFINE COMMAND to define a new CP command, subcommand, ora new version of an existing CP command or subcommand.

DEFINE ALIAS command or statement Use DEFINE ALIAS to define a new alias command for an existing CPcommand or subcommand. The existing CP command is termed the basecommand, because the alias command points to it for its attributes. Analias command cannot be defined for another alias command. Oncedefined, an alias name cannot be used again. An alias command cannot bemodified or eliminated; it can only be disabled. Use QUERY CPCMDS tosee which commands are alias commands and which are base commands.

MODIFY COMMAND or CMD command or statement Use MODIFY COMMAND to change certain attributes of any CPcommand or subcommand. (An alias command cannot be modified.)Among the attributes that can be changed by MODIFY are the commandprocessing routine and privilege classes. A user whose privilege classes donot overlap the command's privilege classes will not be able to issue thecommand.


QUERY CPCMDS command Use QUERY CPCMDS to display attributes of any CP command orsubcommand. Among the data displayed will be the status of thecommand (enabled or disabled), the command processing routine, and theprivilege classes. A disabled base command or alias command cannot beissued. The command must be enabled before it can be used.

LOCATE SYMBOL command Use LOCATE to display the address of any external symbol. When theaddress is known, you can use the DISPLAY (Host Storage) command toexamine the module.

Controlling a Dynamically Loaded Diagnose Code RoutineYou can use any of the following commands and configuration file statements tocontrol your dynamically loaded Diagnose code routine:

DISABLE DIAGNOSE command or statement Use DISABLE to make a Diagnose code routine unavailable. DISABLE canbe undone by ENABLE.

ENABLE DIAGNOSE command or statement Use ENABLE to resume the usability of a Diagnose code routine. Bydefault, a new Diagnose code is defined initially as disabled. ENABLE maybe needed to make the Diagnose code usable.


CPXUNLOAD command Use CPXUNLOAD to remove one or more modules that were loaded intothe system execution space by a previous CPXLOAD request. Onlymodules that were loaded with the TEMPORARY operand can beunloaded.

DEFINE DIAGNOSE command or statement Use DEFINE DIAGNOSE to define a new Diagnose code.

MODIFY DIAGNOSE command or statement Use MODIFY DIAGNOSE to change certain attributes of any Diagnosecode (except Diagnose code X'214'). Among the attributes that can bechanged by MODIFY DIAGNOSE are the Diagnose code processingroutine and privilege classes. A user whose privilege classes do not overlapthe Diagnose code's privilege classes will not be able to issue the Diagnosecode.

QUERY DIAGNOSE command Use QUERY DIAGNOSE to display attributes of any Diagnose code.Among the data displayed will be the status of the Diagnose code (enabledor disabled), the Diagnose code processing routine, and privilege classes. Adisabled Diagnose code cannot be issued. The Diagnose code must beenabled before it can be used.

LOCATE SYMBOL command Use LOCATE to display the address of any external symbol. When theaddress is known, you can use the DISPLAY (Host Storage) command toexamine the module.

Controlling Routines


Controlling a Dynamically Loaded CP Exit RoutineYou can use any of the following commands and configuration file statements tocontrol your dynamically loaded CP exit routine:

DISABLE EXITS command or statement Use DISABLE to tell CP not to call any routines associated with thespecified CP exit number. DISABLE can be undone by ENABLE.

ENABLE EXITS command or statement Use ENABLE to tell CP to resume calling routines associated with thespecified CP exit number. By default, ASSOCIATE EXIT is defined initiallyas disabled. ENABLE may be needed to tell CP to start calling the routinesassociated with the specified CP exit number.


CPXUNLOAD command Use CPXUNLOAD to remove one or more modules that were loaded intothe system execution space by a previous CPXLOAD request. Onlymodules that were loaded with the TEMPORARY operand can beunloaded.

DEFINE EXIT command or statement Use DEFINE EXIT to define an exit point dynamically. You place the exitpoint by specifying the module name and the offset within the modulewhere the exit is to reside, as well as the instruction at that offset. The exitis taken before that instruction is executed. You may also specify theparameters that are to be provided when the exit is called.

MODIFY EXIT command or statement Use MODIFY EXIT to modify or remove a dynamic exit point defined bythe DEFINE EXIT command or statement. You can change the exit location,characteristics, and parameters.

ASSOCIATE EXIT command or statement Use ASSOCIATE EXIT to associate a list of entry points with a CP exitnumber. If the CP exit point is reached, then CP tries to call the entrypoints if the CP exit point is enabled.

DISASSOCIATE EXIT Use DISASSOCIATE EXIT to delete the list of entry points from the exitnumber. The exit remains enabled or disabled, whichever it was. Ifenabled, CP will continue to perform exit call initialization. If enabled andno entry points are associated with the exit then the CP exit callinitialization is unnecessary processing. To avoid this overhead, issueDISABLE EXIT for the exit number.

QUERY EXIT Use QUERY EXIT to display attributes of any exit number. Among the datadisplayed will be the status of the exit (enabled or disabled), the exitprocessing routine, statistics, and so on. For a dynamic exit, the exitlocation, characteristics, and parameter definitions will also be displayed.

LOCATE SYMBOL Use LOCATE to display the address of any external symbol. When theaddress is known, you can use the DISPLAY (Host Storage) command toexamine the module.


Chapter 5. Controlling a Dynamically Loaded Routine 49

Controlling a Dynamically Loaded Local Message RepositoryYou can use any of the following commands and configuration file statements tocontrol your dynamically loaded local CP message repository:


CPXUNLOAD command Use CPXUNLOAD to remove one or more modules that were loaded intothe system execution space by a previous CPXLOAD request. Onlymodules that were loaded with the TEMPORARY operand can beunloaded. Modules still in use (still associated as message repositories)cannot be unloaded until disassociated.

ASSOCIATE MESSAGES or MSGS command or statement Use ASSOCIATE MESSAGES to associate one or more entry point nameswith a message repository component ID. This will enable your modules towrite your messages.

DISASSOCIATE MESSAGES Use DISASSOCIATE MESSAGES to undo ASSOCIATE MESSAGESrequests.

QUERY CPLANGLIST ASSOCIATEDUse QUERY CPLANGLIST ASSOCIATED to display message repositorycomponent IDs and their associated entry point names. You can use thecomponent ID and language ID displayed in DISASSOCIATE MESSAGEScommands to break or remove the association, thereby allowingCPXUNLOAD to be used.

LOCATE SYMBOL Use LOCATE SYMBOL to display the address of any external symbol.When the address is known, you can use the DISPLAY (Host Storage)command to examine the module.

IPL Parameter NOEXITSIf you find yourself in a situation where a CP exit routine is causing your systemto not initialize, there is help. This help is in the form of the new IPL parameterNOEXITS. Like all other IPL parameters, the NOEXITS parameter would besupplied by you on the Stand Alone Programmer Loader initial panel.

If specified, the NOEXITS IPL parameter will cause the following to happen:v CPXLOAD statement will be discarded.v EXTERNAL_SYNTAX statement will be discarded.v ASSOCIATE EXIT statement operand ENABLE will be ignored.v ASSOCIATE MESSAGES statement will be discarded.v ENABLE EXITS statement will be discarded.

All of these statements will be parsed for syntactical correctness, but will not beotherwise processed.

The intended effects of NOEXITS are that only modules in the nucleus be used,and that nothing dynamically “attached” to the nucleus be used or called.



Chapter 6. Defining and Modifying Commands and DiagnoseCodes

This section provides an overview of the basic information that you will need todefine your own command or Diagnose code, or modify an existing one. Note thatwe cannot possibly discuss all topics relating to coding CP functions. In thissection, we discuss:v A high level overview of the command and Diagnose code control blocks so that

you understand what the DEFINE COMMAND (and DEFINE DIAGNOSE) andMODIFY COMMAND (and MODIFY DIAGNOSE) commands are doing.

v How to code a command or Diagnose code. This includes inputs on entry fromthe router and expected outputs from your handler.

v External security manager (ESM) considerations.v The commands necessary to define or modify a command or Diagnose code.v How to disable the command or Diagnose code.

CMDBKs, DGNBKs and YouIn order to understand how to code your command and Diagnose code, and whatoperands to specify on the DEFINE and MODIFY commands, you shouldunderstand where CP stores the information it uses for command and Diagnosecode routing. This section describes this structure.

CMDBKsIn CP, all commands, the SET subcommands, the QUERY subcommands and theQUERY VIRTUAL subcommands are processed by the command router. Each oneof these entities has a CMDBK control block defined with information concerningthe command. These control blocks are chained together in a manner that allowsquick efficient searching. There is one chain for commands, another for SETsubcommands, and so on. If a command has multiple IBM Classes then there willbe a CMDBK for each class.

The CMDBK information includes:v Command name and its minimum abbreviationv Command handler name and addressing informationv IBM Class and User Privilege Classesv Control flags concerning ESM settings and other CP functionsv Space set aside for installation variables (field names begin with the string

"CMDUSR")

DGNBKsJust as each command has a control block with information about it, each Diagnosecode has a DGNBK control block. The DGNBKs are accessed in an array by theDiagnose code router. Diagnose codes are numbered from x'000' to x'3FC' andincremented by 4 (such as 0,4,8,C,10, ... 3FC). Numbers x'100' through x'1FC' arereserved for customer and vendor use.

The DGNBK information includes:v Diagnose code number


v Diagnose code handler name and addressing informationv User Privilege Classesv Control flags concerning ESM settings and other CP functionsv Space set aside for installation variables (field names begin with the string

"DGNUSR")

Relationship between IBM Class and User Privilege ClassA command or Diagnose code may be able to perform different functionsdepending upon the privilege class of the user that invoked it.

For a Diagnose code, the various functions provided by a Diagnose code areidentified by the user privilege class. Diagnose code definitions do not include IBMclass.

The various functions provided by a command are identified by the IBM class,which is derived from the user privilege class. The types of authorities for thevarious IBM classes are shown in Table 3.

Table 3. IBM Class Definitions

Class User and Function

A System Operator:. The class A user controls the z/VM system. The system operator is responsiblefor the availability of the z/VM system and its resources. In addition, the system operator controlssystem accounting, broadcast messages, virtual machine performance options, and other optionsthat affect the overall performance of z/VM.

B System Resource Operator. The class B user controls all the real resources of the z/VM system,except those controlled by the system operator and the spooling operator.

C System Programmer. The class C user updates or changes system-wide parameters of the z/VMsystem.

D Spooling Operator. The class D user controls spool files and the system's real reader, printer, andpunch equipment allocated to spooling use.

E System Analyst. The class E user examines and saves system operation data in specified z/VMstorage areas.

F Service Representative. The class F user obtains, and examines in detail, data about input andoutput devices connected to the z/VM system. This privilege class is reserved for IBM use only.

G General User. The class G user controls functions associated with a particular virtual machine.

0 No IBM class. A command with IBM class 0 is associated with the version of the command withPRIVCLASSANY. A command routine handling multiple functions for a command with some IBMclasses and no IBM class would typically look for the IBM class authorities first and then, if noIBM class authority was granted, would handle the case of no IBM class.

When the CP system is shipped, there is usually a one-to-one relationship betweenthe IBM class (A-G, 0) and the user privilege classes (A-Z, 1-6 and 'any') to whichit is mapped. However, installations may change this mapping by using systemconfiguration file MODIFY statements and the CP MODIFY command.

Coding Your Command and Diagnose CodeNow that you know how CP identifies the commands and Diagnose codes, we candescribe items you need to consider when you code your command or Diagnosecode. Once again, we will not cover all possible rules and conventions for writingcode in CP. Instead, we will cover the interfaces that relate to invoking your codeand returning from your code.

Your Own Commands and Diagnose Codes


Coding a Command Handler

Input from the Command RouterThe command router determines whether the user can issue a particular command.It will invoke the command handler if it determines that the user has the userprivilege class necessary to invoke at least one of the versions of a command. Thecommand router makes this determination based on the command or subcommandname. However, some command versions are only differentiated by a specificoption that is allowed on the command line. Because a user may be authorized formore than one version of a command, CP requires that all versions of thecommand have the same entry point. It is up to the command handler todetermine which version of the command it should perform.

When control is given to the command handler, a number of registers areinitialized with information about the command. The registers contain:

RegisterContents

R0 Length of the command, as specified.

R1 Address of the command in the GSDBK.

R2 Zero

R3 First 4 bytes of the command name from the base CMDBK. Because ofcommand aliasing, this may not be the same command name as indicatedby R0 and R1. That is because the command issued may be an alias for theactual command to be invoked. For example, if the user issued MSG that isan alias of MESSAGE then the base command is MESSAGE and thisregister would contain the string "MESS".

R4 Second 4 bytes of the command name from the base CMDBK. (See theexplanation for R3 about base CMDBKs.)

R5 Address of the base CMDBK. This is the CMDBK for one of the versions ofthe base CMDBK. If the command has multiple versions this address neednot be the version that the command handler will select to handle.

R6 Zero

R7 Zero

R11 Address of the VMDBK of the issuer.

R13 Address of the SAVBK to be used during the call.

R14 Linkage register

R15 Linkage register

The contents of the registers that are not specified in the preceding list should beconsidered undefined. No assumptions should be made on their contents.

Among the information contained in the VMDBK is the address of the commandGSDBK. This value is contained in the VMDCFBUF field.

In addition to specifying certain registers with information about the commandbeing invoked, the VMDBK is in CONSOLE FUNCTION MODE. This means thatthe other virtual processors (VMDBKs) for this user are not actively beingdispatched.


Chapter 6. Defining and Modifying Commands and Diagnose Codes 53

Determining the Command Version (IBMCLASS)On entry from the command router, the command handler knows that the user hasbeen authorized to issue one of the versions of the command. The VMDCTYPEfield in the base VMDBK contains the IBMCLASS values for the versions of thecommand that the user can issue. The byte consists of one flag bit for eachIBMCLASS values A-H (see USERCLS0 bit definitions in HCPCLASS COPY for amapping of the flag values).

No flag bit is set for IBMCLASS 0 because any other version of the commandshould be considered a superset of the function provided by the IBMCLASS 0version. Thus, if the user did not issue any of the other versions of a command,the command handler knows that the IBMCLASS 0 version should be handled.

ESM Interactions and AuditingMany, if not all, ESMs support logging of the commands that a user invokes. Thislogging provides an audit trail of the commands issued by a user for securityanalysis. Whether the ESM call for auditing is performed by the command routeror command handler depends on the type of command and its versions. Singleversion commands may allow the command router to perform the auditing call. Ifthere is no "security" difference between the versions of a multi-version commandthen the command router may perform the auditing call. If it is necessary todifferentiate between which version of a command the user invoked then thecommand handler has to perform the ESM call for auditing.

In addition to auditing, some systems run ESMs at a higher level of securityprotection that require additional security verification dependent upon the versionof the command and its operands. The command handler handles the invocation ofthe ESM for this level of security verification.

For information on interfacing with ESMs, see the CP Access Control Interfacetopic in z/VM: CP Planning and Administration.

Exiting to the Command RouterUpon completion of processing, the command handler should return to thecommand router with register 2 set to zero or the message number of the errormessage that it generated. This is normally accomplished by storing the value inSAVER2 prior to invoking the HCPEXIT macro. The value returned in SAVER2 isthe command completion return code that is returned to CMS and displayed onthe CMS READY prompt.

The command router will attempt to process the next command (if one exists).

Coding a Diagnose Code Handler

Input from the Diagnose Code RouterWhile Diagnose codes that are defined using the DIAGNOSE macro and assembledinto HCPHVB allow selection of different types of Diagnose code routerinvocation, such as HCPCALL or HCPGOTO linkage, the Diagnose codes that wediscuss in this section are loaded using the CPXLOAD command and definedusing the DEFINE DIAGNOSE command. The Diagnose code router will invokethese Diagnose code handlers using HCPCALL with INDIRECT linkage.Additional information on Diagnose codes and descriptions of the errors reportedby the Diagnose codes is contained in z/VM: CP Programming Services.

As with commands, the Diagnose code router verifies that the user has thenecessary privilege class to invoke the Diagnose code. The Diagnose code handler



may need to handle additional authorization checks. Any ESM calls for additionalchecks would be contained in the Diagnose code handler.

When control is given to the Diagnose code handler, a number of registers areinitialized with information about the Diagnose code. The registers contain:

RegisterContents

R5 Address of GUEST 'Rx' register value in the VMDBK.

R6 Address of GUEST 'Ry' register value in the VMDBK.

R8 Address of the DGNBK.

R11 Address of the VMDBK of the virtual processor for the user from whichthe Diagnose code was issued.

R13 Address of the SAVBK to be used during the call.

Additional information pertaining to the Diagnose code may be obtained using theHCPDCODE macro. This data includes the Diagnose code number whose valuewill be between X'100' and X'1FC'.

ESM Interactions and AuditingFor information on interfacing with ESMs, see the CP Access Control Interfacetopic in z/VM: CP Planning and Administration.

Exiting to the Diagnose Code RouterAny return codes or condition codes to be returned to the user are set by theDiagnose code handler. HCPGSVC0, HCPGSVC1, HCPGSVC2, and HCPGSVC3routines provide function to set virtual condition codes 0, 1, 2 and 3, respectively,in the VMDBK. The return codes are usually set in the Ry+1 register or one of theother Rx, Rx+1, or Ry registers. The address of the fields for the Rx and Ryregisters are passed as input to the Diagnose code handler and can be used toupdate these fields.

In addition, some other conditions (e.g. return a program check) may be passedback to the Diagnose code router to handle using a combination of values set inregister 15 and other registers. For more information on the recognized return codevalues for register 15, see the description of the DEFINE DIAGNOSE command inz/VM: CP Commands and Utilities Reference concerning the CHECKR15 operand.

Defining your Command and Diagnose CodeAfter you have coded your command or Diagnose code, you can load the codeinto the system execution space using the CPXLOAD command or configurationfile statement. See Chapter 4, “Loading Dynamically into the System ExecutionSpace,” on page 39. You should note that you can define the command orDiagnose Code before you load the code but we recommend that you load thecode first, because this will save you from getting information messages warningyou about the absence of the code when you attempt to perform the DEFINEcommand and specify an EPNAME that is not loaded.

If your system is running an ESM, you should define your commands andDiagnose codes using configuration file statements. This is because the ESM takesa snapshot of the list of commands and Diagnose codes that are part of the system.Also, some ESMs support selective auditing where a copy of the list of commandsand Diagnose codes are maintained for a user's virtual machine when they log on.



Changing the table after the ESM has acquired its snapshot will causeunpredictable results. By defining any new commands (including new versions ofa command) or Diagnose codes using configuration file statements, you limitchanges to the command and Diagnose code structure at IPL time prior to theautologging of the ESM virtual machine or other users.

Next, you should consider the operands and options that you will wish to specifyon the DEFINE COMMAND and DEFINE DIAGNOSE commands. Thesecommands inform the system about your command and Diagnose code. As theresult of processing these commands, the system creates the necessary CMDBKand DGNBK with the control flags and settings set for your code.

There are a number of operands on the DEFINE COMMAND and DEFINEDIAGNOSE instruction that relate to ESM processing. The PROC operand indicatesthat the command/Diagnose code router should not perform any ESM calls.Instead, the command/Diagnose code handler is expected to perform the necessaryESM calls.

AUDIT indicates that the command/Diagnose code will be audited by the ESM. Itis the responsibility of the handler to perform the AUDIT call to the ESM if PROCwas specified. The AUDIT setting may be modified by the ESM.

PROT indicates that the command or Diagnose code should be protected by theESM. When commands or Diagnose codes with PROT are invoked the call to theESM will inform the ESM that it should search authorization lists to determinewhether the user may invoke the command or Diagnose Code The PROT settingmay be modified by the ESM if VPROT was also specified.

MAC indicates that the command should be protected by the ESM at a mandatoryaccess control level. ESMs that support this level of protection perform securitylabel validation. The MAC setting may be modified by the ESM if VMAC was alsospecified. See your ESM for documentation on the level of protection that itprovides.

Defining Your CommandIn this section we discuss the DEFINE command operands which are unique tocommand processing.

Some ESMs restrict the usable characters that you may assign to a command name.For example, some ESMs use the underscore character (_) as an operand separator.You should consult your ESM documentation for information on any restrictionsthat apply to your system.

Prior to defining your new command you should verify that the command orsubcommand name does not conflict with any existing command or subcommand.The QUERY CPCMDS command can be used to verify your command and itsabbreviation. For example, to determine if any other QUERY subcommands have a3 character abbreviation of "ACC", which we wish to use for our new "QUERYACCUMULATOR" command, you could issue:QUERY CPCMDS QUERY SUBCMD ACC

The resulting output would show that the QUERY ACCOUNT shares the sameabbreviation. Thus, 3 characters for an abbreviation of "ACCUMULATOR" wouldbe an illegal choice.



As indicated earlier in this section, if a command has multiple versions (IBMClasses) then all versions of the command must specify the same entry point. TheDEFINE COMMAND and MODIFY COMMAND commands will not allow you toviolate this requirement. However, if you had previously changed the entry pointname associated with a command and defined a new command version using thenew entry point name, you would be unwittingly creating a situation where youcould not use the RESET option on the MODIFY COMMAND command to restorethe CMDBKs to their original state. For this reason, you want to define all versionsof a command prior to changing their entry point name to a new name.

Our next step in constructing the DEFINE COMMAND command is to decidewhen a command may be issued and what IBM classes and user privilege classesshould be assigned to the command.

If the version of the command that you are defining is valid before the user haslogged on then you can choose BEFORE_LOGON or ANYTIME, depending onwhether it is valid after the user ID has logged on. For example, the MESSAGEcommand has a version that is valid ANYTIME, but the DIAL command is validonly BEFORE_LOGON. If either of these two options are chosen thenPRIVCLASSANY must be chosen for the privilege class and this will generate anIBMCLASS of 0.

If the version of the command is valid only after a user has logged on thenAFTER_LOGON should be specified. This is also the default. If you do not specifyPRIVCLASSANY for this version then you would specify the PRIVCLASSESoperand and the IBMCLASS operand. The IBMCLASS operand will define the IBMclass to be associated with this version and PRIVCLASSES would define the initialmapping of the IBM class to the user privilege class allowed to issue this versionof the command.

The default state for defining a command is that it is disabled. You can overridethat state by specifying the ENABLE operand or enable it by using the ENABLECOMMAND command.

Defining Your Diagnose CodeIn this section we discuss the DEFINE command operands which are unique toDiagnose code processing.

After considering the ESM processing operands, the next step is to consider theprivilege classes authorized to invoke your Diagnose code. You can specify eitherPRIVCLASSANY or specify the specific privilege classes that can invoke theDiagnose code.

The next two operands provide directives to the Diagnose code router concerningadditional checks that should be performed prior to invoking the Diagnose codehandler. If INVAR is specified then the Diagnose code will not be allowed to beissued by virtual machines that are in host access register mode, instead returninga Special-Operation Exception program interrupt. If INVXC is specified then theDiagnose code will not be allowed to be issued by virtual machines that are inEnterprise System Architecture/Extended Configuration (ESA/XC) mode, insteadreturning a Specification Exception program interrupt.

If your Diagnose code handler uses register 15 to pass results and directives to theDiagnose code router, you must activate this feature using the CHECKR15 YESoperand. Otherwise, the values in register 15 are ignored on return to the Diagnose



code router. See the description of the DEFINE DIAGNOSE command in z/VM: CPCommands and Utilities Reference concerning the CHECKR15 operand.

The default state for defining a Diagnose code is that it is disabled. You canoverride that state by specifying the ENABLE operand or enable it by using theENABLE DIAGNOSE command.

Defining an Alias CommandCP restricts an alias command from referencing another alias command. Whendefining a new alias command, you must name a base command as its referencedcommand. For example, the command MSG is actually an alias for the MESSAGEcommand. MESSAGE is called a base command by elimination: because it is not analias command, it must be a base command.

To determine if a command you want to define is an alias or a base command, usethe QUERY CPCMDS command. This shows that MESSAGE is a base command,because it is not shown to be an alias command.

CP Q CPCMDS MESSAGECommand: MESSAGE

Status: EnabledIBM Class: A PrivClasses: ACMDBK Address: 004CFD28 Entry Point: HCPXMGMS

Command: MESSAGEStatus: EnabledIBM Class: B PrivClasses: BCMDBK Address: 004CFD98 Entry Point: HCPXMGMS

Command: MESSAGEStatus: EnabledIBM Class: 0 PrivClasses: <ANY>CMDBK Address: 004CFE08 Entry Point: HCPXMGMS

Ready

This shows that MSG is an alias command for MESSAGE.CP Q CPCMDS MSGAlias: MSG

Alias Status: EnabledAlias CMDBK Address: 004D0118Command: MESSAGEIBM Class: A PrivClasses: ACMDBK Address: 004CFD28 Entry Point: HCPXMGMS

Alias: MSGAlias Status: EnabledAlias CMDBK Address: 004D0188Command: MESSAGEIBM Class: B PrivClasses: BCMDBK Address: 004CFD98 Entry Point: HCPXMGMS

Alias: MSGAlias Status: EnabledAlias CMDBK Address: 004D01F8Command: MESSAGEIBM Class: 0 PrivClasses: <ANY>CMDBK Address: 004CFE08 Entry Point: HCPXMGMS

Ready;

Once defined, an alias name cannot be reused. An alias command can be disabled,but it cannot be modified or eliminated until a SHUTDOWN or RESTART IPL isdone.



Modifying a Command or Diagnose CodeThe ability to alter attributes like privilege classes or the name of the routine to callis indispensable if you must tailor a z/VM system while avoiding modifications toIBM source files. You can redefine the following attributes of a CP command or aDiagnose code:v Privilege class, or PRIVCLASSANYv Name of the routine used to process the command or Diagnose code

To redefine CP commands and Diagnose codes during system initialization, use theMODIFY COMMAND and MODIFY DIAGNOSE statements in the systemconfiguration file. For information about these statements, see z/VM: CP Planningand Administration.

To dynamically redefine CP commands and Diagnose codes after systeminitialization, use the MODIFY COMMAND and MODIFY DIAGNOSE commands.For information about these commands, see z/VM: CP Commands and UtilitiesReference.

For more information about modifying commands and Diagnose codes, see thetopic in z/VM: CP Planning and Administration.

Disabling a Command or Diagnose CodeIf for some reason, you need to disable a command or Diagnose code, you can doso using the DISABLE COMMAND and DISABLE DIAGNOSE commands.Especially for Diagnose codes, care should be taken to verify that disabling theDiagnose code does not break any other function. For example, disabling Diagnosecode X'008' would bring most CMS users to a stand still because this is theDiagnose code used by CMS to pass CP commands for processing. Also, if youdisable a base command, you are also disabling all aliases of that command.



Chapter 7. Defining and Using CP Message Repositories

This section describes:v Why you would use message repositoriesv How to create a message repository filev How to load and unload message repository filesv How to produce messages using a repository

Why Use Message Repositories?When you write CP code and you want to display error messages, you can putmessage text directly into the code. However, if you have many messages, yourcode can become cluttered and the size of the module will grow unnecessarily.Instead of coding message text directly in your code, you can store all yourmessage text in a file called a repository. Then, to display a message, CP willretrieve the message text from this local repository on your behalf.

Having all message text in one central file has the following advantages:v Message text does not clutter your code.v You can access the same message from many modules without having to specify

the message text each time.v You can have your messages translated into other languages. You can then have

your messages in any number of languages without changing your executablemodule.

For CP system messages, a source repository file is already built for you. It has afile ID of HCPMES REPOS. You can edit this file to view messages. You can alsoprint a copy of the CP message file so you can refer to it when you want to call anexisting CP message from your code.

Note: The file name of the CP message repository is different for languages otherthan English that are available on your system. For more information, see z/VM:Installation Guide.

Components of a MessageA message can be logically divided into two components, the header (also calledthe code) and the text. The user can control which portion of a message they willreceive using the message settings (e.g. SET EMSG TEXT, SET EMSG CODE, etc.).In addition, the two parts of a message can be further divided into subparts.

The message header, xxxxxxnnnns, consists of three subparts:

xxxxxx is the first six characters of the module ID that caused the message to begenerated.

nnnn is the message number. If the number is less than 1000 then only the lastthree digits are displayed, otherwise all four digits are displayed.

s is the severity. This character is obtained from the message repository forthat specific message.


The message text consists of the constant text portion and any substitution datathat is passed when the message is generated. The constant text portion andlocation of the substitution data is defined for the message in the messagerepository.

Creating a Message Repository FileThe message repository consists of a source file that is processed into a machinereadable file (object repository file) that can be used by CP. You can create thesource file using XEDIT.

When creating the file, we suggest that you specify support identification codes(SID codes) in columns 64 through 71 to identify who changed a line of the fileand why. The SET SIDCODE subcommand in XEDIT will insert the SID code foryou as you change the file. If you choose to use SID codes then you will specifythe MARGIN option on the GENMSG command when you proceed to create themachine readable file.

The source file consists of:v Comment records.v A control line to indicate the control character used to identify substitution

indicators.v Message records which contain the message text along with any substitution

indicators. The message records can identify multiple lines of message output.

For information on the format of the source file, see Appendix G, “Understandingthe CP Message Repository,” on page 231.

Example of a Message RepositoryThe following example shows an external repository file, SPGMES REPOS.

Here is a description of what this message repository contains:

Line Content

1-6 Comment lines. Any line with an asterisk (*) in column 1 is a commentline.

SPGMES REPOS A1 F 80 Trunc=80 Size=14 Line=1 Col=1 Alt=0

00000 * * * Top of File * * *|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...

00001 *00002 * This is an example of a message repository file.00003 *00004 * This file was created using XEDIT.00005 * You can code a file similar to this for your own installation.00006 *00007 $00008 00050101E Invalid syntax; please issue command again00009 001501 A Enter the number of copies you want:00010 00250101I Function has completed00011 00250201I Subroutine has completed00012 01000101A Your program halted at label ABCD00013 01000102A To quit the program, enter ’Q’, or00014 01000103A to continue, press the ENTER key00015 * * * End of File * * *

Figure 4. Sample Repository - SPGMES REPOS

Your Own Messages


7 The control line. The first nonblank character on this line ($) defines thesubstitution character for messages. (For more information, see “ProducingMessages With Substitution” on page 67.)

8 The first message in the repository is number 0005. It has only one version(columns 5 and 6) and is a 1-line message (columns 7 and 8). This messageis issued in response to a user error, so the severity (column 9) is “E”.

9 The second message in the repository is number 0015. Again, it has onlyone version (columns 5 and 6) and is a 1-line message (columns 7 and 8).We did not need to specify the message line number because it has onlyone line. The message is requesting immediate action by the user so theseverity (column 9) is “A”.

10-11 The third message in the repository is number 0025. This message has twoformats: depending on the error, either Function has completed (format 01)or Subroutine has completed (format 02) is displayed. These messagesgive the user information, so the severity (column 9) is “I”.

12 - 14 The fourth message is number 0100. This message has only one format, butit spreads across three lines of the repository. Columns (7-8) show the linenumbers of this message. The message is requesting immediate action bythe user so the severity (column 9) is “A”.

Generating the Object Repository FileAfter you create a message repository, you should check for incorrect entries in themessage repository file, correct these errors, and then compile the messagerepository file into an object repository file. Use the GENMSG command to do thechecking and compiling.

You can use the GENMSG command with the NOOBJECT option to check forerrors in the message repository file. When you specify the NOOBJECT option,CMS only checks for errors. The message repository file is not compiled. When themessage repository does not contain any errors, use the GENMSG commandwithout the NOOBJECT option to compile the message repository file.

The GENMSG command with the NOOBJECT option does not create a TEXT file,it only creates a LISTING file. The LISTING file contains the messages returnedfrom the GENMSG command. The GENMSG command without the NOOBJECToption creates two files. One file has a file type of LISTING. The other file has afile type of TEXT. The TEXT file contains the internal version of your messagerepository. The file name of the LISTING file and TEXT file is the same as themessage repository source file name.

When you look at the LISTING file for information about an error in the messagerepository file, search for DMSMGC. The line containing DMSMGC describes theerror.

See z/VM: CMS Commands and Utilities Reference for details on the GENMSGcommand.

Example 1Enter the following GENMSG command to check for errors in your messagerepository file called SPGMES REPOS:GENMSG SPGMES REPOS A SPG (NOOBJECT MARGIN 63

Your Own Messages

Chapter 7. Defining and Using CP Message Repositories 63

In this example, SPGMES REPOS A is the file ID of the message repository youcreated. The operand SPG is the applid, which is the operand used to identify yourapplication. This application identifier must be three characters long. Be sure torecord the application identifier you choose. You will need to reference it as thecomponent ID when you specify the HCPCONSL macro to generate the messagefrom your code. The MARGIN 63 operand indicates that the data for the messagerepository is contained in columns 1 through 63. In this example, we assume thatwe specified the SID codes in columns 64 through 71.

Once the errors are corrected in the message repository file, enter the followingGENMSG command to compile SPGMES REPOS:GENMSG SPGMES REPOS A SPG ( CP MARGIN 63

The CP operand indicates that the object file should be in a format useable by CP.CP's message repository format is different from the format used by CMS andother components.

Example 2Enter the following GENMSG command to check for errors in your messagerepository file called SPGMES REPOS and to compile SPGMES REPOS:GENMSG SPGMES REPOS A SPG (CP

In this example, the MARGIN 63 option is not used. The data for the messagerepository is expected to be in columns 1 through 71. Once again, the CP operandis specified so that the correct format of the object directory is created.

If there are incorrect syntax statements in the message repository file, correct theerrors and issue the command again.

Loading and Unloading Message FilesOnce you have created the object repository, you will need to make it accessible byCP code. This will consist of moving the file to CP accessed minidisks, loading itinto the system execution space, and associating the message repository with acomponent ID and language.

As indicated in Chapter 4, “Loading Dynamically into the System ExecutionSpace,” on page 39, the message must be loaded into the system execution spaceprior to attempting to use it in CP code. In order to access the file as part of theload function, CPXLOAD requires that the object repository file reside on aCP-accessible minidisk.

Once the object repository file is on the CP-accessed minidisk, you can invokeCPXLOAD to load it into the system execution space. Continuing with ourexample repository of SPGMES, we would issue the following command:CPXLOAD SPGMES TEXT * TEMPORARY NOCONTROL

SPGMES TEXT is the file to be loaded and it is located on one of the CP accesseddisks. The file is loaded TEMPORARY so that it can be replaced if necessary. Nocontrol entry point is associated with this load.

Once loaded into the system execution space, the next task is to associate themessage with a component ID so that invocations of HCPCONSL for thatcomponent will find the repository. Unlike exits, we must load the repository usingCPXLOAD prior to associating the entry point.

Your Own Messages


ASSOCIATE MSGS COMP SPG EPNAME SPGMES

SPGMES is the entry point that is to be associated with component SPG. Thelanguage is not specified on the ASSOCIATE command because that informationwas specified when the object repository file was created by GENMSG.

If you wish to replace an existing message repository then you will need todisassociate the repository file and unload it prior to replacing it. An alternative isto associate a different entry point with the component for the language beingreplaced (see example 2 below).

Example 1DISASSOCIATE MSGS COMP SPG LANGUAGE UCENG

As with the ASSOCIATE MSGS command, we specified the component ID butinstead of an entry point we specified the language which we will disassociate.This is necessary because the same entry point could have been associated withdifferent languages. We must disassociate the object repository with each languageand component that it is associated prior to unloading it.

Example 2ASSOCIATE MSGS COMP SPG REPLACE EPNAME SPGMET

The REPLACE operand on the ASSOCIATE MSGS command indicates that theexisting repository file for the language contained in SPGMET is to be replaced.

CPXUNLOAD will unload the message repository from the system executionspace. For further information on unloading files, see Chapter 8, “UnloadingDynamically from the System Execution Space,” on page 71.

Producing Messages from a RepositoryNow you know how to add a message repository to the system. The next step is todiscuss how the system decides which repository to use and how you can codeinvocations of a CP macro to generate the messages.

HCPCONSL is the macro that encapsulates the calls to message routines thatgenerate messages or read input. You should consult the macro prologue forfurther information about its use. The examples in this section will illustrate themost common usage of the macro. See Chapter 3, “Creating a Dynamically LoadedRoutine,” on page 13 for a discussion of the HCPCONSL macro.

How Does CP Choose Which Repository to Use?When searching the message repositories for a message, CP limits its search byasking two questions.

Question 1:Which component ID is being used on the invocation of HCPCONSL? CPwill search only the repositories associated with the component IDspecified on the HCPCONSL invocation. If the COMPID= operand is notspecified then the component ID defaults to the system repository,COMPID=HCP.

Your Own Messages


Question 2:Is there a repository for the current language being used by the receiver ofthe message? Only the correct language message repository will besearched.

When the appropriate repositories are located (there can be more than one entrypoint associated with a specific message repository) then the repositories aresearched in the order in which the repositories were associated with thecomponent by the ASSOCIATE MSGS command.

For component HCP, the local repositories are searched prior to searching thedefault system repository. This allows you to override CP message texts with yourown message texts.

If the message is not found in the message repositories then the message will bedisplayed without the message text but may include any substitution data. Theseverity field in the message header is set to 'E' because the severity code couldnot be obtained from the message repository. Of course, the resulting messageoutput depends upon both the HCPCONSL operands and the user messagesettings. Table 4 shows the output when a message is found and the output when amessage is not found in the repository.

Table 4. Results if a message is found or not found in a repository.

EMSG Setting Substitution data Message Found Message Not Found

CODE n/a message header only message header only

ON no message header and messagetext

message header only

ON yes message header and messagetext with substitution data

message header withsubstitution data separated byblanks

TEXT no message text only blank line

TEXT yes message text withsubstitution data

substitution data separated byblanks

Producing Messages Without SubstitutionThe following is an example of an HCPCONSL invocation for the repository inFigure 4 on page 62 to display a message without substitution.

The HCPCONSL invocation:

WRITEindicates that a console write is requested.

HCPCONSL (WRITE), XCOMPID=’SPG’, XREPOSNUM=’MS000501’

B EXIT Skip around constantsSPACE 1

MS000501 EQU X’00000501’ Message number/version in hex

Figure 5. Sample Assembler Code Accessing SPGMES REPOS from module HCPXXX

Your Own Messages


COMPID=indicates the component ID whose repositories are to be searched for thespecified message number and version.

REPOSNUM=indicates the equate containing the message number and version.

The result of the previous HCPCONSL invocation is:

HCPXXX005E Invalid syntax; please issue command again

Producing Messages With SubstitutionIn the SPGMES REPOS example, the text for each message is the same every timethe message is displayed. However, you will probably want to have some messagetexts that are similar, but say different things depending on the situation. Forexample, you might have a message that says:Invalid option: GO

But you also want to have these messages in your repository:Invalid option: FILEInvalid option: RUNInvalid option: STOP

You do not need four separate messages in your repository. Instead, you can createa single message text that contains a substitution indicator. CP will substitutedifferent information using this substitution indicator. For example, your repositorycould look like this:

Messages that require substitutions have parameters in a form defined by the user(for example, $1, $2 ...). These parameters show the placement of the substitutionsand their order. The first character in the first noncommentary record of the sourcerepository defines the substitution character. This character cannot be a DBCScharacter.

Here are some rules about substitutions:v A substitution can be a single word, a phrase, or an entire sentence.v A substitution can go anywhere within a message.v You can have more than one substitution per message.v Trailing blanks from the substitution data are removed when non-column format

is used.

JCRMES REPOS A1 F 80 Trunc=80 Size=6 Line=1 Col=1 Alt=0

===== * * * Top of File * * *|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...

===== *===== * This is an example of a message repository file that===== * uses simple substitution.===== *===== $===== 020001 E Invalid option: $1===== * * * End of File * * *

Figure 6. Sample Repository - JCRMES REPOS

Your Own Messages


The following is an example of an HCPCONSL invocation for the repository inFigure 6 on page 67.





SUBDATA=indicates the variable containing the message substitution data. The end ofthis data is signaled by the x'ff' value.

The result of the previous HCPCONSL invocation is:

HCPXXX200E Invalid option: FILE

Producing Messages With Column FormatSubstitution can also be used to build messages with column alignment. Therepository in Figure 8 illustrates the use of substitution in this manner.

Here is a line-by-line description of what this repository contains:

Line number(s)Explanation

HCPCONSL (WRITE), XCOMPID=’JCR’, XREPOSNUM=’MS020001’, XSUBDATA=MSGSUB Generate the message


MS020001 EQU X’00020001’ Message number/version in hexMSGSUB DC C’FILE’,X’FF’ Substitution data

Figure 7. Sample Assembler Code Accessing JCRMES REPOS from module HCPXXX

JAFMES REPOS A1 F 80 Trunc=80 Size=14 Line=1 Col=1 Alt=0

00000 * * * Top of File * * *|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...

00001 *00002 * This is an example of a message repository file made via XEDIT00003 * and maintain alignment of data.00004 * You can code a file similar to this for your application.00005 *00006 $00007 74000101R PREV OWNER CURR OWNER NEXT OWNER00008 74000102 ---------- ---------- ----------00009 74000103 USERID $1 $3 $500010 74000104 NODEID $2 $4 $600011 * * * End of File * * *

Figure 8. Sample Repository - JAFMES REPOS

Your Own Messages


1 - 5 Comment lines.

6 The control line.

A dollar sign ($) is the substitution character.

7 - 10 Message number is 7400. This message has only one format and will bedisplayed as four lines. There are six substitution indicators which shouldline up as specified. We made certain that the substitution data will fitwithin the space set aside for the data. This was done by specifyingenough blank space so that the substitution data may replace the indicatorand the extra blank space.

Because the message number is in the range of 7000-7999, CP will displaythe message without the message header. The 7000 series messages arenormally used for responses that do not utilize a header.

Here are some rules about column substitutions:v The message in the repository must have a number of blanks following the

substitution data symbol, '$nnn', such that the length of the symbol plus thenumber of blanks is equal to or greater than the maximum length of thesubstitution data.

v If the length of the substitution data is less than the length of the substitutionsymbol, '$nnn', blanks will be placed after the substitution data to make it thesame length as the '$nnn'.

v If a message substitution place holder is used, blanks will be filled in thatsubstitution field.

The following is an example of HCPCONSL invocations for the repository inFigure 8 on page 68.




DATAEDIT=indicates the format of the data which in this case is column formatted.

HCPCONSL (WRITE), XCOMPID=’JAF’, XREPOSNUM=’MS740001’, XDATAEDIT=COLFORMAT, XSUBDATA=MSGSUB Generate the message


MS740001 EQU X’00740001’ Message number/version in hexSPACE 1

* Keep the following 6 lines togetherMSGSUB DC CL8’POWNER’,X’00’ Substitution data 1 + separator

DC CL8’VM1’,X’00’ Substitution data 2 + separatorDC CL8’COWNER’,X’00’ Substitution data 3 + separatorDC CL8’VM2’,X’00’ Substitution data 4 + separatorDC CL8’NOWNER’,X’00’ Substitution data 5 + separatorDC CL8’VM3’,X’FF’ Substitution data 6 + end flag

Figure 9. Sample Assembler code accessing JAFMES REPOS

Your Own Messages



SUBDATA=indicates the variable containing the message substitution data. The end ofthis data is signaled by the x'ff' value.

The output from this HCPCONSL invocation will look like this:

PREV OWNER CURR OWNER NEXT OWNER---------- ---------- ----------

USERID POWNER COWNER NOWNERNODEID VM1 VM2 VM3

When You Cannot Use a Message RepositoryThere are situations when you cannot use a message repository or HCPCONSL.These situations include:v Points in the code where you cannot tolerate a loss of control.v From modules that do not have a savearea.v From modules that run under CMS (e.g. DIRECTXA) or are standalone routines

(e.g. HCPSAL).v Points early in initialization processing or near the end of system termination

processing.v Modules where R11 does not point to a VMDBK.

Your Own Messages


Chapter 8. Unloading Dynamically from the System ExecutionSpace

This section describes how to remove your dynamically loaded routines from thesystem execution space.

What May Be UnloadedAny module that was loaded by CPXLOAD TEMPORARY may be unloaded byCPXUNLOAD. Usually, any such module may be unloaded at any time. Thiswould include modules that contain external symbols used as entry points forcommands, Diagnose codes, or CP exit routines. If the CPXLOAD was performedwith the PERMANENT operand, the CPXUNLOAD command will be rejected withthis error message:

HCP2769E CPXUNLOAD for load ID $1 has been rejected;the requested load ID was loaded as PERMANENT

There is nothing to be done, except to remember to perform a CPXLOADTEMPORARY the next time that you load the module. This will need to be doneafter the next IPL.

Even if loaded by CPXLOAD TEMPORARY, there still are reasons why theCPXUNLOAD command could fail. An error message from CPXUNLOAD mayindicate that the CPXUNLOAD command may not be issued at this time:

HCP2769E CPXUNLOAD for load ID $1 has been rejected;the requested load ID is still in use by asystem service

This indicates that something that was loaded as part of the indicated load IDcannot be unloaded at this time without exposing CP to catastrophe. The systemservice that may be involved could be message processing.

Some external symbol from the load ID has been associated with messageprocessing by ASSOCIATE MESSAGE. The external symbol must be removed fromthis association before CPXUNLOAD can be permitted.

To see if the external symbol is in use for message processing, issue the followingcommand:

CP QUERY CPLANGLIST ASSOCIATED

Removal from use for message processing can be accomplished by either of thefollowing commands:v ASSOCIATE MESSAGE with the REPLACE operand, without including the

external symbol among the EPNAME list of external symbolsv DISASSOCIATE MESSAGE

Another exception would be when the CPXUNLOAD command is rejected by theCONTROL routine. If this happens, this message should be displayed:

HCP2769E CPXUNLOAD for load ID $1 has been rejected;the request was denied by the control entrypoint


This indicates that the control routine specified on the CPXLOAD request for thisload ID has decided that the CPXUNLOAD request must not be processed. A wellbehaved control routine will indicate why it rejected the CPXUNLOAD request.Because this decision is completely under the control of the control routine, CP hasno idea why the request was rejected. The only thing that CP will do is honor thecontrol routine's decision. You will need to examine any messages from the controlroutine to determine your next action.

CPXLOAD Load ID NumberThe syntax for the CPXUNLOAD command requires the load ID assigned byCPXLOAD. This number can be remembered from the time of the CPXLOADrequest, or can be determined from QUERY CPXLOAD responses. However it maybe determined, supply it on the CPXUNLOAD command.

When to Use ASYNCHRONOUS and SYNCHRONOUSA CP command is normally processed under the control of the user's VirtualMachine Definition Block (VMDBK). While processing a command, no otheractivity for that VMDBK is allowed. This means that any other command that theuser may issue is held waiting until all prior commands issued by the user havecompleted.

In a busy system, a CPXUNLOAD command may take longer than the user iswilling to wait. To complete a CPXUNLOAD request, CP must prevent all newattempts to use the module, and then wait until all present uses complete. Then,finally, CP can remove the module from storage.

To avoid such a delay, the user may use the CPXUNLOAD ASYNCHRONOUSoperand (which is the default). This operand tells CP to process the command onthe system's VMDBK, not on the user's VMDBK. By switching the command to thesystem's VMDBK, CP can make the user's VMDBK immediately available for morecommands. The user at the terminal is not delayed from doing more work.

If the CPXUNLOAD ASYNCHRONOUS operand is used by an EXEC or by aprogram, this also means that the EXEC or program continues executing beyondthe CPXUNLOAD command. If the CPXUNLOAD processing generates aninformational message or an error message, there is no program ready to receive it.Therefore, all messages will be sent to the user's terminal. This also means that theEXEC or program will not know if the CPXUNLOAD command succeeded orfailed.

The best use of the SYNCHRONOUS and ASYNCHRONOUS operands is this:v If the user is issuing the command at the terminal, use (or allow to default to)

the ASYNCHRONOUS operand. The user may continue working while theCPXUNLOAD command continues.

v If the user is issuing the command by an EXEC or a program, use theSYNCHRONOUS operand. The EXEC or program can then look for messages orerror return code from the command and make decisions about how to proceed.

Unloading from the SXS


Chapter 9. Understanding the CP Parser

The CP parser simplifies the process of developing new CP commands andconfiguration file statements. Rather than writing code to implement the logic forparsing an input string, you can make use of the CP parser facilities to handle thateffort for you.

By using a set of syntax definition macros, you define your syntax and generatethe data structures that represent that syntax. The CP parser can then use thatinformation to parse an input string (for example, a command). Based on how youdefine your syntax, the parser can perform tasks such as:v Generating messages for certain error situationsv Converting token values for youv Saving information in data areas of your choicev Driving a post-processor routine you provide to handle additional processing

Introduction to the Syntax Definition MacrosThe parser facility provides the following set of syntax definition macros that youcan use to define the rules of your syntax:v HCPCFDEF

This macro is used to mark the start of a given command or configuration filestatement. You use this macro to define the command or statement verb. Theminimum abbreviation can be specified either through the transition from upperto lower case in the verb (e.g. 'DISconnect' has a minimum abbreviation of 3characters) or by means of a keyword parameter. You can also use this macro toindicate the name of a post-processor routine you want called if the statement orcommand entered passed all syntax checks.For a description of all of the parameters available on this macro refer to“HCPCFDEF: Command/Config File Statement Definition Macro” on page 212.

v HCPSTDEFEach HCPCFDEF macro has one or more HCPSTDEF macros associated with it.The HCPSTDEF macro identifies the additional states or pathways that exist inyour command or statement syntax. There are keyword parameters to describeproperties associated with the tokens that are parsed. For example, is the tokenoptional; is at least one token match out of a list of possible choices required; isit acceptable to find no tokens on the input line. There are keyword parametersthat tell the parser what HCPSTDEF macro to look at next when a token matchoccurs. There are also keyword parameters that can be used to identify errormessage equates to be used for the certain missing token situations.For a description of all of the parameters available on this macro refer to“HCPSTDEF: Parser State Definition Macro” on page 216.

v HCPTKDEFEach HCPSTDEF macro has one or more HCPTKDEF macros associated with it.The HCPTKDEF macro defines what a token can be and what the parser shoulddo when that token is found. There are keyword parameters that let you tell theparser the type of validation you want performed on the token. For example, isthe token a valid hex number; is the token within a specified range of numericvalues; is the token something that would be a valid file mode. There are avariety of keywords to tell the parser how to store information into plist areas


passed to the parser. You can indicate error message equates to use for certainerror conditions. There are keyword parameters that can be used to tell theparser what HCPSTDEF macro to look at next when a token match occurs.For a description of all of the parameters available on this macro refer to“HCPTKDEF: Parser Token Definition Macro” on page 219.

v HCPDOSYNThe HCPCFDEF, HCPSTDEF and HCPTKDEF provide a way to set globalvariables, but they do not generate any actual data structures. The HCPDOSYNmacro takes the global variables and creates the data structures that representyour syntax definition. The HCPDOSYN macro identifies the plists that are usedfor storing information. You can provide error message equates to be used for avariety of syntax errors that may be detected. The HCPDOSYN macro alsoprovides a way for you to tie together syntax definitions that have been splitover several modules.For a description of all of the parameters available on this macro refer to“HCPDOSYN: Parser Syntax Table Generator Macro” on page 214.

Understanding How to Code for the Parser Using an ExampleIn this example we will cover the various steps necessary to develop a syntax tablefor use with the CP parser and the related processing. Ours is a 10 Step Process:

Steps What to do

1 Develop the command syntax

2-5 Determine the locations of the HCPCFDEF, HCPSTDEF and HCPTKDEFmacros

6-7 Further develop the HCPSTDEF and HCPTKDEF macros to transitionflows and error processing.

8 Develop the HCPDOSYN macro.

9 Write the code to call the parser.

10 Write the commands to activate the code.

Step 1: Develop the Syntax Railroad Track DiagramWe will not go into great detail on railroad track diagrams. Instead, we will usethe railroad track diagram as a tool to develop our command syntax. See “Syntax,Message, and Response Conventions” on page xiii for a discussion of railroad trackdiagrams.

Let's begin with a very simple command. From there we will construct morecomplex versions of our command until we get to one that is sufficiently complexto illustrate various aspects of the parser. You should note that we could haveeasily implemented the simplest command and added the additional complexitylater. One of the great strengths of the CP parser is the ease with which it canhandle new syntax.

Our simplest railroad track syntax will be a command to ask Dad for n dollars. Ofcourse, we can show you how to code the command syntax to request the dollarsbut we cannot show you how to get the dollars from Dad.

CP Parser


►► ASK DAD FOR n DOLLARS ►◄

We expand this to give a choice of whom to ask for the money.

►► ASK DADMOM

FOR n DOLLARS ►◄

Let's expand this even further to ask additional people.

►► ASK DADMOMAUNT nameUNCLE namefriend

FOR n DOLLARS ►◄

Now that we have grown who to ask, let us expand our horizons and think abouta way to ask for a car instead of only money.


FOR n DOLLARSCAR

►◄

Finally, let's improve the command so that it is closer to an actual language. Wewill do this by adding in the ability to specify the word "THE" if desired. In thisexample, "THE" is affectionately known as a "noise word"; its presence or absenceadds nothing to the syntax.


FOR n DOLLARSCAR

THE

►◄

This, then, is the syntax that we will describe in the parser macros.

CP Parser

Chapter 9. Understanding the CP Parser 75

Step 2: Assign HCPCFDEF Macro to the First TokenThe HCPCFDEF macro starts the syntax macro definition. We list the commandname with this token. So that you can follow our example, we will place "CF" atthe location in the railroad track diagram to show that we have coded theHCPCFDEF macro.

►►(1)

– ASK DADMOMAUNT nameUNCLE namefriend

FOR n DOLLARSCAR

THE

►◄

Notes:

1 HCPCFDEF 'ASK'

Step 3: Mark Alternative Path LocationsNow, we want to determine the various points on the railroad track diagramwhere we must handle alternate paths. Remember that at every word is an implicitpath that can be thought of as "this is wrong". So, even when it appears that thereis no possible alternate path (as in the path 'AUNT-name'), there is always theimplicit path to the end of parsing and a possible error message. Mark such places.Also, we want to mark the end of the railroad track syntax.

►►(1)

–(2)

ASK(2)

DADMOM

(2)AUNT name

(2)UNCLE namefriend

(2)FOR ►

►(2) (2)

n DOLLARS(2) (2)

– – CARTHE

►◄

Notes:

1 HCPCFDEF 'ASK'

2 HCPSTDEF

CP Parser


Step 4: Assign HCPSTDEF Macro to Alternative PathLocations

Assign HCPSTDEF macro to each location that was marked as an alternate path.

►►(1)

–(2)

ASK(5)

DADMOM

(3)AUNT name

(4)UNCLE namefriend

(6)FOR ►

►(7) (10)

n DOLLARS(8) (9)

– – CARTHE

►◄

Notes:

1 HCPCFDEF 'ASK'

2 HCPSTDEF

3 HCPSTDEF

4 HCPSTDEF

5 HCPSTDEF

6 HCPSTDEF

7 HCPSTDEF

8 HCPSTDEF

9 HCPSTDEF

10 HCPSTDEF

Step 5: Assign HCPTKDEF Macro to Each TokenFor each HCPSTDEF (state definition) we want to code HCPTKDEF macros thatindicate the possible tokens that can be encountered and the action to perform.Remember that every HCPSTDEF requires at least 1 HCPTKDEF, even if only tospecify HCPTKDEF TYPE=NULL to indicate there is no token.

Five HCPTKDEF macros are added to the ST_1 HCPSTDEF macro. They describethe possible choices (MOM, DAD, ...).

As with REXX SELECT statements or CASE statements in other languages, the firststatement that satisfies the "when" portion will be processed. For example, if wehad coded the HCPTKDEF for friend (TYPE=TOKEN) as the first HCPTKDEF, thennone of the others would be processed because TYPE=TOKEN says that a matchoccurs if any token is found. So, we would match TYPE=TOKEN for 'DAD',

CP Parser


'MOM', 'AUNT' and 'UNCLE'. Because we do not want this to occur, we arecareful in placing the HCPTKDEFs to avoid such confusion.ST_1 HCPSTDEF

HCPTKDEF ’DAD’HCPTKDEF ’MOM’HCPTKDEF ’AUNT’HCPTKDEF ’UNCLE’HCPTKDEF TYPE=TOKEN For ’friend’

Let us code the rest of the HCPTKDEF macros for the other HCPSTDEF macrosST_2 through ST_8. You should notice that in HCPTKDEF for ST_5 we are usinganother conversion type, DEC. This tells the parser that the token must be adecimal character value for a match to occur and that the token should beconverted from decimal characters to their binary value when the value is saved.ST_2 HCPSTDEF

HCPTKDEF TYPE=TOKEN For ’name’ST_3 HCPSTDEF

HCPTKDEF TYPE=TOKEN For ’name’ST_4 HCPSTDEF

HCPTKDEF ’FOR’ST_5 HCPSTDEF

HCPTKDEF TYPE=DEC For ’n’ST_6 HCPSTDEF

HCPTKDEF ’DOLLARS’ST_7 HCPSTDEF

HCPTKDEF ’THE’ST_8 HCPSTDEF

HCPTKDEF ’CAR’

We code the HCPTKDEF for the final HCPSTDEF as TYPE=NULL so that theparser knows that we should not expect any additional operands when processingthis HCPSTDEF state.ST_9 HCPSTDEF HCPTKDEF TYPE=NULL

Step 6: Add the Keywords for the MacrosOur next step is to provide the necessary information to the parser so that itknows how to flow control from the HCPCFDEF macro and among theHCPSTDEF macros.

Since we plan to process the command directly after the parser returns control toour program, we have no post-processor subroutine. Therefore, we codePROCESS=NONE on the HCPCFDEF macro. We will define default transitionflows on the HCPSTDEF macros to indicate what happens if any HCPTKDEF has amatch. We will also define specific transition flows on the HCPTKDEF macros toinform the parser where control flows if a match occurs with that HCPTKDEFmacro. Both macros use the operand NEXT= to define the transition.

We must also indicate to the parser whether a match is required in order for atransition to occur to another HCPSTDEF macro. This is handled using theREQMATCH= operand on the HCPSTDEF macro.

We can also provide the parser with additional rules concerning conflicting optionsso that it can detect those conflicts for us. The CONFLICT= operand on theHCPTKDEF allows us to indicate an arbitrary numeric value (from 1 to 255) whichindicates a possible conflict. When the parser detects that it has a match on aHCPTKDEF macro it will compare the conflict values on that HCPTKDEF macrowith any accumulated conflict values. If the value has already been saved, then wehave a conflict and an error will be generated. Otherwise, there is no conflict. The

CP Parser


parser adds any conflict values from this HCPTKDEF macro to the accumulatedconflict values for later conflict checking, and then continues processing.

Let us update the ST_1 HCPSTDEF macro and related HCPTKDEF macros. Youshould note that we indicate on the HCPSTDEF macro that a match is required forone of the possible tokens (DAD, MOM, AUNT, UNCLE, any non-blank word). Weadd the NEXT= operands to indicate where parsing flows when any of theHCPTKDEF macros match. We also use the CONFLICT= operand to friendHCPTKDEF macro because we want the parser to look for and to reject what wehave decided as an unacceptable combination (in this case, asking a friend formoney).

HCPCFDEF ’ASK’,PROCESS=NONE

ST_1 HCPSTDEF REQMATCH=YESHCPTKDEF ’DAD’,NEXT=ST_4HCPTKDEF ’MOM’,NEXT=ST_4HCPTKDEF ’AUNT’,NEXT=ST_2HCPTKDEF ’UNCLE’,NEXT=ST_3HCPTKDEF TYPE=TOKEN,NEXT=ST_4, For ’friend’

CONFLICT=1 Do not ask for money

We update the HCPSTDEF/HCPTKDEF groups for ST_2 through ST_4 in the samemanner. Notice that we did not specify a NEXT= operand for the ST_4 group. Wecan do this because the default transition is to the next HCPSTDEF/HCPTKDEFgroup that follows the current group. Thus, a match in ST_4 will flow into ST_5.ST_2 HCPSTDEF REQMATCH=YES

HCPTKDEF TYPE=TOKEN,NEXT=ST_4 For ’name’

ST_3 HCPSTDEF REQMATCH=YESHCPTKDEF TYPE=TOKEN,NEXT=ST_4 For ’name’

ST_4 HCPSTDEF REQMATCH=YESHCPTKDEF ’FOR’

ST_5 shows an interesting series of checking. Should a match occur with theHCPTKDEF TYPE=DEC, then we will flow to ST_6. But a match is not requiredand we would flow to ST_7 if a match does not occur. This illustrates the use ofthe NEXT= operand on the HCPSTDEF macro in conjunction with the HCPTKDEFmacro.

CONFLICT=1 is specified. Had the parser earlier matched the HCPTKDEF for'friend', it would have saved the CONFLICT=1 value from that HCPTKDEF. If theparser now matches this HCPTKDEF TYPE=DEC macro, the parser would detectthe conflict and generate the error message specified by the HCPDOSYN macrokeyword CONFLCT=. Thus, we would delegate to the parser the work to enforcethe rule that we do not ask friends for money.

In addition, we have added a new operand on the HCPTKDEF macro. TheRANGE= operand informs the parser of additional rules that it needs to enforce. Inour case, the token must be a decimal value, conflict 1 must not be on (do not aska friend for money) and the value of token must be at least 1 and no more than10,000.ST_5 HCPSTDEF REQMATCH=NO,NEXT=ST_7

HCPTKDEF TYPE=DEC,NEXT=ST_6, For ’n’CONFLICT=1, Do not ask friendRANGE=(1,10000) No more than 10,000

CP Parser


ST_6 informs the parser that DOLLARS is a required token following the decimalvalue detected by ST_5. If there is no token from the input so that the parser hasnothing to check, then error message 6704-01 should be generated from themessage repository.ST_6 HCPSTDEF REQMATCH=YES,MISSING=MS670401

HCPTKDEF ’DOLLARS’,NEXT=ST_9

ST_7 and ST_8 use the operands that we have already discussed, so we havenothing wonderful to say about this segment of the syntax table. You may wish tonote that they have been updated for the transition flow between states.ST_7 HCPSTDEF REQMATCH=NO,NEXT=ST_8

HCPTKDEF ’THE’,NEXT=ST_8

ST_8 HCPSTDEF REQMATCH=YESHCPTKDEF ’CAR’,NEXT=ST_9

The operand FINISH=YES marks the end of the syntax table. ST_9 informs theparser that, if we reach this HCPSTDEF, we are to end here and that no operandsshould be left to be processed.ST_9 HCPSTDEF REQMATCH=NO,FINISH=YES

HCPTKDEF TYPE=NULL

Step 7: Develop the Storage Area DefinitionsWhile it is nice for the parser to validate the syntax of a command or statement, itis even nicer that it can update storage areas with what has been specified.HCPTKDEF supports the STORE=, ORFLAG= and ANDFLAG= operands to storedata, 'OR' flag bits to turn them on, and 'AND' flag bits to turn them off,respectively. The target location for these storage operands would need to bedescribed in an assembler language DSECT.

The DSECT might appear as follows. In this example, this DSECT is made theprimary output plist by the PLBASE= keyword on the HCPDOSYN macro, whichwe will discuss in a later step. Here we see the definition of field names andequates to be used by the STORE=, ORFLAG= and ANDFLAG= operands.

ASKDSECT DSECTHOWMUCH DS FCWHO DS CL15FROM DS BFAUNT EQU X’80’FDAD EQU X’40’FFRIEND EQU X’20’FMOM EQU X’10’FUNCLE EQU X’01’WHAT DS BFCAR EQU X’20’FUSD EQU X’02’LENDSECT EQU *-ASKDSECT

Our expansion of the parser macros has grown with the addition of the newoperands. ST_1, ST_6 and ST_8 show some simple OR operations using theORFLAG= operand (for example, the bit defined by the FDAD equate would be'OR'ed into the FROM field). ST_1, ST_2, ST_3 and ST_5 illustrate the use of theSTORE= operand to indicate to the parser where it should store the token orconverted data that it has encountered. The stored result is not allowed by theparser to be longer than the specified output field. An error message would begenerated.

CP Parser


CFDEF HCPCFDEF ’ASK’,PROCESS=NONE

ST_1 HCPSTDEF REQMATCH=YESHCPTKDEF ’DAD’,NEXT=ST_4,

ORFLAG=(FROM,FDAD)HCPTKDEF ’MOM’,NEXT=ST_4,

ORFLAG=(FROM,FMOM)HCPTKDEF ’AUNT’,NEXT=ST_2,

ORFLAG=(FROM,FAUNT)HCPTKDEF ’UNCLE’,NEXT=ST_3,

ORFLAG=(FROM,FUNCLE)HCPTKDEF TYPE=TOKEN,NEXT=ST_4, For ’friend’

CONFLICT=1, Do not ask for moneyORFLAG=(FROM,FFRIEND),STORE=CWHO

ST_2 HCPSTDEF REQMATCH=YESHCPTKDEF TYPE=TOKEN,NEXT=ST_4, For ’name’

STORE=CWHO


STORE=CWHO


ST_5 HCPSTDEF REQMATCH=NO,NEXT=ST_7HCPTKDEF TYPE=DEC,NEXT=ST_6, For ’n’

CONFLICT=1, Do not ask friendRANGE=(1,10000), No more than 10,000STORE=HOWMUCH

ST_6 HCPSTDEF REQMATCH=YES,MISSING=MS670401HCPTKDEF ’DOLLARS’,NEXT=ST_9,

ORFLAG=(WHAT,FUSD)

ST_7 HCPSTDEF REQMATCH=NO,NEXT=ST_8HCPTKDEF ’THE’,NEXT=ST_8

ST_8 HCPSTDEF REQMATCH=YESHCPTKDEF ’CAR’,NEXT=ST_9,

ORFLAG=(WHAT,FCAR)

ST_9 HCPSTDEF REQMATCH=NO,FINISH=YESHCPTKDEF TYPE=NULL

Step 8: Develop the HCPDOSYN MacroThe HCPCFDEF, HCPSTDEF, and HCPTKDEF macros have not built any controlblocks to define the structure. They only updated macro variables needed to definethe structure. The HCPDOSYN macro will build the necessary control blocks thatthe parser will use.

As we mentioned earlier, we need to inform the parser about the data areas thatwe will use, parameter lists that we use, and inform the parser about whichmessages to generate should we find any one of a number of miscellaneous errors.

Because we are storing into one data area, we can use this as our primaryparameter list. In our case, we will code the HCPDOSYN macro with theROOT=YES operand to indicate we want pointers to the various pieces of syntaxand any error message information common to all the pieces, thePLBASE=ASKDSECT operand to indicate the name of the primary plist and thePLLEN=LENDSECT operand to indicate the length of the plist in bytes. We will

CP Parser


also code the CONFLCT=MS001301 operand to indicate which error messageshould be generated when a conflicting option is detected.CFDEF HCPCFDEF ’ASK’,PROCESS=NONE

ST_1 HCPSTDEF REQMATCH=YESHCPTKDEF ’DAD’,NEXT=ST_4,

ORFLAG=(FROM,FDAD)HCPTKDEF ’MOM’,NEXT=ST_4,

ORFLAG=(FROM,FMOM)HCPTKDEF ’AUNT’,NEXT=ST_2,

ORFLAG=(FROM,FAUNT)HCPTKDEF ’UNCLE’,NEXT=ST_3,

ORFLAG=(FROM,FUNCLE)HCPTKDEF TYPE=TOKEN,NEXT=ST_4, For ’friend’

CONFLICT=1, Do not ask for moneyORFLAG=(FROM,FFRIEND),STORE=CWHO


STORE=CWHO


STORE=CWHO


ST_5 HCPSTDEF REQMATCH=NO,NEXT=ST_7HCPTKDEF TYPE=DEC,NEXT=ST_6, For ’n’

CONFLICT=1, Do not ask friendRANGE=(1,10000), No more than 10,000STORE=HOWMUCH

ST_6 HCPSTDEF REQMATCH=YES,MISSING=MS670401HCPTKDEF ’DOLLARS’,NEXT=ST_9,

ORFLAG=(WHAT,FUSD)

ST_7 HCPSTDEF REQMATCH=NO,NEXT=ST_8HCPTKDEF ’THE’,NEXT=ST_8

ST_8 HCPSTDEF REQMATCH=YESHCPTKDEF ’CAR’,NEXT=ST_9,

ORFLAG=(WHAT,FCAR)

ST_9 HCPSTDEF REQMATCH=NO,FINISH=YESHCPTKDEF TYPE=NULL

DOSYN HCPDOSYN ROOT=YES,PLBASE=ASKDSECT,PLLEN=LENDSECT,CONFLCT=MS001301

We have just finished defining the syntax table to handle our new command.

Step 9: Write the Code to Call the ParserIn this example, we are writing a new command so we will have to write code inthe command handler to pass the command to the parser and act on the responsefrom the parser. When coding the invocation of the parser, you should rememberto pass an address, where appropriate, or zero.

HCPGETST LEN=(R0) Get ASKDSECT areaLA R0,LENDSECT *LR Rx,R1 Base register

CP Parser


HCPUSING ASKDSECT,Rx *L R0,=A(DOSYN) Address of HCPDOSYN

LA R1,ASKDSECT Address of answer plistLA R2,0 Address of add’l basesL R3,=A(CFDEF) Address of HCPCFDEFHCPCALL HCPZPRPC Parse the command lineST R0,SAVER2 Store returned msg numberLTR R15,R15 Check out return codeBNZ EXIT Msg already issued by HCPZPRTM WHO,FDAD Was it ASK DAD?BO ASKDAD ..yesTM WHO,FMOM Was it ASK MOM?BO ASKMOM ..yes

...LA R1,ASKDSECT Release gotten storageHCPRELST BLOCK=(R1) *HCPDROP Rx Drop base register

For more information on the parser routines and their calling conventions, seeAppendix F, “CP Parser Macros and Routines,” on page 211.

Step 10: Write the Commands to Activate the CodeWe will leave this step to you because it is discussed in other areas of thisdocument. You will need to write at least CPXLOAD statements and DEFINEstatements for the SYSTEM CONFIG file.

Using the Parser to Store DataThe parser provides a mechanism to convert some external data, like a commandor a configuration file statement, into an internal format, like a fixed binary 32 bitnumber. To make this work, you need to provide the parser two basic pieces ofinformation:1. the rules for performing the conversions2. the place or places to store the results.

The rules for performing the conversions are called the syntax and you definethese rules using the syntax definition macros (i.e. HCPCFDEF, HCPSTDEF,HCPTKDEF, HCPDOSYN). The places to store the results are called the parameterlists (or plists). You code your syntax definition macros to identify the plists thatare used and to indicate how data is to be stored in these plists.

The parser uses two types of plists:1. Specified by PLBASE= on the HCPDOSYN macro

The plist specified by PLBASE= is known as the primary plist. It is also knownas plist number 0. You are allowed to specify one primary plist. The parser willclear the storage associated with this plist when it starts parsing the commandor configuration file statement.

2. Specified by BASES= on the HCPDOSYN macroThe plists specified by BASES= are known as the secondary plists. You canhave none or several of these depending on your needs. These represent otherareas where you might what to store data. They are numbered starting from 1.The plists specified by BASES= are never cleared.

Here is a picture of how the plists get passed to the parser:

CP Parser


R1 --> +-------------+| || PLBASE= || area || |+-------------+

R2 --> +-------------+| address 1 |+-------------+| address 2 |+-------------+| address 3 |+-------------+...+-------------+| address k-1 |+-------------+| address k |+-------------+

It is important that you build the list of addresses that R2 points correctly. That is,the content and the order must match what you have defined for the syntaxdescription with the BASES= parameter of the HCPDOSYN macro. If your syntaxdefinition does not specify any secondary plists with BASES=, then you wouldpass R2=0 to the parser.

The syntax will tell the parser which plist to use to store the results of theconversions. This is done (that is, the parser is told) by means of the HCPTKDEFand the HCPDOSYN macros.

Storage locations typically are specified in the parser syntax macros by thesemethods:

keyword=wherekeyword=(where,what)

Examples would be:STORE=whereORFLAG=(where,what)ANDFLAG=(where,what)

The value of "what" is simply anything that would be acceptable in anOr-Immediate (OI) instruction or in an And-Immediate (NI) instruction. The valueof "where" typically is specified in either of these 2 forms

fieldbase(field)

A simple "field" specification is always assumed to be based off the primary plist(that is, the PLBASE= value you specify on the HCPDOSYN macro). A "base(field)"specification is based off the secondary plist (that is, the BASES= value you specifyon the HCPDOSYN macro).

HCPTKDEF saves in assembler variables (for use later by the HCPDOSYN macro)the names of the DSECTs into which data are to be stored. For example, theseexample keywords

ORFLAG=(SYSCM(SYSIPLFL),SYSAUTOW)STORE=SYSCM(SYSCKVOL)STORE=SCFMACH

CP Parser


would cause HCPTKDEF to remember the target locations asSYSCM(SYSIPLFL)SYSCM(SYSCKVOL)SCFMACH

Later, HCPDOSYN will look at each target location. HCPDOSYN first tries tomatch the target location to something in BASES=. It does this by separating thestring into what appears to be a DSECT and a label (in these examples, SYSCMand SYSIPLFL; SYSCM and SYSCKVOL). If it cannot perform the separation, thenthe target location must be in the primary plist (in this example, SCFMACH mustbe in the primary plist).

After breaking apart the target location, HCPDOSYN searches for the apparentDSECT name in the BASES= list. If it does not find it, then the target location mustbe in the primary plist. The original target location string will be used. If it doesfind it, then it remembers which entry in BASES= satisfied the search. Finally,HCPDOSYN generates the syntax control blocks, where it saves the number 'n' ofthe plist area ('n' = 0 for the primary plist, 'n' > 0 for something in the BASES= list)and the offset into that DSECT to the target location.

Eventually your system is IPLed and the parser is called. One of the parameterspassed to the parser is R2, which has the address of the list of addresses that youset up to match the list of DSECT names in the BASES= keyword. As the parserprocesses the input against the syntax, it finds that something should be storedsomewhere and looks at the plist number that HCPDOSYN saved.

If the plist number 'n' = 0, then the parser uses whatever was in R1 as the baseaddress of the primary plist. Adding the offset to that value gives the address ofthe field.

If the plist number 'n' > 0, then the parser uses whatever was in R2 to be theaddress of a list of pointers, takes the n-th pointer as the base address of thesecondary plist. Adding the offset to that value gives the address of the field.

In the examples above, if we had this on our HCPDOSYNPLBASE=SCFBKBASES=(PFXPG,RDEV,SYSCM)

then HCPDOSYN would remember that SYSCM should be the third pointer in thelist. Any reference to SYSCM in the syntax macros would be converted to plistposition '3'. When the parser executes, it will take this plist number '3' and use thethird address located by R2 as the base address for SYSCM. The list of addressesthat you build and that point to with R2 should have the address of SYSCM in thethird position. If not, then the parser will get the wrong address and storeunpredictably.

If we call the parser this way (assume that at runtime that MYBASES has beenfilled in with addresses that the statements suggest and that you have obtainedstorage for the primary plist you have selected which is SCFBK in this example):

L R0,...LA R1,SCFBK Address of primary plistLA R2,MYBASES Address of secondary plistsL R3,...HCPCALL the parser

CP Parser


...MYBASES DSECT

DS A(PFXPG)DS A(RDEV)DS A(SYSCM)

then the plist numbers that HCPDOSYN saved are in the same sequence as thecontrol block addresses in the list that R2 points to, and good things should result.

If, however, we call the parser this way (addresses of SYSCM and PFXPG areswitched around in the MYBASES DSECT), bad things will happen.

L R0,...LA R1,SCFBK Address of primary plistLA R2,MYBASES Address of secondary plistsL R3,...HCPCALL the parser...

MYBASES DSECTDS A(SYSCM)DS A(RDEV)DS A(PFXPG)

The parser will try for the third pointer in MYBASES when it needs the address ofSYSCM (because HCPDOSYN remembered 'n' = 3 as the plist number for theSYSCM DSECT) and bad things will happen. Where we want to store into offsetX'6D3' into SYSCM for SYSIPLFL, we will actually be storing into PFXPG plusoffset X'6D3'.

Dividing Your Syntax over Multiple ModulesThe syntax you define can contain many statements of varying complexity. It ispossible that a syntax could grow too large to be conveniently contained in asingle module. In this case, you would need to define pieces of the syntax inseparate modules and then connect them so they can be used together. To do so,you would need to provide a main or "root" piece that would contain pointers tothe various pieces of the syntax. The "root" piece would also contain information(such as error message equates) that would be common for all pieces of the syntax.

In a single syntax piece, both the "root" and the syntax itself are generated togetherautomatically.

+--------++--| || | root || | |+->+--------+

| || syntax || |+--------+

In a situation where you have pieces of your syntax spanning multiple modules,you only want one "root" defined.

+--------++--| |--------------------->+--------+| | root |----->+--------+ | || | | | | | syntax |+->+--------+ | syntax | | |

| | | | +--------+| syntax | +--------+

CP Parser


| |+--------+

-1- -2- -3-

To generate the "root", use ROOT=YES on the HCPDOSYN macro. To avoid the"root", use ROOT=NO on the HCPDOSYN macro. To connect the "root" to theother two pieces of the syntax, use the SYNLIST= keyword on the HCPDOSYNmacro.

For this picture, you would have three modules, each would define its piece of thesyntax and would have its own HCPDOSYN macro. The SYNLIST= option on theroot HCPDOSYN macro is used to tie the various syntax pieces together.

For the first module, you would have:HCPDOSYN ROOT=YES,SYNLIST=(hcpdosyn2,hcpdosyn3)

We use the notation "hcpdosyn2" in order to indicate that you would specify thelabel on the HCPDOSYN macro in module 2. Similarly, the notation "hcpdosyn3"indicates that you would specify the label on the HCPDOSYN macro in module 3.

For the second module, you would have:HCPDOSYN ROOT=NO

For the third module, you would have:HCPDOSYN ROOT=NO

You should note that the HCPDOSYN macro generates an HCPENTRY instructionfor the labels that it generates so that they can be referenced externally from themodule which contains the HCPDOSYN macro. If you were to specify your ownlabel on the HCPDOSYN macro, then you would have to specify your ownHCPENTRY instruction.

Combining ROOT=, PLBASE=, BASES=, and SYNLIST=In the case of multiple syntax pieces, each must have the same set of plists defined.The parser is given only one set of addresses (in R1 and in R2). If the addresses donot match the labels on the PLBASE= and the BASES= keywords, then the parserwill use the wrong address when storing the result of its parsing.

So, in the case where we have multiple syntax pieces, we must specify identicalplists for all three pieces of the syntax.

+--------++--| |--------------------->+--------+| | root |----->+--------+ | || | | | | | syntax |+->+--------+ | syntax | | |

| | | | +--------+| syntax | +--------+| |+--------+

-1- -2- -3-

For the first module, you would have:HCPDOSYN ROOT=YES,SYNLIST=(hcpdosyn2,hcpdosyn3),

PLBASE=dsect0,BASES=(dsect1,dsect2)

For the second module, you would have:

CP Parser


HCPDOSYN ROOT=NO,PLBASE=dsect0,BASES=(dsect1,dsect2)

For the third module, you would have:HCPDOSYN ROOT=NO,

PLBASE=dsect0,BASES=(dsect1,dsect2)

Using a Post-ProcessorThere are times when the parser will be able to handle all the processing yourequire for your new command or configuration file statement. For example, if theonly thing you need to do is to save some information into existing control blocks,and the parser has access to these control blocks, then you can let the parser dothat work for you.

If, however, you have additional processing that you would like to perform afterthe parser has processed the syntax, then you have two choices. You can either1. handle that additional processing in your mainline routine, or2. you can move that processing to another routine that you would identify as

your post-processor.

Let us look at an example of each.

Providing Additional Processing in Your Mainline RoutineIf you have used the syntax macros to define the syntax for your own command,any additional processing that you want to perform can be coded in your mainlineroutine. This is, in general, the easiest thing to do. For example, consider the ASKcommand developed in previous examples. You did not need to use apost-processing routine because all additional processing was handled in themainline routine you wrote. That is, you wrote code in your command handler(your mainline routine) to pass the command to the parser and to act on theresults of the parsing.

your mainlineroutine CP Parser

+------------+ +----------+| | | || Call | | Handle || CP Parser |----->| syntax || |<-----|processing||+----------+| | ||| Handle || | |||additional|| | |||processing|| | ||+----------+| | |+------------+ +----------+

Providing Additional Processing in Your Post-processor.You could have chosen to use a post-processor routine instead of handling all theadditional processing in your mainline routine. The post-processor routine isspecified on the PROCESS= keyword of the HCPCFDEF macro. If you specify thename of a routine, that routine will be called by the parser as long as the parserprocessing completes without detecting an error. The post-processor performs itsown processing, and will return to the parser, which will finally return to themainline routine that called the parser.

your mainlineroutine CP Parser Post-processor

+------------+ +----------+ +------------+

CP Parser


| | | | | || Call | | Handle | |+----------+|| CP Parser |----->| syntax |----->|| Handle ||| |<-----|processing|<-----||additional||| | | | ||processing||| | | | |+----------+|| | | | | |+------------+ +----------+ +------------+

Typically, you only need to consider using a post-processor if you have used thesyntax macros to define the syntax for your own configuration file statement. Forconfiguration file statement processing, you do not provide the mainline routinethat calls the parser. Rather, CP does the work of reading the configuration file toisolate statements and CP does the work of setting up the calls to the parser. Sinceyou do not have a mainline routine of your own where you can code anyadditional processing, if you have additional processing you wish to perform, youmust provide that additional processing in a post-processing routine.

Using a Single Syntax for a Command and for a ConfigurationFile Statement

If you are developing something that you intend to use both as a command and asa configuration file statement, you need to code for the mixed environment.v Since the syntax macros will be used for parsing the configuration file statement,

you will probably code a post-processor.v Since these same syntax macros will be used for parsing the command, the same

post-processor will be used (because the same HCPCFDEF macro will be usedby the parser, and that HCPCFDEF macro specifies the post-processor name).

Therefore, all additional processing that you want to do will have to be done in thepost-processor, whether for the statement or for the command.

Creating Your Own Configuration File StatementsThe root syntax definition for all of CP's configuration file statements is found inHCPZSC. The EXTERNAL_SYNTAX statement provides a way to identify a syntaxdefinition that you want to have included as part of the syntax table for CP'sconfiguration file statements. CP will do the work of joining your syntax to theother syntax pieces so that you do not have to make any updates to the existingsyntax definitions in HCPZSC.

To establish your own configuration file statement, you need to define the syntaxusing the syntax definition macros (HCPCFDEF, HCPSTDEF, HCPTKDEF,HCPDOSYN). In addition, you optionally provide a post-processor subroutine tobe driven if the parsing completes successfully. You only need a post-processor ifthere is additional checking or processing that you would like to do after all parserprocessing is completed.

The EXTERNAL_SYNTAX statement you specify in the configuration file identifiesthe syntax definitions you have coded for your configuration file statements. CPwill treat that syntax definition as an additional piece of the existing syntax inHCPZSC, as if you had coded a SYNLIST= on the root HCPDOSYN macroinvocation. CP will insert your syntax definition into the syntax table so that it isexamined and used before any of the syntax definitions that CP has for its ownconfiguration file statements. Each EXTERNAL_SYNTAX syntax will be insertedinto the syntax table so that it is examined and used before any other existing

CP Parser


syntax definitions. EXTERNAL_SYNTAX gives you the ability to add your ownconfiguration file statement or to replace any existing CP statement.

Because you are defining a piece of a syntax to be added to the existing syntaxtables for configuration file statements, there are a few coding considerations tokeep in mind.v Primary Plist (PLBASE=)

The PLBASE= parameter on the root HCPDOSYN macro in HCPZSC defines theSCFBK as the primary plist that all configuration file statements use for parsing.This means that your syntax definition must also specify SCFBK as the primaryplist on the PLBASE= parameter of your HCPDOSYN macro. You cannot specifyanything else.If you plan to store information into the primary plist, the SCFMISC field is thearea in that control block that you can redefine and use for your own purposes.Your syntax definition and your post-processor do not necessarily have to usethe primary plist. For example, all of the storing you ask the parser to do mayinvolve only the data areas specified in the secondary plists.If you redefine the SCFMISC field, make sure that you do not exceed its size.You can make sure of this by using the following coding technique.SCFBK DSECT , Return to SCFBK

ORG SCFMISC Redefine SCFMISCMYFIELD1 DS ... One of my fieldsMYFIELD2 DS ... Another of my fields

CKMAINT (*-SCFMISC),GT,(L’SCFMISC) Error if trueORG , Return to end of SCFBK

v Secondary Plists (BASES=)The BASES= parameter on the root HCPDOSYN macro in HCPZSC defines thesecondary plists that all configuration file statements use for parsing. This is thelist of bases that are used by the syntax macros to figure out where they have tostore information. Because all of the syntax definitions for all of theconfiguration file statements are considered part of the same syntax structure,you must code the identical list on the BASES= parameter of your HCPDOSYNmacro. Your syntax may not necessarily make use of each entry in the bases list,however, your syntax definition must have that list in the same order asHCPZSC. You cannot change the order, delete any entries, or add new controlblocks to the list. If you want to save some information in a control block that isnot listed in BASES=, then this is work you must defer to your post-processor.For example, your syntax could save information in the primary plist and thenyour post-processor routine could move that information to a different location.The file HCPZSCBS COPY maps the pointers required by the syntax definitionin HCPZSC for configuration file statements. You can use this to interpret the listof base addresses that are passed to your post-processor routine.

v Specifying ROOT=The main control block that CP uses to find all of the syntax related controlblocks is created as a results of the ROOT=YES parameter on the HCPDOSYNmacro. Just as with any syntax definition that spans multiple modules, only oneof the syntax pieces can be considered the root. Your syntax definition isconsidered a secondary syntax piece, so the syntax definitions that you use musthave ROOT=NO specified on their HCPDOSYN macros.

Using One Syntax for Two PurposesIt is possible to connect the same syntax for more than one use. By this, we meanthat more than one "root" would connect to the same syntax.

CP Parser


+--------+ +--------++--| | | || | root |----->+--------+<-----| root || | | | | | |+->+--------+ | syntax | +--------+

| | | || syntax | +--------+| |+--------+-HCPZSC- -2- -3-

This is typically done in the situation where the syntax describes something youintend to use as both a configuration file statement and as a CP command. Let'stake this picture and show how the various pieces of syntax would be tiedtogether and how the HCPDOSYN macro should be coded for each.

In this example the first module represents HCPZSC which contains the rootsyntax definition for all of CP's configuration file statements. The second modulewould contain the syntax you have defined. The third module would be yourcommand handler which will call the parser to parse your command.

As we have explained before, the PLBASE= and the BASES= parameters must bethe same for all pieces of a syntax that are joined together so that the parser willbe able to determine correct storage locations. Because of the coding rules forconfiguration file statements with regard to the plists, then, the PLBASE= andBASES= parameters in this example will all have to match the ones whichHCPZSC defines for all configuration file statements.

The HCPDOSYN macro invocation in HCPZSC (the first module in our example)defines the root syntax for all configuration file statements. The SYNLIST= entrieswould identify other pieces of the syntax found in various CP modules thatcomprise the configuration file syntax table. The PLBASE= and BASES= keywordswould identify the plists that are used. For the purposes of this example, let'sassume the HCPDOSYN macro invocation in HCPZSC is as follows:

HCPDOSYN ROOT=YES,SYNLIST=(HCP...,...HCP...),PLBASE=SCFBK,BASES=(aaa,bbb,ccc)

For the second module which defines your syntax, notice that the value forPLBASE= and BASES= both match what is specified for HCPZSC above. Inaddition, the ROOT=NO keyword is used because this is just a piece of a syntax:

HCPDOSYN ROOT=NO,PLBASE=SCFBK,BASES=(aaa,bbb,ccc)

To make the connection between the syntax table in HCPZSC and your syntaxdefinition in module 2, you would code an EXTERNAL_SYNTAX statement likethe following:

EXTERNAL_SYNTAX EPNAME hcpdosyn2

The notation "hcpdosyn2" represents the label on the HCPDOSYN macroinvocation in module 2.

CP Parser


For the third module, notice that the value for PLBASE= and BASES= both matchwhat is specified in module 2. The ROOT=YES keyword is needed because thiswill be the root of the syntax used for command processing. The SYNLIST=keyword connects the root to the syntax piece you defined in module 2:

HCPDOSYN ROOT=YES,SYNLIST=(hcpdosyn2),PLBASE=SCFBK,BASES=(aaa,bbb,ccc)

Error Messages and How the Parser Handles ThemThe parser can issue error messages of your choice for most of the syntax errorsthat it detects. Message numbers for invalid command verbs, invalid keywords,conflicting keywords, extraneous keywords, and so forth are specified on theHCPDOSYN macro invocation. If there is no message number on the HCPDOSYNmacro for a detected condition, the parser does not issue a message when it detectsthe invalid syntax, but a return code reflects the invalid syntax to the callingroutine.

If a parsed token does not match any keywords specified on one of theHCPTKDEF macros under the current HCPSTDEF and the HCPSTDEF is codedwith REQMATCH=YES, the parser issues a bad keyword message from theBADKWD option on the HCPDOSYN macro.

If the last HCPTKDEF in the list contains only a conversion type and does nothave a keyword, and the token is invalid, the ERROR specification on theHCPTKDEF macro determines the error message to be issued. If the ERRORspecification is omitted, the parser uses the BADKWD specification from theHCPDOSYN macro instead.

If the parsed token matches a keyword specified on a HCPTKDEF entry for thecurrent HCPSTDEF, and the HCPTKDEF entry also contains a TYPE specification(thus requiring an additional token), one of two error conditions may occur:1. There may not be an additional token. In this case, the parser issues the error

message specified on the MISSING parameter of the HCPSTDEF macro or ofthe HCPDOSYN macro.

2. The additional token may be invalid because of the TYPE specified on theHCPTKDEF macro. In this case, the parser uses the message number specifiedon the ERROR parameter of the HCPTKDEF macro. If you omit the ERRORparameter, the parser uses the BADKWD message number from theHCPDOSYN macro instead.

When the parser is called upon to issue error messages before the end of the IPLprocess, it assumes the error messages come from the processing of configurationfiles read by CP. During this phase, the parser builds all error messages byinvoking the HCPCONSL macro with the DESTINATION=GSDBK option, thuscausing the message builder to place the message in a general system data block(GSDBK). The GSDBK is then placed on a queue of GSDBKs anchored atHCPISUSC. This queue of GSDBKs is later issued to the operator console when thelocation of the operator console has been determined.

Once the system is up and running, the parser issues any required messages in theform of EMSGs back to the console of the virtual machine definition block

CP Parser


(VMDBK) it is running under. Thus, when the parser detects an error in acommand a user has issued, it automatically sends the error message back to theuser's console.

For errors encountered in reading configuration files, the parser prefaces the actualerror message with an indication of where in the file the error occurred. Thismessage includes the file name, file type, and record number (or numbers) wherethe statement was.

Detecting Syntax ErrorsThe parser will not commit changes to data areas if an error is detected whileparsing the command or statement. If the parser were to process an input stringfrom left to right and stop when it encountered a parsing error, it would beinconvenient if any changes to data areas had been made. For example, considerthe CHARACTER_DEFAULTS statement:**-------------------------------------------------------------** CHARACTER_DEFaults statement **-------------------------------------------------------------**CFCHAR HCPCFDEF ’CHARACTER_DEFaults’,PROCESS=NONE*CHARLOOP HCPSTDEF REQMATCH=YES,VALEND=YES,MATCH1=YES,NEXT=CHARLOOP

HCPTKDEF ’LINE_END’,TYPE=CHAR,STORE=SYSCM(SYSLEND),CONFLICT=1,ERROR=MS670605

HCPTKDEF ’LINE_DELete’,TYPE=CHAR,STORE=SYSCM(SYSLDEL),CONFLICT=2,ERROR=MS670605

HCPTKDEF ’CHAR_DELete’,TYPE=CHAR,STORE=SYSCM(SYSCDEL),CONFLICT=3,ERROR=MS670605

HCPTKDEF ’ESCape’,TYPE=CHAR,STORE=SYSCM(SYSESCP), XCONFLICT=4,ERROR=MS670605

HCPTKDEF ’TAB’,TYPE=CHAR,STORE=SYSCM(SYSTAB), XCONFLICT=5,ERROR=MS670605

If the parser updated the SYSCM area directly as it parsed from left to right, then astatement such as the following would cause the parser to update the SYSLEND,SYSLDEL, SYSCDEL, and SYSESCP fields in the system common area before itencountered the invalid TAB character specification of arf:Character_Defaults ,

Line_End # , /* Use hash mark as line end character */Line_Del Off , /* Do not have a logical line del char */Char_Delete @ , /* Use at sign as logical char del char */Escape ’"’ , /* Use double quote as escape character */Tab arf /* Use this as a tab character */

Because any invalid syntax invalidates the whole statement, the changes to SYSCMwould have to be replaced by the original values.

Instead of taking this approach, the parser saves up the changes caused by parsingthe statement and only applies them to the actual data areas when the entirestatement has been parsed and no syntax error has been detected. This wouldoccur before invoking a post-processor. Using this approach with the aboveexample, the parser would not change SYSCM, and it would issue message 6706version 5 for the arf token.

Note: The only data that is not saved up until the parser has finished checking thesyntax is the accumulation requested by the ACCUM parameter. The fields referred

CP Parser


to by this parameter must reside in the primary output data area identified by thePLBASE parameter on the HCPDOSYN macro.

Additional FeaturesAnother feature of the parser is the way it handles tokens that could satisfy morethan one HCPTKDEF in a given state. If, for instance, you have a command thataccepts either a device address or a volume identifier in a particular position, youcan code HCPTKDEF macros as follows:

HCPSTDEF ...HCPTKDEF TYPE=HEX,RANGE=(0,X’FFFF’),STORE=DEVADDRHCPTKDEF TYPE=TOKEN,STORE=DEVVOLID

In such a case, if the token parsed from the command line turns out to be a validdevice address, the parser stores the binary equivalent of the address in theDEVADDR field. If the token is not a valid device address and is less than 6characters long (the defined length of the DEVVOLID field), it is uppercased andstored in the DEVVOLID field. The post-processing routine can then check whetherthe DEVVOLID field contains binary zeros to determine whether a device addressor a volume identifier was specified on the command.

CP Parser


Chapter 10. Common and Frequent Problems

This section discusses many of the problems that can occur when you try tocustomize z/VM using dynamically loaded routines. Unfortunately, it is notpossible for us to anticipate all of the problems that you may encounter. Instead,we will try to cover the most common and most frequent mistakes.

This section is divided into two topics that:v Discuss the diagnostic facilities available in handling problems related to CP exit

pointsv List the common mistakes, how to recognize them, and how to solve them.

Available Diagnostic FacilitiesWe have attempted to provide new commands, ensure that existing commandswere adequate and add information where necessary to assist you in diagnosingproblems.

Before we begin discussing the diagnostic tools, we should mention the benefits ofdiagnosing problems on a second-level test system. When you test a second levelsystem you can view the code flow in a step-by-step manner. There are numerouscommands that can be issued to show locations of control blocks and routines.These addresses will be useful in setting trace points to monitor the code flow.

The following commands were added specifically for diagnosing problems relatedto CP Exits:

QUERY CPCMDS Returns information about the various versions of a command. Thisinformation includes: entry point name of the command handler, currentprivilege classes associated with the command version, whether it isenabled or disabled, and information about the primary command (if thecommand being queried is an alias).

QUERY DIAGNOSE Returns information about a Diagnose code. This information includes:entry point name of the Diagnose code handler, assigned privilege classesand whether the Diagnose code is enabled or disabled.

QUERY CPXLOAD Returns information about loaded routines. This information includes:options entered on the CPXLOAD command (does not include anyCPXLOAD directives imbedded in the loaded files). Also included are:CSECT names, address and sizes, entry point names and addresses, nameof the loaded file, and the time and date of the load.

QUERY EXITS Returns information about the specified exits. This information includes:enabled/disabled status, entry point names associated with the exit, andtotal number of calls (successful and attempted) and total elapsed timespent in the entry point.

QUERY UNRESOLVED Returns information about any unresolved references as the result of a


CPXLOAD. This information includes the names of CSECTs that refer to anunresolved entity (entry point/symbol) and the name of the unresolvedentity.

LOCATE CMDBK Returns the address of the CMDBK for a specific command.

LOCATE DGNBK Returns the address of the DGNBK for a specific Diagnose code.

LOCATE ICLBK Returns the address of the CP indirect call locator block for a specific entrypoint.

LOCATE XITBK Risplays the address of the CP exit block for a specific entry point.

QUERY CPLANGLIST Returns information about languages in which CP can display messages tothe specifier's virtual machine. Also returns the message repositorylanguages, their component IDs, and external symbols.

QUERY ICLNAME Returns usage statistics information about indirect calls to external entrypoints. This information includes the number of times the entity wassuccessfully called and the total elapsed time (not CPU time) spent in theentry point.

There are many other CP commands (such as DISPLAY) which you will finduseful. For more information about the command syntax and use of the commandssee z/VM: CP Commands and Utilities Reference. For additional information ondebugging CP, see z/VM: Diagnosis Guide.

Viewing a CP trace table may become necessary when you are diagnosing aproblem. CP Exit processing will create trace records to show the code flow intoand out of exits. The exit codes specific to exit processing are:

F900 Call Exit Start identifies the beginning of processing for a specific exitpoint.

F910 Exit Routine Start identifies the beginning of processing of an exit routineassociated with a specific entry point.

F920 Exit Routine Finish identifies the end of processing of an exit routineassociated with a specific entry point.

F930 Call Exit Finish identifies the end of exit point processing for a specificexit point.

F940 Call Exit Routine Finish (NOP) identifies the inability to call an exitroutine during exit point processing. This can occur if the routine is nolonger loaded.

2810 Indirect Call Request identifies an indirect call to a routine.

2C10 Indirect Call Return identifies the return from a routine that was indirectlycalled.

The following shows a set of trace entries you might see when viewing the CPtrace table:

F900 ... Exit 1200F910 ... Exit 12002810 ...

Common Problems


2C10 ...F920 ... Exit 1200 CtlRc=0 MainRc=4F910 ... Exit 1200F940 ... Exit 1200F930 ... Exit 1200 MainRc=4

In the previous example, exit 1200 is invoked. It in turn called an exit routine andgave control to it indirectly. After the first exit routine was called an attempt toinvoke a second exit routine was made but that invocation failed because theroutine was no longer callable. The final return code from the exit point was four.

A bit of defensive programming that will aid diagnosis or prevent the need fordiagnosis is the CKMAINT macro, Check Future Maintenance macro. This macroprovides a way to automatically check that future maintenance does not, withoutknowing it, change a value that could affect the reliability of the system. Thismacro is used during compilation to ensure that generated sizes such as a tablesize remain addressable or usable. For example, you may create a data area that isless than 256 bytes long so that you can use an MVC, move character instruction,to change the whole area. At the time you develop the original code, you would bewise to code a CKMAINT to verify that the data area is never unwittingly changedby later developers to a size greater than 256.

Finally, you may encounter times, usually in diagnosing a lock related problem,when you will need to cause an abend so that you can attain more data on theproblem. We recommend that you try to cause and recreate these types ofproblems second level because forcing an abend is what we consider to be the finaldiagnostic choice. Users do not enjoy having the system go suddenly unavailablein order to take a system dump.

However, if you have to take a system dump, the HCPASERT macro will be veryuseful. This macro allows a programmer to declare that certain conditions must betrue at a given point in the code. This macro will (essentially) generate code thatchecks the assertion. If the assertion is not true, an abend is generated (by default).In addition, to verifying that specified locks are held, you can also specify otherassertions such as the code is running on the master processor, or the VMDBK isdispatched.

When CP is running as a second level system, HCPASERT is ideal for avoidingdumps related to an assertion problem. HCPASERT processing can indicate whichassertion failed and drop you into CP READ allowing you to further debug theproblem.

Note: The assertion checking performed by HCPASERT is activated by the SETCPCHECKING command or using the FEATURES configuration file statement.

The HCPAIF, HCPAELSE, and HCPAEND macroinstructions can be used to definealternate instruction sequences. HCPAIF, HCPAELSE, and HCPAEND arestructured programming alternatives to the Assembler Language AIF and AGOpseudo-instructions and statement sequence symbol labels. The operand ofHCPAIF must be a simple boolean value; expressions are not permitted. Theoperands of HCPAELSE and HCPAEND are comments and are permitted in orderto improve readability. Ordinarily, excluded blocks of statements are shown in thelisting even though no object code is generated for them. This facilitates codereview processes. HCPAIF, HCPAELSE, and HCPAEND may not be used inmacros.

Common Problems

Chapter 10. Common and Frequent Problems 97

Common MistakesThis section discusses the common mistakes that can be made when customizingCP. It is divided into a series of topics (for example, problems with defining newcommands). Each topic discusses the common mistakes that can occur and thediagnostic functions that you can perform to identify the problem. Suggestedreadings for further information are provided for each topic.

The topics include:“Command Related Problems”“Diagnose Code Related Problems” on page 99“Message Related Problems” on page 99“Exit Point Related Problems” on page 100“CPXLOAD Related Problems” on page 101“CPUNXLOAD Related Problems” on page 101“Miscellaneous CP Customization Errors” on page 102

Command Related Problemsv Symptom: My command is not being recognized.

Some of the causes of this symptom are:– The necessary versions of the command are not defined or enabled.– The command is an alias and both the alias and its base command are not

enabled.– The necessary privilege classes have not been assigned to the command.– The entry point for the command handler is not loaded.– The wrong entry point name was specified on DEFINE COMMAND or

MODIFY COMMAND.The following commands will be useful:– QUERY CPCMDS command

– LOCATE SYMBOL entry_point_name

– QUERY ICLNAME entry_point_name

– QUERY CPXLOAD EPNAME entry_point_name

v Symptom: The system abends when my command is invoked.

Some of the causes of this symptom are:– An address constant in your dynamically loaded routine was not resolved.

Note: QUERY UNRESOLVED will show the unresolved symbol references ina routine that was dynamically loaded using CPXLOAD. It will not showunresolved symbol references that resulted during a build of the system.

– The necessary calling parameters were not defined for your entry point (e.g.MP specified instead of NONMP).

– The EPNAME value specified on the DEFINE COMMAND or the MODIFYCOMMAND is an external symbol (for example, the CSECT name of yourroutine) rather than the entry point name which is coded to set up yourroutine's addressability.

– Your routine is not compiled with the correct level of the maclibs.The following commands will be useful:– QUERY UNRESOLVED– LOCATE SYMBOL entry_point_name

Common Problems


Additional ReadingsFor additional information on defining new commands, see Chapter 6, “Definingand Modifying Commands and Diagnose Codes,” on page 51.

Diagnose Code Related Problemsv Symptom: My Diagnose code is not being recognized.

Some of the causes of this symptom are:– The diagnose code is not enabled.– The correct privilege classes where not assigned to the Diagnose code.– The Diagnose code handler entry point was not loaded.– The wrong entry point name was specified on DEFINE DIAGNOSE or

MODIFY DIAGNOSE.– The necessary calling parameters were not defined for your entry point (such

as INVAR not specified when needed).The following commands will be useful:– QUERY DIAGNOSE diag

– LOCATE DGNBK diag



v Symptom: The system abends when my Diagnose code is invoked.Some of the causes of this symptom are:– All symbols used by your Diagnose code are not resolved. Note: QUERY

UNRESOLVED will show any unresolved symbols that were loaded usingCPXLOAD but will not show unresolved symbols that resulted during a buildof the system.

– All address constants that your code uses were not resolved.– The EPNAME value specified on the DEFINE DIAGNOSE or the MODIFY

DIAGNOSE is an external symbol (for example, the CSECT name of yourroutine) rather than the entry point name which is coded to set up yourroutine's addressability.

– Your routine is not compiled with the correct level of the maclibs.The following commands will be useful:– LOCATE DGNBK diag

– QUERY UNRESOLVED– LOCATE SYMBOL entry_point_name

Additional ReadingsFor additional information on defining new Diagnose codes, see Chapter 6,“Defining and Modifying Commands and Diagnose Codes,” on page 51.

Message Related Problemsv Symptom: My message repository is not being used.

Some of the causes of this symptom are:– The entry point containing the message repository data is not associated with

the correct component and language.– Other entry points are associated ahead of the entry point with the same

component and language and those entry points define the same messagenumbers.

Common Problems


– The correct component ID was not specified on the HCPCONSL invocation.The following commands will be useful:– QUERY CPLANGLIST ASSOCIATED– LOCATE SYMBOL entry_point_name

v Symptom: My message is being displayed with the wrong header.

Some of the causes of this symptom are:– The message number is in the 7000-7999 series of messages and you expect a

header. Headers are not generated for these messages.– The HCPCONSL macro was coded with the wrong operands.The following commands will be useful:– QUERY CPLANGLIST ASSOCIATED

Additional ReadingsFor additional information on adding message repositories, see Appendix G,“Understanding the CP Message Repository,” on page 231.

Exit Point Related Problemsv Symptom: An entry point associated with an exit is not being invoked.

Some of the causes of this symptom are:– The exit is not enabled.– An ASSOCIATE EXIT was not performed for the entry point.– The wrong exit number was specified on ASSOCIATE EXIT or ENABLE EXIT.

For example, you meant 1243 but you typed 1234.– The entry point code is not loaded.– More than one entry point is associated with an exit and a previous routine

returned a control return code indicating the calling sequence should becancelled.

– The exit point is an initialization exit (e.g. 00E0, 00E1) and the code was notCPXLOADed in the configuration file with the NODELAY option forCPXLOAD, or the code was not found on the Parmdisk.

The following commands will be useful:– LOCATE SYMBOL entry_point_name

– QUERY CPXLOAD ALL– QUERY EXIT nnnn

v Symptom: The system abends when my exit is invoked.

Some of the causes of this symptom are:– All address constants in your code were not resolved.– The necessary calling parameters were not defined for your entry point (e.g.

MP specified instead of NONMP).– An EPNAME value specified on ASSOCIATE EXIT is an external symbol (for

example, the CSECT name of your routine) rather than an entry point namewhich is coded to set up your routine's addressability.

– Your routine is not compiled with the correct level of the maclibs.– You have a lock contention problem.The following commands will be useful:– QUERY CPXLOAD ID load_id

– QUERY EXITS exit_number

– QUERY UNRESOLVED

Common Problems


– LOCATE XITBK exit_number

Additional ReadingsFor additional information on adding exit points, see Chapter 3, “Creating aDynamically Loaded Routine,” on page 13, Chapter 4, “Loading Dynamically intothe System Execution Space,” on page 39, Chapter 5, “Controlling a DynamicallyLoaded Routine,” on page 47, and Appendix I, “Samples of Dynamically LoadedRoutines,” on page 241.

CPXLOAD Related Problemsv Symptom: CPXLOAD command will not load a file.

Some of the causes of this symptom are:– You are attempting to reload an entry point that was linked into the system at

system generation time.– You are attempting to load an entry point that is already loaded.– The file is not on a CP-accessed disk.The following commands will be useful:– QUERY CPXLOAD ALL– QUERY CPDISKS– CPLISTFILE

v Symptom: CPXLOAD statement will not load a file.

Some of the causes of this symptom are:– You are attempting to reload an entry point that was linked into the system at

system generation time.– You are attempting to load an entry point that is already loaded.– The file is not on a CP-accessed disk.– CPXLOAD with the NODELAY option was not specified and the code is

needed by an initialization exit point.– CPXLOAD with the NODELAY option was specified and the file is not on the

Parmdisk.The following commands will be useful:– QUERY CPXLOAD ALL– CPTYPE config_file

– QUERY CPDISKS– CPLISTFILE

Additional ReadingsFor additional information on adding CPXLOAD, see Chapter 4, “LoadingDynamically into the System Execution Space,” on page 39.

CPUNXLOAD Related Problemsv Symptom: CPXUNLOAD command will not unload a file.

Some of the causes of this symptom are:– You specified the wrong CPXLOAD ID.– The files to be unloaded were loaded as PERM.– The entry point is in use by a system service (e.g. entry point is a message

repository).The following commands will be useful:

Common Problems


– QUERY CPXLOAD ID id_number

– QUERY CPLANGLIST ASSOCIATED

Additional ReadingsFor additional information on adding CPXUNLOAD, see Chapter 8, “UnloadingDynamically from the System Execution Space,” on page 71, and Chapter 5,“Controlling a Dynamically Loaded Routine,” on page 47.

Miscellaneous CP Customization Errorsv Symptom: Installation modifications converted to be CPXLOADed no longer

work

Some of the causes of this symptom are:– All address constants in your code were not resolved.– The necessary calling parameters were not defined for your entry point (e.g.

MP specified instead of NONMP).– Address constants in the resident nucleus attempted to reference symbols in

the CPXLOADed modules.The following commands will be useful:– QUERY CPXLOAD ID id_number



v Symptom: "LOCATE entry_point" does not show information about my entrypoint.

Some of the causes of this symptom are:– You did not specify "LOCATE SYMBOL entry_point_name". If you do not

specify SYMBOL, the command may be mistaken for a different locatefunction such as LOCATE rdev.

Common Problems


Appendix A. IBM-Defined CP Exit Points

This appendix describes each of the CP exit points defined by IBM. Valid CP exitnumbers are between X'0000' and X'FFFF' with the following assignments:

CP Exit Points Are Reserved for:

0000 - 7FFF IBM-defined CP exit routines

8000 - EFFF Vendors, including general distribution (for example, among SHAREcustomers)

F000 - FFFF Customers for local use (for example, customers that only keep their CPexits in their own shops)

The CP exit numbers reserved for IBM (X'0000' through X'7FFF') are organized intothe following groups:

CP Exit Points Task

Initialization Processing (X'0000' through X'0FFF')

0000 - 00FF System initialization0100 - 01FF Device initialization0200 - 02FF Spool initialization0300 - 0FEF Other types of initialization0FF0 - 0FFF Command processing initialization

CP Command Processing (X'1000' through X'3FFF')

1000 - 107F AUTOLOG command1080 - 10FF XAUTOLOG command1100 - 117F LOGON command1180 - 11FF LOGOFF command1200 - 120F DIAL command1210 - 122F Messaging commands (MESSAGE, WARNING, SMSG)1230 - 3FDF Other types of CP commands3FE0 - 3FFF SHUTDOWN command

Resource Control Processing (X'4000' through X'6FFF')

4000 - 41FF Spool space4200 - 43FF Temporary disk space4400 - 441F Real spool devices4420 - 4FFF Other types of resource control processing5000 - 51FF Scheduler processing5200 - 6FFF Other types of resource control processing

Termination Processing (X'7000' through X'7FFF')

Note: The most current list of CP exit point definitions and groupings ismaintained in the file HCPEQXIT COPY.


Summary of IBM-Defined CP Exit PointsThe following IBM-defined CP exit points are available for use on your z/VMsystem:

Table 5. Summary of IBM-Defined CP Exit Points

CP Exit Name Function Page

00E0 Startup Pre-PromptProcessing

Provide system initialization options to CP, as if theywere provided by the system operator. This CP exitpoint is called when CP prompts the system operator forsystem initialization options.

“CP Exit 00E0: StartupPre-Prompt Processing” onpage 112

00E1 StartupPost-PromptProcessing

Examine and, optionally, change the system initializationoptions, whether supplied by the system operator or byCP Exit 00E0, before CP validates them. This CP exitpoint is called after CP Exit 00E0 has been, or wouldhave been, called. That is, after CP prompts the systemoperator for system initialization options and before CPvalidates those options.

“CP Exit 00E1: StartupPost-Prompt Processing”on page 117

0FFB Post-AuthorizationCommandProcessing

Examine and, optionally, change or reject any CPcommand that has already passed system authorizationprocessing. This CP exit point is called after CP hasperformed authorization processing for a CP command(or subcommand) but before CP has parsed any of thecommand operands.

“CP Exit0FFB: Post-AuthorizationCommand Processing” onpage 122

1100 LOGONCommandPre-ParseProcessing

Examine and, optionally, change or reject the CPLOGON command before CP parses the command. ThisCP exit point is called immediately after a user entersthe CP LOGON command, but before CP parses thecommand. You can use this CP exit point to:

v Specify CP LOGON command operands to:

– Be added to the list of user-specified LOGONoperands

– Replace the list of user-specified LOGON operands

v Replace the specified console input data

v Reject the LOGON request.

“CP Exit 1100: LOGONCommand Pre-ParseProcessing” on page 126

1101 Logon Post-ParseProcessing

Examine and, optionally, change the return codegenerated by CP after parsing the CP LOGONcommand. This CP exit point is called after CP parses aCP LOGON command, but before CP examines thereturn code from the parse (which CP uses to direct therest of the logon process). You can use this CP exit pointto:

v Examine the return code from the parse

v Change the return code from the parse.

“CP Exit 1101: LogonPost-Parse Processing” onpage 129

1110 VMDBK Pre-LogonProcessing

Examine and, optionally, change the virtual machinedefinition block (VMDBK) for a virtual machine after CPcreates and initializes it. This CP exit point is calledduring virtual machine creation after CP has:

v Created and initialized the VMDBK,

v Defined all the virtual CPUs,

v Established all the virtual devices, and

v Created the base address space.

“CP Exit 1110: VMDBKPre-Logon Processing” onpage 132

CP Exits


Table 5. Summary of IBM-Defined CP Exit Points (continued)


117F Logon FinalScreening

Examine and, optionally, perform any processingrequired immediately before a successful LOGONcommand completes. Perform any processing requiredimmediately before a successful LOGON commandcompletes. This CP exit point is called after CPcompletes all logon processing, but immediately beforeterminating the execution of the LOGON command.

“CP Exit 117F: LogonFinal Screening” on page134

11C0 Logoff InitialScreening

Examine the CP LOGOFF command immediately after itis issued. This CP exit point is called immediately after aCP LOGOFF command is issued and CP has set theappropriate status flags in the VMDBK, but before CPhas:

v Displayed the LOGOFF message,

v Terminated console spooling,

v Performed any other cleanup processing associatedwith logging off a virtual machine.

“CP Exit 11C0: LogoffInitial Screening” on page136

11FF Logoff FinalScreening

Examine and, optionally, perform any processingrequired immediately before a successful LOGOFFcommand completes. This CP exit point is called afterCP completes most logoff processing, but before CPterminates the execution of the LOGOFF command. Atthis point, the virtual machine definition block (VMDBK)still exists, but CP has released most of the data areas towhich it referred.

“CP Exit 11FF: LogoffFinal Screening” on page138

1200 DIAL CommandInitial Screening

Examine and, optionally, change or reject the operandsspecified on the CP DIAL command. This CP exit pointis called immediately after a user enters the commandand before CP processes it.

“CP Exit 1200: DIALCommand InitialScreening” on page 140

1201 DIAL CommandFinal Screening

Examine and, optionally, reject the decisions made by theprocessing of the CP DIAL command. This CP exit pointis called immediately after CP has processed the DIALcommand operands and knows the target user ID andthe target virtual device number, but before CPcompletes the actual connection. Using this CP exitpoint, you can only examine the decisions and theirvalues and choose whether to accept this DIALcommand or to reject it. You cannot use this CP exitpoint to change any of the decisions or their values.

“CP Exit 1201: DIALCommand Final Screening”on page 142

1210 MessagingCommandsScreening

Examine and, optionally, change or reject one of thefollowing messaging commands: MESSAGE, MSGNOH,SMSG, and WARNING.

“CP Exit 1210: MessagingCommands Screening” onpage 144

1230 VMRELOCATEEligibility Checks

Define installation-specific conditions for disallowing therelocation of virtual machines using the VMRELOCATEcommand in a single system image.

“CP Exit1230: VMRELOCATEEligibility Checks” on page150

1231 VMRELOCATEDestination Restart

Use CP Exit 1231 to do any necessary processing beforethe target guest is restarted on the destination systemduring a live guest relocation.

“CP Exit1231: VMRELOCATEDestination Restart” onpage 152

3FE8 SHUTDOWNCommandScreening

Examine and, optionally, change the operands of the CPSHUTDOWN command. This CP exit point is calledimmediately before CP begins its examination of theoperands specified on the SHUTDOWN command.

“CP Exit3FE8: SHUTDOWNCommand Screening” onpage 154

CP Exits

Appendix A. IBM-Defined CP Exit Points 105

Table 5. Summary of IBM-Defined CP Exit Points (continued)


4400 Separator PageDataCustomization

Examine and, optionally, modify the information thatwill be printed on the VM separator page for printedoutput. This CP exit point is called during the processingof VM separator pages, after CP fills in the informationthat will be printed on the separator page, but before CPprints it.

“CP Exit 4400: SeparatorPage Data Customization”on page 157

4401 Separator PagePre-PerforationPositioning

Change the channel program which positions impactprinters at the bottom of a form for printing across theperforation.

“CP Exit 4401: SeparatorPage Pre-PerforationPositioning” on page 159

4402 Separator PagePerforationPrinting or 3800Positioning

Change the channel program which either:

v Prints lines of asterisks and dashes across theperforation of separator pages for impact printers, andpositions the printer for printing of separator pagedata

v Positions 3800 printers for printing of separator pagedata

“CP Exit 4402: SeparatorPage Perforation Printingor 3800 Positioning” onpage 161

4403 Separator PagePrinting

Change the channel program which controls the printingof separator page data.

“CP Exit 4403: SeparatorPage Printing” on page 163

4404 Second SeparatorPage Positioning

Change the channel program which positions the printerfor printing of the second separator page. This channelprogram either positions impact printers at the bottom ofthe first separator page to repeat perforation printing, orpositions 3800 printers to the top of the second separatorpage.

“CP Exit 4404: SecondSeparator PagePositioning” on page 165

4405 Second SeparatorPage Printing

Change the channel program which controls printing ofthe second separator page.

“CP Exit 4405: SecondSeparator Page Printing”on page 167

4406 Separator PagePost-PrintPositioning

Change the channel program which positions the printerto begin printing spool file data after the separator pageshave been printed.

“CP Exit 4406: SeparatorPage Post-PrintPositioning” on page 169

4407 Trailer PageProcessing

Change or replace data which is printed on the separatortrailer page, and/or to modify the channel programwhich controls printing of the separator trailer page.

“CP Exit 4407: TrailerPage Processing” on page171

Each of these CP exit points is described in more detail in the following pages.These descriptions include the following information, where applicable:v Usage conventionsv Standard point of processingv Standard entry conditionsv Standard parameter list contentsv Standard exit conditionsv Standard return codes.

Usage ConventionsThis section describes the standard conventions used to pass control to and fromthe IBM-defined CP exit points. Your dynamically loaded CP exit routines shouldfollow these conventions.

CP Exits


Standard Point of ProcessingThis section describes:v Basic information about:

– How the CP exit is used (reentrant or serially reusable)– Type of processing (MP or non-MP)– Locks (does the calling module have any locks in place).

v The events that led up to this CP exit point being called. (For example, someoneissues a command which causes a CP exit to be called to process the command.)

v The conditions and actions upon return. (For example, if CP receives the properreturn codes upon return, it would process the CP exit task and return control tothe calling task.)

Standard Entry ConditionsWhen CP passes control to each CP exit routine, the registers contain the followinginformation:

Register Contents

R0 CP exit number

R1 Address of the parameter list

R2 Address of the CP exit call request block (XCRBK)

R3-R10 Undefined

R11 If called during initialization, this register is undefined. If called afterinitialization, the contents of this register will depend on the specific CP exitpoint, but will frequently be the address of the virtual machine definition block(VMDBK).

R12 Module base register

R13 Address of a dynamic SAVBK (call with savearea block).

R14-R15 Undefined

Standard Parameter List ContentsMost CP exit points place the address of the parameter list in R1. This section liststhe information that is usually included in a parameter list. Refer to the specific CPexit point documentation for information on the particular items provided in thatexit's parameter list. HCPPLXIT COPY contains DSECTS for parameter listdefinitions for IBM-defined CP exit points.

The standard parameter list contains:Xxxxx DSECT ,

DS A ReservedXxxxxUWD DS A Address of 32 bytes of user

... words doubleword aligned

... initialized to binary

... zerosXxxxxTRT DS A Address of 256 bytes

... words doubleword aligned

... initialized to binary

... zerosXxxxx... DS A Address of a data itemXxxxx... DS A Address of a data item

For exit points defined by the HCPXSERV macro with the PLIST operand, theHCPXSERV macro turns on the high order bit of the last address in the parameter

CP Exits


list. For maximum safety, an exit routine should use an address in the parameterlist only if no prior address is marked as the last entry.

Storage in the parameter list is initialized by the HCPXSERV macro. The parameterlist and the storage to which it points are untouched by CP code that processes thecalling of exit routines. If more than one exit routine is associated to an exit point,each exit routine sees whatever the prior exit routine modified.

Standard Exit ConditionsWhen most CP exit routines return control to CP, the registers contain thefollowing information:

Register Contents

R0-R14 Restored to their original contents

R15 Always contains a return code.

Standard Return CodesReturn codes tell CP how it should continue to process the task from which the CPexit routine was called. Each CP exit routine issues 2 return codes, each of whichmust be a multiple of 4, in R15 when it returns control to CP. The return code inbytes 0 through 1 is called the “exit control return code”. The return code in bytes2 through 3 is called the “mainline return code”.

Exit ControlReturn Code Results

0 CP calls the next entry point associated with this CP exit point and continuesthe task.

4 CP skips the next entry point associated with this CP exit point. CP calls thefollowing entry point associated with this CP exit point and continues thetask.

8 CP discontinues calling any remaining entry points associated with this CPexit point. CP returns to the mainline routine, passing back the maximum“mainline return code” return by the CP exit routines that were called.

12 CP discontinues calling any remaining entry points associated with this CPexit point. CP returns to the mainline routine, passing back the “mainlinereturn code” returned by the last CP exit routine that was called.

nn If any other “exit control return code” is returned to CP, CP:

1. Generates soft abend ZXU001,

2. Writes message HCP2765E to the operator, and

3. Continues as if “exit control return code” 8 had been returned.

After calling all entry points associated with this CP exit point, CP returns to themainline routine, passing back the maximum “mainline return code” returned bythe CP exit routines that were called.

The processing of “mainline return codes” varies for each CP exit point. However,return code 0 typically tells CP to proceed as if no CP exit routine had been called.Other “mainline return codes” typically direct CP to change its normal processing.See the description of each CP exit point for more information about “mainlinereturn codes”.

CP Exits


For dynamic exits, the “mainline return code” determines whether or not theinstruction at the exit point is executed. Return code 0 tells CP to execute theinstruction; any other value tells CP to skip the instruction.

Additional Information about Control Entry PointsControl entry points are called during CPXLOAD and CPXUNLOAD commandprocessing when the CONTROL operand is specified. They are also called duringsystem configuration file processing when a CPXLOAD statement specifies theCONTROL operand. The environment in which they execute is different from thatof dynamically loaded CP exit routines.

Entry ConditionsWhen CP passes control to the control entry point, the registers contain thefollowing information:

Register Contents

R0 Undefined

R1 Address of HCPLABK. This control block contains lots of informationabout the CPXLOAD or CPXUNLOAD request.

R21 Control entry point was called as a result of a CPXLOAD

request

2 Control entry point was called as result of CPXUNLOADrequest.

R3-R10 Undefined

R11 See table below

R12 Entry point address

R13 Address of SAVBK

R14-R15 Undefined

The control entry point execution environment varies depending on how thecontrol entry point is called. The following table describes these different executionenvironments.

Situation when control entrypoint is called

Execution Environment

CPXLOAD statement insystem configuration file thatspecifies the NODELAYoperand

The routine is executed very early during CPinitialization. Many CP services are not yet initialized.For instance, there is no real console on which to displaymessages. If you wish to display a message, you shouldcode the HCPCONSL macro to generate the message inan GSDBK and add that GSDBK to the queue anchoredby HCPISUSC. Messages on this queue are displayduring CP initialization after the IBM copyright banner.

R11 contains the SYSTEM VMDBK address. Do not usesystem services that rely on a logged-on user ID.

Dynamically loaded CP routines must be in a file on theparm disk, which is the only disk that CP has access toat this stage of the initialization process.

CP Exits


Situation when control entrypoint is called

Execution Environment

CPXLOAD statement insystem configuration file withthe DELAY operand (ordefaulted)

The routine is executed during CP initialization. Thedirectory and CP_ACCESS statements in the systemconfiguration file have been processed. Many CP servicesare not yet initialized. The HCPCONSL macro can beused to display messages on the IPL console.

R11 contains the address of a skeleton VMDBK for theOPERATOR.

Dynamically loaded CP routines must be located on oneof the disks specified on a CP_ACCESS statement.

CPXLOAD command CP has finished initialization. All CP services areavailable.

R11 contains the issuing user's VMDBK address. CPservices relying on a logged-on user ID (for example,HCPCONSL) will work.

CPXUNLOAD command withthe ASYNC operand specified(or defaulted)

CP has finished initialization. All CP services areavailable.

R11 contains the SYSTEM VMDBK address. Do not usesystem services that rely on a logged-on user ID.HCPCONSL requests should specify the"DESTINATION=" operand.

CPXUNLOAD command withthe SYNC operand specified

CP has finished initialization. All CP services areavailable.

R11 contains the issuing user's VMDBK address. CPservices relying on a logged-on user ID (for example,HCPCONSL) will work.

Other Entry ConditionsDuring CPXLOAD processing:v If the control entry point that is specified cannot be found, the CPXLOAD

request is rejected.v If the control entry point is in a TEMPORARY routine that is not part of the

current CPXLOAD, CP rejects the CPXLOAD request. This is because the controlentry point might later be unloaded and CP would not be able to call it duringCPXUNLOAD processing.

v The DLUCPXLK is held exclusively. The control entry point must not relinquishthe lock or CP may find another CPXLOAD or CPXUNLOAD that is waiting torun, and its view of what external symbols exist may become out of date.

v All address constants that can be resolved have been resolved. This means thataddress constants inside the routines that CP just loaded have been resolved ifthey refer to anything that CP just loaded or if they refer to anything that isconsidered PERMANENT. If they refer to something that CP did not just loadand that is considered TEMPORARY, then the CPXLOAD request would havefailed.

v No external symbols loaded as part of this CPXLOAD operation have beenadded to the CP symbol map. If the control entry point needs to call an entrypoint that is part of what this CPXLOAD operation is loading, it must use adirect call specifying the address of the entry point. The address can be obtainedby using a simple address constant or by calling HCPCYEES to search for theESD entry and using the address from ESDBVADR in the found HCPESDBK.

CP Exits


During CPXUNLOAD processing:v The DLUCPXLK is held exclusively. The control entry point must not relinquish

the lock or CP may find another CPXLOAD or CPXUNLOAD that is waiting torun, and its view of what external symbols exist may become out of date.

v The control entry point can use indirect calls to other entry points.v The control entry point is called after CP has already checked whether the code

can be unloaded (TEMPORARY, not in use). If the control entry point signalsthat the unload should continue, CP will unload the code.

Exit ConditionsWhen the control entry point returns control to CP, the routine must return areturn code in SAVER15. The valid return codes are:

Return Code Meaning

0 CP should continue the CPXLOAD or CPXUNLOAD request.

4 CP should reject the CPXLOAD or CPXUNLOAD request.

Debugging Your Control Entry Point RoutineBecause a control entry point is loaded and run before you have a chance to usethe CP LOCATE command to find it in storage, it will not be as easy to trace anddebug your routine. However, there are several tracing and debugging techniquesthat you can use to debug your control entry point routine on a second-levelsystem:1. To trace a control entry point routine during CPXLOAD, set a trace point in

HCPCLG where it calls the control entry point routine. To trace the routineduring CPXUNLOAD, set a trace point in HCPCLH where it calls the controlentry point routine.

2. At the beginning of your routine, insert an instruction that you know is notissued anywhere else in CP: for example, an SVC instruction that CP does notsupport (such as SVC 1) or an EXECUTE of an EXECUTE instruction (EX R0,*).Establish a breakpoint for that instruction or program check (TRACE SVC 1, orTRACE PROG 3). When the breakpoint is reached, establish any other desiredTRACE entries. Then resume execution after the instruction that triggered theoriginal breakpoint (BEGIN aaaaaa).Be warned that instructions inserted by this technique cannot be part of afirst-level system. The interrupt cannot be trapped, and CP will crash. Alsoremember to delete such instructions from the final version of your routine.

CP Exits


CP Exit 00E0: Startup Pre-Prompt ProcessingPurpose

Use CP Exit 00E0 to provide system initialization options to CP, as if they wereprovided by the system operator.

Point of processing

Process CP Exit Attribute

Startup Pre-Prompt Processing v Reentrant

v MP

v No locks held

CP Exit 00E0 is called whenever CP prompts the system operator for systeminitialization options. (For an explanation of when prompting normally occurs, seeNote 1 on page 113 in the Programming Considerations section.) The calling taskprovides data areas where the CP exit routines can store the CP exit-suppliedsystem initialization options.

Entry conditions

Register 1 points to a parameter list which is described below. For moreinformation about other register contents, see “Standard Entry Conditions” on page107.

Parameter list constant

The parameter list contains the following:

Word Offset Data Length Contents

1 +0 N/A Reserved for future IBM use.

2 +4 32 bytes Address of the doubleword-aligned User Area,which can be used by this CP exit routine asworking storage.

3 +8 256 bytes Address of the doubleword-alignedtranslate-and-test (TRT) table, which can be used bythis CP exit routine as working storage.

4 +12 4 bytes Address of the fullword-aligned maximum lengthof the system initialization options area (Word 6).

5 +16 4 bytes Address of the fullword-aligned actual length ofthe system initialization options area (Word 6),which this CP exit routine uses as a place to storethe actual length of the information in the arealocated by Word 6. If the CP exit routines placesany data into the area located by Word 6, then theCP exit routine must store the length of the datainto this length field (Word 5).

6 +20 (See Word 5) Address of the system initialization options area,which can be used by this CP exit routine as aplace to store the options CP should use duringsystem initialization.

CP Exits



7 +24 4 bytes Address of the fullword-aligned general systemdata block (GSDBK) that can be allocated and usedby this CP exit routine in place of the systeminitialization options area (Word 6). If the CP exitroutine creates a GSDBK to contain the systeminitialization options, then the CP exit routine mustplace the address of the GSDBK into this field.

Exit conditions

On return, CP Exit 00E0 sets the standard register contents described in “StandardExit Conditions” on page 108.

Return codes

On return, R15 contains two return codes. The first half of the fullword containsthe “CP exit control return code”, which is explained in “Standard Return Codes”on page 108. The second half of the fullword contains the “mainline return code”,which is explained in the following table:

Return Code Results

0 CP ignores any system initialization options supplied by this CP exit routine,prompts the system operator for system initialization options, and continuesnormal initialization processing.

4 CP converts the system initialization options in the data area located by Word6 into a GSDBK, parses the options as if the system operator had entered thedata, and continues normal initialization processing. CP does not prompt thesystem operator for the system initialization options.

8 CP uses the system initialization options in the GSDBK (located by Word 7),parses the options as if the system operator had entered the data, andcontinues normal initialization processing. CP does not prompt the systemoperator for the system initialization options.

nn For any other return codes, CP:

v Writes message HCP2765E to the operator

v Disables CP Exit 00E0

v Prompts the system operator for the system initialization options.

Programming considerations1. If enabled, CP Exit 00E0 is called whenever CP would normally prompt the

system operator for system initialization options. This normally occurs in thefollowing situations:v During a system IPL when the system configuration file does not enable the

automatic warm start function using the following statement:Features Enable Auto_Warm_IPL

v During a system IPL when the system operator specifies the IPL parameterPROMPT, which overrides the automatic warm start function

v During a system restart, after a CP abend, if the system operator tells CP toperform system initialization prompting using one of the following:– System configuration file statement:

Features Enable Prompt After_Restart

CP Exits


– CP command:set prompt after_restart on

v During an operator-initiated system re-IPL if the system operator tells CP toperform system initialization prompting using one of the following:– System configuration file statement:

Features Enable Prompt After_Shutdown_ReIPL

– CP command:set prompt after_shutdown_reipl on

2. CP Exit 00E0 is called early in the system initialization process. The onlyminidisk that is available to CP at that time is the parmdisk. This means yourexit routines for CP Exit 00E0 must be placed on the parmdisk. In addition, youmust load and enable this CP exit point in the system configuration file. To doso, use the:a. CPXLOAD statement with the NODELAY option to dynamically load the

CP routines on the parmdisk into the system execution spaceb. ASSOCIATE EXIT statement to assign one or more entry points or external

symbols to this CP exit pointc. ENABLE EXITS statement to enable this CP exit point.

You cannot use the CP commands of the same name to load and enable CP Exit00E0, because system initialization will have completed by the time you can logon and issue the commands.

3. Availability Status of CP Services — Because CP Exit 00E0 is called early inthe system initialization process, some CP Services will not be available:v The user directory will not yet have been read.v The spooling subsystem will not yet have been initialized.v You can only call routines in modules that:

– You loaded using the CPXLOAD statement and the NODELAY option– Are located in the CP nucleus.

v During most of system initialization, CP will be running in uniprocessormode. Any alternate processors will not yet have been brought online.

4. After CP Exit 00E0 completes, CP uses the mainline return code to decide whatto do next. For return code 0, CP prompts the system operator for the systeminitialization options. For return codes 4 and 8, CP stores the systeminitialization options that CP Exit 00E0 provided.Then, CP tries to call CP Exit 00E1 (if it is enabled) to validate the systeminitialization options or to provide additional options. After CP Exit 00E1completes, CP parses all the system initialization options. If CP finds anythingwrong with the options, CP repeats the entire process for gathering systeminitialization information.If your CP Exit 00E0 routine provided CP with the system initialization optionsthat were not valid, your z/VM system will be caught in a loop and will notinitialize. To prevent this looping condition, we suggest you code your CP exitroutine to:v Examine the XCRCALLS field in the exit call request block (XCRBK). (The

address of the XCRBK is passed in Register 2.) The XCRCALLS field countshow many times a CP exit routine has been called by and returned to CP. Ifthe value in XCRCALLS is greater than 0 (zero), then this CP exit routine hasbeen called before and is being called again.To break the loop, consider adding code to your CP exit routine that tests tosee if the XCRCALLS field is greater than zero. If the answer is yes, have

CP Exits


your CP exit routine set the mainline return code to 0, thereby forcing CP toignore the system initialization options supplied by CP Exit 00E0 and promptthe system operator for the options. This XCRCALLS check will allow thesystem operator to correct the system initialization options.If your CP Exit 00E1 routine provided CP with the system initializationoptions that were not valid, you should consider including code in thatroutine to prevent the looping condition.

v Disable itself before returning to CP. You are only prompted for systeminitialization options at one point in the system initialization process. If CPExit 00E0 is called more than once, it is because one or more of the systeminitialization options were not valid.To prevent the loop, consider coding the HCPXSERV DISABLE macro as thevery last entry in your CP exit routine. Disabling this CP exit routine justbefore you return to CP will not have any effect on:– The system initialization options that you have already stored in the data

area or GSDBK– Your running z/VM system, because CP Exit 00E0 is not called after

system initialization– The next IPL, because you are loading and enabling CP Exit 00E0 in the

system configuration file.

For more information on the HCPXSERV macro, see page “HCPXSERV: CPExit Services Director” on page 192.

5. Tracing and Debugging — Because CP Exit 00E0 is called early in the systeminitialization process, it will not be as easy to trace and debug this CP exitroutine as it would be for a CP exit routine that is called after initialization.During system initialization, normal CP commands (such as LOCATE andLOCK) are not yet available to you. However, there are a number of tracingand debugging techniques that you can use to locate your CP exit code on asecond-level system:

Method 1 —At entry point HCPISXE0 in module HCPISX, set a trace point. At thispoint in HCPISX processing, all the CPXLOAD statements thatspecified the NODELAY operand will have been processed and all yourmodules will have been loaded.

During initialization when CP executes the trace point that you set atentry point HCPISXE0, your system drops into CP READ status. In CPREAD, you can issue any CP command (for example, LOCATEVM orTRACE). Use the CP LOCATEVM command to find where your CP exitroutine was loaded. For example, if your CP exit routine used a label ofEXITE0 on the HCPPROLG macro, you could find it using thiscommand:

locatevm 4-end case ignore increment 1000 data exite0

Method 2 —At the beginning of your module, insert instructions to change andthen reset register 11. R11 generally contains the address of thedispatched virtual machine definition block (VMDBK). As a rule, youshould never change R11 in a CP exit routine. However, if changedjudiciously, you can change R11 safely. For example, if you added thefollowing instructions at the beginning of your module, you could set aTRACE breakpoint for the alteration of R11 to a predictable value:

CP Exits


LR R4,R11 Save current value of R11LR R11,R0 Alter R11 to the CP exit numberLR R11,R4 Restore R11 to its original value

Before you IPL the system, establish a breakpoint for the modificationof R11 to an expected value:CP TRACE GB DATA 000000E0 <--- Stop when R11 equals our CP exit numberIPL nnn CLEAR <--- the address of the IPL DASD

In this case, the changed value for R11 would be the CP exit number inR0. Be warned, while this technique is workable, it can be painfullyslow.

Method 3 —At the beginning of your module, insert an instruction known not to beissued anywhere else in CP. For example, an SVC instruction that CPdoes not support (SVC 1) or an EXECUTE of an EXECUTE instruction(EX R0,*). Establish a breakpoint for that instruction or program check(TRACE SVC 1, or TRACE PROG 3). When the breakpoint is reached,establish any other desired TRACE entries. Then, resume executionafter the instruction that triggered the original breakpoint (BEGINzzzzzz).

Be warned that instructions inserted by this technique cannot be part ofa first-level system. The interrupt cannot be trapped, and CP will crash.

Once you find your CP exit routine, you can use the CP TRACE command totrace its execution.

CP Exits


CP Exit 00E1: Startup Post-Prompt ProcessingPurpose

Use CP Exit 00E1 to examine and, optionally, change the system initializationoptions, whether supplied by the system operator or by CP Exit 00E0, before CPvalidates them. This allows your CP exit routine to:v Supply additional CP-defined system initialization options, such as DRAIN or

DISABLEv Supply installation-defined system initialization optionsv Perform additional authorization checking before allowing a clean or cold start.

Point of processing


Startup Post-Prompt Processing v Reentrant

v MP

v No locks held

CP Exit 00E1 is called after CP Exit 00E0 has been, or would have been, called.That is, after CP prompts the system operator for system initialization options andbefore CP validates those options. (For an explanation of when promptingnormally occurs, see Note 1 on page 118 in the Programming Considerationssection.) The calling task provides the system initialization options that weresupplied to CP, whether by the system operator or by CP Exit 00E0.

Entry conditions




Word Offset DataLength

Contents


2 +4 32 bytes Address of the doubleword-aligned User Area, whichcan be used by this CP exit routine as workingstorage.

3 +8 256 bytes Address of the doubleword-aligned translate-and-test(TRT) table, which can be used by this CP exit routineas working storage.

4 +12 4 bytes Address of the fullword-aligned maximum length ofthe system initialization options area (Word 6).

5 +16 4 bytes Address of the fullword-aligned actual length of thesystem initialization options area (Word 6), CP Exit00E1 can change this length value.

6 +20 (See Word5)

Address of the system initialization options area.

CP Exits



Contents

7 +24 4 bytes Address of the fullword-aligned general system datablock (GSDBK), which can be allocated and used bythis CP exit routine in place of the systeminitialization options area (Words 6). If the CP exitroutine creates a GSDBK to contain the systeminitialization options, then the CP exit routine mustplace the address of the GSDBK into this field.

Exit conditions

On return, CP Exit 00E1 sets the standard register contents described in “StandardExit Conditions” on page 108.

Return codes


Return Code Results

0 CP ignores any system initialization options supplied by this CP exit routineand continues normal processing.

4 CP converts the system initialization options in the data area located by Word6 into a GSDBK, parses the options as if the system operator had entered thedata, and continues normal initialization processing.

8 CP uses the system initialization options in the GSDBK (located by Word 7),parses the options as if the system operator had entered the data, andcontinues normal initialization processing.

12 CP ignores any system initialization options supplied by this CP exit routine,reprompts the system operator for system initialization options, and continuesnormal initialization processing.Note: Return code 12 indicates that there is something wrong with thesystem initialization options. If you have CP Exit 00E0 enabled and supplyingthe system initialization options, you should be very careful that you do notcode a situation that results in an infinite loop.



v Disables CP Exit 00E1

v Uses the system initialization options stored in the area located by Word 6,ignoring any changes made by this CP exit routine.

Programming considerations1. If enabled, CP Exit 00E1 will be called before CP would normally begin to

examine the system initialization options. This normally occurs in the followingsituations:v During a system IPL when the system configuration file does not enable the

automatic warm start function using the following statement:Features Enable Auto_Warm_IPL

CP Exits


v During a system IPL when the system operator specifies the IPL parameterPROMPT, which overrides the automatic warm start function

v During a system restart, after a CP abend, if the system operator tells CP toperform system initialization prompting using one of the following:– System configuration file statement:

Features Enable Prompt After_Restart

– CP command:set prompt after_restart on

v During an operator-initiated system re-IPL if the system operator tells CP toperform system initialization prompting using one of the following:– System configuration file statement:

Features Enable Prompt After_Shutdown_ReIPL

– CP command:set prompt after_shutdown_reipl on

2. CP Exit 00E1 is called early in the system initialization process. The onlyminidisk that is available to CP at that time is the parmdisk. This means yourexit routines for CP Exit 00E1 must be placed on the parmdisk. In addition, youmust load and enable this CP exit point in the system configuration file. To doso, use the:a. CPXLOAD statement with the NODELAY option to dynamically load the

CP routines from the parmdisk into the system execution spaceb. ASSOCIATE EXIT statement to assign one or more entry points or external

symbols to this CP exit pointc. ENABLE EXITS statement to enable this CP exit point.

You cannot use the CP commands of the same name to load and enable CP Exit00E1, because system initialization will have completed by the time you can logon and issue the commands.

3. Availability Status of CP Services — Because CP Exit 00E1 is called early inthe system initialization process, some CP Services will not be available:v The user directory will not yet have been read.v The spooling subsystem will not yet have been initialized.v You can only call routines in modules that:

– You loaded using the CPXLOAD statement and the NODELAY option– Are located in the CP nucleus.

v During most of system initialization, CP will be running in uniprocessormode. Any alternate processors will not yet have been brought online.

4. After CP Exit 00E1 completes, CP parses all the system initialization options.These options were supplied by either the system operator (in response to thestartup prompt), CP Exit 00E0, or CP Exit 00E1. If CP finds anything wrongwith the options, CP repeats the entire process for gathering systeminitialization information.If your CP Exit 00E1 routine provided CP with the system initialization optionsthat were not valid, your z/VM system will be caught in a loop and will notinitialize. To prevent this looping condition, we suggest you code your CP exitroutine to:v Examine the XCRCALLS field in the exit call request block (XCRBK). (The

address of the XCRBK is passed in Register 2.) The XCRCALLS field countshow many times a CP exit routine has been called by and returned to CP. Ifthe value in XCRCALLS is greater than 0 (zero), then this CP exit routine hasbeen called before and is being called again.

CP Exits


To break the loop, consider adding code to your CP exit routine that tests tosee if the XCRCALLS field is greater than a small number (for example, 3). Ifthe answer is yes, have your CP exit routine set the mainline return code to0, thereby forcing CP to ignore the system initialization options supplied byCP Exit 00E1 and continue with the options previously provided by thesystem operator or CP Exit 00E0. This XCRCALLS check will allow thesystem operator to correct the system initialization options on a subsequentprompt.

v Disable itself before returning to CP. You are only prompted for systeminitialization options at one point in the system initialization process. If CPExit 00E1 is called more than once, it is because one or more of the systeminitialization options were not valid.To prevent the loop, consider coding the HCPXSERV DISABLE macro as thevery last entry in your CP exit routine. Disabling this CP exit routine justbefore you return to CP will not have any effect on:– The system initialization options that you have already stored in the data

area or GSDBK– Your running z/VM system, because CP Exit 00E1 is not called after

system initialization– The next IPL, because you are loading and enabling CP Exit 00E1 in the

system configuration file.

For more information on the HCPXSERV macro, see “HCPXSERV: CP ExitServices Director” on page 192.

5. Tracing and Debugging — Because CP Exit 00E1 is called early in the systeminitialization process, it will not be as easy to trace and debug this CP exitroutine as it would be for a CP exit routine that is called after initialization.During system initialization, normal CP commands (such as LOCATE andLOCK) are not yet available to you. However, there are a number of tracingand debugging techniques that you can use to locate your CP exit code on asecond-level system:

Method 1 —At entry point HCPISXE1 in module HCPISX, set a trace point. At thispoint in HCPISX processing, all the CPXLOAD statements thatspecified the NODELAY operand will have been processed and all yourmodules will have been loaded.

During initialization when CP executes the trace point that you set atentry point HCPISXE1, your system drops into CP READ status. In CPREAD, you can issue any CP command (for example, LOCATEVM orTRACE). Use the CP LOCATEVM command to find where your CP exitroutine was loaded. For example, if your CP exit routine used a label ofEXITE1 on the HCPPROLG macro, you could find it using thiscommand:

locatevm 4-end case ignore increment 1000 data exite1

Method 2 —At the beginning of your module, insert instructions to change andthen reset register 11. R11 generally contains the address of thedispatched virtual machine definition block (VMDBK). As a rule, youshould never change R11 in a CP exit routine. However, if changedjudiciously, you can change R11 safely. For example, if you added thefollowing instructions at the beginning of your module, you could set aTRACE breakpoint for the alteration of R11 to a predictable value:

CP Exits


LR R4,R11 Save current value of R11LR R11,R0 Alter R11 to the CP exit numberLR R11,R4 Restore R11 to its original value

Before you IPL the system, establish a breakpoint for the modificationof R11 to a predictable value:CP TRACE GB DATA 000000E1 <--- Stop when R11 equals our CP exit numberIPL nnn CLEAR <--- the address of the IPL DASD

In this case, the changed value for R11 would be the CP exit number inR0. Be warned, while this technique is workable, it can be painfullyslow.

Method 3 —At the beginning of your module, insert an instruction known not to beissued anywhere else in CP. For example, an SVC instruction that CPdoes not support (SVC 1) or an EXECUTE of an EXECUTE instruction(EX R0,*). Establish a breakpoint for that instruction or program check(TRACE SVC 1, or TRACE PROG 3). When the breakpoint is reached,establish any other desired TRACE entries. Then, resume executionafter the instruction that triggered the original breakpoint (BEGINzzzzzz).

Be warned that instructions inserted by this technique cannot be part ofa first-level system. The interrupt cannot be trapped, and CP will crash.

Once you find your CP exit routine, you can use the CP TRACE command totrace its execution.

CP Exits


CP Exit 0FFB: Post-Authorization Command ProcessingPurpose

Use CP Exit 0FFB to examine and, optionally, change or reject any CP commandthat has already passed system authorization processing.

Point of processing


Post-Authorization Command Processing v Reentrant

v MP

v No locks held

CP Exit 0FFB is called after CP has performed authorization processing for a CPcommand (or subcommand) but before CP has parsed any of the commandoperands. You can use this CP exit point to examine, change, or reject the CPcommand. CP provides data areas where the CP exit routine can examine orchange the command (or subcommand) operands.

Entry conditions






2 +4 32 bytes Address of the doubleword-aligned User Area,which can be used by this CP exit routine asworking storage.

3 +8 256 bytes Address of the doubleword-alignedtranslate-and-test (TRT) table, which can be usedby this CP exit routine as working storage.

4 +12 12 bytes Address of the CP command name, as entered bythe user.

CP Exits



5 +16 1 byte Address of a value that indicates the commandtype. The possible values are:

Value Meaning

X'01' or ACIXACCP command other than QUERY or SET

X'02' or ACIXAQCP QUERY command followed by akeyword other than VIRTUAL, such asQUERY SET

X'03' or ACIXAQVCP QUERY VIRTUAL commandfollowed by a keyword, such as QUERYVIRTUAL PRT or QUERY VIRTUALALL

X'04' or ACIXAQVMCP QUERY or CP QUERY VIRTUALcommand without a following keyword,such as QUERY userid or QUERYVIRTUAL vaddr

X'05' or ACIXASCP SET command

6 +20 12 bytes Address of the full base command name. That is,if the user enters a command, this is the fullname of that command. If the user enters analias, this is the full base command name of theCP command to which the alias points, not thefull name of the alias.

7 +24 4 bytes Address of the length of the user-suppliedcommand operands located by Word 9, up to butnot including the logical line-end character(X'15').

8 +28 4 bytes Address of the length of the user-suppliedcommand operands located by Word 9, throughand including all logical line-end characters(X'15').

9 +32 (See Word 8) Address of the user-supplied command operands,through and including all logical line-endcharacters (X'15').

10 +36 4 bytes Address of the maximum length of the areacontaining the CP exit-supplied command (orsubcommand) operands located by Word 13,through and including all logical line-endcharacters (X'15').

11 +40 4 bytes Address of the length of the area for new CPexit-supplied command (or subcommand)operands located by Word 13, up to but notincluding the logical line-end character (X'15').

12 +44 4 bytes Address of the length of the area for new CPexit-supplied command (or subcommand)operands located by Word 13, through andincluding all logical line-end characters (X'15').

CP Exits



13 +48 (See Word 12) Address of the area for new CP exit-suppliedcommand (or subcommand) operands. throughand including all logical line-end characters(X'15').

14 +52 (See CMDSIZE) Address of the doubleword-aligned commandtable entry block (CMDBK) for the user-suppliedbase CP command. That is, if the user enters acommand, this is the CMDBK for that command.If the user enters an alias, this is the CMDBK forthe CP command to which the alias points, notthe CMDBK for the alias.Note: You can find the length of the CMDBK inthe CMDSIZE equate. The size value is stored indoublewords, not bytes.

15 +56 (Stored inGSDFRESZ)

Address of the fullword-aligned general systemdata block (GSDBK) for the user-supplied baseCP command.Note: You can find the length of the GSDBKstored in the GSDFRESZ field. The size value isstored in doublewords, not bytes.

16 +60 4 bytes Address of the return code (supplied by this CPexit routine) that CP will use instead of mainlinereturn code 20 or 24.

Exit conditions

On return, CP Exit 0FFB sets the standard register contents described in “StandardExit Conditions” on page 108

Return codes


Return Code Results

0 CP ignores any changes made by this CP exit routine and continues normalprocessing.

4 CP replaces the user-supplied command operands with the new CPexit-supplied operands described by Words 11, 12, and 13. CP does notchange the name of the user-supplied CP command or subcommand.

The contents of the field located by Word 12 determine which length (with orwithout logical line-end characters) CP will use:

v If the value of the length field located by Word 12 is not zero, then CPreplaces the command operands and all subsequent logical lines with thecontents of the area located by Words 12 and 13.

v Otherwise, CP replaces the command operands up to the end of the logicalline with the contents of the area located by Words 11 and 13.

CP Exits


Return Code Results

8 CP replaces the command and its operands with the new data located byWords 11, 12, and 13. If this is a multiple-line command (more than onecommand strung together using logical line-end characters, X'15'), then CPperforms another command authorization operation using the results of thereplacements.

v If the value of the length field located by Word 12 is not zero, then CPreplaces the command and its operands and all subsequent logical lineswith the contents of the area located by Words 12 and 13.

v Otherwise, CP replaces the command and its operands up to the end of thelogical line with the contents of the area located by Words 11 and 13.

12 CP ignores (does not process) the command by skipping to the next logicalline. If the original command was multiple lines (for example, a SET PFnncommand), CP will skip over only the first logical line. CP processes theremainder of the multiple-line input as CP commands.

16 CP ignores (does not process) the command and skips any remaining CPcommands in a multiple-line command.

20 CP rejects the command and skips to the next logical line. If the originalcommand was a multiple-line command (for example, a SET PFnn command),CP only skips over the first logical line. CP processes the remainder of themultiple-line input as CP commands.

CP sets the mainline return code to the value located by Word 16. This valueis supplied by your CP exit routine.

24 CP rejects the command and skips any remaining commands. After rejectingthe command, CP skips any remaining commands.

CP sets the mainline return code to the value located by Word 16. This valueis supplied by your CP exit routine.


v Writes error message HCP2765E to the system operator

v Generates soft abend ABR002

v Ignores any changes made by this CP exit routine and continues normalprocessing.

Programming considerationsv You cannot bypass command and operand authorization checking using CP Exit

0FFB.

CP Exits


CP Exit 1100: LOGON Command Pre-Parse ProcessingPurpose

Use CP Exit 1100 to examine and, optionally, change or reject the CP LOGONcommand before CP parses the command.

Point of processing


LOGON Command Pre-Parse Processing v Reentrant

v non-MP

v No locks held

CP Exit 1100 is called immediately after a user enters the CP LOGON command,but before CP parses the command. You can use this CP exit point to:v Specify CP LOGON command operands to:

– Be added to the list of user-specified LOGON operands– Replace the list of user-specified LOGON operands

v Replace the specified console input datav Reject the LOGON request.

CP provides a data area where the CP exit routine can examine the commandoperands and the console input data that were specified on the CP LOGONcommand. CP also provides data areas where the CP exit routine can storeinformation for CP to use upon return.

Entry conditions





Contents




4 +12 4 bytes Address of the length of the command operands thatwere specified by the user on the CP LOGONcommand. The command operands are stored in thearea located by Word 6. This does not include thelength of the logical line-end character (X'15'), whichmarks the start of the console input data or the lengthof the console input data, if any.

CP Exits



Contents

5 +16 4 bytes Address of the total length of the user-specifiedcommand operands and console input data arealocated by Word 6. This includes the length of alllogical line-end characters (X'15'), which mark thestart of the console input data and the length of theconsole input data, if any.

6 +20 (See Word5)

Address of the area containing the commandoperands and console input data specified by the useron the CP LOGON command.

7 +24 4 bytes Address of the maximum length of the area that thisCP exit routine can use to store additional commandoperands or to replace the command operands,located by Word 9.

8 +28 4 bytes Address of the length of the data that this CP exitroutine stored in the area located by Word 9. CPinitializes this length to zero to indicate that there isno data stored in the area located by Word 9. If yourCP exit routine stores data in the area located byWord 9, your CP exit routine must update this length.

9 +32 (See Word7)

Address of the CP exit-specified command operandarea. Your CP exit routine can store additional orreplacement LOGON command operands in this area.

10 +36 N/A Address of general system data block (GSDBK) forthe CP LOGON command.

11 +40 N/A Address of the logon work buffer (LGNBK). TheLGNBK contains flags, work areas, and data thatdescribe the characteristics of the logon process. Seeto HCPLGNBK COPY for a description of the workarea and its contents.

12 +44 N/A Address of the virtual machine definition block(VMDBK) that CP created for this logon request.Because the user has not yet logged on, CP assigns atemporary user ID (such as LOGL0024).

13 +48 4 bytes Address of the VMDRTERM field, which points to thereal device control block (RDEV) of the displaystation from which the user issued the CP LOGONcommand. If there is no RDEV, this field will be 0(zero).

14 +52 4 bytes Address of the return code that CP should set if thisCP exit routine rejects the CP LOGON command. CPsets the initial value of this field to 0 (zero). Ifrejecting the CP LOGON command, your CP exitroutine must update this field. CP only uses thisreturn code value if your CP exit routine completeswith a return code that indicates the CP LOGONcommand is to be rejected.

Exit conditions

On return, CP Exit 1100 sets the standard register contents described in “StandardExit Conditions” on page 108.

CP Exits


Return codes


Return Code Results

0 CP ignores any changes made by this CP exit routine and continues normalprocessing.

4 CP adds the CP exit-supplied command operands (Word 9) to the end of theuser-supplied command operands, before any console input data (whichappears after the logical line-end of the LOGON command).

8 CP replaces the user-specified command operands with the CP exit-suppliedcommand operands (Word 9), but does not change the console input data(which appears after the logical line-end of the LOGON command).

12 CP replaces the user-specified command operands and any console input datawith the CP exit-supplied command operands and console input data (Word9).

16 CP rejects the command, using the CP exit-supplied return code (Word 14).




v Ignores any changes made by this CP exit routine and continues normalprocessing.

Programming considerations1. The address of the VMDRTERM field is passed in the parameter list because

the value in this field can change during a loss of control as the result ofswitching to a different RDEV or loss of the RDEV. Your CP exit routine mustvalidate the contents of this field before using them. If the field contains a zero,there is no RDEV associated with the VMDBK.

2. Your CP exit routine can only change the following parameter list fields:The work areas located by Word 2 and Word 3.The length value located by Word 8.The values stored in the area located by Word 9.The return code value located by Word 14.

You cannot make changes to any of the other parameter list fields.

CP Exits


CP Exit 1101: Logon Post-Parse ProcessingPurpose

Use CP Exit 1101 to examine and, optionally, change the return code generated byCP after parsing the CP LOGON command.

Point of processing


Logon Post-Parse Processing v Reentrant

v non-MP

v No locks held

CP Exit 1101 is called after CP parses a CP LOGON command, but before CPexamines the return code from the parse (which CP uses to direct the rest of thelogon process). You can use this CP exit point to:

Examine the return code from the parseChange the return code from the parse.

Entry conditions





Contents




4 +12 N/A Address of the LOGON work area (LGNBK), whichcontains flags, work areas, and data that describe thecharacteristics of the logon process. Refer toHCPLGNBK COPY for a description of the work areaand its contents.

5 +16 N/A Address of the virtual machine definition block(VMDBK) for the logging-on user. Because the userhas not yet logged on, the user ID is a temporary one,such as LOGL0024, that CP assigns to a user in thisstate.

6 +20 4 bytes Address of the VMDRTERM field which points to thereal device control block (RDEV) of the console forthe user who is logging on. The field will be zero ifthere is no RDEV.

CP Exits



Contents

7 +24 4 bytes Address of the return code from the parse. On entryto your CP exit routine, the parse return code is thevalue returned by the standard parsing of theLOGON command. On exit from your CP exitroutine, the parse return code is restricted to 0, 1, or2. This value can be changed to control subsequentprocessing. A parse return code value of 0 tells CP tocontinue processing the LOGON command. A returncode value of 1 tells CP to terminate processing of theLOGON command. A return code value of 2 tells CPto perform a forced logon of the system operator. Anyother value is ignored and LOGON processingcontinues based on the original parse return code.

Exit conditions


Return codes


Return Code Results

0 CP validates the parse return code located by Word 7. Valid parse returncodes are:

0 tells CP to continue processing the LOGON command.

1 tells CP to terminate processing of the LOGON command.

2 tells CP to perform a forced logon of the system operator.If the parse return code (Word 7) is valid, CP continues LOGON processingbased on the value of the parse return code. For any other parse return codevalue (Word 7), CP:



v Ignores any changes made by this CP exit routine and continues normalprocessing of the LOGON command based on the value of the originalparse return code.




v Ignores any changes made by this CP exit routine and continues normalprocessing of the LOGON command based on the value of the originalparse return code.


the value in this field can change during a loss of control as the result of

CP Exits


switching to a different RDEV or loss of the RDEV. Your CP exit routine mustvalidate the contents of this field before using them. If the field contains a zero,there is no RDEV associated with the VMDBK.

2. Your CP exit routine can only change the following parameter list fields:The work areas located by Word 2 and Word 3.The return code value located by Word 7.


CP Exits


CP Exit 1110: VMDBK Pre-Logon ProcessingPurpose

Use CP Exit 1110 to examine and, optionally, change the virtual machine definitionblock (VMDBK) for a virtual machine after CP creates and initializes it.

Point of processing


VMDBK Pre-Logon Processing v Reentrant

v non-MP

v No locks held

CP Exit 1110 is called during virtual machine creation after CP has:v Created and initialized the VMDBK,v Defined all the virtual CPUs,v Established all the virtual devices, andv Created the base address space.

CP provides the CP exit routine with the address of the LOGON work area(described by HCPLGNBK COPY), which indicates the source of the virtualmachine creation (for example, the CP AUTOLOG command), and provides otherinformation about the process.

Entry conditions





Contents



3 +8 256 bytes Address of a doubleword-aligned translate-and-test(TRT) table, which can be used by this CP exit routineas working storage.

4 +12 8 bytes Address of the 8-byte area containing the user ID ofthe logging-on user.

5 +16 N/A Address of the LOGON work area (LGNBK), whichcontains flags, work areas, and data that describe thecharacteristics of the logon process. At the point thisCP exit point is called, the LGNDVMD field is validand the data structures needed to read the UserDirectory are set up. Refer to HCPLGNBK COPY fora description of the work area and its contents.

CP Exits



Contents

6 +20 N/A Address of the virtual machine definition block(VMDBK) for the logging-on user. Because the userhas not yet logged on, the user identifier is atemporary one, such as LOGL0024, that CP assigns toa user in this state.

7 +24 4 bytes Address of the VMDRTERM field, which points to thereal device control block (RDEV) of the console forthe logging-on user. The field will be zero if there isno real device control block (RDEV).

Exit conditions


Return codes


Return Code Results

0 CP continues normal processing.




v Continues normal processing.



2. Your CP exit routine can only change the following parameter list fields:The work areas located by Word 2 and 3The VMDBK located by Word 6.


Important Note: Although you can use CP Exit 1110 to change the VMDBK,we must caution you that any such modifications can result in unpredictableside effects. Locating and correcting these side effects is the responsibility of thewriter of the CP exit routine.

CP Exits


CP Exit 117F: Logon Final ScreeningPurpose

Use CP Exit 117F to examine and, optionally, perform any processing requiredimmediately before a successful LOGON command completes.

Point of processing


Logon Final Screening v Reentrant

v non-MP

v No locks held

CP Exit 117F is called after CP completes all logon processing, but immediatelybefore terminating the execution of the LOGON command. CP provides the CPexit routine with the address of the LOGON work area (described by HCPLGNBKCOPY), which indicates the source of the logon activity (for example, the CPAUTOLOG command), and provides other information about the process.

Entry conditions





Contents




4 +12 8 bytes Address of the 8-byte area containing the user ID ofthe logging-on user.

5 +16 N/A Address of the LOGON work area (LGNBK), whichcontains flags, work areas, and data that describe thecharacteristics of the logon process. Refer toHCPLGNBK COPY for a description of the work areaand its contents.

6 +20 N/A Address of the virtual machine definition block(VMDBK) for the logging-on user.

7 +24 4 bytes Address of the VMDRTERM field which points to thereal device control block (RDEV) of the console forthe logging-on user. The field will be zero if there isno real device control block (RDEV).

CP Exits


Exit conditions

On return, CP Exit 117F sets the standard register contents described in “StandardExit Conditions” on page 108.

Return codes


Return Code Results





v Continues normal processing.



2. Your CP exit routine can only change the following parameter list fields:The work areas located by Word 2 and Word 3.


CP Exits


CP Exit 11C0: Logoff Initial ScreeningPurpose

Use CP Exit 11C0 to examine the CP LOGOFF command immediately after it isissued.

Point of processing


Logoff Initial Screening v Reentrant

v non-MP

v No locks held

CP Exit 11C0 is called immediately after a CP LOGOFF command is issued and CPhas set the appropriate status flags in the VMDBK, but before CP has:v Displayed the LOGOFF message,v Terminated console spooling,v Performed any other cleanup processing associated with logging off a virtual

machine.

Entry conditions





Contents




4 +12 8 bytes Address of the 8-byte area containing the user ID ofthe logging-off user.

5 +16 N/A Address of the LOGOFF work area (LGFBK), whichcontains flags, work areas, and data that describe thecharacteristics of the logoff process. Refer toHCPLGFBK COPY for a description of the work areaand its contents. The work area may not exist, inwhich case this parameter will be zero. If the logoff isthe result of a LOGOFF command or a forceddisconnect, the work area will exist.

6 +20 1 byte Address of the VMDTYPE field, which identifies thetype of VMDBK.

CP Exits



Contents

7 +24 N/A Address of the virtual machine definition block(VMDBK) for the logging-off user.

8 +28 4 bytes Address of the VMDRTERM field which points to thereal device control block (RDEV) of the console forthe logging-off user. The field will be zero if there isno real device control block (RDEV).

Exit conditions

On return, CP Exit 11C0 sets the standard register contents described in “StandardExit Conditions” on page 108.

Return codes

On return, R15 contains two return codes. The first half of the fullword containsthe “CP exit control return code”, which is explained in “Standard Return Codes”on page 108. The second half of the fullword contains the “mainline return code”,which is ignored.



2. Your CP exit routine can only change the following parameter list fields:The work areas located by Word 2 and Word 3.


CP Exits


CP Exit 11FF: Logoff Final ScreeningPurpose

Use CP Exit 11FF to examine and, optionally, perform any processing requiredimmediately before a successful LOGOFF command completes.

Point of processing


Logoff Final Screening v Reentrant

v non-MP

v No locks held

CP Exit 11FF is called after CP completes most logoff processing, but before CPterminates the execution of the LOGOFF command. At this point, the virtualmachine definition block (VMDBK) still exists, but CP has released most of thedata areas to which it referred.

Entry conditions





Contents




4 +12 8 bytes Address of the 8-byte area containing the user ID ofthe logging-off user.

5 +16 1 byte Address of VMTYPE field, which identifies the typeof virtual machine definition block (VMDBK).

6 +20 N/A Address of the virtual machine definition block(VMDBK) for the logging-off user.

Exit conditions

On return, CP Exit 11FF sets the standard register contents described in “StandardExit Conditions” on page 108.

CP Exits


Return codes

On return, R15 contains two return codes. The first half of the fullword containsthe “CP exit control return code”, which is explained in “Standard Return Codes”on page 108. The second half of the fullword contains the “mainline return code”,which is ignored.

Programming considerations1. Your CP exit routine can only change the following parameter list fields:

The work areas located by Word 2 and Word 3.You cannot make changes to any of the other parameter list fields.

CP Exits


CP Exit 1200: DIAL Command Initial ScreeningPurpose

Use CP Exit 1200 to examine and, optionally, change or reject the operandsspecified on the CP DIAL command.

Point of processing


DIAL Command Initial Screening v Reentrant

v MP

v No locks held

CP Exit 1200 is called immediately after a user enters the CP DIAL command andCP has parsed its operands but before CP processes them. You can use this CP exitpoint to examine, modify, or reject the DIAL request.

Entry conditions





Contents

1 +0 4 bytes Reserved for future IBM use.

2 +4 32 bytes Address of the doubleword-aligned user area, whichcan be used by this CP exit routine as workingstorage.


4 +12 12 bytes Address of the command name as entered by theuser, left justified and padded with blanks.

5 +16 8 bytes Address of the target user ID as entered by the user,left justified and padded with blanks. If no target userID was entered, then this field will be all blanks.

6 +20 4 bytes Address of the target virtual device number asentered by the user, after conversion to binary. If notarget virtual device number was entered, then thisfield will be all 1 bits.

7 +24 4 bytes Address of the virtual device number where CPshould start searching for a target virtual devicenumber. This field is initialized to binary 0.

8 +28 4 bytes Address of the virtual device number where CPshould stop searching for a target virtual devicenumber. This field is initialized to X'FFFF'.

CP Exits



Contents

9 +32 N/A Address of the RDEV control block for the terminalwhere the user issued the command.

Exit conditions


Return codes


Return Code Results

0 CP continues normal processing, using the initial values or the valuesreplaced by the CP exit routine.

4 CP:

v Writes message HCP2779E to the system operator

v Rejects the command.

8 CP:

v Does not writes any messages

v Rejects the command.


v Writes message HCP2765E to the system operator


v Rejects the DIAL command.

Programming considerations1. CP Exit 1200 routines can change the following parameter list fields:v The target user ID pointed to by Word 5v The target virtual device number pointed to by Word 6v The starting virtual device number for searching pointed to by Word 7v The ending virtual device number for searching pointed to by Word 8.

You cannot make changes to the other parameter list fields.2. A virtual device number must be in the range X'0000' through X'FFFF'. If the

CP exit routine returns a virtual device number that would be illegal, CP willtreat this as if a return code of 4 was returned from the CP exit routine.

CP Exits


CP Exit 1201: DIAL Command Final ScreeningPurpose

Use CP Exit 1201 to examine and, optionally, reject the decisions made by theprocessing of the CP DIAL command.

Point of processing


DIAL Command Final Screening v Reentrant

v MP

v VDEV lock for the target user ID's virtualdevice control block (VDEV) selected tosatisfy that the request is held, and mustnot be relinquished at any time.

CP Exit 1201 is called immediately after CP has processed the DIAL commandoperands and knows the target user ID and the target virtual device number, butbefore CP completes the actual connection. Using this CP exit point, you can onlyexamine the decisions and their values and choose whether to accept this DIALcommand or to reject it. You cannot use this CP exit point to change any of thedecisions or their values.

Entry conditions





Contents

1 +0 4 bytes Reserved for future IBM use.



4 +12 8 bytes Address of the target user ID, left justified andpadded with blanks.

5 +16 N/A Address of the VDEV control block belonging to thetarget user ID chosen by CP to satisfy the request.

6 +20 N/A Address of the real device control block (RDEV) forthe terminal where the user issued the command.

CP Exits


Exit conditions


Return codes


Return Code Results

0 CP continues normal processing, using the initial values or the values set byCP Exit 1200.



v Rejects the DIAL command.

Programming considerations1. CP Exit 1201 routines cannot change what has been decided. The CP exit

routines can only accept or reject the final decisions about the target user IDand the target virtual device number.

CP Exits


CP Exit 1210: Messaging Commands ScreeningPurpose

Use CP Exit 1210 to examine and, optionally, change or reject one of the followingmessaging commands: MESSAGE, MSGNOH, SMSG, and WARNING. You can:v Add more verificationv Change the format of the messagev Change the context of the messagev Change the parameters that control the way the message is displayed on the

screenv Process installation-defined message command options.

Point of processing


Messaging Commands Screening v Reentrant

v MP

v No locks held

CP Exit 1210 is called after a user issues one of the messaging commands(MESSAGE, MSGNOH, SMSG, or WARNING), but before CP sends the formattedmessage to the designated receiver (user ID).

Entry conditions

Register 1 points to a parameter list which is described below.

Register 11 contains the address of the message sender's VMDBK. For moreinformation about other register contents, see “Standard Entry Conditions” on page107.




Contents




CP Exits



Contents

4 +12 32 bits Address of the 32 bit message control flags, whichcontain flag bits that control the way the message isdisplayed. The first 8 bits of this 32-bit field controlthe way the message is displayed. More than one bitmay be set. You can change the settings to change theway the message is displayed. The possible valuesare:

Value Meaning

X'80______'A time stamp is appended to the message.

X'40______'No time stamp is appended to the message.

X'20______'The message is highlighted when displayed.

X'10______'The console alarm sounds when the messageis displayed.

X'08______'This is a high-priority message and isdisplayed immediately.

X'04______'–X'______01'Reserved for IBM use.

Note: If neither of the first two bits which control thetime stamp are set, the receiving user's value for theVMDTSTAM bit in the VMDTOPTN field of theVMDBK is used. If both bits are set, a time stamp isappended.

The supplied display values for the messagecommands are:

Command/ValueMeaning

MESSAGE/X'B0'Time stamp is appended; message ishighlighted; console alarm sounds.

MSGNOH/X'70'No time stamp is appended; message ishighlighted; console alarm sounds.

SMSG/X'00'This type of message is not displayed.

WARNING/X'B8'Time stamp is appended; message ishighlighted; console alarm sounds; messageis high-priority, displayed immediately.

CP Exits



Contents

5 +16 32 bits Address of the 32 bit field containing the messagetype and Issuer IBM class field. This 32-bit fieldconsists of three subfields:

1. The first 8 bits indicate the type of message beingprocessed. You can change the setting to changethe way the message is processed. Note that ifyou change this setting, you might also need tochange other parameters. The possible values are:

Value Meaning

X'80' MESSAGE command processing

X'40' MSGNOH command processing

X'20' SMSG command processing

X'10' WARNING command processing

X'08'–X'01'Reserved for IBM use

Note: If none of these bits are set, the messagetype defaults to MESSAGE command processing.If more than one bit is set, the message processingis set to the type indicated by the first bit set,based on the order in the previous table (i.e. leftmost bit).

2. The next 8 bits indicate which IBM classcommands the issuer of the message is allowed toexecute. More than one bit may be set. Thesettings are dependent on the privilege class of theissuer of the message as well as the privilege classof the command entered. This field is included forreference only. Changes made to this field do notaffect the way the command is processed. Thepossible values are:

Value Meaning

X'80' IBM class A commands

X'40' IBM class B commands

X'20' IBM class C commands

X'10' IBM class D commands

X'08' IBM class E commands

X'04' IBM class F commands

X'02' IBM class G commands

X'01' IBM class H commands

X'00' IBM class ANY

3. The final 16 bits are reserved for IBM use.

6 +20 8 bytes Address of the 8 byte field containing the user ID ofthe issuer of the command. This field is included forreference only. Changes made to this field do notaffect the way the command is processed.

CP Exits



Contents

7 +24 32 bits Address of the 32 bit field containing the length ofthe message being processed. Changes to this fieldmight affect the way the message is displayed.

8 +28 4 bytes Address of the address of the message beingprocessed. This 32-bit field contains the address of themessage being processed. For each type of message,the message buffer looks as follows:

Message TypeBuffer Contents

MESSAGE* MSG FROM userid : text

MSGNOHtext

SMSG text

WARNING* WNG FROM userid : text

Note: The MESSAGE and WARNING messagesalways contain an initial blank and provide eightspaces for the user ID before the colon, regardless ofthe actual length of the user ID.

Following the text is 100 bytes of unused space whichcan be used to add to or modify the existing text. Ifthe length of the message is changed, the length fielddescribed above should be changed to reflect this ornot all text will be displayed.

You can change the address of the message (and alsothe length of the message, if needed) for suchpurposes as, for example, pointing around themessage header so it is not displayed. However,when the CP message function releases the storage ituses for the message, it releases the storage based onthe address passed to the exit routine, not theupdated value.

9 +32 8 bytes Address of the 8 byte field containing the user ID ofthe receiver of the command. If the value of thereceiver's user ID is changed, the message is sent tothe new receiver. However, if an error message isissued during normal message-function processing,and the error message includes the receiver's user ID,the user ID used in the error message is the one thatwas passed to the exit routine, not the changed value.

CP Exits



Contents

10 +36 4 bytes Address of a 32 bit field which contains the length ofthe header for the message being processed. Eachmessage is made up of a header and a text portion.The header includes the header information and theblank delimiter which precedes the text.

The header length is used by the message processingfunction when messages are sent across the *MSG,*MSGALL, and VMCF services. Only the text of themessage is sent. The header is discarded. The headerlength allows the message function to determinewhere the message text begins.

Each message type is considered to have a header.For MESSAGE and WARNING types, the headerlength on entry to the exit routine is 22 characterslong. For MSGNOH and SMSG, the header length onentry to the exit routine is 0 characters long.

The header can be increased or decreased by this exitor by later message processing (for example, when atime stamp is added). SMSG never transmits theheader while the other types display a header at theterminal if one is present.

Exit conditions


Return codes


Return Code Results

0 CP continues normal processing and ignores any changes made by this CPexit routine.

nnnn CP stops processing the message. The installation-defined return code nnnncan be in the range of 0001 to 270F (decimal 9999). The following errormessage will be issued to the invoker of the message function:

HCPMFS6600E An error was detected by installation-wide exitpoint 1210 — return code mmmm.

where mmmm is the decimal value of the return code. See z/VM: CP Messagesand Codes for further information on this message. For any return codegreater than 270F (decimal 9999), CP:

v Writes error message HCP2765.01E to the operator.

v Writes error message HCP6600.02E to the invoker of the commandpassing back the last four decimal digits of the return code set by the exitroutine.

CP Exits


Programming considerations

None.

Migration aids

Previous versions of VM let you perform a similar function by adding source codeto module HCPMSU for entry point HCPMSUEX as described in z/VM: CPPlanning and Administration. CP Exit 1210 is intended to replace HCPMSUEX. Ifroutine associated with CP Exit 1210 is executed then HCPMSUEX is not called.

CP Exits


CP Exit 1230: VMRELOCATE Eligibility ChecksPurpose

Use CP Exit 1230 to define installation-specific conditions for disallowing therelocation of virtual machines using the VMRELOCATE command in a singlesystem image cluster.

Point of processing


VMRELOCATE Eligibility Checks v Reentrant

v MP

v No locks held

CP Exit 1230 is called twice during the processing of a VMRELOCATE command.The first time is early in command processing to test the eligibility for relocation ofthe virtual machine to the specified destination system. The second time is afterthe virtual machine is stopped, to ensure no changes made to the virtual machineduring the early part of the relocation (before the virtual machine is stopped) havemade the virtual machine ineligible.

Entry conditions

Register 1 points to a parameter list which is described below. For moreinformation about other register contents, see page “Standard Entry Conditions” onpage 107.


The parameter list, which is defined as X1230 dsect in HCPPLXIT COPY, containsthe following:


Contents




4 +12 RLOBSIZE Host logical address of the relocation control block(RLOBK dsect defined in HCPRLOBK COPY). TheRLOBK contains information about the relocationsuch as: target user, destination system, and a flagindicating if this is the first time (initial eligibilitychecks) or second time (after virtual machine isstopped) the exit is being called.

CP Exits


Exit conditions

On return, CP Exit 1230 sets the standard register contents described page“Standard Exit Conditions” on page 108.

Return codes

On return, R15 contains two return codes. The first half of the fullword containsthe “CP exit control return code”, which is explained page “Standard ReturnCodes” on page 108. The second half of the fullword contains the “mainline returncode”, which is explained in the following table:

Return Code Results

0 The installation-supplied eligibility routine has determined that therelocation request may continue. The standard IBM relocation eligibilitychecks should be done and the relocation proceeds if no violations aredetected. If an eligibility violation is detected, the relocation should becanceled.

4 The first time this exit is called during a relocation, the installation-suppliedeligibility routine has determined that the relocation request should fail butall other eligibility checks should be made before terminating the command.This return code allows all eligibility violations to be listed in the commandoutput. On the second call to the exit, this return Code has the samemeaning as return code 8.

8 The installation-supplied eligibility routine has determined that therelocation request should be terminated immediately.

Programming considerations1. The installation-supplied exit should display any messages necessary to

indicate which installation-specific eligibility restrictions would be violated bythis relocation request.

CP Exits


CP Exit 1231: VMRELOCATE Destination RestartPurpose

Use CP Exit 1231 to do any necessary processing before the target guest is restartedon the destination system during a live guest relocation..

Point of processing


VMRELOCATE Destination Restart v Reentrant

v MP

v No locks held

CP Exit 1231 is called once during the processing of a VMRELOCATE command.After the guest is temporarily halted and the guest state has been moved from thesource to the destination system, this exit is called on the destination system priorto restart of the guest.

Entry conditions

Register 1 points to a parameter list which is described below. For moreinformation about other register contents, see page “Standard Entry Conditions” onpage 107.


The parameter list, which is defined as X1231 dsect in HCPPLXIT COPY, containsthe following:


Contents




4 +12 RLOBSIZE Host logical address of the relocation control block(RLOBK dsect defined in HCPRLOBK COPY). TheRLOBK contains information about the relocationsuch as: target user, destination system,VMRELOCATE command options, etc..

Exit conditions

On return, CP Exit 1231 sets the standard register contents described page“Standard Exit Conditions” on page 108.

CP Exits


Return codes

On return, R15 contains two return codes. The first half of the fullword containsthe “CP exit control return code”, which is explained page “Standard ReturnCodes” on page 108. The second half of the fullword contains the “mainline returncode”, which is explained in the following table:

Return Code Results

0 Allow relocation to continue.

non-zero Cancel the relocation.

Programming considerations1. The installation-supplied exit should display any messages necessary to

indicate why the relocation was rejected if a non-zero R15 (return code) isreturned to the caller.

2. This exit is called during the time when the relocating guest is quiesced. It iscritical that this quiesce time should be as short as possible.

CP Exits


CP Exit 3FE8: SHUTDOWN Command ScreeningPurpose

Use CP Exit 3FE8 tov examine the operands supplied on the SHUTDOWNv add, remove, or alter any operand on the SHUTDOWN commandv accept or reject the SHUTDOWN command

Point of processing


SHUTDOWN Command Screening v Reentrant

v MP

v No locks held

CP Exit 3FE8 is called after a CP SHUTDOWN command has been issued andauthorized but before CP has examined any operands of the command. The callingtask provides to the exit routinev standard exit work areasv a copy of the operands from the commandv an area for the exit to provide replacement operandsv an area for the exit to provide a command return code if the exit routine rejects

the command

Entry conditions





Contents


2 +4 32 bytes Address of the doubleword-aligned user area, whichmay be used by each CP exit routine as workingstorage.

3 +8 256 bytes Address of the doubleword-aligned translate-and-test(TRT) table, which may be used by each CP exitroutine as working storage.

4 +12 4 bytes Address of the length of the data located by Word 5.

5 +16 (See Word4)

Address of a copy of the operands from theSHUTDOWN command.

6 +20 4 bytes Address of the fullword-aligned maximum length ofthe data area located by Word 8.

7 +24 4 bytes Address of the fullword-aligned length of the data inthe area located by Word 8.

CP Exits



Contents

8 +28 (See Word7)

Address of replacement operands for theSHUTDOWN command.

9 +32 4 bytes Address of the command error return code.

Return codes


Return Code Results

0 This return code indicates that no changes were made to the operands onthe SHUTDOWN command. CP continues processing of the SHUTDOWNcommand.

4 This return code indicates that the exit has supplied additional commandoperands. These operands are returned by the exit routine using Word 7(label X3FE8OUL in the exit parameter list DSECT) and Word 8 (labelX3FE8OU in the exit parameter list DSECT). CP inserts these operands intothe command immediately after the command and before the originaloperands. CP continues processing of the SHUTDOWN command usingthese resulting operands. The operands returned by the exit should beginwith a blank character so that CP can perform proper parsing of thecommand operands.

8 This return code indicates that the exit has supplied replacement commandoperands. These operands are returned by the exit routine using Word 7(label X3FE8OUL in the exit parameter list DSECT) and Word 8 (labelX3FE8OU in the exit parameter list DSECT). CP inserts these operands intothe command immediately after the command and before the originaloperands. The original command operands are discarded. CP continuesprocessing of the SHUTDOWN command using these resulting operands.The operands returned by the exit should begin with a blank character sothat CP can perform proper parsing of the command operands.

12 This return code indicates that the exit has rejected the SHUTDOWNcommand. CP will use as the SHUTDOWN command error return code thevalue located by Word 9 (label X3FE8RC in the exit parameter list DSECT).CP will not generate any additional error message. CP assumes that the exitroutine has already generated any error messages that it deemedappropriate.


v Writes message HCP2765E to the operator.

v Generates a soft abend ABR002.

v Continues normal processing as if return code 0 were returned.

Programming considerations1. Unavailable CP servicesv All CP services are available.

2. Your exit routines can change the following parameter list fields:v The work areas located by Word 2 and Word 3.v The length value located by Word 7.

CP Exits


v The values stored in the area located by Word 8.v The command error return code value located by Word 9.You cannot make changes to the other parameter list fields.

CP Exits


CP Exit 4400: Separator Page Data CustomizationPurpose

Use CP Exit 4400 to examine and, optionally, modify the information that will beprinted on the VM separator page for printed output.

Point of processing


Separator Page Data Customization v Reentrant

v MP

v No locks held

CP Exit 4400 is called during the processing of VM separator pages, after CP fillsin the information that will be printed on the separator page, but before CP printsit. The separator page information is stored in buffers that are mapped by theSEPPAG1 and SEPPAG2 DSECTs.

Entry conditions




Word Offset Length Contents


2 +4 32 bytes Address of the doubleword-aligned user area,which is used by this CP exit routine as workingstorage.

3 +8 256-byte Address of the doubleword-alignedtranslate-and-test (TRT) table, which is used bythis CP exit routine as working storage.


5 +16 4096 bytes Address of the SEPPAG1 buffer which containsseparator page channel command words (CCWs)and data.

6 +20 4096 bytes Address of the SEPPAG2 buffer which containsseparator page data.

7 +24 SPFEND (bytes) Address of the spool file control block (SPFBK) ofthe file being printed.

8 +28 RDEVSZCK(doublewords)

Address of the real device control block (RDEV)of the printer that will print the file.

9 +32 RSPSIZE(doublewords)

Address of the real spool device block (RSPBK) ofthe printer that will print the file.

CP Exits


Exit conditions


Return codes


Return Code Results



8 CP terminates separator page processing for the current file.

Programming considerations1. If you modify the contents of SEPPAG1 or SEPPAG2 DSECT, be aware that

each file cannot exceed 4096 bytes in length.2. To terminate the processing of this VM separator page, you do not have to

create any dynamically loaded CP routines. All you need to do is:v Associate IBM-supplied entry point HCPSRC08 with this CP exit point using

the ASSOCIATE EXIT command (or configuration file statement).v Enable this CP exit point using the ENABLE operand of ASSOCIATE EXIT or

using the ENABLE EXITS command (or configuration file statement).

For more information on the ASSOCIATE EXIT or ENABLE EXITS commands,see z/VM: CP Commands and Utilities Reference. For more information on theASSOCIATE EXIT or ENABLE EXITS statements, see z/VM: CP Planning andAdministration.

CP Exits


CP Exit 4401: Separator Page Pre-Perforation PositioningPurpose

Use CP Exit 4401 to change the channel program which positions impact printersat the bottom of a form for printing across the perforation.

Point of processing


Separator Page Pre-Perforation Positioning v Reentrant

v MP

v No locks held

CP Exit 4401 is called during separator page processing, prior to positioning theform on an impact printer for perforation printing. The channel program ismapped by SEPPAG1 DSECT beginning at label SEPCWP1 in HCPSEPBK COPY.

Entry conditions






2 +4 32 bytes Address of the doubleword-aligned user area,which can be used by this CP exit routine asworking storage.

3 +8 256 bytes Address of the doubleword-alignedtranslate-and-test (TRT) table, which can be usedby this CP exit routine as working storage.

4 +12 N/A Address of the first CCW in the generatedchannel program.Note: The length of the channel program mayvary. The last CCW that is part of the channelprogram will have the command chaining bit andthe data chaining bit turned off.

5 +16 4096 bytes Address of SEPPAG1 which contains separatorpage CCWs and data.

6 +20 4096 bytes Address of SEPPAG2 which contains separatorpage data.

7 +24 SPFEND (bytes) Address of the spool file control block (SPFBK) ofthe file being printed.Note: SPFEND is an equate in HCPSPFBK COPY.


Address of the real device control block (RDEV)of the printer the file is being printed on.Note: RDEVSZCK field is a one byte field inHCPRDEV COPY.

CP Exits




Address of the real spool device block (RSPBK) ofthe printer the file is being printed on.Note: RSPSIZE is an equate in HCPRSPBK COPY.

Exit conditions


Return codes


Return Code Results

0 CP continues separator page processing.

4 CP does not perform the I/O to position the printer at the bottom of theform, but continues separator page processing.


Programming considerations1. If the contents of SEPPAG1 are altered, its total length must not exceed 4096

bytes.2. If the contents of SEPPAG2 are altered, its total length must not exceed 4096

bytes.3. To bypass this step in separator page processing, no user exit code needs to be

written. You can simply associate IBM-supplied entry point HCPSRC04 withthis exit point.

4. To terminate separator page processing at this point, no user exit code needs tobe written. You can simply associate IBM-supplied entry point HCPSRC08 withthis exit point.

CP Exits


CP Exit 4402: Separator Page Perforation Printing or 3800Positioning

Purpose

Use CP Exit 4402 to change the channel program which either:v Prints lines of asterisks and dashes across the perforation of separator pages for

impact printers, and positions the printer for printing of separator page datav Positions 3800 printers for printing of separator page data

Point of processing


Separator Page Perforation Printing or 3800Positioning

v Reentrant

v MP

v No locks held

CP Exit 4402 is called prior to printing of separator perforation lines (for impactprinters) and positioning the printer to print separator page data (both impactprinters and 3800s). The channel program is mapped by SEPPAG1 DSECTbeginning at label SEPCWP1 in HCPSEPBK COPY.

Entry conditions






2 +4 32 bytes Address of a doubleword aligned User Area,which can be used by this CP exit routine asworking storage.

3 +8 256 bytes Address of a doubleword alignedtranslate-and-test (TRT) table, which can be usedby this CP exit routine as working storage.




CP Exits








Exit conditions


Return codes


Return Code Results


4 CP does not perform the I/O to print the perforation pattern (for impactprinters) or position the printer for separator printing, but continuesseparator page processing.







CP Exits


CP Exit 4403: Separator Page PrintingPurpose

Use CP Exit 4403 to alter the channel program which controls the printing ofseparator page data.

Point of processing


Separator Page Printing v Reentrant

v MP

v No locks held

CP Exit 4403 is called prior to printing of the first separator page. The channelprogram is in SEPPAG1 beginning at label SEPCWL1 in HCPSEPBK copy.

Entry conditions






2 +4 32 bytes Address of a doubleword-aligned User Area,which can be used by this CP exit routine asworking storage.

3 +8 256 bytes Address of a doubleword-alignedtranslate-and-test (TRT) table, which can be usedby this CP exit routine as working storage.







CP Exits





Exit conditions


Return codes


Return Code Results


4 CP does not perform the I/O to print the first separator page, but continuesseparator page processing.




bytes.3. To simply bypass this step in separator page processing, you can associate

IBM-supplied entry point HCPSRC04 with this exit point.4. To simply terminate separator page processing at this point, you can associate

IBM-supplied entry point HCPSRC08 with this exit point.

CP Exits


CP Exit 4404: Second Separator Page PositioningPurpose

Use CP Exit 4404 to change the channel program which positions the printer forprinting of the second separator page. This channel program either positionsimpact printers at the bottom of the first separator page to repeat perforationprinting, or positions 3800 printers to the top of the second separator page.

Point of processing


Second Separator Page Positioning v Reentrant

v MP

v No locks held

CP Exit 4404 is called prior to positioning the printer to print the second separatorpage. The channel program is mapped by SEPPAG1 DSECT beginning at labelSEPCWP1.

Entry conditions












CP Exits







Exit conditions


Return codes


Return Code Results


4 CP does not perform the I/O to position the printer for printing the secondseparator page, but continues separator page processing.







CP Exits


CP Exit 4405: Second Separator Page PrintingPurpose

Use CP Exit 4405 to change the channel program which controls printing of thesecond separator page.

Point of processing


Second Separator Page Printing v Reentrant

v MP

v No locks held

CP Exit 4405 is called prior to printing of the second separator page. The channelprogram is mapped by SEPPAG1 DSECT beginning at label SEPCWL1 inHCPSEPBK COPY.

Entry conditions







3 +8 256 bytes Address of doubleword-aligned translate-and-test(TRT) table, which can be used by this CP exitroutine as working storage.







CP Exits





Exit conditions


Return codes


Return Code Results


4 CP does not perform the I/O to print the second separator page, butcontinues separator page processing.







CP Exits


CP Exit 4406: Separator Page Post-Print PositioningPurpose

Use CP Exit 4406 to change the channel program which positions the printer tobegin printing spool file data after the separator pages have been printed.

Point of processing


Separator Page Post-Print Positioning v Reentrant

v MP

v No locks held

CP Exit 4406 is called prior to positioning the printer to begin printing the data inthe spool file. The channel program is mapped by SEPPAG1 DSECT beginning atlabel SEPCCW1 in HCPSEPBK COPY.

Entry conditions














CP Exits





Exit conditions


Return codes


Return Code Results


4 CP does not perform the I/O to position the printer to begin printing spoolfile data, but continues separator page processing.







CP Exits


CP Exit 4407: Trailer Page ProcessingPurpose

Use CP Exit 4407 to change or replace the printed data on the separator trailerpage, and/or to modify the channel program which controls the printing of theseparator trailer page.

Point of processing


Trailer Page Processing v Reentrant

v MP

v No locks held

CP Exit 4407 is called during separator trailer page processing, prior to printing theseparator trailer page. The data that will be printed on the separator page and thechannel program which controls printing of the separator trailer page have beencreated at this point in the process. The separator trailer page data is mapped bySEPTRL DSECT in HCPSEPBK COPY. The channel program is mapped by SEPTRLDSECT beginning at label SEPTCCW1.

Entry conditions









5 +16 4096 bytes Address of SEPTRL which contains separatortrailer page CCWs and data.


CP Exits







Exit conditions


Return codes


Return Code Results

0 CP prints the separator trailer page.

4 CP does not print the separator trailer page.

8 CP does not print the separator trailer page.

Programming considerations1. If the contents of SEPTRL DSECT are altered, its total length must not exceed

4096 bytes.2. To terminate separator trailer page processing at this point, no user exit code

needs to be written. You can simply associate IBM-supplied entry pointHCPSRC04 or HCPSRC08 with this exit point.

CP Exits


CP Exit Point and Module ReferenceThe following table provides a reference to the IBM-defined CP exit points and theCP modules from which they are called. This information is provided fordiagnostic purposes only.

CP Exit Name Module

00E0 Startup Pre-Prompt Processing HCPISX00E1 Startup Post-Prompt Processing HCPISX0FFB Post-Authorization Command Processing HCPCMD1100 LOGON Command Pre-Parse Processing HCPLGX1101 Logon Post-Parse Processing HCPLGX1110 VMDBK Pre-Logon Processing HCPLGX117F Logon Final Screening HCPLGX11C0 Logoff Initial Screening HCPUSP11FF Logoff Final Screening HCPUSP1200 DIAL Command Initial Screening HCPDIA1201 DIAL Command Final Screening HCPDIA1210 Messaging Commands Screening HCPMFS3FE8 SHUTDOWN Command Screening HCPSHS4400 Separator Page Data Customization HCPSEP4401 Separator Page Pre-Perforation Positioning HCPSEP4402 Separator Page Perforation Printing or 3800 Positioning HCPSEP4403 Separator Page Printing HCPSEP4404 Second Separator Page Positioning HCPSEP4405 Second Separator Page Printing HCPSEP4406 Separator Page Post-Print Positioning HCPSEP4407 Trailer Page Processing HCPSEQ

Module Summary


Module Summary


Appendix B. Dynamic Exit Points

The conditions under which exit routines associated with dynamic exit points areinvoked, and the conventions of such invocations, are determined largely by theway that the exit points are defined. However, there are some conventions thatapply regardless of where the exit point is placed.

Point of ProcessingThe point of processing and the associated attributes (for example, the locks held)are determined by the placement of the dynamic exit.

Entry ConditionsRegister 1 points to a parameter list whose format is determined in part by howthe exit point is defined. The invariant portion of the parameter list (words 1through 3) is described below, along with a variant portion (beginning with word4) that includes zero or more user-defined parameters. The contents of otherregisters are described in “Standard Entry Conditions” on page 107.

Parameter List Contents


1 +0 128 bytes Address of the save area(SAVBK) containing the registersat the point where the exit wastaken and from which theregisters will be restored uponcompletion of exit processing.

2 +4 32 bytes Address of thedoubleword-aligned User Area,which can be used by this CPexit routine as working storage.

3 +8 256 bytes Address of thedoubleword-alignedtranslate-and-test (TRT) table,which can be used by this CPexit routine as working storage.

4 +12 Context- dependent User-defined parameter 1

5 +16 Context- dependent User-defined parameter 2...

Exit ConditionsOn return, a dynamic exit restores the original contents of registers 0 through 15.However, if the exit routine chooses to modify the register values in the SAVBKpointed to by the first word of the exit parameter list, it can affect the valuesrestored to the corresponding registers.


Return CodesOn return, R15 contains two return codes. The first half of the fullword containsthe “CP exit control return code”. These return codes are explained in the tableunder “Standard Return Codes” on page 108. The second half of the fullwordcontains the “mainline return code”, which determines whether or not theinstruction at the exit point is executed. Return code 0 tells CP to execute theinstruction; any other value tells CP to skip the instruction.

Dynamic Exit Points


Appendix C. CPXLOAD Directives

This appendix describes the CPXLOAD directives that control the dynamic loadingof CP routines into the system execution space using the CPXLOAD command orconfiguration file statement.

The table below lists and briefly explains the CPXLOAD directives that areavailable to you. These CPXLOAD directives can be used in TEXT files, in controlfiles, or in members of TXTLIBs.

Table 6. CPXLOAD Directives

CPXLOAD Directive Description Page

CHANGE Temporarily renames ordeletes an external symbolassociated with CP routinesdynamically loaded using aCPXLOAD command orconfiguration file statement.This lets you maketemporary changes duringthe loading of a TEXT filewithout requiring you toreassemble the file.

“CHANGE Directive” onpage 178

EXPAND Increases the size of thecontrol section (CSECT) whendynamically loading CProutines using a CPXLOADcommand or configurationfile statement.

“EXPAND Directive” on page180

INCLUDE Reads and processes anotherfile when dynamicallyloading CP routines using aCPXLOAD command orconfiguration file statement.

“INCLUDE Directive” onpage 181

OPTIONS Sets the defaults fordynamically loading CProutines into the systemexecution space using aCPXLOAD command orconfiguration file statement.

“OPTIONS Directive” onpage 183

For information about how to read syntax diagrams, see “Syntax, Message, andResponse Conventions” on page xiii.


CHANGE DirectiveFormat

►► CHANGE symbol1(1)

( symbol2 )

►◄

Notes:

1 If you specify symbol2, there must not be any spaces between symbol1 and the left parenthesisdelimiter of symbol2.

Purpose

Use the CHANGE directive to temporarily rename or delete an external symbolassociated with CP routines dynamically loaded using a CPXLOAD command orconfiguration file statement. This lets you make temporary changes during theloading of a TEXT file without requiring you to reassemble the file.

How to specify

CHANGE directives must start after column 1 of the input record and must bespecified immediately before the first external symbol (symbol1) is defined. Thisdirective remains in effect until it encounters an END record in the TEXT file.

For example, suppose you had an INCLUDE directive which read and processedanother file. In that file, you defined an external symbol that you wanted torename or delete. You would place the CHANGE directive immediately before theINCLUDE directive.

Operands

symbol1is the external symbol that you are renaming or deleting. The variable symbol1must be a 1- to 8-character alphanumeric string.

(symbol2)is the new external symbol name that you want CP to use temporarily duringloading instead of symbol1. The variable symbol2 must be a 1- to 8-characteralphanumeric string.

If you omit symbol2, you are telling CP to temporarily delete symbol1 duringloading.

Usage notes1. Someday, you may need to load a file that duplicates the entry point names

already known to CP. Rather than changing and assembling the source file, youcan use the CHANGE directive. This saves you from assembling again andhelps avoid potential errors.

2. If you do not specify symbol2 on a CHANGE directive, CP temporarily deletessymbol1. If symbol1 is a control section (CSECT), CP will delete that CSECT andall of its internal entry point names. That is, CP treats the CSECT as if it werenot in the input file.If symbol1 is a simple external symbol within a CSECT, CP ignores that externalsymbol, but retains all other parts of the CSECT. That is, CP treats the external

CPXLOAD Directives


symbol as if it had not been declared in the CSECT. An external reference tothat external symbol is treated as an unresolved reference.

Examples1. To have CP temporarily change the references from HCPCVTHB to

HCPCVTDB in the file being loaded, use the following:change hcpcvthb(hcpcvtdb)

MessagesHCP6704E Missing token at end of lineHCP6706E Invalid entry point name - symbol

CPXLOAD Directives

Appendix C. CPXLOAD Directives 179

EXPAND DirectiveFormat

►► EXPAND csect ( nnnn ) ►◄

Purpose

Use the EXPAND directive to increase the size of the control section (CSECT) whendynamically loading CP routines using a CPXLOAD command or configuration filestatement.

How to specify

EXPAND directives must start after column 1 of the input record and must beplaced before the specified control section (csect) is defined.

Operands

csectis the name of the CSECT in the file to be loaded whose size you want toincrease. The variable csect must be a 1- to 8-character alphanumeric string.

(nnnn)tells CP how many more bytes to add to the current CSECT size. The variablennnn is a decimal number between 1 and 4096.

Usage notes1. When CP expands the size of the CSECT, it adds the expansion area at the end

of the CSECT.2. You may get a larger expansion area than you asked for, because CP always

rounds the expansion area size up to a double-word boundary.3. Patching is the most likely use you will have for the expansion area.4. When using the EXPAND directive, be careful not to increase the size of your

program beyond its own design limitations. For example, if space is added to aCSECT beyond the range of its base registers, then the program will not haveaddressability to that area.

5. When using the EXPAND and CHANGE directives together, be careful toexpand the correct CSECT name. That is, if you use the CHANGE directive tochange the name of the CSECT, then the EXPAND directive must refer to thenew CSECT name.

Examples1. To have CP increase the size of a CSECT named QQQCSECT by 16 bytes, use

the following:expand qqqcsect(16)

2. To change the CSECT name to XXXCSECT and then increase its size by 16bytes, use the following:

change qqqcsect(xxxcsect)expand xxxcsect(16)

MessagesHCP002E Invalid operand - operandHCP6706E Invalid entry point name - csect

CPXLOAD Directives


INCLUDE DirectiveFormat

►► INCLUDE fn ftMEMber member

►◄

Purpose

Use the INCLUDE directive to read and process another file when dynamicallyloading CP routines using a CPXLOAD command or configuration file statement.

How to specify

INCLUDE directives must start after column 1 of the input record and can beplaced anywhere in the dynamically loaded routine. For more information abouthow CP processes INCLUDE directives, see Usage Note 2.

Operands

fn is the file name of the CMS file that you want to include.

ft is the file type of the CMS file that you want to include.

MEMBER memberis the name of the member in the TXTLIB that you want included.

You can specify an asterisk (*) to include all the base members in thepartitioned data set.

You can use generic member names to request a specific subset of files. Ageneric member name is a 1- to 8-character string with asterisks (*) in place of1 or more characters and percent signs (%) in place of exactly 1 character. Forexample:

... member hc%p*

includes all members that start with HC and have P as their fourth character.

Note: You can only specify MEMBER when the file is actually a CMSpartitioned data set (PDS).

Usage notes1. The file that you are loading and the file that you are including must both

reside on the same minidisk.2. The placement of the INCLUDE directive in the file that you are loading is

important. CP processes the file that you are loading until it finds anINCLUDE. Then, CP processes the included file until it reaches the end of thefile (or until it reaches an LDT record in a file containing TEXT records). Afterprocessing the included file, CP returns to processing the file that you areloading at the line just after the INCLUDE.

3. Members of a TXTLIB are either base members or alias members. A basemember and its alias members all start at the same record in the file. A basemember is the first member in the file's directory that starts at a differentrecord than all previous directory entries. All subsequent members in thedirectory that start at the same record are alias members to the base member.

CPXLOAD Directives


To display the list of base member names and their alias member names, usethe CPLISTFILE command. For more information about CPLISTFILE, see z/VM:CP Commands and Utilities Reference.

4. CP will reject processing an INCLUDE directive if the included file wouldcause an INCLUDE loop. For example, if a file includes another file which inturn includes the first file, CP would process the first file, but not the secondfile, because the two files would just loop back and forth including each otherand you would never finish loading your routines.

Examples1. To have CP read and process another file when dynamically loading CP

routines, place the following in the file being loaded:include fn1 text

2. To have CP read and process all members of a TXTLIB, place the following inthe file being loaded:

include subrtns txtlib member *

Messagesv HCP003E Invalid option - statement contains extra option(s) starting with optionv HCP6703E File fn ft fm not found.v HCP6704E Missing token at end of linev HCP6706E The variations of this message are as follows:

– Invalid file name - fn– Invalid file type - ft– Invalid file member name - member

v HCP6710E Including file fn ft would cause an include loop -- statement ignored.v HCP8019E Invalid placement:v HCP8040E File fn ft fm Record nnn

Copy_of_record

CPXLOAD Directives


OPTIONS DirectiveFormat

►►(1)

OPTIONsCONtrol epnameNOCONtrol

LEtNOLEt

LOckNOLOck

MPNOMPNONMP

PERManentTEMPorary

►◄

Notes:

1 You must specify at least one operand. If you specify more than one operand, you can specify themin any order.

Purpose

Use the OPTIONS directive to set the defaults for dynamically loading CP routinesinto the system execution space using a CPXLOAD command or configuration filestatement.

How to specify

OPTIONS directives must start after column 1 of the input record. You can placethem anywhere between the control sections (CSECTs) of the dynamically loadedCP routine and you can include as many directives as needed. The attributes thatyou specify on the OPTIONS directive (for example, NOMP) will be set for allexternal symbols in the CSECT. Within a CSECT, if you need to specify differentOPTIONS attributes for different external symbols, you must split the CSECT intomultiple CSECTs.

The defaults that you set on an OPTIONS directive remain in effect only for theduration of the current CPXLOAD operation. After all the routines for thatCPXLOAD operation are loaded, the defaults revert back to those defined by IBM.

If you specify more than one OPTIONS directive that specify conflicting defaults,the latest default specification overrides any previous default specifications, withthe following exceptions: CONTROL, NOCONTROL, PERMANENT, andTEMPORARY. Once specified, you cannot override the defaults for these 4operands in a subsequent OPTIONS directive. However, you can override thesedefaults using a CPXLOAD command or configuration file statement. Defaultsspecified on CPXLOAD always override defaults specified on OPTIONS directives.

Operands

CONtrol epnametells CP to call the specified entry point after dynamically loading the CProutines and before processing a CPXUNLOAD request. You can load theroutines containing the specified entry point either before or within thisCPXLOAD request. The variable epname must be a 1- to 8-character string. Thefirst character must be alphabetic or one of the following special characters:dollar sign ($), number sign (#), underscore (_), or at sign (@). The rest of thestring can be alphanumeric characters, the 4 special characters ($, #, _, and @),or any combination thereof.

Note: Normally, if CP cannot find an entry point when processing a routine, itignores the unknown entry point and continues normal processing. This is not

CPXLOAD Directives


true when you specify the CONTROL epname operand. If CP cannot find theentry point you specify on CONTROL, CP terminates processing yourCPXLOAD request and will not load the routines into its storage.

NOCONtrol tells CP not to call an entry point after loading CP routines and beforeprocessing a CPXUNLOAD request.

LEt tells CP to ignore any records that are completely blank or that contain anunexpected value in column 1, and to continue the load operation. Thisaccommodates the non-commented information that can be left in a TEXT fileby an assembler utility (such as VMFHASM or VMFHLASM).

NOLEt tells CP to stop the load operation when an unexpected value is encounteredin column 1. Column 1 is expected to contain an asterisk (*) to denote acomment, X'02' for a TEXT record, or a blank for a possible CPXLOADdirective.

LOck is provided for compatibility purposes only and has no effect.

NOLOck is provided for compatibility purposes only and has no effect.

MP tells CP that the entry point is multiprocessor (MP) capable. This means thatthe entry point can be dispatched on any of the machine's processors. Ifomitted, MP is the default.

NOMPNONMP

tells CP that the entry point is dispatched only on the master processor,because (in general) the entry point assumes that competitive routines are alsonot multiprocessor capable. Use NOMP or NONMP to prevent entry pointsfrom overlaying each other's chains of control blocks when you do not take theprecaution of getting a system lock. For example, SPOOL routines are NOMP.

PERManent tells CP that the dynamically loaded CP routines are to remain a part of CPuntil a CP SHUTDOWN command is issued or a software-initiated restart(bounce) occurs. This means you cannot use the CPXUNLOAD command toremove these routines.

TEMPorary tells CP that the dynamically loaded CP routines can be unloaded in the futurewith a CPXUNLOAD command.

Usage notes1. To dynamically load the CP routines into the system execution space, use the

CPXLOAD command or configuration file statement. For more information onthe CPXLOAD command, see z/VM: CP Commands and Utilities Reference. Formore information on the CPXLOAD configuration file statement, see z/VM: CPPlanning and Administration.

2. The purpose of the OPTIONS directive is to allow you to specify yourCPXLOAD options before issuing the actual command or configuration filestatement. However, you can specify options on both the OPTIONS directiveand the CPXLOAD command or statement. If you do so and any of the optionsconflict, CP uses the options from the CPXLOAD command or statement. For

CPXLOAD Directives


example, suppose you specify PERMANENT on the OPTIONS directive andTEMPORARY on the CPXLOAD command, CP will use TEMPORARY.

Examples1. To have CP set the default for dynamically loading CP routines that entry

points are not multiprocessor capable and must be dispatched on the masterprocessor, place the following in the file being loaded:

options nomp

Messages

HCP002E Invalid operand - operand

HCP2757E This option[, or its opposite,] hasalready been specified - option

HCP2768E Missing {file name|filetype|number|entry point name|filemember name}

HCP6704E Missing token at end of line

HCP8019E Invalid placement:

HCP8040E File fn ft fm Record nnn Copy_of_record

HCP002E • HCP8040E


CPXLOAD Directives


Appendix D. CP Files of Interest

This appendix lists and briefly describes the CP control blocks, macros, andmodules that you can use with your dynamically loaded CP routines.

CP Control Blocks and MacrosThe CP component of z/VM has many data areas, control blocks, and macros thatgovern such things as real I/O, virtual I/O, system initialization, dispatching, andso forth. The intent of this section is to focus the reader on a few of the controlblocks and macros that are related to virtual machine characteristics, real andvirtual I/O control blocks, system operation, and system-equated values and validdevice types. This list of control blocks and macros is neither complete norexhaustive. It is supplied here only to inform you that these control blocks andmacros exist. It does not imply that you should or must use them.

Control Block Purpose

ADDDL (add double length binary) generates the necessary code to add 2fixed-point doubleword numbers.

HCPCALL (VM general purpose macro to call a module) generates the necessary codeto call a CP entry point.

HCPCASRC (case of return code) generates the necessary code to construct a branchtable for a return code passed in register 15.

HCPCMPBK (component ID block) contains fields for customer use. Each component IDcan be assigned a separate CMPBK.

HCPCMPID (define component ids for macro processing) sets global macro variables sothat other macros may use component ids other than HCP for theirprocessing.

HCPCONSL (console interface macro) generates the necessary code to write a messageor response, or to read input from the terminal.

HCPDROP (structured drop statement) generates the necessary code to assist theHCPUSING macro in identifying conflicts between USING and DROP. Aconflict arises whenever an area is addressed by more than one register ora single register is used to provide addressability to more than one area.

HCPDVTYP (constants for device type information) contains constants for all of thedefined device classes, types, models, and device-specific featureinformation.

HCPENTER (enter a module) generates the necessary code for most CP module entrypoints to save registers and provide addressability.

HCPEPILG (epilogue macro) generates the necessary code to produce an epiloguecontaining the unique characters (the last 2) of every valid entry definitionand entry point within that module, along with the offset to that entrypoint definition. This allows diagnostic and dump modules to locate everyCP entry point. This macro also generates the “END” statement for theassembler.

HCPEQUAT (equate symbols) contains all of the standard system-equated values usedby CP modules. These include equated values such as: hardwarearchitecture definition bits, scheduler values, system name table values,terminal values, and values for general and floating point registers.

HCPEQXIT (equates for exit control) contains equated values for CP exit numbers.



HCPEXIT (exit linkage) generates the necessary code to exit and return to the callerfrom any routine entered using the HCPCALL macro. It provides theability to reload registers from the same save area used at the entry pointestablished by HCPENTER.

HCPEXTRN (generate an EXTRN for a symbol) generates the necessary code togenerate an EXTRN for a symbol, if one has not been previouslygenerated.

HCPGETST (get storage macro) generates the necessary code to get a block of freestorage, or to get one or more contiguous 4 KB pages.

HCPLCALL (local call linkage macro) generates the necessary code to generate a callwith dynamic save area linkage to a function that is local (that is, in thesame module).

HCPLENTR (local function entry linkage) generates the necessary code for a local entrypoint to save registers and provide addressability.

HCPLEXIT (return from local function) generates the necessary code to generatelinkage to return to the caller of a local function.

HCPPROLG (prologue for module) generates the necessary code to establish attributesfor the entire module.

HCPRDEV (real device control block) describes a real I/O device. Each real I/Odevice known to CP is represented by an HCPRDEV control block. TheRDEV contains information about the type and class of a specific device,the status of the device as well as queue anchors for I/O requests. TheRDEV also contains pointers to other I/O control blocks associated with areal I/O device.

HCPRELST (release storage macro) generates the necessary code to release a block offree storage, or to release one or more contiguous 4 KB pages.

HCPSYSCM (system common area) contains system-wide variables, counters, pointers,and constants. Some of these include:

v The volume serial ID of the system residence, warm start, andcheckpoint volumes

v Pointers to real device control blocks

v Spool file block pointers

v System counters for logged on users

v Paging slots available

v Reserved pages

v Paging load.

The system common area also contains constants such as the size of realstorage, directory control information, and the system residence volumecharacteristics and definition information.

HCPUSING (USING assembler statement) generates the necessary code to provide theUSING assembler statement with the ability to identify potential conflictsbetween USING and DROP. A conflict arises whenever an area isaddressed by more than one register or a single register is used to provideaddressability to more than one area.

HCPVDEV (virtual device control block) describes the status of a virtual deviceaccessible by a virtual machine. As with the RDEV block, the VDEV blockalso contains information about the type and class of a specific virtualdevice, the status of that device, and information about the last I/O thatwas active.

CP Control Blocks and Macros



HCPVMDBK (virtual machine definition block) describes the characteristics of a virtualmachine. This includes its user logon identification, accountinginformation, virtual registers, dispatching priority, and machine optionsettings. Every virtual machine on the system is represented by aHCPVMDBK control block.

HCPXCRBK (CP exit call request block) contains data fields used by CP to control thecalling of CP exit routines. At entry, each CP exit routine is passed theaddress of its XCRBK in register 2.

HCPXITPL (exit parameter list) describes parameter lists for each CP exit point.

HCPXREF (force a cross reference) generates the necessary code to force symbols toshow up in the cross reference when they are not referenced explicitly byname.

IPARML (IUCV/APPC parameter list and external interrupt mapping DSECT) mapsthe parameter list used when an IUCV or APPC/VM function is issued.Also, IPARML maps the external interrupt buffer when an IUCV orAPPC/VM external interrupt is reflected to a virtual machine or CPsystem service.

SUBDL (subtract double length binary) generates the necessary code to subtract afixed-point doubleword number from another fixed-point doublewordnumber.

VMCPARM (VMCF communications parameter list) specifies the virtual machinecommunication facility (VMCF) function to be executed along with otherinformation required by VMCF.

VRDCBLOK (virtual/real device characteristics block) describes a specific virtual device.This description includes both virtual and real device information as wellas virtualized read device characteristics data.

For a list of macros and copyfiles which are provided as programming interfaces,see z/VM: CP Programming Services. For a complete description of all of the CPcontrol blocks, see the IBM VM operating system home page. For more informationabout the macros, see the documentation in the macros.

CP ModulesThe CP component of z/VM has many different modules that control systeminitialization, spooling, real I/O, virtual I/O, system services, dispatching,scheduling, and so forth. This section is being provided to give the readerexamples of some of the most commonly called CP routines and their function.

CP Routine Purpose

HCPBITSF Turns off a bit in a bit map.

HCPBITSN Turns on a bit in a bit map.

HCPCVTRM Convert from binary to decimal digits andtrim off any leading zeros.

HCPCVTHB Convert from hexadecimal displayable digitsto binary.

HCPIOLAR Acquire an RDEV lock.

HCPIOLRR Release an RDEV lock.

HCPSCNAR Add an RDEV to the radix tree.

HCPSCNRU Find an RDEV in the radix tree.

CP Control Blocks and Macros

Appendix D. CP Files of Interest 189

CP Routine Purpose

HCPZIACC Access a CP-accessed disk.

HCPZICLS Close a file on a CP-accessed disk.

HCPZIGET Read a record from a file on a CP-accesseddisk.

HCPZIOPN Open a file on a CP-accessed disk.

HCPZIPUT Write a record to a file.

HCPZISTA Provide information about the existence of afile on a CP-accessed disk (STATE).

HCPZPRPC Parse a partial command contained in thegeneral system data block (GSDBK).

HCPZPRPG Parse a general system data block (GSDBK).

For more information on these CP routines and the services they provide, see theindividual CP module.

Note: It is possible that the names of these routines could change. For example, aroutine may be moved from one module to another as a result of a module split.We recommend that you confirm the existence of any routines that you use whenyou apply service.

CP Modules


Appendix E. CP Exit Macros

This section describes the CP exit macros that are used with CP exit points. The CPexit macros are:

Macro Function Page

HCPXSERV performs any of the following tasks:

v Locate exit control blocks

v Enable or disable or test exits

v Call exit routines

v Locate component ID blocks (CMPBKs)

v Allocate or deallocate component ID blocks (CMPBKs)

v Control access to component ID blocks (CMPBKs).

“HCPXSERV: CP Exit ServicesDirector” on page 192

MDLATENT defines the attributes of CP modules and their entry points.The HCPCALL macro uses this information when generatinga CP load list.

“MDLATENT: MDLAT EntryDefinition” on page 202

MDLATHDR marks the beginning of a CP module attribute list. Thismacro initializes variables that will be used and updated bysubsequent MDLATENT macro invocations.

“MDLATHDR: MDLAT Header”on page 209

MDLATTLR marks the end of a CP module attribute list. This macromodifies macro variables to indicate completion of a CPmodule attribute list.

“MDLATTLR: MDLAT Trailer” onpage 210



HCPXSERV: CP Exit Services Director

►► ▼

▼

,(1)

HCPXSERV CALL , EXIT = exit , DISABLED=labellabel DISABLE (Rx) ERROR=label

ENABLE INVEXIT=labelFIND NONE=labelNEXT ,TEST

PLIST= ( label )(Rx)

PLISTBLD= 'GETST'label(Rx)

(2)ALLOCATE , COMPID = 'ccc' , QWORDS = nDEALLOCATE label (Rx)FIND (Rx) valueLOCKEXCLLOCKEXCLUSIVELOCKSHAREDLOCKSHRUNLOCKEXCLUNLOCKEXCLUSIVEUNLOCKSHAREDUNLOCKSHR

►◄

Notes:

1 For a list of legal and illegal combinations of EXIT actions and parameters, see Table 7 on page 196.

2 For a list of legal and illegal combinations of COMPID actions and parameters, see Table 7 on page196.

Purpose

Use HCPXSERV to perform any of the following tasks:v Locate CP exit control blocksv Enable or disable or test CP exit pointsv Call CP exit routinesv Locate component ID blocks (CMPBKs)v Allocate or deallocate component ID blocks (CMPBKs)v Control access to component ID blocks (CMPBKs).

Operands

labelis an optional assembler label.

CALL tells HCPXSERV to generate instructions (a macro expansion) which call theCP exit routines associated with the specified CP exit number.

DISABLE tells HCPXSERV to generate instructions (a macro expansion) which call theCP exit routine that marks CP exit points as “disabled”.

ENABLE tells HCPXSERV to generate instructions (a macro expansion) which call theCP exit routine that marks CP exit points as “enabled”.

CP Exit Macros


FIND tells HCPXSERV to generate instructions (a macro expansion) which call theCP exit routine that locates the CP exit control block (XITBK) for the specifiedCP exit number.

NEXT tells HCPXSERV to generate instructions (a macro expansion) which call theCP exit routine that locates the CP exit control block (XITBK) for the next CPexit number. That is, the CP exit routine looks for the first XITBK with a CPexit number greater than the specified CP exit number. (Remember: a CP exitnumber only has an XITBK if it is defined and has one or more entry pointsassociated with it.)

TEST tells HCPXSERV to generate instructions (a macro expansion) which testwhether the specified CP exit number is marked as “enabled”.

EXIT=exittells HCPXSERV the CP exit number for which you are generating instructions(a macro expansion). The variable exit must be a hexadecimal number in therange X'0000' through X'FFFF'.

EXIT=(Rx) tells HCPXSERV to look in the specified register to find the CP exit number forwhich you are generating instructions (a macro expansion). The variable xmust be a decimal number in the range 0 through 15.

DISABLED=labeltells HCPXSERV to branch to the specified label if the CP exit point is markedas “disabled”.

ERROR=labeltells HCPXSERV to branch to the specified label if an error condition isdetected (based on the value that is returned in R15).

INVEXIT=labeltells HCPXSERV to branch to the specified label if the CP exit number is notvalid. That is, the CP exit number is not a 4-digit hexadecimal number in therange X'0000' through X'FFFF'.

NONE=labeltells HCPXSERV to branch to the specified label if the CP exit number has noCP exit control block (XITBK). That is, having no XITBK implies that no oneused the ASSOCIATE EXIT command or configuration file statement toassociate one or more entry points with this CP exit number.

PLIST=(label)PLIST=(label, label, ...) PLIST=((Rx),...)

lists labels of data items or registers. Labels and registers may be included inthe same parameter list. CP places the addresses of labels and the addressescontained in registers in the parameter list (PLIST) into the parameter list buildarea (PLISTBLD).

Using the PLIST operand causes the HCPXSERV macro expansion to turn onthe high order bit of the last address in the parameter list.

We recommend that you use the standard labels for the first three entries ofthe PLIST. Using the standard entries will assist in the writing of CP exitroutines because each CP exit routine can then be written with the standard

CP Exit Macros

Appendix E. CP Exit Macros 193

entries in mind. These standard entries provide working storage for yourcurrent CP exit routines, and they provide room for possible additionalfunction in the future.

The first three standard entries are:

'RESERVED'is the label of an area that provides room for possible additional functionin the future.

'USERWORD'is the label of the User Area, which provides 32 bytes of user wordsaligned on a doubleword boundary. The first time CP calls the CP exitpoint, CP initializes these 32 bytes to binary zeros. Whatever any CP exitroutine leaves in these 32 bytes are available to the next CP exit routine.After the last CP exit routine returns control to CP, CP releases these 32bytes.

Your CP exit routine can use the User Area as working storage.

'TRTTABLE' is the label of the translate-and-test (TRT) table, which provides 256 bytesof user words aligned on a doubleword boundary. The first time CP callsthe CP exit point, CP initializes these 256 bytes to binary zeros. Whateverany CP exit routine leaves in these 256 bytes are available to the next CPexit routine. After the last CP exit routine returns control to CP, CP releasesthese 256 bytes.

Your CP exit routine can use the TRT table as a translate-and-test table, asa translate table, or as any working storage.

PLISTBLD tells HCPXSERV where to store the addresses of the data items listed on thePLIST operand. There are three ways to indicate the location of the PLIST:

PLISTBLD='GETST'tells HCPXSERV to:v Allocate the PLIST build area from free storage,v Store the addresses of the PLIST data items,v Call to the associated CP exit routines, andv Release the storage allocated for the PLIST build area.

This is the most flexible method because HCPXSERV can calculate therequired size of the PLIST build area and allocate it dynamically. However,this is not the most efficient method.

PLISTBLD=labeltells HCPXSERV to store the addresses of the PLIST data items in thestorage area at the specified label. HCPXSERV assumes that this storagearea is large enough to hold all of the PLIST addresses, becauseHCPXSERV cannot and does not perform any checking.

PLISTBLD=(Rx)tells HCPXSERV to store the addresses of the PLIST data items in thestorage area whose address is in the specified register. HCPXSERV assumesthat this storage area is large enough to hold all of the PLIST addresses,because HCPXSERV cannot and does not perform any checking.

CP Exit Macros


ALLOCATE tells HCPXSERV to generate instructions (a macro expansion) which calls theCP exit routine that allocates or locates the component ID block (CMPBK) forthe specified component ID.

DEALLOCATE tells HCPXSERV to generate instructions (a macro expansion) which calls theCP exit routine that deallocates the component ID block (CMPBK) for thespecified component ID.

FIND tells HCPXSERV to generate instructions (a macro expansion) which calls theCP exit routine that locates the component ID block (CMPBK) for the specifiedcomponent ID.

LOCKEXCLLOCKEXCLUSIVE

tells HCPXSERV to generate instructions (a macro expansion) which calls theCP exit routine that locates the component ID block (CMPBK) for the specifiedcomponent ID and acquires the CMPBK as “lock exclusive”.

LOCKSHAREDLOCKSHR

tells HCPXSERV to generate instructions (a macro expansion) which calls theCP exit routine that locates the component ID block (CMPBK) for the specifiedcomponent ID and acquires the CMPBK as “lock shared”.

UNLOCKEXCLUNLOCKEXCLUSIVE

tells HCPXSERV to generate instructions (a macro expansion) which calls theCP exit routine that relinquishes the component ID block (CMPBK) that wasacquired as “lock exclusive” for the specified component ID.

UNLOCKSHAREDUNLOCKSHR

tells HCPXSERV to generate instructions (a macro expansion) which calls theCP exit routine that relinquishes the component ID block (CMPBK) that wasacquired as “lock shared” for the specified component ID.

COMPID tells HCPXSERV the component ID for which you are generating instructions(a macro expansion). The component ID is a 3-character string. Because youwill probably use the same component ID for the HCPCMPID macro or for thealternate MDLAT macros, we recommend that you use a component IDcomposed of alphabetic characters (A through Z) and numeric characters (0through 9), starting with an alphabetic character.

Specify the component ID in any of the following forms:

COMPID='ccc'defines the 3-character component ID to HCPXSERV.

COMPID=labeltells HCPXSERV to look for the 3-character component ID in the storagelocation specified by label.

COMPID=(Rx)tells HCPXSERV to look for the 3-character component ID in the storagelocation pointed to by the address in the specified register.

CP Exit Macros


QWORDS tells HCPXSERV the number of additional quadwords (units of 16 bytes) to usewhen allocating a new component ID block (CMPBK).

Specify the additional quadwords in any of the following forms:

QWORDS=ndefines the number of additional quadwords that HCPXSERV should usewhen allocating the new CMPBK. The variable n is a decimal numberbetween 0 and 240. If you omit n or specify n as 0 (zero), HCPXSERVallocates a CMPBK of the standard size.

QWORDS=(Rx)tells HCPXSERV to look in the specified register for the number ofadditional quadwords to use when allocating the new CMPBK.

QWORDS=valuedefines the number of additional quadwords in the form of an absolutevalue. For example:

...,QWORDS=LAB2-LAB1

Examples

Usage notes1. The following table shows which combinations of EXIT and COMPID actions

and parameters are valid:

Table 7. Legal and Illegal HCPXSERV Action/Parameter Combinations

EXIT Action

Parameter

EXIT DISABLED ERROR INVEXIT NONE PLIST PLISTBLD COMPID QWORDS

CALL Req v Req Opt1 v Opt2 Opt2 v v

DISABLE Req v Opt Opt1 Opt v v v v

ENABLE Req v Opt Opt1 Opt v v v v

FIND Req v Opt Opt1 Opt v v v v

NEXT Req v Opt Opt1 Opt v v v v

TEST Req Req v Opt1 v v v v v

COMPID Action

ALLOCATE v v v v v v v Req Opt

DEALLOCATE v v v v v v v Req v

FIND v v v v v v v Req v

LOCK EXCLUSIVE v v v v v v v Req v

LOCK SHARED v v v v v v v Req v

UNLOCK EXCLUSIVE v v v v v v v Req v

UNLOCK SHARED v v v v v v v Req v

Legend:

Req Required combination of action and parameter.

v Cannot use this combination of action and parameter.

Opt Optional combination of action and parameter.

Opt1 If you specify EXIT=(Rx), this is a required combination of action and parameter. If you specify EXIT=exit, this is an optional combinationof action and parameter.

Opt2 Optional combination of action and parameter, except that PLIST requires PLISTBLD.Note: You can specify the FIND action with both EXIT and COMPID, but not with the same combinations of parameters. For this reason, we listed ittwice in this table: once under the EXIT actions and once under the COMPID actions.

2. The HCPXSERV macro will generate the necessary machine instructions toplace the data that you specified into the proper registers. For example, if you

CP Exit Macros


specified COMPID='ABC', the HCPXSERV macro will expand to cause register1 to be loaded with the address of the component ID string 'ABC'. In order thatyou know which registers will be used, so that you do not expect the value insome register to be preserved across the HCPXSERV macro expansion, thistable shows you which registers HCPXSERV will use.

Table 8. Register Contents During HCPXSERV Execution

EXIT Action Register

R0 R1 R2 R14 R15

CALL CP ExitNumber

PLISTBLDAddress

Work Area LinkageAddress

LinkageAddress

DISABLE CP ExitNumber

— — LinkageAddress

LinkageAddress

ENABLE CP ExitNumber


LinkageAddress

FIND CP ExitNumber


LinkageAddress

NEXT CP ExitNumber


LinkageAddress

TEST CP ExitNumber

— — Work Area Work Area

COMPID Action

ALLOCATE — COMPIDAddress

QWORDSValue

LinkageAddress

LinkageAddress

DEALLOCATE — COMPIDAddress

— LinkageAddress

LinkageAddress

FIND — COMPIDAddress

— LinkageAddress

LinkageAddress

LOCK EXCLUSIVE — COMPIDAddress

— LinkageAddress

LinkageAddress

LOCK SHARED — COMPIDAddress

— LinkageAddress

LinkageAddress

UNLOCK EXCLUSIVE — COMPIDAddress

— LinkageAddress

LinkageAddress

UNLOCK SHARED — COMPIDAddress

— LinkageAddress

LinkageAddress

3. Following the execution of the HCPXSERV macro, you will need to examinethe return code, which will have been placed into register 15. If the return codeindicates that your HCPXSERV request was successful (which will be indicatedby a return code value of 0, and sometimes 4), you may find a returned valuein certain registers. This table shows possible return codes and possiblereturned values.

Table 9. Register Contents After HCPXSERV Completion

EXIT Action Register Contents or Meaning

CALL R15 Contains the return code as set by your CP exit routine.

CP Exit Macros


Table 9. Register Contents After HCPXSERV Completion (continued)

EXIT Action Register Contents or Meaning

DISABLE R15=0 HCPXSERV updated the control blocks.

R15=4 There is no XITBK for this CP exit number. If it was specified, HCPXSERVtransfers control to the label specified on the NONE parameter. If NONEwas omitted, HCPXSERV continues execution at the next sequentialinstruction.

R15=8 The CP exit number was not valid. HCPXSERV passes control to the labelspecified on the INVEXIT parameter.

ENABLE R15=0 HCPXSERV updated the control blocks.

R15=4 There is no XITBK for this CP exit number. If it was specified, HCPXSERVtransfers control to the label specified on the NONE parameter. If NONEwas omitted, HCPXSERV continues execution at the next sequentialinstruction.

R15=8 The CP exit number was not valid. HCPXSERV passes control to the labelspecified on the INVEXIT parameter.

R15=12 The system is in the process of being IPLed and the IPL parameterNOEXITS was specified after the prompt, either by the system operator orby a CP exit routine. CP rejected this attempt to enable a CP exit pointbecause the system has not finished initialization processing. You mustwait until after the IPL to enable this CP exit point.

FIND R15=0

R1

HCPXSERV found the XITBK for the specified CP exit point.

Contains the address of the newly-found XITBK.

R15=4 The XITBK for the specified CP exit point does not exist. If you specifiedthe NONE parameter on the HCPXSERV invocation, control passes to thelabel specified on NONE. If you did not specify NONE, control passes tothe next sequential instruction.

R15=8 the CP exit number was not valid. HCPXSERV passes control to the labelspecified on the INVEXIT parameter.

NEXT R15=0

R1

HCPXSERV found the XITBK for the CP exit point after the specified CPexit point.

Contains the address of the newly-found XITBK.

R15=4 There is no XITBK after the specified CP exit point. If you specified theNONE parameter on the HCPXSERV invocation, control passes to the labelspecified on NONE. If you did not specify NONE, control passes to thenext sequential instruction.

R15=8 the CP exit number was not valid. HCPXSERV passes control to the labelspecified on the INVEXIT parameter.

TEST — If the XITBK appears to be defined and enabled, control passes to the nextsequential instruction after the HCPXSERV macro.

If the XITBK appears to be disabled, control passes to the label specifiedon the DISABLED parameter.

In general, the registers are not changed, with the exception of R0, R14,and R15, whose contents are destroyed after HCPXSERV completesexecution.

CP Exit Macros


Table 10. Register Contents After HCPXSERV Completion Continued

COMPID Action Register Contents or Meaning

ALLOCATE R15=0

R1

HCPXSERV successfully allocated the component ID block (CMPBK).

Contains the address of CMPBK. The CMPBK lock was acquired asexclusive, so the caller is responsible for relinquishing the lock.

R15=4

R1

The CMPBK could not be allocated as it already exists.

Contains the address of the existing CMPBK. Because the CMPBK was notallocated with this invocation of HCPXSERV, no lock was acquired.

R15=8 Reserved for IBM use and currently unused.

R15=12 The QWORDS value in R2 was not valid; no CMPBK was allocated.

DEALLOCATE R15=0 HCPXSERV successfully deleted the specified CMPBK.

R15=4 HCPXSERV could not locate the specified CMPBK for deletion.


R15=12 The CMPBK lock was not an exclusive lock.

FIND R15=0

R1

HCPXSERV successfully found the CMPBK.

Contains the address of the specified CMPBK.

R15=4 HCPXSERV could not find the specified CMPBK.


LOCK EXCLUSIVE R15=0

R1

HCPXSERV successfully acquired the exclusive lock on the specifiedCMPBK.


R15=4 HCPXSERV could not find the specified CMPBK; no lock was acquired.


R15=12 The CMPBK lock was destroyed.

R15=16 There was an unexpected return code from the locking routine(HCPLCKAX).

LOCK SHARED R15=0

R1

HCPXSERV successfully acquired the shared lock on the specified CMPBK.


R15=4 HCPXSERV could not find the specified CMPBK; no lock was acquired.



R15=16 There was an unexpected return code from the locking routine(HCPLCKAS).

UNLOCK EXCLUSIVE R15=0 HCPXSERV successfully relinquished the exclusive lock on the specifiedCMPBK.

R15=4 HCPXSERV could not find the specified CMPBK; no lock wasrelinquished.



R15=16 There was an unexpected return code from the unlocking routine(HCPLCKRX).

CP Exit Macros


Table 10. Register Contents After HCPXSERV Completion Continued (continued)

COMPID Action Register Contents or Meaning

UNLOCK SHARED R15=0 HCPXSERV successfully relinquished the shared lock on the specifiedCMPBK.

R15=4 HCPXSERV could not find the specified CMPBK; no lock wasrelinquished.



R15=16 There was an unexpected return code from the unlocking routine(HCPLCKRS).

Example 1To locate the CMPBK for your component ID (in this example, “C22”) and toacquire shared control over that CMPBK (if it exists), code the following:

HCPXSERV LOCKSHARED, Locate and lock XCOMPID=’C22’ ... my Component ID Block

HCPCASRC (GOTIT, 00: All OK XMAKEIT, 04: No such CMPBK XABEND7, 08: Bad return code? XMAKEIT, 12: CMPBK was destroyed XABEND11), 16: Bad return code? XELSE=ABEND33 ??: Bad return code?

ABEND7 DS 0HHCPABEND 007,HARD



Example 2To allocate the CMPBK for your component ID (“TAS”), acquire exclusive controlover that CMPBK (if it does not yet exist), and define an additional 32 bytes (2quadwords) of CMPBK space, code the following:

HCPXSERV ALLOCATE, Allocate and lock XCOMPID=’TAS’, ... my Component ID Block XQWORDS=2

HCPCASRC (GOTIT, 00: All OK XBEENDONE, 04: Already exists XABEND1, 08: Bad R1 value? XABEND2), 12: Bad R2 value? XELSE=ABEND33 ??: Bad return code?




CP Exit Macros


Example 3To call the CP exit routines for your CP exit number (in this example, “FEED”),have HCPXSERV allocate and release the parameter list (PLIST) build area, andpass the standard PLIST entries and a control block named C22BK, code thefollowing:

HCPXSERV CALL, Call my exit FEED XEXIT=FEED, XPLIST=(’RESERVED’, X’USERWORD’, X’TRTTABLE’, XC22BK), XPLISTBLD=’GETST’, XERROR=WHAT_HAPPEN...

WHAT_HAPPEN DS 0H

CP Exit Macros


MDLATENT: MDLAT Entry Definition

►►label

MDLATENT(1)

modname,MODATTR=( Module Attributes Entry Point Attributes ) ►

►

▼

,

,MODID=( nn )

►

►

▼

(2),EP=( (epname Entry Point Attributes ) )

(2),(epname Entry Point Attributes )

►

►, CPXLOAD = NO

, CPXLOAD = YES , LLATTR = ' loadlist_attribute '►◄

Module Attributes:

(3) ,RESident ,MP

,NONMP ,DATA

,SHORTREG,SREG

,LONGREG,LREG

,AMODE31,AM31

,AMODE64,AM64,AMODEVAR,AMVAR,AMODEINT,AMINT

►

►

,TMODESTD,TMSTD

,TMODEAR,TMAR,TMODEVAR,TMVAR,TMODEINT,TMINT

Notes:

1 At least one module attribute or entry point attribute must be specified. The separator (,) must beomitted before the first attribute in the string.

2 At least one entry point attribute must be specified.

3 Module attributes may be specified in any order.

Entry Point Attributes:

CP Exit Macros


(2)(1) ,DYNamic

,FASTdyn,GOTO,FASTGOTO,STAtic,FASTR15,FLIH,NONE

(2),NOLEAF

,LEAF ,SHORTREGENT,SREGE,LONGREGENT,LREGE

,AMODE31ENT,AM31E,AMODE64ENT,AM64E,AMODEVARENT,AMVARE

►

►,TMODESTDENT,TMSTDE,TMODEARENT,TMARE,TMODEVARENT,TMVARE

(2),NONRSTD

,RSTD

(2),TRACE

,NOTRACE

Notes:

1 Entry point attributes may be specified in any order.

2 Default only on MODATTR, not on EP.

Purpose

Use MDLATENT to define the attributes of CP modules and their entry points. TheHCPCALL macro uses this information when generating a CP load list.

Operands


modnameis the 6-character name of the module that CP should use when generating theload list.

MODATTR= defines the attributes for the CP module specified by modname. At least onemodule attribute or entry point attribute must be specified on this parameter.You can specify the attributes in any order.

Most module attributes imply corresponding entry point attributes, asindicated in the following table. Other entry point attributes also have defaultson MODATTR. Entry point attributes implied or specified on MODATTR arethe default attributes for all entry points in the module unless overridden. Youcan override an implied default entry point attribute by specifying a differentdefault entry point attribute on MODATTR or by specifying attributes forspecific entry points on the EP parameter. If a module attribute does not implya corresponding default entry point attribute, you must specify the appropriatedefault entry point attribute on MODATTR. You can then override that defaultfor specific entry points on the EP parameter. Entry point attributes aredescribed under the EP parameter.

CP Exit Macros


Module Attribute Implied Default Entry Point Attribute

AMODE31 AMODE31ENTAMODE64 AMODE64ENTAMODEVAR (none)AMODEINT AMODE31ENTTMODESTD TMODESTDENTTMODEAR TMODEARENTTMODEVAR (none)TMODEINT TMODESTDENTSHORTREG SHORTREGENTLONGREG LONGREGENT

The valid module attributes are:

RESident tells CP that the specified module is resident. Because all CP modules areresident, this attribute is supported as a default for compatibility; it shouldnot be specified.

MP tells CP that the specified module can run on any processor. This is thedefault.

NONMP tells CP that the specified module must run on the master processor.

DATA tells CP that the specified module is a data or work area module.

SHORTREG SREG

tells CP that this module uses 32-bit registers. This is the default.

The SHORTREG module attribute implies a default entry point attribute ofSHORTREGENT.

LONGREG LREG

tells CP that this module uses 64-bit registers.

The LONGREG module attribute implies a default entry point attribute ofLONGREGENT.

AMODE31 AM31

tells CP that this module will run in 31-bit addressing mode. This is thedefault.

The AMODE31 module attribute implies a default entry point attribute ofAMODE31ENT.

AMODE64 AM64

tells CP that this module will run in 64-bit addressing mode.

The AMODE64 module attribute implies a default entry point attribute ofAMODE64ENT.

AMODEVAR

CP Exit Macros


AMVARtells CP that this module will run in 31-bit addressing mode or 64-bitaddressing mode, unpredictably.

The AMODEVAR module attribute does not imply a default entry pointattribute. Therefore you must specify the default addressing mode entrypoint attribute on MODATTR.

AMODEINT AMINT

tells CP that this module will be in 31-bit addressing mode at every macro.

The AMODEINT module attribute implies a default entry point attribute ofAMODE31ENT.

TMODESTD TMSTD

tells CP that this module will run in Primary Space mode. This is thedefault.

The TMODESTD module attribute implies a default entry point attribute ofTMODESTDENT.

TMODEAR TMAR

tells CP that this module will run in Access Register mode.

The TMODEAR module attribute implies a default entry point attribute ofTMODEARENT.

TMODEVAR TMVAR

tells CP that this module will run in Primary Space mode or AccessRegister mode, unpredictably.

The TMODEVAR module attribute does not imply a default entry pointattribute. Therefore you must specify the default translation mode entrypoint attribute on MODATTR.

TMODEINT TMINT

tells CP that this module will be in Primary Space mode at every macro.

The TMODEINT module attribute implies a default entry point attribute ofTMODESTDENT.

MODID=(nn)MODID=(nn,nn)MODID=(nn,nn,nn)

are the persistent numeric identifiers that can be used as nicknames torepresent this module in control blocks and trace entries. The variable nn is thevalue from &HCPNXTID. When creating a new MODID, use the valuecurrently specified for the &HCPNXTID variable in the SETNXTID macro. TheSETNXTID macro must also be updated so that the value assigned to&HCPNXTID is one more than the value used for highest MODID that isbeing used by all modules in the system. One module can have a maximum ofthree module IDs (nn).

EP= defines the attributes for specific entry points in this module. For each entrypoint, you can specify these attributes in any order.

CP Exit Macros


Attributes specified on the EP parameter override entry point attributesspecified or implied on the MODATTR parameter. However, only the attributesspecified on EP override MODATTR attributes. Unless overridden by anattribute specified here, the MODATTR entry point attribute (explicit ordefaulted) remains in effect.

The valid entry point attributes are:

epnameis the name of an entry point in this CP module. Each epname must be astring of 1 to 8 characters. The first character must be alphabetic or one ofthe following special characters: dollar sign ($), number sign (#),underscore (_), or at sign (@). The rest of the string can be alphanumericcharacters, the four special characters ($, #, _, and @), or any combinationthereof.

DYNamic tells CP that this entry point is called with a dynamic savearea. This is thedefault on MODATTR.

FASTdyn tells CP that this entry point will be entered using a faster HCPCALL thatprovides fewer services, such as no processor switching and fewer validitychecks. SAVEWRK and SVGWRK are not cleared.

GOTO tells CP that this entry point will be entered using an HCPGOTO statementthat establishes the module's base register.

FASTGOTO tells CP that this entry point will be entered using a faster HCPGOTO thatprovides fewer services, such as no processor switching.

STAtic tells CP that this entry point is called with a static savearea.

FASTR15is a special version of the FASTGOTO attribute. It is intended for IBM useonly.

FLIHidentifies the entry point as a First Level Interrupt Handler. When ahardware interrupt event occurs and a PSW swap takes place, an FLIHentry point is where execution resumes. This attribute is not intended forgeneral CP exit linkage.

NONE tells CP that this entry point does not have a savearea to use.

NOLEAF tells CP that instruction execution reduction is not in effect. This is thedefault on MODATTR.

LEAF can be used with STATIC entry points to reduce instruction execution.STATIC entry points may save Access Registers or may skip saving ARs.There are extra instructions executed in calling a subroutine, and returningfrom a subroutine, that make the right runtime decision. If the programmerknows that saving ARs is not necessary in the subroutine, and that thesubroutine never calls anything else where AR-saving is needed, theprogrammer can assign the LEAF attribute to the entry point to avoid theexecution of the extra instructions. This situation is typically used only in a

CP Exit Macros


high performance execution path, where the programmer wants to reduceinstruction execution as much as possible.

SHORTREGENT SREGE

tells CP that this entry point uses 32-bit registers.

LONGREGENT LREGE

tells CP that this entry point uses 64-bit registers.

AMODE31ENT AM31E

tells CP that this entry point will be entered in 31-bit addressing mode.

AMODE64ENT AM64E

tells CP that this entry point will be entered in 64-bit addressing mode.

AMODEVARENT AMVARE

tells CP that this entry point will be entered in whatever addressing modeis running.

TMODESTDENT TMSTDE

tells CP that this entry point will be entered in Primary Space mode or leftin Home Space mode.

TMODEARENT TMARE

tells CP that this entry point will be entered in Access Register mode.

TMODEVARENT TMVARE

tells CP that this entry point will be entered in whatever translation modeis running.

NONRSTD tells CP that this is a nonrestricted entry point. That is, this entry point canbe called directly using HCPCALL. This is the default on MODATTR.

RSTD tells CP that this is a restricted entry point. That is, this entry point can becalled only by using a special-purpose cover macro.

TRACE tells CP to trace the call and return for dynamic linkage, unless overriddenby specifying TRACE=NO on the HCPCALL macro call. This is the defaulton MODATTR.

NOTRACE tells CP not to trace the call and return for dynamic linkage, unlessoverridden by specifying TRACE=YES on the HCPCALL macro call.

CPXLOAD=NO tells CP that this module will not be loaded using a CPXLOAD command orconfiguration file statement. This means that the module will be included inthe CP load list. This is the default.

CP Exit Macros


CPXLOAD=YEStells CP that this module will loaded using a CPXLOAD command orconfiguration file statement. This means that the module will not be includedin the CP load list.

LLATTR='loadlist_attribute' provides CP with any additional information to be added to the PUNCHstatement of the CP load list. The variable loadlist_attribute must be enclosed insingle quotation marks. Because the information is enclosed in single quotes,you can specify any combination of alphabetic, numeric, and special characters(blanks, parentheses, and so forth). For example, you would specify LLATTR=’(LANG’ if this module was a message repository. Normal assembler rules applyto the specification of single quotes as data for this operand. For example, ifyou specify two single quotes immediately adjacent to each other, the firstsingle quote is not treated as the end of string delimiter. Instead, a single quoteis placed in the string at that point.

Note: The PUNCH statement cannot exceed 80 characters, including thisadditional information. If the PUNCH statement does exceed 80 characters,you will receive an assembler error and the statement will be ignored.

Usage notes1. This macro defines attributes of modules and entry points within a module

attribute list. It must follow a MDLATHDR invocation and precede aMDLATTLR invocation for the list.

2. Entry points called indirectly should be defined with attributes DYN, AM31E,SREGE, and TMSTDE. Entry points called directly may be defined withattributes AM64E, LREGE, and so on.Entry points called indirectly would include:v Dynamically defined CP commandsv Dynamically defined CP Diagnose code routinesv Dynamically defined CP exit routinesThe reason for the attribute restriction on indirect calls is that indirect calls arehandled by service routines that are themselves AM31E, SREGE, and TMSTDE,and will not support the broader attributes. However, if the modules loaded byCPXLOAD can be called directly (for example, if they are all part of the sameCPXLOAD operation or were loaded by CPXLOAD PERMANENT), then theymay use direct calls among themselves and may be defined with the broaderattributes like AM64, LREG, TMAR, and so on.

3. For more information and examples of how to use the MDLATENT macro, seeAppendix H, “Updating the CP Load List,” on page 235.

CP Exit Macros


MDLATHDR: MDLAT Header

►►label

MDLATHDR epname ►◄

Purpose

Use MDLATHDR to mark the beginning of a CP module attribute list. This macroinitializes variables that will be used and updated by subsequent MDLATENTmacro invocations.

Operands


epnameis the symbolic name of the first positional parameter on the alternate MDLATmacro (xxxMDLAT MACRO, where xxx is the 3-character component ID) inwhich this MDLATHDR macro is used. This name should appear exactly ascoded on the alternate MDLAT macro.

For example, if you code a macro variable of “&EPNAME” on the on thealternate MDLAT macro definition line, then you must specify “&EPNAME”for this operand, like this:

MACRO&LABEL xxxMDLAT &EPNAME

MDLATHDR &EPNAME

Usage notes1. This macro marks the beginning of a CP module attribute list. It must precede

any MDLATENT macro invocations for the list. The MDLATTLR macro marksthe end of the CP module attribute list.

2. For more information and examples of the use of this macro, see Appendix H,“Updating the CP Load List,” on page 235.

CP Exit Macros


MDLATTLR: MDLAT Trailer

►►label

MDLATTLR ►◄

Purpose

Use MDLATTLR to mark the end of a CP module attribute list. This macromodifies macro variables to indicate completion of a CP module attribute list.

Operands

labelspecifies an optional assembler label.

Usage notes1. This macro marks the end of a CP module attribute list. It must follow any

MDLATENT macro invocations for the list. The MDLATHDR macro marks thebeginning of the CP module attribute list.

2. For more information and examples of the use of this macro, see Appendix H,“Updating the CP Load List,” on page 235.

CP Exit Macros


Appendix F. CP Parser Macros and Routines

This section describes the CP Parser related macros, and the calling conventionsand parameter lists for CP Parser related routines.

The Parser related macros are:

Macro Function Page

HCPCFDEF denotes the initial state for a given command or configurationfile statement.

“HCPCFDEF: Command/Config File Statement Definition

Macro” on page 212

HCPDOSYN generates the necessary data structures to describe the syntax. “HCPDOSYN: Parser SyntaxTable Generator Macro” on page

214

HCPSTDEF denotes additional states that are possible. “HCPSTDEF: Parser StateDefinition Macro” on page 216

HCPTKDEF defines the transition rules from one state to another. “HCPTKDEF: Parser TokenDefinition Macro” on page 219

The Parser related routines are:

Routine Function Page

HCPZPRPC parses the remainder of the command line. “HCPZPRPC— Parse

Remainder ofCommand

Line” onpage 227

HCPZPRPG parses an arbitrary General System Data Block (GSDBK). “HCPZPRPG— Parse Any

GSDBK” onpage 228

Pre-Processor handles preprocessing of a command or statement prior tobeing processed by the parser. This routine is invoked as theresult of being specified as part of the PREPROC parameterof the HCPDOSYN macro.

“Pre-Processing

Routines” onpage 228

Post-Processor

handles processing after all processing has been successfullycompleted by the parser for a command or statement. Thisroutine is invoked as the result of being specified as part ofthe PROCESS parameter of the HCPCFDEF macro.

“Post-Processing

Routines” onpage 229



HCPCFDEF: Command/Config File Statement Definition Macro

►►label

HCPCFDEF(1)

' verb ' , PROCESS = epname, PROCESS = NONE , MINLEN = n

►

►, RESUME = label

►◄

Notes:

1 You can specify the following operands in any order.

Purpose

Use the HCPCFDEF macro to define the initial state for a given CP command orconfiguration file statement.

Operands


verbis the statement or command verb. The transition to lower case defines theminimum abbreviation. The statement or command verb must be enclosed insingle quotes.

PROCESS=epnameis the label of an entry point used to process the result of an input string scan.

PROCESS=NONEindicates that the results of parsing should not be processed further.

MINLEN=nis the minimum abbreviation that can be used to specify the verb. If MINLENis not specified, the minimum abbreviation length is determined by thetransition from upper to lower case in the verb.

RESUME=labelis the label of an HCPSTDEF entry where parsing is to resume. If RESUME isnot specified, the parser continues processing with the first HCPSTDEFfollowing the HCPCFDEF.

Examples

There are times when you may not wish to begin parsing the command from thebeginning of the command GSDBK. In this example, "QUERY" and "CPCMDS"would have been processed by the command router in order to determine whichsyntax table to use in processing the command. Therefore, we want to resumeparser processing from the point where the command router left off.HCPLCSQC HCPCFDEF ’Query’,RESUME=QRESUME,PROCESS=NONE*

HCPSTDEF REQMATCH=YESHCPTKDEF ’CPCMDs’

*

CP Parser


QRESUME HCPSTDEF REQMATCH=YES...

CP Parser

Appendix F. CP Parser Macros and Routines 213

HCPDOSYN: Parser Syntax Table Generator Macro

►►label

HCPDOSYN ROOT Choice , PLBASE = label, PLBASE = NONE

►◄

ROOT Choice 1:

(1)ROOT = YES

, BADKWD = MSxxxxyy , BADOPEN = MSxxxxyy►

►, BADREAD = MSxxxxyy , BADVERB = MSxxxxyy , TOOMANY = MSxxxxyy

►

►, MISSING = MSxxxxyy , BADCMNT = MSxxxxyy , BADCONT = MSxxxxyy

►

►, BADQUOT = MSxxxxyy , CONFLCT = MSxxxxyy , MAXACC = MSxxxxyy

►

►, PREPROC = epname , RETGSDBK = label , SYNLIST = (pointer,pointer,...)

►

►, TOOLONG = MSxxxxyy , BASES = (area1,area2,...)

, PLLEN = value

ROOT Choice 2:

ROOT = NO, BASES = (area1,area2,...)

Notes:


Purpose

Generates syntax table defined via previous invocations of HCPCFDEF,HCPSTDEF and HCPTKDEF macros.

Operands


ROOT=YESindicates that table being defined is the root of a syntax table. This causesadditional control structure to be set up so that the information can be used asa syntax table.

ROOT=NOindicates that table being defined is not the root of a syntax table.

CP Parser


PLBASE=labelis the label of the base output plist.

PLBASE=NONEindicates that a base output plist is not present.

PLLEN=nis the length of the base output plist in bytes. This operand is required ifPLBASE=NONE is not specified.

SYNLIST=(pointer,pointer,...)is a list of address of other branches of the syntax tree.

BASES=(area1,area2,...,arean)is a list of names of data areas whose addresses will be passed to the parser oninvocation.

BADKWD=MSxxxxyyis a the equate of the message to be issued for a bad keyword error.

BADOPEN=MSxxxxyyis a the equate of the message to be issued when an error is encounteredopening a configuration file.

BADREAD=MSxxxxyyis a the equate of the message to be issued when an error is encounteredreading a configuration file.

BADVERB=MSxxxxyyis a the equate of the message to be issued for a bad statement or commanderror.

TOOMANY=MSxxxxyyis a the equate of the message to be issued for an extra operands on the end ofthe line error.

MISSING=MSxxxxyyis a the equate of the message to be issued for a missing keyword error.

BADCMNT=MSxxxxyyis a the equate of the message to be issued for a bad REXX comment error.

BADCONT=MSxxxxyyis a the equate of the message to be issued for a bad continuation error.

TOOLONG=MSxxxxyyis a the equate of the message to be issued for a records > 4000 error.

CONFLCT=MSxxxxyyis a the equate of the message to be issued for a conflicting options error.

MAXACC=MSxxxxyyis a the equate of the message to be issued for a reached maximumaccumulations error.

PREPROC=epnameindicates a routine to be called by the parser prior to processing the input.

RETGSDBK=labellabel of the fullword field which should point to the queue of error messageGSDBKs.

CP Parser


HCPSTDEF: Parser State Definition Macro

►►label

HCPSTDEF(1)

REQMATCH = YESREQMATCH = NO , FINISH = YES

, FINISH = NO, MATCH1 = YES, MATCH1 = NO

►

►, MISSING = MS xxxxyy , NEXT = label

, NEXT = RETURN_TO_PREVIOUS_STATE, VALEND = YES, VALEND = NO

►◄

Notes:


Purpose

Use the HCPSTDEF macro to define a state in the finite state machine thatexpresses a command or statement syntax.

Operands


REQMATCH=YESREQMATCH=NO

tells the parser whether a token match is required. If CP does not find a matchamong the HCPTKDEFs after the HCPSTDEF, REQMATCH=NO allows atransition to the next state. This operand is required and has no default.

FINISH=YESFINISH=NO

tells the parser whether transition to the next state is allowed once this statehas been processed. FINISH=YES means no additional state transitions areallowed. FINISH=NO means additional state transitions are allowed. If FINISHis not specified and the HCPSTDEF macro is the final HCPSTDEF macrobefore an HCPCFDEF or an HCPDOSYN macro, the default is FINISH=YES. IfFINISH is not specified and the HCPSTDEF macro is not the final HCPSTDEFmacro before an HCPCFDEF or an HCPDOSYN macro, the default isFINISH=NO.

MATCH1=YESMATCH1=NO

tells the parser whether there must be at least one match before theREQMATCH=NO and VALEND=YES options are honored. MATCH1=YESforces the choosing of one or more of a list of keywords.

MISSING=MSxxxxyytells the parser which error message to issue if a required token is notsupplied. If there is no MISSING parameter on the HCPSTDEF macro, then theparser uses the MISSING parameter on the HCPDOSYN macro.

NEXT=labeldefines the default transition to the next state. If omitted, the default transitionis to the next HCPSTDEF definition (if one follows). Even if specified, you canoverride the state transition with the NEXT option on a matched HCPTKDEFmacro.

CP Parser


NEXT=RETURN_TO_PREVIOUS_STATEcodes a state that acts like a subroutine. In this case, upon leaving the state, theparser returns to the last state processed. If no such state exists — that is, if thestate is the first state — no transition takes place.

VALEND=YESVALEND=NO

tells the parser whether another token is required. VALEND=YES indicates thata state is a valid end state. VALEND=NO indicates that a state is not a validend state. If VALEND is not specified and the HCPSTDEF macro is the finalHCPSTDEF macro before an HCPCFDEF or an HCPDOSYN macro, the defaultis VALEND=YES. If VALEND is not specified and the HCPSTDEF macro is notthe final HCPSTDEF macro before an HCPCFDEF or an HCPDOSYN macro,the default is VALEND=NO.

Examples

Example 1This example shows the use of REQMATCH=YES and VALEND=YES.

The syntax of the DIAL command is:

►► Dial useridvdev

►◄

This indicates that "vdev" is optional (in this case, that the command might end)but, if specified, must be a valid hexadecimal virtual device number. TheHCPSTDEF and HCPTKDEF macros for this requirement would include thesekeywords.

HCPSTDEF REQMATCH=YES,VALEND=YESHCPTKDEF TYPE=HEX,RANGE=(0,X’FFFF’)

Example 2This example shows the use of NEXT=label.

The parser may need to be directed to continue its work at a HCPSTDEF macrothat is not immediately following the one presently being used. For example, thissyntax parcel:

►► ▼ A YesNo

B YesNo

►◄

cannot be described in a simple "top-down" series of HCPSTDEF and HCPTKDEFmacros. Branching to separated macros is necessary. This syntax parcel could bedescribed this way.A_OR_B HCPSTDEF REQMATCH=YES,...

HCPTKDEF ’A’,NEXT=AYNHCPTKDEF ’B’,NEXT=BYN

AYN HCPSTDEF REQMATCH=YES,NEXT=A_OR_BHCPTKDEF ’Yes’,ORFLAG=...

CP Parser


HCPTKDEF ’No’,ANDFLAG=...BYN HCPSTDEF REQMATCH=YES,NEXT=A_OR_B

HCPTKDEF ’Yes’,ORFLAG=...HCPTKDEF ’No’,ANDFLAG=...

Example 3This example shows the use of MATCH1=YES.

The syntax for the DRAIN DASD command ends with a repeated choice ofallocation types, at least one of which must be specified.

►► ▼ PAgeSPolSPoolLInksTDskTDiskTEmpdiskALL

►◄

This syntax parcel will almost work.DRSTOPTS HCPSTDEF REQMATCH=YES,VALEND=YES,

NEXT=DRSTOPTSHCPTKDEF ’PAge’,CONFLICT=1,...HCPTKDEF ’SPol’,CONFLICT=2,...HCPTKDEF ’SPool’,CONFLICT=2,...HCPTKDEF ’LInks’,CONFLICT=3,...HCPTKDEF ’TDsk’,CONFLICT=4,...HCPTKDEF ’TDisk’,CONFLICT=4,...HCPTKDEF ’TEmpdisk’,CONFLICT=4,...HCPTKDEF ’ALL’,CONFLICT=(1,2,3,4),...

The use of VALEND=YES indicates that the end of input is accepted.Unfortunately, this is also accepted if there was no allocation type specified at all.To require at least 1 to be specified, we need MATCH1=YES.DRSTOPTS HCPSTDEF REQMATCH=YES,VALEND=YES,MATCH1=YES,

NEXT=DRSTOPTSHCPTKDEF ’PAge’,CONFLICT=1,...HCPTKDEF ’SPol’,CONFLICT=2,...HCPTKDEF ’SPool’,CONFLICT=2,...HCPTKDEF ’LInks’,CONFLICT=3,...HCPTKDEF ’TDsk’,CONFLICT=4,...HCPTKDEF ’TDisk’,CONFLICT=4,...HCPTKDEF ’TEmpdisk’,CONFLICT=4,...HCPTKDEF ’ALL’,CONFLICT=(1,2,3,4),...

CP Parser


HCPTKDEF: Parser Token Definition Macro

►►(1)

HCPTKDEF(2)

' keyword 'Options ►◄

Options:

, ACCUM = (field,value) , ACCUMLEN = field►

►, ANDFLAG = (field,bit_pattern), ANDFLAG = (base(field),bit_pattern)

▼

, CONFLICT = nnn

, CONFLICT = ( nnn ),nnn

►

►, ERROR = MSxxxxyy , LEN = nnnn

, LEN = ( nnn , V ), MINLEN = n

►

►, NEXT = label , ORFLAG = (field,bit_pattern)

, ORFLAG = (base(field),bit_pattern)

►

►(3)

, PRIVS = classes, RANGE = (low_value,high_value) , REQPOSN = n

►

►, SOURCE = field, SOURCE = base(field), SOURCE = (byte1,byte2)

, STORE = field, STORE = base(field)

, TYPE = conv►

►, UWORD = label

Notes:

1 At a minimum, you must specify either a keyword or the TYPE= option.

2 You can specify the following options in any order.

3 This parameter is only valid for commands, not for configuration file statements.

Purpose

The HCPTKDEF macro contains most of the options that simplify the process ofchecking syntax and converting data. Each invocation of the macro contains akeyword, a conversion type, or both.

Operands

ACCUM=(field,value)tells the parser that the value stored at the field specified on the STORE=option of the HCPTKDEF macro is an accumulated item. Thus, you mayspecify more than one such item; if you do, the parser will maintain in the

CP Parser


field identified by field a halfword count of how many such items it hasencountered, and is to consider any attempt to specify more than value suchitems an error. The field field must reside in the primary data area used toreturn information to the calling routine, that is, one identified by the PLBASEkeyword on the HCPDOSYN macro. The parser will check that the number ofitems being accumulated does not exceed the maximum number of itemsallowed (the value of value). The parser will put the converted result of eachitem being accumulated into the next position in the output field after allprevious items that have been accumulated. The parser will not check thatthere is sufficient storage for all of the items being accumulated.

ACCUMLEN=fieldspecifies that the accumulated length of varying strings (TYPE=STRING,LEN=(xxx,V)) is to be maintained in the halfword variable identified by field.

ANDFLAG=(field,bit_pattern)ANDFLAG=(base(field),bit_pattern)

specifies that the flag byte identified by the location (i.e. field or base(field)) isto have a bit_pattern ANDed into it.

CONFLICT=nnnCONFLICT=(nnn[,nnn,])

identifies the other operands with which this option conflicts; the variable nnnis a decimal value between 1 and 255. List as many numbers as you need on asingle CONFLICT keyword.

ERROR=MSxxxxyytells the parser which error message to issue if the token is invalid.

LEN=nnnnLEN=(nnn,V)

defines the maximum length of a string specification (default is the value ofthe L' assembler attribute of the STORE= field). LEN can be used to specifythat a token of TYPE=STRING is to be stored as a varying character string. Ifthe LEN= value specifies a sublist whose second entry is the character V (forexample, LEN=(8,V)) then the token type must be TYPE=STRING. A varyinglength string is stored with a prefix byte that contains the length of the stringvalue. Varying length strings are not padded to the full length of the string.Normal strings are padded with blanks to the full length of the string.

MINLEN=ntells the parser what minimum abbreviation to accept for a keyword. Ifomitted, the transition from upper case to mixed case in the specified keyworddetermines its minimum abbreviation.

NEXT=labeltells the parser what state (which HCPSTDEF macro) to enter next. This labeloverrides any state transition specified on the HCPSTDEF macro or implied byomission of the NEXT keyword on the HCPSTDEF macro.

ORFLAG=(field,bit_pattern)ORFLAG=(base(field),bit_pattern)

specifies that the flag byte identified by the location (i.e. field or base(field)) isto have a bit_pattern ORed into it.

PRIVS=classestells the parser that the specified token is restricted to only those users that areauthorized for any of the specified IBM class versions of the command. ValidIBM privilege class values are A-G. Specify multiple classes as a single token(for example, AEF). If the user executing the command does not have the

CP Parser


required privilege classes for the specified IBM class values, the parser treatsthe HCPTKDEF macro as if it did not exist. This operand should only be usedfor commands and not for configuration file statements.

RANGE=(low_value,high_value)specifies the low and high range for a DEC or HEX conversion. Omission ofthe first number in the ordered pair implies a lower limit of 0, while theomission of the second number implies an upper limit of X'7FFFFFFF'. Thedefault is (0,).

REQPOSN=nspecifies that the token must be in this position in the input stream. The term"position" in this context is the same as saying that "position n" means that wehave scanned of n-1 blank delimited tokens, so this is the n-th blank delimitedtoken. If we are not at this (the value for REQPOSN) position in the inputstream, then we treat this HCPTKDEF as unmatched.

SOURCE=fieldSOURCE=base(field)SOURCE=(byte1,byte2)

tells the parser to move information from the SOURCE location to the locationindicated on the STORE parameter. TYPE and SOURCE cannot be specified onthe same HCPTKDEF invocation. Both the SOURCE and the STORE locationmay reside in the primary output data area or any of the data areas specifiedon the BASES parameter of the HCPDOSYN macro.

Source data may be specified directly in the SOURCE= keyword. Two bytes ofdata must be specified.

STORE=fieldSTORE=base(field)

tells CP where to place the output that results from a conversion or storagereference.

TYPE=convtells what type of token to expect as the next operand. Additional dataverification and processing will be performed on the operand as the result ofthe type specified. See Table 11 for a list of the possible type values.

UWORD=labelspecifies a value that is to be passed to the post-processing routine.

The valid conversion types are listed in Table 11.

Table 11. Conversion types

Conversion Type Meaning

ACCMODE accepts a file mode (A-Z) and converts it to a number from 1 to 26. The result is stored in thespecified output field.

ADDPRIVS accepts a single token (with no imbedded blanks) consisting of the plus sign (+) followed by oneor more privilege classes (alphanumeric characters in the ranges A through Z and 1 through 6). CPconverts the token into a 32-bit bit map where the number 1 marks each privilege class that wasspecified in the token.

CHAR a single character conversion of the form X''hh, c, or 'c'. Any character is accepted.

CP Parser


Table 11. Conversion types (continued)


CSECT accepts and stores a 1- to 8-character token, containing characters only valid in external symbols,in the output field. Valid characters are:

v Dollar sign ($), also called currency symbol

v Number sign (#), also called pound sign or hash symbol

v Commercial “at” sign (@)

v Underscore (_)

v Alphabetic characters (A through Z)

v Numeric characters (0 through 9).

These characters are legal in all positions of the token, except for position 1, which does not acceptthe numeric characters (0 through 9).

DEC accepts and converts a decimal number. The number must be within the range specified on theRANGE keyword on the HCPTKDEF macro. A range from 1 to 65535 (including both end points)is specified as RANGE=(1,65535). All of the following are also valid ranges: RANGE=(,20),RANGE=(1,), RANGE=(,), RANGE=(X'A',B'1111'), and RANGE=(,EQUATEVAL). The resultingnumber may be stored in an output field of one, two, three, or four bytes.

DECLIST accepts a series (or list) of tokens consisting of:

v Decimal numbers (0 through 9)

v Ranges of decimal numbers separated by a dash (–)

The number must be within the range specified on the RANGE keyword on the HCPTKDEFmacro. A range from 1 to 65535 (including both end points) is specified as RANGE=(1,65535). Allof the following are also valid ranges: RANGE=(,20), RANGE=(1,), RANGE=(,),RANGE=(X'A',B'1111'), and RANGE=(,EQUATEVAL).

DECSTOR accepts a decimal token or a decimal token immediately followed by a non-decimal character. Ifthe token is of the latter form, it is split in two and treated as a decimal number followed by asingle character token.

DEVLIST accepts a series (or list) of tokens consisting of:

v Hexadecimal numbers (0 through F)

v Ranges of hexadecimal numbers separated by a dash (–)

The number must be within the range specified on the RANGE keyword on the HCPTKDEFmacro. A range from 1 to 65535 (including both end points) is specified as RANGE=(1,65535). Allof the following are also valid ranges: RANGE=(,20), RANGE=(1,), RANGE=(,),RANGE=(X'A',B'1111'), and RANGE=(,EQUATEVAL).

DEVRANGE a single device number or a range of devices addressed in the form xxxx-yyyy, where xxxx andyyyy are both hexadecimal numbers and xxxx is less than yyyy. The converted result is stored astwo fullwords, the low device number and the high device numbers. If a single address isspecified instead of an address range, the low and high device numbers are identical.

EPNAME accepts and stores a 1- to 8-character token, containing characters only valid in external symbols,in the output field. Valid characters are:




v Underscore (_)




CP Parser




EXTRN accepts and stores a 1- to 8-character token, containing characters only valid in external symbols,in the output field. Valid characters are:




v Underscore (_)




FILENAME accepts and stores a 1- to 8-character token, containing characters only valid in CMS file names, inthe output field. Valid characters are:




v Underscore (_)

v Plus sign (+)

v Minus sign or dash (–)

v Colon (:)



FILETYPE accepts and stores a 1- to 8-character token, containing characters only valid in CMS file types, inthe output field. Valid characters are:




v Underscore (_)

v Plus sign (+)


v Colon (:)



HEX accepts and converts a hexadecimal number. As with decimal conversions, the range checks areapplied. The resulting number may be stored in an output field of one, two, three, or four bytes.

HEXLIST accepts a series (or list) of tokens consisting of:

v Hexadecimal numbers (0 through F)

v Ranges of hexadecimal numbers separated by a dash (–)

The number must be within the range specified on the RANGE keyword on the HCPTKDEFmacro. A range from X'1' to X'FFFF' (including both end points) is specified asRANGE=(1,X'FFFF'). All of the following are also valid ranges: RANGE=(,X'FF'), RANGE=(1,),RANGE=(,), and RANGE=(,EQUATEVAL).

HEX64U accepts a long hex address, in the form nnnnnnnn_nnnnnnnn. The underscore is optional. If anunderscore is used, 8 digits must be to the right of it and a maximum of 8 digits may be to theleft. If an underscore is not used, a total of 16 digits are allowed. RANGE does not affect this type.

IBMCLASS accepts a 1-character token representing one privilege class in the ranges A through G. CPconverts the token into an 8-bit bit map where the number 1 marks the privilege class that wasspecified in the token.

CP Parser




INSTRUCT accepts and converts a 4-, 8-, or 12-digit hexadecimal machine instruction. The instruction must bea valid one as far as its structure and operation code are concerned. The result is a 2-, 4-, or 6-bytevalue, which is stored in the specified output field.

LNKMODE accepts one of the following disk access modes: ER, EW, M, MR, MW, R, RR, SR, SM, SW, W, andWR. The DDEVMODE equivalent equate is placed at the specified output location.

NULL no token is examined. The CP parser uses the NULL conversion type internally.

PASSWORD accepts a single token not longer than the output field. CP converts the token into uppercasebefore storing it. After storing it, CP transforms the token so that the location in storage is nolonger readily readable. CP then clears the original token using blanks.

PRIVS accepts a token consisting of one or more privilege classes (characters in the ranges A-Z and 1-6)concatenated together. The result is converted into a 32-bit bit map with a 1 indicating each classspecified in the token.

PRODID accepts and stores a 7 or 8 character token, containing characters only valid in CMS file names, inthe output field. Valid characters are:




v Underscore (_)

v Plus sign (+)


v Colon (:)



REMPRIVS accepts a token (with no imbedded blanks) consisting of the minus sign (-) followed by one ormore privilege classes (alphanumeric characters in the ranges A through Z and 1 through 6). CPconverts the token into a 32-bit bit map where the number 1 marks each privilege class that isspecified in the token.

REST accepts the remainder of the line to be parsed and places it in the output field, if the output fieldis long enough. REST is useful for commands such as MSG.

SCREENSZ accepts a single token of the form mmmmXnnnn, which represents a screen size and stores theresult as two fullwords in the specified output field.

SETPRIVS accepts a token (with no imbedded blanks) consisting of the equal sign (=) followed by one ormore privilege classes (alphanumeric characters in the ranges A through Z and 1 through 6). CPconverts the token into a 32-bit bit map where the number 1 marks each privilege class that isspecified in the token.

SPLCLASS accepts and converts a single spool file class (A to Z, 0-9).

SPLCLASSES accepts a collection of spool file classes concatenated together. The collection may be as large asthe output field. Each character must be within the ranges A-Z or 0-9.

STRING a single token or quoted string of a length not to exceed that of the output field. Quotation marksare necessary if you want to maintain imbedded blanks and mixed case in the entered string. If itis specified as a single token without quotation marks, the token is uppercased.

TIMEOFF accepts a token of the form hh[.mm[.ss]] that expresses a time offset from UTC. The token isconverted into the number of seconds that the offset represents and is stored as a fullword in theoutput field.

TOKEN a single token not longer than the output field. The token is uppercased before it is stored.

USERID accepts and stores a 1- to 8-character token, containing characters only valid in user IDs, in theoutput field. A userid value of a single asterisk (*) will cause the parser to store the user ID fromthe VMDBK currently addressed by register 11.

CP Parser




USERPTRN accepts and stores a 1- to 8-character token in the output field, which contain only characters validin user IDs and the generic characters (* and %).

Examples

Usage notes1. Storage locations typically are specified in the parser syntax macros by these

methods:kw=wherekw=(where,what)

except for ACCUM= and NEXT=, which we will ignore. Examples would be:STORE=whereORFLAG=(where,what)ANDFLAG=(where,what)

"what" is simply anything that would be acceptable in an Or-Immediate (OI)instruction or in an And-Immediate (NI) instruction."where" typically is specified in either of these 2 forms:

fieldbase(field)

A simple "field" specification is always interpreted as "&PLBASE(field)", so thetwo forms look the same after this interpretation. Usually, we specify "base" asthe name of a DSECT, but this is not necessary. The parser macros simplygenerate a half-word offset:

DC AL2(field-base)

The base address to which this offset is added is the PLBASE= address or thematching BASES= entry as appropriate.HCPTKDEF saves in assembler variables (for use later by the HCPDOSYNmacro) the names of the DSECTs into which data are to be stored. For example,these example keywords:

ORFLAG=(SYSCM(SYSIPLFL),SYSAUTOW)STORE=SYSCM(SYSCKVOL)STORE=SCFMACH

would cause HCPTKDEF to remember the target locations asSYSCM(SYSIPLFL)SYSCM(SYSCKVOL)SCFMACH

Later, HCPDOSYN will look at each target location. HCPDOSYN first tries tomatch the target location to something in BASES=. It does this by separatingthe string into what appears to be a DSECT and a label (in these examples,SYSCM and SYSIPLFL; SYSCM and SYSCKVOL). If it cannot perform theseparation, then the target location must be in the primary plist (in thisexample, SCFMACH must be in the primary plist).After breaking apart the target location, HCPDOSYN searches for the apparentDSECT name in the BASES= list. If it does not find it, then the target locationmust be in the primary plist. The original target location string will be used. Ifit does find it, then it remembers which entry in BASES= satisfied the search.

CP Parser


Finally, HCPDOSYN generates the syntax control blocks, where it saves thenumber 'n' of the plist area ('n' = 0 for the primary plist, 'n' > for something inthe BASES= list) and the offset into that DSECT to the target location.A misspelled "base" will generate a very bizarre error. Consider:

HCPTKDEF ...,STORE=SYSCX(SYSIPLFL)HCPDOSYN ...,PLBASE=MYDSECT,BASES=(SYSCM)

The misspelled "SYSCX" means that "SYSCX" will not be found in BASES=.Therefore, it must be in the primary plist, MYDSECT. The offset that the parserwill generate will be:

DC AL2(SYSCX(SYSIPLFL)-MYDSECT)

This will not be right.

Example 1Example of the use of 2 separate HCPTKDEF macros to handle a keywordfollowed by a required variable compared to the use of a single HCPTKDEF macrowith both a keyword and TYPE= value specified.

This portion of syntax:

►► PIECEs decimal ►◄

could be represented by these parser macros.HCPSTDEF REQMATCH=YESHCPTKDEF ’PIECEs’HCPSTDEF REQMATCH=YESHCPTKDEF TYPE=DEC

The syntax could be represented more simply by these parser macros, whichcombine the 2 HCPTKDEF macros into 1.

HCPSTDEF REQMATCH=YESHCPTKDEF ’PIECEs’,TYPE=DEC

The advantage is a simpler and more compact set of parser macros.

CP Parser


HCPZPRPC — Parse Remainder of Command LineHCPZPRPC is called to parse a partial command contained in the GSDBKanchored at the VMDCFBUF field in the caller's VMDBK. The syntax descriptiondata area passed by the caller describes only the remainder of the command, soprocessing resumes where it left off (earlier parts of the command may have beenprocessed by the traditional method).

Input Registers:

R0 Address of the syntax structure (HCPSYNDF) created by a ROOT=YES invocationof the HCPDOSYN macro.

R1 Address of the primary output area, identified by the PLBASE operand on theHCPDOSYN macro, in which to return information.

R2 Address of the vector of addresses of areas specified on the BASES operand of theHCPDOSYN macro or zero if no BASES were specified.

R3 Address of the command or configuration file statement definition (HCPCFDEF)that defines the operands of the command or statement. If the address is:

0 (zero)tells CP to find the HCPCFDEF.

non-zerotells CP the location of the previously-found HCPCFDEF.

R11 Address of the VMDBK of command invoker (VMDCFBUF → GSDBK, parsingresumes at the offset denoted by GSDSCAN).

Output Registers — Normal:

R0 ZeroR15 Zero

Output Registers — Error:

R0 Error message number as a return code.R15

24 Error encountered paging in the syntax table

28 Syntax error encountered in command

32 Non-fatal error encountered by post-processor

36 Fatal error encountered by post-processor.

HCPZPRPC


HCPZPRPG — Parse Any GSDBKHCPZPRPG is called to parse an arbitrary General System Data Block (GSDBK).The syntax description data area passed by the caller describes the syntax of theremaining data in the GSDBK. Parsing continues in the GSDBK at the positionindicated by GSDSCAN. Parsing will continue only as far as any X'15' character.

Input Registers:

R0 Address of the syntax structure (HCPSYNDF) created by a ROOT=YES invocationof the HCPDOSYN macro.

R1 Address of the primary output area, identified by the PLBASE operand on theHCPDOSYN macro, in which to return information.

R2 Address of the vector of addresses of areas specified on the BASES operand of theHCPDOSYN macro or zero if no BASES were specified.

R3 Address of the command or configuration file statement definition (HCPCFDEF)that defines the operands of the command or statement. If the address is:

0 (zero)tells CP to find the CFDEF.

non-zerotells CP the location of the previously-found HCPCFDEF.

R4 address of the GSDBK to be parsed.


R0 ZeroR15 Zero


R0 Error message number as a return code.R15

24 Error encountered paging in the syntax table

28 Syntax error encountered in command

32 Non-fatal error encountered by post-processor

36 Fatal error encountered by post-processor.

Pre-Processing RoutinesIf you specify a routine on the PREPROC keyword of the HCPDOSYN macro, theparser calls that routine before parsing the command or statement. A pre-processorremoves record qualifiers from statements in the system configuration file before itprocesses the record.

Input Registers Passed to Pre-Processor Routines:

R0 Address of the CONWK area used by the parser. CONRECBF contains a pointer tothe string being processed, CONRECSZ contains the length of the string, andCONBSADR contains a pointer to the vector of addresses mapped by the BASESlist on the HCPDOSYN macro.

R1 Address of the primary output parameter list, identified by PLBASE parameter ofthe HCPDOSYN macro, provided by the routine that called the parser.

HCPZPRPG



R150 Statement may be processed

4 Statement should not be processed


R158 Error encountered in processing input string

Post-Processing RoutinesIf you specify a routine on the PROCESS parameter of the HCPCFDEF macro, theparser calls that routine after all processing for the command or statement hascompleted successfully.

Input Registers Passed to Post-Processor Routines:

R0 Address of the vector of addresses to areas specified on the BASES operand of theHCPDOSYN macro or zero if no BASES were specified.

R1 Address of the primary output plist provided by routine that called the parser(identified by PLBASE parameter of the HCPDOSYN macro).

R2 Address of the CONWK area used by the parser.R3 Value contained in the CONUWORD field of the CONWK area. This field is set as

the result of processing the UWORD= parameter on a HCPTKDEF macro.


R150 Statement processing completed successfully


R0 Message number (including version number) of error message to issue, or zero.R1 Parameter list to use when issuing the message (passed to HCPCONSL).R15

4 Error encountered in statement processing

8 Fatal error encountered in statement processing.

Pre-Processor


Post-Processor


Appendix G. Understanding the CP Message Repository

This appendix describes the format of the CP message repository file andidiosyncrasies related to rules and function of the repository routines.

Message Repository FileThe message repository can have any valid CMS file name. The convention for thefile name is xxxyyycc, where:

xxx is a component identifier (for example, HCP).

yyy usually refers to entry point identifier (for example, MES).

cc is a 1- or 2-character country code that identifies the language you areworking in. Country codes for supported languages are defined in theVMFNLS LANGLIST file. A country code is not used for AmericanEnglish.

The message repository can have any valid CMS file type not reserved for someother function. For a list of reserved CMS file types, see z/VM: CMS User's Guide.The convention is to use a file type of REPOS.

Your message repository must be a fixed-record format file with a maximumlogical record length (LRECL) of 80 and should contain the following items:v Comment recordsv A control linev Message records.

Commenting Your Message RepositoryYour message repository file should contain comment records. These must startwith an asterisk (*) in column 1:* This is an example of a comment line

Comment lines can go anywhere in a message repository file and should describewhat is in the file.

Creating a Control LineThe first non-comment record in your message repository must be a control line.The control line contains a single character in column 1 that defines the characteryou will be using for variable substitutions. For example, the control line of the CPmessage repository (HCPMES REPOS) is:$

This means that the dollar sign ($) is used throughout the CP message repositoryto define indicators that will be substituted with data when CP issues messages.


Creating Message RecordsEach message record in a CP message repository file contains a maximum of 5fields. When you create your file using XEDIT, the message records must be in thefollowing format:

NNNN is the message number, in columns 1 through 4. You must use a 4-digitdecimal message number in a CP message repository. The CP messagerepository uses message numbers 0001 through 9999.

Note: In a CP message repository, all message numbers must be insequential order. CMS (or CMS application) user repositories let you placemessages in any order.

VV is the message version, in columns 5 and 6. The message version is a2-digit decimal number from 01 through 99 that differentiates one versionof a message from any other versions of that same message. If a messageonly has one version, you can specify blanks in columns 5 and 6 and theversion field will default to “01”. You cannot use “00” as a version number.

LL is the line number of the message, in columns 7 and 8. Use this field todefine text for a single message that splits into more than one line. Youmust use a 2-digit decimal line number between 01 and 99. The first line ofthe message must be 01 and all other line numbers must be sequential andconsecutive (that is: 02, 03, 04, and so forth).

If the message has only one line, you do not need to specify a line number,because it defaults to 01 if omitted. You cannot use 00 as a line number.

S is the severity code, in column 9. Valid severity codes are:

Code Message Type

E Error

I Information

R Response

A Immediate action required

D Decision

W System Wait

You can define other severity codes by changing the letter in column 9. Werecommend that you continue to use the currently defined severities for CPmessages so that you do not confuse the users of the system.

text is the message text, starting in column 11. If your message repository willnot contain SID codes (support identification codes), you can specify amaximum of 61 characters of message text per line. If your message

===== .===== .===== .===== NNNNVVLLS ----------------------- text ---------------------------------

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...===== NNNNVVLLS ----------------------- text ----------------------- SID_CODE===== .===== .===== .

Figure 10. CP Message Record Format

CP Message Repository


repository does or will contain SID codes, you can specify a maximum of53 characters of message text per line. The next 8 characters are the SIDcode, which is described below.

If your message text is longer than 61 (or 53) characters, it will not fit onone physical line in the message repository. You must choose whether youwant the message to display as:

One line —specify the identical message number (NNNN), version (VV), and linenumber (LL) for each line.

Note: If your message text is very long, your message mightdisplay as one long continuous line wrapped around to the nextphysical line of the screen.

When creating a 1-line message (wrapped or not) from a multipleline definition, CP strips all but one of the trailing blanks from theend of the message text and concatenates the lines together. If youwant to create a message that displays more than one consecutiveblank space:v If you want more than one blank between two items, split the

items onto two lines. Insert as many blanks as you need beforethe item on the second line.

v If you want more than one blank between words or if you wantto maintain alignment of fields, you can use a substitutionvariable that will have a null or omitted value.

Multiple lines —specify the identical message number (NNNN) and version (VV), butspecify different line numbers (LL) for each line. The first linenumber must be 01, followed by 02, 03, and so forth.

SID_CODEis the support identification code, in columns 64 through 71. When youXEDIT a file and specify the SIDCODE string option, XEDIT inserts the8-character string in the first eight columns of the last 17 columns (logicalrecord length minus 16) of every line in the file that you add or change.Depending on the string that was chosen, the SID code can help youidentify who made the change, and possibly, when and why the changewas made.

Message repositories are fixed-record format files with a maximum logicalrecord length (LRECL) of 80. Thus, if you update a message repositorywith the SIDCODE string option, XEDIT inserts the SID code in columns 64through 71.

Message Repository IdiosyncrasiesThe following rules and conventions govern the use of message repositories.v Message numbers in the range of 7000 through 7999 are treated as responses and

are not displayed with a message header.v All trailing blanks but one are removed from a repository line when the message

is generated.v Trailing blanks in the substitution data are removed when non-column format is

used.v When column format is used:


Appendix G. Understanding the CP Message Repository 233

– The message in the repository must have a number of blanks following thesubstitution data symbol, '$nnn', such that the length of the symbol plus thenumber of blanks is equal to or greater than the maximum length of thesubstitution data.

– If the length of the substitution data is less than the length of the substitutionsymbol, '$nnn', blanks will be placed after the substitution data to make it thesame length as the '$nnn'.

v No message text associated with one line number may be longer than 229characters after the substitution indicators are replaced by the actual substitutiondata.

v In your module that builds the substitution data, the total length of thesubstitution data and field separators must be less than 2000 bytes.

v No more than 200 substitution elements may be passed for processing in a singlemessage.

Additional CP Message Repository IdiosyncrasiesCertain message numbers generated for COMPID=HCP cause special processingrelated to the Protected Application Environment to occur when they are invoked.This processing causes CP to extract data from the error message substitution datafor later use by Diagnose code X'0B0' so the application is protected from seeingthe message and entering the CP READ state. These messages include messagenumbers: 410, 450, 452, 453, 650, 657, 1459, 9300, and 9501. It is recommended thatinstallations refrain from adding or changing versions of these messages.



Appendix H. Updating the CP Load List

This appendix describes the CP load list and how you can update it to includeyour dynamically loaded modules. The CP load list is an ordered listing ofmodules in the CP nucleus. The HCPMDLAT (module attribute) macroinstructiondefines the location of a module in the CP nucleus and the linkage attributes ofthat module.

Traditionally, when you customized your z/VM system by adding new CPmodules, you provided source updates to HCPMDLAT that would include yourroutines as part of the CP nucleus. You can completely avoid modifications to theCP load list by coding your routines so that they are loaded dynamically. This isthe preferred technique from the standpoint of managing your local modifications.

However, there may be cases when you might still want to update the CP load list.For example, as part of an existing local modification, you may have a routinewhich you have not had a chance to modify so that it can be loaded dynamically.Or, perhaps some design consideration requires that you still place certain routineswithin the CP nucleus. In those instances, it is still possible to avoid sourcemodifications to the IBM supplied HCPMDLAT MACRO. This is accomplished byusing an alternate MDLAT MACRO. You will often see this referred to as anxxxMDLAT MACRO. The xxx represents an alternate component ID, that is, acomponent ID that you have selected for your routines.

The following is the basic steps that you need to do in order to add a user moduleto the CP nucleus using an Alternate MDLAT macro.1. Create the alternate MDLAT macro and place it in a maclib where GENCPBLS

will find it.2. Code the user module.3. Use GENCPBLS to generate the new CP load list.4. Use VMFBLD to generate the CP nucleus.

General Rules for Coding an Alternate MDLAT MacroYou use 3 macros (MDLATHDR, MDLATENT, MDLATTLR) to create an alternateMDLAT macro. The alternate MDLAT macro contains a single header macro(MDLATHDR) at the beginning and it contains a single trailer macro (MDLATTRL)at the end. In between these, code as many MDLATENT macros as you require todefine your modules. The syntax for these macros is described in Appendix E, “CPExit Macros,” on page 191.

The alternate MDLAT macro can be used to identify the location of your module inthe CP nucleus. Each section of the CP nucleus is identified by a memory markerthat has the generic format HCPMMn. For example, the memory marker for thestart of the resident MP section of the CP nucleus is HCPMM1. Your modules areplaced in the right section of the load list based on the HCPMMn memory markerthat they follow in your alternate MDLAT MACRO. For information about thedifferent sections of the CP nucleus and the name of the associated memorymarker, refer to the documentation contained in the HCPMDLAT MACRO.


The alternate MDLAT macro also identifies the linkage attributes for your module.This information is used by the standard CP linkage macros (for example,HCPCALL or HCPENTER) in order to generate the correct assembler instructionsto accomplish the linkage.

When you create an alternate MDLAT macro, keep the following general rules inmind:v Your modules are placed in the right section of the load list based on the

HCPMMn memory marker that they follow in your alternate MDLAT MACRO.The exact placement within that section is not predictable.

v There is no default section in the CP load list where modules will be added.That means you must specify at least one HCPMMn memory marker if youralternate MDLAT macro defines any modules that you expect to be placed in theCP load list.

v If your module will be dynamically loaded, you specify CPXLOAD=YES on theMDLATENT macro so that it will not be added to the CP load list. If all yourmodule entries in the alternate MDLAT macro are defined as dynamicallyloaded, then you do not have to specify any HCPMMn memory marker.

v It is not necessary to specify all the memory markers. Only use the ones thatyou need in order to specify the section of the load list in which you wish toplace your modules.

v The order of the HCPMMn entries in your alternate MDLAT MACRO is notsignificant. Your modules will be placed in the right section of the load listbased on the HCPMMn memory marker that they follow in your alternateMDLAT MACRO.

v Multiple occurrences of a specific HCPMMn memory marker are allowed.

Creating an Alternate MDLAT MacroUse the XEDIT command to create an xxxMDLAT MACRO file. The format of thefile must conform to the requirements of a program written in assembler macrolanguage as defined in HLASM MVS & VM Language Reference.

Figure 1 shows an example of an alternate MDLAT macro called ABCMDLATMACRO. This alternate MDLAT macro defines five new modules, four of whichare to be included in the CP nucleus and one which is expected to be loadeddynamically.

Updating the CP Load List


A brief explanation of the significant lines in this alternate MDLAT MACRO filefollows.v The following statements should be coded exactly as shown:

– Line 1 - Macro definition header statement– Line 4 - MDLATHDR macro

This macro does some actions necessary to initialize for processing of thesubsequent MDLATENT macros.

– Line 22 - MDLATTLR macroThis macro does some actions necessary to complete the definition of thealternate MDLAT macro.

– Line 24 - MEXIT instruction– Line 25 - Macro definition trailer statement

v Lines 3, 5, 9, 12, 17, 21, and 23These are internal macro comment statements. They are used to improve thereadability of the macro.

v Line 2This is the macro instruction prototype statement. This statement assigns thename ABCMDLAT to the macro. It also declares &EPNAME as a parameter. Thisparameter is passed without modification to the MDLATHDR macro.

v Lines 6, 7 and 8

+-------------------------------------------------------------------------------+| ABCMDLAT MACRO A1 F 80 Trunc=72 Size=23 Line=8 Col=1 Alt=1 || || |...+....1....+....2....+....3....+....4....+....5....+....6....+....7.> || 0 * * * Top of File * * * || 1 MACRO || 2 &LABEL ABCMDLAT &EPNAME || 3 .* || 4 &LABEL MDLATHDR &EPNAME || 5 .* || 6 MDLATENT HCPMM1,MODATTR=(MP,DYN) || 7 MDLATENT ABCTST,MODATTR=(MP,DYN), * || 8 EP=((ABCTSTEP,STAT)) || 9 .* || 10 MDLATENT HCPMM5,MODATTR=(MP,DYN) || 11 MDLATENT ABCMOD,MODATTR=(MP,DYN) || 12 .* || 13 MDLATENT HCPMM1,MODATTR=(MP,DYN) || 14 MDLATENT ABCKLM,MODATTR=(MP,DYN), * || 15 EP=((ABCKLMST,STAT)) || 16 MDLATENT ABCIJK,MODATTR=(MP,DYN) || 17 .* || 18 MDLATENT ABCCMD,MODATTR=(MP,DYN),CPXLOAD=YES || 19 MDLATENT ABCSRV,MODATTR=(MP,DYN,TMAR), * || 20 EP=((ABCSRVXX,AM64E,LREGE)),CPXLOAD=YES || 21 .* || 22 MDLATTLR || 23 .* || 24 MEXIT || 25 MEND || 26 * * * End of File * * * || |+-------------------------------------------------------------------------------+

Figure 11. ABCMDLAT Macro


Appendix H. Updating the CP Load List 237

These two MDLATENT macros will add your new module ABCTST to the MPnucleus section that starts with the HCPMM1 memory marker. All the entrypoints in ABCTST will use CP dynamic linkage except for ABCTSTEP, whichwill use CP static linkage.

v Lines 10 and 11These two MDLATENT macros will add your new module ABCMOD to thenon-MP nucleus section that starts with the HCPMM5 memory marker. All theentry points in ABCMOD will use CP dynamic linkage.

v Lines 13 through 16These three MDLATENT macros define the user modules ABCKLM and ABCIJKto the MP nucleus section that starts with the HCPMM1 memory marker. Theselines illustrate several points. You are allowed to have multiple occurrences ofthe same HCPMMn memory marker. In addition, you do not have to ensure thatthese memory markers are in any numeric order. Also, you can have multiplemodules defined after one HCPMMn memory marker.

v Lines 18This MDLATENT macro defines the module ABCCMD, which will not be addedto the CP load list. The CPXLOAD=YES operand indicates that the CPCPXLOAD command or configuration file statement will be used to load theroutine dynamically so CP can use it.

v Lines 19 and 20This MDLATENT macro defines the module ABCSRV, which will not be addedto the CP load list. The CPXLOAD=YES operand indicates that the CPCPXLOAD command or configuration file statement will be used to load theroutine dynamically so CP can use it. The module will always execute in AccessRegister mode. The module will always be entered in 32-bit addressing mode,except for entry point ABCSRVXX, which will be entered in 64-bit addressingmode.

v Lines 18 through 20The scenario we envision here is that ABCCMD is going to handle some new CPcommand. Also, we plan to load ABCCMD and ABCSRV with CPXLOAD sothat they can call each other directly. When the new CP command is executed,ABCCMD will be called TYPE=INDIRECT (because it was dynamically loaded),so its entry point must be DYN AM31 SREG. ABCCMD may, however, callABCSRV entry points even though they are defined with broader attributes.These calls must be TYPE=DIRECT, and they could even be deferred (by usingHCPSTK).

Coding the User ModuleThe first thing that you will need to do is decide the name of the user module.Refer to “How Should the Routine be Named?” on page 33 and follow its advice.For example, let's suppose you choose the name 'ABCMOD' and it has an entrypoint called 'ABCMODEP'.

When you write the code for your module, be sure to include an invocation of theHCPCMPID macro in order to define the component ID of your module. Thecomponent ID will be used during assembly of your module to resolve the systemlinkage to your entry points in your module. It tells the assembler which alternateMDLAT macros to look in to find the attributes of your module. In our example,you would code a 'HCPCMPID COMPID=(ABC)' in the beginning of your module.



You also need to code a HCPCMPID macro in the module that you updated to callyour module. For example, if you updated HCPNOS to call entry pointABCMODEP in your module, you will need to code a 'HCPCMPIDCOMPID=(ABC)' in HCPNOS so that HCPCALL will generate the correct linkage.

Generating a New CP Load ListOnce you have created your alternate MDLAT file and specified each module thatyou want to define in the CP nucleus you use the VMSES/E command,GENCPBLS, to create the CP loadlist. For more information on the GENCPBLScommand, see z/VM: VMSES/E Introduction and Reference. There is also a section inz/VM: Service Guide that shows how to use the GENCPBLS command.

It is important to note that your alternate MDLAT macro (xxxMDLAT) must be ina maclib specified on the MACS statement of the control file that is used by theGENCPBLS command in order to be found. You may update an existing maclib toaccomplish this. You may also create your own maclib and update the control fileso that it includes your maclib name.

If your alternate MDLAT contains only modules that will be dynamically loaded,then there is no need to generate a new CP load list.


Appendix H. Updating the CP Load List 239

Appendix I. Samples of Dynamically Loaded Routines

This appendix discusses the sample CP exit routines that are shipped on the CPtools disk (usually MAINT 193). We are providing these sample CP exit routinesfor the following reasons:

You can try out the CP Exit support without first having to write your owndynamically loaded CP routines.The functions provided by these samples are functions that most users of theCP Exit support would find useful.When you do write your own dynamically loaded CP routines, you havesamples of typical code to use as a pattern. For example, if you needed to use acomponent ID block (CMPBK), you could see how the samples perform thattask and modify the code to meet your installation's needs.

Important Note

The CP exit routines mentioned in this appendix are to be used only as samples.Although the samples may have been reviewed by IBM for accuracy in a specificenvironment, there is no guarantee that the same or similar results will be obtainedelsewhere. The sample CP exit routines are being provided on an “as is” basiswithout any warranty expressed or implied.

The samples shipped on the CP tools disk are:1. XDISPL SAMPASM — a sample exit routine that can be used for debugging.

The entry points provided in this sample are designed to display CP exit pointentry information (CP exit number, register contents, parameter list entries, andso forth).You can use one of the routines in this module to display “before and after”values. For example, suppose you wrote a dynamically loaded CP routine,XYZ. You could issue this ASSOCIATE EXIT command (or configuration filestatement):

associate exit 1200 enable epname xdispldt xyz xdispldt

Then, when CP Exit 1200 is called, you will see the parameter list as it wasinitialized by HCPDIA and after it was changed by your entry point XYZ. Thiscan be helpful when you are trying to understand what XYZ is doing.

2. VREPOS SAMPASM — a sample command handler that takes the messagesor responses that you specify and displays them at the console with thespecified substitution data. That is, you can use this routine to verify the formatof any message in a message repository. So, you could dynamically define acommand (for example, CPXMITMSG) and then use that new command toverify the format of a message in the CP message repository (HCPMES REPOS)or in one of your local message repositories.

3. JAFEXS SAMPASM — a sample that shows the syntax definition andpost-processor routine for an EXTERNAL_SYNTAX example.

4. JAMSAMA SAMPASM — a sample routine for CP Exit 1200.5. JAMSAMB SAMPASM — another (more complex) sample routine for CP Exit

1200.


The rest of this appendix is devoted to listing and explaining the two sample CPexit routines for CP Exit 1200, which allow you to examine and, optionally, changeor reject the operands specified on the CP DIAL command. These samples arepractical examples that you can use as a basis for exploiting CP exit routines onyour z/VM system.

For each sample, there is an assembler language listing with comments discussingcertain statements of interest. In general, the assembler language listings do notshow macroinstruction expansions or copy files. However, there are a fewinteresting exceptions.

The second example is more complex than the first sample. So, in addition to theannotated assembler language listing, there is also a local message repository (withcomments) and a control data file.

What You Should Gain from the Sample CP Exit 1200 RoutinesAfter reviewing (and perhaps even using) these two sample CP exit routines, wehope that you:v Recognize how powerful the CP Exits support isv Feel comfortable using the CP Exits supportv Realize that CP exit routines are easy to writev Have acquired a few new skills, such as:

– Manipulating a component identification block (CMPBK) — your own privateextension to the system common area (SYSCM)

– Reading a CMS file– Calling a CP exit point– Controlling a CP exit point– Using the CP parser– Using your own local message repository.

Understanding CP Exit 1200CP Exit 1200 allows you to examine and, optionally, change or reject anyinformation provided for the CP DIAL command. This information includes the:

Command entered by the user —This would be 'DIAL', unless your system has defined a new command oran alias that also called the HCPDIAL module. Whatever the user entered(command or alias) is passed on to the CP exit routine.

Target user ID —For example, suppose the user entered 'DIAL PVM', but you would ratherhave the target user ID virtual machine be 'PVMTEST'. Using CP Exit 1200,you can change the target user ID from 'PVM' to 'PVMTEST'.

If the user did not specify a target user ID, your CP exit routine can supplyit. If the user did not specify a target user ID and your CP exit routinedoes not specify one, the command will fail because DIAL needs toconnect to a target user ID.

Virtual device number of the target user ID —For example, suppose the user entered 'DIAL PVM 120', but you wouldrather have the target virtual device be '220'. Using CP Exit 1200, you canchange the target virtual device from '120' to '220'.

Sample Routines


Or, suppose you wanted to delete the target virtual device and pretendthat none was specified. Your CP exit routine can do this by changing thetarget virtual device number from '120' to '-1', which is a special value thatindicates that no specific virtual device number was specified.

If the user did not specify a target virtual device, your CP exit routine cansupply it. If the user did not specify a target virtual device number andyour CP exit routine does not specify one, CP will search for an availablevirtual device number to use, within some range of virtual devicenumbers.

Range of virtual device numbers —If the target virtual device number ends up being '-1' (either because theuser did not specify it or because CP Exit 1200 changed it), CP will restrictthe search for an available virtual device to the specified range. The defaultrange is X'0000' through X'FFFF'.

If the target virtual device number was specifically determined (eitherbecause the user specified it or because CP Exit 1200 changed it), CP willignore the specified range.

Understanding the Sample CP Exit 1200 RoutinesThese sample CP exit routines allow you to customize the processing of the CPDIAL command. To customize the DIAL processing, these samples actuallycustomize the control data supplied by the user (command name, target user ID,target virtual device number or range). To accomplish this, the samples use a tablethat associates the user-specified command name with the information to bereturned to the DIAL processor.

Sample 1The first sample CP exit routine (page Table 12 on page 247) defines the tableentries in a control section (CSECT) during assembly. Specifically, Sample 1 can bedescribed as a table lookup subroutine:v Validate the input (specifically, the CP exit number)v Search the table for the incoming command name or target user ID

– If found, return these values:- Target user ID- Target virtual device number- Start of virtual device range- End of virtual device range

v Exit.

Sample 2The second sample CP exit routine (page Table 13 on page 265) defines the table ina CMS file and reads that file into the system execution space. Specifically, Sample2 can be described as a more complicated table lookup subroutine than Sample 1:v Validate the input (specifically, the CP exit number)v Check to see if CP Exit F200 (our local CP exit routine) is enabled

If enabled, then call it to load the CMS file into the system execution spacev Locate our component ID block (CMPBK)v Acquire a shared lock on the CMPBKv Search the table for the incoming command name or target user ID

Sample Routines

Appendix I. Samples of Dynamically Loaded Routines 243

– If found, return these values:- Target user ID- Target virtual device number- Start of virtual device range- End of virtual device range

v Relinquish the CMPBK lockv Exit.

The second sample calls local CP Exit F200, which loads a CMS source file into thesystem execution space:v Validate the input (specifically, the CP exit number)v Locate the component ID block (CMPBK) for component ID 'JAM'

– If found, then acquire a shared lock on the CMPBK– If not found, then:

- Allocate a new CMPBK- Acquire a shared lock on the new CMPBK

v Check to see if CP Exit F200 is disabledIf disabled, then exit

v Disable CP Exit F200v Get a CP data request block (DRBK) for reading the table in the CMS filev Get a general system data block (GSDBK) for parsingv Interconnect the DRBK and the GSDBKv Open the DRBK

– If the open fails, then exit– If the open succeeds, then do until end of file:

- Read the next recordIf the record is sparse, all blanks, or a comment, then go back to readingthe next record

- Get a new JAMTABLE- Call the CP parserv If the call fails:

– Generate an error message– Go back to reading the next record

- Add the JAMTABLE to the new chain- If EOF, end

v Close the filev Release the DRBK, GSDBK, and the unused JAMTABLE

– If we had no errors, then:- Swap the new chain of JAMTABLEs for the old chain- Release the old JAMTABLEs

– If we had errors, then release the new JAMTABLEsv Exit.

Why Sample 2 Is Better Than Sample 1Sample 1 is simple and straightforward to understand, but because the table iscreated during assembly, it is also rigid and difficult to change after assembly.

Sample Routines


Sample 2 is more complicated, but much more flexible. You can reload the table atany time using a simple system operator command:

enable exit f200

Without local CP Exit F200, Sample 2 would need a way to indicate that the tableneeded to be reloaded. To do this, the alternatives would be to create a new:v CP commandv User Diagnose code

Using the Sample CP Exit 1200 RoutinesIf you decide to use one of the sample CP exit routines listed in this appendix, youmust load the files into the system execution space, assign one or more entrypoints, and enable CP Exit 1200. To accomplish this, you would enter the followingcommands:

To Use Sample 1:

1. Load the sample (JAMSAM) into the system execution space using the following CPcommand or system configuration file statement:

cpxload jamsam text temporary nocontrol

2. Assign entry point JAMSAMDL to CP Exit 1200 and enable CP Exit 1200 using thefollowing CP command or system configuration file statement:

associate exit 1200 enable epname jamsamdl

See Table 12 on page 247.

To Use Sample 2:

1. Load the sample (JAMSAM) into the system execution space using the following CPcommand or system configuration file statement:

cpxload jamsam text temporary nocontrol

2. Assign entry point JAMSAMDL to CP Exit 1200 and enable CP Exit 1200 using thefollowing CP command or system configuration file statement:

associate exit 1200 enable epname jamsamdl

3. Assign entry point JAMSAMLD to CP Exit F200 and enable CP Exit F200 using thefollowing CP command or system configuration file statement:

associate exit f200 enable epname jamsamld

See Table 13 on page 265, Table 14 on page 309, and “A Sample JAMTABLE SOURCE File”on page 310.

Potential ImprovementsAs an exercise to get used to creating your own CP exit routines, you could makeimprovements to the second sample CP exit routine in this appendix. For example,you might want to add code to Sample 2 that would:v Notify the system operator when CP Exit F200 succeedsv Give the system operator a heading regarding the error messagesv Call search routines using BAS rather than HCPLCALLv Change the structure of JAMTABLE. Currently, you cannot change the structure

of JAMTABLE without careful and judicious use of the following:– Creating a new module– Using the CPXLOAD statement

Sample Routines


– Using the ASSOCIATE EXIT statement– And so forth

Sample Routines


Tabl

e12

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

1 fo

r C

P E

xit

1200

Ass

emb

ler

Sou

rce

Com

men

tary

12MA

CRO

0120

0001

13&L

ABEL

JAMM

DLAT

&EPN

AME

0130

0001

14MD

LATH

DR&E

PNAM

E01

4000

0115

MDLA

TENT

JAMS

AM,M

ODAT

TR=(

MP,D

YN),

X015

0000

1CP

XLOA

D=YE

S01

6000

0116

MDLA

TTLR

0170

0001

17ME

ND01

8000

01

Lin

e ▌1

2▐: T

his

mac

ro, J

AM

MD

LA

T, d

escr

ibes

the

mod

ules

and

ent

ry p

oint

s fo

r co

mpo

nent

ID

JA

M.

Thi

s m

acro

can

be

incl

uded

inl

ine,

as

show

n he

re, o

rin

a M

AC

LIB

tha

t is

pro

cess

ed b

y th

e co

mpi

ler.

The

HC

PCM

PID

mac

ro, i

nvok

ed o

n lin

e 19

, ad

ds

JAM

to

the

com

pone

nt I

Ds

for

this

com

pile

.

Sample Routines


Tabl

e12

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

1 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

19HC

PCMP

IDCO

MPID

=JAM

0200

0001

20CO

PYHC

POPT

NS02

1000

01

Lin

e ▌1

9▐: H

CPC

MPI

D i

s a

mac

roin

stru

ctio

n w

hose

purp

ose

is t

o sp

ecif

y yo

ur c

ompo

nent

ID

ent

ries

. CP

uses

the

com

pone

nt I

D e

ntri

es t

o id

enti

fy y

our

xxxM

DL

AT

mac

roin

stru

ctio

ns, w

hich

CP

uses

to

assi

gn l

inka

ge a

ttri

bute

s. C

ompo

nent

ID

ent

ries

are

3-ch

arac

ter

stri

ngs.

For

exa

mpl

e, I

BM

's c

ompo

nent

ID

for

CP

is 'H

CP'

.

Com

pone

nt I

D e

ntri

es c

an a

lso

be u

sed

on

HC

PCO

NSL

MA

CR

Os,

whi

ch w

ould

con

nect

the

HC

PCO

NSL

MA

CR

O w

ith

asso

ciat

ed m

essa

gere

posi

tori

es (

see

the

CP

ASS

OC

IAT

E M

ESS

AG

Eco

mm

and

for

mor

e in

form

atio

n). H

CPC

MPI

D m

aybe

spe

cifi

ed m

ulti

ple

tim

es, a

nd w

ith

mul

tipl

eco

mpo

nent

ID

ent

ries

. For

exa

mpl

e:

HCPC

MPID

COMP

ID=(

JAM,

JAM,

XYZ)

HCPC

MPID

COMP

ID=I

JK

The

HC

PCM

PID

MA

CR

O i

s ti

ed t

o th

e su

ppor

t fo

rm

ulti

ple

HC

PMD

LA

T M

AC

RO

s, e

ach

know

n as

xxxM

DL

AT.

The

'xxx

' let

ters

rep

rese

nt t

he c

ompo

nent

ID e

ntri

es s

peci

fied

in

your

HC

PCM

PID

MA

CR

Os.

Bas

ed o

n th

e H

CPC

MPI

D M

AC

RO

s sh

own

abov

e,th

e xx

xMD

LA

T M

AC

RO

s th

at H

CPC

AL

L w

ould

use

are:

HCPM

DLAT

MACR

Oal

ways

chec

kedfi

rst

JAMM

DLAT

MACR

OJA

MMDL

ATMA

CRO

XYZM

DLAT

MACR

OIJ

KMDL

ATMA

CRO

JAM

MD

LA

T i

s sh

own

twic

e be

caus

e JA

M i

ssp

ecif

ied

tw

ice

in t

he H

CPC

MPI

D M

AC

RO

s.

HC

PCA

LL

and

oth

er M

AC

RO

s ca

ll yo

ur x

xxM

DL

AT

MA

CR

O l

ooki

ng f

or t

he a

ttri

bute

s of

the

mod

ule

inor

der

to

know

the

pro

per

linka

ge t

o ge

nera

te.

HC

PCA

LL

will

cal

l yo

ur x

xxM

DL

AT

MA

CR

Os

in t

heor

der

tha

t yo

ur c

ompo

nent

ID

ent

ries

are

spe

cifi

edon

the

HC

PCM

PID

MA

CR

Os.

Sample Routines


Tabl

e12

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

1 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

Lin

e ▌1

9▐(c

onti

nued

): T

he f

orm

at o

f yo

urxx

xMD

LA

T M

AC

RO

s is

sim

ilar

to t

he f

orm

at o

f th

eH

CPM

DL

AT

MA

CR

O. H

ere

is o

ur J

AM

MD

LA

TM

AC

RO

, als

o sh

own

in t

he l

isti

ng a

t lin

e 12

:

MACR

O&L

ABEL

JAMM

DLAT

&EPN

AME

MDLA

THDR

&EPN

AME

MDLA

TENT

JAMS

AM,M

ODAT

TR=(

MP,D

YN),

XCP

XLOA

D=YE

SMD

LATT

LRME

ND

You

use

the

MD

LA

TE

NT

MA

CR

O t

o sp

ecif

y th

eat

trib

utes

of

your

mod

ule

usin

g th

e sa

me

keyw

ord

sas

you

use

d i

n H

CPM

DL

AT.

For

a t

ypic

al m

odul

e,w

hat

you

see

here

is

all

that

you

wou

ld n

eed

. Onl

y if

your

mod

ule

has

spec

ial

attr

ibut

es b

eyon

d t

hese

wou

ld y

ou i

nves

tiga

te o

ther

MD

LA

TE

NT

key

wor

ds.

Att

rib

ute

Mea

nin

g

MP

Mul

tipr

oces

sor

capa

ble.

Thi

s m

eans

tha

tta

sks

on d

iffe

rent

pro

cess

ors

may

run

thi

sm

odul

e si

mul

tane

ousl

y.

DY

NU

ses

a d

ynam

ic s

avea

rea

(SA

VB

K).

Att

ribu

tes,

spe

cifi

cally

MP

or N

ON

MP

, spe

cifi

edhe

re m

ust

mat

ch t

he a

ttri

bute

s sp

ecif

ied

by

CPX

LO

AD

.

347JA

MSAM

HCPP

ROLG

ATTR

=(RE

SIDE

NT,R

EENT

ERAB

LE),

X023

0000

1CO

PYR=

(199

5,20

05),

COPY

RID=

’My

Copy

righ

t’,

X024

0000

1BA

SE=(

R12)

0260

0001

Lin

e ▌3

47▐:

The

key

wor

d 'C

OPY

RID

=' i

s us

ed o

nly

ifth

e ke

ywor

d 'C

OPY

R=

' is

spec

ifie

d. T

he s

trin

gas

sign

ed t

o 'C

OPY

RID

=' w

ill b

e as

sem

bled

as

ach

arac

ter

cons

tant

in

plac

e of

the

IB

M c

opyr

ight

noti

ce.

0000

0000

000

0021

848

0+JA

MSAM

CSEC

T,

&VX1

NOZW

01-H

CPPR

0000

0048

1+HC

P@MO

DDS

0D@V

X1NO

ZW01

-HCP

PR00

0000

00E5

482+

DCAL

2(C’

V’)

Bogu

sin

stru

ctio

nto

prev

entfa

ll-t

hru

@VRG

B1QY

01-H

CPPR

0000

02E5

E548

3+DC

C’VV

’Fo

rHC

PENT

ERen

forc

emen

tch

arac

ters

@VRG

B1QY

01-H

CPPR

0000

0400

0000

0048

4+DC

A(0)

Noca

ll-

orgo

to-b

y-re

gist

erve

ctor

@VRG

B1QY

01-H

CPPR

0000

0800

0000

0048

5+DC

A(0)

For

PLX,

bran

char

ound

prol

ogue

@VRG

B1QY

X01-

HCPP

R+

For

ASM,

spac

er@V

RGB1

QY

Lin

es ▌48

2-48

5▐: H

ere

you

see

"bog

us i

nstr

ucti

on",

enfo

rcem

ent

char

acte

rs, a

dd

ress

of

vect

or, a

nd s

o on

.T

hese

fie

lds

mir

ror

fiel

ds

gene

rate

d b

y H

CPE

NT

ER

to s

uppo

rt c

all-

by-r

egis

ter

and

got

o-by

-reg

iste

r. N

one

of t

hese

dat

a fi

eld

s ar

e ex

ecut

able

ins

truc

tion

s, s

oex

ecut

ion

cann

ot f

all

thro

ugh

into

any

HC

PEN

TE

Rm

acro

, whi

ch i

s w

hy t

here

is

a "b

ogus

ins

truc

tion

".

Sample Routines


Tabl

e12

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

1 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

0000

0C91

8194

A281

9440

4048

6+DC

CL8’

jams

am’,

AL2(

(HCP

@END

-HCP

@MOD

)/8)

@VR4

GCZW

01-H

CPPR

0000

16C5

D4C5

F2F0

F500

0048

7+DC

CL6’

EME2

05’,

XL2’

0000

’@A

0002

FA01

-HCP

PR00

001E

F0F7

61F2

F961

F0F5

488+

DCCL

8’07

/29/

05’

@A00

02FA

01-H

CPPR

0000

267A

F1F0

4BF4

F5D9

C548

9+DC

CL6’

:10.

45’,

CL1’

R’,C

L1’E’

@A00

02FA

01-H

CPPR

Lin

e ▌4

86▐:

The

mod

ule

nam

e is

sav

ed i

n lo

wer

cas

ew

hene

ver

it d

oes

not

star

t w

ith

'HC

P'. S

ervi

ces

in C

Pm

ay u

se t

his

valu

e as

sto

red

her

e (T

RA

CE

inst

ruct

ions

for

HC

PCA

LL

/H

CPE

XIT

lin

kage

) or

may

con

vert

it

to u

pper

cas

e (H

CPC

ON

SL w

hen

build

ing

erro

r m

essa

ge h

ead

ers)

. Thi

s is

just

ano

ther

pecu

liari

ty t

hat

you

shou

ld b

e aw

are

of.

0000

2ED4

A840

C396

97A8

9949

0+DC

C’My

Copy

righ

t’@V

R5HI

QY01

-HCP

PR00

003A

F1F9

F9F5

491+

DCCL

4’19

95’

@V80

GNU2

01-H

CPPR

0000

3E6B

492+

DCCL

1’,’

@V80

GNU2

01-H

CPPR

0000

3FF2

F0F0

F449

3+DC

CL4’

2005

’@V

80GN

U201

-HCP

PR00

0048

494+

HCP@

0002

DS0D

LABE

LFO

RBR

ANCH

AROU

NDPR

OLG

@P68

39ZW

01-H

CPPR

Lin

es ▌49

0-49

3▐: Y

ou c

an u

se t

he 'C

OPY

R=

' and

'CO

PYR

ID=

' key

wor

ds

to i

nser

t yo

ur o

wn

copy

righ

tin

form

atio

n in

to t

he e

xpan

sion

of

the

HC

PPR

OL

Gm

acro

. Not

ice

that

bot

h ke

ywor

ds

mus

t be

spe

cifi

ed,

or e

lse

your

cop

yrig

ht i

nfor

mat

ion

will

not

be

gene

rate

d.

0000

4800

048

0021

857

1+HC

PDAT

AALO

CTR

,@Y

0656

QY02

-HCP

DA00

0060

0006

000

218

573+

HCPC

ODEA

LOCT

R,

@Y06

56QY

02-H

CPDA

Lin

es ▌57

1-57

3▐: L

OC

TR

ins

truc

tion

s ar

e us

ed t

opl

ace

dat

a ea

rly

in t

he m

odul

e (i

n th

is e

xam

ple,

dat

ast

arts

at

offs

et 0

x000

048)

fol

low

ed b

y ex

ecut

able

cod

e(i

n th

is e

xam

ple,

cod

e st

arts

at

offs

et 0

x000

060)

.C

erta

in m

acro

s w

ill g

ener

ate

LO

CT

R i

nstr

ucti

ons

inor

der

to

add

the

ir d

ata

to t

hese

sec

tion

s. S

o yo

u m

ayfi

nd i

nstr

ucti

ons

that

are

seq

uent

ial

in t

he l

isti

ng b

utar

e no

t se

quen

tial

in

mem

ory.

The

re w

ill b

e m

ore

exam

ples

of

this

in

Sam

ple

Exi

t R

outi

ne 2

.

575

PRIN

TON

,NOG

EN02

7000

01

577

COPY

HCPE

QUAT

-Ge

nera

leq

uate

s02

9000

01

3455

COPY

HCPE

QXIT

-Eq

uate

sfo

rEx

itco

ntro

l03

0000

01L

ine ▌3

455▐

: HC

PEQ

XIT

is

a go

od p

lace

to

look

for

exit

equ

ates

. Exi

t eq

uate

s sh

ould

all

be o

f th

e fo

rm:

XIT

@xx

xx E

QU

X'x

xxx'

. As

alw

ays,

we

sugg

est

that

you

do

not

add

you

r ex

it n

umbe

r eq

uate

s to

thi

sIB

M C

OPY

file

. Ad

d t

hem

to

your

ow

n C

OPY

file

inst

ead

. IB

M-d

efin

ed C

P ex

it r

outi

nes

shou

ld h

ave

equa

tes

of t

his

form

in

the

HC

PEQ

XIT

CO

PY f

ile.

The

int

ent

is t

hat

ever

y ex

it p

oint

sho

uld

be

liste

dhe

re, s

o th

at w

e ca

n te

ll w

hat

has

been

use

d, w

ith

asm

all

amou

nt o

f in

form

atio

n ab

out

wha

t it

is

for.

The

two

exit

s in

DIA

L p

roce

ssin

g ar

e as

sign

ed t

hese

CP

exit

num

bers

:

XIT@

1200

EQU

X’12

00’

Comm

and:

DIAL

*Va

lida

teop

eran

dspa

ssed

*on

the

DIAL

comm

and

* XIT@

1201

EQU

X’12

01’

Comm

and:

DIAL

*Se

cond

chan

ce,af

ter

*ta

rget

has

been

deci

ded.

Sample Routines


Tabl

e12

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

1 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

3616

COPY

HCPP

FXPG

-Ho

stPr

efix

Page

0310

0001

6589

COPY

HCPP

LXIT

-PL

IST

defi

niti

ons

for

IBM

Exit

Poin

ts03

2000

0100

0000

X120

0DS

ECT

,Th

ePL

IST

poin

ters

for

exit

1200

7050

0210

*Re

adal

lco

mmen

tshe

reas

if71

0002

10*

they

allbe

gin

"Add

ress

of"

7150

0210

0000

00DS

A1

Rese

rved

7200

0210

0000

04X1

200U

WDDS

A2

User

word

s72

5002

1000

0008

X120

0TRT

DSA

3TR

T25

6by

tes

7300

0210

0000

0CX1

200C

MDDS

A4

Comm

andna

me73

5002

1000

0010

X120

0UID

DSA

5Ta

rget

user

id74

0002

1000

0014

X120

0VDN

DSA

6Ta

rget

VDEV

numb

er74

5002

1000

0018

X120

0VDS

DSA

7VD

EVnu

mber

star

tse

arch

rang

e75

0002

1000

001C

X120

0VDE

DSA

8VD

EVnu

mber

end

sear

chra

nge

7550

0210

0000

20X1

200R

DVDS

A9

RDEV

7600

0210

6975

COPY

HCPS

AVBK

-Sa

vear

eaBl

ock

0330

0001

7342

COPY

HCPV

MDBK

-Vi

rtua

lMa

chin

eDe

fini

tion

Bloc

k03

4000

01

1160

5HC

PUSI

NGPF

XPG,

R003

6000

0111

608

HCPU

SING

VMDB

K,R1

103

7000

0111

611

HCPU

SING

SAVB

K,R1

303

8000

01

Lin

e ▌6

589▐

: HC

PPL

XIT

is

the

plac

e to

loo

k fo

r pl

ist

def

init

ions

for

IB

M-d

efin

ed C

P ex

it p

oint

s. A

sal

way

s, w

e su

gges

t th

at y

ou d

o no

t ad

d y

our

exit

plis

t d

efin

itio

ns t

o th

is I

BM

CO

PY f

ile. A

dd

the

m t

oyo

ur o

wn

CO

PY f

ile i

nste

ad. E

very

exi

t pl

ist

shou

ldbe

of

the

form

:

Xxxx

xDS

ECT

,DS

ARe

serv

edXx

xxxU

WDDS

AAd

dres

sof

32by

tes

ofus

er..

.wo

rds

doub

lewo

rdal

igne

d..

.in

itia

lize

dto

bina

ry..

.ze

ros

Xxxx

xTRT

DSA

Addr

ess

of25

6by

tes

...

doub

lewo

rdal

igne

d..

.in

itia

lize

dto

bina

ry..

.ze

ros

Xxxx

x...

DSA

Addr

ess

ofa

data

item

Xxxx

x...

DSA

Addr

ess

ofa

data

item

Stor

age

for

the

plis

t is

allo

cate

d i

n th

e m

ainl

ine

rout

ine

for

each

ins

tanc

e of

cal

ling

an e

xit.

The

plis

tan

d w

hat

it p

oint

s to

are

unt

ouch

ed b

y th

e ex

itco

ntro

l ro

utin

es. E

ach

exit

rou

tine

see

s w

hate

ver

the

prio

r ex

it r

outi

ne l

eft.

The

sto

rage

is

del

eted

upo

nfi

nal

retu

rn f

rom

all

of t

he e

xit

rout

ines

.

Plis

t ad

dre

sses

aft

er t

he f

irst

thr

ee s

tand

ard

ent

ries

all

dep

end

on

the

exit

. In

fact

, the

exi

t ne

ed n

otco

nfor

m t

o us

ing

the

firs

t th

ree

stan

dar

d e

ntri

es.

How

the

mai

nlin

e bu

ilds

the

plis

t fo

r it

s ex

it m

ay b

era

ther

arb

itra

ry.

0000

0000

000

0002

011

615

JAMT

ABLE

DSEC

T,

Myco

mman

d-to

-use

rid

tabl

e04

0000

0100

0000

1161

6JA

MTCM

DDS

CL12

Comm

and

0410

0001

0000

0C11

617

JAMT

UID

DSCL

(L’V

MDUS

ER)

Targ

etus

erid

0420

0001

0000

1411

618

JAMT

VDN

DSF

Targ

etVD

EVnu

mber

0430

0001

0000

1811

619

JAMT

VDS

DSF

VDEV

numb

erra

nge

star

t04

4000

0100

001C

1162

0JA

MTVD

EDS

FVD

EVnu

mber

rang

een

d04

5000

0100

020

1162

1JA

MTAB

LNEQ

U*-

JAMT

ABLE

0460

0001

Lin

e ▌1

1615

▐: T

his

is o

ur l

ocal

DSE

CT.

It

map

s th

est

orag

e d

efin

ed l

ater

at

line

1787

7.

Sample Routines


Tabl

e12

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

1 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

1162

3*

Star

tof

spec

ific

atio

ns**

****

****

****

****

****

****

****

****

**04

8000

0111

624

**

0490

0001

1162

5*

Entr

yPo

int

Name

-JA

MSAM

DL*

0500

0001

1162

6*

*05

1000

0111

627

*De

scri

ptiv

ena

me-

*05

2000

0111

628

*Di

alex

it12

00*

0530

0001

1162

9*

*05

4000

0111

630

*Fu

ncti

on-

*05

5000

0111

631

*Pr

epro

cess

DIAL

comm

andin

put

*05

6000

0111

632

**

0570

0001

1163

3*

Regi

ster

usag

e-

*05

8000

0111

634

*R0

-Ex

itnu

mber

*05

9000

0111

635

*R1

-Ad

dres

sof

exit

plis

tpo

inte

rs*

0600

0001

1163

6*

R2-

*06

1000

0111

637

*R3

-*

0620

0001

1163

8*

R4-

*06

3000

0111

639

*R5

-*

0640

0001

1164

0*

R6-

*06

5000

0111

641

*R7

-Ad

dres

sof

JAMT

ABLE

*06

6000

0111

642

*R8

-*

0670

0001

1164

3*

R9-Ad

dres

sof

exit

1200

plis

t*

0680

0001

1164

4*

R10

-*

0690

0001

1164

5*

R11

-Di

spat

ched

VMDB

Kad

dres

s*

0700

0001

1164

6*

R12

-Ba

sere

gist

er*

0710

0001

1164

7*

R13

-Sa

veAr

eaad

dres

s*

0720

0001

1164

8*

R14

-Wo

rkre

gist

er,

link

age

*07

3000

0111

649

*R1

5-Wo

rkre

gist

er,

link

age

*07

4000

0111

650

**

0750

0001

1165

1*

SAVE

WRKus

age

-*

0760

0001

1165

2*

SAVE

WRK0

-*

0770

0001

1165

3*

SAVE

WRK1

-*

0780

0001

1165

4*

SAVE

WRK2

-*

0790

0001

1165

5*

SAVE

WRK3

-*

0800

0001

1165

6*

SAVE

WRK4

-*

0810

0001

1165

7*

SAVE

WRK5

-*

0820

0001

1165

8*

SAVE

WRK6

-*

0830

0001

1165

9*

SAVE

WRK7

-*

0840

0001

1166

0*

SAVE

WRK8

-*

0850

0001

1166

1*

SAVE

WRK9

-*

0860

0001

1166

2*

*08

7000

01

Sample Routines


Tabl

e12

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

1 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

1166

3*

Inpu

t-

*08

8000

0111

664

*R0

-Ex

itnu

mber

*08

9000

0111

665

*R1

-Ad

dres

sof

plis

tad

dres

ses

*09

0000

0111

666

*R2

-Ad

dres

sof

XCRB

K*

0910

0001

1166

7*

*09

2000

0111

668

*Ou

tput

-Se

eEx

itno

rmal

,Ex

iter

ror

*09

3000

0111

669

**

0940

0001

1167

0*

Exit

norm

al-

*09

5000

0111

671

*R1

5=0

*09

6000

0111

672

*Ta

rget

user

idch

ange

d*

0970

0001

1167

3*

*09

8000

0111

674

*Ex

iter

ror

-*

0990

0001

1167

5*

None

*10

0000

0111

676

**

1010

0001

1167

7*

Gene

ralco

mmen

ts-

*10

2000

0111

678

*Th

eor

igin

alpl

ist

buil

tfo

rex

it12

00wa

sth

is:

*10

3000

0111

679

**

1040

0001

Lin

e ▌1

1663

▐: T

he s

tand

ard

con

tent

s of

the

reg

iste

rsat

ent

ry t

o al

l ex

it r

outi

nes

will

be

like

this

:

vR

0 w

ill c

onta

in t

he e

xit

num

ber.

vR

1 w

ill c

onta

in t

he a

dd

ress

of

an a

rray

of

add

ress

es (

the

plis

t). T

he h

igh

ord

er b

it o

f th

e la

stad

dre

ss w

ill b

e on

.

vR

2 w

ill c

onta

in t

he a

dd

ress

of

an X

CR

BK

(E

xit

Cal

lR

eque

st B

lock

).

vR

3-R

10 w

ill b

e ga

rbag

e.

vR

11 m

ay c

onta

in t

he a

dd

ress

of

the

dis

patc

hed

VM

DB

K, o

r m

aybe

not

. Tha

t al

l d

epen

ds

on t

heex

it.

vR

12 w

ill b

e us

ed a

s th

e m

odul

e ba

se r

egis

ter.

vR

13 w

ill b

e us

ed a

s th

e SA

VB

K b

ase

regi

ster

.

vR

14-R

15 w

ill b

e us

ed a

s lin

kage

reg

iste

rs.

Stor

age

for

the

XC

RB

K i

s al

loca

ted

or

del

eted

by

ASS

OC

IAT

E E

XIT

pro

cess

ing.

An

XC

RB

K i

s al

loca

ted

for

each

epn

ame

spec

ifie

d b

y A

SSO

CIA

TE

EX

IT. I

f an

epna

me

is s

peci

fied

mor

e th

an o

nce,

eac

h oc

curr

ence

gets

a s

epar

ate

XC

RB

K. T

he u

ser

wor

ds

(Res

erve

dfo

r no

n-IB

M u

se)

are

init

ializ

ed t

o bi

nary

zer

os w

hen

allo

cate

d b

ut a

re o

ther

wis

e un

touc

hed

by

the

exit

cont

rol

rout

ines

.

Sample Routines


Tabl

e12

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

1 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

Lin

e ▌1

1663

▐(c

onti

nued

): In

thi

s ex

ampl

e, w

e d

o no

tus

e H

CPX

CR

BK

, so

we

do

not

show

it

in t

he l

isti

ng.

Her

e is

wha

t it

loo

ks l

ike:

XCRB

KDS

ECT

////

(var

ious

cont

rolfi

elds

)* XC

RUSR

D1DS

DRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

D2DS

DRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

F1DS

FRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

F2DS

FRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

H1DS

HRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

H2DS

HRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

X1DS

XRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

X2DS

XRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

X3DS

XRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

X4DS

XRe

serv

edfo

rno

n-IB

Mus

e* XC

RFWD

DSA

Addr

ess

ofne

xtXC

RBK

* XCRA

TMPT

DSF

Coun

tof

atte

mpts

toca

ll*

this

rout

ine

* XCRC

ALLS

DSF

Coun

tof

call

sco

mple

ted

*DS

FRe

serv

edXC

RMSA

CTDS

DTi

me(i

nmi

cro-

seco

nds)

that

*..

.th

isro

utin

ewa

sac

tive

.XC

R$EN

DDS

0DTh

een

d*

Sample Routines


Tabl

e12

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

1 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

1168

0*

PLIS

T=(’

RESE

RVED’,

Argu

ment

1*

1050

0001

1168

1*

’USE

RWOR

D’,

Argu

ment

2*

1060

0001

1168

2*

’TRT

TABL

E’,

Argu

ment

3*

1070

0001

1168

3*

SAVC

MD,

Argu

ment

4*

1080

0001

1168

4*

DIAL

EUSR

,Ar

gume

nt5

*10

9000

0111

685

*VN

UMBI

N,Ar

gume

nt6

*11

0000

0111

686

*VN

UMST

RT,

Argu

ment

7*

1110

0001

1168

7*

VNUM

END,

Argu

ment

8*

1120

0001

1168

8*

RDEV

)Ar

gume

nt9

*11

3000

0111

689

**

1140

0001

1169

0*

*11

5000

0111

691

*Ou

rpu

rpos

eis

tocu

stom

ize

the

DIAL

comm

and

*11

6000

0111

692

*pr

oces

sing

.Gi

ven

some

cont

rol

data

(eit

herth

e*

1170

0001

1169

3*

comm

and

name

that

caus

edth

eDI

ALpr

oces

sing

tobe

*11

8000

0111

694

*dr

iven

orth

eta

rget

user

id),

wewi

llcu

stom

ize

the

DIAL

*11

9000

0111

695

*pr

oces

sing

.To

doso

,we

need

ata

ble

that

asso

ciat

es*

1200

0001

1169

6*

the

inco

ming

comm

andna

mewi

thth

eda

tato

retu

rnto

*12

1000

0111

697

*DI

AL.

Wewi

llde

fine

the

tabl

een

trie

sin

this

CSEC

T*

1220

0001

1169

8*

duri

ngas

semb

ly.

*12

3000

0111

699

**

1240

0001

1170

0*

Our

logi

c:*

1250

0001

1170

1*

*12

6000

0111

702

*va

lida

tein

put

(spe

cifi

call

y,ex

itnu

mber

)*

1270

0001

1170

3*

sear

chth

eta

ble

forth

eco

mman

dor

targ

etus

erid

*12

8000

0111

704

*if

foun

d,*

1290

0001

1170

5*

then

retu

rnth

ese

*13

0000

0111

706

*-

targ

etus

erid

*13

1000

0111

707

*-

targ

etvd

ev*

1320

0001

1170

8*

-vd

evra

nge

star

t*

1330

0001

1170

9*

-vd

evra

nge

end

*13

4000

0111

710

*ex

it*

1350

0001

1171

1*

*13

6000

0111

712

*En

dof

spec

ific

atio

ns**

****

****

****

****

****

****

****

****

****

1370

0001

1171

4JA

MSAM

DLHC

PENT

ERCA

LL,S

AVE=

DYNA

MIC

1390

0001

1230

0*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

1410

0001

1230

1*

Init

iali

ze:

*14

2000

0112

302

*SA

VEWR

K*

1430

0001

1230

3*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

1440

0001

1230

5*c

mtXC

SAVE

WRK,

SAVE

WRK

HCPS

VCac

tual

lydo

esth

is14

6000

01

1233

3*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

1740

0001

1233

4*

Test

exit

numb

er;le

ave

ifno

t12

00.

*17

5000

0112

335

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*17

6000

01

Lin

e ▌1

1680

▐: T

he f

ollo

win

g co

mm

ents

are

cop

ied

from

HC

PDIA

and

are

her

e fo

r yo

u to

ed

it a

sne

eded

:

*PL

IST=

(’RE

SERV

ED’,

Argu

ment

1*

’USE

RWOR

D’,

Argu

ment

2*

’TRT

TABL

E’,

Argu

ment

3*

SAVC

MD,

Argu

ment

4*

DIAL

EUSR

,Ar

gume

nt5

*VN

UMBI

N,Ar

gume

nt6

*VN

UMST

RT,

Argu

ment

7*

VNUM

END,

Argu

ment

8*

RDEV

)Ar

gume

nt9

Thi

s pl

ist

map

s to

the

X12

00 D

SEC

T t

hat

was

sho

wn

in t

he H

CPP

LX

IT C

OPY

file

on

line

6589

.

Sample Routines


Tabl

e12

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

1 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

0000

7259

00C0

4800

048

1233

7C

R0,=

A(XI

T@12

00)

Exit

1200

?17

8000

01L

ine ▌1

2337

▐: A

litt

le d

efen

sive

pro

gram

min

g he

re.

You

coul

d c

ode

the

sam

e en

try

poin

t fo

r m

ore

than

one

exit

. Whe

ther

you

do

or n

ot, i

t w

ould

be

good

prac

tice

to

veri

fy t

hat

R0

cont

ains

the

exi

t nu

mbe

rth

at y

ou e

xpec

t.

0000

76A7

7400

4400

0FE

1233

8Br

NEDL

EXIT

..no

,le

ave

1790

0001

1234

0*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

1810

0001

1234

1*

Ifth

eor

igin

alco

mman

dwa

sDI

AL,

oron

eof

its

*18

2000

0112

342

*ab

brev

iati

ons,

then

wene

edto

sear

chth

eta

ble

for

*18

3000

0112

343

*th

eta

rget

user

id.

*18

4000

0112

344

**

1850

0001

1234

5*

Ifth

eor

igin

alco

mman

dwa

sno

tDI

AL,

then

wene

edto

*18

6000

0112

346

*se

arch

the

tabl

efo

rth

eco

mman

d.*

1870

0001

1234

7*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

1880

0001

Lin

e ▌1

2338

▐: B

ranc

h R

elat

ive

inst

ruct

ions

are

use

dex

tens

ivel

y in

CP.

The

ir u

se m

eans

a b

ranc

h ta

rget

may

be

wel

l be

yond

the

bas

e re

gist

er o

ffse

tm

axim

um o

f 40

95, w

hich

the

n m

eans

mod

ules

may

grow

wel

l be

yond

4 K

B y

et r

equi

re o

nly

a si

ngle

bas

ere

gist

er f

or d

ata.

CP'

s m

nem

onic

usa

ge t

end

s to

be

uppe

rcas

e-B

-low

erca

se-r

-upp

erca

se-c

ond

itio

n, a

s in

BrN

E, B

rC, B

rU.

Sample Routines


Tabl

e12

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

1 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

0000

7A58

90D0

1C00

01C

1234

9L

R9,S

AVER

1Ad

dres

sof

ourpl

ist

1900

0001

1235

0HC

PUSI

NGX1

200,

R9Ad

dres

sabi

lity

1910

0001

0000

7E58

1090

0C00

00C

1235

4L

R1,X

1200

CMD

Addr

essof

comm

and

1930

0001

0000

82D5

04C0

5210

0000

052

0000

012

356

CLC

=CL5

’DIA

L’,

0(R1

)DI

AL19

5000

0100

0088

A784

0013

000A

E12

357

BrE

DL30

019

6000

0100

008C

D503

C04C

1000

0004

C00

000

1235

8CL

C=C

L4’D

IA’,

0(R1

)DI

A19

7000

0100

0092

A784

000E

000A

E12

359

BrE

DL30

019

8000

0100

0096

D502

C057

1000

0005

700

000

1236

0CL

C=C

L3’D

I’,

0(R1

)DI

1990

0001

0000

9CA7

8400

0900

0AE

1236

1Br

EDL

300

2000

0001

0000

A0D5

01C0

5010

0000

050

0000

012

362

CLC

=CL2

’D’,

0(R1

)D

2010

0001

0000

A6A7

8400

0400

0AE

1236

3Br

EDL

300

2020

0001

0000

AAA7

F400

0E00

0C6

1236

5Br

UDL

400

Sear

chta

ble

for

cmd

2040

0001

1236

7*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2060

0001

1236

8*

The

comm

andwa

sDI

AL.

Ther

efor

e,se

arch

the

tabl

e*

2070

0001

1236

9*

for

theta

rget

user

id.

*20

8000

0112

370

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*20

9000

01

0000

AE12

372

DL30

0DS

0H21

1000

0100

00AE

5810

9010

0001

012

373

LR1

,X12

00UI

DAd

dres

sof

targ

etus

erid

2120

0001

1237

4HC

PLCA

LLSR

CHUI

DLo

okfo

rth

eta

rget

uid

2130

0001

0000

BEA7

7400

2000

0FE

1368

6Br

NZDL

EXIT

..no

tfo

und

2140

0001

0000

C2A7

F400

0A00

0D6

1368

7Br

UDL

500

..fo

und

2150

0001

1368

9*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2170

0001

1369

0*

The

comm

andwa

sno

tDI

AL.

Ther

efor

e,se

arch

the

tabl

e*

2180

0001

1369

1*

for

theco

mman

d.*

2190

0001

1369

2*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2200

0001

0000

C613

694

DL40

0DS

0H22

2000

0113

695

*cmt

LR1

,X12

00CM

DAd

dres

sof

theco

mman

d22

3000

0113

696

HCPL

CALL

SRCH

CMD

Look

forth

eco

mman

d22

4000

0100

00D2

A774

0016

000F

E15

008

BrNZ

DLEX

IT..

not

foun

d22

5000

0115

009

*cmt

BrU

DL50

0..

foun

d22

6000

01

1501

1*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2280

0001

1501

2*

Ata

ble

entr

ywa

sfo

und.

*22

9000

0115

013

*Co

pyou

rco

ntro

lda

tato

the

exit

1200

plis

t.*

2300

0001

1501

4*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2310

0001

0000

D615

016

DL50

0DS

0H23

3000

0115

017

HCPU

SING

JAMT

ABLE

,R7

Addr

essa

bili

ty23

4000

01

Lin

e ▌1

2349

▐: H

ere

is a

n ex

ampl

e of

how

to

get

toon

e of

the

arg

umen

ts (

in t

his

case

, the

com

man

d t

hat

got

us h

ere)

tha

t w

as s

uppl

ied

to

exit

120

0.R

emem

ber

that

eve

ryth

ing

pass

ed t

o an

exi

t is

pass

ed b

y ad

dre

ss.

Sample Routines


Tabl

e12

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

1 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

0000

D658

1090

1000

010

1502

1L

R1,X

1200

UID

Retu

rnta

rget

uid

2360

0001

0000

DAD2

0710

0070

0C00

000

0000

C15

022

MVC

0(L’

VMDU

SER,

R1),

JAMT

UID

2370

0001

0000

E058

1090

1400

014

1502

4L

R1,X

1200

VDN

Retu

rnta

rget

vdev

2390

0001

0000

E4D2

0310

0070

1400

000

0001

415

025

MVC

0(4,

R1),

JAMT

VDN

2400

0001

0000

EA58

1090

1800

018

1502

7L

R1,X

1200

VDS

Retu

rnvd

evra

nge

star

t24

2000

0100

00EE

D203

1000

7018

0000

000

018

1502

8MV

C0(

4,R1

),JA

MTVD

S24

3000

01

0000

F458

1090

1C00

01C

1503

0L

R1,X

1200

VDE

Retu

rnvd

evra

nge

end

2450

0001

0000

F8D2

0310

0070

1C00

000

0001

C15

031

MVC

0(4,

R1),

JAMT

VDE

2460

0001

1503

3*c

mtBr

UDL

EXIT

Retu

rn24

8000

01

1503

5*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2500

0001

1503

6*

Retu

rn*

2510

0001

1503

7*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2520

0001

0000

FE15

039

DLEX

ITDS

0H25

4000

01

Lin

e ▌1

5021

▐: R

etur

n d

ata

back

to

the

mai

nlin

e by

usin

g th

e ad

dre

sses

pas

sed

to

you

in t

he p

list.

Che

ckth

e pl

ist

def

init

ion

to b

e su

re w

hich

ent

ries

you

are

allo

wed

to

chan

ge.

0000

FED2

03D0

540A

0000

054

00A0

015

041

MVC

SAVE

R15,

PFX0

Rc<-

-0

2560

0001

1504

2HC

PEXI

TEP

=(JA

MSAM

DL),

SETC

C=NO

2570

0001

1560

0HC

PDRO

PR7

2590

0001

1560

2HC

PDRO

PR9

2600

0001

Lin

e ▌1

5041

▐: A

lway

s re

turn

R15

= 0

, unl

ess

you

know

for

sur

e th

at i

t sh

ould

not

be.

The

val

ue r

etur

ned

in

R15

is

real

ly c

onsi

der

ed t

o be

two

unsi

gned

hal

fwor

d v

alue

s: t

he e

xit

cont

rol

retu

rnco

de

and

the

mai

nlin

e re

turn

cod

e.

01

23

┌───

────

──┬─

────

────

┬───

────

──┬─

────

────

┐R1

5│

Exit

Cont

rolRC

│Ma

inli

neRC

│└─

────

────

┴───

────

──┴─

────

────

┴───

────

──┘

Byt

es 0

-1 (

the

exit

con

trol

ret

urn

cod

e) c

onta

in t

hed

irec

tive

to

the

exit

con

trol

ler.

Byt

es 0

-1 w

ill b

e se

t to

zero

by

the

exit

con

trol

rou

tine

bef

ore

bein

g pa

ssed

back

to

the

mai

nlin

e ro

utin

e.

Byt

es 2

-3 (

the

mai

nlin

e re

turn

cod

e) c

onta

in t

hed

irec

tive

to

the

mai

nlin

e ro

utin

e. T

he e

xit

cont

rolle

rw

ill r

etur

n to

the

mai

nlin

e, a

s th

e re

turn

cod

e in

R15

,th

e m

axim

um m

ainl

ine

retu

rn c

ode

valu

e fr

om a

ll of

the

exit

rou

tine

s th

at w

ere

calle

d. T

he m

eani

ng o

f th

ere

turn

cod

e w

ill d

epen

d o

n th

e m

ainl

ine

rout

ine.

Sample Routines


Tabl

e12

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

1 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

1560

5*

Star

tof

spec

ific

atio

ns**

****

****

****

****

****

****

****

****

**26

2000

0115

606

**

2630

0001

1560

7*

Entr

yPo

int

Name

-SR

CHCM

D*

2640

0001

1560

8*

*26

5000

0115

609

*De

scri

ptiv

ena

me-

*26

6000

0115

610

*Se

arch

the

JAMT

ABLE

entr

iesfo

rth

efi

rst

entr

yth

at*

2670

0001

1561

1*

matc

hes

thear

gume

ntpa

ssed

inR1

.*

2680

0001

1561

2*

*26

9000

0115

613

*Fu

ncti

on-

*27

0000

0115

614

*Ta

ble

look

up*

2710

0001

1561

5*

*27

2000

0115

616

*Re

gist

erus

age

-*

2730

0001

1561

7*

R0-BC

Tlo

opre

gfo

rse

arch

ing

JAMT

ABLE

*27

4000

0115

618

*R1

-Ad

dres

sof

12by

teco

mman

d*

2750

0001

1561

9*

R2-

*27

6000

0115

620

*R3

-*

2770

0001

1562

1*

R4-

*27

8000

0115

622

*R5

-*

2790

0001

1562

3*

R6-

*28

0000

0115

624

*R7

-Ad

dres

sof

JAMT

ABLE

*28

1000

0115

625

*R8

-*

2820

0001

1562

6*

R9-

*28

3000

0115

627

*R1

0-

*28

4000

0115

628

*R1

1-Di

spat

ched

VMDB

Kad

dres

s*

2850

0001

1562

9*

R12

-Ba

sere

gist

er*

2860

0001

1563

0*

R13

-Sa

veAr

eaad

dres

s*

2870

0001

1563

1*

R14

-Wo

rkre

gist

er,

link

age

*28

8000

0115

632

*R1

5-Wo

rkre

gist

er,

link

age

*28

9000

0115

633

**

2900

0001

1563

4*

SAVE

WRKus

age

-*

2910

0001

1563

5*

SAVE

WRK0

-*

2920

0001

1563

6*

SAVE

WRK1

-*

2930

0001

1563

7*

SAVE

WRK2

-*

2940

0001

1563

8*

SAVE

WRK3

-*

2950

0001

1563

9*

SAVE

WRK4

-*

2960

0001

1564

0*

SAVE

WRK5

-*

2970

0001

1564

1*

SAVE

WRK6

-*

2980

0001

1564

2*

SAVE

WRK7

-*

2990

0001

1564

3*

SAVE

WRK8

-*

3000

0001

1564

4*

SAVE

WRK9

-*

3010

0001

1564

5*

*30

2000

0115

646

*In

put

-*

3030

0001

1564

7*

R1-Ad

dres

sof

12by

teco

mman

d*

3040

0001

1564

8*

*30

5000

0115

649

*Ou

tput

-Se

eEx

itno

rmal

,Ex

iter

ror

*30

6000

0115

650

**

3070

0001

Sample Routines


Tabl

e12

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

1 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

1565

1*

Exit

norm

al-

*30

8000

0115

652

*CC

=0,

Tabl

een

try

foun

d*

3090

0001

1565

3*

R7=Ad

dres

sof

JAMT

ABLE

*31

0000

0115

654

**

3110

0001

1565

5*

CC=3,

Tabl

een

try

not

foun

d*

3120

0001

1565

6*

*31

3000

0115

657

*Ex

iter

ror

-*

3140

0001

1565

8*

None

*31

5000

0115

659

**

3160

0001

1566

0*

Gene

ralco

mmen

ts-

*31

7000

0115

661

*No

ne*

3180

0001

1566

2*

*31

9000

0115

663

*En

dof

spec

ific

atio

ns**

****

****

****

****

****

****

****

****

****

3200

0001

1566

5SR

CHCM

DHC

PLEN

TR,

3220

0001

1613

6*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

3240

0001

1613

7*

Init

iali

ze:

*32

5000

0116

138

*SA

VEWR

K*

3260

0001

1613

9*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

3270

0001

Lin

e ▌1

5665

▐: H

CPL

EN

TR

def

ault

ent

ry t

ype

isC

AL

L.

1614

1*c

mtXC

SAVE

WRK,

SAVE

WRK

HCPS

VCac

tual

lydo

esth

is32

9000

01

1614

3*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

3310

0001

1614

4*

Star

tlo

okin

gfo

rata

ble

entr

yth

atma

tche

sth

eco

mman

d*

3320

0001

1614

5*

that

R1po

ints

to.

*33

3000

0116

146

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*33

4000

01

0001

1E41

0000

0400

004

1614

8LA

R0,J

AM$D

CNNu

mber

ofen

trie

s33

6000

0100

0122

4170

C190

0019

016

149

LAR7

,JAM

$DC

Addr

essof

firs

tJA

MTAB

LE33

7000

0116

150

HCPU

SING

JAMT

ABLE

,R7

Addr

essa

bili

ty33

8000

01

0001

2616

154

SCMD

100

DS0H

3400

0001

0001

26D5

0B70

0010

0000

000

0000

016

155

CLC

JAMT

CMD,

0(R1

)Fo

und

it?

3410

0001

0001

2CA7

8400

0A00

140

1615

6Br

ESC

MDCC

0..

yes

3420

0001

0001

3041

7700

2000

020

1615

8LA

R7,J

AMTA

BLN(

R7)

Addr

essof

thene

xtJA

MTAB

LE34

4000

0100

0134

A706

FFF9

0012

616

159

BrCT

R0,S

CMD1

00Ke

eplo

okin

g34

5000

01

0001

3816

161

SCMD

CC3

DS0H

3470

0001

1616

2CC

3Se

tco

ndit

ion

code

=3

3480

0001

0001

3CA7

F400

0500

146

1616

4Br

USC

MDEX

ITRe

turn

3490

0001

0001

4016

166

SCMD

CC0

DS0H

3510

0001

0001

4050

70D0

3400

034

1616

7ST

R7,S

AVER

7Re

turn

addr

essof

JAMT

ABLE

3520

0001

1616

8CC

0Se

tco

ndit

ion

code

=0

3530

0001

1617

0*c

mtBr

USC

MDEX

ITRe

turn

3540

0001

Lin

e ▌1

6141

▐: A

new

CA

LL

-typ

e en

try,

HC

PEN

TE

Ror

HC

PLE

NT

R, w

ill b

e ha

nded

a n

ew s

avea

rea.

So,

even

tho

ugh

the

sam

e la

bels

are

use

d i

n th

issu

brou

tine

, the

y ar

e to

uchi

ng s

tora

ge d

iffe

rent

tha

nth

e ca

ller's

sav

eare

a.

Sample Routines


Tabl

e12

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

1 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

1617

2*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

3560

0001

1617

3*

Retu

rn*

3570

0001

1617

4*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

3580

0001

0001

4616

176

SCMD

EXIT

DS0H

3600

0001

1617

7HC

PLEX

IT,

3610

0001

1673

6HC

PDRO

PR7

3630

0001

1673

9*

Star

tof

spec

ific

atio

ns**

****

****

****

****

****

****

****

****

**36

5000

0116

740

**

3660

0001

1674

1*

Entr

yPo

int

Name

-SR

CHUI

D*

3670

0001

1674

2*

*36

8000

0116

743

*De

scri

ptiv

ena

me-

*36

9000

0116

744

*Se

arch

the

JAMT

ABLE

entr

iesfo

rth

efi

rst

entr

yth

at*

3700

0001

1674

5*

matc

hes

thear

gume

ntpa

ssed

inR1

.*

3710

0001

1674

6*

*37

2000

0116

747

*Fu

ncti

on-

*37

3000

0116

748

*Ta

ble

look

up*

3740

0001

1674

9*

*37

5000

0116

750

*Re

gist

erus

age

-*

3760

0001

1675

1*

R0-BC

Tlo

opre

gfo

rse

arch

ing

JAMT

ABLE

*37

7000

0116

752

*R1

-Ad

dres

sof

8by

teus

erID

*37

8000

0116

753

*R2

-*

3790

0001

1675

4*

R3-

*38

0000

0116

755

*R4

-*

3810

0001

1675

6*

R5-

*38

2000

0116

757

*R6

-*

3830

0001

1675

8*

R7-Ad

dres

sof

JAMT

ABLE

*38

4000

0116

759

*R8

-*

3850

0001

1676

0*

R9-

*38

6000

0116

761

*R1

0-

*38

7000

0116

762

*R1

1-Di

spat

ched

VMDB

Kad

dres

s*

3880

0001

1676

3*

R12

-Ba

sere

gist

er*

3890

0001

1676

4*

R13

-Sa

veAr

eaad

dres

s*

3900

0001

1676

5*

R14

-Wo

rkre

gist

er,

link

age

*39

1000

0116

766

*R1

5-Wo

rkre

gist

er,

link

age

*39

2000

0116

767

**

3930

0001

1676

8*

SAVE

WRKus

age

-*

3940

0001

1676

9*

SAVE

WRK0

-*

3950

0001

1677

0*

SAVE

WRK1

-*

3960

0001

1677

1*

SAVE

WRK2

-*

3970

0001

1677

2*

SAVE

WRK3

-*

3980

0001

1677

3*

SAVE

WRK4

-*

3990

0001

1677

4*

SAVE

WRK5

-*

4000

0001

1677

5*

SAVE

WRK6

-*

4010

0001

1677

6*

SAVE

WRK7

-*

4020

0001

1677

7*

SAVE

WRK8

-*

4030

0001

1677

8*

SAVE

WRK9

-*

4040

0001

1677

9*

*40

5000

01

Sample Routines


Tabl

e12

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

1 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

1678

0*

Inpu

t-

*40

6000

0116

781

*R1

-Ad

dres

sof

8by

teus

erID

*40

7000

0116

782

**

4080

0001

1678

3*

Outp

ut-

See

Exit

norm

al,Ex

iter

ror

*40

9000

0116

784

**

4100

0001

1678

5*

Exit

norm

al-

*41

1000

0116

786

*CC

=0,

Tabl

een

try

foun

d*

4120

0001

1678

7*

R7=Ad

dres

sof

JAMT

ABLE

*41

3000

0116

788

**

4140

0001

1678

9*

CC=3,

Tabl

een

try

not

foun

d*

4150

0001

1679

0*

*41

6000

0116

791

*Ex

iter

ror

-*

4170

0001

1679

2*

None

*41

8000

0116

793

**

4190

0001

1679

4*

Gene

ralco

mmen

ts-

*42

0000

0116

795

*No

ne*

4210

0001

1679

6*

*42

2000

0116

797

*En

dof

spec

ific

atio

ns**

****

****

****

****

****

****

****

****

****

4230

0001

1679

9SR

CHUI

DHC

PLEN

TR,

4250

0001

1727

0*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4270

0001

1727

1*

Init

iali

ze:

*42

8000

0117

272

*SA

VEWR

K*

4290

0001

1727

3*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4300

0001

1727

5*c

mtXC

SAVE

WRK,

SAVE

WRK

HCPS

VCac

tual

lydo

esth

is43

2000

01

1727

7*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4340

0001

1727

8*

Star

tlo

okin

gfo

rata

ble

entr

yth

atma

tche

sth

eus

erid

*43

5000

0117

279

*th

atR1

poin

tsto

.*

4360

0001

1728

0*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4370

0001

0001

5E41

0000

0400

004

1728

2LA

R0,J

AM$D

CNNu

mber

ofen

trie

s43

9000

0100

0162

4170

C190

0019

017

283

LAR7

,JAM

$DC

Addr

essof

firs

tJA

MTAB

LE44

0000

0117

284

HCPU

SING

JAMT

ABLE

,R7

Addr

essa

bili

ty44

1000

01

0001

6617

288

SUID

100

DS0H

4430

0001

0001

66D5

0770

0C10

0000

00C

0000

017

289

CLC

JAMT

UID,

0(R1

)Fo

und

it?

4440

0001

0001

6CA7

8400

0A00

180

1729

0Br

ESU

IDCC

0..

yes

4450

0001

0001

7041

7700

2000

020

1729

2LA

R7,J

AMTA

BLN(

R7)

Addr

essof

thene

xtJA

MTAB

LE44

7000

0100

0174

A706

FFF9

0016

617

293

BrCT

R0,S

UID1

00Ke

eplo

okin

g44

8000

01

0001

7817

295

SUID

CC3

DS0H

4500

0001

1729

6CC

3Se

tco

ndit

ion

code

=3

4510

0001

0001

7CA7

F400

0500

186

1729

8Br

USU

IDEX

ITRe

turn

4520

0001

Sample Routines


Tabl

e12

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

1 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

0001

8017

300

SUID

CC0

DS0H

4540

0001

0001

8050

70D0

3400

034

1730

1ST

R7,S

AVER

7Re

turn

addr

essof

JAMT

ABLE

4550

0001

1730

2CC

0Se

tco

ndit

ion

code

=0

4560

0001

1730

4*c

mtBr

USU

IDEX

ITRe

turn

4570

0001

1730

6*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4590

0001

1730

7*

Retu

rn*

4600

0001

1730

8*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4610

0001

0001

8617

310

SUID

EXIT

DS0H

4630

0001

1731

1HC

PLEX

IT,

4640

0001

1787

0HC

PDRO

PR7

4660

0001

1787

3*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

----

*46

8000

0117

874

*Th

eJA

MTAB

LEen

trie

s.*

4690

0001

1787

5*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

----

*47

0000

01

0001

9017

877

JAM$

DCDS

0D47

2000

0117

878

*47

3000

0100

0190

6F40

4040

4040

4040

1787

9DC

CL12

’?’

Comm

and

4740

0001

0001

9CC8

C5D3

D7D4

C1C3

C817

880

DCCL

8’HE

LPMA

CH’

Targ

etus

erid

4750

0001

0001

A4FF

FFFF

FF17

881

DCF’

-1’

Targ

etVD

EVnu

mber

4760

0001

0001

A800

0000

0017

882

DCXL

4’00

0000

00’

VDEV

numb

erra

nge

star

t47

7000

0100

01AC

0000

FFFF

1788

3DC

XL4’

0000

FFFF’

VDEV

numb

erra

nge

end

4780

0001

1788

4*

4790

0001

0001

B0C2

D6D6

D2E2

4040

4017

885

DCCL

12’B

OOKS

’Co

mman

d48

0000

0100

01BC

D3C9

C2D9

C1D9

E840

1788

6DC

CL8’

LIBR

ARY’

Targ

etus

erid

4810

0001

0001

C4FF

FFFF

FF17

887

DCF’

-1’

Targ

etVD

EVnu

mber

4820

0001

0001

C800

0000

0017

888

DCXL

4’00

0000

00’

VDEV

numb

erra

nge

star

t48

3000

0100

01CC

0000

00FF

1788

9DC

XL4’

0000

00FF’

VDEV

numb

erra

nge

end

4840

0001

1789

0*

4850

0001

0001

D0D1

D6E4

D9D5

C1D3

E217

891

DCCL

12’J

OURN

ALS’

Comm

and

4860

0001

0001

DCD3

C9C2

D9C1

D9E8

4017

892

DCCL

8’LI

BRAR

Y’

Targ

etus

erid

4870

0001

0001

E4FF

FFFF

FF17

893

DCF’

-1’

Targ

etVD

EVnu

mber

4880

0001

0001

E800

0001

0017

894

DCXL

4’00

0001

00’

VDEV

numb

erra

nge

star

t48

9000

0100

01EC

0000

01FF

1789

5DC

XL4’

0000

01FF’

VDEV

numb

erra

nge

end

4900

0001

1789

6*

4910

0001

0001

F0D7

E5D4

4040

4040

4017

897

DCCL

12’P

VM’

Comm

and

4920

0001

0001

FCD7

E5D4

4040

4040

4017

898

DCCL

8’PV

M’

Targ

etus

erid

4930

0001

0002

04FF

FFFF

FF17

899

DCF’

-1’

Targ

etVD

EVnu

mber

4940

0001

0002

0800

0000

0017

900

DCXL

4’00

0000

00’

VDEV

numb

erra

nge

star

t49

5000

0100

020C

0000

FFFF

1790

1DC

XL4’

0000

FFFF’

VDEV

numb

erra

nge

end

4960

0001

1790

2*

4970

0001

0000

417

903

JAM$

DCN

EQU

(*-J

AM$D

C)/J

AMTA

BLN

4980

0001

1790

5HC

PDRO

PR0

5000

0001

1790

7HC

PDRO

PR1

150

1000

0117

909

HCPD

ROP

R13

5020

0001

1791

1HC

PEPI

LG50

3000

01

Lin

e ▌1

7873

▐: T

hese

are

our

con

trol

dat

a d

efin

itio

ns,

whi

ch a

re m

appe

d b

y JA

MTA

BL

E.

Not

ice

the

two

entr

ies

for

com

man

ds

BO

OK

S an

dJO

UR

NA

LS,

whe

re t

he t

arge

t us

er I

D i

s th

e sa

me

but

the

rang

e of

tar

get

virt

ual

dev

ices

is

dif

fere

nt. T

his

sepa

rati

on g

uara

ntee

s th

at n

eith

er t

he B

OO

KS

user

sno

r th

e JO

UR

NA

LS

user

s ca

n co

nsum

e al

l of

the

virt

ual

term

inal

ad

dre

sses

, wit

h on

e ty

pe o

f us

elo

ckin

g ou

t th

e ot

her.

For

this

tab

le t

o be

mos

t us

eful

, you

sho

uld

als

oen

ter

the

follo

win

g D

EFI

NE

AL

IAS

com

man

ds:

DEFI

NEAL

IAS

?FO

RDI

ALEN

ABLE

DEFI

NEAL

IAS

BOOK

SFO

RDI

ALEN

ABLE

DEFI

NEAL

IAS

JOUR

NALS

FOR

DIAL

ENAB

LEDE

FINE

ALIA

SPV

MFO

RDI

ALEN

ABLE

If s

o, t

hen

any

of t

he a

liase

s (?

, BO

OK

S, J

OU

RN

AL

S,PV

M)

or t

he b

ase

com

man

d (

DIA

L)

will

cau

seH

CPD

IA to

be

calle

d, a

nd H

CPD

IA w

ill c

all

exit

1200

.

If a

use

r at

a t

erm

inal

ent

ers

the

com

man

d '?

', or

'BO

OK

S', o

r an

y of

the

oth

er a

lias

nam

es, i

t w

ill b

etr

eate

d a

s an

alia

s to

DIA

L, w

hich

mea

ns t

hat

CP

will

tre

at i

t ju

st a

s if

the

use

r ha

d e

nter

ed t

heco

mm

and

'DIA

L' w

ith

no o

pera

nds.

Unl

ess

exit

120

0su

pplie

s a

targ

et u

ser

ID, t

his

com

man

d w

ill f

ail.

It i

sup

to

exit

120

0 to

mak

e th

e co

mm

and

“w

hole

”.

Sample Routines


Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

Ass

emb

ler

Sou

rce

Com

men

tary

12MA

CRO

0060

0001

13&L

ABEL

JAMM

DLAT

&EPN

AME

0065

0001

14MD

LATH

DR&E

PNAM

E00

7000

0115

MDLA

TENT

JAMS

AM,M

ODAT

TR=(

MP,D

YN),

X007

5000

1CP

XLOA

D=YE

S00

8000

0116

MDLA

TTLR

0085

0001

17ME

ND00

9000

01

Lin

e ▌1

2▐: T

his

mac

ro, J

AM

MD

LA

T, d

escr

ibes

the

mod

ules

and

ent

ry p

oint

s fo

r co

mpo

nent

ID

JA

M.

Thi

s m

acro

can

be

incl

uded

inl

ine,

as

show

n he

re, o

rin

a M

AC

LIB

tha

t is

pro

cess

ed b

y th

e co

mpi

ler.

The

HC

PCM

PID

mac

ro, i

nvok

ed o

n lin

e 19

, ad

ds

JAM

to

the

com

pone

nt I

Ds

for

this

com

pile

.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

19HC

PCMP

IDCO

MPID

=JAM

0100

0001

20CO

PYHC

POPT

NS01

0500

01

Lin

e ▌1

9▐: H

CPC

MPI

D i

s a

mac

roin

stru

ctio

n w

hose

purp

ose

is t

o sp

ecif

y yo

ur c

ompo

nent

ID

ent

ries

. CP

uses

the

com

pone

nt I

D e

ntri

es t

o id

enti

fy y

our

xxxM

DL

AT

mac

roin

stru

ctio

ns, w

hich

CP

uses

to

assi

gn l

inka

ge a

ttri

bute

s. C

ompo

nent

ID

ent

ries

are

3-ch

arac

ter

stri

ngs.

For

exa

mpl

e, I

BM

's c

ompo

nent

ID

for

CP

is 'H

CP'

.

Com

pone

nt I

D e

ntri

es c

an a

lso

be u

sed

on

HC

PCO

NSL

MA

CR

Os,

whi

ch w

ould

con

nect

the

HC

PCO

NSL

MA

CR

O w

ith

asso

ciat

ed m

essa

gere

posi

tori

es (

see

the

CP

ASS

OC

IAT

E M

ESS

AG

Eco

mm

and

for

mor

e in

form

atio

n). H

CPC

MPI

D m

aybe

spe

cifi

ed m

ulti

ple

tim

es, a

nd w

ith

mul

tipl

eco

mpo

nent

ID

ent

ries

. For

exa

mpl

e:

HCPC

MPID

COMP

ID=(

JAM,

JAM,

XYZ)

HCPC

MPID

COMP

ID=I

JK

The

HC

PCM

PID

MA

CR

O i

s ti

ed t

o th

e su

ppor

t fo

rm

ulti

ple

HC

PMD

LA

T M

AC

RO

s, e

ach

know

n as

xxxM

DL

AT.

The

'xxx

' let

ters

rep

rese

nt t

he c

ompo

nent

ID e

ntri

es s

peci

fied

in

your

HC

PCM

PID

MA

CR

Os.

Bas

ed o

n th

e H

CPC

MPI

D M

AC

RO

s sh

own

abov

e,th

e xx

xMD

LA

T M

AC

RO

s th

at H

CPC

AL

L w

ould

use

are:

HCPM

DLAT

MACR

Oal

ways

chec

kedfi

rst

JAMM

DLAT

MACR

OJA

MMDL

ATMA

CRO

XYZM

DLAT

MACR

OIJ

KMDL

ATMA

CRO

JAM

MD

LA

T i

s sh

own

twic

e be

caus

e JA

M i

ssp

ecif

ied

tw

ice

in t

he H

CPC

MPI

D M

AC

RO

s.

HC

PCA

LL

and

oth

er M

AC

RO

s ca

ll yo

ur x

xxM

DL

AT

MA

CR

O l

ooki

ng f

or t

he a

ttri

bute

s of

the

mod

ule

inor

der

to

know

the

pro

per

linka

ge t

o ge

nera

te.

HC

PCA

LL

will

cal

l yo

ur x

xxM

DL

AT

MA

CR

Os

in t

heor

der

tha

t yo

ur c

ompo

nent

ID

ent

ries

are

spe

cifi

edon

the

HC

PCM

PID

MA

CR

Os.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

Lin

e ▌1

9▐(c

onti

nued

): T

he f

orm

at o

f yo

urxx

xMD

LA

T M

AC

RO

s is

sim

ilar

to t

he f

orm

at o

f th

eH

CPM

DL

AT

MA

CR

O. H

ere

is o

ur J

AM

MD

LA

TM

AC

RO

, als

o sh

own

in t

he l

isti

ng a

t lin

e 12

:

MACR

O&L

ABEL

JAMM

DLAT

&EPN

AME

MDLA

THDR

&EPN

AME

MDLA

TENT

JAMS

AM,M

ODAT

TR=(

MP,D

YN),

XCP

XLOA

D=YE

SMD

LATT

LRME

ND

You

use

the

MD

LA

TE

NT

MA

CR

O t

o sp

ecif

y th

eat

trib

utes

of

your

mod

ule

usin

g th

e sa

me

keyw

ord

sas

you

use

d i

n H

CPM

DL

AT.

For

a t

ypic

al m

odul

e,w

hat

you

see

here

is

all

that

you

wou

ld n

eed

. Onl

y if

your

mod

ule

has

spec

ial

attr

ibut

es b

eyon

d t

hese

wou

ld y

ou i

nves

tiga

te o

ther

MD

LA

TE

NT

key

wor

ds.

Att

rib

ute

Mea

nin

g

MP

Mul

tipr

oces

sor

capa

ble.

Thi

s m

eans

tha

tta

sks

on d

iffe

rent

pro

cess

ors

may

run

thi

sm

odul

e si

mul

tane

ousl

y.

DY

NU

ses

a d

ynam

ic s

avea

rea

(SA

VB

K).

Att

ribu

tes,

spe

cifi

cally

MP

or N

ON

MP

, spe

cifi

edhe

re m

ust

mat

ch t

he a

ttri

bute

s sp

ecif

ied

by

CPX

LO

AD

.

347JA

MSAM

HCPP

ROLG

ATTR

=(RE

SIDE

NT,R

EENT

ERAB

LE),

X011

5000

1CO

PYR=

(199

5,20

05),

COPY

RID=

’My

Copy

righ

t’,

X012

0000

1BA

SE=(

R12)

0130

0001

Lin

e ▌3

47▐:

The

key

wor

d 'C

OPY

RID

=' i

s us

ed o

nly

ifth

e ke

ywor

d 'C

OPY

R=

' is

spec

ifie

d. T

he s

trin

gas

sign

ed t

o 'C

OPY

RID

=' w

ill b

e as

sem

bled

as

ach

arac

ter

cons

tant

in

plac

e of

the

IB

M c

opyr

ight

noti

ce.

0000

0000

000

00AE

848

0+JA

MSAM

CSEC

T,

&VX1

NOZW

01-H

CPPR

0000

0048

1+HC

P@MO

DDS

0D@V

X1NO

ZW01

-HCP

PR00

0000

00E5

482+

DCAL

2(C’

V’)

Bogu

sin

stru

ctio

nto

prev

entfa

ll-t

hru

@VRG

B1QY

01-H

CPPR

0000

02E5

E548

3+DC

C’VV

’Fo

rHC

PENT

ERen

forc

emen

tch

arac

ters

@VRG

B1QY

01-H

CPPR

0000

0400

0000

0048

4+DC

A(0)

Noca

ll-

orgo

to-b

y-re

gist

erve

ctor

@VRG

B1QY

01-H

CPPR

0000

0800

0000

0048

5+DC

A(0)

For

PLX,

bran

char

ound

prol

ogue

@VRG

B1QY

X01-

HCPP

R+

For

ASM,

spac

er@V

RGB1

QY

Lin

es ▌48

2-48

5▐: H

ere

you

see

"bog

us i

nstr

ucti

on",

enfo

rcem

ent

char

acte

rs, a

dd

ress

of

vect

or, a

nd s

o on

.T

hese

fie

lds

mir

ror

fiel

ds

gene

rate

d b

y H

CPE

NT

ER

to s

uppo

rt c

all-

by-r

egis

ter

and

got

o-by

-reg

iste

r. N

one

of t

hese

dat

a fi

eld

s ar

e ex

ecut

able

ins

truc

tion

s, s

oex

ecut

ion

cann

ot f

all

thro

ugh

into

any

HC

PEN

TE

Rm

acro

, whi

ch i

s w

hy t

here

is

a "b

ogus

ins

truc

tion

".

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

0000

0C91

8194

A281

9440

4048

6+DC

CL8’

jams

am’,

AL2(

(HCP

@END

-HCP

@MOD

)/8)

@VR4

GCZW

01-H

CPPR

0000

16C5

D4C5

F2F0

F500

0048

7+DC

CL6’

EME2

05’,

XL2’

0000

’@A

0002

FA01

-HCP

PR00

001E

F0F7

61F2

F961

F0F5

488+

DCCL

8’07

/29/

05’

@A00

02FA

01-H

CPPR

0000

267A

F1F0

4BF4

F5D9

C548

9+DC

CL6’

:10.

45’,

CL1’

R’,C

L1’E’

@A00

02FA

01-H

CPPR

Lin

e ▌4

86▐:

The

mod

ule

nam

e is

sav

ed i

n lo

wer

cas

ew

hene

ver

it d

oes

not

star

t w

ith

'HC

P'. S

ervi

ces

in C

Pm

ay u

se t

his

valu

e as

sto

red

her

e (T

RA

CE

inst

ruct

ions

for

HC

PCA

LL

/H

CPE

XIT

lin

kage

) or

may

con

vert

it

to u

pper

cas

e (H

CPC

ON

SL w

hen

build

ing

erro

r m

essa

ge h

ead

ers)

. Thi

s is

just

ano

ther

pecu

liari

ty t

hat

you

shou

ld b

e aw

are

of.

0000

2ED4

A840

C396

97A8

9949

0+DC

C’My

Copy

righ

t’@V

R5HI

QY01

-HCP

PR00

003A

F1F9

F9F5

491+

DCCL

4’19

95’

@V80

GNU2

01-H

CPPR

0000

3E6B

492+

DCCL

1’,’

@V80

GNU2

01-H

CPPR

0000

3FF2

F0F0

F449

3+DC

CL4’

2005

’@V

80GN

U201

-HCP

PR00

0048

494+

HCP@

0002

DS0D

LABE

LFO

RBR

ANCH

AROU

NDPR

OLG

@P68

39ZW

01-H

CPPR

Lin

es ▌49

0-49

3▐: Y

ou c

an u

se t

he 'C

OPY

R=

' and

'CO

PYR

ID=

' key

wor

ds

to i

nser

t yo

ur o

wn

copy

righ

tin

form

atio

n in

to t

he e

xpan

sion

of

the

HC

PPR

OL

Gm

acro

. Not

ice

that

bot

h ke

ywor

ds

mus

t be

spe

cifi

ed,

or e

lse

your

cop

yrig

ht i

nfor

mat

ion

will

not

be

gene

rate

d.

0000

4800

048

0021

857

1+HC

PDAT

AALO

CTR

,@Y

0656

QY02

-HCP

DA00

0060

0006

000

218

573+

HCPC

ODEA

LOCT

R,

@Y06

56QY

02-H

CPDA

575

PRIN

TON

,NOG

EN01

3500

01

577

HCPE

XTRN

HCPC

VTRM

-Bi

nto

deci

mal

conv

ersi

on,

trim

0’S

0145

0001

579

HCPE

XTRN

HCPC

VUBM

-Bi

nary

toFi

lemo

deco

nver

sion

0150

0001

581

HCPE

XTRN

HCPZ

ICLS

-Cl

ose

file

onaCP

-acc

esse

dmd

isk

0155

0001

583

HCPE

XTRN

HCPZ

IGET

-Ge

ta

reco

rdfr

oma

CMSfi

le01

6000

0158

5HC

PEXT

RNHC

PZIO

PN-

Open

file

onCP

-acc

esse

dmi

nidi

sk01

6500

0158

7HC

PEXT

RNHC

PZPR

PG-

Gene

ral

pars

er01

7000

01

590

COPY

HCPB

ITMP

-Bi

tMa

pCo

ntro

lBl

ock

0180

0001

710

COPY

HCPC

MPBK

-Co

mpon

ent

IDBl

ock

0185

0001

829

COPY

HCPC

ONDF

-St

atem

ent

defi

niti

onma

ppin

g01

9000

0110

02CO

PYHC

PCSL

PL-

Cons

ole

MACR

Opa

rame

terli

st01

9500

0119

24CO

PYHC

PDRB

K-

Data

Requ

estBl

ock

0200

0001

2623

COPY

HCPE

QUAT

-Ge

nera

leq

uate

s02

0500

01

Lin

es ▌57

1-57

3▐: L

OC

TR

ins

truc

tion

s ar

e us

ed t

opl

ace

dat

a ea

rly

in t

he m

odul

e (i

n th

is e

xam

ple,

dat

ast

arts

at

offs

et 0

x000

048)

fol

low

ed b

y ex

ecut

able

cod

e(i

n th

is e

xam

ple,

cod

e st

arts

at

offs

et 0

x000

060)

.C

erta

in m

acro

s w

ill g

ener

ate

LO

CT

R i

nstr

ucti

ons

inor

der

to

add

the

ir d

ata

to t

hese

sec

tion

s. S

o yo

u m

ayfi

nd i

nstr

ucti

ons

that

are

seq

uent

ial

in t

he l

isti

ng b

utar

e no

t se

quen

tial

in

mem

ory.

The

re w

ill b

e m

ore

exam

ples

of

this

sho

wn

belo

w.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

5501

COPY

HCPE

QXIT

-Eq

uate

sfo

rEx

itco

ntro

l02

1000

0156

62CO

PYHC

PGSD

BK-

Gene

ral

Syst

emDa

taBl

ock

0215

0001

5847

COPY

HCPM

XRBK

-Me

ssag

enu

mber

equa

tes

0220

0001

1086

5CO

PYHC

PPFX

PG-

Host

Pref

ixPa

ge02

2500

01

Lin

e ▌5

501▐

: HC

PEQ

XIT

is

a go

od p

lace

to

look

for

exit

equ

ates

. Exi

t eq

uate

s sh

ould

all

be o

f th

e fo

rm:

XIT

@xx

xx E

QU

X'x

xxx'

. As

alw

ays,

we

sugg

est

that

you

do

not

add

you

r ex

it n

umbe

r eq

uate

s to

thi

sIB

M C

OPY

file

. Ad

d t

hem

to

your

ow

n C

OPY

file

inst

ead

. IB

M-d

efin

ed C

P ex

it r

outi

nes

shou

ld h

ave

equa

tes

of t

his

form

in

the

HC

PEQ

XIT

CO

PY f

ile.

The

int

ent

is t

hat

ever

y ex

it p

oint

sho

uld

be

liste

dhe

re, s

o th

at w

e ca

n te

ll w

hat

has

been

use

d, w

ith

asm

all

amou

nt o

f in

form

atio

n ab

out

wha

t it

is

for.

The

two

exit

s in

DIA

L p

roce

ssin

g ar

e as

sign

ed t

hese

CP

exit

num

bers

:

XIT@

1200

EQU

X’12

00’

Comm

and:

DIAL

*Va

lida

teop

eran

dspa

ssed

*on

theDI

ALco

mman

d* XI

T@12

01EQ

UX’

1201’

Comm

and:

DIAL

*Se

cond

chan

ce,

afte

r*

targ

etha

sbe

ende

cide

d.*

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

1383

8CO

PYHC

PPLX

IT-

PLIS

Tde

fini

tion

sfo

rIB

MEx

itPo

ints

0230

0001

0000

00X1

200

DSEC

T,

The

PLIS

Tpo

inte

rsfo

rex

it12

0070

5002

10*

Read

allco

mmen

tshe

reas

if71

0002

10*

they

allbe

gin

"Add

ress

of"

7150

0210

0000

00DS

A1

Rese

rved

7200

0210

0000

04X1

200U

WDDS

A2

User

word

s72

5002

1000

0008

X120

0TRT

DSA

3TR

T25

6by

tes

7300

0210

0000

0CX1

200C

MDDS

A4

Comm

andna

me73

5002

1000

0010

X120

0UID

DSA

5Ta

rget

user

id74

0002

1000

0014

X120

0VDN

DSA

6Ta

rget

VDEV

numb

er74

5002

1000

0018

X120

0VDS

DSA

7VD

EVnu

mber

star

tse

arch

rang

e75

0002

1000

001C

X120

0VDE

DSA

8VD

EVnu

mber

end

sear

chra

nge

7550

0210

0000

20X1

200R

DVDS

A9

RDEV

7600

0210

1422

4CO

PYHC

PRDE

V-

Real

Devi

ceBl

ock

0235

0001

1511

5CO

PYHC

PSAV

BK-

Save

area

Bloc

k02

4000

0115

482

COPY

HCPS

SBDF

-Sy

ntax

Subd

efin

itio

nde

scri

ptio

nar

ea02

4500

0115

615

COPY

HCPS

SPBK

-Po

inte

rto

SSBD

F02

5000

0115

742

COPY

HCPS

TADF

-Sy

ntax

stat

ede

fini

tion

area

0255

0001

1586

3CO

PYHC

PSYN

DF-

Synt

axde

fini

tion

area

0260

0001

1604

0CO

PYHC

PSYS

CM-

Host

Syst

emCo

mmon

Area

0265

0001

1743

9CO

PYHC

PTOK

DF-

Toke

nde

fini

tion

mapp

ing

0270

0001

1785

0CO

PYHC

PVMD

BK-

Virt

ual

Mach

ineDe

fini

tion

Bloc

k02

7500

0122

112

COPY

HCPX

CTBK

-CP

Exit

Cont

rolBl

ock

0280

0001

2229

0HC

PUSI

NGPF

XPG,

R002

9000

0122

293

HCPU

SING

VMDB

K,R1

102

9500

0122

296

HCPU

SING

SAVB

K,R1

303

0000

01

Lin

e ▌1

3838

▐: H

CPP

LX

IT i

s th

e pl

ace

to l

ook

for

plis

td

efin

itio

ns f

or I

BM

-def

ined

CP

exit

poi

nts.

As

alw

ays,

we

sugg

est

that

you

do

not

add

you

r ex

itpl

ist

def

init

ions

to

this

IB

M C

OPY

file

. Ad

d t

hem

to

your

ow

n C

OPY

file

ins

tead

. Eve

ry e

xit

plis

t sh

ould

be o

f th

e fo

rm:

Xxxx

xDS

ECT

,DS

ARe

serv

edXx

xxxU

WDDS

AAd

dres

sof

32by

tes

ofus

er..

.wo

rds

doub

lewo

rdal

igne

d..

.in

itia

lize

dto

bina

ry..

.ze

ros

Xxxx

xTRT

DSA

Addr

ess

of25

6by

tes

...

doub

lewo

rdal

igne

d..

.in

itia

lize

dto

bina

ry..

.ze

ros

Xxxx

x...

DSA

Addr

ess

ofa

data

item

Xxxx

x...

DSA

Addr

ess

ofa

data

item

Stor

age

for

the

plis

t is

allo

cate

d i

n th

e m

ainl

ine

rout

ine

for

each

ins

tanc

e of

cal

ling

an e

xit.

The

plis

tan

d w

hat

it p

oint

s to

are

unt

ouch

ed b

y th

e ex

itco

ntro

l ro

utin

es. E

ach

exit

see

s w

hate

ver

the

prio

rex

it l

eft.

The

sto

rage

is

del

eted

upo

n fi

nal

retu

rnfr

om a

ll of

the

exi

t ro

utin

es.

Plis

t ad

dre

sses

aft

er t

he f

irst

thr

ee s

tand

ard

ent

ries

all

dep

end

on

the

exit

. In

fact

, the

exi

t ne

ed n

otco

nfor

m t

o us

ing

the

firs

t th

ree

stan

dar

d e

ntri

es.

How

the

mai

nlin

e bu

ilds

the

plis

t fo

r it

s ex

it m

ay b

era

ther

arb

itra

ry.

0000

0000

000

0002

422

300

JAMT

ABLE

DSEC

T,

Myco

mman

d-to

-use

rid

tabl

e03

1000

0100

0000

2230

1JA

MTFW

DDS

AAd

dres

sof

next

JAMT

ABLE

0315

0001

0000

022

302

JAMT

GSD

EQU

JAMT

FWD

Addr

essof

erro

rms

gGS

DBK

X032

0000

1..

.if

the

pars

erde

tect

edX0

3250

001

...il

lega

lsy

ntax

0330

0001

0000

0422

303

JAMT

CMD

DSCL

12Co

mman

d03

3500

0100

0010

2230

4JA

MTUI

DDS

CL(L

’VMD

USER

)Ta

rget

user

id03

4000

0100

0018

2230

5JA

MTVD

NDS

FTa

rget

VDEV

numb

er03

4500

0100

001C

2230

6JA

MTVD

SDS

FVD

EVnu

mber

rang

est

art

0350

0001

0000

2022

307

JAMT

VDE

DSF

VDEV

numb

erra

nge

end

0355

0001

0002

422

308

JAMT

ABLN

EQU

*-JA

MTAB

LE03

6000

01

Lin

e ▌2

2300

▐: T

his

is o

ur l

ocal

DSE

CT.

It

map

s th

est

orag

e th

at t

he p

arse

r fi

lls i

n (a

t lin

e 49

151)

bas

edon

the

par

ser

synt

ax d

efin

itio

n at

lin

e 70

492.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

2231

0*

Star

tof

spec

ific

atio

ns**

****

****

****

****

****

****

****

****

**03

7000

0122

311

**

0375

0001

2231

2*

Entr

yPo

int

Name

-JA

MSAM

DL*

0380

0001

2231

3*

*03

8500

0122

314

*De

scri

ptiv

ena

me-

*03

9000

0122

315

*Di

alex

it12

00*

0395

0001

2231

6*

*04

0000

0122

317

*Fu

ncti

on-

*04

0500

0122

318

*Pr

epro

cess

DIAL

comm

andin

put

*04

1000

0122

319

**

0415

0001

2232

0*

Regi

ster

usag

e-

*04

2000

0122

321

*R0

-Ex

itnu

mber

*04

2500

0122

322

*R1

-Ad

dres

sof

exit

plis

tpo

inte

rs*

0430

0001

2232

3*

R2-

*04

3500

0122

324

*R3

-*

0440

0001

2232

5*

R4-Ad

dres

sof

argu

ment

4,th

eco

mman

d*

0445

0001

2232

6*

R5-Ad

dres

sof

argu

ment

5,th

eta

rget

user

id*

0450

0001

2232

7*

R6-

*04

5500

0122

328

*R7

-Ad

dres

sof

JAMT

ABLE

*04

6000

0122

329

*R8

-*

0465

0001

2233

0*

R9-Ad

dres

sof

exit

1200

plis

t*

0470

0001

2233

1*

R10

-Ad

dres

sof

our

CMPB

K*

0475

0001

2233

2*

R11

-Di

spat

ched

VMDB

Kad

dres

s*

0480

0001

2233

3*

R12

-Ba

sere

gist

er*

0485

0001

2233

4*

R13

-Sa

veAr

eaad

dres

s*

0490

0001

2233

5*

R14

-Wo

rkre

gist

er,

link

age

*04

9500

0122

336

*R1

5-Wo

rkre

gist

er,

link

age

*05

0000

0122

337

**

0505

0001

2233

8*

SAVE

WRKus

age

-*

0510

0001

2233

9*

SAVE

WRK0

-Fl

ags

*05

1500

0122

340

*SA

VEWR

K1-

*05

2000

0122

341

*SA

VEWR

K2-

*05

2500

0122

342

*SA

VEWR

K3-

*05

3000

0122

343

*SA

VEWR

K4-

*05

3500

0122

344

*SA

VEWR

K5-

*05

4000

0122

345

*SA

VEWR

K6-

*05

4500

0122

346

*SA

VEWR

K7-

*05

5000

0122

347

*SA

VEWR

K8-

*05

5500

0122

348

*SA

VEWR

K9-

*05

6000

0122

349

**

0565

0001

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

2235

0*

Inpu

t-

*05

7000

0122

351

*R0

-Ex

itnu

mber

*05

7500

0122

352

*R1

-Ad

dres

sof

plis

tad

dres

ses

*05

8000

0122

353

*R2

-Ad

dres

sof

XCRB

K*

0585

0001

2235

4*

*05

9000

0122

355

*Ou

tput

-Se

eEx

itno

rmal

,Ex

iter

ror

*05

9500

0122

356

**

0600

0001

2235

7*

Exit

norm

al-

*06

0500

0122

358

*R1

5=0

*06

1000

0122

359

*Ta

rget

user

id,

VDEV

chan

ged

*06

1500

0122

360

**

0620

0001

2236

1*

Exit

erro

r-

*06

2500

0122

362

*No

ne*

0630

0001

2236

3*

*06

3500

01

Lin

e ▌2

2350

▐: T

he s

tand

ard

con

tent

s of

the

reg

iste

rsat

ent

ry t

o al

l ex

it r

outi

nes

will

be

like

this

:

vR

0 w

ill c

onta

in t

he e

xit

num

ber.

vR

1 w

ill c

onta

in t

he a

dd

ress

of

an a

rray

of

add

ress

es (

the

plis

t). T

he h

igh

ord

er b

it o

f th

e la

stad

dre

ss w

ill b

e on

.

vR

2 w

ill c

onta

in t

he a

dd

ress

of

an X

CR

BK

(E

xit

Cal

lR

eque

st B

lock

).

vR

3-R

10 w

ill b

e ga

rbag

e.

vR

11 m

ay c

onta

in t

he a

dd

ress

of

the

dis

patc

hed

VM

DB

K, o

r m

aybe

not

. Tha

t al

l d

epen

ds

on t

heex

it.

vR

12 w

ill b

e us

ed a

s th

e m

odul

e ba

se r

egis

ter.

vR

13 w

ill b

e us

ed a

s th

e SA

VB

K b

ase

regi

ster

.

vR

14-R

15 w

ill b

e us

ed a

s lin

kage

reg

iste

rs.

Stor

age

for

the

XC

RB

K i

s al

loca

ted

or

del

eted

by

ASS

OC

IAT

E E

XIT

pro

cess

ing.

An

XC

RB

K i

s al

loca

ted

for

each

epn

ame

spec

ifie

d b

y A

SSO

CIA

TE

EX

IT. I

f an

epna

me

is s

peci

fied

mor

e th

an o

nce,

eac

h oc

curr

ence

gets

a s

epar

ate

XC

RB

K. T

he u

ser

wor

ds

(Res

erve

dfo

r no

n-IB

M u

se)

are

init

ializ

ed t

o bi

nary

zer

os w

hen

allo

cate

d b

ut a

re o

ther

wis

e un

touc

hed

by

the

exit

cont

rol

rout

ines

.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

Lin

e ▌2

2350

▐(c

onti

nued

): In

thi

s ex

ampl

e, w

e d

o no

tus

e th

e H

CPX

CR

BK

, so

we

do

not

show

it

in t

helis

ting

. Her

e is

wha

t it

loo

ks l

ike:

XCRB

KDS

ECT

////

(var

ious

cont

rolfi

elds

)* XC

RUSR

D1DS

DRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

D2DS

DRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

F1DS

FRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

F2DS

FRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

H1DS

HRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

H2DS

HRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

X1DS

XRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

X2DS

XRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

X3DS

XRe

serv

edfo

rno

n-IB

Mus

eXC

RUSR

X4DS

XRe

serv

edfo

rno

n-IB

Mus

e* XC

RFWD

DSA

Addr

ess

ofne

xtXC

RBK

* XCRA

TMPT

DSF

Coun

tof

atte

mpts

toca

ll*

this

rout

ine

* XCRC

ALLS

DSF

Coun

tof

call

sco

mple

ted

*DS

FRe

serv

edXC

RMSA

CTDS

DTi

me(i

nmi

cro-

seco

nds)

that

*..

.th

isro

utin

ewa

sac

tive

.XC

R$EN

DDS

0DTh

een

d*

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

2236

4*

Gene

ralco

mmen

ts-

*06

4000

0122

365

*Th

eor

igin

alpl

ist

buil

tfo

rex

it12

00wa

sth

is:

*06

4500

0122

366

**

0650

0001

2236

7*

PLIS

T=(’

RESE

RVED’,

Argu

ment

1*

0655

0001

2236

8*

’USE

RWOR

D’,

Argu

ment

2*

0660

0001

2236

9*

’TRT

TABL

E’,

Argu

ment

3*

0665

0001

2237

0*

SAVC

MD,

Argu

ment

4*

0670

0001

2237

1*

DIAL

EUSR

,Ar

gume

nt5

*06

7500

0122

372

*VN

UMBI

N,Ar

gume

nt6

*06

8000

0122

373

*VN

UMST

RT,

Argu

ment

7*

0685

0001

2237

4*

VNUM

END,

Argu

ment

8*

0690

0001

2237

5*

RDEV

)Ar

gume

nt9

*06

9500

0122

376

**

0700

0001

2237

7*

*07

0500

0122

378

*Ou

rpu

rpos

eis

tocu

stom

ize

the

DIAL

comm

and

*07

1000

0122

379

*pr

oces

sing

.Gi

ven

some

cont

rol

data

(eit

herth

e*

0715

0001

2238

0*

comm

and

name

that

caus

edth

eDI

ALpr

oces

sing

tobe

*07

2000

0122

381

*dr

iven

orth

eta

rget

user

id),

wewi

llcu

stom

ize

the

DIAL

*07

2500

0122

382

*pr

oces

sing

.To

doso

,we

need

ata

ble

that

asso

ciat

es*

0730

0001

2238

3*

the

inco

ming

comm

andna

mewi

thth

eda

tato

retu

rnto

*07

3500

0122

384

*DI

AL.

Wewi

llke

epth

eso

urce

ofth

atta

ble

ondi

sk.

*07

4000

0122

385

*We

will

load

that

tabl

eba

sed

onus

erin

stru

ctio

ns.

We*

0745

0001

2238

6*

will

read

the

tabl

efr

omdi

skan

dpl

ace

itin

stor

age.

*07

5000

0122

387

*We

will

sear

chth

ein

-sto

rage

data

asne

eded

.*

0755

0001

2238

8*

*07

6000

0122

389

*On

ein

tere

stin

gas

pect

ofth

issa

mple

isth

atwe

have

*07

6500

0122

390

*de

fine

dan

exit

(num

berF2

00)

forex

it12

00.

Bydo

ing

*07

7000

0122

391

*th

is,

wegi

veth

eus

erth

eab

ilit

yto

tell

usto

relo

ad*

0775

0001

2239

2*

the

tabl

e.Wh

enth

eus

eren

able

sex

itF2

00,

then

the

*07

8000

0122

393

*ne

xtti

meex

it12

00is

call

ed,

itwi

llno

tice

that

exit

*07

8500

0122

394

*F2

00is

enab

ledan

dwi

llca

llit

.Ex

itF2

00wi

ll*

0790

0001

2239

5*

relo

adth

eta

ble.

Befo

rere

load

ing

theta

ble,

exit

*07

9500

0122

396

*F2

00wi

lldi

sabl

eit

self

,so

that

the

tabl

ewi

llbe

*08

0000

0122

397

*lo

aded

only

once

for

each

time

exit

F200

isen

able

d.*

0805

0001

2239

8*

And

ifth

eus

eren

able

sex

it12

00(t

oca

use

usto

be*

0810

0001

2239

9*

call

ed)

andex

itF2

00(t

oca

use

usto

load

the

tabl

e)*

0815

0001

2240

0*

byus

ing

stat

emen

tsin

the

SYST

EMCO

NFIG

file

,we

will

*08

2000

0122

401

*ha

veth

eta

ble

auto

mati

call

ylo

aded

thefi

rst

time

DIAL

*08

2500

0122

402

*is

invo

ked.

*08

3000

0122

403

**

0835

0001

Lin

e ▌2

2365

▐: T

his

plis

t m

aps

to t

he X

1200

DSE

CT

that

was

sho

wn

in t

he H

CPP

LX

IT C

OPY

file

on

line

1383

8.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

2240

4*

Our

logi

c:*

0840

0001

2240

5*

vali

date

inpu

t(s

peci

fica

lly,

exit

numb

er)

*08

4500

0122

406

*te

stfo

rex

itF2

00(o

urlo

cal

exit

)*

0850

0001

2240

7*

ifen

able

d*

0855

0001

2240

8*

then

call

it*

0860

0001

2240

9*

loca

teou

rco

mpon

entID

bloc

k*

0865

0001

2241

0*

acqu

ireco

mpon

ent

IDbl

ock

lock

shar

ed*

0870

0001

2241

1*

sear

chth

eta

ble

forth

eco

mman

dor

targ

etus

erid

*08

7500

0122

412

*if

foun

d,*

0880

0001

2241

3*

then

retu

rnth

ese

*08

8500

0122

414

*-

targ

etus

erid

*08

9000

0122

415

*-

targ

etVD

EV*

0895

0001

2241

6*

-VD

EVra

nge

star

t*

0900

0001

2241

7*

-VD

EVra

nge

end

*09

0500

0122

418

*re

linq

uish

comp

onen

tID

bloc

klo

ck*

0910

0001

2241

9*

exit

*09

1500

0122

420

**

0920

0001

2242

1*

End

ofsp

ecif

icat

ions

****

****

****

****

****

****

****

****

****

**09

2500

01

2242

3JA

MSAM

DLHC

PENT

ERCA

LL,S

AVE=

DYNA

MIC

0935

0001

0001

6400

164

00AE

822

969+

JAMS

AMCS

ECT

,Ma

inli

neco

de@Y

0656

QY01

-HCP

EN00

0164

0016

400

AE8

2297

1+HC

PCOD

EALO

CTR

,@Y

0656

QY02

-HCP

DA22

973+

ENTR

YJA

MSAM

DL@V

RGB1

QY02

-224

4100

0168

2297

4+JA

MSAM

DLDS

0DSt

art

byde

fini

ngep

onD-

word

@VRG

B1QY

01-H

CPEN

0001

6800

E522

975+

dcal

2(c’

V’)

Then

,a

bogu

sin

stru

ctio

n@V

RGB1

QY01

-HCP

EN00

016A

C3C4

2297

6+dc

c’CD’

Then

,an

enfo

rcem

ent

thin

g@V

RGB1

QY01

-HCP

EN00

016C

0000

0000

2297

7+DC

A(HC

PSVV

S1)

Then

,ca

ll-b

y-re

gist

erve

ctor

@VRG

B1QY

01-H

CPEN

2298

0+*

Then

,re

alco

de@V

RGB1

QY

2300

9*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

0945

0001

2301

0*

Init

iali

ze:

*09

5000

0123

011

*SA

VEWR

K*

0955

0001

2301

2*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

0960

0001

2301

4*c

mtXC

SAVE

WRK,

SAVE

WRK

HCPS

VCac

tual

lydo

esth

is09

7000

01

2304

2*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

1110

0001

2304

3*

Test

exit

numb

er;le

ave

ifno

t12

00.

*11

1500

0123

044

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*11

2000

01

0001

7A59

00C0

8800

088

2304

6C

R0,=

A(XI

T@12

00)

Exit

1200

?11

3000

01L

ine ▌2

3046

▐: A

litt

le d

efen

sive

pro

gram

min

g he

re.

You

coul

d c

ode

the

sam

e en

try

poin

t fo

r m

ore

than

one

exit

. Whe

ther

you

do

or n

ot, i

t w

ould

be

good

prac

tice

to

veri

fy t

hat

R0

cont

ains

the

exi

t nu

mbe

rth

at y

ou e

xpec

t.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

0001

7EA7

7400

AA00

2D2

2304

7Br

NEDL

EXIT

..no

,le

ave

1135

0001

2304

9*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

1145

0001

2305

0*

Test

exit

numb

erF2

00.

Ifen

able

d,ca

llit

.*

1150

0001

2305

1*

Even

ifth

eca

llfa

ils,

our

comp

onen

tID

bloc

kma

yha

ve*

1155

0001

2305

2*

some

usef

ulda

ta,

soco

ntin

ueno

rmal

ly.

*11

6000

0123

053

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*11

6500

01

Lin

e ▌2

3047

▐: B

ranc

h R

elat

ive

inst

ruct

ions

are

use

dex

tens

ivel

y in

CP.

The

ir u

se m

eans

a b

ranc

h ta

rget

may

be

wel

l be

yond

the

bas

e re

gist

er o

ffse

tm

axim

um o

f 40

95, w

hich

the

n m

eans

mod

ules

may

grow

wel

l be

yond

4 K

B y

et r

equi

re o

nly

a si

ngle

bas

ere

gist

er f

or d

ata.

CP'

s m

nem

onic

usa

ge t

end

s to

be

uppe

rcas

e-B

-low

erca

se-r

-upp

erca

se-c

ond

itio

n, a

s in

BrN

E, B

rC, B

rU.

2305

5HC

PXSE

RVTE

ST,E

XIT=

F200

,X1

1750

001

DISA

BLED

=DL1

0011

8000

01

Lin

e ▌2

3055

▐: A

n ex

it n

umbe

r ca

n be

spe

cifi

edex

plic

itly

, as

is d

one

here

. Or

an e

xit

num

ber

can

besu

pplie

d i

n a

regi

ster

, for

exa

mpl

e 'E

XIT

=(R

0)'.

0001

A658

10D0

1C00

01C

2306

8L

R1,S

AVER

1Pa

ssex

it12

00pl

ist

toex

itF2

0011

9000

0123

069

HCPX

SERV

CALL

,EXI

T=F2

00,

X119

5000

1PL

ISTB

LD=(

R1),

X120

0000

1ER

ROR=

DL10

012

0500

01

0001

C024

660

DL10

0DS

0H12

1500

01

2466

2*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

1225

0001

2466

3*

Get

ourco

mpon

ent

IDbl

ock.

Itsh

ould

have

been

fill

ed*

1230

0001

2466

4*

inby

exit

F200

,bu

twe

won’

tas

sume

so.

*12

3500

0124

665

**

1240

0001

2466

6*

Ifou

rco

mpon

ent

IDbl

ock

does

not

exis

t(w

hich

is*

1245

0001

2466

7*

indi

cate

dby

R15

=4

from

FIND

),th

enwe

have

noth

ing

to*

1250

0001

2466

8*

do.

*12

5500

0124

669

**

1260

0001

2467

0*

Ifou

rco

mpon

ent

IDbl

ock

does

exis

t(w

hich

isin

dica

ted

*12

6500

0124

671

*by

R15

=0

from

FIND

),th

enwe

have

some

thin

gto

do.

We*

1270

0001

2467

2*

will

getsh

ared

cont

rolov

erth

eco

mpon

ent

IDbl

ock,

so*

1275

0001

2467

3*

that

noch

ange

sma

ybe

made

unti

lwe

fini

sh.

Wewi

ll*

1280

0001

2467

4*

perf

ormou

rta

ble

sear

ch,an

dso

fort

h.Th

en,

wewi

ll*

1285

0001

2467

5*

reli

nqui

shou

rco

ntro

lov

erth

eco

mpon

entID

bloc

kan

d*

1290

0001

2467

6*

retu

rn.

*12

9500

0124

677

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*13

0000

01

Lin

e ▌2

3068

▐: H

ere

we

call

an e

xit

pass

ing

the

plis

tth

at w

as a

lrea

dy

built

for

exi

t 12

00. S

ince

we

are

now

cons

ider

ed t

he m

ainl

ine

for

exit

F20

0, w

e ca

n pa

ss R

1w

ith

anyt

hing

tha

t w

e w

ant,

and

we

can

use

the

retu

rn c

ode

from

exi

t F2

00 a

ny w

ay t

hat

we

wan

t.

Thi

s is

how

HC

PDIA

cal

led

exi

t 12

00 o

rigi

nally

:

HCPX

SERV

CALL

,EXI

T=12

00,

PLIS

T=(’RE

SERV

ED’,

Argu

ment

1’U

SERW

ORD’

,Ar

gume

nt2r/

w’T

RTTA

BLE’

,Ar

gume

nt3r/

wSA

VCMD

,Ar

gume

nt4r/

oDI

ALEU

SR,

Argu

ment

5r/

wVN

UMBI

N,Ar

gume

nt6r/

wVN

UMST

RT,

Argu

ment

7r/

wVN

UMEN

D,Ar

gume

nt8r/

wRD

EV),

Argu

ment

9r/

oPL

ISTB

LD=’

GETS

T’,

R1->

thepl

ist

ERRO

R=EX

X@01

Z

'PL

IST

BL

D=

(R1)

' tha

t w

e us

e m

eans

tha

t th

epa

ram

eter

lis

t ha

s al

read

y be

en b

uilt

, and

tha

t R

1po

ints

to

it. H

CPD

IA b

uilt

it,

and

we

can

pass

it

on.

'PL

IST

BL

D=

'GE

TST

'' th

at H

CPD

IA u

sed

mea

nt t

hat

ane

w p

aram

eter

lis

t w

as t

o be

bui

lt i

n ac

quir

edst

orag

e, a

nd t

he a

dd

ress

of

that

sto

rage

was

to

bere

turn

ed i

n R

1.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

2467

9HC

PXSE

RVFI

ND,C

OMPI

D=’J

AM’

1310

0001

Lin

e ▌2

4679

▐: T

his

is a

n ex

ampl

e fo

r fi

ndin

g yo

urco

mpo

nent

ID

blo

ck (

CM

PBK

). A

CM

PBK

is:

vA

con

trol

blo

ck (

32 b

ytes

of

user

dat

a fi

eld

s by

def

ault

) th

at y

ou c

an u

se a

s sy

stem

-wid

e fi

eld

s fo

ryo

ur a

dd

itio

ns t

o C

P

vId

enti

fied

by

a un

ique

3-c

hara

cter

com

pone

nt I

D

vA

lloca

ted

for

you

by

HC

PXSE

RV

MA

CR

O

vD

eallo

cate

d f

or y

ou b

y H

CPX

SER

V M

AC

RO

vSe

rial

ized

for

you

by

HC

PXSE

RV

MA

CR

O

vA

pla

ce t

o us

e to

avo

id c

hang

es t

o SY

SCM

Your

com

pone

nt I

D b

lock

can

be

your

anc

hor

for

any

cont

rol

bloc

ks t

hat

your

exi

ts o

r m

ods

need

. You

cont

rol

acce

ss t

o th

e C

MPB

K b

y us

ing

the

HC

PXSE

RV

MA

CR

O. T

he C

MPB

K i

s an

att

empt

to

prov

ide

a m

echa

nism

for

you

to

have

sys

tem

-wid

ean

chor

for

you

r ad

dit

ions

to

CP

wit

hout

req

uiri

nglo

cal

mod

ific

atio

ns t

o SY

SCM

.

Her

e ar

e th

e H

CPX

SER

V M

AC

RO

s re

late

d t

oco

mpo

nent

ID

ent

ries

:

HCPX

SERV

ALLO

CATE

,COM

PID=

....

.

HCPX

SERV

DEAL

LOCA

TE,C

OMPI

D=..

...

HCPX

SERV

FIND

,COM

PID=

....

.

HCPX

SERV

LOCK

EXCL

,COM

PID=

....

.HC

PXSE

RVLO

CKEX

CLUS

IVE,

COMP

ID=.

....

HCPX

SERV

LOCK

SHAR

ED,C

OMPI

D=..

...

HCPX

SERV

LOCK

SHR,

COMP

ID=.

....

HCPX

SERV

UNLO

CKEX

CL,C

OMPI

D=..

...

HCPX

SERV

UNLO

CKEX

CLUS

IVE,

COMP

ID=.

....

HCPX

SERV

UNLO

CKSH

ARED

,COM

PID=

....

.HC

PXSE

RVUN

LOCK

SHR,

COMP

ID=.

....

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

Lin

e ▌2

4679

▐(c

onti

nued

): T

he C

MPB

K D

SEC

T l

ooks

like

this

:

CMPB

KDS

ECT

,Co

mpon

entID

Bloc

k* *-

----

----

----

----

----

----

----

----

----

----

----

**

The

IBM

fiel

dssh

ould

rema

inat

the

fron

t*

*---

----

----

----

----

----

----

----

----

----

----

--*

CMPB

KLK

DS3D

Lock

word

tose

rial

ize

*ac

cess

toth

isCM

PBK

* CMPF

WDDS

AAd

dres

sof

thene

xtCM

PBK

* CMPE

XTNQ

DSFL

1Si

zeof

exte

nsio

nat

CMPE

XTND

*in

Numb

erof

Quad

-wor

ds.

*Th

ema

ximu

mal

lowe

dva

lue

for

*CM

PEXT

NQis

240,

whic

hgi

ves

*a

maxi

mumsi

zefo

raCM

PBK

of* *

x’60

’+

240*

16=39

36by

tes

* *wh

ich

allo

wsfo

ra

litt

le*

grow

thup

to40

72by

tes.

* CMPI

DDS

CL3

Theco

mpon

ent

Id*

DSCL

8Re

serv

edfo

rIB

Mus

eDS

CL8

Rese

rved

for

IBM

use

DSCL

8Re

serv

edfo

rIB

Mus

eDS

CL8

Rese

rved

for

IBM

use

* *---

----

----

----

----

----

----

----

----

----

----

--*

*Th

eus

erfi

elds

shou

ldre

main

atth

een

d*

*---

----

----

----

----

----

----

----

----

----

----

--*

CMPU

SRD1

DSD

Rese

rved

for

non-

IBMus

eCM

PUSR

D2DS

DRe

serv

edfo

rno

n-IB

Mus

eCM

PUSR

F1DS

FRe

serv

edfo

rno

n-IB

Mus

eCM

PUSR

F2DS

FRe

serv

edfo

rno

n-IB

Mus

eCM

PUSR

H1DS

HRe

serv

edfo

rno

n-IB

Mus

eCM

PUSR

H2DS

HRe

serv

edfo

rno

n-IB

Mus

eCM

PUSR

X1DS

XRe

serv

edfo

rno

n-IB

Mus

eCM

PUSR

X2DS

XRe

serv

edfo

rno

n-IB

Mus

eCM

PUSR

X3DS

XRe

serv

edfo

rno

n-IB

Mus

eCM

PUSR

X4DS

XRe

serv

edfo

rno

n-IB

Mus

e*

SPAC

E5

CMPE

XTND

DS0D

Star

tof

vari

able

leng

thda

ta*

TheCM

PBK

may

beex

tend

edat

*al

loca

tion

time

inun

its

of*

quad

-wor

ds(1

6by

tes)

The

use

r fi

eld

s (R

eser

ved

for

non

-IB

M u

se)

are

ther

efo

r yo

u to

anc

hor

poin

ters

to

your

oth

er c

ontr

olbl

ocks

. Bec

ause

the

ow

ners

hip

of a

dd

itio

ns (

your

s or

vend

ors)

to

CP

shou

ld b

e id

enti

fied

wit

h a

uniq

ueco

mpo

nent

ID

, the

re s

houl

d n

ot b

e co

llisi

ons

in t

heus

e of

the

se c

ontr

ol b

lock

s.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

2626

1HC

PCAS

RC(D

L200

,00

:fo

und

X131

5000

1DL

EXIT

,04

:no

tfo

und

X132

0000

1DL

EXIT

),08

:ba

dar

gume

ntpa

ssed

X132

5000

1EL

SE=D

LEXI

T??

:in

vali

drc

1330

0001

0001

CE12

FF26

266+

LTR

R15,

R15

Chec

kfo

rze

roor

nega

tive

.@Y

0665

QY01

-HCP

CA00

01D0

A784

000E

001E

C26

267+

BrZ

DL20

0Fa

stpa

thfo

rRC

0@Y

0665

QY01

-HCP

CA00

01D4

A744

007F

002D

226

268+

BrM

DLEX

ITMi

nus,

unex

pect

edre

tco

de@Y

0656

QY01

-HCP

CA00

01D8

A7FE

0008

0000

826

269+

CHI

R15,

(8)

With

inbr

anch

tabl

e?@Y

0656

QY01

-HCP

CA00

01DC

A724

007B

002D

226

270+

BrH

DLEX

ITNo

,un

expe

cted

retu

rnco

de@Y

0656

QY01

-HCP

CA00

01E0

A7F1

0003

0000

326

271+

TML

R15,

B’00

11’

Retu

rnco

demu

ltip

leof

4?@Y

0656

QY01

-HCP

CA00

01E4

A774

0077

002D

226

272+

BrNZ

DLEX

ITNo

,ba

dre

turn

code

@Y06

56QY

01-H

CPCA

0001

E847

FFC1

1800

118

2627

3+B

CASR

C058

0(R1

5)Br

anch

into

bran

chta

ble

@Y06

65QY

01-H

CPCA

0001

1800

118

00AE

826

276+

HCPC

ODE5

LOCT

R,

@Y06

56QY

02-H

CPDA

0001

1826

277+

CASR

C058

0DS

0FBr

anch

tabl

e,wo

rdal

igne

d@Y

0665

QY01

-HCP

CA00

0118

A7F4

006A

001E

C26

278+

BrU

DL20

000

@Y06

65QY

01-H

CPCA

0001

1CA7

F400

DB00

2D2

2627

9+Br

UDL

EXIT

04@Y

0665

QY01

-HCP

CA00

0120

A7F4

00D9

002D

226

280+

BrU

DLEX

IT08

@Y06

65QY

01-H

CPCA

0001

EC00

164

00AE

826

282+

HCPC

ODEA

LOCT

R,

@Y06

56QY

02-H

CPDA

0001

EC26

283

DL20

0DS

0H13

3500

01

Lin

e ▌2

6261

▐: H

ere

is a

n ex

ampl

e of

a m

acro

expa

nsio

n th

at g

ener

ates

ins

truc

tion

s ou

t-of

-lin

e. L

ine

2627

6 sh

ows

a L

OC

TR

sta

tem

ent

that

cau

ses

the

next

inst

ruct

ion

to b

e pl

aced

at

offs

et 0

x000

118.

Fol

low

ing

the

bran

ch t

able

, lin

e 26

282

show

s a

LO

CT

Rst

atem

ent

that

cau

ses

the

next

ins

truc

tion

, nam

ely

the

def

init

ion

of l

abel

'DL

200'

, to

be p

lace

d a

t of

fset

0x00

01E

C.

2628

5HC

PXSE

RVLO

CKSH

ARED

,COM

PID=

’JAM’

1345

0001

2786

7HC

PCAS

RC(D

L250

,00

:su

cces

sX1

3500

001

DLEX

IT)

04:no

tfo

und

X135

5000

108

:pa

ssed

badR1

X136

0000

112

:lo

ckwa

sde

lete

dX1

3650

001

16:so

meth

ing

else

bad

X137

0000

1??

:in

vali

drc

1375

0001

0002

1827

888

DL25

0DS

0H13

8500

0100

0218

18A1

2788

9LR

R10,

R1Ad

dres

sof

ourCM

PBK

1390

0001

2789

0HC

PUSI

NGCM

PBK,

R10

Addr

essa

bili

ty13

9500

0100

021A

9602

D058

0005

827

893

OISA

VEWR

K0,X

’02’

CMPB

Kis

lock

edsh

ared

1400

0001

2789

5*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

1410

0001

2789

6*

Ifth

eor

igin

alco

mman

dwa

sDI

AL,

oron

eof

its

*14

1500

0127

897

*ab

brev

iati

ons,

then

wene

edto

sear

chth

eta

ble

for

*14

2000

0127

898

*th

eta

rget

user

id.

*14

2500

0127

899

**

1430

0001

2790

0*

Ifth

eor

igin

alco

mman

dwa

sno

tDI

AL,

then

wene

edto

*14

3500

0127

901

*se

arch

the

tabl

efo

rth

eco

mman

d.*

1440

0001

2790

2*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

1445

0001

Lin

e ▌2

6285

▐: T

hese

are

the

tw

o d

iffe

rent

way

s(f

orge

ttin

g ab

out

alte

rnat

ive

spel

lings

) to

get

con

trol

over

you

r co

mpo

nent

ID

blo

ck:

HCPX

SERV

LOCK

EXCL

USIV

E,CO

MPID

=...

..

HCPX

SERV

LOCK

SHAR

ED,C

OMPI

D=..

...

It i

s a

very

goo

d i

dea

to

lock

acc

ess

to a

ny C

MPB

Kbe

fore

you

att

empt

to

use

it b

ecau

se i

t m

ight

dis

appe

ar (

by H

CPX

SER

V D

EA

LL

OC

AT

E).

Whe

n it

com

es t

ime

to r

elin

quis

h th

e lo

ck o

ver

your

CM

PBK

,be

sur

e to

use

the

com

plem

enta

ry U

NL

OC

K r

eque

st.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

0002

1E58

90D0

1C00

01C

2790

4L

R9,S

AVER

1Ad

dres

sof

ourpl

ist

1455

0001

2790

5HC

PUSI

NGX1

200,

R9Ad

dres

sabi

lity

1460

0001

0002

2258

1090

0C00

00C

2790

9L

R1,X

1200

CMD

Addr

essof

comm

and

1470

0001

0002

26D5

04C1

0D10

0000

10D

0000

027

911

CLC

=CL5

’DIA

L’,

0(R1

)DI

AL14

8000

0100

022C

A784

0013

0025

227

912

BrE

DL30

014

8500

0100

0230

D503

C09C

1000

0009

C00

000

2791

3CL

C=C

L4’D

IA’,

0(R1

)DI

A14

9000

0100

0236

A784

000E

0025

227

914

BrE

DL30

014

9500

0100

023A

D502

C112

1000

0011

200

000

2791

5CL

C=C

L3’D

I’,

0(R1

)DI

1500

0001

0002

40A7

8400

0900

252

2791

6Br

EDL

300

1505

0001

0002

44D5

01C1

0010

0000

100

0000

027

917

CLC

=CL2

’D’,

0(R1

)D

1510

0001

0002

4AA7

8400

0400

252

2791

8Br

EDL

300

1515

0001

0002

4EA7

F400

0E00

26A

2792

0Br

UDL

400

Sera

chta

ble

for

cmd

1525

0001

2792

2*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

1535

0001

2792

3*

The

comm

andwa

sDI

AL.

Ther

efor

e,se

arch

the

tabl

e*

1540

0001

2792

4*

for

theta

rget

user

id.

*15

4500

0127

925

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*15

5000

01

0002

5227

927

DL30

0DS

0H15

6000

0100

0252

5810

9010

0001

027

928

LR1

,X12

00UI

DAd

dres

sof

targ

etus

erid

1565

0001

2792

9*c

mtLR

R10,

R10

Addr

essof

ourCM

PBK

1570

0001

2793

0HC

PLCA

LLSR

CHUI

DLo

okfo

rth

eta

rget

uid

1575

0001

0002

62A7

7400

3800

2D2

2924

2Br

NZDL

EXIT

..no

tfo

und

1580

0001

0002

66A7

F400

0C00

27E

2924

3Br

UDL

500

..fo

und

1585

0001

2924

5*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

1595

0001

2924

6*

The

comm

andwa

sno

tDI

AL.

Ther

efor

e,se

arch

the

tabl

e*

1600

0001

2924

7*

for

theco

mman

d.*

1605

0001

2924

8*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

1610

0001

0002

6A29

250

DL40

0DS

0H16

2000

0129

251

*cmt

LR1

,X12

00CM

DAd

dres

sof

theco

mman

d16

2500

0129

252

*cmt

LRR1

0,R1

0Ad

dres

sof

ourCM

PBK

1630

0001

2925

3HC

PLCA

LLSR

CHCM

DLo

okfo

rth

eco

mman

d16

3500

0100

0276

A774

002E

002D

230

565

BrNZ

DLEX

IT..

not

foun

d16

4000

0100

027A

A7F4

0002

0027

E30

566

BrU

DL50

0..

foun

d16

4500

01

3056

8*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

1655

0001

3056

9*

Ata

ble

entr

ywa

sfo

und.

*16

6000

0130

570

*Co

pyou

rco

ntro

lda

tato

the

exit

1200

plis

t.*

1665

0001

3057

1*

*16

7000

0130

572

*If

the

targ

etVD

EVfr

omth

eta

ble

is’=

’,th

enwe

want

to*

1675

0001

3057

3*

make

thedi

aled

-to

VDEV

numb

er=

theRD

EVnu

mber

(but

*16

8000

0130

574

*th

isca

non

lybe

done

ifth

eRD

EVis

for

are

alde

vice

*16

8500

0130

575

*an

dno

tfo

ralo

gica

lde

vice

orfo

ra

VTAM

devi

ce).

*16

9000

0130

576

*If

’=’is

inth

eta

ble

entr

ybu

tth

ete

rmin

alis

nota

*16

9500

0130

577

*re

alde

vice

,th

enwe

will

retu

rnth

eta

rget

VDEV

as’-

1’*

1700

0001

3057

8*

soth

atth

eVD

EVra

nge

will

bese

arch

ed.

Ifwe

retu

rna

*17

0500

0130

579

*de

vice

numb

er,

then

any

rang

ewi

llbe

igno

red.

*17

1000

0130

580

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*17

1500

01

Lin

e ▌2

7904

▐: H

ere

is a

n ex

ampl

e of

how

to

get

toon

e of

the

arg

umen

ts (

in t

his

case

, the

com

man

d t

hat

got

us h

ere)

tha

t w

as s

uppl

ied

to

exit

120

0.R

emem

ber

that

eve

ryth

ing

pass

ed t

o an

exi

t is

pass

ed b

y ad

dre

ss.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

0002

7E30

582

DL50

0DS

0H17

2500

0130

583

HCPU

SING

JAMT

ABLE

,R7

Addr

essa

bili

ty17

3000

0100

027E

5810

9010

0001

030

586

LR1

,X12

00UI

DRe

turn

targ

etui

d17

3500

01

0002

82D2

0710

0070

1000

000

0001

030

587

MVC

0(L’

VMDU

SER,

R1),

JAMT

UID

1740

0001

0002

8858

8090

2000

020

3058

9L

R8,X

1200

RDV

Addr

essof

RDEV

1750

0001

3059

0HC

PUSI

NGRD

EV,R

8Ad

dres

sabi

lity

1755

0001

0002

8C58

0070

1800

018

3059

3L

R0,J

AMTV

DNEn

try

from

theJA

MTAB

LE17

6000

0100

0290

957E

7018

0001

830

594

CLI

JAMT

VDN,

C’=’

C’=’

==>ma

keVD

EV==

RDEV

?17

6500

0100

0294

A774

0011

002B

630

595

BrNE

DL55

0..

no,

retu

rnJA

MTVD

N17

7000

0100

0298

5800

0A48

00A4

830

596

LR0

,PFX

FFS

Prep

areVD

EVnu

mber

=’-

1’17

7500

0100

029C

D503

8130

0A00

0013

000

A00

3059

7CL

CRD

EVSN

A,PF

X0RD

EV->

SNAB

Kim

plie

sSN

A17

8000

0100

02A2

A774

000A

002B

630

598

BrNE

DL55

0..

SNA,

retu

rn’-

1’17

8500

0100

02A6

D503

8014

0A00

0001

400

A00

3059

9CL

CRD

EVLS

OP,P

FX0

RDEV

->LS

OBJ

impl

iesLD

EV17

9000

0100

02AC

A774

0005

002B

630

600

BrNE

DL55

0..

LDEV

,re

turn

’-1’

1795

0001

0002

B01F

0030

601

SLR

R0,R

0Cl

ear

for

ICM

1800

0001

0002

B2BF

0380

A800

0A8

3060

2IC

MR0

,B’0

011’

,RDE

VDEV

GetRD

EVde

vice

numb

er18

0500

0100

02B6

3060

3DL

550

DS0H

1810

0001

0002

B658

1090

1400

014

3060

4L

R1,X

1200

VDN

Retu

rnta

rget

VDEV

1815

0001

0002

BA50

0010

0000

000

3060

5ST

R0,0

(,R1

)*

1820

0001

3060

6HC

PDRO

PR8

1825

0001

0002

BE58

1090

1800

018

3060

9L

R1,X

1200

VDS

Retu

rnVD

EVra

nge

star

t18

3500

0100

02C2

D203

1000

701C

0000

000

01C

3061

0MV

C0(

4,R1

),JA

MTVD

S18

4000

01

0002

C858

1090

1C00

01C

3061

2L

R1,X

1200

VDE

Retu

rnVD

EVra

nge

end

1850

0001

0002

CCD2

0310

0070

2000

000

0002

030

613

MVC

0(4,

R1),

JAMT

VDE

1855

0001

3061

4*c

mtBr

UDL

EXIT

Retu

rn18

6000

01

3061

6*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

1870

0001

3061

7*

Retu

rn*

1875

0001

3061

8*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

1880

0001

0002

D230

620

DLEX

ITDS

0H18

9000

0100

02D2

A785

0267

007A

030

621

BrAS

R8,L

DUNL

OCK

Unlo

ckou

rCM

PBK

1895

0001

Lin

e ▌3

0587

▐: R

etur

n d

ata

back

to

the

mai

nlin

e by

usin

g th

e ad

dre

sses

pas

sed

to

you

in t

he p

list.

Che

ckth

e pl

ist

def

init

ion

to b

e su

re w

hich

ent

ries

you

are

allo

wed

to

chan

ge.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

0002

D6D2

03D0

540A

0000

054

00A0

030

623

MVC

SAVE

R15,

PFX0

Rc<-

-0

1905

0001

3062

4HC

PEXI

TEP

=(JA

MSAM

DL),

SETC

C=NO

1910

0001

0002

DC58

FD00

1400

014

3090

3+L

R15,

SAVE

RETN

-SAV

BK(R

13,0

)@V

RGB1

QY01

-HCP

EX00

02E0

0DEF

3104

2+BA

SRR1

4,R1

5Re

turn

toHC

PSVR

@VRG

B1QY

02-H

CPEX

3118

2HC

PDRO

PR7

1920

0001

3118

4HC

PDRO

PR9

1925

0001

3118

6HC

PDRO

PR1

019

3000

01

3118

9*

Star

tof

spec

ific

atio

ns**

****

****

****

****

****

****

****

****

**19

4000

0131

190

**

1945

0001

3119

1*

Entr

yPo

int

Name

-SR

CHCM

D*

1950

0001

3119

2*

*19

5500

0131

193

*De

scri

ptiv

ena

me-

*19

6000

0131

194

*Se

arch

the

chai

nof

JAMT

ABLE

cont

rol

bloc

ksfo

rth

e*

1965

0001

3119

5*

firs

ten

try

whos

eJA

MTCM

Den

try

matc

hesth

ear

gume

nt*

1970

0001

3119

6*

pass

edin

R1.

*19

7500

0131

197

**

1980

0001

3119

8*

Func

tion

-*

1985

0001

3119

9*

Tabl

elo

okup

*19

9000

0131

200

**

1995

0001

3120

1*

Regi

ster

usag

e-

*20

0000

0131

202

*R0

-*

2005

0001

3120

3*

R1-Ad

dres

sof

12by

teco

mman

d*

2010

0001

3120

4*

R2-

*20

1500

0131

205

*R3

-*

2020

0001

3120

6*

R4-

*20

2500

0131

207

*R5

-*

2030

0001

3120

8*

R6-

*20

3500

0131

209

*R7

-Ad

dres

sof

JAMT

ABLE

*20

4000

0131

210

*R8

-*

2045

0001

3121

1*

R9-

*20

5000

0131

212

*R1

0-Ad

dres

sof

our

CMPB

K*

2055

0001

3121

3*

R11

-Di

spat

ched

VMDB

Kad

dres

s*

2060

0001

3121

4*

R12

-Ba

sere

gist

er*

2065

0001

3121

5*

R13

-Sa

veAr

eaad

dres

s*

2070

0001

3121

6*

R14

-Wo

rkre

gist

er,

link

age

*20

7500

0131

217

*R1

5-Wo

rkre

gist

er,

link

age

*20

8000

0131

218

**

2085

0001

Lin

e ▌3

0623

▐: A

lway

s re

turn

R15

= 0

, unl

ess

you

know

for

sur

e th

at i

t sh

ould

not

be.

The

val

ue r

etur

ned

in

R15

is

real

ly c

onsi

der

ed t

o be

2 un

sign

ed h

alfw

ord

val

ues:

the

exi

t co

ntro

l re

turn

cod

e an

d t

he m

ainl

ine

retu

rn c

ode.

01

23

┌───

────

──┬─

────

────

┬───

────

──┬─

────

────

┐R1

5│

Exit

Cont

rolRC

│Ma

inli

neRC

│└─

────

────

┴───

────

──┴─

────

────

┴───

────

──┘

Byt

es 0

-1 (

the

exit

con

trol

ret

urn

cod

e) c

onta

in t

hed

irec

tive

to

the

exit

con

trol

ler.

Byt

es 0

-1 w

ill b

e se

t to

zero

by

the

exit

con

trol

rou

tine

bef

ore

bein

g pa

ssed

back

to

the

mai

nlin

e ro

utin

e.

Byt

es 2

-3 (

the

mai

nlin

e re

turn

cod

e) c

onta

in t

hed

irec

tive

to

the

mai

nlin

e ro

utin

e. T

he e

xit

cont

rolle

rw

ill r

etur

n to

the

mai

nlin

e, a

s th

e re

turn

cod

e in

R15

,th

e m

axim

um m

ainl

ine

retu

rn c

ode

valu

e fr

om a

ll of

the

exit

rou

tine

s th

at w

ere

calle

d. T

he m

eani

ng o

f th

ere

turn

cod

e w

ill d

epen

d o

n th

e m

ainl

ine

rout

ine.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

3121

9*

SAVE

WRKus

age

-*

2090

0001

3122

0*

SAVE

WRK0

-*

2095

0001

3122

1*

SAVE

WRK1

-*

2100

0001

3122

2*

SAVE

WRK2

-*

2105

0001

3122

3*

SAVE

WRK3

-*

2110

0001

3122

4*

SAVE

WRK4

-*

2115

0001

3122

5*

SAVE

WRK5

-*

2120

0001

3122

6*

SAVE

WRK6

-*

2125

0001

3122

7*

SAVE

WRK7

-*

2130

0001

3122

8*

SAVE

WRK8

-*

2135

0001

3122

9*

SAVE

WRK9

-*

2140

0001

3123

0*

*21

4500

0131

231

*In

put

-*

2150

0001

3123

2*

R1-Ad

dres

sof

12by

teco

mman

d*

2155

0001

3123

3*

R10

-Ad

dres

sof

our

CMPB

K*

2160

0001

3123

4*

*21

6500

0131

235

*Ou

tput

-Se

eEx

itno

rmal

,Ex

iter

ror

*21

7000

0131

236

**

2175

0001

3123

7*

Exit

norm

al-

*21

8000

0131

238

*CC

=0,

Tabl

een

try

foun

d*

2185

0001

3123

9*

R7=Ad

dres

sof

JAMT

ABLE

*21

9000

0131

240

**

2195

0001

3124

1*

CC=3,

Tabl

een

try

not

foun

d*

2200

0001

3124

2*

*22

0500

0131

243

*Ex

iter

ror

-*

2210

0001

3124

4*

None

*22

1500

0131

245

**

2220

0001

3124

6*

Gene

ralco

mmen

ts-

*22

2500

0131

247

*No

ne*

2230

0001

3124

8*

*22

3500

0131

249

*En

dof

spec

ific

atio

ns**

****

****

****

****

****

****

****

****

****

2240

0001

3125

1SR

CHCM

DHC

PLEN

TR,

2250

0001

3172

2HC

PUSI

NGCM

PBK,

R10

Addr

essa

bili

ty22

6000

01

3172

6*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2270

0001

3172

7*

Init

iali

ze:

*22

7500

0131

728

*SA

VEWR

K*

2280

0001

3172

9*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2285

0001

Lin

e ▌3

1251

▐: H

CPL

EN

TR

def

ault

ent

ry t

ype

isC

AL

L.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

3173

1*c

mtXC

SAVE

WRK,

SAVE

WRK

HCPS

VCac

tual

lydo

esth

is22

9500

01

3173

3*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2305

0001

3173

4*

Star

tlo

okin

gfo

rata

ble

entr

yth

atma

tche

sth

eco

mman

d*

2310

0001

3173

5*

that

R1po

ints

to.

*23

1500

0131

736

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*23

2000

01

0002

F658

70A0

5400

054

3173

8L

R7,C

MPUS

RF2

Addr

essof

firs

tJA

MTAB

LE23

3000

0100

02FA

1277

3173

9LT

RR7

,R7

Any?

2335

0001

0002

FCA7

D400

0C00

314

3174

0Br

NPSC

MDCC

323

4000

0131

741

HCPU

SING

JAMT

ABLE

,R7

Addr

essa

bili

ty23

4500

01

0003

0031

745

SCMD

100

DS0H

2355

0001

0003

00D5

0B70

0410

0000

004

0000

031

746

CLC

JAMT

CMD,

0(R1

)Fo

und

it?

2360

0001

0003

06A7

8400

0B00

31C

3174

7Br

ESC

MDCC

0..

yes

2365

0001

0003

0A58

7070

0000

000

3174

9L

R7,J

AMTF

WDAd

dres

sof

thene

xtJA

MTAB

LE23

7500

0100

030E

1277

3175

0LT

RR7

,R7

Any?

2380

0001

0003

10A7

24FF

F800

300

3175

1Br

PSC

MD10

0..

yes

2385

0001

0003

1431

753

SCMD

CC3

DS0H

2395

0001

3175

4CC

3Se

tco

ndit

ion

code

=3

2400

0001

0003

18A7

F400

0500

322

3175

6Br

USC

MDEX

ITRe

turn

2405

0001

0003

1C31

758

SCMD

CC0

DS0H

2415

0001

0003

1C50

70D0

3400

034

3175

9ST

R7,S

AVER

7Re

turn

addr

essof

JAMT

ABLE

2420

0001

3176

0CC

0Se

tco

ndit

ion

code

=0

2425

0001

3176

2*c

mtBr

USC

MDEX

ITRe

turn

2430

0001

3176

4*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2440

0001

3176

5*

Retu

rn*

2445

0001

3176

6*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2450

0001

0003

2231

768

SCMD

EXIT

DS0H

2460

0001

3176

9HC

PLEX

IT,

2465

0001

3232

8HC

PDRO

PR7

2475

0001

3233

0HC

PDRO

PR1

024

8000

01

3233

3*

Star

tof

spec

ific

atio

ns**

****

****

****

****

****

****

****

****

**24

9000

0132

334

**

2495

0001

3233

5*

Entr

yPo

int

Name

-SR

CHUI

D*

2500

0001

3233

6*

*25

0500

0132

337

*De

scri

ptiv

ena

me-

*25

1000

0132

338

*Se

arch

the

chai

nof

JAMT

ABLE

cont

rol

bloc

ksfo

rth

e*

2515

0001

3233

9*

firs

ten

try

whos

eJA

MTUI

Den

try

matc

hesth

ear

gume

nt*

2520

0001

3234

0*

pass

edin

R1.

*25

2500

0132

341

**

2530

0001

3234

2*

Func

tion

-*

2535

0001

3234

3*

Tabl

elo

okup

*25

4000

0132

344

**

2545

0001

Lin

e ▌3

1731

▐: A

new

CA

LL

-typ

e en

try,

HC

PEN

TE

Ror

HC

PLE

NT

R, w

ill b

e ha

nded

a n

ew s

avea

rea.

So

even

tho

ugh

the

sam

e la

bels

are

use

d i

n th

issu

brou

tine

, the

y ar

e to

uchi

ng s

tora

ge d

iffe

rent

fro

mth

e ca

ller's

sav

eare

a.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

3234

5*

Regi

ster

usag

e-

*25

5000

0132

346

*R0

-*

2555

0001

3234

7*

R1-Ad

dres

sof

8by

teus

erID

*25

6000

0132

348

*R2

-*

2565

0001

3234

9*

R3-

*25

7000

0132

350

*R4

-*

2575

0001

3235

1*

R5-

*25

8000

0132

352

*R6

-*

2585

0001

3235

3*

R7-Ad

dres

sof

JAMT

ABLE

*25

9000

0132

354

*R8

-*

2595

0001

3235

5*

R9-

*26

0000

0132

356

*R1

0-Ad

dres

sof

our

CMPB

K*

2605

0001

3235

7*

R11

-Di

spat

ched

VMDB

Kad

dres

s*

2610

0001

3235

8*

R12

-Ba

sere

gist

er*

2615

0001

3235

9*

R13

-Sa

veAr

eaad

dres

s*

2620

0001

3236

0*

R14

-Wo

rkre

gist

er,

link

age

*26

2500

0132

361

*R1

5-Wo

rkre

gist

er,

link

age

*26

3000

0132

362

**

2635

0001

3236

3*

SAVE

WRKus

age

-*

2640

0001

3236

4*

SAVE

WRK0

-*

2645

0001

3236

5*

SAVE

WRK1

-*

2650

0001

3236

6*

SAVE

WRK2

-*

2655

0001

3236

7*

SAVE

WRK3

-*

2660

0001

3236

8*

SAVE

WRK4

-*

2665

0001

3236

9*

SAVE

WRK5

-*

2670

0001

3237

0*

SAVE

WRK6

-*

2675

0001

3237

1*

SAVE

WRK7

-*

2680

0001

3237

2*

SAVE

WRK8

-*

2685

0001

3237

3*

SAVE

WRK9

-*

2690

0001

3237

4*

*26

9500

0132

375

*In

put

-*

2700

0001

3237

6*

R1-Ad

dres

sof

8by

teus

erID

*27

0500

0132

377

*R1

0-Ad

dres

sof

our

CMPB

K*

2710

0001

3237

8*

*27

1500

0132

379

*Ou

tput

-Se

eEx

itno

rmal

,Ex

iter

ror

*27

2000

0132

380

**

2725

0001

3238

1*

Exit

norm

al-

*27

3000

0132

382

*CC

=0,

Tabl

een

try

foun

d*

2735

0001

3238

3*

R7=Ad

dres

sof

JAMT

ABLE

*27

4000

0132

384

**

2745

0001

3238

5*

CC=3,

Tabl

een

try

not

foun

d*

2750

0001

3238

6*

*27

5500

0132

387

*Ex

iter

ror

-*

2760

0001

3238

8*

None

*27

6500

0132

389

**

2770

0001

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

3239

0*

Gene

ralco

mmen

ts-

*27

7500

0132

391

*No

ne*

2780

0001

3239

2*

*27

8500

0132

393

*En

dof

spec

ific

atio

ns**

****

****

****

****

****

****

****

****

****

2790

0001

3239

5SR

CHUI

DHC

PLEN

TR,

2800

0001

3286

5HC

PUSI

NGCM

PBK,

R10

Addr

essa

bili

ty28

0500

01

3286

9*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2815

0001

3287

0*

Init

iali

ze:

*28

2000

0132

871

*SA

VEWR

K*

2825

0001

3287

2*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2830

0001

3287

4*c

mtXC

SAVE

WRK,

SAVE

WRK

HCPS

VCac

tual

lydo

esth

is28

4000

01

3287

6*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2850

0001

3287

7*

Star

tlo

okin

gfo

rata

ble

entr

yth

atma

tche

sth

eus

erid

*28

5500

0132

878

*th

atR1

poin

tsto

.*

2860

0001

3287

9*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2865

0001

0003

3E58

70A0

5400

054

3288

1L

R7,C

MPUS

RF2

Addr

essof

firs

tJA

MTAB

LE28

7500

0100

0342

1277

3288

2LT

RR7

,R7

Any?

2880

0001

0003

44A7

D400

0C00

35C

3288

3Br

NPSU

IDCC

328

8500

0132

884

HCPU

SING

JAMT

ABLE

,R7

Addr

essa

bili

ty28

9000

01

0003

4832

888

SUID

100

DS0H

2900

0001

0003

48D5

0770

1010

0000

010

0000

032

889

CLC

JAMT

UID,

0(R1

)Fo

und

it?

2905

0001

0003

4EA7

8400

0B00

364

3289

0Br

ESU

IDCC

0..

yes

2910

0001

0003

5258

7070

0000

000

3289

2L

R7,J

AMTF

WDAd

dres

sof

thene

xtJA

MTAB

LE29

2000

0100

0356

1277

3289

3LT

RR7

,R7

Any?

2925

0001

0003

58A7

24FF

F800

348

3289

4Br

PSU

ID10

0..

yes

2930

0001

0003

5C32

896

SUID

CC3

DS0H

2940

0001

3289

7CC

3Se

tco

ndit

ion

code

=3

2945

0001

0003

60A7

F400

0500

36A

3289

9Br

USU

IDEX

ITRe

turn

2950

0001

0003

6432

901

SUID

CC0

DS0H

2960

0001

0003

6450

70D0

3400

034

3290

2ST

R7,S

AVER

7Re

turn

addr

essof

JAMT

ABLE

2965

0001

3290

3CC

0Se

tco

ndit

ion

code

=0

2970

0001

3290

5*c

mtBr

USU

IDEX

ITRe

turn

2975

0001

3290

7*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2985

0001

3290

8*

Retu

rn*

2990

0001

3290

9*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

2995

0001

0003

6A32

911

SUID

EXIT

DS0H

3005

0001

3291

2HC

PLEX

IT,

3010

0001

3347

1HC

PDRO

PR7

3020

0001

3347

3HC

PDRO

PR1

030

2500

01

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

3347

6*

Star

tof

spec

ific

atio

ns**

****

****

****

****

****

****

****

****

**30

3500

0133

477

**

3040

0001

3347

8*

Entr

yPo

int

Name

-JA

MSAM

LD*

3045

0001

3347

9*

*30

5000

0133

480

*De

scri

ptiv

ena

me-

*30

5500

0133

481

*Ex

itF2

00,

load

JAMT

ABLE

*30

6000

0133

482

**

3065

0001

3348

3*

Func

tion

-*

3070

0001

3348

4*

Exit

F200

,lo

adJA

MTAB

LE*

3075

0001

3348

5*

*30

8000

0133

486

*Re

gist

erus

age

-*

3085

0001

3348

7*

R0-Ex

itnu

mber

*30

9000

0133

488

*-Sc

ratc

h*

3095

0001

3348

9*

R1-Ad

dres

sof

exit

plis

tpo

inte

rs*

3100

0001

3349

0*

-Ar

gume

ntto

pars

er*

3105

0001

3349

1*

-Sc

ratc

h*

3110

0001

3349

2*

R2-Ar

gume

ntto

pars

er*

3115

0001

3349

3*

R3-Ad

dres

sof

GSDB

K*

3120

0001

3349

4*

-Ar

gume

ntto

pars

er*

3125

0001

3349

5*

-Sc

ratc

h*

3130

0001

3349

6*

R4-Ad

dres

sof

DRBK

*31

3500

0133

497

*R5

-Sc

ratc

h*

3140

0001

3349

8*

R6-

*31

4500

0133

499

*R7

-Ad

dres

sof

JAMT

ABLE

*31

5000

0133

500

*R8

-Lo

cal

link

age

*31

5500

0133

501

*R9

-Ad

dres

sof

exit

1200

plis

t*

3160

0001

3350

2*

R10

-Ad

dres

sof

our

CMPB

K*

3165

0001

3350

3*

R11

-Di

spat

ched

VMDB

Kad

dres

s*

3170

0001

3350

4*

R12

-Ba

sere

gist

er*

3175

0001

3350

5*

R13

-Sa

veAr

eaad

dres

s*

3180

0001

3350

6*

R14

-Wo

rkre

gist

er,

link

age

*31

8500

0133

507

*R1

5-Wo

rkre

gist

er,

link

age

*31

9000

0133

508

**

3195

0001

3350

9*

SAVE

WRKus

age

-*

3200

0001

3351

0*

SAVE

WRK0

-Fl

ags

*32

0500

0133

511

*SA

VEWR

K1-

Addr

ess

ofer

ror

mess

age

GSDB

Ksfo

rop

erat

or*

3210

0001

3351

2*

SAVE

WRK2

-Ad

dres

sof

DRBK

*32

1500

0133

513

*SA

VEWR

K3-

Addr

ess

ofGS

DBK

for

pars

ing

*32

2000

0133

514

*SA

VEWR

K4-

Addr

ess

offi

rst

JAMT

ABLE

ofne

wch

ain

*32

2500

0133

515

*SA

VEWR

K5-

Addr

ess

ofla

stJA

MTAB

LEof

new

chai

n*

3230

0001

3351

6*

SAVE

WRK6

-*

3235

0001

3351

7*

SAVE

WRK7

-Ad

dres

sof

empt

yJA

MTAB

LE*

3240

0001

3351

8*

SAVE

WRK8

-*

3245

0001

3351

9*

SAVE

WRK9

-Er

ror

mess

age

numb

er*

3250

0001

3352

0*

*32

5500

01

Lin

e ▌3

3476

▐: T

his

is l

ocal

CP

Exi

t F2

00, w

hich

loa

ds

a so

urce

CM

S fi

le i

nto

the

syst

em e

xecu

tion

spa

ce.

For

an o

verv

iew

of

loca

l C

P E

xit

F200

's l

ogic

, see

“Sam

ple

2” o

n pa

ge 2

43 o

r se

e lin

e ▌3

3570

▐be

low

.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

3352

1*

Inpu

t-

*32

6000

0133

522

*R0

-Ex

itnu

mber

*32

6500

0133

523

*R1

-Ad

dres

sof

exit

1200

plis

tad

dres

ses

*32

7000

0133

524

*R2

-Ad

dres

sof

XCRB

K*

3275

0001

3352

5*

*32

8000

0133

526

*Ou

tput

-Se

eEx

itno

rmal

,Ex

iter

ror

*32

8500

0133

527

**

3290

0001

3352

8*

Exit

norm

al-

*32

9500

0133

529

*JA

MTAB

LEbl

ocks

buil

t*

3300

0001

3353

0*

*33

0500

0133

531

*Ex

iter

ror

-*

3310

0001

3353

2*

None

*33

1500

0133

533

**

3320

0001

Lin

e ▌3

3521

▐: T

he r

egis

ters

pas

sed

to

CP

Exi

t F2

00ar

e:

R0-

Exit

numb

erR1

-Ad

dres

sof

exit

1200

plis

tad

dres

ses

R2-

Addr

essof

XCRB

K

The

reg

iste

rs p

asse

d t

o ex

it F

200

are

def

ined

as

they

wer

e fo

r ex

it 1

200

on l

ine

2230

0. T

he o

nly

regi

ster

that

the

mai

nlin

e ha

s co

ntro

l ov

er i

s R

1. H

ere,

our

exit

120

0 ro

utin

e is

con

sid

ered

the

mai

nlin

e fo

r ex

itF2

00. T

his

cod

e ha

s pa

ssed

on

R1

as o

rigi

nally

set

by

the

mai

nlin

e m

odul

e fo

r ex

it 1

200,

mod

ule

HC

PDIA

.

3353

4*

Seri

aliz

atio

n*

3325

0001

3353

5*

Cons

ider

the

poss

ibil

ity

that

wear

eru

nnin

gon

a*

3330

0001

3353

6*

10-w

ay.

Itis

theo

reti

call

ypo

ssib

leth

at10

DIAL

*33

3500

0133

537

*co

mman

dsco

uld

beru

nnin

gsi

mult

aneo

usly

,on

eon

each

*33

4000

0133

538

*pr

oces

sor.

Each

call

sex

it12

00.

Each

exit

1200

call

s*

3345

0001

3353

9*

exit

F200

.On

eof

theex

itF2

00ta

sks

gets

the

CMPB

K*

3350

0001

3354

0*

lock

excl

usiv

e,lo

ads

the

JAMT

ABLE

SOUR

CEfi

le,

and

*33

5500

0133

541

*th

enre

linq

uish

esth

eCM

PBK

lock

.Th

ese

cond

ofth

e*

3360

0001

3354

2*

orig

inal

10ta

sks

then

does

the

same

thin

g,th

enth

e*

3365

0001

3354

3*

thir

d,an

dso

on.

TheJA

MTAB

LESO

URCE

file

gets

load

ed*

3370

0001

3354

4*

10ti

mes,

need

less

ly.

*33

7500

0133

545

**

3380

0001

3354

6*

Toav

oid

this

unne

cess

ary

proc

essi

ng,

the

firs

tta

sk*

3385

0001

3354

7*

will

disa

ble

exit

F200

befo

reit

reli

nqui

shes

the

CMPB

K*

3390

0001

3354

8*

lock

.Wh

enth

isha

ppen

sis

imma

teri

al.

Wesi

mply

*33

9500

0133

549

*de

cide

dto

doit

earl

y.Wh

enta

sks

2th

roug

h10

*34

0000

0133

550

*fi

nall

yge

ta

chan

ceto

run,

they

will

noti

ceth

atex

it*

3405

0001

3355

1*

F200

has

beco

medi

sabl

ed,

soth

eyha

veno

thin

gto

do;

*34

1000

0133

552

*th

eysi

mply

retu

rnto

exit

1200

.*

3415

0001

3355

3*

*34

2000

0133

554

*In

exit

1200

,if

an11

-th

task

come

sal

ong,

itwi

ll*

3425

0001

3355

5*

noti

ceex

itF2

00is

disa

bled

and

simp

lyco

ntin

ue.

It*

3430

0001

3355

6*

will

atte

mpt

toac

quir

eth

eCM

PBK

lock

shar

ed,

butwi

ll*

3435

0001

3355

7*

bede

laye

dun

til

all

task

s1

thro

ugh

10re

linq

uish

the

*34

4000

0133

558

*CM

PLK

lock

that

they

hold

excl

usiv

e.Wh

enta

sk11

*34

4500

0133

559

*fi

nall

yru

ns,

theJA

MTAB

LESO

URCE

file

will

alre

ady

*34

5000

0133

560

*ha

vebe

enlo

aded

.*

3455

0001

3356

1*

*34

6000

01

Lin

e ▌3

3534

▐: H

ere

is a

n ex

plan

atio

n of

our

seri

aliz

atio

n.

Con

sid

er t

he p

ossi

bilit

y th

at w

e ar

e ru

nnin

g on

a10

-way

. It

is t

heor

etic

ally

pos

sibl

e th

at 1

0 D

IAL

com

man

ds

coul

d b

e ru

nnin

g si

mul

tane

ousl

y, o

ne o

nea

ch p

roce

ssor

. Eac

h ca

lls e

xit

1200

. Eac

h ex

it 1

200

calls

exi

t F2

00. O

ne o

f th

e ex

it F

200

task

s ge

ts t

heC

MPB

K l

ock

excl

usiv

e, l

oad

s th

e JA

MTA

BL

ESO

UR

CE

file

, and

the

n re

linqu

ishe

s th

e C

MPB

K l

ock.

The

sec

ond

of

the

orig

inal

10

task

s th

en d

oes

the

sam

e th

ing,

the

n th

e th

ird

, and

so

on. T

heJA

MTA

BL

E S

OU

RC

E f

ile g

ets

load

ed 1

0 ti

mes

,ne

edle

ssly

.

To a

void

thi

s un

nece

ssar

y pr

oces

sing

, the

fir

st t

ask

will

dis

able

exi

t F2

00 b

efor

e it

rel

inqu

ishe

s th

eC

MPB

K l

ock.

Whe

n th

is h

appe

ns i

s im

mat

eria

l. W

esi

mpl

y d

ecid

ed t

o d

o it

ear

ly. W

hen

task

s 2

thro

ugh

10 f

inal

ly g

et a

cha

nce

to r

un, t

hey

will

not

ice

that

exit

F20

0 ha

s be

com

e d

isab

led

, so

they

hav

e no

thin

gto

do;

the

y si

mpl

y re

turn

to

exit

120

0.

In e

xit

1200

, if

an 1

1th

task

com

es a

long

, it

will

noti

ce e

xit

F200

is

dis

able

d a

nd s

impl

y co

ntin

ue. I

tw

ill a

ttem

pt t

o ac

quir

e th

e C

MPB

K l

ock

shar

ed, b

utw

ill b

e d

elay

ed u

ntil

all

task

s 1

thro

ugh

10 r

elin

quis

hth

e C

MPB

K l

ock

that

the

y ho

ld e

xclu

sive

. Whe

n ta

sk11

fin

ally

run

s, t

he J

AM

TAB

LE

SO

UR

CE

file

will

alre

ady

have

bee

n lo

aded

.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

Lin

e ▌3

3534

▐(c

onti

nued

):

Star

tSt

art

Star

tEx

it12

00Ex

it12

00Ex

it12

00──

───→

Task

1Ta

sk2

Task

3│

││

↓↓

↓Ca

llCa

llCa

llEx

itF2

00Ex

itF2

00Ex

itF2

00│

││

↓↓

↓Ex

itF2

00Ex

itF2

00Ex

itF2

00Ta

sk1

Task

2Ta

sk3

││

│↓

↓↓

Lock

Lock

Lock

CMPB

KCM

PBK

CMPB

K│

││

Task

s2

&3

↓─┴

──┴

─Su

spen

ded

Test

Exit

F200

│ ↓Di

sabl

eEx

itF2

00│ ↓ Load

the

File

│ ↓Un

lock

CMPB

K─┬

─Ta

sk2

││

Resu

mes

↓↓

Fini

shTe

stEx

itF2

00Ex

itF2

00│

│↓

↓←─

─┐Fi

nish

Disa

ble

│Ex

it12

00Ex

itF2

00│

────

────

─│

│Av

oide

d↓

│Lo

ad│

the

File

││

←─┘

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

Lin

e ▌3

3534

▐(c

onti

nued

):

│ ↓Un

lock

CMPB

K─┬

─Ta

sk3

││

Resu

mes

↓↓

Fini

shTe

stEx

itF2

00Ex

itF2

00│

│↓

↓←─

┐Fi

nish

Disa

ble

│Ex

it12

00Ex

itF2

00│

────

────

─│

│Av

oide

d↓

│Lo

ad│

the

File

││

←─┘

↓Un

lock

CMPB

K│ ↓

Fini

shEx

itF2

00│ ↓

Fini

shEx

it12

00──

────

───

If t

he t

est

for

exit

F20

0 w

ere

not

perf

orm

ed, e

ach

task

in t

urn

wou

ld r

eloa

d t

he f

ile, w

hich

wou

ld b

e bo

thun

nece

ssar

y an

d w

aste

ful.

Mor

eove

r, th

is m

ight

seri

ousl

y d

elay

lat

er t

asks

tha

t, w

hile

sti

ll in

exi

t12

00, s

ee t

hat

exit

F20

0 w

as d

isab

led

and

try

to

dro

pri

ght

to t

he t

able

sea

rchi

ng.

3356

2*

Gene

ralco

mmen

ts-

*34

6500

0133

563

*We

usest

anda

rdCP

mess

agenu

mber

s,bu

tth

eme

ssag

e*

3470

0001

3356

4*

text

come

sfr

omou

row

nme

ssag

ere

posi

tory

.Th

isis

*34

7500

0133

565

*in

dica

ted

onth

eHC

PCON

SLMA

CRO

byth

eCO

MPID

=ke

ywor

d.*

3480

0001

3356

6*

*34

8500

0133

567

*Th

epa

rser

will

gene

rate

mess

ages

usin

gth

est

anda

rd*

3490

0001

3356

8*

’HCP

’me

ssag

ere

posi

tory

.*

3495

0001

3356

9*

*35

0000

01

Lin

e ▌3

3562

▐: S

omet

hing

to

keep

in

min

d w

hen

usin

g lo

cal

mes

sage

rep

osit

orie

s. S

tand

ard

CP

serv

ices

tha

t yo

u us

e m

ay g

ener

ate

mes

sage

s. I

f so

,th

ey w

ill b

e fr

om t

he m

essa

ge r

epos

itor

y as

soci

ated

wit

h 'H

CP'

.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

3357

0*

Our

logi

cfo

rex

itF2

00*

3505

0001

3357

1*

vali

date

inpu

t(s

peci

fica

lly,

exit

numb

er)

*35

1000

0133

572

*fi

ndCM

PBK

forco

mpon

ent

ID’J

AM’

*35

1500

0133

573

*if

foun

d*

3520

0001

3357

4*

then

do*

3525

0001

3357

5*

acqu

ire

CMPB

Klo

ckex

clus

ive

*35

3000

0133

576

*en

d*

3535

0001

3357

7*

else

do*

3540

0001

3357

8*

allo

cate

CMPB

K,wh

ich

also

acqu

ires

CMPB

Klo

ck*

3545

0001

3357

9*

end

*35

5000

0133

580

*te

stex

itF2

00*

3555

0001

3358

1*

ifdi

sabl

ed*

3560

0001

3358

2*

then

exit

*35

6500

0133

583

*di

sabl

eex

itF2

00*

3570

0001

3358

4*

geta

DRBK

forre

adin

gou

rta

ble

file

*35

7500

0133

585

*ge

ta

GSDB

Kfo

rpa

rsin

g*

3580

0001

3358

6*

inte

rcon

nect

the

DRBK

and

the

GSDB

K*

3585

0001

3358

7*

open

the

DRBK

*35

9000

0133

588

*if

fail

ed*

3595

0001

3358

9*

then

exit

*36

0000

0133

590

*do

unti

leo

f*

3605

0001

3359

1*

read

the

next

reco

rd*

3610

0001

3359

2*

ifsp

arse

oral

lbl

anks

orco

mmen

t*

3615

0001

3359

3*

then

iter

ate

*36

2000

0133

594

*ge

tane

wJA

MTAB

LE*

3625

0001

3359

5*

call

the

pars

er*

3630

0001

3359

6*

iffa

iled

*36

3500

0133

597

*ge

nera

tean

erro

rme

ssag

e*

3640

0001

3359

8*

iter

ate

*36

4500

0133

599

*ad

dth

eJA

MTAB

LEto

new

chai

n*

3650

0001

3360

0*

end

*36

5500

0133

601

*cl

ose

thefi

le*

3660

0001

3360

2*

rele

aseth

eDR

BK,

GSDB

K,un

used

JAMT

ABLE

*36

6500

0133

603

*if

weha

dno

erro

rs,

*36

7000

0133

604

*th

endo

*36

7500

0133

605

*sw

apth

ene

wch

ain

ofJA

MTAB

LEs

for

theol

d*

3680

0001

3360

6*

rele

ase

theol

dJA

MTAB

LEs

*36

8500

0133

607

*en

d*

3690

0001

3360

8*

else

do*

3695

0001

3360

9*

rele

ase

thene

wJA

MTAB

LEs

*37

0000

0133

610

*en

d*

3705

0001

3361

1*

exit

*37

1000

0133

612

**

3715

0001

3361

3*

Note

that

"exi

t"al

ways

impl

iescl

eanu

pfi

rst.

*37

2000

0133

614

**

3725

0001

3361

5*

End

ofsp

ecif

icat

ions

****

****

****

****

****

****

****

****

****

**37

3000

01

Lin

e ▌3

3570

▐: B

asic

ally

, CP

Exi

t F2

00 l

oad

s a

dat

a fi

lefr

om a

CM

S m

inid

isk.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

3361

7JA

MSAM

LDHC

PENT

ERCA

LL,S

AVE=

DYNA

MIC

3740

0001

3420

3*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

3750

0001

3420

4*

Init

iali

ze:

*37

5500

0134

205

*SA

VEWR

K*

3760

0001

3420

6*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

3765

0001

3420

8*c

mtXC

SAVE

WRK,

SAVE

WRK

HCPS

VCac

tual

lydo

esth

is37

7500

01

3423

6*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

3915

0001

3423

7*

Test

exit

numb

er;le

ave

ifno

tF2

00.

*39

2000

0134

238

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*39

2500

01

0003

8A59

00C0

A000

0A0

3424

0C

R0,=

A(XI

T@F2

00)

Exit

F200

?39

3500

0100

038E

A774

01AE

006E

A34

241

BrNE

LDEX

IT..

no,

leav

e39

4000

01

0003

9218

9134

243

LRR9

,R1

Addr

essof

exit

1200

plis

t39

5000

0134

244

HCPU

SING

X120

0,R9

Addr

essa

bili

ty39

5500

01

3424

8*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

3965

0001

3424

9*

Get

ourco

mpon

ent

IDbl

ock.

*39

7000

0134

250

*If

our

comp

onen

tID

bloc

kdo

esno

tex

ist

(whi

chis

*39

7500

0134

251

*in

dica

ted

byR1

5=4

from

FIND

),th

enwe

need

to*

3980

0001

3425

2*

allo

cate

it.

Allo

cate

will

also

acqu

ireth

eCM

PBK

*39

8500

0134

253

*lo

ckex

clus

ive.

*39

9000

0134

254

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*39

9500

01

Lin

e ▌3

4240

▐: A

litt

le d

efen

sive

pro

gram

min

g he

re.

You

coul

d c

ode

the

sam

e en

try

poin

t fo

r m

ore

than

one

exit

. Whe

ther

you

do

or n

ot, i

t w

ould

be

good

prac

tice

to

veri

fy t

hat

R0

cont

ains

the

exi

t nu

mbe

rth

at y

ou e

xpec

t.

3425

6HC

PXSE

RVFI

ND,C

OMPI

D=’J

AM’

4005

0001

3583

8HC

PCAS

RC(L

D100

,00

:fo

und

X401

0000

1LD

033,

04:no

tfo

und

X401

5000

1LD

EXIT

),08

:ba

dar

gume

ntpa

ssed

X402

0000

1EL

SE=L

DEXI

T??

:in

vali

drc

4025

0001

Lin

e ▌3

4256

▐: H

ere

is h

ow t

o sp

ecif

y yo

urco

mpo

nent

ID

whe

n fi

ndin

g, a

lloca

ting

, dea

lloca

ting

,lo

ckin

g, o

r un

lock

ing.

The

re w

ill b

e at

mos

t on

eco

mpo

nent

ID

blo

ck (

CM

PBK

) fo

r a

spec

ific

com

pone

nt. T

he c

ompo

nent

ID

is

3 ch

arac

ters

lon

g.Yo

u ca

n sp

ecif

y yo

ur c

ompo

nent

ID

in

any

of t

hese

way

s:

HCPX

SERV

xxxx

,COM

PID=

’JAM’

LARx

,DCJ

AMHC

PXSE

RVxx

xx,C

OMPI

D=(R

x)R1

reco

mmen

ded

HCPX

SERV

xxxx

,COM

PID=

DCJA

MDC

JAM

DCC’JA

M’

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

0003

C035

861

LD03

3DS

0H40

3500

0135

862

HCPX

SERV

ALLO

CATE

,COM

PID=

’JAM

’40

4000

01

3744

7HC

PCAS

RC(L

D066

,00

:su

cces

s,lo

ckob

tain

edX4

0450

001

LD10

0,04

:ex

ists

,no

tlo

cked

X405

0000

1LD

EXIT

)08

:pa

ssed

badR1

X405

5000

112

:pa

ssed

badR2

X406

0000

1??

:in

vali

drc

4065

0001

0003

EE37

470

LD06

6DS

0H40

7500

0100

03EE

18A1

3747

1LR

R10,

R1Ad

dres

sof

ourCM

PBK

4080

0001

0003

F0A7

F400

1900

422

3747

2Br

ULD

166

4085

0001

Lin

e ▌3

5861

▐: B

efor

e us

ing

your

com

pone

nt I

D b

lock

,yo

u m

ust

mak

e a

requ

est

to h

ave

it c

reat

ed.

If t

he C

MPB

K w

as a

lloca

ted

by

this

HC

PXSE

RV

AL

LO

CA

TE

:

vR

15 r

etur

ned

to

you

will

con

tain

0.

vYo

u w

ill h

ave

the

CM

PBK

loc

k ex

clus

ive;

you

will

need

to

UN

LO

CK

EX

CL

USI

VE

lat

er. T

hepr

esum

ptio

n is

tha

t yo

u in

tend

to

init

ializ

e th

eco

ntro

l bl

ock

and

tha

t yo

u d

o no

t w

ant

any

inte

rfer

ence

.

vT

he C

MPB

K w

ill b

e in

itia

lized

to

bina

ry z

eros

.

vR

1 re

turn

ed t

o yo

u w

ill c

onta

in t

he a

dd

ress

of

the

CM

PBK

.

If t

he C

MPB

K w

as n

ot a

lloca

ted

by

this

HC

PXSE

RV

AL

LO

CA

TE

:

vR

15 r

etur

ned

to

you

will

con

tain

4 (

assu

min

g al

lar

gum

ents

wer

e va

lid).

vYo

u w

ill n

ot h

ave

the

CM

PBK

loc

k.

vR

1 re

turn

ed t

o yo

u w

ill c

onta

in t

he a

dd

ress

of

the

CM

PBK

.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

0003

F437

474

LD10

0DS

0H40

9500

0137

475

HCPX

SERV

LOCK

EXCL

USIV

E,CO

MPID

=’JA

M’41

0000

01

3905

7HC

PCAS

RC(L

D133

,00

:su

cces

sX4

1050

001

LD03

3,04

:no

tfo

und

X411

0000

1LD

EXIT

,08

:pa

ssed

badR1

X411

5000

1LD

033,

12:lo

ckwa

sde

lete

dX4

1200

001

LDEX

IT),

16:so

meth

ing

else

bad

X412

5000

1EL

SE=L

DEXI

T??

:in

vali

drc

4130

0001

0004

2039

084

LD13

3DS

0H41

4000

0100

0420

18A1

3908

5LR

R10,

R1Ad

dres

sof

ourCM

PBK

4145

0001

0004

2239

087

LD16

6DS

0H41

5500

0100

0422

9601

D058

0005

839

088

OISA

VEWR

K0,X

’01’

CMPB

Kis

lock

edex

clus

ive

4160

0001

3908

9HC

PUSI

NGCM

PBK,

R10

Addr

essa

bili

ty41

6500

01

3909

3*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4175

0001

3909

4*

Befo

rewe

goan

yfu

rthe

r,le

t’s

seeif

exit

F200

has

*41

8000

0139

095

*be

come

disa

bled

.If

so,we

will

assu

meit

isbe

caus

e*

4185

0001

3909

6*

anot

herin

stan

ceof

this

exit

has

alre

adydo

newh

atwe

*41

9000

0139

097

*in

tend

edto

do.

Ther

efor

e,we

can

simp

lyre

turn

and

*41

9500

0139

098

*ex

pect

that

the

JAMT

ABLE

data

stru

ctur

eha

sbe

enbu

ilt.

*42

0000

0139

099

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*42

0500

01

Lin

e ▌3

7474

▐: I

f th

e H

CPX

SER

V A

LL

OC

AT

E d

id n

otcr

eate

a n

ew C

MPB

K b

ecau

se i

t al

read

y ex

iste

d, t

hen

excl

usiv

e co

ntro

l ov

er t

he C

MPB

K w

as n

ot g

rant

ed.

We

need

to

get

excl

usiv

e co

ntro

l be

fore

pro

ceed

ing.

3910

1HC

PXSE

RVTE

ST,E

XIT=

F200

,If

exit

F200

disa

bled

,qu

itX4

2150

001

DISA

BLED

=LD7

0042

2000

01

Lin

e ▌3

9101

▐: T

his

is h

ow a

ny e

xit

can

be t

este

d f

oren

able

d o

r d

isab

led

.

vIf

ena

bled

, exe

cuti

on c

onti

nues

at

the

next

inst

ruct

ion.

vIf

dis

able

d, e

xecu

tion

con

tinu

es a

t th

e'D

ISA

BL

ED

=' l

abel

.

'EX

IT=

' cou

ld b

e sp

ecif

ied

in

a re

gist

er, a

s in

'EX

IT=

(Rx)

'.

3911

4HC

PXSE

RVDI

SABL

E,EX

IT=F

200

Disa

bleit

for

next

task

4230

0001

Lin

e ▌3

9114

▐: T

his

is h

ow a

ny e

xit

can

be d

isab

led

.'E

XIT

=' c

ould

be

spec

ifie

d i

n a

regi

ster

, as

in'E

XIT

=(R

x)'.

4072

4*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4240

0001

4072

5*

Get

aDR

BK,

save

its

addr

essin

SAVE

WRK2

.*

4245

0001

4072

6*

Fill

inth

eDR

BK.

*42

5000

0140

727

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*42

5500

01

Lin

e ▌4

0724

▐: T

he D

RB

K i

s th

e co

ntro

l bl

ock

used

in

all

requ

ests

to

read

a C

MS

file

. It

is a

nalo

gous

to

the

CM

S co

ntro

l bl

ock

FSC

B.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

4072

9HC

PGET

STID

=DRB

KGe

taDa

taRe

ques

tBl

ock

4265

0001

0004

7658

10C0

B000

0B0

4115

5+L

R1,=

F’14

88’

CBI

offs

et@V

RGAB

RP01

-HCP

GE00

047A

4142

0+DC

0AL4

(HCP

FREE

)Fo

rce

acr

oss

refe

renc

e@V

83HP

M803

-HCP

XR00

047A

58F0

0950

0095

041

974+

LR1

5,PF

XFRE

E@V

RGB1

QY03

-HCP

CA42

159+

*cmt

MVI

PFXI

ACR,

SACP

RIM/

256

Call

ermo

dule

’sTm

ode

@VRG

B1QY

4216

0+*c

mtMV

IPF

XIAC

E,SA

CPRI

M/25

6Ca

llee

entr

y’s

Tmod

e@V

RGB1

QY42

161+

*cmt

SACF

SACP

RIM

Ente

rne

eded

Tmod

e@V

RGB1

QY00

047E

0CEF

4234

7+BA

SSM

R14,

R15

Stat

icli

nkag

e,se

tAm

ode

@VRG

B1QY

03-H

CPCA

4253

4+*c

mtSA

CFSA

CPRI

MRe

stor

eca

ller

’sTm

ode

@VRG

B1QY

0004

8018

4142

720

LRR4

,R1

Addr

ess

ofDR

BK42

7000

0142

721

HCPU

SING

DRBK

,R4

Addr

essa

bili

ty42

7500

0100

0482

5040

D060

0006

042

724

STR4

,SAV

EWRK

2Sa

veth

ead

dres

s42

8000

01

0004

86D2

0740

28C0

7800

028

0007

842

726

MVC

DRBF

IDFN

,=CL

(L’D

RBFI

DFN)’J

AMTA

BLE’

fnam

e42

9000

0100

048C

D207

4030

C080

0003

000

080

4272

7MV

CDR

BFID

FT,=

CL(L

’DRB

FIDF

T)’S

OURC

E’ft

ype

4295

0001

0004

92D2

0140

7CC1

0200

07C

0010

242

728

MVC

DRBA

CSBX

,=FL

(L’D

RBAC

SBX)’-

1’fm

ode

=’*’

4300

0001

4272

9*c

mtMV

CDR

BREC

NO,=

FL(L

’DRB

RECN

O)’0

’43

0500

01

0004

98D2

0340

6CC0

B400

06C

000B

442

731

MVC

DRBB

UFSZ

,=FL

(L’D

RBBU

FSZ)’4

000’

4315

0001

4273

2CK

MAIN

T40

00,G

T,FR

EMX*

8-GS

DHLE

N43

2000

01

4273

7*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4330

0001

4273

8*

Get

ama

ximu

msi

zeGS

DBK,

save

its

addr

ess

inSA

VEWR

K3.

*43

3500

0142

739

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*43

4000

01

4274

1HC

PGET

STID

=GSD

BK,L

EN=F

REMX

Get

abi

gGS

DBK

4350

0001

0004

AC18

3144

309

LRR3

,R1

Addr

essof

GSDB

K43

5500

0144

310

HCPU

SING

GSDB

K,R3

Addr

essa

bili

ty43

6000

0100

04AE

5030

D064

0006

444

313

STR3

,SAV

EWRK

3Sa

veth

ead

dres

s43

6500

01

0004

B2D2

0130

0AC1

0400

00A

0010

444

315

MVC

GSDF

RESZ

,=AL

(L’G

SDFR

ESZ)

(FRE

MX)

size

4375

0001

4431

7*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4385

0001

4431

8*

Inte

rcon

nect

the

DRBK

andth

eGS

DBK.

*43

9000

0144

319

*We

will

setu

pDR

BBUF

ADto

poin

tto

GSDD

ATA

soth

atwh

en*

4395

0001

4432

0*

were

ada

reco

rdit

will

bepl

aced

righ

tin

toth

eGS

DBK,

*44

0000

0144

321

*al

most

read

yfo

rpa

rsin

g.*

4405

0001

4432

2*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4410

0001

Lin

e ▌4

0729

▐: H

ere

is a

n ex

pans

ion

of a

HC

PGE

TST

mac

ro r

eque

st. T

he e

xpan

sion

inc

lud

es c

omm

ent

stat

emen

ts t

hat

mig

ht n

ot b

e co

mm

ents

if

a d

iffe

rent

set

of m

odul

e an

d e

ntry

poi

nt a

ttri

bute

s w

ere

assi

gned

to

the

calle

r an

d t

o th

e ca

llee.

The

MV

Iin

stru

ctio

ns m

ight

act

ually

sav

e va

lues

oth

er t

han

SAC

PRIM

. The

SA

CF

inst

ruct

ions

mig

ht s

et P

SWtr

ansl

atio

ns m

ode

to s

omet

hing

oth

er t

han

Prim

ary

Spac

e m

ode.

Lin

kage

ser

vice

s d

epen

d o

n ac

cura

teat

trib

ute

def

init

ions

.

0004

B841

1030

1000

010

4432

4LA

R1,G

SDDA

TA44

2000

0100

04BC

5010

4068

0006

844

325

STR1

,DRB

BUFA

DDR

BBUF

AD--

>GS

DDAT

A44

2500

01

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

4432

7*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4435

0001

4432

8*

Open

theDR

BK.

*44

4000

0144

329

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*44

4500

01

0004

C041

1040

0000

000

4433

1LA

R1,D

RBK

Open

theDR

BK44

5500

0144

332

HCPC

ALL

HCPZ

IOPN

4460

0001

0004

CED5

0140

7EC1

0600

07E

0010

645

909

CLC

DRBR

ETCD

,=AL

(L’D

RBRE

TCD)

(DRB

OK)

Succ

ess?

4470

0001

0004

D4A7

7400

8E00

5F0

4591

0Br

NELD

433

,..

no44

7500

01

4591

2*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4485

0001

4591

3*

Read

thefi

leun

til

were

ach

e-o-

f.*

4490

0001

4591

4*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4495

0001

0004

D845

916

LD20

0DS

0H45

0500

0100

04D8

5830

D064

0006

445

917

LR3

,SAV

EWRK

3Fi

xR3

befo

rewe

cras

h45

1000

0100

04DC

5840

D060

0006

045

918

LR4

,SAV

EWRK

2Fi

xR4

befo

rewe

cras

h45

1500

01

Lin

e ▌4

4327

▐: T

his

is h

ow y

ou o

pen

a C

MS

file

for

read

ing.

Aft

er y

ou o

pen

the

file

, che

ck t

he r

etur

n co

de

inD

RB

RE

TC

D. T

he r

etur

n co

des

are

def

ined

in

HC

PDR

BK

CO

PY.

0004

E041

0000

0100

001

4591

9LA

R0,1

Incr

emen

tto

next

reco

rd45

2000

0100

04E4

5A00

405C

0005

C45

920

AR0

,DRB

RECN

O*

4525

0001

0004

E850

0040

5C00

05C

4592

1ST

R0,D

RBRE

CNO

*45

3000

01

0004

EC41

1040

0000

000

4592

3LA

R1,D

RBK

Read

are

cord

4540

0001

4592

4HC

PCAL

LHC

PZIG

ET*

4545

0001

0004

FAD5

0140

7EC1

0800

07E

0010

847

501

CLC

DRBR

ETCD

,=AL

(L’D

RBRE

TCD)

(DRB

EOF)

e-o-

f?45

5500

0100

0500

A784

0095

0062

A47

502

BrE

LD53

3,

..ye

s45

6000

0100

0504

D501

407E

C106

0007

E00

106

4750

3CL

CDR

BRET

CD,=

AL(L

’DRB

RETC

D)(D

RBOK

)Su

cces

s?45

6500

0100

050A

A774

006D

005E

447

504

BrNE

LD40

0,

..no

4570

0001

4750

6*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4580

0001

4750

7*

Ifth

ere

cord

was

empt

y,th

enit

erat

e.*

4585

0001

4750

8*

Ifth

ere

cord

isaco

mmen

t,th

enit

erat

e.*

4590

0001

4750

9*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4595

0001

0005

0E91

2040

5500

055

4751

1TM

DRBF

LAG2

,DRB

SPAR

SSp

arse

file

?46

0500

0100

0512

A714

FFE3

004D

847

512

BrO

LD20

0..

yes,

try

thene

xtre

cord

4610

0001

0005

16D5

0340

7040

6C00

070

0006

C47

514

CLC

DRBR

ECSZ

,DRB

BUFS

ZBi

gger

than

buff

er?

4620

0001

0005

1CA7

2400

5E00

5D8

4751

5Br

HLD

366

..ye

s,er

ror

4625

0001

0005

2058

0040

6800

068

4751

7L

R0,D

RBBU

FAD

A(da

ta)

4635

0001

0005

2458

1040

7000

070

4751

8L

R1,D

RBRE

CSZ

L’da

ta46

4000

0147

519

*cmt

LAR1

4,0

Imma

teri

al46

4500

0100

0528

58F0

C0C8

000C

847

520

LR1

5,=A

L1(C

’’,

0,0,

0)(p

ad=C

’’,

leng

th=0

)46

5000

0100

052C

0F0E

4752

1CL

CLR0

,R14

Allbl

anks

?46

5500

0100

052E

A784

FFD5

004D

847

522

BrE

LD20

0..

yes,

try

thene

xtre

cord

4660

0001

0005

3295

5C30

1000

010

4752

4CL

IGS

DDAT

A,C’

*’Co

mmen

t?46

7000

0100

0536

A784

FFD1

004D

847

525

BrE

LD20

0..

yes,

try

thene

xtre

cord

4675

0001

Lin

e ▌4

5919

▐: T

his

is h

ow t

o re

ad t

he n

ext

reco

rd i

na

CM

S fi

le.

All

I/O

to

a C

MS

file

is

by r

ecor

d n

umbe

r; t

here

is

no “

get

next

” re

ques

t. T

here

is

no r

eque

st f

or m

ore

than

a s

ingl

e re

cord

.

CM

S fi

le I

/O

is

not

inte

nded

to

be a

hig

h pe

rfor

mer

,be

caus

e it

is

expe

cted

tha

t C

P w

ill n

ot b

e re

adin

gla

rge

quan

titi

es o

f C

MS

dat

a.

Che

ck t

he r

etur

n co

de

in D

RB

RE

TC

D a

fter

war

d.

Forg

et a

bout

RE

CFM

. Whe

ther

the

file

is

F or

V, y

oush

ould

alw

ays

use

DR

BR

EC

SZ a

s th

e si

ze o

f th

ere

cord

tha

t w

as r

ead

. Do

not

requ

ire

any

part

icul

arR

EC

FM, b

ecau

se i

t ju

st a

dd

s bu

rden

to

the

pers

oncr

eati

ng t

he f

ile.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

0005

3A58

0040

7000

070

4752

7L

R0,D

RBRE

CSZ

Copy

reco

rdsi

zeto

GSDB

K46

8500

0100

053E

4000

300E

0000

E47

528

STH

R0,G

SDDC

NT*

4690

0001

0005

4241

0000

0000

000

4752

9LA

R0,0

Star

tpa

rsin

gfr

omth

ebe

ginn

ing

4695

0001

0005

4640

0030

0C00

00C

4753

0ST

HR0

,GSD

SCAN

*47

0000

01

4753

2*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4710

0001

4753

3*

Ifwe

have

are

ady

JAMT

ABLE

bloc

k,us

eit

.*

4715

0001

4753

4*

Ifwe

don’

t,th

enal

loca

teon

e.*

4720

0001

4753

5*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4725

0001

0005

4A58

70D0

7400

074

4753

7L

R7,S

AVEW

RK7

Addr

essof

JAMT

ABLE

,or

zero

4735

0001

0005

4E12

7747

538

LTR

R7,R

7An

y?47

4000

0100

0550

A724

000C

0056

847

539

BrP

LD23

3..

yes,

use

it47

4500

01

4754

1HC

PGET

STLE

N=0+

(JAM

TABL

N+7)

/847

5500

0100

0562

1871

4910

8LR

R7,R

1Ad

dres

sof

ane

wJA

MTAB

LE47

6000

0100

0564

5070

D074

0007

449

109

STR7

,SAV

EWRK

7Sa

vead

dres

sof

JAMT

ABLE

4765

0001

0005

6849

111

LD23

3DS

0H47

7500

0149

112

HCPU

SING

JAMT

ABLE

,R7

Addr

essa

bili

ty47

8000

01

4911

6*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4790

0001

4911

7*

Call

thepa

rser

.*

4795

0001

4911

8*

*48

0000

0149

119

*Pa

rtof

what

the

pars

erdo

esis

tocl

ear

the

prim

ary

*48

0500

0149

120

*pl

ist

tobi

nary

zero

s.*

4810

0001

4912

1*

*48

1500

0149

122

*By

pass

ing

R3wi

thth

ead

dres

sof

the

HCPC

FDEF

*48

2000

0149

123

*th

atwe

want

,we

are

actu

ally

pret

endi

ngth

atwe

pars

ed*

4825

0001

4912

4*

off

thefi

rst

toke

nan

dus

edit

tofi

ndth

eHC

PCFD

EFth

at*

4830

0001

4912

5*

wewa

nt.

*48

3500

0149

126

**

4840

0001

4912

7*

Ifth

epa

rser

dete

cted

asy

ntax

erro

r,th

enwe

will

queu

e*

4845

0001

4912

8*

the

erro

rGS

DBK

that

thepa

rser

gene

rate

dan

daGS

DBK

to*

4850

0001

4912

9*

tell

theop

erat

orwh

atre

cord

was

bad.

*48

5500

0149

130

*Lo

opfo

ran

othe

rre

cord

.*

4860

0001

4913

1*

*48

6500

0149

132

*We

will

use

X120

0TRT

asasc

ratc

har

eain

orde

rto

leav

e*

4870

0001

4913

3*

X120

0UWD

alon

e.We

anti

cipa

teth

atus

esof

X120

0TRT

by*

4875

0001

4913

4*

othe

rex

itro

utin

eswo

uld

betr

ansi

tory

inth

ese

nse

that

*48

8000

0149

135

*su

chro

utin

eswo

uld

init

iali

zeth

eTR

Tar

eabe

fore

use.

*48

8500

0149

136

*Th

eus

erwo

rds

area

(X12

00UW

D)ar

edo

cume

nted

asa

*48

9000

0149

137

*su

gges

ted

area

forex

itro

utin

esto

pass

data

toea

ch*

4895

0001

4913

8*

othe

r.If

weav

oid

the

user

word

s,we

won’

ttr

omp

onan

y*

4900

0001

4913

9*

such

shar

ing.

*49

0500

0149

140

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*49

1000

01

0005

6858

2090

0800

008

4914

2L

R2,X

1200

TRT

Addi

tion

alba

ses

4920

0001

0005

6C41

F000

0000

000

4914

3LA

R15,

PFXP

GAn

addi

tion

alba

se49

2500

0100

0570

50F0

2000

0000

049

144

STR1

5,0(

,R2)

*49

3000

01

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

0005

7441

00C7

D800

7D8

4914

6LA

R0,S

YNTA

XAd

dres

sof

HCPD

OSYN

4940

0001

0005

7841

1070

0000

000

4914

7LA

R1,J

AMTA

BLE

Addr

essof

prim

arypl

ist

4945

0001

4914

8*c

mtL

R2,X

1200

TRT

Addi

tion

alba

ses

4950

0001

0005

7C41

30C8

3D00

83D

4914

9LA

R3,C

FAd

dres

sof

HCPC

FDEF

4955

0001

0005

8058

40D0

6400

064

4915

0L

R4,S

AVEW

RK3

Addr

essof

GSDB

K49

6000

01

4915

1HC

PCAL

LHC

PZPR

PGPa

rse

the

GSDB

Kli

ne49

6500

0100

058E

5830

D064

0006

450

727

LR3

,SAV

EWRK

3Fi

xR3

befo

rewe

cras

h49

7000

0100

0592

5840

D060

0006

050

728

LR4

,SAV

EWRK

2Fi

xR4

befo

rewe

cras

h49

7500

0100

0596

12FF

5072

9LT

RR1

5,R1

5Ch

eck

out

retu

rnco

de49

8000

0100

0598

A784

0034

0060

050

730

BrZ

LD46

6..

succ

ess

4985

0001

5073

2*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

4995

0001

5073

3*

Bad

synt

axde

tect

edby

the

pars

er.

*50

0000

0150

734

*Co

nnec

tth

eer

ror

mess

ageGS

DBK

toan

yex

isti

ngon

es.

*50

0500

0150

735

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*50

1000

01

Lin

e ▌4

9151

▐: P

arsi

ng t

he c

onte

nts

of a

GSD

BK

.

We

are

pass

ing

the

follo

win

g re

gist

ers

to p

arse

r en

try

poin

t H

CPZ

PRPG

:

R0

Con

tain

s th

e ad

dre

ss o

f th

e H

CPD

OSY

Nm

acro

.

R1

Con

tain

s th

e ad

dre

ss o

f th

e pr

imar

y PL

IST,

as s

peci

fied

by

the

'PL

=' p

aram

eter

of

the

HC

PDO

SYN

mac

ro.

R2

Con

tain

s ei

ther

:

vZ

ero

vT

he a

dd

ress

of

the

'BA

SES=

' PL

IST,

as

spec

ifie

d o

n th

e H

CPD

OSY

N m

acro

.

R3

Con

tain

s ei

ther

:

vZ

ero

vT

he a

dd

ress

of

the

HC

PCFD

EF

mac

ro.

R4

Con

tain

s th

e ad

dre

ss o

f th

e G

SDB

K t

hat

we

are

pars

ing.

On

retu

rn, t

he f

ollo

win

g re

gist

ers

cont

ain

info

rmat

ion:

R0

Con

tain

s ei

ther

:

vZ

ero,

if

ther

e w

ere

no s

ynta

x er

rors

vA

non

zero

ret

urn

cod

e, i

f th

ere

wer

esy

ntax

err

ors.

R15

Con

tain

s a

retu

rn c

ode

of:

vZ

ero,

if

ther

e w

ere

no s

ynta

x er

rors

vN

onze

ro, i

f th

ere

wer

e sy

ntax

err

ors.

Err

or m

essa

ges

will

hav

e be

en w

ritt

en u

nles

sR

ET

GSD

BK

=xx

x w

as s

peci

fied

on

the

HC

PDO

SYN

mac

ro. R

efer

to

line

7051

7 be

low

.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

0005

9C58

1070

0000

000

5073

7L

R1,J

AMTG

SDAd

dres

sof

erro

rGS

DBK

5020

0001

0005

A058

30D0

5C00

05C

5073

9L

R3,S

AVEW

RK1

Addr

essof

firs

t,or

zero

5030

0001

0005

A4D5

03D0

5C0A

0000

05C

00A0

050

740

CLC

SAVE

WRK1

,PFX

0Ach

ain

tose

arch

?50

3500

0100

05AA

A774

0006

005B

650

741

BrNE

LD26

6..

yes,

gose

arch

it50

4000

01

0005

AE50

10D0

5C00

05C

5074

3ST

R1,S

AVEW

RK1

Addr

essof

thene

xt50

5000

0100

05B2

A7F4

000D

005C

C50

744

BrU

LD33

3Sa

ywh

ich

reco

rdis

bad

5055

0001

0005

B650

746

LD26

6DS

0H50

6500

0100

05B6

D503

3000

0A00

0000

000

A00

5074

7CL

CGS

DNEX

T,PF

X0An

othe

rfo

llow

s?50

7000

0100

05BC

A784

0006

005C

850

748

BrE

LD30

0..

no,

add

this

one

5075

0001

0005

C058

3030

0000

000

5074

9L

R3,G

SDNE

XTAd

dres

sof

thene

xt50

8000

0100

05C4

A7F4

FFF9

005B

650

750

BrU

LD26

6Co

ntin

uelo

okin

g50

8500

01

0005

C850

752

LD30

0DS

0H50

9500

0100

05C8

5010

3000

0000

050

753

STR1

,GSD

NEXT

Addr

essof

thene

xt51

0000

01

5075

5*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5110

0001

5075

6*

Add

aner

ror

mess

age

GSDB

Kth

atin

dica

teswh

ich

reco

rd*

5115

0001

5075

7*

fail

edpa

rsin

g.*

5120

0001

5075

8*

Goba

ckan

dre

adth

ene

xtre

cord

.*

5125

0001

5075

9*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5130

0001

0005

CC50

761

LD33

3DS

0H51

4000

0100

05CC

5800

C0D0

000D

050

762

LR0

,=A(

MS67

0001

)Er

ror

mess

agenu

mber

5145

0001

0005

D0A7

8500

9300

6F6

5076

3Br

ASR8

,LDE

RRFo

rmat

the

GSDB

K51

5000

0100

05D4

A7F4

FF82

004D

850

764

BrU

LD20

0Go

read

anot

her

reco

rd51

5500

01

5076

6*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5165

0001

5076

7*

Add

aner

ror

mess

age

GSDB

Kth

atin

dica

testh

atth

e*

5170

0001

5076

8*

reco

rdis

toolo

ng.

*51

7500

0150

769

*Go

back

and

read

the

next

reco

rd.

*51

8000

0150

770

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*51

8500

0100

05D8

5077

1LD

366

DS0H

5190

0001

0005

D858

00C0

D400

0D4

5077

2L

R0,=

A(MS

6707

02)

Erro

rme

ssag

enu

mber

5195

0001

0005

DCA7

8500

8D00

6F6

5077

3Br

ASR8

,LDE

RRFo

rmat

the

GSDB

K52

0000

0100

05E0

A7F4

FF7C

004D

850

774

BrU

LD20

0Go

read

anot

her

reco

rd52

0500

01

5077

6*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5215

0001

5077

7*

Add

aner

ror

mess

age

GSDB

Kth

atin

dica

testh

atwe

had

*52

2000

0150

778

*an

I/O

erro

r.*

5225

0001

5077

9*

Goba

ckan

dre

adth

ene

xtre

cord

.*

5230

0001

5078

0*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5235

0001

Lin

e ▌5

0737

▐: R

emem

ber

the

HC

PDO

SYN

key

wor

d'R

ET

GSD

BK

=JA

MT

GSD

'?

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

0005

E450

782

LD40

0DS

0H52

4500

0100

05E4

5800

C0D8

000D

850

783

LR0

,=A(

MS67

0201

)Er

ror

mess

agenu

mber

5250

0001

0005

E8A7

8500

8700

6F6

5078

4Br

ASR8

,LDE

RRFo

rmat

the

GSDB

K52

5500

0100

05EC

A7F4

FF76

004D

850

785

BrU

LD20

0Go

read

anot

her

reco

rd52

6000

01

5078

7*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5270

0001

5078

8*

Add

aner

ror

mess

age

GSDB

Kth

atin

dica

testh

atwe

cann

ot*

5275

0001

5078

9*

find

thefi

le.

*52

8000

0150

790

*Qu

ital

toge

ther

.*

5285

0001

5079

1*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5290

0001

0005

F050

793

LD43

3DS

0H53

0000

0100

05F0

5800

C0DC

000D

C50

794

LR0

,=A(

MS67

0301

)Er

ror

mess

agenu

mber

5305

0001

0005

F4A7

8500

8100

6F6

5079

5Br

ASR8

,LDE

RRFo

rmat

the

GSDB

K53

1000

0100

05F8

A785

00D4

007A

050

796

BrAS

R8,L

DUNL

OCK

Unlo

ckou

rCM

PBK

5315

0001

0005

FCA7

F400

3B00

672

5079

7Br

ULD

633

Clea

nupan

dre

turn

5320

0001

5079

9*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5330

0001

5080

0*

Conn

ectth

ene

wJA

MTAB

LEto

our

newch

ain

ofJA

MTAB

LEs.

*53

3500

0150

801

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*53

4000

01

0006

0050

803

LD46

6DS

0H53

5000

0100

0600

5810

D06C

0006

C50

804

LR1

,SAV

EWRK

5Cu

rren

tla

st53

5500

0100

0604

1211

5080

5LT

RR1

,R1

Anyhe

re?

5360

0001

0006

06A7

D400

0900

618

5080

6Br

NPLD

500

..no

,th

isis

the

firs

t53

6500

01

0006

0A50

7010

0000

000

5080

8ST

R7,J

AMTF

WD-J

AMTA

BLE(

,R1)

5375

0001

0006

0E1F

7750

809

SLR

R7,R

7No

empt

yJA

MTAB

LE53

8000

0100

0610

5070

D074

0007

450

810

STR7

,SAV

EWRK

7Cl

ear

away

here

,to

o53

8500

0100

614

A7F4

FF62

004D

850

811

BrU

LD20

0Go

read

anot

her

reco

rd53

9000

01

0006

1850

813

LD50

0DS

0H54

0000

0100

0618

5070

D068

0006

850

814

STR7

,SAV

EWRK

4Re

memb

erfi

rst

new

JAMT

ABLE

5405

0001

0006

1C50

70D0

6C00

06C

5081

5ST

R7,S

AVEW

RK5

Reme

mber

last

new

JAMT

ABLE

5410

0001

0006

201F

7750

816

SLR

R7,R

7No

empt

yJA

MTAB

LE54

1500

0100

0622

5070

D074

0007

450

817

STR7

,SAV

EWRK

7Cl

ear

away

here

,to

o54

2000

0100

0626

A7F4

FF59

004D

850

818

BrU

LD20

0Go

read

anot

her

reco

rd54

2500

01

5082

0*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5435

0001

5082

1*

E-o-

f.*

5440

0001

5082

2*

Clos

eth

efi

le.

*54

4500

0150

823

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*54

5000

01

0006

2A50

825

LD53

3DS

0H54

6000

0100

062A

4110

4000

0000

050

826

LAR1

,DRB

KCl

ose

the

DRBK

5465

0001

5082

7HC

PCAL

LHC

PZIC

LS54

7000

01

Lin

e ▌5

0820

▐: A

lway

s cl

ose

the

CM

S fi

le b

efor

e yo

ure

leas

e th

e D

RB

K.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

5240

4*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5480

0001

5240

5*

Ifwe

had

noer

ror,

*54

8500

0152

406

*th

enin

stal

lou

rne

wch

ain

ofJA

MTAB

LEs

*54

9000

0152

407

*el

sefr

eeou

rne

wch

ain

ofJA

MTAB

LEs

*54

9500

0152

408

**

5500

0001

5240

9*

What

wedo

isca

use

SAVE

WRK4

topo

int

towh

atev

eris

to*

5505

0001

5241

0*

befr

eed,

whet

herth

isis

the

old

chai

nof

JAMT

ABLE

sth

at*

5510

0001

5241

1*

wear

ere

plac

ing,

orth

ene

wch

ain

that

wewe

rebu

ildi

ng.

*55

1500

0152

412

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*55

2000

01

0006

38D5

03D0

5C0A

0000

05C

00A0

052

414

CLC

SAVE

WRK1

,PFX

0Er

ror

GSDB

Kch

ain

empt

y?55

3000

0100

063E

A774

0009

0065

052

415

BrNE

LD56

6..

no,

disc

ardwh

atwe

buil

t55

3500

01

0006

4258

00D0

6800

068

5241

7L

R0,S

AVEW

RK4

R0--

>ne

wch

ain

5545

0001

0006

46D2

03D0

68A0

5400

068

0005

452

418

MVC

SAVE

WRK4

,CMP

USRF

2SA

VEWR

K4--

>ol

dch

ain

5550

0001

0006

4C50

00A0

5400

054

5241

9ST

R0,C

MPUS

RF2

CMPU

SRF2

-->

new

chai

n55

5500

01

0006

5052

421

LD56

6DS

0H55

6500

0100

0650

5810

D068

0006

852

422

LR1

,SAV

EWRK

4Ge

tto

pof

JAMT

ABLE

chai

n55

7000

0100

0654

1211

5242

3LT

RR1

,R1

Anyle

ft?

5575

0001

0006

56A7

D400

0C00

66E

5242

4Br

NPLD

600

..no

,fr

eed

’em

all

5580

0001

0006

5AD2

03D0

6810

0000

068

0000

052

425

MVC

SAVE

WRK4

,JAM

TFWD

-JAM

TABL

E(R1

)55

8500

0152

426

HCPR

ELST

BLOC

K=(R

1)55

9000

0100

066A

A7F4

FFF3

0065

053

994

BrU

LD56

655

9500

01

0006

6E53

996

LD60

0DS

0H56

0500

0100

066E

A785

0099

007A

053

997

BrAS

R8,L

DUNL

OCK

Unlo

ckou

rCM

PBK

5610

0001

5399

9*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5620

0001

5400

0*

Ifwe

have

any

erro

rme

ssag

eGS

DBKs

,*

5625

0001

5400

1*

then

send

them

onto

the

oper

ator

*56

3000

0154

002

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*56

3500

01

0006

7254

004

LD63

3DS

0H56

4500

0100

0672

5830

D05C

0005

C54

005

LR3

,SAV

EWRK

1Ge

tto

pof

GSDB

K56

5000

0100

0676

1233

5400

6LT

RR3

,R3

Anyle

ft?

5655

0001

0006

78A7

D400

1900

6AA

5400

7Br

NPLD

666

..no

,fr

eed

’em

all

5660

0001

0006

7CD2

03D0

5C30

0000

05C

0000

054

008

MVC

SAVE

WRK1

,GSD

NEXT

5665

0001

0006

8241

4030

1000

010

5400

9LA

R4,G

SDDA

TAAd

dres

sof

erro

rme

ssag

e56

7000

0100

0686

4820

300E

0000

E54

010

LHR2

,GSD

DCNT

Leng

thof

erro

rme

ssag

e56

7500

0154

011

HCPC

ONSL

WRIT

E,X5

6800

001

DATA

=((R

4),(

R2))

,DA

TA=(

loca

tion

,len

gth)

X568

5000

1DA

TATY

PE=F

ULLE

MSG,

X569

0000

1DE

STIN

ATIO

N=’O

PERA

TOR’

5695

0001

5567

1HC

PREL

STID

=GSD

BK,B

LOCK

=(R3

)57

0500

01

0006

A6A7

F4FF

E600

672

5724

2Br

ULD

633

5715

0001

0006

AA57

244

LD66

6DS

0H57

2500

01

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

5724

6*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5735

0001

5724

7*

Clea

nupan

dre

turn

.*

5740

0001

5724

8*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5745

0001

0006

AA57

250

LD70

0DS

0H57

5500

0100

06AA

A785

007B

007A

057

251

BrAS

R8,L

DUNL

OCK

Unlo

ckou

rCM

PBK

5760

0001

5725

3*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5770

0001

5725

4*

Rele

aseth

eDR

BK,

the

GSDB

K,an

yun

used

JAMT

ABLE

.*

5775

0001

5725

5*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5780

0001

0006

AE58

10D0

6000

060

5725

7L

R1,S

AVEW

RK2

Addr

essof

DRBK

,if

any

5790

0001

0006

B212

1157

258

LTR

R1,R

157

9500

0100

06B4

A7D4

0007

006C

257

259

BrNP

LD73

358

0000

0157

260

HCPR

ELST

ID=D

RBK,

BLOC

K=(R

1)58

0500

0100

06C2

5882

9LD

733

DS0H

5810

0001

0006

C258

10D0

6400

064

5883

0L

R1,S

AVEW

RK3

Addr

essof

GSDB

K,if

any

5815

0001

0006

C612

1158

831

LTR

R1,R

158

2000

0100

06C8

A7D4

0007

006D

658

832

BrNP

LD76

658

2500

0158

833

HCPR

ELST

ID=G

SDBK

,BLO

CK=(

R1)

5830

0001

0006

D660

402

LD76

6DS

0H58

3500

01

0006

D658

10D0

7400

074

6040

4L

R1,S

AVEW

RK7

Addr

essof

JAMT

ABLE

,if

any

5845

0001

0006

DA12

1160

405

LTR

R1,R

158

5000

0100

06DC

A7D4

0007

006E

A60

406

BrNP

LD80

058

5500

0160

407

HCPR

ELST

BLOC

K=(R

1)58

6000

0100

06EA

6197

5LD

800

DS0H

5865

0001

6197

7*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5875

0001

6197

8*

Retu

rn.

*58

8000

0161

979

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*58

8500

01

0006

EA61

981

LDEX

ITDS

0H58

9500

0100

06EA

D203

D054

0A00

0005

400

A00

6198

2MV

CSA

VER1

5,PF

X0Rc

<--

059

0000

01

6198

4HC

PEXI

TEP

=(JA

MSAM

LD),

SETC

C=NO

5910

0001

0F20

062

542

XIT@

F200

EQU

X’F2

00’

5920

0001

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

6254

4*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5930

0001

6254

5*

Add

aner

ror

mess

age

GSDB

Kth

atin

clud

esth

ere

cord

numb

er*

5935

0001

6254

6*

iner

ror.

*59

4000

0162

547

*Th

esu

bsti

tuti

onte

xtth

atwe

buil

din

GSDD

ATAwi

lllo

ok*

5945

0001

6254

8*

like

this

,as

ifwe

had

asse

mble

dth

ese

DCs.

*59

5000

0162

549

**

5955

0001

6255

0*

DCC’

fnam

e’,X’0

0’*

5960

0001

6255

1*

DCC’

ftyp

e’,X’0

0’*

5965

0001

6255

2*

DCC’

fmod

e’,X’0

0’*

5970

0001

6255

3*

DCC’

recn

umbe

r’,X

’FF’

*59

7500

0162

554

**

5980

0001

6255

5*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

5985

0001

0006

F662

557

LDER

RDS

0H59

9500

0100

06F6

5000

D07C

0007

C62

558

STR0

,SAV

EWRK

9Sa

veth

eme

ssag

enu

mber

6000

0001

0006

FA58

30D0

6400

064

6255

9L

R3,S

AVEW

RK3

FixR3

befo

rewe

cras

h60

0500

0100

06FE

5840

D060

0006

062

560

LR4

,SAV

EWRK

2Fi

xR4

befo

rewe

cras

h60

1000

01

0007

0241

5030

1000

010

6256

2LA

R5,G

SDDA

TAUs

eth

isas

asc

ratc

har

ea60

2000

0100

0706

4100

3010

0001

062

563

LAR0

,GSD

DATA

Clea

rar

eato

buil

dth

e60

2500

0100

070A

5810

C0E4

000E

462

564

LR1

,=F’

4000

’..

.me

ssag

esu

bsti

tuti

on60

3000

0162

565

*cmt

LAR1

4,0

...te

xt60

3500

0100

070E

58F0

C0E8

000E

862

566

LR1

5,=A

L1(0

,0,0

,0)

...(p

ad=x

’00’,

leng

th=0

)60

4000

0100

0712

0E0E

6256

7MV

CLR0

,R14

...

6045

0001

0007

14D2

0750

0040

2800

000

0002

862

568

MVC

0(L’

DRBF

IDFN

,R5)

,DRB

FIDF

NRe

port

fnam

e60

5000

0100

071A

4150

5009

0000

962

569

LAR5

,1+L

’DRB

FIDF

N(,R

5)60

5500

01

0007

1ED2

0750

0040

3000

000

0003

062

571

MVC

0(L’

DRBF

IDFT

,R5)

,DRB

FIDF

TRe

port

ftyp

e60

6500

0100

0724

4150

5009

0000

962

572

LAR5

,1+L

’DRB

FIDF

T(,R

5)60

7000

01

0007

2848

1040

7C00

07C

6257

4LH

R1,D

RBAC

SBX

Repo

rtfm

ode

6080

0001

6257

5HC

PCAL

LHC

PCVU

BM*

6085

0001

0007

3218

F064

094

LRR1

5,R0

*60

9000

0100

0734

06F0

6409

5BC

TRR1

5,0

*60

9500

0100

0736

44F0

C79A

0079

A64

096

EXR1

5,LD

MVC

*MV

C0(

*-*,

R5),

0(R1

)61

0000

0100

073A

415F

5002

0000

264

097

LAR5

,1+1

(R15

,R5)

Addr

essof

next

fiel

d61

0500

0100

073E

5810

405C

0005

C64

098

LR1

,DRB

RECN

ORe

port

reco

rdnu

mber

6110

0001

6409

9HC

PCAL

LHC

PCVT

RM*

6115

0001

0007

4818

F065

639

LRR1

5,R0

*61

2000

0100

074A

06F0

6564

0BC

TRR1

5,0

*61

2500

0100

074C

44F0

C79A

0079

A65

641

EXR1

5,LD

MVC

*MV

C0(

*-*,

R5),

0(R1

)61

3000

0100

0750

415F

5002

0000

265

642

LAR5

,1+1

(R15

,R5)

Addr

essof

next

fiel

d61

3500

01

0007

5406

5065

644

BCTR

R5,0

Back

upto

last

sepa

rato

rby

te61

4500

0100

0756

92FF

5000

0000

065

645

MVI

0(R5

),X’

FF’

Inse

rtsu

bsti

tuti

onte

rmin

ator

6150

0001

0007

5A58

50D0

7C00

07C

6564

6L

R5,S

AVEW

RK9

Theme

ssag

enu

mber

6155

0001

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

6564

7HC

PCON

SLWR

ITE,

X616

0000

1CO

MPID

=’JA

M’,

X616

5000

1DA

TATY

PE=F

ULLE

MSG,

X617

0000

1DE

STIN

ATIO

N=GS

DBK,

X617

5000

1RE

POSN

UM=(

R5),

X618

0000

1RE

TGSD

BKAD

DR=(

R1),

X618

5000

1SU

BDAT

A=GS

DDAT

A61

9000

01

6725

7*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

6200

0001

6725

8*

Conn

ectth

eer

ror

mess

ageGS

DBK

toan

yex

isti

ngon

es.

*62

0500

0167

259

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*62

1000

01

0007

6E58

30D0

5C00

05C

6726

1L

R3,S

AVEW

RK1

Addr

essof

firs

t,or

zero

6220

0001

0007

72D5

03D0

5C0A

0000

05C

00A0

067

262

CLC

SAVE

WRK1

,PFX

0Ach

ain

tose

arch

?62

2500

0100

0778

A774

0005

0078

267

263

BrNE

LDE1

0..

yes,

sear

chit

6230

0001

0007

7C50

10D0

5C00

05C

6726

5ST

R1,S

AVEW

RK1

Addr

essof

thene

xt62

4000

0100

0780

07F8

6726

6BR

R8Re

turn

6245

0001

0007

8267

268

LDE1

0DS

0H62

5500

0100

0782

D503

3000

0A00

0000

000

A00

6726

9CL

CGS

DNEX

T,PF

X0An

othe

rfo

llow

s?62

6000

0100

0788

A784

0006

0079

467

270

BrE

LDE2

0..

no,

add

this

one

6265

0001

0007

8C58

3030

0000

000

6727

1L

R3,G

SDNE

XTAd

dres

sof

thene

xt62

7000

0100

0790

A7F4

FFF9

0078

267

272

BrU

LDE1

0Co

ntin

uelo

okin

g62

7500

01

0007

9467

274

LDE2

0DS

0H62

8500

0100

0794

5010

3000

0000

067

275

STR1

,GSD

NEXT

Addr

essof

thene

xt62

9000

0100

0798

07F8

6727

6BR

R8Re

turn

6295

0001

0007

9AD2

0050

0010

0000

000

0000

067

278

LDMV

CMV

C0(

*-*,

R5),

0(R1

)Re

mote

inst

ruct

ion

6305

0001

6728

0*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

6315

0001

6728

1*

Asi

mple

"Unl

ock

the

CMPB

K"su

brou

tine

,fo

rJA

MSAM

DLan

d*

6320

0001

6728

2*

for

JAMS

AMLD

.*

6325

0001

6728

3*

*63

3000

0167

284

*if

SAVE

WRK0

=X’

01’

*63

3500

0167

285

*th

enUN

LOCK

EXCL

USIV

E*

6340

0001

6728

6*

ifSA

VEWR

K0=X’

02’

*63

4500

0167

287

*th

enUN

LOCK

SHAR

ED*

6350

0001

6728

8*

*63

5500

0167

289

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*63

6000

01

0007

A067

291

LDUN

LOCK

DS0H

Unlo

ckou

rCM

PBK

6370

0001

0007

A091

03D0

5800

058

6729

2TM

SAVE

WRK0

,X’0

3’Sh

ared

orEx

clus

ive?

6375

0001

0007

A407

8867

293

BZR

R8..

neit

her

6380

0001

0007

A691

02D0

5800

058

6729

5TM

SAVE

WRK0

,X’0

2’Sh

ared

?63

9000

0100

07AA

A714

000C

007C

267

296

BrO

LDUN

200

..ye

s63

9500

01

Lin

e ▌6

5647

▐: W

riti

ng m

essa

ges

from

a l

ocal

mes

sage

repo

sito

ry.

Her

e is

how

to

spec

ify

your

com

pone

nt I

D f

or y

our

own

mes

sage

rep

osit

ory:

HCPC

ONSL

xxxx

,COM

PID=

’JAM’

LARx

,DCJ

AMHC

PCON

SLxx

xx,C

OMPI

D=(R

x)R1

not

allo

wed

HCPC

ONSL

xxxx

,COM

PID=

DCJA

M

DCJA

MDC

C’JA

M’

Her

e is

how

you

r m

essa

ges

are

conn

ecte

d t

oH

CPC

ON

SL:

vT

he C

OM

PID

= c

ompo

nent

ID

is

asso

ciat

ed t

o yo

urm

essa

ge r

epos

itor

ies

wit

h th

e A

SSO

CIA

TE

ME

SSA

GE

com

man

d o

r co

nfig

urat

ion

file

stat

emen

t.

vYo

ur m

essa

ge r

epos

itor

ies

are

crea

ted

wit

h X

ED

IT.

vYo

ur m

essa

ge r

epos

itor

ies

are

com

pile

d w

ith

the

CM

S G

EN

MSG

com

man

d.

vYo

ur m

essa

ge r

epos

itor

ies

are

load

wit

h th

eC

PXL

OA

D c

omm

and

or

conf

igur

atio

n fi

lest

atem

ent.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

6729

8HC

PXSE

RVUN

LOCK

EXCL

USIV

E,CO

MPID

=’JA

M’64

0500

01

0007

BC94

FCD0

5800

058

6888

1NI

SAVE

WRK0

,X’F

C’CM

PBK

nolo

nger

lock

ed64

1500

0100

07C0

07F8

6888

2BR

R8Re

turn

6420

0001

0007

C268

884

LDUN

200

DS0H

Unlo

ckou

rCM

PBK

6430

0001

0007

D094

FCD0

5800

058

7046

8NI

SAVE

WRK0

,X’F

C’CM

PBK

nolo

nger

lock

ed64

4500

0100

07D4

07F8

7046

9BR

R8Re

turn

6450

0001

7047

1HC

PDRO

PR3

6460

0001

7047

3HC

PDRO

PR4

6465

0001

7047

5HC

PDRO

PR7

6470

0001

7047

7HC

PDRO

PR9

6475

0001

7047

9HC

PDRO

PR1

064

8000

01

Lin

e ▌6

7298

▐: A

lway

s re

linqu

ish

cont

rol

over

you

rC

MPB

K w

ith

the

com

plem

enta

ry “

unlo

ck”

requ

est.

To d

o ot

herw

ise

invi

tes

dis

aste

r.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

7048

2*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

---*

6490

0001

7048

3*

Synt

axde

fini

tion

ofth

eso

urce

file

for

JAMT

ABLE

.*

6495

0001

7048

4*

The

pars

erdo

esn’

tlo

okat

this

HCPC

FDEF

defi

niti

on*

6500

0001

7048

5*

beca

usewe

tell

itth

atwe

have

alre

adyus

eda

toke

n*

6505

0001

7048

6*

(rea

lly,

wepr

eten

ded

to)an

dfo

und

the

desi

redHC

PCFD

EF*

6510

0001

7048

7*

(the

reco

uld

have

been

many

).We

tell

the

pars

eral

lof

*65

1500

0170

488

*th

isby

pass

ing

thead

dres

sof

this

HCPC

FDEF

inR3

when

*65

2000

0170

489

*we

call

the

pars

er.

*65

2500

0170

490

*---

----

----

----

----

----

----

----

----

----

----

----

----

----

----

-*65

3000

01

7049

2CF

HCPC

FDEF

’JAM

TABL

E’,P

ROCE

SS=N

ONE

6540

0001

7049

3*

6545

0001

7049

4HC

PSTD

EFRE

QMAT

CH=Y

ESTh

eco

mman

d65

5000

0170

495

HCPT

KDEF

TYPE

=TOK

EN,

X655

5000

1ER

ROR=

MS67

0635

,X6

5600

001

STOR

E=JA

MTCM

D65

6500

0170

496

*65

7000

0170

497

HCPS

TDEF

REQM

ATCH

=YES

,Th

eta

rget

user

idX6

5750

001

MISS

ING=

MS00

2001

6580

0001

7049

8HC

PTKD

EFTY

PE=U

SERI

D,X6

5850

001

ERRO

R=MS

0007

01,

X659

0000

1ST

ORE=

JAMT

UID

6595

0001

7049

9*

6600

0001

7050

0HC

PSTD

EFRE

QMAT

CH=Y

ES,

Theta

rget

VDEV

numb

erX6

6050

001

MISS

ING=

MS00

2201

6610

0001

7050

1HC

PTKD

EF’*

’,C’*’

impl

iesF’-1

’to

usX6

6150

001

SOUR

CE=P

FXPG

(PFX

FFS)

,X6

6200

001

STOR

E=JA

MTVD

N66

2500

0170

503

HCPT

KDEF

’=’,

C’=’

issp

ecia

lto

usX6

6300

001

SOUR

CE=(

C’=’,0

),LE

N=1,

X663

5000

1ST

ORE=

JAMT

VDN

6640

0001

7050

5HC

PTKD

EFTY

PE=H

EX,

X664

5000

1ER

ROR=

MS00

2201

,X6

6500

001

RANG

E=(0

,X’F

FFF’

),X6

6550

001

STOR

E=JA

MTVD

N66

6000

0170

506

*66

6500

0170

507

HCPS

TDEF

REQM

ATCH

=YES

,Th

eVD

EVnu

mber

rang

est

art

X667

0000

1MI

SSIN

G=MS

0022

0166

7500

0170

508

HCPT

KDEF

TYPE

=HEX

,X6

6800

001

ERRO

R=MS

0022

01,

X668

5000

1RA

NGE=

(0,X

’FFF

F’),

X669

0000

1ST

ORE=

JAMT

VDS

6695

0001

7050

9*

6700

0001

7051

0HC

PSTD

EFRE

QMAT

CH=Y

ES,

TheVD

EVnu

mber

rang

een

dX6

7050

001

MISS

ING=

MS00

2201

6710

0001

7051

1HC

PTKD

EFTY

PE=H

EX,

X671

5000

1ER

ROR=

MS00

2201

,X6

7200

001

RANG

E=(0

,X’F

FFF’

),X6

7250

001

STOR

E=JA

MTVD

E67

3000

01

Lin

e ▌7

0482

▐: D

efin

ing

synt

ax t

o th

e C

P pa

rser

.

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

7051

3*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

----

*67

4000

0170

514

*Th

eHC

PDOS

YNMA

CRO

dump

sth

epr

evio

usly

defi

nedsy

ntax

6745

0001

7051

5*-

----

----

----

----

----

----

----

----

----

----

----

----

----

----

----

*67

5000

01

7051

7SY

NTAX

HCPD

OSYN

ROOT

=YES

,Ge

nera

teth

etr

ee’s

root

sX6

7600

001

BADC

MNT=

MS67

0501

,Me

ssag

efo

rba

dcm

ntX6

7650

001

BADC

ONT=

MS67

0502

,Me

ssag

efo

rba

dco

ntin

ueX6

7700

001

BADK

WD=M

S000

201,

Mess

agefo

rba

dke

ywor

dX6

7750

001

BADO

PEN=

MS67

0301

,Me

ssag

eif

nofi

leX6

7800

001

BADQ

UOT=

MS67

0604

,Me

ssag

efo

rba

dqu

ote

X678

5000

1BA

DREA

D=MS

6702

01,

Mess

agefo

rba

dre

adX6

7900

001

BADV

ERB=

MS67

0102

,Me

ssag

efo

rba

dst

mtX6

7950

001

CONF

LCT=

MS00

1301

,Me

ssag

efo

rco

nfli

ctX6

8000

001

MAXA

CC=M

S670

901,

Mess

agefo

rto

oma

nyX6

8050

001

MISS

ING=

MS67

0401

,Me

ssag

efo

rmi

ssin

gto

ken

X681

0000

1PL

BASE

=JAM

TABL

E,Na

meof

prim

ary

plis

tX6

8150

001

PLLE

N=JA

MTAB

LN,

Leng

thof

prim

arypl

ist

X682

0000

1PR

EPRO

C=0,

Nopr

e-pr

oces

sor

X682

5000

1RE

TGSD

BK=J

AMTG

SD,

Retu

rner

ror

mess

ages

X683

0000

1SY

NLIS

T=,

Nore

mote

synt

axX6

8350

001

TOOL

ONG=

MS67

0702

,Me

ssag

efo

rto

olo

ngX6

8400

001

TOOM

ANY=

MS00

0304

,Me

ssag

efo

rex

tra

toke

nX6

8450

001

BASE

S=PF

XPG

Addi

tion

alba

ses

6850

0001

7103

6HC

PDRO

PR0

6860

0001

7103

8HC

PDRO

PR1

168

6500

0171

040

HCPD

ROP

R13

6870

0001

7104

2HC

PEPI

LG68

7500

01

Sample Routines


Tabl

e13

. Ann

otat

ed L

istin

g fo

r S

ampl

e C

P E

xit

Rou

tine

2 fo

r C

P E

xit

1200

(con

tinue

d)A

ssem

ble

r S

ourc

eC

omm

enta

ry

0000

7800

071

00AE

871

265+

JAMS

AMCS

ECT

,@V

80G0

FA01

-HCP

EP00

0078

0007

100

AE8

7126

7+HC

PDAT

AALO

CTR

,@Y

0656

QY02

-HCP

DA00

0078

7126

8+LT

ORG

@Y06

56QY

01-H

CPEP

0000

78D1

C1D4

E3C1

C2D3

C571

269

=CL(

L’DR

BFID

FN)’

JAMT

ABLE’

0000

80E2

D6E4

D9C3

C540

4071

270

=CL(

L’DR

BFID

FT)’

SOUR

CE’

0000

8800

0012

0071

271

=A(X

IT@1

200)

0000

8C00

00F2

0071

272

=A(X

’F20

0’)

0000

9000

0000

0071

273

=A(H

CPZX

UCL)

0000

9400

0000

0071

274

=A(H

CPZX

CFC)

0000

9800

0000

0071

275

=A(H

CPZX

CLS)

0000

9CC4

C9C1

4071

276

=CL4

’DIA

’00

00A0

0000

F200

7127

7=A

(XIT

@F20

0)00

00A4

0000

0000

7127

8=A

(HCP

ZXCA

C)00

00A8

0000

0000

7127

9=A

(HCP

ZXCL

X)00

00AC

0000

0000

7128

0=A

(HCP

ZXUD

S)00

00B0

0000

05D0

7128

1=F

’148

8’00

00B4

0000

0FA0

7128

2=F

L(L’

DRBB

UFSZ

)’40

00’

0000

B800

0000

5071

283

=F’8

0’00

00BC

0000

0000

7128

4=A

(HCP

SVCK

J)00

00C0

0000

0000

7128

5=A

(HCP

ZIOP

N)00

00C4

0000

0000

7128

6=A

(HCP

ZIGE

T)00

00C8

4000

0000

7128

7=A

L1(C

’’,

0,0,

0)00

00CC

0000

0000

7128

8=A

(HCP

ZPRP

G)00

00D0

0067

0001

7128

9=A

(MS6

7000

1)00

00D4

0067

0702

7129

0=A

(MS6

7070

2)00

00D8

0067

0201

7129

1=A

(MS6

7020

1)00

00DC

0067

0301

7129

2=A

(MS6

7030

1)00

00E0

0000

0000

7129

3=A

(HCP

ZICL

S)00

00E4

0000

0FA0

7129

4=F

’400

0’00

00E8

0000

0000

7129

5=A

L1(0

,0,0

,0)

0000

EC00

0000

0071

296

=A(H

CPCV

UBM)

0000

F080

0000

0071

297

=A(H

CPCV

TRM+

x’80

0000

00’)

0000

F400

0000

0071

298

=A(H

CPER

MPR)

0000

F800

0000

0071

299

=A(H

CPZX

CUX)

0000

FC00

0000

0071

300

=A(H

CPZX

CUS)

0001

00C4

4071

301

=CL2

’D’

0001

02FF

FF71

302

=FL(

L’DR

BACS

BX)’

-1’

0001

0401

FD71

303

=AL(

L’GS

DFRE

SZ)(

FREM

X)00

0106

0000

7130

4=A

L(L’

DRBR

ETCD

)(DR

BOK)

0001

0800

5871

305

=AL(

L’DR

BRET

CD)(

DRBE

OF)

0001

0AD1

C1D4

7130

6=C

L3’J

AM’

0001

0DC4

C9C1

D340

7130

7=C

L5’D

IAL

’00

0112

C4C9

4071

308

=CL3

’DI

’

Lin

e ▌7

1267

▐: H

ere

is a

noth

er e

xam

ple

of g

ener

atin

gd

ata

out-

of-l

ine.

LTO

RG

dat

a is

pla

ced

ear

ly i

n th

em

odul

e in

ord

er t

o en

sure

ad

dre

ssab

ility

eve

n if

the

mod

ule

grow

s be

yond

4 K

B i

n si

ze.

Sample Routines


Tabl

e14

. Ann

otat

ed L

istin

g of

a L

ocal

Mes

sage

Rep

osito

ry f

or S

ampl

e 2

of C

P E

xit

1200

Ass

emb

ler

Sou

rce

Com

men

tary

1**

****

0000

0100

2$

0000

0200

3**

****

0000

0300

4*

0000

0400

Lin

e ▌2▐:

CP

uses

the

dol

lar

sign

($)

to

ind

icat

e th

atsu

bsti

tuti

on s

houl

d t

ake

plac

e in

a m

essa

ge. I

t is

impo

rtan

t th

at y

ou d

o no

t al

low

thi

s in

dic

ator

to

def

ault

to

any

othe

r sy

mbo

l.

567

0001

EFi

le$1

$2$3

,re

cord

$400

0005

006

*00

0006

007

6702

0101

EEr

ror

enco

unte

red

whil

eat

temp

ting

tore

ad00

0007

008

6702

0101

reco

rds

from

$1$2

$300

0008

009

*00

0009

0010

6703

01E

File

$1$2

$3no

tfo

und.

0000

1000

11*

0000

1100

Lin

e ▌5▐:

IB

M d

efin

es C

P m

essa

ge H

CP6

700E

(ver

sion

1)

as:

6700

01EFi

le$1

$2,

reco

rd$3

:

Thi

s d

oes

not

prov

ide

for

the

file

mod

e po

siti

on. W

eco

uld

hav

e:

vM

ade

$2 =

'fty

pe f

mod

e'

vIg

nore

d s

how

ing

the

file

mod

e

vTr

ied

to

find

ano

ther

mes

sage

vM

ade

a m

od t

o H

CPM

ES

to a

dd

a n

ew m

essa

gelik

e w

e w

ant

vM

ade

a m

od t

o H

CPM

ES

to c

hang

e 67

00.0

1:

6700

01EFi

le$1

$2$4

,re

cord

$3:

But

non

e of

the

se w

ould

hav

e be

en i

n th

e sp

irit

of

CP

Exi

ts.

Wha

t w

ill b

e ge

nera

ted

for

thi

s er

ror

mes

sage

is:

JAMS

AM67

00E

File

fnft

fm,re

cord

nn

1267

0702

01E

Stat

emen

tex

ceed

edma

ximu

mle

ngth

of40

00on

reco

rd$

0000

1200

1367

0702

014

infi

le$1

$2$3

.00

0013

0014

*00

0014

00

Lin

e ▌1

2▐: T

hese

rep

osit

ory

lines

wra

p at

col

umn

63ju

st s

o th

at t

he s

ourc

e lo

oks

like

HC

PME

S R

EPO

S. T

oge

nera

te a

TE

XT

file

fro

m y

our

repo

sito

ry s

ourc

e fi

le,

use

the

CM

S co

mm

and

GE

NM

SG. A

fter

you

hav

eth

e T

EX

T f

ile o

n a

CP

acce

ssed

dis

k, y

ou c

an l

oad

it

wit

h C

PXL

OA

D a

nd a

ssoc

iate

it

wit

h m

essa

gepr

oces

sing

wit

h A

SSO

CIA

TE

ME

SSA

GE

.

GENM

SGcm

pMES

REPO

SA

cmpla

ng(

CPMA

RGIN

63

1574

8007

RMo

deAC

PBK

ACSB

K00

0015

0016

*00

0016

0017

7480

08R

$1$2

$300

0017

0018

*00

0018

00

Lin

e ▌1

5▐: H

CPC

MPI

D O

ur r

espo

nse

7480

ver

sion

07.

Our

com

man

d r

espo

nses

for

ano

ther

of

our

loca

lco

mm

and

s.

Mes

sage

num

bers

in

the

7000

-799

9 ra

nge

are

cons

ider

ed r

espo

nses

, not

err

or m

essa

ges,

so

they

neve

r ar

e w

ritt

en w

ith

a m

essa

ge h

ead

er(H

CPX

XX

nnnn

E).

Sample Routines


A Sample JAMTABLE SOURCE File* Command Userid vdev lo hi* -------- -------- ---- ---- ----

? HELPMACH * 0000 FFFFBOOKS LIBRARY * 0000 00FFJOURNALS LIBRARY * 0100 01FFPVM PVM * 0000 FFFFVTAM MVS = 0120 013F

All blank records are treated as comments. See line numbers 47517-47522 in thelisting.

Records with '*' in column 1 are treated as comments. See line number 47524 in thelisting.

Our source file duplicates the entries in the JAM$DC table that was used inSample 1, except for the last entry.

The last entry has the value for the vdev column equal to '='. This is defined for theparser in the assembler language listing at line number 70503. The parsed value ishandled in the assembler language listing at line number 30594.

These are our control data definitions, which are mapped by JAMTABLE. Noticethe two entries for commands BOOKS and JOURNALS, where the target user ID isthe same but the range of target virtual devices is different. This separationguarantees that neither the BOOKS users nor the JOURNALS users can consumeall of the virtual terminal addresses, with one type of use locking out the other.

For this table to be most useful, you should also enter the following DEFINEALIAS commands:

DEFINE ALIAS ? FOR DIAL ENABLEDEFINE ALIAS BOOKS FOR DIAL ENABLEDEFINE ALIAS JOURNALS FOR DIAL ENABLEDEFINE ALIAS PVM FOR DIAL ENABLEDEFINE ALIAS VTAM FOR DIAL ENABLE

If so, then any of the aliases (?, BOOKS, JOURNALS, PVM, VTAM) or the basecommand (DIAL) will cause HCPDIA to be called, who will call us as exit 1200.

If a user at a terminal enters the command '?', or 'BOOKS', or any of the other aliasnames, it will be treated as an alias to DIAL, which means that CP will treat it justas if the user had entered the command 'DIAL' with no operands. Unless exit 1200supplies a target user ID, this command will fail. It is up to CP Exit 1200 to makethe command “whole”.

Sample Routines


Appendix J. I/O Monitor User Exit

This topic describes how to set up an internal exit routine to monitor real I/Orequests. It is important to note that what is described here pertains to z/VM V5.4,z/VM V6.2, and z/VM V6.3 with the PTFs for APARs VM65537 and VM65629.This support is included in the base of z/VM V6.4 and later releases.

31-bit address SYSIOMON in HCPSYSCM is provided to point to a user exitroutine for the purpose of monitoring real I/O requests started by the CPhypervisor. The intent is for a dynamically loaded user exit module to store andexploit the SYSIOMON address. The SYSIOMON routine address, if nonzero, iscalled out of the following CP locations:

ModuleCall to SYSIOMON

HCPIOS (real I/O dispatcher)Called right before a real SSCH instruction is executed for any type of realdevice. Called in two locations in z/VM V6.4 and later.

HCPIQM (real I/O queue manager)Called right before a real SSCH instruction is executed for any type of realdevice.

HCPPAU (real paging I/O manager)Called right before a real SSCH instruction is issued to a real paging orspooling volume. In z/VM V6.4 and later, this call is made only if thelegacy paging I/O driver has been enabled with the PAGING63 IPLparameter.

HCPPAH (real paging interrupt manager)Called right before a real SSCH instruction is issued to a real paging orspooling volume. In z/VM V6.4 and later, this call is made only if thelegacy paging I/O driver has been enabled with the PAGING63 IPLparameter.

Call MechanicsIf the contents of SYSIOMON are nonzero, representing the address of the user exitroutine, the specific HCPCALL invocation to the SYSIOMON routine depends onwhether the high order bit, x’80000000’, of SYSIOMON is ON or OFF. This wasengineered in this manner to be backward compatible over an important change tothe HCPCALL invocation to allow the routine to be called from the CP paging orspooling modules, but at the same time not break existing usage of the routine.This operates as follows:v If the high order bit of SYSIOMON is ON, then the call to the addressed routine

is made out of all four CP locations (HCPIOS, HCPIQM, HCPPAU, andHCPPAH). In this case, the call is made as follows, and the addressed user exitroutine is expected to conform to the attributes defined on this HCPCALLinvocation (that is, static save area, 32-bit registers, 31-bit addressing mode, andrun in primary space mode):HCPCALL (R15),ATTR=(STA,SREGE,AM31E,TMSTDE)

v If the high order bit of SYSIOMON is OFF, this is considered the legacy call,where the addressed routine is called only out of HCPIOS and HCPIQM. Thereis no CP paging or spooling call. In this case, the call is made as follows, and the


|

|

||||

|||||

||

|||

|||

|||||

|||||

||

|||||||

||||||

|

|||

addressed user exit routine is expected to use a dynamic save area (attributeDYN), 32-bit registers (SREGE), 31-bit addressing mode (AM31E), and run inprimary space mode (that is, no access register use) (TMSTDE):HCPCALL (R15),TYPE=DIRECT

Important Usage Notes1. On z/VM V5.4, z/VM V6.2, and z/VM V6.3, APARs VM65537 and VM65629

must be applied for the SYSIOMON exit points to operate as stated in thistopic. z/VM V6.1 does not contain this support.

2. An attempt to violate the call attributes as listed in “Call Mechanics” on page311 will result in an abend or other undesirable, unpredictable results. Theseattributes were specifically defined to be compatible with the calling moduleslisted and to conform to their specific requirements, especially serializationrequirements.

3. When the exit is called with a static save area, a loss of control in the exitroutine is prohibited and will result in an abend or other undesirable,unpredictable results. An example of a loss of control is calling another modulewhich uses a dynamic save area. Be aware that this could occur subtly by amacro, such as with HCPXSERV, and should be avoided.

4. I/O requests to EDEVICEs are not monitored by these exit points.5. I/O done on behalf of the SNAPDUMP command is not monitored by these

exit points. SNAPDUMP uses a special purpose I/O dispatcher because thesystem is quiesced.

6. A SYSIOMON value of zero, the initial value, causes CP to skip the HCPCALLinvocation.

SerializationThe calling modules will call the SYSIOMON exit routine holding the followinglocks:

ModuleLocks

HCPIOSRDEV lock for associated real device is held.

HCPIQMRDEV lock for associated real device is held.

HCPPAURDEV lock for the system volume might be held. Exposure block lock(EXPLCKFG.EXPBK) for the volume is held. EXPLCKFG is a spin lock,therefore the exit must not lose control.

HCPPAHRDEV lock and Exposure block lock (EXPLCKFG.EXPBK) for the systemvolume are held. EXPLCKFG is a spin lock, therefore the exit must not losecontrol.

EnablementThe existence of the SYSIOMON support, as stated above, does not exist on alllevels of z/VM. User exit code may check the following flag bits in data routineHCPIODFF (I/O features flag) for existence of this support:


|||

|

||

|||

|||||

|||||

|

|||

||

||

||

||

||

||

||||

||||

||

|||

DC CL8’HCPIODFF’ Eye CatcherDC CL8’Ver 1.00’ Version IdentifierDC XL1’C0’ Hex 80 bit VM65537 applied expanding SYSIOMON to Paging,

Hex 40 bit VM65629 applied making SYSIOMON Paging exits,backward compatible,

Hex 3F bits Reserved (may change)DC XL31’00’ ... Reserved (may change)

HCPIODFF provides a string of flag bits representing different I/O featuresavailable in CP that z/VM has externalized to provide CP extensions to the I/Osubsystem. Because this data area was added to z/VM V5.4, z/VM V6.2, andz/VM V6.3 via CP service, VM65537, it should be located on those systems asfollows:1. Load the address of entry point HCPIODMS + byte size of RDEV control block:

Addr(HCPIODMS)+(RDEVSIZE*8)

2. Validate the existence of the HCPIODFF eye catcher:CL8’HCPIODFF’

Appendix J. I/O Monitor User Exit 313

|||||||

|||||

|

|

|

|

Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not grant youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte character set (DBCS) information,contact the IBM Intellectual Property Department in your country or sendinquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan Ltd.1623-14, Shimotsurama, Yamato-shiKanagawa 242-8502 Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM websites are provided forconvenience only and do not in any manner serve as an endorsement of thosewebsites. The materials at those websites are not part of the materials for this IBMproduct and use of those websites is at your own risk.


|

IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

Site CounselIBM Corporation2455 South RoadPoughkeepsie, NY 12601-5400U.S.A.

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurement may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM's future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information may contain examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information may contain sample application programs in source language,which illustrate programming techniques on various operating platforms. You maycopy, modify, and distribute these sample programs in any form without paymentto IBM, for the purposes of developing, using, marketing or distributingapplication programs conforming to the application programming interface for theoperating platform for which the sample programs are written. These exampleshave not been thoroughly tested under all conditions. IBM, therefore, cannotguarantee or imply reliability, serviceability, or function of these programs. The


sample programs are provided "AS IS", without warranty of any kind. IBM shallnot be liable for any damages arising out of your use of the sample programs.

Programming Interface InformationThis book documents intended Programming Interfaces that allow the customer towrite programs to obtain the services of z/VM.

TrademarksIBM, the IBM logo, and ibm.com are trademarks or registered trademarks ofInternational Business Machines Corp., registered in many jurisdictions worldwide.Other product and service names might be trademarks of IBM or other companies.A current list of IBM trademarks is available on the web at IBM copyright andtrademark information - United States (www.ibm.com/legal/us/en/copytrade.shtml).

Linux is a trademark of Linus Torvalds in the United States, other countries, orboth.

Terms and Conditions for Product DocumentationPermissions for the use of these publications are granted subject to the followingterms and conditions.

Applicability

These terms and conditions are in addition to any terms of use for the IBMwebsite.

Personal Use

You may reproduce these publications for your personal, noncommercial useprovided that all proprietary notices are preserved. You may not distribute, displayor make derivative work of these publications, or any portion thereof, without theexpress consent of IBM.

Commercial Use

You may reproduce, distribute and display these publications solely within yourenterprise provided that all proprietary notices are preserved. You may not makederivative works of these publications, or reproduce, distribute or display thesepublications or any portion thereof outside your enterprise, without the expressconsent of IBM.

Rights

Except as expressly granted in this permission, no other permissions, licenses orrights are granted, either express or implied, to the publications or anyinformation, data, software or other intellectual property contained therein.

IBM reserves the right to withdraw the permissions granted herein whenever, in itsdiscretion, the use of the publications is detrimental to its interest or, asdetermined by IBM, the above instructions are not being properly followed.

Notices 317

http://www.ibm.com/legal/us/en/copytrade.shtml

http://www.ibm.com/legal/us/en/copytrade.shtml

You may not download, export or re-export this information except in fullcompliance with all applicable laws and regulations, including all United Statesexport laws and regulations.

IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESEPUBLICATIONS. THE PUBLICATIONS ARE PROVIDED “AS-IS” AND WITHOUTWARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDINGBUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY,NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.

IBM Online Privacy StatementIBM Software products, including software as a service solutions, (“SoftwareOfferings”) may use cookies or other technologies to collect product usageinformation, to help improve the end user experience, to tailor interactions withthe end user, or for other purposes. In many cases no personally identifiableinformation is collected by the Software Offerings. Some of our Software Offeringscan help enable you to collect personally identifiable information. If this SoftwareOffering uses cookies to collect personally identifiable information, specificinformation about this offering’s use of cookies is set forth below.

This Software Offering does not use cookies or other technologies to collectpersonally identifiable information.

If the configurations deployed for this Software Offering provide you as customerthe ability to collect personally identifiable information from end users via cookiesand other technologies, you should seek your own legal advice about any lawsapplicable to such data collection, including any requirements for notice andconsent.

For more information about the use of various technologies, including cookies, forthese purposes, see IBM Online Privacy Statement Highlights athttp://www.ibm.com/privacy and the IBM Online Privacy Statement athttp://www.ibm.com/privacy/details in the section entitled “Cookies, WebBeacons and Other Technologies”, and the IBM Software Products andSoftware-as-a-Service Privacy Statement at http://www.ibm.com/software/info/product-privacy.


http://www.ibm.com/privacy

http://www.ibm.com/privacy/details

http://www.ibm.com/software/info/product-privacy

http://www.ibm.com/software/info/product-privacy

Glossary

For a list of z/VM terms and their definitions, see z/VM: Glossary.

The z/VM glossary is also available through the online z/VM HELP Facility, ifHELP files are installed on your z/VM system. For example, to display thedefinition of the term “dedicated device”, issue the following HELP command:help glossary dedicated device

While you are in the glossary help file, you can do additional searches:v To display the definition of a new term, type a new HELP command on the

command line:help glossary newterm

This command opens a new help file inside the previous help file. You canrepeat this process many times. The status area in the lower right corner of thescreen shows how many help files you have open. To close the current file, pressthe Quit key (PF3/F3). To exit from the HELP Facility, press the Return key(PF4/F4).

v To search for a word, phrase, or character string, type it on the command lineand press the Clocate key (PF5/F5). To find other occurrences, press the keymultiple times.The Clocate function searches from the current location to the end of the file. Itdoes not wrap. To search the whole file, press the Top key (PF2/F2) to go to thetop of the file before using Clocate.


Bibliography

See the following publications for additionalinformation about z/VM. For abstracts of thez/VM publications, see z/VM: General Information,GC24-6193.

Where to Get z/VM Informationz/VM product documentation and other z/VMinformation is available in IBM Knowledge Center- z/VM (www.ibm.com/support/knowledgecenter/SSB27U).

You can also obtain z/VM product publicationsfrom IBM Publications Center(www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss).

z/VM Base LibraryOverviewv z/VM: License Information, GC24-6200v z/VM: General Information, GC24-6193v z/VM: Glossary, GC24-6195

Installation, Migration, and Servicev z/VM: Installation Guide, GC24-6246v z/VM: Migration Guide, GC24-6201v z/VM: Service Guide, GC24-6247v z/VM: VMSES/E Introduction and Reference,

GC24-6243

Planning and Administrationv z/VM: CMS File Pool Planning, Administration,

and Operation, SC24-6167v z/VM: CMS Planning and Administration,

SC24-6171v z/VM: Connectivity, SC24-6174v z/VM: CP Planning and Administration,

SC24-6178v z/VM: Enabling z/VM for OpenStack (Support for

OpenStack Liberty Release), SC24-6251v z/VM: Getting Started with Linux on z Systems,

SC24-6194v z/VM: Group Control System, SC24-6196v z/VM: I/O Configuration, SC24-6198v z/VM: Running Guest Operating Systems,

SC24-6228

v z/VM: Saved Segments Planning andAdministration, SC24-6229

v z/VM: Secure Configuration Guide, SC24-6230v z/VM: TCP/IP LDAP Administration Guide,

SC24-6236v z/VM: TCP/IP Planning and Customization,

SC24-6238v z/OS and z/VM: Hardware Configuration Manager

User's Guide, SC34-2670

Customization and Tuningv z/VM: CP Exit Customization, SC24-6176v z/VM: Performance, SC24-6208

Operation and Usev z/VM: CMS Commands and Utilities Reference,

SC24-6166v z/VM: CMS Primer, SC24-6172v z/VM: CMS User's Guide, SC24-6173v z/VM: CP Commands and Utilities Reference,

SC24-6175v z/VM: System Operation, SC24-6233v z/VM: TCP/IP User's Guide, SC24-6240v z/VM: Virtual Machine Operation, SC24-6241v z/VM: XEDIT Commands and Macros Reference,

SC24-6244v z/VM: XEDIT User's Guide, SC24-6245

Application Programmingv z/VM: CMS Application Development Guide,

SC24-6162v z/VM: CMS Application Development Guide for

Assembler, SC24-6163v z/VM: CMS Application Multitasking, SC24-6164v z/VM: CMS Callable Services Reference, SC24-6165v z/VM: CMS Macros and Functions Reference,

SC24-6168v z/VM: CMS Pipelines User's Guide and Reference,

SC24-6252v z/VM: CP Programming Services, SC24-6179v z/VM: CPI Communications User's Guide,

SC24-6180v z/VM: Enterprise Systems Architecture/Extended

Configuration Principles of Operation, SC24-6192


http://www.ibm.com/support/knowledgecenter/SSB27U

http://www.ibm.com/support/knowledgecenter/SSB27U

http://www.ibm.com/shop/publications/order

v z/VM: Language Environment User's Guide,SC24-6199

v z/VM: OpenExtensions Advanced ApplicationProgramming Tools, SC24-6202

v z/VM: OpenExtensions Callable Services Reference,SC24-6203

v z/VM: OpenExtensions Commands Reference,SC24-6204

v z/VM: OpenExtensions POSIX ConformanceDocument, GC24-6205

v z/VM: OpenExtensions User's Guide, SC24-6206v z/VM: Program Management Binder for CMS,

SC24-6211v z/VM: Reusable Server Kernel Programmer's Guide

and Reference, SC24-6220v z/VM: REXX/VM Reference, SC24-6221v z/VM: REXX/VM User's Guide, SC24-6222v z/VM: Systems Management Application

Programming, SC24-6234v z/VM: TCP/IP Programmer's Reference, SC24-6239v Common Programming Interface Communications

Reference, SC26-4399v Common Programming Interface Resource Recovery

Reference, SC31-6821v z/OS: IBM Tivoli Directory Server Plug-in

Reference for z/OS, SA76-0169v z/OS: Language Environment Concepts Guide,

SA22-7567v z/OS: Language Environment Debugging Guide,

GA22-7560v z/OS: Language Environment Programming Guide,

SA22-7561v z/OS: Language Environment Programming

Reference, SA22-7562v z/OS: Language Environment Run-Time Messages,

SA22-7566v z/OS: Language Environment Writing

Interlanguage Communication Applications,SA22-7563

v z/OS MVS Program Management: AdvancedFacilities, SA23-1392

v z/OS MVS Program Management: User's Guideand Reference, SA23-1393

Diagnosisv z/VM: CMS and REXX/VM Messages and Codes,

GC24-6161v z/VM: CP Messages and Codes, GC24-6177v z/VM: Diagnosis Guide, GC24-6187

v z/VM: Dump Viewing Facility, GC24-6191v z/VM: Other Components Messages and Codes,

GC24-6207v z/VM: TCP/IP Diagnosis Guide, GC24-6235v z/VM: TCP/IP Messages and Codes, GC24-6237v z/VM: VM Dump Tool, GC24-6242v z/OS and z/VM: Hardware Configuration

Definition Messages, SC34-2668

z/VM Facilities and FeaturesData Facility Storage ManagementSubsystem for VMv z/VM: DFSMS/VM Customization, SC24-6181v z/VM: DFSMS/VM Diagnosis Guide, GC24-6182v z/VM: DFSMS/VM Messages and Codes,

GC24-6183v z/VM: DFSMS/VM Planning Guide, SC24-6184v z/VM: DFSMS/VM Removable Media Services,

SC24-6185v z/VM: DFSMS/VM Storage Administration,

SC24-6186

Directory Maintenance Facility for z/VMv z/VM: Directory Maintenance Facility Commands

Reference, SC24-6188v z/VM: Directory Maintenance Facility Messages,

GC24-6189v z/VM: Directory Maintenance Facility Tailoring

and Administration Guide, SC24-6190

Open Systems Adapter/Support Facilityv Open Systems Adapter-Express Customer's Guide

and Reference, SA22-7935v Open Systems Adapter-Express Integrated Console

Controller User's Guide, SA22-7990v Open Systems Adapter-Express Integrated Console

Controller 3215 Support, SA23-2247v Open Systems Adapter-Express3 Integrated Console

Controller Dual-Port User's Guide, SA23-2266

Performance Toolkit for VMv z/VM: Performance Toolkit Guide, SC24-6209v z/VM: Performance Toolkit Reference, SC24-6210

RACF® Security Server for z/VMv z/VM: RACF Security Server Auditor's Guide,

SC24-6212v z/VM: RACF Security Server Command Language

Reference, SC24-6213


v z/VM: RACF Security Server Diagnosis Guide,GC24-6214

v z/VM: RACF Security Server General User'sGuide, SC24-6215

v z/VM: RACF Security Server Macros andInterfaces, SC24-6216

v z/VM: RACF Security Server Messages and Codes,GC24-6217

v z/VM: RACF Security Server SecurityAdministrator's Guide, SC24-6218

v z/VM: RACF Security Server System Programmer'sGuide, SC24-6219

v z/VM: Security Server RACROUTE MacroReference, SC24-6231

Remote Spooling CommunicationsSubsystem Networking for z/VMv z/VM: RSCS Networking Diagnosis, GC24-6223v z/VM: RSCS Networking Exit Customization,

SC24-6224v z/VM: RSCS Networking Messages and Codes,

GC24-6225v z/VM: RSCS Networking Operation and Use,

SC24-6226v z/VM: RSCS Networking Planning and

Configuration, SC24-6227

Prerequisite ProductsDevice Support Facilitiesv Device Support Facilities: User's Guide and

Reference, GC35-0033

Environmental Record Editing andPrinting Programv Environmental Record Editing and Printing

Program (EREP): Reference, GC35-0152v Environmental Record Editing and Printing

Program (EREP): User's Guide, GC35-0151

Bibliography 323

Index

Aacquire

lock on component ID 192output data from CP exit routine 15

addconfiguration file statements 89new

alias 58CP commands 4, 51CP exit routines 4CP message repositories 5, 61diagnose codes 4, 51

address constant resolutiondefinition 35effect on

CPXLOAD of prohibiting 33CPXLOAD when unresolved 35SYSGEN when unresolved 35

when resolved by CPXLOAD 32addresses, storage 2addressing mode

addressing mode 16choosing for CP exit routine 15entry point attributes 17register styles 16translation mode 17

aliascreating 58

allocateCMPBKs 192component ID blocks 192

ALLOCATE operandHCPXSERV macro 195

alterCP load list 235CP mods to CP exits 12LOGON command operands 126return code from parsing LOGON command 129separator page 171system initialization options 117VMDBK

after creation/initialization 132alternate MDLAT

coding 235creating 236using 19

AMODE31 operandMDLATENT macro 204

AMODE31ENT operandMDLATENT macro 207

AMODE64 operandMDLATENT macro 204

AMODE64ENT operandMDLATENT macro 207

AMODEINT operandMDLATENT macro 205

AMODEVAR operandMDLATENT macro 205

AMODEVARENT operandMDLATENT macro 207

ASSOCIATE EXIT command 49

ASSOCIATE EXIT statement 49ASSOCIATE MESSAGES command 50, 64ASSOCIATE MESSAGES statement 50ASSOCIATE MSGS command 50, 64ASSOCIATE MSGS statement 50attribute list

definingfor CP modules 203for entry points 203

markingthe beginning of 209the end of 210

restrictions for CP routines 208attributes

addressing mode 16entry point 17register style 16translation mode 17

authorizationexamining CP commands after 122

Bbeginning

CP module attribute list, marking 209block, command table entry

changing after authorization processing 122creating with COMMD macro 10

Ccall

CP exit points 4CP exit routines 192local CP message repositories 5, 29

CALL operandHCPXSERV macro 192

changeCP load list 235CP mods to CP exits 12LOGON command operands 126return code from parsing LOGON command 129separator page 171system initialization options 117VMDBK

after creation/initialization 132CHANGE directive 178choose

addressing mode for CP exit routine 15class

IBM 52privilege 52

code, diagnosecontrolling 4, 48creating 4, 54overriding 4

code, executabledynamically loading into system execution space 3, 39dynamically unloading from system execution space 4, 71


code, returnchanging

from parsed LOGON command 129examining

from parsed LOGON command 129standard 108

commandASSOCIATE

EXIT 49MESSAGES 50MSGS 50

controlling 4, 47CPLISTFILE 101, 182CPTYPE 101CPXLOAD

examples 42loading CP command routines 47loading CP exit routines 49loading diagnose code routines 48loading message repositories 50operand explanations 39restrictions for CP routine attributes 208

CPXUNLOADunloading CP command routines 47unloading CP exit routines 49unloading diagnose code routines 48unloading message repositories 50

creating 4, 51DEFINE

ALIAS 47CMD 47COMMAND 47DIAGNOSE 48EXIT 49

DISABLECMD 47COMMAND 47DIAGNOSE 48EXITS 49

ENABLECMD 47COMMAND 47DIAGNOSE 48EXITS 49

LOCATESYMBOL 48, 49, 50

LOGOFFexamining operands 136, 138performing processing before completion 138

LOGONchanging operands 126changing return code after parsing 129examining operands 126, 134examining return code after parsing 129performing processing before completion 134rejecting 126replacing operands 126

MODIFYCMD 47COMMAND 47DIAGNOSE 48EXIT 49

overriding 4QUERY

CPCMDS 48, 58DIAGNOSE 48

command table entry blockchanging after authorization processing 122creating with COMMD macro 10

COMPID operandHCPXSERV macro 195

component ID blockacquiring lock on 192allocating 192controlling access to 192deallocating 192locating 192

configuration file, systemASSOCIATE


CPXLOAD statementloading CP command routines 47loading CP exit routines 49loading diagnose code routines 48loading message repositories 50parameter explanations 39restrictions for CP routine attributes 208

DEFINE statementALIAS 47CMD 47COMMAND 47DIAGNOSE 48EXIT 49

DISABLE statementCMD 47COMMAND 47DIAGNOSE 48EXITS 49

ENABLE statementCMD 47COMMAND 47DIAGNOSE 48EXITS 49

MODIFY statementCMD 47COMMAND 47, 48EXIT 49

console input datareplacing 126

constant resolution, addressdefinition 35effect on


when resolved by CPXLOAD 32control

access to component ID block 192CP commands 4, 47CP exit points 4, 49diagnose codes 4, 48dynamically loaded routine 47local CP message repositories 5, 50

control blockCMPBK

allocating 192controlling access to 192deallocating 192locating 192relinquishing lock on 192

XITBK 192


CONTROL operandOPTIONS directive 183when to specify 40

control section (CSECT)size, increasing 180

convertCP load list 235CP mods to CP exits 12LOGON command operands 126return code from parsing LOGON command 129separator page 171system initialization options 117VMDBK

after creation/initialization 132CP (control program)

commandsexamining after authorization 122

customizationCP Exit method 3SYSGEN method 2

exit pointscalling 4controlling 4, 49CP Exit 00E0 112CP Exit 00E1 117CP Exit 0FFB 122CP Exit 1100 126CP Exit 1101 129CP Exit 1110 132CP Exit 117F 134CP Exit 11C0 136CP Exit 11FF 138CP Exit 1200 140CP Exit 1201 142CP Exit 1210 144, 150, 152CP Exit 3FE8 154CP Exit 4400 157CP Exit 4401 159CP Exit 4402 161CP Exit 4403 163CP Exit 4404 165CP Exit 4405 167CP Exit 4406 169CP Exit 4407 171defining parameter list 192defining using HCPXSERV macro 4dynamic 8, 175

exit routineschoosing addressing mode for 15creating 4providing input data to 14receiving output data from 15

macrosHCPXSERV 192MDLATENT 203MDLATHDR 209MDLATTLR 210

CP customizationCP Exit method 3SYSGEN method 2

CP Exit 00E0 (Startup Pre-Prompt Processing) 112CP Exit 00E1 (Startup Post-Prompt Processing) 117CP Exit 0FFB (Post-Authorization Command Processing) 122CP Exit 1100 (LOGON Command Pre-Parse Processing) 126CP Exit 1101 (Logon Post-Parse Processing) 129CP Exit 1110 (VMDBK Pre-Logon Processing) 132CP Exit 117F (Logon Final Screening) 134

CP Exit 11C0 (Logoff Initial Screening) 136CP Exit 11FF (Logoff Final Screening) 138CP Exit 1200 (DIAL Command Initial Screening) 140CP Exit 1201 (DIAL Command Final Screening) 142CP Exit 1210 (Messaging Commands Screening) 144, 150, 152CP Exit 3FE8 (SHUTDOWN Command Screening) 154CP Exit 4400 (Separator Page Data Customization) 157CP Exit 4401 (Separator Page Pre-Perforation Positioning) 159CP Exit 4402 (Separator Page Perforation Printing or 3800

Positioning) 161CP Exit 4403 (Separator Page Printing) 163CP Exit 4404 (Second Separator Page Positioning) 165CP Exit 4405 (Second Separator Page Printing) 167CP Exit 4406 (Separator Page Post-Print Positioning) 169CP Exit 4407 (Trailer Page Processing) 171CP exit point

benefits of using 1calling 4controlling 4, 49defining

parameter list 192using HCPXSERV macro 4, 201

disabling 192dynamic 8, 175enabling 192locating control blocks 192testing 192

CP exit routinechoosing addressing mode for 15creating 4providing input data to 14receiving output data from 15

CP load listupdating 235

CP message repositoryadvantages of 61calling local 5, 29commenting 231control line 231controlling local 5, 50creating local 5, 61example 62message record format 232overview 231using local 5

CP modificationsmigrating to CP Exits 7

CP moduleattribute list

defining 203marking the beginning of 209marking the end of 210restrictions for CP routines 208

attributesaddressing mode 16register style 16translation mode 17

defining attribute list 203packaging 41writing 41

CP nucleusordered module list 235

CP parsercreating a syntax definition 74HCPCFDEF macro 73, 212HCPDOSYN macro 74, 214HCPSTDEF macro 73, 216

Index 327

CP parser (continued)HCPTKDEF macro 73, 219overview 73, 211syntax descriptions 73token conversion types 73, 221

CP serviceavailable for CP Exit 00E0 114available for CP Exit 00E1 119

CPLISTFILE command 101, 182CPTYPE command 101CPXLOAD command

examples 42loading

CP command routines 47CP exit routines 49diagnose code routines 48message repositories 50

message repositories 64operand explanations 39restrictions for CP routine attributes 208

CPXLOAD directiveCHANGE 178examples 44EXPAND 180INCLUDE 181OPTIONS 183

CPXLOAD operandMDLATENT macro 207

CPXLOAD statementloading


loading CP exit routines 49loading diagnose code routines 48loading message repositories 50parameter explanations 39restrictions for CP routine attributes 208

CPXUNLOAD commandunloading


createdynamically loaded routines 13new

alias 58CP commands 4CP exit routines 4CP message repositories 5diagnose codes 4

parameter list for CP exit point 192VMDBK

changing after 132examining after 132

CSECTsize, increasing 180

customization, CPCP Exit method 3SYSGEN method 2

DDATA operand

MDLATENT macro 204

data, console inputreplacing 126

date, inputproviding to CP exit routine 14

date, outputreceiving from CP exit routine 15

deallocateCMPBKs 192component ID blocks 192

DEALLOCATE operandHCPXSERV macro 195

debugCP Exit 00E0 115CP Exit 00E1 120

defaultsetting for loading CP routines 183

defineCP module

attribute list 203defaults for loading CP routines 183lock on component ID 192new

alias 58CP commands 4CP exit routines 4CP message repositories 5diagnose codes 4

parameter list for CP exit point 192DEFINE ALIAS command 47DEFINE ALIAS statement 47DEFINE CMD command 47DEFINE CMD statement 47DEFINE COMMAND command 47DEFINE COMMAND statement 47DEFINE DIAGNOSE command 48DEFINE DIAGNOSE statement 48DEFINE EXIT command 49DEFINE EXIT statement 49definition of

address constant resolution 35dynamically loaded CP routines 1SXS dynamic area 2

DELAY operandwhen to specify 39

deleteexternal symbol, temporarily 178

diagnose codecontrolling 4, 48creating 4, 54overriding 4

directive, CPXLOADCHANGE 178examples 44EXPAND 180INCLUDE 181OPTIONS 183

disableCP exit points 192

DISABLE CMD command 47DISABLE CMD statement 47DISABLE COMMAND command 47DISABLE COMMAND statement 47DISABLE DIAGNOSE command 48DISABLE DIAGNOSE statement 48DISABLE EXITS command 49DISABLE EXITS statement 49


DISABLE operandHCPXSERV macro 192

DISABLED operandHCPXSERV macro 193

DISASSOCIATE EXIT command 49DISASSOCIATE MESSAGES command 50, 71display

messages with HCPCONSL macro 12dynamic

loadingdeleting external symbol, temporarily 178including another file 181into SXS dynamic area 3renaming external symbol, temporarily 178restrictions for CP routine attributes 208routines into SXS dynamic area 39setting defaults for loading 183

unloadingfrom SXS dynamic area 4

dynamic area, SXSdefinition 2loading code into 3, 39unloading code from 4

dynamic exit pointconventions 175defining 8, 49modifying 49querying 49removing 49

DYNAMIC operandMDLATENT macro 206

dynamically-loaded routinechoosing addressing mode for 15controlling 47creating 13definition 1deleting external symbol for, temporarily 178design issues 13including another file when loading 181providing input data to 14receiving output data from 15renaming external symbol for, temporarily 178restrictions for CP routine attributes 208setting defaults for loading 183

Eenable

CP exit points 192ENABLE CMD command 47ENABLE CMD statement 47ENABLE COMMAND command 47ENABLE COMMAND statement 47ENABLE DIAGNOSE command 48ENABLE DIAGNOSE statement 48ENABLE EXITS command 49ENABLE EXITS statement 49ENABLE operand

HCPXSERV macro 192, 193end

CP module attribute list, marking 210entry block, command table

changing after authorization processing 122creating with COMMD macro 10

entry pointattribute list

defining 203

entry point (continued)attribute list (continued)

restrictions for CP routines 208attributes 17

EP operandMDLATENT macro 205

ERROR operandHCPXSERV macro 193

examineCP commands after authorization 122LOGOFF command 136, 138LOGON command operands 134LOGON COMMAND operands 126return code from parsing LOGON command 129system initialization options 117VMDBK

after creation/initialization 132example

acquiringexclusive lock on CMPBK 200shared lock on CMPBK 200

allocatingCMPBK 200component ID block 200parameter list build area 201PLISTBLD 201

callingCP exit routines 201

changingexternal symbols when loading CP routines 179

configuration file statement 89CP message repository 62CP routines, setting defaults for loading 185CPXLOAD commands 42CPXLOAD directives 44CSECT size, expanding 180defining

more CMPBK space 200deleting

external symbols when loading CP routines 179expanding

CSECT size 180finding

CMPBK 200component ID block 200

includinganother file during loading 182

increasingCSECT size 180

loadingCP routines, setting defaults 185

locatingCMPBK 200component ID block 200

passingcontrol blocks 201parameter list entries 201PLIST entries 201

releasingparameter list build area 201PLISTBLD 201

renamingexternal symbols when loading CP routines 179

settingdefaults for loading CP routines 185

size, expanding CSECT 180

Index 329

executable codedynamically loading into system execution space 3, 39dynamically unloading from system execution space 4, 71

execution space, systemdynamic area

definition 2loading code into 3, 39unloading code from 4

layout 2EXIT operand

HCPXSERV macro 193exit point, CP

benefits of using 1calling 4controlling 4, 49defining

parameter list 192using HCPXSERV macro 4, 201

disabling 192dynamic 8, 175enabling 192locating control blocks 192testing 192

exit routine, CPchoosing addressing mode for 15creating 4providing input data to 14receiving output data from 15

EXPAND directive 180external symbol

deleting temporarily 178renaming temporarily 178

EXTERNAL_SYNTAX statement 89

FFASTDYN operand

MDLATENT macro 206file

CP message repositoryadvantages of 61commenting 231control line 231example 62message record format 232overview 231

including another when loading code 181file, system configuration

ASSOCIATEEXIT 49MESSAGES 50MSGS 50



DISABLE statementCMD 47

file, system configuration (continued)DISABLE statement (continued)

COMMAND 47DIAGNOSE 48EXITS 49



findCMPBKs 192component ID blocks 192CP exit control blocks 192XITBKs 192

FIND operandHCPXSERV macro 195

formatrecord

messages 232

Gget

lock on component ID 192output data from CP exit routine 15

giveinput data to CP exit routine 14system initialization options 112

GOTO operandMDLATENT macro 206

HHCP002E 185HCP2757E 185HCP2768E 185HCP6704E 185HCP8019E 185HCP8040E 185HCPAIF, HCPAELSE, HCPAEND 97HCPCFDEF macro 73HCPCMPID macro

using 19HCPCONSL macro

displaying messages with 12HCPDOSYN macro 214HCPSTDEF macro 216HCPTKDEF macro 219HCPTRANS macro 12HCPXSERV macro

defining CP exit points with 4general definition 192

Host Absolute Address (HAA) 2Host Logical Address (HLA) 2Host Real Address (HRA) 2

II/O monitor user exit 311identify

input data to CP exit routine 14


identify (continued)system initialization options 112

includeanother file when loading code 181loop, preventing 182

INCLUDE directive 181increase

CSECT size 180initialization options, system

changing 117examining 117providing 112when prompted for 113, 118

initializeVMDBK

changing after 132examining after 132

input dataproviding to CP exit routine 14

input data, consolereplacing 126

INVEXIT operandHCPXSERV macro 193

IPLdynamically loading your CP routines during 39system initialization options


Llanguage

translating your messages into another 61LET operand

OPTIONS directive 184when to specify 40

listparameter, defining for CP exit point 192

LLATTR operandMDLATENT macro 208

loaddynamically

deleting external symbol, temporarily 178including another file 181into SXS 3renaming external symbol, temporarily 178restrictions for CP routine attributes 208routines into SXS dynamic area 39setting defaults for loading 183

loaded routine, dynamicallychoosing addressing mode for 15controlling 47creating 13definition 1deleting external symbol for, temporarily 178design issues 13including another file when loading 181providing input data to 14receiving output data from 15renaming external symbol for, temporarily 178restrictions for CP routine attributes 208setting defaults for loading 183

local message repositorycalling CP 5controlling CP 5, 50

local message repository (continued)creating CP 5using CP 5

locateCMPBKs 192component ID blocks 192CP exit control blocks 192XITBKs 192

LOCATE CMDBK command 96LOCATE DGNBK command 96LOCATE ICLBK command 96LOCATE SYMBOL command 48, 49, 50LOCATE XITBK command 96lock

acquiring on component ID 192relinquishing on component ID 192

LOCK operandOPTIONS directive 184

LOCKEXCLUSIVE operandHCPXSERV macro 195

LOCKSHARED operandHCPXSERV macro 195

log offexamining characteristics of 136, 138performing processing before completion 138

log onchanging

characteristics of 126return code after parsing 129VMDBK during 132

examiningcharacteristics of 126, 134return code after parsing 129VMDBK during 132

performing processing before completion 134rejecting 126

LOGOFF commandexamining operands 136, 138performing processing before completion 138

LOGON commandchanging

operands 126return code after parsing 129

examiningoperands 126, 134return code after parsing 129

performing processing before completion 134rejecting 126replacing operands 126

LONGREG operandMDLATENT macro 204

LONGREGENT operandMDLATENT macro 207

loopinclude

preventing 182system initialization

preventing for CP Exit 00E0 114preventing for CP Exit 00E1 119

Mmacroinstruction

CPHCPXSERV 192MDLATENT 203MDLATHDR 209

Index 331

macroinstruction (continued)CP (continued)

MDLATTLR 210mark

end of CP module attribute list 210start of CP module attribute list 209

MDLATENT macro 203MDLATHDR macro 209MDLATTLR macro 210MEMBER operand

INCLUDE directive 181message

displaying with HCPCONSL macro 12, 26, 65translating into another languague 61

message examples, notation used in xvmessage repository, CP

advantages of 61calling local 5, 29commenting 231control line 231controlling local 5, 50creating local 5, 61example 62message record format 232overview 231using local 5

MODATTR operandMDLATENT macro 203

mode, addressingaddressing mode 16choosing for CP exit routine 15entry point attributes 17register styles 16translation mode 17

MODID operandMDLATENT macro 205

modifications, CPmigrating to CP Exits 7

modifyCP commands 4CP load list 235CP mods to CP exits 12diagnose codes 4LOGON command operands 126return code from parsing LOGON command 129separator page 171system initialization options 117VMDBK

after creation/initialization 132MODIFY CMD command 47MODIFY CMD statement 47MODIFY COMMAND command 47MODIFY COMMAND statement 47MODIFY DIAGNOSE command 48MODIFY DIAGNOSE statement 48MODIFY EXIT command 49MODIFY EXIT statement 49module, CP

attribute listdefining 203marking the beginning of 209marking the end of 210restrictions for CP routines 208

attributesaddressing mode 16register style 16translation mode 17

module, CP (continued)defining attribute list 203packaging 41writing 41

MP operandMDLATENT macro 204OPTIONS directive 184when to specify 40

Nnew

aliasdefining 58

commandsusing CP parser 73, 211

diagnose codes 52message repository 231version 54

NEXT operandHCPXSERV macro 193

NOCONTROL operandOPTIONS directive 184when to specify 40

NODELAY operandwhen to specify 39

NOLET operandOPTIONS directive 184when to specify 40

NOLOCK operandOPTIONS directive 184

NOMP operandOPTIONS directive 184when to specify 40

NONE operandHCPXSERV macro 193MDLATENT macro 206

NONMP operandMDLATENT macro 204OPTIONS directive 184when to specify 40

NONRSTD operandMDLATENT macro 207

notation used in message and response examples xvNOTRACE operand

MDLATENT macro 206, 207nucleus

CPordered module list 235

OOPTIONS directive 183options, system initialization


output datareceiving from CP exit routine 15

overviewCP message repository 231CP parser 73, 211


Pparameter list

defining for CP exit point 192dynamic exit point 175

parser, CPcreating a syntax definition 74HCPCFDEF macro 73, 212HCPDOSYN macro 74, 214HCPSTDEF macro 73, 216HCPTKDEF macro 73, 219overview 73, 211syntax descriptions 73token conversion types 73, 221

PERMANENT operandOPTIONS directive 184when to specify 40

PLIST operandHCPXSERV macro 193

PLISTBLD operandHCPXSERV macro 194

preventinclude loop 182system initialization loop

for CP Exit 00E0 114for CP Exit 00E1 119

printer separator page exitCP Exit 4400 157CP Exit 4401 159CP Exit 4402 161CP Exit 4403 163CP Exit 4404 165CP Exit 4405 167CP Exit 4406 169

printer trailer page exitCP Exit 4407 171

privilege class 52process

another file when loading code 181LOGOFF command before completion 138LOGON command before completion 134

provideinput data to CP exit routine 14system initialization options 112

QQUERY CPCMDS command 48, 95QUERY CPLANGLIST command 96QUERY CPXLOAD command 95QUERY DIAGNOSE command 48, 95QUERY EXITS command 95QUERY ICLNAME command 96QUERY UNRESOLVED command 95QWORDS operand

HCPXSERV macro 196

Rread

another file when loading code 181receive

output data from CP exit routine 15record format

messages 232redefine

CP commands 4

redefine (continued)diagnose codes 4

register styles 16reject

LOGON command 126release

lock on component ID 192relinquish

lock on component ID 192remove

lock on component ID 192rename

external symbol, temporarily 178replace

console input data 126LOGON command operands 126

repository, CP messageadvantages of 61calling local 5, 29commenting 231control line 231controlling local 5, 50creating local 5, 61example 62message record format 232overview 231using local 5

RESIDENT operandMDLATENT macro 204

resolution, address constantdefinition 35effect on


when resolved by CPXLOAD 32response examples, notation used in xvrestriction

attributes for CP routines 208CPXLOAD, specifying CP routine attributes 208

return codechanging

from parsed LOGON command 129examining

from parsed LOGON command 129standard 108

routine, dynamically-loadedchoosing addressing mode for 15controlling 47creating 13definition 1deleting external symbol for, temporarily 178design issues 13including another file when loading 181providing input data to 14receiving output data from 15renaming external symbol for, temporarily 178restrictions for CP routine attributes 208setting defaults for loading 183

RSTD operandMDLATENT macro 207

Sselect

addressing mode for CP exit routine 15

Index 333

separator page exit for printersCP Exit 4400 157CP Exit 4401 159CP Exit 4402 161CP Exit 4403 163CP Exit 4404 165CP Exit 4405 167CP Exit 4406 169

service, CPavailable for CP Exit 00E0 114available for CP Exit 00E1 119

setdefaults for loading CP routines 183lock on component ID 192

SHORTREG operandMDLATENT macro 204

SHORTREGENT operandMDLATENT macro 207

sizeincreasing CSECT 180

startCP module attribute list, marking 209

statementASSOCIATE


CPXLOADloading CP command routines 47loading CP exit routines 49loading diagnose code routines 48loading message repositories 50parameter explanations 39restrictions for CP routine attributes 208

DEFINEALIAS 47CMD 47COMMAND 47DIAGNOSE 48EXIT 49

DISABLECMD 47COMMAND 47DIAGNOSE 48EXITS 49

ENABLECMD 47COMMAND 47DIAGNOSE 48EXITS 49

MODIFYCMD 47COMMAND 47DIAGNOSE 48EXIT 49

STATIC operandMDLATENT macro 206

storage addresses 2summary

assigned CP exit number ranges 103CP exit macros 191CPXLOAD directives 177HCPXSERV register contents

after execution 197during execution 197

IBM-defined CP exit point range assignments 103IBM-defined CP exit points 104

summary (continued)valid HCPXSERV action/parameter combinations 196

supplyinput data to CP exit routine 14system initialization options 112

symbollocating 102

symbol, externaldeleting temporarily 178renaming temporarily 178

syntax diagrams, how to read xiiiSYSIOMON address for I/O monitor user exit 311system authorization

examining CP commands after 122system configuration file

ASSOCIATEEXIT 49MESSAGES 50MSGS 50



DISABLE statementCMD 47COMMAND 47DIAGNOSE 48EXITS 49



system execution spacedynamic area

definition 2loading code into 3, 39unloading code from 4

layout 2system initialization options


Ttable

assigned CP exit number ranges 103CP exit macros 191CPXLOAD directives 177HCPXSERV register contents

after execution 197during execution 197


table (continued)IBM-defined CP exit point range assignments 103IBM-defined CP exit points (summary) 104valid HCPXSERV action/parameter combinations 196

table entry block, commandchanging after authorization processing 122creating with COMMD macro 10

TEMPORARY operandOPTIONS directive 184when to specify 40

testCP exit points 192

TEST operandHCPXSERV macro 193

TMODEAR operandMDLATENT macro 205

TMODEARENT operandMDLATENT macro 207

TMODEINT operandMDLATENT macro 205

TMODESTD operandMDLATENT macro 205

TMODESTDENT operandMDLATENT macro 207

TMODEVAR operandMDLATENT macro 205

TMODEVARENT operandMDLATENT macro 207

traceCP Exit 00E0 115CP Exit 00E1 120

TRACE operandMDLATENT macro 206, 207

trailer page exit for printersCP Exit 4407 171

translatemessages into another languague 61

translate-and-test tabledefining in parameter list for CP exit routine 194

translation mode 17TRTTABLE operand

HCPXSERV macro 194

Uunload

dynamicallyfrom SXS 4

UNLOCKEXCLUSIVE operandHCPXSERV macro 195

UNLOCKSHARED operandHCPXSERV macro 195

updateCP load list 235

uselocal CP message repositories 5

user exit to monitor real I/O requests 311

VVMDBK

after creation/initializationchanging 132examining 132

Wwarning

calling entry point after loading CP routines 183CONTROL operand of OPTIONS directive 183increasing CSECT space beyond program limits 180preventing include loop 182using CHANGE and EXPAND directives together 180

Index 335

IBM®

Product Number: 5741-A07

Printed in USA

SC24-6176-03

z/VM V6.4 CP Exit CustomizationStandar d Parameter List Contents . 107 Standar d Exit Conditions ....

Documents

Transcript of z/VM V6.4 CP Exit CustomizationStandar d Parameter List Contents . 107 Standar d Exit Conditions ....