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
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.
SC24-6176-01, z/VM Version 6 Release 2This edition includes changes to support the general availability of z/VM V6.2.
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.
SC24-6176-00, z/VM Version 6 Release 1This edition includes changes to support the general availability of z/VM V6.1.
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
4 z/VM V6.4 CP Exit Customization
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
6 z/VM V6.4 CP Exit Customization
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,
© Copyright IBM Corp. 1995, 2016 7
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
8 z/VM V6.4 CP Exit Customization
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
10 z/VM V6.4 CP Exit Customization
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
12 z/VM V6.4 CP Exit Customization
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?
© Copyright IBM Corp. 1995, 2016 13
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
14 z/VM V6.4 CP Exit Customization
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
16 z/VM V6.4 CP Exit Customization
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
Chapter 3. Creating a Dynamically Loaded Routine 17
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
18 z/VM V6.4 CP Exit Customization
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
Chapter 3. Creating a Dynamically Loaded Routine 19
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
20 z/VM V6.4 CP Exit Customization
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.
– SETCC=1 indicates that condition code 1 should be set and returned to thecaller.
– SETCC=2 indicates that condition code 2 should be set and returned to thecaller.
– SETCC=3 indicates that condition code 3 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:
Defining System Linkage
Chapter 3. Creating a Dynamically Loaded Routine 21
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
Defining System Linkage
22 z/VM V6.4 CP Exit Customization
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:
Defining System Linkage
Chapter 3. Creating a Dynamically Loaded Routine 23
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
Defining System Linkage
24 z/VM V6.4 CP Exit Customization
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.
Defining System Linkage
Chapter 3. Creating a Dynamically Loaded Routine 25
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
Defining System Linkage
26 z/VM V6.4 CP Exit Customization
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
Defining System Linkage
Chapter 3. Creating a Dynamically Loaded Routine 27
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?
Defining System Linkage
28 z/VM V6.4 CP Exit Customization
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
Defining System Linkage
Chapter 3. Creating a Dynamically Loaded Routine 29
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
Defining System Linkage
30 z/VM V6.4 CP Exit Customization
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)
Defining System Linkage
Chapter 3. Creating a Dynamically Loaded Routine 31
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
Defining System Linkage
32 z/VM V6.4 CP Exit Customization
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
Defining System Linkage
Chapter 3. Creating a Dynamically Loaded Routine 33
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.
Defining System Linkage
34 z/VM V6.4 CP Exit Customization
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.
Defining System Linkage
Chapter 3. Creating a Dynamically Loaded Routine 35
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.
Defining System Linkage
36 z/VM V6.4 CP Exit Customization
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.
Defining System Linkage
Chapter 3. Creating a Dynamically Loaded Routine 37
38 z/VM V6.4 CP Exit Customization
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.
© Copyright IBM Corp. 1995, 2016 39
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
40 z/VM V6.4 CP Exit Customization
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.
Loading into the SXS
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.
Loading into the SXS
42 z/VM V6.4 CP Exit Customization
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.
Loading into the SXS
Chapter 4. Loading Dynamically into the System Execution Space 43
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.
Loading into the SXS
44 z/VM V6.4 CP Exit Customization
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
Loading into the SXS
Chapter 4. Loading Dynamically into the System Execution Space 45
46 z/VM V6.4 CP Exit Customization
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.
© Copyright IBM Corp. 1995, 2016 47
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.
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 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
48 z/VM V6.4 CP Exit Customization
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.
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 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.
Controlling Routines
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:
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 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.
Controlling Routines
50 z/VM V6.4 CP Exit Customization
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
© Copyright IBM Corp. 1995, 2016 51
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
52 z/VM V6.4 CP Exit Customization
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.
Your Own Commands and Diagnose Codes
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
Your Own Commands and Diagnose Codes
54 z/VM V6.4 CP Exit Customization
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.
Your Own Commands and Diagnose Codes
Chapter 6. Defining and Modifying Commands and Diagnose Codes 55
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.
Your Own Commands and Diagnose Codes
56 z/VM V6.4 CP Exit Customization
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
Your Own Commands and Diagnose Codes
Chapter 6. Defining and Modifying Commands and Diagnose Codes 57
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.
Your Own Commands and Diagnose Codes
58 z/VM V6.4 CP Exit Customization
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.
Your Own Commands and Diagnose Codes
Chapter 6. Defining and Modifying Commands and Diagnose Codes 59
60 z/VM V6.4 CP Exit Customization
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.
© Copyright IBM Corp. 1995, 2016 61
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
62 z/VM V6.4 CP Exit Customization
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
64 z/VM V6.4 CP Exit Customization
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
Chapter 7. Defining and Using CP Message Repositories 65
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
66 z/VM V6.4 CP Exit Customization
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
Chapter 7. Defining and Using CP Message Repositories 67
The following is an example of an HCPCONSL invocation for the repository inFigure 6 on page 67.
The HCPCONSL invocation:
WRITEindicates that a console write is requested.
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.
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
B EXIT Skip around constantsSPACE 1
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
68 z/VM V6.4 CP Exit Customization
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.
The HCPCONSL invocation:
WRITEindicates that a console write is requested.
COMPID=indicates the component ID whose repositories are to be searched for thespecified message number and version.
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
B EXIT Skip around constantsSPACE 1
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
Chapter 7. Defining and Using CP Message Repositories 69
REPOSNUM=indicates the equate containing the message number and version.
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
70 z/VM V6.4 CP Exit Customization
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
© Copyright IBM Corp. 1995, 2016 71
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
72 z/VM V6.4 CP Exit Customization
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
© Copyright IBM Corp. 1995, 2016 73
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
74 z/VM V6.4 CP Exit Customization
►► 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.
►► ASK DADMOMAUNT nameUNCLE namefriend
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.
►► ASK DADMOMAUNT nameUNCLE namefriend
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
76 z/VM V6.4 CP Exit Customization
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
Chapter 9. Understanding the CP Parser 77
'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
78 z/VM V6.4 CP Exit Customization
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
Chapter 9. Understanding the CP Parser 79
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
80 z/VM V6.4 CP Exit Customization
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
ST_3 HCPSTDEF REQMATCH=YESHCPTKDEF TYPE=TOKEN,NEXT=ST_4, For ’name’
STORE=CWHO
ST_4 HCPSTDEF REQMATCH=YESHCPTKDEF ’FOR’
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
Chapter 9. Understanding the CP Parser 81
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
ST_2 HCPSTDEF REQMATCH=YESHCPTKDEF TYPE=TOKEN,NEXT=ST_4, For ’name’
STORE=CWHO
ST_3 HCPSTDEF REQMATCH=YESHCPTKDEF TYPE=TOKEN,NEXT=ST_4, For ’name’
STORE=CWHO
ST_4 HCPSTDEF REQMATCH=YESHCPTKDEF ’FOR’
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
82 z/VM V6.4 CP Exit Customization
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
Chapter 9. Understanding the CP Parser 83
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
84 z/VM V6.4 CP Exit Customization
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
Chapter 9. Understanding the CP Parser 85
...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
86 z/VM V6.4 CP Exit Customization
| |+--------+
-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
Chapter 9. Understanding the CP Parser 87
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
88 z/VM V6.4 CP Exit Customization
| | | | | || 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
Chapter 9. Understanding the CP Parser 89
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
90 z/VM V6.4 CP Exit Customization
+--------+ +--------++--| | | || | 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
Chapter 9. Understanding the CP Parser 91
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
92 z/VM V6.4 CP Exit Customization
(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
Chapter 9. Understanding the CP Parser 93
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
94 z/VM V6.4 CP Exit Customization
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
© Copyright IBM Corp. 1995, 2016 95
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
96 z/VM V6.4 CP Exit Customization
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
98 z/VM V6.4 CP Exit Customization
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
– LOCATE SYMBOL entry_point_name
– QUERY ICLNAME entry_point_name
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
Chapter 10. Common and Frequent Problems 99
– 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
100 z/VM V6.4 CP Exit Customization
– 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
Chapter 10. Common and Frequent Problems 101
– 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
– LOCATE SYMBOL entry_point_name
– QUERY ICLNAME entry_point_name
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
102 z/VM V6.4 CP Exit Customization
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.
© Copyright IBM Corp. 1995, 2016 103
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
104 z/VM V6.4 CP Exit Customization
Table 5. Summary of IBM-Defined CP Exit Points (continued)
CP Exit Name Function Page
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)
CP Exit Name Function Page
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
106 z/VM V6.4 CP Exit Customization
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
Appendix A. IBM-Defined CP Exit Points 107
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
108 z/VM V6.4 CP Exit Customization
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
Appendix A. IBM-Defined CP Exit Points 109
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
110 z/VM V6.4 CP Exit Customization
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
Appendix A. IBM-Defined CP Exit Points 111
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
112 z/VM V6.4 CP Exit Customization
Word Offset Data Length Contents
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
Appendix A. IBM-Defined CP Exit Points 113
– 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
114 z/VM V6.4 CP Exit Customization
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
Appendix A. IBM-Defined CP Exit Points 115
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
116 z/VM V6.4 CP Exit Customization
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
Process CP Exit Attribute
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
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 DataLength
Contents
1 +0 N/A 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.
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
Appendix A. IBM-Defined CP Exit Points 117
Word Offset DataLength
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
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 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.
nn For any other return codes, CP:
v Writes message HCP2765E to the operator
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
118 z/VM V6.4 CP Exit Customization
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
Appendix A. IBM-Defined CP Exit Points 119
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
120 z/VM V6.4 CP Exit Customization
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
Appendix A. IBM-Defined CP Exit Points 121
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
Process CP Exit Attribute
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
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 usedby this CP exit routine as working storage.
4 +12 12 bytes Address of the CP command name, as entered bythe user.
CP Exits
122 z/VM V6.4 CP Exit Customization
Word Offset Data Length Contents
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
Appendix A. IBM-Defined CP Exit Points 123
Word Offset Data Length Contents
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
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 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
124 z/VM V6.4 CP Exit Customization
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.
nn For any other return codes, CP:
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
Appendix A. IBM-Defined CP Exit Points 125
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
Process CP Exit Attribute
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
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 DataLength
Contents
1 +0 N/A 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.
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 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
126 z/VM V6.4 CP Exit Customization
Word Offset DataLength
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
Appendix A. IBM-Defined CP Exit Points 127
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 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).
nn For any other return codes, CP:
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 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
128 z/VM V6.4 CP Exit Customization
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
Process CP Exit Attribute
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
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 DataLength
Contents
1 +0 N/A 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.
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 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
Appendix A. IBM-Defined CP Exit Points 129
Word Offset DataLength
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
On return, CP Exit 1101 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 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 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 of the LOGON command based on the value of the originalparse return code.
nn For any other return codes, CP:
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 of the LOGON command based on the value of the originalparse return code.
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 of
CP Exits
130 z/VM V6.4 CP Exit Customization
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.
You cannot make changes to any of the other parameter list fields.
CP Exits
Appendix A. IBM-Defined CP Exit Points 131
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
Process CP Exit Attribute
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
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 DataLength
Contents
1 +0 N/A 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.
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
132 z/VM V6.4 CP Exit Customization
Word Offset DataLength
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
On return, CP Exit 1110 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 continues normal processing.
nn For any other return codes, CP:
v Writes error message HCP2765E to the system operator
v Generates soft abend ABR002
v Continues normal processing.
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 3The VMDBK located by Word 6.
You cannot make changes to any of the other parameter list fields.
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
Appendix A. IBM-Defined CP Exit Points 133
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
Process CP Exit Attribute
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
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 DataLength
Contents
1 +0 N/A 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.
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 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
134 z/VM V6.4 CP Exit Customization
Exit conditions
On return, CP Exit 117F 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 continues normal processing.
nn For any other return codes, CP:
v Writes error message HCP2765E to the system operator
v Generates soft abend ABR002
v Continues normal processing.
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.
You cannot make changes to any of the other parameter list fields.
CP Exits
Appendix A. IBM-Defined CP Exit Points 135
CP Exit 11C0: Logoff Initial ScreeningPurpose
Use CP Exit 11C0 to examine the CP LOGOFF command immediately after it isissued.
Point of processing
Process CP Exit Attribute
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
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 DataLength
Contents
1 +0 N/A 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.
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 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
136 z/VM V6.4 CP Exit Customization
Word Offset DataLength
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.
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.
You cannot make changes to any of the other parameter list fields.
CP Exits
Appendix A. IBM-Defined CP Exit Points 137
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
Process CP Exit Attribute
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
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 DataLength
Contents
1 +0 N/A 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.
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 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
138 z/VM V6.4 CP Exit Customization
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
Appendix A. IBM-Defined CP Exit Points 139
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
Process CP Exit Attribute
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
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 DataLength
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.
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 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
140 z/VM V6.4 CP Exit Customization
Word Offset DataLength
Contents
9 +32 N/A Address of the RDEV control block for the terminalwhere the user issued the command.
Exit conditions
On return, CP Exit 1200 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 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.
nn For any other return codes, CP:
v Writes message HCP2765E to the system operator
v Generates soft abend ABR002
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
Appendix A. IBM-Defined CP Exit Points 141
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
Process CP Exit Attribute
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
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 DataLength
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.
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 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
142 z/VM V6.4 CP Exit Customization
Exit conditions
On return, CP Exit 1201 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 continues normal processing, using the initial values or the values set byCP Exit 1200.
nn For any other return codes, CP:
v Writes message HCP2779E to the operator
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
Appendix A. IBM-Defined CP Exit Points 143
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
Process CP Exit Attribute
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.
Parameter list constant
The parameter list contains the following:
Word Offset DataLength
Contents
1 +0 N/A 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.
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.
CP Exits
144 z/VM V6.4 CP Exit Customization
Word Offset DataLength
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
Appendix A. IBM-Defined CP Exit Points 145
Word Offset DataLength
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
146 z/VM V6.4 CP Exit Customization
Word Offset DataLength
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
Appendix A. IBM-Defined CP Exit Points 147
Word Offset DataLength
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
On return, CP Exit 1210 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 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
148 z/VM V6.4 CP Exit Customization
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
Appendix A. IBM-Defined CP Exit Points 149
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
Process CP Exit Attribute
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.
Parameter list constant
The parameter list, which is defined as X1230 dsect in HCPPLXIT COPY, containsthe following:
Word Offset DataLength
Contents
1 +0 N/A 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.
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 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
150 z/VM V6.4 CP Exit Customization
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
Appendix A. IBM-Defined CP Exit Points 151
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
Process CP Exit Attribute
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.
Parameter list constant
The parameter list, which is defined as X1231 dsect in HCPPLXIT COPY, containsthe following:
Word Offset DataLength
Contents
1 +0 N/A 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.
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 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
152 z/VM V6.4 CP Exit Customization
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
Appendix A. IBM-Defined CP Exit Points 153
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
Process CP Exit Attribute
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
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 DataLength
Contents
1 +0 N/A Reserved for future IBM use.
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
154 z/VM V6.4 CP Exit Customization
Word Offset DataLength
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
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 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.
nn For any other return codes, CP:
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
Appendix A. IBM-Defined CP Exit Points 155
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
156 z/VM V6.4 CP Exit Customization
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
Process CP Exit Attribute
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
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 Length Contents
1 +0 N/A Reserved for future IBM use.
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.
4 +12 N/A Reserved for future IBM use.
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
Appendix A. IBM-Defined CP Exit Points 157
Exit conditions
On return, CP Exit 4400 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 continues normal processing.
4 CP continues normal processing.
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
158 z/VM V6.4 CP Exit Customization
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
Process CP Exit Attribute
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
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 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.
8 +28 RDEVSZCK(doublewords)
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
Appendix A. IBM-Defined CP Exit Points 159
Word Offset Data Length Contents
9 +32 RSPSIZE(doublewords)
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
On return, CP Exit 4401 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 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.
8 CP terminates separator page processing for the current file.
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
160 z/VM V6.4 CP Exit Customization
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
Process CP Exit Attribute
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
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 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.
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.
CP Exits
Appendix A. IBM-Defined CP Exit Points 161
Word Offset Data Length Contents
7 +24 SPFEND (bytes) Address of the spool file control block (SPFBK) ofthe file being printed.Note: SPFEND is an equate in HCPSPFBK COPY.
8 +28 RDEVSZCK(doublewords)
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.
9 +32 RSPSIZE(doublewords)
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
On return, CP Exit 4402 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 continues separator page processing.
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.
8 CP terminates separator page processing for the current file.
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
162 z/VM V6.4 CP Exit Customization
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
Process CP Exit Attribute
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
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 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.
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.
8 +28 RDEVSZCK(doublewords)
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
Appendix A. IBM-Defined CP Exit Points 163
Word Offset Data Length Contents
9 +32 RSPSIZE(doublewords)
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
On return, CP Exit 4403 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 continues separator page processing.
4 CP does not perform the I/O to print the first separator page, but continuesseparator page processing.
8 CP terminates separator page processing for the current file.
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 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
164 z/VM V6.4 CP Exit Customization
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
Process CP Exit Attribute
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
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 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.
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.
CP Exits
Appendix A. IBM-Defined CP Exit Points 165
Word Offset Data Length Contents
8 +28 RDEVSZCK(doublewords)
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.
9 +32 RSPSIZE(doublewords)
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
On return, CP Exit 4404 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 continues separator page processing.
4 CP does not perform the I/O to position the printer for printing the secondseparator page, but continues separator page processing.
8 CP terminates separator page processing for the current file.
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
166 z/VM V6.4 CP Exit Customization
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
Process CP Exit Attribute
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
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 a doubleword-aligned User Area,which can be used by this CP exit routine asworking storage.
3 +8 256 bytes Address of doubleword-aligned translate-and-test(TRT) table, which can be used by this CP exitroutine 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.
8 +28 RDEVSZCK(doublewords)
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
Appendix A. IBM-Defined CP Exit Points 167
Word Offset Data Length Contents
9 +32 RSPSIZE(doublewords)
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
On return, CP Exit 4405 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 continues separator page processing.
4 CP does not perform the I/O to print the second separator page, butcontinues separator page processing.
8 CP terminates separator page processing for the current file.
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
168 z/VM V6.4 CP Exit Customization
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
Process CP Exit Attribute
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
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 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.
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.
8 +28 RDEVSZCK(doublewords)
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
Appendix A. IBM-Defined CP Exit Points 169
Word Offset Data Length Contents
9 +32 RSPSIZE(doublewords)
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
On return, CP Exit 4406 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 continues separator page processing.
4 CP does not perform the I/O to position the printer to begin printing spoolfile data, but continues separator page processing.
8 CP terminates separator page processing for the current file.
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
170 z/VM V6.4 CP Exit Customization
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
Process CP Exit Attribute
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
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 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.
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 SEPTRL which contains separatortrailer page CCWs and data.
6 +20 SPFEND (bytes) Address of the spool file control block (SPFBK) ofthe file being printed.Note: SPFEND is an equate in HCPSPFBK COPY.
CP Exits
Appendix A. IBM-Defined CP Exit Points 171
Word Offset Data Length Contents
7 +24 RDEVSZCK(doublewords)
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.
8 +28 RSPSIZE(doublewords)
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
On return, CP Exit 4407 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 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
172 z/VM V6.4 CP Exit Customization
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
Appendix A. IBM-Defined CP Exit Points 173
Module Summary
174 z/VM V6.4 CP Exit Customization
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
Word Offset Data Length 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.
© Copyright IBM Corp. 1995, 2016 175
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
176 z/VM V6.4 CP Exit Customization
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.
© Copyright IBM Corp. 1995, 2016 177
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
178 z/VM V6.4 CP Exit Customization
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
180 z/VM V6.4 CP Exit Customization
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
Appendix C. CPXLOAD Directives 181
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
182 z/VM V6.4 CP Exit Customization
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
Appendix C. CPXLOAD Directives 183
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
184 z/VM V6.4 CP Exit Customization
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
Appendix C. CPXLOAD Directives 185
CPXLOAD Directives
186 z/VM V6.4 CP Exit Customization
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.
© Copyright IBM Corp. 1995, 2016 187
Control Block Purpose
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
188 z/VM V6.4 CP Exit Customization
Control Block Purpose
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
190 z/VM V6.4 CP Exit Customization
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
For information about how to read syntax diagrams, see “Syntax, Message, andResponse Conventions” on page xiii.
© Copyright IBM Corp. 1995, 2016 191
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
192 z/VM V6.4 CP Exit Customization
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
194 z/VM V6.4 CP Exit Customization
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
Appendix E. CP Exit Macros 195
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
196 z/VM V6.4 CP Exit Customization
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
LinkageAddress
FIND CP ExitNumber
— — LinkageAddress
LinkageAddress
NEXT CP ExitNumber
— — LinkageAddress
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
Appendix E. CP Exit Macros 197
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
198 z/VM V6.4 CP Exit Customization
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=8 Reserved for IBM use and currently unused.
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.
R15=8 Reserved for IBM use and currently unused.
LOCK EXCLUSIVE R15=0
R1
HCPXSERV successfully acquired the exclusive lock on the specifiedCMPBK.
Contains the address of the specified CMPBK.
R15=4 HCPXSERV could not find the specified CMPBK; no lock was acquired.
R15=8 Reserved for IBM use and currently unused.
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.
Contains the address of the specified CMPBK.
R15=4 HCPXSERV could not find the specified CMPBK; no lock was acquired.
R15=8 Reserved for IBM use and currently unused.
R15=12 The CMPBK lock was destroyed.
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=8 Reserved for IBM use and currently unused.
R15=12 The CMPBK lock was destroyed.
R15=16 There was an unexpected return code from the unlocking routine(HCPLCKRX).
CP Exit Macros
Appendix E. CP Exit Macros 199
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=8 Reserved for IBM use and currently unused.
R15=12 The CMPBK lock was destroyed.
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
ABEND11 DS 0HHCPABEND 011,HARD
ABEND33 DS 0HHCPABEND 033,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?
ABEND1 DS 0HHCPABEND 001,HARD
ABEND2 DS 0HHCPABEND 002,HARD
ABEND33 DS 0HHCPABEND 033,HARD
CP Exit Macros
200 z/VM V6.4 CP Exit Customization
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
Appendix E. CP Exit Macros 201
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
202 z/VM V6.4 CP Exit Customization
(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
labelis an optional assembler label.
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
Appendix E. CP Exit Macros 203
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
204 z/VM V6.4 CP Exit Customization
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
Appendix E. CP Exit Macros 205
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
206 z/VM V6.4 CP Exit Customization
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
Appendix E. CP Exit Macros 207
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
208 z/VM V6.4 CP Exit Customization
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
labelis an optional assembler label.
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
Appendix E. CP Exit Macros 209
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
210 z/VM V6.4 CP Exit Customization
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
For information about how to read syntax diagrams, see “Syntax, Message, andResponse Conventions” on page xiii.
© Copyright IBM Corp. 1995, 2016 211
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
labelis an optional assembler label.
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
212 z/VM V6.4 CP Exit Customization
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:
1 You can specify the following operands in any order.
Purpose
Generates syntax table defined via previous invocations of HCPCFDEF,HCPSTDEF and HCPTKDEF macros.
Operands
labelis an optional assembler label.
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
214 z/VM V6.4 CP Exit Customization
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
Appendix F. CP Parser Macros and Routines 215
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:
1 You can specify the following operands in any order.
Purpose
Use the HCPSTDEF macro to define a state in the finite state machine thatexpresses a command or statement syntax.
Operands
labelis an optional assembler label.
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
216 z/VM V6.4 CP Exit Customization
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
Appendix F. CP Parser Macros and Routines 217
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
218 z/VM V6.4 CP Exit Customization
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
Appendix F. CP Parser Macros and Routines 219
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
220 z/VM V6.4 CP Exit Customization
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
Appendix F. CP Parser Macros and Routines 221
Table 11. Conversion types (continued)
Conversion Type Meaning
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 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).
CP Parser
222 z/VM V6.4 CP Exit Customization
Table 11. Conversion types (continued)
Conversion Type Meaning
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 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).
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 Dollar sign ($), also called currency symbol
v Number sign (#), also called pound sign or hash symbol
v Commercial “at” sign (@)
v Underscore (_)
v Plus sign (+)
v Minus sign or dash (–)
v Colon (:)
v Alphabetic characters (A through Z)
v Numeric characters (0 through 9).
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 Dollar sign ($), also called currency symbol
v Number sign (#), also called pound sign or hash symbol
v Commercial “at” sign (@)
v Underscore (_)
v Plus sign (+)
v Minus sign or dash (–)
v Colon (:)
v Alphabetic characters (A through Z)
v Numeric characters (0 through 9).
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
Appendix F. CP Parser Macros and Routines 223
Table 11. Conversion types (continued)
Conversion Type Meaning
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 Dollar sign ($), also called currency symbol
v Number sign (#), also called pound sign or hash symbol
v Commercial “at” sign (@)
v Underscore (_)
v Plus sign (+)
v Minus sign or dash (–)
v Colon (:)
v Alphabetic characters (A through Z)
v Numeric characters (0 through 9).
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
224 z/VM V6.4 CP Exit Customization
Table 11. Conversion types (continued)
Conversion Type Meaning
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
Appendix F. CP Parser Macros and Routines 225
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
226 z/VM V6.4 CP Exit Customization
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
Appendix F. CP Parser Macros and Routines 227
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.
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.
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
228 z/VM V6.4 CP Exit Customization
Output Registers — Normal:
R150 Statement may be processed
4 Statement should not be processed
Output Registers — Error:
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.
Output Registers — Normal:
R150 Statement processing completed successfully
Output Registers — Error:
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
Appendix F. CP Parser Macros and Routines 229
Post-Processor
230 z/VM V6.4 CP Exit Customization
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.
© Copyright IBM Corp. 1995, 2016 231
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
232 z/VM V6.4 CP Exit Customization
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:
CP Message Repository
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.
CP Message Repository
234 z/VM V6.4 CP Exit Customization
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.
© Copyright IBM Corp. 1995, 2016 235
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
236 z/VM V6.4 CP Exit Customization
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
Updating the CP Load List
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.
Updating the CP Load List
238 z/VM V6.4 CP Exit Customization
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.
Updating the CP Load List
Appendix H. Updating the CP Load List 239
240 z/VM V6.4 CP Exit Customization
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.
© Copyright IBM Corp. 1995, 2016 241
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
242 z/VM V6.4 CP Exit Customization
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
244 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 245
– Using the ASSOCIATE EXIT statement– And so forth
Sample Routines
246 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 247
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
248 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 249
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
250 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 251
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
252 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 253
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
254 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 255
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
256 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 257
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
258 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 259
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
260 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 261
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
262 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 263
Sample Routines
264 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 265
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
266 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 267
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
268 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 269
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
270 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 271
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
272 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 273
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
274 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 275
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
276 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 277
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
278 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 279
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
280 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 281
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
282 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 283
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
284 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 285
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
286 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 287
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
288 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 289
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
290 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 291
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
292 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 293
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
294 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 295
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
296 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 297
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
298 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 299
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
300 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 301
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
302 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 303
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
304 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 305
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
306 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 307
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
308 z/VM V6.4 CP Exit Customization
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
Appendix I. Samples of Dynamically Loaded Routines 309
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
310 z/VM V6.4 CP Exit Customization
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
© Copyright IBM Corp. 1995, 2016 311
|
|
||||
|||||
||
|||
|||
|||||
|||||
||
|||||||
||||||
|
|||
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:
312 z/VM V6.4 CP Exit Customization
|||
|
||
|||
|||||
|||||
|
|||
||
||
||
||
||
||
||||
||||
||
|||
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
|||||||
|||||
|
|
|
|
314 z/VM V6.4 CP Exit Customization
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.
© Copyright IBM Corp. 1995, 2016 315
|
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
316 z/VM V6.4 CP Exit Customization
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
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.
318 z/VM V6.4 CP Exit Customization
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.
© Copyright IBM Corp. 1995, 2016 319
320 z/VM V6.4 CP Exit Customization
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
© Copyright IBM Corp. 1995, 2016 321
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
322 z/VM V6.4 CP Exit Customization
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
324 z/VM V6.4 CP Exit Customization
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
© Copyright IBM Corp. 1995, 2016 325
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
EXIT 49MESSAGES 50MSGS 50
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
CPXLOAD of prohibiting 33CPXLOAD when unresolved 35SYSGEN when unresolved 35
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
326 z/VM V6.4 CP Exit Customization
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
CP command routines 47CP exit routines 49diagnose code routines 48message repositories 50
loading CP exit routines 49loading diagnose code routines 48loading message repositories 50parameter explanations 39restrictions for CP routine attributes 208
CPXUNLOAD commandunloading
CP command routines 47CP exit routines 49diagnose code routines 48message repositories 50
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
328 z/VM V6.4 CP Exit Customization
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
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 47
file, system configuration (continued)DISABLE statement (continued)
COMMAND 47DIAGNOSE 48EXITS 49
ENABLE statementCMD 47COMMAND 47DIAGNOSE 48EXITS 49
MODIFY statementCMD 47COMMAND 47, 48EXIT 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
330 z/VM V6.4 CP Exit Customization
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
changing 117examining 117providing 112when prompted for 113, 118
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
changing 117examining 117providing 112when prompted for 113, 118
output datareceiving from CP exit routine 15
overviewCP message repository 231CP parser 73, 211
332 z/VM V6.4 CP Exit Customization
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
CPXLOAD of prohibiting 33CPXLOAD when unresolved 35SYSGEN when unresolved 35
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
EXIT 49MESSAGES 50MSGS 50
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
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
system execution spacedynamic area
definition 2loading code into 3, 39unloading code from 4
layout 2system initialization options
changing 117examining 117providing 112when prompted for 113, 118
Ttable
assigned CP exit number ranges 103CP exit macros 191CPXLOAD directives 177HCPXSERV register contents
after execution 197during execution 197
334 z/VM V6.4 CP Exit Customization
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
336 z/VM V6.4 CP Exit Customization
IBM®
Product Number: 5741-A07
Printed in USA
SC24-6176-03