z/VM: CP Planning and Administration - z/VM - IBM

z/VMCP Planning and AdministrationVersion 5 Release 1SC24-6083-01

z/VMCP Planning and AdministrationVersion 5 Release 1SC24-6083-01

Note:Before using this information and the product it supports, read the information under “Notices” on page 781.Second Edition (December 2004)This edition applies to version 5, release 1, modification 0 of IBM z/VM (product number 5741-A05) and to allsubsequent releases and modifications until otherwise indicated in new editions.This edition replaces SC24-6083-00.© Copyright International Business Machines Corporation 1991, 2004. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

ContentsAbout This Book . . . . . . . . . . . . . . . . . . . . . . . . xvWho Should Read This Book . . . . . . . . . . . . . . . . . . . . xvWhat You Should Know before Reading This Book . . . . . . . . . . . . xvHow to Read Syntax Diagrams . . . . . . . . . . . . . . . . . . . xviWhere to Find More Information . . . . . . . . . . . . . . . . . . xviiiHow to Send Your Comments to IBM . . . . . . . . . . . . . . . . xviiiSummary of Changes . . . . . . . . . . . . . . . . . . . . . xixSC24-6083-01, z/VM Version 5 Release 1, Updated Edition . . . . . . . . xixFibre Channel Protocol (FCP) Logical Unit Number (LUN) Access Control(APAR VM63328) . . . . . . . . . . . . . . . . . . . . . . xixSupport for the IBM TotalStorage DS8000 (APAR VM63534) . . . . . . . xixSC24-6083-00, z/VM Version 5 Release 1 . . . . . . . . . . . . . . . xixSCSI FCP Disk Support . . . . . . . . . . . . . . . . . . . . xixPCIX Cryptographic Coprocessor (PCIXCC) . . . . . . . . . . . . . xixEnhanced Guest LAN and Virtual Switch Authorization Support . . . . . . xixNetworking Enhancements . . . . . . . . . . . . . . . . . . . xixHyperswap Support . . . . . . . . . . . . . . . . . . . . . . xxRemoval of CP Functions . . . . . . . . . . . . . . . . . . . . xxConverting to System Configuration Files . . . . . . . . . . . . . . xxRemoval of Obsolete 370 References . . . . . . . . . . . . . . . xxSC24-6043-01, z/VM Version 4 Release 4 . . . . . . . . . . . . . . . xxNetworking Enhancements . . . . . . . . . . . . . . . . . . . xxHardware Configuration Definition (HCD) . . . . . . . . . . . . . . xxiCP Command Response Suppression . . . . . . . . . . . . . . . xxiGuest IPL from SCSI Disks . . . . . . . . . . . . . . . . . . . xxiMiscellaneous . . . . . . . . . . . . . . . . . . . . . . . . xxiPart 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Chapter 1. Planning and Administration Overview . . . . . . . . . . . 3Migration Planning . . . . . . . . . . . . . . . . . . . . . . . . 3Major z/VM Files . . . . . . . . . . . . . . . . . . . . . . . . . 3System Planning and Administration . . . . . . . . . . . . . . . . . 4User Planning and Administration . . . . . . . . . . . . . . . . . . 5Real and Virtual Storage Planning and Administration . . . . . . . . . . . 7Auxiliary Storage (Expanded Storage and DASD) Planning and Administration 7CP-Owned DASDs . . . . . . . . . . . . . . . . . . . . . . . 7Dedicated DASDs . . . . . . . . . . . . . . . . . . . . . . . 8DASDs Used for Minidisks . . . . . . . . . . . . . . . . . . . . 8DASD Space Used for Shared File Pools . . . . . . . . . . . . . . 9Expanded Storage . . . . . . . . . . . . . . . . . . . . . . . 9Virtual Disks in Storage . . . . . . . . . . . . . . . . . . . . . 9Terminals . . . . . . . . . . . . . . . . . . . . . . . . . . 10Unit Record Devices . . . . . . . . . . . . . . . . . . . . . . . 11Dedicated Unit Record Devices . . . . . . . . . . . . . . . . . . 11Spooled Unit Record Devices . . . . . . . . . . . . . . . . . . 11Performance Planning and Administration . . . . . . . . . . . . . . . 12I/O Reconfiguration in z/VM . . . . . . . . . . . . . . . . . . . . 12OpenExtensions Planning . . . . . . . . . . . . . . . . . . . . . 13Part 2. System Planning and Administration . . . . . . . . . . . . . . . . . . 15© Copyright IBM Corp. 1991, 2004 iii

Chapter 2. Configuring Your System . . . . . . . . . . . . . . . . 23Specifying System Configuration Information . . . . . . . . . . . . . . 23Using Configuration Files . . . . . . . . . . . . . . . . . . . . . 23What You Can Specify in the System Configuration File . . . . . . . . . . 24Contents of the System Configuration File . . . . . . . . . . . . . . 25What You Can Specify in the Logo Configuration File . . . . . . . . . . . 28Contents of the Logo Configuration File . . . . . . . . . . . . . . . 28Chapter 3. Understanding the CP File System . . . . . . . . . . . . 31Initial State of the CP File System . . . . . . . . . . . . . . . . . . 31Changing the List of Disks Accessed by CP . . . . . . . . . . . . . . 32Performance Considerations . . . . . . . . . . . . . . . . . . . . 33Displaying the Contents of CP-Accessed Minidisks . . . . . . . . . . . 33Changing Information on CP-Accessed Minidisks . . . . . . . . . . . . 34Chapter 4. Using the Stand-Alone Program Loader . . . . . . . . . . 37Creating the Stand-Alone Program Loader . . . . . . . . . . . . . . . 37Overriding the Console that CP Will Use . . . . . . . . . . . . . . 39Overriding Stand-Alone Program Loader Defaults . . . . . . . . . . . 39To IPL from a SCSI Disk . . . . . . . . . . . . . . . . . . . . 39The Stand-Alone Program Loader Screen . . . . . . . . . . . . . . 40Passing IPL Parameters . . . . . . . . . . . . . . . . . . . . . 42Chapter 5. Defining I/O Devices . . . . . . . . . . . . . . . . . . 45Device Support . . . . . . . . . . . . . . . . . . . . . . . . . 45Unsupported Devices . . . . . . . . . . . . . . . . . . . . . 46Device Sensing . . . . . . . . . . . . . . . . . . . . . . . . 46DASD . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Tapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Printers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Unit Record Devices . . . . . . . . . . . . . . . . . . . . . . . 48Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Communication Controllers . . . . . . . . . . . . . . . . . . . . 49ESCON Devices . . . . . . . . . . . . . . . . . . . . . . . . 49Other Devices . . . . . . . . . . . . . . . . . . . . . . . . . 50Chapter 6. The System Configuration File . . . . . . . . . . . . . . 51The Parm Disk . . . . . . . . . . . . . . . . . . . . . . . . . 51Summary of System Configuration File Statements . . . . . . . . . . . 51General Rules for Coding a System Configuration File . . . . . . . . . . 55Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Comments . . . . . . . . . . . . . . . . . . . . . . . . . 55Continuations . . . . . . . . . . . . . . . . . . . . . . . . 55Case . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Record Qualifiers . . . . . . . . . . . . . . . . . . . . . . . 56The Order of Statements in the File . . . . . . . . . . . . . . . . 57Checking the Syntax of Statements in the File . . . . . . . . . . . . 57ALTERNATE_OPERATORS Statement . . . . . . . . . . . . . . . . 58ASSOCIATE EXIT Statement . . . . . . . . . . . . . . . . . . . 60ASSOCIATE MESSAGES / MSGS Statement . . . . . . . . . . . . . 64CHARACTER_DEFAULTS Statement . . . . . . . . . . . . . . . . 67CP_ACCESS Statement . . . . . . . . . . . . . . . . . . . . . 70CP_ADDON_INITIALIZE_ROUTINES Statement . . . . . . . . . . . . 72CP_OWNED Statement . . . . . . . . . . . . . . . . . . . . . 73CPXLOAD Statement . . . . . . . . . . . . . . . . . . . . . . 76DEFINE ALIAS Statement . . . . . . . . . . . . . . . . . . . . . 81iv z/VM: CP Planning and Administration

DEFINE COMMAND / CMD Statement . . . . . . . . . . . . . . . . 84DEFINE DIAGNOSE Statement . . . . . . . . . . . . . . . . . . . 90DEFINE EXIT Statement . . . . . . . . . . . . . . . . . . . . . 94DEFINE LAN Statement . . . . . . . . . . . . . . . . . . . . . 97DEFINE VSWITCH Statement . . . . . . . . . . . . . . . . . . . 100DEVICES Statement . . . . . . . . . . . . . . . . . . . . . . 105DISABLE COMMAND / CMD Statement . . . . . . . . . . . . . . . 110DISABLE DIAGNOSE Statement . . . . . . . . . . . . . . . . . . 112DISABLE EXITS Statement . . . . . . . . . . . . . . . . . . . . 114DISTRIBUTE Statement . . . . . . . . . . . . . . . . . . . . . 116DRAIN (Disk) Statement . . . . . . . . . . . . . . . . . . . . . 118EDEVICE Statement . . . . . . . . . . . . . . . . . . . . . . 121EMERGENCY_MESSAGE_CONSOLES Statement . . . . . . . . . . . 124ENABLE COMMAND / CMD Statement . . . . . . . . . . . . . . . 126ENABLE DIAGNOSE Statement . . . . . . . . . . . . . . . . . . 128ENABLE EXITS Statement . . . . . . . . . . . . . . . . . . . . 130ENFORCE_BY_VOLid Statement . . . . . . . . . . . . . . . . . 132EQUATE Statement . . . . . . . . . . . . . . . . . . . . . . 133EXTERNAL_SYNTAX Statement . . . . . . . . . . . . . . . . . . 135FEATURES Statement . . . . . . . . . . . . . . . . . . . . . 136FORM_DEFAULT Statement . . . . . . . . . . . . . . . . . . . 150HOT_IO_RATE Statement . . . . . . . . . . . . . . . . . . . . 152IMBED Statement . . . . . . . . . . . . . . . . . . . . . . . 155INIT_MITIME Statement . . . . . . . . . . . . . . . . . . . . . 157IODF Statement . . . . . . . . . . . . . . . . . . . . . . . . 158JOURNALING Statement . . . . . . . . . . . . . . . . . . . . 160LOGO_CONFIG Statement . . . . . . . . . . . . . . . . . . . . 164MODIFY COMMAND / CMD Statement . . . . . . . . . . . . . . . 165MODIFY DIAGNOSE Statement . . . . . . . . . . . . . . . . . . 169MODIFY EXIT Statement . . . . . . . . . . . . . . . . . . . . . 172MODIFY LAN Statement . . . . . . . . . . . . . . . . . . . . . 175MODIFY PRIV_CLASSES Statement . . . . . . . . . . . . . . . . 176MODIFY VSWITCH Statement . . . . . . . . . . . . . . . . . . 178OPERATOR_CONSOLES Statement . . . . . . . . . . . . . . . . 180PRINTER_TITLE Statement . . . . . . . . . . . . . . . . . . . 182PRIV_CLASSES Statement . . . . . . . . . . . . . . . . . . . . 184PRODUCT Statement . . . . . . . . . . . . . . . . . . . . . . 186RDEVICE Statement . . . . . . . . . . . . . . . . . . . . . . 188RDEVICE Statement (Advanced Function Printers) . . . . . . . . . . . 189RDEVICE Statement (Card Punches) . . . . . . . . . . . . . . . . 190RDEVICE Statement (Card Readers) . . . . . . . . . . . . . . . . 192RDEVICE Statement (Communication Controllers) . . . . . . . . . . . 193RDEVICE Statement (DASD) . . . . . . . . . . . . . . . . . . . 195RDEVICE Statement (Graphic Display Devices) . . . . . . . . . . . . 197RDEVICE Statement (Impact Printers) . . . . . . . . . . . . . . . . 201RDEVICE Statement (Special Devices) . . . . . . . . . . . . . . . 205RDEVICE Statement (Tape Units) . . . . . . . . . . . . . . . . . 207RDEVICE Statement (Unsupported Devices) . . . . . . . . . . . . . 209RDEVICE Statement (3800 Printers) . . . . . . . . . . . . . . . . 212SAY Statement . . . . . . . . . . . . . . . . . . . . . . . . 217SET Statement . . . . . . . . . . . . . . . . . . . . . . . . 219START (Disk) Statement . . . . . . . . . . . . . . . . . . . . . 220STORAGE Statement . . . . . . . . . . . . . . . . . . . . . . 222SYSTEM_DATEFORMAT Statement . . . . . . . . . . . . . . . . 225SYSTEM_IDENTIFIER Statement . . . . . . . . . . . . . . . . . 226SYSTEM_IDENTIFIER_DEFAULT Statement . . . . . . . . . . . . . 228Contentsv

SYSTEM_RESIDENCE Statement . . . . . . . . . . . . . . . . . 230SYSTEM_USERIDS Statement . . . . . . . . . . . . . . . . . . 232THROTTLE Statement . . . . . . . . . . . . . . . . . . . . . 236TIMEZONE_BOUNDARY Statement . . . . . . . . . . . . . . . . 237TIMEZONE_DEFINITION Statement . . . . . . . . . . . . . . . . 239TOLERATE_CONFIG_ERRORS Statement . . . . . . . . . . . . . . 241TRANSLATE_TABLE Statement . . . . . . . . . . . . . . . . . . 243USERFORM Statement . . . . . . . . . . . . . . . . . . . . . 247USER_DEFAULTS System Configuration File Statement . . . . . . . . . 248USER_VOLUME_EXCLUDE Statement . . . . . . . . . . . . . . . 251USER_VOLUME_INCLUDE Statement . . . . . . . . . . . . . . . 253USER_VOLUME_LIST Statement . . . . . . . . . . . . . . . . . 255VMLAN Statement . . . . . . . . . . . . . . . . . . . . . . . 257XLINK_DEVICE_DEFAULTS Statement . . . . . . . . . . . . . . . 259XLINK_SYSTEM_EXCLUDE Statement . . . . . . . . . . . . . . . 263XLINK_SYSTEM_INCLUDE Statement . . . . . . . . . . . . . . . 264XLINK_VOLUME_EXCLUDE Statement . . . . . . . . . . . . . . . 266XLINK_VOLUME_INCLUDE Statement . . . . . . . . . . . . . . . 268XSPOOL_SYSTEM Statement . . . . . . . . . . . . . . . . . . . 271XSPOOL_TRACE Statement . . . . . . . . . . . . . . . . . . . 273XSPOOL_XLIST_INPUT Statement . . . . . . . . . . . . . . . . . 274XSPOOL_XLIST_OUTPUT Statement . . . . . . . . . . . . . . . . 276Chapter 7. The Logo Configuration File . . . . . . . . . . . . . . 279Using a Logo Configuration File . . . . . . . . . . . . . . . . . . 279Summary of Logo Configuration File Statements . . . . . . . . . . . . 279General Rules for Coding a Logo Configuration File . . . . . . . . . . . 279Format . . . . . . . . . . . . . . . . . . . . . . . . . . 279Comments . . . . . . . . . . . . . . . . . . . . . . . . . 279Continuations . . . . . . . . . . . . . . . . . . . . . . . . 280Case . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Categories . . . . . . . . . . . . . . . . . . . . . . . . . 281Precedence . . . . . . . . . . . . . . . . . . . . . . . . 281Selection . . . . . . . . . . . . . . . . . . . . . . . . . 282Creating Logo Screens . . . . . . . . . . . . . . . . . . . . . 282Special Considerations When Creating Logos . . . . . . . . . . . . 283CHOOSE_LOGO Statement . . . . . . . . . . . . . . . . . . . 285INPUT_AREA Statement . . . . . . . . . . . . . . . . . . . . . 291ONLINE_MESSAGE Statement . . . . . . . . . . . . . . . . . . 292STATUS Statement . . . . . . . . . . . . . . . . . . . . . . . 293Chapter 8. Setting Up Service Virtual Machines . . . . . . . . . . . 295Setting Up Virtual Machines for Accounting . . . . . . . . . . . . . . 295Setting Up Virtual Machines to Collect Accounting Records . . . . . . . . 297Specifying a New Accounting Virtual Machine . . . . . . . . . . . . 297Starting Manual Retrieval of Accounting Records . . . . . . . . . . . 297Disassociating a User ID from the Retrieval of Accounting Records . . . . 298Accounting Record Formats . . . . . . . . . . . . . . . . . . . 299Adding Your Own Accounting Records and Source Code . . . . . . . . 310Setting Up Virtual Machines for Error Recording . . . . . . . . . . . . 314Setting Up Virtual Machines to Collect EREP Records . . . . . . . . . . 315Specifying a New EREP Virtual Machine . . . . . . . . . . . . . . 316Starting EREP Record Retrieval Manually . . . . . . . . . . . . . 316Disassociating a User ID from the Retrieval of EREP Records . . . . . . 317Setting Up Virtual Machines for Symptom Record Recording . . . . . . . 318Setting Up Virtual Machines to Collect Symptom Records . . . . . . . . . 319vi z/VM: CP Planning and Administration

Specifying a New Symptom Record Recording Virtual Machine . . . . . . 319Starting Manual Retrieval of Symptom Records . . . . . . . . . . . 320Disassociating a User ID from the Retrieval of Symptom Records . . . . . 320Setting Up a Virtual Machine for Communication Controller Support forEmulator Program (EP) . . . . . . . . . . . . . . . . . . . . 321PVM Example . . . . . . . . . . . . . . . . . . . . . . . . 323Setting Up Service Pool Virtual Machines . . . . . . . . . . . . . . . 325Setting Up Print Services Facility/VM Virtual Machines . . . . . . . . . . 326Setting Up Virtual Machines for Data Storage Management . . . . . . . . 327Chapter 9. Planning for SNA Console Communication Services(SNA/CCS) . . . . . . . . . . . . . . . . . . . . . . . . . 329Structure of the SNA Environment . . . . . . . . . . . . . . . . . 329Establishing the SNA/CCS Terminal Environment . . . . . . . . . . . . 330Defining the VSM to z/VM . . . . . . . . . . . . . . . . . . . 330Defining Logos Used by VSMs . . . . . . . . . . . . . . . . . 330Defining SNA/CCS to VCNA . . . . . . . . . . . . . . . . . . 330Defining SNA/CCS to VSCS . . . . . . . . . . . . . . . . . . 331Enabling SNA Communication . . . . . . . . . . . . . . . . . . 331Starting the VTAM Service Machine . . . . . . . . . . . . . . . . 332Improving SNA/CCS Performance . . . . . . . . . . . . . . . . 332VSM Termination . . . . . . . . . . . . . . . . . . . . . . . 332Chapter 10. Setting Up Cross System Extensions (CSE) . . . . . . . . 333Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 333CSE Capabilities . . . . . . . . . . . . . . . . . . . . . . . 333Users Supported . . . . . . . . . . . . . . . . . . . . . . . 334Setting Up a CSE Complex . . . . . . . . . . . . . . . . . . . 334Planning for CSE . . . . . . . . . . . . . . . . . . . . . . . 334Requirements . . . . . . . . . . . . . . . . . . . . . . . . 334Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 335Supported Features . . . . . . . . . . . . . . . . . . . . . . 335Sharing DASD Volumes . . . . . . . . . . . . . . . . . . . . 336Spool File Directory Statements . . . . . . . . . . . . . . . . . 341Preparing for CSE . . . . . . . . . . . . . . . . . . . . . . 341Enabling CSE . . . . . . . . . . . . . . . . . . . . . . . . . 345Installing the VM/Pass-Through Facility and Its Modifications . . . . . . 345Defining CP for Each System . . . . . . . . . . . . . . . . . . 346Initializing the Volumes for Cross System Link . . . . . . . . . . . . 349Preparing the Communication Virtual Machine (CVM) . . . . . . . . . 350Verifying Your CSE Configuration . . . . . . . . . . . . . . . . . 353Verifying Cross System Link . . . . . . . . . . . . . . . . . . 353Enabling Cross System Spool . . . . . . . . . . . . . . . . . . 353Phasing CSE into the Production Environment . . . . . . . . . . . . 356Administering CSE . . . . . . . . . . . . . . . . . . . . . . . 358How Linking Works in z/VM . . . . . . . . . . . . . . . . . . . 358How CSE Extends Linking . . . . . . . . . . . . . . . . . . . 359CSE Area . . . . . . . . . . . . . . . . . . . . . . . . . 359VM I/O Performance Measurement for Shared DASD . . . . . . . . . 365What Is Cross System Spool? . . . . . . . . . . . . . . . . . . 366How CSE Extends Spooling . . . . . . . . . . . . . . . . . . 367VM/Pass-Through Facility Functions for Cross System Spool . . . . . . 371Multiple Concurrent Logon Sessions . . . . . . . . . . . . . . . 371Preparing to Deal with Outages . . . . . . . . . . . . . . . . . . 372Returning to Non-CSE Operation . . . . . . . . . . . . . . . . . 372Contentsvii

Chapter 11. Customizing the CP Message Function . . . . . . . . . . 373HCPMSU Module . . . . . . . . . . . . . . . . . . . . . . . 373Entry Point HCPMSUEX . . . . . . . . . . . . . . . . . . . . 374Changing and Adding to the CP Message Function . . . . . . . . . . . 377Chapter 12. Security and Integrity in z/VM . . . . . . . . . . . . . 379Security-Enhancing Products . . . . . . . . . . . . . . . . . . . 379Security Considerations and Guidelines . . . . . . . . . . . . . . . 380z/VM Security Facilities . . . . . . . . . . . . . . . . . . . . . 383Using an External Security Manager for Auditing and Protecting . . . . . 384Verifying Storage Access . . . . . . . . . . . . . . . . . . . . 384Clearing Temporary Disk Space . . . . . . . . . . . . . . . . . 384Permitting Bypassing of Directory Password Authorization . . . . . . . 385Journaling the LOGON, AUTOLOG, XAUTOLOG, and LINK Commands 385Automatic Deactivation of Restricted Passwords . . . . . . . . . . . 386Using Link Access Control Options . . . . . . . . . . . . . . . . 387Suppressing Passwords Entered on the Command Line . . . . . . . . 387Using an Integrated Cryptographic Facility . . . . . . . . . . . . . 387Maintaining System Integrity . . . . . . . . . . . . . . . . . . . 389z/VM System Integrity Requirements . . . . . . . . . . . . . . . 390z/VM Integrity and CP Function . . . . . . . . . . . . . . . . . 392Data Structures That Can Enhance System Integrity . . . . . . . . . 395z/VM Options That Can Enhance System Integrity . . . . . . . . . . 397Storage Handling . . . . . . . . . . . . . . . . . . . . . . 397Program Stack, Security, and Integrity . . . . . . . . . . . . . . . 398Reporting z/VM Integrity Problems . . . . . . . . . . . . . . . . 400Chapter 13. Using the Stand-Alone Dump Utility . . . . . . . . . . . 403Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 403Creating the Stand-Alone Dump Utility . . . . . . . . . . . . . . . . 403Before You Begin . . . . . . . . . . . . . . . . . . . . . . 404Devices You Can Use to IPL a Stand-Alone Dump . . . . . . . . . . 405Devices to Which You Can Send Dump Output . . . . . . . . . . . 406Example for Generating the Stand-Alone Dump Utility . . . . . . . . . 406Taking a Stand-Alone Dump . . . . . . . . . . . . . . . . . . . 408Processing the Stand-Alone Dump Data on Tape . . . . . . . . . . . . 409The HCPSADMP EXEC . . . . . . . . . . . . . . . . . . . . . 409Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . 409Chapter 14. Creating and Modifying Image Libraries for Printers . . . . . 411Creating Text Decks . . . . . . . . . . . . . . . . . . . . . . 411Creating Text Decks for the 3800 . . . . . . . . . . . . . . . . . 411Creating Text Decks for Impact Printers . . . . . . . . . . . . . . 412Using VMFHASM or VMFHLASM to Create a Text Deck . . . . . . . . 422Image Libraries . . . . . . . . . . . . . . . . . . . . . . . . 422Default Image Library Names . . . . . . . . . . . . . . . . . . 422Installing the Image Library That IBM Provides . . . . . . . . . . . . 423Installing Your Own Image Library . . . . . . . . . . . . . . . . 423Modifying Image Libraries . . . . . . . . . . . . . . . . . . . 424Displaying Information about Image Libraries . . . . . . . . . . . . 424Purging Image Libraries . . . . . . . . . . . . . . . . . . . . 425Keeping Backup Copies of Image Libraries . . . . . . . . . . . . . 425Where to Find More Information about Printers . . . . . . . . . . . . 425Chapter 15. CCW Translation . . . . . . . . . . . . . . . . . . 427Using CCW Translation . . . . . . . . . . . . . . . . . . . . . 427viii z/VM: CP Planning and Administration

Coding the Device Class Macroinstruction . . . . . . . . . . . . . . 427Unsupported Devices Tables . . . . . . . . . . . . . . . . . . . 428Device Macroinstruction . . . . . . . . . . . . . . . . . . . . . 429Part 3. User Planning and Administration . . . . . . . . . . . . . . . . . . 431Chapter 16. Redefining Command Privilege Classes . . . . . . . . . 433IBM-Defined Privilege Classes . . . . . . . . . . . . . . . . . . . 433Planning a New User Class Structure . . . . . . . . . . . . . . . . 434Defining Users’ Needs . . . . . . . . . . . . . . . . . . . . . 434Assigning Commands to Types of Users . . . . . . . . . . . . . . 435Associating Privilege Classes with Users and Commands . . . . . . . . 436Further Considerations . . . . . . . . . . . . . . . . . . . . 437Preparing and Activating the Override File . . . . . . . . . . . . . . 438Creating a Class Override File . . . . . . . . . . . . . . . . . . 438Class Override File Example . . . . . . . . . . . . . . . . . . 439Verifying and Activating the Override File . . . . . . . . . . . . . . 441Querying the User Class Restructure File . . . . . . . . . . . . . . 442Changing Back to the IBM-Defined User Classes . . . . . . . . . . . 442Another Way of Changing the Privilege Class of Certain CP Functions 443Changing the Directory . . . . . . . . . . . . . . . . . . . . . 443Defining Privilege Classes for a Virtual Machine . . . . . . . . . . . 444How Users Can Find Which Commands They Can Enter . . . . . . . . 446Chapter 17. Creating and Updating a User Directory . . . . . . . . . 447Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 447Creating the User Directory . . . . . . . . . . . . . . . . . . . . 451Continued Directory Control Statements . . . . . . . . . . . . . . . 452Quoted String Operands . . . . . . . . . . . . . . . . . . . . . 452Running the User Directory Program . . . . . . . . . . . . . . . . 453Changing the Directory . . . . . . . . . . . . . . . . . . . . . 454Checking a Directory for Errors . . . . . . . . . . . . . . . . . . 454Specifying a Directory That Contains VM/SP Control Statements . . . . . . 455Creating Directory Profiles . . . . . . . . . . . . . . . . . . . . 455Determining How Much Space the Directory Needs . . . . . . . . . . . 455ACCOUNT Directory Control Statement (General) . . . . . . . . . . . 456ACIGROUP Directory Control Statement (General) . . . . . . . . . . . 458APPCPASS Directory Control Statement (General) . . . . . . . . . . . 459AUTOLOG Directory Control Statement (General) . . . . . . . . . . . 461CLASS Directory Control Statement (General) . . . . . . . . . . . . . 462CONSOLE Directory Control Statement (Device) . . . . . . . . . . . . 463CPU Directory Control Statement (General) . . . . . . . . . . . . . . 465CRYPTO Directory Control Statement (General) . . . . . . . . . . . . 468DASDOPT Directory Control Statement (Device) . . . . . . . . . . . . 472DATEFORMAT Directory Control Statement (General) . . . . . . . . . . 475DEDICATE Directory Control Statement (Device) . . . . . . . . . . . . 477DIRECTORY Directory Control Statement (Control) . . . . . . . . . . . 480D8ONECMD Directory Control Statement (General) . . . . . . . . . . . 483GLOBALDEFS Directory Control Statement (Control) . . . . . . . . . . 485GLOBALOPTS Directory Control Statement (Control) . . . . . . . . . . 486INCLUDE Directory Control Statement (General) . . . . . . . . . . . . 487IOPRIORITY Directory Control Statement (General) . . . . . . . . . . . 488IPL Directory Control Statement (General) . . . . . . . . . . . . . . 490IUCV Directory Control Statement (General) . . . . . . . . . . . . . 493LINK Directory Control Statement (Device) . . . . . . . . . . . . . . 500LOAD Directory Control Statement (Control) . . . . . . . . . . . . . 504Contentsix

LOADDEV Directory Control Statement (General) . . . . . . . . . . . 507LOGONBY Directory Control Statement (General) . . . . . . . . . . . 509MACHINE Directory Control Statement (General) . . . . . . . . . . . . 510MAXSTORAGE Directory Control Statement (General) . . . . . . . . . . 512MDISK Directory Control Statement (Device) . . . . . . . . . . . . . 513MINIOPT Directory Control Statement (Device) . . . . . . . . . . . . 524NAMESAVE Directory Control Statement (General) . . . . . . . . . . . 527NICDEF Directory Control Statement (Device) . . . . . . . . . . . . . 529NOPDATA Directory Control Statement (General) . . . . . . . . . . . . 532OPTION Directory Control Statement (General) . . . . . . . . . . . . 533POOL Directory Control Statement (General) . . . . . . . . . . . . . 540POSIXGLIST Directory Control Statement (General). . . . . . . . . . . 541POSIXGROUP Directory Control Statement (Control) . . . . . . . . . . 543POSIXINFO Directory Control Statement (General) . . . . . . . . . . . 545POSIXOPT Directory Control Statement (General) . . . . . . . . . . . 548PROFILE Directory Control Statement (Control) . . . . . . . . . . . . 551SCREEN Directory Control Statement (General) . . . . . . . . . . . . 553SHARE Directory Control Statement (General) . . . . . . . . . . . . . 555SPECIAL Directory Control Statement (Device) . . . . . . . . . . . . 557SPOOL Directory Control Statement (Device) . . . . . . . . . . . . . 562SPOOLFILE Directory Control Statement (General) . . . . . . . . . . . 565STDEVOPT Directory Control Statement (General) . . . . . . . . . . . 566STORAGE Directory Control Statement (General) . . . . . . . . . . . 568SYSAFFIN Directory Control Statement (Control) . . . . . . . . . . . . 569USER Directory Control Statement (Control) . . . . . . . . . . . . . 572XAUTOLOG Directory Control Statement (General) . . . . . . . . . . . 578XCONFIG Directory Control Statement (General) . . . . . . . . . . . . 580XCONFIG ACCESSLIST Operand . . . . . . . . . . . . . . . . . 581XCONFIG ADDRSPACE Operand . . . . . . . . . . . . . . . . . 583XSTORE Directory Control Statement (General) . . . . . . . . . . . . 585Part 4. Storage Planning and Administration . . . . . . . . . . . . . . . . . 587x z/VM: CP Planning and AdministrationChapter 18. Real Storage Planning and Administration . . . . . . . . 589Planning Real Storage Needs . . . . . . . . . . . . . . . . . . . 589Real and Virtual Storage Requirements for Generating a CP Module . . . . 589Determining the Size of the Dynamic Paging Area . . . . . . . . . . . 590Virtual Machine Considerations . . . . . . . . . . . . . . . . . . 590Chapter 19. Expanded Storage Planning and Administration . . . . . . 591Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 591Expanded Storage Considerations with Shared CMS Minidisks . . . . . . . 592Attaching Expanded Storage to a Virtual Machine . . . . . . . . . . . 592Mapping Expanded Storage . . . . . . . . . . . . . . . . . . . 593Fragmentation . . . . . . . . . . . . . . . . . . . . . . . . 593Discontinuous Expanded Storage . . . . . . . . . . . . . . . . 593Allocating Expanded Storage to CP . . . . . . . . . . . . . . . . . 596Allocating Retained Expanded Storage . . . . . . . . . . . . . . 596Pending Retained Expanded Storage . . . . . . . . . . . . . . . 597Using Expanded Storage as a Minidisk Cache . . . . . . . . . . . . . 597What Devices Can Be Cached . . . . . . . . . . . . . . . . . 600Turning Caching Off . . . . . . . . . . . . . . . . . . . . . 600Planning for and Using Minidisk Caching . . . . . . . . . . . . . . 600Chapter 20. Allocating DASD Space . . . . . . . . . . . . . . . . 603Direct Access Storage Requirements . . . . . . . . . . . . . . . . 603

CKD Device Geometry . . . . . . . . . . . . . . . . . . . . 603FBA Device Geometry . . . . . . . . . . . . . . . . . . . . . 604Storage Calculations . . . . . . . . . . . . . . . . . . . . . 604CP Module . . . . . . . . . . . . . . . . . . . . . . . . . . 605Warm Start Data . . . . . . . . . . . . . . . . . . . . . . . . 606Example . . . . . . . . . . . . . . . . . . . . . . . . . . 607Checkpoint Data . . . . . . . . . . . . . . . . . . . . . . . . 607Directory Space . . . . . . . . . . . . . . . . . . . . . . . . 608Example . . . . . . . . . . . . . . . . . . . . . . . . . . 609Directory Size Constraints . . . . . . . . . . . . . . . . . . . 610Paging Space . . . . . . . . . . . . . . . . . . . . . . . . . 610Example . . . . . . . . . . . . . . . . . . . . . . . . . . 611Spooling Space . . . . . . . . . . . . . . . . . . . . . . . . 613Allocating Space for CP Abend Dumps . . . . . . . . . . . . . . 614Named Saved System . . . . . . . . . . . . . . . . . . . . . 615Spool Space Example . . . . . . . . . . . . . . . . . . . . . 615Switching Operating Modes for 3390 Devices . . . . . . . . . . . . . 615Mode Switch Procedure . . . . . . . . . . . . . . . . . . . . 616Migration Considerations for the 3390 Model 9 . . . . . . . . . . . . . 617Chapter 21. DASD Sharing . . . . . . . . . . . . . . . . . . . 619Sharing DASD among Multiple Virtual Machines by Using VirtualReserve/Release . . . . . . . . . . . . . . . . . . . . . . . 619When to Use Virtual Reserve/Release . . . . . . . . . . . . . . . 621Sharing DASD without Using Virtual Reserve/Release . . . . . . . . . . 622Sharing DASD Using the CMS Shared File System . . . . . . . . . . . 622Sharing DASD between One Virtual Machine and Other Systems Using RealReserve/Release . . . . . . . . . . . . . . . . . . . . . . . 622When to Use Real Reserve/Release . . . . . . . . . . . . . . . 624Sharing DASD among Multiple Virtual Machines and Other Systems UsingConcurrent Virtual and Real Reserve/Release . . . . . . . . . . . . 624When to Use Concurrent Virtual and Real Reserve/Release . . . . . . . 626Restrictions for Using Reserve/Release . . . . . . . . . . . . . . . 626Reserve/Release Summary . . . . . . . . . . . . . . . . . . . . 626Sharing DASD using the Multi-Path Lock Facility . . . . . . . . . . . . 627Cached DASD . . . . . . . . . . . . . . . . . . . . . . . . 628Cache Control . . . . . . . . . . . . . . . . . . . . . . . . 628Defining a Minidisk on a Cached DASD . . . . . . . . . . . . . . 629Defining a Cached DASD as a Dedicated Device . . . . . . . . . . . 630Using ESS Parallel Access Volumes . . . . . . . . . . . . . . . . 631Using PAV for Workload Balancing . . . . . . . . . . . . . . . . 631Using PAV for DASD Sharing . . . . . . . . . . . . . . . . . . 632z/VM Restrictions on Using PAV . . . . . . . . . . . . . . . . . 633Chapter 22. Defining and Managing SCSI FCP Disks . . . . . . . . . 635Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 635Defining SCSI Devices . . . . . . . . . . . . . . . . . . . . . 637Emulated FBA Disks on SCSI Disks . . . . . . . . . . . . . . . 637Real SCSI Disks . . . . . . . . . . . . . . . . . . . . . . . 638Additional Considerations . . . . . . . . . . . . . . . . . . . . 639Appendix A. Sample Utility Programs . . . . . . . . . . . . . . . 641DRAWLOGO . . . . . . . . . . . . . . . . . . . . . . . . . 642Appendix B. Defining Your System (HCPSYS Macroinstructions) . . . . 643Coding HCPSYS ASSEMBLE . . . . . . . . . . . . . . . . . . . 644Contentsxi

CSELDEV (Optional) . . . . . . . . . . . . . . . . . . . . . . 646CSELVOL EXCLUDE (Optional) . . . . . . . . . . . . . . . . . . 649CSELVOL INCLUDE (Optional) . . . . . . . . . . . . . . . . . . 650CSESYS (Optional). . . . . . . . . . . . . . . . . . . . . . . 653CSETRACE (Optional) . . . . . . . . . . . . . . . . . . . . . 658CSEUSER (Optional) . . . . . . . . . . . . . . . . . . . . . . 659SYSACNT (Optional) . . . . . . . . . . . . . . . . . . . . . . 661SYSADDIN (Optional) . . . . . . . . . . . . . . . . . . . . . . 663SYSCPVOL (Required) . . . . . . . . . . . . . . . . . . . . . 664SYSDUMP (Optional) . . . . . . . . . . . . . . . . . . . . . . 667SYSEND (Required) . . . . . . . . . . . . . . . . . . . . . . 668SYSEREP (Optional) . . . . . . . . . . . . . . . . . . . . . . 669SYSEXCL (Optional) . . . . . . . . . . . . . . . . . . . . . . 671SYSFCN (Optional). . . . . . . . . . . . . . . . . . . . . . . 673SYSFORM (Optional) . . . . . . . . . . . . . . . . . . . . . . 675SYSID (Optional) . . . . . . . . . . . . . . . . . . . . . . . 677SYSINCL (Optional) . . . . . . . . . . . . . . . . . . . . . . 680SYSJRL (Optional) . . . . . . . . . . . . . . . . . . . . . . . 682SYSMAXU (Optional) . . . . . . . . . . . . . . . . . . . . . . 686SYSOPR (Required) . . . . . . . . . . . . . . . . . . . . . . 687SYSOPTS (Optional) . . . . . . . . . . . . . . . . . . . . . . 689SYSPCLAS (Optional). . . . . . . . . . . . . . . . . . . . . . 691SYSRES (Required) . . . . . . . . . . . . . . . . . . . . . . 693SYSSTORE (Required) . . . . . . . . . . . . . . . . . . . . . 697SYSSYMP (Optional) . . . . . . . . . . . . . . . . . . . . . . 699SYSTIME (Required) . . . . . . . . . . . . . . . . . . . . . . 701SYSUVOL (Optional) . . . . . . . . . . . . . . . . . . . . . . 703Appendix C. Defining I/O Devices Using HCPRIO . . . . . . . . . . . 705Coding HCPRIO ASSEMBLE . . . . . . . . . . . . . . . . . . . 705RDEVICE Macroinstructions . . . . . . . . . . . . . . . . . . . 706RDEVICE—General Usage Notes . . . . . . . . . . . . . . . . 707Dedicated AFP* Printers . . . . . . . . . . . . . . . . . . . . . 707Common Control Unit (CCU) Printers . . . . . . . . . . . . . . . 7083820 Printer . . . . . . . . . . . . . . . . . . . . . . . . 710Printers Attached to a Display Control Unit . . . . . . . . . . . . . . 712Display Printers . . . . . . . . . . . . . . . . . . . . . . . 713CP System-Managed Impact Printers . . . . . . . . . . . . . . . . 715Impact Printers . . . . . . . . . . . . . . . . . . . . . . . 716CP System-Managed 3800 Printers . . . . . . . . . . . . . . . . . 7203800 Printer . . . . . . . . . . . . . . . . . . . . . . . . 721Unit Record Devices . . . . . . . . . . . . . . . . . . . . . . 7263505 Card Reader . . . . . . . . . . . . . . . . . . . . . . 7273525 Card Punch . . . . . . . . . . . . . . . . . . . . . . 7293890 Document Processor . . . . . . . . . . . . . . . . . . . 731Display Terminals and Adapters . . . . . . . . . . . . . . . . . . 7323250 Display . . . . . . . . . . . . . . . . . . . . . . . . 7333270-Family Displays . . . . . . . . . . . . . . . . . . . . . 734Teleprocessing Integrated Adapters . . . . . . . . . . . . . . . . 7385080 and 6090 Graphics Display . . . . . . . . . . . . . . . . . 740Tape Units . . . . . . . . . . . . . . . . . . . . . . . . . . 7423422, 3480, 3490 and 3590 Tape Drives . . . . . . . . . . . . . . 743DASD . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745DASD Types . . . . . . . . . . . . . . . . . . . . . . . . 746FBA DASD . . . . . . . . . . . . . . . . . . . . . . . . . 749Communication Devices . . . . . . . . . . . . . . . . . . . . . 751xii z/VM: CP Planning and Administration

2701 Data Adapter . . . . . . . . . . . . . . . . . . . . . . 7523705, 3725, and 3745 Line Adapters, 2741 Terminal, and 3151, 3161, 3162,3163, and 3167 Display Terminals . . . . . . . . . . . . . . . 75437xx Communications Controllers and 3x74 Controllers . . . . . . . . 757CTCA, 3088 Multisystem Channel Communication Unit, and 3737 RemoteChannel-to-Channel Unit . . . . . . . . . . . . . . . . . . . 760Dynamic Switching Devices . . . . . . . . . . . . . . . . . . . . 7619032 and 9033 ES Connection Directors (ESCDs) . . . . . . . . . . 762Unsupported Devices . . . . . . . . . . . . . . . . . . . . . 763RIOGEN . . . . . . . . . . . . . . . . . . . . . . . . . . . 766Appendix D. Configuration Guide for Printers . . . . . . . . . . . . 769Appendix E. Device Class and Type Codes . . . . . . . . . . . . . 773Device Class Definitions . . . . . . . . . . . . . . . . . . . . . 773Device Type Definitions within Device Classes . . . . . . . . . . . . . 773Device Features by Class and Type . . . . . . . . . . . . . . . . . 775Device Model Definitions . . . . . . . . . . . . . . . . . . . . . 775Appendix F. Stand-Alone Dump Formats . . . . . . . . . . . . . . 777Tape Format . . . . . . . . . . . . . . . . . . . . . . . . . 777DASD Format . . . . . . . . . . . . . . . . . . . . . . . . . 779Printer Format . . . . . . . . . . . . . . . . . . . . . . . . . 780Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 781Programming Interface Information . . . . . . . . . . . . . . . . . 782Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . 783Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . 785Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . 787Where to Get z/VM Books . . . . . . . . . . . . . . . . . . . . 787z/VM Base Library . . . . . . . . . . . . . . . . . . . . . . . 787System Overview . . . . . . . . . . . . . . . . . . . . . . 787Installation and Service . . . . . . . . . . . . . . . . . . . . 787Planning and Administration . . . . . . . . . . . . . . . . . . . 787Customization . . . . . . . . . . . . . . . . . . . . . . . . 787Operation . . . . . . . . . . . . . . . . . . . . . . . . . 787Application Programming . . . . . . . . . . . . . . . . . . . . 787End Use . . . . . . . . . . . . . . . . . . . . . . . . . . 788Diagnosis . . . . . . . . . . . . . . . . . . . . . . . . . 788Books for z/VM Optional Features . . . . . . . . . . . . . . . . . 788Data Facility Storage Management Subsystem for VM . . . . . . . . . 788Directory Maintenance Facility . . . . . . . . . . . . . . . . . . 788Performance Toolkit for VM . . . . . . . . . . . . . . . . . . . 789Resource Access Control Facility . . . . . . . . . . . . . . . . . 789Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791Contentsxiii

xiv z/VM: CP Planning and Administration

About This BookThis book tells you how to plan and administer your IBM ® z/VM ® system. Itdescribes the following tasks:v System planning and administrationv Dynamic I/O configuration planningv User planning and administrationv Storage planning and administrationv Saved Segment planning and administrationv CMS planning and administration.System planning and administration are tasks that overlap. Before installation ofz/VM, you need to plan:v What the processor and device configuration will bev What z/VM functions the system will usev Which guest operating systems will be usedv How much storage will be requiredWho Should Read This Bookv What sort of user environments will be available.During system generation, you will set the proper parameters in the system toimplement your plan for the system. Later, after the system is running, you will wantto change some of these parameters as conditions change; for example, when newusers are allowed access to the system and new devices are brought online. Youwill also want to monitor the performance of the system and perhaps change tuningparameters to make it run more efficiently.A good example of the overlap between planning and administration is the userdirectory. The user directory is a file that identifies each user on the system andcontains control statements that define the environment each user works under.Initially, you will set up this directory for the known users of the system. Later, asnew users are given access to the system and others are removed, you will have toupdate the directory.Some information provided here is based on the experiences of IBM customers.The recommendations in this publication are meant to help installations runoperating systems efficiently under z/VM.This manual is for anyone responsible for planning, installing, and updating a z/VMsystem.What You Should Know before Reading This BookThe reader is expected to have a general understanding of data processing andteleprocessing techniques. This book assumes you have thought about:v What z/VM functions your site requiresv What connections you need to other sites and the implications for coordinationv What your hardware and physical requirements are and the implications forcoordinationv Which guest operating systems you will be running© Copyright IBM Corp. 1991, 2004 xv

v How many users you are going to have and what sort of environment they will berunning their applications under.How to Read Syntax DiagramsThis book uses syntax diagrams to show the operands and options of externalinterfaces and statements.Getting Started: To read a syntax diagram, follow the path of the line. Read fromleft to right and top to bottom.v The ►►─── symbol indicates the beginning of a syntax diagram.v The ───► symbol, at the end of a line, indicates that the syntax diagramcontinues on the next line.v The ►─── symbol, at the beginning of a line, indicates that a syntax diagramcontinues from the previous line.v The ───►◄ symbol indicates the end of a syntax diagram.Syntax items (for example, a keyword or variable) may be:v Directly on the line (required)v Above the line (default)v Below the line (optional).Syntax Diagram Description ExampleAbbreviations:Uppercase letters denote the shortest acceptableabbreviation. If an item appears entirely in uppercaseletters, it cannot be abbreviated.You can type the item in uppercase letters, lowercaseletters, or any combination.►► KEYWOrd ►◄In this example, you can enter KEYWO, KEYWOR, orKEYWORD in any combination of uppercase andlowercase letters.Symbols:You must code these symbols exactly as they appearin the syntax diagram.Variables:Highlighted lowercase items (like this) denotevariables.* Asterisk: Colon, Comma= Equal Sign- Hyphen() Parentheses. Period►► KEYWOrd var_name ►◄In this example, var_name represents a variable youmust specify when you code the KEYWORDinstruction.Repetition:An arrow returning to the left means that the item canbe repeated. ►► ▼ repeat ►◄xvi z/VM: CP Planning and Administration

Syntax Diagram Description ExampleA character within the arrow means you mustseparate repeated items with that character.,►►▼repeat►◄A footnote (1) by the arrow references a limit that tellshow many times the item can be repeated.►► ▼ (1) repeat ►◄Notes:1 Specify repeat up to 5 times.Required Choices:When two or more items are in a stack and one ofthem is on the line, you must specify one item.►►ABC►◄In this example, you must choose A, B, or C.Optional Choice:When an item is below the line, the item is optional. Inthis example, you can choose A or nothing at all.►►A►◄When two or more items are in a stack below the line,all of them are optional. In this example, you canchoose A, B, C, or nothing at all.►►ABC►◄Defaults:Defaults are above the line. The system uses thedefault unless you override it. You can override thedefault by coding an option from the stack below theline.►►ABC►◄In this example, A is the default. You can override Aby choosing B or C.Repeatable Choices:A stack of items followed by an arrow returning to theleft means that you can select more than one item or,in some cases, repeat a single item.In this example, you can choose any combination ofA, B, or C.Syntax Fragments: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 heading withthe same fragment name.In this example, the fragment is named “A Fragment.”►► ▼ ABC►◄►► A Fragment ►◄A Fragment:ABCAbout This Book xvii

Where to Find More InformationFor more information about z/VM functions, see the books listed in the“Bibliography” on page 787.If you plan to deploy Linux ® on z/VM, read z/VM: Getting Started with Linux onzSeries for important planning information about Linux virtual servers.Links to Other Online BooksIf you are viewing the Adobe Portable Document Format (PDF) version of thisbook, it may contain links to other books. A link to another book is based onthe name of the requested PDF file. The name of the PDF file for an IBM bookis unique and identifies both the book and the edition. The book links providedin this book are for the editions (PDF names) that were current when the PDFfile for this book was generated. However, newer editions of some books (withdifferent PDF names) may exist. A link from this book to another book worksonly when a PDF file with the requested name resides in the same directoryas this book.How to Send Your Comments to IBMIBM welcomes your comments. You can send us comments about this book orother VM documentation using any of the following methods:v Complete and mail the Readers’ Comments form (if one is provided at the backof this book) or send your comments to the following address:IBM CorporationDepartment 55JA, Mail Station P3842455 South RoadPoughkeepsie, New York 12601-5400U.S.A.FAX (United States and Canada): 1-845-432-9405FAX (Other Countries): +1 845 432 9405v Send your comments by electronic mail to one of the following addresses:– Internet: mhvrcfs@us.ibm.com– IBMLink (US customers only): IBMUSM10(MHVRCFS)v Submit your comments through the VM Feedback page (“Contact z/VM”) on thez/VM Web site at www.ibm.com/eserver/zseries/zvm/forms/.Please provide the following information in your comment or note:v Title and complete publication number of the book (including the suffix)v Page number, section title, or topic you are commenting onIf you would like a reply, be sure to include your name, postal or email address, andtelephone or FAX number.When you send information to IBM, you grant IBM a nonexclusive right to use ordistribute the information in any way it believes appropriate without incurring anyobligation to you.xviii z/VM: CP Planning and Administration

Summary of ChangesThis book 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.SC24-6083-01, z/VM Version 5 Release 1, Updated EditionThis edition includes support announced after the announcement of z/VM Version 5Release 1 (z/VM V5R1) or programming enhancements provided after the generalavailability of z/VM V5R1. These programming enhancements may be providedthrough z/VM service by program temporary fixes (PTFs) for authorized programanalysis reports (APARs), as indicated.Fibre Channel Protocol (FCP) Logical Unit Number (LUN) AccessControl (APAR VM63328)Updates in this book include:v In Chapter 17, “Creating and Updating a User Directory,” on page 447, theDEDICATE statement was updated.Support for the IBM TotalStorage ® DS8000 (APAR VM63534)z/VM support for the high-capacity DS8000 allows the definition of SCSI FCP disksup to 2,147,483,640 512-byte blocks (1 terabyte minus 1 page) in size. A new 2107attribute has been added to the EDEVICE system configuration statement.SC24-6083-00, z/VM Version 5 Release 1This edition supports the general availability of z/VM Version 5 Release 1 (z/VMV5R1)SCSI FCP Disk SupportUpdates in this book include:v A new chapter, Chapter 22, “Defining and Managing SCSI FCP Disks,” on page635, was added.v In Chapter 6, “The System Configuration File,” on page 51, the EDEVICEstatement was added.PCIX Cryptographic Coprocessor (PCIXCC)Updates in this book include:v In Chapter 17, “Creating and Updating a User Directory,” on page 447, theCRYPTO statement was updated.Enhanced Guest LAN and Virtual Switch Authorization SupportUpdates in this book include:v In Chapter 6, “The System Configuration File,” on page 51, the MODIFY LANand MODIFY VSWITCH statements were updated.NetworkingEnhancementsUpdates in this book include:© Copyright IBM Corp. 1991, 2004 xix

v In Chapter 6, “The System Configuration File,” on page 51, the DEFINEVSWITCH statement was updated.HyperswapSupportUpdates in this book include:v In Chapter 6, “The System Configuration File,” on page 51, the newENFORCE_BY_VOLid statement was added to the System Configuration FileStatements.Removal of CP Functionsz/VM V5R1 is designed to operate only on IBM zSeries ® , or equivalent servers thatsupport IBM z/Architecture (64-bit). As a result, certain functions are not providedby z/VM V5R1:v IPL from a 31-bit image of the CP nucleusv Preferred (V=R and V=F) virtual machinesv Paging of the CP nucleusSeveral system configuration statements and directory control statements havebeen updated. For information about the affected external interfaces, see the z/VM:Migration Guide.Converting to System Configuration FilesIBM assumes that you are using configuration files to define the characteristics ofyour z/VM system. Accordingly, most references to using the system control file(HCPSYS ASSEMBLE), system real I/O configuration file (HCPRIO ASSEMBLE),and system logo definition file (HCPBOX ASSEMBLE) have been removed.Although the HCPSYS and HCPRIO macroinstructions are still documented in theappendixes of this book, IBM discourages their use. If you are still using thesemacros to define your system, IBM strongly recommends that you convert to usingconfiguration files. Using the ASSEMBLE files is more difficult and error-prone,requires knowledge of the Assembler H Version 2 Licensed Program, does notsupport recent CP enhancements, and requires rebuilding the CP module aftermaking changes.The “Converting to System Configuration Files” chapter has been removed from thisbook. See the z/VM: Migration Guide for information that can assist you in migratingyour system definition data to configuration files.Removal of Obsolete 370 ReferencesSystem/370 architecture (370 mode) virtual machines are not supported on z/VMVersion 4 or later. Obsolete 370 references have been removed. However, 370Accommodation is still supported.SC24-6043-01, z/VM Version 4 Release 4This edition supports the general availability of z/VM Version 4 Release 4 (z/VMV4R4).NetworkingEnhancementsUpdates in this book include:xx z/VM: CP Planning and Administration

v In Chapter 6, “The System Configuration File,” on page 51, three newstatements, DEFINE VSWITCH, MODIFY VSWITCH, and MODIFY LAN, wereadded to the System Configuration File Statements. Also, the VMLAN statementwas updated.v In Chapter 8, “Setting Up Service Virtual Machines,” on page 295, columns35–42 and 43–50, under Accounting Records Network Data Transmissions(Record Type C), were updated.v In Chapter 17, “Creating and Updating a User Directory,” on page 447, the IUCVDirectory Control Statement and the SPECIAL Directory Control Statement wereupdated. A new statement, NICDEF Directory Control Statement, was added.Hardware Configuration Definition (HCD)Hardware Configuration Definition (HCD), along with Hardware ConfigurationManager (HCM), are components of z/VM that work together to create and manageyour z/VM I/O configuration. Updates in this book include:v Additional material in Chapter 1, “Planning and Administration Overview,” onpage 3, Chapter 2, “Configuring Your System,” on page 23, and Chapter 5,“Defining I/O Devices,” on page 45 to reflect the new HCD support. While theoriginal command-based dynamic I/O configuration capabilities of z/VM are stillvalid, the use of HCM and HCD is incompatible with those commands. Youshould choose one method or the other and stay with it for the duration of anygiven IPL of your z/VM system.v A new system configuration file statement, IODF, which indicates that HCD willbe used to control the I/O hardware and/or software configuration. See “IODFStatement” on page 158.v In Chapter 4, “Using the Stand-Alone Program Loader,” on page 37, a new IPLoption, NOHCD, which specificies that CP should ignore any IODF statements inthe system configuration file.For more information on HCD and HCM, see z/VM: I/O Configuration.CP Command Response SuppressionThe SILENT operand has been added to the DEFINE COMMAND / CMD andMODIFY COMMAND / CMD system configuration statements to enable responsesuppression for the CP command being defined or redefined.Guest IPL from SCSI DisksThe directory control statement, LOADDEV, was added to Chapter 17, “Creatingand Updating a User Directory,” on page 447. LOADDEV is used to identify thelocation of a program to be loaded as a result of an FCP–attached SCSI disk (Linuxand other guest operating systems) IPL.Miscellaneousv Information about using the CP Access Control Interface has been moved to thez/VM: Service Guide.v A new parameter (FCTC) was added to the SPECIAL directory control statement.This supports Virtual FICON CTCA.Summary of Changes xxi

xxii z/VM: CP Planning and Administration

Part 1. OverviewChapter 1. Planning and Administration Overview . . . . . . . . . . . 3Migration Planning . . . . . . . . . . . . . . . . . . . . . . . . 3Major z/VM Files . . . . . . . . . . . . . . . . . . . . . . . . . 3System Planning and Administration . . . . . . . . . . . . . . . . . 4User Planning and Administration . . . . . . . . . . . . . . . . . . 5Real and Virtual Storage Planning and Administration . . . . . . . . . . . 7Auxiliary Storage (Expanded Storage and DASD) Planning and Administration 7CP-Owned DASDs . . . . . . . . . . . . . . . . . . . . . . . 7Dedicated DASDs . . . . . . . . . . . . . . . . . . . . . . . 8DASDs Used for Minidisks . . . . . . . . . . . . . . . . . . . . 8DASD Space Used for Shared File Pools . . . . . . . . . . . . . . 9Expanded Storage . . . . . . . . . . . . . . . . . . . . . . . 9Virtual Disks in Storage . . . . . . . . . . . . . . . . . . . . . 9Terminals . . . . . . . . . . . . . . . . . . . . . . . . . . 10Unit Record Devices . . . . . . . . . . . . . . . . . . . . . . . 11Dedicated Unit Record Devices . . . . . . . . . . . . . . . . . . 11Spooled Unit Record Devices . . . . . . . . . . . . . . . . . . 11Performance Planning and Administration . . . . . . . . . . . . . . . 12I/O Reconfiguration in z/VM . . . . . . . . . . . . . . . . . . . . 12OpenExtensions Planning . . . . . . . . . . . . . . . . . . . . . 13© Copyright IBM Corp. 1991, 2004 1

2 z/VM: CP Planning and Administration

Chapter 1. Planning and Administration OverviewThis chapter summarizes planning and administration tasks for the z/VM licensedprogram. Planning involves deciding how your system will be organized, configured,and used. Administration involves setting up, configuring, and modifying the system.Planning tasks and administration tasks are discussed together in this manualbecause the tasks are interrelated.When planning for users, for example, it is useful to know how user IDs are addedafter the system is installed and running. You might then decide to define a minimalset of user IDs initially (perhaps those needed for key personnel, service machines,and guest operating systems), and add other user IDs later.User IDs and many other aspects of the system configuration are defined bystatements in z/VM files. Many administration tasks involve changing those files andthen processing the files in some way to activate the changes. This chaptercontains overviews of the following files:v System configuration filev Logo configuration filev User directory.These files are used in the planning and administration tasks for:v The systemvvvUsersStoragePerformance.Although this chapter does not describe how to perform any planning oradministration tasks, it tells you where to find information that does.This manual covers planning and administration for the base CP system. Thecomplete set of manuals is listed under the “Planning and Administration” section ofthe “Bibliography” on page 787. Other manuals focus on topics such asconnectivity, security, the Shared File System (SFS), and the Group ControlSystem.MigrationPlanningMajor z/VM FilesIf you are migrating from a previous VM release, see the z/VM: Migration Guide.The following z/VM files are used to define and tailor many characteristics of yourinstallation’s z/VM system:v The system configuration file (SYSTEM CONFIG) defines real I/O devices in yoursystem’s I/O configuration and operating characteristics such as the layout of theCP system residence disk, lists of DASD volumes that CP uses, the real storageconfiguration, and information CP requires to determine the correct offset fromCoordinated Universal Time (UTC).For more information, see Chapter 2, “Configuring Your System,” on page 23,Chapter 5, “Defining I/O Devices,” on page 45, and Chapter 6, “The SystemConfiguration File,” on page 51.© Copyright IBM Corp. 1991, 2004 3

Overviewv The logo configuration file (LOGO CONFIG) defines where CP can find:– Logos for local, logical, and VTAM ® -attached devices– Status area definition– Online message and input area definition information– Print separator pages for printers.For more information, see Chapter 2, “Configuring Your System,” on page 23 andChapter 7, “The Logo Configuration File,” on page 279.v The user directory (USER DIRECT) defines the users of the system, theirauthority to enter various commands, and the resources they can use in thesystem. (You do not need to name your directory USER DIRECT.)For more information, see Chapter 17, “Creating and Updating a User Directory,”on page 447.System Planning and AdministrationThe following list briefly describes system planning and administration tasks andwhere to find detailed information about each task:v Define operating characteristics of your system by coding the systemconfiguration file. Information on the system configuration file can be found inChapter 2, “Configuring Your System,” on page 23 and Chapter 6, “The SystemConfiguration File,” on page 51.v Specify the local time to provide CP with the information it needs to determinethe correct offset from Coordinated Universal Time (UTC). Specify the local timeon the TIMEZONE_BOUNDARY and TIMEZONE_DEFINITION statements in thesystem configuration file. For more information on TIMEZONE_BOUNDARY andTIMEZONE_DEFINITION, see “TIMEZONE_BOUNDARY Statement” on page237 and “TIMEZONE_DEFINITION Statement” on page 239.v Create a system identifier for the processor on which you run. Code theSYSTEM_IDENTIFIER and SYSTEM_IDENTIFIER_DEFAULT statements in thesystem configuration file to create a system identifier for each processor onwhich you run z/VM. The system identifier appears on printed output separatorpages and in the status area of the display screen. For more information, see“SYSTEM_IDENTIFIER Statement” on page 226 and“SYSTEM_IDENTIFIER_DEFAULT Statement” on page 228.v Set up service virtual machines for accounting, error recording, symptomrecord recording, communication controller support for the emulator program,service spool support, Print Services Facility /VM (PSF /VM), and data storagemanagement. Details on setting up these virtual machines can be found inChapter 8, “Setting Up Service Virtual Machines,” on page 295.To use the CMS shared file system, set up file pool service and file pooladministration virtual machines. Details on how to do this are in z/VM: CMS FilePool Planning, Administration, and Operation.v Use SNA communication products to use SNA terminals as virtual machineconsoles. Systems Network Architecture/Console Communications Services(SNA/CCS) provides a total communication structure for transmitting informationthrough a communications network. For details on SNA/CCS, refer to Chapter 9,“Planning for SNA Console Communication Services (SNA/CCS),” on page 329.v Plan for cross system extensions (CSE) if users are to participate in amultisystem environment. CSE extends CP link protocols across multiple systemsin a CSE complex. It controls read or read/write access for minidisks on CKD orECKD( ) DASD, extends MESSAGE and QUERY commands, and manages4 z/VM: CP Planning and Administration

Overviewspool files for users across multiple z/VM systems. For additional informationabout CSE, refer to Chapter 10, “Setting Up Cross System Extensions (CSE),” onpage 333.v Plan for security facilities. Facilities are available in z/VM to help protect thesystem from security and integrity exposures. For descriptions and use of thesefacilities, see Chapter 12, “Security and Integrity in z/VM,” on page 379.v Improve system availability by defining and saving multiple copies of theCP module. For more information, see Chapter 4, “Using the Stand-AloneProgram Loader,” on page 37.v Create the stand-alone dump utility program and place it on tape or DASD.For additional information on the stand-alone dump utility provided by z/VM ,refer to Chapter 13, “Using the Stand-Alone Dump Utility,” on page 403.User Planning and AdministrationThe following list describes user planning and administration tasks and where tofind information on each task:v Plan for any changes to command privilege classes. The user classrestructure feature lets you extend the privilege class structure of CP commands,DIAGNOSE codes, and certain CP system functions from eight classes to asmany as 32 classes. For detailed information on how to extend the privilegeclass structure, refer to Chapter 16, “Redefining Command Privilege Classes,” onpage 433.v Create a z/VM user directory. As mentioned under “Major z/VM Files” on page3, each user who can log on to z/VM must have an entry in the z/VM userdirectory. You can create your own directory or update the sample that z/VMprovides. See Chapter 17, “Creating and Updating a User Directory,” on page447 which contains detailed descriptions of the control statements you can codein the directory.v Define virtual machine modes and processor configurations. Coding theMACHINE statement in a user’s directory entry allows you to specify:1. The virtual machine mode (ESA, XA, or XC), which indicates the architecturethe virtual machine simulates (ESA/390 or ESA/XC).Note: XA mode is supported for compatibility and is functionally equivalent toESA mode. Some CMS applications may require the virtual machine tobe in XA mode.2. The maximum number of virtual processors the virtual machine can define.To define virtual processors, the virtual machine user must enter the DEFINECPU command.For information on the MACHINE directory control statement, see “MACHINEDirectory Control Statement (General)” on page 510.As an alternative to including a MACHINE statement in each user’s directoryentry, you can define the virtual machine mode and virtual processor capabilitiesfor a group of virtual machines by including the MACHINE directory statement ina directory profile. See “Creating Directory Profiles” on page 455.If the MACHINE statement is not included in the user’s directory entry or includedin a profile, the default virtual machine mode is XA and the maximum number ofvirtual processors the virtual machine can define is determined by the number ofCPU statements included in the user’s directory entry or in a profile. If no CPUstatements are included in the directory entry or a profile, the virtual machine hasno virtual multiprocessor capabilities.Chapter 1. Planning and Administration Overview 5

OverviewThe MACHINE operand on the GLOBALOPTS directory statement allows you tospecify a global virtual machine mode for all virtual machines that do not have aMACHINE statement in their directory entry and are not included in a directoryprofile that contains a MACHINE statement. For more information, see the“GLOBALOPTS Directory Control Statement (Control)” on page 486.v Determine how you want real processor resources dedicated. The systemoperator can use the DEDICATE command to dedicate virtual CPUs to realprocessors.To dedicate specific virtual CPUs to real processors at logon, add a DEDICATEoperand for each CPU directory statement that is to have automatic dedication.For information on coding the CPU directory statement, see Chapter 17,“Creating and Updating a User Directory,” on page 447.v Make sure that the user IDs specified in the system configuration file haveuser directory entries. The sample system configuration file that is shipped onthe z/VM System DDR tapes or CD-ROM defines the following user IDs (on theSYSTEM_USERIDS statement), and the sample directories contain entries forthem:– OPERATOR as the user ID for the primary system operator– DISKACNT as the user ID for the accounting virtual machine– EREP as the user ID for an error recording virtual machine– OPERATNS as the user ID for a virtual machine that receives system dumps.If you change these or other user IDs specified in the system configuration file,make sure you change the user directory.v Decide which users are to be enrolled in a file pool. Detailed instructions onenrolling users in a file pool can be found in z/VM: CMS File Pool Planning,Administration, and Operation.v Create a PROFILE EXEC for the system bring-up virtual machine. Thesystem bring-up machine (which, by default, has a user ID of AUTOLOG1)provides an optional way to automatically log on virtual machines during systeminitialization. As part of system initialization, CP automatically logs onAUTOLOG1. AUTOLOG1, in turn, can automatically log on other virtualmachines, assuming that:– A PROFILE EXEC for AUTOLOG1 issues the XAUTOLOG command for eachvirtual machine AUTOLOG1 is to log on. (The XAUTOLOG command isasynchronous.) The system, however, automatically logs on the errorrecording, accounting, and symptom record recording virtual machines withoutreceiving a command from AUTOLOG1’s PROFILE EXEC. For information oncreating CMS PROFILE EXEC files, see z/VM: CMS User’s Guide. Forinformation on the XAUTOLOG command, see z/VM: CP Commands andUtilities Reference. For copies of the sample directories IBM provides, see thez/VM Installation and Service Sample Files informal document packaged withthe z/VM System DDR tapes or CD-ROM. For information on the XAUTOLOGdirectory control statement, see “XAUTOLOG Directory Control Statement(General)” on page 578.v Determine which operating system will be in each virtual machine. z/VM:Running Guest Operating Systems contains information on various operatingsystems as guests running in virtual machines.v Decide what the default POSIX authorizations should be. TheUSER_DEFAULTS system configuration file statement determines what thedefaults will be for querying other users’ POSIX database information and havingtheir POSIX security values changed. For more information, see“USER_DEFAULTS System Configuration File Statement” on page 248.6 z/VM: CP Planning and Administration

OverviewReal and Virtual Storage Planning and AdministrationThe following list describes real and virtual storage tasks and where to findinformation about each task:v Configure real storage. To define your real storage configuration, code theSTORAGE system configuration file statement. For more information, seeChapter 18, “Real Storage Planning and Administration,” on page 589 and“STORAGE Statement” on page 222.v Provide virtual storage to virtual machines. The amount of virtual storage CPassigns to a virtual machine when the virtual machine logs on is determined byan operand on the USER statement in the virtual machine’s directory entry. TheUSER statement can also set a maximum storage amount that each particularvirtual machine user can define. Code the mstor operand to specify the maximumvirtual machine storage size that a user can define. (Virtual machine users canenter the DEFINE STORAGE command to redefine their virtual machine storageup to the maximum specified on the USER statement.) For more information, see“USER Directory Control Statement (Control)” on page 572.Note: Allowing large numbers of virtual machines to have large storage sizes(primary address spaces and/or data spaces) may affect real storageavailability. This is discussed in the descriptions of the USER andXCONFIG Directory Control Statements. See “USER Directory ControlStatement (Control)” on page 572 and “XCONFIG ADDRSPACE Operand”on page 583.v Plan for using saved segments. A saved segment is an area of virtual storagethat holds data or reentrant code. Defining frequently used data as savedsegments provides several advantages. For detailed information, refer to thez/VM: Saved Segments Planning and Administration.Auxiliary Storage (Expanded Storage and DASD) Planning andAdministrationThe following sections describe planning and administration tasks for CP-owneddirect access storage devices (DASDs), dedicated DASDs, DASDs for minidisks,DASDs for shared file pools, Expanded Storage, and virtual disk in storage.CP-OwnedDASDsCP-owned DASDs are used for the CP system residence volume, real systempaging, spooling, directory and dump space, and temporary disk space for virtualmachines. Do the following for CP-owned DASDs:v Use HCM and HCD to define the DASD or, if needed, code an RDEVICEstatement in the system configuration file for the DASD. For moreinformation on HCM and HCD, see z/OS and z/VM: Hardware ConfigurationManager User’s Guide and z/VM: I/O Configuration. For more information oncoding the RDEVICE statement, see “RDEVICE Statement (DASD)” on page195.v Format CP-owned DASDs. Before CP can use a DASD as a CP-owned DASD,you must use the CPFMTXA utility, or the Device Support Facilities (ICKDSF)program to format the DASD. However, using ICKDSF is the recommendedmethod to format DASD volumes for CP use. For more information onCPFMTXA, refer to z/VM: CP Commands and Utilities Reference. For moreinformation on ICKDSF, refer to Device Support Facilities User’s Guide andReference.Chapter 1. Planning and Administration Overview 7

Overviewv Define a list of CP-owned volumes on the CP_OWNED system configurationfile statement. For more information, see “CP_OWNED Statement” on page 73.v Define the layout of the CP system residence volume on the FEATURESand SYSTEM_RESIDENCE statements in the system configuration file. Formore information, see “FEATURES Statement” on page 136 and“SYSTEM_RESIDENCE Statement” on page 230.v Create a parm disk You must store system configuration files on a parm disk,which is a CMS-formatted minidisk on the IPL volume. For more information, see“Using Configuration Files” on page 23.v Allocate temporary disk space to virtual machines. Use the MDISK directorycontrol statement to define temporary disk space for virtual machines. Virtualmachine users can enter the DEFINE command to define temporary disk spacewhen they need it. For more information, see “MDISK Directory ControlStatement (Device)” on page 513.DedicatedDASDsA dedicated DASD is a DASD that CP allocates exclusively to a virtual machine. Dothe following for a dedicated DASD:v Use HCM and HCD to define the DASD or, if needed, code an RDEVICEstatement in the system configuration file for the DASD. For moreinformation on HCM and HCD, see z/OS and z/VM: Hardware ConfigurationManager User’s Guide and z/VM: I/O Configuration. For more information oncoding the RDEVICE statement, see “RDEVICE Statement (DASD)” on page195.v Code a DEDICATE statement in the user directory entry of the virtualmachine to which you dedicate the DASD. To dedicate the DASD after theuser logs on, use the ATTACH command.v Set up a dedicated DASD so it can be shared with an operating systemrunning on another processor (using reserve/release). For more information,see “Sharing DASD between One Virtual Machine and Other Systems UsingReal Reserve/Release” on page 622.Note: If the DASD has not been used previously by the virtual machine’s operatingsystem, it must be initialized by the user after it is attached.DASDs Used for MinidisksTo use a DASD to provide minidisks for virtual machines, do the following:8 z/VM: CP Planning and Administrationv Use HCM and HCD to define the DASD or, if needed, code an RDEVICEstatement in the system configuration file for the DASD. For moreinformation on HCM and HCD, see z/OS and z/VM: Hardware ConfigurationManager User’s Guide and z/VM: I/O Configuration. For more information oncoding the RDEVICE statement, see “RDEVICE Statement (DASD)” on page195.v Define on the USER_VOLUME_LIST statement in the system configurationfile a list of volumes you use to contain minidisks. For more information, see“USER_VOLUME_LIST Statement” on page 255 or “SYSUVOL (Optional)” onpage 703.Note that you can also define minidisks on CP-owned volumes if the CP-ownedvolume is formatted appropriately. Although you may use the CPFMTXA utility, itis recommended that you use the Device Support Facilities (ICKDSF) program toformat DASD volumes for CP use. For more information on the CPFMTXA utility,see z/VM: CP Commands and Utilities Reference. For more information onICKDSF, see Device Support Facilities User’s Guide and Reference.

Overviewv Define minidisks for users. Use the MDISK directory control statement todefine a minidisk for a virtual machine. Use the LINK directory control statementto define a link to another user’s minidisk. The virtual machine for which theminidisk is defined is responsible for formatting it. For more information, see“MDISK Directory Control Statement (Device)” on page 513 and “LINK DirectoryControl Statement (Device)” on page 500.Note: CP and the directory program do not prevent you from defining minidisksthat overlap. If you define such overlap, you assume responsibility for dataintegrity. You can use the Directory Maintenance Facility (DirMaint)optional feature of z/VM to assist in managing the directory.v Set up a minidisk so it can be shared with an operating system running onanother processor and with other virtual machines (using reserve/release).For more information, see “Sharing DASD among Multiple Virtual Machines byUsing Virtual Reserve/Release” on page 619.DASD Space Used for Shared File PoolsTo define file pools, you need to estimate how large each file pool will become. Alsodefine one or more virtual machines to be used for file pool service machines. In sodoing, you must decide what the initial DASD storage for the file pool will be.For information on generating a file pool, refer to z/VM: CMS File Pool Planning,Administration, and Operation.ExpandedStorageExpanded Storage is hardware available only on certain processors. It providesanother level of general-purpose storage. Expanded Storage may be dedicated toone or more virtual machines and shared with CP. It can also be used for pagingand minidisk caching. Do the following for Expanded Storage:v Plan a map of Expanded Storage and determine which virtual machines shouldhave access to this resource (see “Mapping Expanded Storage” on page 593).v Use the XSTORE directory statement to attach Expanded Storage to avirtual machine. (You can also do this by using the ATTACH XSTOREcommand.) For information on the XSTORE directory statement, see “XSTOREDirectory Control Statement (General)” on page 585. For information on theATTACH XSTORE command, refer to z/VM: CP Commands and UtilitiesReference.v Use the RETAIN XSTORE command to set aside Expanded Storage forexclusive use by CP (see z/VM: CP Commands and Utilities Reference). Notethat CP determines which portion of Expanded Storage it will use for paging andminidisk caching. Use the RETAIN XSTORE command to override this.v Code the NOMDC operand of the MINIOPT directory statement if you do notwant to use a portion of Expanded Storage as a minidisk cache (see “MINIOPTDirectory Control Statement (Device)” on page 524 and Chapter 19, “ExpandedStorage Planning and Administration,” on page 591). Otherwise, you do not needto code the MINIOPT control statement.Virtual Disks in StorageA virtual disk in storage is the temporary simulation of an FBA minidisk in anaddress space in system storage. Because a virtual disk in storage is not mappedto a real DASD, having a real FBA DASD in the system configuration is notrequired. By avoiding the I/O overhead, virtual disks in storage may be faster to usethan other minidisks.Chapter 1. Planning and Administration Overview 9

OverviewThere are two ways to define a virtual disk in storage:v Using the DEFINE command. This creates a private (nonshareable) virtual disk instorage that is destroyed when the user detaches it or logs off.There is a limit on the amount of storage that can be allocated for virtual disks instorage created by a single user using the DEFINE command. This is called theuser limit. The built-in default for the user limit is 0. You can override the built-indefault by defining the user limit on the FEATURES statement in the systemconfiguration file or by using the SET VDISK command. For more information,see “FEATURES Statement” on page 136.v Using the MDISK directory control statement. This creates a shareable virtualdisk in storage. Use the LINK directory control statement to define a link toanother user’s virtual disk in storage. A shareable virtual disk in storage iscreated when the first user links to it (the owner links to it by logging on) anddestroyed when the last user detaches it or logs off. The first user must initializeor format the virtual disk in storage. For more information, see “MDISK DirectoryControl Statement (Device)” on page 513 and “LINK Directory Control Statement(Device)” on page 500.There is a limit on the total amount of storage that can be allocated for virtualdisks in storage on the system. This is called the system limit. The built-in defaultfor the system limit is the minimum of:– The amount of virtual storage that can be represented by one-quarter of theusable dynamic paging area (DPA) below 2 gigabytes (based on the fact thateach gigabyte of virtual disk defined requires 2050 pages of real storagebelow 2 gigabytes)– The amount of storage represented by one-quarter of the paging spacedefined for CP use.You can override the built-in default by defining the system limit on theFEATURES statement in the system configuration file or by using the SET VDISKcommand. For more information, see “FEATURES Statement” on page 136.Guests, servers, and other applications that use FBA minidisks can use virtual disksin storage without recoding. Because of their volatility, virtual disks in storageshould not be used for permanent data; work files and other files that holdtemporary results may be appropriate for virtual disks in storage. For an example ofcoding VSE guests to use a virtual disk in storage for storing label informationareas and the cross-system communication file (lock file), see the z/VM: RunningGuest Operating Systems book.TerminalsThe following list describes tasks for terminals and where to find information abouteach task:v For all real terminals use HCM and HCD to define them or code anRDEVICE statement in the system configuration file. For more information onHCM and HCD, see z/OS and z/VM: Hardware Configuration Manager User’sGuide and z/VM: I/O Configuration. Otherwise, see either “RDEVICE Statement(Graphic Display Devices)” on page 197 or Appendix C, “Defining I/O DevicesUsing HCPRIO,” on page 705.v Define primary and alternate system consoles using HCM and HCD ordefine primary and alternate system consoles on either theOPERATOR_CONSOLES or EMERGENCY_MESSAGE_CONSOLES statementin the system configuration file. For more information on HCM and HCD, seez/OS and z/VM: Hardware Configuration Manager User’s Guide and z/VM: I/O10 z/VM: CP Planning and Administration

OverviewUnit Record DevicesConfiguration. Otherwise, see either “EMERGENCY_MESSAGE_CONSOLESStatement” on page 124 or “OPERATOR_CONSOLES Statement” on page 180.v To define a virtual machine operator console for a virtual machine, code theCONSOLE control statement in the directory entry for a user. For moreinformation, see “CONSOLE Directory Control Statement (Device)” on page 463.v Define terminals for virtual machines. To define a terminal for a virtualmachine, code the DEDICATE or SPECIAL control statements, or both, in thedirectory entry for a user. For more information, see “DEDICATE DirectoryControl Statement (Device)” on page 477 and “SPECIAL Directory ControlStatement (Device)” on page 557.The tasks for a unit record device depend on whether the unit record device is (a)dedicated to a virtual machine or (b) used for spooling.Dedicated Unit Record DevicesTo dedicate a unit record device to a virtual machine, perform the following:v Use HCM and HCD to define the device or code an RDEVICE statement inthe system configuration file for the device. For more information on HCMand HCD, see z/OS and z/VM: Hardware Configuration Manager User’s Guideand z/VM: I/O Configuration. Otherwise, see:– “RDEVICE Statement (Card Punches)” on page 190– “RDEVICE Statement (Card Readers)” on page 192– “RDEVICE Statement (Impact Printers)” on page 201– “RDEVICE Statement (3800 Printers)” on page 212v Code a DEDICATE statement in the virtual machine’s user directory entry.The virtual machine user is responsible for other device tasks (such as creatingimage libraries for dedicated 3800 printers, defining forms control buffers, and soon). For more information, see “DEDICATE Directory Control Statement (Device)”on page 477.Spooled Unit Record DevicesTo use a unit record device for spooling, perform the following:v Use HCM and HCD to define the device or code an RDEVICE statement inthe system configuration file for each unit record device you use forspooling. For more information on HCM and HCD, see z/OS and z/VM:Hardware Configuration Manager User’s Guide and z/VM: I/O Configuration.Otherwise, see “RDEVICE Statement” on page 188.v Create a list of user form names and their corresponding operator formnumbers on either the FORM_DEFAULT or USERFORM statements. Formore information, see “FORM_DEFAULT Statement” on page 150, “USERFORMStatement” on page 247, or “SYSFORM (Optional)” on page 675.v Specify classification titles for specific classes of spooled output on thePRINTER_TITLE statement. For more information, see either “PRINTER_TITLEStatement” on page 182 or “SYSPCLAS (Optional)” on page 691.v Define forms control buffers (FCBs) and universal character sets (UCSs) for3203, 3211, 3262, 4245, and 4248 printers. For more information, seeChapter 14, “Creating and Modifying Image Libraries for Printers,” on page 411.v Define image libraries for 3800 and impact printers. For more information,see Chapter 14, “Creating and Modifying Image Libraries for Printers,” on page411.Chapter 1. Planning and Administration Overview 11

Overviewv Define spooled unit record devices for virtual machines. For moreinformation, see “SPOOL Directory Control Statement (Device)” on page 562.Performance Planning and AdministrationI/O Reconfiguration in z/VMThe performance characteristics of an operating system are dependent on suchfactors as choice of hardware, the total number of users on the system during peakperiods, functions being performed by the system, and the way system parametersare set up. You can improve performance to some degree by the choice ofhardware and system options. The following general tasks pertain to improving yourz/VM system efficiency:v Plan how you will handle performance monitoring, measurements, improvements,and problems. Become familiar with the CP monitor facility and the facilities youcan manipulate to change the performance characteristics of the system as awhole or of selected virtual machines.v Before you decide which performance options to apply, monitor the system’scurrent performance. This will help you determine which options would mostlikely give the system a performance gain and where performance bottlenecksare occurring. The CP monitor facility collects such data, which can then beprocessed to produce statistics to give you an understanding of systemoperation.v Perform system tuning to do any of the following:– Process a larger or more demanding work load without increasing the systemconfiguration– Obtain better system response or throughput– Reduce processing costs without affecting service to users.Details on system tuning can be found in z/VM: Performance.z/VM supports the hardware dynamic I/O configuration facility. This facility allowsyou to dynamically add, delete or modify the I/O configuration of the processorwithout requiring a power-on reset of the processor or IPL of z/VM.z/VM’s support allows the system administrator or system operator to use theHCM/HCD interface or CP’s dynamic I/O configuration commands to change the I/Oconfiguration of the processor without a re-IPL of z/VM or a power-on reset of theprocessor.In addition to the HCM/HCD interface and the CP commands to dynamically alterthe I/O configuration of the machine, other I/O commands allow you to:v Query the logical partitions on a machine (if the machine is in LPAR mode)v Query the channel pathsv Query the status of channel paths to devices.For more information on z/VM’s support of dynamic I/O configuration, please seethe z/VM: I/O Configuration.12 z/VM: CP Planning and Administration

OverviewOpenExtensions PlanningPlanning for OpenExtensions involves setting up the OpenExtensions facilities inz/VM that allow users to run POSIX applications. These tasks involve assigningPOSIX security values to users (by specifying certain system configuration filestatements and CP directory control statements) and setting up the OpenExtensionsByte File System. For an overview of how to set up OpenExtensions, see the z/VM:OpenExtensions User’s Guide.Chapter 1. Planning and Administration Overview 13


Part 2. System Planning and AdministrationChapter 2. Configuring Your System . . . . . . . . . . . . . . . . 23Specifying System Configuration Information . . . . . . . . . . . . . . 23Using Configuration Files . . . . . . . . . . . . . . . . . . . . . 23What You Can Specify in the System Configuration File . . . . . . . . . . 24Contents of the System Configuration File . . . . . . . . . . . . . . 25The Bare Minimum . . . . . . . . . . . . . . . . . . . . . 25Other Important Statements . . . . . . . . . . . . . . . . . . 25Real Devices . . . . . . . . . . . . . . . . . . . . . . . 25User Volume List . . . . . . . . . . . . . . . . . . . . . . 26Cross System Operations . . . . . . . . . . . . . . . . . . . 26Other System Attributes . . . . . . . . . . . . . . . . . . . 26Semantic and Syntactic Statements . . . . . . . . . . . . . . . 27Spool File Processing . . . . . . . . . . . . . . . . . . . . 27CP File System . . . . . . . . . . . . . . . . . . . . . . . 27Logo Processing . . . . . . . . . . . . . . . . . . . . . . 28What You Can Specify in the Logo Configuration File . . . . . . . . . . . 28Contents of the Logo Configuration File . . . . . . . . . . . . . . . 28Choosing Logo Picture Files . . . . . . . . . . . . . . . . . . 28Input Area . . . . . . . . . . . . . . . . . . . . . . . . . 29Online Messages . . . . . . . . . . . . . . . . . . . . . . 29Status Area . . . . . . . . . . . . . . . . . . . . . . . . 29Chapter 3. Understanding the CP File System . . . . . . . . . . . . 31Initial State of the CP File System . . . . . . . . . . . . . . . . . . 31Changing the List of Disks Accessed by CP . . . . . . . . . . . . . . 32Performance Considerations . . . . . . . . . . . . . . . . . . . . 33Displaying the Contents of CP-Accessed Minidisks . . . . . . . . . . . 33Changing Information on CP-Accessed Minidisks . . . . . . . . . . . . 34Chapter 4. Using the Stand-Alone Program Loader . . . . . . . . . . 37Creating the Stand-Alone Program Loader . . . . . . . . . . . . . . . 37Overriding the Console that CP Will Use . . . . . . . . . . . . . . 39Overriding Stand-Alone Program Loader Defaults . . . . . . . . . . . 39To IPL from a SCSI Disk . . . . . . . . . . . . . . . . . . . . 39The Stand-Alone Program Loader Screen . . . . . . . . . . . . . . 40Passing IPL Parameters . . . . . . . . . . . . . . . . . . . . . 42Chapter 5. Defining I/O Devices . . . . . . . . . . . . . . . . . . 45Device Support . . . . . . . . . . . . . . . . . . . . . . . . . 45Unsupported Devices . . . . . . . . . . . . . . . . . . . . . 46Device Sensing . . . . . . . . . . . . . . . . . . . . . . . . 46DASD . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Tapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Printers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Unit Record Devices . . . . . . . . . . . . . . . . . . . . . . . 48Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Communication Controllers . . . . . . . . . . . . . . . . . . . . 49ESCON Devices . . . . . . . . . . . . . . . . . . . . . . . . 49Other Devices . . . . . . . . . . . . . . . . . . . . . . . . . 50Chapter 6. The System Configuration File . . . . . . . . . . . . . . 51The Parm Disk . . . . . . . . . . . . . . . . . . . . . . . . . 51Summary of System Configuration File Statements . . . . . . . . . . . 51© Copyright IBM Corp. 1991, 2004 15

16 z/VM: CP Planning and AdministrationGeneral Rules for Coding a System Configuration File . . . . . . . . . . 55Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Comments . . . . . . . . . . . . . . . . . . . . . . . . . 55Continuations . . . . . . . . . . . . . . . . . . . . . . . . 55Case . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Record Qualifiers . . . . . . . . . . . . . . . . . . . . . . . 56The Order of Statements in the File . . . . . . . . . . . . . . . . 57Checking the Syntax of Statements in the File . . . . . . . . . . . . 57ALTERNATE_OPERATORS Statement . . . . . . . . . . . . . . . . 58ASSOCIATE EXIT Statement . . . . . . . . . . . . . . . . . . . 60ASSOCIATE MESSAGES / MSGS Statement . . . . . . . . . . . . . 64CHARACTER_DEFAULTS Statement . . . . . . . . . . . . . . . . 67CP_ACCESS Statement . . . . . . . . . . . . . . . . . . . . . 70CP_ADDON_INITIALIZE_ROUTINES Statement . . . . . . . . . . . . 72CP_OWNED Statement . . . . . . . . . . . . . . . . . . . . . 73CPXLOAD Statement . . . . . . . . . . . . . . . . . . . . . . 76DEFINE ALIAS Statement . . . . . . . . . . . . . . . . . . . . . 81DEFINE COMMAND / CMD Statement . . . . . . . . . . . . . . . . 84DEFINE DIAGNOSE Statement . . . . . . . . . . . . . . . . . . . 90DEFINE EXIT Statement . . . . . . . . . . . . . . . . . . . . . 94DEFINE LAN Statement . . . . . . . . . . . . . . . . . . . . . 97DEFINE VSWITCH Statement . . . . . . . . . . . . . . . . . . . 100DEVICES Statement . . . . . . . . . . . . . . . . . . . . . . 105DISABLE COMMAND / CMD Statement . . . . . . . . . . . . . . . 110DISABLE DIAGNOSE Statement . . . . . . . . . . . . . . . . . . 112DISABLE EXITS Statement . . . . . . . . . . . . . . . . . . . . 114DISTRIBUTE Statement . . . . . . . . . . . . . . . . . . . . . 116DRAIN (Disk) Statement . . . . . . . . . . . . . . . . . . . . . 118EDEVICE Statement . . . . . . . . . . . . . . . . . . . . . . 121EMERGENCY_MESSAGE_CONSOLES Statement . . . . . . . . . . . 124ENABLE COMMAND / CMD Statement . . . . . . . . . . . . . . . 126ENABLE DIAGNOSE Statement . . . . . . . . . . . . . . . . . . 128ENABLE EXITS Statement . . . . . . . . . . . . . . . . . . . . 130ENFORCE_BY_VOLid Statement . . . . . . . . . . . . . . . . . 132EQUATE Statement . . . . . . . . . . . . . . . . . . . . . . 133EXTERNAL_SYNTAX Statement . . . . . . . . . . . . . . . . . . 135FEATURES Statement . . . . . . . . . . . . . . . . . . . . . 136FORM_DEFAULT Statement . . . . . . . . . . . . . . . . . . . 150HOT_IO_RATE Statement . . . . . . . . . . . . . . . . . . . . 152IMBED Statement . . . . . . . . . . . . . . . . . . . . . . . 155INIT_MITIME Statement . . . . . . . . . . . . . . . . . . . . . 157IODF Statement . . . . . . . . . . . . . . . . . . . . . . . . 158JOURNALING Statement . . . . . . . . . . . . . . . . . . . . 160LOGO_CONFIG Statement . . . . . . . . . . . . . . . . . . . . 164MODIFY COMMAND / CMD Statement . . . . . . . . . . . . . . . 165MODIFY DIAGNOSE Statement . . . . . . . . . . . . . . . . . . 169MODIFY EXIT Statement . . . . . . . . . . . . . . . . . . . . . 172MODIFY LAN Statement . . . . . . . . . . . . . . . . . . . . . 175MODIFY PRIV_CLASSES Statement . . . . . . . . . . . . . . . . 176MODIFY VSWITCH Statement . . . . . . . . . . . . . . . . . . 178OPERATOR_CONSOLES Statement . . . . . . . . . . . . . . . . 180PRINTER_TITLE Statement . . . . . . . . . . . . . . . . . . . 182PRIV_CLASSES Statement . . . . . . . . . . . . . . . . . . . . 184PRODUCT Statement . . . . . . . . . . . . . . . . . . . . . . 186RDEVICE Statement . . . . . . . . . . . . . . . . . . . . . . 188RDEVICE Statement (Advanced Function Printers) . . . . . . . . . . . 189

RDEVICE Statement (Card Punches) . . . . . . . . . . . . . . . . 190RDEVICE Statement (Card Readers) . . . . . . . . . . . . . . . . 192RDEVICE Statement (Communication Controllers) . . . . . . . . . . . 193RDEVICE Statement (DASD) . . . . . . . . . . . . . . . . . . . 195RDEVICE Statement (Graphic Display Devices) . . . . . . . . . . . . 197RDEVICE Statement (Impact Printers) . . . . . . . . . . . . . . . . 201RDEVICE Statement (Special Devices) . . . . . . . . . . . . . . . 205RDEVICE Statement (Tape Units) . . . . . . . . . . . . . . . . . 207RDEVICE Statement (Unsupported Devices) . . . . . . . . . . . . . 209RDEVICE Statement (3800 Printers) . . . . . . . . . . . . . . . . 212SAY Statement . . . . . . . . . . . . . . . . . . . . . . . . 217SET Statement . . . . . . . . . . . . . . . . . . . . . . . . 219START (Disk) Statement . . . . . . . . . . . . . . . . . . . . . 220STORAGE Statement . . . . . . . . . . . . . . . . . . . . . . 222SYSTEM_DATEFORMAT Statement . . . . . . . . . . . . . . . . 225SYSTEM_IDENTIFIER Statement . . . . . . . . . . . . . . . . . 226SYSTEM_IDENTIFIER_DEFAULT Statement . . . . . . . . . . . . . 228SYSTEM_RESIDENCE Statement . . . . . . . . . . . . . . . . . 230SYSTEM_USERIDS Statement . . . . . . . . . . . . . . . . . . 232THROTTLE Statement . . . . . . . . . . . . . . . . . . . . . 236TIMEZONE_BOUNDARY Statement . . . . . . . . . . . . . . . . 237TIMEZONE_DEFINITION Statement . . . . . . . . . . . . . . . . 239TOLERATE_CONFIG_ERRORS Statement . . . . . . . . . . . . . . 241TRANSLATE_TABLE Statement . . . . . . . . . . . . . . . . . . 243USERFORM Statement . . . . . . . . . . . . . . . . . . . . . 247USER_DEFAULTS System Configuration File Statement . . . . . . . . . 248USER_VOLUME_EXCLUDE Statement . . . . . . . . . . . . . . . 251USER_VOLUME_INCLUDE Statement . . . . . . . . . . . . . . . 253USER_VOLUME_LIST Statement . . . . . . . . . . . . . . . . . 255VMLAN Statement . . . . . . . . . . . . . . . . . . . . . . . 257XLINK_DEVICE_DEFAULTS Statement . . . . . . . . . . . . . . . 259XLINK_SYSTEM_EXCLUDE Statement . . . . . . . . . . . . . . . 263XLINK_SYSTEM_INCLUDE Statement . . . . . . . . . . . . . . . 264XLINK_VOLUME_EXCLUDE Statement . . . . . . . . . . . . . . . 266XLINK_VOLUME_INCLUDE Statement . . . . . . . . . . . . . . . 268XSPOOL_SYSTEM Statement . . . . . . . . . . . . . . . . . . . 271XSPOOL_TRACE Statement . . . . . . . . . . . . . . . . . . . 273XSPOOL_XLIST_INPUT Statement . . . . . . . . . . . . . . . . . 274XSPOOL_XLIST_OUTPUT Statement . . . . . . . . . . . . . . . . 276Chapter 7. The Logo Configuration File . . . . . . . . . . . . . . 279Using a Logo Configuration File . . . . . . . . . . . . . . . . . . 279Summary of Logo Configuration File Statements . . . . . . . . . . . . 279General Rules for Coding a Logo Configuration File . . . . . . . . . . . 279Format . . . . . . . . . . . . . . . . . . . . . . . . . . 279Comments . . . . . . . . . . . . . . . . . . . . . . . . . 279Continuations . . . . . . . . . . . . . . . . . . . . . . . . 280Case . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Categories . . . . . . . . . . . . . . . . . . . . . . . . . 281Precedence . . . . . . . . . . . . . . . . . . . . . . . . 281Selection . . . . . . . . . . . . . . . . . . . . . . . . . 282Creating Logo Screens . . . . . . . . . . . . . . . . . . . . . 282Special Considerations When Creating Logos . . . . . . . . . . . . 283CHOOSE_LOGO Statement . . . . . . . . . . . . . . . . . . . 285INPUT_AREA Statement . . . . . . . . . . . . . . . . . . . . . 291ONLINE_MESSAGE Statement . . . . . . . . . . . . . . . . . . 292Part 2. System Planning and Administration 17

STATUS Statement . . . . . . . . . . . . . . . . . . . . . . . 293Chapter 8. Setting Up Service Virtual Machines . . . . . . . . . . . 295Setting Up Virtual Machines for Accounting . . . . . . . . . . . . . . 295Setting Up Virtual Machines to Collect Accounting Records . . . . . . . . 297Specifying a New Accounting Virtual Machine . . . . . . . . . . . . 297Starting Manual Retrieval of Accounting Records . . . . . . . . . . . 297Disassociating a User ID from the Retrieval of Accounting Records . . . . 298Accounting Record Formats . . . . . . . . . . . . . . . . . . . 299Accounting Records for Virtual Machine Resource Usage (Record Type1) . . . . . . . . . . . . . . . . . . . . . . . . . . 299Accounting Records for Dedicated Devices (Record Type 2) . . . . . . 300Accounting Records for Temporary Disk Space (Record Type 3) . . . . 301Accounting Records for Journaling (Record Types 04, 05, 06, 08, and 0I) 301Accounting Records for SNA/CCS (Record Type 07) . . . . . . . . 304Accounting Records for Inter-System Facility for Communications (RecordType 09) . . . . . . . . . . . . . . . . . . . . . . . . 304Accounting Records for logging changes to a user’s privilege (RecordType 0A) . . . . . . . . . . . . . . . . . . . . . . . . 306Accounting Records for virtual disk in storage space (Record Type B) 307Accounting Records Network Data Transmissions (Record Type C) . . . 307Accounting Records for CPU Capability (Record Type D) . . . . . . . 309Adding Your Own Accounting Records and Source Code . . . . . . . . 310User-Initiated Accounting Records (Record Type C0) . . . . . . . . 310CP Accounting Exit (Module HCPACU) . . . . . . . . . . . . . 310Setting Up Virtual Machines for Error Recording . . . . . . . . . . . . 314Setting Up Virtual Machines to Collect EREP Records . . . . . . . . . . 315Specifying a New EREP Virtual Machine . . . . . . . . . . . . . . 316Starting EREP Record Retrieval Manually . . . . . . . . . . . . . 316Disassociating a User ID from the Retrieval of EREP Records . . . . . . 317Setting Up Virtual Machines for Symptom Record Recording . . . . . . . 318Setting Up Virtual Machines to Collect Symptom Records . . . . . . . . . 319Specifying a New Symptom Record Recording Virtual Machine . . . . . . 319Starting Manual Retrieval of Symptom Records . . . . . . . . . . . 320Disassociating a User ID from the Retrieval of Symptom Records . . . . . 320Setting Up a Virtual Machine for Communication Controller Support forEmulator Program (EP) . . . . . . . . . . . . . . . . . . . . 321PVM Example . . . . . . . . . . . . . . . . . . . . . . . . 323Setting Up Service Pool Virtual Machines . . . . . . . . . . . . . . . 325Setting Up Print Services Facility/VM Virtual Machines . . . . . . . . . . 326Setting Up Virtual Machines for Data Storage Management . . . . . . . . 327Chapter 9. Planning for SNA Console Communication Services(SNA/CCS) . . . . . . . . . . . . . . . . . . . . . . . . . 329Structure of the SNA Environment . . . . . . . . . . . . . . . . . 329Establishing the SNA/CCS Terminal Environment . . . . . . . . . . . . 330Defining the VSM to z/VM . . . . . . . . . . . . . . . . . . . 330Defining Logos Used by VSMs . . . . . . . . . . . . . . . . . 330Defining SNA/CCS to VCNA . . . . . . . . . . . . . . . . . . 330Defining SNA/CCS to VSCS . . . . . . . . . . . . . . . . . . 331Enabling SNA Communication . . . . . . . . . . . . . . . . . . 331Starting the VTAM Service Machine . . . . . . . . . . . . . . . . 332Improving SNA/CCS Performance . . . . . . . . . . . . . . . . 332VSM Termination . . . . . . . . . . . . . . . . . . . . . . . 332Chapter 10. Setting Up Cross System Extensions (CSE) . . . . . . . . 33318 z/VM: CP Planning and Administration

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 333CSE Capabilities . . . . . . . . . . . . . . . . . . . . . . . 333Users Supported . . . . . . . . . . . . . . . . . . . . . . . 334Setting Up a CSE Complex . . . . . . . . . . . . . . . . . . . 334Planning for CSE . . . . . . . . . . . . . . . . . . . . . . . 334Requirements . . . . . . . . . . . . . . . . . . . . . . . . 334Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 335Supported Features . . . . . . . . . . . . . . . . . . . . . . 335Sharing DASD Volumes . . . . . . . . . . . . . . . . . . . . 336Avoiding Shared DASD I/O Bottlenecks . . . . . . . . . . . . . 337Placing of the CSE Area . . . . . . . . . . . . . . . . . . . 340Defining Volumes Containing Minidisks to be Shared . . . . . . . . 340Cross System Linking and Synchronization of Directories . . . . . . . 340Spool File Directory Statements . . . . . . . . . . . . . . . . . 341Preparing for CSE . . . . . . . . . . . . . . . . . . . . . . 341Cabling the Hardware . . . . . . . . . . . . . . . . . . . . 341Preparing for a Single Source Directory . . . . . . . . . . . . . 341Nonshared Directory Entries . . . . . . . . . . . . . . . . . 342Enabling CSE . . . . . . . . . . . . . . . . . . . . . . . . . 345Installing the VM/Pass-Through Facility and Its Modifications . . . . . . 345Defining CP for Each System . . . . . . . . . . . . . . . . . . 346System Definition for CSE . . . . . . . . . . . . . . . . . . 346CP_OWNED Statements . . . . . . . . . . . . . . . . . . . 347Example of a System Configuration File . . . . . . . . . . . . . 347Initializing the Volumes for Cross System Link . . . . . . . . . . . . 349Generating the Cross System Link Facility . . . . . . . . . . . . 349Initializing the CSE Area on Shared Minidisk Volumes . . . . . . . . 350Preparing the Communication Virtual Machine (CVM) . . . . . . . . . 350Verifying Your CSE Configuration . . . . . . . . . . . . . . . . . 353Verifying Cross System Link . . . . . . . . . . . . . . . . . . 353Enabling Cross System Spool . . . . . . . . . . . . . . . . . . 353Starting CSE Communication . . . . . . . . . . . . . . . . . 353Verifying Cross System Spool . . . . . . . . . . . . . . . . . 354Activating Spool for Systems Not Active after Start CSECOM . . . . . 355Phasing CSE into the Production Environment . . . . . . . . . . . . 356Networking Implications of CSE . . . . . . . . . . . . . . . . 357Administering CSE . . . . . . . . . . . . . . . . . . . . . . . 358How Linking Works in z/VM . . . . . . . . . . . . . . . . . . . 358How CSE Extends Linking . . . . . . . . . . . . . . . . . . . 359Controlling Cross System Link . . . . . . . . . . . . . . . . . 359CSE Area . . . . . . . . . . . . . . . . . . . . . . . . . 359Location of the CSE Area . . . . . . . . . . . . . . . . . . 361Protecting the CSE Area . . . . . . . . . . . . . . . . . . . 361Placing of the CSE Area . . . . . . . . . . . . . . . . . . . 361VM I/O Performance Measurement for Shared DASD . . . . . . . . . 365What Is Cross System Spool? . . . . . . . . . . . . . . . . . . 366How CSE Extends Spooling . . . . . . . . . . . . . . . . . . 367z/VM Spooling Commands Extended by CSE . . . . . . . . . . . 368Copy Input (Reader) Spool Files . . . . . . . . . . . . . . . . 369Copy Output (Print and Punch) Spool Files . . . . . . . . . . . . 370Spool File Numbering . . . . . . . . . . . . . . . . . . . . 370Access to Spool Files . . . . . . . . . . . . . . . . . . . . 370VM/Pass-Through Facility Functions for Cross System Spool . . . . . . 371Spool Synchronization Request Tracing . . . . . . . . . . . . . 371Multiple Concurrent Logon Sessions . . . . . . . . . . . . . . . 371Preparing to Deal with Outages . . . . . . . . . . . . . . . . . . 372Part 2. System Planning and Administration 19

Returning to Non-CSE Operation . . . . . . . . . . . . . . . . . 372Chapter 11. Customizing the CP Message Function . . . . . . . . . . 373HCPMSU Module . . . . . . . . . . . . . . . . . . . . . . . 373Entry Point HCPMSUEX . . . . . . . . . . . . . . . . . . . . 374Parameter Values . . . . . . . . . . . . . . . . . . . . . 374Changing and Adding to the CP Message Function . . . . . . . . . . . 377Chapter 12. Security and Integrity in z/VM . . . . . . . . . . . . . 379Security-Enhancing Products . . . . . . . . . . . . . . . . . . . 379Security Considerations and Guidelines . . . . . . . . . . . . . . . 380z/VM Security Facilities . . . . . . . . . . . . . . . . . . . . . 383Using an External Security Manager for Auditing and Protecting . . . . . 384Verifying Storage Access . . . . . . . . . . . . . . . . . . . . 384Clearing Temporary Disk Space . . . . . . . . . . . . . . . . . 384Permitting Bypassing of Directory Password Authorization . . . . . . . 385Journaling the LOGON, AUTOLOG, XAUTOLOG, and LINK Commands 385Automatic Deactivation of Restricted Passwords . . . . . . . . . . . 386Using Link Access Control Options . . . . . . . . . . . . . . . . 387Suppressing Passwords Entered on the Command Line . . . . . . . . 387Using an Integrated Cryptographic Facility . . . . . . . . . . . . . 387Maintaining System Integrity . . . . . . . . . . . . . . . . . . . 389z/VM System Integrity Requirements . . . . . . . . . . . . . . . 390z/VM Integrity and CP Function . . . . . . . . . . . . . . . . . 392Data Structures That Can Enhance System Integrity . . . . . . . . . 395z/VM Options That Can Enhance System Integrity . . . . . . . . . . 397Storage Handling . . . . . . . . . . . . . . . . . . . . . . 397Program Stack, Security, and Integrity . . . . . . . . . . . . . . . 398Reporting z/VM Integrity Problems . . . . . . . . . . . . . . . . 400Chapter 13. Using the Stand-Alone Dump Utility . . . . . . . . . . . 403Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 403Creating the Stand-Alone Dump Utility . . . . . . . . . . . . . . . . 403Before You Begin . . . . . . . . . . . . . . . . . . . . . . 404Devices You Can Use to IPL a Stand-Alone Dump . . . . . . . . . . 405Devices to Which You Can Send Dump Output . . . . . . . . . . . 406Example for Generating the Stand-Alone Dump Utility . . . . . . . . . 406Taking a Stand-Alone Dump . . . . . . . . . . . . . . . . . . . 408Processing the Stand-Alone Dump Data on Tape . . . . . . . . . . . . 409The HCPSADMP EXEC . . . . . . . . . . . . . . . . . . . . . 409Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . 409Chapter 14. Creating and Modifying Image Libraries for Printers . . . . . 411Creating Text Decks . . . . . . . . . . . . . . . . . . . . . . 411Creating Text Decks for the 3800 . . . . . . . . . . . . . . . . . 411Creating Text Decks for Impact Printers . . . . . . . . . . . . . . 412Universal Character Sets and FCBs Supplied by IBM . . . . . . . . 412Adding New Universal Character Set Buffer Images . . . . . . . . . 414Forms Control Buffers Supplied by IBM . . . . . . . . . . . . . 418Adding a New Forms Control Buffer . . . . . . . . . . . . . . . 418Adding an Extended Forms Control Buffer for the 4248 Printer . . . . . 420Using VMFHASM or VMFHLASM to Create a Text Deck . . . . . . . . 422Image Libraries . . . . . . . . . . . . . . . . . . . . . . . . 422Default Image Library Names . . . . . . . . . . . . . . . . . . 422Installing the Image Library That IBM Provides . . . . . . . . . . . . 423Installing Your Own Image Library . . . . . . . . . . . . . . . . 42320 z/VM: CP Planning and Administration

Modifying Image Libraries . . . . . . . . . . . . . . . . . . . 424Adding Files to an Image Library . . . . . . . . . . . . . . . . 424Deleting Members from an Image Library . . . . . . . . . . . . . 424Replacing Members or Modules in an Image Library . . . . . . . . 424Creating an Image Library Map . . . . . . . . . . . . . . . . 424Displaying Information about Image Libraries . . . . . . . . . . . . 424Purging Image Libraries . . . . . . . . . . . . . . . . . . . . 425Keeping Backup Copies of Image Libraries . . . . . . . . . . . . . 425Where to Find More Information about Printers . . . . . . . . . . . . 425Chapter 15. CCW Translation . . . . . . . . . . . . . . . . . . 427Using CCW Translation . . . . . . . . . . . . . . . . . . . . . 427Coding the Device Class Macroinstruction . . . . . . . . . . . . . . 427Unsupported Devices Tables . . . . . . . . . . . . . . . . . . . 428Device Macroinstruction . . . . . . . . . . . . . . . . . . . . . 429Part 2. System Planning and Administration 21


Chapter 2. Configuring Your SystemThis chapter provides an introduction to the files that define the configuration ofyour system.Specifying System Configuration InformationUsing Configuration FilesMost of the information about the configuration of your system is defined in thesystem configuration file, which is a CMS data file. Additional configurationinformation is defined in the user class restructure (UCR) files and the userdirectory files. You can also define the characteristics of screen logos in a logoconfiguration file. While the system is running, you can dynamically change many ofthese system characteristics by issuing various CP commands.This chapter provides an overview of the configuration files and what they contain.The following chapters provide additional information about configuring your system:v Chapter 5, “Defining I/O Devices,” on page 45 discusses considerations fordefining I/O devices.v Chapter 6, “The System Configuration File,” on page 51 describes the systemconfiguration file in more detail.v Chapter 7, “The Logo Configuration File,” on page 279 describes the logoconfiguration file in more detail.v Chapter 16, “Redefining Command Privilege Classes,” on page 433 describeshow to define the user class restructure (UCR) files.v Chapter 17, “Creating and Updating a User Directory,” on page 447 describeshow to define the user directory.The system configuration file and the logo configuration file, as well as any files thatthese configuration files imbed, are stored on the parm disk. The parm disk is aregular CMS-formatted minidisk that you identify to CP by writing an allocation mapon the IPL volume marking the location of the minidisk. The parm disk is accessedat IPL time, and configuration information is read from the configuration files storedon the disk.To place configuration information on the parm disk, you must do the following:1. Choose a CMS-formatted minidisk on the IPL volume on which you plan toplace configuration files. (If the minidisk is not CMS-formatted, the system willenter a wait state when you try to use it.)2. Run the ICKDSF utility to rewrite the allocation map on the IPL volume to marka parm disk extent that covers the location of the minidisk. See the DeviceSupport Facilities User’s Guide and Reference for details on formatting andallocating DASD volumes using ICKDSF.3. Place a system configuration file (called SYSTEM CONFIG by default), a logoconfiguration file (called LOGO CONFIG by default), or both, on the parm disk.Other names can be used for these files. See “Passing IPL Parameters” onpage 42 for specifying a name for the system configuration file. You can specifya name for the logo configuration file inside the system configuration file. Placeany logo picture files on this disk also.© Copyright IBM Corp. 1991, 2004 23

Configuring Your SystemNote: Although z/VM continues to support the system control file (HCPSYSASSEMBLE), system real I/O configuration file (HCPRIO ASSEMBLE), andsystem logo definition file (HCPBOX ASSEMBLE), IBM strongly recommendsthat you use configuration files to define your system. Using the ASSEMBLEfiles is more difficult and error-prone, requires knowledge of the Assembler HVersion 2 Licensed Program, does not support recent CP enhancements,and requires rebuilding the CP module after making changes. The HCPSYSASSEMBLE file supplied with z/VM contains no system definitions. Thesupplied HCPRIO ASSEMBLE file contains only an RIOGENCONS=DYNAMIC macro to indicate that console addresses are defined inthe system configuration file. The supplied HCPBOX ASSEMBLE containsdefault system logos.A default SYSTEM CONFIG file is created at installation time. You can update thisfile or create your own system configuration file using the editor of your choice. Usethe QUERY CPDISK command to find out what parm disks are accessed, theCPRELEASE command to release the parm disk, the LINK and ACCESScommands for write access, and the CPACCESS command to return the disk to CP.See Chapter 3, “Understanding the CP File System,” on page 31 for additionalinformation on these commands.During the IPL process, CP tries to access the first parm disk that is marked in theallocation map on the IPL volume. If there is a parm disk marked, and if the disklocations matching the extent represent a CMS-formatted minidisk, CP attempts toread the system configuration file from the disk.The format of the system configuration file is described in “What You Can Specify inthe System Configuration File.” If CP finds a file called SYSTEM CONFIG (or thename you specify on IPL), it examines the contents of the file and applies anychanges requested in the file to the system configuration. Values defined in thesystem configuration file override any values defined in HCPSYS ASSEMBLE andHCPRIO ASSEMBLE. If CP finds a file called LOGO CONFIG (or the name definedin the system configuration file), it uses the contents of that file to override all thelogo characteristics set in HCPBOX ASSEMBLE.Before the first prompt, which asks you what method of system initialization youneed, the system displays information about the parm disk. After the system is upand running, you can use the QUERY CPLOAD command to find out whether CPaccessed a parm disk, and if so, what that disk was.What You Can Specify in the System Configuration FileThe system configuration file defines the basic characteristics of your system andallows you to define many system options, such as:v The devices CP should bring online at IPL timev The time zone CP should select at IPL time from a list of time zonesv Whether CP should autolog special user IDs at IPL time, such as the accountingand symptom user IDsv The contents of most translation tables defined in CPv Whether CP should automatically attempt a warm start without changing the TODclock at IPL timev The number of buffers CP provides for the retrieving of command linesv The characters used as default terminal characters, such as the line endcharacter and the line delete character24 z/VM: CP Planning and Administration

Configuring Your Systemv The defaults that will be used for querying other users’ POSIX databaseinformation and having their POSIX security values changedv The IODF that HCD will use to control CP’s I/O configuration.Note: You cannot define the size of system storage in the system configuration file.For information on defining the size of system storage to a value less thanwhat is actually available, see the STORE parameter under “Passing IPLParameters” on page 42.Contents of the System Configuration FileThe following sections contain a brief description of some of the statements thatyou can specify in the system configuration file. For complete descriptions of all thesystem configuration statements and general rules for coding a systemconfiguration file, see Chapter 6, “The System Configuration File,” on page 51.The Bare MinimumYou must include the following statements for the system to come up:v CP_OWNED defines a volume in the CP-owned volume list. After the system isrunning, you can use the DEFINE CPOWNED command to change this list. (Tomake the change permanent, update the system configuration file.)v SYSTEM_RESIDENCE specifies the location of the checkpoint and warm startareas.v OPERATOR_CONSOLE defines a list of console addresses from which CPshould choose the operator console.These three statements are all that the system really needs to come up and startrunning.Other Important StatementsYou may also want to include the following statements:v SYSTEM_IDENTIFIER and SYSTEM_IDENTIFIER_DEFAULT define systemidentifiers for the processors on which you run z/VM.v TIMEZONE_DEFINITION and TIMEZONE_BOUNDARY enable the system tochoose the correct local time zone definition.v IODF indicates that HCM and HCD will control the hardware and optionally thesoftware I/O configuration.Real DevicesThe statements previously listed are the most basic ones that you need to get yoursystem running and to give it an identifier and a local time. You can customize yoursystem further with the other statements. For example, if you are not using HCMand HCD to control your software I/O configuration, you can define real devices tothe system and establish characteristics for them using the following statements:v RDEVICE defines real I/O devices that do not respond to a sense ID request andI/O devices that need more defining information than a sense ID request returns(for example, printers and communications controllers). After the system isrunning, you can use the SET RDEVICE command to define or redefine realdevices.See Chapter 5, “Defining I/O Devices,” on page 45 for information about whichdevices may need to be defined with RDEVICE statements.v DEVICES tells CP whether to bring specified devices online, accept and buildreal device blocks for specified devices, and use the information returned from aChapter 2. Configuring Your System 25

Configuring Your Systemsense ID request to help define a device. It is recommended that you let CPbring all devices online at IPL, and that you let CP use the sense information.v HOT_IO_RATE specifies the maximum unsolicited interrupt rate for real devices.You can control operations on real DASD using the following statements:v DRAIN stops new allocations of certain types of space on the DASD.v START restarts a DASD after it has been drained.After the system is running, you can use the DRAIN (Disk) and START (Disk)commands to perform the same functions as the DRAIN and START statements.User Volume ListYou can generate and change the user volume list using the following statements:v USER_VOLUME_LIST generates the user volume list.v USER_VOLUME_EXCLUDE and USER_VOLUME_INCLUDE specify volumes tobe excluded from or included in the user volume list. These statements can usewildcard characters (% and *) in defining volume serial identifiers.Cross System OperationsYou can control cross system spool operations, cross system link operations, andcross system commands using the following statements:v XLINK_SYSTEM_EXCLUDE and XLINK_SYSTEM_INCLUDE specify thesystems to be excluded from or included in cross system link protection.v XLINK_VOLUME_EXCLUDE and XLINK_VOLUME_INCLUDE specify the DASDvolumes to be excluded from or included in cross system link protection.v XSPOOL_SYSTEM specifies the systems that are to participate in cross systemcommands and spooling operations.v XSPOOL_TRACE allocates storage for the cross system spool (XSPOOL) tracetables.v XSPOOL_XLIST_INPUT and XSPOOL_XLIST_OUTPUT specify virtual machineswhose input or output spool files do not participate in cross system spooling andcommands. After the system is running, you can use the XSPOOL XLISTADDand XSPOOL XLISTDEL commands to work with these lists.The statements controlling cross system link operations are separate from thosecontrolling cross system commands and spool operations.Other System AttributesYou can set other attributes of your system using the following statements:v EMERGENCY_MESSAGE_CONSOLES specifies a list of consoles that CPshould notify if there is an impending abnormal end or other system emergency.If you do not include this statement, CP uses the list specified on theOPERATOR_CONSOLES statement for the list of emergency consoles as well.v STORAGE allocates real storage and trace frames.v JOURNALING specifies characteristics of the system’s journaling facility. After thesystem is running, you can use the QUERY and SET JOURNAL commands towork with the journaling facility.v PRIV_CLASSES changes the privilege classes authorizing certain CP functions.v SYSTEM_USERIDS specifies user IDs that perform special functions during andafter IPL. These user IDs identify the virtual machines that handle accountingrecords, system dump files, EREP records, and symptom records; the operatorand startup user IDs are also specified.26 z/VM: CP Planning and Administration

Configuring Your Systemv FEATURES sets several different attributes of the system. These attributesinclude:– Trying an automatic warm start without changing the TOD clock– Clearing TDISK DASD space automatically– Enabling the new LOGMSG support that causes CP to read log messageinformation from disk files instead of the warm start area– Giving end users the authority to change their own privilege classes, andprivileged users the authority to change the privilege classes of other userslogged on to the system– Establishing the largest number of users who may be logged on to the systemat one time– Enabling the facility that suppresses the password on the command line forAUTOLOG, LOGON, and LINK commands.v CHARACTER_DEFAULTS specifies default characters, such as the line endcharacter and the character delete character.v USER_DEFAULTS determines what the defaults will be for:– the global lines per page value for all virtual printers and consoles that aredefined on the system, and– querying other users’ POSIX database information and having their POSIXsecurity values changed.– TRANSLATE_TABLE specifies replacements for the standard translationtables that CP uses to accomplish certain tasks.v PRODUCT defines a product or feature to the system.Semantic and Syntactic StatementsThe following statements affect the way that your system processes the systemconfiguration file:v EQUATE creates names for groups of systems that all have something incommon and should, therefore, be treated similarly. You can use systemidentifiers or nicknames created by EQUATE statements to preface statementsthat should only apply to certain systems.v IMBED specifies the name and type of a file to be imbedded into the systemconfiguration file.v TOLERATE_CONFIG_ERRORS controls whether a section of the systemconfiguration file must be without errors when CP processes it.Spool File ProcessingThe following statements affect the way that your system processes spool files:v FORM_DEFAULT defines default user form names for CP to use when it createsfiles on virtual printers, punches, consoles, or real card readers.v PRINTER_TITLE specifies the printed output classes that are to containclassification titles.v USERFORM creates a list of user form names and their corresponding operatorform numbers, and can specify the forms as NARROW so that a narrowseparator page is printed.CP File SystemCP_ACCESS statements direct CP to access CMS-formatted minidisks that containinformation that CP can use at run time. Each CP_ACCESS statement specifies aCMS-formatted minidisk that CP should access after it brings the user directoryonline. After the system is up and running, you can use the CPACCESS commandto perform the same function as the CP_ACCESS statement.Chapter 2. Configuring Your System 27

Configuring Your SystemLogo ProcessingLOGO_CONFIG specifies the name of a logo configuration file for CP to use.What You Can Specify in the Logo Configuration FileYou can use the logo configuration file to override all of the default logo informationspecified in the HCPBOX ASSEMBLE file included in the CP nucleus. You canchange four logo pictures:v Normal logov Minimum screen logov Basic logov Spooling logoYou can use statements in the logo configuration file to choose logo pictures forlogical devices, SNA terminals, and locally attached terminals. CP can choosepictures for logical devices based on the user ID of the virtual machine that createdthe device, for SNA terminals based on the user ID of the VSM that is managingthe terminal, and for locally attached terminals based on their device addresses. Itcan also choose pictures for locally attached terminals or logical devices based onthe size of their screens.You can also use the logo configuration file to define the contents of the followingfields:v The command areav The input area at the bottom of the logo screen, and the layout of this areav The online message found at the top of each logo screenv The status areas (such as VM READ and CP READ)Unless you specify a different file name and file type in the system configurationfile, CP looks for a file called LOGO CONFIG after it has processed the systemconfiguration file. If CP has accessed a parm disk successfully, it attempts toprocess a logo configuration file even if it does not find a system configuration fileon the parm disk. After the system is up and running, you can use the REFRESHLOGOINFO command to change this information.Contents of the Logo Configuration FileThe logo configuration file contains the following four statements:vvvCHOOSE_LOGOINPUT_AREAONLINE_MESSAGEv STATUSFor complete descriptions of these statements and information about creating alogo configuration file, see Chapter 7, “The Logo Configuration File,” on page 279.Choosing Logo Picture FilesThe CHOOSE_LOGO statement is the most complex of these statements. TheCHOOSE_LOGO statement defines the logo picture files that CP uses for thefollowing:v Locally attached terminals. You can select certain pictures for certain terminaladdresses.v Terminals logging on through logical devices28 z/VM: CP Planning and Administration

Configuring Your Systemv Terminals managed by certain VTAM service machines (VSMs)v Separator pages of printed output.You can also select a different logo picture file for each locally attached terminaland different picture files for terminals logging on through different user IDs. Youcan specify a logo picture file to appear on screens that are too small toaccommodate the picture that another statement has specified for them.Input AreaThe INPUT_AREA statement contains information defining the layout of the inputarea that contains the user ID, password, and command areas of the logo screen.You can specify the number of lines each field should have, where the fields shouldappear, and the text that surrounds each area. You can use the CHOOSE_LOGOstatement to put specific text into the command area; this text appears by defaulton the logo screen. This option is helpful for systems on which users often dialthrough to PVM or VTAM. For example, you can include the text DIAL VTAM in thecommand area.Online MessagesThe ONLINE_MESSAGE statement specifies the file that contains the onlinemessage that you want to appear at the top of the logo screen. You can changethis message to show the date that the system was brought online, the version ofz/VM that you are running, or whatever other information you may want.Status AreaThe STATUS statement specifies the text that appears in the bottom right corner ofthe screen. You can use this statement to change the contents of the status area tomixed case (for example, RUNNING to Running) or to change the text entirely.Chapter 2. Configuring Your System 29


Chapter 3. Understanding the CP File SystemThis chapter describes:v Initial state of the CP file systemv Changing the list of disks accessed by CPv Performance considerationsv Displaying the contents of CP-accessed minidisksv Changing information on CP-accessed minidisks.Initial State of the CP File SystemAfter CP has read and processed the system and logo configuration files, itreleases the temporary link and access that it established to the parm disk. The IPLprocess continues as it would if there had been no parm disk present. CP thenprompts the operator with the options for the type of start:17:10:58 Start ((Warm|Force|COLD|CLEAN) (DRain) (DIsable) (NODIRect))17:10:58 (NOAUTOlog)) or (SHUTDOWN)If you choose to start with no options or with any option other than NODIRECT, CPtries to bring the user directory online after it has performed the requested spool fileinitialization. After the user directory is brought online, CP tries to access anyminidisks specified on the CP_ACCESS statements in the system configuration file.If no such statements exist, CP will not have any minidisks accessed. For example,to determine what minidisks (if any) CP has accessed, issue the followingcommand:query cpdisksIf no disks are accessed, you receive the following response:No disks accessed.Ready;If a FEATURES statement in your system configuration file instructed CP to use logmessages from files on CP-accessed minidisks, there would be no log messagedata because CP does not have any minidisks accessed. For example, todetermine if any log message data exists, issue the following command:query logmsgAnd receive the response:There is no logmsg dataReady;If CP had processed a logo configuration file at IPL time and the logo configurationfile statements referred to logo picture files, an input area file, or an online messagefile, CP displays the standard system logo defined in HCPBOX ASSEMBLE on allterminals (because CP does not have any minidisks accessed).Therefore, depending on information in your system and logo configuration files, CPmay look for files on CP-accessed minidisks when it needs to find log message filesor logos. If you had placed one or more CP_ACCESS statements in your systemconfiguration file, the response to the QUERY CPDISKS command after an IPLmight be similar to the following:© Copyright IBM Corp. 1991, 2004 31

Understanding the CP File SystemLabel Userid Vdev Mode Stat Vol-ID Rdev Type StartLoc EndLocPROD1 MAINT 0300 A R/O ESARES 0A0F ECKD 2400 2449BACKUP MAINT 0301 B R/O ESARES 0A0F ECKD 2450 2499Ready;This response indicates that MAINT’s 300 and 301 disks are accessed by CP.Unless you specify otherwise, CP accesses these disks in stable-read (SR) modeso that while CP only has read-only access to the minidisks, no other user canobtain a write link to the minidisk. In this case, if a user requests a copy of the logmessages, CP reads files on the CP-accessed minidisks (MAINT’s 300 and 301)and displays the contents of one or more files at the user’s terminal. If a userswitches on a terminal, CP can construct a logo from information contained in logopicture files, an input area file, and an online message file on the CP-accessedminidisks.Changing the List of Disks Accessed by CPAs previously discussed, the CP_ACCESS statements in the system configurationfile define the initial list of disks accessed by CP. After the system is up andrunning, you can change the list of disks that CP searches for log message andlogo information without having to shut down and restart the system. TheCPACCESS and CPRELEASE commands are similar to the CMS ACCESS andRELEASE commands in that they enable privileged users to modify the list of CPaccessed disks. However, unlike the CMS ACCESS and RELEASE commands, theCPACCESS and CPRELEASE do not affect any operations in the virtual machinewhere the command was issued. Instead, they instruct CP to modify its list ofaccessed minidisks. For example, to release a disk accessed by CP, issue thefollowing command:cprelease aYou receive these responses:CPRELEASE request for disk A scheduled.Ready;CPRELEASE request for disk A completed.If you issue QUERY CPDISKS, you see that in this case, CP has only a single diskaccessed, and all the logo and log message information have to be on this disk.Label Userid Vdev Mode Stat Vol-ID Rdev Type StartLoc EndLocBACKUP MAINT 0301 B R/O ESARES 0A0F ECKD 2450 2499Ready;You can also add to the list of minidisks accessed by CP. For example, to addMAINT’s 400 disk to the list of disks accessed by CP, issue the following command:cpaccess maint 400 aYou receive these responses:CPACCESS request for mode A scheduled.Ready;CPACCESS request for MAINT’s 0400 in mode A completed.To determine which disks are now accessed, issue QUERY CPDISKS. You receivethis response:Label Userid Vdev Mode Stat Vol-ID Rdev Type StartLoc EndLocPROD2 MAINT 0400 A R/O XAUSR8 0B12 CKD 2300 2349BACKUP MAINT 0301 B R/O ESARES 0A0F ECKD 2450 2499Ready;32 z/VM: CP Planning and Administration

Understanding the CP File SystemYou are only authorized to request that CP should access a minidisk if you have theauthority to link to the minidisk yourself. To have CP access the minidisk in SRmode (the default), you must be authorized to link to the disk in SR mode yourself.Whenever CP needs to display the log message or create a logo, it tries to readfiles from the minidisks that it currently has accessed.PerformanceConsiderationsBecause CP tries to read files from CP-accessed minidisks whenever it displays logmessages or logos, it may read certain files on the minidisks many times. Ratherthan reading these files from the minidisks each time, CP can cache the files instorage. Then, every time the files have to be read, CP does not have to wait for acopy of the files to be read from DASD because their contents are already instorage.For example, to cache certain files that reside on CP-accessed minidisk, issue thefollowing CPCACHE command:cpcache sna% logms* a2 file(s) cached.Ready;The response to the command indicates that 2 files were placed in storage as aresult of the CPCACHE command. CPCACHE accepts the use of wildcardcharacters (% and *) to specify files that it should cache.You can also give CP a list of files to read into storage whenever it accesses theminidisk. You do this by creating a file called CPCACHE FILES, which contains thelist of files, and placing the file on the minidisk that CP accesses. This is anexample of a CPCACHE FILES file:* logms* /* Cache all log message related files */sna% logo /* Cache all SNA logo picture files */online message /* Cache the file that contains the"VM/ESA Online" message */CP attempts to read CPCACHE FILES on any minidisk it accesses, whether theaccess attempt is the result of a CPACCESS command or CP_ACCESS statementsfound in the system configuration file.CP removes the appropriate cached files from storage when a CPRELEASE orCPACCESS command is issued for the minidisk from which the files were loaded. Ifthe files were loaded into storage as a result of the CPCACHE command (ratherthan a CPCACHE FILES file), you have to issue the CPCACHE command againwhen CP reaccesses the disk.Displaying the Contents of CP-Accessed MinidisksJust as you can use the CMS LISTFILE command to display what files are onaccessed minidisks, privileged users can use the CP CPLISTFILE command todisplay what files are on CP-accessed minidisks. For example, to display the LOGOfiles found on a CP-accessed minidisk, issue the following CPLISTFILE command:cplistfile * logo aChapter 3. Understanding the CP File System 33

Understanding the CP File SystemThe response displays the file name and file type of the file, its format and size, thedate it was last modified, and whether the file is currently cached:Filename Filetype FM Fmt LRecL Records Date Time CacheDEFAULT LOGO A F 80 15 10/30/91 21:15:15 No08E6 LOGO A F 80 23 02/20/92 08:12:56 NoLDEV LOGO A F 80 15 11/30/91 21:14:50 NoLOCAL LOGO A F 80 15 09/16/91 23:17:42 NoMOD5 LOGO A F 132 15 10/30/91 21:13:53 NoPVM LOGO A F 78 15 10/30/91 21:15:02 NoSNA1 LOGO A F 78 15 11/29/91 12:32:35 YesSNA2 LOGO A F 78 15 10/30/91 21:14:35 YesSYSTEM LOGO A F 80 15 10/30/91 21:14:29 NoTCPIP LOGO A F 78 15 01/27/92 20:22:09 NoReady;To display certain statistics about files on CP-accessed minidisks, issue:cplistfile sna* logo a statisticsThe response looks similar to this:Filename Filetype FM Opens ClosesSNA1 LOGO A 27 26SNA2 LOGO A 57 56Ready;Finally, to display the contents of a file that resides on a CP-accessed minidisk,issue:cptype cpcache files aAnd, receive this response:* logms* /* Cache all log message related files */sna% logo /* Cache all SNA logo picture files */online message /* Cache the file that contains the"VM/ESA Online" message */Ready;You are authorized to display the contents of files using the CPTYPE commandonly if you have the authority to link to the minidisk on which the files reside.Changing Information on CP-Accessed MinidisksIf your system configuration file contains a FEATURES statement that instructs CPto construct log messages from information in files on CP-accessed minidisks, youcan no longer use the SET LOGMSG command to alter the contents of the logmessage. Instead, you must do the following:1. Issue a CPRELEASE command to have CP remove the minidisk from its list ofaccessed disks.2. Issue the CP LINK command and CMS ACCESS command to link and accessthe target minidisk in write mode.3. Edit the files that contain the log messages for your system.4. Issue the CMS RELEASE command and the CP DETACH command to releasethe minidisk and detach it from your virtual machine.5. Issue a CPACCESS command to have CP add the minidisk to its list ofaccessed disks.34 z/VM: CP Planning and Administration

Understanding the CP File SystemEven though you could have CP maintain read-only access to the disk while youare editing the files, it is recommended that you remove the disk from CP’s list ofaccessed disks first. When CP accesses a minidisk, it reads the minidisk’s filedirectory into storage. Any subsequent changes to the minidisk are not reflected intothe file directory CP keeps in storage until you issue a CPACCESS command tohave CP reaccess the minidisk. If you change files on the minidisk while CP hasaccess to it, users may receive incorrect output in response to commands such asQUERY LOGMSG.On the other hand, you may encounter another problem if you tell CP to remove theminidisk from its list of accessed minidisks before you make your change. If theminidisk you are changing is the only one that contained log message information,and a user issued a QUERY LOGMSG command while you were in the process ofchanging the log message, CP would find no log message files and would respondthat no log message data existed.For example,query cpdisksLabel Userid Vdev Mode Stat Vol-ID Rdev Type StartLoc EndLocPROD1 MAINT 0300 A R/O ESARES 0A0F ECKD 2400 2449Ready;cprelease aCPRELEASE request for disk A scheduled.Ready;CPRELEASE request for disk A completed.query logmsgThere is no logmsg dataReady;It is recommended that to change the contents of minidisks that are accessed byCP, you should work with at least two disks. When you instruct CP to release oneminidisk in order to change files on the minidisk, CP can still read information fromthe second minidisk.For example:query cpdisksLabel Userid Vdev Mode Stat Vol-ID Rdev Type StartLoc EndLocPROD1 MAINT 0300 A R/O ESARES 0A0F ECKD 2400 2449BACKUP MAINT 0301 B R/O ESARES 0A0F ECKD 2450 2499Ready;cprelease aCPRELEASE request for disk A scheduled.Ready;CPRELEASE request for disk A completed.link maint 300 300 wrReady;access 300 aReady;xedit system logmsg aReady;release a (detachReady;Chapter 3. Understanding the CP File System 35

Understanding the CP File Systemcpaccess maint 300 aCPACCESS request for mode A scheduled.Ready;CPACCESS request for MAINT’s 0300 in mode A completed.You can now tell CP to release the B disk (MAINT’s 301) and update it to containthe new SYSTEM LOGMSG file that you placed on MAINT’s 300 disk.You can update logo picture files, input area files, and online message files in asimilar manner. CP uses the changed files as soon as the CPACCESS request forthe minidisk completes.36 z/VM: CP Planning and Administration

Chapter 4. Using the Stand-Alone Program LoaderThe Stand-Alone Program Loader (SAPL) is a generic loader that loads stand-aloneprograms stored in CMS module form on a CMS minidisk. Using SAPL, you canuse any stand-alone program that can be generated in the form of a CMS module.Examples of such programs are:v The CP nucleus module (CPLOAD)v Stand-Alone Program Loader Creation Utility (SALIPL)v DASD Dump Restore Utility (DDR)v Device Support Facilities Program (ICKDSF)This chapter tells you how to use the Stand-Alone Program Loader to load astand-alone program that is generated in the form of a module.During the IPL process, various information is read from DASD devices. Here aresome terms that will be used to refer to these devices:v The IPL device is the device which is specified on the load screen and fromwhich SAPL is loaded.v The SYSRES device is the device from which SAPL loads the CP module.v The parm disk device is the device on which the CP module finds the systemconfiguration file.v Other DASD devices are used but are not of interest for this discussion. Theyinclude the DASD devices used for the CP directory, warmstart, checkpoint,paging, spooling and user minidisks.Creating the Stand-Alone Program LoaderBefore a DASD device can be IPLed, SAPL must be written to the device using theStand-Alone Loader Creation Utility (SALIPL). See the z/VM: CP Commands andUtilities Reference for information on how you can write SAPL to the IPL device byusing SALIPL from the CMS command line. See the “Running Utility Programs” inz/VM: System Operation for information on how to write SAPL to the IPL device byusing SALIPL on the real processor.© Copyright IBM Corp. 1991, 2004 37

Using SAPL|||||||||||||||Important Note!As of z/VM V5R1, the number of blocks on FBA DASD (SCSI or not) thatSALIPL uses for SAPL has increased. SALIPL writes to blocks 5-207 onCP-formatted DASD. In previous releases, SALIPL wrote to blocks 5-31. Youmust ensure that no other functions, such as CP directory, warmstart,checkpoint, paging, spooling, or minidisks, are using the area to which SALIPLwrites.On a CMS minidisk with a RECOMP area, SALIPL writes SAPL to blocks5-207 of the RECOMP area. In previous releases, blocks 5-31 of theRECOMP area were used. In order to accommodate the larger size of SAPL,you may need to increase the size of the RECOMP area on the CMS minidisk.The following data is in the blocks that SALIPL writes out:Blocks 5–196 SAPL programBlocks 197–199 Reserved for IBM UseBlocks 200–207 SCSI boot recordsWhen SALIPL writes SAPL to the IPL device, defaults for the following attributesthat SAPL uses are established:v The location of the CMS minidisk where modules can be foundv The name of the module that is to be loaded by SAPLv The location in storage at which the module will be loaded, if it is relocatablev The IPL parameters that are passed to the program being loadedv Operator instructions that are displayed on the SAPL screen.These defaults can be overridden as described below.The default module is CP (default name CPLOAD), but it may be a stand-aloneprogram in CMS module form. You can have many CP modules in your installation,allowing for different conditions or providing backup. You select the CP module tobe used:v When you run Stand-Alone Program Loader Creation Utility (SALIPL)v During IPL by overriding the SAPL defaults on the SAPL screenv During SHUTDOWN REIPL by using the MODULE operand.Although the file name of a CP module is variable, the file type must be MODULE.CP modules typically reside on a minidisk that is identified as a parm disk in thevolume allocation table, but you can select the DASD volume and offset/extent fromwhich SAPL will read. Therefore, you can have CP modules on multiple minidiskson multiple DASDs.Note: Although SAPL will accept a load origin when loading a CP module, it has noeffect. CP will always relocate itself to location X’2000’.38 z/VM: CP Planning and Administration

Overriding the Console that CP Will UseIf you only need to override the console that CP will use as the system operatorconsole during CP initialization, specify a load parameter of CONSxxxx. Forexample:v Specify CONSSYSG to use the integrated 3270 console on the hardwaremanagement consolev Specify CONSSYSC to use the operating system messages panel on thehardware management consolev Specify CONSxxxx to cause CP to use the 3270 at address xxxx.Overriding Stand-Alone Program Loader DefaultsIf the defaults that were established by the SALIPL utility when it wrote SAPL to theIPL device are acceptable, all you need to do is to IPL from the IPL device. If youneed to change any of the defaults, however, then you must supply a loadparameter with the address of a console for SAPL to use. The console specifiedmust accept 3270 CCWs and data streams and have at least 20 lines and 80columns.If you are running SAPL on a real processor, you specify the console address byentering the device number of the console into the load parameter field of the loadwindow on your processor console. The SAPL screen will be displayed on thespecified console.If you are running SAPL in a virtual machine, you specify the console address usingthe LOADPARM option of the CP IPL command. For example:IPL 18B LOADPARM EA0In this example, 18B is the DASD volume to load from and EA0 is the devicenumber of the console to be used.To cause the SAPL screen to appear on the integrated 3270 console on thehardware management console, specify SYSG as a load parameter. The operatingsystem messages panel on the hardware management console (SYSC) cannot beused by SAPL because it does not accept 3270 CCWs and data streams.To IPL from a SCSI DiskIf you are IPLing CP in a virtual machine from a minidisk on an emulated FBAdevice (SCSI), just specify the minidisk device address as the IPL device on the IPLcommand as shown in the previous example.To IPL from a SCSI disk on the real processor, access the load window on theprocessor console in order to specify additional information. To IPL from a SCSIdisk in a virtual machine by using an FCP device, use the CP SET LOADDEVcommand to specify additional information that will be used by the CP IPLcommand:v Specify the load address of the FCP device you wish to use.v Specify the world wide port name (PORT on the SET LOADDEV command)v Specify the logical unit number (LUN)v Specify 0 for the boot program selector (BOOTPROG)Using SAPLv Specify C8 for the boot record logical block address (BR_LBA) if the IPL devicehas been CP-formatted by ICKDSF or CPFMTXA. The SALIPL utility writes theChapter 4. Using the Stand-Alone Program Loader 39

Using SAPLSCSI boot record to block 200 (X’C8’) of a CP-formatted device. For aCMS-formatted device, SALIPL writes the SCSI boot record at block 200 (X’C8’)into the RECOMP area of the minidisk.v For the load parameter operand, optionally specify a console address on whichyou wish the SAPL screen to appear.v For the OS specific load parameters (SCPDATA) operand, optionally specify aconsole address on which you wish the SAPL screen to appear.Note: As described earlier, the console specified must accept 3270 datastreams. Specify SYSG for the integrated 3270 console on the HMC. Theconsole may also be specified in the load parameter field of the loadpanel on the system console. Note that if both the OS specific loadparameter SCPDATA and the load parameter fields are specified, SAPLwill use the load parameter value.If your configuration uses normal DASD devices (such as 3390), then the IPLdevice, SYSRES device, and parm disk device can all be the same device ordifferent devices. If the IPL device is an FCP device, then the IPL device,SYSRES device, and parm disk device must be the same SCSI disk. This isbecause the FCP device, WWPN, and LUN combination specified on the loadscreen is the only DASD device path known during the IPL process.The Stand-Alone Program Loader ScreenWhen the IPL completes and a valid console has been specified for the loadparameter, you will see a menu screen similar to Figure 1. The defaults will be filledin for some of the fields — all fields except the comments section can be altered.STAND ALONE PROGRAM LOADER: z/VM VERSION n RELEASE n.nDEVICE NUMBER: 018B MINIDISK OFFSET: 35 EXTENT: -MODULE NAME: CPLOAD LOAD ORIGIN: 2000--------------------------------IPL PARAMETERS--------------------------------cons=0ea0 fn=maine-----------------------------------COMMENTS-----------------------------------Secondary parm disks can be found on 18B at offset 185 and on 18A at offsets35 and 185.------------------------------------------------------------------------------9= FILELIST 10= LOAD 11= TOGGLE EXTENT/OFFSETFigure 1. Stand-Alone Program LoaderThe Stand-Alone Program Loader screen contains the following fields:DEVICE NUMBER Specifies the device number of the DASD volumefrom which SAPL will read. Initially, this will be thesame as the device you IPLed, but it can bechanged to any DASD volume containing CMSminidisks.If you IPLed from an FCP device (SCSI disk), theDEVICE NUMBER field will contain the FCP deviceaddress. The WWPN and LUN are not displayed on40 z/VM: CP Planning and Administration

Using SAPLthe SAPL screen and cannot be changed. If youIPLed from an FCP device, you can change theDEVICE NUMBER value to a DASD volume (3390).If you IPLed from a DASD volume, however, youcannot change to an FCP device.MINIDISK OFFSET Specifies the offset from the beginning of the DASDvolume to the start of the CMS minidisk from whichSAPL is to read. This number is cylinders for countkey data devices and blocks for fixed blockarchitecture devices.EXTENT Specifies the extent number from 1 to 9 (first toninth). This field may be used only with DASDvolumes that have been formatted using the DeviceSupport Facilities Program (ICKDSF) and have anallocation map containing PARM extents written onthem. When a valid extent is entered, the offsetcorresponding to the extent will be displayed in theMINIDISK OFFSET field.Note: Only one of the fields, EXTENT or MINIDISKOFFSET, can be altered at a time. Use PF11to toggle which field can be altered.MODULE NAME Specifies the name of a module on the minidisk thatwill be loaded by SAPL.LOAD ORIGIN Specifies the location in memory (HEX address)into which SAPL will load a relocatable module.Specify a LOAD ORIGIN value of 2000 if IPLing aCP module. As of z/VM V5R1, CP will always runwith an origin of X’2000’. If a value other than 2000is specified, then after initially loading at thespecified address, CP will relocate itself to locationX’2000’.IPL PARAMETERS Specifies the data that will be passed to the loadedprogram by SAPL. The contents of this fielddepends entirely on the program loaded by SAPL.For parameters valid for CP, see “Passing IPLParameters” on page 42. If you are IPLing CPfrom an FCP device (SCSI disk), PDVOL=addrmust be specified as an IPL parameter. See thePDVOL= description below for more information.COMMENTS Contains comments such as operator instructions.This field may only be altered by running theSALIPL utility.There is also a message line after the comments area. Any informational messagesor error messages will appear on the message line.There is a list of program function (PF) key numbers and their functions at thebottom of the screen. PF11 toggles which of the two fields, MINIDISK OFFSET orEXTENT, is active. PF10 causes SAPL to try to load a module using the currentcontents of the fields. PF9 displays a list (FILELIST) of files that are on theminidisk. The module you wish to use can be selected on that screen. Figure 2 onpage 42 is an example of a Stand-Alone Program Loader file list screen.Chapter 4. Using the Stand-Alone Program Loader 41

Using SAPLPassing IPL ParametersSTAND ALONE PROGRAM LOADER: z/VM VERSION n RELEASE n.nFILENAME FILETYPE FORMAT LRECL RECORDS BLOCKS DATE TIMEDYN MODULE V 65535 59 925 2003/07/07 12:15:28SALIPL MODULE V 24400 4 7 2003/06/22 15:30:10SYSTEM CONFIG F 80 190 4 2003/06/17 14:47:19HCPSAL MODULE V 24400 4 7 2003/06/15 14:32:29END MODULE F 1024 1896 474 2003/06/01 13:40:19DYNF MODULE V 65535 56 869 2003/05/22 12:36:18DDR MODULE V 65535 5 30 2003/05/21 16:21:44SALTEST MODULE F 7656 1 2 2003/05/21 11:11:22LOGO CONFIG F 80 48 1 2003/05/18 16:31:48LOGO CONFOLD F 80 48 1 2003/11/22 14:43:28SYSTEM CONFN F 80 277 6 2003/08/08 15:40:51GOTHIC LOGO F 79 16 1 2003/06/18 17:11:12UMS LOGO V 75 16 1 2003/06/18 17:04:53SPOOL LOGO F 46 16 1 2003/06/17 18:13:58SYSTEM NETID F 80 8 1 2003/04/29 11:40:35ONLINE MESSFILE F 80 1 1 2003/04/29 11:26:11SYSTEM LOGMSG F 80 1 1 2003/10/03 9:04:223=QUIT 4=SORT(TYPE) 5=SORT(DATE) 6=SORT(NAME) 7=BACK 8=FORWARD 11=SELECTFigure 2. Stand-Alone Program Loader File ListThe files displayed will initially be sorted in descending order by date and time. Youcan sort by file name/file type, file type/file name, and date/time by using the PFkeys identified at the bottom of the screen. If you press PF11 (SELECT) when thecursor is on a line that lists a file, you will be returned to the main menu and the filename of the selected file will be placed in the MODULE NAME file.Using SAPL, you can pass up to 240 characters of parameters into CP at IPL time.The default contents of the 240-character parameter field can be selected whenSALIPL is used to write SAPL to the IPL device. You can choose to override thedefaults by using the full screen option of SAPL.During CP initialization, CP scans the IPL parameter list from left to right. If aparameter is specified more than once, CP uses the last valid occurrence of theparameter.The following list describes the parameters that CP supports:CONS=addrCON=addrSpecifies the location of the operator console that CP is to use. Specify aone-digit to four-digit device address for a 3270 console. Specify SYSC for theoperating system messages panel on the hardware management console(HMC). Specify SYSG for the integrated 3270 console on the HMC.All OPERATOR_CONSoles statements in the system configuration file areignored. The console address specified will be added to the list of consolesdefined on the EMERGENCY_MESSAGE_CONSoles statement found in thesystem configuration file if it has not already been included in that list. For moreinformation, see the description of the EMERGENCY_MESSAGE_CONSolesstatement.FN=filenameSpecifies the file name of the system configuration file. If you do not specify thisoption, CP uses SYSTEM as the file name.42 z/VM: CP Planning and Administration

Using SAPLFT=filetypeSpecifies the file type of the system configuration file. If you do not specify thisoption, CP uses CONFIG as the file type.NOEXITSIntended to assist you in a situation where your dynamic additions to CP aresomehow wrong and are preventing CP from completing system initialization.Use the NOEXITS parameter to tell CP not to process any of these requestsfrom your system configuration file:v CPXLOAD statementv ENABLE EXIT statementv EXTERNAL_SYNTAX statementv ASSOCIATE MESSAGES statementv The ENABLE operand of the ASSOCIATE EXIT statementExcept for examining the statement for syntactic correctness, CP will ignore thestatement or the operand. If it was one of your dynamic additions to CP (forexample, a CP exit) that was causing CP not to initilize, using NOEXITS mayhelp you to IPL CP so that you can correct the problem.NOHCDSpecifies that CP should ignore any IODF statement in the system configurationfile. The system initializes as if no IODF statement were present and HCD isnot used for I/O configuration.An example of when the NOHCD IPL parameter would be useful is if youencounter a disabled wait state because of problems with the IODF statementor problems with the file specified on the IODF statement. Use the NOHCDparameter to IPL the system without HCD and then change the IODFstatement, replacing the IODF or otherwise investigate the wait state condition.PROMPTSpecifies that you wish to have CP prompt you about start-up options at IPLtime. If you specify this option, CP ignores the AUTO_WARM_IPL andAUTO_IPL operands on the FEATURES statement in the system configurationfile.The PROMPT parameter is only valid for the SAPL screen. This parameter isnot acknowledged during CP bounce processing (SHUTDOWN REIPL orrestarting after an abend).PDNUM=nSpecifies the number of the parm disk that you wish CP to use. CP will read theallocation map on the IPL device or the DASD volume indicated on the PDVOLoption and will skip to the n parm disk. If the allocation map does not contain atleast n parm disks, CP loads a disabled wait.PDOFF=offsetSpecifies the offset at which the parm disk resides in the IPL device or theDASD volume indicated on the PDVOL option. If the DASD volume does nothave at least offset cylinders or blocks, or if there is no CMS-formatted minidiskat the specified offset, CP loads a disabled wait.PDVOL=addrSpecifies the real address of the volume on which a parm disk resides that youwish CP to access. If there is no device at address addr or if the device is not aDASD volume, CP loads a disabled wait.If you are IPLing CP from an FCP device (SCSI disk), PDVOL=addr must bespecified as an IPL parameter. Any device address that is not in the I/OChapter 4. Using the Stand-Alone Program Loader 43

Using SAPLconfiguration of the system to be IPLed can be specified for addr. CP requiresthis parameter in order build the EDEVICE control block for the SYSRES/parmdisk device during CP initialization. See “EDEVICE Statement” on page 121 formore information.STORE=nnnnuIndicates the amount of storage you wish CP to use. This amount can be lessthan the real storage that is installed. If you specify an amount that exceeds theactual real storage available on the CPU, CP uses the real storage amount.nnnn is a 1-digit to 4-digit decimal number. u can be:v M Megabytesv G Gigabytesv T Terabytesv P Petabytesv E Ekabytes44 z/VM: CP Planning and Administration

Chapter 5. Defining I/O DevicesThere are four methods that can be used to define I/O devices to CP during IPL:v Allow CP to dynamically sense the devicesv Use RDEVICE statements or EDEVICE statements in the system configurationfilev Use RDEVICE macroinstructions in the HCPRIO ASSEMBLE filev Use Hardware Configuration Manager (HCM) and Hardware ConfigurationDefinition (HCD) to define the devices.The first three methods can be used in combination with each other, but typicallyCP senses the devices and only those devices requiring additional definition willhave an RDEVICE statement or an EDEVICE statement in the system configurationfile. Generally, the HCPRIO ASSEMBLE file is used only in special circumstances,because updating the file requires rebuilding the CP module. It is recommendedthat the tables in this chapter be used to determine how, and if, a given deviceshould be defined in the system configuration file. If a configuration file statement islisted as "not required", then no definition is required and VM will dynamicallydetermine the device characteristics through device sensing. There may be caseswhere a configuration file statement, although "not required", should be used tospecify additional options or features, or both. Devices not found in the tables areeither unsupported or require an RDEVICE macro statement in HCPRIO.To use HCM and HCD to define devices to CP, an IODF statement that specifiesboth an IODF and an osconfig name must be specified in the system configurationfile. In this case, all devices are defined by HCD (except older and unsupporteddevices, which still can be defined in HCPRIO ASSEMBLE) and device sensing andRDEVICE statements or EDEVICE statements in the system configuration filecannot be used. For information about using HCM and HCD, see the z/OS andz/VM: Hardware Configuration Manager User’s Guide and z/VM: I/O Configuration.DeviceSupportA real device can be supported or unsupported. A supported device can besupported for CP and guest use or only for dedicated use by a single guest.A supported device is one of those listed in the z/VM: General Information bookalong with the type of support it receives. If that book does not list a device,assume the device is not supported. The use of listed devices is fully supported byIBM through z/VM service support.A device supported for CP and guest use is one that CP and virtual machines canuse. CP provides system services for the device, including error recovery for guestDIAGNOSE I/O requests and a full command set (that is, you can use alldevice-oriented CP commands for the device). Such a device can also be sharedamong multiple guests if appropriate (for example, DASD) or can be dedicated tothe exclusive use of a single guest.A device supported for dedicated-only use by a single guest can only be logicallyattached to a single guest virtual machine at any one time. The guest must be fullycapable of running with the device. CP cannot use the device itself, andDIAGNOSE I/O services are not supplied to the guest.© Copyright IBM Corp. 1991, 2004 45

Defining I/O DevicesUnsupportedDevicesAn unsupported device is any device not listed in the z/VM: General Informationbook. An unsupported device must be dedicated to a single guest, but properoperation with z/VM and the guest is the customer’s responsibility; IBM does notguarantee that unsupported devices will run properly with z/VM, and service supportfor such device attachments is not supplied.An unsupported device must be defined to z/VM as some unrecognizable devicetype (that is, a device type different from any of the supported IBM devices) andmust be defined with either RDEVICE TYPE UNSUPPORTED statement in thesystem configuration file or the CLASS operand on the RDEVICE macroinstruction.By knowing the class of devices (DASD, tape, and so on) to which the unsupporteddevice belongs, z/VM knows what kinds of unsupported devices are similar.Note: DASD which is defined as being unsupported cannot be IPLed by CP.Unsupported DASD can only be used by a virtual machine which is IPLedeither from a supported device or from a named saved system.DeviceSensingMost IBM devices can be queried (sensed) to determine what type of device theyare. This is done at IPL time and when a device is varied on. For example, assumeyou have an IBM DASD device at address 300. CP issues a sense ID command todevice 300. The device returns information indicating what type of device it is.CP may need more information than that returned by some devices when they arequeried. An example of this type of device is the IBM 4248 printer. When queried,the printer returns only the information that it is a 4248. Necessary information suchas the printer class and the forms control buffer to be used is not provided viasensing; if CP is not provided this information on an RDEVICE statement, CP usesdefault values for that type of printer.If a device does not respond to the device sense ID command, then the devicemust be defined in the system configuration file using the RDEVICE statement.For a complete description of the RDEVICE statement, see “RDEVICE Statement”on page 188.DASDTable 1 indicates for DASD devices whether or not a statement is required in thesystem configuration file. For some devices, a statement is needed only if thedevice is shared, in which case the following statement can be used:RDEVICE rdev TYPE DASD SHARED YESTable 1. Configuration Guide for DASDDevice Statement Needed in Configuration File3380 Models A04, AA4, B04, AD4, BD4,AE4, BE4, AJ4, BJ4, AK4, BK4v When not shared, not requiredv When shared, TYPE DASD YES3380 Model CJ2 v When not shared, not required3390 Models A14, A18, B14, B18, B1C, A24,A28, B24, B28, B2C, A34, B34, A38, B38,B3Cv When shared, TYPE DASD YESv When not shared, not requiredv When shared, TYPE DASD YES46 z/VM: CP Planning and Administration

Defining I/O DevicesTable 1. Configuration Guide for DASD (continued)Device Statement Needed in Configuration File3390 Models A98, B9C v When not shared, not requiredv When shared, TYPE DASD YES9336 Model 20 Not requiredSee “RDEVICE Statement (DASD)” on page 195 for a complete description of theRDEVICE statement.TapesTable 2 indicates for tape devices whether or not a statement is required in thesystem configuration file. The TYPE operand of the RDEVICE statement is requiredfor those devices whose characteristics cannot be dynamically determined.Table 2. Configuration Guide for Tape DrivesDevice Statement Needed in Configuration File3480 All Models Not required*3490 All Models Not required*3495 Tape Library Dataserver **3590 All Models Not required*Notes:*The ’TYPE TAPE’ operand can be specified to provide query capability for tapes that areintentionally left offline at IPL.**See the DFSMS/VM Installation and Customization Guide for information on defining the3495 Tape Library Dataserver for VM use.See “RDEVICE Statement (Tape Units)” on page 207 for a complete description ofthe RDEVICE statement.PrintersTable 3 indicates for printer devices whether or not a statement is required in thesystem configuration file. The TYPE operand of the RDEVICE statement is requiredfor those devices whose characteristics cannot be dynamically determined.Table 3. Configuration Guide for PrintersDevice Statement Needed in Configuration File3203 Model 5 TYPE 32033211 Models 1, 5 TYPE 3211 (For devices, such as a 4248,that emulate a 3211)3262 TYPE IMPACT_PRINTER3268 Models 2, 2C Not required3287 Models 1, 1C, 2, 2C, 4 Not required3289 Models 1, 3, 4, 8 TYPE 32893800 Model 1 TYPE 3800Chapter 5. Defining I/O Devices 47

Defining I/O DevicesTable 3. Configuration Guide for Printers (continued)Device Statement Needed in Configuration File3800 Models 3, 6, 8 TYPE Advance Function Printing( )(AFP)( ) or TYPE 38003812 v When coax attached, not requiredv When BSC attached, TYPEBSC_ADAPTERv When SDLC (VTAM attached), notrequired3816 v When coax attached, not requiredv When BSC attached, TYPEBSC_ADAPTERv When SDLC (VTAM attached), notrequired3820 v When channel attached for use as a PSFprinter, TYPE AFP3825 TYPE AFP3827 TYPE AFP3828 TYPE AFP3835 TYPE AFP3900 TYPE AFPv When VTAM attached, TYPE 37054245 Models 1, 12, 20 TYPE IMPACT_PRINTER4248 Models 1, 2 TYPE IMPACT_PRINTER6262 Models 14, 22 TYPE IMPACT_PRINTERUnit Record DevicesFor BSC attached 3812 or 3816 printers, see “RDEVICE Statement(Communication Controllers)” on page 193 for a complete description of theappropriate RDEVICE statement. For the other printers, see “RDEVICE Statement(Advanced Function Printers)” on page 189 and “RDEVICE Statement (ImpactPrinters)” on page 201 for a complete description.Table 4 indicates for reader and punch devices whether or not a statement isrequired in the system configuration file. The TYPE operand of the RDEVICEstatement is required for those devices whose characteristics cannot be dynamicallydetermined.Table 4. Configuration Guide for Reader and Punch DevicesDevice Statement Needed in Configuration File3505 Models B1, B2 TYPE READER3525 Models P1, P2, P3 TYPE PUNCHSee “RDEVICE Statement (Card Readers)” on page 192 and “RDEVICE Statement(Card Punches)” on page 190 for a complete description of the appropriateRDEVICE statement.48 z/VM: CP Planning and Administration

Defining I/O DevicesDisplaysDisplay devices can be defined in the system configuration file. IBM 3277 displayshave 3277 defined on the TYPE operand of the RDEVICE statement. All othernon-3270 displays can be sensed and no configuration file statement is neededunless the device has special features, such as the Operator Identification Card. If adisplay has a special feature, an RDEVICE statement for the display is needed. Forexample, if a display has an Operator Identification Card, the following RDEVICEstatement should be included in the system configuration file:RDEVICE rdev TYPE 3270_DISPLAY OPER_IDENT_READER YESThe operand rdev is the real device number. For a complete description thisstatement, see “RDEVICE Statement (Graphic Display Devices)” on page 197.CommunicationControllersTable 5 indicates for communication controller devices whether or not a statement isrequired in the system configuration file. The TYPE operand of the RDEVICEstatement is required for those devices whose characteristics cannot be dynamicallydetermined.Table 5. Configuration Guide for Communication ControllersDeviced Statement Needed in Configuration File3705 v When running EP, TYPE 3705v When running NCP, not requiredv When running PEP for BSC lines, TYPEBSC_ADAPTERv When running PEP for ASCII lines, TYPETELE2_ADAPTER3720 Not required when running NCP3725 v When running EP, TYPE 3705v When running NCP, not requiredv When running PEP for BSC lines, TYPEBSC_ADAPTERv When running PEP for ASCII lines, TYPETELE2_ADAPTER3745 v When running NCP, not requiredv When running PEP for ASCII lines, TYPETELE2_ADAPTER9221 Integrated Token Ring TYPE ICA_TOKENRING9221 Integrated Ethernet TYPE ICA_ETHERNETSee “RDEVICE Statement (Communication Controllers)” on page 193 for acomplete description of the RDEVICE statement.ESCONDevicesThese ESCON* devices can be sensed by CP and do not require a systemconfiguration file statement:v 9032 ESCON Director Model 2v 9033 ESCON Director Model 1Chapter 5. Defining I/O Devices 49

Defining I/O Devicesv 9034 ESCON Converter Model 1v 9035 ESCON Converter Model 2v ESCON CTCAFor information on defining ESCON devices that cannot be sensed by CP, see“RDEVICE Statement (Unsupported Devices)” on page 209 in the description of theRDEVICE statement in Chapter 6, “The System Configuration File.” For informationon defining ESCON-attached devices, see the appropriate device tables in thischapter.OtherDevicesTable 6 indicates for various devices whether or not a statement is required in thesystem configuration file. The TYPE operand of the RDEVICE statement is requiredfor those devices whose characteristics cannot be dynamically determined.Table 6. Configuration Guide for Other DevicesDevice Statement Needed in Configuration File3088 Not required3172 Not required3423 Optical Media Attachment TYPE UNSUPPORTED3737 Remote CTCA TYPE CTCA3890 Document Processor Not required4753 Network Security Processor Not required (looks like a 3088)7171 TYPE 3270_DISPLAY8232 Not requiredCTCA TYPE CTCAOSA Not required50 z/VM: CP Planning and Administration

Chapter 6. The System Configuration FileThe Parm DiskThis chapter:v Discusses the parm diskv Provides a summary of system configuration file statementsv Defines general rules for coding the system configuration filev Describes each system configuration file statement in detailThe system definition information required at IPL resides in files on the parm disk, aCMS-formatted minidisk that CP can read. The parm disk must reside on the IPLvolume. The system definition files on the parm disk include:v The main system configuration file, usually called SYSTEM CONFIG, whichcontains operating characteristics such as the layout of the CP system residencedisk, lists of DASD volumes that CP uses, your real storage configuration, andinformation CP requires to determine the correct offset from CoordinatedUniversal Time (UTC). It also contains real device definitions for I/O devices thatdo not respond to a sense ID request and for I/O devices that need moreinformation defined than a sense ID request returns (for example, printers andcommunications controllers). This file is described in detail in this chapter.v The logo configuration file, usually called LOGO CONFIG, which containsinformation about the creation and configuration of logos, including the file namesand file types of the different logo files. For details, see Chapter 7, “The LogoConfiguration File,” on page 279.Note: The parm disk must be CMS-formatted. If it is not CMS-formatted, thesystem enters a disabled wait state, code 6758. If you get this wait code,you can use the alternate parm disk at IPL time. To do this, use theStand-alone Program Loader in console mode and change the parm diskextent on the Stand-alone Program Loader screen to the alternate parm diskextent.Summary of System Configuration File StatementsTable 7 lists all the system configuration file statements, gives you a briefdescription of each statement, and points you to where you can get moreinformation about each statement.Table 7. System Configuration File Statements (SYSTEM CONFIG)Statement Description PageALTERNATE_OPERators Identifies up to eight user IDs that have thepotential to become the system operatorautomatically when the primary system operatorlogs off.ASSOCiate EXit Assigns one or more entry points or externalsymbols to an exit point during initialization.ASSOCiate MESSages/MSGS Assigns an external symbol to a local messagerepository and gives CP information about howto select messages in that repository duringinitialization.CHARACTER_DEFaults Establishes system-wide defaults for the logicalcharacter delete, escape, line delete, line end,and tab symbols.67606467© Copyright IBM Corp. 1991, 2004 51

System Configuration FileTable 7. System Configuration File Statements (SYSTEM CONFIG) (continued)Statement Description PageCP_ACCess Defines the list of disks that CP accessesimmediately when it brings the user directory online.CP_ADDON_INITIALIZE_ROUtines Lists the installation-added entry points that willbe called during system initialization.CP_OWNed Defines and generates a list of up to 255CP-owned volumes.CPXLoad Loads a file containing customer-written CProutines from the parm disk or a CP-accesseddisk into CP’s virtual storage during initialization.DEFine ALIAS Defines a new alias for an existing CP commandon the system during initialization.DEFine COMmand/CMD Defines a new CP command or a new version ofan existing CP command on the system duringinitialization.DEFine DIAGnose Defines a new DIAGNOSE code on the systemduring initialization.DEFine EXit Defines a new exit point in CP duringinitialization.DEFINE LAN Defines a VM LAN segment. 97DEFINE VSWITCH Creates a CP system-owned switch (a VirtualSwitch) to which virtual machines can connect.DEVICes Tells CP what to do with various devices at IPL. 105DISAble COMmand/CMD Prevents CP from processing requests for thespecified CP command during and afterinitialization.DISAble DIAGnose Prevents CP from processing requests for thespecified locally-developed DIAGNOSE codesduring and after initialization.DISAble EXits Prevents CP from calling all entry points andexternal symbols associated with one or moreexit points during and after initialization.DISTRIBUTE Specifies the distribution features for the localsystem.DRAin Stops new operations on specified real devices. 118EDEVice Defines an emulated device that represents areal device.EMERGENCY_MESSAGE_CONSoles Defines consoles for system emergencymessages.ENable COMmand/CMD Permits CP to process requests for the specifiedCP command during and after initialization.ENable DIAGnose Permits CP to process requests for the specifiedlocally-developed DIAGNOSE codes during andafter initialization.ENable EXits Permits CP to call all entry points and externalsymbols associated with one or more exit pointsduring and after initialization.ENFORCE_BY_VOLid Enforces attachment of DASD devices by theirVOLIDs on the ATTACH command.EQUate Groups names of systems that all havesomething in common and should thus betreated similarly.707273768184909410011011211411612112412612813013213352 z/VM: CP Planning and Administration

System Configuration FileTable 7. System Configuration File Statements (SYSTEM CONFIG) (continued)Statement Description PageEXTERNAL_SYNtax Adds locally-developed system configuration filestatements to the system without modifying thesystem configuration file processor, HCPZSCASSEMBLE.FEATures Establishes certain attributes of the system atsystem initialization.FORM_DEFault Generates default user form names. 150HOT_IO_Rate Specifies the number of contiguous unsolicitedinterrupts that CP will accept from faulty I/Odevices before it stops accepting input fromthose devices.IMbed Specifies files to imbed into the SYSTEMCONFIG file at IPL.INIT_MITIME Specifies the MITIME (the time interval at whicha device is checked for missing interrupts) thatis in effect during device initialization at systemIPL time.IODF Specifies the IODF that HCD will use in itscontrol of the I/O configuration.JOURNALing Specifies whether CP should include thejournaling facility in the system being generated;establishes attributes of the facility.LOGO_CONfig Specifies the name and type of a logoconfiguration file.MODify COMmand/CMD Redefines an existing CP command on thesystem during initialization.MODify DIAGnose Redefines an existing DIAGNOSE code on thesystem during initialization.MODify EXit Redefines or removes an existing dynamic CPexit point during initialization.MODify LAN Modifies the properties of a VM LAN segment. 175MODify PRIV_CLASSes Changes the privilege classes and establishesinitial values.MODify VSWITCH Modifies the properties of an existing VirtualSwitch.OPERATOR_CONSoles Defines a list of consoles from which CP canchoose an operator console.PRINTER_TItle Specifies the printed output classes that are tocontain classification titles.PRIV_CLASSes Changes the privilege class that authorizescertain internal CP functions.PRODUCT Defines a product or feature to the system. 186RDEVice Adds to the system’s definition of a set of realdevices.SAY Writes a line of text to the operator’s consoleduring initialization.SET Defines default system configuration values. 219STArt Restarts devices after they have been drained;changes the processing options in effect fordevices.STORage Configures the use of real storage. 222SYSTEM_DATEFormat Sets the system-wide default date format forcommands that provide multiple date formats.135136152155157158160164165169172176178180182184188217220225Chapter 6. The System Configuration File 53

System Configuration FileTable 7. System Configuration File Statements (SYSTEM CONFIG) (continued)Statement Description PageSYSTEM_IDentifier Creates a system identifier for the processor onwhich you run z/VM.SYSTEM_IDENTIFIER_DEFault Provides CP with a default system identifier. 228SYSTEM_RESidence Describes the layout of the system residencedisk.SYSTEM_USERids Specifies user IDs that will perform specialfunctions during and after IPL.THROTtle Limits the number of I/O operations that guestoperating systems can initiate to a specific realdevice.TIMEZONE_Boundary Tells CP which time zone to choose at IPL. 237TIMEZONE_DEFinition Defines system time zones according to theirdistance from UTC.TOLERATE_CONFIG_ERRors Marks sections of the system configuration file inwhich CP is not to tolerate errors.TRANSLATE_TABle Specifies replacements for standard translationtables.USERFOrm Creates a list of user form names and theircorresponding operator form numbers; specifiesforms as NARROW so that a narrow separatorform is printed.USER_DEFAULTS Defines defaults to be used forv global lines per page values for virtual printersand consoles defined on the system, andv querying other users’ POSIX databaseinformation and having their POSIX securityvalues changed.USER_VOLUME_EXclude Defines volumes to be excluded from the uservolume list.USER_VOLUME_INclude Defines user volumes by a generic volumeidentifier.USER_VOLUME_List Generates a list of user DASD volumes not tobe used for paging, spooling, directory, ortemporary disk space.VMLAN Controls global attributes for VM Guest LAN andVirtual Switch support.XLINK_DEVICE_DEFaults Changes the defaults for the CSE track locationformat for particular types of DASD.XLINK_SYSTEM_EXclude Specifies the systems that CP is to exclude fromcross-system link.XLINK_SYSTEM_INclude Specifies the systems that CP is to include incross-system link.XLINK_VOLUME_EXclude Specifies the DASD volumes that CP is excludefrom cross-system link.XLINK_VOLUME_INclude Specifies the DASD volumes that CP is includein cross-system link.XSPOOL_SYStem Specifies the systems that are to participate incross-system commands and spoolingoperations.XSPOOL_TRace Establishes the number of pages of CP storageallocated for the XSPOOL trace tables.XSPOOL_XLIST_INput Defines virtual machines whose input spool fileswill not participate in cross-system functions.22623023223623924124324724825125325525725926326426626827127327454 z/VM: CP Planning and Administration

System Configuration FileTable 7. System Configuration File Statements (SYSTEM CONFIG) (continued)Statement Description PageXSPOOL_XLIST_OUTput Defines virtual machines whose output spoolfiles will not participate in cross-systemfunctions.276General Rules for Coding a System Configuration FileWhen creating or updating a system configuration file, you must follow somegeneral syntax rules.FormatCommentsThe system configuration file can be a fixed-length or variable-length record file.After all continuations of a statement have been resolved, no individual statement inthe file should be longer than 4000 characters, and no individual record in the fileshould be longer than 4000 characters.You can add comments to the file by delimiting them with a beginning charactersequence of /* and an ending sequence of */. A single comment may span multiplerecords in the file. Thus,/*--------------------------------------------------------** The following section defines the CP owned volume list **--------------------------------------------------------*/is a valid comment. As many comments as necessary may be entered on a singlerecord in the file. For example,Features Retrieve Max 100 /* Max for all */ Default 7 /* 7 to start */is allowed.ContinuationsTo put a statement in more than one record of the configuration file, place a commaat the ends of all but the last line of the statement. For example, you can code theFEATURES statement as follows:Features ,Retrieve Max 100 , /* Max for all */Default 7 /* 7 to start */A comma at the end of a line indicates that the statement is not yet complete. Youshould not code a comma if the statement information is complete but a commentcontinues to the next record.Features ,Retrieve Max 100 , /* Maximum number of buffers a non... privileged user may ask for */Default 7 /* Seven to start. This matches the... previous release’s default */is valid, but a comma after DEFAULT 7 would make the statement invalid, as youhave specified no subsequent options. The comma can be placed directly after thelast entry on the line. Thus, the example above would also be valid if specified asChapter 6. The System Configuration File 55

System Configuration FileFeatures,Retrieve Max 100, /* Maximum number of buffers a non... privileged user may ask for */Default 7 /* Seven to start. This matches the... previous release’s default */Finally, a blank line does not cause a continuation to be terminated. You couldspecifyFeatures,Retrieve Max 100because CP ignores any blank lines in the configuration file.CaseIn general, it does not matter whether information in the system configuration file isentered in upper case or mixed case. Most entries in the configuration file areconverted to upper case before they are processed. Thus,System_Identifier_DefaultTHATVMandSystem_Identifier_Defaultthatvmwould have the same results. An exception to this rule occurs when CP encountersa quoted string in the file. A quoted string is any string enclosed within singlequotation marks; the string may contain blanks and special character sequencessuch as /* and */ that are not usually permitted in a single token. Where quotedstrings are allowed and a quoted string is specified in the configuration file, the textinside the quotation marks is not converted to upper case. In the following example,the specified printer title would remain in mixed case:Printer_title I ’Internal Use Only’whilePrinter_title J Confidentialwould create a print classification of CONFIDENTIAL.RecordQualifiersYou can instruct CP to process certain statements in the system configuration fileonly if the file is being used on certain systems. To do this, add one or more recordqualifiers onto the front of a statement. A record qualifier consists of a parameterfollowed by a colon. The parameter can be the system name to which you wish thestatement to apply, or it can be one of the following:v a pattern that contains the special characters * (used in place of one or morearbitrary characters) and % (used in place of exactly one arbitrary character) andthat matches one or more systems to which you wish the statement to applyv a symbol defined with an EQUATE statement that lists the system or systems towhich you wish the statement to apply. An EQUATE statement can list suchsystems either explicitly or describe them using the pattern matching discussedabove.For example, specifyingBOBVM1: BOBVM2: Operator_Consoles 00F256 z/VM: CP Planning and Administration

System Configuration Filewill cause the above OPERATOR_CONSOLES statement to be processed only ifthe system being IPLed is called BOBVM1 or BOBVM2. CP finds out the name ofthe system from SYSTEM_IDENTIFIER or SYSTEM_IDENTIFIER_DEFAULTstatements.The Order of Statements in the FileIn general, statements may be specified in the system configuration file in anyorder. There are, however, a few exceptions to this rule:v TIMEZONE_BOUNDARY statements can refer only to time zones that have beenpreviously defined by TIMEZONE_DEFINITION statements.v IMBED statements and LOGO_CONFIG statements can only use the specialfilename or filetype of -SYSTEM- if the system name has been previously resolvedby a SYSTEM_IDENTIFIER or SYSTEM_IDENTIFIER_DEFAULT statement.v Record qualifiers can only be used if the system name has been previouslyresolved by a SYSTEM_IDENTIFIER or SYSTEM_IDENTIFIER_DEFAULTstatement.Therefore, we recommend that you code SYSTEM_IDENTIFIER,SYSTEM_IDENTIFIER_DEFAULT, and EQUATE statements at the top of theconfiguration file.For statements that do not specify lists of items, statements that occur later in theconfiguration file override equivalent statements specified earlier. For example,Features Disable Clear_TDisk.Features Enable Clear_TDiskwould cause TDISK clearing to be enabled. Exceptions to this rule are theCP_OWNed statement and the IODF statement. If you specify more than oneCP-OWNed statement with the same slot number, CP uses only the first occurrenceof these statements and ignores the subsequent statements. Likewise, if youspecify more than one IODF statement, CP uses only the first occurrence of theIODF statement and ignores the subsequent statements.Statements that specify lists of items are usually processed cumulatively.User_Volume_List ESAUS1 ESAUS2 ESAUS3.User_Volume_List ESAUS4 ESAUS5 ESAUS6would cause the user volume list to consist of all six specified volumes. Twoexceptions to this rule are the OPERATOR_CONSOLES statement and theEMERGENCY_MESSAGE_CONSOLES statement. Each invocation of one of thesestatements defines an entire list of consoles to be used for a specific purpose; anysubsequent invocation causes the entire list for that purpose to be replaced.Checking the Syntax of Statements in the FileYou can check the syntax of the statements in a system configuration file by usingthe CPSYNTAX command. This command checks the specified systemconfiguration file and any files imbedded in that file. For details, refer to the z/VM:CP Commands and Utilities Reference book.Chapter 6. The System Configuration File 57

System Configuration FileALTERNATE_OPERATORS Statement►► ALTERNATE_OPERators ▼ userid ►◄PurposeUse the ALTERNATE_OPERATORS statement to specify a maximum of eight userIDs that have the potential to become the system operator automatically when theprimary system operator logs off.How to SpecifyThe ALTERNATE_OPERATORS statement is optional. You can place theALTERNATE_OPERATORS statement anywhere in the system configuration file. Ifyou specify more than one ALTERNATE_OPERATORS statement, the laststatement overrides any previous specifications.Operandsuseridspecifies up to eight alternate operator user IDs. If the current primary systemoperator logs off and the default primary system operator is not available, oneof these user IDs automatically becomes the primary system operator if thefollowing conditions are met:v the user ID is logged on or disconnectedv the user ID has at least one of the privilege classes required for the systemoperator at the time the operator logs off.The variable userid is an alphanumeric character string of as many as eightcharacters. There is no default alternate operator user ID.UsageNotes1. If alternate operator user IDs are specified and the primary system operator logsoff, CP will select the default operator ID before the alternates if the defaultoperator is logged on or disconnected.2. If no alternate operator user IDs are specified or no alternate can be selectedwhen the primary system operator logs off, there will be no operator until onethe following events occurs:v The default operator ID logs onv Any user ID logs on with at least one of the privilege classes required for thesystem operatorv The SET SYSOPER command successfully selects a new operatorv The system is IPLed.3. For more information on the default primary system operator ID, see the“SYSTEM_USERIDS Statement” on page 232 or “SYSOPR (Required)” on page687.4. For more information on defining operator privilege class, see the“PRIV_CLASSES Statement” on page 184 or “SYSFCN (Optional)” on page673.58 z/VM: CP Planning and Administration

System Configuration FileExamplesTo specify user IDs ALTOP, OTHEROP and OPBACKUP as alternate operators, usethe following ALTERNATE_OPERATORS statement:Alternate_Operators,ALTOP, /* This ID is tried after the default operator */OTHEROP, /* This ID will be tried next */OPBACKUP /* This ID is tried last */Chapter 6. The System Configuration File 59

System Configuration FileASSOCIATE EXIT Statement►►ASSOCiateEXitexit(1)REPlaceFollowingPrecedingDISAbleENable▼ EPName name ►◄Notes:1 You can specify the following operands in any order, as long as EPNAME is the last operandspecified.PurposeUse the ASSOCIATE EXIT statement to assign one or more entry points or externalsymbols to an exit point during initialization.You can also assign entry points and external symbols to an exit point afterinitialization using the ASSOCIATE EXIT command. For more information, see thez/VM: CP Commands and Utilities Reference.How to SpecifyInclude as many statements as needed; they are optional. You can placeASSOCIATE EXIT statements anywhere in the system configuration file.If you specify more than one statement with the same exit point number, CP keepsa cumulative list of operations. For example, if you have one statement indicatingthat you want to replace the list of entry point names and a later statementindicating that you want to add an entry point to the end of the list, CP replaces thelist and adds to the end. The second statement does not overrule the firststatement.Operandsexitis the number of the exit point to which you want to assign an entry point orexternal symbol. The variable exit must be a hexadecimal number betweenX'0000' and X'FFFF'.REPlacetells CP to replace the current list of entry point names and external symbolsthat are already associated with this exit point with the list specified after theEPNAME operand.60 z/VM: CP Planning and AdministrationNote: The order that you specify the entry points and external symbols is theorder in which CP will call them.Followingtells CP to add the specified entry point names or external symbols to the endof the list of existing entry point names and external symbols that are alreadyassociated with the specified exit point number.Note: The order that you specify the entry points and external symbols is theorder in which CP will call them.

System Configuration FileUsageNotesPrecedingtells CP to add the specified entry point names or external symbols to thebeginning of the list of existing entry point names and external symbols that arealready associated with the specified exit point number.Note: The order that you specify the entry points and external symbols is theorder in which CP will call them.DISAbletells CP not to call the entry points and external symbols associated with thisexit point until you enable it. (For more information about enabling exit points,see Usage Note 4.) If omitted, DISABLE is the default.ENabletells CP to immediately start calling the entry points and external symbolsassociated with this exit point.EPName nameis the name (or names) of the entry point or external symbol that CP calls whenencountering this exit point number. Each name must be a 1-character to8-character string. The first character must be alphabetic or one of the followingspecial characters: dollar sign ($), number sign (#), underscore (_), or at sign(@). The rest of the string can be alphanumeric characters, the four specialcharacters ($, #, _, and @), or any combination thereof.Note: The order that you specify the entry points and external symbols is theorder in which CP will call them.1. If you specify the ASSOCIATE EXIT statement in your system configurationfile, you should also specify the CPXLOAD statement (page 76) to load thecustomer-written CP routines for the exit point into CP’s system executionspace. These customer-written CP routines should contain the entry pointnames and external symbols that you will specify on the ASSOCIATE EXITstatement.If CP cannot locate one or more of the entry point names or external symbolson your ASSOCIATE EXIT statement after initialization, CP will ignore theunknown entry point name or external symbol that it does not recognize andcontinues normal processing. If the unknown entry point or external symbol ispart of a list associated with an exit point, CP continues processing the othermembers of the list. CP does not ignore an exit point because it cannot findone entry point or external symbol in the list. CP only ignores an exit point if itcannot find all the entry points and external symbols in the list.For more information about the CPXLOAD command, see the z/VM: CPCommands and Utilities Reference.2. To display whether there are any unknown entry points or external symbolsassociated with an exit point, use the QUERY UNRESOLVED command. Formore information, see the z/VM: CP Commands and Utilities Reference.3. If you specify the ASSOCIATE EXIT statement and do not specify the ENABLEoperand, CP will redefine the exit point with the information from yourASSOCIATE EXIT statement, but will not call any of the entry points orexternal symbols associated with that exit point until you later enable it.4. There are 4 ways to enable an exit point:v Specify another ASSOCIATE EXIT statement further on in your systemconfiguration file and specify the ENABLE operand,Chapter 6. The System Configuration File 61

System Configuration Filev Specify an ENABLE EXITS statement (page 130) further on in your systemconfiguration file,v Enter an ASSOCIATE EXIT command after initialization and specify theENABLE operand, orv Enter an ENABLE EXITS command after initialization.For more information about the ASSOCIATE EXIT or ENABLE EXITScommand, see the z/VM: CP Commands and Utilities Reference.By default, exit points are disabled. Thus, in general, you should follow anyASSOCIATE EXIT commands or statements with ENABLE EXITS commandsor statements.5. CP calls the entry points and external symbols for an exit point in the orderthat you specify them on the ASSOCIATE EXIT statement or command, unlessan entry point overrides this action. Any entry point can tell CP to change thenormal processing flow by skipping one or all subsequent entry points orexternal symbols.6. To display status and usage statistics information about a specific exit pointafter initialization, use the QUERY EXITS command. For more information, seethe z/VM: CP Commands and Utilities Reference.Note: While processing the ASSOCIATE EXIT statement (or command), CPcreates a CP exit block for the specified exit point. For a static exitpoint, CP does not create CP exit control blocks until you associate oneor more entry points or external symbols with that exit point. If you try toissue a QUERY EXITS command against such an exit point, CP issuesmessage HCP2752E as the response to your QUERY EXITS command.For a dynamic exit point, QUERY EXITS responds with the definition ofthe exit, even if there are no entry points associated with it.7. To display the real address of the CP exit block for a specific exit point afterinitialization, use the LOCATE XITBK command. For more information, see thez/VM: CP Commands and Utilities Reference. Again, if you have notassociated one or more entry points or external symbols with the specified exitpoint, there is no CP exit block for CP to locate and display. Instead, CPissues error message HCP2752E.8. To display the real address of the CP indirect call locator block for a specificexit point, use the LOCATE ICLBK command. For more information, see thez/VM: CP Commands and Utilities Reference.9. To change the definition of an existing dynamic exit point, or remove the exitpoint from the system, use the MODIFY EXIT statement (page 172) orcommand. For more information about the MODIFY EXIT command, see thez/VM: CP Commands and Utilities Reference.10. To stop CP from calling the entry points and external symbols associated withone or more exit points after defining those exit points, use the DISABLEEXITS command. For more information, see the z/VM: CP Commands andUtilities Reference.11. To remove the customer-written CP routines from CP’s system executionspace:a. Use the DISASSOCIATE command to revoke all entry point and externalsymbol assignments made with the ASSOCIATE EXIT statement (orcommand)b. Use the CPXUNLOAD command to unload the customer-written CProutines.62 z/VM: CP Planning and Administration

System Configuration File12. After creating a CP exit block, CP will not erase that CP exit block until anotherIPL. Disabling the exit point affects certain fields in the CP exit block, but doesnot erase it. Disassociating the entry point names and external symbols erasesthose fields in the CP exit block, but does not erase the CP exit block itself.13. For more information about user-defined exit points, see the z/VM: CP ExitCustomization book.Examples1. To have CP associate entry point HCPSRC00 with exit number F and to replaceany existing entry point associations, use the following:Associate Exit f EPname hcpsrc002. To have CP add entry point HCPSRC04 at the end of the current list for exitpoint 9C, use the following:Associate Exit 9c Following EPname hcpsrc04Chapter 6. The System Configuration File 63

System Configuration FileASSOCIATE MESSAGES / MSGS Statement►►ASSOCiateMESSagesMSGS(1)COMPonentcompidREPlaceFollowingPrecedingDELayNODELay▼ EPName name ►◄Notes:1 You can specify the following operands in any order, as long as EPNAME is the last operandspecified.PurposeTest Use the ASSOCIATE MESSAGES / MSGS statement to assign an externalsymbol to a local message repository and to give CP information about how toselect the messages in that repository during initialization.You can also assign external symbols to local message repositories afterinitialization using the ASSOCIATE MESSAGES or MSGS commands. For moreinformation, see the z/VM: CP Commands and Utilities Reference.How to SpecifyInclude as many statements as needed; they are optional. You can placeASSOCIATE MESSAGES or MSGS statements anywhere in the systemconfiguration file.If you specify more than one statement with the same component name, CP keepsa cumulative list of operations. For example, if you have one statement indicatingthat you want to replace the list of entry point names and a later statementindicating that you want to add an entry point to the end of the list, CP replaces thelist and adds to the end. The second statement does not overrule the firststatement.OperandsCOMPonent compidtells CP the component identifier to use when issuing one of the messages inthe local message repository. The variable compid is a 1-character tothree-character alphanumeric string. For example, the component ID for thesystem message repository (VM/ESA) is HCP, which is, by default, the lastmessage repository in the search list. For more information, see Usage Note 1.REPlacetells CP to replace the current list of entry point names and external symbolsthat are already associated with this local message repository with the listspecified after the EPNAME operand.Note: The order that you specify the entry points and external symbols is theorder in which CP will call them.Followingtells CP to add the specified entry point names or external symbols to the end64 z/VM: CP Planning and Administration

System Configuration FileUsageNotesof the list of existing entry point names and external symbols that are alreadyassociated with the specified local message repository.Note: The order that you specify the entry points and external symbols is theorder in which CP will call them.Precedingtells CP to add the specified entry point names or external symbols to thebeginning of the list of existing entry point names and external symbols that arealready associated with the specified local message repository.Note: The order that you specify the entry points and external symbols is theorder in which CP will call them.DELaytells CP to process this ASSOCIATE statement after all of the CP_ACCESSstatements have been processed and after all of the delayed CPXLOADstatements have been processed. If omitted, DELAY is the default.NODELaytells CP to process this ASSOCIATE statement immediately.EPName nameis the name (or names) of the entry point or external symbol that points to thedata in CP’s system execution space where the local message repository canbe found. Each name must be a 1-character to 8-character string. The firstcharacter must be alphabetic or one of the following special characters: dollarsign ($), number sign (#), underscore (_), or at sign (@). The rest of the stringcan be alphanumeric characters, the four special characters ($, #, _, and @), orany combination thereof.Note: The order that you specify the entry points and external symbols is theorder in which CP will call them.1. HCP is the standard component ID for z/VM messages. If you do not specifyany ASSOCIATE MESSAGES or MSGS statements (or commands) for an entrypoint, HCPMES is, by default, the only message repository in the search list forthat entry point.If you do assign one or more local message repositories to an entry point, thoserepositories are added to the search list in the order that you specify (using theREPLACE, FOLLOWING, or PRECEDING operands) and, by default, HCPMESis the last message repository in the search list.When the routines in that entry point issue a message, CP searches the firstmessage repository in the search list. If CP finds the message in that repository,it issues the message and does not search any more repositories. If CP doesnot find the message, it continues searching through each repository until itfinds the first occurrence of that message.Using ASSOCIATE MESSAGES or MSGS statements (or commands), you canassign local message repositories which override existing z/VM messages in theHCPMES repository. Or, you can specify HCP as the component ID and movethe z/VM message repository to a place in the search list other than last place.2. Before CP can begin using your message repository, you must:a. Generate your messages using the CMS GENMSG command. For moreinformation about the CMS GENMSG command, see the z/VM: CMSCommands and Utilities Reference.Chapter 6. The System Configuration File 65

System Configuration Fileb. Load the message repository file using the CPXLOAD statement (page 76)or command. For more information about the CPXLOAD command, see thez/VM: CP Commands and Utilities Reference.3. If CP cannot find the entry point you specified for EPNAME when the messageis being displayed, CP displays message substitution data, if any.4. To display information about the local message repositories available on yoursystem, use the QUERY CPLANGLIST command and specify the ASSOCIATEDoperand. For more information, see the z/VM: CP Commands and UtilitiesReference.5. To remove the message repository file from CP’s system execution space:a. Use the DISASSOCIATE command to revoke the external symbolassignment made with the ASSOCIATE MESSAGES or MSGS statement (orcommand.)b. Use the CPXUNLOAD command to unload the repository.For more information about the DISASSOCIATE or CPXUNLOAD command,see the z/VM: CP Commands and Utilities Reference.6. To have CP use the message repositories associated with a specificcomponent, you must specify that component ID on the COMPID keyword ofthe HCPCONSL macroinstruction. For more information about the HCPCONSLmacroinstruction and about using your own message repositories, see the z/VM:CP Exit Customization book.Examples1. To have CP assign an uppercase English message repository containingmessages starting with OUR to entry point OURMESS1, use the following:Associate Messages component our, /* Set it up so we can use */preceding, /* messages we wrote. */epname ourmess166 z/VM: CP Planning and Administration

System Configuration FileCHARACTER_DEFAULTS Statement►►CHARACTER_DEFaults(1)▼ASCII_LINE_DELete [ASCII_LINE_DELeteCHAR_DELete@cOFF►◄CHAR_DELeteESCape'"'cOFFESCape cOFFLINE_DELete ¢LINE_DELeteLINE_END #LINE_ENDTAB ]cOFFcOFFTABcOFFNotes:1 You must specify at least one of the following operands.PurposeOperandsUse the CHARACTER_DEFAULTS statement to set the default characters that willrepresent the logical character delete, escape, line delete, line end, and tabsymbols on your system.ASCII_LINE_DELete cdefines the logical line delete symbol for ASCII devices on your system.Choose a character that is not commonly specified by the users on yoursystem. If you specify OFF, your system will not have a logical line deletefunction for ASCII devices. If omitted, the default is a left bracket ([).CHAR_DELete cdefines the default logical character delete symbol on your system. Choose acharacter that is not commonly specified by the users on your system. If youspecify OFF, your system will not have a logical character delete symbol. Ifomitted, the default is an at sign (@).ESCape cdefines the default logical escape symbol on your system. Choose a characterthat is not commonly specified by the users on your system. If you specify OFF,your system will not have a logical escape character. If omitted, the default is adouble quotation mark (").Chapter 6. The System Configuration File 67

System Configuration FileLINE_DELete cdefines the logical line delete symbol for all non-ASCII devices on your system.Choose a character that is not commonly specified by the users on yoursystem. If you specify OFF, your system will not have a logical line deletefunction. If omitted, the default is a cent sign (¢).LINE_END cdefines the logical line end symbol on your system. Choose a character that isnot commonly specified by the users on your system. If you specify OFF, yoursystem will not have a logical line end symbol. If omitted, the default is a poundsign (#).TAB cdefines the logical tab symbol on your system. If you specify OFF, your systemwill not have a logical tab character. If omitted, the default is a right bracket (]).For each of the Operands, you can specify c by typing the character (c), bytyping the character enclosed in single or double quotation marks ('c') or ("c") orby typing the hexadecimal equivalent of the character (X'hh') or (X"hh"). If youneed to specify a single quotation mark, enclose it within double quotationmarks. If you need to specify a double quotation mark, enclose it within singlequotation marks.UsageNotes1. The CHARACTER_DEFAULTS statement defines default symbols for yourentire system. If you want to override the system defaults for a specific user,you can specify defaults for that user:v On the USER control statement in the system directory (page 572)v By having the user issue the CP TERMINAL command after logging on. Formore information, see the z/VM: CP Commands and Utilities Reference.2. You cannot use any of the letters A through Z, the numbers 0 through 9, or thebytes X'0E' (shift out) or X'0F' (shift in) for the line-end, line-delete,character-delete, escape, or tab characters.3. With the widespread use of “@” in internet addresses, it is recommended thatyou specify OFF for the default character-delete symbol, or define a symbolother than @ as the character-delete symbol, to avoid problems in the datastream.4. Specifying a blank character (X'40') for any of the default symbols is notrecommended.5. The character display depends on the code page used by the terminal emulator.These characters are from code page 037 United States:# X'7B'SYSLEND LINEND¢ X'4A'SYSLDEL LINDEL@X'7C'SYSLCEL CHARDEL“ X'7F'SYSLESCP ESCAPEX'6A'SYSTAB TABCHAR68 z/VM: CP Planning and Administration

System Configuration File[ X'AD'SYSALDEL LINDELExamples1. To turn off the logical line delete symbol and define the logical tab symbol onyour system as a backslash (\), use the following CHARACTER_DEFAULTSstatement:Character_Defaults Line_Delete off, /* Turn off Line_Delete */Tab \ /* Override Tab default */Chapter 6. The System Configuration File 69

System Configuration FileCP_ACCESS Statement►► CP_ACCess userid vdev fmSRmode►◄PurposeUse the CP_ACCESS statement to specify a CMS-formatted minidisk that CPshould access when it brings the user directory online. This CP-accessed minidiskmay contain system, logo, or device information to use at run-time. This informationmay include log messages and logos. CP searches for this information on anyCP-accessed disks you specify in the order that you specify.How to SpecifyInclude as many statements as needed; they are optional. You can placeCP_ACCESS statements anywhere in the system configuration file. If you specifymore than one statement with the same operands, the last operand definitionoverrides any previous specifications.Operandsuseridspecifies the user ID of the owner of the minidisk that you want to makeavailable to CP.vdevis the virtual device number of the specified user’s minidisk, as defined in theuser’s entry in the system directory. The number can be any hexadecimalnumber between X'0000' and X'FFFF'.fm is the file mode letter that you want assigned to all files on the specifiedminidisk. You can specify any letter from A to Z.modeis the access mode. The following is a list of valid modes listed in order ofincreasing control:R Read-only access. CP establishes read access.RRRead-only access. CP establishes read access.W Write access. CP establishes write access.WRWrite access. CP establishes write access. If write access is denied, CPestablishes read access.M Multiple-write access. CP establishes write access. If a previous write,stable, or exclusive mode access exists, CP denies access.MRMultiple-write access. CP establishes write access. If a previous write orstable access exists, CP establishes read-only access.MWMultiple-write access. CP establishes write access in all cases.SR(The default) Stable read-only access. CP establishes read access. CPdenies all requests for write access to a disk with an existing SR mode70 z/VM: CP Planning and Administration

System Configuration FileUsageNotesaccess. A stable access means that the user holding the SR access can beassured that the disk remains stable, unchanged by others, until CPreleases the access.SWStable write access. CP establishes write access. CP denies all requests forwrite access to a disk with an existing SW mode access. A stable accessmeans that the user holding the SW access can be assured that the diskremains stable, unchanged by others, until CP releases the access.SMStable multiple access. CP establishes write access. CP denies all requestsfor write access to a disk with an existing SM mode access. A stableaccess means that the user holding the SM access can be assured that thedisk remains stable, unchanged by others, until CP releases the access.ERExclusive read-only access. CP establishes read access. CP denies allrequests for access to a disk with an existing exclusive mode. An exclusiveaccess means that the user holding the ER access has stable access withthe added restriction that no one else has, or can get access to, thespecified minidisk until CP releases the access.EWExclusive write access. CP establishes write access. CP denies all requestsfor access to a disk with an existing exclusive mode. An exclusive accessmeans that the user holding the EW access has stable access with theadded restriction that no one else has, or can get access to, the specifiedminidisk until CP releases the access.1. Because CP does not bring the user directory online until after all CP_ACCESSstatements are parsed, CP cannot tell you whether you specified an invalid userID and virtual device number combination. To find out which CP_ACCESSstatements were valid, you must wait until initialization completes and check tosee what minidisks CP accessed. To display all the CP-accessed minidisks, usethe QUERY CPDISK command. For more information about the QUERYCPDISK command, see the z/VM: CP Commands and Utilities Reference.2. If you specify the NODIRECT option during the IPL, CP ignores allCP_ACCESS statements in the system configuration file.3. After initializing CP, use the CPACCESS command to access minidisks for CPand use the CPRELEASE command to release minidisks. For more information,see the z/VM: CP Commands and Utilities Reference.4. The use of the stable and exclusive link modes (SR, SW, SM, ER, EW) iscontrolled by the LNKSTABL and LNKEXCLU options on the OPTION directorycontrol statement. For more information about the OPTION statement, see“OPTION Directory Control Statement (General)” on page 533.Examples1. To access three minidisks owned by the MAINT and PICTURE user IDs, usethe following CP_ACCESS statements:CP_Access maint 0300 a SR /* Give CP access to LOGMSG files */CP_Access maint 0301 b SR /* Give CP access to backupLOGMSG files */CP_Access picture 0193 c SR /* Give CP access to LOGO files */Chapter 6. The System Configuration File 71

System Configuration FileCP_ADDON_INITIALIZE_ROUTINES Statement►► CP_ADDON_INITIALIZE_ROUtines ▼ entry point name ►◄PurposeCode the CP_ADDON_INITIALIZE_ROUTINES statement to generate a list ofinstallation-added entry points in CP which are to be called during systeminitialization.How to SpecifyThe CP_ADDON_INITIALIZE_ROUTINES statement is optional; if specified, youcan include as many statements as you need as long as the total number of entrypoints does not exceed 500.OperandsYou can place CP_ADDON_INITIALIZE_ROUTINES statements anywhere in thesystem configuration file. If you specify more than one statement with the sameoperands, the last operand definition overrides any previous specifications.entry point nameis the installation-defined entry point which is to be called during systeminitialization. The variable entry point name is a 1-character to 8-characteridentifier. This must be a valid CP entry point, which can be located with the CPLOCATE command. The entry point must be MP (multi-processor)-capable anduse a dynamic savearea.UsageNotes1. Entry points listed must be included in the CP module.2. CP will schedule each of the specified entry points for execution during thesystem initialization process. However, the entry points may not run until afterinitialization is complete.ExamplesTo specify LOCALMOD, USERMOD, and XMOD as entry points to be startedduring system initialization, code the following CP_ADDON_INITIALIZE_ROUTINESstatement:CP_ADDON_INITIALIZE_ROUTINESLOCALMOD,USERMOD,XMOD72 z/VM: CP Planning and Administration

System Configuration FileCP_OWNED Statement►► CP_OWNed Slot nnn RESERVEdOwnvolidDumpShared►◄PurposeUse the CP_OWNED statement to define a list of up to 255 CP-owned DASDvolumes. CP-owned DASD volumes are the CP system residence volume and anyvolumes containing real system paging, spooling, dump, directory, and temporarydisk space.If you are not using cross system spool (XSPOOL) file sharing, you can use anyvolumes listed on a CP_OWNED statement and containing spool space to read andwrite spool files. (CP writes spool files only once, when they are created.)If you are using cross system spool (XSPOOL) file sharing, physical sharing of thespooling DASD provides shared access to spool files for all systems in the complex.Although physically this is both read and write sharing, logically the sharing isread-only. Therefore, you must identify some volumes as available for writing thespool files created on this system, and others as available only for reading spoolfiles created on other systems. You can identify these volumes using the OWN andSHARED options of the CP_OWNED statement.Note: We strongly recommend that you do not share the system residencevolumes and paging volumes among systems in a cross system spoolingcomplex.How to SpecifyInclude as many statements as needed; they are optional. You can placeCP_OWNED statements anywhere in the system configuration file. If you specifymore than one statement with the same slot number, CP uses only the firststatement. Subsequent CP_OWNED statements do not redefine the slot.OperandsSlot nnntells CP the number of the slot in the CP-owned volume list. nnn must be adecimal number from 1 to 255.RESERVEdtells CP to reserve the slot for future use.volidis the 1-character to 6-character volume serial number of the volume you wantto include in the CP-owned volume list.Own(the default) tells CP that the system you are generating owns the specifiedvolume and that only this system can create or destroy spool files on thisvolume. The other systems in the cross system spooling complex, which defineChapter 6. The System Configuration File 73

System Configuration Filethe specified volume with the SHARED option, have shared access to thissystem’s spool files because they can read the data on this volume.Dumptells CP to reserve the spool space on the specified volume exclusively fordumps.Sharedtells CP that another system in the cross system spooling complex owns thespecified volume. This system cannot create or destroy spool files on theidentified volume. It can, however, read spool files previously written by theowning system.UsageNotes1. Before CP can use a DASD, you must format, label, and allocate space on theDASD. You can do this using the Device Support Facilities program (ICKDSF)or the CPFMTXA utility. However, we recommend that you use the ICKDSFmethod of CP volume maintenance because it is required for certain DASDtypes. You should format ECKD devices without filler records using ICKDSF. Formore information about ICKDSF, see the ICKDSF User’s Guide and Reference.For more information on the CPFMTXA utility, see the z/VM: CP Commandsand Utilities Reference.2. If you specify a volume that is not mounted on a CP_OWNED statement whenCP is loaded, CP considers that volume unavailable. If possible, CP continuesprocessing and creates an empty slot for the specified volume in the CP-ownedvolume list. By creating empty slots in the CP-owned volume list, you canprovide space for future growth. When you need to attach a volume to thesystem, the system operator can mount and attach the volume (using the CPATTACH command) without having to re-IPL the system. For more informationabout the CP ATTACH command, see the z/VM: CP Commands and UtilitiesReference.3. If you want to add new volumes to a system that has already been IPLed, addnew volume identifications either in empty slots in the CP-owned volume list orat the end of the list, using the CP DEFINE CPOWNED command. For moreinformation about the CP DEFINE CPOWNED command, see the z/VM: CPCommands and Utilities Reference.By adding new volumes in empty slots or at the end of the CP-owned list, youdo not affect the warm start data on the volumes already listed in the CP-ownedlist. This means you can warm start the system without disturbing the relativeentry number that locates system spool buffers.To delete a CP_OWNED volume:v Remove the CP_OWNED statement from the system configuration file. In thiscase, you must IPL with a cold start.v Change the volid to RESERVED in the system configuration file. In this case,you must IPL, but a cold start may not be necessary.Attention: If you delete any volume that contains spool space from theCP-owned volume list, or move any volume that contains spool space to adifferent slot in the CP-owned volume list, a clean start is required. A clean startcauses the deletion of spool files and system data files, including named savedsystems and saved segments. Files that are to be preserved over such achange should be dumped to tape using the CP SPXTAPE DUMP command.After the clean start, SPXTAPE LOAD should be used to restore the spool filesand system data files from tape. This ensures that spool files and system data74 z/VM: CP Planning and Administration

System Configuration Filefiles that existed on the system before deletion or movement of volumes in theCP-owned volume list are restored correctly.4. If you specify the DUMP option for a volume with spool space that is already inuse when you IPL the system, those spool files remain on that volume until youmove them with a CP SPXTAPE DUMP command with the PURGE option. Formore information about the CP SPXTAPE command, see the z/VM: CPCommands and Utilities Reference.5. For a single VM/ESA system, that is, one that is not using cross systemspooling, you should specify the OWN option for all CP volumes. Do not specifythe SHARED option.6. If you are using cross system spooling:a. You must include all volumes that have SPOL extents in a CP_OWNEDstatement for each system, with the same slot number in each system’sCP_OWNED statement. We suggest that you group all volumes with SPOLextents by system and place them first in the CP-owned volume list.b. If you specify the DUMP option for a specific volume, CP treats that volumethe same way as it would if you had specified the OWN option; only thissystem may allocate spool space for dumps on this volume.You must specify the SHARED option for the same volume in the CP-ownedvolume lists of all the other systems in the CSE complex.c. In the CP-owned volume list, you cannot change the order of the volumesthat contain SPOL space unless you perform a clean start on all systems inthe complex. If you do change the order, you may have to use the CPSPXTAPE command to avoid losing spool files. However, if you add newSPOL space volumes to the end of the CP-owned volume lists of theassociated systems without disturbing the slot numbers of existing volumes,a clean start is not required.7. At system initialization (IPL), if more than one DASD volume has the samevolume serial number (volid) and that volid is in the CP or user volume list, thevolume with the lowest device number is attached to the system. This rule doesnot apply to duplicates of the system residence (IPLed) volume.8. The list of CP-owned volumes generated by CP_OWNED statementscompletely supersedes the list of CP-owned volumes generated by theSYSCPVOL macroinstruction in HCPSYS ASSEMBLE.Examples1. To define a CP-owned volume list that contains:v A system residence volume, which your system ownsv A volume for spool and temporary disk space, which your system ownsv A volume for spool space, which another system ownsv A volume for dump space, which your system ownsv Three empty slots for volumes you will be getting shortlyuse the following CP_OWNED statements:CP_Owned Slot 001 esares Own /* System Residence volume */CP_Owned Slot 002 essys1 Own /* Spool and T-disk space */CP_Owned Slot 003 essys2 Shared /* Spool space for VM2 */CP_Owned Slot 004 sysdmp Dump /* Dump space */CP_Owned Slot 005 Reserved /* Leave some slots open in */CP_Owned Slot 006 Reserved /* case we need to add some */CP_Owned Slot 007 Reserved /* extra spool space later. */Chapter 6. The System Configuration File 75

System Configuration FileCPXLOAD Statement►► CPXLoad fn* (1)ftTEXT fm*TXTLIB MEMber memberfmRun-Time Operands Load Operands ►◄Run-Time Operands:LOckNOLOckMPNOMPNONMPLoad Operands:(2)CONtrol epnameNOCONtrolDELayNODELayLEt (3)NOLEtPERManentTEMPoraryNotes:1 You can specify the Run-Time and Load operands in any order.2 If you specify CONTROL or NOCONTROL on an OPTIONS directive, you can omit them on thisCPXLOAD command.3 If you specify PERMANENT or TEMPORARY on an OPTIONS directive, you can omit them onthis CPXLOAD command.PurposeUse the CPXLOAD statement to load a file containing customer-written CP routinesfrom the parm disk or a CP-accessed disk into CP’s system execution space duringinitialization.You can also load customer-written CP routines into CP’s system execution spaceafter initialization using the CPXLOAD command. For more information, see thez/VM: CP Commands and Utilities Reference.How to SpecifyInclude as many statements as needed; they are optional. You can placeCPXLOAD statements anywhere in the system configuration file. For moreinformation about where you can place the customer-written CP routines, seeUsage Note 3.Operandsfn is the name of the file that you want loaded. Because you are loading duringsystem initialization, you must make sure the CP routines are located in a placewhere CP can find them. See Usage Note 3 for more information.76 z/VM: CP Planning and Administration

System Configuration Fileft is the file type (other than TEXT or TXTLIB) of the file that you want loaded.This file may contain CPXLOAD directives, text records, or a combination ofboth. If the file contains text records, it must have a fixed record format(RECFM F) and a logical record length of 80 (LRECL 80). If the file does notcontain text records, it can be any record format and must have a logical recordlength less than 4,000 (LRECL < 4000).TEXTtells CP that this is a text file that contains 1 or more CSECTs and can contain1 or more CPXLOAD directives. Text files must have a fixed record format(RECFM F) and a logical record length of 80 (LRECL 80).TXTLIBtells CP that the file is a text library that contains 1 or more members. A TXTLIBmember can contain 1 or more control sections (CSECTs) and can containCPXLOAD directives. TXTLIB files must have a fixed record format (RECFM F)and a logical record length of 80 (LRECL 80).* tells CP to search the list of CP-accessed minidisks until it finds the firstoccurrence of the specified file that you want loaded. If you do not specify a filemode, * is the default.fm is the file mode of the CP-accessed minidisk containing the file that you wantloaded.MEMber memberis the name of the member in the TXTLIB that you want loaded.You can use generic member names to request a specific subset of files. Ageneric member name is a 1-character to 8-character string with asterisks (*) inplace of 1 or more characters and percent signs (%) in place of exactly 1character. For example:hc%p* ...lists all members that start with HC and have P as their fourth character.LOckNOLOckhas no effect and is retained only for compatibility. All symbols are consideredresident, which means they cannot be locked or unlocked.MPtells 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.NOMPNONMPtells 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 (MP) 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.CONtrol epnametells CP to call the specified entry point after loading the customer-written CProutines and before processing a CPXUNLOAD request. You can load thecustomer-written CP routines containing the specified entry point either beforeor within this CPXLOAD request. The variable epname must be a 1-character to8-character string. The first character must be alphabetic or one of the followingChapter 6. The System Configuration File 77

System Configuration Filespecial characters: dollar sign ($), number sign (#), underscore (_), or at sign(@). The rest of the string can be alphanumeric characters, the 4 specialcharacters ($, #, _, and @), or any combination thereof.Note: Normally, if CP cannot find an entry point when processing an exit pointroutine, it ignores the unknown entry point and continues normalprocessing. This is not true when you specify the CONTROL epnameoperand. If CP cannot find the entry point you specify on CONTROL, CPwill terminate processing your CPXLOAD statement and will not load thecustomer-written CP routines into its system execution space.NOCONtroltells CP not to call an entry point after loading the customer-written CP routinesand before processing a CPXUNLOAD request.DELaytells CP to process all CP_ACCESS statements before processing thisCPXLOAD statement. The customer-written CP routines that you are loadingmust be located on one of the disks specified on one of the CP_ACCESSstatements. If omitted, DELAY is the default.NODELaytells CP to process this CPXLOAD statement immediately and not to wait untilafter processing the CP_ACCESS statements. This means that thecustomer-written CP routines must be a file on the parm disk, which is the onlydisk that CP has access to at this stage of the initialization process. If youspecify a file mode letter and NODELAY, CP ignores your file mode, issuesmessage HCP2777I, and looks for your customer-written CP routines on theparm disk.LEttells CP to load the specified file and to ignore any records that are completelyblank or that contain an unexpected value in column 1. This is meant toaccommodate the non-commented information that can be left in a TEXT file byan assembler utility such as VMHASM.NOLEttells CP to stop loading the specified file when it encounters an unexpectedvalue in column 1. Column 1 is expected to contain '*' (to denote a comment),X'02' (to denote a TEXT record), or blank (to denote a possible CPXLOADdirective).PERManenttells CP that the customer-written CP routines being loaded are to remain a partof CP until a CP SHUTDOWN command is issued or a software-initiated restart(bounce) occurs. This means you cannot use the CPXUNLOAD command toremove these CP routines.TEMPorarytells CP that the customer-written CP routines being loaded can be unloaded inthe future with a CPXUNLOAD command.UsageNotes1. When loading your files into storage, CP treats each control section (CSECT)independently for storage allocation. Also during loading, CP allocates 1 pageof storage to each CSECT. There is 1 exception: if CP encounters a CSECT ofzero length during CPXLOAD processing, that CSECT is deleted. If you needto load a zero-length CSECT, add an EXPAND directive to your input file. For78 z/VM: CP Planning and Administration

System Configuration Fileexample, if you had zero-length CSECT XXXDOG to load, you would add“EXPAND XXXDOG(8)” to your input file.2. When invoking your files, CP treats each entry point in a CSECTindependently for the MP attribute.3. The customer-written CP routines that you are loading must be on a disk thatCP has access to when the load operation is done. If you have a CPXLOADstatement in your system configuration file that specifies the NODELAYoperand, the customer-written CP routines must be a file on the parm diskbecause the minidisks specified on CP_ACCESS statements are not availableuntil the end of the initialization process. If your CPXLOAD statement specifiesthe DELAY operand, the customer-written CP routines can be on any disk, aslong as you have specified a CP_ACCESS statement for that disk in yourconfiguration file. For more information about the CP_ACCESS statement, seepage 70.4. You can specify run-time and load operands on either the CPXLOADstatement or the OPTIONS directive, or both. However, if you specify optionson both and those options conflict, CP uses the options from the CPXLOADstatement. For example, suppose you specify PERMANENT on the OPTIONSdirective and TEMPORARY on the CPXLOAD statement, CP will load the CProutines as temporary. For more information about the OPTIONS directive andseveral other directives, see the z/VM: CP Exit Customization book.5. To assign entry points and external symbols to an exit point and to enable ordisable that exit point, use the ASSOCIATE EXIT statement (page 60) orcommand. For more information about the ASSOCIATE EXIT command, seethe z/VM: CP Commands and Utilities Reference.6. To assign an external symbol to a local message repository, use theASSOCIATE MESSAGES or MSGS statement (page 64) or command. Formore information about the ASSOCIATE MESSAGES or MSGS command, seethe z/VM: CP Commands and Utilities Reference.7. To display information about customer-written CP routines loaded by theCPXLOAD statement, use the QUERY CPXLOAD command. For moreinformation, see the z/VM: CP Commands and Utilities Reference.8. To display information about external symbols you may have loaded, use theLOCATE SYMBOL command. For more information, see the z/VM: CPCommands and Utilities Reference.9. To remove CPXLOADed files from CP’s system execution space:a. Use the DISASSOCIATE command to revoke all entry point and externalsymbol assignments made with the ASSOCIATE EXIT, MESSAGES, orMSGS statements or commandsb. Use the CPXUNLOAD command to unload the customer-written CProutines.For more information about the commands listed above, see the z/VM: CPCommands and Utilities Reference.10. For more information about loading customer-written CP routines into CP’ssystem execution space, about run-time and load operands, and aboutCPXLOAD directives, see the z/VM: CP Exit Customization book.11. CPXLOAD provides the ability to load executable code, message repositories,and data modules dynamically. Only compiled files may be loaded. Thesecompiled files would be the TEXT file output from the assembler or from theCMS GENMSG command.Chapter 6. The System Configuration File 79

System Configuration FileExamples1. To have CP load a multiprocessor capable abend text deck, use the following:CPXload abend text * MP, /* Load the abend text deck */Control kaos,PermanentCP assigns a load identifier (load ID) to the loaded CP routines. If you everwant to unload these CP routines (using the CPXUNLOAD command), you willneed to specify the load ID that CP assigned. If you do not know the load ID,use the ALL operand of the QUERY CPXLOAD command to display (amongother things) the load IDs of all the CP routines loaded onto (and not yetunloaded from) the system.The load ID that CP assigns is a 1-digit to 10-digit decimal number between 0and 2,147,483,647. The first time you use the CPXLOAD statement (orcommand), CP assigns that set of customer-written CP routines a load ID of 0.CP increases the load ID by 1 for each subsequent CPXLOAD request. If all theCPXLOAD requests are successful, you will have a sequential list of loaded CProutines.If one or more of the CPXLOAD requests are unsuccessful or you issue theCPXULOAD command to unload some customer-written CP routines, there willbe one or more gaps in your sequential list of loaded CP routines. The next timeyou load some customer-written CP routines, CP ignores these gaps in the listand assigns the newly-loaded CP routines a load ID that is one more than thelast assigned load ID.For example, suppose you had customer-written CP routines loaded at IDs 0through 7 and you unloaded the CP routines at IDs 2, 3, and 5. This means youstill have CP routines loaded at IDs 0, 1, 4, 6, and 7. The next time you use theCPXLOAD command, CP will assign 8 as the load ID for those CP routines. CPwill not try to fill in the gaps at 2, 3, or 5.80 z/VM: CP Planning and Administration

System Configuration FileDEFINE ALIAS Statement►► DEFine ALIAS aliasFORcommandQuery SUBCmd subcommandVirtualSet SUBCmd subcommand(1)►►ABBRevlengthnnDISAbleENable(2) IBMclass *IBMclassc►◄Notes:1 You can specify the following operands in any order.2 If the existing CP command has multiple versions, you must specify the IBMCLASS operand forCP to locate the correct version.PurposeUse the DEFINE ALIAS statement to define a new alias for an existing CPcommand on the system during initialization.You can also define a new alias after initialization using the DEFINE ALIAScommand. For more information, see the z/VM: CP Commands and UtilitiesReference.How to SpecifyInclude as many statements as needed; they are optional. You can place DEFINEALIAS statements anywhere in the system configuration file. If you specify morethan one statement with the same operands, the last operand definition overridesany previous specifications.Operandsaliasis the name of the alias that you are defining. The variable alias must be a1-character to 12-character string.commandis the name of the existing CP command for which you are creating an alias.The variable command is a 1-character to 12-character string.Query SUBCmd subcommandtells CP the name of the existing CP QUERY subcommand for which you arecreating an alias. The variable subcommand is a 1-character to 12-characterstring.Query Virtual SUBCmd subcommandtells CP the name of the existing CP QUERY VIRTUAL subcommand for whichyou are creating an alias. The variable subcommand is a 1-character to12-character string.Chapter 6. The System Configuration File 81

System Configuration FileSet SUBCmd subcommandtells CP the name of the existing CP SET subcommand for which you arecreating an alias. The variable subcommand is a 1-character to 12-characterstring.ABBRevlength nnis the length of the smallest acceptable abbreviation of the alias that you aredefining. The variable nn is a decimal number between 1 and the length of thefull alias name.DISAbletells CP not activate this alias until you enable it. (For more information aboutenabling aliases, see Usage Note 5.) If omitted, DISABLE is the default.ENabletells CP to immediately activate this alias.IBMclass *tells CP to define aliases for all versions of the specified command orsubcommand. If omitted, IBMCLASS * is the default.IBMclass ctells CP to define an alias for a specific version of the specified command orsubcommand. The variable c can be any 1 of the following:A this is a system-control command to be used by the primary systemoperator.B this is a command for operational control of real devices.C this is a command to alter system storage.D this is a command for system-wide control of spool files.E this is a command to examine system storage.F this is a command for service control of real devices.G this is a general-use command used to control the functions of a virtualmachine.0 (zero) this command has no specific IBM class assigned.UsageNotes1. You can create many aliases for one command, but you cannot create an aliasfor an alias. For example, the CP MSG command is actually an alias for the CPMESSAGE command:┌─────────┐MSG ───► │ MESSAGE │└─────────┘You can create another alias for the MESSAGE command:┌─────────┐MSG ───► │ MESSAGE │ ◄─── TELL└─────────┘But you cannot create an alias for MSG:┌─────────┐TELL ───► MSG ───► │ MESSAGE │└─────────┘2. If you specify the QUERY, QUERY VIRTUAL, or SET operands, you arecreating an alias for a subcommand, not a command. For example, supposeyou created alias TUBE for the CP QUERY VIRTUAL GRAF command. Toinvoke your new alias, you would enter QUERY VIRTUAL TUBE, not QUERYTUBE or just TUBE.82 z/VM: CP Planning and Administration

System Configuration File3. When specifying an alias name, you can use special characters in the name.However, we do not recommend that you use the pattern matching characters (*and %). You can use these characters to define aliases, but they may seemconfusing when you issue other commands that allow you to use the patternmatching characters because CP will interpret the % or * in your alias name asa pattern matching character.4. If you try to define a minimum abbreviation that matches the abbreviation for anexisting command, subcommand, or alias CP rejects your DEFINE statement.For example, if you created a “QUEUE” alias with a minimum abbreviation of 2,CP would reject your QUEUE alias because “QU” is an abbreviation for theQUERY command. In this case, you would need to specify a minimumabbreviation greater than or equal to 4 because the first 3 characters of QUERYand QUEUE are identical.5. If you do not specify the ENABLE operand, the new alias is initially in a disabledstate. To activate an alias after defining it, use the ENABLE COMMAND or CMDstatement (page 126) or command. For more information about the ENABLECOMMAND or CMD command, see the z/VM: CP Commands and UtilitiesReference book.6. To deactivate an alias after defining it, use the DISABLE COMMAND or CMDstatement (page 110) or command. For more information about the DISABLECOMMAND or CMD command, see the z/VM: CP Commands and UtilitiesReference book.7. Once defined, an ALIAS NAME cannot be used again. An ALIAS cannnot bemodified or eliminated. It can only be disabled. Only a SHUTDOWN orRESTART IPL will eliminate an ALIAS.8. For more information about creating an alias, see the z/VM: CP ExitCustomization book.Examples1. To have CP define GOODNIGHT as an alias for the CP SHUTDOWN commandand make it available immediately after initialization, use the following:Define Alias goodnight For shutdown, /* Goodnight, Gracie! */AbbrevLength 5,Enable2. To have CP define TELL as an alias for the IBM class version of the CPMESSAGE command and make it available immediately after initialization, usethe following:Define Alias tell For message, /* Create CP TELL command so users do not */IBMclass 0, /* get confused when they drop out of CMS */Enable3. To have CP define NUKE as an alias for all of the IBM class versions of the CPPURGE command and make it available immediately after initialization, use thefollowing:Define Alias nuke For purge, /* Set it up so that users can “nuke” */IBMclass *, /* instead of “purge” */EnableChapter 6. The System Configuration File 83

System Configuration FileDEFINE COMMAND / CMD Statement►► DEFine COMmandCMDcommandQuery SUBCmd subcommandVirtualSet SUBCmd subcommand(1)ABBRevlengthnn►►AFTer_logonBEFore_logonANYTimeAUDITDISAbleENable EPName name MAC►►PRIVCLASSANYPRIVclasses classes IBMclass c PROC PROT SILENT VMAC VPROT►◄Notes:1 You must specify at least one of these operands. If you specify more than one operand, you canspecify them in any order.PurposeUse the DEFINE COMMAND or CMD statement to define a new CP command or anew version (by IBM class) of an existing CP command on the system duringinitialization.You can also define a new CP command after initialization using the DEFINECOMMAND or CMD commands. For more information, see the z/VM: CPCommands and Utilities Reference.How to SpecifyInclude as many statements as needed; they are optional. You can place DEFINECOMMAND or CMD statements anywhere in the system configuration file. If youspecify more than 1 statement with the same command or subcommand name, CPuses only the first statement. Subsequent DEFINE COMMAND or CMD statementsdo not redefine the command.Operandscommandis the name of the command that you are defining. The variable command is a1-character to 12-character string.Query SUBCmd subcommandtells CP the name of the CP QUERY subcommand that you are defining. Thevariable subcommand is a 1-character to 12-character string.Query Virtual SUBCmd subcommandtells CP the name of the CP QUERY VIRTUAL subcommand that you aredefining. The variable subcommand is a 1-character to 12-character string.Set SUBCmd subcommandtells CP the name of the CP SET subcommand that you are defining. Thevariable subcommand is a 1-character to 12-character string.84 z/VM: CP Planning and Administration

System Configuration FileABBRevlength nnis the length of the smallest acceptable abbreviation of the command orsubcommand that you are defining. The variable nn is a decimal numberbetween 1 and the length of the full command or subcommand name.AFTer_logontells CP that the command version you are defining will only be issued by usersafter they log onto the system. Most CP commands fall into this category. Thedefault is AFTER_LOGON.BEFore_logontells CP that the command you are defining will only be issued by users beforethey log onto the system. For example, the CP DIAL command can only beused before logon.Note: If you specify BEFORE_LOGON, you must specify PRIVCLASSANYbecause CP cannot check privilege classes before a user logs on. Thus,you cannot specify BEFORE_LOGON with the PRIVCLASSES orIBMCLASS operands.ANYTimetells CP that the command version you are defining can be issued by usersboth before and after they log onto the system. For example, many systems letusers issue the CP MESSAGE or MSG commands before and after logon.Note: If you specify ANYTIME, you must specify PRIVCLASSANY because CPcannot check privilege classes before a user logs on. Thus, you cannotspecify ANYTIME with the PRIVCLASSES or IBMCLASS operands.AUDITtells the external security manager (ESM) to audit the command that you aredefining. When you audit a command, the ESM logs each attempt by users toissue this command.DISAbletells CP not to call the entry points and external symbols associated with thisCP command until you enable it. (For more information about enabling CPcommands, see Usage Note 4.) If omitted, DISABLE is the default.ENabletells CP to immediately start calling the entry points and external symbolsassociated with this CP command.EPName nametells CP the name of the entry point that contains the code to process thecommand. The variable name must be a 1-character 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 four special characters ($, #, _, and@), or any combination thereof.Note: If you are defining a new command, you must specify EPNAME. If youare defining a new version of an existing command, specifying EPNAMEis optional. This is because CP only allows one entry point percommand, regardless of how many versions that command has. So,when you define a new version of an existing command, CP alreadyknows the entry point name.Chapter 6. The System Configuration File 85

System Configuration FileThe QUERY and SET commands are the only exceptions, because theyhave subcommands. Note that CP only allows one entry point persubcommand, regardless of how many versions that subcommand has.MACtells CP to enable mandatory access control (MAC) for the command that youare defining. When MAC is enabled for your command, the external securitymanager (ESM) compares the security label of the user who issued yourcommand to the security label of the resource or user that your command willaffect. If you want the ESM to dynamically turn MAC on or off for thiscommand, specify the VMAC operand.PRIVCLASSANYtells CP that users with any privilege class can issue the command that you aredefining.PRIVclasses classestells CP that only users with 1 or more of the specified privilege classes canissue the command that you are defining. The variable classes is 1 or moreprivilege classes in the range A through Z, 1 through 6, or an asterisk (*).Privilege class * indicates all privilege classes (A-Z and 1-6).Notes:1. If you want more than one privilege class, specify your classes in one stringof characters. Do not separate the classes with blank spaces. For example,specify “privclasses abc123”, not “privclasses a b c 1 2 3”.2. If you specify PRIVCLASSES, you must also specify IBMCLASS. You canspecify these 2 operands in any order.IBMclass ctells CP what type of command you are defining. The variable c can be any 1 ofthe following:A this is a system-control command to be used by the primary systemoperator.B this is a command for operational control of real devices.C this is a command to alter system storage.D this is a command for system-wide control of spool files.E this is a command to examine system storage.F this is a command for service control of real devices.G this is a general-use command used to control the functions of a virtualmachine.Note: If you specify IBMCLASS, you must also specify PRIVCLASSES. Youcan specify these 2 operands in any order.PROCtells CP that, after performing the initial privilege class checks, your commandprocessor will be responsible for any further calls to the external securitymanager (ESM) for the command that you are defining.PROTtells the external security manager (ESM) to protect the command that you aredefining. When protection is enabled for your command, the ESM checks anaccess list to ensure that the user who issued your command is authorized todo so. If you want the ESM to dynamically turn protection on or off for yourcommand, specify the VPROT operand.SILENTtells CP that the responses from the command you are defining can be86 z/VM: CP Planning and Administration

System Configuration FileUsageNotessuppressed by invoking it using the SILENTLY command. For more information,see the z/VM: CP Commands and Utilities Reference.Note: Response suppression is supported only for the ATTACH, DETACH, andGIVE commands.VMACgives the external security manager (ESM) the power to dynamically turnmandatory access control (MAC) on or off. If you specify MAC and VMAC forthis command, you are enabling MAC and allowing the external securitymanager (ESM) to dynamically disable MAC. If you specify VMAC and you donot specify MAC for this command, you are disabling MAC and allowing theESM to dynamically enable MAC.VPROTgives the external security manager (ESM the power to dynamically turncommand access protection on or off. If you specify PROT and VPROT for thiscommand, you are enabling protection and allowing the external securitymanager (ESM) to dynamically disable that protection. If you specify VPROTand you do not specify PROT for this command, you are disabling protectionand allowing the ESM to dynamically enable that protection.1. For each existing CP command, CP has at least 1 command table entry block.If the command has more than 1 privilege class, CP has 1 command tableentry block for each version of the command. The only exceptions to this arethe QUERY and SET commands. CP has at least 1 command table entryblock for each QUERY and SET subcommand.2. When you define a new CP command or a new version of an existing CPcommand, you must supply CP with certain information about that command.The amount of information you must supply varies depending on what you aredefining. You must always supply the command (or subcommand) informationand the following table lists any other operands you are required to supplywhen defining a new command or command version.When Adding aNew:You Must Specify:Command EPNAME EPNAMEPRIVCLASSANY - or - PRIVCLASSESIBMCLASSCommand Version PRIVCLASSANY - or - PRIVCLASSESIBMCLASS3. To load the command processing code into CP’s system execution space, usethe CPXLOAD statement (page 76) or command. For more information aboutthe CPXLOAD command, see the z/VM: CP Commands and UtilitiesReference.4. If you do not specify the ENABLE operand, the new CP command is initially ina disabled state. To activate a CP command after defining it, use the ENABLECOMMAND or CMD statement (page 126) or command. For more informationabout the ENABLE COMMAND or CMD command, see the z/VM: CPCommands and Utilities Reference.5. To display the real address of the CP command table entry block, the currentIBM class, and the current privilege class for a specified CP command, use theLOCATE CMDBK command. For more information, see the z/VM: CPCommands and Utilities Reference.Chapter 6. The System Configuration File 87

System Configuration File6. To change the definition of an existing CP command, use the MODIFYCOMMAND or CMD statement (page 165) or command. For more informationabout the MODIFY COMMAND or CMD command, see the z/VM: CPCommands and Utilities Reference.7. Once defined, COMMANDS, SUBCOMMANDS, ALIASES, and DIAGNOSEcodes cannot be DELETED. They can be altered in various appropriate waysbut they remain in existence until a SHUTDOWN or RESTART IPL is done.8. To deactivate a CP command after defining it, use the DISABLE COMMANDor CMD statement (page 110) or command. For more information about theDISABLE COMMAND or CMD command, see the z/VM: CP Commands andUtilities Reference.9. To remove the command processing code from CP’s system execution space,use the CPXUNLOAD command. For more information, see the z/VM: CPCommands and Utilities Reference.10. When specifying a command or subcommand name, you can use specialcharacters in the name. However, we do not recommend that you use thepattern matching characters (* and %). You can use these characters to definecommands, but they may seem confusing when you issue the LOCATECMDBK command. For example, suppose you define 2 new commands:CPU% — to calculate recent CPU busy as a percentage, and CPU1 — tocause some action on real processor number 1. If you issue LOCATE CMDBKCPU%, CP displays information on both CPU% and CPU1, because CPinterprets the % in your LOCATE command to be a pattern matching character.11. If you try to define a minimum abbreviation that matches the abbreviation foran existing command or subcommand, CP rejects your DEFINE statement. Forexample, if you created a “QUEUE” command with a minimum abbreviation of2, CP would reject your QUEUE command because “QU” is an abbreviation forthe CP QUERY command. In this case, you would need to specify a minimumabbreviation greater than or equal to 4 because the first 3 characters ofQUERY and QUEUE are identical.12. For more information about user-defined commands, see the z/VM: CP ExitCustomization book.Examples1. To define a new command, TELL, with:v 3 versions:– Privilege class A, IBM class A, issued after logon– Privilege class B, IBM class B, issued after logon– Any privilege class, no IBM class, issued before and after logon,v No minimum abbreviation, andv The same entry point and syntax as the CP MESSAGE command,use the following statements:Define Cmd tell EPName hcpxmgms, /* Create class A "CP TELL" */IBMClass a, /* command. */PrivClasses aDefine Cmd tell IBMClass b, /* Create class B "CP TELL" */PrivClasses b /* command. */Define Cmd tell AnyTime, /* Create "CP TELL" command for */PrivClassAny /* any class user, to use *//* before or after logon. */88 z/VM: CP Planning and Administration

System Configuration FileImportant Note: Normally, it is not a good practice to define a CP commandthat has the same name as a command, exec, or functionbelonging to another z/VM subsystem. (This newly-definedcommand will interfere with the CMS TELL command.)However, in this case, we thought we would show you anexample of how to create a “synonym” for a common CMScommand that could be used by novice z/VM users when theyaccidentally drop out of their CMS session into CP.2. To define 2 new commands, CONTINUE and RESUME, which behave like theCP BEGIN command, use the following statements:Define Cmd continue AbbrevLength 4, /* Create "CP CONTINUE" */EPName hcpcmcbe, /* command to use instead */IBMClass g, /* of CP BEGIN. */PrivClasses gDefine Cmd resume EPName hcpcmcbe, /* Create "CP RESUME" command */IBMClass g, /* to use instead of CP */PrivClasses g /* BEGIN. */In this example, the CONTINUE and RESUME commands:v Have the same entry point and syntax as the CP BEGIN command,v Are IBM class G,v Are privilege class G, andv Can only be issued after logon.Additionally, the CONTINUE command has a minimum abbreviation of 4(CONT) and the RESUME command has no minimum abbreviation.Chapter 6. The System Configuration File 89

System Configuration FileDEFINE DIAGNOSE Statement►► DEFine DIAGnosediag(1)AUDITDISAbleENableEPNamenameINVARINVXC►►MACPRIVCLASSANYPRIVclasses classes PROC PROT VMAC VPROT►►CHECKR15CHECKR15NOYESNO►◄Notes:1 You must specify at least one of these operands. If you specify more than one operand, you canspecify them in any order.PurposeUse the DEFINE DIAGNOSE statement to define a new DIAGNOSE code on thesystem during initialization.You can also define a new DIAGNOSE code on the system after initialization usingthe DEFINE DIAGNOSE command. For more information, see the z/VM: CPCommands and Utilities Reference.How to SpecifyInclude as many statements as needed; they are optional. You can place DEFINEDIAGNOSE statements anywhere in the system configuration file. If you specifymore than one statement with the same operands, the last operand definitionoverrides any previous specifications.Operandsdiagis the number of the DIAGNOSE code that you are defining. The variable diagis a hexadecimal number between X'0' and X'03FC' and must be a multiple of4. The recommended variable range is a value between X'100' and X'1FC'because that is the range of diagnose codes reserved for customer use. Allother DIAGNOSE code numbers are reserved for IBM use.AUDITtells the external security manager (ESM) to audit the DIAGNOSE code thatyou are defining. When you audit a DIAGNOSE code, the ESM logs eachattempt by users to issue this DIAGNOSE code.DISAbletells CP not to call the entry points and external symbols associated with thisDIAGNOSE code until you enable it. (For more information about enablingDIAGNOSE codes, see Usage Note 3.) If omitted, DISABLE is the default.90 z/VM: CP Planning and Administration

System Configuration FileENabletells CP to immediately start calling the entry points and external symbolsassociated with this DIAGNOSE code.EPName nametells CP the name of the entry point that contains the code to process theDIAGNOSE code that you are defining. The variable name must be a1-character to 8-character string. The first character must be alphabetic or oneof the following special characters: dollar sign ($), number sign (#), underscore(_), or at sign (@). The rest of the string can be alphanumeric characters, thefour special characters ($, #, _, and @), or any combination thereof.INVARtells CP not to process this DIAGNOSE code if the virtual machine issuing theDIAGNOSE code is in host access register mode.INVXCtells CP not to process this DIAGNOSE code if the virtual machine issuing theDIAGNOSE code is in Enterprise System Architecture/Extended Configuration(ESA/XC) mode.MACtells CP to enable mandatory access control (MAC) for the DIAGNOSE codethat you are defining. When MAC is enabled for your DIAGNOSE code, theexternal security manager (ESM) compares the security label of the virtualmachine that issued your DIAGNOSE code to the security label of the resourceor user that your DIAGNOSE code will affect. If you want the ESM todynamically turn MAC on or off for this DIAGNOSE code, specify the VMACoperand.PRIVCLASSANYtells CP that users with any privilege class can issue the DIAGNOSE code thatyou are defining.PRIVclasses classestells CP that only users with 1 or more of the specified privilege classes canissue the DIAGNOSE code that you are defining. The variable classes is 1 ormore privilege classes in the range A through Z, 1 through 6, or an asterisk (*).Privilege class * indicates all privilege classes (A-Z and 1-6).Note: If you want more than one privilege class, specify your classes in onestring of characters. Do not separate the classes with blank spaces. Forexample, specify “privclasses abc123”, not “privclasses a b c 1 2 3”.PROCtells CP that, after performing the initial privilege class checks, your DIAGNOSEcode processor will be responsible for any further calls to the external securitymanager (ESM) for the DIAGNOSE code that you are defining.PROTtells the external security manager (ESM) to protect the DIAGNOSE code thatyou are defining. When protection is enabled for your DIAGNOSE code, theESM checks an access list to ensure that the user who issued your DIAGNOSEcode is authorized to do so. If you want the ESM to dynamically turn protectionon or off for your DIAGNOSE code, specify the VPROT operand.VMACgives the external security manager (ESM) the power to dynamically turnmandatory access control (MAC) on or off.Chapter 6. The System Configuration File 91

System Configuration FileVPROTgives the external security manager (ESM) the power to dynamically turnDIAGNOSE code access protection on or off. If you specify PROT and VPROTfor this command, you are enabling protection and allowing the external securitymanager (ESM) to dynamically disable that protection. If you specify VPROTand you do not specify PROT for this command, you are disabling protectionand allowing the ESM to dynamically enable that protection.CHECKR15 YESCHECKR15 NOindicates whether the diagnose router should check register 15 upon returnfrom the diagnose handler.UsageNotes1. If you do not specify the ENABLE operand, a new DIAGNOSE code is initiallyin a disabled state after being defined. CP treats disabled DIAGNOSE codesas if they were never defined. If you try to use a disabled DIAGNOSE code ina program, CP will give you a program check specification exception.2. To load the DIAGNOSE processing code into CP’s system execution space,use the CPXLOAD statement (page 76) or command. For more informationabout the CPXLOAD command, see the z/VM: CP Commands and UtilitiesReference.3. To activate a new DIAGNOSE code after defining it, use the ENABLEDIAGNOSE statement (page 128) or command. For more information aboutthe ENABLE DIAGNOSE command, see the z/VM: CP Commands and UtilitiesReference.4. To change the definition of an existing DIAGNOSE code, use the MODIFYDIAGNOSE statement (page 169) or command. For more information aboutthe MODIFY DIAGNOSE command, see the z/VM: CP Commands and UtilitiesReference.5. To display information about a DIAGNOSE code (status, entry point name, andprivilege class) after initialization, use the QUERY DIAGNOSE command. Formore information, see the z/VM: CP Commands and Utilities Reference.6. To display the real address of the CP DIAGNOSE code table block for aDIAGNOSE code after initialization, use the LOCATE DGNBK command. Formore information, see the z/VM: CP Commands and Utilities Reference.7. To deactivate a DIAGNOSE code after defining it, use the DISABLEDIAGNOSE statement (page 112) or command. For more information aboutthe DISABLE DIAGNOSE command, see the z/VM: CP Commands andUtilities Reference.8. Once defined, DIAGNOSE codes cannot be deleted. They can be altered invarious appropriate ways, but they remain in existence until a SHUTDOWN orRESTART IPL is done.9. To remove the DIAGNOSE processing code from CP’s system executionspace, use the CPXUNLOAD command. For more information, see the z/VM:CP Commands and Utilities Reference.10. Many external security managers (ESMs) do not support DIAGNOSE codesabove X'03FC'. For this reason, CP does not support DIAGNOSE codes aboveX'03FC'. The DIAGNOSE codes between X'0000' and X'03FC' are divided asfollows:X'0000' to X'00FC'Reserved for IBM useX'0100' to X'01FC'Reserved for customer use92 z/VM: CP Planning and Administration

System Configuration FileX'0200' to X'03FC'Reserved for IBM use.11. When CHECKR15 YES is specified, the diagnose router will check register 15on return from the diagnose handler. If register 15 contains:RC = 0Processing was successful. Complete the guest instruction.RC = 4Processing failed due to a condition which would cause a guestprogram check. Simulate guest program interruption passed in R0.RC = 8Nullify the instruction.RC = 12Present the machine check then nullify the instruction. R2 will containthe address of the MCRBK which will contain the machine checkinformation.RC = 16Generate machine check for processing damage, then go toHCPENDOP to terminate the instruction.RC = 20Present the machine check, then go to HCPENDOP to terminate theinstruction. R2 will contain the address of the MCRBK, which containsmachine check information.RC = 24Issue error message or soft abend for paging I/O error, then nullify theinstruction. R1 has the message or abend number.If a return code is invalid (negative, not a multiple of 4 or too big ( RC > 24 )),then a soft abend will occur.12. For more information about user-defined DIAGNOSE codes, see the z/VM: CPExit Customization book.Examples1. To have CP define a general purpose DIAGNOSE code (X'10C') that will beprocessed by entry point HCPSRC00, use the following:Define Diagnose 10c EPname hcpsrc00,PrivClasses g2. To have CP define DIAGNOSE code X'100' and make it available to users withprivilege classes C or E, use the following:Define Diagnose 100 EPname qwerty,PrivClasses ce3. To have CP define DIAGNOSE code X'18C' and make it available to all users,use the following:Define Diagnose 18c EPname hcpsrc00,PrivClassAnyChapter 6. The System Configuration File 93

DEFINE EXITDEFINE EXIT Statement►► DEFine EXit exit AT entry + offset instructionNORESolveRESolve►◄PARM▼parameterPurposeUse DEFINE EXIT to define a new exit point in CP during initialization.You can also define a new CP exit point after initialization using the DEFINE EXITcommand. For more information, see the z/VM: CP Commands and UtilitiesReference book.How to SpecifyInclude as many statements as needed; they are optional. You can place DEFINEEXIT statements anywhere in the system configuration file. If you specify more thanone statement with the same operands, the last operand definition overrides anyprevious specifications.Operandsexitis the number of the exit point you are defining. This value must be ahexadecimal number between X'0' and X'FFFF'. The recommended value isbetween X'F000' and X'FFFF', because that range is reserved for customer use.All other exit numbers are reserved for IBM, vendor, or general use.AT entry + offset instructionidentifies the location of the exit point you are defining and the instruction that islocated at the exit point. The variable entry must be a 1-character to 8-characterstring. The first character must be alphabetic or one of the following specialcharacters: $ (dollar sign), # (number sign), _ (underscore), or @ (at sign). Therest of the string can be alphabetic or numeric characters, the four specialcharacters ($, #, _, or @), or any combination. The variable offset must be a1-character to 4-character even hexadecimal number between X'0' and X'FFFE'.The variable instruction must be a 2-, 4-, or 6-character hexadecimal number.NORESolvetells CP to resolve the entry points associated with this exit number the firsttime they are called. This is the default.RESolvetells CP to resolve the entry points associated with this exit number when theassociation is first established. Any existing associated entry points are resolvedimmediately.PARM parameteris a list of one or more parameters to be supplied to the exit. Five kinds oftokens can be used to define a parameter:1. Addresses: strings up to eight characters long, consisting of thehexadecimal digits 0 through 9 and A through F.94 z/VM: CP Planning and Administration

DEFINE EXITUsageNotes2. General Registers: strings beginning with G or R, followed by a decimalnumber between 0 and 15 or a hexadecimal digit, designating the contentsof a general register.3. Indirection: a percent sign (%), which causes the contents of an address orthe contents of an address in a register to be used instead of the address orregister contents itself.4. Arithmetic: a plus sign (+) or minus sign (−).5. Displacement: strings of up to four hexadecimal digits.Each parameter string specifies how to combine these tokens to generate aparameter value to be passed to an exit routine. The following is a Backus-Naurdefinition of the syntax of a parameter: ::= | ::= | 0...FFFFFFFF | % ::= | % | ::= + | − | + < or. − ::= G | R ::= 0...15 | 0...9, A...F ::= 0...7FFF1. To load the exit processing code into CP’s system execution space, use theCPXLOAD statement (page 76) or command. For information about theCPXLOAD command, see the z/VM: CP Commands and Utilities Reference.2. To assign entry points or external symbols to an exit point, use theASSOCIATE EXIT statement (page 60) or command. For information about theASSOCIATE EXIT command, see the z/VM: CP Commands and UtilitiesReference.3. To activate a new exit after defining it, use the ENABLE EXITS statement(page 130) or command. For information about the ENABLE EXITS command,see the z/VM: CP Commands and Utilities Reference.4. To change the definition of an existing dynamic exit point, or remove the exitpoint from the system, use the MODIFY EXIT statement (page 172) orcommand. For information about the MODIFY EXIT command, see the z/VM:CP Commands and Utilities Reference.5. To display information about an exit (status, entry point name, andparameters), use the QUERY EXITS command. For more information, see thez/VM: CP Commands and Utilities Reference book.6. Exit numbers are allocated as follows:v X'0000' to X'7FFF' are reserved for IBM use.v X'8000' to X'EFFF' are reserved for vendor and general use.v X'F000' to X'FFFF' are reserved for private customer use.7. The RESOLVE option ensures that the entry names associated with an exitpoint are defined.8. Each exit is passed a parameter list that begins with three standardparameters, as described in the z/VM: CP Exit Customization book. Additionalparameters, specified by the PARM operand, are optional and follow the firstthree in the order in which they are specified.9. Errors (for example, addressing exceptions) during evaluation of user-definedparameters when an exit is being invoked cause CP to abend.10. For more information about user-defined exits, see the z/VM: CP ExitCustomization book.Chapter 6. The System Configuration File 95

DEFINE EXITExamples1. To define an exit that will be entered every time a MESSAGE command isissued, use the following:Define Exit f422 At hcpxmgms + 4 41700000 /* Exit from MESSAGE cmd */Enable Exits f422 /* */2. To define exit X'F800', pass it two additional parameters, and associate it withentry point QWERTY, use the following:Define Exit f800 At hcplog + 7ce 41204028, /* */Parm gl+8% g4 /* */Associate Exit f800 EPname qwerty /* */Enable Exits f800 /* */96 z/VM: CP Planning and Administration

DEFINE LANDEFINE LAN Statement►► DEFine LAN lannameOWNERidOWNERidSYSTEMowneridMAXCONNMAXCONNINFinitemaxconnUNRESTrictedRESTricted►►ACCOUNTingONOFFTYPETYPEHIPERsocketsQDIOIPETHernetIP MFS 16KMFS24K40K64K►►GRANTuserlist(1)►◄Notes:1 You can specify up to 20 UserIDs in the userlist.PurposeUse the DEFINE LAN statement to create a VM LAN segment in the host CPsystem. A VM user can create a virtual network adapter (with the CP DEFINE NICcommand) and connect it to this LAN (with the COUPLE command). Each VM LANsegment is qualified by ownerid and lanname. See the z/VM: CP Commands andUtilities Reference for more information on these commands.The MODIFY LAN statement can be used to add additional users to be included inthe initial access list of a RESTRICTED LAN. For more information, see “MODIFYLAN Statement” on page 175.Operandslannameis the name of the new emulated LAN (Local Area Network). The lanname is asingle token (1-8 alphanumeric characters). The combination of ownerid andlanname will identify this LAN for subsequent commands.OWNERid owneridOWNERid SYSTEMestablishes the owner of the new LAN.MAXCONN INFiniteChapter 6. The System Configuration File 97

DEFINE LANMAXCONN maxconnsets the maximum number of simultaneous adapter connections permitted atany given time. When MAXCONN is specified as INFinite, there is no limit onthe number of connections. Any other value, maxconn, limits the number ofsimultaneous connections to a decimal number in the range of 1–1024(inclusive).If MAXCONN is omitted, the default is MAXCONN INFinite.RESTricted|UNRESTrictedsets the type of authorization required to connect to this LAN. Options are:RESTrictedDefines a LAN with an access list to restrict connections. The LANowner will use the SET LAN command to GRANT or REVOKE accessto specific VM users (by userid). The COUPLE command will only allowauthorized users (those on the access list) to connect a simulatedadapter to a RESTRICTED network.UNRESTrictedDefines a LAN with no access list. When CP is in control of the LAN,connections to this LAN are not restricted by user ID. If an ExternalSecurity Manager (ESM) is in control of the LAN, the ESM may restrictaccess.When neither option is specified, the default is to define an UNRESTrictedLAN.ACCOUNTing ONACCOUNTing OFFAllows a system administrator to control whether accounting records arecreated for the LAN being defined. The default setting may be changed by theVMLAN statement in the system configuration file, and queried by QUERYVMLAN.TYPE HIPERsocketsdefines a VM LAN for use by simulated HiperSockets adapters. AHiperSockets LAN can only accept connections from a simulated HiperSocketsadapter.If TYPE is omitted, the default is TYPE HIPERsockets.MFS 16KMFS 24KMFS 40KMFS 64Ksets the Maximum Frame Size (MFS) for adapters on this network. When anadapter is connected to this LAN, it will adopt the network MFS. The MFS valuedetermines the amount of storage to be allocated for internal structures, andlimits the effective MTU size (Maximum Transmission Unit) for the coupledadapters. For general internet communications, a lower MFS is probably better.However, a high MFS may provide higher data transfer rates for applicationsthat are capable of using larger packet sizes.If MFS is omitted, the default for HiperSockets is 16K. The MFS operand is notvalid for QDIO but the effective MFS is 8992 for a QDIO adapter.TYPE QDIOdefines a VM LAN for use by simulated QDIO adapters. A QDIO LAN can onlyaccept connections from a simulated QDIO adapter.98 z/VM: CP Planning and Administration

DEFINE LANUsageNotesIP|ETHernetindicates whether the transport for the LAN is ETHERNET or IP. An ETHERNETLAN operates at the Layer 2 level of the OSI model.GRANT userlistdefines the initial list of users to be included in the Initial Access list of aRESTRICTED LAN. If the GRANT operand is omitted, the default is to GRANTthe LAN owner. You can specify up to 20 users in this list. If selected, theGRANT operand must be the last operand on this statement.1. A Class B user can invoke the SET LAN and DETACH LAN commands tooperate on a SYSTEM LAN (or any LAN regardless of ownership).2. When a RESTRICTED LAN is defined, the owner is automatically added to theaccess list.3. A LAN segment created by the DEFINE LAN statement will be "persistent" (thatis, it will survive LOGOFF of the owner). It can only be removed by an explicitDETACH LAN command.4. MODIFY LAN cannot be used to change the type of transport. The LAN willneed to be redefined.Examples1. To create a user LAN named QDIO that will allow up to 16 connections, specifythe following:define lan type qdio maxconn 162. To create a system LAN named INEWS that allows up to 100 connections,specify the following:define lan inews ownerid system maxconn 1003. To create a SYSTEM LAN named INEWS that will allow up to 100 connectionsand will not have accounting records created, specify the following:cp define lan inews ownerid system maxconn 100 accounting offChapter 6. The System Configuration File 99

DEFINE VSWITCHDEFINE VSWITCH Statement►►DEFINE VSWITCH switchname(1)RDEVRDEVNONE▼ rdev(2)CONnectDISCONnect►►QUEuestorageQUEuestorage8MnumberMCONTRoller *CONTRolleruserid1IPTimeout 5 NONrouterIPIPTimeout nnn PRIrouterETHernet►►VLANVLANUNAWAREdefvidPORTType ACCESSPORTType TRUNK PORTname ▼portname(3)►◄Notes:1 You can specify the operands in any order, as long as switchname is the first operand specified,and portname is the last operand specified, if applicable.2 You can specify a maximum of 3 real device numbers.3 You can specify a maximum of 3 port names.PurposeUse the DEFINE VSWITCH statement to create a CP system-owned switch (aVirtual Switch) to which virtual machines can connect. Each switch is identified by aswitchname. A z/VM user can create a simulated QDIO Network Interface Card(NIC) and connect it to this switch with the NICDEF directory statement. See“NICDEF Directory Control Statement (Device)” on page 529 for more informationabout the statement.The MODIFY VSWITCH statement can be used to define the initial access list ofthe virtual switch. See “MODIFY VSWITCH Statement” on page 178 for moreinformation.Operandsswitchnameis the name of the new Virtual Switch. The switchname is a single token (1–8alphanumeric characters) that identifies this Virtual Switch for subsequentcommands.RDEV rdevis a real device address to be used to connect the Virtual Switch to a QDIOOSA Express device. Specify each real device number as a 1- to 4-digit100 z/VM: CP Planning and Administration

DEFINE VSWITCHhexadecimal number. You can specify a maximum of three real device numbers.If you specify more than one device number, each must be separated from theothers by at least one blank.Each real device address represents a trio of devices. For example, specifyingRDEV 111 222 333 means that the first devices, 111-113, are used to providethe connection to the real hardware LAN segment. If there is a problem with theconnection, devices 222-224 are used next to provide the connection, and ifthose devices fail to connect, devices 333-335 are used. This feature providesdynamic recovery for OSA Express device failures.RDEV NONE means that the Virtual Switch should not be connected to the realLAN segment.CONnectindicates that the device identified by the RDEV keyword must be activated,and traffic must flow through the device to the real LAN segment.DISCONnectindicates that the device identified by the RDEV keyword must not be activated,and no traffic must flow through the device to the real LAN segment.A Virtual Switch can be functional without a connection to a real LAN segment,and traffic flows only between virtual machines coupled to the Virtual Switch.QUEuestorage numberMindicates the upper limit of the amount of fixed storage CP and Queued DirectI/O Hardware Facility will use for buffers.number defines the maximum number of megabytes of storage that can beconsumed for QDIO queues. Fixed storage is allocated as needed based onnetwork traffic, until the maximum of numberM are allocated.number is a number from 1 to 8. 8M is the default value.CONTRoller * | userid1identifies the z/VM user ID that controls the OSA Express device connected atthe device address identified by rdev. CONTROLLER * means CP selects fromany of the eligible TCP/IP stacks. See Usage Note 3 on page 102 for moreinformation about the function of a controller.If you specify multiple real devices on the RDEV keyword, specifyCONTROLLER *, or allow it to default. The controller functions are then spreadacross multiple z/VM TCP/IP stacks, providing more flexibility in case of afailure.IP|ETHernetindicates whether the transport for the Virtual Switch is ETHERNET or IP. AnETHERNET Virtual Switch operates at the Layer 2 level of the OSI model whilean IP Virtual Switch operates at Layer 3.IPTimeout nnnindicates the length of time in minutes that a remote IP address table entryremains in the IP address table for the Virtual Switch.nnn is a number from 1 to 120. 5 minutes is the default value.NONrouterindicates that the OSA Express device identified by the RDEV keyword will notact as a router to the Virtual Switch. If a datagram is received at this device foran unknown IP address, the datagram will be discarded. This is the default.Chapter 6. The System Configuration File 101

DEFINE VSWITCHUsageNotesPRIrouterindicates that the OSA Express device identified by the RDEV keyword will actas a primary router to the Virtual Switch. If a datagram is received at this devicefor an unknown IP address, the datagram will be passed to the Virtual Switch.VLAN UNAWAREindicates the Virtual Switch does not support IEEE standard 802.lQ. All framesflow within the Virtual Switch regardless of presence or absence of Virtual LocalArea Network (VLAN) tags. Any VLAN tags present in the frames will beignored within the switch (however the guest hosts may perform VLAN filteringat the virtual NIC level). This is the default.VLAN defvidDefines the Virtual Switch as a VLAN-aware switch supporting IEEE standard802.lQ. The defvid defines the default VLAN ID to be associated with untaggedframes received and transmitted by the Virtual Switch. It is a number from 1 to4094. A VLAN-aware virtual switch provides VLAN controls at the switch level(with SET VSWITCH GRANT VLAN and PORTTYPE commands) that may notbe overridden by a guest host.PORTType ACCESSdefines the default porttype attribute for guests authorized for the Virtual Switch.For PORTTYPE ACCESS, the guest is unaware of VLAN IDs and sends andreceives only untagged traffic.PORTType TRUNKdefines the default porttype attribute for guests authorized for the Virtual Switch.For PORTTYPE TRUNK, the guest is VLAN aware and sends and receivestagged traffic for those VLANs to which the guest is authorized. If the guest isalso authorized to the defvid, untagged traffic sent or received by the guest isassociated with the default VLAN ID (defvid) of the Virtual Switch..PORTname portnameis a 1- to 8-character name that identifies the OSA Express adapter. You canspecify a maximum of three port names. Multiple port names are used whendifferent port names are needed for the multiple rdevs specified on the RDEVoperand. See Usage Note 9 on page 103 for more information.1. The DEFINE VSWITCH statement creates a Virtual Switch. The MODIFYVSWITCH statement can be used to modify a Virtual Switch by authorizingusers to use the switch. Authorization to a virtual switch may also be providedby an External Security Manager.2. Accounting is set for the switch based on the default accounting state as setby the SET VMLAN ACCOUNT SYSTEM command or configuration statement.If accounting is turned on after the virtual switch is defined, the virtual switchwill need to be redefined for accounting to take effect.3. A Virtual Switch’s connection to a real hardware LAN segment through one ofthe rdev values specified on the RDEV operand is not operational until aneligible TCP/IP stack is selected to be the controller for the OSA Expressdevice. CP selects an eligible TCP/IP stack to be the controller by either:v If CONTROLLER userid1 is specified on the DEFINE VSWITCH commandor System Configuration statement, only userid1 is selected.v If CONTROLLER * is specified or allowed to default, CP selects from anyeligible TCP/IP stack.A TCP/IP stack becomes eligible when:102 z/VM: CP Planning and Administration

DEFINE VSWITCHv An IUCV *VSWITCH statement is included in its CP directory entry.v The TCP/IP VSWITCH CONTROLLER statement is coded, and hasdefaulted to be ON or is explicitly set to ON in the TCP/IP configuration fileor through an OBEYFILE command.v The stack has completed initialization.v The stack has virtual device addresses available for CP to attach the controldevice.The virtual address range used by CP is specified in the VSWITCHCONTROLLER TCP/IP configuration statement. If no VDEV range isspecified, CP uses the virtual device address (vdev) that matches the rdevaddress specified on the DEFINE VSWITCH or SET VSWITCH command.See z/VM: TCP/IP Planning and Customization for more information aboutthe VSWITCH CONTROLLER statement.Note: Do not code DEVICE and LINK TCP/IP configuration statements forthe device. Do not attach the device to a TCP/IP controller virtualmachine. These steps are handled by DEFINE VSWITCH processingwhen a controller is selected.If an eligible stack is not found, or none of the rdevs are operational, youreceive a message, and the Virtual Switch operates in a local LANenvironment.4. The IP transport type is IPv4 only. In order to support IPv6 through the VirtualSwitch RDEV, the ETHERNET transport is required.5. MODIFY VSWITCH cannot be used to change the type of transport. TheVirtual Switch will need to be redefined.6. Use the QUERY CONTROLLER command output to find the TCP/IP stack thatis the Virtual Switch controller. Use the QUERY VSWITCH command to displayinformation about the Virtual Switch.7. CP manages the devices used to control a Virtual Switch’s connection to a realLAN segment through an OSA Express device. CP attaches the devices to thez/VM TCP/IP virtual machine. CP also defines a device of type VSWITCH-OSDto the TCP/IP stack, concatenating switchname with vdev and ″DEV″ to formthe device name and switchname with vdev and ″LINK″ to form the link name.These names appear in the TCP/IP query and trace information.DEVICE and LINK statements must not be included in the TCP/IPconfiguration file for these devices.Note: Adapter number 0 (link number 0) will be used when attaching the OSAExpress device to the controller.8. Multiple real devices and portnames can be specified on the RDEV andPORTNAME operands. This feature allows failover to an alternate real devicein the event of a failure with the current OSA-Express device. All real devicesspecified must be active and connected to the same hardware LAN in order toeffectively and dynamically failover to an alternate device. In addition, thealternate devices must be defined on separate CHPIDs. If your OSA-Expressdevice requires a portname, specify one portname for each real devicenumber.9. When the real device identified by one of the rdevs is started, TCP/IP assignsthe port name as the hardware adapter name. If an adapter name was alreadyassigned by a previous connection, then the port name must be the same asassigned by any other connection in order to share the adapter. This includessharing the OSA Express adapter with this logical partition or all otherpartitions.Chapter 6. The System Configuration File 103

DEFINE VSWITCHThe PORTNAME operand is optional. However, some levels of the OSAExpress adapters require that the PORTNAME operand is specified. Whensuch an adapter is in use and the PORTNAME operand is omitted, an errormessage is displayed during switch initialization.If the device is already started, you must stop it by issuing the SET VSWITCHswitchname DISCONNECT command before changing the port name.10. PRIROUTER is required only when IP forwarding (routing) nodes will becoupled to the switch. Router nodes provide connectivity for their LANsegments (remote nodes) through their switch connection. When Router nodesare deployed, their switch connection must be configured as PRIROUTER. Inaddition to this, the switch itself must also be configured as PRIROUTER tothe OSA-E adapter. This will insure delivery of datagrams destined for LANsegments that are connected through routers coupled to a switch. Only oneconnection on each OSA-Express card can be designated as PRIROUTER. Ifthe switch is successful in establishing PRIROUTER on the OSA-Expresscard, no other node (or switch) sharing the same OSA-Express card will beable to act as PRIROUTER. If another connection has already beenestablished as PRIROUTER, the switch will be left with NONROUTER status(which is reflected in the QUERY VSWITCH response).11. NONROUTER is the default mode for the switch. Every node is directlycoupled to the switch and the associated IP destinations are registered with theOSA Express connection. This is the most efficient way to use the VirtualSwitch. In this mode, packets with an unrecognized IP destination areautomatically sent out through the switch connection.Examples1. To define a switch named BIGANG that connects to a real LAN through devicefd00, specify the following:define vswitch bigang rdev fd00104 z/VM: CP Planning and Administration

DEVICESDEVICES Statement►► DEVICes ▼ ACCEPTed▼NOTACCEPTedASSIGN_at_iplNOASSIGN_at_iplDYNamic_i/oNOTDYNamic_i/oINITialized_at_iplNOTINITialized_at_iplOFFLine_at_iplONLine_at_iplSCMeasuredNOTSCMeasuredSENSedNOTSENSedSHAREdNOTSHAREdTHROTtledNOTTHROTtledrdevrdev-rdev►◄PurposeUse the DEVICES statement to tell CP how to handle specific devices duringinitialization. You can tell CP whether to:v Accept (and build real device blocks for) specified devicesv Allow dynamic changes for specified devicesv Initialize the specified devices during IPLv Measure the subchannels for specified devicesv Assign the tape drive to the system when the device is being brought online.v Use the information returned from a sense ID request to help define the devicev Share DASD between independent operating systemsv Limit (throttle) the I/O rate for specified devices.How to SpecifyInclude as many statements as needed; they are optional. You can place DEVICESstatements anywhere in the system configuration file. If you specify more than onestatement with the same operands, the last operand definition overrides anyprevious specifications.ParametersACCEPTedtells CP to accept the specified device or devices.rdevrdev-rdevis the real device number of the device or devices that you are affecting. Thevariable rdev must be a hexadecimal number between X'0000' and X'FFFF'.You can specify a single device, a range of devices, or any combination thereof.Chapter 6. The System Configuration File 105

DEVICESNOTACCEPTedtells CP not to accept the specified device or devices.Note: CP ignores any devices you specify on the NOTACCEPTED operand,even if you have explicitly defined those devices using RDEVICEstatements in the system configuration file or using RDEVICEmacroinstructions in HCPRIO.ASSIGN_at_ipltells CP to assign the tape drive to the system when the device is being broughtonline.NOASSIGN_at_ipltells CP not to assign the tape drive when the device is being brought online.DYNamic_i/otells CP to allow dynamic I/O changes on the specified device or devices.Note: If you want to allow dynamic I/O changes on any devices, do not forgetto specify FEATURES ENABLE DYNAMIC_I/O in your systemconfiguration file. This FEATURES operand enables or disables dynamicI/O changes for your system’s processor. So, if you do not enabledynamic I/O changes on the processor, CP will not let you makedynamic I/O changes on any individual device or devices.NOTDYNamic_i/otells CP not to allow dynamic I/O changes on the specified device or devices.INITialized_at_ipltells CP to initialize the specified device or devices during IPL.NOTINITialized_at_ipltells CP not to initialize the specified device or devices during IPL.Note: The last two operands are functionally equivalent to the ONLINE_AT_IPLand OFFLINE_AT_IPL operands respectively.OFFLine_at_ipltells CP not to initialize the specified device or devices at IPL.Note: Due to the fact that Open Systems Adapter (OSA) devices may not beready to come online until after system IPL has completed, thisstatement will not always work for OSA devices.ONLine_at_ipltells CP to initialize the specified device or devices at IPL.SCMeasuredtells CP to collect subchannel measurement data for the subchannels of thespecified device or devices.NOTSCMeasuredtells CP not to collect subchannel measurement data for the subchannels of thespecified device or devices.SENSedtells CP to use the information returned from a sense ID request to determinethe device class or type.NOTSENSedtells CP not to use the information returned from a sense ID request todetermine the device class or type.106 z/VM: CP Planning and Administration

DEVICESUsageNotesSHAREdtells CP that the specified DASD device or devices will be shared betweenindependent operating systems.NOTSHAREdtells CP that the specified DASD device or devices will not be shared with anyother independent operating system.THROTtledtells CP to limit (throttle) the rate of I/O coming from the specified device ordevices.NOTTHROTtledtells CP not to limit (throttle) the I/O rate of the specified device or devices.1. If an IODF statement is defined in the system configuration file with the osconfigparameter specified, then the software I/O configuration will be controlled byHCD. In this case, the following DEVICES statements are ignored if they arespecified:v DEVICES ACCEPTEDv DEVICES NOTACCEPTEDv DEVICES DYNAMIN_I/Ov DEVICES NOTDYNAMIC_I/Ov DEVICES OFFLINE_AT_IPLv DEVICES ONLINE_AT_IPLv DEVICES SENSEDv DEVICES NOTSENSEDv DEVICES SHAREDv DEVICES NOTSHAREDRefer to “IODF Statement” on page 158 for more information.2. If you do not specify the DEVICES statement in the system configuration file,the defaults that CP uses depend on what is specified on the SYSOPTSmacroinstruction in the HCPSYS ASSEMBLE file.v If the SYSOPTS setting is SENSE=YES (the default), CP will:– Accept all devices,– Allow dynamic changes on all devices (if you specified FEATURESENABLE DYNAMIC_I/O),– Initialize all devices,– Measure all devices,– Sense the characteristics of all devices,– Not share any DASD devices,– Not throttle any devices, and– Not assign any tape drives to CP at IPL.For any devices that you have not explicitly defined with the RDEVICEstatement in the system configuration file or with the RDEVICEmacroinstruction in HCPRIO, CP will sense the device, if possible, anddynamically build an RDEV for it.v If the SYSOPTS setting is SENSE=NO, CP will accept, initialize, measure,and bring online only those devices that you explicitly define with RDEVICEstatements or macroinstructions. CP will not throttle or allow dynamicChapter 6. The System Configuration File 107

DEVICESchanges on any of these devices. CP will share DASD devices only if youspecify the SHARED operand on the RDEVICE statement or macroinstructionfor that DASD. CP ignores all other devices.Also, if you specify the wrong device type on the RDEVICE statement ormacroinstruction, CP will not bring the device online because of conflictingdevice information. That is, if you define a 3420 tape drive and the device isreally a 3480 tape drive, CP will not bring the device online. If you specify thewrong device class, CP will not bring the device online. That is, if you definea tape drive and the device is really a DASD, CP will not bring the deviceonline.For more information about the RDEVICE statement, see page 188. For moreinformation about the RDEVICE macroinstruction, see page 705.3. To allow or prevent dynamic changes after IPL, use the SET DYNAMIC_I/Ocommand. For more information, see the z/VM: CP Commands and UtilitiesReference.4. To start or stop subchannel measuring after IPL, use the SET SCMEASUREcommand. For more information, see the z/VM: CP Commands and UtilitiesReference.5. You can also share DASD devices between independent operating systems byspecifying the SHARED operand on the SET RDEVICE command, by issuingthe SET SHARED command, or by specifying the SHARED operand on theRDEVICE statement or macroinstruction. For more information about the SETRDEVICE command, see the z/VM: CP Commands and Utilities Reference. Formore information about the RDEVICE statement or macroinstruction, see page195 or page 745, respectively.6. To define new devices after IPL, use the SET RDEVICE command. For moreinformation, see the z/VM: CP Commands and Utilities Reference.7. For each category (ACCEPTED, DYNAMIC_I/O, INITIALIZED_AT_IPL,MEASURED, ONLINE_AT_IPL, SENSED, SHARED, THROTTLED, andASSIGN_AT_IPL), CP processes the information on the DEVICES statementsequentially. If you specify more than one DEVICES statement or you overlapranges of real device numbers, CP uses the last specification. For example, ifyou specify:DEVICES NotAccepted 1000-1fff,Accepted 1800-18ff,NotAccepted 1820-182fCP accepts devices at address 1800 through 181F and at address 1830through 18FF. CP does not accept devices at address 1000 through 17FF, 1820through 182F, and 1900 through 1FFF.Note: The INITIALIZED_AT_IPL and ONLINE_AT_IPL operands performexactly the same function. You can use these two operands (and theirnegative counterparts, NOTINITIALIZED_AT_IPL and OFFLINE_AT_IPL)in any combination. If you overlap ranges of real device numbers, CPuses the last specification.Examples1. To have CP:v Not accept a group of terminals, except for one,v Allow dynamic I/O changes on all devices, except for 1905 through 1943.v Initialize all devices, except 8E0 through 8EF,v Measure all devices, except DASD 2F04,108 z/VM: CP Planning and Administration

DEVICESv Leave a group of disks offline or not initialized,v Not sense a group of 3705 devices,v Share a string of DASDs at 1100 through 114F,v Throttle the I/O rate to a shared database at 460 through 48F, andv Assign tape drive 181 to CP,use the following DEVICES statement:Devices NotAccepted 2f12-2f22, /* Don’t accept terminals */Accepted 2f1f, /* ... except David’s */Dynamic_I/O 0000-ffff, /* Dynamic changes are ok *//* on these devices. */NotDynamic_I/O 1905-1943, /* No changes allowed on *//* these ... ever! */Initialized_at_IPL 0000-ffff, /* Initialize everything...*/NotInitialized_at_IPL 08e0-08ef, /* ... almost. */SCMeasured 0000-ffff, /* Measure everything ... */NotSCMeasured 2f04, /* ... almost. */Offline_at_IPL 0a00-0aff, /* Backup DASD string */NotSensed 0100-01ff, /* Don’t sense these 3705s */NotShared 0000-ffff, /* Don’t share anything! */Shared 1100-114f, /* ... except these. */Throttled 0460-048f Rate 20 /* Limit the I/O on the *//* shared database DASD */Assign_at_ipl 181 /* Assign 181 to CP. */Chapter 6. The System Configuration File 109

DISABLE COMMAND/CMDDISABLE COMMAND / CMD Statement►► DISAble COMmandCMDcommandQuery SUBCmd subcommandVirtualSet SUBCmd subcommandIBMclass *IBMclassc►◄PurposeUse the DISABLE COMMAND or CMD statement to prevent CP from processingrequests for the specified CP command during and after initialization.You can also prevent processing of CP commands after initialization using theDISABLE COMMAND or CMD commands. For more information, see the z/VM: CPCommands and Utilities Reference.How to SpecifyInclude as many statements as needed; they are optional. You can place DISABLECOMMAND or CMD statements anywhere in the system configuration file. If youspecify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.Operandscommandis the name of the command that you are disabling. The variable command is a1-character to 12-character alphanumeric string.Query SUBCmd subcommandtells CP the name of the CP QUERY subcommand that you are disabling. Thevariable subcommand is a 1-character to 12-character alphanumeric string.Query Virtual SUBCmd subcommandtells CP the name of the CP QUERY VIRTUAL subcommand that you aredisabling. The variable subcommand is a 1-character to 12-characteralphanumeric string.Set SUBCmd subcommandtells CP the name of the CP SET subcommand that you are disabling. Thevariable subcommand is a 1-character to 12-character alphanumeric string.IBMclass *tells CP to disable all versions of the specified command or subcommand. Ifomitted, IBMCLASS * is the default.IBMclass ctells CP to disable a specific version of the specified command or subcommand.The variable c can be any 1 of the following:A this is a system-control command to be used by the primary systemoperator.B this is a command for operational control of real devices.C this is a command to alter system storage.D this is a command for system-wide control of spool files.E this is a command to examine system storage.110 z/VM: CP Planning and Administration

DISABLE COMMAND/CMDUsageNotesF this is a command for service control of real devices.G this is a general-use command used to control the functions of a virtualmachine.0 (zero) this command has no specific IBM class assigned.1. To remove the command processing code from CP’s system execution space,use the CPXUNLOAD command. For more information, see the z/VM: CPCommands and Utilities Reference.2. To load the command processing code into CP’s system execution space, usethe CPXLOAD statement (page 76) or command. For more information aboutthe CPXLOAD command, see the z/VM: CP Commands and Utilities Reference.3. To deactivate a CP command while defining it, use the DISABLE operand of theDEFINE COMMAND or CMD statement (page 84) or command. For moreinformation about the DEFINE COMMAND or CMD command, see the z/VM:CP Commands and Utilities Reference.4. To activate a CP command:v While defining it, use the ENABLE operand of the DEFINE COMMAND orCMD statement (page 84) or command.v After defining it, use the ENABLE COMMAND or CMD statement (page 126)or command.For more information about the DEFINE or ENABLE COMMAND or CMDcommands, see the z/VM: CP Commands and Utilities Reference.5. To change the definition of an existing CP command, use the MODIFYCOMMAND or CMD statement (page 165) or command. For more informationabout the MODIFY COMMAND or CMD command, see the z/VM: CPCommands and Utilities Reference.6. Once defined, COMMANDS, SUBCOMMANDS, and ALIASES cannot bedeleted. They can be altered in various appropriate ways, but they remain inexistence until a SHUTDOWN or RESTART IPL is done.7. To display the real address of the CP command table entry block, the currentIBM class, and the current privilege class for a specified CP command, use theLOCATE CMDBK command. For more information, see the z/VM: CPCommands and Utilities Reference.8. For more information about enabling and disabling commands, see the z/VM:CP Exit Customization book.Examples1. To disable the class D version of the CP PURGE command, but not the class Gversion of the CP PURGE command, use the following:Disable Command purge IBMclass d2. To disable the CP SHUTDOWN command, use the following:Disable Command shutdownChapter 6. The System Configuration File 111

DISABLE DIAGNOSEDISABLE DIAGNOSE Statement►► DISAble DIAGnoseALL►◄▼diagdiag1-diag2PurposeUse the DISABLE DIAGNOSE statement to prevent CP from processing requestsfor one or more locally-developed DIAGNOSE codes during and after initialization.You can also prevent processing of locally-developed DIAGNOSE codes afterinitialization using the DISABLE DIAGNOSE command. For more information, seethe z/VM: CP Commands and Utilities Reference.How to SpecifyInclude as many statements as needed; they are optional. You can place DISABLEDIAGNOSE statements anywhere in the system configuration file. If you specifymore than one statement with the same operands, the last operand definitionoverrides any previous specifications.OperandsALLtells CP to disable all existing DIAGNOSE codes.Note: This operand disables all DIAGNOSE codes: the locally-defined ones,the IBM-supplied ones, and any supplied by third-party software vendors.diagdiag1-diag2is the number of the DIAGNOSE code that you are disabling. Each diag mustbe a hexadecimal number between X'0000' and X'03FC' and must be a multipleof 4. You can specify a single DIAGNOSE code, a range of DIAGNOSE codes,or any combination thereof.UsageNotes1. CP treats disabled DIAGNOSE codes as if they were never defined. If you tryto use a disabled DIAGNOSE code in a program, CP will give you a programcheck specification exception.2. To load the DIAGNOSE processing code into CP’s system execution space,use the CPXLOAD statement (page 76) or command. For more informationabout the CPXLOAD command, see the z/VM: CP Commands and UtilitiesReference.3. To define a new DIAGNOSE code, use the DEFINE DIAGNOSE statement(page 90) or command. For more information about the DEFINE DIAGNOSEcommand, see the z/VM: CP Commands and Utilities Reference.112 z/VM: CP Planning and Administration

DISABLE DIAGNOSENote: Unless you specify the ENABLE operand of the DEFINE DIAGNOSEstatement or command, the new DIAGNOSE code is initially in adisabled state after being defined.4. To activate a new DIAGNOSE code after defining it, use the ENABLEDIAGNOSE statement (page 128) or command. For more information aboutthe ENABLE DIAGNOSE command, see the z/VM: CP Commands and UtilitiesReference.5. To change the definition of an existing DIAGNOSE code, use the MODIFYDIAGNOSE statement (page 169) or command. For more information aboutthe MODIFY DIAGNOSE command, see the z/VM: CP Commands and UtilitiesReference.6. To display information about a DIAGNOSE code (status, entry point name, andprivilege class) after initialization, use the QUERY DIAGNOSE command. Formore information, see the z/VM: CP Commands and Utilities Reference.7. To display the real address of the CP DIAGNOSE code table block for aDIAGNOSE code after initialization, use the LOCATE DGNBK command. Formore information, see the z/VM: CP Commands and Utilities Reference.8. Once defined, DIAGNOSE codes cannot be deleted. They can be altered invarious appropriate ways, but they remain in existence until a SHUTDOWN orRESTART IPL is done.9. To remove the DIAGNOSE processing code from CP’s system executionspace, use the CPXUNLOAD command. For more information, see the z/VM:CP Commands and Utilities Reference.10. Many external security managers (ESMs) do not support DIAGNOSE codesabove X'03FC'. For this reason, CP does not support DIAGNOSE codes aboveX'03FC'. The DIAGNOSE codes between X'0000' and X'03FC' are divided asfollows:X'0000' to X'00FC'Reserved for IBM useX'0100' to X'01FC'Reserved for customer useX'0200' to X'03FC'Reserved for IBM use.11. For more information about user-defined DIAGNOSE codes, see the z/VM: CPExit Customization book.Examples1. To have CP disable DIAGNOSE code X'100', use the following:Disable Diagnose 100After initialization, any virtual machine that issues DIAGNOSE code X'100'receives a program specification exception in that virtual machine.2. To have CP disable all DIAGNOSE codes on your system, use the following:Disable Diagnose All3. To have CP disable all locally-defined DIAGNOSE codes, use the following:Disable Diagnose 100-1fc4. To have CP disable all locally-defined DIAGNOSE codes except DIAGNOSEcode X'01F0', use the following:Disable Diagnose 100-iec if4-1fcChapter 6. The System Configuration File 113

DISABLE EXITSDISABLE EXITS Statement►► DISAble EXitsALL►◄▼exitexit1-exit2PurposeUse the DISABLE EXITS statement to prevent CP from calling all entry points andexternal symbols associated with one or more exit points during and afterinitialization.You can also prevent CP from calling one or more exit points after initializationusing the DISABLE EXITS command. For more information, see the z/VM: CPCommands and Utilities Reference.How to SpecifyInclude as many statements as needed; they are optional. You can place DISABLEEXITS statements anywhere in the system configuration file. If you specify morethan one statement with the same operands, the last operand definition overridesany previous specifications.OperandsALLtells CP to disable all existing CP exit points.exitexit1-exit2is the number of the exit point (or exit points) that you do not want CP to use.Each exit must be a hexadecimal number between X'0000' and X'FFFF'. Youcan specify a single exit point number, a range of exit point numbers, or anycombination thereof.UsageNotes1. To load the exit point code into CP’s system execution space, use theCPXLOAD statement (page 76) or command. For more information about theCPXLOAD command, see the z/VM: CP Commands and Utilities Reference.2. To add to, change, or replace the list of entry points and external symbolsassociated with an exit point and to enable or disable that exit point, use theASSOCIATE EXIT statement (page 60) or command. For more informationabout the ASSOCIATE EXIT command, see the z/VM: CP Commands andUtilities Reference.3. To activate an exit point after defining it, use the ENABLE EXITS statement(page 130) or command. For more information about the ENABLE EXITScommand, see the z/VM: CP Commands and Utilities Reference.4. To display status and usage statistics information about a specific exit pointafter initialization, use the QUERY EXITS command. For more information, seethe z/VM: CP Commands and Utilities Reference.114 z/VM: CP Planning and Administration

DISABLE EXITS5. To display the real address of the CP exit block for a specific exit point, usethe LOCATE XITBK command. For more information, see the z/VM: CPCommands and Utilities Reference.6. To display the real address of the CP indirect call locator block for a specificexit point, use the LOCATE ICLBK command. For more information, see thez/VM: CP Commands and Utilities Reference.7. To change the definition of an existing dynamic exit point, or remove the exitpoint from the system, use the MODIFY EXIT statement (page 172) orcommand. For more information about the MODIFY EXIT command, see thez/VM: CP Commands and Utilities Reference.8. To remove the exit point code from CP’s system execution space, use theCPXUNLOAD command. For more information, see the z/VM: CP Commandsand Utilities Reference.9. After processing a DISABLE EXITS statement (or command), CP updates thestatus of the exit point in its CP exit block, but does not erase the CP exitblock. CP will not erase any CP exit blocks until the next IPL.10. For more information about user-defined exit points, see the z/VM: CP ExitCustomization book.Examples1. To stop CP from calling the entry points and external symbols associated withCP Exits 1, 2, 3, 4, and 6, use the following:Disable Exits 1-4 62. To stop CP from calling the entry points and external symbols associated withall CP exit points, use the following:Disable Exits AllChapter 6. The System Configuration File 115

DISTRIBUTEDISTRIBUTE StatementFormat►► DISTRIBUTE IUCVNOTOLERATEYES MAXimum 16MAXimumxxxx►◄PurposeUse the DISTRIBUTE statement to specify distribution features for the local system.InternalRepresentationInclude as many statements as needed; they are optional. You can placeDISTRIBUTE statements anywhere in the system configuration file. If you specifymore than one statement with the same operands, the last operand definitionoverrides any previous specifications.ParametersIUCVindicates that IUCV distribution option is to be set.NOindicates that no Distributed IUCV traffic will be allowed to or from othernodes within the ISFC collection. This is the default.TOLERATEindicates that Distributed IUCV is allowed to or from any other node in theISFC collection. However, IUCV traffic will only leave the local node if theapplication specifies the target system name.YESindicates that this node participates fully in Distributed IUCV across theentire ISFC collection. This means that target searches will be done to theISFC collection instead of the default of just the local system.MAXimum xxxxindicates the number of megabytes of the largest distributed IUCV send allowedfrom the host. xxxx is a value between 1 and 1024. The default maximum is 16.Note: It is recommended that all nodes in a CS collection have the same valuespecified for MAXIMUM because the maximum value is enforced only bythe originating node.Usage1. When TOLERATE is specified, IUCV will be distributed via the TARGETparameter of the IUCV macro. When YES is specified, IUCV will first attempt tosatisfy a CONNECT on the local system and then will attempt to locate thetarget on a system within the CS collection. The only exception is if theapplication specifies that the CONNECT must be satisfied either locally or on aparticular target system.116 z/VM: CP Planning and Administration

DISTRIBUTE2. IUCV applications will behave the same in a distributed environment as they doon a local system with the following exceptions:v PURGE and REJECT will only be honored on the local system. Once amessage is sent to the other system it is considered to be delivered.v The PRIORITY and MSGLIMIT directory specifications must be present onboth systems if they are to be honored.v The default maximum data length is 16M per message. The maximum can bealtered via the SYSTEM CONFIG file by using the DISTRIBUTE statement.Chapter 6. The System Configuration File 117

DRAIN (Disk)DRAIN (Disk) Statement►► DRain DASd ▼ rdevrdev-rdevVOLid volidALL▼LInksPAgeSPolSPoolTDiskTDskTEmpdisk►◄PurposeUse the DRAIN statement to stop new operations on specified DASD. You can stopCP from:v Writing pages to the specified device or devicesv Letting users link to minidisks on the specified device or devicesv Allocating spool space on the specified device or devicesv Allocating temporary minidisks on the specified device or devices.How to SpecifyInclude as many statements as needed; they are optional. You can place DRAINDASD statements anywhere in the system configuration file, but you must placeDRAIN VOLID statements after the CP_OWNED statement (page 73) with thesame volume serial number.If you specify the same device on more than one statement, CP keeps a cumulativelist of operations. For example, if you have one statement indicating that you do notwant paging on a device and another statement indicating that you do not wanttemporary disks allocated on that same device, CP prevents paging and temporarydisk allocation on that device. The second statement does not overrule the firststatement.OperandsDASd rdevis the real device number of the DASD you want drained. The variable rdev is ahexadecimal number between X'0000' and X'FFFF'.DASd rdev-rdevis a range of real device numbers specifying the DASD you want drained. Eachrdev is a hexadecimal number between X'0000' and X'FFFF'.VOLid volidis the volume serial number of the volume you want drained.ALLtells CP not to allow any new operations on this device, including:v Writing pages during page-out118 z/VM: CP Planning and Administration

DRAIN (Disk)UsageNotesv Allowing minidisk linkingv Allocating space for new spool records.v Allocating temporary disk space.LInkstells CP not to allow users to link to minidisks on this device.PAgetells CP not to write pages to this device during page-out operations.SPolSPooltells CP not to allocate space on this device for new spool records.TDiskTDskTEmpdisktells CP not to allocate temporary disk space on this device.1. When you drain a DASD (or one of its operations), CP makes the DASD appearto be full. Because the DASD appears to be full, CP tries to allocate from thenext appropriate device, if possible. Issuing DRAIN (Disk) or START (Disk)commands does not cause CP to adjust the system counters. For example, ifyou are draining spool space on a DASD, CP does not adjust the amount ofspool space that is unused and available to zero, even though, logically, thereappears to be no available spool space on that DASD. Issuing a CP DETACHcommand adjusts the appropriate system counters to account for the spacebeing removed from the system. For more information about the DRAIN (Disk),START (Disk), or DETACH commands, see the z/VM: CP Commands andUtilities Reference.2. You can attach a draining DASD to a virtual machine.3. Issuing CP ATTACH and DETACH commands does not affect the DRAININGstatus indicators, so you can drain a DASD before attaching it to the system.For more information about the CP ATTACH and DETACH commands, see thez/VM: CP Commands and Utilities Reference.4. CP processes the system configuration file during an IPL, which means CP hasnot attached any volumes to the system when processing your DRAINstatements. Therefore, when you specify a DRAIN VOLID statement, you canonly use volumes that were previously specified in the system configuration fileon CP_OWNED statements.5. Use the CP START (Disk) command or statement to tell CP to resume normalallocation on the device and use the QUERY DASD DRAINING command to getinformation about the draining status of your DASD. For more information aboutthe START (Disk) or QUERY DASD DRAINING commands, see the z/VM: CPCommands and Utilities Reference. For more information about the START(Disk) statement, see page 220.ExamplesUse the DRAIN and START statements shown in Figure 3 on page 120 to have CP:v Drain all operations on all DASD between X'0700' and X'07FF',v Allow users to link to minidisks on DASD X'0700', andv Ensure that CP can write pages to the CP-owned paging pack (SYSPG1), ifsomeone moves that DASD to one of the addresses that are draining (X'0700'through X'07FF')Chapter 6. The System Configuration File 119

DRAIN (Disk)Drain DASD 0700-07ff All /* Do not allow any activity onthese DASD ... */Start DASD 0700 Links /* ... except for 700, which hasa minidisk I need to link to */Start Volid SYSPG1 Page /* ... and, if Operations movesthe CP-owned paging pack anywherein the 700-7FF range, ithas to be useable for systempaging! */Figure 3. Example DRAIN and START StatementsAfter you IPL the system, you can use the CP QUERY DASD DRAINING commandto see the results of your DRAIN (Disk) and START (Disk) statements. For example,if the CP-owned volume did not fall into the range of drained devices, you wouldsee:Vol-ID Rdev Draining: PAge LInks SPool TDiskSYS700 0700 Yes No Yes YesSYS701 0701 Yes Yes Yes YesSYS702 0702 Yes Yes Yes Yes.SYS7FE 07FE Yes Yes Yes YesSYS7FF 07FF Yes Yes Yes YesIf the CP-owned volume SYSPG1 fell into the range of drained devices, you wouldsee:Vol-ID Rdev Draining: PAge LInks SPool TDisk.SYSPG1 0777 No Yes Yes Yes.If the CP-owned volume SYSPG1 had a real device number of X'0700', you wouldsee:Vol-ID Rdev Draining: PAge LInks SPool TDisk.SYSPG1 0700 No No Yes Yes.120 z/VM: CP Planning and Administration

EDEVICEEDEVICE Statement►► EDEVice rdev TYpe FBA ATTRibutes 21052107SCSIPaths►◄Paths:▼(1)FCP_DEVice rdev WWPN wwpn LUN lunNotes:1 You can specify a maximum of 8 ″paths″ to the device.PurposeUse the EDEVICE statement to define an emulated device that represents a realSCSI device.How to SpecifyInclude as many EDEVICE statements as needed; they are optional and can beplaced anywhere in the system configuration file. If you specify more than onestatement with the real device number, CP uses the last statement. For example, ifyou specify:RDEVice 0500 Type AFP...EDEVice 0500 TYpe FBA ATTR ESS FCP_DEV 2000 WWPN 5005076300CE04DA,LUN 6100000000000000CP defines an emulated FBA DASD at real device number 0500, and not anadvanced function printer.Operandsrdevspecifies the device number that is associated with the emulated device. Therdev must be a 1-digit to 4-digit hexadecimal number between X'0000' andX'FFFF'.TYpespecifies the emulated device type, selected by the immediately followingparameter.FBAidentifies the emulated device as an FBA DASD.ATTRibutesspecifies the name of an attribute set to be associated with the real device.Chapter 6. The System Configuration File 121

EDEVICE|||2105specifies that IBM 2105 device attributes are to be used for the real device thatis being emulated.2107specifies that IBM 2107 device attributes are to be used for the real device thatis being emulated.SCSIspecifies that general SCSI device attributes are to be used for the real devicethat is being emulated.Note: When specifying this value, you should exercise caution in defining morethan one path to the device. Be sure that the device actually supportsmultiple paths. Defining multiple paths to a device that does not supportmultiple paths could result in data-integrity problems on the device.FCP_DEVice rdevspecifies the real device number of the FCP device to be used for a specificpath to a SCSI device. The rdev must be a 1-digit to 4-digit hexadecimalnumber between X'0000' and X'FFFF'.WWPN wwpnspecifies the world wide port name for a specific path to a SCSI device. Thewwpn must be a 16-digit hexadecimal number between X'0000000000000000'and X'FFFFFFFFFFFFFFFF'.If fewer than 16 digits are specified for the wwpn, the number will be paddedwith leading zeros to make it a 16-digit number.LUN lunspecifies the logical unit number for a specific path to a SCSI device. The lunmust be a 16-digit hexadecimal number between X'0000000000000000' andX'FFFFFFFFFFFFFFFF'. Note, however, that the number of digits recognizedby the SCSI device may vary by manufacturer, type and model.If fewer than 16 digits are specified for the lun, the number will be padded withleading zeros to make it a 16-digit number, but this will almost certainly producean invalid value. You must be careful to specify all 16 digits, using trailing zeros,as per the note below.AttentionBecause CP cannot know how many digits your device recognizes, youmust enter all 16 digits. If your SCSI device is identified by fewer than 16digits, you should use trailing zeros to fill out the 16-digit lun. Note that ifyou enter nonzero digits following the digits identifying the SCSI device,those extra digits may be ignored by your device. It is therefore possibleto define multiple EDEVs that differ only in their rightmost unsupporteddigits, and the EDEVs will in fact represent the same SCSI device. (Forexample, if your device recognizes a 4-digit lun, 5A51888811221122 and5A51999933443344 would both represent the same device.) This couldlead to unintended device sharing and hence might introduce data-integrityexposures. Always identify your SCSI device by its actual logical unitnumber as defined in your storage-area network, padded on the rightwith zeros.122 z/VM: CP Planning and Administration

EDEVICEUsage NotesExamples1. When defining emulated devices to represent real SCSI devices, there shouldbe a one-to-one relationship between an emulated device and a real SCSIdevice. All paths defined for an emulated device should represent paths to thesame real SCSI device. If the paths for one emulated device are associatedwith more than one real SCSI device, or if more than one emulated device isassociated with the same real SCSI device, then data integrity problems couldoccur.2. Path validation for an emulated device occurs when the emulated device isvaried online. Any invalid path will be deleted from the EDEV. A path isconsidered to be invalid for any of the following reasons:v The path is a duplicate of an already existing path for the emulated device.v The device specified by the FCP_DEVice parameter does not exist.v The device specified by the FCP_DEVice parameter is not an FCP device.v The device specified by the FCP_DEVice parameter is an offline FCP device.v The device specified by the FCP_DEVice parameter is dedicated to a virtualmachine.v The value specified by the WWPN parameter is not a valid world wide portname in your configuration.v The value specified by the LUN parameter is not a valid logical unit numberfor the specified world wide port name.3. You can add paths and change the attribute name associated with a SCSIsystem residence volume by specifying an EDEVICE statement for it. TheEDEVICE statement must specify the path already associated with the device(passed from SAPL) in order to be valid. By default a SCSI system residencevolume is associated with the general SCSI attributes.1. To define an emulated device 8181 for a 2105 SCSI device with one path, enterthe following:edev 8181 type fba attr 2105,fcp_dev 900 wwpn 200400A0B80BA987 lun 00020000000000002. To define an emulated device 4343 for a general SCSI device with two paths,enter the following:edev 4343 type fba attr scsi,fcp_dev 800 wwpn 200400A0B80BA687 lun 0001000000000000,fcp_dev 801 wwpn 200400A0B80BA688 lun 0001000000000000Chapter 6. The System Configuration File 123

EMERGENCY_MESSAGE_CONSOLESEMERGENCY_MESSAGE_CONSOLES Statement►► EMERGENCY_MESSAGE_CONSoles ▼ rdevSYSTEM_CONSole►◄PurposeUse the EMERGENCY_MESSAGE_CONSOLES statement to define the list ofconsole addresses which CP notifies when there is a system emergency (forexample, an impending abend, shutdown, or dump). During initialization, CP createsa list of valid emergency consoles from the ones you have defined on thisstatement. The maximum number of unique console IDs that you can specify is100. If CP abends, or if a software re-IPL occurs, CP sends messages to all theconsoles on the list it created.How to SpecifyThis statement is optional and you can place it anywhere in the systemconfiguration file. Although you can include as many statements as needed, werecommend you only specify one. This statement defines the entire list of consolesthat CP uses to notify you of impending abends or other system emergencies. Ifyou specify more than one statement, CP redefines the list each time and only usesthe list of consoles specified on the very lastEMERGENCY_MESSAGE_CONSOLES statement that you specify. CP will notcombine multiple statements into one comprehensive list of consoles.Operandsrdevadds the real device number or numbers to the list of CP emergency consolesthat are sent emergency messages. The variable rdev must be a hexadecimalnumber between X'0000' and X'FFFF', and they must be locally-attached3270-type supported displays. (See z/VM: General Information for a completelist of supported 3270-type displays.)SYSTEM_CONSoleadds the system console to the list of consoles that are sent emergencymessages.UsageNotes1. If an IODF statement is defined in the system configuration file with the osconfigparameter specified, then the software I/O configuration will be controlled byHCD. In this case, the EMERGENCY_MESSAGE_CONSoles statement isignored if it is specified. Refer to “IODF Statement” on page 158 for moreinformation.2. 2250 and 3250 displays are not valid emergency message consoles.3. If you do not specify an EMERGENCY_MESSAGE_CONSOLES statement, CPsends all emergency messages to the operator consoles that you listed on theOPERATOR_CONSOLES statement in the system configuration file or theRIOGEN macroinstruction in HCPRIO, before IPL. During IPL, CP checks all theconsoles in this list to see if they are operational. If they are, CP includes them124 z/VM: CP Planning and Administration

EMERGENCY_MESSAGE_CONSOLESin the list of operator consoles. For more information about theOPERATOR_CONSOLES statement, see page 180. For more information aboutthe RIOGEN macroinstruction, see page 766.4. If the CONS=addr or CON=addr parameter was specified on the Stand-AloneProgram Loader (SAPL) panel to specify a console address and this consoleaddress is not already specified on the EMERGENCY_MESSAGE_CONSOLESstatement, it is added to the list of emergency message consoles.There will be a total of 101 emergency message consoles if the maximumnumber of 100 is specified on the EMERGENCY_MESSAGE_CONSOLESstatement and the additional console address is added to the list.Examples1. To have CP send emergency messages to the operator’s and systemprogrammer’s consoles, use the followingEMERGENCY_MESSAGE_CONSOLES statement:Emergency_Message_Consoles 0bc0 0bc1 /* Oper and SysProg consoles */Chapter 6. The System Configuration File 125

ENABLE COMMAND / CMDENABLE COMMAND / CMD Statement►► ENable COMmandCMDcommandQuery SUBCmd subcommandVirtualSet SUBCmd subcommandIBMclass *IBMclassc►◄PurposeUse the ENABLE COMMAND or CMD statement to permit CP to process requestsfor the specified CP command during and after initialization.You can also permit processing of CP commands after initialization using theENABLE COMMAND or CMD commands. For more information, see the z/VM: CPCommands and Utilities Reference.How to SpecifyInclude as many statements as needed; they are optional. You can place ENABLECOMMAND or CMD statements anywhere in the system configuration file. If youspecify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.Operandscommandis the name of the command that you are enabling. The variable command is a1-character to 12-character alphanumeric string.Query SUBCmd subcommandtells CP the name of the CP QUERY subcommand that you are enabling. Thevariable subcommand is a 1-character to 12-character alphanumeric string.Query Virtual SUBCmd subcommandtells CP the name of the CP QUERY VIRTUAL subcommand that you areenabling. The variable subcommand is a 1-character to 12-characteralphanumeric string.Set SUBCmd subcommandtells CP the name of the CP SET subcommand that you are enabling. Thevariable subcommand is a 1-character to 12-character alphanumeric string.IBMclass *tells CP to enable all versions of the specified command or subcommand. Ifomitted, IBMCLASS * is the default.IBMclass ctells CP to enable a specific version of the specified command or subcommand.The variable c can be any 1 of the following:A this is a system-control command to be used by the primary systemoperator.B this is a command for operational control of real devices.C this is a command to alter system storage.D this is a command for system-wide control of spool files.E this is a command to examine system storage.126 z/VM: CP Planning and Administration

ENABLE COMMAND / CMDUsageNotesF this is a command for service control of real devices.G this is a general-use command used to control the functions of a virtualmachine.0 (zero) this command has no specific IBM class assigned.1. To load the command processing code into CP’s system execution space, usethe CPXLOAD statement (page 76) or command. For more information aboutthe CPXLOAD command, see the z/VM: CP Commands and Utilities Reference.2. To activate a CP command while defining it, use the ENABLE operand of theDEFINE COMMAND or CMD statement (page 84) or command. For moreinformation about the DEFINE COMMAND or CMD command, see the z/VM:CP Commands and Utilities Reference.3. To deactivate a CP command:v While defining it, use the DISABLE operand of the DEFINE COMMAND orCMD statement (page 84) or command.v After defining it, use the DISABLE COMMAND or CMD statement (page 110)or command.For more information about the DEFINE or DISABLE COMMAND or CMDcommands, see the z/VM: CP Commands and Utilities Reference.4. To change the definition of an existing CP command, use the MODIFYCOMMAND or CMD statement (page 165) or command. For more informationabout the MODIFY COMMAND or CMD command, see the z/VM: CPCommands and Utilities Reference.5. To display the real address of the CP command table entry block, the currentIBM class, and the current privilege class for a specified CP command, use theLOCATE CMDBK command. For more information, see the z/VM: CPCommands and Utilities Reference.6. To remove the command processing code from CP’s system execution space,use the CPXUNLOAD command. For more information, see the z/VM: CPCommands and Utilities Reference.7. For more information about enabling and disabling commands, see the z/VM:CP Exit Customization book.Examples1. To activate the CP SHUTDOWN command (after a prior DISABLE COMMANDstatement had deactivated it), use the following:Enable Command shutdown2. To activate the class version of the CP SET PRIVCLASS command(after a prior DISABLE COMMAND statement had deactivated it), use thefollowing:Enable Command Set SubCmd privclass IBMclass 0Chapter 6. The System Configuration File 127

ENABLE DIAGNOSEENABLE DIAGNOSE Statement►► ENable DIAGnoseALL►◄▼diagdiag1-diag2PurposeUse the ENABLE DIAGNOSE statement to permit CP to process requests for oneor more locally-developed DIAGNOSE codes during and after initialization.You can also permit processing of locally-developed DIAGNOSE codes afterinitialization using the ENABLE DIAGNOSE command. For more information, seethe z/VM: CP Commands and Utilities Reference.How to SpecifyInclude as many statements as needed; they are optional. You can place ENABLEDIAGNOSE statements anywhere in the system configuration file. If you specifymore than one statement with the same operands, the last operand definitionoverrides any previous specifications.OperandsALLtells CP to enable all existing DIAGNOSE codes.Note: This operand enables all DIAGNOSE codes: the locally-defined ones, theIBM-supplied ones, and any supplied by third-party software vendors.diagdiag1-diag2is the number of the DIAGNOSE code that you are enabling. Each diag mustbe a hexadecimal number between X'0000' and X'03FC' and must be a multipleof 4. You can specify a single DIAGNOSE code, a range of DIAGNOSE codes,or any combination thereof.UsageNotes1. To define a new DIAGNOSE code, use the DEFINE DIAGNOSE statement(page 90) or command. For more information about the DEFINE DIAGNOSEcommand, see the z/VM: CP Commands and Utilities Reference.2. To load the DIAGNOSE processing code into CP’s system execution space,use the CPXLOAD statement (page 76) or command. For more informationabout the CPXLOAD command, see the z/VM: CP Commands and UtilitiesReference.3. If you do not specify the ENABLE operand, a new DIAGNOSE code is initiallyin a disabled state after being defined. CP treats disabled DIAGNOSE codesas if they were never defined. If you try to use a disabled DIAGNOSE code ina program, CP will give you a program check specification exception.128 z/VM: CP Planning and Administration

ENABLE DIAGNOSE4. To change the definition of an existing DIAGNOSE code, use the MODIFYDIAGNOSE statement (page 169) or command. For more information aboutthe MODIFY DIAGNOSE command, see the z/VM: CP Commands and UtilitiesReference.5. To display information about a DIAGNOSE code (status, entry point name, andprivilege class) after initialization, use the QUERY DIAGNOSE command. Formore information, see the z/VM: CP Commands and Utilities Reference.6. To display the real address of the CP DIAGNOSE code table block for aDIAGNOSE code, use the LOCATE DGNBK command. For more information,see the z/VM: CP Commands and Utilities Reference.7. To deactivate a DIAGNOSE code:v While defining it, use the DISABLE operand of the DEFINE DIAGNOSEstatement (page 90) or command.v After defining it, use the DISABLE DIAGNOSE statement (page 112) orcommand.For more information about the DEFINE or DISABLE DIAGNOSE commands,see the z/VM: CP Commands and Utilities Reference.8. To remove the DIAGNOSE processing code from CP’s system executionspace, use the CPXUNLOAD command. For more information, see the z/VM:CP Commands and Utilities Reference.9. Many external security managers (ESMs) do not support DIAGNOSE codesabove X'03FC'. For this reason, CP does not support DIAGNOSE codes aboveX'03FC'. The DIAGNOSE codes between X'0000' and X'03FC' are divided asfollows:X'0000' to X'00FC'Reserved for IBM useX'0100' to X'01FC'Reserved for customer useX'0200' to X'03FC'Reserved for IBM use.10. For more information about user-defined DIAGNOSE codes, see the z/VM: CPExit Customization book.Examples1. To have CP enable DIAGNOSE code X'100', use the following:Enable Diagnose 1002. To have CP enable all DIAGNOSE codes on your system, use the following:Enable Diagnose All3. To have CP enable all locally-defined DIAGNOSE codes, use the following:Enable Diagnose 100-1fc4. To have CP enable all locally-defined DIAGNOSE codes, except DIAGNOSEcode X'180', use the following:Enable Diagnose 100-17c 184-1fcChapter 6. The System Configuration File 129

ENABLE EXITSENABLE EXITS Statement►► ENable EXitsALL►◄▼exitexit1-exit2PurposeUse the ENABLE EXITS statement to permit CP to call all entry points and externalsymbols associated with one or more exit points during and after initialization.You can also permit CP to call the entry points and external symbols associatedwith an exit point after initialization using the ENABLE EXITS command. For moreinformation, see the z/VM: CP Commands and Utilities Reference.How to SpecifyInclude as many statements as needed; they are optional. You can place ENABLEEXITS statements anywhere in the system configuration file. If you specify morethan one statement with the same operands, the last operand definition overridesany previous specifications.OperandsALLtells CP to enable all existing CP exit points.exitexit1-exit2is the number of the exit point (or exit points) that you want CP to start using.Each exit must be a hexadecimal number between X'0000' and X'FFFF'. Youcan specify a single exit point number, a range of exit point numbers, or anycombination thereof.UsageNotes1. To load the exit point code into CP’s system execution space, use theCPXLOAD statement (page 76) or command. For more information about theCPXLOAD command, see the z/VM: CP Commands and Utilities Reference.2. To associate one or more entry points or external symbols with a specific exitpoint and to enable or disable that exit point, use the ASSOCIATE EXITstatement (page 60) or command. (For more information about theASSOCIATE EXIT command, see the z/VM: CP Commands and UtilitiesReference.) You can also use the ASSOCIATE EXIT statement to change theentry points and external symbols associated with a specific entry point.3. If the list of entry points and external symbols associated with this exit pointcontain any entry points or external symbols that CP does not know about, CPjust ignores them and continues normal processing. That is, CP will continue toprocess the other members of the list associated with this exit point. CP doesnot ignore an exit point because it cannot find one entry point or externalsymbol in the list. CP only ignores an exit point if it cannot find all the entrypoints and external symbols in the list.130 z/VM: CP Planning and Administration

ENABLE EXITS4. To display whether there are any unknown entry points or external symbolsassociated with an exit point after initialization, use the QUERY UNRESOLVEDcommand. For more information, see the z/VM: CP Commands and UtilitiesReference.5. To display status and usage statistics information about a specific exit pointafter initialization, use the QUERY EXITS command. For more information, seethe z/VM: CP Commands and Utilities Reference.6. To display the real address of the CP exit block for a specific exit point, usethe LOCATE XITBK command. For more information, see the z/VM: CPCommands and Utilities Reference.7. To display the real address of the CP indirect call locator block for a specificexit point, use the LOCATE ICLBK command. For more information, see thez/VM: CP Commands and Utilities Reference.8. To change the definition of an existing dynamic exit point, or remove the exitpoint from the system, use the MODIFY EXIT statement (page 172) orcommand. For more information about the MODIFY EXIT command, see thez/VM: CP Commands and Utilities Reference.9. To stop CP from calling all the entry points and external symbols associatedwith one or more exit points after defining those exit points, use the DISABLEEXITS statement (page 114) or command. For more information about theDISABLE EXITS command, see the z/VM: CP Commands and UtilitiesReference.10. To remove the exit point code from CP’s system execution space, use theCPXUNLOAD command. For more information, see the z/VM: CP Commandsand Utilities Reference.11. For more information about user-defined exit points, see the z/VM: CP ExitCustomization book.Examples1. To have CP start using the entry points and external symbols associated withCP Exit 99 after initialization, use the following:Enable Exits 992. To have CP start using the entry points and external symbols associated with allCP exit points after initialization, use the following:Enable Exits AllChapter 6. The System Configuration File 131

ENFORCE_BY_VOLidENFORCE_BY_VOLid Statement►► ENFORCE_BY_VOLid ONOFF►◄PurposeUse the ENFORCE_BY_VOLid configuration statement to enforce attachment ofDASD devices by their VOLIDs on the ATTACH command.How to SpecifyThe ENFORCE_BY_VOLid statement is optional. If you do not specify thestatement, CP will not enforce attachment of DASD devices by their VOLIDs. If youspecify the statement more than once, CP will use the last ENFORCE_BY_VOLidstatement entered.OperandsONtells CP to enforce attachment of DASD devices by VOLID only.OFFtells CP not to enforce attachment of DASD devices by VOLID only.UsageNotes1. When the ENFORCE_BY_VOLid ON statement is specified, the VOLIDs for allDASD devices must be specified on the CP ATTACH command. For moreinformation about the CP ATTACH command, see the z/VM: CP Commands andUtilities Reference book.132 z/VM: CP Planning and Administration

EQUATEEQUATE Statement►► EQUate symbol ▼ sysname ►◄PurposeUse the EQUATE statement to create nicknames for systems or groups of systems.After creating a nickname, you can use it as a record qualifier in the systemconfiguration file to limit the scope of the statement and to group systems that havecommon properties. This allows you to create generic system configuration files thatcan be shared across multiple systems.How to SpecifyInclude as many statements as needed; they are optional. You must define anickname before you use it, so place your EQUATE statements anywhere in thesystem configuration file before any statements using those nicknames. If youspecify more than one statement with the same nickname, CP uses the laststatement. CP will not combine multiple statements with the same nickname intoone comprehensive group.Operandssymbolis the nickname for a system or group of systems that you are groupingtogether because they have similar properties and should therefore be treatedthe same way when CP processes the system configuration file. Each symbol isa 1-character to 16-character alphanumeric nickname with no imbedded blanks.sysnameis the name of the system (or systems) you want included in the specifiednickname group. You can use generic system names to request a specificsubset of systems. A generic system name is a 1-character to 8-character stringwith asterisks (*) in place of one or more arbitrary characters and percent signs(%) in place of exactly one arbitrary character. For example:Equate yorktown y%tvm*creates a nickname that includes all systems that start with Y and have TVM astheir third, fourth, and fifth characters.UsageNotes1. You can use multiple names in an EQUATE statement and still distinguishbetween the systems. For example:Equate vm3 sys1 sys2 sys4creates the nickname VM3 for systems SYS1, SYS2, and SYS4. If you laterhave statements using these names:Sys4: ...Sys1: ...Vm3: ...Chapter 6. The System Configuration File 133

EQUATEThe statement starting with Sys4: only applies to system SYS4; the statementstarting with Sys1: only applies to system SYS1; and the statement starting withVm3: applies to systems SYS1, SYS2, and SYS4.2. You can also use the systemid on the SYSTEM_IDENTIFIER statement (page226) as a record qualifier. Just be sure to define the systemid in aSYSTEM_IDENTIFIER statement before you try to use it as a nickname.Examples1. If you have five systems set aside for business and five set aside for research,you can use an EQUATE statement to give each of the two groups a nickname.Then you can use the nicknames as record qualifiers on other statements in thesystem configuration file.For example:Equate business atlanta boston, /* Define BUSINESS nickname */chicago clevland,newyorkEquate research maine raleigh, /* Define RESEARCH nickname */rdsys1 testsys,yorktown.Business: Features Disable Set_PrivClass /* Don’t let users set *//* their own privilege *//* classes */.Research: Features Enable Set_PrivClass /* Let users set their *//* own privilege classes */allows the users on the five research systems to change their own privilegeclasses and allows the system operator on those system to change the privilegeclasses of any users logged on those systems. It also prevents the users andsystem operators on the five business systems from changing privilege classes.134 z/VM: CP Planning and Administration

EXTERNAL_SYNTAXEXTERNAL_SYNTAX Statement►► EXTERNAL_SYNtax EPName epname ►◄PurposeUse the EXTERNAL_SYNTAX statement to add locally-developed systemconfiguration file statements to the system without modifying the systemconfiguration file processor, HCPZSC ASSEMBLE.How to SpecifyInclude as many statements as needed; they are optional. You can placeEXTERNAL_SYNTAX statements anywhere in the system configuration file, as longas they appear before the first invocation of the new configuration file statement. Ifyou specify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.OperandsEPName epnametells CP the name of the external symbol that identifies the start of your syntaxdefinition. This would be the label that is generated or coded on theHCPDOSYN macro which defines the syntax of your locally-developed systemconfiguration file statement.UsageNotes1. If your locally-developed system configuration file statement has the same name(or minimum abbreviation) as a system configuration file statement shipped byIBM, your statement will override the existing statement.Examples1. To define and use your own system configuration file statement duringinitialization, use the following:CPXLoad tttsyn text a /* Load the module */Temporary, /* ... in case we must unload it later */NoControl, /* ... to unload without more checking */Nodelay, /* ... load immediately from parmdisk */Lock /* ... make sure all of it is in storage *//* if it is > 4K. (Not necessary, *//* unless you are paranoid, like me!) *//* Let us hook into the front of the standard syntax definitions */External_Syntax EPname tttsyntxIn this example, the module TTTSYN contains your syntax tree, which starts atlabel TTTSYNTX. This example shows how you would get CP to load themodule and make CP consider it additional syntax during initialization.Chapter 6. The System Configuration File 135

FEATURESFEATURES Statement►► FEATURES ▼ AUTO_IPLAUTO_IPL_AFTER_RESTartAUTO_IPL_AFTER_SHUTDOWN_REIPLCMVLANDISableDISCONNECT_TIMEoutENABLeMAXUsersPASSWORDS_ON_CMDsRETRieveVDISK►◄AUTO_IPL:AUTO_IPLCLEANCOLDFORCEWARMNOENABLEDRAINNOAUTOLOGNODIRECTAUTO_IPL_AFTER_RESTART:AUTO_IPL_AFTER_RESTARTCLEANCOLDFORCEWARMNOENABLEDRAINNOAUTOLOGNODIRECTAUTO_IPL_AFTER_SHUTDOWN_REIPL:AUTO_IPL_AFTER_SHUTDOWN_REIPLCLEANCOLDFORCEWARMNOENABLEDRAINNOAUTOLOGNODIRECT136 z/VM: CP Planning and Administration

FEATURESDISable:DISableAUTO_WARM_IPLCLEAR_TDiskCPCHECKingDYNamic_i/oDYNamic_ioIPL_MESSAGEsLOGMSG_FROM_FileNEW_DEVices_initialized_when_addedPROMPt AFTER_RESTartPROMPt AFTER_SHUTDOWN_REIPLPROMPt AFTER_POWERoffSET_DEVicesSET_DYNamic_i/oSET_DYNamic_ioSET_PRIVclassTHROTTLE_ALLDISCONNECT_TIMEout:DISCONNECT_TIMEoutnnnnnnOFFChapter 6. The System Configuration File 137

FEATURESENABle:ENABleAUTO_WARM_IPLCLEAR_TDiskABENDCPCHECKingVMSTOPDYNamic_i/oDYNamic_ioIPL_MESSAGEsLOGMSG_FROM_FileSHOW_ACCountNoSHOW_ACCountSHOW_ACIgroupYesNoSHOW_ACIgroup YesSHOW_Userid NoSHOW_UseridPROMPt AFTER_RESTartPROMPt AFTER_SHUTDOWN_REIPLPROMPt AFTER_POWERoffSET_DEVicesSET_DYNamic_i/oSET_DYNamic_ioSET_PRIVclassTHROTTLE_ALLYesMAXUsers:MAXUsersMAXUsersNOLimitnnnnn138 z/VM: CP Planning and Administration

FEATURESPASSWORDS_ON_CMDs:PASSWORDS_ON_CMDs(1) AUTOLog NoAUTOLog YesLINK NoLINKLOGonLOGonYesNoYesNotes:1 You must specify at least one of the operands.RETRieve:RETRieve(1) DEFault 7DEFault nnnMAXimum 7MAXimumnnnNotes:1 You must specify at least one of the operands.VDISK:VDISK Syslim InfiniteVDSK Userlim nnnnnnnnnn BlocksBlksnnnnnnnMnnnnGPurposeUse the FEATURES statement to set certain attributes of the system at systeminitialization.How to SpecifyInclude as many statements as needed; they are optional. You can placeFEATURES statements anywhere in the system configuration file. If you specifymore than one statement with the same operands, the last operand definitionoverrides any previous specifications.Chapter 6. The System Configuration File 139

FEATURESOperandsAUTO_IPLdefines the kind of start to be performed when the system is initialized. Thesystem will be started without prompting the system operator and withoutchanging the TOD clock.AUTO_IPL_AFTER_RESTartdefines the kind of start to be performed when the system is initialized after asystem restart. The system will be restarted without prompting the systemoperator and without changing the TOD clockAUTO_IPL_AFTER_SHUTDOWN_REIPLdefines the kind of start to be performed when the system is initialized after aSHUTDOWN REIPL. The system will be restarted without prompting the systemoperator and without changing the TOD clock.COLDtells CP to perform a cold start. This will purge all spool files, accountingrecords, error recording records, symptom records, and the system logmessage. System data files will not be purged.If spooling errors that could result in the loss of system data files (NSS,DCSS, TRF, IMG, UCR, NLS) are encountered, the system operator will beprompted and given the opportunity to stop. If no spooling errors areencountered, the system operator will not be prompted and there will be noopportunity to stop.CLEANtells CP to perform a clean start. This will purge all spool files, system datafiles, accounting records, error recording records, symptom records, and thesystem log message. The system operator will not be prompted and therewill be no opportunity to stop.FORCEtells CP to perform a force start. If spooling errors are encountered, thespool files and system data files in error will be purged. The systemoperator will not be prompted and there will be no opportunity to stop.WARMtells CP to perform a warm start. If spooling errors are encountered, thesystem operator will be prompted and given the opportunity to stop.NOENABLEtells CP not to enable terminal access after system initialization.DRAINtells CP to drain unit-record devices after system initialization.NOAUTOLOGtells CP to bypass automatic logon of virtual machines after systeminitialization.NODIRECTtells CP to bring up the system without a User Directory.DISabledisables the following system attributes during IPL. Note that initially, eachoption is disabled until enabled using the ENABLE operand.AUTO_WARM_IPLtells CP to go through all the usual prompts in the IPL process.140 z/VM: CP Planning and Administration

FEATURESCLEAR_TDisktells CP to clear only cylinder 0 or the first eight blocks on the temporaryminidisk when it detaches the minidisk.CPCHECKingtells CP that internal CP checking is not to be executed.DYNamic_i/oDYNamic_iotells CP not to allow dynamic I/O changes on this processor.IPL_MESSAGEstells CP not to display IPL or SHUTDOWN messages or prompts duringsystem initialization.If IPL_MESSAGES are disabled and spooling errors are encountered duringan automatic WARM or COLD IPL, wait state HCP2516W will be issued.LOGMSG_FROM_Filetells CP not to look for any LOGMSG files on disk. Instead, CP should useinformation from the class B CP SET LOGMSG command. For moreinformation on the CP SET LOGMSG command, see the z/VM: CPCommands and Utilities Reference.NEW_DEVices_initialized_when_addedtells CP to create a real device control block (RDEV) for a new I/O device,but not to initialize (bring online) that device when your system receives anI/O machine check (IOMCK) for adding a new device to the system. Tobring the device online, use the CP VARY (Real Device) command. Formore information about the CP VARY (Real Device) command, see thez/VM: CP Commands and Utilities Reference.PROMPt AFTER_RESTarttells CP not to force a prompt to the operator when CP bounces.PROMPt AFTER_SHUTDOWN_REIPLtells CP not to force a prompt to the operator when CP is performing aSHUTDOWN REIPL.PROMPt AFTER_POWERofftells CP not to force a prompt to the operator when CP detects that this IPLis during a power on after a SHUTDOWN POWEROFF.SET_DEVicestells CP not to allow users to execute CP SET DEVICES commands tochange the way the way CP handles specific real devices after initialization.For more information about the CP SET DEVICES command, see the z/VM:CP Commands and Utilities Reference.SET_DYNamic_i/oSET_DYNamic_iotells CP not to allow users to execute CP SET DYNAMIC_I/O commands toenable or disable CP’s ability to dynamically change the processor’s I/Oconfiguration after initialization. For more information about the CP SETDYNAMIC_I/O command, see the z/VM: CP Commands and UtilitiesReference.SET_PRIVclasstells CP not to give end users the authority to use the CP SET PRIVCLASScommand to change their own privilege classes, and tells CP not to give thesystem operator the authority to use the CP SET PRIVCLASS command toChapter 6. The System Configuration File 141

FEATURESchange the privilege classes of users logged on to the system. For moreinformation about the CP SET PRIVCLASS command, see the z/VM: CPCommands and Utilities Reference.THROTTLE_ALLtells CP to allow throttling of ALL devices on the system except CP OWNEDDASD.DISCONNECT_TIMEout nnnnnnsets the interval between a forced disconnect of a virtual machine and its logoffto the specified number of minutes. The default is 15 minutes.DISCONNECT_TIMEout OFFdisables the automatic logoff of a virtual machine that is forcibly disconnected.ENABleenables the following system attributes during IPL. Note that initially, eachoption is disabled until it is enabled.AUTO_WARM_IPLtells CP to attempt a warm start without changing the TOD clock. If there isno warm start data, if the TOD clock is not set, or if spooling errors areencountered, CP will prompt the operator for more information.CLEAR_TDisktells CP to automatically clear all previously written data and directory areason TDISK DASD space. CP will change TDISK DASD space to binary zerosduring CP initialization, when attaching a CP-owned volume that containsTDISK allocations, and when a user detaches a TDISK minidisk. Byclearing this space, you prevent users from accidentally accessing oldtemporary disk space and provides your system with additional security.CPCHECKingtells CP to activate internal CP checking to confirm assertions established inthe CP code and take the appropriate action based on whether ABEND orVMSTOP is specified.ABENDIndicates that an abend should occur. Whether it is a hard abend or asoft abend is controlled by the specific assertion case. It is typically ahard abend. This is the default when internal CP checking is activated.VMSTOPThis parameter is permitted only when CP is itself running in a virtualmachine, and is generally useful only for debugging CP. Specifying thisparameter causes CP to issue DIAGNOSE code X'8' when an untrueassertion is encountered, specifying a command string length of zero.This causes the virtual machine to stop and for CP to post a read to theconsole. A message is sent to the console (using DIAGNOSE code X'8'and the CP MESSAGE * command) providing information about thecause of the stop.DYNamic_i/oDYNamic_iotells CP to allow dynamic I/O changes on this processor.IPL_MESSAGEstells CP to display IPL or SHUTDOWN messges and prompts duringsystem initialization (the default).LOGMSG_FROM_Filetells CP to display the contents of the SYSTEM LOGMSG file on the lowest142 z/VM: CP Planning and Administration

FEATURESaccessed CP disk. You can optionally choose to have CP read and displayadditional files at a user’s terminal using one or more of the followingoperands:SHOW_ACCount No(the default) tells CP not to display a file called accountid LOGMSACC(accountid is the account ID of a specific user) in response to a CPQUERY LOGMSG command.SHOW_ACCount Yestells CP to display a file called accountid LOGMSACC (accountid is theaccount ID of a specific user) in response to a CP QUERY LOGMSGcommand.SHOW_ACIgroup No(the default) tells CP not to display a file called acigroup LOGMSACI(acigroup is the ACI group of a specific user) in response to a CPQUERY LOGMSG command.SHOW_ACIgroup Yestells CP to display a file called acigroup LOGMSACI (acigroup is theACI group of a specific user) in response to a CP QUERY LOGMSGcommand.SHOW_Userid No(the default) tells CP not to display a file called userid LOGMSUSR(userid is the user ID of a specific user) in response to a CP QUERYLOGMSG command.SHOW_Userid Yestells CP to display a file called userid LOGMSUSR (userid is the userID of a specific user) in response to a CP QUERY LOGMSG command.For more information about the CP QUERY LOGMSG command, see thez/VM: CP Commands and Utilities Reference.NEW_DEVices_initialized_when_addedtells CP to automatically create a real device control block (RDEV) andinitialize (bring online) the associated I/O device when you add a newdevice, causing an I/O machine check (IOMCK).PROMPt AFTER_RESTarttells CP to force a prompt to the operator when CP bounces, so that REIPLcan be stopped or the type of start desired (WARM, FORCE, etc.) can bespecified.PROMPt AFTER_SHUTDOWN_REIPLtells CP to force a prompt to the operator when CP is performing aSHUTDOWN REIPL, so that REIPL can be stopped or the type of startdesired (WARM, FORCE, etc.) can be specified.PROMPt AFTER_POWERofftells CP to force a prompt to the operator when CP detects that this IPL isduring a power on after a SHUTDOWN POWEROFF, so that REIPL can bestopped or the type of start desired (WARM, FORCE, etc.) can be specified.SET_DEVicestells CP to allow users to execute CP SET DEVICES commands to changethe way the way CP handles specific real devices after initialization. Formore information about the CP SET DEVICES command, see the z/VM: CPCommands and Utilities Reference.Chapter 6. The System Configuration File 143

FEATURES||||||||||||SET_DYNamic_i/oSET_DYNamic_iotells CP to allow users to execute CP SET DYNAMIC_I/O commands toenable or disable CP’s ability to dynamically change the processor’s I/Oconfiguration after initialization. For more information about the CP SETDYNAMIC_I/O command, see the z/VM: CP Commands and UtilitiesReference.SET_PRIVclasstells CP to give end users the authority to use the CP SET PRIVCLASScommand to change their own privilege classes, and tells CP to give thesystem operator the authority to use the CP SET PRIVCLASS command tochange the privilege classes of users logged on to the system. For moreinformation about the CP SET PRIVCLASS command, see the z/VM: CPCommands and Utilities Reference.THROTTLE_ALLtells CP to allow throttling of ALL devices on the system including CPOWNED DASD.MAXusers NOLimit(the default) tells CP that an unlimited number of users can log on.MAXusers nnnnndefines the maximum number of users who can log on to the system at onetime. The variable nnnnn is a decimal number from 1 to 99999.PASSWORDS_ON_CMDstells CP whether to accept passwords in the command syntax (in clear text)when users issue the CP AUTOLOG, XAUTOLOG, LINK, or LOGONcommands. If the setting is NO, CP accepts the command only without thepassword, then prompts the user for the password and masks the input field.AUTOLog No(the default) tells CP to not accept passwords entered by users who areissuing the CP AUTOLOG or XAUTOLOG command.AUTOLog Yestells CP to accept passwords entered by users who are issuing the CPAUTOLOG or XAUTOLOG command. For AUTOLOG, users must enter thepassword as part of the command.LINK No(the default) tells CP to not accept passwords entered by users who areissuing the CP LINK command.LINK Yestells CP to accept passwords entered by users who are issuing the CPLINK command.LOGon No(the default) tells CP to not accept passwords entered by users who areissuing the CP LOGON command.LOGon Yestells CP to accept passwords entered by users who are issuing the CPLOGON command.For more information about the CP AUTOLOG, XAUTOLOG, LINK, and LOGONcommands, see the z/VM: CP Commands and Utilities Reference.144 z/VM: CP Planning and Administration

FEATURESRETRievedefines the default and maximum number of retrieve buffers allowed per useron your system. These numbers determine how many console input lines auser can retrieve. Before retrieving a buffer, users must define a programfunction (PF) key as a retrieve key, using the CP SET PFnn RETRIEVEcommand. After defining a retrieve key, users can press that PF key when theywant to retrieve a command that they issued previously. For more informationabout the CP SET PFnn RETRIEVE command, see the z/VM: CP Commandsand Utilities Reference.DEFault nnntells CP to define nnn default retrieve buffers per user on your system. Thevariable nnn is a decimal number from 0 to 255. If omitted, the default is 7.Note: The number of default retrieve buffers must be less than or equal tothe number of maximum retrieve buffers.MAXimum nnntells CP to define nnn maximum retrieve buffers per user on your system.The variable nnn is a decimal number from 0 to 255. If omitted, the defaultis 7.VDISKVDSKdefines installation defaults for the system and user limits on the maximumamount of system storage available for allocation as virtual disks in storage. Ifan installation default is not defined, CP uses a built-in default.You can supercede the installation or built-in default by using the CP SETVDISK command to set the current system limit or user limit. The DEFAULToperand on the SET VDISK command resets the current limit to the installationdefault, or, if none is defined, to the built-in default. The CP QUERY VDISKcommand displays current and default system and user limits. For moreinformation about the CP SET and QUERY VDISK commands, see the z/VM:CP Commands and Utilities Reference.Note: Use of virtual disks in storage increases the load on system paging, soyou should set limits in proportion to the availability of paging space.Syslimsets the total resource available for allocating virtual disks in storage on thesystem.If an installation default is not defined, CP calculates the built-in default fromthe available system storage. It takes 2050 non-pageable pages of pageand segment data tables to support each gigabyte of address space forvirtual disks in storage. The limit is set so these non-pageable structurescan consume no more than 1/4 of the DPA pages. The limit is furtherreduced, if necessary, so the virtual storage pages used for address spacesfor virtual disks in storage can consume no more than 1/4 of the totalavailable paging space.Userlimsets the maximum resource available for virtual disks in storage created bya single user using the CP DEFINE command. This limit does not apply tovirtual disks in storage defined by MDISK statements in the directory. If aninstallation default is not defined, the built-in default is 0.Chapter 6. The System Configuration File 145

FEATURESUsageNotesInfiniteindicates that there is no limit. All available system storage may beallocated to virtual disks in storage.nnnnnnnnnn Blocksnnnnnnnnnn Blksspecifies the number of 512-byte blocks of storage available for virtual disksin storage. If the number specified is equal to or greater than 2147483648,the limit is set to INFINITE.nnnnnnnMspecifies the number of megabytes of storage available for virtual disks instorage. If the number specified is equal to or greater than 1048576, thelimit is set to INFINITE.nnnnGspecifies the number of gigabytes of storage available for virtual disks instorage. If the number specified is equal to or greater than 1024, the limit isset to INFINITE.1. If an IODF statement is defined in the system configuration file, then thehardware I/O configuration will be controlled by HCD. In this case, thefollowing FEATURES statements are ignored if they are specified:v FEATURES ENABLE DYNAMIC_I/Ov FEATURES ENABLE DYNAMIC_IOv FEATURES ENABLE SET_DYNAMIC_I/Ov FEATURES ENABLE SET_DYNAMIC_IOv FEATURES DISABLE DYNAMIC_I/Ov FEATURES DISABLE DYNAMIC_IOv FEATURES DISABLE SET_DYNAMIC_I/Ov FEATURES DISABLE SET_DYNAMIC_IOIf the osconfig parameter is specified on the IODF statement, then the softwareI/O configuration will be controlled by HCD. In this case, the followingFEATURES statements are ignored if they are specified:v FEATURES ENABLE SET_DEVICESv FEATURES DISABLE SET_DEVICESRefer to “IODF Statement” on page 158 for more information.2. FEATURES ... SET_PRIVCLASS sets the parameters for the CP SETPRIVCLASS command, which general users can use to change their privilegeclasses to be all or a subset of the classes specified in their directory entries.For more information about the CP SET PRIVCLASS command, see the z/VM:CP Commands and Utilities Reference.3. At logon, CP gives each user enough storage for the default number ofretrieve buffers. If users want to retrieve more than the default number ofconsole input lines, they can use the CP SET RETRIEVE command toincrease their number of retrieve buffers to some number less than or equal tothe maximum number of retrieve buffers that you are defining for the systemusing this FEATURES statement. To find out the maximum number of retrievebuffers allowed on a running system, users can issue the CP QUERYRETRIEVE command. For more information about the CP QUERY and SETRETRIEVE commands, see the z/VM: CP Commands and Utilities Reference.146 z/VM: CP Planning and Administration

FEATURES4. If you enable AUTO_WARM_IPL and no warm start data has been saved, or ifinvalid warm start data is encountered, CP will only ask the operator whether itshould try a FORCE start instead.5. If you enable AUTO_WARM_IPL in the system configuration file and you wantto go through the full series of prompts during the IPL, you can specify thePROMPT keyword as part of the IPL parameters on the Stand-Alone ProgramLoader (SAPL). For more information about the Stand-Alone Program Loader(SAPL) and the IPL parameters, see page 37.6. To change whether new devices are initialized when they are added to thesystem after IPL, use the CP SET NEW_DEVICES command. For moreinformation about the SET NEW_DEVICES command, see the z/VM: CPCommands and Utilities Reference.7. To allow users to dynamically change a device’s I/O configuration after IPL,you must specify the ENABLE DYNAMIC_I/O operand on the FEATURESstatement in the system configuration file or you must issue the CP SETDYNAMIC_I/O ON command after IPL. If you do not turn this function on eitherduring or after IPL, CP will reject all attempts to dynamically change the I/Oconfiguration. This means that CP rejects the following dynamic I/Ocommands:DEFINE CHPID DEFINE CU DEFINE DEVICEDELETE CHPID DELETE CU DELETE DEVICEMODIFY CHPID MODIFY CU MODIFY DEVICEDEFINE PATH DEFINE CNTLUNIT DEFINEIODEVICEDELETE PATH DELETE CNTLUNIT DELETEIODEVICEMODIFY PATH MODIFY CNTLUNIT MODIFYIODEVICEQUERYCONFIGMODEQUERYDYNAMIC_I/OSET CONFIGMODE SET DEVICES SETDYNAMIC_I/O||||||8. To change whether I/O operations from guest operating systems can be limited(or controlled) after IPL, use the CP SET DEVICES command. For moreinformation about the SET DEVICES command, see the z/VM: CP Commandsand Utilities Reference.9. Because the SYSLimit does not apply during system initialization, it is possibleto find more LAN segments in the system than the number defined as thesystem limit.10. Although the PASSWORDS_ON_CMDs operand can be set to preventpasswords from being entered with the commands (in clear text) on theterminal screen, passwords may still be included on the command line byREXX execs using the DIAG() and DIAGRC() functions. If you require accesssecurity without the possibility of passwords being stored in clear text, youshould consider installing an external security manager (ESM).Examples1. To have CP:v Enable all log message supportv Allow end users and the operator to issue the SET PRIVCLASS commandChapter 6. The System Configuration File 147

FEATURES|v Clear all temporary disk space after users are through with itv Allow operators to dynamically change the I/O configurationv Prompt the operator for startup information after a software restart (bounce)v Allow operators to limit the I/O operations from guest operating systemsv Initialize new devices when they are added to the systemv Disable the automatic warm start featurev Give users a default of 7 retrieve buffers and let them go up to a maximum of255 buffersv Allow an unlimited number of users to be logged on at one timev Prompt users for passwords on the CP AUTOLOG, XAUTOLOG, andLOGON commands, but not the CP LINK commandv Set the installation default system limit on space for virtual disks in storage to’32GB’ and the installation default user limit to 800 blocksuse the following FEATURES statement:/*----------------------- Features Statement ------------------------*/Features,Enable,Logmsg_From_File, /* Allow log messages from files */Show_ACCount Yes, /* If account logmsg exists, show it */Show_ACIgroup Yes, /* If acigroup logmsg exists, show it */Show_Userid Yes, /* If userid logmsg exists, show it */Set_Privclass, /* Let the SET PRIVCLASS command beexecuted. If this option is disabled,then the SET PRIVCLASS command is notallowed. */Clear_Tdisk, /* Clear all temporary disk space afteruse */Dynamic_I/O, /* Allow dynamic I/O changes on thissystem */Prompt_on_Bounce, /* If CP bounces, prompt operator forstartup conditions */Throttling, /* Allow people to limit I/O from guests */New_Devices_Initialized_when_Added, /* Initialize devices if we getan IPI I/O machine check */Disable,Auto_Warm_Ipl, /* Do not perform Auto_Warm_IPL’s, letoperator see the CP start-up messageprompts and time message *//* Set some additional features ... */Retrieve,Default 7, /* Give each user 7 default retrieve buffers */Maximum 255, /* Set the maximum system buffers per user to 255 */MaxUser NoLimit, /* Don’t set a maximum number of user limit */Passwords_On_Cmds,148 z/VM: CP Planning and AdministrationAutoLog No, /* Prompt user for password on AUTOLOG command */Link Yes, /* Do not prompt for password on LINK command */

FEATURESLogon No, /* Prompt user for password on LOGON command */Vdisk,Syslim 32G, /* Set total virtual disks in storage to 32GB */Userlim 800 Blks, /* User can define max 800 blocks using DEFINE *//*-------------------- End of Features Statement --------------------*/Chapter 6. The System Configuration File 149

FORM_DEFAULTFORM_DEFAULT Statement►►FORM_DEFault(1)▼CONSoleCONSolePRINTerSTANDARDformnameSTANDARD►◄PRINTer formnamePUNch STANDARDPUNchREADerREADerformnameSTANDARDformnameNotes:1 You must specify at least one of the following operands.PurposeUse the FORM_DEFAULT statement to define default user form names for CP touse when it creates files on virtual printers, virtual punches, virtual consoles, or realcard readers.How to SpecifyInclude as many statements as needed; they are optional. You can placeFORM_DEFAULT statements anywhere in the system configuration file. If youspecify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.OperandsExamplesCONSole formnamedefines the default user (and, implicitly, operator) forms for virtual console spoolfiles. If omitted, the default is STANDARD.PRINTer formnamespecifies the default user form for virtual printer spool files. If omitted, thedefault is STANDARD.PUNch formnamespecifies the default user form for virtual punch spool files. If omitted, thedefault is STANDARD.READer formnamespecifies the default user (and, implicitly, operator) forms for files created on areal card reader. If omitted, the default is STANDARD.1. To have CP use the form name STANDARD for the console, printer, punch, andreader user form names, use the following FORM_DEFAULT statement:150 z/VM: CP Planning and Administration

FORM_DEFAULTForm_Default, /* Set up user form defaults */Console STANDARD, /* so they are all set to */Printer STANDARD, /* the default ... STANDARD */Punch STANDARD,Reader STANDARDChapter 6. The System Configuration File 151

HOT_IO_RATEHOT_IO_RATE Statement►► HOT_IO_Rate ALLDASDGrafrdevrdev-rdevSPecialSWCHSWitchTApeTErminalUnit_recordURDefaultOffnnnnn►◄PurposeUse the HOT_IO_RATE statement to define the maximum number of consecutive,unsolicited interrupts per second that CP should allow from an I/O device (the hotI/O rate) before refusing to accept input from it.How to SpecifyInclude as many statements as needed; they are optional. You can placeHOT_IO_RATE statements anywhere in the system configuration file. If you specifymore than one statement with the same operands, the last operand definitionoverrides any previous specifications.OperandsALLtells CP to define the hot I/O rate for all devices in the active I/O configuration.DASDtells CP to define the hot I/O rate for all DASDs in the active I/O configuration.Graftells CP to define the hot I/O rate for all graphic display devices in the active I/Oconfiguration.rdevtells CP to define the hot I/O rate for a device at a specific real device numberin the active I/O configuration. The variable rdev must be a hexadecimalnumber between X'0000' and X'FFFF'.rdev-rdevtells CP to define the hot I/O rate for devices in a range of specific real devicenumbers in the active I/O configuration. Each rdev must be a hexadecimalnumber between X'0000' and X'FFFF'.SPecialtells CP to define the hot I/O rate for all special devices (3088s, CTCAs, 37x5s)in the active I/O configuration.SWCH152 z/VM: CP Planning and Administration

HOT_IO_RATESWitchtells CP to define the hot I/O rate for all switching devices in the active I/Oconfiguration.TApetells CP to define the hot I/O rate for all tape drive devices in the active I/Oconfiguration.TErminaltells CP to define the hot I/O rate for all terminals in the active I/O configuration.Unit_recordURtells CP to define the hot I/O rate for all unit record devices in the active I/Oconfiguration.Defaulttells CP to use the default rate of 16 unsolicited interrupts per second for thespecified device or devices.Offturns hot I/O detection off and tells CP to accept all unsolicited interrupts for thespecified device or devices.Attention!We do not recommend that you specify the OFF operand to turn off thehot I/O detection for a device or devices for any length of time. Hot I/Odetection protects CP from broken hardware that floods the system withunsolicited interrupts. If you turn hot I/O detection off, you may experienceperformance degradation or a system abend.UsageNotesnnnnntells CP how many unsolicited interrupts per second to accept for the specifieddevice or devices before CP stops accepting input from the device or devices.The variable nnnnn is a decimal number from 1 to 62500.1. If an IODF statement is defined in the system configuration file with the osconfigparameter specified, then the software I/O configuration will be controlled byHCD. In this case, the HOT_IO_Rate statement is ignored if it is specified.Refer to “IODF Statement” on page 158 for more information.2. CP processes HOT_IO_RATE statements sequentially for each device beforebringing it online. For example, if you specify:Hot_IO_Rate DASD 100Hot_IO_Rate 200-300 50CP accepts 100 unsolicited interrupts per second for all DASD and 50unsolicited interrupts per second for all devices with real device numbersbetween 200 and 300, inclusive. If there are any DASD defined in the 200-300real device number range, those DASD will have an unsolicited interrupt rate of50, not 100.3. Attention: We do not recommend that you specify the OFF operand to turn offthe hot I/O detection for a device or devices for any length of time. Hot I/Odetection protects CP from broken hardware that floods the system withunsolicited interrupts. If you turn hot I/O detection off, you may experienceperformance degradation or a system abend.Chapter 6. The System Configuration File 153

HOT_IO_RATE4. If you need to change the hot I/O rate after IPL, use the CP SET HOTIOcommand. To check the current hot I/O rates, use the CP QUERY HOTIOcommand. For more information about the CP SET HOTIO and QUERY HOTIOcommands, see the z/VM: CP Commands and Utilities Reference.Examples1. To specify a global unsolicited interrupt rate of 100 for all I/O devices, overridethe global rate for all DASDs, and override the global DASD rate for a specificrange of DASD, use the following HOT_IO_RATE statements:Hot_IO_Rate All 100 /* Set rate for all devices tomake sure none affect thesystem too much. */Hot_IO_Rate DASD 200 /* Allow DASD a few more errors */Hot_IO_Rate 0280-028f 50 /* Third party DASD string */154 z/VM: CP Planning and Administration

IMBEDIMBED Statement►► IMbed fn=ft=►◄PurposeUse the IMBED statement to tell CP to imbed a file into the main systemconfiguration file during an IPL. All imbedded files must reside on the same disk asthe main system configuration file.How to SpecifyInclude as many statements as needed; they are optional. You can place IMBEDstatements anywhere in the main system configuration file and in any files that areimbedded into the main system configuration file. You can nest imbedded files asdeep as you like.Operandsfn is the file name of the file you want imbedded. An = tells CP to imbed a file withthe same file name.ft is the file type of the file you want imbedded. An = tells CP to imbed a file withthe same file type.UsageNotes1. If you specify a file name or file type of -SYSTEM-, CP uses the name of thesystem being IPLed as that file name or file type. For example, if your systemname is VMSYS3 and you have the following IMBED statement in your systemconfiguration file:Imbed -system- configCP looks for a file named VMSYS3 CONFIG on the parm disk. If found, CPimbeds the file and processes the statements within it. If CP does not find thefile, the IMBED statement fails and CP continues processing with the statementafter the IMBED.2. An imbed will not succeed if the -SYSTEM- variable is included and no systemidentifier exists to replace it. This situation arises when you do not specify aSYSID macroinstruction in HCPSYS and you do not specifySYSTEM_IDENTIFIER and SYSTEM_IDENTIFIER_DEFAULT statements in thesystem configuration file before the IMBED statement.3. This statement will not accept imbed loops. If the system configuration fileincludes an imbed of the file SAMPLE CONFIG, and the SAMPLE CONFIG fileincludes an imbed of the file SAMPLE2 CONFIG, then CP will generate an errormessage if the SAMPLE2 CONFIG file tries to imbed the SAMPLE CONFIG file.Examples1. If you list your RDEVICE statements in a file separate from the master systemconfiguration file, you can use the following IMBED statement to include theRDEVICE statements:Imbed rdev config /* Pull in RDEVICE statements */Chapter 6. The System Configuration File 155

IMBED2. If you have several systems with similar system configuration files, you can usethe IMBED statement to create a master system configuration file that containsthe common statements and imbed files that contain the system-specificstatements. For example, suppose you had three systems (BOSTON, MAINE,and NEWYORK) that had very similar system configuration files with thefollowing exceptions:v BOSTON lets end users change their privilege classesv MAINE wants to manually answer all the prompts during an IPLv NEWYORK limits the number of logged on users to 1000.You can create a main system configuration file with the following IMBEDstatement:Imbed -systemconfig /* Pull in the system-specificinformation */Each of the three systems has a copy of this main system configuration file andeach has a system-specific configuration file. For example, on the BOSTONsystem, there is a file called BOSTON CONFIG which contains the followingstatement:Features Enable Set_PrivClass /* Let the users and the systemoperator change commandprivilege classes */On the MAINE system, there is a file called MAINE CONFIG which contains thefollowing statement:Features Disable Auto_Warm_IPL /* Perform manual IPLs */And on the NEWYORK system, there is a file called NEWYORK CONFIG whichcontains the following statement:Features MaxUsers 1000 /* Do not let more than1000 users log on */Note: You can also process system-specific information without using theIMBED statement. You can use the EQUATE statement (page 133) to setup nicknames for systems and use those nicknames in the main systemconfiguration file to limit the scope of the statements they preface.In the previous example, you could have defined nicknames for the threesystems and used those nicknames to preface the FEATURESstatements:.Equate Marketing bostonEquate University maineEquate Research newyork.Marketing: Features Enable Set_PrivClassUniversity: Features Disable Auto_Warm_IPLResearch: Features MaxUsers 1000.156 z/VM: CP Planning and Administration

INIT_MITIMEINIT_MITIME Statement►► INIT_MITime ss ►◄PurposeUse the INIT_MITIME statement to change the MITIME (the time interval at which adevice is checked for missing interrupts) that is in effect during device initializationat system IPL time.How to SpecifyThe INIT_MITIME statement is optional. Since there is only one MITIME value usedat IPL time, there should never be a need for more than one INIT_MITIMEstatement. However, if you specify more than one INIT_MITIME statement, CP usesthe value from the last statement. If no INIT_MITIME statement is specified, CPuses the default value of 15 seconds.Operandsss is the time interval in seconds at which the device should be examined formissing interrupts. The number of seconds specified must be a value from oneto 60, and the value is rounded up to the next multiple of five seconds.UsageNotes1. Lowering the initialization MITIME value below the default value of 15 secondsmay cause certain devices to not come online during IPL due to timeout errors.These devices may be able to be brought online with the VARY ON commandafter the IPL has completed.2. When using the INIT_MITIME statement to raise the MITIME value, take intoconsideration the fact that this could result in a slower IPL due to CP waitinglonger for I/O interrupts to come in from devices.Examples1. To set the initialization MITIME to 45 seconds, use the following INIT_MITIMEstatement:Init_Mitime 45Chapter 6. The System Configuration File 157

IODFIODF Statement►► IODF IODF nn* osconfig SYSTEM_CONSole►◄PurposeUse the IODF statement to indicate that HCD will be used to control the I/Ohardware and/or software configuration.How to SpecifyThe IODF statement is optional. If specified, it must contain at least the IODFnnoperand to indicate the filename of the production IODF from which configurationinformation will be read.OperandsYou can place the IODF statement anywhere in the system configuration file. Onlythe first IODF statement that is found in the system configuration file is honored. Ifadditional IODF statements are specified, they are ignored.IODFnnspecifies the filename of the production IODF to be used. The filename must bespecified in the form IODFnn and the filetype that will be used with thatfilename is PRODIODF. This file must be located on the system parameter disk(SYSPARM) at system IPL time.* specifies that the filename of the production IODF to be used is the onecurrently stored in the hardware configuration token in the HSA. The filenamemust be in the form of IODFnn and the filetype that will be used with thatfilename is PRODIODF. This file must be located on the system parameter disk(SYSPARM) at system IPL time.osconfigspecifies the OS configuration ID of the VM I/O configuration that is defined inthe IODF. If specified, this configuration is used to build the software view of theI/O configuration, and the statements that are normally used in the systemconfiguration file to build this view are ignored.SYSTEM_CONSolespecifies that the system console can serve as the operator console. This canonly be specified when an OS configuration ID is specified.UsageNotes1. If an error occurs during the processing of an IODF statement which wouldresult in the system coming up without the I/O configuration being defined asexpected, then CP will enter a disabled wait state. This wait state could occurfor any of the following reasons:the specified IODF name is not validthe IODF could not be openedthe IODF could not be readthe data in the IODF was not valid158 z/VM: CP Planning and Administration

IODFan osconfig name was specified, but no matching OSR record was found inthe IODF2. Once an IODF statement has been processed in the system configuration file,HCD is in control of the hardware and/or software I/O configuration. Because ofthis, any system configuration file statements that affect the I/O configurationare nullified. Any of these statements occurring prior to the IODF statement(meaning they have already been processed) are undone, and any of thesestatements which occur after the IODF statement are ignored. The following listshows the I/O configuration statements that are always undone or ignored, aswell as which I/O configuration statements are only undone or ignored whenHCD is controlling the software configuration (i.e. when an osconfig name hasbeen specified):vIODFv FEATURES DISABLE/ENABLE DYNAMIC_IOv FEATURES DISABLE/ENABLE SET_DYNAMIC_IOv RDEVICE (if osconfig name specified)v DEVICES ACCEPTED/NOTACCEPTED (if osconfig name specified)v DEVICES DYNAMIC_I/O/NOTDYNAMICI/O (if osconfig name specified)v DEVICES OFFLINE_AT_IPL/ONLINE_AT_IPL (if osconfig name specified)v DEVICES SENSED/NOTSENSED (if osconfig name specified)v DEVICES SHARED/NOTSHARED (if osconfig name specified)v HOT_IO_RATE (if osconfig name specified)v OPERATOR_CONSOLES (if osconfig name specified)v EMERGENCY_MESSAGE_CONSOLES (if osconfig name specified)v FEATURES DISABLE/ENABLE SET_DEVICES (if osconfig name specified)3. Once a system is IPLed with HCD in control of the I/O configuration, there is aone-way mechanism to take that control away from HCD and give it back toVM. The DISABLE HCD command provides this one-way escape from havingHCD control the I/O configuration. It will shut down HCD’s capabilities for therest of the current IPL, and will attempt to give VM the capability to dynamicallychange the I/O configuration through its dynamic I/O command interface.Examples1. To have HCD control only the hardware I/O configuration, as specified in theIODF01 PRODIODF production IODF file, use the following IODF statement inthe system configuration file:IODF IODF012. To have HCD control both the hardware and software I/O configuration, asspecified in the IODF02 PRODIODF file (which contains the CONFIG04operating system configuration), use the following IODF statement in the systemconfiguration file:IODF IODF02 CONFIG043. To have HCD control both the hardware and software I/O configuration, asspecified in the IODF02 PRODIODF file (which contains the CONFIG04operating system configuration), and to have the system console as a possibleoperator console, use the following IODF statement in the system configurationfile:IODF IODF02 CONFIG04 SYSTEM_CONSOLEChapter 6. The System Configuration File 159

JOURNALINGJOURNALING Statement►►(1)JOURNALing Operands ►◄Operands:▼FACility OFF SET_AND_Query OFFSET_AND_Query OFFFACility ONSET_AND_Query ON(1)LINK LINK Operands(1)LOGON LOGON OperandsLINK Operands:▼ACCount After 2 AttemptsAttemptsACCount After nnnDISable After 10 AttemptsAttemptsDISable After nnnMESSage After 5 Attempts To OPERATORAttemptsMESSage After nnn To useridMSGNotes:1 You must specify at least one of the following operands.160 z/VM: CP Planning and Administration

JOURNALINGLOGON Operands:▼ACCount After 2 AttemptsAttemptsACCount After nnnLOCKout After 10 Attempts For 60 MinutesAttemptsLOCKout After nnn For mmmMESSage After 3 Attempts To OPERATORMinutesAttemptsMESSage After nnn To useridMSGVM_LOGO After 4 AttemptsVM_LOGO After nnnAttemptsPurposeUse the JOURNALING statement to tell CP whether to include the journaling facility,whether to enable the system being initialized to set and query the journalingfacility, and what to do if someone tries to log on to the system or link to a diskwithout a valid password.How to SpecifyInclude as many statements as needed; they are optional. You can placeJOURNALING statements anywhere in the system configuration file. If you specifymore than one statement with the same operands, the last operand definitionoverrides any previous specifications.OperandsFACility OFFtells CP to disable the journaling facility for this system. This is the initial setting.FACility ONtells CP to enable the journaling facility for this system.SET_AND_Query OFFtells CP to prevent people from using the CP SET and QUERY commandsto set and query the journaling function for this system.SET_AND_Query ONtells CP to allow people to use the CP SET and QUERY commands to setand query the journaling function for this system.LINKtells CP that you want to define what should happen when users try to link to aminidisk with the wrong password. These settings only apply to a single user IDfor a single logon session.Chapter 6. The System Configuration File 161

JOURNALINGACCount After nnn Attemptstells CP to generate a type 06 accounting record after someone tries nnntimes to use a CP LINK command with an invalid password and to generatea type 06 accounting record each time that person issues a subsequent CPLINK command with an invalid password. The variable nnn is a decimalnumber from 0 to 255. If omitted, the default is ACCOUNT AFTER 2ATTEMPTS.DISable After nnn Attemptstells CP to disable the CP LINK command for a user that tries nnn times touse the CP LINK command with an invalid password. The variable nnn is adecimal number from 1 to 255. If omitted, the default is DISABLE AFTER10 ATTEMPTS.MESSage After nnn Attempts To useridMSG After nnn Attempts To useridtells CP to send a message to a specific user ID when a user tries nnntimes to use the CP LINK command with an invalid password. If thespecified userid is disconnected or logged off, CP sends the message tothe system operator. The variable nnn is a decimal number from 0 to 255. Ifomitted, the default is MESSAGE AFTER 5 TO OPERATOR.LOGONtells CP that you want to define what should happen when users try to log onwith the wrong password.ACCount After nnn Attemptstells CP to generate a type 04 accounting record after someone tries nnntimes to log on with an invalid password and to generate a type 04accounting record each time that person issues a subsequent CPAUTOLOG, LOGON, or XAUTOLOG command with an invalid password.The variable nnn is a decimal number from 0 to 255. If omitted, the defaultis ACCOUNT AFTER 2 ATTEMPTS.LOCKout After nnn Attempts For mmm Minutestells CP to issue an error message to the terminal, lock the terminal, andlock the user ID after someone tries (unsuccessfully) more than nnn timesto log on to a specific user ID or terminal. No one can log on to that user IDor use that terminal for mmm minutes; anyone who tries receives anothererror message. The variable nnn is a decimal number from 1 to 255 and thevariable mmm is a decimal number from 0 to 255. If omitted, the default isLOCKOUT AFTER 10 ATTEMPTS FOR 60 MINUTES.MESSage After nnn Attempts To useridMSG After nnn Attempts To useridtells CP to send a message to a specific user ID when a user tries morethan nnn times to log on to a user ID with an invalid password. If thespecified userid is disconnected or logged off, CP sends the message tothe system operator. The variable nnn is a decimal number from 0 to 255. Ifomitted, the default is MESSAGE AFTER 3 ATTEMPTS TO OPERATOR.VM_LOGO After nnn Attemptstells CP to display a new VM logon screen and allow a new logon sequenceto be started after someone tries more than nnn times to log on with aninvalid password from a single terminal. The variable nnn is a decimalnumber from 1 to 255. If omitted, the default is VM_LOGO AFTER 4ATTEMPTS.162 z/VM: CP Planning and Administration

JOURNALINGExamples1. To have CP:v Enable the journaling facilityv Allow the QUERY and SET journaling commands to be issuedv Send a message to the operator after someone tries 3 times to log on withthe wrong password and after someone tries 5 times to link to a minidisk withthe wrong passwordv Generate a type 04 accounting record after someone tries 5 times to log onwith the wrong password (and to generate a type 04 accounting record foreach subsequent attempt)v Generate a type 06 accounting record after someone tries 6 times to link to aminidisk with the wrong passwordv Display a new logo screen on a terminal after someone tries 7 times to logonwith the wrong passwordv Lock a terminal and user ID for 10 minutes after someone tries 9 times to logon with the wrong passwordv Disable the LINK command for a specific user ID for the rest of their logonsession when they try to link to a minidisk 8 times with the wrong passworduse the following JOURNALING statement:Journaling, /* Set Up Journaling Facility */Facility on, /* Turn On Journaling */Set_and_Query on, /* Allow Set & Query Journaling Commands */Logon, /* Set Up Logon Journaling Values */Message after 3 attempts to operator,Account after 5 attempts,VM_Logo after 7 attempts,Lockout after 9 attempts for 10,Link, /* Set Up Link Journaling Values */Message after 5 attempts to operator,Account after 6 attempts,Disable after 8 attemptsChapter 6. The System Configuration File 163

LOGO_CONFIGLOGO_CONFIG Statement►► LOGO_CONfig fn ft ►◄PurposeUse the LOGO_CONFIG statement to specify the file name and file type of a logoconfiguration file.How to SpecifyThe LOGO_CONFIG statement is optional. Because there is only one logoconfiguration file, you need only one LOGO_CONFIG statement. If you specifymore than one LOGO_CONFIG statement, CP uses the last one specified. You canplace LOGO_CONFIG statements anywhere in the system configuration file.OperandsIf you do not specify a LOGO_CONFIG statement, CP looks for a file named LOGOCONFIG on the parm disk. If this file does not exist on the parm disk, CP uses theinformation in HCPBOX ASSEMBLE to build the logos.fn is the file name of the logo configuration file.ft is the file type of the logo configuration file. This file must be on the same diskas the system configuration file.UsageNotes1. If you specify a file name or file type of -SYSTEM-, CP uses the name of thesystem being IPLed as that file name or file type. For example, if your systemname is VMSYS3 and you have the following LOGO_CONFIG statement in yoursystem configuration file:Logo_Config -system- configCP looks for a file named VMSYS3 CONFIG on the parm disk.2. CP will not read a logo configuration file if the -SYSTEM- variable is includedand no system identifier exists to replace it. This situation arises when you donot specify a SYSID macroinstruction in HCPSYS and you do not specifySYSTEM_IDENTIFIER and SYSTEM_IDENTIFIER_DEFAULT statements in thesystem configuration file before the LOGO_CONFIG statement.Examples1. To have CP read a logo configuration file called LOGO CONFIG during IPL, usethe following LOGO_CONFIG statement:Logo_Config logo config164 z/VM: CP Planning and Administration

MODIFY COMMAND / CMDMODIFY COMMAND / CMD Statement►► MODify COMmandCMDcommandQuerySetSUBCmdVirtualSUBCmdsubcommandsubcommandIBMclass *IBMclassc►►RESETEPName name SILENTPRIVCLASSANYNOTSILENTPRIVclasses classesSILENTNOTSILENT►◄PurposeUse the MODIFY COMMAND or CMD statement to redefine an existing CPcommand on the system during initialization.Note: The OVERRIDE utility can provide some of the same functions. However,you should use either the OVERRIDE method or the MODIFY statements. Ifany MODIFY statement is detected at IPL time, the UCR (User ClassRestructure) OVERRIDE changes will be bypassed. IBM recommends usingthe new MODIFY statements.You can also redefine an existing CP command after initialization using theMODIFY COMMAND or MODIFY CMD commands. For more information, see thez/VM: CP Commands and Utilities Reference.How to SpecifyInclude as many statements as needed; they are optional. You can place MODIFYCOMMAND or CMD statements anywhere in the system configuration file. If youspecify more than 1 statement with the same command or subcommand name, CPuses only the first statement. Subsequent MODIFY COMMAND or CMD statementsdo not redefine the command.Operandscommandis the name of the existing CP command that you are overriding. The variablecommand is a 1-character to 12-character alphanumeric string.Querytells CP that you are overriding a CP QUERY command.Virtualtells CP that you are overriding a CP QUERY VIRTUAL subcommand.SUBCmd subcommandis the name of the CP QUERY subcommand that you are overriding. TheChapter 6. The System Configuration File 165

MODIFY COMMAND / CMDvariable subcommand is a 1-character to 12-character alphanumeric string.For more information about specifying generic subcommand names, seeUsage Note 1.Settells CP that you are overriding a CP SET command.SUBCmd subcommandis the name of the CP SET subcommand that you are overriding. Thevariable subcommand is a 1-character to 12-character alphanumeric string.For more information about specifying generic subcommand names, seeUsage Note 1.IBMclass *tells CP to redefine all versions of the specified command or subcommand. Ifomitted, IBMCLASS * is the default.IBMclass ctells CP to redefine a specific version of the specified command orsubcommand. The variable c can be any 1 of the following:A this is a system-control command to be used by the primary systemoperator.B this is a command for operational control of real devices.C this is a command to alter system storage.D this is a command for system-wide control of spool files.E this is a command to examine system storage.F this is a command for service control of real devices.G this is a general-use command used to control the functions of a virtualmachine.0 (zero) this command has no specific IBM class assigned.RESETtells CP to stop using the customer-written CP command and return to usingthe existing CP command that was shipped with the z/VM product.EPName nametells CP the name of the entry point that contains the code to process thecommand. The variable name must be a 1-character 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 four special characters ($, #, _, and@), or any combination thereof.PRIVCLASSANYtells CP that users with any privilege class can issue the command that you areredefining.PRIVclasses classestells CP that only users with 1 or more of the specified privilege classes canissue the command that you are redefining. Whatever you specify on thisoperand will replace the current privilege classes. The variable classes is 1 ormore privilege classes in the range A through Z, 1 through 6, or an asterisk (*).Privilege class * indicates all privilege classes (A-Z and 1-6).Note: If you want more than one privilege class, specify your classes in onestring of characters. Do not separate the classes with blank spaces. Forexample, specify “privclasses abc123”, not “privclasses a b c 1 2 3”.SILENTtells CP that the responses from the command you are redefining can be166 z/VM: CP Planning and Administration

MODIFY COMMAND / CMDUsageNotessuppressed by invoking it using the SILENTLY command. For more information,see the z/VM: CP Commands and Utilities Reference.Note: Response suppression is supported only for the ATTACH, DETACH, andGIVE commands.NOTSILENTtells CP that the responses from the command you are redefining cannot besuppressed.1. If you are making similar changes to several QUERY (or SET) subcommandsand those subcommands share common characters, you can use a genericsubcommand name rather than specifying multiple MODIFY COMMAND orCMD statements (or commands). A generic subcommand name is a1-character to 12-character alphanumeric string with asterisks (*) in place ofone or more characters and percent signs (%) in place of exactly onecharacter. For example:modify command query tr*c% ...redefines all QUERY commands that start with TR and have C as theirnext-to-last character.2. To define a new CP command or a new version (by IBM class) of an existingCP command, use the DEFINE COMMAND or CMD statement (page 84) orcommand. For more information about the DEFINE COMMAND or CMDcommands, see the z/VM: CP Commands and Utilities Reference.3. To define a new alias for an existing CP command, use the DEFINE ALIASstatement (page 81) or command. For more information about the DEFINEALIAS command, see the z/VM: CP Commands and Utilities Reference.4. Once defined, COMMANDS, SUBCOMMANDS, ALIASES, and DIAGNOSEcodes cannot be deleted. They can be altered in various appropriate ways butthey remain in existence until a SHUTDOWN or RESTART IPL is done.5. To load the command processing code into CP’s system execution space, usethe CPXLOAD statement (page 76) or command. For more information aboutthe CPXLOAD command, see the z/VM: CP Commands and UtilitiesReference.6. To activate a CP command:v While defining it, use the ENABLE operand of the DEFINE COMMAND orCMD statement (page 84) or command.v After defining it, use the ENABLE COMMAND or CMD statement (page 126)or command.For more information about the DEFINE or ENABLE COMMAND or CMDcommands, see the z/VM: CP Commands and Utilities Reference.7. To display the real address of the CP command table entry block, the currentIBM class, and the current privilege class for a specified CP command, use theLOCATE CMDBK command. For more information, see the z/VM: CPCommands and Utilities Reference.8. To deactivate a CP command:v While defining it, use the DISABLE operand of the DEFINE COMMAND orCMD statement (page 84) or command.v After defining it, use the DISABLE COMMAND or CMD statement (page110) or command.Chapter 6. The System Configuration File 167

MODIFY COMMAND / CMDFor more information about the DEFINE or DISABLE COMMAND or CMDcommands, see the z/VM: CP Commands and Utilities Reference.9. To remove the command processing code from CP’s system execution space,use the CPXUNLOAD command. For more information, see the z/VM: CPCommands and Utilities Reference.10. For more information about user-defined commands, see the z/VM: CP ExitCustomization book.Examples1. To have CP change the CP SHUTDOWN command from privilege class A toprivilege class S, use the following:Modify Command shutdown, /* Put tighter controls on who can */privclasses s /* shut down the system. */2. To have CP change the version of the CP SET PRIVCLASS command thatallows users with any privilege class to issue the command to a version thatallows only users with privilege class G and Z to issue the command, use thefollowing:Modify Command Set SubCmd privclass, /* Make sure only a few can */IBMclass 0, /* issue SET PRIVCLASS */PrivClasses gz3. To have CP change all IBM class E QUERY subcommands to privilege class G,use the following:Modify Command Query SubCmd *, /* Make sure anyone can use */IBMclass e, /* the Queries to check */PrivClasses g /* system storage */168 z/VM: CP Planning and Administration

MODIFY DIAGNOSEMODIFY DIAGNOSE Statement►► MODify DIAGnosediag(1)RESETOperands(2)►◄Operands:EPName epname PRIVCLASSANYPRIVclassesclassesCHECKR15YESNONotes:1 You must specify one of the following operands.2 If you specify more than one operand, you can specify them in any order.PurposeUse the MODIFY DIAGNOSE statement to redefine an existing DIAGNOSE codeon the system during initialization.Note: The OVERRIDE utility can provide some of the same functions. However,you should use either the OVERRIDE method or the MODIFY statements. Ifany MODIFY statement is detected at IPL time, the UCR (User ClassRestructure) OVERRIDE changes will be bypassed. IBM recommends usingthe new MODIFY statements.You can also redefine an existing DIAGNOSE code after initialization using theMODIFY DIAGNOSE command. For more information, see the z/VM: CPCommands and Utilities Reference.How to SpecifyInclude as many statements as needed; they are optional. You can place MODIFYDIAGNOSE statements anywhere in the system configuration file. If you specifymore than one statement with the same operands, the last operand definitionoverrides any previous specifications.Operandsdiagis the number of the DIAGNOSE code that you are redefining. The variable diagmust be a hexadecimal number between X'0100' and X'01FC' and must be amultiple of 4. All other DIAGNOSE code numbers are reserved for IBM useonly.RESETtells CP to stop using the customer-written DIAGNOSE code and return to usingthe existing DIAGNOSE code that was shipped with the z/VM product.Chapter 6. The System Configuration File 169

MODIFY DIAGNOSEEPName nametells CP the name of the entry point that contains the code to process theDIAGNOSE code. The variable name 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.PRIVCLASSANYtells CP that users with any privilege class can issue the DIAGNOSE code thatyou are redefining.PRIVclasses classestells CP that only users with 1 or more of the specified privilege classes canissue the DIAGNOSE code that you are redefining. Whatever you specify onthis operand will replace the current privilege classes. The variable classes is 1or more privilege classes in the range A through Z, 1 through 6, or an asterisk(*). Privilege class * indicates all privilege classes (A-Z and 1-6).Note: If you want more than one privilege class, specify your classes in onestring of characters. Do not separate the classes with blank spaces. Forexample, specify “privclasses abc123”, not “privclasses a b c 1 2 3”.CHECKR15 YESCHECKR15 NOindicates whether the diagnose router should check register 15 upon returnfrom the diagnose handler.UsageNotes1. To define a new DIAGNOSE code, use the DEFINE DIAGNOSE statement(page 90) or command. For more information about the DEFINE DIAGNOSEcommand, see the z/VM: CP Commands and Utilities Reference.2. To load the DIAGNOSE processing code into CP’s system execution space,use the CPXLOAD statement (page 76) or command. For more informationabout the CPXLOAD command, see the z/VM: CP Commands and UtilitiesReference.3. If you do not specify the ENABLE operand, a new DIAGNOSE code is initiallyin a disabled state after being defined. CP treats disabled DIAGNOSE codesas if they were never defined. If you try to use a disabled DIAGNOSE code ina program, CP will give you a program check specification exception.4. To activate a new DIAGNOSE code:v While defining it, use the ENABLE operand of the DEFINE DIAGNOSEstatement (page 90) or command.v After defining it, use the ENABLE DIAGNOSE statement (page 128) orcommand.For more information about the DEFINE or ENABLE DIAGNOSE commands,see the z/VM: CP Commands and Utilities Reference.5. To display information about a DIAGNOSE code (status, entry point name, andprivilege class) after initialization, use the QUERY DIAGNOSE command. Formore information, see the z/VM: CP Commands and Utilities Reference.6. To display the real address of the CP DIAGNOSE code table block for aDIAGNOSE code, use the LOCATE DGNBK command. For more information,see the z/VM: CP Commands and Utilities Reference.7. To deactivate a DIAGNOSE code:170 z/VM: CP Planning and Administration

MODIFY DIAGNOSEv While defining it, use the DISABLE operand of the DEFINE DIAGNOSEstatement (page 90) or command.v After defining it, use the DISABLE DIAGNOSE statement (page 112) orcommand.For more information about the DEFINE or DISABLE DIAGNOSE commands,see the z/VM: CP Commands and Utilities Reference.8. To remove the DIAGNOSE processing code from CP’s system executionspace, use the CPXUNLOAD command. For more information, see the z/VM:CP Commands and Utilities Reference.9. Many external security managers (ESMs) do not support DIAGNOSE codesabove X'03FC'. For this reason, CP does not support DIAGNOSE codes aboveX'03FC'. The DIAGNOSE codes between X'0000' and X'03FC' are divided asfollows:X'0000' to X'00FC'Reserved for IBM useX'0100' to X'01FC'Reserved for customer useX'0200' to X'03FC'Reserved for IBM use.10. When CHECKR15 YES is specified, the diagnose router will check register 15on return from the diagnose handler. If register 15 contains:RC = 0Processing was successful. Complete the guest instruction.RC = 4Processing failed due to a condition which would cause a guestprogram check. Simulate guest program interruption passed in R0.RC = 8Nullify the instruction.RC = 12Present the machine check then nullify the instruction. R2 will containthe address of the MCRBK which will contain the machine checkinformation.RC = 16Generate machine check for processing damage, then go toHCPENDOP to terminate the instruction.RC = 20Present the machine check, then go to HCPENDOP to terminate theinstruction. R2 will contain the address of the MCRBK, which containsmachine check information.RC = 24Issue error message or soft abend for paging I/O error, then nullify theinstruction. R1 has the message or abend number.If a return code is invalid (negative, not a multiple of 4 or too big ( RC > 24 )),then a soft abend will occur.11. For more information about user-defined DIAGNOSE codes, see the z/VM: CPExit Customization book.Examples1. To have CP change the privilege class for DIAGNOSE code X'7C' from “any” toR, use the following:Modify Diagnose 7c PrivClasses rChapter 6. The System Configuration File 171

MODIFY EXITMODIFY EXIT Statement►► MODify EXit exit CLEAROperands(1)►◄Operands:AT entry + offset instruction NORESolveRESolvePARM▼parameterNotes:1 You must specify at least one of the listed operands. If you specify more than one, you canspecify them in any order.PurposeUse MODIFY EXIT to redefine or remove an existing dynamic exit point duringinitialization.You can also redefine or remove an existing dynamic exit point after initializationusing the MODIFY EXIT command. For more information, see the z/VM: CPCommands and Utilities Reference book.How to SpecifyInclude as many statements as needed; they are optional. You can place MODIFYEXIT statements anywhere in the system configuration file. If you specify more thanone statement with the same operands, the last operand definition overrides anyprevious specifications.Operandsexitis the number of the exit point you are redefining or removing. This value mustbe a hexadecimal number between X'0' and X'FFFF'. The recommended valueis between X'F000' and X'FFFF', because that range is reserved for customeruse. All other exit numbers are reserved for IBM, vendor, or general use.CLEARtells CP to remove the exit.AT entry + offset instructionidentifies the new location for the exit point you are redefining and theinstruction that is located at the exit point. The variable entry must be a1-to-8-character string. The first character must be alphabetic or one of thefollowing special characters: $ (dollar sign), # (number sign), _ (underscore), or@ (at sign). The rest of the string can be alphabetic or numeric characters, thefour special characters ($, #, _, or @), or any combination. The variable offsetmust be a 1-to-4-character even hexadecimal number between X'0' andX'FFFE'. The variable instruction must be a 2-, 4-, or 6-character hexadecimalnumber.172 z/VM: CP Planning and Administration

MODIFY EXITUsageNotesNORESolvetells CP to resolve the entry points associated with this exit number the firsttime they are called.RESolvetells CP to resolve the entry points associated with this exit number when theassociation is first established. Any existing associated entry points are resolvedimmediately.PARM parameteris a list of one or more parameters to be supplied to the exit. Five kinds oftokens can be used to define a parameter:1. Addresses: strings up to eight characters long, consisting of thehexadecimal digits 0 through 9 and A through F.2. General Registers: strings beginning with G or R, followed by a decimalnumber between 0 and 15 or a hexadecimal digit, designating the contentsof a general register.3. Indirection: a percent sign (%), which causes the contents of an address orthe contents of an address in a register to be used instead of the address orregister contents itself.4. Arithmetic: a plus sign (+) or minus sign (−).5. Displacement: strings of up to four hexadecimal digits.Each parameter string specifies how to combine these tokens to generate aparameter value to be passed to an exit routine. The following is a Backus-Naurdefinition of the syntax of a parameter: ::= | ::= | 0...FFFFFFFF | % ::= | % | ::= + | − | + | − ::= G | R ::= 0...15 | 0...9, A...F ::= 0...7FFF1. To define a new dynamic exit point, use the DEFINE EXIT statement (page 94)or command. For information about the DEFINE EXIT command, see thez/VM: CP Commands and Utilities Reference.2. To load the exit processing code into CP’s system execution space, use theCPXLOAD statement (page 76) or command. For information about theCPXLOAD command, see the z/VM: CP Commands and Utilities Reference.3. To activate a new exit point, use the ENABLE EXITS statement (page 130) orcommand. For information about the ENABLE EXITS command, see the z/VM:CP Commands and Utilities Reference.4. To display information about an exit point (status, entry point name, andparameters), use the QUERY EXITS command. For more information, see thez/VM: CP Commands and Utilities Reference.5. To deactivate an exit point, use the DISABLE EXITS statement (page 114) orcommand. For information about the DISABLE EXITS command, see thez/VM: CP Commands and Utilities Reference.6. To remove the exit processing code from CP’s system execution space, usethe CPXUNLOAD command. For more information, see the z/VM: CPCommands and Utilities Reference.7. Exit numbers are allocated as follows:v X'0000' to X'7FFF' are reserved for IBM use.Chapter 6. The System Configuration File 173

MODIFY EXITv X'8000' to X'EFFF' are reserved for vendor and general use.v X'F000' to X'FFFF' are reserved for private customer use.8. The RESOLVE option ensures that the entry names associated with an exitpoint are defined.9. Each exit is passed a parameter list that begins with three standardparameters, as described in the z/VM: CP Exit Customization book. Additionalparameters, specified by the PARM operand, are optional and follow the firstthree in the order in which they are specified.10. Errors (for example, addressing exceptions) during evaluation of user-definedparameters when an exit is being invoked cause CP to abend.11. For more information about user-defined exits, see the z/VM: CP ExitCustomization book.Examples1. To change the location of exit point X'F422' to HCPXGMSM + 4, enter thefollowing:Modify Exit f422 At hcpxmgsm + 4 41700001174 z/VM: CP Planning and Administration

MODIFY LANMODIFY LAN Statement►► MODify LAN lannameOWNERidOWNERidSYSTEMowneridGRANT userid ►◄PurposeOperandsUse the MODIFY LAN statement to modify the attributes of an existing VM GuestLAN segment during initialization.lannameis the name of the VM LAN segment to be modified. The lanname is a singletoken (1–8 alphanumeric characters). The combination of ownerid and lannamewill identify the LAN. This LAN must be created by a DEFINE LAN statement inthe System Configuration file.OWNERid owneridOWNERid SYSTEMspecifies the owner of the LAN.GRANT useridspecifies userid is added to the access list for this LAN. This allows user useridto connect an adapter to LAN lanname if it is a RESTRICTED LAN. If anExternal Security Manager (ESM) is in control of the LAN, it may override theCP access list.UsageNotes1. If the VM LAN is defined with the UNRESTRICTED attribute, any user canconnect a virtual adapter to that LAN. The CP access list has no meaning for anUNRESTRICTED LAN. This will be overridden if an External Security Manager(ESM) is in control of the Virtual Switch.2. When a RESTRICTED LAN is defined, the owner is automatically added to theaccess list.Examples1. To modify a SYSTEM LAN named TECHINFO by adding user REYNOLDS tothe access list, specify the following:modify lan techinfo grant reynoldsChapter 6. The System Configuration File 175

MODIFY PRIV_CLASSESMODIFY PRIV_CLASSES Statement►► MODify PRIV_CLASSes HW_ServiceIOCP_ReadIOCP_WriteOPERatorUSER_DEFaultclassesRESET►◄PurposeUse MODIFY PRIV_CLASSES to change the privilege classes authorizing thefollowing CP functions:v Logging on as the primary system operatorv Intensive error recordingv Using the read function of the CP IOCP utilityv Using the write function of the CP IOCP utilityv Specifying the default user class.Note: The OVERRIDE utility can provide some of the same functions. However,you should use either the OVERRIDE method or the MODIFY statements. Ifany MODIFY statement is detected at IPL time, the UCR (User ClassRestructure) OVERRIDE changes will be bypassed. IBM recommends usingthe new MODIFY statements.ParametersHW_Servicetells CP to change the privilege classes authorized to perform intensive errorrecording.IOCP_Readtells CP to change the privilege classes authorized to use the read function ofthe IOCP utility.IOCP_Writetells CP to change the privilege classes authorized to use the write function ofthe IOCP utility. (For more information about the IOCP utility, see the z/VM: CPCommands and Utilities Reference.)OPERatortells CP to change the privilege classes which are for the primary systemoperator.USER_DEFaulttells CP to change the privilege classes that are defined for users who do nothave a class specified in their directory entries.RESETtells CP to reset the privilege classes to their original default settings.classestells CP which class or classes are to be set. The variable classes is a 1- to8-character alphanumeric string from A through Z and from 0 to 6.176 z/VM: CP Planning and Administration

MODIFY PRIV_CLASSESUsage Notes1. It is suggested that you simply use the PRIV_CLASSES statement to establishinitial privilege class values.2. If you previously used the OVERRIDE utility to change the privilege classes,you can use the CVTOVRID utility to convert your override file into a set ofMODIFY statements. For more information about the CVTOVRID utility, see thez/VM: CP Commands and Utilities Reference.Chapter 6. The System Configuration File 177

MODIFY VSWITCHMODIFY VSWITCH Statement►► MODIFY VSWITCH switchname GRAnt useridPORTTypePORTTypedefporttypeACCESSTRUNKVLANVLANdefvid▼ vlanid►◄PurposeOperandsUse the MODIFY VSWITCH statement to modify the attributes of an existing VirtualSwitch.switchnameis the name of the Virtual Switch to be modified. The switchname is a singletoken (1–8 alphanumeric characters) that identifies the Virtual Switch. ThisVirtual Switch was created by a DEFINE VSWITCH command or statement inthe System Configuration file.GRANT useridspecifies the userid to be added to the access list for this Virtual Switch. Thisallows userid to connect a QDIO adapter to switchname. If an External SecurityManager (ESM) is in control of the Virtual Switch, it may override the CPaccess list.PORTType ACCESSdefines the type of connections that are established by the userid to be anaccess port. The guest is unaware of VLAN IDs and sends and receives onlyuntagged traffic.PORTType TRUNKdefines the type of connections that are established by the userid to be a trunkport. The guest is VLAN aware and sends and receives only tagged traffic forthose VLANs to which the guest is authorized. If the guest is also authorized tothe defvid, untagged traffic sent or received by the guest is associated with thedefault VLAN ID of the virtual switch.VLAN vlanididentifies the VLAN ID to be used to restrict traffic across the adapter useridconnected to switchname. When VLAN is used with GRANT, userid isauthorized to connect to the Virtual Switch and vlanid is used as a filter.Specifying GRANT with one or more VLAN IDs adds to the set of VLAN IDsassociated with userid. A limit of four vlanids can be associated with userid inthe CP access list.vlanid is a number from 1 to 4094.If VLAN vlanid is not specified, the default VLAN for the userid is the defaultVLAN ID as specified on the DEFINE VSWITCH command or statement.If an External Security Manager (ESM) is in control of the Virtual Switch, it mayoverride the CP access list.178 z/VM: CP Planning and Administration

MODIFY VSWITCHUsage NotesExamples1. VLAN configuration information can be found in Planning for Guest LANs andVirtual Switches in z/VM: Connectivity.2. If the Virtual Switch has been defined as VLAN UNAWARE, the PORTTYPEoption and the VLAN option on GRANT are not allowed.3. If the Virtual Switch has been defined as VLAN aware and no VLANmembership is given with the GRANT (or provided by an external securitymanger), the guest is a member of the Virtual Switch’s default VLAN ID (defvid).4. If the Virtual Switch has been defined as VLAN aware and no PORTTYPE isgiven with the GRANT, the guest is assigned the porttype of the Virtual Switch’sdefault porttype (defporttype).1. To allow user VMTCPIP to connect to Virtual Switch BIGANG and filter anyincoming traffic using VLAN 9, specify the following:modify vswitch bigang grant vmtcpip vlan 9Chapter 6. The System Configuration File 179

OPERATOR_CONSOLESOPERATOR_CONSOLES Statement(1)►► OPERATOR_CONSoles ▼ rdevSYSTEM_CONSoleSYSTEM_3270►◄Notes:1 The maximum number of device numbers that you can specify is 500.PurposeUse the OPERATOR_CONSOLES statement to define a list of device numbers fromwhich CP is to choose the system operator console. CP will log on the systemoperator virtual machine at the first available address or location specified with thecommand.How to SpecifyInclude as many statements as needed; they are optional. You can placeOPERATOR_CONSOLES statements anywhere in the system configuration file. Ifyou specify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.Operandsrdevis the real hexadecimal device numbers of possible system operator consoles.These devices must be locally-attached 3270-type supported displays.The maximum number of device numbers that you can specify is 500. Whenyou initialize the system, CP goes sequentially through the list defined with theOPERATOR_CONSOLES statement and looks for the first operational console.When CP finds an operational console, it uses it as the system operator’sconsole. If CP cannot find an operational console, it enters a disabled wait statewith a wait state code of X'1010' in the PSW.SYSTEM_CONSolespecifies that the Operating System Messages panel on the HardwareManagement Console can serve as a system operator console.SYSTEM_3270specifies that the integrated 3270 console on the Hardware ManagmentConsole can serve as a system operator console.UsageNotes1. If an IODF statement is defined in the system configuration file with the osconfigparameter specified, then the software I/O configuration will be controlled byHCD. In this case, the OPERATOR_CONSoles statement is ignored if it isspecified. Refer to “IODF Statement” on page 158 for more information.2. Consoles that CP is to notify when there is a system emergency (for example,an impending abend, shutdown, or dump) should be listed on theEMERGENCY_MESSAGE_CONSOLES statement (page 124).180 z/VM: CP Planning and Administration

OPERATOR_CONSOLES3. 2250 and 3250 displays are not valid operator consoles.4. During a software re-IPL caused by either a system incident or the CPSHUTDOWN REIPL command, CP determines whether the operator virtualmachine is connected to the primary system console. If the operator virtualmachine is disconnected, logged off, or logged on to a console other than theprimary console, CP disconnects the operator virtual machine when the systemis reinitialized, unless you specified the NODISCONNECT operand on aSYSTEM_USERIDS statement or a SYSOPER macroinstruction. Thisdisconnection is a security measure to reduce the risk of CP’s logging theoperator virtual machine on to an unattended console.5. Specifying CONS=addr or CON=addr in the IPL parameters portion of theStand-Alone Program Loader window overrides any consoles specified with theOPERATOR_CONSOLES statement. See Chapter 4, “Using the Stand-AloneProgram Loader,” on page 37.Examples1. The following example shows three possible device addresses for the systemoperator console.Operator_Consoles 8e6 8e0 bc0 /* Operator Consoles in theMachine Room */Chapter 6. The System Configuration File 181

PRINTER_TITLEPRINTER_TITLE Statement►► PRINTER_TItle class stringBOTtomTOP►◄PurposeUse the PRINTER_TITLE statement to specify the printed output classes that are tocontain classification titles. CP prints classification titles on the output separatorpage and, optionally, at the top or bottom of each page of output. You can specify adifferent classification title for each class of output (A through Z and 0 through 9).How to SpecifyInclude as many statements as needed; they are optional. You can placePRINTER_TITLE statements anywhere in the system configuration file. If youspecify more than one statement with the same class, the last statement overridesany previous specifications.If you omit the PRINTER_TITLE statement, CP does not print any classificationtitles.Operandsclassis a 1-character alphanumeric string specifying the spool file class.stringis a classification title for this class. It may be up to 46 characters long, andmust be enclosed in single or double quotation marks unless it is a single wordentered with no imbedded blanks, in which case the entire word will becapitalized.If you need to include a single quotation mark in the title, enclose the wholestring with double quotation marks. If you need to include a double quotationmark in the title, enclose the whole string with single quotation marks. Also, youmay use two consecutive double quote marks ("") to represent a " characterwithin a string delimited by double quotation marks. Similarly, you may use twoconsecutive single quotation marks ('') to represent a ' character within a stringdelimited by single quotation marks.BOTtomtells CP that this title is to be printed both on the separator page and at thebottom of each page of output.TOPtells CP that this title is to be printed both on the separator page and at the topof each page of output.Note: If you do not specify the TOP or BOTTOM operands, CP only prints the titleon the separator pages.182 z/VM: CP Planning and Administration

PRINTER_TITLEUsage NotesExamples1. CP inserts the title line at the top or bottom of each page. To do this, CP insertsa CCW to print one space, followed by the title line before or after each skip tochannel 1 CCW issued by the operating system running in the virtual machineprinting the file. Inserting the title lines this way means that:v CP inserts the titles as the file is created. Later, if you change the file to adifferent class, CP does not change the titles in the file. However, the title onthe separator page always reflects the true class of the file.v Inserting the title on the output page adds a line of output to the printed page.If the virtual machine application is counting lines, its count will be incorrect.Thus, the output listing may contain blank pages.v If the operating system running in the virtual machine printing the file doesnot use skip to channel 1, the title lines are never printed.1. To define four printer classes as follows:v Class A has the title “No Security Rating” printed at the bottom of each pageand on the separator pagesv Class C has the title “COMPANY XYZ CONFIDENTIAL” printed at the top ofeach page and on the separator pagesv Class Q has the title “It’s not Confidential” printed on the separator pagesv Class X has the title “Contents aren’t Confidential” printed on the separatorpagesuse the following PRINTER_TITLE statements:/*---------------------------------------------------------------------*//* Setting up Printer Titles *//* ------------------------- *//*/* Class A printer files get "No Security Rating" printed on the *//* bottom of each page and on the separator pages *//* Class C printer files get "COMPANY XYZ CONFIDENTIAL" printed at *//* the top of each page and on the separator pages *//* Class Q printer files get "It’s Not Confidential" printed at *//* the top of each page and on the separator pages *//* Class X printer files get "Contents aren’t Confidential" printed *//* at the top of each page and on the separator pages *//*---------------------------------------------------------------------*/Printer_Title A ’No Security Rating’ BottomPrinter_Title C ’COMPANY XYZ CONFIDENTIAL’ TopPrinter_Title Q ’It’’s Not Confidential’Printer_Title X "Contents aren’t Confidential"Chapter 6. The System Configuration File 183

PRIV_CLASSESPRIV_CLASSES Statement►►PRIV_CLASSes(1)▼HW_Service FHW_Service classesIOCP_Read CEIOCP_Read classesIOCP_Write CIOCP_Write classesOPERator AOPERator classesUSER_DEFault GUSER_DEFault classes►◄Notes:1 You must specify at least one of the following operands.PurposeUse the PRIV_CLASSES statement to change the privilege classes authorizing thefollowing CP functions:v Logging on as the primary system operatorv Intensive error recordingv Using the read function of the CP IOCP utilityv Using the write function of the CP IOCP utilityv Specifying the default user class.How to SpecifyInclude as many statements as needed; they are optional. You can placePRIV_CLASSES statements anywhere in the system configuration file. If youspecify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.OperandsHW_Service classestells CP which class or classes are authorized to perform intensive errorrecording. The variable classes is a 1- to 8-character alphanumeric string fromA through Z and from 0 to 9. If omitted, the default is class F.IOCP_Read classestells CP which class or classes are authorized to use the read function of theIOCP utility. (For more information about the IOCP utility, see the z/VM: CPCommands and Utilities Reference book.) The variable classes is a 1- to8-character alphanumeric string from A through Z and from 0 to 9. If omitted,the default is classes CE.IOCP_Write classestells CP which class or classes are authorized to use the write function of theIOCP utility. (For more information about the IOCP utility, see the z/VM: CP184 z/VM: CP Planning and Administration

PRIV_CLASSESCommands and Utilities Reference book.) The variable classes is a 1- to8-character alphanumeric string from A through Z and from 0 to 9. If omitted,the default is class C.OPERator classestells CP which class or classes are for the primary system operator. Thevariable classes is a 1- to 8-character alphanumeric string from A through Z andfrom 0 to 9. If omitted, the default is class A.USER_DEFault classestells CP which class or classes to define for users who do not have a classspecified in their directory entries. The variable classes is a 1- to 8-characteralphanumeric string from A through Z and from 0 to 9. If omitted, the default isclass G.Examples1. To authorize:v The primary system operator for class A, C, and E commandsv Class C users to issue the IOCP READ and WRITEv Class D users to perform intensive error recordingv All users without classes defined in their directory entries for class Gcommandsuse the following PRIV_CLASSES statement:Priv_Classes,Operator ACE, /* Classes needed to be operator */IOCP_Write C, /* Class needed for IOCDS read */IOCP_Read C, /* Class needed for IOCDS write */HW_Service D, /* Class needed for intensive error *//* recording */User_Default G /* Default classes for general user */Chapter 6. The System Configuration File 185

PRODUCTPRODUCT Statement►►PRODIDPRODuct vmses_prodid STATE ENabledDISAbled DESCRiption stringDELete►◄PurposeUse the PRODUCT statement to define a product or feature to the system.How to SpecifyInclude as many statements as needed; they are optional. You can placePRODUCT statements anywhere in the system configuration file. If you specifymore than one statement with the same operands, the last operand definitionoverrides any previous specifications.OperandsPRODID vmses_prodidis the identifier used by VMSES/E to install and service the given product.vmses_prodid must be a 7 or 8 character identifier.STATE ENABLEDidentifies this product or feature as being licensed to run on this system.When a product is defined with STATE ENABLED, it indicates that the productis authorized by the installation to run on this system. It does not mean that theproduct is installed or is being used.STATE DISABLEDidentifies this product or feature as not being licensed to run on this system.The product may or may not be physically installed on the system.DESCRIPTION stringis a string of data that identifies additional information regarding the product.string is a 1-255 character string (including any imbedded blanks and specialcharacters) associated with the vmses_prodid entered. The string may beenclosed in single or double quotation marks. The text inside the quotationmarks is not translated to uppercase. The string is stored unchanged andwithout the delimiting quotation marks.If string is not delimited by quotation marks, it is translated to uppercase andmultiple blanks are compressed to a single blank.If you need to include a single quotation mark in the string, enclose the wholestring with double quotation marks. If you need to include a double quotationmark in the string, enclose the whole string with single quotation marks. Also,you may use two consecutive double quote marks ("") to represent a ″character within a string delimited by double quotation marks. Similarly, youmay use two consecutive single quotation marks ('') to represent a ' characterwithin a string delimited by single quotation marks.DELETEremoves from the system any definition information for the product ID,vmses_prodid.186 z/VM: CP Planning and Administration

PRODUCTUsage NotesExamples1. Each product is identified by a unique vmses_prodid. If a subsequentPRODUCT statement or SET PRODUCT command specifying an existingvmses_prodid is issued, it overwrites all of the related data including thedescription data.2. The DELETE operand is included for those installations that may choose tohave a common imbed for multiple systems with specific imbed statementsfollowing for each specific system.1. To define and enable RSCS (5684096K) to the system with a comment thatdescribes what the specified product ID identifies, use the following PRODUCTstatement:PRODUCT 5684096K STATE ENABLED DESCRIPTION ’RSCS Networking Version 3Release 2 Modification 0’2. To define and enable TCP/IP VM (5735FALQ) to the system with a commentthat describes what the specified product ID identifies, use the followingPRODUCT statement:PRODUCT 5735FALQ STATE ENABLED DESCRIPTION ’TCP/IP LEVEL 310 - TCP/IPFEATURE (BASE)’3. To define PVM and explicitly disable PVM (5684100E) to the system with acomment that identifies why the product is disabled, use the followingPRODUCT statement:PRODUCT 5684100E STATE DISABLED DESCRIPTION ’PVM FACILITY BASE - Disabled23-AUG-1997 after license expired.’4. To delete the entry for PVM (5684100E), use the following PRODUCTstatement:PRODUCT 5684100E DELETEA description is not allowed because all data for the product is discarded fromthe system when the DELETE operand is processed.5. To define and enable DITTO (5688025A) to the system, use the followingPRODUCT statement:PRODUCT 5688025A STATE ENABLEDA description was not entered, therefore, there is no tie between the enablementstatement for product ID 5688025A and DITTO.If the above PRODUCT statements were processed in the given order, you wouldreceive the following results after entering the Q PRODUCT command:Q PRODUCTProduct State Description5684096K Enabled RSCS Networking Version 3 Release 2 Modification 05688025A Enabled5735FALQ Enabled TCP/IP LEVEL 310 - TCP/IP FEATURE (BASE)Chapter 6. The System Configuration File 187

RDEVICERDEVICE StatementPurposeUse the RDEVICE statement to add to the system’s definition of a set of real I/Odevices. The sections below describe the syntax of the RDEVICE statements forthe following devices:v Dedicated advanced function printers (page 189)v Card punches (page 190)v Card readers (page 192)v Communication controllers and line adapters (page 193)v DASD (page 195)v Graphic display devices (page 197)v Impact printers (page 201)v Special devices (page 205)v Tape units (page 207)v Unsupported devices (page 209)v 3800 printers (page 212).How to SpecifyInclude as many statements as needed; they are optional. You can place RDEVICEstatements anywhere in the system configuration file.If you specify more than one statement with the real device number, CP uses thelast statement. For example, if you specify:Rdevice 0500 Type 3800 Model 1 AFP yes Chars gf10.Rdevice 0500 Type AFPCP defines a dedicated advanced function printer at real device number 0500, not a3800 printer.UsageNotes1. If an IODF statement is defined in the system configuration file with the osconfigparameter specified, then the software I/O configuration will be controlled byHCD. In this case, the RDEVice statement is ignored if it is specified. Refer to“IODF Statement” on page 158 for more information.2. If you try to redefine the system residence or parm disk volume, CP will issuethe following message:HCP6751E Device rdev cannot be defined because it is the {SYSRES|parmdisk} volume.3. The RDEVICE statement cannot be used to change a current static devicedefinition that exists in HCPRIO. When this redefinition is detected, you will seethe following message:HCP6895E RDEV rdev cannot be changed or deleted because it is staticdevice definition from HCPRIO188 z/VM: CP Planning and Administration

RDEVICE (Advanced Function Printers)RDEVICE Statement (Advanced Function Printers)►► RDEVice rdevrdev-rdevTYpe AFP ►◄PurposeUse this RDEVICE statement to define one or more dedicated advanced functionprinters to CP. CP supports the following advanced function printers using advancedfunction printing licensed programs:3800 13820 23835 39003825 3827 38281. Supported only for models 3, 6, and 8.2. Supported only when the 3820 printer is channel-attached.Note: Printers defined as advanced function printers that follow the CCUspecifications can be used only as dedicated devices.Operandsrdevrdev-rdevis the real device number (or numbers) of the dedicated advanced functionprinter that you want defined. The maximum number of devices allowed within arange is 256. Each rdev must be a hexadecimal number between X'0000' andX'FFFF'.TYpe AFPtells CP that the real device (or devices) that you are defining are dedicatedadvanced function printers (AFP) that follow the CCU specification. Note thatprinters defined as TYPE AFP can only be used as dedicated devices.For more information about advanced function printers, see the PSF/VM SystemProgramming Guide.Examples1. To define a dedicated advanced function printer at real device number 0110,use the following RDEVICE statement:Rdevice 0110 Type AFP2. To define three dedicated advanced function printers at real device numbers0111, 0112, and 0113, use one of the following RDEVICE statements:Rdevice 0111-0113 Type AFP3. To define three dedicated advanced function printers at real device numbersE20, F10, and 1F00, use the following RDEVICE statements:Rdevice e20 Type AFPRdevice f10 Type AFPRdevice 1f00 Type AFPChapter 6. The System Configuration File 189

RDEVICE (Card Punches)RDEVICE Statement (Card Punches)►► RDEVice rdevrdev-rdevTYpePCHPUNch(1)NO_SPOOLing▼CLasses ACLasses classes*FOrm STANDARDFOrm form*►◄Notes:1 You must specify at least one of the following operands.PurposeUse this RDEVICE statement to define one or more card punches to CP. CPsupports the following card punch:3525 11. Supported only for punching; the printing features are not supported.Operandsrdevrdev-rdevis the real device number (or numbers) of the card punch that you want defined.The maximum number of devices allowed within a range is 256. Each rdevmust be a hexadecimal number between X'0000' and X'FFFF'.TYpe PCHTYpe PUNchtells CP that the real device (or devices) that you are defining are cardpunches. Note that CP only supports the 3525 for punching; the printingfeatures are not supported.NO_SPOOLingtells CP not to use the card punch for spooling.CLasses classesCLasses *defines the output spooling class or classes that the card punch may process.Each class is one alphanumeric character and you can specify up to eightclasses. If you specify more than one class, do not include any blanks betweenclasses (for example, CLASSES ABC). If omitted, the default is A. If specifiedas an asterisk (*), the card punch can process any file, regardless of class.To change the spooling class without having to re-IPL, use the CP START URcommand. For more information, see the z/VM: CP Commands and UtilitiesReference.FOrm formFOrm *defines the 1- to 8-character spooling form number that the card punch can190 z/VM: CP Planning and Administration

RDEVICE (Card Punches)process. When the operator starts the device after a cold start and does notspecify a form, CP uses the form specified on this RDEVICE statement. Ifomitted, the default is STANDARD. If specified as an asterisk (*), the cardpunch can process any file, regardless of form number.Examples1. To define a card punch at real device number 0120, use the following RDEVICEstatement:Rdevice 0120 Type Punch2. To define three card punches at device numbers 0121, 0122, and 0123, and toindicate that they can process any file regardless of form number, use one ofthe following RDEVICE statements:Rdevice 0121-0123 Type Punch Form *3. To define a card punch at device number 124 that processes class A files andfour card punches that process files with spooling form number XYZ and classZ, use the following RDEVICE statements:Rdevice 124 Type Punch Class aRdevice 125-128 Type Punch Form xyz Class zChapter 6. The System Configuration File 191

RDEVICE - Card ReadersRDEVICE Statement (Card Readers)►► RDEVice rdevrdev-rdevTYpeRDRREADerCLass ACLass cNO_SPOOLing►◄PurposeUse this RDEVICE statement to define one or more real card readers to CP. CPsupports the following card readers:3505OperandsExamplesrdevrdev-rdevis the real device number (or numbers) of the card reader that you wantdefined. The maximum number of devices allowed within a range is 256. Eachrdev must be a hexadecimal number between X'0000' and X'FFFF'.TYpe RDRTYpe READertells CP that the real device (or devices) that you are defining are card readers.CLass cdefines the 1-character alphanumeric spooling class that the card readerassigns to spool files it creates. If omitted, the default is A.To change the spooling class without having to re-IPL, use the CP START URcommand. For more information, see the z/VM: CP Commands and UtilitiesReference.NO_SPOOLingtells CP not to use the card reader for spooling.1. To define a card reader at device number 0130, use the following RDEVICEstatement:Rdevice 0130 Type Reader2. To define three card readers at device numbers 0131, 0132, and 0133, and toindicate that CP should not use them for spooling, use one of the followingRDEVICE statements:Rdevice 0131-0133 Type Reader No_Spooling3. To define a card reader at device number 134 that creates class W spool files,use the following RDEVICE statement:Rdevice 134 Type Reader Class w192 z/VM: CP Planning and Administration

RDEVICE (Communication Controllers)RDEVICE Statement (Communication Controllers)►► RDEVice rdevrdev-rdevTYpeSET_ADDRess 4BSC_ADAPTerIBM1_ADAPTer SET_ADDRess nTELE2_ADAPTer3705►◄PurposeUse this RDEVICE statement to define one or more real communication controllersor line adapters to CP. CP supports the following communication controllers andline adapters:3705 3720 3725 3745Note: CP supports the BSC adapter as dedicated only.Operandsrdevrdev-rdevis the real device number (or numbers) of the communication controller or lineadapter that you want defined. The maximum number of devices allowed withina range is 256. Each rdev must be a hexadecimal number between X'0000' andX'FFFF'.TYpetells CP that the real devices you are defining are:BSC_ADAPTertells CP that you are defining one or more IBM Binary SynchronousTerminal Control Type II devices for a 3705, 3725, or 3745. (The BSCadapter is supported as dedicated-only.)IBM1_ADAPTertells CP that you are defining one or more IBM Terminal Adapter Type Iattaches a 2741 to a 3705, 3725, or 3745.TELE2_ADAPTertells CP that you are defining one or more CPT-TWX (Models 33 or 35)Terminal, 3101, 3151, 3161, 3162, or 3163 attaches to a Line InterfaceBase Type I in a 3705, 3725, or 3745.SET_ADDRess ntells CP which set address (SAD) command to enter for atelecommunication line attached to a control unit. The variable n is a1-character decimal number between 0 and 4, with a default of 4. Thevariable n can be:0 tells CP to enter a SADZERO command.1 tells CP to enter a SADONE command.2 tells CP to enter a SADTWO command.3 tells CP to enter a SADTHREE command.4 (the default) tells CP not to enter a SAD command.Chapter 6. The System Configuration File 193

RDEVICE (Communication Controllers)3705defines the base address used to load the 3705 communications controller.UsageNotes1. You must define the base (load) address of a 3705 communications controllerusing the RDEVICE TYPE 3705 statement, using the CP SET RDEVICE TYPE3705 command, or by genning the 3705 base address in HCPRIO. Although thisis not a requirement for the 3720, 3725, or 3745 base addresses (because theycan be sensed dynamically), you may also define the base addresses for thesedevices as TYPE 3705 in this same manner. For more information about the CPSET RDEVICE command, see the z/VM: CP Commands and UtilitiesReference.2. For all emulated lines running EP or NCP (PEP), you must have an RDEVICEstatement for every line and the lines must be in the DEVICES NOT_SENSEDlist.If you do not want to use RDEVICE statements in your system configuration file,you can use the CP SET RDEVICE command. However, the emulated linesmust still be in the DEVICES NOT_SENSED list. If you fail to do this, the linesmay not come online and you will not be able to correct this situation withoutIPLing the system again.3. Because emulator lines cannot be sensed dynamically, you should define all EPor NCP (PEP) emulator lines using either an RDEVICE statement or the CPSET RDEVICE command. The valid line types are:vvvBSC_ADAPTERIBM1_ADAPTERTELE2_ADAPTERExamples1. To define an IBM Terminal Adapter Type 1 at device number 01F0, use thefollowing RDEVICE statement:Rdevice 01F0 Type IBM1_Adapter2. To define three BSC Terminal Control Type II adapters at device numbers 01F1,01F2, and 01F3, use one of the following RDEVICE statements:Rdevice 01F1-01F3 Type BSC_Adapter3. To define an IBM 3705 communication controller at device address 004, and 63161, 3162, and 3163 lines at device addresses 030 through 035, use thefollowing RDEVICE statements:Rdevice 004 Type 3705 /* 3705 load address */Rdevice 010-02F Type BSC_Adapter /* Bisync lines for PVM */Rdevice 030-035 Type TELE2_Adapter /* 316x ASCII lines */194 z/VM: CP Planning and Administration

RDEVICE (DASD)RDEVICE Statement (DASD)►► RDEVice rdevrdev-rdevTYpeDASDSHAREdSHAREdNoYesMDCMDCMDCDFLTONOFFDFLTOFF►◄PurposeUse this RDEVICE statement to define one or more real direct access storagedevices (DASD) to CP. CP supports the following DASD:3380 3390 9336These DASD types do respond to the sense ID request instruction; you need tospecify RDEVICE statements for them only if you want to specify the SHAREDYES, the MDC OFF, or the MDC DFLTOFF options.A Note About the 3850 Mass Storage SystemVM/ESA Release 1.1 was the last release to support the IBM 3850 MassStorage System. Therefore, new function (like the system configuration file)does not support the 3850. When devices are no longer supported, you mayfind that the existing code has not be removed from the product. If you have a3850, you may still be able to use it by coding an RDEVICE macroinstructionin HCPRIO ASSEMBLE. For more information, see “DASD Types” on page746.Operandsrdevrdev-rdevis the real device number (or numbers) of the DASD that you want defined. Themaximum number of devices allowed within a range is 256. Each rdev must bea hexadecimal number between X'0000' and X'FFFF'.TYpe DASDtells CP that the real device (or devices) that you are defining are DASD.SHAREdtells CP whether you want the device or devices to be shared concurrentlyamong multiple real systems.No(the default) tells CP not to share the device or devices among multiple realsystems.Yestells CP to share the device or devices among multiple real systems. Formore information on sharing DASDs, see Chapter 21, “DASD Sharing,” onpage 619.Chapter 6. The System Configuration File 195

RDEVICE (DASD)UsageNotesMDCtells CP whether you want the device or devices to be cached in the minidiskcache.DFLTON(the default if the SHARED option is not specified or the SHARED NOoption is specified.) Tells CP to cache data on the real device in theminidisk cache except for minidisks that have caching specifically disabledby the MINIOPT NOMDC directory statement or the SET MDCACHEMDISK OFF command.OFF(the default if the SHARED YES option is specified.) Tells CP to not cachedata on the real device in the minidisk cache.DFLTOFFtells CP to not cache data on the real device in the minidisk cache exceptfor minidisks that have caching specifically enabled by the MINIOPT MDCdirectory statement or the SET MDCACHE MDISK ON command.1. Not all DASD types are eligible for caching in the minidisk cache. If you specifyMDC DFLTON or MDC DFLTOFF for a device that is not cache eligible, data onthat device will not be cached.Examples1. To define a shared DASD with minidisk caching off at device number 0410, usethe following RDEVICE statement:Rdevice 0410 Type DASD Shared yes2. To define 64 shared DASDs with minidisk caching off at device numbers 100through 13F and 32 shared DASDs at device numbers 140 through 15F, use thefollowing RDEVICE statements:Rdevice 100-13f Type Dasd Shared yes /* 3390 Dasd shared with *//* other 2064 ... */Rdevice 140-15f Type Dasd Shared yes /* 3380 Dasd shared with *//* 2064 ... */3. To define a non-shared DASD with minidisk caching on, no RDEVICE statementis necessary.4. To define a non-shared DASD at device number 500 with minidisk cachingenabled on a device only for those minidisks that have specifically enabledcaching, use the following RDEVICE statement:Rdevice 500 Type Dasd MDC DFLTOFF196 z/VM: CP Planning and Administration

RDEVICE (Graphic Display Devices)RDEVICE Statement (Graphic Display Devices)►► RDEVice rdev TYpe TYPE Operandsrdev-rdev►◄TYPEOperandsMODel 23178 Options3179 MODel 2A3180 2C3190 33270 43278 532793290MODel 23270_DISPlay327732843286328732883289Options▼EMULATED_3270 NoEMULATED_3270YesOPER_IDENT_READerOPER_IDENT_READerHOLDHOLDNoYesNoYesPurposeOperandsUse this RDEVICE statement to define one or more graphic display devices to CP.rdevrdev-rdevis the real device number (or numbers) of the graphic display devices that youwant defined. The maximum number of devices allowed within a range is 256.Each rdev must be a hexadecimal number between X'0000' and X'FFFF'.TYpe 3178, 3179, 3180, 3190, 3270, 3278, 3279, or 3290tells CP that the real device (or devices) that you are defining are graphicdisplay devices. CP can determine dynamically all of these graphic displaydevices during initialization or when you vary on the device. You only need tospecify these graphic display devices if you want to specify the extendedattributes.Chapter 6. The System Configuration File 197

RDEVICE (Graphic Display Devices)MODel 2, 2A, 2C, 3, 4, or 5is the model number of the graphic display device. If omitted, the default isModel 2.TYpe 3270_DISPlay or 3277tells CP that the real device (or devices) that you are defining are graphicdisplay devices. CP can determine dynamically all of the 3270 graphic displaydevices during initialization or when you vary on the device. You only need tospecify the 3270 graphic display devices if you want to specify the extendedattributes.Note: The 3270-PC is supported in control-unit terminal mode anddistributed-function terminal (DTF) mode when defined as a 3270.You must specify the 3277 display because its device type cannot bedetermined.MODel 2is the model number of the graphic display device. If omitted, the default isModel 2.TYpe 3284, 3286, 3287, 3288, or 3289tells CP that the real device (or devices) that you are defining are graphicprinter devices. CP can determine dynamically all of the graphic printer devicesduring initialization or when you vary on the device; therefore, you do not needto specify them.Note: CP cannot sense these devices when they are attached either to a 3174or a 3274 control unit. If these devices are attached to a 3174 or a 3274control unit, each device must be defined in the system configuration fileusing the RDEVICE statement.EMULATED_3270 No(the default) tells CP that this device (or devices) is not a TTY ASCII displayterminal connected to the system through a 7171 ASCII DACU or ASCIISubsystem (an emulated 3270).EMULATED_3270 Yestells CP that this device (or devices) is a TTY ASCII display terminal connectedto the system through a 7171 ASCII DACU or ASCII Subsystem (an emulated3270).Note: The 3101 must be connected to a 7171 Control Unit. You must alsospecify EMULATED_3270 YES.HOLD No(the default) tells CP not to keep the display terminal telecommunicationsconnection to the 7171 ASCII DACU or ASCII Subsystem after the virtualmachine logs off or disconnects.HOLD Yestells CP keep the display terminal telecommunications connection to the7171 ASCII DACU or ASCII Subsystem after the virtual machine logs off ordisconnects.OPER_IDENT_READer No(the default) tells CP that the 327x display does not have an operatoridentification card reader.OPER_IDENT_READer Yestells CP that the 327x display has an operator identification card reader. If you198 z/VM: CP Planning and Administration

RDEVICE (Graphic Display Devices)UsageNotesspecify OPER_IDENT_READER YES, the virtual machine operator can gainaccess to the system (log on) only by inserting a magnetically encoded card.Use of a badge reader is optional for each user ID and not required for any ofthem. Use of a badge reader cannot replace entering a correct password butmay follow a correct password as an additional security measure. If you do notwant to have a card reader authorize access, do not specifyOPER_IDENT_READER YES, or specify OPER_IDENT_READER NO.1. For a complete list of all graphic displays and printers supported for this release,see Chapter 5, “Defining I/O Devices,” on page 45.2. You must ensure that the device numbers specified on the statementcorrespond to the device numbers required for the category of display terminalin the controller.3. Refer to the 7171 Device Attachment Control Unit Reference Manual andProgramming Guide to determine which type of device (TYPE) to specify for aTTY ASCII terminal attached to a 7171 DACU or ASCII Subsystem.4. The 3178, 3179, 3180, 3190, 3278, 3279, 3284, 3486, 3287, 3288, 3289, and3290 devices are defined primarily for use with second-level systems. In asecond-level system, you can define a printer or display to be at a particulardevice number and then you can do a first-level define of the device number. Ifyou define the device in the system configuration file, the second-level systembrings that device online immediately rather than having you define a devicenumber first-level, issue the CP SET RDEVICE command second-level, andvary on the device second-level.Examples1. To define a 3277 display at device number 0210, use the following RDEVICEstatement:Rdevice 0210 Type 32772. To define three 3270 displays at device numbers 0211, 0212, and 0213, and toindicate that users should not be able to log on to them without an operatoridentification card, use the following RDEVICE statement:Rdevice 0211-0213 Type 3270_Display Oper_Ident_Reader yes3. To define:v 48 3270 displays at device numbers 800 through 82Fv 16 3277 displays at device numbers 830 through 83Fv 31 3278 displays at device numbers 970 through 98Ev One 3287 display at device number 98Fv One 3290 display at device number 1010v 15 3190 displays at device numbers 1011 through 101Fv 61 3278 displays at device numbers 200 through 23C, which are TTY ASCIIdisplay terminals connected to the system through 7171 ASCII DACU orASCII Subsystems, and which retain their connections after logging off ordisconnectinguse the following RDEVICE statements:Rdevice 800-82f Type 3270_Display /* 3174 controller *//* ... with 32 local ports */Rdevice 830-83f Type 3277 /* 3272 controller *//* ... with 16 3277 displays */Rdevice 970-98e Type 3278 /* 3274 controller *//* ... with 31 3178s and 3278s */Chapter 6. The System Configuration File 199

RDEVICE (Graphic Display Devices)Rdevice 98f Type 3287 /* 3287 printer *//* ... hung off 3274 port 32 */Rdevice 1010 Type 3290 /* 3290 information display on *//* ... port 0 of 3174 control *//* ... unit */Rdevice 1011-101f Type 3190 /* 15 3190s on *//* ... 3174 control unit */Rdevice 200-23c Type 3278, /* 7171 ports looking like */Emulated_3270 yes, /* ... 3278s to CP */Hold yes200 z/VM: CP Planning and Administration

RDEVICE (Impact Printers)RDEVICE Statement (Impact Printers)►► RDEVice rdevrdev-rdevTYpeIMPact_printer32033211NO_SPOOLing▼AFP YesAFP NoCHARS ucsnameCLasses ACLasses classesDEST OFFDEST *►◄(1)▼ DEST destFCB fcbnameFOLDup NoFOLDup YesFOrm STANDARDFOrm formIMAGE_LIBrary imagelibINDex 1INDex nnLIMit NoneLIMit nnnnnnnnnnSEParator YesSEParator NoUNIVERSAL_CHARset NoUNIVERSAL_CHARset YesNotes:1 You cannot specify more than four output destinations.PurposeUse this RDEVICE statement to define the following system-managed,channel-attached impact printers to CP:3203 162623211 23262 4245 42481. Only the 3203 Model 5 is supported.2. 3211 printers are only supported as emulated by other printers.Operandsrdevrdev-rdevis the real device number (or numbers) of the impact printer that you wantdefined. The maximum number of devices allowed within a range is 256. Eachrdev must be a hexadecimal number between X'0000' and X'FFFF'.TYpe IMPact_printerTYpe 3202Chapter 6. The System Configuration File 201

RDEVICE (Impact Printers)TYpe 3211tells CP that the real device (or devices) that you are defining is one of theimpact printers listed above.NO_SPOOLingtells CP not to use the impact printer for spooling.AFP Yes(the default) tells CP that the impact printer can process files with advancedfunction printer (AFP) characteristics, XABs, or X'5A' CCWs.AFP Notells CP that the impact printer cannot process files with advanced functionprinter (AFP) characteristics, XABs, or X'5A' CCWs.CHARS ucsnameFor a printer with the UNIVERSAL_CHARSET feature, CHARS ucsnamespecifies the 1- to 4-character suffix of the name of the default universalcharacter set (UCS) buffer image. The variable ucsname must correspond toone of the UCS images stored in the image library. For example, if you specify:Rdevice 0003 Type 3203 Chars anThe image library must contain a member named 3203AN.CLasses classesdefines the output spooling class or classes that the impact printer can print.Each class is 1 alphanumeric character and you can specify up to 8 classes. Ifyou specify more than one class, do not include any blanks between theclasses (for example, CLASSES ABC). If omitted, the default is A. If specifiedas an asterisk (*), the printer can process any file, regardless of class.To change the spooling classes without having to re-IPL, use the CP STARTUR command. For more information about the CP START UR command, seethe z/VM: CP Commands and Utilities Reference.DEST OFFDEST *DEST destspecifies the output destination values the printer can print. Specify DEST inone of the following ways:v By default — if you omit the DEST operand, DEST OFF is assumed.v You can specify as many as four destination values by entering four differentDEST operands, as follows:Dest printer1 Dest printer2 Dest printer3 Dest printer4v DEST * specifies that the printer should process files regardless ofdestination.To change the spooling destinations without having to re-IPL, use the CPSTART UR command. For more information about the CP START URcommand, see the z/VM: CP Commands and Utilities Reference.FCB fcbnamespecifies the 1- to 4-character alphanumeric suffix of the name of the defaultforms control buffer (FCB) CP should use after a cold start or force start. Thismust correspond to one of the FCB images added to an image library. Forexample, if you specify:Rdevice 0003 Type 3203 FCB fcb8The image library must contain a member named 3203FCB8.202 z/VM: CP Planning and Administration

RDEVICE (Impact Printers)FOLDup No(the default) tells CP not to fold (translate) lowercase into uppercase.FOLDup Yestells CP to fold (translate) lowercase into uppercase.FOrm STANDARDFOrm formis the current spooling form number that the printer can process. This form isthe default operator form for the real printer when the operator starts the deviceafter a cold start without specifying a form. Specify FORM in one of thefollowing ways:v FORM form (form is a 1- to 8-character operator form number for the files theprinter can process)v FORM * indicates that the printer can process files regardless of formnumberv FORM STANDARD indicates that the type of paper to be mounted on theprinter is the type of paper that the installation has assigned the nameSTANDARD. Each installation establishes its own set of form names, assignsthose form names to types of paper, and informs the operations staff and endusers of the correlation between form names and types of paper.If omitted, the default is STANDARD.IMAGE_LIBrary imagelibtells CP which image library to use after a cold start. If omitted, the default isIMAGE_LIBRARY nnnn (nnnn is the device type number).INDex nnspecifies the position at which to start printing. The variable nn is a decimalnumber from 1 to 31. If omitted, the default is 1.Note: The INDEX operand is only valid for 3211 printers. If you specify it foranother impact printer, CP ignores the operand.LIMit None(the default) tells CP that this impact printer can print files with an unlimitednumber of records.LIMit nnnnnnnnnntells CP that this impact printer limits the size of files it can print. The variablennnnnnnnnn is a 1- to 10-digit decimal number that indicates the maximumnumber of records per file that this printer can print.SEParator Yes(the default) tells CP to print separator pages between output files.SEParator Notells CP not to print separator pages between output files.UNIVERSAL_CHARset No(the default) tells CP that this impact printer is not a universal character setprinter.UNIVERSAL_CHARset Yestells CP that this impact printer is a universal character set printer.Note: Although UNIVERSAL_CHARset Yes is accepted for TYpe IMPactprinter, it is only meaningful for TYpe 3203 and TYpe 3211 printers.Chapter 6. The System Configuration File 203

RDEVICE (Impact Printers)Examples1. To define a 3203 printer at device number 0110 that prints only class A spoolfiles (the default value), use the following RDEVICE statement:Rdevice 0110 Type Impact_Printer2. To define a 3262 printer at device number 0110 that will be dedicated to aguest, use the following RDEVICE statement:Rdevice 0110 Type Impact_Printer No_Spooling3. To define an impact printer at device number:v E0E that can print class 1, process “standard” forms, and use the “normal”output destination, forms control buffer FCB8, and image library 4245IMAGv 00E that can print class A files, use forms control buffer FCB8, and processFORM8 formsv 01E that can print class A files, use forms control buffer FCB8, and processFORM1 formsuse the following RDEVICE statements:Rdevice e0e Type Impact_Printer,Class 1,Dest normal,FCB fcb8,Image_Library 4245IMAG,Form standardRdevice 00e Type 3203,Class a,FCB fcb8,Form form8Rdevice 01e Type 3211, /* 4248 printer running in 3211 */Class a, /* compatibility mode */FCB fcb8,Form form1204 z/VM: CP Planning and Administration

RDEVICE (Special Devices)RDEVICE Statement (Special Devices)►► RDEVice rdevrdev-rdevTYpeCTCaFCPHIPERSocketsLAN_ADAPTerOSA►◄PurposeOperandsUse this RDEVICE statement to define device addresses of certain types of devicesto CP.rdevrdev-rdevis the real device number (or numbers) of the devices that you want defined.The maximum number of devices allowed within a range is 256. Each rdevmust be a hexadecimal number between X'0000' and X'FFFF'.TYpe CTCatells CP that the real device (or devices) that you are defining is achannel-to-channel device.UsageNotesNote: Specify a 3737 Remote Channel-to-Channel Unit Model 2 as a CTCA.TYpe FCPtells CP that the real device (or devices) that you are defining is aFiber-Channel-Protocol device.TYpe HIPERSocketstells CP that the real device (or devices) that you are defining is a HiperSocketsdevice.TYpe LAN_ADAPTertells CP that the real device (or devices) that you are defining is achannel-attached 8232 or 3172 representing a local area network.TYpe OSAtells CP that the real device (or devices) that you are defining is anOpen-Systems-Adapter device.1. CP can sense 3172 and 8232 devices. Therefore you do not need to specifythem in the system configuration file, unless you are running programs in thedevice that do not respond to sense ID requests.Examples1. To define a channel-to-channel adapter at device number 0250, use thefollowing RDEVICE statement:Rdevice 0250 Type CTCA2. To define a local area network adapter at device number 0251, use the followingRDEVICE statement:Chapter 6. The System Configuration File 205

RDEVICE (Special Devices)Rdevice 0251 Type LAN_Adapter3. To define an Open-Systems-Adapter device at device number 0252, use thefollowing RDEVICE statement:Rdevice 0252 Type OSA4. The following RDEVICE statements define:v 48 channel-attached 3172s at device numbers 700 through 72Fv 48 channel-attached 8232s at device numbers 600 through 62Fv One channel-to-channel adapter at device address 250/*-------------------------------------------------------------------*//* 3172 LAN attached control unit - LAN adapter looks like a 3088 to *//* CP. Note: you do not have to have a statement for 3088 *//* looking devices ... *//*-------------------------------------------------------------------*/Rdevice 700-72f Type LAN_Adapter/*-------------------------------------------------------------------*//* 8232 LAN attached control unit - Note: 8232s look like 3088s to *//* CP but sometimes, the software does not respond correctly so *//* you can be assured it is a 3088 device if you gen it as *//* LAN_Adapter *//*-------------------------------------------------------------------*/Rdevice 600-62f Type LAN_Adapter/*-------------------------------------------------------------------*//* Real CTCA to 4381, 4381 owns CTCA *//*-------------------------------------------------------------------*/Rdevice 250 Type CTCA206 z/VM: CP Planning and Administration

RDEVICE (Tape Units)RDEVICE Statement (Tape Units)►► RDEVice rdevrdev-rdevTYpe 3422TAPE►◄PurposeOperandsUse this RDEVICE statement to define one or more tape units to CP.rdevrdev-rdevis the real device number (or numbers) of the tape unit that you want defined.The maximum number of devices allowed within a range is 256. Each rdevmust be a hexadecimal number between X'0000' and X'FFFF'.TYpe 3422tells CP that the real device (or devices) that you are defining is an IBM 3422magnetic tape subsystem.TYpe TAPEspecifies an IBM tape unit that can be dynamically sensed by CP (such as anIBM 3424, 3480, 3490, 3590, or 9348 tape unit).UsageNotes1. CP can dynamically sense most tape units at IPL time (such as the IBM 3480and 3490 tape units), so there is no need for an RDEVICE statement for thoseunits. However, if you decide to define one of these type of tape units to CPwithout it being connected to the system at IPL time, you can use the RDEVICEstatement with the TYPE TAPE operand.Examples1. To define a 3422 tape unit at device number 0310, use the following RDEVICEstatement:Rdevice 0310 Type 34222. To define eight 3422 tape drives at device numbers F10 through F17, use thefollowing RDEVICE statements:/*-------------------------------------------------------------------*//* We do not have to specify RDEVICE statements for our: *//* *//* 3490s at 100-10F because they answer with their device type *//* when asked (sensed). *//* *//* 3480s at 500-50F because they answer with their device type *//* when asked (sensed). *//* *//*-------------------------------------------------------------------*//*-------------------------*//* Define our eight 3422s: *//*-------------------------*/Rdevice f10-f17 Type 3422Chapter 6. The System Configuration File 207

RDEVICE (Tape Units)3. To define a tape unit which can be dynamically sensed by CP at device number0F20, use the following RDEVICE statement:Rdevice 0F20 Type Tape208 z/VM: CP Planning and Administration

RDEVICE (Unsupported Devices)RDEVICE Statement (Unsupported Devices)►► RDEVice rdevrdev-rdevTYpe UNSUPported ►►DEVCLassDASD▼DPS NoDPS YesRESERVE_RELeaseNo►◄RESERVE_RELeaseYesPRINTerPUNchREADerSWITchDPS NoTAPeDPS YesTERMinal3270_DISPlay3270_PRINTerPurposeUse this RDEVICE statement to define one or more unsupported devices to CP.Note: When you define an unsupported device, you must dedicate the device to avirtual machine. To do this, specify the DEDICATE directory controlstatement in the virtual machine’s directory statement or issue the CPATTACH command. For more information about the DEDICATE statement,see page 477. For more information about the CP ATTACH command, seethe z/VM: CP Commands and Utilities Reference book.Operandsrdevrdev-rdevis the real device number (or numbers) of the unsupported device that you wantdefined. The maximum number of devices allowed within a range is 256. Eachrdev must be a hexadecimal number between X'0000' and X'FFFF'.TYpe UNSUPportedtells CP that this is an unsupported device type.DEVCLassis the device class of the unsupported device. Valid classes are:Class Unsupported Device TypeDASDDirect access storage devicesChapter 6. The System Configuration File 209

RDEVICE (Unsupported Devices)PRINTerUnit record printer devicesPUNchUnit record punch devicesREADerUnit record input devicesSWITchDynamic switching devices.TAPe Tape devicesTERMinalTerminals3270_DISPlay3270 display devices3270_PRINTer3270 printer devicesDPS Yestells CP that the unsupported DASD or tape device supports the dynamic pathselection (DPS) function: CCW command codes X'34', Sense Path GroupIdentifier (SNID), and X'AF', Set Path Group Identifier (SPID).When you specify DPS YES, CP places VM’s path group identifier (PGID) inthe device’s control unit for each path to the control unit. This placementenables the use of a single PGID for all devices connected to the control unit,regardless of the number of guests that might be using the different devices onthe control unit, how many times a given guest is re-IPLed, or how a givendevice might be shifted from one guest to another over time. A guest operatingsystem, such as IBM’s MVS/XA or MVS/ESA , has an alternate-PGIDcapability so it can deal with the VM PGID on these channel paths.DPS No(the default) tells CP that the unsupported DASD or tape device does notsupport the dynamic path selection (DPS) function.When you specify DPS NO, VM takes no action with regard to path groups orPGIDs. It is the responsibility of the guest to which the unsupported DASD ortape device is dedicated or attached to form and maintain path groups, ifdesired, using the guest’s own PGID. The use of a guest’s PGID is oftencumbersome if not unworkable for DPS devices, because a PGID on a channelpath to a control unit applies to all devices connected to the control unit, and aPGID can only be changed after clearing any previous PGID with asystem-reset of the channel path or paths.If the guest operating system to which the device will be dedicated or attacheddoes not contain alternate PGID support, specify DPS NO.RESERVE_RELease Yestells CP that the unsupported DASD supports the reserve/release function:CCW command codes X'B4', Device Reserve (RES), X'94', Device Release(REL), and X'14', Unconditional Reserve (UR).When you specify RESERVE_RELEASE YES for an unsupported DASD, CPissues the DEVICE RELEASE CCW command to the device whenever thevirtual machine to which the device is dedicated or attached is reset by the CPSYSTEM CLEAR, SYSTEM RESET, or IPL commands.RESERVE_RELease No(the default) tells CP that the unsupported DASD does not support thereserve/release function. If you specify RESERVE_RELEASE NO for anunsupported DASD that contains support for the reserve/release function, a210 z/VM: CP Planning and Administration

RDEVICE (Unsupported Devices)malfunction of the guest to which the device is dedicated or attached mightleave a device reservation held by the guest, preventing the device from beingaccessed by other sharing systems.Examples1. To define an unsupported DASD, use the following RDEVICE statement:Rdevice 0fff Type UnSupported DevClass DASD2. To define an unsupported DASD that supports dynamic path selection, use thefollowing RDEVICE statement:Rdevice 0fe0 Type UnSupported DevClass DASD DPS yes3. To define an unsupported DASD that supports both dynamic path selection andreserve/release, use the following RDEVICE statement:Rdevice 0fd0 Type UnSupported,DevClass DASD,DPS yes,Reserve_Release yes4. To define 4 unsupported tape devices and 23 unsupported DASD that supportboth dynamic path selection and reserve/release, use the following RDEVICEstatements:Rdevice 2040-2043 Type Unsupported, /* Unsupported tape */DevClass Tape /* device */Rdevice 1280-1296 Type Unsupported, /* Unsupported DASD supporting */DevClass DASD, /* reserve/release CCW and */DPS yes, /* dynamic path selection CCW */Reserve_Release yesChapter 6. The System Configuration File 211

RDEVICE (3800 Printers)RDEVICE Statement (3800 Printers)►► RDEVice rdevrdev-rdevTYpe 3800MODel 1(1)►◄MODel 13 (2)6 OptionsNO_SPOOLing8Options:AFP YesAFP No CHARS ffffCLassesCLassesAclassesDEST OFF(3)▼ DESTdestDPMSIZE 1DPMSIZEn►►FCB 6FCB lpi FLASH flashlibFOrmFOrmSTANDARDoperformIMAGE_LIBraryIMAGE_LIBraryIMAG3800imagelib►►LIMitLIMitNonennnnnnnnnnSEParatorSEParatorYesNoMARKYesMARK No (4)WCGM 24Notes:1 The defaults you receive appear above the line in the Options fragment.2 The following operands can be specified in any order.3 You cannot specify more than four output destinations.4 This operand can only be specified for model 1.PurposeOperandsUse this RDEVICE statement to define 3800 and 3900 printers to CP.rdevrdev-rdevis the real device number (or numbers) of the 3800 printer that you wantdefined. The maximum number of devices allowed within a range is 256. Eachrdev must be a hexadecimal number between X'0000' and X'FFFF'.TYpe 3800tells CP that the real device (or devices) that you are defining is a 3800 printer.212 z/VM: CP Planning and Administration

RDEVICE (3800 Printers)MODel 1, 3, 6, or 8tells CP the model number of the 3800 printer that you are defining. The defaultvalue is 1.Notes:1. The 3800 Models 3 and 6 are supported in Model 1 compatibility mode,defined as a Model 1, or by using the Advanced Function Printing licensedprogram, defined as a Model 3 or as a Model 6. If you are using them asadvanced function printers, specify AFP YES.2. The 3800 Model 8 is supported using an Advanced Function Printinglicensed program.NO_SPOOLingtells CP not to use the 3800 printer for spooling.AFP YesAFP Nospecifies whether the printer is to process files with advanced function printer(AFP ) characteristics, XABs, or X'5A' CCWs. The default is YES.CHARS ffffspecifies the name of a character-arrangement table for the separator page tobe used after a cold start. The default values for 3800 printers areFor Model 1, CHARS GF10.For Model 3 or Model 6, CHARS GF12.CLasses classesdefines the output spooling class or classes that the 3800 Model 1, Model 3, orModel 6 printer can print. Each class is 1 alphanumeric character and you canspecify up to 8 classes. If you specify more than one class, do not include anyblanks between the classes (for example, CLASSES ABC). If omitted, thedefault is A. If specified as an asterisk (*), the printer can process any file,regardless of class.To change the spooling classes without having to re-IPL, use the CP STARTUR command. For more information, see the z/VM: CP Commands and UtilitiesReference.DEST OFFDEST destspecifies the output destination values the printer can print. Specify DEST inone of the following ways:v By default — if you omit the DEST operand, DEST OFF is assumed.v You can specify as many as four destination values by entering four differentDEST operands, as follows:Dest printer1 Dest printer2 Dest printer3 Dest printer4v DEST * specifies that the printer should process files regardless ofdestination.To change the spooling destinations without having to re-IPL, use the CPSTART UR command. For more information about the CP START URcommand, see the z/VM: CP Commands and Utilities Reference.DPMSIZE nspecifies the maximum size of the delayed purge queue (see note 1) that the3800 Model 1, Model 3, or Model 6 printer uses after a cold start. The defaultvalue for n is 1, the maximum is 9. If 0 is specified, no delayed purge queue ismaintained (See note 2).Chapter 6. The System Configuration File 213

RDEVICE (3800 Printers)Notes:1. After the 3800 prints a file, CP places the file on the delayed purge queue ifa delayed purge queue is being maintained. When the queue is full, CPpurges the oldest file. This delay helps ensure that the 3800 (a) transfersthe last page of the file from the page buffer in the 3800 printer to paperand (b) stacks the printed page. If the 3800 fails before CP purges a filefrom the delayed purge queue, CP places the file in system hold.2. Specifying 0 for DPMSIZE saves some spool DASD space because filesprinted on the 3800 are purged immediately. However, this decreases thepossibility of recovering a printer file which has failed during printing.FCB lpispecifies the name of the forms control buffer for the separator page to be usedafter a cold start. Note that you can override this value by naming a formscontrol buffer on the START command. The default value for lpi is 6.The number of lines to be printed on the separator page is determined by theFCB loaded on the printer. The default separator page contains 58 lines of data.If the page length defined by the FCB is less than the default separator pagelength, the separator page data must be customized in order to fit on a singlepage. This may be done using CP Exit points that are provided in separatorpage processing. See the z/VM: CP Exit Customization for details.FLASH flashlibspecifies the flash overlay for use with this device.FOrm operformis the current spooling form number that the printer can process. This form isthe default operator form for the real printer when the operator starts the deviceafter a cold start without specifying a form. Specify this parameter in one of thefollowing ways:v FORM operform, where operform specifies a one- to eight-character operatorform number for the files the printer can process.v FORM *, where the asterisk specifies that the printer can process filesregardless of form number.v FORM STANDARD, where STANDARD indicates that the type of paper to bemounted on the printer is the type of paper that the installation has assignedthe name STANDARD. Each installation establishes its own set of formnames, assigns those form names to types of paper, and informs theoperations staff and end users of the correlation between form names andtypes of paper.STANDARD is the default.IMAGE_LIBrary imagelibspecifies the name of the image library to be used after a cold start. Note thatyou can override this value by specifying an image library name on the STARTcommand.The default value is IMAGE IMAG3800.LIMit None(the default) tells CP that this 3800 printer can print files with an unlimitednumber of records.LIMit nnnnnnnnnntells CP that this 3800 printer limits the size of files it can print. The variablennnnnnnnnn is a 1- to 10-digit decimal number that indicates the maximumnumber of records per file that this printer can print.214 z/VM: CP Planning and Administration

RDEVICE (3800 Printers)SEParator YesSEParator Nospecifies whether a separator is desired for output files. The default value isSEPARATOR YES.MARK YesMARK Nospecifies whether a 3800 printer will mark separator trailer pages with separatorbars.When ’Mark Yes’ is in effect, 3 separator trailer pages are printed for each file.’Mark No’ causes only one trailer page to be printed, thus saving paper.However, using ’Mark No’ could also make it more difficult to separate 3800output, as there are no markings between files. The default is YES.WCGM 2WCGM 4specifies that the 3800 has either the 2-writable-character generation modulefeature or the 4-writable-character generation module feature.Note: You can only specify this option for a 3800 model 1.For a 3800 model 1, the default is WCGM 2. For 3800 models 3, 6, and 8, thedefault is WCGM 4.Examples1. To define a Model 3 3800 printer at device number 0500 to be dedicated to avirtual machine, use the following RDEVICE statement:Rdevice 0500 Type 3800 Model 32. To define three Model 8 3800 printers at device numbers 0501, 0502, and 0503to be dedicated to virtual machines, use the following RDEVICE statement:Rdevice 0501-0503 Type 3800 Model 83. To define a 3800:v Model 1 printer at device number 100 with a class of 1, the4-writable-character generation module, and an image library calledIMAG3800v Model 3 printer at device number 150 driven by AFPv Model 6 printer at device number 180 driven by AFPuse the following RDEVICE statements:/*-------------------------------------------------------------------*//* What you always wanted to know about our printers, but were *//* afraid to ask: *//* *//* 3800 Model 1 is a CP Spooling Printer *//* 3800 Model 3 is driven by the AFP Program Product *//* 3800 Model 6 is driven by the AFP Program Product */Chapter 6. The System Configuration File 215

RDEVICE (3800 Printers)/* *//* Note: 3800 Models 3, 6 and 8 can be specified as either: *//* Type 3800 *//* - or - *//* Type AFP *//*-------------------------------------------------------------------*/RDevice 100 Type 3800 Model 1,Class 1,WCGM 4,IMAGE_LibraryIMAG3800Rdevice 150 Type 3800 Model 3,AFP YesRdevice 180 Type AFP Model 6216 z/VM: CP Planning and Administration

SAYSAY Statement►►SAY►◄▼token'string'"string"PurposeUse the SAY statement to write a line of text to the operator’s console duringinitialization.How to SpecifyInclude as many statements as needed; they are optional. You can place SAYstatements anywhere in the system configuration file.Operandstokenis the text to be displayed. Because the token is not delimited by quotationmarks, it will be converted to upper case when it is displayed.'string'"string"is the text to be displayed. The text inside the quotation marks is not convertedto upper case. The string is displayed unchanged and without the delimitingquotation marks.UsageNotes1. Multiple blanks not within quotation marks are compressed to a single blank.2. Multiple blanks within quotation marks are not compressed.3. Variable substitution does not occur for any token specified on the SAYstatement.4. A SAY statement that contains no text will cause a blank line to be displayed.5. Use two consecutive double quote marks (″″) to represent a ″ character within astring delimited by double quotation marks. Similarly, use two consecutive singlequotation marks (’’) to represent a ’ character within a string delimited by singlequotation marks.6. Each SAY statement shows up as a message on the operator’s console. Themessages are not displayed as they are encountered. These, as well as all theother initialization messages, are queued in storage until the operator isautologged.7. Messages that display the SAY statement text will also appear in a spooledconsole listing from the IPL. Use an appropriate text length on your SAYstatements to ensure the entire text is captured in the spooled console file.The text limit for a SAY statement is approximately 1900 characters. This is themaximum amount of data that will be displayed at the operator’s console. Fordata written to a console file, the existing limit is 299 characters. Because theChapter 6. The System Configuration File 217

SAYlogical record length of a console file is 132, also note that any data placed in aconsole file may be arbitrarily split into multiple lines.Examples1. If your system configuration file contains the following:SAY ’at line 100, a test of SAY:’SAY "Reading file" -system- configSAYSAY ’Here’’s my test’ a b cSAYSAY "Here’’s another test"Your operator would see:HCPZPQ2780I At line 100, a test of SAY:HCPZPQ2780I Reading file -SYSTEM- CONFIGHCPZPQ2780IHCPZPQ2780I Here’s my test A B CHCPZPQ2780IHCPZPQ2780I Here’’s another test218 z/VM: CP Planning and Administration

SETSET Statement►►30SET ▼ SHUTDOWNtime interval0SIGnal SHUTDOWNtime interval►◄PurposeOperandsUse the SET statement to define default system configuration values.SHUTDOWNtime intervaldefines the amount of time reserved for VM to shut down when a SHUTDOWNcommand is issued or a hardware termination signal is received. The intervalspecifies a number of seconds in the range 0 to 32767. If SETSHUTDOWNTIME is not specified in the system configuration file, the default is30 seconds.SIGnal SHUTDOWNtime intervaldefines the duration of the default shutdown signal timeout interval in seconds.This value is used as the default timeout interval for SIGNAL, FORCE, andSHUTDOWN commands when no explicit interval is specified. The intervalspecifies a number of seconds in the range 0 to 32767. If SET SIGNALSHUTDOWNTIME is not specified in the system configuration file, the default is0, which suppresses guest shutdown signals.Chapter 6. The System Configuration File 219

START (Disk)START (Disk) Statement►► STArt DASd ▼ rdevrdev-rdevVOLid volidALL▼LInksPAgeSPolSPoolTDiskTDskTEmpdisk►◄PurposeUse the START statement to restart devices after they have been drained. You canalso use them to change the processing options currently in effect for the devices.How to SpecifyInclude as many statements as needed; they are optional. You can place STARTstatements anywhere in the system configuration file. If you specify more than onestatement with the same operands, the last operand definition overrides anyprevious specifications.OperandsDASd rdevis the real device number of the DASD you want started. The variable rdev is ahexadecimal number between X'0000' and X'FFFF'.DASd rdev-rdevis a range of real device numbers specifying the DASD you want started. Eachrdev is a hexadecimal number between X'0000' and X'FFFF'.VOLid volidis the volume serial number of the volume you want started.ALLtells CP to allow new operations on this device, including:v Writing pages during page-outv Allowing minidisk linkingv Allocating space for new spool records.v Allocating temporary disk space.LInkstells CP to start allowing users to link to minidisks on this device.PAgetells CP to start writing pages to this device during page-out operations.SPolSPooltells CP to allocate space on this device for new spool records.220 z/VM: CP Planning and Administration

START (Disk)UsageNotesTDiskTDskTEmpdisktells CP to allocate temporary disk space on this device.1. CP processes the system configuration file during an IPL, which means CP hasnot attached any volumes to the system when processing your STARTstatements. Therefore, when you specify a START VOLID statement, you canonly use volumes that were previously specified in the system configuration fileusing CP_OWNED statements (page 73).Examples1. To have CP start allowing:v All new operations on all DASD at real devices numbers X'0700' throughX'07FF'v Spooling on DASD at real device number X'0800'v Paging on volume SYSPG1 (which was, of course, previously defined on aCP_OWNED statement)use the following START statements:Start DASD 0700-07ff All /* Allow all activity on these DASD */Start DASD 0800 Spool /* Allow spooling only on DASD 800 */Start VolID syspg1 Page /* Allow CP to allocate page space *//* on volume SYSPG1 */Chapter 6. The System Configuration File 221

STORAGESTORAGE Statement►► STORage Operands ►◄Operands:▼ SCMBK nnnnn Devices_extra TRACE optionsnnn Pages_extraTRACE options:TRace nnnn MegabytesMaster Pages Alternate mPercentPurposeUse the STORAGE statement to configure the use of real storage.How to SpecifyInclude as many statements as needed; they are optional. You can placeSTORAGE statements anywhere in the system configuration file. If you specifymore than one statement with the same operands, the last operand definitionoverrides any previous specifications.OperandsSCMBK nnnnn Devices_extraSCMBK nnn Pages_extratells CP how much additional storage to allocate for subchannel measurementblocks (SCMBKs). CP allocates the SCMBK space in contiguous pages ofstorage. During initialization, CP allocates 1 SCMBK for every subchannel onthe system and rounds the amount of storage up to the nearest page. Thus,you have enough SCMBK space for every real device on your system plussome free SCMBK space. How much free SCMBK space you have will vary,depending upon how many real devices you have on your system.When you specify the SCMBK operand, CP calculates the amount of SCMBKstorage exactly as if you had not specified the SCMBK operand, and then CPadds on the extra storage you want.When you specify the DEVICES_EXTRA operand, CP takes the number ofextra devices you specified, calculates the number of pages of storage that itneeds to reserve for those extra devices, and then adds the extra pages to thenumber of pages of SCMBK space that it originally calculated for the existingsubchannels on your system. The variable nnnnn must be a 1- to 5-digitdecimal number between 0 and 65535.When you specify the PAGES_EXTRA operand, CP takes the number of pagesthat it originally calculated for the existing subchannels on your system and222 z/VM: CP Planning and Administration

STORAGEUsageNotesadds to that the number of extra pages you specified. The variable nnn must bea 1- to 3-digit decimal number between 0 and 511.TRacetells CP how many 4 KB pages to allocate to the internal trace table for themaster processor and alternate processors in the configuration. For example, ifyou run z/VM on a uniprocessor and you specify:Storage Trace 100 PagesCP allocates 100 pages for the internal trace table. If you run z/VM on a dyadicprocessor and you specify:Storage Trace Master 100 Pages Alternate 90 PercentCP allocates 100 pages for the internal trace table of the master processor, and90 percent of the 100 pages (that is, 90 pages) as the internal trace table foreach of the other processors in the complex.If you omit the TRACE operand, CP calculates the internal trace table storagesize by allocating 1 page of storage for every 64 pages (256 KB) of real storageor 100 pages, whichever is smaller.You can specify nnnn as any decimal number between 3 pages and less thanone fourth of real memory.1. What CP uses as the size of the real memory depends on what you have codedin HCPSYS and the amount of real storage installed on the system. If inHCPSYS you use the SYSSTORE macroinstruction to specify a real memorysize smaller than what is actually available, CP will use the size specified inHCPSYS. We recommend that you not use SYSSTORE, or that you code it totell CP that two gigabytes of memory (the largest amount possible) areavailable, so that CP itself can determine the actual amount of memory in thesystem. If you do not code the macroinstruction, CP will default to twogigabytes.2. You can override what you or CP has determined to be the amount of memoryavailable by using the IPL parameter screen of the Stand-Alone Program Loader(SAPL) when you IPL the system.3. In storage configurations that have a large area of unaddressable storage (ahole) near the top of the storage address range, and with only a small amountof storage addressable after the hole, you may want to code the SYSSTOREmacro to limit the system’s use of storage to the large contiguous area belowthe hole. This will have two effects:a. the QUERY (real) STORAGE response will be closer to the actual usablestorage, andb. the system will not map the unaddressable area of storage with controlblocks which may use more storage than would be gained by the smallamount of usable storage that is available above the hole.One example of this type of storage configuration is a physically partitionedprocessor. The processor controller makes some of the storage available to onepartition, but it doesn’t always make contiguous address ranges available to oneside or the other.Note: Many processors do provide only contiguous storage ranges to eachpartition.Chapter 6. The System Configuration File 223

STORAGE4. The SCMBK operand will be ignored when format-1 measurement blocks arebeing used.Examples1. The following STORAGE statement allocates:v 1 megabyte of storage for the internal trace tableStorage, /* Configure Use of Real Storage */Trace Master 1 M Alternate 90 Percent,/* Allocate 1 Megabyte of space *//* Master Processors trace table *//* and 90% of that amount for *//* each of the other processors *//* in the complex */224 z/VM: CP Planning and Administration

SYSTEM_DATEFORMATSYSTEM_DATEFORMAT Statement►► SYSTEM_DATEFormat SHOrtdateFULldateISOdate►◄PurposeUse the SYSTEM_DATEFORMAT statement to set the system-wide default dateformat for commands that provide multiple date formats.How to SpecifyInclude as many statements as needed; they are optional. You can placeSYSTEM_DATEFORMAT statements anywhere in the system configuration file. Ifyou specify more than one SYSTEM_DATEFORMAT statement, the last statementoverrides any previous specifications.OperandsSHOrtdatespecifies that dates in command responses be displayed in mm/dd/yy, mm/dd,or yy/mm/dd format, where mm is the month, dd is the day of the month, and yyis the 2-digit year.FULldatespecifies that dates in command responses be displayed in mm/dd/yyyy oryyyy/mm/dd format, where mm is the month, dd is the day of the month, andyyyy is the 4-digit year.ISOdatespecified that dates in command responses be displayed in yyyy-mm-dd format,where yyyy is the 4-digit year, mm is the month, and dd is the day of the month.UsageNotes1. If the SYSTEM_DATEFORMAT statement is not in the system configuration file,then the system-wide default date format is SHORTDATE.2. The format of the dates, such as mm/dd/yy, mm/dd, and yy/mm/dd, aredependent upon the command or routine that displays or generates the date.Examples1. To define a default date format of mm/dd/yy, mm/dd, or yy/mm/dd, use thefollowing SYSTEM_DATEFORMAT statement:SYSTEM_DATEFORMAT SHORTDATE2. To define a default date format of mm/dd/yyyy or yyyy/mm/dd, use the followingSYSTEM_DATEFORMAT statement:SYSTEM_DATEFORMAT FULLDATE3. To define a default date format of yyyy-mm-dd, use the followingSYSTEM_DATEFORMAT statement:SYSTEM_DATEFORMAT ISODATEChapter 6. The System Configuration File 225

SYSTEM_IDENTIFIERSYSTEM_IDENTIFIER Statement►► SYSTEM_IDentifier model cpuid systemidGatewaygateid►◄PurposeUse the SYSTEM_IDENTIFIER statement to create a system identifier for theprocessor on which you run Z/VM. If your installation has several processors, youcan specify a SYSTEM_IDENTIFIER statement for each one. At initialization, CPmatches the processor model and CPU identification numbers with those specifiedwith the SYSTEM_IDENTIFIER statements. The selected system identifier appearson printed output separator pages and in the status area of 3270 display screens.The SYSTEM_IDENTIFIER statement also identifies the system gateway name fora system. The system gateway is identified automatically when CP initializes on thesystem. A system gateway provides a way to access private or global resources ona specific system within a CS or TSAF collection. It also provides access to privateor global resources in a CS collection from an adjacent TSAF collection. Similarly,resources in a TSAF collection can be accessed from an adjacent CS collection.By default, the system gateway name is the same as the system ID for the system;this is the recommended naming convention. However, if this default conflicts withanother gateway name, you can use the SYSTEM_IDENTIFIER statement tospecify a unique system gateway name for the system.How to SpecifyInclude as many statements as needed; they are optional. You can placeSYSTEM_IDENTIFIER statements anywhere in the system configuration file. If youspecify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.Operandsmodelis a character string with a length from 1 to 4 that specifies the processor unitmodel number. CP evaluates the string using pattern matching rules that aredescribed below in Usage Note 2 on page 227. An asterisk (*) tells CP to matchany processor unit model number.cpuidis a character string with a length from 1 to 6 that specifies the processoridentification number of a CPU in the processor complex. CP evaluates thestring using pattern matching rules that are described below in Usage Note 2 onpage 227. An asterisk (*) tells CP to match any processor identification number.systemidis the 1- to 8-character system identification.Gateway gateidis the 1- to 8-character name of the system gateway that will be identified whenthis system initializes. The gateid name is optional; if not specified, the system226 z/VM: CP Planning and Administration

SYSTEM_IDENTIFIERUsageNotesgateway name defaults to the systemid for the system. ISFC will then use thisvalue as its node name within a CS collection.If you specify NOSYSGAT as the gateid value, a system gateway name is notidentified for the system. Also, the specified system cannot join a CS collection.1. The EQUATE statement (page 133) defines nicknames that you can use asrecord qualifiers. You can also use the systemid on the SYSTEM_IDENTIFIERstatement as a record qualifier. Just be sure to define the systemid in aSYSTEM_IDENTIFIER statement before you try to use it as a nickname.2. Pattern matching generally follows the rules used by the CMS LISTFILEcommand. Use an asterisk (*) to match any number of characters; use apercent sign (%) to match any single character.Examples1. To define 3 9121 processors in a CSE complex with a system identifier ofBOSTON3, use the following SYSTEM_IDENTIFIER statements:System_Identifier 9121 020721 Boston3 /* Set Boston3 as our */System_Identifier 9121 120721 Boston3 /* system identifier */System_Identifier 9121 220721 Boston3 /* for processor 0/1/2 *//* in the complex */2. Here is another way to do what Example 1 does. In addition, this method tellsCP to match any processor model and any processor in that complex, evenmore than the 3 processors shown in Example 1.System_Identifier * %20721 Boston3 /* Set Boston3as our *//* system identifier *//* for processor 0/1/2 *//* in the complex */Chapter 6. The System Configuration File 227

SYSTEM_IDENTIFIER_DEFAULTSYSTEM_IDENTIFIER_DEFAULT Statement►► SYSTEM_IDENTIFIER_DEFault systemidGatewaygateid►◄PurposeUse the SYSTEM_IDENTIFIER_DEFAULT statement to provide CP with a defaultsystem identifier. CP uses the SYSTEM_IDENTIFIER_DEFAULT statement whenZ/VM is loaded on a system whose model and CPU identification numbers do notcorrespond with any of those specified on SYSTEM_IDENTIFIER statements.The default system identifier then appears on printed output separator pages and inthe status area of 3270 display screens.The SYSTEM_IDENTIFIER_DEFAULT statement also identifies the system gatewayname for a system. The system gateway is identified automatically when CPinitializes on the system. A system gateway provides a way to access private orglobal resources on a specific system within a CS or TSAF collection. It alsoprovides access to private or global resources in a CS collection from an adjacentTSAF collection. Similarly, resources in a TSAF collection can be accessed from anadjacent CS collection.By default, the system gateway name is the same as the system ID for the system;this is the recommended naming convention. However, if this default conflicts withanother gateway name, you can use the SYSTEM_IDENTIFIER_DEFAULTstatement to specify a unique system gateway name for the system.How to SpecifyInclude as many statements as needed; they are optional. You can placeSYSTEM_IDENTIFIER_DEFAULT statements anywhere in the system configurationfile. If you specify more than one statement with the same operands, the lastoperand definition overrides any previous specifications.OperandsExamplessystemidis the 1- to 8-character system identifier.Gateway gateidis the 1- to 8-character name of the system gateway that will be identified whenthis system initializes. The gateid name is optional; if not specified, the systemgateway name defaults to the systemid for the system. ISFC will then use thisvalue as its node name within a CS collection.If you specify NOSYSGAT as the gateid value, a system gateway name is notidentified for the system. Also, the specified system cannot join a CS collection.1. To define a default system identifier of BOSTON3 for your system, use thefollowing SYSTEM_IDENTIFIER_DEFAULT statement:228 z/VM: CP Planning and Administration

SYSTEM_IDENTIFIER_DEFAULTSystem_Identifier_Default Boston3 /* No matter what machine *//* CP is IPLed on, let us *//* be known as BOSTON3 */Chapter 6. The System Configuration File 229

SYSTEM_RESIDENCESYSTEM_RESIDENCE Statement►► SYSTEM_RESidence ►► CHECKpoint Cylinder start n▼FRom FORWARMstart VOLid volid Page&SYSRES&SYSPARM►◄PurposeUse the SYSTEM_RESIDENCE statement to describe the layout of the CP systemresidence disk.How to SpecifyInclude as many statements as needed; they are optional. You can placeSYSTEM_RESIDENCE statements anywhere in the system configuration file. If youspecify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.OperandsCHECKpointtells CP that you are defining the real starting location and the maximumnumber of pages or cylinders that the checkpoint process will use to preservesystem restart data.WARMstarttells CP that you are defining the real starting location and the maximumnumber of pages or cylinders that will be used for saving warm start data.VOLid volidtells CP the volume label of the device to use as the checkpoint or warm startdevice. If omitted, it defaults to the system residence volume.VOLid &SYSREStells CP that the system residence device is to be used as the checkpoint orwarm start device.VOLid &SYSPARMtells CP that the volume containing the active PARM disk is to be used as thecheckpoint or warm start device.FRom Cylinder startFRom Page starttells CP the real starting location (in cylinders or pages) where the checkpointor warm start information is saved. For CKD device types, start is a nonzerodecimal number from 1 to 65535. For FBA devices, startis a 1-to-6 digit 4 KBpage number that is greater than 3 (pages 0 through 3 are reserved).FOR ndefines the maximum number of cylinders or pages that CP should use for the230 z/VM: CP Planning and Administration

SYSTEM_RESIDENCEUsageNotescheckpoint or warm start area. For CKD device types, n is a 1-digit decimalnumber from 1 to 9 that represents cylinders. For FBA device types, n is adecimal number from 1 to 2000 that represents 4 KB pages.1. The checkpoint and warm start areas must not overlap.2. The system residence volume is the volume on which the CP module resides.This is usually the IPL volume, but may be another volume selected through thefull screen loader.3. The checkpoint and warm start areas must be on a CP_OWNED volume.4. Once you have IPLed the system with Checkpoint and warm start areasdefined, you cannot move them without doing a CLEAN START, therefore youshould allocate enough space to allow for expected growth.5. The checkpoint and warm start areas can be extended (in the same place) ifthere is room without doing a CLEAN START. For example, if your currentspecification is:SYSTEM_RESIDENCE CHECKpoint volid ESARES from Cyl 100 for 5you could change it to:SYSTEM_RESIDENCE CHECKpoint volid ESARES from Cyl 100 for 9if cylinders 105 – 108 are not in use for other purposes.Examples1. To define the system residence volume with the:v Checkpoint area starting at cylinder 101 and occupying 2 cylinders on DASDSYS002 andv Warm start area starting at cylinder 204 and occupying 1 cylinder on DASDSYS001,specify the following SYSTEM_RESIDENCE statement:System_Residence,CheckPoint VolID sys002 from Cylinder 101 for 2,WarmStart VolID sys001 from Cylinder 204 for 12. To define the system residence volume with the:v Checkpoint area starting at cylinder 568 and occupying 9 cylinders on DASDESARES andv Warm start area starting at cylinder 784 and occupying 9 cylinders on DASDESARES,specify the following SYSTEM_RESIDENCE statement:System_Residence,WarmStart VolID esares from Cylinder 568 for 9,CheckPoint VolID esares from Cylinder 784 for 9Chapter 6. The System Configuration File 231

SYSTEM_USERIDSSYSTEM_USERIDS Statement►►SYSTEM_USERids(1)▼ACCount1 OPERACCT AUTOlogAUTOlogACCount1 useridNOAUTOlogAUTOlogACCOUNT2 useridNOAUTOlogDUMP OPERATNSDUMP useridEREP1 OPEREREP AUTOlogAUTOlogEREP1 useridNOAUTOlogAUTOlogEREP2 useridNOAUTOlogOPERator OPERATOR DISConnectOPERator userid DISConnectNODISConnectSTARTup AUTOLOG1 AUTOlogAUTOlogSTARTup useridNOAUTOlogSYMPtom1 OPERSYMP AUTOlogAUTOlogSYMPtom1 useridNOAUTOlogAUTOlogSYMPTOM2 useridNOAUTOlog►◄Notes:1 You must specify at least one of the following operands.PurposeUse the SYSTEM_USERIDS statement to specify user IDs that will perform specialfunctions during and after IPL. These functions include accumulating accountingrecords, system dump files, EREP records, and symptom records, and specifyingthe primary system operator’s user ID and disconnect status.How to SpecifyInclude as many statements as needed; they are optional. You can placeSYSTEM_USERIDS statements anywhere in the system configuration file. If youspecify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.OperandsACCount1 userid232 z/VM: CP Planning and Administration

SYSTEM_USERIDSUsageNotesACCOUNT2 useridspecifies the user IDs of the virtual machines for which the *ACCOUNT systemservice is to accumulate and checkpoint accounting records. You can specifyone or two user IDs. One or both of these virtual machines are automaticallylogged on during CP initialization. The user IDs are alphanumeric characterstrings of up to eight characters. OPERACCT is the default for ACCOUNT1.AUTOlogNOAUTOlogspecify whether CP should log on the indicated user ID at IPL.DUMP useridis the user ID of the virtual machine that receives spooled system dumps. Thevariable userid must be an alphanumeric character string of as many as eightcharacters. OPERATNS is the default.EREP1 useridEREP2 useridare the user IDs of the virtual machines for which the *LOGREC system serviceis to accumulate and checkpoint error records. You can specify one or two userIDs. EREP1 can be shortened to EREP. The variable userid must be analphanumeric string 1- to 8-characters long. These virtual machines areautomatically logged on during CP initialization. OPEREREP is the default forEREP1.OPERator useridis the primary system operator’s user ID. The variable userid is analphanumeric character string of as many as eight characters. The default isOPERATOR.DISConnectNODISConnectindicates whether CP should disconnect the primary system operator when asoftware-initiated IPL occurs and the primary system operator is not logged ontothe primary system console.If you specify DISCONNECT, and the primary system operator is not loggedonto the primary system console when a software-initiated IPL occurs, CPdisconnects the primary system operator. If you specify NODISCONNECT, CPdoes not force the primary system operator to be disconnected. If you do notcode this operand, DISCONNECT is assumed.Specifying NODISCONNECT may affect system security. For more information,see usage note 5 on page 234.STARTup useridspecifies the user ID that is to be logged on automatically at IPL to performfunctions you select. AUTOLOG1 is the default.SYMPtom1 useridSYMPTOM2 useridspecifies the user IDs of virtual machines for which the CP *SYMPTOM systemservice is to accumulate and checkpoint symptom records. One or two user IDscan be specified. The user IDs are alphanumeric strings of as many as eightcharacters each. OPERSYMP is the default for SYMPTOM and SYMPTOM1.1. If the user ID specified on the SYSTEM_USERIDS ACCOUNT statement has anentry in the user directory, that user ID is logged on at system initialization.Chapter 6. The System Configuration File 233

SYSTEM_USERIDS2. CP creates system dump files as a result of system abends and systemrestarts. You can also use the VMDUMP command to send virtual machinedumps to the virtual machine you specify in the SYSTEM_USERIDS statement.3. If the user ID specified on the SYSTEM_USERIDS EREP statement has anentry in the user directory at system initialization, the associated virtual machineis logged on to the system.4. CP logs on a system operator with the user ID you specify on the OPERATORoperand, regardless of whether that user ID has an entry in the user directory.5. If you specify NODISCONNECT, CP allows the primary system operator toremain logged onto the primary system console after all software-initiated IPLs.This makes the primary system operator’s user ID available to any user withaccess to the primary system console, which could lead to a system-widecompromise of security. If you specify NODISCONNECT, make sure that theprimary system console and all alternate system consoles are in a secureenvironment and are continuously monitored by authorized personnel.6. When the primary system operator logs off, the next user that logs on with atleast one of the privilege classes required for the system operator will becomethe primary system operator. However, this can be overridden by either:v Specifying alternate operators using the ALTERNATE_OPERATORSstatement in the system configuration filev Selecting a new operator using the SET SYSOPER command.For more information about the ALTERNATE_OPERATORS statement, see“ALTERNATE_OPERATORS Statement” on page 58. For more information ondefining operator privilege class, see the “PRIV_CLASSES Statement” on page184 or the “SYSFCN (Optional)” on page 673.7. If the user ID specified on the SYSSYMP statement has an entry in the userdirectory at system initialization, the virtual machine designated by that user IDis logged on to the system.8. If you are changing records relating to ACCOUNT, EREP or SYMPTOM, refer tothe following sections: “Disassociating a User ID from the Retrieval ofAccounting Records” on page 298, “Disassociating a User ID from the Retrievalof EREP Records” on page 317, and “Disassociating a User ID from theRetrieval of Symptom Records” on page 320.Examples1. The following SYSTEM_USERIDS statement specifies:v The system operator as user ID OPERATOR and to specify that CP shoulddisconnect the system operator when a software re-IPL occurs and thesystem operator is not logged on to the system consolev Dumps should go to the OPERATNS user IDv CP should automatically log the AUTOLOG1 user ID at IPLv One EREP user ID called EREP and to have CP automatically log on thatuser ID at IPLv One accounting user ID called DISKACNTv One symptom records user ID called OPERSYMPSystem_UserIDs,Operator operator, /* use OPERATOR ID as operator */Disconnect, /* If bounce, disconnect oper */Dump operatns, /* use OPERATNS ID for dump collection */StartUp autolog1, /* CP will XAUTOLOG this ID during init */234 z/VM: CP Planning and Administration

SYSTEM_USERIDSErep erep Autolog, /* Collect I/O error & Send to EREP ID */Account diskacnt, /* Send Accting Records to Diskacnt ID */Symptom opersymp /* Send Symptom Records to Opersymp ID */Chapter 6. The System Configuration File 235

THROTTLETHROTTLE Statement►► THROTtle ▼ rdevrdev1-rdev2RATE nnnnn ►◄PurposeUse the THROTTLE statement to limit (throttle) the number of I/O operations that aguest operating system can initiate to a specific real device. This prevents a guestfrom interfering with or dominating I/O resources.The THROTTLE statement adds real devices to the I/O throttling list. Afterinitialization completes, CP begins limiting (throttling) the guest’s I/O rate to thespecified device or devices.How to SpecifyInclude as many statements as needed; they are optional. You can placeTHROTTLE statements anywhere in the system configuration file. If you specifymore than one statement with the same device number, CP uses the I/O rate onthe last statement, and ignores all previous statements with that device number.Operandsrdevrdev1-rdev2identifies the real device or devices that you want to throttle. The variable rdevis the real device number of the device and must be a hexadecimal numberbetween X'0000' and X'FFFF'. You can specify a single device address, a rangeof device addresses, or any combination thereof.RATE nnnnnspecifies the I/O throttling rate (number of I/O operations per second that thisdevice can process from a guest operating system). The variable nnnnn mustbe a decimal number between 1 and 10,000.UsageNotes1. To add devices to or delete devices from the I/O throttling list after initialization,use the SET THROTTLE command. For more information about the SETTHROTTLE command, see the z/VM: CP Commands and Utilities Reference.2. To display the list of devices being throttled and their respective I/O rates, usethe QUERY THROTTLE command. For more information about the QUERYTHROTTLE command, see the z/VM: CP Commands and Utilities Reference.Examples1. To limit all guest operating systems using 1c10 to 1 I/O operations per second,use the following THROTTLE statement:Throttle 1c10 rate 1 */During initialization, CP responds:Device 1C10 added to throttle set. Rate = 1.236 z/VM: CP Planning and Administration

TIMEZONE_BOUNDARYTIMEZONE_BOUNDARY Statement►►TIMEZONE_BoundaryONdateATtimeTOzoneid►◄PurposeUse the TIMEZONE_BOUNDARY statement to tell CP what time zone to choose atIPL so that it can determine the local time.How to SpecifyInclude as many statements as needed; they are optional. You can placeTIMEZONE_BOUNDARY statements anywhere in the system configuration file. Ifyou specify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.OperandsON dateis the date, in the format yyyy-mm-dd, on which CP should begin using a giventime zone.ATtimeis the time, in the format hh:mm:ss, when CP should begin using a given timezone.TO zoneidis a 3-character time zone definition established by an earlierTIMEZONE_DEFINITION statement.UsageNotes1. Before you can use this statement, you must already have defined the timezoneto which you are changing. You can do so with TIMEZONE_DEFINITIONstatements in the system configuration file. For more information about theTIMEZONE_DEFINITION statement, see page 239.2. As its name suggests, this statement establishes the boundaries for the timezones that CP can use. You must specify at least one boundary that hasoccurred before the current date; otherwise, CP will use Coordinated UniversalTime (UTC) to determine the new time. For example, if you include the followingstatements in your system configuration file:TimeZone_Boundary on 1992-04-05 at 02:00:00 to edtTimeZone_Boundary on 1992-10-25 at 02:00:00 to estTimeZone_Boundary on 1993-04-04 at 02:00:00 to edtTimeZone_Boundary on 1993-10-31 at 02:00:00 to estCP determines the local time according to where the time of the system’s clockfits in to the boundaries. If you IPL the system before 02:00:00 UTC on April 5,1992, CP assumes that the local time is UTC, because nothing has told itotherwise. If you IPL between 02:00:00 UTC on April 5, 1992, and 02:00:00EDT on October 25, 1992, CP assumes that EDT is the local time. If you IPLafter 02:00:00 EDT on October 25, 1992, but before 02:00:00 EST April 4, 1993,CP takes EST as the local time; if you IPL any time after 02:00:00 EST on April4, 1993, CP assumes that the local time is EDT. CP determines which timeChapter 6. The System Configuration File 237

TIMEZONE_BOUNDARYzone 02:00:00 is in from the preceding TIMEZONE_BOUNDARY statement. Ifthere is no preceding statement, CP assumes that 02:00:00 is in UTC.3. After the system is up and running, you can issue the CP SET TIMEZONEcommand to change the time zone of the running system. If you do so, you mayonly choose a time zone that has already been defined with either aTIMEZONE_DEFINITION statement or the CP DEFINE TIMEZONE command.For more information about the TIMEZONE_DEFINITION statement, see page239. For more information about the CP SET TIMEZONE command, see thez/VM: CP Commands and Utilities Reference.Examples1. To define eastern daylight time (EDT) and eastern standard time (EST) throughthe year 1999, use the following TIMEZONE_BOUNDARY statements:/*---------- Timezone Boundary Condition Definitions ----------*/TimeZone_Boundary on 1992-04-05 at 02:00:00 to edtTimeZone_Boundary on 1992-10-25 at 02:00:00 to estTimeZone_Boundary on 1993-04-04 at 02:00:00 to edtTimeZone_Boundary on 1993-10-31 at 02:00:00 to estTimeZone_Boundary on 1994-04-03 at 02:00:00 to edtTimeZone_Boundary on 1994-10-30 at 02:00:00 to estTimeZone_Boundary on 1995-04-02 at 02:00:00 to edtTimeZone_Boundary on 1995-10-29 at 02:00:00 to estTimeZone_Boundary on 1996-04-07 at 02:00:00 to edtTimeZone_Boundary on 1996-10-27 at 02:00:00 to estTimeZone_Boundary on 1997-04-06 at 02:00:00 to edtTimeZone_Boundary on 1997-10-26 at 02:00:00 to estTimeZone_Boundary on 1998-04-05 at 02:00:00 to estTimeZone_Boundary on 1998-10-25 at 02:00:00 to estTimeZone_Boundary on 1999-04-04 at 02:00:00 to edtTimeZone_Boundary on 1999-10-31 at 02:00:00 to est238 z/VM: CP Planning and Administration

TIMEZONE_DEFINITIONTIMEZONE_DEFINITION Statement►► TIMEZONE_DEFinition zoneid East+West−offset►◄PurposeUse the TIMEZONE_DEFINITION statement to define system time zones accordingto their difference from Coordinated Universal Time (UTC).How to SpecifyInclude as many statements as needed; they are optional. You can placeTIMEZONE_DEFINITION statements anywhere in the system configuration file. Ifyou specify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.Operandszoneidis the 3-letter time zone ID that you are defining. The variable zoneid must be a1- to 3-character identifier.Important NoteThe zone IDs UTC and GMT are predefined. You cannot specify UTC orGMT as a zoneid.UsageNotesEast+ tells CP to add the value specified by offset to Coordinated Universal Time(UTC) to define this time zone ID. EAST is the same as +.West− tells CP to to subtract the value specified by offset from the CoordinatedUniversal Time (UTC) to define the time zone ID. WEST is the same as −.offsetis the difference between UTC and zoneid. You can enter offset as hh:mm:ss orhh.mm.ss, where hh is required and mm and ss are optional. You can specifyss only if you have specified mm.1. This statement defines the time zones that will always be available after an IPL.You can use the CP DEFINE TIMEZONE command to define additional timezones after the system is up and running. For more information about the CPDEFINE TIMEZONE command, see the z/VM: CP Commands and UtilitiesReference.Examples1. To define time zone:v EDT as 4 hours west of UTCChapter 6. The System Configuration File 239

TIMEZONE_DEFINITIONv EST as 5 hours west of UTCv DRB as 5 ½ hours west of UTCv RFC as 4 ½ hours west of UTCv IKA as 3 ½ hours west of UTCv DAC as 4 ½ hours east of UTCv PDT as 7 hours west of UTCv PST as 8 hours west of UTCuse the following TIMEZONE_DEFINITION statements:TimeZone_Definition edt West 4.00.00 /* EDT is West 4 from UTC */TimeZone_Definition est West 5.00.00 /* EST is West 5 from UTC */TimeZone_Definition drb West 5.30.00 /* DRB is West 5 hrs, 30 *//* minutes from UTC */TimeZone_Definition rfc West 4.30.00 /* RFC is West 4 hrs, 30 *//* minutes from UTC */TimeZone_Definition ika West 3.30.00 /* IKA is West 3 hrs, 30 *//* minutes from UTC */TimeZone_Definition dac East 4.30.00 /* DAC is East 4 hrs, 30 *//* minutes from UTC */TimeZone_Definition pdt West 7.00.00 /* PDT is 7 West of UTC */TimeZone_Definition pst West 8.00.00 /* PST is 8 West of UTC */240 z/VM: CP Planning and Administration

TOLERATE_CONFIG_ERRORSTOLERATE_CONFIG_ERRORS Statement►► TOLERATE_CONFIG_ERRors YesNo►◄PurposeUse the TOLERATE_CONFIG_ERRORS statement to mark sections of the systemconfiguration file that must be without errors when CP processes them.How to SpecifyInclude as many statements as needed; they are optional. You can placeTOLERATE_CONFIG_ERRORS statements anywhere in the system configurationfile.If you do not specify any TOLERATE_CONFIG_ERRORS statements, CP willtolerate errors in your system configuration file.The first statement you specify must be TOLERATE_CONFIG_ERRORS NO. Allsubsequent statements must alternate between YES and NO. You cannot have twoTOLERATE_CONFIG_ERRORS statements in a row with the same operand. Thatis, you cannot tell CP to tolerate errors, process a few more statements, and thentolerate errors again.OperandsYestells CP to begin tolerating errors in the system configuration file.Notells CP not to tolerating any errors in the system configuration file untilencountering a TOLERATE_CONFIG_ERRORS YES statement.UsageNotes1. When CP finds an error in a system configuration file statement that follows aTOLERATE_CONFIG_ERRORS NO statement, it remembers the erroroccurrence and, after displaying all the errors encountered, prompts theoperator with a question. The operator can respond to the question in one of thefollowing ways:v Stopping the IPL processv Continuing with the normal IPL processv Continuing with the normal IPL process but not automatically logging on anyvirtual machines.2. If CP does not find any errors while processing the system configuration file or ifall errors found are in sections of the system configuration file whereTOLERATE_CONFIG_ERRORS YES is in effect, the normal IPL processcontinues.3. If you are using the IMBED and the TOLERATE_CONFIG_ERRORSstatements, remember that CP processes the statements in an imbed file as ifthose statements were included in the master system configuration file. If youChapter 6. The System Configuration File 241

TOLERATE_CONFIG_ERRORSare not tolerating errors in the master file and then repeat the statement in theimbeded file, CP will flag the duplicate statement in the imbedded file as anerror.4. If you change a system configuration file, you should run the CPSYNTAX execto make sure there are no syntax errors in the system configuration file.Examples1. To tell CP not to ignore any syntax problems found in the processing of theCP_OWNED statements, use the following TOLERATE_CONFIG_ERRORSstatements:Tolerate_Config_Errors no /* Don’t ignore errors here */CP_Owned Slot 1 ESARESCP_Owned Slot 2 ESAP01CP_Owned Slot 3 ESAP02CP_Owned Slot 4 ESAP03CP_Owned Slot 5 ESAP04CP_Owned Slot 6 ESAP05Tolerate_Config_Errors yes /* Back to normal mode */2. To make sure CP does not ignore any errors when defining your checkpoint andwarm start areas, use the following TOLERATE_CONFIG_ERRORS statements:Tolerate_Config_Errors no /* Don’t Ignore Any Errors in *//* the System Residence Stmt */System_Residence,CheckPoint VolID esares From Cylinder 784 For 9,WarmStart VolID esares From Cylinder 568 For 9Tolerate_Config_Errors yes /* From here on, errors are OK */242 z/VM: CP Planning and Administration

TRANSLATE_TABLETRANSLATE_TABLE Statement►► TRANSLATE_TABle FILter GRAPHICS_APLGRAPHICS_NONAPLGRAPHICS_TextTRANSlate CMS_FILENAMEDISPlay_storageEXTERNAL_SYMBOLUSERID_CHARactersUSERID_PATTERNINputOUTputASCII_APLASCII_1977ASCII_19803277_APL3277_Text3278_APL3278_Textfn ft ►◄PurposeUse TRANSLATE_TABLE statements to specify replacements for the standardtranslation tables that CP uses to accomplish certain tasks.How to SpecifyInclude as many statements as needed; they are optional. You can placeTRANSLATE_TABLE statements anywhere in the system configuration file. If youspecify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.OperandsFILtertells CP to use the specified file to filter out invalid characters.GRAPHICS_APLtells CP to use this translation table to filter out invalid characters and 3270orders out of a 3270 data stream destined for an APL display.GRAPHICS_NONAPLtells CP to use this translation table to filter invalid characters out of a 3270data stream destined for an EBCDIC (non-APL) display.GRAPHICS_Texttells CP to use this translation table to filter out invalid characters and 3270orders out of a 3270 data stream destined for an 3270 text display.TRANSlatetells CP to use the specified file to translate input or output characters.CMS_FILENAMEdefines which characters are acceptable to use when defining CMS filenames and file types.DISPlay_storagetells CP to use the hexadecimal-to-EBCDIC translation table when issuingthe CP DISPLAY command with the T option or the CPTYPE command.Chapter 6. The System Configuration File 243

TRANSLATE_TABLEFor more information about the CP DISPLAY and CPTYPE commands, seethe z/VM: CP Commands and Utilities Reference.EXTERNAL_SYMBOLdefines which characters are acceptable to use when defining entry pointnames.USERID_CHARactersdefines the translation test table used to validate user IDs in the systemconfiguration file. This statement overrides the table in HCPTBL. Indicatevalid characters by setting their positions in the translation test table toX'00'. A non-zero value means that the character is not valid in a user ID.If you change the USERID_CHARACTERS table, make correspondingchanges to the USERID_PATTERN table. See “USER Directory ControlStatement (Control)” on page 572 for points to consider in selecting validcharacters for user IDs.If the translation test table you define invalidates any characters from thedefault acceptable set:v Uppercase letters (A through Z)v Numbers (0 through 9)v Other (# $ @ _ -)then results are unpredictable.USERID_PATTERNdefines the translation test table used to validate user ID patterns in thesystem configuration file. This statement overrides the table in HCPTBL.Indicate valid characters by setting their positions in the translation testtable to X'00'. Any non-zero value means that the character is not valid in auser ID pattern.If you change the USERID_PATTERN table, make corresponding changesto the USERID_CHARACTERS table. Make sure the USERID_PATTERNtable includes the pattern-matching characters asterisk (*) and percent (%)as valid characters.INputOUTputtells CP to use the specified file to translate input or output characters.ASCII_1977defines the translation table used to translate input characters comingfrom a TTY UASCII-1977 level display to EBCDIC, or output EBCDICcharacters to those going to a TTY UASCII-1977 terminal.ASCII_1980defines the translation table used to translate input characters comingfrom a TTY UASCII-1980 level display to EBCDIC, or output EBCDICcharacters to those going to a TTY UASCII-1980 terminal.ASCII_APLdefines the translation table used to translate ASCII APL inputcharacters coming from an ASCII APL-capable display to EBCDIC APLcharacters, or to translate EBCDIC APL characters to those going to anASCII APL-capable display.3277_APLdefines the translation table used to translate input characters comingfrom a 3277 APL display, or output characters going to such a display.244 z/VM: CP Planning and Administration

TRANSLATE_TABLEUsageNotes3278_APLdefines the translation table used to translate input characters comingfrom a 3278 APL display, or output characters going to such a display.3277_Textdefines the translation table used to translate input characters comingfrom a text-only 3277 display, or output characters coming from such adisplay.3278_Textdefines the translation table used to translate input characters comingfrom a text-only 3278 display, or output characters going to such adisplay.fn is the file name of the translation table file.ft is the file type of the translation table file.1. The specified file must reside on the same minidisk as the system configurationfile so that CP can find the file during IPL processing.2. As with the system configuration file, comments in the file containing thetranslation table must be delimited with a beginning /* and an ending */. A singlecomment may span multiple lines in the file.3. Data found outside the aforementioned comment delimiters must be EBCDIChexadecimal. Because each byte in the translation table is represented by 2hexadecimal digits, no token in the file can consist of an odd number ofcharacters. Translated characters may be grouped in clusters to improve thereadability of the table.4. Exactly 256 translated characters (512 data bytes) must exist in the file. If thenumber of characters specified does not equal 256, CP will generate an errorand otherwise ignore the statement.Examples1. To display the underscore character (X'6D') as an underscore character ratherthan the period (X'4B') defined in the default translation table used by theDISPLAY command, use the following:/* Use the following translate table located in file, *//* DISPLAY STORAGE, as the hexadecimal to EBCDIC *//* translate table. */Translate_Table Translate Display_Storage display storageOn the same minidisk as the system configuration file, you would put a filecalled DISPLAY STORAGE containing the following information:/*----------------------------------------** Translate table for display of storage **----------------------------------------*/4B4B4B4B 4B4B4B4B 4B4B4B4B 4B4B4B4B /* .... .... .... ....*/4B4B4B4B 4B4B4B4B 4B4B4B4B 4B4B4B4B /* .... .... .... ....*/4B4B4B4B 4B4B4B4B 4B4B4B4B 4B4B4B4B /* .... .... .... ....*/4B4B4B4B 4B4B4B4B 4B4B4B4B 4B4B4B4B /* .... .... .... ....*/404B4B4B 4B4B4B4B 4B4B4B4B 4C4D4E4F /* .... .... ....

TRANSLATE_TABLE504B4B4B 4B4B4B4B 4B4B4B5B 5C5D5E5F /* &;.. .... ...$*);* */60614B4B 4B4B4B4B 4B4B4B6B 6C6D6E6F /* -/.. .... ..., %_>?*/4B4B4B4B 4B4B4B4B 4B4B7A7B 7C7D7E7F /* .... .... ..# @’=" */4B818283 84858687 88894B4B 4B4B4B4B /* .abc defg hi.. ....*/4B919293 94959697 98994B4B 4B4B4B4B /* .jkl mnop qr.. ....*/4B4BA2A3 A4A5A6A7 A8A94B4B 4B4B4B4B /* ..st uvwx yz.. ....*/4B4B4B4B 4B4B4B4B 4B4B4B4B 4B4B4B4B /* .... .... .... ....*/4BC1C2C3 C4C5C6C7 C8C94B4B 4B4B4B4B /* .ABC DEFG HI.. ....*/4BD1D2D3 D4D5D6D7 D8D94B4B 4B4B4B4B /* .JKL MNOP QR.. ....*/4B4BE2E3 E4E5E6E7 E8E94B4B 4B4B4B4B /* ..ST UVWX YZ.. ....*/F0F1F2F3 F4F5F6F7 F8F94B4B 4B4B4B4B /* 0123 4567 89.. ....*/CP reads the DISPLAY STORAGE file at IPL time and would replace the defaulttable used with the CP DISPLAY or CPTYPE commands with the table specifiedin the file.246 z/VM: CP Planning and Administration

USERFORMUSERFORM Statement►► USERFOrm userform operformNARrow►◄PurposeUse the USERFORM statement to create a list of user form names and theircorresponding operator form numbers, and to specify forms as NARROW so that anarrow separator page is printed.How to SpecifyInclude as many statements as needed; they are optional. You can placeUSERFORM statements anywhere in the system configuration file. If you specifymore than one statement with the same operands, the last operand definitionoverrides any previous specifications.Operandsuserformis a 1- to 8-character alphanumeric name of a user form.operformis a 1- to 8-character alphanumeric operator form number.NARrowtells CP that the form is no more than 86 columns wide. If you specifyNARROW, separator information does not print beyond column 86.UsageNotes1. The userform and operform operands establish the correspondence betweenthe user form and operator form. If you do not specify any user form andoperator form pairs, CP does not generate a form list and does not distinguishbetween user and operator forms.Examples1. To define three user form and operator form pairs with the followingcharacteristics:v User form DOCUMENT paired with operator form G1PN which are at most86 characters widev User form LISTING paired with operator form G1PWv User form PLAIN paired with operator form G1PN which are at most 86characters wideuse the following USERFORM statements:Userform document g1pn NarrowUserform listing g1pwUserform plain g1pn NarrowChapter 6. The System Configuration File 247

USER_DEFAULTSUSER_DEFAULTS System Configuration File Statement►► USER_DEFAULTS Operands ►◄Operands▼(1) LPP OFFLPPOFFnnnPOSIXOPT QUERYDB ALLOW EXEC_SETIDS DISALLOWQUERYDB ALLOW EXEC_SETIDS DISALLOWPOSIXOPTQUERYDB DISALLOW EXEC_SETIDS ALLOWMESSAGE_LEVel WNG MSG EMSG_CODE EMSG_TEST IMSGMESSAGE_LEVelCPLANGuage▼OFFlangidWNGMSGEMSG_CODEEMSG_TEXTIMSGNotes:1 You must specify at least one of the following operands. If you want to specify more than oneoperand, you can specify them in any order.PurposeUse the USER_DEFAULTS statement to define default attributes and permissionsfor all users on the system.How to SpecifyInclude as many statements as needed; they are optional. You can place theUSER_DEFAULTS statement anywhere in the system configuration file. If youspecify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.OperandsLPPSets the default global lines per page value for all virtual printers and virtualconsoles defined on the system.The lines per page value is used by VM functions which generate virtual printerand console output. For CP, these include console spooling, SPXTAPE log files,CP dump and trace output, DDR, and load maps generated by HCPLDR. CMSfunctions which use the lines per page value for virtual printer output include thePRINT, ASSEMBLE, UPDATE, GENMSG, TAPE, FILEPOOL FORMAT AUDIT,and SET DOSLNCNT commands.248 z/VM: CP Planning and Administration

USER_DEFAULTSLPP OFFIndicates that internal defaults will be used as the global value for lines perpage. The defaults are the same as those which have been used on priorreleases of VM for virtual printers and consoles.LPP nnnSets the default global lines per page value to nnn. nnn must be a decimalnumber with a range of 30 to 255.POSIXOPTdefines the default POSIX authorizations to permit or prohibit all users on thesystem from querying other users’ POSIX information or having their POSIXsecurity values changed.These authorizations can be overridden for a specific user by adding thePOSIXOPT directory control statement (“POSIXOPT Directory ControlStatement (General)” on page 548) to that users’ directory entry.QUERYDB ALLOW(the default) specifies by default, users are permitted to query other users’POSIX database information.QUERYDB DISALLOWspecifies that by default, users are not permitted to query other users’ POSIXdatabase information.EXEC_SETIDS DISALLOW(the default) specifies by default, users are not permitted to have their POSIXsecurity values changed on behalf of a POSIX exec() function call designating afile with the setuid or setgid attributes.EXEC_SETIDS ALLOWspecifies that by default, users are permitted to have their POSIX securityvalues changed on behalf of a CP exec() processing. The server requesting thechange must be authorized to do so by the SETIDS option of the POSIXOPTdirectory statement.MESSAGE_LEVELsets the default message level for a user who accesses the system, overridingthe default of WNG ON, MSG ON, and IMSG ON. At least one of the followingmessage levels must be specified:WNGenables the user to receive messages from other users issued by theWARNING or WNG command.MSGenables the user to receive messages from other users issued by theMESSAGE, MSG, or MSGNOH command.EMSG_CODEenables the user to receive the message code portion of error messages.EMSG_TEXTenables the user to receive the text portion of error messages.IMSGenables the user to receive informational messagesOFFprevents the user from receiving any messages, warnings, error messages,or informational messages.Chapter 6. The System Configuration File 249

USER_DEFAULTSUsageNotesCPLANGUAGE langidlangid is the system default language. langid must be 1 to 5 characters andmust consist of CMS file system characters only. If the CPLANGUAGE operandis not specified on any USER_DEFAULTS statement, CP uses the languagethat was built into the CP nucleus as the system default language.1. If the USER_DEFAULTS statement is not specified, or the POSIXOPT operandis not specified, the defaults are to permit all users to query other users’ POSIXdatabase information, and prohibit all users from having their POSIX securityvalues changed on behalf of CP exec() processing. ESM (External SecurityManager) may override each user’s settings.2. If the USER_DEFAULTS statement is not specified, or the LPP operand is notspecified, the default global value for lines per page is ’OFF’.3. The LPP option of the SPOOL command may be used to change the LPP valuefor individual virtual printers and consoles.Examples1. The following example shows how to specify the USER_DEFAULTS statement.Note that you can specify more than one operand on a singleUSER_DEFAULTS statement.To specify that:v All users in the system can not query other users’ POSIX databaseinformation.v All users in the system are prohibited from having their POSIX securityvalues changed by other (authorized) users.use the following USER_DEFAULTS statement:User_Default posixopt Querydb disallow Exec_Setids disallow2. To specify that the default lines per page value for all virtual printers and virtualconsoles is 56, use the following USER_DEFAULTS statement:User_Defaults lpp 563. To specify that internal defaults should be used (as in prior releases of VM) asthe lines per page value for all virtual printers and virtual consoles, use thefollowing USER_DEFAULTS statement:User_Defaults lpp OFF250 z/VM: CP Planning and Administration

USER_VOLUME_EXCLUDEUSER_VOLUME_EXCLUDE Statement►► USER_VOLUME_EXclude ▼ volid ►◄PurposeUse the USER_VOLUME_EXCLUDE statement to define volumes that are to beexcluded from the user volume list. (User volumes are those volumes that you useto contain minidisks.) During system IPL, CP attaches to the system any volumeswhose volume identifiers match a generic volume identifier specified in aUSER_VOLUME_INCLUDE statement unless the volume is also specified in aUSER_VOLUME_EXCLUDE statement.How to SpecifyThe USER_VOLUME_EXCLUDE statement is optional; if specified, you can includeas many statements as you need as long as the total number of volumes specifiedon a single statement does not exceed 500. If you specify a generic volumeidentifier, CP counts each volume that matches the pattern as one.You can place USER_VOLUME_EXCLUDE statements anywhere in the systemconfiguration file. If you specify more than one statement with the same operands,the last operand definition overrides any previous specifications.Operandsvolidis a volume serial number or a generic volume serial number for a specificsubset of volumes. The variable volid is a 1- to 6-character alphanumeric stringwith no imbedded blanks. A generic volume serial number is a 1- to 6-characterstring with asterisks (*) in place of one or more arbitrary characters and percentsigns (%) in place of exactly one arbitrary character. For example:User_Volume_Excludees%vm*UsageNotescreates a list that includes all volumes whose volume serial number start withES and have VM as their fourth and fifth characters.A single asterisk (*) prevents CP from attaching all user volumes from thesystem that are also specified on any USER_VOLUME_EXCLUDE statements.1. If a volume identifier matches a volid pattern specified both inUSER_VOLUME_EXCLUDE and USER_VOLUME_INCLUDE statements, CPdoes not attach the volume to the system during initialization. A duplicate volidcauses the entire statement to be rejected. A volume is automatically attachedto the system if:It is explicitly listed in the USER_VOLUME_LIST statementIt is explicitly listed in the USER_VOLUME_INCLUDE statementIt satisfies a USER_VOLUME_INCLUDE pattern and does not satisfy aUSER_VOLUME_EXCLUDE statement.Chapter 6. The System Configuration File 251

USER_VOLUME_EXCLUDE2. Dedicated devices are not user volumes. They must be attached to the user towhich they are dedicated and not to the system. Therefore, if you specifyUSER_VOLUME_INCLUDE statements, you may want to specify dedicateddevices in USER_VOLUME_EXCLUDE statements.Examples1. To exclude volume XAUSRF from the user volume list, use the followingUSER_VOLUME_EXCLUDE statement:/* Exclude the following User Volume */User_Volume_Exclude xausrf /* from the System User Volume List. *//* NOTE: a previous USER_VOLUME_INCLUDE *//* XAUSR* would have caused this volume *//* to be mounted. */252 z/VM: CP Planning and Administration

USER_VOLUME_INCLUDEUSER_VOLUME_INCLUDE Statement►► USER_VOLUME_INclude ▼ volid ►◄PurposeUse the USER_VOLUME_INCLUDE statement to define user volumes by a genericvolume identifier and to include those volumes in the user volume list. (Uservolumes are those volumes that you use to contain minidisks.) During system IPL,CP attaches to the system any volumes whose volume identifiers match a genericvolume identifier specified in a USER_VOLUME_INCLUDE statement. A volumemust be attached to the system before users can link to minidisks it contains.How to SpecifyThe USER_VOLUME_INCLUDE statement is optional; if specified, you can includeas many statements as you need as long as the total number of volumes specifiedon a single statement does not exceed 500. If you specify a generic volumeidentifier, CP counts each volume that matches the pattern as one.OperandsYou can place USER_VOLUME_INCLUDE statements anywhere in the systemconfiguration file. If you specify more than one statement with the same operands,the last operand definition overrides any previous specifications.volidis a volume serial number or a generic volume serial number for a specificsubset of volumes. The variable volid is a 1- to 6-character alphanumeric stringwith no imbedded blanks. A generic volume serial number is a 1- to 6-characterstring with asterisks (*) in place of one or more arbitrary characters and percentsigns (%) in place of exactly one arbitrary character. For example:User_Volume_Includees%vm*creates a list that includes all volumes whose volume serial number start withES and have VM as their fourth and fifth characters.A single asterisk (*) attaches all volumes to the system.UsageNotes1. You can specify volumes that you do not want defined as user volumes byspecifying them on USER_VOLUME_EXCLUDE statements (page 251).2. If a volume identifier matches a generic volume identifier specified in bothUSER_VOLUME_INCLUDE and USER_VOLUME_EXCLUDE statements, CPdoes not attach the volume to the system during initialization. A duplicate volidcauses the entire statement to be rejected. A volume is automatically attachedto the system if:It is explicitly listed in the USER_VOLUME_LIST statementIt is explicitly listed in the USER_VOLUME_INCLUDE statementChapter 6. The System Configuration File 253

USER_VOLUME_INCLUDEIt satisfies a USER_VOLUME_INCLUDE pattern and does not satisfy aUSER_VOLUME_EXCLUDE statement.3. If a volume is normally attached to the system using aUSER_VOLUME_INCLUDE statement, CP does not notify the operator if thevolume is not mounted. If a user volume is necessary for normal systemoperation, specify it with a USER_VOLUME_LIST statement (page 255) so thatthe operator is notified during system initialization that the volume is notmounted.Examples1. To include all volumes whose first 5 characters are XAUSR in the user volumelist, use the following USER_VOLUME_INCLUDE statement:/* Include the following User Volumes */User_Volume_Include xausr* /* on the System User Volume List.. *//* So, any volume starting with *//* XAUSR* will be mounted. */254 z/VM: CP Planning and Administration

USER_VOLUME_LISTUSER_VOLUME_LIST Statement►► USER_VOLUME_List ▼ volid ►◄PurposeUse the USER_VOLUME_LIST statement to generate a list of user DASD volumes.(User volumes are those volumes you use to contain minidisks.) At system IPL, CPattaches the specified user volumes to the system. A volume must be attached tothe system before users can link to minidisks it contains.How to SpecifyThe USER_VOLUME_LIST statement is optional; if specified, you can include asmany statements as you need as long as the total number of volumes specified ona single statement does not exceed 500.OperandsYou can place USER_VOLUME_LIST statements anywhere in the systemconfiguration file.volidis the volume serial number of the DASD that you want included in the uservolume list. The variable volid is a 1- to 6-character string where each charactercan be a letter, number, or hyphen.UsageNotes1. If you do not specify user volumes in any USER_VOLUME_LIST statements,you can still attach a volume to a virtual machine or system using the CPATTACH command. For more information about the CP ATTACH command, seethe z/VM: CP Commands and Utilities Reference.2. If you specify a volume on a USER_VOLUME_LIST statement that is notmounted when you load CP, CP considers that volume unavailable. CP notifiesthe operator that the volume is not mounted and continues processing, ifpossible. The system operator can mount and attach the volume to the systemwhen it is needed using the CP ATTACH command. This provision leaves spacefor future growth.3. You can also define user volumes by specifying a generic volume identifier. Todo this, use the USER_VOLUME_INCLUDE statement (page 253).4. When more than one DASD volume is found at system initialization (IPL) tohave the same volume serial number (volid), and that volume serial number isin the CP or user volume list, the volume attached to the system is the one atthe lowest device number. This rule does not apply to duplicates of the systemresidence volume. For more information about the system residence volume,see note 2 on page 231.5. A duplicate volid causes the entire statement to be rejected.6. A volume is automatically attached to the system if:It is explicitly listed in the USER_VOLUME_LIST statementChapter 6. The System Configuration File 255

USER_VOLUME_LISTIt is explicitly listed in the USER_VOLUME_INCLUDE statementIt satisfies a USER_VOLUME_INCLUDE pattern and does not satisfy aUSER_VOLUME_EXCLUDE statement.Examples1. To add volumes USPK1, USPK2, USPK3, USPK4, and USPK5 to the userDASD volume list, use the following USER_VOLUME_LIST statements:User_Volume_List uspk1 /* Attach the following disks to the */User_Volume_List uspk2 /* system at IPL time. These disks */User_Volume_List uspk3 /* contain user minidisks. They */User_Volume_List uspk4 /* will be attached to the system */User_Volume_List uspk5 /* IPL time. */256 z/VM: CP Planning and Administration

VMLANVMLAN StatementPERSistent INFinitemaxcount►► VMLAN LIMit ▼ TRANSient INFinitemaxcount►◄ACNT ▼ SYSTEM OFFACCOUNTingONUSER OFFONMACPREFIX macprefixMACIDRange SYSTEM xxxxxx-xxxxxxUSERxxxxxx-xxxxxxPurposeOperandsUse the VMLAN statement to set control global attributes for VM Guest LANsupport.PERSistent INFiniteindicates the number of PERSISTENT VM LAN segments and Virtual Switchesallowed on the CP Host system as infinite. This is the default.PERSistent maxcountis the maximum number of PERSISTENT VM LAN segments and VirtualSwitches allowed on the CP Host system at one time. The value maxcountmust be a decimal number in the range of 0 to 1024. If PERSistent maxcount isnot specified, the system default is INFinite.A persistent LAN is created when the DEFINE LAN statement is used to createa LAN during system initialization, or when a Class B user defines a SYSTEMowned LAN. A persistent Virtual Switch is created when the DEFINE VSWITCHstatement is used to create the switch during system initialization, or when aClass B user defines a Virtual Switch.TRANSient INFiniteindicates the number of TRANSIENT VM LAN segments allowed on the CPHost system as infinite. This is the default.TRANSient maxcountis the maximum number of TRANSIENT VM LAN segments allowed on the CPHost system at one time. The value maxcount must be a decimal number in therange of 0 to 1024. If TRANSient maxcount is not specified, the system defaultis INFinite.A transient LAN is created when the DEFINE LAN command is used to define ageneral user LAN.ACNT|ACCOUNTing SYSTEM ON|OFFSet the default accounting state for VM LAN segments owned by the SYSTEMuser ID. The default state of this attribute is OFF. Class B users are authorizedto override this setting on the DEFINE LAN and SET LAN commands.Chapter 6. The System Configuration File 257

VMLANUsageNotesACNT|ACCOUNTing USER ON|OFFSet the default accounting state for VM LAN segments owned by individualusers. The default state of this attribute is OFF. Class B users are authorized tooverride this setting on the DEFINE LAN and SET LAN commands.MACPREFIX macprefixspecifies the three byte prefix (manufacturer ID) used when generating locallyadministered MAC addresses on the system. It must be 6 hexadecimal digitswithin the range of 020000 through 02FFFF (inclusive). In combination with theMAC ID used on the NICDEF directory statement, the MACPREFIX allowsunique identification of virtual adapters within a network. If MACPREFIX is notspecified, the default is 020000 (02–00–00).MACIDRange SYSTEM xxxxxx-xxxxxx USER xxxxxx-xxxxxxis the range of identifiers (up to six hexadecimal digits each) to be used by CPwhen generating the unique identifier part (last six hexadecimal digits) of avirtual adapter MAC address. If a SYSTEM MACIDRANGE is not specified, CPcreates unique identifiers in any range (000001–FFFFFF).USER xxxxxx-xxxxxx is the subset of the SYSTEM range of identifiers that arereserved for user definition of MACIDs in the NICDEF directory statement.When specified, CP does not assign MACIDs within this USER range duringcreation of virtual adapters defined dynamically (DEFINE NIC) or with theNICDEF (or SPECIAL) directory statement without the MACID operand. Inthese cases, CP generates a unique identifier for the adapter outside of theUSER range. Any MACID values specified on a NICDEF directory statementmust be within the USER range or the virtual adapter is not defined duringLOGON processing. If a USER MACIDRANGE is not specified, CP createsunique identifiers within the SYSTEM MACIDRANGE.1. Use the QUERY VMLAN command to find out the limits that have beenestablished for a running CP system.2. The limits established by the VMLAN statement only apply AFTER systeminitialization. The DEFINE LAN and DEFINE VSWITCH statements in SYSTEMCONFIG are not affected by these limits. Therefore, it is possible to find (usingQUERY VMLAN) that the current number of VM LAN segments is higher thanthe limit.3. To prohibit users from defining any VM LAN segments on a given system, setthe limit to zero (0). For example, ″VMLAN LIMIT TRANSIENT 0″ would preventgeneral users from creating VM LAN segments.4. Use the MACPREFIX and MACIDRange parameters if you require a predictableMAC address assignment for virtual NICs on your system. When you combinesystems using a virtual switch, each host should define a unique MACPREFIXin the SYSTEM CONFIG file to ensure that each host will generate unique MACaddresses.Examples1. To allow any number of PERSISTENT VM LAN segments, but set a limit of 20VM LAN segments for use on a transient basis, specify the following:vmlan limit persistent infinite transient 202. To enable accounting for every user-owned VM LAN segment, specify thefollowing:vmlan accounting user on258 z/VM: CP Planning and Administration

XLINK_DEVICE_DEFAULTSXLINK_DEVICE_DEFAULTS Statement►► XLINK_DEVICE_DEFaults TYPe33803390CLass 3CLass 012CLass 1239▼CYLinder 0CYLinder nnnnnMAP_RECORDS nnMAP_RECORD_LengthTRack 1TRack nnnnnnn►◄PurposeUse the XLINK_DEVICE_DEFAULTS statement to change the defaults for the CSEtrack location and format for specific types of DASD.Note: Although this statement allows you to change the definitions of cylinder,track, record length, and map records for the CSE track, we do notrecommend that you do so. This allows you to provide link support for newdevices with new geometries, should that become necessary in the future.Attention: Current upper limits may exceed capacities of present devices andcause errors when attempting to access beyond a particular device limit. Therefore,any change of defaults should be done with caution.How to SpecifyInclude as many statements as needed; they are optional. You can placeXLINK_DEVICE_DEFAULTS statements anywhere in the system configuration file.If you specify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.OperandsTYPe 3380tells CP that you want to change the defaults for a 3380 DASD. Optionally, youcan specify:CLass 0, 1, or 2tells CP that this 3380 DASD belongs in the 1770 cylinder size group.CLass 3(the default) tells CP that this 3380 DASD belongs in the 2655 cylinder sizegroup.If you are not sure which class to specify, we recommend that you choose acylinder size group which is larger than the actual number of cylinders on thedevice or choose the default.If you omit the CLASS operand for 3380 devices, CSE uses a value of 2655cylinders for all 3380 type K devices and 1770 for for all 3380 non-type Kdevices.Chapter 6. The System Configuration File 259

XLINK_DEVICE_DEFAULTSTYPe 3390tells CP that you want to change the defaults for a 3390 DASD. Optionally, youcan specify:CLass 1tells CP that this 3390 DASD belongs in the 1113 cylinder size group.CLass 2tells CP that this 3390 DASD belongs in the 2226 cylinder size group.CLass 3tells CP that this 3390 DASD belongs in the 3339 cylinder size group.CLass 9tells CP that this 3390 DASD belongs in the 10017 or greater, cylinder sizegroup. This class supports the maximum number of cylinders on the 3390.If you are not sure which class to specify, we recommend that you choose acylinder size class larger than the actual number of cylinders on the device.CYLinder nnnnntells CP the number of the cylinder where the CSE track is located for thespecified DASD type. The variable nnnnn is a decimal number from 0 to themaximum number of cylinders on the DASD. If omitted, the default is 0.Note: Although this statement allows you to change the cylinder definition forthe CSE track, it is not recommended. This allows you to provide linksupport for new devices with new geometries, should that becomenecessary in the future.Attention: Current upper limits may exceed capacities of present devices andcause errors when attempting to access beyond a particular device limit.Therefore, any change of defaults should be done with caution.MAP_RECORD nndefines the number of map records on the CSE track. The variable nn is adecimal number from 2 to 56. Specify as many records as will fit on one track.Table 8 shows the map record defaults for each device type.Table 8. Map Record Defaults for Each DASD TypeDevice Type Number of Map Records Map Record Length3380 non-type K 11 17703380 type K 8 26553390-1 (native) 12 11133390-1 (emulated) 12 11133390-2 (native) 8 22263390-2 (emulated) 8 22263390-3 (native) 8 33393390-3 (emulated) 8 33393390-9 (native) 56 10017¹OTHER 8 1024¹Value can be up to the maximum number of cylinders on the DASD.260 z/VM: CP Planning and Administration

XLINK_DEVICE_DEFAULTSUsageNotesNote: Although this statement allows you to change the definition of maprecords for the CSE track, it is not recommended. This allows you toprovide link support for new devices with new geometries, should thatbecome necessary in the future.Attention: Current upper limits may exceed capacities of present devices andcause errors when attempting to access beyond a particular device limit.Therefore, any change of defaults should be done with caution.MAP_RECORD_Length nnnnndefines the number of cylinders CP should make available for CSE to use. Thisvalue should be at least equal to the number of cylinders on the volume. Ifnnnnn is smaller than the number of cylinders on the volume CP denies links tominidisks on cylinders with a number higher than nnnnn. The variable nnnnn isa decimal number from 203 to the maximum number of cylinders on the DASD.Table 8 on page 260 shows the map record defaults for each device type.For CKD devices nnnnn also defines the record length of the map records. Onthese devices 1 byte in the map record corresponds to 1 cylinder. All cylindersare mapped in 1 physical record per system. On ECKD capable CKD devicesthere may be several physical records per system. One byte in the map recordcorresponds to 2 cylinders. Each physical record is 256 bytes and maps 512cylinders. The number of physical records needed depends on the number ofcylinders made available to CSE.Note: Although this statement allows you to change the definitions of recordlength for the CSE track, it is not recommended. This allows you toprovide link support for new devices with new geometries, should thatbecome necessary in the future.Attention: Current upper limits may exceed capacities of present devices andcause errors when attempting to access beyond a particular device limit.Therefore, any change of defaults should be done with caution.TRack nntells CP on which track of the specified CKD DASD to place the CSE track. Thevariable nn is a decimal number from 0 to 64, but you cannot specify TRACK 0if you also specified CYLINDER 0. If omitted, the default is TRACK 1.CP uses multiple tracks for ECKD capable CKD devices. The number of tracksused for ECKD capable CKD devices depends on the number of cylinders onthe volume. Thus, CP does not use the value specified in TRACK nn for anECKD capable CKD device.Note: Although this statement allows you to change the definition of track forthe CSE track, it is not recommended. This allows you to provide linksupport for new devices with new geometries, should that becomenecessary in the future.Attention: Current upper limits may exceed capacities of present devices andcause errors when attempting to access beyond a particular device limit.Therefore, any change of defaults should be done with caution.1. The CYLINDER, MAP_RECORD, MAP_RECORD_LENGTH, and TRACKoperands let you specify CSE track values that are different from the defaultvalues associated with the device type. This is not recommended unless thereis a valid reason for doing so.Chapter 6. The System Configuration File 261

XLINK_DEVICE_DEFAULTS2. The default parameters for model K devices are those associated with 3380CLASS=3, which are 2655 cylinders and 12 map records. If you want to makeall 3380s use the same parameters as model Ks, add the three followingstatements to each system configuration file:Xlink_Device_Defaults Type 3380 Class 0,MAP_Record 8,MAP_Record_Length 2655Xlink_Device_Defaults Type 3380 Class 1,MAP_Record 8,MAP_Record_Length 2655Xlink_Device_Defaults Type 3380 Class 2,MAP_Record 8,MAP_Record_Length 2655Examples1. Normal defaults for the placement of the CSE cross system link protection(XLINK) map on cylinder 0 track 1. If this default is inappropriate for yourinstallation, you may specify a different DASD location on everyXLINK_VOLUME_INCLUDE statement (q.v.), or use theXLINK_DEVICE_DEFAULTS statement.For example, suppose that all of your 3390 devices, regardless of capacity,must reserve all tracks on cylinder 0 for other uses. Because of this, you decideto place the XLINK map on cylinder 5 track 0. Therefore, use the followingXLINK_DEVICE_DEFAULTS statement:Xlink_Device_Defaults Type 3390 Cylinder 5 Track 0Any individual volumes on 3390 devices could have their XLINK map placedelsewhere on the device by use of the XLINK_VOLUME_INCLUDE statement.262 z/VM: CP Planning and Administration

XLINK_SYSTEM_EXCLUDEXLINK_SYSTEM_EXCLUDE Statement►► XLINK_SYSTEM_EXclude sysname ►◄PurposeUse the XLINK_SYSTEM_EXCLUDE statement to specify the systems that CP is toexclude from cross system link (prevent from accessing each other’s minidisksusing cross system link). This statement has no effect on systems’ participation incross system spooling or cross system commands.How to SpecifyInclude as many statements as needed; they are optional. You can placeXLINK_SYSTEM_EXCLUDE statements anywhere in the system configuration file.If you specify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.Operandssysnameis the 1- to 8-character name of a system that CP is to exclude from crosssystem link. This statement has no effect on a system’s participation in crosssystem spooling or cross system commands.UsageNotes1. If a system name is specified on both an XLINK_SYSTEM_EXCLUDEstatement and an XLINK_SYSTEM_INCLUDE statement, CP will ignore theXLINK_SYSTEM_EXCLUDE statement.2. Fixed-Block Architecture (FBA) devices are supported by the CSE function forspooling only. The cross system link function of CSE is not supported for FBAdevices.Examples1. To exclude systems VM1, VM2, VM3, and VM4 from cross system link, use thefollowing XLINK_SYSTEM_EXCLUDE statements:Xlink_System_Exclude vm1 /* Exclude the following systems from */Xlink_System_Exclude vm2 /* cross system links so that no one */Xlink_System_Exclude vm3 /* on the other CSE systems will have */Xlink_System_Exclude vm4 /* access to them. */Chapter 6. The System Configuration File 263

XLINK_SYSTEM_INCLUDEXLINK_SYSTEM_INCLUDE Statement►► XLINK_SYSTEM_INclude Slot n sysname ►◄PurposeUse the XLINK_SYSTEM_INCLUDE statement to specify the systems that CP is toinclude in cross system link. None of these systems need to share spool file accesswith any other system in the complex, nor need they send or receive cross systemcommands.How to SpecifyInclude as many statements as needed; they are optional. You can placeXLINK_SYSTEM_INCLUDE statements anywhere in the system configuration file. Ifyou specify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.OperandsSlot ntells CP what position this system will hold in the list of systems participating inCSE cross system link. The maximum value of n depends on the type of DASDunder CSE cross system link protection.sysnameis the 1- to 8-character name of a system to be included in cross system linkonly.UsageNotes1. If a system name is specified on both an XLINK_SYSTEM_EXCLUDEstatement and an XLINK_SYSTEM_INCLUDE statement, CP ignores theXLINK_SYSTEM_EXCLUDE statement.2. If you specify any systems on the XLINK_SYSTEM_INCLUDE orXLINK_SYSTEM_EXCLUDE statements and the system that you IPL is inneither list, CP prompts the operator with a warning that this omission maycause the loss of data integrity. The operator can choose to stop the systeminitialization process, continue as normal, or allow system initialization tocontinue but have CP skip the normal process of autologging users.3. The order of system names in XLINK_SYSTEM_INCLUDE statements for allsystems participating in CSE cross system link must be identical. That is, thesystem name for all XLINK_SYSTEM_INCLUDE SLOT 1 statements must bethe same for all systems.Examples1. To include systems BOSTON3, NEWYORK, and BOSTON4 in cross system linkin slots 1, 2, and 3 (respectively), use the following XLINK_SYSTEM_INCLUDEstatements:/*---------------------------------------------------*//* Include the BOSTON3, NEWYORK, and BOSTON4 systems *//* in cross system linking. Note: Non of these *//* systems have to share spool or commands. *//*---------------------------------------------------*/264 z/VM: CP Planning and Administration

XLINK_SYSTEM_INCLUDEXlink_System_Include Slot 1 boston3Xlink_System_Include Slot 2 newyorkXlink_System_Include Slot 3 boston4Chapter 6. The System Configuration File 265

XLINK_VOLUME_EXCLUDEXLINK_VOLUME_EXCLUDE Statement►► XLINK_VOLUME_EXclude volid ►◄PurposeUse the XLINK_VOLUME_EXCLUDE statement to define DASD volumes to beexcluded from the cross system link operation. The volumes specified are not to beshared through cross system link. These volumes, if mounted and shared amongsystems, have no extended link protection.How to SpecifyInclude as many statements as needed; they are optional. You can placeXLINK_VOLUME_EXCLUDE statements anywhere in the system configuration file.If you specify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.Operandsvolidis a volume serial number or a generic volume serial number for a specificsubset of volumes to be excluded from sharing by cross system link. Thevariable volid is a 1- to 6-character alphanumeric string with no imbeddedblanks. A generic volume serial number is a 1- to 6-character string withasterisks (*) in place of one or more arbitrary characters and percent signs (%)in place of exactly one arbitrary character. For example:Xlink_Volume_Excludees%vm*UsageNotesexcludes all volumes whose volume serial number start with ES and have VMas their fourth and fifth characters.1. If you do not specify XLINK_VOLUME_EXCLUDE and the system that you areIPLing has been specified in an XLINK_SYSTEM_INCLUDE statement, allDASD volumes are included in cross system link protection.2. If you do not specify XLINK_VOLUME_EXCLUDE andXLINK_VOLUME_INCLUDE (page 268) statements, and the system that youare IPLing is specified on an XLINK_SYSTEM statement, all DASD volumes areincluded in cross system link protection.3. A volume is included in cross system link protection if it is:v Explicitly listed on an XLINK_VOLUME_INCLUDE statement, orv Matched by a generic volume identifier on an XLINK_VOLUME_INCLUDEstatement and not found (either explicitly or generically) on anXLINK_VOLUME_EXCLUDE statement.Examples1. To exclude volumes VMUSR4, VMUSR7, and VMUSR9 from cross systemlinking, use the following XLINK_VOLUME_EXCLUDE statements:266 z/VM: CP Planning and Administration

XLINK_VOLUME_EXCLUDEXlink_Volume_Exclude vmusr4 /* Exclude VMUSR4, VMUSR7, and */Xlink_Volume_Exclude vmusr7 /* VMUSR9 from cross system */Xlink_Volume_Exclude vmusr9 /* link operations ... */Chapter 6. The System Configuration File 267

XLINK_VOLUME_INCLUDEXLINK_VOLUME_INCLUDE Statement►► XLINK_VOLUME_INclude volid►◄▼ CYLinder nnnnnMAP_RECORDS nnMAP_RECORD_LengthTRack nnnnnnnPurposeUse the XLINK_VOLUME_INCLUDE statement to define the DASD volumes to beincluded in the cross system link operation. If you do not use this statement, allvolumes are included.How to SpecifyInclude as many statements as needed; they are optional. You can placeXLINK_VOLUME_INCLUDE statements anywhere in the system configuration file. Ifyou specify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.Operandsvolidis a volume serial number or a generic volume serial number for a specificsubset of volumes to be included in sharing by cross system link. The variablevolid is a 1-character to 6-character alphanumeric string with no imbeddedblanks. A generic volume serial number is a 1-character to 6-character stringwith asterisks (*) in place of one or more arbitrary characters and percent signs(%) in place of exactly one arbitrary character. For example:Xlink_Volume_Includees%vm*includes all volumes whose volume serial number start with ES and have VMas their fourth and fifth characters.CYLinder nnnnndefines the cylinder where the CSE track is located for every volid. The variablennnnn is a decimal number from 0 to the maximum number of cylinders on theDASD. If omitted, the default is 0. If CP is to use a volume that is to beincluded in cross system link as an IPL device for the stand-alone dump utility,you must specify a cylinder other than the default of 0 for that volume.MAP_RECORDS nndefines the number of map records on the CSE track. The variable nn shouldnot be smaller than the number of systems that share the volume. If it is, thenall links to minidisks on this volume are denied. We recommend that you use asmany records as can fit on one track. See Table 9 on page 269 for the defaultvalues.MAP_RECORD_Length nnnnndefines the number of cylinders made available for CSE use. This value shouldnot be smaller than the number of cylinders on the volume. If it is, links tominidisks starting on a cylinder with a number higher than nnnnn are denied.268 z/VM: CP Planning and Administration

XLINK_VOLUME_INCLUDEUsageNotesThe variable nnnnn is a decimal number from 203 to the maximum number ofcylinders on the DASD. See Table 9 for the default values.For CKD devices, nnnnn also defines the record length of the map records. Onthese devices, one byte in the map record corresponds to one cylinder. Allcylinders are mapped in one physical record per system. On ECKD-capableCKD devices, there may be several physical records per system, as one byte inthe map record corresponds to two cylinders. Each physical record is 256 bytesand maps 512 cylinders. The number of physical records needed depends onthe number of cylinders made available to CSE.TRack nndefines the track number on which the CSE track is located for every CKDDASD volume matching volidn. The variable nn is a decimal number from 0 to64, but it cannot be 0 if the value of CYLINDER is 0. If omitted, the default is 1.For ECKD-capable CKD devices, multiple tracks are used. The number oftracks used for ECKD-capable CKD devices depends on the number ofcylinders on the volume. The value specified in TRACK nn is not used for anECKD-capable CKD device matching volidn.1. If you do not specify XLINK_VOLUME_INCLUDE andXLINK_VOLUME_EXCLUDE (page 266) statements, and the system that youare IPLing is specified on an XLINK_SYSTEM statement, all DASD volumes areincluded in cross system link protection.2. A volume is included in cross system link protection if it is:v Explicitly listed on an XLINK_VOLUME_INCLUDE statement, orv Matched by a generic volume identifier on an XLINK_VOLUME_INCLUDEstatement and not found (either explicitly or generically) on anXLINK_VOLUME_EXCLUDE statement.3. The values you choose for CYLINDER and TRACK must be valid for the devicetype or types on which the specified volumes reside. This statement does notmake sure that your values are valid, because when it is processed, the devicetypes are not yet known.4. Although the XLINK_VOLUME_INCLUDE enables you to change the definitionsof cylinder, track, record length, and map records for the CSE track, we do notrecommend that you do so. We have included this capability to provide linksupport for new devices with new geometries, should that support becomenecessary in the future. Table 9 shows the map record defaults for each devicetype.Table 9. Map Record Defaults for Each Device TypeDevice Type Number of Map Records Map Record Length3380 non-type K 11 17703380 type K 8 26553390-1 (native) 12 11133390-1 (emulated) 12 11133390-2 (native) 8 22263390-2 (emulated) 8 22263390-3 (native) 8 33393390-3 (emulated) 8 3339Chapter 6. The System Configuration File 269

XLINK_VOLUME_INCLUDETable 9. Map Record Defaults for Each Device Type (continued)Device Type Number of Map Records Map Record Length3390-9 (native) 56 10017¹OTHER 8 1024¹Value can be up to the maximum number of cylinders on the DASD.5. These defaults support the current CKD and ECKD-capable CKD DASD. Thelength of each map record is the maximum number of cylinders on any currentlyexisting model of that device type. The number of records defined for otherdevices is 8, but the actual number of records used is limited to the number thatfits on a track of such “other” device.Examples1. To include DASD volumes USRPK1, USRPK2, and USRPK3 in cross systemlinking, use the following XLINK_VOLUME_INCLUDE statements:Xlink_Volume_Include usrpk1 /* Include USERPK1, USERPK2 and */Xlink_Volume_Include usrpk2 /* USERPK3 in cross system link */Xlink_Volume_Include usrpk3 /* operations ... */270 z/VM: CP Planning and Administration

XSPOOL_SYSTEMXSPOOL_SYSTEM Statement►► XSPOOL_SYStem Slot nRESERVEd►◄sysname▼Alias aliasCOMMunications_useridPVMCOMMunications_useridSHARE_SPool YesuseridSHARE_SPool NoTIMEout 12 SECondsTIMEoutnnnnnSECondsPurposeUse the XSPOOL_SYSTEM statement to specify the systems that are to participatein cross system commands and spooling operations.How to SpecifyInclude as many statements as needed; they are optional. You can placeXSPOOL_SYSTEM statements anywhere in the system configuration file. If youspecify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.OperandsSlot ntells CP what position this system will hold in the list of systems participating inCSE cross system link. The variable n is a decimal number from 1 to 4 and themaximum value of n depends on the type of DASD under CSE cross systemlink protection.RESERVEdtells CP to reserve the slot for future use.sysnameis the 1- to 8-character system name.Alias aliasis a 1- to 8-character nickname for sysname that people can use in CPcommands instead of sysname to identify the system.COMMunications_userid useridis the 1- to 8-character user ID of the communication virtual machine (CVM) forsharing spool files and cross system commands. If omitted, the default is PVM.SHARE_SPool Yes(the default) tells CP that the specified system can share spool files with thesystem you are IPLing.Chapter 6. The System Configuration File 271

XSPOOL_SYSTEMUsageNotesNote: If you have DIRMAINT Release 5 operating in your CSE complex andyou specify SHARE_SPOOL YES, you must specifyGLOBAL_SMSG=NO in the DIRMAINT DATA file.SHARE_SPool Notells CP that the specified system is excluded from sharing spool systemcontinues to participate in cross system link and cross system commands.TIMEout nnnnn SECondstells CP how many seconds to wait for a response from another system. Thiswaiting (or timeout) period applies to the overall status of the communicationlink, rather than being associated with a particular transaction. When the systemyou are IPLing sends a request to another system, CP waits for a response. IfCP does not get a response before the timeout period expires, CP:v Terminates the request with an error,v Assumes that the CVM link to that system (or the system itself) is down, andv Notifies the system operator (by message) of this event.Until the system operator restores the connection, no cross system spoolprocessing can take place between these two systems.The variable nnnnn is any decimal number from 1 to 65535. If omitted, thedefault is 12 seconds.1. A system name, sysname, must have the same slot number in all the lists on allthe systems using cross system commands and shared spool operations.2. Because some system in the list may not be using a particular slot number, youcan use the RESERVED operand reserve a slot that is not used on the systemthat you are IPLing, but is used elsewhere in the complex.Examples1. To define two systems (BOSTON and NEWYORK) that will participate in crosssystem commands and spooling operations, use the followingXSPOOL_SYSTEM statements:XSpool_System Slot 1 bostonXSpool_System Slot 2 newyork272 z/VM: CP Planning and Administration

XSPOOL_TRACEXSPOOL_TRACE Statement►► XSPOOL_TRace nnnPages►◄PurposeUse the XSPOOL_TRACE statement to define the number of pages of storage thatCP should allocate for the cross system spool (XSPOOL) trace tables.How to SpecifyInclude as many statements as needed; they are optional. You can placeXSPOOL_TRACE statements anywhere in the system configuration file. If youspecify more than one statement with the same operands, the last operanddefinition overrides any previous specifications.Operandsnnn Pagestells CP how many pages to allocate for the XSPOOL trace tables when youinitialize the system. The variable nnn is a decimal number from 0 to 255. Ifomitted, CP allocates 4 pages. If specified as 0, CP does not allocate anypages for XSPOOL trace tables.UsageNotes1. The first trace table has enough space to hold 16 synchronization requests and111 CVM communication requests. Each additional page has space for 127more CVM communication requests. When this number is exceeded, the tracetables wrap around, and the previously recorded entries are overwritten.Examples1. To have CP allocate 10 pages of storage for the XSPOOL trace tables, use thefollowing XSPOOL_TRACE statement:XSpool_Trace 10 Pages /* Allow for 10 CSE Trace Frames *//* Each frame holds 16 Sync Requests *//* and 111 CVM communication requests. */Chapter 6. The System Configuration File 273

XSPOOL_XLIST_INPUTXSPOOL_XLIST_INPUT Statement►► XSPOOL_XLIST_INput ▼ userid ►◄PurposeUse the XSPOOL_XLIST_INPUT statement to specify virtual machines whose inputspool files will not participate in cross system spooling and cross system messageand query commands. The other systems in the shared spool complex will not haveaccess to input (reader) spool files owned by the user IDs specified in thesestatements.How to SpecifyThe XSPOOL_XLIST_INPUT statement is optional; if specified, you can include asmany statements as you need as long as the total number of user IDs does notexceed 500. If you specify a generic user ID, CP counts each user that matches thepattern as one.OperandsYou can place XSPOOL_XLIST_INPUT statements anywhere in the systemconfiguration file. If you specify more than one statement with the same operands,the last operand definition overrides any previous specifications.useridis the 1- to 8-character user ID or generic user ID of a virtual machine whoseinput files are to be excluded from access to cross system spooling. A genericuser ID is a 1- to 8-character string with asterisks (*) in place of one or morearbitrary characters and percent signs (%) in place of exactly one arbitrarycharacter. For example:Xspool_Xlist_Inputus%vm*creates a list that includes all user IDs that start with US and have VM as theirfourth and fifth characters.UsageNotes1. If your installation uses DIRMAINT Release 5, the DIRMAINT user ID andsatellite machine user IDs must not be coded in XSPOOL_XLIST_INPUTstatements.2. User IDs listed in XSPOOL_XLIST_INPUT statements have operationalcharacteristics that are different from the characteristics of those that are notlisted. The users associated with the listed user IDs:v Can log on to more than one system in the complex at the same time. Userswhose user IDs are not listed here cannot.v Receive messages generated by the CP MSG, MSGNOH, WNG, and SMSGcommands, but only from users on the same system they are on, unless theuser entering the CP command specifies the AT parameter.Also, when these users:274 z/VM: CP Planning and Administration

XSPOOL_XLIST_INPUTv Enter a CP QUERY userid or QUERY NAMES command, only the system onwhich the command was entered is queried, unless the issuer specifies theAT parameter.v Are the target of a CP QUERY userid command, only the system on whichthe command was entered is queried, unless the issuer specifies the ATparameter.3. CP automatically excludes the:v Default system operatorv Communication virtual machine (CVM).Do not code any XSPOOL_XLIST_INPUT statements for these virtualmachines. You may decide that other virtual machines should also be excluded,but for ease of operation and administration of the shared spool complex, keepexclusions to a minimum.4. The XSPOOL_XLIST_INPUT list for every system in the shared spool complexmust be the same; the XSPOOL_XLIST_OUTPUT list for every system in theshared spool complex must be the same.Examples1. To specify that the input spool files of user IDs OPERATOR, MAINT, DAWN,and RICH are excluded from cross system spooling and cross system messageand query commands, use the following XSPOOL_XLIST_INPUT statements:Xspool_Xlist_Input Operator /* Userid Operator, Maint, Dawn */Xspool_Xlist_Input Maint /* and Rich’s input files will */Xspool_Xlist_Input Dawn /* not participate in CSE */Xspool_Xlist_Input Rich /* spooling. */Chapter 6. The System Configuration File 275

XSPOOL_XLIST_OUTPUTXSPOOL_XLIST_OUTPUT Statement►► XSPOOL_XLIST_OUTput ▼ userid ►◄PurposeUse the XSPOOL_XLIST_OUTPUT statement to specify virtual machines whoseoutput spool files will not participate in cross system spooling and cross systemmessage and query commands. The other systems in the shared spool complex willnot have access to output (printer and punch) spool files owned by the user IDsspecified in these statements.How to SpecifyThe XSPOOL_XLIST_OUTPUT statement is optional; if specified, you can includeas many statements as you need as long as the total number of user IDs does notexceed 500. If you specify a generic user ID, CP counts each user that matches thepattern as one.OperandsYou can place XSPOOL_XLIST_OUTPUT statements anywhere in the systemconfiguration file. If you specify more than one statement with the same operands,the last operand definition overrides any previous specifications.useridis the 1- to 8-character user ID or generic user ID of a virtual machine whoseoutput files are to be excluded from access to cross system spooling. A genericuser ID is a 1- to 8-character string with asterisks (*) in place of one or morearbitrary characters and percent signs (%) in place of exactly one arbitrarycharacter. For example:Xspool_Xlist_Outputus%vm*creates a list that includes all user IDs that start with US and have VM as theirfourth and fifth characters.UsageNotes1. If you have DIRMAINT Release 5 installed, you cannot specify the DIRMAINTuser ID and satellite machine user IDs on the XSPOOL_XLIST_OUTPUTstatement.2. User IDs you specify on the XSPOOL_XLIST_OUTPUT statement haveoperational characteristics that are different from the characteristics of the userIDs that are not listed. The users associated with these user IDs:v Can log on to more than one system in the complex at the same time. Userswhose user IDs are not listed here cannot.v Receive messages generated by the CP MSG, MSGNOH, WNG, and SMSGcommands, but only from users on the same system they are on, unless theuser entering the CP command specifies the AT operand.Also, when these users:276 z/VM: CP Planning and Administration

XSPOOL_XLIST_OUTPUTv Enter a CP QUERY userid or QUERY NAMES command, CP only queriesthe system on which the command was entered, unless the user specifies theAT operand.v Are the target of a CP QUERY userid command, CP only queries the systemon which the command was entered, unless the person who issued thecommand specified the AT operand.3. CP automatically excludes the:v Default system operatorv Communication virtual machine (CVM).Do not specify any XSPOOL_XLIST_OUTPUT statements for these virtualmachines. Your installation may decide that other virtual machines should alsobe excluded, but for ease of operation and administration of the shared spoolcomplex, keep exclusions to a minimum.4. The XSPOOL_XLIST_INPUT list for every system in the shared spool complexmust be the same; the XSPOOL_XLIST_OUTPUT list for every system in theshared spool complex must be the same.Examples1. To specify that the output spool files of user IDs OPERATOR, KERRY, DAVID,and MAINT are excluded from cross system spooling and cross systemmessage and query commands, use the following XSPOOL_XLIST_OUTPUTstatements:Xspool_Xlist_Output Operator /* Userid Operator, Kerry, David */Xspool_Xlist_Output Kerry /* and Maint’s output spool files */Xspool_Xlist_Output David /* will not participate in CSE */Xspool_Xlist_Output Maint /* spooling. */Chapter 6. The System Configuration File 277

XSPOOL_XLIST_OUTPUT278 z/VM: CP Planning and Administration

Chapter 7. The Logo Configuration FileThis chapter:v Provides a summary of logo configuration file statementsv Provides general rules for coding the logo configuration filev Describes each logo configuration file statement in detailUsing a Logo Configuration FileCreating a logo configuration file allows you to change features of logos that appearon the screen or on separator pages of printed output. The logo configuration fileoverrides the default logo information, which is defined in the HCPBOX ASSEMBLEfile included in the CP module. For example, you can:v Have certain logo picture files appear on certain terminalsv Include your own information in status and online fieldsv Place often-used command text in the command input field on the logo screenThe name of the logo configuration file defaults to LOGO CONFIG unless youspecify a different name on the LOGO_CONFIG statement in the systemconfiguration file. You must place the logo configuration file and the files to which itrefers on the parm disk, the CMS minidisk that CP will access at IPL time.Summary of Logo Configuration File StatementsTable 10 lists all the logo configuration file statements, gives you a brief descriptionof each statement, and points you to where you can get more information abouteach statement.Table 10. Logo Configuration File Statements (LOGO CONFIG)Statement Description PageCHOOSE_Logo Defines the logo picture files that CP uses for specified terminals and for separator pages 285of printed output.INPUT_AREA Defines which file CP uses when displaying the input area of the logo. 291ONLINE_MESSage Specifies the file whose text CP should use for the online message area of the logo. 292STATUS Defines the text of the status fields displayed in the bottom right corner of the screen. 293General Rules for Coding a Logo Configuration FileWhen creating or updating a logo configuration file, you must follow some generalsyntax rules.FormatCommentsThe logo configuration file can be a fixed or variable length record file. No individualrecord in the file should be longer than 4000 characters. No individual statement inthe file should be longer than 4000 characters after all continuations of thestatement have been resolved.You can add comments to the file by delimiting them with /* and */. A singlecomment may span multiple records in the file. Thus,© Copyright IBM Corp. 1991, 2004 279

Logo Configuration File/*-------------------------------------------------** The following section defines the status areas **-------------------------------------------------*/is valid. As many comments as necessary may be entered on a single record in thefile. For example,Choose_logo default /* fn ft */ LOGO DEFAULT /* Default cmd */ ’DIAL PVM’is allowed.ContinuationsTo put a statement in more than one record of the configuration file, place a commaat the ends of all but the last line of the statement. For example, you can code theCHOOSE_LOGO statement as follows:Choose_logo Local ,Address 100-200 ,Screen_size 27x132 ,MODEL5 LOGO ,’DIAL VTAM’A comma at the end of a line indicates that the statement is not yet complete. Youshould not code a comma if the statement information is complete but a commentcontinues to the next record.Choose_logo Local ,Address 100-200 ,Screen_size 27x132 ,MODEL5 LOGO ,'DIAL VTAM' /* Go to VTAM if user entersnothing for user or password */is valid, but a comma after 'DIAL VTAM' would make the statement invalid, as youhave specified no subsequent options. The comma can be placed directly after thelast entry on the line. Thus, the example above would also be valid if specified asChoose_logo Local,Address 100-200,Screen_size 27x132,MODEL5 LOGO,'DIAL VTAM' /* Go to VTAM if user entersnothing for user or password */Finally, a blank line does not cause a continuation to be terminated. You couldspecifyChoose_logo Local,Address 100-200,Screen_size 27x132,MODEL5 LOGO,'DIAL VTAM' /* Go to VTAM if user entersnothing for user or password */because CP ignores any blank lines in the configuration file.CaseIn general, it does not matter whether information in the logo configuration file isentered in upper case or mixed case. Most entries in the configuration file areconverted to upper case before they are processed. Thus,Status Running Running280 z/VM: CP Planning and Administration

Logo Configuration FileandStatus Running RUNNINGwould have the same results. An exception to this rule occurs when CP encountersa quoted string in the file. A quoted string is any string enclosed within singlequotation marks; the string may contain blanks and special character sequencessuch as /* and */ that are not usually permitted in a single token. Where quotedstrings are allowed and a quoted string is specified in the configuration file, the textinside the quotation marks is not converted to upper case. In the following example,the specified status area would remain in mixed case:Status Running 'Running'CategoriesPrecedenceEach of the four statements in a logo configuration file modifies a different part ofthe screen.v CHOOSE_LOGO defines the logo picture that occupies the center of a screen.v INPUT_AREA defines the input area that contains the user ID, password, andcommand areas.v ONLINE_MESSAGE defines the online message that appears at the top of thescreen.v STATUS defines the status area in the lower right hand portion of the screen.You can include more than one INPUT_AREA or ONLINE_MESSAGE statement inthe configuration file, but CP will use only the last occurrence of a given statementduring logo processing. For example,Input_Area INPUT FILEfollowed byInput_Area INPUT AREAwould cause CP to use the file INPUT AREA instead of INPUT FILE.You can code a STATUS statement for each of the different operands. You cancode multiple STATUS statements with the same operand, but CP will use only thelast one with a given operand. For example,Status Running ’Going ’followed byStatus Running ’Gone ’would cause CP to use Gone instead of Going.You should code CHOOSE_LOGO statements in three separate groups, one foreach of the following categories:v Locally attached terminalsv Terminals logging on through logical devicesv Terminals managed by a VSM.Chapter 7. The Logo Configuration File 281

Logo Configuration FileWithin these groups, you should code statements in the order of least specific tomost specific. Statements that choose logo picture files for certain terminals within agroup should occur after statements that choose files for all the terminals in thatgroup.CP puts the information specified on each group of CHOOSE_LOGO statementsinto separate search chains, which it searches from the bottom up. When CPencounters a terminal, it goes through the search chain established for similarterminals until it finds a statement that applies to the specific terminal. Thus, for agiven terminal, CP uses the last statement in the logo configuration file that applies.SelectionThe type of terminal determines the process that CP uses to select a logo picturefile. CP supports three types of terminals:v Terminals directly managed by CPv Terminals logging on through logical devicesv Terminals managed by a VTAM service machine (VSM)Creating Logo ScreensFor each type, CP looks at a series of CHOOSE_LOGO statements to find outwhich logo picture file to use for a terminal.v For terminals that CP manages directly, CP searches through CHOOSE_LOGOstatements with the LOCAL operand.v For terminals represented by logical devices, it searches throughCHOOSE_LOGO statements with the LDEV operand.v For terminals managed by a VSM, it searches through CHOOSE_LOGOstatements with the VSM operand.In all three cases, if CP cannot find a statement that applies to a given terminal, itwill use the file specified on the CHOOSE_LOGO DEFAULT statement, if there isone.If CP finds a statement that applies to a terminal, but the logo picture file it specifiesis too large for the screen, CP will skip the statement and try the next one in thesearch order.When CP gets to the end of the search order, the last file it will try to use is eitherthe one specified on a CHOOSE_LOGO DEFAULT statement, or, if there is no suchstatement, the default logo in HCPBOX. If the default logo picture file (from eithersource) is too large, CP will use the file specified on the CHOOSE_LOGOMINIMUM statement, if there is such a statement.If all else fails, CP will use the logos defined in HCPBOX.You can use the DRAWLOGO sample utility program to create logo screens foryour system. DRAWLOGO invokes the X$DRWL$X sample XEDIT macro. With thisutility, you can edit the text of the logo file and modify the 3270 screen attributes ofthe logo components in a logo file:v The online messagev The picturev The input area282 z/VM: CP Planning and Administration

Logo Configuration FileDRAWLOGO creates these logo files on the first CMS minidisk accessed in R/Wmode. By default, the file type is LOGO. For example, assuming file mode A isaccessed in read/write mode, to create LOCOTERM LOGO A, enter:drawlogo locotermIn addition to using XEDIT commands, you can use special functions that aredefined for the PF keys:v Insert 3270 attributes (for colors, highlighting, and so on) When you insert anattribute into your logo, a special symbol appears on your screen to mark theposition of the attribute. This symbol does not appear when the logo is put intoproduction and displayed by CP.v Change attributesv Insert input field markers.v Display your logo as you are creating it.For the complete description of DRAWLOGO, see “DRAWLOGO” on page 642.DRAWLOGO creates a new logo configuration file, but it does not put it intoproduction. To replace the current system logo configuration file with LOCOTERMLOGO, use the CP REFRESH command:1. Put LOCOTERM LOGO on a CMS-formatted minidisk accessed by CP.2. Enter:refresh logoinfo locoterm logoFor information about the REFRESH command, see the z/VM: CP Commands andUtilities Reference.Special Considerations When Creating LogosYou can use certain special characters to add color anywhere in theONLINE_MESSAGE and CHOOSE_LOGO files. If you do so, be careful when youuse the INPUT_AREA file, as the screen cursor will be tabbed to the stringsdefining the beginning of the color fields as well as to the various INPUT_AREAfields.Other special characters are defined for use in building an INPUT_AREA file. Theinput area consists of the user ID, password, and command areas.The use of four colors is supported. PF (program function) keys are defined to allowthe insertion of the correct hexadecimal values. The colors defined are as follows:Table 11. Colors for the CHOOSE_LOGO and ONLINE_MESSAGE FilesColor Hexadecimal RepresentationBlueGreenRed1DF01D401DC8White, highlighting 1DF8Protected field 1D70The input area comprises three input fields, user ID, password, and commandareas. Customarily they appear in this order; the user ID area must precede thepassword area. The fields may all appear on the same line or on different lines.Chapter 7. The Logo Configuration File 283

Logo Configuration FilePF (program function) keys are also defined to assist in their use. A table of thedifferent fields and their values follows.Table 12. Input Area FieldsField ID Hexadecimal RepresentationUser ID 1D4013PasswordCommand1D4C1D40The above values are the same as in HCPBOX. Logo processing scans the inputarea for these values in order to determine where to read from the screen. For thelogon process to operate correctly, these values must be used.284 z/VM: CP Planning and Administration

CHOOSE_LOGOCHOOSE_LOGO Statement►►CHOOSE_LogoDEFaultLDEV▼MODel 2345SCReen_size rowsXcolumnsUSERid useridFilefnft'text'(1)►◄LOCal▼ADDRessMINimumPRINT_SEParatorVSMUSERidMODel 2345SCReen_sizeuseridrdevrdev-rdevrowsXcolumnsNotes:1 If you specified MINIMUM, PRINT_SEPARATOR, or VSM, you cannot specify text.PurposeUse the CHOOSE_LOGO statement to tell CP which logo picture files to use forterminals and printer separator pages. You can have separate logo picture files for:v All terminals logging on to a systemv Terminals directly attached to a particular systemv Locally-attached terminals at certain device addressesv Terminals logging on through a logical devicev Terminals too small to accommodate files selected for them by anotherCHOOSE_LOGO statementv Separator pages of printed output from spooling printersv Terminals logging on through a particular VTAM service machine (VSM) user ID.How to SpecifyInclude as many statements as needed; they are optional. You can placeCHOOSE_LOGO statements anywhere in the LOGO CONFIG file. Be aware thatwhen looking for the proper logo picture file to display, CP starts at the bottom ofyour LOGO CONFIG file and works its way up until it finds the firstCHOOSE_LOGO statement that applies. Therefore, when specifying multipleCHOOSE_LOGO statements, put the generic ones at the top of the file and put thespecific ones at the bottom.Chapter 7. The Logo Configuration File 285

CHOOSE_LOGOOperandsDEFaulttells CP which logo picture file to use when no other CHOOSE_LOGOstatements apply to a specific terminal.LDEVtells CP which logo picture file to use for terminals logging on to the systemthrough a logical device. You can choose to have one logo picture file for allterminals or you can choose a specific model number, screen size, or user ID:MODeltells CP the model number of the terminal. The table below shows thescreen size associated with each model:Model Equivalent Screen Size2 24 by 803 32 by 804 43 by 805 27 by 132Note: MODEL operands only apply to terminals with at least as many rowsand columns as the screen size that the model number implies. Forexample, if you had the following statements in your LOGO CONFIGfile:Choose_Logo Default File DEFAULT LOGOChoose_Logo Ldev Model 3 File PVM LOGOand a user with a 24 by 80 terminal used the PVM logical device toget to your system, that user would be looking at the DEFAULTLOGO, not the PVM LOGO. The user needs at least a 32 by 80terminal to see the PVM LOGO..SCReen_size rowsXcolumnstells CP the screen size of the terminal. SCREEN_SIZE operands onlyapply to terminals with at least as many rows and columns as the user’sactual screen size.USERid useridtells CP to use a specific logo picture file for a specific user ID that createsthe logical device (for example, PVM or TCP/IP). You can use this operandto tell CP to use a certain logo picture file for terminals logging on throughcertain types of logical devices.LOCaltells CP which logo picture file to use for devices attached directly to thesystem. You can choose to have one logo picture file for all locally-attacheddevices, or you can choose a specific address, a specific address range, themodel number, or the screen size:ADDRess rdevADDRess rdev-rdevtells CP which logo picture file to use for a specific device address (orrange of device addresses) for terminals that CP manages directly. rdevmust be a hexadecimal number between X'0000' and X'FFFF'.MODeltells CP the model number of the terminal. The table below shows thescreen size associated with each model:286 z/VM: CP Planning and Administration

CHOOSE_LOGOModel Equivalent Screen Size2 24 by 803 32 by 804 43 by 805 27 by 132Note: MODEL operands only apply to terminals with at least as many rowsand columns as the screen size that the model number implies. Forexample, if you had the following statements in your LOGO CONFIGfile:Choose_Logo Default File DEFAULT LOGOChoose_Logo Local Model 4 File LOCAL LOGOand someone used a locally-attached terminal with 32 rows and 80columns, that user would be looking at the DEFAULT LOGO, not theLOCAL LOGO. The user needs at least a 43 by 80 terminal to seethe LOCAL LOGO.SCReen_size rowsXcolumnstells CP the screen size of the terminal. SCREEN_SIZE operands onlyapply to terminals with at least as many rows and columns as the user’sactual screen size.MINimumtells CP which logo picture file to use when the file specified on anotherCHOOSE_LOGO statement is too large to fit on that terminal’s screen.PRINT_SEParatortells CP which logo picture file to use on separator pages of output printed onspooling printers.VSMtells CP which logo picture file to use for people logging on through VTAMservice machines (VSMs). You can choose to have one logo picture file for allVSMs, or you can choose a specific user ID:USERid useridtells CP the user ID of the VSM through which the user is logging on. Youcan use this operand to tell CP to use a specific logo picture file forterminals logging on through a specific VSM.fn ftFile fn fttells CP the file name and file type of the logo picture file. The FILE keyword isoptional, unless you gave the logo picture file a name that CP might mistake fora different operand. For example, use FILE if the logo picture file’s name isMOD LOGO, because CP interprets the file name MOD as an abbreviation ofthe MODEL keyword.'text'Tells CP what text to display in the command area of the logo’s area. Enclosethe text in single or double quotation marks, so that CP does not mistake animbedded blank as the end of the text. If the text is longer than the input area,CP truncates the text.If you need to include a single quotation mark in the title, enclose the wholestring with double quotation marks. If you need to include a double quotationmark in the title, enclose the whole string with single quotation marks. Also, youmay use two consecutive double quote marks ("") to represent a " characterChapter 7. The Logo Configuration File 287

CHOOSE_LOGOUsageNoteswithin a string delimited by double quotation marks. Similarly, you may use twoconsecutive single quotation marks ('') to represent a ' character within a stringdelimited by single quotation marks.Notes for Logo Picture Selection on Terminals:For terminal picture selection, CP determines the amount of space that remains onthe screen after accommodating the online message (at the top of the screen), theinput area (at the bottom of the screen) and leaving one reserved line. For example,if the screen on which a logo is to be displayed measures 32 rows by 80 columnsand the input area contains 6 records, the picture must fit in the remaining space:remaining rows = 32 (rows in screen)- 6 (rows in input area)- 1 (rows in online message)- 1 (reserved row)= 24Thus, the picture file selected for this screen can measure no more that 24 rows by80 columns.A Note about Picture WidthsFor VSM logos, the screen is assumed to be 24 rows by 78 columns and theinput area need not be accommodated within the 24 rows. Thus, a VSM logopicture file can never contain more than 22 rows or be wider than 78characters.No matter how large a screen is on which CP is to display a logo, the number ofrows in the logo picture file multiplied by the logical record length of the picture filecannot exceed 3000 characters.The type of terminal on which the logo is to be displayed determines the processthat CP uses to select a logo picture file. For each type of terminal, CP looks at aseries of CHOOSE_LOGO statements to find out which logo picture file to use forthe terminal:v For terminals that CP manages directly, CP searches through CHOOSE_LOGOstatements with the LOCAL operand.v For terminals represented by logical devices, it searches throughCHOOSE_LOGO statements with the LDEV operand.v For terminals managed by a VSM, it searches through CHOOSE_LOGOstatements with the VSM operand.In all three cases, CP attempts to find a CHOOSE_LOGO statement that applies tothe screen and for which the picture file exists on a CP-accessed disk and fits inthe space remaining on the screen. The CHOOSE_LOGO statements are scannedin reverse order of their specification in the logo configuration file.If no CHOOSE_LOGO statement meets the aforementioned criteria, the next steptaken by CP will depend on whether or not a CHOOSE_LOGO DEFAULT statementwas specified in the logo configuration file.v If CHOOSE_LOGO DEFAULT was specified, CP will attempt to read the filespecified on the statement and will check if the picture in the file fits in the spaceremaining on the screen. The maximum width (logical record length) of a default288 z/VM: CP Planning and Administration

CHOOSE_LOGOlogo file is 78 characters. If the file does not exist on a CP-accessed minidisk orthe file is too large to fit on the screen, CP will move on to minimum logoprocessing.v If CHOOSE_LOGO DEFAULT was not specified, CP will check to see if the logopicture specified at HCPBOXNS in HCPBOX fits on the space remaining on thescreen. If the picture at HCPBOXNS is too large to fit on the screen, CP willmove on to minimum logo processing.As the minimum logo screen does not include an input area, CP determines theamount of rows remaining for a logo picture as:(number of rows in screen) - 1 (for online message) - 2 (reserved lines)Thus, our example above would now read:remaining rows = 32 (rows in screen)- 1 (rows in online message)- 2 (reserved rows)= 29Thus, the minimum logo picture used for this screen can measure no more than 29rows by 78 columns. Minimum logo processing proceeds as follows:v If CHOOSE_LOGO MINIMUM was specified, CP will attempt to read the filespecified on the statement and will check if the picture in the file fits in the spaceremaining on the screen. The maximum width (logical record length) of aminimum logo file is 78 characters. If the file does not exist on a CP-accessedminidisk or the file is too large to fit on the screen, CP will move on to basic logoprocessing.v If CHOOSE_LOGO MINIMUM was not specified, CP will check to see if the logopicture specified at HCPBOXMS in HCPBOX fits on the space remaining on thescreen. If the picture at HCPBOXMS is too large to fit on the screen, CP willmove on to basic logo processing.Finally, if no suitable logo picture has been found for the screen, CP will use thebasic logo picture defined at HCPBOXBS in HCPBOX. This logo contains nopicture; only an online message will be displayed at the top of the screen and astatus area at the bottom of the screen. This logo is guaranteed to fit on allscreens.Notes for Separator Pages of Printed Output:1. Files containing logo pictures for separator pages should have no more than 16records, each of which should not be longer than 49 characters.2. If you do not code a CHOOSE_LOGO PRINT_SEPARATOR statement, or if thefile specified is too large to fit on a separator page, then CP will use thespooling logo defined at HCPBOXBX or, failing that, HCPBLKDB. If you changethe logo picture file for the separator pages, enter the CPACCESS command tohave CP re-access the minidisk where the separator logo is stored. Use theREFRESH command to activate the changes.ExamplesDefaultsChoose_Logo Default CAMBVM3 DEFAULTspecifies that CP should use the file CAMBVM3 DEFAULT to create default logos.Choose_Logo Minimum CAMBVM3 MINIMUMChapter 7. The Logo Configuration File 289

CHOOSE_LOGOspecifies that CP should use the file CAMBVM3 MINIMUM as the logo picture filewhen no other picture file can be found to fit on the terminal screen.Logical DevicesChoose_Logo LDEV LDEVS LOGOspecifies that CP should use the logo picture file LDEVS LOGO for all terminalslogging on through logical devices.Choose_Logo LDEV Model 3 CAMBVM3 MOD3LOGOspecifies that CP should use the logo picture file CAMBVM3 MOD3LOGO for all theModel 3 terminals that log on through logical devices. Model 3 terminals have 32rows and 80 columns.Choose_Logo LDEV Model 3 Userid PVM PVM LOGOspecifies that CP should use the logo picture file PVM LOGO for all terminals thathave at least 32 rows and 80 columns and that log in through PVM.Locally Attached Terminals:Choose_Logo Local CAMBVM3 LOCALspecifies that CP should display the file CAMBVM3 LOCAL on all locally attachedterminals.Choose_Logo Local Address 0010-001F CAMBVM3 LOCAL2 'DIAL VTAM'specifies that for terminals attached locally between the addresses X'0010' andX'001F', CP should use the logo picture file CAMBVM3 LOCAL2, and place thecommand DIAL VTAM on the command line.Choose_Logo Local Address 0200-02FF Screen_size 27X132 CAMBVM3 LOCMOD5specifies that CP should display the file CAMBVM3 LOCMOD5 on all the Model 5terminals (terminals that have 27 rows and 132 columns) between addressesX'0200' and X'02FF'.Separator PagesChoose_Logo Print_separator PRINTSEP LOGOspecifies that CP should use the logo picture file PRINTSEP LOGO on separatorpages of printed output.Terminals Logging on through a VSMChoose_Logo VSM Userid VTAM CAMBVM3 VTAMspecifies that CP should use the logo picture file CAMBVM3 VTAM on all screensmanaged by the VSM named VTAM.290 z/VM: CP Planning and Administration

INPUT_AREAINPUT_AREA Statement►► INPUT_AREA fn ft ►◄PurposeUse the INPUT_AREA statement to define a file whose contents will be used inplace of the input area provided in HCPBOX ASSEMBLE. This input area containsthe input fields for a user ID, password, and command text.How to SpecifyYou can place INPUT_AREA statements anywhere in the logo configuration file. Ifyou specify more than one INPUT_AREA statement, the last overrides any previousspecifications.Operandsfn tells CP the file name of the file containing the input area text.ft tells CP the file type of the file containing the input area text.UsageNotes1. If the input area file contains more than 6 records or is wider than 80characters, CP will use the input area in HCPBOX instead of the one specifiedin the file.2. If more than one version of the file exists on the disks accessed by CP, CP willuse the file on the lowest accessed minidisk.3. Although you can use different logo pictures for different terminals, you candefine only one input area, which will be displayed on all terminals.4. CP is shipped with a sample utility program, DRAWLOGO, and a sample XEDITmacro, X$DRWL$X, to help you construct the input area file. Refer toAppendix A, “Sample Utility Programs,” on page 641 for more information onDRAWLOGO and X$DRWL$X.5. Within the file, you can choose to place more than one input field on one line.Examples1. To use the VM1 INPUT file to define the input area, use the followingINPUT_AREA statement:Input_Area VM1 INPUT /* Use the Input Area defined in *//* file, "VM1 INPUT" */Chapter 7. The Logo Configuration File 291

ONLINE_MESSAGEONLINE_MESSAGE Statement►► ONLINE_MESSage fn ft ►◄PurposeUse the ONLINE_MESSAGE statement to change what appears in the onlinemessage section, which always appears at the top of the logo screen. If you omitthis statement, CP uses the default online message defined in HCPBOXASSEMBLE.How to SpecifyYou can place ONLINE_MESSAGE statements anywhere in the logo configurationfile. If you specify more than one ONLINE_MESSAGE statement, the last overridesany previous specifications.Operandsfn tells CP the file name of the file containing the online message text.ft tells CP the file type of the file containing the online message text.UsageNotes1. If the online message file contains more than one record or is wider than 78characters, CP will use the online message defined in HCPBOX instead of theone defined in the file.2. If the online message text is wider than the screen on which it will be displayed,CP truncates it.Examples1. To use the TOP MESSAGE file to define the online message section, use thefollowing ONLINE_MESSAGE statement:Online_Message Top Message /* The Online Message Can be found *//* in file "TOP MESSAGE" */292 z/VM: CP Planning and Administration

STATUSSTATUS Statement►► STATUS CP_Read 'string'▼'CP READ''HOLDING'HOLDing 'string''MORE... 'MORe 'string''NOT ACCEPTED'NOT_ACCepted 'string''RUNNING'RUNning 'string''VM READ'VM_Read 'string'►◄PurposeUse the STATUS statement to redefine the default text of the status fields displayedin the bottom right corner of the screen.How to SpecifyInclude as many statements as needed; they are optional. You can place STATUSstatements anywhere in the logo configuration file. If you specify more than onestatement with the same operands, the last operand definition overrides anyprevious specifications.OperandsCP_Read stringidentifies the string to be displayed in the status area when a virtual machinehas issued a CP read. The string can be as long as eight characters. Thedefault string is 'CP READ'.HOLDing stringidentifies the string to be displayed in the status area when there is moreinformation to be displayed and the current screen cannot be cleared becausehighlighted output appears on it, or when the user presses ENTER when thescreen is in MORE... status. The string can be as long as eight characters. Thedefault string is 'HOLDING'.MORe stringidentifies the string to be displayed in the status area when there is moreinformation to be displayed and there is no highlighted text on the currentscreen. The string can be as long as eight characters. The default string is'MORE... '.NOT_ACCepted stringidentifies the string to be displayed in the status area when CP is executing acommand that prevents it from accepting any more input from the commandline. The string can be as long as 12 characters. The default string is 'NOTACCEPTED'.Chapter 7. The Logo Configuration File 293

STATUSUsageNotesRUNning stringidentifies the string to be displayed in the status area when none of the otherstatus conditions exists. The string can be as long as eight characters. Thedefault string is 'RUNNING'.VM_Read stringidentifies the string to be displayed in the status area when a virtual machinehas issued a VM read. The string can be as long as eight characters. Thedefault string is 'VM READ'.1. You may have applications that depend on the default status fields. Changingthe values of the fields may cause these applications to fail.2. If you want to include imbedded blanks or preserve mixed case in yourcharacter strings, enclose the strings in single quotation marks.3. The string may be enclosed in single or double quotation marks un it is a singleword entered with no imbedded blanks, in which case the entire word will becapitalized.If you need to include a single quotation mark in the string, enclose the wholestring with double quotation marks. If you need to include a double quotationmark in the string, enclose the whole string with single quotation marks. Also,you may use two consecutive double quote marks ("") to represent a " characterwithin a string delimited by double quotation marks. Similarly, you may use twoconsecutive single quotation marks ('') to represent a ' character within a stringdelimited by single quotation marks.Examples1. You can code the following STATUS statement to change all of the status fieldsto mixed case:Status CP_Read 'CP Read',Holding 'Holding',More 'More... ',Not_Accepted 'Not accepted',Running 'Running',VM_Read 'VM Read'294 z/VM: CP Planning and Administration

Chapter 8. Setting Up Service Virtual MachinesThis chapter describes how to set up virtual machines for:v Accounting, error recording, and symptom record recordingv Communication controller supportv Service pool virtual machinesv Print Services Facility/VMv Data storage management.Notes:1. All virtual machines that contain data retrieval applications and use the IUCVfacility to connect to the CP accounting, error recording, or symptom recordrecording system services must include an IUCV user directory controlstatement that identifies the appropriate CP recording system service. Inaddition, when the virtual machine user ID is identified to CP in the appropriateSYSTEM_USERIDS system configuration file statement (ACCOUNT1,ACCOUNT2, EREP1, EREP2, SYMPTOM1, or SYMPTOM2), data is queued forthe application even when the virtual machine is not logged on and CP isstarted with the COLD option. CP logs on these virtual machines as part of itsinitialization.2. Consider adding a LOGONBY statement to the user directory entry for servicemachines. It lets the system administrators and system programmers log on tothe service machine using their own log on password rather than that of theservice virtual machine. This eliminates the need for many users to know theservice virtual machine’s log on password.3. Consider adding the STGEXEMPT operand to the OPTION directory controlstatement for service virtual machines. This operand ensures that the user ID isnot subject to being stopped or forced due to the amount of free storage itcauses CP to consume. STGEXEMPT is recommended to protect specialpurpose user IDs which are vital to the installation, user IDs running trustedcode, and user IDs which should never be forced off the system.Setting Up Virtual Machines for AccountingThe z/VM System DDR tapes or CD-ROM include:v A sample directory entry for an accounting virtual machine. This entry containsthe required IUCV authorization for connecting to the CP accounting systemservice.v A sample system configuration file that defines the user ID for the accountingvirtual machine as DISKACNT. The user ID for the accounting virtual machine isdefined as part of the SYSTEM_USERIDS statement in the system configurationfile so that it is automatically logged on by CP.v A sample PROFILE EXEC for the accounting virtual machine.Note: One or two virtual machines can be set up as accounting virtual machines.To set up a virtual machine to begin recording accounting information automatically,you must have the proper PROFILE EXEC and user directory set up. The followingsteps show this procedure:1. Log on as MAINT. If you did this step as part of installation, you may alreadybe logged on as MAINT, or the user ID you are installing with on your currentoperating system.© Copyright IBM Corp. 1991, 2004 295

Setting Up SVMs2. Determine the write password of the accounting virtual machine’s 191disk. The accounting virtual machine has been specified in either theSYSTEM_USERIDS ACCOUNT1 or ACCOUNT2 system configuration filestatement or the SYSACNT macroinstruction. Before linking to the accountingvirtual machine’s 191 disk, find out its write password by examining its userdirectory entry. (As MAINT, you usually have access to the user directory.)If the accounting virtual machine’s 191 disk does not have a write password,you must supply one and update the directory.Notes:a. To set up virtual machines for error recording and for symptom recordrecording, you must determine the write password of the 191 disk of theerror recording virtual machines and symptom record recording virtualmachines. To avoid having to update the directory three times, check thewrite password of the error recording virtual machine’s and symptom recordrecording virtual machine’s 191 disk at the same time you check the writepassword of the accounting virtual machine’s 191 disk.b. Verify that the directory entry for this virtual machine contains the requiredIUCV authorization for connecting to the CP accounting system service. Forexample, IUCV *ACCOUNT.3. Link to the accounting virtual machine’s 191 disk. To do this, enter:link to diskacnt 191 as 391 wrWhen CP responds with ENTER WRITE PASSWORD: enter:wpasswhere wpass is the write password of the accounting virtual machine.The accounting virtual machine’s 191 disk is now your 391 disk.4. Access the 391 disk. To do this, enter:access 391 xIf you receive a message that says X'391' DEVICE ERROR, you must format the391 disk. To do this, enter:format 391 xCMS responds with FORMAT WILL ERASE ALL FILES ON DISK X (391). DO YOUWISH TO CONTINUE? (YES|NO). You should enter:yesWhen CP responds with ENTER DISK LABEL, enter:acntor any 1- to 6-character label name.5. Copy a file named DVM PROFILE from MAINT’s 191 disk to the 391 disk.(DVM PROFILE is the PROFILE EXEC for the accounting, symptom recordrecording, and error recording virtual machines). The RETRIEVE utility, whichdoes the IUCV connect to the *ACCOUNT system service, is invoked from thisPROFILE EXEC. To do this, enter:copyfile dvm profile a profile exec x6. Release and detach the 391 disk. To do this, enter:release x (det7. If the accounting virtual machine is not logged on, use the XAUTOLOGcommand to log on the accounting virtual machine automatically. To dothis for the diskacnt user ID, enter:.xautolog diskacnt296 z/VM: CP Planning and Administration

Setting Up SVMsSetting Up Virtual Machines to Collect Accounting RecordsYour installation can set up multiple virtual machines to collect the accountingrecords. There are two methods that you can use to specify to CP which virtualmachines will be used to retrieve accounting data. These are as follows:v At CP generation time in the system configuration file, code theSYSTEM_USERIDS statement or the SYSACNT macroinstruction to specify thevirtual machine IDs (up to two) for which the CP accounting system service(*ACCOUNT) is to accumulate records. If these users have an entry in the userdirectory, they will be logged on as part of CP initialization. See“SYSTEM_USERIDS Statement” on page 232 for information about theSYSTEM_USERIDS statement or “SYSACNT (Optional)” on page 661 forinformation about the SYSACNT macroinstruction.v Additional virtual machines can also collect accounting records by following theinstructions in sections:– See “Specifying a New Accounting Virtual Machine.”– See “Starting Manual Retrieval of Accounting Records.”Specifying a New Accounting Virtual MachineNormally your installation sets up particular virtual machines to be the accountingvirtual machines. If you want to have additional virtual machines collect accountingrecords, do the following:v Make sure the new accounting virtual machine has an A-disk available to receivethe accounting records.v Make sure the system programmer authorizes the new virtual machine to receivethe records in the IUCV directory statement.The user entering the RETRIEVE utility must have a directory entry containing anIUCV directory control statement authorizing the virtual machine to connect to theCP system service which supports the type of record being collected.*ACCOUNT must be specified for ACCOUNT records.v Follow the steps outlined in “Starting Manual Retrieval of Accounting Records.”Starting Manual Retrieval of Accounting RecordsOrdinarily, the accounting virtual machine starts retrieving automatically when youbring up z/VM. But there may be times when you need to start retrieval manually.For example, you may find out through error messages or by entering the QUERYRECORDING command that the accounting virtual machine has stopped retrieving.Or your installation may not set up the accounting virtual machine to start retrievalautomatically. In either case, you may start retrieval manually, as follows:1. If necessary, disconnect from the operator’s virtual machine by entering:disconnect2. Log on the accounting virtual machine.3. Clear any activity in the virtual machine (including retrieval) by entering:#cp system reset4. Load CMS into storage by entering:ipl 190or, if your installation has installed CMS in a named saved system,ipl cmsnamewhere cmsname is the name of your CMS system.Chapter 8. Setting Up Service Virtual Machines 297

Setting Up SVMs5. Make sure there is room on the accounting virtual machine’s A-disk for moreaccounting records. To find out how full the A-disk is, enter:query disk aIf the A-disk is almost full, process some of the accounting records. Then erasethe old files to free space on the A-disk.6. Start retrieval of accounting records by entering:retrieve account7. Disconnect the accounting virtual machine by entering:#cp disconnectYou may now use the display for another virtual machine.8. If necessary, reconnect the operator’s virtual machine.Disassociating a User ID from the Retrieval of Accounting Records1. Stop the recording of ACCOUNT records for this user ID. To do this from a userID authorized for the class A or B version of the CP RECORDING command,enter:recording account off qid useridOr, the user ID being removed (must be authorized for the class C, E, or Fversion of the recording command), enter:recording account off2. If there are accounting records queued in CP storage for this user ID and youwant to save the data, log on the user ID to be deleted and enter:retrieve accountThis will place the accounting records in the proper file for later processing.Disconnect this user by entering:#cp disconnectLog back on the authorized user ID.3. If the accounting records queued in CP storage for this user ID are not wanted,they may be purged. To do this from a user ID authorized for the class A or Bversion of the CP RECORDING command, enter:recording account purge qid useridOr, the user ID being removed (must be authorized for the class C, E, or Fversion of the recording command), enter:recording account purgeThis will PURGE all the accounting records queued in CP storage for this userID.4. Verify the record count is zero and recording is off for this user ID. To do this,enter:query recordingNote: The deleted user ID remains in the warm start data and in the output ofthe QUERY RECORDING command until VM is restarted with the COLDoption.5. If the user ID is specified on the SYSTEM_USERIDS statement in the systemconfiguration file, remove that user ID.298 z/VM: CP Planning and Administration

Setting Up SVMsAccounting Record Formats▌PI▐Note: The user ID OPERACCT is the default if the SYSACNT macroinstructionis omitted and no user ID for accounting is specified in the systemconfiguration file.CP produces the following types of accounting records:v Virtual machine user records (record type 1).v Records for devices dedicated to a virtual machine user (record type 2).v Records for temporary disk space dedicated to a virtual machine user (recordtype 3).v Records that are written when CP detects that a user has entered enoughLOGON, AUTOLOG, XAUTOLOG, or APPCVM CONNECT invocations with aninvalid password to reach or exceed an installation-defined threshold value(record type 04).v Records that are written when CP detects that a user has successfully entered aLINK command to a protected minidisk not owned by the user (record type 05).v Records that are written when CP detects that a user has entered enough LINKcommands with an invalid password to reach or exceed an installation-definedthreshold value (record type 06).v Records generated whenever a user logs off or disconnects from a devicecontrolled by the VCNA or VSCS (record type 07).v Records that are written when CP detects that a user has successfully entered aLINK command to a protected minidisk not owned by that user’s virtual machine(record type 08). Record type 08 is also generated when the user logs off ordisconnects or when a SHUTDOWN or FORCE command causes a logged-onvirtual machine to be forced off the system. Disconnected virtual machines do nothave another 08 record generated for them if they are forced off.v Records generated about ISFC (record type 09).v Records logging changes to a user’s privilege class (record type 0A)v Records for virtual disk in storage space (record type B)v Records for Network Data Transmissions (record type C)v Records generated as a result of a user-initiated DIAGNOSE X'4C' instruction(record type C0).Note: Record types 04, 05, 06, and 08 are generated only when LOGON,AUTOLOG, XAUTOLOG, LINK, and CONNECT journaling is on.These records are all 80-character card images.The size of the fields in the accounting records restricts the data limit that each fieldcan contain. To find the available field size, refer to each record type. Since thefields are limited in their capacity, it is recommended that you cut accountingrecords at least once a day.Accounting Records for Virtual Machine Resource Usage(Record Type 1)A type 1 accounting record is produced whenever a user logs off or whenever theACNT command is entered. Columns 1 through 28 and 79 and 80 of this recordcontain character data; all other data is in hexadecimal form (the hexadecimal datais unprintable).Chapter 8. Setting Up Service Virtual Machines 299

Setting Up SVMsColumn Contents1–8 User ID9–16 Account number17–28 Date and time of accounting (mmddyyhhmmss)29–32 Number of seconds connected to CP33–36 Milliseconds of processor time used, including time for supervisorfunctions37–40 Milliseconds of virtual CPU time used41–44 Number of page reads45–48 Number of page writes49–52 Number of requested virtual I/O starts for non-spooled I/O53–56 Number of virtual punch cards sent to a virtual punch57–60 Number of virtual print lines sent to a virtual printer (this includesone line for each carriage control command)61–64 Number of virtual punch cards received from a virtual reader65–68 Milliseconds of total Vector time69–72 Milliseconds of virtual Vector time73–76 Number of completed virtual I/O starts for non-spooled I/O (exceptDIAGNOSE X'58' and DIAGNOSE X'98')77–78 CPU address (for the SYSTEM VMDBK, this is the real processoraddress)79 Card generator field (C if Diag 4C has been issued, 0 otherwise)80 Accounting record identification code (1)Note: User virtual machine time may be recorded in more than one record entry.For example:v Processor time is accumulated under connect time (bits 29 - 32) andprocessor time (bits 33 - 40)v Vector processing time is accumulated under connect time (bits 29 - 32),processor time (bits 33 - 40), and vector time (bits 65 - 72).Accounting Records for Dedicated Devices (Record Type 2)A type 2 accounting record is produced whenever a virtual machine user releases apreviously dedicated device. Columns 1 through 28 and 79 and 80 of this recordcontain character data; all other data is in hexadecimal form (the hexadecimal datais unprintable). Translation codes for columns 33 through 36 can be found inAppendix E, “Device Class and Type Codes,” on page 773. See the documentationfor each specific device for more complete information on model numbers.Column Contents1–8 User ID9–16 Account number17–28 Date and time of accounting (mmddyyhhmmss)29–32 Number of seconds since the virtual disk was created or thenumber of seconds since the last accounting record was cut for thisvirtual disk33 Device class34 Device type35 Device model (if any)36 Device features (if any)37–78 Reserved79 Card generator field (C if Diag 4C has been issued, 0 otherwise)80 Accounting record identification code (2)300 z/VM: CP Planning and Administration

Setting Up SVMsAccounting Records for Temporary Disk Space (Record Type 3)A type 3 accounting record is produced whenever a virtual machine user releasestemporary disk space. Columns 1 through 28 and 79 and 80 of this record containcharacter data; all other data is in hexadecimal form (the hexadecimal data isunprintable). See Appendix E, “Device Class and Type Codes,” on page 773 forinformation about translation codes for columns 33 through 36. See thedocumentation for each device for more information on model numbers.Column Contents1–8 User ID9–16 Account number17–28 Date and time of accounting (mmddyyhhmmss)29–32 Number of seconds since the TDISK was created or the number ofseconds since the last accounting record was cut for this TDISK33 Device class34 Device type35 Device model (if any)36 Device features (if any)37–38 CKD and ECKD Only Number of cylinders of temporary disk spaceused (only present for CKD or ECKD architected device types)39–40 CKD and ECKD Only Reserved37–40 FBA Only Number of FBA blocks used (only present for FBAarchitected device types)41–44 Number of 4K pages used (present for all device types)45–78 Reserved79 Card generator field (C if Diag 4C has been issued, 0 otherwise)80 Accounting record identification code (3)Accounting Records for Journaling (Record Types 04, 05, 06, 08,and 0I)When LOGON, AUTOLOG, XAUTOLOG, LINK, or APPCVM CONNECT journalingis on, CP may create type 04, type 05, type 06, type 08, and type 0I accountingrecords.A type 04 accounting record is written whenever CP detects that a user has issuedenough LOGON, AUTOLOG, XAUTOLOG, or APPCVM CONNECT invocations withan invalid password to reach or exceed an installation-defined threshold value. Thisrecord has the following format:Column Contents1–8 User ID specified on the command9–16 Reserved for IBM use17–28 Date and time of accounting (mmddyyhhmmss)29–32 Terminal address (see Note 1 on page 303)33–40 Invalid password (see Note 2 on page 303)41–48 User ID that entered AUTOLOG, XAUTOLOG, APPCVMCONNECT, or the BYUSER ID that entered LOGON (see Note 4 onpage 303).49–51 Reserved for IBM use52–53 Current invalid password count in hexadecimal54–55 Accounting record limit in hexadecimal56 Blank57–62 Reserved63–70 Network qualifier for SNA terminal. Host virtual machine name forTCP/IP terminal.71–78 LUNAME for SNA terminal. IP address for TCP/IP terminal (seeNote 5 on page 303).Chapter 8. Setting Up Service Virtual Machines 301

Setting Up SVMs79–80 Accounting card identification code (04)A type 05 accounting record is produced whenever CP detects that a user hassuccessfully entered a LINK command to a minidisk protected by a password andnot owned by that user. This record is always produced when an external securitymanager authorizes the link. This record has the following format:Column Contents1–8 User ID that entered the command9–16 Account number17–28 Date and time of accounting (mmddyyhhmmss)29–32 Terminal address (see Note 1 on page 303)33–40 Reserved for IBM use41–48 User ID of the user that owns the minidisk49–52 The minidisk address for which the LINK command was entered53 Type of minidisk linked (see Note 3 on page 303)54–55 Reserved for IBM use56–57 Blank58–62 Reserved63–70 Network qualifier for SNA terminal. Host virtual machine name forTCP/IP terminal.71–78 LUNAME for SNA terminal. IP address for TCP/IP terminal (seeNote 5 on page 303).79–80 Accounting card identification code (05)A type 06 accounting record is produced whenever CP detects that a user hasentered enough LINK commands with an invalid password to reach or exceed aninstallation-defined threshold value. This record has the following format:Column Contents1–8 User ID that entered the command9–16 Account number17–28 Date and time of accounting (mmddyyhhmmss)29–32 Terminal address (see Note 1 on page 303)33–40 Invalid password (see Note 2 on page 303)41–48 User ID of the user that owns the minidisk49–51 Reserved for IBM use52–53 Invalid password count in hexadecimal54–55 Invalid password limit in hexadecimal56 Blank57–60 Minidisk address for which the LINK command was entered61–62 Reserved63–70 Network qualifier for SNA terminal. Host virtual machine name forTCP/IP terminal.71–78 LUNAME for SNA terminal. IP address for TCP/IP terminal (seeNote 5 on page 303).79–80 Accounting card identification code (06)A type 08 record is generated when a user logs off or disconnects or when aSHUTDOWN or FORCE command causes that logged-on user to be forced off thesystem. Disconnected users do not have another 08 record generated for them ifthey are forced off. This record has the following format:Column Contents1–8 User ID9–16 Account number17–28 Date and time of accounting (mmddyyhhmmss)302 z/VM: CP Planning and Administration

Setting Up SVMs29–48 Reserved49–56 LUNAME for SNA terminal. IP address for TCP/IP terminal (seeNote 5).57–64 Network qualifier for SNA terminal. Host virtual machine name forTCP/IP terminal.65–72 Terminal identification (logical device number, real device number,LUNAME for SNA terminal or NONE)73–78 Reserved79–80 Accounting record identification code (08)Notes:1. For the terminal address, columns 29 through 32 may contain one of thefollowing:v NONE—if no terminal is foundv SNA—if terminal is SNA (LUNAME is in columns 71–78)v A real or logical device number in the form Lnnn, where nnn is the logicaldevice number, for all other cases.2. For the invalid password, columns 33 through 40 may contain one of thefollowing:v Incorrect passwordv TOO LONG—if entered password is more than 8 characters.3. For the type of minidisk linked, column 53 may contain one of the following:v X'00'–if the link is to a user’s minidiskv X'10'–if the link is to a full-pack overlay minidisk.4. A by-user is a user who logs on to a virtual machine using the BY operand ofthe LOGON command. The by-user’s own password is used for LOGONauthorization checking for the virtual machine, so the invalid password attemptsare counted against the by-user ID, not the user ID of the virtual machine.5. IP addresses are normally written in dotted-decimal format (for example,9.130.58.78). In journal records, each segment of the IP address is converted toa two-digit hexadecimal value. For example, 9 is converted to 09, and 130 isconverted to 82. The result is an eight-byte string of four two-digit hexadecimalnumbers in character form. So, 9.130.58.78 becomes the character string09823A4E.A type 0I record is generated when the user is logged on through a logical devicewith an associated IPv6 address. This record has the following format:Column Contents1–8 VM user ID9–16 Account number17–28 Date and time of accounting (mmddyyhhmmss)29–36 Host virtual machine name37–68 IPv6 address (see note 1)69–78 Reserved79–80 Accounting record identification code (0I)Notes:1. IPv6 addresses are normally written in hexadecimal text representation.Example: 0123:4567:89AB:CDEF:FEDC:BA98:7654:3210In type 0I records, each segment of the IP address is converted from binary tocharacter form. The result is a 32-byte string of sixteen two-digit hexadecimalnumbers in character form. So, the address shown above becomes0123456789ABCDEFFEDCBA9876543210.Chapter 8. Setting Up Service Virtual Machines 303

Setting Up SVMsAccounting Records for SNA/CCS (Record Type 07)A type 07 accounting record is produced whenever a user logs off or disconnectsfrom a device controlled by VCNA or VSCS. The record indicates the user’s shareof the VCNA/VSCS resource used. Columns 1 through 16 and 79 and 80 of thisrecord contain character data. See the VCNA Installation and Terminal Use Guidefor details of VM/VCNA accounting records and the ACF/VTAM* Planning andInstallation book for details of VSCS accounting records.Column Contents1–8 User ID9–16 Account number17–78 VSCS/VCNA accounting data79–80 Accounting record identification code (07)Accounting Records for Inter-System Facility forCommunications (Record Type 09)A type 09 accounting record is produced when the ALL option of the ACNTcommand is entered. Accounting records are generated for all active conversationsand all active links.There are four different categories of ISFC accounting records:v Initialization accounting recordsv Conversation accounting recordsv Link statistics accounting recordsv Termination accounting records.ISFC produces the initialization accounting record during its initialization on thez/VM system. This record, along with the termination accounting record indicatesthe time frame in which ISFC was active on the z/VM system.The format of the initialization accounting record is:Column Contents1–8 SYSISFC, indicating that this record was created by the z/VMdomain controller9–12 Initialization record identifier, ISFI13–16 Reserved for IBM use17–28 Date and time the accounting record is generated29–78 Reserved for IBM use79–80 ISFC accounting record identifierThe format of the conversation start accounting record is:Column Contents1–8 SYSISFC, indicating that this record was created by the z/VMdomain controller9–12 Conversation start accounting record identifier, ISFS13–16 Conversation ID17–28 Date and time the accounting record is generated29–36 User ID of the user that initiated the conversation37–59 Reserved for IBM use60 Type of name in bytes 61–68. R indicates a global resource. Gindicates a gateway name. U indicates a private resource servervirtual machine or workstation user ID. I indicates IUCV.304 z/VM: CP Planning and Administration

Setting Up SVMs61–68 Resource name, a gateway name, the user ID of the privateresource server virtual machine or workstation, or target userid foran IUCV CONNECT.69–78 Reserved for IBM use79–80 ISFC accounting record identifierThe format of the conversation active and conversation end accounting records is:Column Contents1–8 SYSISFC, indicating that this record was created by the z/VMdomain controller9–12 Conversation record identifier. ISFA indicates a conversation activeaccounting record; ISFE, a conversation end accounting record.13–16 Conversation ID17–28 Date and time the accounting record is generated29–32 Number of bytes received from the remote domain controller sincethe conversation started or since the last conversation activeaccounting record was issued.33–36 Number of bytes sent to the remote domain controller since theconversation started or since the last conversation activeaccounting record was issued.37–78 Reserved for IBM use.79–80 ISFC accounting record identifierThe format of the link statistics accounting records is:Column Contents1–8 SYSISFC, indicating that this record was created by the z/VMdomain controller9–12 Link statistics record identifier, ISFL13–16 Reserved for IBM use17–28 Date and time the accounting record is generated29–32 Number of bytes of data received (unsigned binary fullword)33–36 Number of bytes of data sent since the link came up or since thelast accounting record was generated for this link (unsigned binaryfullword)37–40 Unit address of the link41–44 Number of attention interrupts45–48 Number of write operations that result in collisions49–52 Number of successful write operations53–56 Number of successful read operations57–78 Reserved for IBM use.79–80 ISFC accounting record identifierThe format of the termination accounting record is:Column Contents1–8 SYSISFC, indicating that this record was created by the z/VMdomain controller9–12 Termination record identifier, ISFT.13–16 Reserved for IBM use17–28 Date and time the accounting record was generated29–78 Reserved for IBM use79–80 ISFC accounting record identifierChapter 8. Setting Up Service Virtual Machines 305

Setting Up SVMsAccounting Records for logging changes to a user’s privilege(Record Type 0A)A type 0A accounting record is produced whenever a SET PRIVCLASS command issuccessfully issued. The record tracks changes to a user’s privilege class and theirability to change their privilege class settings.There are 4 subtypes of this record.Subtype DescriptionL SET PRIVCLASS LOCK has been issuedU SET PRIVCLASS UNLOCK has been issuedC The user’s privilege class(es) have been changed via the SETPRIVCLASS command.R SET PRIVCLASS RESET has been issuedThe format for subtypes ’L’ (SET PRIVCLASS LOCK) and ’U’ (SET PRIVCLASSUNLOCK) appears below. Columns 1 through 36 and 78 through 80 of this recordcontain character data; all other data is in hexadecimal form (the hexadecimal datais unprintable).Column Contents1–8 User ID of the issuer of the SET PRIVCLASS command.9–16 Account number17–28 Date and time of accounting (mmddyyhhmmss)29–36 Target user ID. User ID that is the target of the SET PRIVCLASSlock or unlock37–77 Reserved78 SubtypeCharacter Subtype MeaningL SET PRIVCLASS LOCK has been issuedU SET PRIVCLASS UNLOCK has been issued79–80 Accounting record identification code (0A)The format for subtypes ’C’ (SET PRIVCLASS change) and ’R’ (SET PRIVCLASSRESET) appears below. Columns 1 through 36 and 78 through 80 of this recordcontain character data; all other data is in hexadecimal form (the hexadecimal datais unprintable). The privilege class information consists of bits representing privilegeclasses A-Z, and 1-6 respectively. The bit definitions are defined in HCPCLASSCOPY.Column Contents1–8 User ID of the issuer of the SET PRIVCLASS command9–16 Account number17–28 Date and time of accounting (mmddyyhhmmss)29–36 Target user ID. User ID whose settings are being changed37–40 User privilege classes before the change or reset41–44 User privilege classes after the change or reset45–48 User privilege classes as indicated in the directory49–77 Reserved78 SubtypeCharacter Subtype MeaningC The User’s privilege class has been changedR The User’s privilege class has been reset79–80 Accounting record identification code (0A)306 z/VM: CP Planning and Administration

Accounting Records for virtual disk in storage space (RecordType B)A type B accounting record is produced for a virtual disk in storage. Columns 1through 28 and 79 and 80 of this record contain character data; all other data is inhexadecimal form (the hexadecimal data is unprintable). Translation codes forcolumns 33 through 36 can be found in Appendix E, “Device Class and TypeCodes,” on page 773. See the documentation for each specific device for morecomplete information on model numbers.Column Contents1–8 User ID. This user ID is defined as follows:v If the virtual disk in storage is defined in the directory, this is theuser ID which contains the MDISK definition for this virtual disk instorage.v If the virtual disk in storage was defined using the CP DEFINEcommand, this is the user ID that issued the DEFINE command.9–16 Account number17–28 Date and time of accounting (mmddyyhhmmss)29–32 Number of seconds connected to CP33 Device class34 Device type35 Device model (if any)36 Device features (if any)37–40 Number of FBA blocks used41–44 Number of 4K pages used (present for all device types)45 Sub-type of virtual disk accounting record. The only volume definedis zero. If non-zero, the contents of bytes 1-44 and 46-78 areundefined.46–78 Reserved79 Card generator field (C if Diag 4C has been issued, 0 otherwise)80 Accounting record identification code (B)Accounting Records Network Data Transmissions (Record TypeC)Type C accounting records may be produced for any virtual machine user withNETAccounting or NETRouter specified as an option in its user directory. Theaccount records are produced when accounting is performed (CP ACNT command),or when a field in the accounting record is about to overflow, and the user has sentor received data from a Network device. These records are only produced whenfields containing byte counters for a device are non-zero.Network devices to be included in these counts are:v Virtual Network Interface Cards (NIC)v Virtual Channel to Channel Adaptersv IUCV and APPC/VM connection pathsSetting Up SVMsThe contents of Network Data Transmission accounting records depends on thetype of Network device being used. There are 3 different formats, designated bya subtype in byte 78. For subtype 00 (Virtual NIC records), an additional 4subformats, designated in byte 77, indicate what type of network data is countedin the record.Type C account record describing data transfer involving routers through a VirtualNIC (Network device type 00). Columns 1 through 28, 35 through 50, and 79through 80 of this record contain character data; all other data is in hexadecimalform (the hexadecimal data is unprintable.)Chapter 8. Setting Up Service Virtual Machines 307

Setting Up SVMsColumnContents1-8 VM Userid (Owner of the Virtual NIC)9-16 Account number17-28 Date and time of accounting (mmddyyhhmmss)29-30 Base VDEV address of the Virtual NIC.31-34 Default IP Address for this network adapter.35-42 LAN or Virtual Switch Owner43-50 LAN Name or Virtual Switch Name51-58 Bytes Sent (See Data Descriptor).59-66 Bytes Received (See Data Descriptor).67-76 Reserved77 Data Descriptor:00 - Bytes sent to or received from Routers01 - Bytes sent to or received from non-Routers02 - Bytes sent to or received via Broadcast03 - Bytes sent to or received via Multicast78 Network device type (00) Virtual NIC79 Card generator field (C if Diag 4C has been issued, 0 otherwise)80 Accounting record identification code (C)Notes:1. Hardware headers which appear before the IP Header are not included in thebyte counts reported for simulated network adapters.2. IP addresses are normally written in dotted-decimal format (for example,9.130.58.78). In journal records, each segment of the IP address is convertedto a two-digit hexadecimal value. For example, 9 is converted to 09, and 130is converted to 82. The result is an eight-byte string of four two-digithexadecimal numbers in character form. So, 9.130.58.78 becomes thecharacter string 09823A4E.TYPE C accounting record for data transfer with a Virtual Channel to ChannelAdapter. Columns 1 through 28, 35 through 42, and 79 through 80 of this recordcontain character data; all other data is in hexadecimal form (the hexadecimaldata is unprintable.)Column308 z/VM: CP Planning and AdministrationContents1-8 VM Userid (owner of the local CTCA)9-16 Account number17-28 Date and time of accounting (mmddyyhhmmss)29-30 VDEV address of the local CTCA31-34 Reserved35-42 Userid of the owner of the remote CTCA43-44 VDEV address of the remote CTCA45-50 Reserved51-58 Number of bytes sent to the remote CTCA.

Setting Up SVMs59-66 Number of bytes received from the remote CTCA.67-77 Reserved78 Network device type (01) virtual CTCA79 Card generator field (C if Diag 4C has been issued, 0 otherwise)80 Accounting record identification code (C)TYPE C account record for data transfer with an IUCV or APPC/VM connection.Columns 1 through 28, 35 through 42, and 79 through 80 of this record containcharacter data; all other data is in hexadecimal form (the hexadecimal data isunprintable.)ColumnContents1-8 VM Userid (Owner of the local connection.)9-16 Account number17-28 Date and time of accounting (mmddyyhhmmss)29-34 Reserved35-42 Connected VM Userid (remote)43-50 Reserved51-58 Number of bytes sent to the remote user.59-66 Number of bytes received from the remote user.67-77 Reserved78 Network device type (02) IUCV or APPC path79 Card generator field (C if Diag 4C has been issued, 0 otherwise)80 Accounting record identification code (C)Notes:1. Byte count values are reset to zero after an accounting record is created.2. Byte count values represent data read or written to the device. They will nottypically contain bytes transferred as a result of initialization, termination, orerror recovery.3. Accounting for a particular LAN may be controlled by the DEFINE LAN, andSET LAN commands, and default settings may be set by the VMLANcommand or VMLAN statement in the system config file.Accounting Records for CPU Capability (Record Type D)A Type D accounting record is produced to record the CPU capability of theprocessors in the system. A record is generated during VM system initialization andwhenever the CPU capability changes.All fields of the record contain character data.ColumnContents1-16 Reserved17-28 Date and time of accounting (mmddyyhhmmss)29-36 CPU capability37-38 Reserved79 Card generator field (0)Chapter 8. Setting Up Service Virtual Machines 309

Setting Up SVMs80 Accounting record identification code (D)Adding Your Own Accounting Records and Source CodeCP allows you to customize the way it collects accounting records in two ways:v A virtual machine can use the DIAGNOSE instruction to initiate the generation ofa virtual machine accounting record.v You can add your own source code to the CP accounting exit module.User-Initiated Accounting Records (Record Type C0)A virtual machine user can initiate the creation of an accounting record that containsup to 70 bytes of information of the user’s choosing. To do this, the user enters aDIAGNOSE code X'4C' instruction with the following operands (the z/VM: CPProgramming Services book describes how to enter a DIAGNOSE code):v The address of a data area in virtual storage that contains the information thatthe user wants in columns 9 through 78 of the card image record. (Thisinformation is placed in the accounting record exactly as it appears in the dataarea. If more than 70 bytes of data are included, only the first 70 bytes appear inthe accounting record.)v A function code of X'10'.v The length of the data area in bytes.The information on this type of accounting record is as follows:Column Contents1–8 User ID9–78 User-formatted data79–80 Accounting record identification code (C0)▌PIend▐File spool service virtual machines can generate accounting records in thiscategory. For details, see the z/VM: CMS File Pool Planning, Administration, andOperation book.CP Accounting Exit (Module HCPACU)▌PI▐You can make system-wide changes to the accounting records that CP collects byadding source code to module HCPACU. HCPACU is an installation-wide exit.HCPACU supports installation-supplied code for the IBM 3277 OperatorIdentification Card Reader feature and for examining and modifying CP accountingrecords. HCPACU is included in the CP nucleus at system generation. Later, duringsystem operation, the CP accounting function calls HCPACU whenever any of thefollowing occurs:v A virtual machine is started or stoppedv Accounting commands are entered by an operator or a virtual machinev CP does checkpointing operations.However, if you do not add any code to HCPACU, the module performs nomeaningful function.310 z/VM: CP Planning and Administration

Setting Up SVMsHCPACU contains two entry points, HCPACUON and HCPACUOF. Figure 4provides an overview of the IBM-supplied HCPACU module, showing the entrypoints and the areas where you can add your own source code.COPY HCPOPTNSHCPACU HCPPROLG ATTR=(RESIDENT),BASE=(R12)*COPY AOFPARM parameter list for HCPACUOFCOPY AONPARM parameter list for HCPACUONCOPY HCPEQUAT common system equatesCOPY HCPPFXPG prefix pageCOPY HCPSAVBK savearea block*HCPUSING PFXPG,0*HCPACUON HCPENTER CALL,SAVE=DYNAMICHCPUSING AONPARM,R1****************************************************************** Installation-supplied code can be inserted here.*****************************************************************HCPDROP R1SLR R15,R15 Set return code of 0ACUONEXT DS 0HST R15,SAVER15 Store return codeL R11,SAVER11 Restore register 11HCPEXIT EP=HCPACUONHCPDROP R13*HCPACUOF HCPENTER CALL,SAVE=PFXBALSVHCPUSING AOFPARM,R1LA R13,PFXBALSV Establish savearea addressHCPUSING SAVBK,R13****************************************************************** Installation-supplied code can be inserted here.*****************************************************************HCPDROP R1SLR R15,R15 Set return code of 0ACUOFEXT DS 0HST R15,SAVER15 Store return code* L R11,SAVER11 HCPEXIT does actual loadHCPEXIT EP=HCPACUOFHCPDROP R0,R13*HCPEPILGFigure 4. Module HCPACU OverviewHCPACU has the following requirements and restrictions:1. HCPACU is written in Assembler H coding language.2. HCPPROLG, HCPUSING, HCPENTER, HCPDROP, HCPEXIT, and HCPEPILGare IBM-supplied macros (in HCPPSI MACLIB) that must be preserved inHCPACU and used only as shown.3. The attributes of HCPACU must be REENTRANT and RESIDENT, becauseHCPACU is called during CP initialization and during CP checkpointingoperations.4. Links and accesses from HCPACU to other modules, data areas, and controlblocks are not supported.Chapter 8. Setting Up Service Virtual Machines 311

Setting Up SVMs5. IBM reserves the right to modify the code associated with this exit. IBM willattempt to make any changes as transparent as possible to the customer.6. Upon entry to both HCPACUON and HCPACUOF, register 13 points to a savearea mapped by HCPSAVBK, shown in Figure 5. The caller’s registers aresaved in the save area. A ten-fullword work area, beginning at label SAVEWRK,is available for use by installation-supplied code.7. Register 11, which points to the address of the dispatched VMDBK, andRegister 13, which points to the address of the save area, must not be modifiedby installation-supplied code.SAVBK DSECTDS 6F Reserved for IBM useSAVEREGS DS 0XL64 CALLER’S REGISTERS - R0 to R15SAVER0 DS F CALLER’S SAVED REGISTER 0SAVER1 DS F CALLER’S SAVED REGISTER 1SAVER2 DS F CALLER’S SAVED REGISTER 2SAVER3 DS F CALLER’S SAVED REGISTER 3SAVER4 DS F CALLER’S SAVED REGISTER 4SAVER5 DS F CALLER’S SAVED REGISTER 5SAVER6 DS F CALLER’S SAVED REGISTER 6SAVER7 DS F CALLER’S SAVED REGISTER 7SAVER8 DS F CALLER’S SAVED REGISTER 8SAVER9 DS F CALLER’S SAVED REGISTER 9SAVER10 DS F CALLER’S SAVED REGISTER 10SAVER11 DS F CALLER’S SAVED REGISTER 11SAVER12 DS F CALLER’S SAVED REGISTER 12SAVER13 DS F CALLER’S SAVED REGISTER 13SAVER14 DS F CALLER’S SAVED REGISTER 14SAVER15 DS F CALLER’S SAVED REGISTER 15SAVEWRK DS 0XL40 WORKAREA FOR CALLEESAVEWRK0 DS F WORKAREA FOR CALLEESAVEWRK1 DS F WORKAREA FOR CALLEESAVEWRK2 DS F WORKAREA FOR CALLEESAVEWRK3 DS F WORKAREA FOR CALLEESAVEWRK4 DS F WORKAREA FOR CALLEESAVEWRK5 DS F WORKAREA FOR CALLEESAVEWRK6 DS F WORKAREA FOR CALLEESAVEWRK7 DS F WORKAREA FOR CALLEESAVEWRK8 DS F WORKAREA FOR CALLEESAVEWRK9 DS F WORKAREA FOR CALLEEFigure 5. HCPSAVBK Save AreaEntry Point HCPACUON: Entry point HCPACUON supports installation-suppliedcode for the IBM 3277 Operator Identification Card Reader feature. You can addcode to examine or validate the data read from an identification card and to acceptor reject operator connection to the system.HCPACUON is called when a LOGON command is entered from a virtual machine,or during autolog processing.The CP accounting function uses general-purpose register 1 for input to entry pointHCPACUON. Register 1 contains the address of a parameter list, called AONPARM,that is described in Figure 6 on page 313. The DSECT for this parameter list mustbe preserved as shown.312 z/VM: CP Planning and Administration

Setting Up SVMsAONPARM DSECT ,**** AONPARM -** ┌-─-─-─-─-─-─-─-─-─-─-─┐* 0 | AONBUFF |* └-─-─-─-─-─-─-─-─-─-─-─┘* 8***** AONPARM -**************************************************************** ** Parameters for IBM 3277 Operator Identification Card ** Reader Feature. ** ****************************************************************AONBUFF DC F’0’ Contains one of the following:** - Address of a buffer containing* up to 130 bytes of data that* has been read from the IBM 3277* Operator Identification Card* Reader Feature. The data is* user-defined for terminal* operator identification.** - 0, if the reader feature was* not available** - 4, if an unsuccessful attempt* to read this reader feature* was made.*AONSIZE EQU (*-AONPARM+7)/8 AONPARM size in doublewordsFigure 6. AONPARM Parameter List for Entry Point HCPACUONUpon return to the CP accounting function from entry point HCPACUON,general-purpose register 15 must contain one of the following return codes:ValueMeaningX'00000000' Normal processing continues.X'00000004' The terminal operator should be forced off the system. However, if theterminal operator was automatically logged on during initialization, youcannot force the operator off the system.Entry Point HCPACUOF: HCPACUOF supports the addition ofinstallation-supplied code for examining and modifying accounting records.HCPACUOF is called when any of the following occurs:v A virtual machine operator or system operator enters a LOGOFF or FORCEcommandv The system operator enters an ACNT or SET ACCOUNT commandv CP starts the checkpointing functionv A virtual machine issues DIAGNOSE code X'4C' to create a user-initiatedaccounting record.For the first three conditions listed above, CP generates accounting record type 1,2, 3, B, or C. For the last condition, CP generates type C0 accounting records.HCPACUOF is not called during the generation of other types of accountingrecords.Chapter 8. Setting Up Service Virtual Machines 313

Setting Up SVMsThe CP accounting function uses general-purpose register 1 for input to entry pointHCPACUOF. Register 1 contains the address of a parameter list, called AOFPARM,that is described in Figure 7. The DSECT for this parameter list must be preservedas shown.AOFPARM DSECT ,**** AOFPARM -** ┌-─-─-─-─-─-─-─-─-─-─-─┐* 0 │ AOFAREC │* └-─-─-─-─-─-─-─-─-─-─-─┘* 8***** AOFPARM -**************************************************************** ** ACCOUNTING RECORD. ** ****************************************************************AOFAREC DC F’0’ Contains the address of a* completed accounting record.AOFSIZE EQU (*-AOFPARM+7)/8 AOFPARM size in doublewordsFigure 7. AOFPARM Parameter List for Entry Point HCPACUOFUpon return to the CP accounting function from entry point HCPACUOF,general-purpose register 15 must contain following return code:ValueMeaningX'00000000' Normal processing continues▌PIend▐Setting Up Virtual Machines for Error RecordingSetting up virtual machines for error recording is similar to setting up virtualmachines for accounting. (One or two virtual machines can be used for errorrecording.) The z/VM System DDR tapes or CD-ROM include:v A sample directory entry for one error recording virtual machine.v A sample system configuration file that defines the user ID for an error recordingvirtual machine as OPEREREP. The user ID for an error recording virtualmachine is defined as part of the SYSTEM_USERIDS statement in the systemconfiguration file. Records are queued for it and it is automatically logged on byCP initialization.v A sample PROFILE EXEC for one error recording virtual machine.Note: The sample directory entry for an error recording virtual machine(OPEREREP) supplied on the z/VM System DDR tapes or CD-ROMcontains the required IUCV authorization to connect to the CP *LOGRECsystem service.To set up a virtual machine to begin error recording automatically, you must havethe proper PROFILE EXEC and user directory set up. The following steps show thisprocedure:314 z/VM: CP Planning and Administration

Setting Up SVMs1. Log on as MAINT. If you did this step as part of installation, you may alreadybe logged on as MAINT, or the user ID you are installing with on your currentoperating system.2. Determine the write password of the error recording virtual machine’s 191disk. Before you can link to the error recording virtual machine’s 191 disk, youneed to know its write password. To find out the write password, examine theuser directory entry of the error recording virtual machine. (As MAINT, youusually have access to the user directory.)If the error recording virtual machine’s 191 disk does not have a write password,you must supply one and update the directory.Note: Verify that the directory entry for this virtual machine contains therequired IUCV authorization for connecting to the CP error recordingsystem service. For example, IUCV *LOGREC.3. Link to the error recording virtual machine’s 191 disk. To do this, enter:link to opererep 191 as 391 wrWhen CP responds with ENTER WRITE PASSWORD: enter:wpasswhere wpass is the write password of the error recording virtual machine.4. Access the 391 disk. To do this, enter:access 391 xIf you receive a message that says X'391' DEVICE ERROR, you must format the391 disk. To do this, enter:format 391 xCMS responds with FORMAT WILL ERASE ALL FILES ON DISK X (391). DO YOUWISH TO CONTINUE? (YES|NO). You should enter:yesCP responds with ENTER DISK LABEL. You should enter:erepor any 1- to 6-character label name.5. Copy a file named DVM PROFILE from MAINT’s 191 disk to the 391 disk.(DVM PROFILE is the PROFILE EXEC for the accounting and error recordingvirtual machines). The RETRIEVE utility, which does the IUCV connect to the*LOGREC system service, is invoked from this PROFILE EXEC. To do this,enter:copyfile dvm profile a profile exec x6. Release and detach the 391 disk. To do this, enter:release x (det7. If the error recording virtual machine is not logged on, use theXAUTOLOG command to automatically log on the error recording virtualmachine. To do this for the opererep user ID, enter:xautolog opererepSetting Up Virtual Machines to Collect EREP RecordsYour installation can set up multiple virtual machines to collect the EREP records.There are two methods that you can use to specify to CP which virtual machineswill be used to retrieve error recording data. These are as follows:Chapter 8. Setting Up Service Virtual Machines 315

Setting Up SVMsv At CP generation time in the system configuration file, code theSYSTEM_USERIDS statement or the SYSEREP macroinstruction to specify thevirtual machine IDs (up to two) for which the CP accounting system service(*LOGREC) is to accumulate records. If these users have an entry in the userdirectory, they will be logged on as part of CP initialization. See“SYSTEM_USERIDS Statement” on page 232 for information about theSYSTEM_USERIDS statement or “SYSACNT (Optional)” on page 661 forinformation about the SYSEREP macroinstruction.v Additional virtual machines can also collect error recording data by following theinstructions in sections:– See “Specifying a New EREP Virtual Machine.”– See “Starting EREP Record Retrieval Manually.”Specifying a New EREP Virtual MachineNormally, your installation sets up particular virtual machines to be the EREP virtualmachines. If you want to have additional virtual machines collect EREP records,then you must do the following:1. Make sure the new EREP virtual machine has an A disk available to receive theEREP records.2. Make sure the system programmer had authorized the new virtual machine toreceive the records in the IUCV directory statement.The directory entry of the user entering the RETRIEVE utility must have anIUCV directory control statement authorizing the virtual machine to connect tothe CP system service which supports the type of record being collected.*LOGREC must be specified for EREP records.3. Follow the steps outlined in the next section, “Starting EREP Record RetrievalManually.”Starting EREP Record Retrieval ManuallyOrdinarily, the EREP virtual machine starts retrieving automatically when you bringup z/VM. But there may be times when you need to start retrieval manually. Forexample, you may find out through error messages or by entering the QUERYRECORDING command that the EREP virtual machine has stopped retrieving. Oryour installation may not set up the EREP virtual machine to start retrievalautomatically. In either case, you can start retrieval manually, as follows:1. If necessary, disconnect from the operator’s virtual machine by entering:disconnect2. Log on the EREP virtual machine.3. Clear any activity in the virtual machine (including retrieval) by entering:#cp system reset4. Load CMS into storage by entering:ipl 190or, if your installation has installed CMS in a named saved system:ipl cmsnamewhere cmsname is the name of your CMS system.5. Make sure there is room on the EREP virtual machine’s A disk for more EREPrecords. To find out how full the A disk is, enter:query disk a316 z/VM: CP Planning and Administration

Setting Up SVMsIf the A disk is almost full, process some of the EREP records. Then erase theold files to free space on the A disk.6. Start EREP record retrieval by entering:retrieve erep7. Disconnect the EREP virtual machine by entering:#cp disconnectYou may now use the display for another virtual machine.8. If necessary, reconnect the operator’s virtual machine.Disassociating a User ID from the Retrieval of EREP Records1. Stop the recording of EREP records for this user ID. To do this from a user IDauthorized for the class A or B version of the CP RECORDING command,enter:recording erep off qid useridOr, the user ID being removed (must be authorized for the class C, E, or Fversion of the recording command), enter:recording erep off2. If there are EREP records queued in CP storage for this user ID and you wantto save the data, log on the user ID to be deleted and enter:retrieve erepThis will place the EREP records in the proper file for later processing.Disconnect this user by entering:#cp disconnectLog back on the authorized user ID.3. If the EREP records queued in CP storage for this user ID are not wanted, theymay be purged. To do this from a user ID authorized for the class A or Bversion of the CP RECORDING command, enter:recording erep purge qid useridOr, the user ID being removed (must be authorized for the class C, E, or Fversion of the recording command), enter:recording erep purgeThis will PURGE all the accounting records queued in CP storage for this userID.4. Verify the record count is zero and recording is off for this user ID. To do this,enter:query recordingNote: The deleted user ID remains in the warm start data and in the output ofthe QUERY RECORDING command until VM is restarted with the COLDoption.5. If the user ID is specified on the SYSTEM_USERIDS statement in the systemconfiguration file, remove that user ID.Note: The user ID OPEREREP is the default if the SYSEREP macroinstructionis omitted and no user ID for EREP is specified in the systemconfiguration file.Chapter 8. Setting Up Service Virtual Machines 317

Setting Up SVMsSetting Up Virtual Machines for Symptom Record RecordingSymptom record recording support allows your installation to record symptomrecords in CMS files separate from dumps or processor and I/O (LOGREC) errors.CP provides additional information in a symptom record when appropriate. You canuse the Dump Viewing Facility VIEWSYM command to view, compare, and selectmultiple symptom records in CMS files.A data retrieval application can connect to the CP *SYMPTOM system servicethrough the IUCV facility to collect symptom records. A virtual machine that containssuch an application must have an IUCV directory control statement in its userdirectory entry that identifies the CP *SYMPTOM system service. In addition, whenyou identify the virtual machine user ID to CP in either the SYSTEM_USERIDSSYMPTOM1 or SYMPTOM2 statement in the system configuration file, data isqueued for the virtual machine even when the virtual machine is not logged on andthe z/VM system is started with the COLD option. The virtual machine is alsologged on by z/VM as part of initialization.Setting up virtual machines for symptom record recording is similar to setting upvirtual machines for accounting and error recording. (One or two virtual machinescan be used for symptom record recording.) The z/VM System DDR tapes orCD-ROM include:v A sample directory entry for one symptom record recording virtual machine thatcontains the required IUCV authorization to connect to the CP *SYMPTOMsystem service. (The user ID for the virtual machine is OPERSYMP.)v A sample system configuration file that does not define the user ID for asymptom record recording virtual machine. The user ID for the symptom recordrecording virtual machine therefore defaults to OPERSYMP.v A sample PROFILE EXEC for one symptom record recording virtual machine.To set up a virtual machine so that it automatically begins symptom recordrecording, you must have the proper PROFILE EXEC and user directory set up.The following steps show this procedure:1. Log on as MAINT. If you did this step as part of installation, you may alreadybe logged on as MAINT, or the user ID you are installing with on your currentoperating system.2. Determine the write password of the symptom record recording virtualmachine’s 191 disk. Before you can link to the symptom record recordingvirtual machine’s 191 disk, you need to know its write password. To find out thewrite password, examine the user directory entry of the symptom recordrecording virtual machine. (As MAINT, you usually have access to the userdirectory.)If the symptom record recording virtual machine’s 191 disk does not have awrite password, you must supply one and update the directory.Note: Verify that the directory entry for this virtual machine contains therequired IUCV authorization for connecting to the CP accounting systemservice. For example, IUCV *SYMPTOM.3. Link to the symptom record recording virtual machine’s 191 disk. To dothis, enter:link to opersymp 191 as 391 wrWhen CP responds with ENTER WRITE PASSWORD: enter:wpass318 z/VM: CP Planning and Administration

Setting Up SVMswhere wpass is the write password of the symptom record recording virtualmachine.4. Access the 391 disk. To do this, enter:access 391 xIf you receive a message that says X'391' DEVICE ERROR, you must format the391 disk. To do this, enter:format 391 xCMS responds with FORMAT WILL ERASE ALL FILES ON DISK X (391). DO YOUWISH TO CONTINUE? (YES|NO). You should enter:yesCP responds with ENTER DISK LABEL. You should enter:symptomor any 1- to 6-character label name.5. Copy a file named DVM PROFILE from MAINT’s 191 disk to the 391 disk.(DVM PROFILE is the PROFILE EXEC for the accounting, error recording, andsymptom record recording virtual machines.) The RETRIEVE utility, which doesthe IUCV connect to the *SYMPTOM system service, is invoked from thisPROFILE EXEC. To do this, enter:copyfile dvm profile a profile exec x6. Release and detach the 391 disk. To do this, enter:release x (det7. If the symptom record recording virtual machine is not logged on, use theXAUTOLOG command to automatically log on the symptom recordrecording virtual machine. To do this for the opersymp user ID, enter:xautolog opersympSetting Up Virtual Machines to Collect Symptom RecordsYour installation can set up multiple virtual machines to collect the symptomrecords. There are two methods that you can use to specify to CP which virtualmachines will be used to retrieve symptom data. These are as follows:v At CP generation time in the system configuration file, code theSYSTEM_USERIDS statement or the SYSSYMP macroinstruction to specify thevirtual machine IDs (up to two) for which the CP symptom system service(*SYMPTOM) is to accumulate records. If these users have an entry in the userdirectory, they will be logged on as part of CP initialization. See“SYSTEM_USERIDS Statement” on page 232 for information about theSYSTEM_USERIDS statement or “SYSACNT (Optional)” on page 661 forinformation about the SYSSYMP macroinstruction.v Additional virtual machines can also collect symptom records by following theinstructions in sections:– See “Specifying a New Symptom Record Recording Virtual Machine.”– See “Starting Manual Retrieval of Symptom Records” on page 320.Specifying a New Symptom Record Recording Virtual MachineNormally your installation sets up particular virtual machines to be the symptomvirtual machines. If you want to have additional virtual machines collect symptomrecords, do the following:v Make sure the new symptom virtual machine has an A-disk available to receivethe symptom records.Chapter 8. Setting Up Service Virtual Machines 319

Setting Up SVMsv Make sure the system programmer authorizes the new virtual machine to receivethe records in the IUCV directory statement.The user entering the RETRIEVE utility must have a directory containing anIUCV directory control statement authorizing the virtual machine to connect to theCP system service which supports the type of record being collected.*SYMPTOM must be specified for SYMPTOM records.v Follow the steps outlined in “Starting Manual Retrieval of Symptom Records.”Starting Manual Retrieval of Symptom RecordsOrdinarily, the symptom virtual machine starts retrieving automatically when youbring up z/VM. But there may be times when you need to start retrieval manually.For example, you may find out through error messages or by entering the QUERYRECORDING command that the recording virtual machine has stopped retrieving.You may also start retrieval manually, as follows:1. If necessary, disconnect from the operator’s virtual machine by entering:disconnect2. Log on the symptom virtual machine.3. Clear any activity in the virtual machine (including retrieval) by entering:#cp system reset4. Load CMS into storage by entering:ipl 190or, if your installation has installed CMS in a named saved system,ipl cmsnamewhere cmsname is the name of your CMS system.5. Make sure there is room on the symptom virtual machine’s A-disk for moresymptom records. To find out how full the A-disk is, enter:query disk aIf the A-disk is almost full, process some of the symptom records. Then erasethe old files to free space on the A-disk.6. Start retrieval of symptom records by entering:retrieve symptom7. Disconnect the symptom virtual machine by entering:#cp disconnectYou may now use the display for another virtual machine.8. If necessary, reconnect the operator’s virtual machine.Disassociating a User ID from the Retrieval of Symptom Records1. Stop the recording of SYMPTOM records for this user ID. To do this from a userID authorized for the class A or B version of the CP RECORDING command,enter:recording symptom off qid useridOr, the user ID being removed (must be authorized for the class C, E, or Fversion of the recording command), enter:recording symptom off320 z/VM: CP Planning and Administration

Setting Up SVMs2. If there are symptom records queued in CP storage for this user ID and youwant to save the data, log on the user ID to be deleted and enter:retrieve symptomThis will place the symptom records in the proper file for later processing.Disconnect this user by entering:#cp disconnectLog back on the authorized user ID.3. If the symptom records queued in CP storage for this user ID are not wanted,they may be purged. To do this from a user ID authorized for the class A or Bversion of the CP RECORDING command, enter:recording symptom purge qid useridOr, the user ID being removed (must be authorized for the class C, E, or Fversion of the recording command), enter:recording symptom purgeThis will PURGE all the symptom records queued in CP storage for this user ID.4. Verify the record count is zero and recording is off for this user ID. To do this,enter:query recordingNote: The deleted user ID remains in the warm start data and in the output ofthe QUERY RECORDING command until VM is restarted with the COLDoption.5. If the user ID is specified on the SYSTEM_USERIDS statement in the systemconfiguration file, remove that user ID.Note: The user ID OPERSYMP is the default if the SYSSYMP macroinstructionis omitted and no user ID for SYMPTOM is specified in the systemconfiguration file.Setting Up a Virtual Machine for Communication Controller Support forEmulator Program (EP)To manage a 3705, 3720, or 3725 communication controller, set up a specialservice virtual machine. Unlike other service virtual machines such as theaccounting virtual machine, the z/VM System DDR tapes or CD-ROM do notinclude a sample directory entry for a communication controller virtual machine.This support requires that Advanced Communications Function for Systems SupportPrograms (ACF/SSP) be installed on your system.The networking facilities available with communication controllers are providedthrough VM/Pass-Through (PVM) licensed program. PVM requires a separatevirtual machine to perform the loading and dumping of communication controllers.The CCLOAD utility, which can be issued by the disconnected service machine,provides automatic loading for the communication controller. The CCDUMP utilitycan be used to format a communication controller dump file produced by CCLOAD.For the complete syntax of these utilities, see the z/VM: CP Commands and UtilitiesReference.Chapter 8. Setting Up Service Virtual Machines 321

Setting Up SVMsCCLOAD requires access to the read/write A disk. Loading requires space forSYSIN and SYSPRINT files. If CCLOAD is used for dumping the communicationcontroller either automatically or by user request, it requires enough disk space forthe dump files. For direct access storage device (DASD) requirements, see thenetwork program products publications.Use CCDUMP to format and print the dump files produced by CCLOAD. If youprovide another user with shared access to the A disk of the service machine,CTLR dump files can be printed offline while the service machine monitors theCTLR. If you specify DISK, you must have enough space on the A disk for theformatted output file. Refer to the network program products publication for DASDrequirements. When you format the dump on a printer (PRINTER option),messages do not appear on your console but are included in the SYSPRINT file. Ifyou specify DISK, messages included in the SYSPRINT file are displayed on theconsole.To erase the input dump file, you must have write access to the disk where itresides. Do not specify the ERASE option if you are sharing access to files onanother user’s A disk (for example, those generated by the CCLOAD EXEC on adisconnected service machine).The following examples show you how to set up a service virtual machine toperform utility functions for a communication controller:1. Create a directory entry for each communication controller. Use the directoryentry in Figure 8 on page 323 as a sample, but make sure you tailor thedirectory statements to match your system configuration and network licensedprogram requirements.322 z/VM: CP Planning and Administration

Setting Up SVMsUSER EP0F7 NOPASS 1M 4M G** This virtual machine requires only a minimal amount** of storage and the G privilege class.**ACCOUNT 10AUTOLOG AUTOLOG1 PVM OP1 MAINT** Depending on how you set up your network, you will want** this virtual machine to be autologged by either the** system or another service virtual machine such as** VM/Pass-Through (PVM).**IPL CMSCONSOLE 01F 3215 T OP1** If you want the capability to interrupt the service** virtual machine to manually dump and then reload the** communication controller, or to terminate the service** virtual machine, specify a secondary user ID (OP1) on** the CONSOLE statement.**SPOOL 00C 2540 READER ASPOOL 00D 2540 PUNCH ASPOOL 00E 1403 A**DEDICATE 0F7 0F7** Dedicates the communication controller to this user.**LINK MAINT 343 343 RR RMAINT** Provides access to ACF/SSP.**MDISK 191 3380 900 40 XADISK MR** Provides space for dumps of the communication controller.Figure 8. Sample Directory Entry for a Communication Controller2. Set up a PROFILE EXEC for the EP0F7 user ID. Use the sample in Figure 9 asa guideline.access 343 b/a** Access the ACF/SSP disk.**queue ’RUN0F7’** Stack a command to execute the CCLOAD command.**PVMExampleFigure 9. Sample PROFILE EXEC for EP0F7 User ID3. Set up the RUN0F7 EXEC to run the CCLOAD EXEC and inform theVM/Pass-Through virtual machine that the communication controller is active, asfollows:/**/’exec ccload 0f7 ep0f7 cmd(smsg pvm exec ep0f7)’Note: You may need to stop CCLOAD processing while the service virtual machineis disconnected. For example, you may need to free space for dump files. Tohave the service virtual machine resume monitoring the communicationcontroller, have the secondary user ID (OP1 in this case) issue SENDEP0F7 RUN0F7.The following examples illustrate a possible use of the service virtual machine.Refer to PVM publications for details.Chapter 8. Setting Up Service Virtual Machines 323

Setting Up SVMsThe PVM configuration file shown in Figure 10 contains definition of EP (emulatorprogram) lines....** BSC lines on the EP communications controller* whose base subchannel address is 0F7*LINK 030 B0F7A R3270...LINK 031 B0F7B R3270...LINK 032 B0F7C R3270...LINK 033 B0F7D R3270...LINK 034 B0F7E R3270...LINK 035 B0F7F R3270...LINK 036 B0F7G R3270...LINK 037 B0F7H R3270...Figure 10. Sample PVM Configuration FilePROFILE PVM additions to use this support are shown in Figure 11.* For each EP communications controller, whose lines are* owned by PVM, authorize its utility service virtual* machine to send commands to PVM and AUTOLOG the user ID.*AUTHORIZ EP0F7CP XAUTOLOG EP0F7...Figure 11. PROFILE PVM AdditionsThe EP0F7 PVM file shown in Figure 12 on page 325 is used to start the EP linesautomatically.324 z/VM: CP Planning and Administration

Setting Up SVMs* START LINE commands for PVM to execute when signalled* by EP0F7 userid executing CCLOAD for CTLR device 0F7*CP VARY ON 030CP ATTACH 030 *START LINE 030CP VARY ON 031CP ATTACH 031 *START LINE 031CP VARY ON 032CP ATTACH 032 *START LINE 032CP VARY ON 033CP ATTACH 033 *START LINE 033CP VARY ON 034CP ATTACH 034 *START LINE 034CP VARY ON 035CP ATTACH 035 *START LINE 035CP VARY ON 036CP ATTACH 036 *START LINE 036CP VARY ON 037CP ATTACH 037 *START LINE 037Figure 12. Sample EP0F7 FileWhen the 37xx is first loaded by the service machine and PVM issues the VARYand ATTACH commands, the following response is displayed:xxxx varied onlineLine xxxx attached to PVM xxxxFollowing recovery of a 37xx failure, where the EP control program has beenreloaded, CP still considers the EP lines online and attached. When the same PVMcommand list is executed by the service machine, the VARY command displays thefollowing response message:xxxx already onlineATTACH displays the following error message for each line:HCPATR122E Line xxxx already attached to PVMSetting Up Service Pool Virtual MachinesYou can establish a collection of virtual machines that are logged on over extendedperiods. Certain applications use this collection to create tasks on behalf of a user.Such a collection is called a service pool.The pool of virtual machines, each initialized by an application running on CMS, isavailable to handle requests for services from programmable workstations. Theapplication makes a logical connection between the functions the virtual machinesare executing. These services are managed through a VTAM application running onthe Advanced Program-to-Program Communications/VM VTAM Support (AVS) ofz/VM. The VTAM application uses an LU 6.2 APPC/VM session to invoke theseservices. For additional information on AVS, see the z/VM: Connectivity book. Theapplication that controls the service pool is called the service pool manager. TheChapter 8. Setting Up Service Virtual Machines 325

Setting Up SVMsservice pool manager provides services such as autologging the service pool virtualmachines and selecting one to handle a request from a workstation.To define a range of virtual machines to be defined as a pool, code the POOL userdirectory control statement. This assigns a directory entry for each virtual machineto be included in the pool. See “POOL Directory Control Statement (General)” onpage 540 for information on coding the POOL user directory control statement. Ifyou code the POOL statement in a user’s directory entry, it is assigned the onlycontrol statement other than a USER statement in that user’s directory entry. Eachvirtual machine in the pool must have the same first three characters in its user ID,followed by a number in the range specified in the POOL statement.You must code other user directory control statements that apply to the range ofvirtual machines in the pool in a profile entry in the directory (see “PROFILEDirectory Control Statement (Control)” on page 551). The pool definition uses thePROFILE statement as the common user definition information. The PROFILEname must have been defined in the directory before any POOL statement thatrefers to it.A password (AUTOONLY) specifies that a virtual machine can only be autologged.Thus, a user at a terminal cannot enter a LOGON command for a virtual machinewith the AUTOONLY password. This provides a security and data integrity functionfor service pool virtual machines without having to administer different, changingpasswords for the pool of virtual machines.Setting Up Print Services Facility/VM Virtual MachinesThe Print Services Facility/VM (PSF/VM) licensed program processes the spooledoutput for advanced function printers. It also uses defaults and options specified ina PSF command and CP SPOOL command to generate printer commands toproduce formatted output. PSF/VM supports the following printers:v 3800 Printing Subsystem Models 3 and 8v 3812 Page Printer Model 2v 3820 Page Printerv 3827 Page Printerv 3835 Page Printerv 4224 Printer.PSF/VM is composed of the following components:v The PSF command, which places a print file and resource files in a printer spoolfile for a page printer and places the processing options in an external attributebuffer (XAB).v The spool file conversion machine (SFCM), which converts the spooled print filesinto the relevant printer command stream for a specified type of printer drivermachine (PDM) (for example, a 3800 PDM or a 3820 PDM) and builds a set ofcontrol files for use during processing of the print file.v The 3800 PDM, which drives a 3800 using the printer command stream andcontrol files created by the SFCM.v The 3820 PDM, which processes files either for a 3820 or for one or moreprinters attached through RSCS. For the 3820, the 3820 PDM drives the printerusing the printer command stream created by the SFCM.v The Group3 PDM, which processes files for a Group3 printer using the printercommand stream and control files created by the SFCM.326 z/VM: CP Planning and Administration

Setting Up SVMsYou must define one virtual machine for the SFCM and for each PDM. Dependingon the requirements of your installation, you might define a virtual machine ownedby the system programmer for maintaining PSF/VM.For more information about PSF/VM and how to set up the virtual machinesrequired for this product, see the Print Services Facility/VM System Programmer’sGuide.Setting Up Virtual Machines for Data Storage ManagementThe DFSMS/VM* is the foundation for system-managed storage in the VMenvironment. A DFSMS/VM service machine uses the Interactive StorageManagement Facility (ISMF) to reduce the amount of manual work that must beperformed when data is migrating to newly installed DASD. ISMF automaticallyformats new minidisks, updates user directories, and automates other functions,providing both speed and predictability during data migration activities.You can use a DFSMS/VM service virtual machine to provide information aboutother storage management tasks. For example, you can use DIAGNOSE X'08' todetermine the devices allocated to the system. The VMUDQ macroinstructionqueries user directory minidisk definitions.You can configure a DFSMS/VM virtual machine to ensure data integrity andsecurity when you move data to new storage locations. ISMF provides a checkutility that performs an integrity evaluation of a CMS minidisk to verify whether itsfile structure is intact. To ensure data security during and after move operations, aDFSMS/VM machine can rely on the usual access authority checking mechanisms,such as ACI and password validation, as well as stable and exclusive link accessoptions that require specific authorization to allow user access to data.The LNKSTABL and LNKEXCLU options, specified with the OPTION user directorycontrol statement for a particular virtual machine, give that machine authority tospecify access modes that limit the ability of other users to obtain link access to aminidisk while the service machine is linked to that disk. However, the use of theseaccess-mode options can potentially tie up the system if improperly orindiscriminately used and should be treated as a special resource.These options are described in more detail in “Using Link Access Control Options”on page 387. In addition, further information on access modes can be found in“LINK Directory Control Statement (Device)” on page 500 and “MDISK DirectoryControl Statement (Device)” on page 513. The VMUDQ macroinstruction isdescribed in z/VM: CP Programming Services.Chapter 8. Setting Up Service Virtual Machines 327


Chapter 9. Planning for SNA Console CommunicationServices (SNA/CCS)The Systems Network Architecture console communication services (SNA/CCS)provide a total data communication structure for transmitting information by using acommunications network. SNA communication products perform functionstraditionally handled by the main processor (for example, management ofcommunication lines, device-dependent characteristics and control, and dataformatting).SNA/CCS provides full z/VM console capabilities to operators on SNA/CCSterminals. You can use SNA/CCS terminals as virtual machine consoles. Theinformation is transparent. If you are planning to use SNA/CCS processing, youmust consider the topics discussed in this chapter.This chapter describes the SNA environment and tells you how to:v Establish the SNA/CCS terminal environmentv Do tracing for SNA/CCS.Structure of the SNA EnvironmentThree major components contribute to SNA/CCS terminal support:v SNA console communication services (SNA/CCS)v Inter-user communication vehicle (IUCV)v One of the following:– VTAM SNA Console Support (VSCS)– VTAM Communications Network Application (VCNA) licensed program.IUCV and SNA/CCS are part of z/VM.SNA/CCS terminal support is provided through a virtual machine. The VTAM servicemachine (VSM) is the virtual machine that acts as an interface between SNA/CCSand the SNA network. It runs either VSCS or VCNA. VSCS and VCNA both workwith the Advanced Communications Function for Virtual Telecommunications AccessMethod (ACF/VTAM) in doing their job.Usually, ACF/VTAM is also in the VTAM service machine. VSCS, however, may bein a different virtual machine. ACF/VTAM manages the SNA network, and VSCS orVCNA acts as the interface to CP.A VCNA VTAM service machine also requires one of the following operatingsystems with External Interrupt Support (EIS):v VSE/Advanced Functions licensed program (latest level)v OS/VS1 with Basic Programming Extensions licensed program.VSCS does not require a guest operating system but does require GCS.© Copyright IBM Corp. 1991, 2004 329

Planning for SNA/CCSEstablishing the SNA/CCS Terminal EnvironmentTo allow SNA/CCS terminals to access z/VM:v VSM must be defined to the systemv SNA/CCS must be defined to the VSMv SNA communications must be enabledv VSM must be started in its own virtual machinev VSM must establish a global IUCV connection with SNA/CCS.After these tasks are accomplished, individual SNA terminal users may accessz/VM through the terminals managed by that VSM.Defining the VSM to z/VMThe directory entry for the virtual machine that contains the VSM:v Must authorize the VSM to use IUCV to communicate with SNA/CCS using theIUCV directory control statement.v Should specify PRIORITY on the IUCV directory statement to allow the use ofIUCV priority messages.v May specify how many IUCV connections are allowed by using the MAXCONNoperand on the OPTION control statement. Note that the MAXCONN operanddetermines how many SNA/CCS terminal users may access z/VM through theVSM.v May specify that the virtual machine can be automatically logged on by othervirtual machines using the XAUTOLOG control statement.v May specify that a named saved system or device is to be loaded when thevirtual machine is logged on using the IPL control statement.v May specify a secondary user ID on the CONSOLE directory control statement ifsecondary console support is to be used in the operation of the VSM.Defining Logos Used by VSMsLogos used by VSMs are selected via the logo configuration file. You can choose tohave one logo picture file for all VSMs, or you can choose a different logo picturefor each VSM in your system. You use CHOOSE_LOGO statements in the logoconfiguration file to tell CP which logos to use for terminals logging on throughVSMs.For more information about logos used by VSMs, refer to Chapter 7, “The LogoConfiguration File,” on page 279; for details, see “CHOOSE_LOGO Statement” onpage 285.Defining SNA/CCS to VCNAThe VCNA START parameters that relate to SNA/CCS are described below. Theyare all operands of the DTIGEN macroinstruction, which is optional.CCSMLMspecifies the CP message limit. This is the maximum number of messages tobe specified on the IUCV ACCEPT request.LGNCMDSspecifies the CP commands that are valid before logon.PACEspecifies the pacing value for communication between VM/VCNA and CP. This330 z/VM: CP Planning and Administration

Planning for SNA/CCSvalue is the maximum number of I/O requests per terminal from CP toVM/VCNA before VM/VCNA must return a pacing response. It is provided toprevent a buffer overrun in VM/VCNA.RDSPTMRspecifies the redisplay timer value in sixteenths of a second. CP uses this valueto force VM/VCNA to redisplay data entered and to unlock the keyboard afterthe prescribed time has elapsed.TIMEINTspecifies an interval in seconds that VM/VCNA uses to determine how oftentimer functions such as MORE, HOLDING, and NOT ACCEPTED are to beperformed. A smaller value gives greater accuracy with more timer overhead.VCNAMLMspecifies the IUCV VM/VCNA message limit. This limit is the maximum numberof messages specified by VM/VCNA on the IUCV CONNECT request.Defining SNA/CCS to VSCSThe VSCS START parameters that relate to SNA/CCS are described below. Theyare all operands on the DTIGEN macroinstruction, which is optional.LGNCMDSspecifies the CP commands that are valid before logon.RDSPTMRis the redisplay timer value. CP uses this value to force VSCS to redisplayentered data and to unlock the keyboard after the prescribed time.W3767Lis the default line size for 3767 and 3777 terminals. This value is the initialsetting of the CP TERMINAL LINESIZE command when the user logs on with a3767 or 3777 terminal.W2741Lis the default line size for 2741 terminals. This value is the initial setting of theCP TERMINAL LINESIZE command when the user logs on with a 2741terminal.WTWXLis the line length for teletype keyboard printers.VSAMLMis the maximum number of messages specified on IUCV ACCEPT andCONNECT requests.DPACEis the pacing value to be used with display terminals.KPACEis the pacing value to be used with keyboard terminals and printers.Enabling SNA CommunicationBefore a VSM can establish communication with SNA/CCS, you must enable SNAcommunication. In a multiple VSM environment, you must selectively enable ordisable SNA communication for a particular VSM. Use the CP ENABLE andDISABLE commands to enable and disable SNA communications.Chapter 9. Planning for SNA Console Communication Services (SNA/CCS) 331

Planning for SNA/CCSStarting the VTAM Service MachineThe VSM operator must initialize the VSM before a user can log on to a terminalcontrolled by the VSM. The VSM operator logs on to z/VM from a nativelycontrolled terminal to create a virtual machine in which the VSM can be initialized.The VSM consists of the programs loaded into this virtual machine: the operatingsystem, the access method, and VM/VCNA or VSCS. After the VSM is operational,the VSM operator can disconnect, and further commands to the VSM can beentered from a secondary console (perhaps the system operator’s console), freeingthe virtual machine terminal.An alternative method, also using secondary console support, does not require avirtual machine terminal that is dedicated to VSM. The VSM is automatically loggedon in disconnected mode during CP initialization using XAUTOLOG. Then aPROFILE EXEC (VCNA) or a PROFILE GCS EXEC (VSCS) can bring up thesystem (saved or newly IPLed), and the VSM can be operated from the designatedsecondary console from the start.Improving SNA/CCS PerformanceBecause SNA/CCS is implemented using a service virtual machine, you canimprove the performance of the SNA/CCS environment by allocating more realprocessor resources to the VSMs that control the terminals connected to CP. Usethe CP SET SRM command or the SHARE directory statement to do this. Thisperformance consideration is not specific to SNA/CCS VSMs but applies to allservice virtual machines. For more information on the CP SET SRM command, seethe z/VM: CP Commands and Utilities Reference. For more information on theSHARE statement, see page 555. For more information on performance and theuse of the CP SET SRM command and the SHARE statement, see the z/VM:Performance book.Some installations may see a performance benefit by using the IPOLL function withGCS to poll for pending replies and messages. By allowing GCS to retrieve up to102 interrupts on each IPOLL, a significant reduction in the number of interrupts toVSCS when it is flooded with incoming IUCVs can be expected. The benefit isgreatest when the VSCS virtual machine is loaded with work. The GCS commandSET IPOLL ON enables this function.VSMTerminationYou can shut down a VSM in the following ways:v You can use normal CP shutdown processing.v You can terminate VTAM by using the VTAM HALT command.v You can deactivate VCNA or VSCS by using the ACF/VTAM commands.v The VSM operator can enter the VCNA or VSCS QUIT command to terminateVCNA or VSCS.v The z/VM operator or the VSM operator (if authorized) can enter a CP FORCEcommand to remove individual users. This, combined with entering the DISABLESNA command to prevent any new SNA/CCS connections, in effect shuts downthe VSM.332 z/VM: CP Planning and Administration

Chapter 10. Setting Up Cross System Extensions (CSE)OverviewThis chapter contains an overview of cross system extensions (CSE) and tells howto:v Plan for CSEv Enable CSEv Administer CSEv Define a virtual CSE system to be used during hardware outages.VM provides programming support for cross system extension (CSE). With CSE,end users can participate in a multisystem environment. This environment caninclude up to four z/VM systems connected in a complex. Systems running differentreleases of z/VM may be connected in the same CSE complex.Figure 13 depicts an example of a CSE complex consisting of four z/VM systems.System1CSE SystemDASDDASDDASDSystem4CSE SystemSystem2VM/ISF SystemSystem3VM/ISF SystemFigure 13. A Four-System CSE ComplexCSECapabilitiesCSE consists of three related, but independent, parts:v Cross system linkThis facility extends CP link protocols across the CSE complex. It controlsnormal, stable, and exclusive read or read/write access across multiple VM© Copyright IBM Corp. 1991, 2004 333

CSE Overviewsystems for minidisks on shared count-key-data direct access storage devices(CKD DASD), including those devices that accept the extended-count-key-data(ECKD) channel program protocol.v Cross system spoolThis facility extends CP spooling capabilities. It contains and manages spool filesfor users across multiple VM systems by using shared DASD and acommunication vehicle. The communication vehicle is the VirtualMachine/Pass-Through Facility with modifications. You can set up your system tohave cross system linking without cross system spooling.v Cross system MESSAGE and QUERY commands.With CSE, MESSAGE and QUERY command support is extended to allow theiruse across multiple VM systems. Refer to “Supported Features” on page 335 forfeatures of z/VM that are supported across system boundaries.Cross system spool is supported among all CSE systems. The maximum number ofsystems which may be coupled using CSE functions depends on the specificfunctions being used:v Shared spool: 4v Shared minidisks: up to 56, depending on the physical devicesv Shared source directory: 4UsersSupportedA CSE complex can support 95% of the total number of users that could besupported by each system without CSE. For example, if each system could support1000 users, a four-system CSE complex could support 3800 users, as shown bythe equation:1000 x .95 x 4 = 3800(users) (percent) (systems) (users supported)For general users, this CSE complex functions as a single larger system. Forsystem operators, programmers, and administrators, the single image is lesspronounced. These users tend to view the CSE complex as up to four systems thatmust be managed as before.Setting Up a CSE ComplexSetting up a CSE complex consists of:Planning for CSEv Providing the hardware connections between the processorsv Installing the IBM VM/Pass-Through Facility licensed programv Configuring z/VM and the supporting programs with the information they need torun the CSE complex.Before you install CSE, you need to identify the requirements unique to yourinstallation in a detailed plan.RequirementsUsing CSE requires the following:v A single source directory. A single source directory requires z/VM DirectoryMaintenance Facility (DirMaint) to synchronize the user directories of all systemsin the CSE complex. You may, if you wish, choose another means of creating asingle source directory, but that is outside the scope of CSE.334 z/VM: CP Planning and Administration

Planning CSEv A single version of DIRECTXA. The most current version of DIRECTXA must beused on all systems in the CSE complex.v Multiple z/VM systems.v The systems in the complex must be connected by means of channel-to-channeladapters (CTCA) or an IBM 3088 Multisystem Channel Communications Unit.The VM/Pass-Through Facility virtual machines used by CSE communicate overthese connections.v The systems must share CKD-formatted DASDs. Fixed block architecture (FBA)devices are not supported by the cross system link facility.v The same release of the IBM VM/Pass-Through Facility (Program Number5684-100) licensed program must be installed on all systems in the complex. TheVM/Pass-Through Facility is needed to support cross system spool and CSEmessage support among all systems.You need detailed information about z/VM. (See the “Bibliography” on page 787 fora list of z/VM books.)RestrictionsSystem paging space and minidisks cannot reside on the same DASD device. Thiswill avoid a possible deadlock situation.An installation should not define users with a password of LBYONLY, unless allsystems in the CSE complex support the LBYONLY operand of the USER directorycontrol statement. For more information about this function, see the “USERDirectory Control Statement (Control)” on page 572 and the LOGON command inthe z/VM: CP Commands and Utilities Reference.SupportedFeaturesCSE supports the following features of z/VM across system boundaries:v LINK command for count-key-data (CKD) DASD, including those DASD thataccept the extended-count-key-data (ECKD) channel program protocolv Spool filesv Special message function (SMSG)v Message (MSG, MSGNOH) and warning (WNG) commandsv RACF( ) licensed program for VMNote: If the RACF licensed program is on one system in the complex, it must beon all systems in the complex.v QUERY commands– QUERY LINKS– QUERY NAMES– QUERY USERS– QUERY USERS useridv DIRMAINT support for general usersv Other commands– CHANGE– INDICATE LOAD– ORDER– PURGE– TAGChapter 10. Setting Up Cross System Extensions (CSE) 335

Planning CSE– TRANSFER.Some features of z/VM, although unchanged within any system in the CSEcomplex, are not supported across system boundaries by CSE. These are:v Virtual machine communication facility (VMCF)v Inter-user communication vehicle (IUCV)– Monitoring data collectors– Accountingv Virtual reserve/releasev System data filesv Virtual disks in storage.Applications that contain the Transparent Services Access Facility (TSAF) can useTSAF functions within a CSE complex.Note: The VMUDQ macro, used to query the CP user directory, examines only theobject directory of the system on which it is being run. For DASD that arenot totally shared and globally defined among member systems of a CSEcomplex, you must run VMUDQ on each of those systems to obtain acomplete picture of the target volume. For more information about theVMUDQ macro, see the z/VM: CP Programming Services book.Sharing DASD VolumesDevice I/O activity may increase significantly when DASD are shared amongmultiple VM systems. Devices can serve only one system at any given instant. Iftwo systems require service at the same time, one system will find the device busyand must wait. The length of this wait depends upon the type of I/O request alreadyin progress. If the first I/O is limited to a single track, as are most read and writeoperations on behalf of the CMS file system, the wait is not long. If the I/Opotentially affects all tracks on the same cylinder, for such activity as dumping,restoring, CMS and CP formatting, or CP paging and spooling, the time spentwaiting can seriously affect the performance of the second system.Furthermore, if additional work is queued for the device in the first system (forexample, during periods of heavy CP paging and spooling loads), when the currentI/O operation ends, both systems race to engage the device and start the nextoperation. The second system is at a disadvantage in this race because it mustexecute a longer code path. That is, fewer instructions are required to redrive adevice with an already-queued I/O request after the operation in progressterminates than are required to recognize that the busy device is now free and thatanother I/O operation can be started for it.An additional complication arises because DASD control units do not, in general,respond to each of their channel interfaces in a round-robin or fair-share manner.Thus, the system connected to the highest-priority channel interface of the controlunit receives more service than any other during periods of high contention. Inextreme cases, this can result in a lockout.Because of these considerations, you should follow these general guidelines:v Assign storage devices, control units, and channel paths to avoid unnecessaryCSE I/O contention.336 z/VM: CP Planning and Administration

Planning CSEv Cable the fastest system to the lowest priority port and the slowest system to thehighest priority port on the control units when DASD is shared among systems ofunequal power.v Check that all devices are online after the system is IPLed.Avoiding Shared DASD I/O BottlenecksSince multiple systems can now cause I/O operations on the same devices andcontrol units, bottlenecks that did not exist (or that were not obvious) in a singlesystem can cause serious performance complications in a CSE environment.Careful planning will eliminate unnecessary performance problems by preventingundue I/O interference caused by CSE activity. In general, the aim of such planningis to isolate I/O operations by type and by system.The kinds of shared DASD that you should consider when planning for CSE areDASD for:v Shared spool filesv Backup and recoveryv Shared access to minidisks.Each of these has somewhat different characteristics, which are explained asfollows.DASD for Shared Spool Files: For shared access to spool files, all CP-ownedDASD on which spooling space has been allocated must be physically and logicallyshared by all systems in the complex. Proper cabling of channels and control unitscreates physical sharing. The volume ID of each spooling DASD in each system’slist of CP-owned DASD (created by the CP_OWNED statement in the systemconfiguration file) creates logical sharing.Performance Considerations: To reduce the performance impact of DASD sharingfor spool files:v Isolate by system–Do not intermix the CP-owned spooling DASD of differentsystems on the same string, control unit, or channel path. If this rule is followed,systems will not compete with each other when writing, checkpointing, or purgingspool files. CSE contention is possible only when systems are reading spool filesother than their own.v Isolate by type–Do not mix DASD spooling space with other high-activity DASDspace, either on the same device or on the same control unit. Paging space,temporary disk space, and frequently used CMS minidisks should not be allowedto contend with spooling.v Review how you have organized your CP-owned DASD.Each system has its own spooling volumes. In the list of each system’sCP-owned volumes, you must include the volumes used for spooling in the othersystems, but you must designate them as shared volumes.Use the SHARED option on CP_OWNED statements in your systemconfiguration file. You do not have to list the volumes in any particular order aslong as you use the SLOT operand to give the same slot number to the samevolume on each system.DASD for Backup and Recovery: When one system in the CSE complex is downfor scheduled or unscheduled maintenance, spool files created on that system canbe made available to users on other systems by operating CSE in a virtualmachine. Refer to the z/VM: System Operation book.Chapter 10. Setting Up Cross System Extensions (CSE) 337

Planning CSEFor this to be effective, the spooling and paging DASD owned by the system mustbe available to at least one other system in the complex. Spooling DASD areshared as a matter of course and do not present a problem. Paging space,temporary disk space, and the system residence volume should not be online to(logically shared by) any other system during normal operation. Since I/Ooperations to these spaces are initiated only by the system to which the space isdedicated, intermixing paging or T-disk space belonging to different systems on thesame device, control unit, or channel path introduces unnecessary CSE contention.Such contention could degrade the performance of all systems without providingany compensating functional benefit.To allow DASD sharing for backup and recovery without creating performanceproblems, try to:v Share physically the DASD required for backup operation. To provide the mostflexibility, all DASD should be accessible by all systems in the complex.v Isolate the DASD that is dedicated to a single system. Do not intermix such aDASD on the same device, control unit, or channel path with shared DASDs.v Avoid logically sharing DASD space that is dedicated to a particular systemduring normal operation. DASD that contain the following should be online to thesystem where used and offline to all others:– Paging space– Directory space– T-disk space– System residence volume.When the required DASD is operating in backup mode, it should be switched andvaried online to the backup system.DASD for Shared Access to Minidisks: For CSE to control links between themultiple VM systems in the complex, the real volumes on which the minidisks residemust be physically and logically shared by all systems. Physical sharing is providedby having the disk drives accessible to all systems. Logical sharing is assured bycorresponding I/O device specifications (in system configuration files and IOCPs ifneeded), and identical lists of DASD volumes (in XLINK_VOLUME_INCLUDE andEXCLUDE statements in system configuration files) of all systems.Maximum Number of Systems Supported for Cross System Link: The maximumnumber of systems supported for cross system link is 56 if the CSE complex usesonly shared ECKD capable CKD devices. If any shared CKD devices are used,then the maximum number of systems supported depends on the device type. SeeTable 13 on page 365 for the maximum number of systems supported for each CKDdevice type. See “Default Values for the CSE Area” on page 365 for furtherexplanation.Choosing Which Minidisks to Share: When multiple systems access the same realdisks, the probability that CP will find the device busy when an I/O command isentered is increased. Therefore, heavily accessed disks like the CMS S and Y disksshould not be shared by all systems. Multiple copies of these minidisks (onseparate real volumes) can be provided so that each system can access its own Sor Y disk without CSE contention. These volumes can still be included in crosssystem link for maintenance, but general users cannot share them across VMsystems.338 z/VM: CP Planning and Administration

Planning CSEPerformance Considerations for CMS Minidisks: In a CSE environment, thechance of having high contention volumes is increased because potentially moreusers have access to one or more minidisks on the same volume.To achieve better I/O performance:1. Use 4 KB blocking on all CMS minidisks. Since the block size used by the CMSFORMAT command defaults to 2 KB for 3350s and 4 KB for 3380s, you musttake positive action to achieve 4 KB blocking on 3350s.2. Use a 3880-13, 3880-23, or 3990-3,6 to cache heavily used read-only minidisksin the controller. This should dramatically reduce the volume’s busy time.3. Put heavily used minidisks on separate volumes and assign users to theseminidisks so that the load is primarily from a single system. For example, as youplan the use of the CMS Y disk, consider creating the CP directory entries forMAINT 19E on each system that point to a different real device and cylinderoffset, so that each system uses a different Y disk. Another user ID —CMSMAINT, for example — could have minidisk entries defined for all the Ydisks in the complex. You would link to the CMSMAINT entries to update all theY disks from one system.4. Avoid using the minidisk caching feature for minidisks on shared DASDs. Inprinciple, all general-user minidisks should be shared through cross systemlinking in the CSE environment. Minidisks that contain the single sourcedirectory and serve as preliminary A disks for user IDs such as OPERATORmust be shared throughout the complex. Consider minidisks owned by servicemachines individually, depending on the activity level of each minidisk and howit is used.Note: Using MDC with CSE may cause data integrity problems. See MinidiskCaching Feature (MDC) below.MDISK Statements in the CP User Directory: The CP user directory defines thelocation and extent of all minidisks. For two or more systems to link to the sameminidisks, the MDISK directory entries for all shared volumes must be identical onevery system in the complex. CP and the directory program do not prevent youfrom defining minidisks that overlap. A CP system in a CSE complex is completelyunable to recognize overlapping minidisks on other systems because the minidisksare known solely by their starting cylinders. If you define such overlap, you assumeresponsibility for data integrity.Correctly protecting an installation’s minidisks across a CSE complex meanskeeping CP directory entries for shared volumes exactly synchronized. This supportis provided by DIRMAINT Release 5 with multiple CPU support.Minidisk Caching Feature (MDC): CP can cache CMS minidisks in Expanded orMain Storage. This is a definite performance advantage in a CMS-intensiveenvironment. However, because MDC does not address cross-cache invalidation,the scope of caching is limited to one system only. The MDC feature is thereforeincompatible with DASD sharing in any form, with or without CSE. Using MDC withCSE may cause data integrity problems.Since CACHING=ON is the default, the real devices on which all shared minidisksreside can be identified by the SHARED YES specification on their RDEVICEstatements in the system configuration file. This specification prevents MDC forthese devices. Alternatively, you can suppress MDC at a more granular level byspecifying NOMDC on the MINIOPT statement for shared minidisks in the directoryand also by using the SET MDC command.Chapter 10. Setting Up Cross System Extensions (CSE) 339

Planning CSEPlacing of the CSE AreaCSE keeps control information about the state of CSE links to minidisks on aspecial area (called the CSE area) of the real volume where the minidisks reside.(In earlier releases this area was referred to as the CSE track.) During installation,the XLINK utility initializes this area. This information must be updated only whenthe first link to that minidisk occurs, when a link higher than any other links to thatminidisk occurs, or when the last link of that type disappears. It is important that thisarea not be inadvertently updated by any program other than CP.If you do not specify a particular location during system definition, CSE initializesthe CSE area starting on cylinder 0, track 1, when you enter the XLINK FORMATcommand. This is described under “Generating the Cross System Link Facility” onpage 349. Since CP keeps the volume label and allocation maps on cylinder 0,track 0, the default location for the CSE area should be available. Allocate thelocation you choose for the CSE area as PERM space with the Device SupportFacilities program (ICKDSF). The XLINK FORMAT command allows these volumesto be shared by formatting the CSE area. For more information about the XLINKFORMAT command, see the z/VM: CP Commands and Utilities Reference book.Note: Do not define user minidisks in the space reserved for the CSE area, exceptfor the purpose described under “Generating the Cross System Link Facility”on page 349. For some device types, the CSE area resides on multiplecylinders. See Table 13 on page 365 describing the number of cylindersused for each device. When reserving space for the CSE area, thesecylinders must also be considered.Defining Volumes Containing Minidisks to be SharedYou can include and exclude volumes containing minidisks to be shared. Use theXLINK_VOLUME_INCLUDE statement (see page 268) to include volumes and theXLINK_VOLUME_EXCLUDE statement (see page 266) to exclude volumes.Cross System Linking and Synchronization of DirectoriesTo protect your installation’s minidisks across the CSE complex, the CP directoryentries for shared DASD volumes must be kept exactly synchronized. One methodfor synchronizing these directories is with the IBM z/VM Directory MaintenanceFacility (DirMaint).So that all CSE systems can link to the same minidisks, the MDISK directoryentries for all shared volumes must be identical on all systems in the CSE complex.Directory entries for user IDs that are allowed to be simultaneously logged on toevery system should not contain MDISK or LINK statements with an access modeof multiwrite (M/W) if these minidisks are used by CMS. When a hardware pathfrom each system to the proper device is defined, and identical minidisk extents inthe VM directory are also defined, minidisks become available to every system.You can use the OPTION, MDISK, or LINK directory control statements to give aspecified user sole write access to a minidisk for a limited period of time, thusoffering increased data integrity in cases where the stability of a given minidisk isrequired. The LNKSTABL and LNKEXCLU operands of the OPTION directorycontrol statement authorize a user to use the stable and exclusive link modes of theLINK command and DIAGNOSE code X'E4'. This global authority allows a virtualmachine to perform a stable link to any minidisk to which it has password-levelauthorization. You can also specify stable and exclusive authority to a specificminidisk using the mode suffix letter (S or E) on the MDISK or LINK directorycontrol statements. While stable or exclusive links to a minidisk are in effect, accessto that minidisk by any other user will be restricted or denied. For more information340 z/VM: CP Planning and Administration

Planning CSEabout the LNKSTABL and LNKEXCLU options, see the “OPTION Directory ControlStatement (General)” on page 533. For more information about link accesses, see“LINK Directory Control Statement (Device)” on page 500 or “MDISK DirectoryControl Statement (Device)” on page 513.Spool File Directory StatementsIn a CSE complex, the MAXSPOOL operand of the SPOOLFILE directory statementlimits the number of spool files that a user may have on any given system. Sincethe CSE complex operates on a single source directory, this limit is the same for allsystems. To define different MAXSPOOL limits for different systems, use the systemaffinity records.The maximum number of spool files that a user may create on each system in thecomplex is determined by dividing the number of files declared with MAXSPOOL bythe number of systems in the complex. For example, if the MAXSPOOL operand isdefined as 300 on a three-system complex, that user may create 100 spool files oneach of the three systems. If that user uses the conditional statement facilities andchooses to define MAXSPOOL limits of 150 spool files on the first system, 210spool files on the second system, and 300 spool files on the third system, that usermay create up to 50 on the first system, 70 on the second system, and 100 on thethird system.Preparing for CSETo prepare for CSE, you must:v Cable the systems’ hardware paths.v Prepare the existing directories for a merger into a single source directory.v Put the same version of DIRECTXA on every system in the CSE complex.v Define user IDs that concurrently log onto all systems so that they have onedirectory entry (for example, OPERATOR).v Decide which volumes should be shared. See “Sharing DASD Volumes” on page336.v Decide where to place the CSE area on each of the shared volumes. (Thedefault is cylinder 0, track 1.)v Plan how to set up the communication virtual machine (CVM). See “Installing theVM/Pass-Through Facility and Its Modifications” on page 345 and “Preparing theCommunication Virtual Machine (CVM)” on page 350.v Prepare to deal with outages. Each system should have a properly configuredvirtual machine in its user directory able to run a guest system in the eventanother system is disabled. See the z/VM: System Operation book for anexample.Cabling the HardwareUse the operator’s guides for your hardware devices to plan the best cabling foryour hardware. Ensure that shared volumes are accessible to all the systems in theCSE complex.Preparing for a Single Source DirectoryReview the directories of the current systems. Minidisks that are defined in all thedirectories must have identical volume identifiers and cylinder extents, since onlyone definition of them is in the single source directory. To avoid overlapping extents,you need to:v Identify identical virtual machines in existing directoriesv Define a policy for managing identical identifiers in the existing directories.Chapter 10. Setting Up Cross System Extensions (CSE) 341

Planning CSENote: When using different levels of CMS, it may be necessary to generate CMSon a disk other than the standard 190 disk.Nonshared Directory EntriesSome directory entries define user IDs that may be logged on to more than onesystem within the CSE complex at the same time. These user IDs include:v The system operatorv The communication virtual machine (CVM)v The service machines that have identical names and run concurrently on morethan one system.Refer to the z/VM Directory Maintenance (DirMaint) library for information andexamples of directory entries.Example of a Directory Entry: Figure 14 is an example of a directory entry. Thisentry is appropriate for the system operator user ID in each system in the CSEcomplex. The format is standard for any similar user IDs.Note: You can use either the pre-PROFILE EXECs (see Figure 15 on page 343and Figure 16 on page 344) or the SYSAFFIN control statement ofDIRMAINT Release 5 to set up your directory statements.**************************************** SYSTEM OPERATOR ****************************************USER OPERATOR XXXXXX 4M 16M ABCDEGACCOUNT ACT1 35H:0253CONSOLE 009 3215SPOOL 00C 2540 READER ASPOOL 00D 2540 PUNCH ASPOOL 00E 1403 ALINK CMSPACKS 190 190 RRLINK CMSPACKS 19E 19E RRLINK ADISKS 207 191 RRLINK ADISKS 204 204 MRLINK ADISKS 304 304 MRLINK ADISKS 404 404 MRLINK ADISKS 504 504 MRFigure 14. Example of a Directory EntryThe ADISKS user ID is an arbitrarily chosen name for the entry that defines the poolof read/write (R/W) CMS minidisks from which each of the common user IDsreceives a particular minidisk.Note: The preliminary A disk, linked as 191, will be in read-only (R/O) mode, buteach of the real A disks, linked initially as 204, 304, 404, and 504, will belinked in R/W mode (unless some other user already has them in R/Wmode). Only one of these disks is required, depending upon which system isbeing logged on to. The secondary pre-PROFILE EXEC for this user shoulddetach the disks that are not required, so that the disks can be used by thesame user ID on an associated system.Example of a Pre-PROFILE EXEC: Figure 15 on page 343 is an example of apre-PROFILE EXEC for a four-system complex. This sample exec configuresOPERATOR and other common user IDs.342 z/VM: CP Planning and Administration

Planning CSE/*---------------------------------------------------------------------*//* Definitions for this installation follow. These names are the *//* same as those used in the combination of XSPOOL_SYSTEM, *//* XLINK_SYSTEM_INCLUDE, XLINK_SYSTEM_EXCLUDE statements in a system *//* configuration file. *//* *//**/ sysname1 = "SYSTEM1" /**//**/ sysname2 = "SYSTEM2" /**//**/ sysname3 = "SYSTEM3" /**//**/ sysname4 = "SYSTEM4" /**//* *//**/ userid1 = "OPERATOR" /**//**/ userid2 = "PVM" /**//**/ userid3 = "none" /**//*---------------------------------------------------------------------*/MAKEBUF’EXECIO * CP (STRING QUERY USERID’PULL userid junk sysidSAY userid junk sysidIF sysid = sysname1 THEN DO; CALL CSE1; EXIT; END;IF sysid = sysname2 THEN DO; CALL CSE2; EXIT; END;IF sysid = sysname3 THEN DO; CALL CSE3; EXIT; END;IF sysid = sysname4 THEN DO; CALL CSE4; EXIT; END;CALL sysname_bad;CSE1:IF userid = userid1 THEN DO; ’EXEC CSE1USR1’ ; RETURN; END;IF userid = userid2 THEN DO; ’EXEC CSE1USR2’ ; RETURN; END;IF userid = userid3 THEN DO; ’EXEC CSE1USR3’ ; RETURN; END;CALL userid_bad;CSE2:IF userid = userid1 THEN DO; ’EXEC CSE2USR1’ ; RETURN; END;IF userid = userid2 THEN DO; ’EXEC CSE2USR2’ ; RETURN; END;IF userid = userid3 THEN DO; ’EXEC CSE2USR3’ ; RETURN; END;CALL userid_bad;CSE3:IF userid = userid1 THEN DO; ’EXEC CSE3USR1’ ; RETURN; END;IF userid = userid2 THEN DO; ’EXEC CSE3USR2’ ; RETURN; END;IF userid = userid3 THEN DO; ’EXEC CSE3USR3’ ; RETURN; END;CALL userid_bad;CSE4:IF userid = userid1 THEN DO; ’EXEC CSE4USR1’ ; RETURN; END;IF userid = userid2 THEN DO; ’EXEC CSE4USR2’ ; RETURN; END;IF userid = userid3 THEN DO; ’EXEC CSE4USR3’ ; RETURN; END;CALL userid_bad;Figure 15. Example of a Pre-PROFILE EXEC (Part 1 of 2)Chapter 10. Setting Up Cross System Extensions (CSE) 343

Planning CSE/*---------------------------------------------------------------------*//* System name not recognized - Cannot continue. *//*---------------------------------------------------------------------*/Sysname_bad:SAY "ERROR IN INITIALIZATION OF "||userid||" VIRTUAL MACHINE: "SAY "CSE SYSTEM NAME "||sysid||" IS UNDEFINED IN THIS PROFILE."EXIT 999/*---------------------------------------------------------------------*//* User ID not recognized - Cannot continue. *//*---------------------------------------------------------------------*/Userid_bad:SAY "ERROR IN INITIALIZATION OF "||userid||" VIRTUAL MACHINE: "SAY "USER ID "||userid||" IS UNDEFINED IN THIS PROFILE."EXIT 998Figure 15. Example of a Pre-PROFILE EXEC (Part 2 of 2)Example of a Secondary Pre-PROFILE EXEC: Figure 16 is an example of asecondary pre-PROFILE EXEC for a four-system complex. This entry is appropriatefor the user ID OPERATOR on system SYSTEM1 defined in Figure 15 on page343./*--------------------------------------------------------------------*//* Secondary pre-PROFILE EXEC for OPERATOR on system SYSTEM1. *//* *//* The purpose of this EXEC is to link to and access the proper *//* R/W A disk for the above user ID and system. To tailor this *//* EXEC, perform the following 3 steps: *//* *//* 1). Modify the following CP LINK command to link to the *//* proper R/W A disk as defined in the single source directory *//* for the CSE complex. For SYSTEM2, SYSTEM3, and SYSTEM4, *//* make comparable changes. *//* *//**/’CP LINK * 204 204 MR’ /* System SYSTEM1 OPERATOR’s A disk *//* *//* 2). The following statement will retry the step if the link *//* was not obtained. *//* *//**/ IF rc 0 THEN DO;’CP SLEEP 5 SEC’; PUSH ’PROFILE’; EXIT; END /**//* *//* 3). Modify the following CP DETACH commands to detach the other *//* user’s R/W A disks that were also defined in the single *//* source directory entry for this user ID. These disks were *//* defined as multiaccess (MR) to eliminate the need for *//* passwords in this EXEC, and may have been linked R/W when *//* this user ID logged on. They belong to the same user ID on *//* another system, and must be detached from this one. Make *//* comparable changes for SYSTEM2, SYSTEM3, and SYSTEM4. *//* *//**/’CP DETACH 304’ /* System SYSTEM2 OPERATOR’s A disk *//**/’CP DETACH 404’ /* System SYSTEM3 OPERATOR’s A disk *//**/’CP DETACH 504’ /* System SYSTEM4 OPERATOR’s A disk *//*--------------------------------------------------------------------*/’RELEASE 191 (DET’ /* Detach the preliminary A disk. */’CP DEFINE 204 191’ /* Make the "real" A disk 191. */’ACCESS 191 A’ /* Make it the A disk. */’EXEC PROFILE’ /* Execute the "real" profile. */Figure 16. Secondary Pre-PROFILE EXEC for System1344 z/VM: CP Planning and Administration

Enabling CSEEnabling CSETo enable CSE:1. Create the single source directory (page 341).2. Install tapes (page 345):a. VM/Pass-Through Facility (Release 4 with modifications, or later)b. If using DIRMAINT, refer to the z/VM: Directory Maintenance FacilityCommands Reference book.3. Create or update the system configuration file (page 346). Add XLINK familystatements (and possibly XSPOOL family statements) to the systemconfiguration file for each system. Add SHARED operands to appropriateCP_OWNED statements.4. Initialize the volumes for linking (page 349):a. Generate the XLINK utility program.b. Initialize the CSE areas.Note: If you wish to initialize the CSE areas to something other than thedefaults, you must IPL the system prior to running XLINK format.5. Prepare the communication virtual machine (page 350).6. Perform an initial program load.7. Verify the cross system links (page 353).8. Optionally initialize cross system spool:a. Join the systems (page 353).b. Verify the cross system spool status (page 354).9. Phase CSE into the production environment (page 356).Installing the VM/Pass-Through Facility and Its ModificationsThe communication virtual machine (CVM) is the means by which the VM controlprograms communicate within a CSE complex. The CVM runs theVM/Pass-Through Facility licensed program.The CVM requires 3 MB for two systems plus 1 MB for each additional system inthe complex.To provide general functions of a pass-through virtual machine, you may use theCVM, or you may use a copy of the VM/Pass-Through Facility running in anothervirtual machine.If you use the CVM to provide general pass-through services and CSEcommunications, you can assign to it the customary user ID for the pass-throughvirtual machine, PVM. If you use a virtual machine other than the CVM to providegeneral pass-through services, you should give the user ID PVM to that virtualmachine and select another user ID for CVM.Specify the user ID of the CVM using the COMMUNICATIONS_USERID operand ofthe XSPOOL_SYSTEM statement (page 271). Install VM/Pass-Through FacilityVersion 2 Release 1.1 or later. Although the procedures include all the informationyou need, you must be aware of the layout of the CSE complex and may need tomodify:v The PVM CONFIG statementv The PROFILE PVM statementChapter 10. Setting Up Cross System Extensions (CSE) 345

Enabling CSEv The entry in the directory that defines the CVMv The PROFILE EXEC of the CVM.Defining CP for Each SystemNote: All systems in the CSE complex must run the same level of PVM.These modifications must be completed before the systems in the CSE complexcan communicate. Procedures for establishing communication are described under“Preparing the Communication Virtual Machine (CVM)” on page 350.System Definition for CSEIf CSE is not being used, system definition from the user’s point of view iscompletely unchanged. A default set of CSE tables that define a one-systemcomplex is generated automatically when the HCPSYS ASSEMBLE file isprocessed.Note: This is the only way that a one-system complex can be defined. If the XLINKor XSPOOL families of statements are used in a system configuration file,the CSE complex must be composed of at least two systems.If CSE is used, you must make the following entries in the system configuration file:v The CP_OWNED statement must be coded to identify each CP-owned volumethat will contain spool space that belongs to any associated system in the CSEcomplex.v XLINK_SYSTEM_INCLUDE statements are required.v The following statements are optional. They may be coded as needed for aparticular installation. (Notice that cross system spooling has been separatedfrom cross system linking; separate statements now control these functions.)XLINK_DEVICE_DEFAULTSmodifies certain attributes of the cross system link operation on adevice-type basis. (See page 259.)XLINK_SYSTEM_EXCLUDEidentifies a system to be excluded from the CSE complex. (See page263.)XLINK_VOLUME_INCLUDEidentifies which DASD volumes will be controlled by the cross system linkfeature of CSE. (See page 268.)XLINK_VOLUME_EXCLUDEidentifies which DASD volumes will be excluded from control by the (Seepage 266.) cross system link feature of CSE.XSPOOL_TRACEcontrols the number of free storage pages to be allocated and used forthe CSE trace tables. (See page 273.)XSPOOL_XLIST_INPUTidentifies certain virtual machines whose input files will not participate incross system spooling and cross system message and query commands.(See page 274.)346 z/VM: CP Planning and Administration

Enabling CSEXSPOOL_XLIST_OUTPUTidentifies certain virtual machines whose output files will not participate incross system spooling and cross system message and query commands.(See page 276.)CP_OWNED StatementsThe specific DASD volumes to be used for spool file space are described byCP_OWNED statements.Code CP_OWNED statements to define a list of up to 255 CP-owned DASDvolumes. CP-owned volumes are the CP system residence volume and volumesthat contain real system paging, spooling, dump, directory, or temporary disk space.When CSE is not used, all the volumes listed on CP_OWNED statements thatcontain spool space may be used to read and write spool files. (Spool files arewritten only once, when they are created.)When CSE is active, shared access to spool files for all systems in the complex isprovided by physically sharing the spooling DASD. Although physically this is bothread and write sharing, logically the sharing is on a read-only basis. Thus, somevolumes must be identified as available for writing the spool files created on thissystem, and others must be identified as available only for reading spool filescreated on other systems. To do this, specify the CP_OWNED operands OWN andSHARED as needed.Attention: It is recommended that the system residence volumes and pagingvolumes not be shared among systems in a CSE complex. If you share systemresidence and paging volumes, results are unpredictable.For the format and complete description of the CP_OWNED statement, refer to“CP_OWNED Statement” on page 73.Example of a System Configuration FileFigure 17 on page 348 shows portions of a system configuration file for afour-system complex that includes significant information for CSE.Chapter 10. Setting Up Cross System Extensions (CSE) 347

Enabling CSE/**********************************************************************//* Timezone Definitions *//**********************************************************************/Timezone_Definition EDT West 04.00.00/**********************************************************************//* Checkpoint and Warmstart Information *//**********************************************************************/System_Residence ,Checkpoint Volid KS3RES From Cylinder 2 For 2 ,Warmstart Volid KS3RES From Cylinder 4 For 2/**********************************************************************//* CP_Owned Volume Statements *//**********************************************************************/CP_Owned Slot 1 KS3RES OWNCP_Owned Slot 2 MD-SP0 ShareCP_Owned Slot 3 SPOOL0 ShareCP_Owned Slot 4 MD-SP1 ShareCP_Owned Slot 5 SPOOL1 ShareCP_Owned Slot 6 MD-SP2 OWNCP_Owned Slot 7 SPOOL2 OWNCP_Owned Slot 8 LDUMP0 ShareCP_Owned Slot 9 LDUMP1 ShareCP_Owned Slot 10 LDUMP2 OWNCP_Owned Slot 11 LDUMP3 Share/**********************************************************************//* System_Identifier Information *//**********************************************************************/System_Identifier_Default KEN3/**********************************************************************//* User_Volume_List *//**********************************************************************/User_Volume_List KLS191User_Volume_List CMS55User_Volume_List UTOOLSUser_Volume_List CMS195User_Volume_List XSPACEUser_Volume_List PVMDSKUser_Volume_List PVM191User_Volume_List TEMPUser_Volume_List MD-SP3Figure 17. Portions of a Configuration File for a CSE Four-System Complex (Part 1 of 2)348 z/VM: CP Planning and Administration

Enabling CSE/**********************************************************************//* XSPOOL_System Statements *//**********************************************************************/XSPOOL_System Slot 1 KEN1 Alias K1 ,Communications_Userid PVM Timeout 20 Seconds Share_Spool YesXSPOOL_System Slot 2 KEN2 Alias K2 ,Communications_Userid PVM Timeout 20 Seconds Share_Spool YesXSPOOL_System Slot 3 KEN3 Alias K3 ,Communications_Userid PVM Timeout 20 Seconds Share_Spool YesXSPOOL_System Slot 4 KEN4 Alias K4 ,Communications_Userid PVM Timeout 20 Seconds Share_Spool No/**********************************************************************//* XLINK_Volume_Include Information *//**********************************************************************/XLINK_Volume_Include MD1XLINK_Volume_Include MD2XLINK_Volume_Include MD3XLINK_Volume_Include MD-SP*/**********************************************************************//* XLINK_Volume_Exclude Information *//**********************************************************************/XLINK_Volume_Exclude MD-SP3/**********************************************************************//* XSPOOL_Userid_Input Information *//**********************************************************************/XSPOOL_Xlist_Input OPERATNS MAINT KEN IN/**********************************************************************//* XSPOOL_Userid_Output Information *//**********************************************************************/XSPOOL_Xlist_Output OPERATNS MAINT KEN OUT/**********************************************************************//* XLINK_Device_Defaults *//**********************************************************************/XLINK_Device_Defaults Type 3390 Class 3,Cylinder 300 Track 12 Map_Record_Length 203 Map_Records 2/**********************************************************************//* System Userids *//**********************************************************************/System_Userids ,Operator OPERATOR disconnect ,Dump OPERATNSFigure 17. Portions of a Configuration File for a CSE Four-System Complex (Part 2 of 2)Initializing the Volumes for Cross System LinkThe CSE area on each DASD volume contains link information about the minidiskon that volume. You need to format this area to prepare DASD for sharing.Generating the Cross System Link FacilityThe cross system link facility utility contains the XLINK DISPLAY and XLINKFORMAT commands. To ensure that the DASD parameters used by thesecommands are the same as those used by CP, you should generate a separateversion of XLINK for each system in the CSE complex. Use the following commandto generate the XLINK MODULE for each system:VMFBLD PPF ppfname compname HCPXLOAD XLINK (ALLChapter 10. Setting Up Cross System Extensions (CSE) 349

Enabling CSEppfnameis the name of the product parameter filecompnmameis the name of the componentSee the z/VM: VMSES/E Introduction and Reference book for information about theVMFBLD EXEC.Now that the XLINK MODULE has been generated, it may be used to format theCSE areas on the DASD volumes that cross system link will control. You mustformat the areas before the cross system link facility can be activated.Note: The XLINK MODULE should be placed on a nonshared minidisk of the userwho will enter the XLINK FORMAT or XLINK DISPLAY command from theCSE system.For more information about the XLINK FORMAT or XLINK DISPLAY commands,see the z/VM: CP Commands and Utilities Reference book.Initializing the CSE Area on Shared Minidisk VolumesTo initialize the CSE area on shared minidisk volumes:1. Connect the volume to be formatted to the virtual machine by one of thefollowing methods:a. LINK, in R/W mode–to link to a minidisk that defines a portion of the volumefrom cylinder 0 to where the CSE area is assigned. The default assignmentfor the CSE area is on cylinder 0. Since this method does not expose anydata beyond the CSE area, it is preferred.Note: The CSE area on some devices will reside on multiple cylinders. Ifyou are using one of those devices, your minidisk must include all ofthose cylinders. See Table 13 on page 365 for devices that usemultiple cylinders for the CSE area.b. ATTACH–to attach the real volume to the virtual machine.c. LINK, in R/W mode–to link to a minidisk that defines the entire real volume(a full-pack minidisk).2. Enter an XLINK FORMAT command that specifies the virtual address and thereal volume identification of the volume to be formatted. The volume label onthe disk must match the volume name given on the command. This command isrun under CMS. Therefore, it does not require that you have any special CPprivilege class. It does require, however, write access to the device as vdev.You should run XLINK FORMAT before you load the new CP module. However, ifyou wish to initialize the CSE areas to something other than the defaults, you mustIPL the system prior to running XLINK format.For the format, description, and responses of XLINK FORMAT, refer to the z/VM:CP Commands and Utilities Reference book.Preparing the Communication Virtual Machine (CVM)To establish proper connections between the CVM of one system in the CSEcomplex and the CVM of the other systems in the CSE complex, you need to definethe addresses of the channel-to-channel links that connect them.350 z/VM: CP Planning and Administration

Enabling CSENote: When using the 3088 Multisystem Channel Communications Unit, refer tothe VM/Pass-Through Facility library.Figure 18 shows an example that is based on channel-to-channel linking for afour-system complex.┌────────┐ vdev1 ┌────────┐│sysname1├─────────────────┤sysname2│└───┬─┬──┘└───┬─┬──┘│ │ vdev6 │ ││ └──────────────────────┐ │ │vdev3 │ │ │ │ vdev2│ vdev5 │ │ ││ ┌──────────────────────┼─┘ ││ │ │ │┌───┴─┴──┐ vdev4 ┌─┴───┴──┐│sysname3├─────────────────┤sysname4│└────────┘└────────┘Figure 18. Connecting the Communication Virtual MachinesFor the example shown in Figure 18, the directory entry for the CVM user ID shouldinclude:DEDICATE vdev1 rdev1DEDICATE vdev2 rdev2DEDICATE vdev3 rdev3DEDICATE vdev4 rdev4DEDICATE vdev5 rdev5DEDICATE vdev6 rdev6Modify the PVM CONFIG and PROFILE PVM from each system to include thenecessary statements.For the first system:v PVM CONFIG should include:LOCAL sysname1LANG AMENGLINK vdev1 sysname2 CTCALINK vdev3 sysname3 CTCALINK vdev6 sysname4 CTCAv PROFILE PVM should include:START LINE vdev1START LINE vdev3START LINE vdev6For the second system:v PVM CONFIG should include:LOCAL sysname2LANG AMENGLINK vdev1 sysname1 CTCALINK vdev5 sysname3 CTCALINK vdev2 sysname4 CTCAv PROFILE PVM should include:Chapter 10. Setting Up Cross System Extensions (CSE) 351

Enabling CSESTART LINE vdev1START LINE vdev2START LINE vdev5For the third system:v PVM CONFIG should include:LOCAL sysname3LANG AMENGLINK vdev3 sysname1 CTCALINK vdev5 sysname2 CTCALINK vdev4 sysname4 CTCAv PROFILE PVM should include:START LINE vdev3START LINE vdev4START LINE vdev5For the fourth system:v PVM CONFIG should include:LOCAL sysname4LANG AMENGLINK vdev6 sysname1 CTCALINK vdev2 sysname2 CTCALINK vdev4 sysname3 CTCAv PROFILE PVM should include:START LINE vdev2START LINE vdev4START LINE vdev6where (as shown in Figure 18 on page 351):sysname1is the name of the first system.sysname2is the name of the second system.sysname3is the name of the third system.sysname4is the name of the fourth system.vdev1 is the 1- to 3-character virtual device number of the channel-to-channel linkfor sysname1 and sysname2.vdev2 is the 1- to 3-character virtual device number of the channel-to-channel linkfor sysname2 and sysname4.vdev3 is the 1- to 3-character virtual device number of the channel-to-channel linkfor sysname1 and sysname3.vdev4 is the 1- to 3-character virtual device number of the channel-to-channel linkfor sysname3 and sysname4.352 z/VM: CP Planning and Administration

Enabling CSEvdev5 is the 1- to 3-character virtual device number of the channel-to-channel linkfor sysname2 and sysname3.vdev6 is the 1- to 3-character virtual device number of the channel-to-channel linkfor sysname1 and sysname4.rdev1 is the 1- to 4-character real device number of the channel-to-channel linkfor sysname1 and sysname2.rdev2 is the 1- to 4-character real device number of the channel-to-channel linkfor sysname2 and sysname4.rdev3 is the 1- to 4-character real device number of the channel-to-channel linkfor sysname1 and sysname3.rdev4 is the 1- to 4-character real device number of the channel-to-channel linkfor sysname3 and sysname4.rdev5 is the 1- to 4-character real device number of the channel-to-channel linkfor sysname2 and sysname3.rdev6 is the 1- to 4-character real device number of the channel-to-channel linkfor sysname1 and sysname4.For more information about routing, links, the START and DROP commands, and3088 connections, refer to the VM/Pass-Through Facility Managing and Using bookfor Release 4 of the VM/Pass-Through Facility.Verifying Your CSE Configuration1. IPL your z/VM system.2. Perform your installation’s customary verification testing.Verifying Cross System LinkUse the XLINK CHECK command when you want to know whether one or morevolumes are under cross system link control. You can execute this command afteryou have completed the IPL of the CSE system. For the format and a completedescription of this command, refer to the z/VM: CP Commands and UtilitiesReference book.Enabling Cross System SpoolStarting CSE CommunicationTo initialize CSE and bring it into full operation, you need to join each system toCSE by following these procedures:1. IPL the system and continue with initialization as described in the z/VM: CPCommands and Utilities Reference book.Note: Do not start the output spooling devices and do not enable userterminals now.2. XAUTOLOG the CVM.3. Use the SMSG command to inform the CVM to start the CSECOM task.CSECOM is the task that joins the systems together. Your installation may havean exec you can invoke to enter this command with fewer keystrokes.Use the START command to start a CSE communication task.Chapter 10. Setting Up Cross System Extensions (CSE) 353

Enabling CSE►► START CSEcom system ►◄CSEcomindicates that the CSE communication task is to be started.Note: To join any two systems in the CSE complex, the CSECOM task must bestarted from each of those systems specifying the system to be joined asthe target system.systemindicates the target system with which the session is to be initiated. The targetfor START CSECOM must be another CSE system.In the examples that follow, these are sysname1, sysname2, sysname3, andsysname4, which specify the names of the systems in the CSE complex definedin the system configuration file. In these examples, cvm is the user ID of thecommunication virtual machine as defined in the system configuration file.Example: The following is an example for the four-system complex shown inFigure 18 on page 351:1. From the first system, enter the following commands to join the appropriatesystems to the CSE complex:SMSG cvm START CSECOM sysname2SMSG cvm START CSECOM sysname3SMSG cvm START CSECOM sysname42. From the second system, enter the following commands to join the appropriatesystems to the CSE complex:SMSG cvm START CSECOM sysname1SMSG cvm START CSECOM sysname3SMSG cvm START CSECOM sysname43. From the third system, enter the following commands to join the appropriatesystems to the CSE complex:SMSG cvm START CSECOM sysname1SMSG cvm START CSECOM sysname2SMSG cvm START CSECOM sysname44. From the fourth system, enter the following commands to join the appropriatesystems to the CSE complex:SMSG cvm START CSECOM sysname1SMSG cvm START CSECOM sysname2SMSG cvm START CSECOM sysname35. After you have started the CSECOM task, enable the lines and terminals andthen start the output spooling devices, if any.Responses: The normal responses to a START CSECOM command are:DVMCSE0851I CSE sysnamex CONNECTED TO NODE sysnamey useridDVMCSE0853I SYSTEM sysnamex SYNCHRONIZED WITH SYSTEM sysnameyuseridVerifying Cross System SpoolUse the XSPOOL QUERY command to request system spool status.354 z/VM: CP Planning and Administration

Enabling CSE►► XSpool QueryALLsysnameNOMSG►◄sysnameis the name of the CSE system. If you specify a system name, the status of thatsystem is displayed.ALLdisplays the status of all the cross system spool systems. ALL is the default.NOMSGsuppresses the normal command response; however, any error messages aredisplayed.Responses: The normal response to the XSPOOL QUERY command is:HCPXXS2987I Associated system sysname is activeIf any of the systems is not active, the response for that system is:HCPXXS2982I Associated system sysname is not activeIf the CVM link used by CSE is not in operation, the response is:HCPXXS2980I The CSE Communication Virtual Machine is not activeNote: For a system to be listed as active, the CSECOM task must be started fromboth the system issuing the XSPOOL QUERY command and the systembeing queried.Activating Spool for Systems Not Active after Start CSECOMUse the following commands to activate cross system spool for systems that arelisted as not active after starting the CSECOM task for that system.The following is an example of how to activate the CVM in a four-system complex(shown in Figure 18 on page 351):1. From sysname1, enter the following commands for the systems that are notactive:smsg cvm drop line vdev1smsg cvm drop csecom sysname2smsg cvm start line vdev1smsg cvm start csecom sysname2smsg cvm drop line vdev3smsg cvm drop csecom sysname3smsg cvm start line vdev3smsg cvm start csecom sysname3smsg cvm drop line vdev6smsg cvm drop csecom sysname4smsg cvm start line vdev6smsg cvm start csecom sysname42. From sysname2, enter the following commands for the systems that are notactive:smsg cvm drop line vdev1smsg cvm drop csecom sysname1smsg cvm start line vdev1smsg cvm start csecom sysname1Chapter 10. Setting Up Cross System Extensions (CSE) 355

Enabling CSEsmsg cvm drop line vdev5smsg cvm drop csecom sysname3smsg cvm start line vdev5smsg cvm start csecom sysname3smsg cvm drop line vdev2smsg cvm drop csecom sysname4smsg cvm start line vdev2smsg cvm start csecom sysname43. From sysname3, enter the following commands for the systems that are notactive:smsg cvm drop line vdev3smsg cvm drop csecom sysname1smsg cvm start line vdev3smsg cvm start csecom sysname1smsg cvm drop line vdev5smsg cvm drop csecom sysname2smsg cvm start line vdev5smsg cvm start csecom sysname2smsg cvm drop line vdev4smsg cvm drop csecom sysname4smsg cvm start line vdev4smsg cvm start csecom sysname44. From sysname4, enter the following commands for the systems that are notactive:smsg cvm drop line vdev6smsg cvm drop csecom sysname1smsg cvm start line vdev6smsg cvm start csecom sysname1smsg cvm drop line vdev2smsg cvm drop csecom sysname2smsg cvm start line vdev2smsg cvm start csecom sysname2smsg cvm drop line vdev4smsg cvm drop csecom sysname3smsg cvm start line vdev4smsg cvm start csecom sysname3Note: If you find a problem using the START and DROP process and the lines arestill not active, you can use another method to activate cross system spool.To use this alternative method, use the CP FORCE command with the CVMuser ID and then re-XAUTOLOG each CVM user ID on all systems.Phasing CSE into the Production EnvironmentYou should introduce CSE into your environment in a manner that builds confidencein the stability of the complex before you create dependencies on its functions andcapabilities.The following steps may vary according to installation policy and experience:1. IPL one system in the complex but do not activate cross system link and spool.To keep from activating cross system link:v Do not start the CSECOM task of the communication virtual machine.v Do not bring any shared minidisk volumes online to the other systems in theCSE complex.356 z/VM: CP Planning and Administration

Enabling CSEv Ensure that the current non-CSE system has the same list of CP-ownedvolumes with dummy volumes replacing those volumes having the shareoption. (This list is from the CP_OWNED statements in the systemconfiguration file).2. When you have confidence in the stability of the system:a. IPL CP on each of the systems.b. Introduce the cross system link facility by bringing online all shared minidiskvolumes, after they have been formatted by the cross system link facilityutility program.c. Start the CSECOM task in the CVMs of all the systems in the CSE complexto initiate the cross system spool facility.Note: You may place the START CSECOM command in the PROFILE PVMfile on the CVM user ID at a later time.Networking Implications of CSEA single VM system may be a node in many different kinds of networks, all of whichrequire their own independent form of definition and control. CSE does notintroduce any new networking mechanism, but it does have an effect on thedefinition of network nodes. In general terms, the following kinds of networks aretypically found on VM systems:vvvRSCSPVMSNA.RSCS Networks: Users communicate with each other over an RSCS network byusing RSCS service virtual machines, and they communicate with these servicevirtual machines by means of spool files and the SMSG mechanism. Since both ofthese modes are supported across systems by CSE, an entire CSE complex mayappear as a single node on an RSCS network.Users can enter CMS commands such as SENDFILE and TELL to communicateconveniently with users on the same node or on different nodes in an RSCSnetwork. These commands and RSCS network communicating programs use theIDENTIFY command to determine the user ID of the RSCS virtual machine and theRSCS node name of the system on which they are operating. The source of thedata supplied by the IDENTIFY command is a CMS file, usually found on the Sdisk, named SYSTEM NETID. If your installation uses a single RSCS node, this fileis the same for all systems in the CSE complex. Commands and programs such asSENDFILE and TELL operate the same way in the complex as they do on a singlesystem.There is no systematic relationship between the RSCS node name (as specified inSYSTEM NETID) and any of the node name specifications of the other networkingmechanisms that may be in use, or any of the CSE complex system names.PVM Networks: PVM uses the logical device facility to allow users to log on tohost machines. Since this mode is not supported across a CSE complex, eachsystem in the complex appears to the PVM network as a single node. In otherwords, for PVM purposes the CSE complex does not exist.Network node definitions for PVM are in the PVM CONFIG file on the PVM servicemachine’s A disk. Again, there is no systematic relationship between the PVM nodename and any of the node name specifications of the other networkingChapter 10. Setting Up Cross System Extensions (CSE) 357

Enabling CSEmechanisms, or any of the CSE complex system names. It does make sense,however, to define the PVM node names for the systems in a CSE complex so thatthey are the same as their CSE system names.SNA Networks: VM/VTAM uses CP console services (CCS) to allow users to logon to host machines. Since this mode is not supported across a CSE complex,each system in the complex appears to the SNA network as a single node, and forSNA purposes the CSE complex does not exist.Network node definitions for SNA are contained in data files managed by VTAM andhave no systematic relationship with any of the node name specifications of othernetworking mechanisms or with any of the CSE complex system names. As in thecase of PVM, it makes sense to define the SNA node names for the systems in aCSE complex so that they are the same as their CSE system names.AdministeringCSEThis section is to help you manage CSE as part of your system resources. Theinformation describes the cross system link, the CSE area, and cross systemspooling.How Linking Works in z/VMThe unit of data control on z/VM systems is the minidisk. A minidisk is defined toCP by specifying in the CP directory the DASD volume on which it is located, thecylinder on which it starts, and the number of cylinders it encompasses. You shouldavoid defining minidisk extents that overlap.The CP directory controls access to all minidisks. The CP LINK command is themechanism by which virtual machines are connected to a particular minidisk.Access may be read-only (R/O) or read/write (R/W). A user with the necessaryauthorization may use stable read, stable write, exclusive read, or exclusive writeaccess.By linking to another user’s minidisk, users can share data, usually CMS files. Theaccess method that controls the updating of data on the minidisk is not part of CP,but runs in each user’s virtual machine. That access method does not support datasharing. Therefore, any updating of data on minidisks can result in read or writefailures or even data loss.When a link is requested, CP finds the status of existing links. It then grants ordenies the requested new link depending on CP link protocols. CP checks all linksto that same minidisk and all minidisks that overlap the cylinders of the requestedminidisk with these exceptions:v If you are requesting a full-pack minidisk, CP ignores any smaller minidisks thatmay be active on that same DASD.v If you are requesting a smaller-than-full-pack minidisk, CP ignores any full-packminidisks that may be active on that same DASD.Defining full-pack/smaller-than-full-pack minidisk overlap compromises the dataintegrity otherwise guaranteed by the stable and exclusive link access modes,because a full-pack minidisk can be exclusive write at the same time that a smallerminidisk on that same DASD is exclusive write. If you define such overlap, youassume responsibility for data integrity.358 z/VM: CP Planning and Administration

Administering CSEDASD RESERVE/RELEASE processing is not designed to handle overlappingminidisks and will issue a virtual reserve for each of the two overlapping minidisks.If you define such overlap, you assume responsibility for data integrity.To maintain data integrity you must control the use of the command DEFINEMDISK and of DIAGNOSE code X'E4' for full-pack overlay. These are two powerfulvariants of LINK which must be used carefully or not at all to maintain data integrity.How CSE Extends LinkingCross system link extends the CP LINK command. When multiple VM systems areconnected in a CSE complex, CP LINK protection includes all minidisks defined incommon across the CSE complex. Thus, users on any of these systems can enterLINK commands without regard to which system they are actually logged on to.From the general user’s point of view, cross system link functions in the samemanner that the current CP LINK command does and is therefore transparent.To record and interrogate the types of links outstanding on all interconnectedsystems, CSE uses channel programs that work with CKD DASD, including ECKDcapable CKD DASD. Cross system link does not work with fixed-block architecture(FBA) DASDs.The hardware facility reserve/release is not used.It is important that the CSE area not be updated inadvertently by any program otherthan CP. If you do not specify a particular location in the system configuration file,CSE initializes the CSE area starting on cylinder 0, track 1, when you enter theXLINK FORMAT command. This is described under “Generating the Cross SystemLink Facility” on page 349. Since CP keeps the volume label and allocation mapson cylinder 0, track 0, the default location for the CSE area should be available.Allocate the location you choose for the CSE area as PERM space with the DeviceSupport Facilities program (ICKDSF). The XLINK FORMAT command allows thesevolumes to be shared by assigning and formatting the CSE area.Note: For some device types, the CSE area resides on multiple cylinders. SeeTable 13 on page 365 describing the number of cylinders used for eachdevice. Be careful not to define user minidisks in the space reserved for theCSE area, except for the purpose described under “Generating the CrossSystem Link Facility” on page 349.Controlling Cross System LinkThe lists of shared and excluded volumes reside in the system configuration file.The list of shared volumes is in the XLINK_VOLUME_INCLUDE statements. Thelist of volumes to be excluded from sharing is in the XLINK_VOLUME_EXCLUDEstatements.The XLINK RESET command is provided to recover links and prevent lockouts ifone of the systems in the CSE complex fails. This should be used with the cautionsdescribed in the z/VM: CP Commands and Utilities Reference book.CSEAreaInformation about the state of current links is kept on special tracks (called the CSEarea) on each DASD volume being shared. To see these link indicators, use theXLINK DISPLAY command (see the z/VM: CMS Commands and Utilities Referencebook).Chapter 10. Setting Up Cross System Extensions (CSE) 359

Administering CSEThe CKD cross system link support uses a single track on each real DASD volumeto hold information about the status of links to each of the minidisks contained onthat volume. This information is contained in map records. There is one map recordfor each system in the complex and one byte in each map record for each cylinderon the volume. Since CKD minidisks always begin on a cylinder boundary, aparticular byte in a particular map record can represent the status of a particularsystem’s links to a particular minidisk on that real DASD volume. A single channelprogram is used to interrogate and update the map records for each link mode. SeeFigure 19 on page 362 for an example of the format of a CKD formatted CSE area,and see Figure 20 on page 363 for an example of map records for a CKD formattedCSE area.The ECKD cross system link support uses multiple tracks on each real DASDvolume to hold information about the status of links to each of the minidiskscontained on that volume. This information is contained in link records. There is onelink record for each system in the complex on each track and one half byte in eachlink record for each cylinder on the volume. Each link record is 256 bytes long andcontains link information for 512 cylinders. Multiple cylinders will be used if thenumber of tracks needed for the CSE area is greater than the number of tracks percylinder. For more details on the XLINK FORMAT command, see the z/VM: CPCommands and Utilities Reference book. A series of channel programs are used tointerrogate and update the link flag. See Figure 21 on page 363 for an example ofan ECKD-formatted CSE area, and Figure 22 on page 364 for an example of linkrecords for an ECKD-formatted CSE area.Each link state is signified by the following flags:v A NOLINK flag indicates that no links exist for the minidisk.v A READ flag indicates that read links exist for the minidisk, but write links do not.v A WRITE flag indicates that at least one write link, and possibly one or moreread links, exist for the minidisk.v A STABLE READ flag indicates that at least one stable read link, and possiblyone or more read links exist for the minidisk. No write links will be granted whilethe STABLE READ flag exists for the minidisk.v A STABLE WRITE flag indicates that one stable write link, and possibly one ormore read links exist for the minidisk. No write links will be granted while theSTABLE WRITE flag exists for the minidisk.v An EXCLUSIVE READ flag indicates that one exclusive read link exists for theminidisk. No links will be granted while the EXCLUSIVE READ flag exists for theminidisk.v An EXCLUSIVE WRITE flag indicates that one exclusive write link exists for theminidisk. No links will be granted while the EXCLUSIVE WRITE flag exists for theminidisk.To operate cross system link, the CSE area must be formatted properly. You canuse cross system link only with volumes that are currently attached to the systemby CP and that have been formatted by the cross system link facility utility (XLINKFORMAT command). Cross system link cannot support DASD that have not beenformatted by this program or that are attached to virtual machines.The cross system link facility utility writes the map records and other controlinformation on the CSE area of each volume. The cylinder containing the CSE areamust have been allocated as PERM space. Make sure that no user minidisks are360 z/VM: CP Planning and Administration

Administering CSEallocated on that cylinder. No program other than CP should have write access tothe CSE area of any volume attached to the system, lest it be inadvertentlychanged.Since the CSE area for each shared volume is on that volume, any damage to thevolume results in a loss of access to that volume only. A DASD hardware failure ona CSE complex has no greater impact than that on a single VM system withoutCSE.Location of the CSE AreaThe CSE area may be placed at any unused location on a volume. If no other areawas specified, CP uses the default location of cylinder 0, track 1, for the CSE area.CP keeps the volume label and allocation maps on cylinder 0, track 0. Therefore,the remaining tracks on cylinder 1 are available. Regardless of the location of theCSE area, it should be allocated as PERM space. For some device types, the CSEarea resides on multiple cylinders. See Table 13 on page 365 describing thenumber of cylinders used for each device.CSE needs to update information about links only when the first link to that minidiskoccurs, when a link higher than any other links to that minidisk occurs, or the lastlink of that type is detached. Thus, the first link to a minidisk causes the disk arm tomove to the CSE area, but subsequent links may not.To reduce the need for, and frequency of, input/output (I/O) to CSE areas, theprimary read-only (RR) link mode should be used in LINK commands and directorycontrol statements whenever possible. Since RR links are always granted once anynonexclusive link exists on a given system, CSE is not concerned with theinformation on the CSE area.If the disk arm does move, it moves to the CSE area, which defaults to track 1 ofcylinder 0. If a minidisk is frequently linked (more than once a second) in a modeother than RR, or if the type of access changes frequently from R/O to R/W, it maybe useful to move that minidisk as close to the CSE area as possible. This avoidslong seeks on every LINK command. Alternatively, the CSE area could be moved toa different position on the volume, closer to the high-usage minidisk.Protecting the CSE AreaTo protect the CSE areas from inadvertent assignment as user’s minidisk space, itmay be helpful to assign a NOLOG user ID to the cylinder on which the arearesides. Access to the cylinder containing the CSE area must be strictly controlled.Placing of the CSE AreaFigure 19 on page 362 illustrates the general format of a CKD-formatted CSE areain an n-system complex.Chapter 10. Setting Up Cross System Extensions (CSE) 361

Administering CSE┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌───────┐ ┌───────┐ ┌───────┐│ │ │ │ │ │ │ │ ││ │ ... │ │ │ │ │ │ ... │ │ │ │ │└──────┘ │ └──────┘ └──────┘ │ │└──────┘ └──────┘ │ │ └───────┘ └───────┘ │ └───────┘Header │ System 1 ... System n │ │System 1 System n │ │ │ ClearRecord │ │ │ │ │ │ Record│ │ │ │ │ ││ │ │ │ │ │└───────────────────────┘ └──────────────────────┘ └─────────────────────────┘Map Records Key Records Flag RecordsFigure 19. Format of a CKD-Formatted CSE Area for an n-System Complex1 Header Record Contains 240 bytes of cross system link generalinformation.n Map Records One record per system, each containing linkinformation for a cylinder on the volume. The lengthof the data area is greater than or equal to thenumber of cylinders on the volume.n Key Records One record per system, each containing 1 byte ofirrelevant information. The key area is used as acomparison argument.7 Flag Records Each record contains a byte representing NOLINK,READ, WRITE, STABLE READ, STABLE WRITE,EXCLUSIVE READ, or EXCLUSIVE WRITE linkflags.1 Clear Record Contains in all bytes NOLINK link flags. The lengthis the same as a map record.n is the number of map records on this track. The number of sharing systemscannot exceed this value. The recommended value for n is equal to themaximum track capacity. If it is necessary to change this value, use the RECS=operand on the XLINK_DEVICE_DEFAULTS statement (page“XLINK_DEVICE_DEFAULTS Statement” on page 259) and the CYLINDERoperand on the XLINK_VOLUME_INCLUDE statement (page“XLINK_VOLUME_INCLUDE Statement” on page 268).The number of map records used should equal the number of systems that yourCSE complex supports.Map records show the state of the existing links on the CSE systems. Figure 20 onpage 363 is an example.362 z/VM: CP Planning and Administration

Administering CSE┌──────────────────────────────────────────Byte │ 0 │1 │2Position │ 0 1 2 3 4 5 6 7 8 9│0 1 2 3 4 5 6 7 8 9│0└─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │Map record 1, for system1: 1 1 1 2 1 1 1 1 1 1 1 1 1 1 1 3 1 1 1 1 1 ...Map record 2, for system2: 1 1 1 1 1 1 5 1 1 1 1 1 1 1 1 3 1 1 1 1 1 ...Map record 3, for system3: 0 1 1 0 1 1 1 1 1 1 1 0 1 1 1 1 1 1 1 1 1 ...Map record 4, for system4: 4 1 1 1 1 1 1 1 1 1 1 2 1 1 1 1 1 1 1 6 1 ...0 is the READ flag.1 is the NOLINK flag.2 is the WRITE flag.3 is the STABLE READ flag.4 is the STABLE WRITE flag.5 is the EXCLUSIVE READ flag.6 is the EXCLUSIVE WRITE flag.Figure 20. Sample Map Records for a CKD-Formatted CSE Area for a Four-System ComplexThese map records show that:v System1 has write links to a minidisk beginning at cylinder 3 and stable readlinks to a minidisk beginning at cylinder 15.v System2 has an exclusive read link to a minidisk beginning at cylinder 6 andstable read links to a minidisk beginning at cylinder 15.v System3 has read links to minidisks beginning at cylinders 0, 3, and 11.v System4 has a stable write link to a minidisk beginning at cylinder 0, write linksto minidisks beginning at cylinder 11, and an exclusive write link to a minidiskbeginning at cylinder 19.Figure 21 illustrates the general format of an ECKD-formatted CSE area in ann-system complex.TRACK 1 ┌────────────┐│ │ Header Record└────────────┘───┐TRACK 2 ┌────────────┐ ┌────────────┐ ││ │ .... │ │ │└────────────┘ └────────────┘ │. System 1 System n │. │ LINK. │ RecordsTRACK i ┌────────────┐ ┌────────────┐ ││ │ .... │ │ │└────────────┘ └────────────┘ │System 1 System n ───┘Figure 21. Format of a CKD-Formatted CSE Area for an n-System Complex1 Header Record Contains 56 bytes of cross system link generalinformation.n*i LINK Records Of length 256 bytes. Contains link information for512 cylinders on the volume. Record X on track 2Chapter 10. Setting Up Cross System Extensions (CSE) 363

Administering CSErepresents cylinders 0–511 for system X. Record Xon track 3 represents cylinders 512–1023 forsystem X.n is the number of link records on each track, which is the number of systemsdefined as sharing minidisks with cross system link. If it is necessary to changethis value, use the RECS= operand on the XLINK_DEVICE_DEFAULTSstatement (page “XLINK_DEVICE_DEFAULTS Statement” on page 259) andthe MAP_RECORDS operand on the XLINK_VOLUME_INCLUDE statement(page “XLINK_VOLUME_INCLUDE Statement” on page 268).Note: For some devices, the CSE area does not fit on one cylinder so multiplecylinders are used. See Table 13 on page 365 describing the number ofcylinders used for each device.i is the number of tracks needed to hold link records with link information for atleast the number of cylinders on this volume. If it is necessary to change thisvalue, use the RECL= operand on the XLINK_DEVICE_DEFAULTS statement(page “XLINK_DEVICE_DEFAULTS Statement” on page 259) and theMAP_RECORD_LENGTH operand on the XLINK_VOLUME_INCLUDEstatement (page “XLINK_VOLUME_INCLUDE Statement” on page 268).Figure 22 is an example of link records for an ECKD-formatted CSE area.┌────────────────────────────────────────────Byte │ 0 │Position │ 0 1 2 3 4 5 6 7 8 9 │└─────┬───┬───┬───┬───┬───┬───┬───┬───┬──────│ │ │ │ │ │ │ │ │Link record 1, for system1: 0 0 0 4 0 0 0 0 0 0 0 0 0 0 0 2 0 0 0 0 ...Link record 2, for system2: 0 0 0 0 0 0 5 0 0 0 0 0 0 0 0 2 0 0 0 0 ...Link record 3, for system3: 1 0 0 1 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 ...Link record 4, for system4: 3 0 0 0 0 0 0 0 0 0 0 4 0 0 0 0 0 0 0 6 ...0 is the NOLINK flag.1 is the READ flag.4 is the WRITE flag.2 is the STABLE READ flag.3 is the STABLE WRITE flag.5 is the EXCLUSIVE READ flag.6 is the EXCLUSIVE WRITE flag.Figure 22. Sample Link Records for an ECKD-Formatted CSE Area for a Four-SystemComplexThese LINK records are on track 2 of the CSE area and show that:v System1 has write links to a minidisk beginning at cylinder 3 and stable readlinks to a minidisk beginning at cylinder 15.v System2 has an exclusive read link to a minidisk beginning at cylinder 6 andstable read links to a minidisk beginning at cylinder 15.v System3 has read links to minidisks beginning at cylinders 0, 3, and 11.v System4 has a stable write link to a minidisk beginning at cylinder 0, write linksto a minidisk beginning at cylinder 11, and an exclusive write link to a minidiskbeginning at cylinder 19.364 z/VM: CP Planning and Administration

Administering CSEDefault Values for the CSE Area: The defaults in the CSE system tables aresuch that the cross system link facility utility formats each volume with themaximum number of map records that can be recorded on 1 track forCKD-formatted DASDs. The same defaults are used for ECKD capable CKDDASDs even though the maximum number allowed is higher. Table 13 shows, bydevice type, the default number of map records, (which is also the number ofsystems that can be supported for cross system link) and the default map recordlengths.Table 13. Defaults for the CSE AreaDevice Type Number of MapRecords3330 (3350 in 3330compatibility mode)Map Record Length Number ofcylinders neededfor CSE area8 808 13340 4 696 13350 15 555 13375 12 959 13380 type K 8 2655 13380 non-type K 11 1770 13390-1 12 1113 13390-2 8 2226 13390-3 8 3339 13390-9 56 65520 99345-1 12 1440 19345-2 8 2156 1Other 8 1024 1Note: These defaults support CKD and ECKD capable CKD DASDs. FBA is not supported.The length of each map record is the maximum number of cylinders on any currentlyexisting model of that device type.Note: The NUMBER OF CYLINDERS NEEDED FOR CSE AREA is for ECKD-capableDASD only. If the last cylinder on the volume is specified for the CSE area and multiplecylinders are needed, the CSE area will not wrap to the beginning of the volume for theother CSE area cylinders.Eight records are defined for other devices, but the actual number of records usedis limited to the number that fit on a track of such other device.VM I/O Performance Measurement for Shared DASDThe z/VM: Performance book describes CP monitoring in detail. When you areusing CSE, the information received when you request seek domain monitoring maybe misleading. To measure use of a shared DASD accurately, you need to usehardware measuring methods.CP monitor can function on only one system; it cannot determine the effect thatrequests for shared DASD made by each system in a CSE complex have on thatdevice.Except for DASD performance, measuring performance within a CSE complex isthe same for the same systems operating independently.Chapter 10. Setting Up Cross System Extensions (CSE) 365

Administering CSEComplexes with 3380-13 and 3380-23 cache controllers installed should considersharing minidisks, even heavily used ones, by caching them. These cachecontrollers reduce mechanical I/O activity and therefore device contention that maybe caused by either cross-system or single-system activity.What Is Cross System Spool?Figures 23 through 25 show how cross system spool works in a four-systemcomplex.System1System2 System3 System4OriginalSpoolFileThe user:1. Logs on to system12. Creates a reader spool file on system1.Figure 23. Cross System Spool–Step 1366 z/VM: CP Planning and Administration

Administering CSESystem1OriginalSpoolFileSystem2 System3 System4CopySpoolFileBlockThe user:1. Logs off from system1.2. Logs on to system4. System1 sends system4 a copy of the spool file block fromthe original spool file.3. Sees the spool file as being on system4. The user can process the spool file.Figure 24. Cross System Spool–Step 2System1OriginalSpoolFileSystem2 System3 System4CopySpoolFile BlockDeletedThe user:1. Logs off from system42. Logs on to system13. Processes the reader spool file on system1 again.The copy of the spool file block on system4 is deleted.Figure 25. Cross System Spool–Step 3How CSE Extends SpoolingWith cross system spool, the CP spooling system can include up to four z/VMsystems connected in a CSE complex. The connection mechanism used requiresshared DASD hardware and a VM/Pass-Through Facility network.Chapter 10. Setting Up Cross System Extensions (CSE) 367

Administering CSEWithin the CSE complex, users have a single logical view of all their spool files.Spooling devices (such as printers) are still controlled by the spooling operatorlogged on to the system that physically controls those devices. Users logged on toone of these systems can access all of their spool files regardless of which systemthey have logged on to for that session. They can transfer these files to other usersor to service virtual machines anywhere in the CSE complex. They can selectprinters and other spool output devices for processing spool files created by anyuser in the CSE complex. Thus, end-user view of spooling is nearly transparent.Although the CP commands that manipulate spool files operate differently internally,additional user options or parameters are not required.Cross system spooling enables CP spooling functions on each system in thecomplex to manage and share spool files cooperatively. Because of this, when allthe systems are operating normally, there is little awareness of CSE and no specialmeasures are required either for users or for operators. For example, a printer poolthat might formerly have resided on one system and have been reached by userson other systems over a network connection appears local to each user, regardlessof which system in the CSE complex that user is on. The files to be printed appearto the spooling operator to be local to the system on which the printers are active.Operator intervention is required for proper handling of scheduled or unscheduledsystem outages.Cross system spool is concerned only with closed spool files and not with theallocation of CP spool space. Each system has its own set of spooling disks toallocate from exclusively. All other CP systems within the CSE complex have readand write access to these spool disks because they are on shared DASDs. Theseother systems, however, cannot allocate or release space on these volumes.The system on which a spool file is created owns the spool space. The spooldescriptor on the system where the file was created is called an original spooldescriptor. The identity of the originating system, the one that owns the spool spacethe file occupies, is kept in the spool descriptor. Another system may receive a copyof the original spool descriptor, which is known as a copy spool descriptor. Copyspool descriptors may be deleted by any of the sharing systems, but the actualreturning of spool file resources is performed by the originating system. Eachsystem has peer status. This means that each system has responsibility for itsoriginal spool descriptors and for keeping the other systems’ copy spool descriptorsup to date.CSE tries to minimize the number of copy spool descriptors by capitalizing on theinherent differences between input and output spool files. Output spool files must beavailable on all systems so that they can be handled by real printers or punches.Input spool files must be available only on the system where their owning user ID isactive.Because more users are involved, the number of spool file blocks in a CSEcomplex may easily exceed the number normally expected on a single system.Across the CSE complex, the total amount of main storage required for original andcopy spool file blocks increases each time a system receives a copy spool fileblock.z/VM Spooling Commands Extended by CSECross system spool extends the scope of the following CP commands to apply tospool files anywhere in the CSE complex:vvCHANGEORDER368 z/VM: CP Planning and Administration

Administering CSEvPURGEv QUERY FILESv QUERY { READER │ PRINTER │ PUNCH } ALTIDv QUERY { READER │ PRINTER │ PUNCH } XFERvvTAGTRANSFER.The syntax and operands of these commands are unchanged by CSE.CP spooling commands, such as PURGE and CHANGE, normally access only filesthat are not locked at all or that are locked by the system on which the commandwas entered. For example, suppose that the system on which a command has beenissued is referred to as systemA. Suppose that another system involved in theexecution of the command is referred to as systemB.Most spooling commands directly process only original spool files, that is, spool filescreated on systemA. Commands, such as TRANSFER and CHANGE, that try tomodify the status of copy spool descriptors are sent to the system that originatedthe spool file, systemB, for processing. (Copy spool descriptors are those createdby another system in the CSE complex.) These commands are executed onsystemB exactly as they were entered on systemA, as if the user had actuallyentered the command on systemB.A copy of the spooling command is sent to another system whenever a candidatespool file is found that is a copy of an original spool file owned by that system. Thisconcept reduces the amount of additional CSE processing necessary to process CPspooling commands across the CSE complex.The TAG and PURGE commands are exceptions. TAG information is not kept in thespool descriptor but is on a DASD. Also, all systems actually have shared R/Waccess to that DASD. Thus, systemA performs the command directly, whether it isthe originating system or not. PURGE does not modify the spool descriptor, butmerely obtains the file’s lock and deletes the file.SPOOL commands, such as SPOOL PRINTER HOLD, that refer to virtual devicesrather than to spool files are executed only on the system on which they areentered.Copy Input (Reader) Spool FilesWhen an original spool descriptor is closed and placed on the input queue and theowner is logged on to the same system, a copy spool descriptor is not sent toanother system. There is just one original spool descriptor for this spool file. If theowner is logged on to another system but is not logged on to the originatingsystem, a copy input spool descriptor is sent to the system that the user is currentlylogged on to. In this case, the original spool descriptor and one copy spooldescriptor exist. If the owner is not logged on, only the original spool descriptor onthe originating system exists.When a user logs on, all other systems in the CSE complex send a copy of anyavailable input (reader) spool descriptors owned by the user to the system wherethe user is logged on. A copy input spool descriptor exists on a system as long asthe owner remains logged on to that system, assuming nothing is done to changeits place in the input queue. When a user logs off, all copy input spool descriptorson that system will be deleted. Only the original spool descriptors remain on theoriginating system.Chapter 10. Setting Up Cross System Extensions (CSE) 369

Administering CSENote: If a reader spool file is being dumped to tape by the SPXTAPE DUMPcommand on the originating system, and the owner of the file is logged on toanother system in the CSE complex, there is no indication to the ownerduring the dump that the file is not available.Copy Output (Print and Punch) Spool FilesA copy spool descriptor is sent to all the other systems when an original spool file isadded to the output queue. The spool descriptor remains on each system until it isprocessed, purged, or transferred to the input queue. When a copy output spooldescriptor is transferred to the input queue and the owner is logged on to thesystem that initiated the transfer, the copy output spool descriptor becomes a copyinput spool descriptor and the original output spool descriptor becomes an originalinput spool descriptor. If the owner is not logged on to the system that originatedthe transfer, the copy output spool descriptor is deleted and the original outputspool descriptor becomes an original input spool descriptor.When a system receives a copy spool descriptor, it allocates the same spool ID forthe file as the original, or it does not allow the copy spool descriptor to remain onthis system. A file’s spool ID is always the same throughout the complex. Since anysystem can process an output spool file, whether the user is logged on or not,output spool files always exist on all the systems in the CSE complex.Spool File NumberingSee “Spool File Directory Statements” on page 341 for a description of how themaximum number of spool files is determined.Spool files for any given user are assigned spool ID numbers starting from 0001and proceeding to 9999, or to the MAXSPOOL limit if a SPOOLFILE statement wasspecified in that user’s directory entry. In a z/VM system without CSE, these spoolID numbers start at 1 and increment by 1 for each new spool file owned by thatuser. When CSE is installed, the increment and the initial value of the spool IDnumbers depend on the relative position of the system on which the spool file iscreated in the list of systems in the CSE complex. This is done so that no user hasmore than one spool file with any given spool ID number.If only two systems are in the CSE complex, spool files created on one system areassigned all the odd numbers from 0001 to MAXSPOOL, and those created on theother system are assigned all the even numbers in the same range. If threesystems are specified, spool ID numbers for spool files created on any system1start at 0001, on system2 at 0002, and on system3 at 0003. If four systems arespecified, spool ID numbers for spool files created on any system1 start at 0001, onsystem2 at 0002, on system3 at 0003, and on system4 at 0004.The number by which the spool ID number is incremented is the same as thenumber of systems in the complex. For example, in a two-system complex, 2 isadded to each spool ID number to create the next; in a three-system complex, 3 isadded to that number, and so on.Access to Spool FilesPrivileged users have access to all output spool files from any of the coupledsystems. Privileged users can access the reader files of other users only on thesystem where the owner is logged on and on the system having the original spooldescriptor.However, since privileged users need access only to the spool files that the systemcan process or to the input files that exist on their system, this is not a limitation.370 z/VM: CP Planning and Administration

VM/Pass-Through Facility Functions for Cross System SpoolThe VM/Pass-Through Facility is used to communicate among systems within theCSE complex. The virtual machine that runs the VM/Pass-Through Facility for thispurpose is called the communication virtual machine (CVM). The VM/Pass-ThroughFacility supports either binary synchronous communication (BSC) lines orchannel-to-channel adapters (CTCAs). Though CSE supports BSC for itsoperations, BSC lines are not recommended, because they are too slow.Each CVM is a VM/Pass-Through Facility virtual machine. There is a control task,CSECOM, in each CVM for each system within the CSE complex. When foursystems are connected and accessing each other’s spool files, three CSECOMtasks are started and active on each system. A CSECOM task may be started byan authorized VM/Pass-Through Facility user or as part of the VM/Pass-ThroughFacility virtual machine initialization.A CSECOM task:v Synchronizes spool filesv Communicates with CPv Sends data to, and receives data from, another CSECOM task.CP communicates with the VM/Pass-Through Facility virtual machine using theVirtual Machine Communication Facility (VMCF).Synchronization takes place:v Each time the CSECOM task starts upv When another system requests synchronizationAdministering CSEv When a CP spool command detects a problem requiring synchronization.CSE queues requests to be sent to the other systems, such as requests to lock,unlock, or delete spool files. The CSECOM task associated with a particular systemwithin the CSE complex is posted when a request item is queued to be sent to thatsystem. The CSECOM task reads the request and then sends it to the CSECOMtask on the other system. There the requests are received by the CSECOM task,passed to CP, and serviced.The VM/Pass-Through Facility virtual machine controls the CTCA line hardware thatconnects the systems. This minimizes the communication hardware necessary tocouple systems and allows the sharing of any existing hardware connection withother VM/Pass-Through Facility tasks. The VM/Pass-Through Facility virtualmachine handles the connection, reconnection, rerouting, and the other lineproblems associated with communication service.Spool Synchronization Request TracingCSE maintains a trace of requests to synchronize spool files among systems withinthe CSE complex. The trace entries record why the synchronization was requestedand which module caused it. A synchronization request can be lost because ofprogramming errors or hardware problems in the link between CVMs. The traceentries identify the source of the error.Multiple Concurrent Logon SessionsCSE prevents a user from logging on with the same user ID concurrently on morethan one system within the CSE complex. However, sometimes (primarily whenoperational and service virtual machines are involved) multiple concurrent logonsessions with the same user ID are useful. Excluding a user ID from cross systemChapter 10. Setting Up Cross System Extensions (CSE) 371

Administering CSEspooling is done using the XSPOOL_XLIST_INPUT statement (page 274) and theXSPOOL_XLIST_OUTPUT statement (page 276).The user IDs specified are excluded from cross system spooling but can log on tomultiple systems.Note: The lists of excluded user IDs must be the same for every system in theCSE complex.For information about creating a single source directory for a CSE complex, refer toz/VM: Directory Maintenance Facility Commands Reference.Preparing to Deal with OutagesIf the hardware of a system in the CSE complex should fail, both the users of thatsystem and other users throughout the CSE complex may be affected. If the outageis a long one, the option to continue service should be available by operating thefailed system’s software in a virtual machine on a remaining system.You should be aware that virtual operation makes spool files created on the downsystem available to all users of the CSE complex. For performance, during thisbackup mode of service, users should use and applications should run on, the othersystems within the CSE complex whenever that is practical.For each system in the CSE complex, an entry in the single source directory shouldbe created with the following information:v Full-pack minidisk definitions should be included for each volume in the list ofCP-owned volumes.v Full-pack minidisk definitions should be included for each volume containingminidisks required during the period of virtual operation. If the number of usersand applications supported during this period is limited, not all minidisk volumesmay be required.v DEDICATE directory control statements should be included for the realchannel-to-channel adapters (CTCAs) or IBM 3088 ports used to connect thedown hardware with the other systems within the CSE complex. If the realhardware is not available when virtual operation is required, virtual CTCAs canbe defined to connect the virtual system with its host. If more than two systemsare in the complex, you may have to change PVM CONFIG files of some CVMs.v Terminal definitions, as required, should be included if users are to be permittedto use the DIAL command to access this system from the host.The z/VM: System Operation book describes how to respond to outages.Returning to Non-CSE OperationIf you disable CSE from your complex, you must do the following:v Distribute spool files to their owners using RSCS or the SPXTAPE command.v Assign users to one particular system.v Duplicate the once-common source directory, and provide a copy for each of thenow separate systems.v If you are using DIRMAINT Release 5 to synchronize directories, define a servicevirtual machine using that program for each system.v Delete MDISK statements defining minidisks that will not exist on a particularsystem from that system’s user directory.372 z/VM: CP Planning and Administration

Chapter 11. Customizing the CP Message Function▌PI▐You can customize the CP message function for your installation by adding code tomodule HCPMSU, as described in this chapter. HCPMSU is an installation-wideexit.CP Exit 1210 is provided to allow that same tailoring of the system. If this exit pointis activated then the HCPMSU installation code will not be invoked. For moreinformation on CP Exit 1210, see the z/VM: CP Exit Customization book.HCPMSUModuleModule HCPMSU allows alteration of the following message function commands:MESSAGE, MSGNOH, SMSG, and WARNING. You can include code in thismodule to do any of the following:v Add further verificationv Change the format or context of the messagev Alter parameters that control the way the message is displayed on the screenv Process installation-defined message command options.HCPMSU is included in the CP module at system generation. Later, during systemoperation, when a user issues a message command, the CP message function callsHCPMSU before sending the formatted message to the designated receiver. If nocode has been added to HCPMSU, the module performs no meaningful function.HCPMSU contains one entry point, HCPMSUEX. Figure 26 provides an overview ofthe IBM-supplied HCPMSU module, showing the entry point and the area whereyou can add your own source code.COPY HCPOPTNSHCPMSU HCPPROLG ATTR=(RESIDENT),BASE=(R12)*COPY HCPEQUAT common system equatesCOPY HCPSAVBK savearea block*HCPMSUEX HCPENTER CALL,SAVE=DYNAMIC****************************************************************** Installation-supplied code can be inserted here.*****************************************************************SLR R15,R15 Set return code of 0MSUEXEND DS 0H Load regs and exitST R15,SAVER15 Store return codeL R11,SAVER11 Restore register 11HCPEXIT EP=HCPMSUEXHCPDROP R13*HCPEPILGFigure 26. Module HCPMSU OverviewHCPMSU has the following requirements and restrictions:1. HCPMSU is written in Assembler H coding language.© Copyright IBM Corp. 1991, 2004 373

Customizing Messages2. HCPPROLG, HCPENTER, HCPDROP, HCPEXIT, and HCPEPILG areIBM-supplied macros (in HCPPSI MACLIB) that must be preserved in HCPMSUand used only as shown.3. The attributes of HCPMSU must be REENTRANT and RESIDENT.4. Links and accesses from HCPMSU to other modules, data areas, and controlblocks are not supported.5. IBM reserves the right to modify the code associated with this exit. IBM willattempt to make any changes as transparent as possible to the customer.6. Upon entry to HCPMSUEX, register 13 points to a save area mapped byHCPSAVBK, shown in Figure 5 on page 312. The caller’s registers are saved inthe save area. A ten-fullword work area, beginning at label SAVEWRK, isavailable for use by installation-supplied code.7. Register 11, which points to the address of the dispatched VMDBK, andRegister 13, which points to the address of the save area, must not be modifiedby installation-supplied code.Entry Point HCPMSUEXEntry point HCPMSUEX supports installation modifications to the MESSAGE,MSGNOH, WARNING, and SMSG commands. If the specified receiver of amessage from one of these commands is logged on and has not turned off displayof that message type (using the SET MSG OFF, SET SMSG OFF, or SET WNGOFF command), the CP message function verifies and formats the message, setsup the proper sending parameters, and calls HCPMSUEX before sending themessage.The CP message function uses general-purpose register 1 for input to entry pointHCPMSUEX. Register 1 contains the address of a PLIST, which contains a list ofaddresses. Each fullword address points to a parameter being passed to themodule. See “Parameter Values.”Upon return to the CP message function from entry point HCPMSUEX,general-purpose register 15 must contain one of the following return codes:ValueMeaning0 Normal processing continues.nnnn An error was detected during HCPMSUEX exit processing. Theinstallation-defined return code nnnn can be in the range of 0001 to 9999. TheCP message function stops processing and issues the following message:HCPMFS6600E An error was detected by installation-wide exitHCPMSU — return code nnnn.See z/VM: System Messages and Codes - CP for further information on thismessage.Parameter ValuesGeneral-purpose register 1 contains the address of a PLIST that contains a list ofaddresses, each pointing to a parameter, as shown in the following figure.┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐R1 ──►│ addr. 1 │ addr. 2 │ addr. 3 │ addr. 4 │ addr. 5 │ addr. 6 │ addr. 7 │└────┬────┴────┬────┴────┬────┴────┬────┴────┬────┴────┬────┴────┬────┘ parm. 1 parm. 2 parm. 3 parm. 4 parm. 5 parm. 6 parm. 7The parameters contain the following values:374 z/VM: CP Planning and Administration

Customizing Messages1. The first 8 bits of this 32-bit field control the way the message is displayed.More than one bit may be set. You can change the settings to change the waythe message is displayed. The possible values are:ValueMeaningX'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 message isdisplayed.X'08______' This is a high-priority message and is displayedimmediately.X'04______'–X'______01' Reserved for IBM use.Note: If neither of the first two bits, which control the time stamp, are set, thereceiving user’s value is used. If both bits are set, a time stamp isappended.The supplied display values for the message commands are:Command Value MeaningMESSAGE X'B0' Time stamp is appended; message is highlighted;console alarm sounds.MSGNOH X'70' No time stamp is appended; message is highlighted;console alarm sounds.SMSG X'00' This type of message is not displayed.WARNING X'B8' Time stamp is appended; message is highlighted;console alarm sounds; message is high-priority,displayed immediately.2. This 32-bit field consists of three subfields:a. The first 8 bits indicate the type of message being processed. You canchange the setting to change the way the message is processed. Note thatif you change this setting, you might also need to change other parameters.The possible values are:ValueMeaningX'80' MESSAGE command processingX'40' MSGNOH command processingX'20' SMSG command processingX'10' WARNING command processingX'08'–X'01' Reserved for IBM useNote: If none of these bits are set, the message type defaults to MESSAGEcommand processing. If more than one bit is set, the messageprocessing is set to the type indicated by the first bit set.b. The next 8 bits indicate which IBM class commands the issuer of themessage is allowed to execute. More than one bit may be set. The settingsare dependent on the privilege class of the issuer of the message as well asthe privilege class of the command entered. This field is included forreference only. Changes made to this field do not affect the way thecommand is processed. The possible values are:Chapter 11. Customizing the CP Message Function 375

Customizing MessagesValueMeaningX'80' IBM class A commandsX'40' IBM class B commandsX'20' IBM class C commandsX'10' IBM class D commandsX'08' IBM class E commandsX'04' IBM class F commandsX'02' IBM class G commandsX'01' IBM class H commandsX'00' IBM class ANYc. The final 16 bits are reserved for IBM use.3. This 8-byte field contains the user ID of the issuer of the command. This field isincluded for reference only. Changes made to this field do not affect the way thecommand is processed.4. This 32-bit field contains the length of the message being processed. It includesthe length of any installation-defined option that has been specified. Changes tothis field might affect the way the message is displayed.5. This 32-bit field contains the address of the message being processed. Foreach type of message, the message buffer looks as follows:Message Type Buffer ContentsMESSAGE * MSG FROM userid : textMSGNOHtextSMSGtextWARNING * WNG FROM userid : textNote: The MESSAGE and WARNING messages always contain an initial blankand provide eight spaces for the user ID before the colon regardless ofthe actual length of the user ID.Following the text is 100 bytes of unused space which can be used to add to ormodify the existing text. If the length of the message is changed, the length fielddescribed above should be changed to reflect this or not all text will bedisplayed.You can change the address of the message (and also the length of themessage, if needed) for such purposes as, for example, pointing around themessage header so it is not displayed. However, when the CP messagefunction releases the storage it uses for the message, it releases the storagebased on the address passed to HCPMSUEX, not the updated value.6. This 8-byte field contains the user ID of the receiver of the message. If thevalue of the receiver’s user ID is changed, the message is sent to the newreceiver. However, if an error message is issued during normalmessage-function processing, and the error message includes the receiver’suser ID, the user ID used in the error message is the one that was passed toHCPMSUEX, not the changed value.7. This 32-bit field contains the length of the header for the message beingprocessed. Each message is made up of a header and a text portion. Theheader includes the header information and the blank delimiter which precedesthe text.The header length is used by the message processing function when messagesare sent across the *MSG, *MSGALL, and VMCF services. Only the text of the376 z/VM: CP Planning and Administration

Customizing Messagesmessage is sent. The header is discarded. The header length allows themessage function to determine where the message text begins.Each message type is considered to have a header. For MESSAGE andWARNING types, the header length on entry to HCPMSUEX is 22 characterslong. For MSGNOH and SMSG, the header length on entry to HCPMSUEX is 0characters long.The header can be increased or decreased by this exit or by later messageprocessing (for example, when a time stamp is added). SMSG never transmitsthe header while the other types display a header at the terminal if one ispresent.Changing and Adding to the CP Message FunctionThere are two categories of CP message command modifications:v A global change is one that takes effect each time the command is used.v A local change is an installation-defined command option, which takes effect onlywhen the option is used. If you define a new option, you determine where youwant the option to appear in the command string. For example:MESSAGE userid option textThe CP message function processes the option as part of the text and passes itto HCPMSUEX as such.┌──────────────────────────────────┐ ┌──────────────────────────────────┐│ Message Command Processor │ ┌►│ HCPMSUEX │├──────────────────────────────────┤ │ ├──────────────────────────────────┤│ Do normal processing │ │ │ Check for installation-defined ││ Set up the parameters for the │ │ │ option and process accordingly ││ exit call (values set depend │ │ │ Modify parameters as needed, ││ on the message type) │ │ │ such as: ││ Call HCPMSUEX to allow │ │ │ - change values of parameters ││ installation modifications │─┘ │ - modify the message format ││ If return code is > 0, issue │◄┐ │ - set appropriate return code ││ error message and exit │ │ │ Return ││ Otherwise send the message │ │ └──────────────────────────────────┘│ to the receiver │ │ ││ Return │ └───┘└──────────────────────────────────┘Figure 27. Flow of CP Message Function CustomizationFigure 27 illustrates the process of customizing the CP message function. Thisprocess is described in the following steps:1. The message command processor sets up the parameters for the exit call.General-purpose register 1 contains the address of a PLIST that contains a listof addresses, each pointing to a parameter. Parameter values depend on themessage type.2. The message command processor calls entry point HCPMSUEX:a. If you have defined a new message command option, add code toHCPMSUEX to parse the option from the message text and process itaccordingly.b. Add code to HCPMSUEX to do your global modifications. The processingrequired might depend on the values of the parameters passed toHCPMSUEX, which are dependent on the type of message beingChapter 11. Customizing the CP Message Function 377

Customizing Messagesprocessed. You can change these values, reformat the message, and doadditional verification. See “Parameter Values” on page 374 for a descriptionof each field and possible values.c. Set the appropriate return code in general-purpose register 15.d. Return to the message command processor.3. If general-purpose register 15 is zero, the message is sent to the receiver.4. If general-purpose register 15 is nonzero, the message is not sent to thereceiver and error message 6600E is issued.▌PIend▐378 z/VM: CP Planning and Administration

Chapter 12. Security and Integrity in z/VMProtection against attempts to breach the security of your system and againstinadvertently compromising the integrity of your system and data should be part ofthe planning and administration for your z/VM system. z/VM has built-in facilitiesand support for products to aid you in this task. This chapter gives you some pointsto consider and recommendations to follow that will help you to improve yoursystem security and integrity. In particular, this chapter discusses:v IBM software products available to enhance the security and integrity of yourz/VM systemv Points and recommendations to consider in enhancing the security and integrityof your z/VM systemv z/VM facilities available for detecting and foiling attempts to break systemsecurityv Considerations for maintaining system integrity.Note that these recommendations are optional and whether you follow themdepends on the level of security that your installation requires.Security-EnhancingProductsThe following IBM software products supported by z/VM can be used to enhancethe security and integrity of your system:v Resource Access Control Facility (RACF) for VMv Directory Maintenance licensed program (DIRMAINT)v Interactive System Productivity Facility (ISPF)Resource Access Control Facility (RACF) for VM:v Helps your installation implement its security policyv Identifies and authenticates each userv Controls each user’s access to sensitive datav Logs and reports events that are relevant to the system’s security.For detailed information on RACF for VM, see the following manuals:RACF General InformationSystem Programming Library: RACFRACF Command Language ReferenceRACF Security Administrator’s GuideRACF Auditor’s GuideRACF Diagnosis GuideDirectory Maintenance Licensed Program (DIRMAINT):DIRMAINT provides a safe, efficient, and interactive way to maintain the z/VM userdirectory. You can manage the directory with DIRMAINT through the use of itscommands. Thus, with DIRMAINT, you avert errors that are often made duringdirect updating of the directory source file. You can also use DIRMAINT to auditsecurity of relevant tasks that it performs.Interactive System Productivity Facility (ISPF):© Copyright IBM Corp. 1991, 2004 379

Security and Integrity in z/VMISPF manages interactive applications and provides services to them. It does thisby controlling the interactions of a dialog. In z/VM, it can be used to manageDIRMAINT and RACF dialogs.Security Considerations and GuidelinesTo enhance the security and integrity of your z/VM system, consider the followingpoints and recommendations:v Limit access to READ/WRITE saved segments.v Between the time you initialize z/VM and the time you initialize RACF/VM, thereis a lapse in security. In particular, the OPERATOR and AUTOLOG1 virtualmachines run totally unrestrained and without audit. To prevent anyone fromtaking advantage of this, take the following precautions:– Initialize RACF/VM immediately after you initialize z/VM.– Make sure that AUTOLOG1 enables only the RACF service virtual machineand no other. Any other virtual machine that must be autologged can beenabled by AUTOLOG2 (for example, the DATAMOVR virtual machine, whichis part of DIRMAINT).– Do not enable general-use console terminals until after you install andinitialize RACF/VM. Enable only the system console and keep it under strictphysical security.– Do not perform any major tasks until you install and initialize RACF/VM.v Use the AUTOLOG function to log on the DATAMOVR virtual machine. When aminidisk is detached by its owner, it still contains data the owner placed on it.Before you reallocate the same minidisk space to another user, this residual datashould be removed. The DATAMOVR virtual machine automates this process.Make sure that the DATAMOVR virtual machine is logged on whenever z/VM isinitialized. Place the CP AUTOLOG command for DATAMOVR in the PROFILEEXEC of the AUTOLOG2 virtual machine.v Limit and audit access to the system and logo configuration files.v Limit and audit access to the parm disk and all CP-accessed disks. Use of thesedisks should be limited to system administrators or system programmers. If theminidisk is simply integrated into the administrator’s or programmer’s virtualmachine, no auditing is possible. One way to audit the disks is to place them in avirtual machine whose user ID is NOLOG. This forces the administrator to usethe CP LINK command—an auditable and controllable event—to access thedisks. You can also restrict access and control auditing using an external securitymanager, like RACF.v Format any space before converting it to minidisk space. If you convert DASDspace (such as spool space, temporary disk space, or paging space) topermanent minidisk space, you should clear the entire space of all data. Thisprevents a new owner of the space from seeing any residual data left by theformer owner. Use the CP FORMAT command to do this.v Avoid DIAGNOSE code X'98'. DIAGNOSE code X'98' lets an authorized virtualmachine lock and unlock virtual pages in storage. It also lets the virtual machineexecute its own real channel programs. Thus, the virtual machine could inspectand alter CP or some other virtual machine. Because DIAGNOSE code X'98' issuch a powerful function, you should take the following precautions:– Audit the use of DIAGNOSE X'98'– Remove the DIAG98 operand from the OPTION statement of any user’sdirectory entry unless it is really necessary for the virtual machine to use thisfunction.380 z/VM: CP Planning and Administration

Security and Integrity in z/VMv Limit and audit the use of DIAGNOSE code X'08'. DIAGNOSE code X'08' lets anauthorized virtual machine issue a CP command from a program. In some cases,multiple CP commands can be imbedded in what appears to be a single CPcommand when the commands are separated by X'15' characters. You shouldtake the following precautions:– Add the D8ONECMD directory statement to the directory entries for servervirtual machines. With this statement, any time a server virtual machine issuesa single CP command that contains imbedded CP commands, the activity canbe logged, rejected, or no action taken (the default).– Audit the use of DIAGNOSE X'08' using the SET D8ONECMD command. Thisauditing, however, can result in many audit records and degrade systemperformance.v Avoid directly accessing the z/VM user directory. A user who has acquired theauthorization can directly access the user directory source file and modify it.Without the DIRMAINT product, this is the only way to maintain the directory.Manually updating the z/VM user directory could compromise system securityand integrity.Do not let any user directly access the z/VM user directory source file. WithDIRMAINT and RACF installed, the only safe, legitimate way for an administratorto modify this file is by using dual registration (see the next recommendation).v Use dual registration, an interface between DIRMAINT and RACF, to add, modify,or delete a user entry in the z/VM user directory and in the RACF/VM databasewith one transaction.When you delete a user from the system using dual registration, take specialcare. Dual registration deletes the user ID from the z/VM user directory and fromthe main RACF database. It does not, however, delete all occurrences of theindividual’s user ID or associations with RACF groups. You must deal with theseseparately, according to instructions in System Programming Library: RACF. Usethe ICHUT100 utility program to identify and locate all occurrences of the user IDin the RACF database.The XEDIT option must be in effect with dual registration.v Limit DIRMAINT privileged users. Strictly limit the number of user IDs you list inthe DIRMAINT DIRM_STAFF installation option. The users you list here canenter DIRMAINT privileged commands.v Limit access to the DIRMAINT LOG. The DIRMAINT LOG, also known as theDIRMAINT history file, is a time-stamped, sequential listing of DIRMAINTcommands entered against the z/VM user directory and the results of certainother DIRMAINT procedures. This file contains an audit record of everysignificant change made to the z/VM user directory and to the DIRMAINT virtualmachine. Thus, it is a very sensitive file.Also, a system administrator can record a message or note in the history fileusing the DIRMAINT LOGMSG command. This can be quite useful, but, in thewrong hands, it could introduce erroneous or deliberately misleading informationinto the history file.To limit the number of users with access to the DIRMAINT LOG, limit the numberof user IDs you associate with the DIRM_STAFF option in the DIRMAINT DATAfile. Only a user listed on this option can enter the DIRMAINT LOGMSGcommand.Note: Each use of the DIRMAINT LOGMSG command appears in theDIRMAINT audit trail.v Restrict the use of the single console image facility (SCIF). Also, restrict the useof the CP SET SECUSER command. See the z/VM: CP Commands and UtilitiesChapter 12. Security and Integrity in z/VM 381

Security and Integrity in z/VMReference for information about the CP SET SECUSER command. This facilityallows a virtual machine to control several other disconnected virtual machinessimultaneously.v Consider disabling the use of the DIAL and MESSAGE commands before logon.RACF/VM can be used to disable these commands. See the RACF CommandLanguage Reference book for more information. When DIAL and MESSAGEhave been disabled before logon, any user attempting to use them before logonwill receive an error message. Some things to consider when deciding whether ornot to disable these commands before logon are your site’s use of DIAL to get tosecond level systems and the amount of accountability your site desires for thesending of messages.v Restrict and audit full-pack minidisks. Full-pack minidisks that overlay otherindividual minidisks should be given only to system administrators. Their useshould be one of the audited privileges of an administrator. However, if theminidisk is simply integrated into the administrator’s virtual machine, no auditingis possible.One way to audit a full-pack minidisk is to place it in a virtual machine whoseuser ID is NOLOG. This forces the administrator to use the LINK command—anauditable and controllable event—to access the minidisk.You should also audit the DIAGNOSE code X'E4', the full-pack minidisk overlayfunction. If you have RACF installed, the resource name DIAG0E4 must beidentified to RACF to authorize the protected functions of DIAGNOSE code X'E4'.Users may request information about their own minidisks without RACFauthorization.v Clear all tapes and DASD areas before reassignment. You should set rules thatgovern the reassignment of tapes and DASD space. For example, minidisks andtemporary disks should be reformatted and tapes erased. (Note that temporarydisks can be cleared automatically—see “Clearing Temporary Disk Space” onpage 384.)v Audit the OVERRIDE utility. The OVERRIDE utility lets you restructure privilegeclasses. The privilege class structure defines the subset of CP commands andDIAGNOSE code functions that each user is allowed to enter. Installations mayneed to modify the privilege class system to accommodate local needs. Theability to modify the privilege class structure is important and highly sensitive.When the audit flag is set for DIAGNOSE code X'C4', an audit record is madewhen a user tries to restructure privilege classes.v Limit and audit the use of the SET PRIVCLASS command. The SET PRIVCLASScommand lets you control future SET PRIVCLASS commands or to temporarilychange the set of privilege classes for a logged-on user. The ability todynamically change privilege classes is important and highly sensitive, therefore,you should limit the number of people that you allow to issue this command. Thiscommand can be issued only if the FEATURES ENABLE SET_PRIVCLASSstatement has been specified in the system configuration file.v Restrict the system operator. Certain restrictions on the system operator canincrease system security; for example:– Ensure a high level of physical security over the IPL system console for theprocessor. Also, use the programmable operator facility to control what thesystem operator can do at this console and what the system does for thesystem operator. The programmable operator facility can increase theefficiency and security of your operations by intercepting all messages andrequests directed to the system operator and by handling them according tothe rules you have established. For more information on the programmableoperator facility, see the z/VM: CMS Planning and Administration.382 z/VM: CP Planning and Administration

Security and Integrity in z/VMz/VM Security Facilities– Make sure the system operator is aware that DASD areas and tapes must becleared before they are assigned to new owners.v With the ability to define the command access to suit your installation’s securityand system integrity requirements, you have great flexibility and control overeach user’s access to CP commands. You can use this to enhance security andsystem integrity at your installation by restricting access to system resources andinformation controlled by commands, DIAGNOSE codes, or system functions.The CP configuration statement USER_DEFAULTS with the POSIXOPT ofquerying the database has a default of ALLOW. If you do not want to allowothers to query the database you will need to change this setting. However, whenyou change the privilege class of commands and make changes to user access,be careful not to inadvertently compromise security or system integrity byallowing users to use commands that could provide access to unauthorizedinformation or that could affect system operation.z/VM facilities for detecting and foiling attempts to break system security and fordetecting and preventing integrity exposures are:v An interface which allows installation of an external security manager (ESM) toperform the following functions:– Auditing of commands, diagnose codes, and security-relevant systemfunctions– Protection of selected commands, diagnoses, and system function– Disabling the DIAL and MESSAGE command before logon.– Authorizing access to POSIX database and the information it containsv Storage access verification functions.v The ability to provide automatic clearing of temporary disks after use to preventthe current user from accessing data left from a previous user of the temporarydisk, with the ENABLE CLEAR_TDISK operand on the FEATURES systemconfiguration file statement.v The ability to bypass directory password authorization.v Journaling that allows you to monitor, record, and act on possible attempts togain unauthorized access to system resources.v Automatic deactivation of passwords that keeps restricted passwords from beingassembled in the object directory.v The ability to grant a virtual machine authority to restrict temporarily link accessto minidisks by other users.v The ability to suppress the display of passwords entered as part of the LOGONand LINK commands.v The ability for multiple virtual machines to gain cryptographic capability by usingan Integrated Cryptographic Facility (an optional hardware feature).In addition to the above facilities, the CMS shared file system includes various kindsof authority checking. Users can, for example, grant and revoke authority on theirfiles and directories. When a user tries to use a file or directory, the shared filesystem checks whether the user is authorized to do so. More information aboutshared file system security can be found in the z/VM: CMS File Pool Planning,Administration, and Operation book.Chapter 12. Security and Integrity in z/VM 383

Security and Integrity in z/VMUsing an External Security Manager for Auditing and ProtectingAn external security manager (ESM) is a service virtual machine used to maintainVM/ESA security and integrity. An IBM application you can use for this purpose isRACF/VM. CP can call upon RACF not only to protect certain system resources butalso to audit security-relevant events such as CP commands, DIAGNOSE codefunctions, and communication among virtual machines.Although all events can be audited, not all events will be audited. They are auditedonly if you choose. Use RACF to specify which of those events, if any, you care toaudit. Any audit task involves longer path lengths, substantial input and output, andheavy use of DASD. Thus, auditing tends to degrade performance of the system.For performance considerations, do not audit more events than necessary.RACF also provides various forms of authorization control for a subset of CPcommands and DIAGNOSE codes. For additional information on using RACF/VM toaudit and control CP commands, see the RACF Security Administrator’s Guide andthe RACF Auditor’s Guide.If you choose not to use RACF but want to write your own security application, youcan use this interface to provide your own auditing. For details on DIAGNOSE codeX'A0', see the z/VM: CP Programming Services book.Verifying Storage AccessMany CP functions allow a user to access the user’s own virtual storage. z/VM hasfunctions that prevent such an access from straying outside the space the user isentitled to. Whenever a user invokes one of these CP functions that checks user’sauthority, for example, IUCV DECLARE BUFFER or DIAGNOSE code X'A0', CPchecks whether that user is entitled to access the storage area assigned to thebuffer. CP prevents the requested buffer from overlaying any area in which the userhas no authority. For example, the space may be protected because it is alreadyoccupied by a CMS module. If the requested buffer is in storage-protected space,the user receives a protection exception.For additional information on the DIAGNOSE codes and the IUCV DECLAREBUFFER function, see the z/VM: CP Programming Services book.Clearing Temporary Disk SpaceIn some previous VM systems, CP cleared only cylinder 0, track 0, of a temporarydisk before allocating temporary disk space. As a result, data owned by theprevious user was available to the current user of the temporary disk. This createda data integrity exposure. With z/VM, temporary disk space can be optionallycleared completely to avoid this integrity exposure.To eliminate user access to sensitive data remaining on a temporary disk, use theCLEAR_TDISK operand on the FEATURES system configuration file statement orthe SYSCLR operand of the SYSRES macroinstruction to specify whethertemporary disk space is to be cleared. If space is to be cleared, it is cleared at thefollowing times:v at IPL time,v when CP volumes that contain temporary disk space are attached to the system,orv when a temporary disk is detached from a user384 z/VM: CP Planning and Administration

Security and Integrity in z/VMif the ENABLE CLEAR_TDISK operand is specified on the FEATURES systemconfiguration file statement. Or, see “SYSRES (Required)” on page 693 foradditional information on the SYSCLR operand of the SYSRES macroinstruction.Class B system resource operators can query the state of temporary disk clearingby using QUERY TDISKCLR. See z/VM: CP Commands and Utilities Reference foradditional details on the purpose and syntax of the QUERY TDISKCLR command.Note: If I/O errors occur during clearing of the DASD cylinders, the cylinders notcleared are not marked available for temporary disk space. This prevents theallocation of TDISK space that has not been cleared.Compatibility Note: z/VM temporary disk clearing is not compatible with VM/SPHPO temporary disk clearing. VM/SP HPO clears temporary disks only duringDEFINE TDISK and issues messages to the user during the clearing. z/VM clearstemporary disks during IPL, attach to system, and DETACH TDISK. Messages areissued only when CP volumes that contain temporary disk space are attached tothe system.Performance Note: Because clearing takes place asynchronously, a period of timemay elapse before the actual clearing occurs. The clearing of temporary disk spacehappens independently of the tasks that require it. Thus, it does not specificallyaffect these tasks, such as IPL, except for contention for the processor and I/O.There should be no significant impact on performance. Nevertheless, the spacemay not be immediately available.Permitting Bypassing of Directory Password AuthorizationWith z/VM, you can bypass directory password authorization to allow speciallydesignated virtual machines to:v Link to any other virtual machine’s virtual DASD without performance of minidiskpassword authorizationv Use a subset of the DIAGNOSE X'84' subfunctions to update a user’s directoryentry without performance of logon password authorization.To provide one or both of these functions to a virtual machine, code either or bothof the LNKNOPAS and D84NOPAS operands on the OPTION directory statement ofthe virtual machine’s directory entry. For additional information on these operands ofthe OPTION statement, see “OPTION Directory Control Statement (General)” onpage 533.Journaling the LOGON, AUTOLOG, XAUTOLOG, and LINK CommandsLOGON, AUTOLOG, XAUTOLOG, and LINK journaling detects and records certainoccurrences of the LOGON, AUTOLOG, XAUTOLOG, and LINK commands. Usingthe recorded information, you can identify attempts to log on to CP by users whoenter invalid passwords. Also, you can identify any user who successfully enters theLINK command to a protected minidisk that user does not own.Briefly, LOGON, AUTOLOG, XAUTOLOG, and LINK journaling works like this. Whilejournaling is turned on, CP monitors all occurrences of the LOGON, AUTOLOG,XAUTOLOG, and LINK commands. CP counts how many times a user enters oneof these commands with an invalid password. CP can be set to take one or more ofthese actions when the count reaches a threshold value:v Write a record to the accounting data set to record the incidentChapter 12. Security and Integrity in z/VM 385

Security and Integrity in z/VMv Reject subsequent LOGON, AUTOLOG, XAUTOLOG, and LINK commandsentered by the userv Lock that terminal for a designated periodv Send a message to a designated user ID to alert the installation to the incident.While journaling is turned on, CP creates an accounting record each time it detectsthat a user has successfully entered a LINK command to a protected minidisk notowned by that user. A protected minidisk is a minidisk whose password is anythingbut ALL for the type of LINK attempted, or a minidisk protected by an externalsecurity manager.For a description of the accounting records that CP writes for LOGON, AUTOLOG,XAUTOLOG, and LINK journaling, see “Accounting Record Formats” on page 299.To make LOGON, AUTOLOG, XAUTOLOG, and LINK journaling available and tospecify options, you may use the JOURNALING statement in the systemconfiguration file. For more information, see “JOURNALING Statement” on page160. For instructions on how to code this macroinstruction, see “SYSJRL (Optional)”on page 682. To turn journaling on or off, use the class A SET command. Todetermine whether journaling is on or off, use the class A or C QUERY command.For additional information on these commands, see z/VM: CP Commands andUtilities Reference.Automatic Deactivation of Restricted PasswordsA facility is available to validate user logon passwords against a set of predefinedrestricted passwords. The facility automatically validates other user passwords toprevent the accidental use of a restricted (published) password for or by a user. Itprovides a file that contains a list of IBM restricted passwords. This list, called theRPWLIST DATA, is a CMS file that is included on MAINT 2C2. When you run theDIRECTXA command to convert the source directory to an object directory,passwords are checked against the passwords in this list. You do not need toperform any action to use this list.You may add your own restricted passwords to this list or remove some of theIBM-restricted passwords from the list as the need arises. To modify the RPWLISTDATA file, you simply edit it and create a private copy to be kept with the sourcedirectory. You can find this file by using the CMS search order.You must use the following formatting rules when you edit the RPWLIST DATA file:v The RPWLIST DATA file must have a fixed-record-length format.v The records must be at least 8 characters long but no longer than 80 characters.v The passwords to be restricted must begin in the first column of each record.v Columns 1 through 8 must contain only one restricted password and nothingelse.v There may be only one restricted password per record.v Column 9 must be blank.v Columns 10 through 80 may be used for comments.If you do not want automatic deactivation of passwords, edit the RPWLIST DATAfile and delete all the passwords. Leave one dummy record of an asterisk (*) incolumn 1.386 z/VM: CP Planning and Administration

Security and Integrity in z/VMUsing Link Access Control OptionsWith VM/ESA, you can set up a service virtual machine with the authority to controluser access to minidisks and databases. This authority is useful when runningdatabase applications and performing data migration tasks where data stability andintegrity are essential. To do this, the service machine is configured with directorycontrol statement options that allow it to use certain link access modes thattemporarily restrict other users from gaining link access to the data the servicemachine is using.Two types of access modes can be used to ensure data integrity when linking toanother minidisk for a limited period of time. The stable access modes, whenrequested by an authorized virtual machine, prevent other users from obtainingwrite access to a disk while the stable access is in effect. The exclusive accessmodes grant an authorized virtual machine sole access to a minidisk, preventingboth read and write access by any other users.The LNKSTABL and LNKEXCLU operands of the OPTION directory controlstatement authorize a user to use the stable or exclusive access modes of the LINKcommand or DIAGNOSE X'E4'. This global authority allows a virtual machine toperform a stable link to any minidisk for which it has password level authorization.You can also specify stable and exclusive authority to a specific minidisk using themode suffix letter (S or E) on the MDISK or LINK directory control statements.While stable or exclusive links to a minidisk are in effect, access to that minidisk byany other user will be restricted or denied. For more information on the LNKSTABLand LNKEXCLU options of the OPTION directory control statement, see “OPTIONDirectory Control Statement (General)” on page 533. See “LINK Directory ControlStatement (Device)” on page 500 and “MDISK Directory Control Statement(Device)” on page 513 for more information about access modes and suffixes.Suppressing Passwords Entered on the Command LineCP can be set to reject LOGON or LINK commands that have the passwordentered on the same line as the command. Rejecting these commands preventspasswords from being displayed or printed without masking (masking a passwordmeans overprinting the password so it cannot be read).This capability is also available to virtual machines that issue LINK commands byDIAGNOSE code X'08'. For a description of DIAGNOSE code X'08', see z/VM: CPProgramming Services.To request password suppression, specify it as an option on the FEATURESstatement in the system configuration file. Once requested, password suppressionis always on; an operator cannot turn it off. See “FEATURES Statement” on page136 for information on how to use the FEATURES PASWORDS_ON_CMDSoperand.Using an Integrated Cryptographic FacilityThe Integrated Cryptographic Facility (ICRF) is an optional feature that providescryptographic capabilities for z/VM. z/VM allows multiple virtual machines to accessthe ICRF. The ICRF is available only to ESA mode virtual machines and only if thereal processor has a real ICRF installed. (z/VM does not provide a softwaresimulation of this hardware.) A processor complex can contain one or two ICRFsand the ICRFs can be used by one or more guest virtual machines. A processorcan access only one ICRF, although each ICRF can be accessed by more than oneprocessor.Chapter 12. Security and Integrity in z/VM 387

Security and Integrity in z/VMA real ICRF can be shared among virtual machines if the real processor with whichit is associated is not dedicated to a virtual processor of a virtual machine. If a realprocessor, with its associated ICRF, is dedicated to a virtual processor of a virtualmachine, then that ICRF is unavailable to other virtual machines. This is true even ifthe virtual machine to which the processor is dedicated does not have a virtualICRF defined for the virtual processor.Virtual machines can make use of the real ICRF by means of one or more virtualICRFs. The number of users that can access a real ICRF is limited by the numberof cryptographic domains installed. An ICRF can have up to 16 cryptographicdomains installed. Therefore, up to 16 users can have access to a virtual ICRF atany given time. If a user that is authorized for a certain cryptographic domain logson and that domain is in use, CP issues an informational message stating that thedomain is already in use by another user.Each cryptographic domain consists of one master-key register and oneauxiliary-master-key register. The master key can only be manually installed but isdone with interaction with a program which uses the new cryptographic instructions.Users are assigned use of one or more domains. It is the users’ responsibility toenter the keys and do key management. z/VM will not do any key management.In a processor configuration with two ICRFs installed, the keys in each domain ofeach ICRF are entered separately. Because the keys are set in the ICRF byinteraction with a program, that program must know which ICRF a processoraccesses. The program can then dispatch work on a processor that has access tothe ICRF whose key it is trying to set. When keys are changed it is up to the userto set the keys of each domain in both ICRFs. When the keys are different,cryptography work must only be dispatched on processors accessing the ICRFwhose key is the value the program expects (the ICRF that contains the key theprogram has used to encipher its data).Programs running in virtual processors have the same requirement. That is, thevirtual processors must only be dispatched on real processors which have accessto the ICRF (Crypto) containing the key they expect. If there are two real Cryptounits available and the keys are the same in both Crypto units, a virtual CPU maybe dispatched on either Crypto processor.Virtual machines should be defined with the same number of virtual CPUs withCrypto, as the number of real Crypto processors available. For example, if there aretwo real Crypto units available then the virtual machine should have two virtualCPUs with Crypto defined. If the virtual machines are not defined like this the userwill not be able to interact with the program to set the keys in both real Cryptoprocessors. Likewise, if there is one real Crypto unit available, there would only bea need for one virtual CPU with Crypto.To define two virtual CPUs with Crypto, you need to define a minimum of two virtualCPUs, a virtual Crypto on both virtual CPUs and specify that the virtual Cryptos beassigned to real Cryptos 0 and 1. The virtual Crypto units are defined either byCPU directory control statements or the DEFINE CPU and DEFINE CRYPTOcommands. The virtual Crypto units should be assigned to real Cryptos with theCSU * operand of the CRYPTO directory control statement. See “CRYPTODirectory Control Statement (General)” on page 468 for more information.An example of the directory control statements:388 z/VM: CP Planning and Administration

Security and Integrity in z/VMCRYPTO DOMAIN 1 CSU *CPU 0 NOVECTOR CRYPTOCPU 1 NOVECTOR CRYPTOMaintaining System IntegrityIn a real configuration with two ICRFs installed, if virtual machines are not definedwith more than one ICRF, the user will not be able to interact with the program toset the keys in both real ICRFs. While not the recommended mode of operation, ifthis virtual configuration is desired, the CSU 0 or CSU 1 operand of the CRYPTOdirectory control statement can be used to specify which real ICRF the virtual ICRFshould be assigned to.The ICRF, like the Vector Facility, is an optional feature which may be installed ononly some of the processors in a real processor complex. When a vector or cryptoinstruction is issued by a guest on a virtual CPU, z/VM assigns that virtual CPUaffinity to a real processor that has the corresponding facility installed. If both vectorand crypto instructions are being executed on a virtual CPU, z/VM would continuallybe switching the virtual CPU from one real processor to another since no realprocessor exists that can execute both sets of instructions. Therefore, virtualconfigurations should not be defined with vector and crypto facilities on the samevirtual processor.Your z/VM system has integrity if it can prevent the circumvention, subversion, anddisabling of its security mechanisms. In general, this is achieved by keeping usersseparate from each other, separate from the operating system, and limiting theiraccess only to data which they need to do their jobs.Quite simply, system integrity is your system’s ability to:v Resist compromise of its security controls through misuse and manipulationv Ensure that its resources can only be accessed through authorized routes byauthorized users.To put it another way, system integrity is the inability of any program running in yoursystem to:v Obtain control in real supervisor state, with privilege class authority or directorycapabilities greater than assignedv Use CP to circumvent the system integrity of any guest operating system whichitself has system integrityv Circumvent z/VM main storage protection or auxiliary storage protectionv Access, without authority, a z/VM password-protected resourcev Access, without authority, a resource protected by an external security manager(ESM), like RACF.The IBM System/390 architecture, upon which z/VM is based, is at the center of thesystem’s ability to maintain integrity. One crucial aspect of this is your system’sability to keep each virtual machine absolutely isolated from every other virtualmachine. This isolation especially extends to CP, which is logically separate from allvirtual machines in the system.For the sake of integrity, z/VM exploits the System/390 architecture in several otherways:v The addresses in a virtual machine are virtual addresses. They have no meaningoutside the virtual machine in which they are generated and used. WheneverChapter 12. Security and Integrity in z/VM 389

Security and Integrity in z/VMrequired, these virtual addresses are translated into real addresses by ART(access register translation) and DAT (dynamic address translation), for theaddress space referenced by the user. Using ART and DAT, the system keepsthese address spaces absolutely separate from one another. This means that it isimpossible for one user to access an address space of another user unless theowner allows the other user to do so. Additional information about accessing dataspaces can be found in the z/VM: CMS Application Development Guide.v z/VM translates the addresses in all channel programs, except those initiated byDIAGNOSE X'98'. Channel programs are programs built and run by virtualmachines that request auxiliary storage devices to perform input and outputtasks. z/VM identifies the storage device and performs the I/O operation onbehalf of the virtual machine.v Every z/VM virtual machine runs in interpretive-execution mode which processesmost privileged and nonprivileged instructions and handles virtual storageaddress translation without requiring intervention of z/VM.v z/VM uses page protection to prevent read-only saved segments from beingmodified. A saved segment is a block of data or re-entrant code in virtual, sharedstorage that many users can share simultaneously. However, if a user has alegitimate reason for wanting to change a read-only saved segment, the usermust specifically request an exclusive copy of the saved segment and beauthorized to do so in the user directory. The unmodified code remains sharedamong the other virtual machines. See “Protection of Shared Storage” on page398 for more information.z/VM System Integrity RequirementsThere are many things z/VM provides to support system integrity. You should beaware of them and make certain that all programs and users cooperate with them.System Modification Requirements:A program added to the z/VM system does not weaken the latter’s integrity as longas it:v Uses only documented, unrestricted z/VM interfacesv Runs only with privilege class G authorityv Does not supply services to more than one user from within a single virtualmachinev Does not require the use of special CP system directory optionsv Does not share VM or other passwords with any other program running in anyvirtual machine.Your installation probably will add several programs to the system to fulfill localneeds. Since z/VM’s integrity can be affected by these, consider the followingquestions before you add any to your system:Does the program (or any of its parts):v Run with a user ID which, if an ESM is installed, requires special privileges?v Require the use of CP DIAGNOSE functions that are restricted to classes otherthan G or ANY?v Require CP directory options?v Modify z/VM code?v Modify z/VM by adding or changing a z/VM command?v Run as a multi-user service machine?390 z/VM: CP Planning and Administration

Security and Integrity in z/VMIf the answer to any of these questions is yes, the program could seriously weakenthe integrity of z/VM. Carefully reconsider whether you should add the program toyour system. If you must add a program that threatens to weaken your system’sintegrity, keep the following in mind:v z/VM maintains storage protection in one of two ways, depending upon thenature of the object:– Access register translation (ART) and dynamic address translation (DAT)protect the storage of non-shared segments; that is, storage that is reservedexclusively for one user. ART and DAT are hardware facilities used by z/VMduring the execution of any instruction to translate a virtual address into thecorresponding real address. The system uses ART and DAT to providesecure, separate address spaces for each virtual machine in the system. Thismeans that it is impossible for one user to access an address space ofanother user unless its owner allows the other user to do so. Additionalinformation about accessing data spaces can be found in the z/VM: CMSApplication Development Guide.– z/VM’s shared segment protection mechanism gives any user that tries toalter a read-only saved segment a protection exception. This preserves theintegrity of data or code being shared simultaneously by other users.v You may wish to use an ESM to protect sensitive system data and work areasfrom access by unauthorized users and to protect any proprietary informationautomatically stored on external media. Such protection requires several things ofthe user:– The user must protect proprietary information from all other users exceptthose properly authorized. Proprietary information includes passwords,cryptographic keys, user register contents, user data areas, and buffers.– The user must clear all proprietary data from any storage device or bufferbefore he releases it. Temporary disks (T-disks) are the exception. operand onthe FEATURES system configuration file statement or the SYSCLR option ofthe SYSRES macroinstruction, z/VM clears each T-disk before it is assignedto anyone.– The user must not use z/VM commands and DIAGNOSE codes that bypass(or allow the bypassing of) security checks, integrity controls, or validationprocedures. That is, limit the use of commands and functions that allow directand uncontrolled access to basic system resources. (See “Sensitive z/VMCommands to Restrict” on page 392 and “Sensitive DIAGNOSE Functions toRestrict” on page 394.) Use z/VM privilege classes, DIRMAINT, or an ESM tocontrol access to these resources.User Identification Requirements: To identify a user means to firmly establishwho is using the system to perform a particular act. Every command, DIAGNOSE,and other security-relevant event must be directly attributable to a user whoseidentity has been well-established. With POSIX, however, you can have multipleuser IDs associated with a single UID. Authorities can be given to the one UID andtherefore multiple user IDs. Determining the identity becomes difficult. For thisreason, it is not recommended that you have multiple user IDs associated with asingle UID. User identification requires the following:v System and user resources must be separated from one another and identified.Otherwise, system resources may be counterfeited or one system resource maybe substituted for another.v Before a privileged program passes user data to another privileged program, it isnecessary to define who is responsible for validating the user data. Then, ofcourse, the data must be validated.Chapter 12. Security and Integrity in z/VM 391

Security and Integrity in z/VMValidation Requirements: Validation is an important term that can mean severalthings:v z/VM routines that access areas of storage based on user-supplied addressesmust first validate that the user has the appropriate kind of access (READ,WRITE, and so forth).v During the validating process, the system can use only previously validated andprotected data. Using non-validated or unprotected data during the validationprocess invalidates the process itself.v When a user wants to access an area that spans a page boundary, the systemmust confirm that the user has authority to access the entire range of addressesinvolved.v z/VM routines that simulate CPU instructions or translate channel programs mustdo so according to the architecture of the CPU or device involved.v Parameters passed to the system must be validated for the purpose intended.Serialization Requirements: Serialization is a method used to prevent theasynchronous altering of variables, whose validity must be checked, until after theoperation for which they are validated is complete.A gap can occur between the time when a variable is checked and approved andthe time when the variable is actually used in an operation. During this time, thevariable is vulnerable to change by some unauthorized, asynchronous function. Thesolution is to protect each validated variable from asynchronous alteration until it isused.Note: z/VM system integrity does not specifically include the protection of dataamong several users of a single CMS batch system nor does it apply tovirtual machines using the non-disruptive transition (NDT) support.z/VM Integrity and CP FunctionThere are several CP resources that can affect system integrity:Privilege Classes: A privilege class is a subset of z/VM commands andDIAGNOSE codes. Each user is assigned to a particular privilege class, dependingupon his responsibilities, level of skill, and place in the organization’s hierarchy.Every user is a member of at least one privilege class.If a user attempts to issue a command that is outside his privilege class, the systemignores the command. The main benefit of this is that no user can alter the systemin any way that goes beyond his expertise and authority.IBM designed the structure of z/VM privilege classes with the typical organizationalhierarchy at the typical computing installation in mind. If you find the IBM privilegeclass structure inappropriate to your organization’s needs, you can modify it orcompletely replace it. It is possible for your organization to precisely define up to 32privilege classes of its own that partly or completely override the privilege classstructure that comes with your system. To learn the details of tailoring your system’sprivilege class structure, see Chapter 16, “Redefining Command Privilege Classes,”on page 433.Sensitive z/VM Commands to Restrict: Very few CP commands and DIAGNOSEfunctions have no security and integrity relevance. Some affect the security and392 z/VM: CP Planning and Administration

Security and Integrity in z/VMintegrity of your system more than others, and there are some CP commands andDIAGNOSE functions that allow direct, uncontrolled access to basic systemresources.Change the CP privilege classes or use an external security manager to limit theuse of the following sensitive CP commands:CPACCESSIdentifies a CMS-formatted minidisk to CP and makes the files on thatminidisk available to CP by establishing a file mode letter for the files.CPCACHECauses CP to cache a file on a CP-accessed minidisk.CPRELEASEReleases a CP-accessed minidisk.DEFINE CPOWNEDLets a user define new entries or to change existing entries in the list ofCP-owned DASD volumes.DEFINE TIMEZONELets a user define a new time zone or change an existing time zonedefinition.DISPLAY HOSTDisplays the contents of real storage at the user’s terminal.DUMPHOSTPrints the contents of real storage at the spooled, virtual printer.LOCATEDetermines the address of a particular user’s CP control block, the addressof a virtual device, or the address of a real device.SETD8ONECMDLets a user change the D8ONECMD settings for their or other’s virtualmachine. The D8ONECMD settings control whether CP will accept multiplecommands imbedded in a single command and separated by X'15'characters.SET MDCACHE SYSTEMturns minidisk caching on and off for the whole system. Turning minidiskcaching off at the system level disables caching enabled at the device orrecord level.SETSETSETSETSETOBSERVERChanges the observer user ID associated with your virtual machine oranother user’s virtual machine.PRIVCLASSControls future SET PRIVCLASS commands or temporarily changes the setof privilege classes for a logged-on user.RDEVICEChanges or adds devices to the system’s definition of a set of real devices.SECUSERChanges the secondary user ID associated with your virtual machine oranother user’s virtual machine.SYSOPERChanges the user ID of the primary system operator on your system.Chapter 12. Security and Integrity in z/VM 393

Security and Integrity in z/VMSET TIMEZONEChanges the system’s active time zone ID and time zone offset.SET VDISK SYSLIMlimits the total resource available for allocating virtual disks in storage.Users may suddenly find that they cannot create as many virtual disks instorage as they had been able to.SHUTDOWNSystematically ends all system functions and checkpoints the system for aneventual warmstart. May also perform an automatic warmstart of thenucleus.SNAPDUMPTakes a dump identical to a hard abend dump, without shutting down thesystem. Could stop the system long enough to cause communication linesto be dropped.STORE HOSTLets a user alter the contents of real storage.Sensitive DIAGNOSE Functions to Restrict: Change the CP system of privilegeor use an external security manager to limit the use of the following sensitiveDIAGNOSE functions:DIAGNOSE X'04'Allows the user to examine real storage.DIAGNOSE X'08'Allows a virtual machine running in supervisor state to issue CP commands.Usually, this presents no danger to your system’s security or integrity. Often,z/VM commands are issued on behalf of authorized users by privilegedserver virtual machines. However, if a server virtual machine were to issuea CP command on behalf of an unauthorized virtual machine, your system’ssecurity and integrity would be threatened. Each server should checkcarefully the identity and authorization of each machine for whom it doeswork, like DIRMAINT does.DIAGNOSE X'28'Allows channel programs modified after STARTIO (but before the I/Ooperation is complete) to execute correctly.DIAGNOSE X'3C'Allows the user to dynamically update the CP system directory.DIAGNOSE X'4C'Allows a user with the ACCT option in his directory entry to generateaccounting records.DIAGNOSE X'7C'Allows a program to drive a logical 3270 terminal as though it were a real,locally attached 3270.DIAGNOSE X'84'Allows a user to replace certain data in the CP system directory.DIAGNOSE X'98'Allows a virtual machine authorized to use it to lock and unlock virtualpages in storage. It also allows the virtual machine to execute its own realchannel programs.394 z/VM: CP Planning and Administration

Data Structures That Can Enhance System Integrityz/VM maintains many directories, tables, and control blocks that manage thesystem. Many of these data structures contribute to your system’s security andintegrity.System Configuration File: The system configuration file contains definitions foryour system and how it should operate. The items in this file that pertain to securityand integrity include:v FEATURES ENABLE CLEAR_TDISK statement, specifying that all previouslywritten data and directory areas on temporary disk DASD space should becleared automaticallyv FEATURES PASSWORDS_ON_CMDS statement, specifying whether the facilitythat suppresses the password on the command line should initially be part of thesystem.v JOURNALING statement, specifying whether the facility that journals eventsshould be part of the system, whether the system can set and query thejournaling facility, and what to do if someone tries to log on to the system or linkto a disk without a valid password.CP System Directory: The CP system directory is a table maintained on DASD,each entry of which describes the configuration of a particular virtual machine inyour system. To put it another way, the CP system directory tells z/VM exactlywhich system resources will be available to each virtual machine, how each shouldbe built, and how access to each shall be governed.The items in each directory entry that pertain to security and integrity include:v CP log on passwordsv Minidisk passwordsv LINK statementsv CLASS statement, describing what kind of user this is and what class ofcommands and instructions the user will be allowed to issuev DIAG98 option on the OPTION control statement, letting the user invoke theDIAGNOSE X'98' function.v LNKNOPAS and D84PAS options on the OPTION control statement.v POSIXINFO statement for the UID and GID|GNAMEv POSIXGLIST statement for listing the groups that the user belongs toRSCS Configuration File Options: The RSCS configuration file defines the RSCSnetwork, and includes such information as:v Local node identifierv Identifier of each node with which the local node can communicatev Network links over which the local node communicates with the remote nodes.VM/Pass-Through Directories: VM Pass-Through (PVM) allows a user tointeractively access a virtual machine in some remote system. Your system’s PVMvirtual machine maintains a directory called a configuration file. This file includes:v Local and remote node identifiersv Link and routing definitionsv Authorization of certain users to issue restricted commands.Security and Integrity in z/VMChapter 12. Security and Integrity in z/VM 395

Security and Integrity in z/VMDirectory Update-in-Place: DIAGNOSE X'84' gives a privilege class B user theability to replace data in the CP system directory. Note that this doesn’t authorizethe user to add new entries or to delete existing ones.As z/VM is delivered, all privilege class B users can issue DIAGNOSE X'84'. Forthe sake of security, strictly limit the number of privilege class B users in yoursystem. Of course, your organization may have chosen to change the privilegeclass structure that IBM has built into your system. If so, be certain to limit thenumber of users who can issue DIAGNOSE X'84'.Dumps: A dump is a snapshot, taken at a particular moment, of the contents of acomputer’s main storage. Most dumps are created by highly privileged users to helpthem solve system problems.There is no way to predict what main storage contains when the dump is created.Passwords or poorly encrypted data may be present, or the dump may containother material that your organization considers proprietary and confidential.Therefore, take great care that only authorized personnel handle the dumpsgenerated by the system. What’s more, never send a dump to anyone outside yourorganization unless you are certain it contains nothing proprietary or confidential.Composite Reader File: The composite reader file is a spool file that contains agroup of CMS files. From CMS’s point of view, the composite reader file is manyfiles; from z/VM’s point of view, however, it is all one spool file. This difference inperspective can create security and integrity problems.To illustrate, consider the following sequence of commands issued by a user namedMARY to create a composite reader file in the virtual reader of a user namedJOHN.CP SPOOL PUNCH JOHN CONTPUNCH PROFILE EXECPUNCH PROFILE XEDITPUNCH CALENDAR DATA.PUNCH NOVEMBER REPORTCP SPOOL PUNCH CLOSE NOCONTIf JOHN issues a CP QUERY READER command, the response indicates that thereis only one file in his reader, NOVEMBER REPORT. But because this is acomposite spool file, there are several other files present that are hidden from anyQUERY. The presence of these other files is neither implicit nor apparent.Now, assume that JOHN already has a file called PROFILE EXEC. When he readsin NOVEMBER REPORT, all the other files are read in, too. JOHN’s PROFILEEXEC disappears, overwritten by the new PROFILE EXEC. JOHN may or may notconsider that desirable. At the very least, he should be informed of the loss of hisfile.To prevent security and integrity problems like this from arising, z/VM providesseveral options to the DISK LOAD, READCARD, RECEIVE, and DEFAULTScommands:FULLPROMPTSpecifies that a prompt message is issued for each file.MINPROMPTSpecifies that a prompt message is issued when the name of the first file396 z/VM: CP Planning and Administration

Security and Integrity in z/VMdiffers from the name of the spool file. The prompt message for the first filedoes not appear when it has the same name as the spool file.NOPROMPTSpecifies that a prompt is not issued when a file is received.REPLACESpecifies that if a file with the same file name and file type already exists,then it is to be replaced with this one.NOREPLACESpecifies that no file ever overlays an existing file on the receiving disk.z/VM Options That Can Enhance System Integrityz/VM offers several options that can help you to enhance the integrity of yoursystem.Real Channel Program Support: DIAGNOSE X'98' lets an authorized virtualmachine lock and unlock virtual pages in storage. It also allows the virtual machineto execute its own real channel programs. That would make it possible for thevirtual machine to access real storage beyond the legitimate end of its addressspace. It would then be possible for the virtual machine to inspect and alter CP orsome other virtual machine. That would not be sound security practice.The ability to invoke this function is an extremely powerful privilege, which thesystem administrator should either restrict or eliminate.There are two ways to prevent the use of DIAGNOSE X'98':v Remove DIAG98 from the OPTION statement of each entry in the CP systemdirectory in which it appears.v Set DIAGNOSE X'98' to an unused privilege class.If an unauthorized user attempts to use DIAGNOSE X'98', he receives an operationexception.StorageHandlingYour z/VM system maintains the security and integrity of its storage, as follows:Protection of Main Storage: z/VM provides both fetch and store protection for real,main storage. No user may store in or fetch from a segment of main storage unlesshis key matches the protection key of that storage.z/VM protects real, main storage using the privilege class structure. As the systemis delivered, only privilege class C users can alter CP storage. Of course, yourorganization may have chosen to change the privilege class structure that IBM hasbuilt into your system.Allocation of Main Storage: Real storage is allocated to a user when he firstrefers to a virtual page for which a real page has not yet been allocated. Allocationcontinues, as needed, up to and including the maximum storage size indicated inthe user’s CP system directory entry.Before z/VM allocates a new, real page, that page is cleared of any data that mayhave been left behind by another user. This prevents a user from having access todata for which he has no authorization.Chapter 12. Security and Integrity in z/VM 397

Security and Integrity in z/VMPaging: In z/VM, many users share main storage simultaneously. Not every pageof storage could possibly be active every second of the time. When a page of mainstorage is not being actively accessed by a user, the system transfers it toexpanded storage or DASD. This is known as paging out. The space in mainstorage that it abandons then becomes available to another user who really needsit. When and if that same page is needed again, the system transfers it fromexpanded storage or DASD back to main storage. This is known as paging in.z/VM maintains a set of page and segment data tables that contain preciseinformation on the location and owner of every page and segment of main storage,whether paged in or paged out. The system follows them rigorously, helping tomaintain the integrity of the system.Protection of Shared Storage: Virtual storage space is routinely shared by usersof z/VM. These shared segments help the system manage its storage moreefficiently.Shared segments can be read/only or read/write blocks of storage containing codeor data shared by many users. Sharing one copy of something, like XEDIT, ispreferable to giving each user his own copy.As z/VM is delivered, only a user with privilege class E can define and save ashared segment. Of course, your organization may have chosen to change theprivilege class structure that IBM has built into your system. If so, take care that theability to define and save shared segments is not given out indiscriminately.Clearing Residual Data from Minidisks: You can tailor DIRMAINT to automaticallyclear DASD space whenever a minidisk is detached. This applies when you releasean entire minidisk and when you permanently reduce the size of a minidisk. Thisprevents the next user to whom the space is allocated from seeing information hemay not be authorized to see.Clearing Residual Data from Temporary Minidisks: You can also tailor yoursystem to automatically clear each temporary minidisk (T-disk) before it isreassigned. Simply add the ENABLE CLEAR_TDISK operand on the FEATURESsystem configuration file statement.Clearing Residual Data from Tapes: Sometimes, a user finds that he no longerneeds the data on a reel or cartridge of tape. This does not mean that the data isno longer sensitive. Hence, you must establish procedures to ensure that each reelor cartridge of tape is degaussed before it is assigned to a new user.Program Stack, Security, and IntegrityWhile executing, many programs and EXECs place data on the program stack.Ideally, this data should be used to accomplish useful work and then promptlydiscarded. In reality, though, it may be left behind in the stack after the programterminates. In fact, many programs intentionally leave data on the program stack sothat they can pass information to other routines. While this practice may be clever, itis not risk free.As a rule, when a program or EXEC terminates or relinquishes control, the programstack should be exactly as it was when the program or EXEC gained control. Thisshould apply to both normal and abnormal termination. The program or EXEC thatterminates before restoring the program stack can cause serious security andintegrity problems.398 z/VM: CP Planning and Administration

Security and Integrity in z/VMFor example, suppose a privileged server virtual machine runs a program thatobtains data from a virtual reader or other communication channel and places it inthe program stack. An unscrupulous party comes along and feeds his owncommands to the program through the communication channel. Dutifully, theprogram places them on the program stack until the attacker somehow forces theprogram to fail. If the program is designed to restore the program stack, no harm isdone. However, if the program does not restore the stack, then the attacker’scommands are executed by the privileged server machine!Many programmers prudently avoid using the program stack altogether by usingGLOBALV variables to pass information to other routines. Some programmers useother techniques, such as managing the program stack with the CMS MAKEBUFand DROPBUF commands and the StackBufferCreate and StackBufferDelete CSLroutines. These commands and routines enable a user to manage a new, separatebuffer that can be used without affecting the contents of any buffers previouslydefined.Study the following examples.A Simple EXEC that Manages the Stack with MAKEBUF and DROPBUFADDRESS COMMANDSIGNAL ON HALT /* FORCE ANY INTERRUPTION TO COME OUTOF MAIN EXIT */’MAKEBUF’ /* GET A BUFFER TO HOLD ANY GARBAGE */BUFNO = RC /* KEEP ITS NUMBER */.(MAINPROCESSING).HALT: /* MAIN EXIT PROM PROGRAM */SRC = RC /* KEEP LAST "RC" FOR EXIT */’DROPBUF’ BUFNO /* DISCARD GARBAGE */EXIT SRCA More Complex EXEC Calling a SubroutineADDRESS COMMANDSIGNAL ON HALT /* FORCE ANY INTERRUPTION TO COME OUTOF MAIN EXIT */’MAKEBUF’ /* GET A BUFFER TO HOLD ANY GARBAGE */BUFNO = RC /* KEEP ITS NUMBER */.(MAINPROCESSING).’MAKEBUF’ /* GET ANOTHER BUFFER TO PASS DATATO SUBROUTINE */QUEUE ’SOMETHING FOR SUBROUTINE’CALL SUBROUTINESRC = RC /* KEEP "RC" FROM SUBROUTINE */’DROPBUF’ BUFNO + 1 /* DISCARD ANYTHING NOT CLEARED BY SUBROUTINE */.(MORE/* AT THIS POINT, TEST RETURN CODE FROMSUBROUTINE, USING "SRC" INSTEAD OF "RC" */PROCESSING).HALT: /* MAIN EXIT FROM PROGRAM */SRC = RC /* KEEP LAST RC FOR EXIT */’DROPBUF’ BUFNO /* DISCARD GARBAGE */EXIT SRCAn EXEC Called as a Subroutine and Returning Data in the Program StackChapter 12. Security and Integrity in z/VM 399

Security and Integrity in z/VMADDRESS COMMANDSIGNAL ON HALT /* FORCE ANY INTERRUPTION TO DOFINAL PROCESSING */’MAKEBUF’ /* GET A BUFFER TO HOLD ANY GARBAGE */BUFNO = RC /* KEEP ITS NUMBER */.(MAINPROCESSING).SRC = RC /* KEEP LAST "RC" FOR EXIT */’DROPBUF’ BUFNO /* DISCARD GARBAGE */QUEUE ’SOMETHING FOR CALLING ROUTINE’EXIT SRC /* MAIN EXIT FROM PROGRAM */HALT: /* SPECIAL EXIT FROM PROGRAM IFINTERRUPTED BY "HI" */’DROPBUF’ BUFNO /* DISCARD GARBAGE */EXITReporting z/VM Integrity ProblemsThe authorized program analysis report (APAR) is the formal mechanism forreporting to IBM problems you are having with z/VM. These problems may include:v Integrity exposuresv Logic errors in the programmingv Documentation errorsv Program distribution problems.You should never use the APAR process to:v Comment on or suggest improvements to z/VMv Report minor stylistic, grammatical, spelling, or punctuation errors in a z/VMdocumentv Report on the packaging or quality of the items you received from IBM.IBM also accepts security APARs involving z/VM or any product that runs on it. Asecurity APAR reports problems in existing z/VM security mechanisms where theproblem is not quite an integrity problem but does represent a threat to the securityof the system as a whole or to one of its components.If you discover an integrity problem in z/VM, proceed as follows:1. Consider your problem in light of the discussion of system integrity under“Maintaining System Integrity” on page 389. If it is truly a system integrityproblem, proceed to the next step.2. Confirm that you have the current version, release, and modification level ofeach of the software products in your system.3. Examine the appropriate documentation to see if there is a solution to yourproblem.4. Remove any modifications you may have applied to z/VM to be certain that thisis not the cause.5. If your modification has caused the problem, do not replace it until it is repaired.If none of your modifications is the problem (or if you have made none), try toisolate the problem to a particular component of z/VM.6. Gather and retain the necessary materials that document your problem: dumps,output listings, tapes, messages, return codes, and so forth. Be certain thatnone of this material is considered proprietary by your organization. If it is, try toreplicate the problem resulting in data that is not proprietary.7. Notify IBM service.400 z/VM: CP Planning and Administration

Security and Integrity in z/VMTo resolve your problem, IBM may:v Correct IBM code or documentationv Document a temporary or permanent restrictionv Notify you that it is aware of the problem (IBM either provides an immediatesolution or waits until the next release of the program or document)v Notify you that someone or something at your installation is the cause of theproblem (IBM then advises you on a solution).If, to solve your problem, IBM must correct its code or documentation, the companyalerts all z/VM customers to the problem and provides a program temporary fix(PTF). A PTF is a temporary solution to or bypass of a problem identified by IBM asthe result of a defect in a current, unaltered release of the software product. Yoursystem administrator is responsible for installing all PTFs; IBM provides anynecessary PTF documentation.Chapter 12. Security and Integrity in z/VM 401


Chapter 13. Using the Stand-Alone Dump UtilityOverviewCP can produce several types of dumps: a CP dump, a snapdump, a stand-alonedump and a virtual machine dump. Dumps are especially helpful in analyzingproblems such as wait states, infinite loops, and abends. This chapter describeshow to create the stand-alone dump utility and use it. For more information on thestand-alone dump utility, debugging various types of problems, the other dumptypes, and other problem diagnosis tools, see the z/VM: Diagnosis Guide.z/VM includes a stand-alone dump utility that you tailor according to yourinstallation’s configuration, using CMS. After you generate z/VM, you should createthe stand-alone dump utility and place it on tape or a DASD for emergency use. If,after a system failure, CP cannot create an abend dump, you can use thestand-alone dump utility to dump all of storage.This chapter describes how to create the stand-alone dump utility and providesreference information about the:v HCPSADMP EXECv HCPSDC ASSEMBLE file.With the stand-alone dump utility, you can dump all of real storage when z/VMcannot create a CP abend dump. This utility dumps all resident, nonzero pages, CPand non-CP. It cannot dump virtual machine storage and nonresident pages fromthe paging device.To use the stand-alone dump utility to dump real storage, you must have access toIPL the real machine. (This is usually done by the System Administrator, not a user.)You can IPL the stand-alone dump utility from tape or a DASD and direct the outputto a tape. You may need to reserve several tapes to hold all the information. Basicerror recovery is available for DASD and tape devices used as IPL or outputdevices.Typically, an installation can have several stand-alone dump utilities generated andready to run. It would be useful to have the following configurations available for thestand-alone dump utility:v IPL from tape with output directed to tapesv IPL from DASD with output directed to tapesThese configurations let you take a stand-alone dump with any of the supportedpossible environments.Creating the Stand-Alone Dump UtilityYour installation can generate the stand-alone dump utility to customize the facilityto your system configuration. This gives you control over the device used to IPL thestand-alone dump utility and the output device for the dump. Invoke theHCPSADMP EXEC in a CMS virtual machine to do the generation.Do not call the HCPSADMP EXEC from within another exec. Also, do not queue upthe answers ahead of time when running the HCPSADMP EXEC.© Copyright IBM Corp. 1991, 2004 403

Using the Stand-Alone Dump UtilityTo use the HCPSADMP EXEC:v You must have read/write access to file mode A.v The following files must exist on an accessed disk:– HCPSADMP EXEC– HCPGPI MACLIB– HCPPSI MACLIB– HCPOM1 MACLIB– HCPOM2 MACLIB– HCPVM CNTRL (the control file)– HCPLDR MODULE– HCPSADLD EXEC (the load list)– LDT HCPSADWT– HCPSAD TEXT– HCPSAH TEXT.v You need the H assembler or the high-level assembler.You are asked to answer a series of questions that describe the environment wherethe stand-alone dump utility will run. The HCPSADMP EXEC checks all input forvalidity and returns messages if you enter invalid data.1. If the system has generated more than one stand-alone configuration, useunique names for each configuration. The active configuration must always benamed HCPSDC. If you answer Y to create a new HCPSDC module, (refer to“Example for Generating the Stand-Alone Dump Utility” on page 406), theoriginal is erased.2. If you respond with N to any of the questions (refer to “Example for Generatingthe Stand-Alone Dump Utility” on page 406), the exec goes directly to the nextquestion without doing the indicated work.3. When the exec asks you to enter the real output device number, you are limitedto four digits for z/VM.An example of the prompts and replies that appear on the virtual machine consoleduring HCPSADMP EXEC execution is shown in “Example for Generating theStand-Alone Dump Utility” on page 406.Following the data that you provide, the HCPSADMP EXEC:v Creates a file called HCPSDC ASSEMBLE and writes the file on your A diskv Assembles the HCPSDC ASSEMBLE file to create the HCPSDC TEXT file andlink-edits it with the stand-alone dump utility modulev Writes the stand-alone dump utility load module on a real device.At the end of this procedure, the stand-alone dump utility resides on auxiliarystorage (tape or disk) ready for loading at any time.Before You BeginBefore you create the stand-alone dump utility, note the following:v If you use a DASD as the IPL device, the stand-alone dump utility takes upcylinder 0. The volume you use as the IPL device may be any CP-formattedDASD volume except the system residence (SYSRES) volume. The cylinder404 z/VM: CP Planning and Administration

Using the Stand-Alone Dump Utilitymust be formatted as PERM space; use ICKDSF. The remaining cylinders maybe formatted and used for any CP function other than system residencefunctions.v If the volume you are going to use as your IPL device is shared through crosssystem link, the data created for cross system link by the XLINK FORMATcommand must be placed in a cylinder other than cylinder 0 (its default location).The CSELVOL macroinstruction may be used to define an alternative location forcross system link data for specified volumes.v Any IPL device (tape or DASD) must be write-enabled.v When you create the stand-alone dump utility, you can specify up to eight dumpdevices. With one exception, the stand-alone dump utility chooses the first readydevice as a dump device. The exception is the IPL device. If a dump device isalso the IPL device, the stand-alone dump utility chooses any other ready dumpdevice first.v Choosing a dump device:– You may wish to include tape drives on different tape control units. Otherwise,if the tape control unit for the stand-alone dump devices is inoperative at thetime of failure, you will not be able to run the utility.– To increase the amount of dump data the stand-alone dump utility can writeon one tape, choose tape drives that can write the most data per tape reel orcartridge.Note: It is suggested that the 3590 be used for central storage sizes of 2Gigor more due to the 3590’s speed and high data capacity.Attention: The stand-alone dump utility does not support device sharing with otherprocessor complexes. Therefore, when you are ready to use the stand-alone dumputility, you should make sure no other system on any other processor complex isusing any of the possible dump devices.Devices You Can Use to IPL a Stand-Alone DumpThe following are the devices you can use to IPL the stand-alone dump utility:DASD 3380 and 3390Tape 3422, 3480, 3490 and 3590Notes:1. If you select a DASD as the IPL device:a. It cannot be a device that has the Stand-Alone Program Loader (SAPL) onit.b. It cannot be the resident system device.c. It must be CP-formatted by using either a CPFMTXA command or ICKDSF(recommended).d. Cylinder 0 must be allocated as permanent space.e. The stand-alone dump uses cylinder 0.f. The remaining cylinders may be formatted and used for any CP functionother than system residence functions.2. The stand-alone dump IPL tape can be the same as the tape to which youdirect the dump output. If you choose to use the same tape, the dump will NOTbe written over the stand-alone dump utility. That is, the same tape can beIPLed to take a dump at a later time.Chapter 13. Using the Stand-Alone Dump Utility 405

Using the Stand-Alone Dump Utility3. Do not try to IPL from a device that is not in the previous list. The stand-alonedump utility does not support FBA DASD.Devices to Which You Can Send Dump OutputThe following are the devices to which the dump output can be directed:Tape 3422, 3480, 3490 and 3590Notes:1. You can specify a maximum of eight real device numbers for the dump outputdevice. To increase the amount of dump data the stand-alone dump utility canwrite on a tape, choose tape drives that can write the most data per tape reel orcartridge. You can enter up to four digits for each real output device number. Itis suggested that the 3590 be used for central storage sizes of 2Gig or moredue to the 3590’s speed and high data capacity.2. When you configure the stand-alone dump utility, you can use any tape devicetype from the list of supported devices. You may wish to include tape drives ondifferent control units. Otherwise, if the tape control unit is inoperative at thetime of the failure, you will not be able to run the program.3. All 3480 tape devices save tape data in non-compact format. All 3490 and 3590tape devices save tape data in compact format.4. Do not send the stand-alone dump output to a device that is not included in theprevious list.The stand-alone dump utility selects, as the dump output device, the first availabledevice in the list, excluding the IPL device (if it is in the list). If you want thestand-alone dump output to go to the IPL tape, make all other devices that are inthe list not ready. If no other device within the output address list is available andthe IPL tape address is in the list, the IPL device receives the dump.If you select a tape for the dump output device, other than the IPL tape, thestand-alone dump utility:1. Rewinds the tape to ensure that the dump is at the beginning of the tape2. Sets the density to the highest value for the tape device.If the tape device selected is the one on which the stand-alone dump utility resides,the utility writes the dump at the same density as the stand-alone dump utility waswritten.When using tape, reserve the complete tape for the stand-alone dump utility; do notput the stand-alone dump utility on a tape with the other stand-alone utilities.Use a single-volume, nonlabeled tape for the stand-alone dump utility. Be sure thatthe tape is nonlabeled, because the utility does not check to ensure that it is anonlabeled tape.Example for Generating the Stand-Alone Dump UtilityThe following is an example of generating the stand-alone dump utility. In thisexample:406 z/VM: CP Planning and Administrationv You are placing the stand-alone dump utility on a 3390 DASD device with anaddress of 150.v The control file in this example is HCPVM.v The system sends the dump output to the first available 3490 tape drive whoseaddress is 570, 571, 572, 573, 574, 575, 576, or 577.

Using the Stand-Alone Dump Utilityv The HCPSDC ASSEMBLE file is created and contains the HCPSDCMPmacroinstruction.v It is assumed that the stand-alone dump utility residence volume is attached toyour virtual machine and that you have the appropriate minidisk accesses.Note: To ensure the proper access order, use the UTILITY EXEC (see the z/VM:Guide for Automated Installation and Service).1. Use the CP ATTACH command to attach logically the stand-alone dump utilityresidence device to your virtual machine. For example, if you enter:attach rdev * vdevthe command attaches the device specified by rdev to the virtual machine.2. Establish the appropriate minidisk accesses by entering:vmfsetup esa cp3. Ensure that the HCPSADMP EXEC and HCPVM CNTRL files to be used are ona minidisk accessed earliest in the user’s search order. HCPSADMP EXECuses the HCPVM CNTRL file.Under CMS, enter:hcpsadmpThe exec replies:THE HCPSADMP EXEC:-OPTIONALLY CREATES A NEW HCPSDC ASSEMBLE FILECONTAINING AN HCPSDCMP MACRO WITH SELECTED PARAMETERSON YOUR A DISK. THE NEWLY CREATED MODULE WILL BEREASSEMBLED.-OPTIONALLY PLACES A LINK-EDITED HCPSAD MODULE (HCPSAD,HCPSAH AND HCPSDC) ONTO WHATEVER DEVICE IS DEFINED AS THERESIDENCE DEVICE, WHERE THE RESIDENCE DEVICE IS THETARGET DEVICE ON WHICH THE STAND-ALONE DUMP UTILITYWILL RESIDE.PLEASE RESPOND YES, NO (OR END TO EXIT EXEC) WHEN ITPROMPTS YOU. IF YOU RESPOND NO, YOU MUST HAVE A HCPSDCTEXT FILE FROM A PRIOR GENERATION OF THE STAND-ALONEDUMP UTILITY.DO YOU WANT TO CREATE A NEW HCPSDC MODULE?Enter:yesPLEASE SELECT RESIDENCE DEVICE TYPE(3350, 3375, 3380, 3390, 9345, 3420, 3422,3424, 3430, 3480, 3490, 3590, 9348 or END):9345PLEASE ENTER RESIDENCE DEVICE NUMBER:150PLEASE SELECT OUTPUT DEVICE TYPE:(3420, 3422, 3424, 3430, 3480, 3490, 3590, 9348 or END).3420Chapter 13. Using the Stand-Alone Dump Utility 407

Using the Stand-Alone Dump UtilityPLEASE SELECT OUTPUT DEVICE NUMBER OR LIST:A LIST MUST BE PLACED WITHINPARENTHESES AND THE ADDRESSESSEPARATED BY COMMAS(570,571,572,573,574,575,576,577)ASSEMBLING HCPSDCHCPSDC TEXT CREATED PRT FILE 4584 SENT FROM MAINT PRT AS 1234 RECS 0056COPY 001 HOLD NOKEEPDO YOU WANT TO PLACE THE STANDALONE DUMP ONTO 150?yesTaking a Stand-Alone DumpLOAD LIST: HCPSADLD EXEC A2 mm/dd/yy hh:mm (MNT190)These messages inform you about the load list that the exec is using.CPU STOPPED; DISABLED WAIT PSW 000A0000 00008200When the HCPSADMP EXEC completes successfully, your virtual machine enters adisabled wait state, code 8200.If you plan to dump 16 MB of storage on a 1/2-inch reel, use a tape density of 1600or 6250 BPI. A 16 MB dump may not fit on a tape at 800 BPI.To invoke the stand-alone dump:1. For multiple processor systems, stop all tightly coupled processors. Do not clearstorage.2. For multiple-processor systems, select the processor with the I/O configurationthat has access to the resident volume address and the output deviceaddress(es).3. Display locations X'0' to X'18' at the console. The stand-alone dump IPLsequence overlays these bytes, so they cannot be recovered.4. Do a STORE STATUS operation on the CPU where you will IPL the stand-alonedump utility. If you do not do the STORE STATUS, the following are not savedin low storage:v CPU timerv Clock comparatorv Current PSWvPrefixv Model-dependent featuresv Control registersv Floating-point registers 0, 2, 4, and 6v Access registers408 z/VM: CP Planning and Administrationv General-purpose registers.If the prefix value is not saved in low storage, the information from the prefixpage is not available for the formatted section of the dump.5. If the stand-alone dump utility resides on a tape, then mount and ready thevolume, making sure that the tape is write enabled.6. Ready the output device. If you want the system to place the stand-alone dumpon the IPL tape, make all other tapes listed as output devices (at generation

Using the Stand-Alone Dump Utilitytime) not ready. If you do not want the stand-alone dump on a device that islisted as a possible output device, the device must not be ready at the time youIPL the stand-alone dump utility.7. IPL the stand-alone dump utility.Note: Do not use the LOAD CLEAR command to load the stand-alone dumputility. This command destroys the storage contents you are trying todump.Initially, the stand-alone dump utility writes the first seventeen pages of storageto the IPL device. This provides an area to load the stand-alone dump utility andwork space. (See “Tape Format” on page 777 and “DASD Format” on page 779for information about the tape and DASD format.) This step causes the systemto place the dump on the output tape.8. After the CPU has gone into a wait state, display the PSW to determine thestatus. A wait state of 8200 indicates that the stand-alone dump hassuccessfully completed. If the stand-alone dump utility is unsuccessful becauseof some error that you can fix (for example, an I/O error on the output tape):a. Correct the error.b. Invoke a hardware RESTART to restart the stand-alone dump.If you re-IPL the stand-alone dump utility again, part or all of the first six pagesof storage will be invalid. After the initial IPL, you cannot change the IPLaddress or IPL volume. See the z/VM: System Operation book for a completedescription on the different wait state codes.Processing the Stand-Alone Dump Data on TapeThe HCPSADMP EXECRe-IPL z/VM. Use the CP DUMPLOAD utility to create a CMS file from the dump onthe tape, and then use the VM Dump Tool to process the dump. For details onusing DUMPLOAD see the z/VM: CP Commands and Utilities Reference. Fordetails on using the VM Dump Tool, see the z/VM: VM Dump Tool book.The HCPSADMP EXEC creates a load module of the stand-alone dump utility andwrites the module on a real device. To invoke this exec, enter:hcpsadmpThe exec command line has no operands. It prompts you for the information itneeds. See “Creating the Stand-Alone Dump Utility” on page 403.UsageNotes1. The IPL device, the device from which the stand-alone dump utility is loaded,cannot be the CP system residence device.2. If the IPL device is a tape, the stand-alone dump utility supports that same tapeas a dump device, the device to which dumps are sent.3. This utility does not support FBA DASD devices. For device support information,refer to “Devices You Can Use to IPL a Stand-Alone Dump” on page 405 and“Devices to Which You Can Send Dump Output” on page 406.4. When the HCPSADMP EXEC completes successfully, your virtual machineenters a disabled wait state, code 8200.Chapter 13. Using the Stand-Alone Dump Utility 409

Using the Stand-Alone Dump Utility410 z/VM: CP Planning and Administration

Chapter 14. Creating and Modifying Image Libraries forPrintersCreating Text DecksThis chapter describes how to:v Create text decks for IBM 3800 and impact printersv Install and modify image librariesv Display information about image librariesv Purge image librariesv Find information on how to back up image librariesv Find more information about printers.For a printer to work properly, it must have access to an image library. This imagelibrary is a set of modules that define the spacing, characters, and copymodification data the printer needs to format and print information. For each printertype there can be a number of IMAGE libraries, but the IMAGE library used for anyone file must contain both the UCS images and the FCB images required for theprinter to properly format and print the file.An image library requires a text deck as its input file. The procedure for creating atext deck for a 3800 is different from the procedure for creating a text deck for animpact printer. This chapter explains both methods.If your installation dedicates a printer to a virtual machine, use the facilities of theoperating system you run in the virtual machine to build the appropriate imagelibraries. If your installation is going to use a printer as a CP spooling device (thatis, a device that CP uses to print data for one or more virtual machines), you canfollow the procedures described in this book to install image libraries.A text deck is the input file required to produce an image library. A text deckcontains forms control buffers (FCBs), copy modifications, character arrangementtables, graphic character modifications, or library character sets.Creating Text Decks for the 3800IBM supplies a 3800 image library feature tape. This feature tape is preinstalled onthe z/VM System DDR, source is excluded. Control files for a 3800 image libraryare included.Character sets supplied by IBM are supplied as separate files on the S disk; theyare named XTB1xxxx TEXT S. These fonts are described in the IBM 3800 PrintingSubsystem Programmer’s Guide.If you are modifying a 3800 image library or creating your own 3800 image library,you need to use the GENIMAGE utility to create a text deck for that image library.The following is an example of the command to initiate GENIMAGE:genimage sysin file * sysprint listing a1sysin file *is the file name, file type, and file mode of the CMS input file. (The file modecan represent an accessed minidisk or an accessed shared file systemdirectory.)© Copyright IBM Corp. 1991, 2004 411

Creating and Modifying Image Librariessysprint listing a1is the file name, file type, and file mode of the file in which GENIMAGE placesa message listing. (The file mode can represent an accessed minidisk or anaccessed shared file system directory.) GENIMAGE produces two groups ofoutput files: a message listing and a text deck.For more information on the GENIMAGE utility, see the z/VM: CP Commands andUtilities Reference book. For information on creating your own FCBs, copymodifications, and library character sets for a 3800, see the IBM 3800 PrintingSubsystem Programmer’s Guide.Creating Text Decks for Impact PrintersWith the z/VM System DDR tapes or CD-ROM, IBM supplies text decks, assemblefiles, and control files, which you can use to create image libraries for impactprinters. Impact printers supported by z/VM are listed in the z/VM: GeneralInformation book.If you are modifying an image library or creating your own image library, you needto create a text deck for that image library. To do so, you must:1. Code the appropriate macroinstructions to add universal character sets (UCSs)and FCBs to produce assemble files. For more information on the namingrestrictions and conventions for FCBs and UCSs, see “Universal Character Setsand FCBs Supplied by IBM,” “Forms Control Buffers Supplied by IBM” on page418, and “Naming Conventions for UCS Buffer Images and FCBs” on page 416.2. Process the assemble file with the VMFHASM utility. The output of VMFHASMis a text deck. If you have the H Assembler then use the VMFHASM command.If you have the High Level Assembler then use the VMFHLASM command.Universal Character Sets and FCBs Supplied by IBMThe IBM-supplied buffer images for each printer are located in an assemble file ofthe form nnnnxxxx ASSEMBLE (nnnn is the printer type, xxxx is the buffer imagename).For example, the AN buffer image associated with the 3203 is located in 3203ANASSEMBLE.IBM supplies the following UCS buffer images for the 3203 printer:Name MeaningAN Normal alphanumeric notation character set arrangementHN Normal hexadecimal notation character set arrangementPCAN Preferred alphanumeric notation character set arrangementPCHN Preferred hexadecimal notation character set arrangementPN PL/I—60 graphicsQN PL/I—60 graphicsQNC PL/I—60 graphicsRN FORTRAN, COBOL commercialSN Text printing 84 graphicsTN Text printing 120 graphicsYN High-speed alphanumericIBM also supplies the following UCS buffer images for devices that emulate the3211 printer.Name MeaningA11 Standard commercial412 z/VM: CP Planning and Administration

Creating and Modifying Image LibrariesH11 Standard scientificG11 ASCIIP11 PLIT11 Text printingIBM supplies the following UCS buffer images for the 3262 printer:Name MeaningP48 USA EBCDICP52 Austria/Germany character setP63 USA EBCDICP64 USA EBCDICP96 USA EBCDICP128 Katakana character setIBM supplies the following FCB images for the 3203, 3262, 4245, and 4248 printersand devices that emulate the 3211 printer:Name MeaningFCB1 Space—6 lines per inch; Length of page—66 linesLine Represented Channel Skip Specification1 13 25 37 49 511 613 715 819 1021 1123 1264 9FCB8 Space—8 lines per inch; Length of page—68 linesLine Represented Channel Skip Specification1 14 28 312 416 520 624 728 832 1036 1163 1266 9FCBS Space—8 lines per inch; Length of page—68 linesChapter 14. Creating and Modifying Image Libraries for Printers 413

Creating and Modifying Image LibrariesLine Represented Channel Skip Specification1 154 255 356 457 558 659 760 861 1062 1163 1264 9For the exact contents of these buffer images, see the IBM 3211 Printer, 3216Interchangeable Train Cartridge, and 3811 Printer Control Unit ComponentDescription and Operator’s Guide.Notes:1. During print line buffer (PLB) loading, the 3211 attaches to the end of the UCS a64-byte associative field. This buffer is used to ensure that each character thatis loaded into the PLB for printing is also on the print train.For the 3203, the dualing and uncomparable table (DUCT) serves a similarpurpose. For more information on coding the DUCT, see the IBM 3203 PrinterModel 5 Component Description and Operator’s Guide.2. The forms control buffer (FCB) for a virtual 3203, 3262 Model 5, 4245, 4248 ora device that emulates a 3211 should be compatible with the FCB that is loadedin the real counterpart; otherwise, the results will be unpredictable.Adding New Universal Character Set Buffer ImagesIf the UCS buffer images that IBM supplies do not meet your needs, you canchange a buffer image or create a new buffer image.With z/VM, two UCS macroinstructions define a UCS for any impact printer. Tocreate the text deck to add a new print buffer image to z/VM, you must:1. Provide a buffer image name and a 12-byte header for the buffer load by codingthe UCSI macroinstruction.2. Provide the exact image of the print chain.3. Code the UCSICCW macroinstruction and produce the appropriate ASSEMBLEfile. The UCSICCW macroinstruction marks the end of the print image andoptionally creates a CCW to print the image.4. Process the assemble file with the VMFHASM utility. The output of VMFHASMis a text deck. For more information on VMFHASM, see “Using VMFHASM orVMFHLASM to Create a Text Deck” on page 422.Note: Only one UCS may be defined in an ASSEMBLE file.Macros are available that make the process of adding new print buffer imagesrelatively easy. The following procedures tell you how to use thesemacroinstructions. Using them also helps you avoid error.414 z/VM: CP Planning and Administration

Creating and Modifying Image LibrariesThe UCSI Macro: The UCSI macroinstruction creates a 12-byte header record forthe buffer load for any supported impact printer. CP uses the header record duringprocessing of the LOADBUF and START commands.Note that the UCS buffer contains up to 512 characters.The syntax of the UCSI macroinstruction is:►►labelUCSI ucsname ►◄ucsnameis a 1- to 4-character name that is assigned to the buffer load.After you have coded the UCSI macroinstruction, you must supply the exact printimage. To supply the print image, code DCs in hexadecimal or character format.The print image may consist of several DCs and may be up to 512 characters inlength. The image consists of a train image and possibly a dualing anduncomparable character table (DUCT). The length of the data for each of theseareas varies depending on the the printer type. Refer to the appropriate hardwaremanual for details. A list of some useful hardware manuals appears near the end ofthis chapter.UCSICCW Macro: After you have supplied the print image, code the UCSICCWmacroinstruction. The UCSICCW macroinstruction marks the end of the print imageand optionally creates a CCW string to print the buffer load image when theoperator specifies VERIFY on the LOADBUF command. This macroinstructionapplies to any supported impact printer. The syntax of the UCSICCWmacroinstruction is:►►labelUCSICCWucsname,device►◄▼ ( ,printn )ucsnameis a 1- to 4-character name assigned to the buffer load by the UCSmacroinstruction.deviceis the device name of the printer with which the buffer is associated.printnare the line lengths to be printed. The variable print1 represents the number ofcharacters printed on the first line, print2 represents the number of charactersprinted on the second line, and so on. Each count specified must be between 1and the maximum length of the print line for the printer you specify. Up to 12print fields may be specified. However, the total number of characters to beprinted may not exceed the maximum for that printer. If the lengths are notspecified, the default is 48 characters per line for the entire UCS buffer image.Chapter 14. Creating and Modifying Image Libraries for Printers 415

Creating and Modifying Image LibrariesNaming Conventions for UCS Buffer Images and FCBs: When you modify orcreate a new UCS or FCB, follow the naming conventions listed below.v The name of the file containing UCS or FCB macroinstructions is composed ofthe printer type followed by the name of the character set. For the 3203 printerwith the PN character set, UCS macroinstructions are found in 3203PNASSEMBLE. This naming convention means that, for a given printer, no UCSmay have the same name as an FCB.v The CSECT name in an assemble file is the name of the character set. In3203PN ASSEMBLE, the CSECT name is PN.v Text files have the same file name as the associated assemble file and have afile type of TEXT. The text file associated with 3203PN ASSEMBLE is 3203PNTEXT.v Each UCS must be defined in a separate ASSEMBLE file.Examples of coding assemble files for printers are given in this chapter. Forinformation on creating text decks, see “Using VMFHASM or VMFHLASM to Createa Text Deck” on page 422.Examples of New 3203 UCS Buffer Images:Example 1: This example defines a buffer image called EX01. The associatedmodule in which you include the code for EX01 should be called 3203EX01ASSEMBLE.You do not have to specify the line length for verification of the buffer load. Insertthe following code in 3203EX01 ASSEMBLE:EX01 CSECTSPACECOPY HCPCWOEQCOPY HCPEQUATSPACEEX01 CSECT ,UCSI EX01DC 5C’1234567890A...Z1234567890*/’DC X’00101010101010101010004000404000’ 240-255DC X’40101010101010101010004040400000’ 256-271DC X’40401010101010101010004000000000’ 272-287DC X’10101010101010101010000000404000’ 288-303UCSICCW EX01,3203END EX01The buffer image is five representations of a 48-character string containing:v The alphabetic charactersv The numeric digits, twicev The special characters asterisk (*) and slash (/).Example 2: This example defines a buffer image called NUM1. The associatedmodule in which you include the code for NUM1 should be called 3203NUM1ASSEMBLE. Insert the following code in 3203NUM1 ASSEMBLE:416 z/VM: CP Planning and Administration

Creating and Modifying Image LibrariesEX02 CSECTSPACECOPY HCPCWOEQCOPY HCPEQUATSPACEEX02 CSECT ,UCSI NUM1DC 24C’1234567890’DC X’00101010101010101010004000404000’ 240-255DC X’40101010101010101010004040400000’ 256-271DC X’40401010101010101010004000000000’ 272-287DC X’10101010101010101010000000404000’ 288-303UCSICCW NUM1,3203,(60,60,60,60)END NUM1The NUM1 print buffer consists of twenty-four 10-character entries. If, after3203NUM1 ASSEMBLE is reloaded, you enter the command:loadbuf 00e ucs num1 verfour lines of 60 characters (the 10-character string repeated six times) are printed toverify the buffer load.Examples of New 3211 UCS Buffer Images: This example defines a bufferimage called A11. The associated module in which you include the code for A11should be called 3211A11 ASSEMBLE.Enter the following code for the A11 UCS buffer image in 3211A11 ASSEMBLE:ALL CSECTSPACECOPY HCPCWOEQCOPY HCPEQUATSPACEALL CSECT ,* a11 standard commercial 48 graphics 3211UCSI ALLDC 9C’1

Creating and Modifying Image LibrariesP48 CSECTSPACECOPY HCPCWOEQCOPY HCPEQUATSPACEP48 CSECT ,* ’usa ebcdic 48 character’UCSI P48SPACE* 0 1 2 3 4 5 6 7 8 9 a b c d e fDC X’F1F2F3F4F5F6F7F8F9F07B7C61E2E3E4’ 000DC X’E5E6E7E8E9506B6CD1D2D3D4D5D6D7D8’ 010DC X’D9605B5CC1C2C3C4C5C6C7C8C94E4B7D’ 020DC X’F1F2F3F4F5F6F7F8F9F07B7C61E2E3E4’ 030DC X’E5E6E7E8E9506B6CD1D2D3D4D5D6D7D8’ 040DC X’D9605B5CC1C2C3C4C5C6C7C8C94E4B7D’ 050DC X’F1F2F3F4F5F6F7F8F9F07B7C61E2E3E4’ 060DC X’E5E6E7E8E9506B6CD1D2D3D4D5D6D7D8’ 070DC X’D9605B5CC1C2C3C4C5C6C7C8C94E4B7D’ 080DC X’F1F2F3F4F5F6F7F8F9F07B7C61E2E3E4’ 090DC X’E5E6E7E8E9506B6CD1D2D3D4D5D6D7D8’ 0A0DC X’D9605B5CC1C2C3C4C5C6C7C8C94E4B7D’ 0B0DC X’F1F2F3F4F5F6F7F8F9F07B7C61E2E3E4’ 0C0DC X’E5E6E7E8E9506B6CD1D2D3D4D5D6D7D8’ 0D0DC X’D9605B5CC1C2C3C4C5C6C7C8C94E4B7D’ 0E0DC X’F1F2F3F4F5F6F7F8F9F07B7C61E2E3E4’ 0F0DC X’E5E6E7E8E9506B6CD1D2D3D4D5D6D7D8’ 100DC X’D9605B5CC1C2C3C4C5C6C7C8C94E4B7D’ 110UCSICCW P48,3262,(48,48,48,48,48,48)END P48Forms Control Buffers Supplied by IBMz/VM provides three FCB images: FCB1, FCB8, and FCBS. These FCBs arelocated in assemble files of the form nnnnxxxx ASSEMBLE, where:v The variable nnnn is the printer typev The variable xxxx is the buffer image name.For example, the FCB1 buffer image associated with the 4248 printer is located in4248FCB1 ASSEMBLE.Adding a New Forms Control BufferTo add a new forms control buffer for your real or virtual printer, use the FCBmacroinstruction. This macroinstruction applies to the following printers:3203 Model 5Devices that emulate the 32113262 Model 542454248.When you add a new FCB, make sure you follow the naming conventions givenunder “Naming Conventions for UCS Buffer Images and FCBs” on page 416. Theformat of the FCB macroinstruction for the printers listed above is:418 z/VM: CP Planning and Administration

Creating and Modifying Image Libraries►►labelFCB,6fcbname, ,length, ( ▼ line,channel )8 ,index►◄fcbnameis the name of the forms control buffer. The variable fcbname can be 1 to 4alphanumeric characters in length.spaceis the number of lines per inch. Valid specifications are 6 and 8. This operandcan be omitted; the default is six lines per inch. When the space operand isomitted, a comma (,) must be coded. This operand has no meaning for a virtualprinter.lengthis the number of print lines per page or carriage tape (2 to 255).(line,channel...)shows which print line (line) corresponds to each channel (channel). The valuesfor channel range from 1 to 12. The entries can be specified in any order.indexis an index value from 1 to 31. The variable index specifies the print positionthat is to be the first printed position. It is valid only for devices that emulate the3211 printer.To create the text deck that will add a new FCB:1. Code the FCB macroinstruction in the appropriate assemble file.2. Process the assemble file with the VMFHASM utility. The output of VMFHASMis a text deck. If you have the H Assembler then use the VMFHASM command.If you have the High Level Assembler then use the VMFHLASM command. Formore information on VMFHASM or VMFHLASM, see “Using VMFHASM orVMFHLASM to Create a Text Deck” on page 422.Notes:1. If you code the FCB macroinstruction with more than one channel designatedfor one print line, the macroinstruction includes only the last channel in thebuffer for that print line. (A buffer byte can only be loaded with one channelcode.)2. The forms control buffer must have compatibility with channel 1; that is, channel1 and line 1 must be the same physical line for all FCBs that are built. If theyare not, the forms will be misaligned.3. Each FCB assemble file should only contain one FCB or messageHCPCSB241E will be issued when you try to load any FCB other that the firstFCB into the printer.4. Make sure you access the disk that contains the HCPOM2 MACLIB beforeassembling your file. The HCPOM2 MACLIB contains the CP version of theFCB MACRO. Otherwise, the CMS version of the FCB MACRO might be foundin the DMSOM MACLIB and that will not create a valid text deck.ExampleCode the FCB macroinstruction (using the name SPEC), if you want:v Your printer to print 8 lines per inchChapter 14. Creating and Modifying Image Libraries for Printers 419

Creating and Modifying Image Librariesv Your printer to print 60 lines per pagev Channel 1 to correspond to print line 1v Channel 12 to correspond to print line 40v Channel 9 to correspond to print line 60v Print position 10 to be the first print position.fcb spec,8,60,(1,1,40,12,60,9),10If you want another forms control buffer, called LONG, to be exactly the same asSPEC with the exception that only six lines are printed per inch, code either of thefollowing:fcb long,6,60,(1,1,40,12,60,9),10fcb long,,60,(1,1,40,12,60,9),10Adding an Extended Forms Control Buffer for the 4248 PrinterTo add an extended forms control buffer for your real or virtual 4248 printer, use thefollowing format of the FCB macroinstruction:►►labelFCB fcbname, U ,lengthLMH►►,(1) A,( ▼ li, , ), ,ch sp offset 71 ,2 133 1925►◄Notes:1 The li,ch,sp values are positional; therefore, if the ch or sp or both values are omitted, theseparator commas are required to maintain the proper positioning. However, if on the lastline-channel-space definition the ch and sp values are omitted, the separator commas are notrequired, or if the sp value is omitted the separator comma is not required.fcbnameis the name of the forms control buffer. The variable fcbname can be from 1 to4 alphanumeric characters in length.speedis the speed at which the 4248 printer runs. The value of speed must be one ofthe following:ValueULMHMeaningUnchangedLowMediumHigh420 z/VM: CP Planning and Administration

Creating and Modifying Image Librarieslengthis the number of lines on the output page (2 to 256).li,ch,spis the information that defines a line in the FCB. You can specify multiple linesby separating the lines with commas. Enclose the entire line definition with onepair of parentheses.li specifies the line number on the page. This must be between 1 and thevalue you specified for length.ch specifies the channel code (1 to 12), or can be omitted. If you omit thisoperand, no channel is defined on this line.sp specifies the lines-per-inch (LPI) spacing. Spacing is variable with each line.Acceptable values are 6 and 8; or, you can omit this operand. If omitted,the line spacing already in effect does not change.offsetspecifies the character position in which the duplicate copy begins if you requirethe duplicate feature. If you omit this operand, no duplicate copy prints.levelscontrols the level of the paper stacker. Acceptable values are:Value MeaningA Automatic stacker level control, which is the default1 Paper tray lowered 1 inch below automatic position2 Paper tray lowered 2 inches below automatic position3 Paper tray lowered 3 inches below automatic positionratespecifies the paper stacker drop rate. Acceptable values are:Value Meaning7 Drop the paper tray after seven sheets, which is the default13 Drop the paper tray after 13 sheets19 Drop the paper tray after 19 sheets25 Drop the paper tray after 25 sheetsNote: If you specify the automatic stacker level control, the stacker drop rate isignored.Notes:1. If you code the FCB macroinstruction with more than one channel designatedfor one print line, the macroinstruction includes only the last channel in thebuffer for that print line. (A buffer byte can only be loaded with one channelcode.)2. The forms control buffer must have compatibility with channel 1; that is, channel1 and line 1 must be the same physical line for all FCBs that are built. If theyare not, the forms will be misaligned.3. Each FCB assemble file should only contain one FCB or messageHCPCSB241E will be issued when you try to load any FCB other that the firstFCB into the printer.4. Make sure you access the disk that contains the HCPOM2 MACLIB beforeassembling your file. The HCPOM2 MACLIB contains the CP version of theFCB MACRO. Otherwise, the CMS version of the FCB MACRO might be foundin the DMSOM MACLIB and that will not create a valid text deck.ExampleChapter 14. Creating and Modifying Image Libraries for Printers 421

Creating and Modifying Image LibrariesIf you want:v Your printer to run at medium speed, print 8 lines per inch, and 60 lines per pagev Channel 1 to correspond to print line 1v Channel 12 to correspond to print line 40v Channel 9 to correspond to print line 60v To begin the duplicate copy at position 67v To set the paper tray 2 inches below the automatic positionv To drop the paper tray after 25 sheets.code the FCB macroinstruction (using the name SPEC) as:fcb spec,m,60,(1,1,8,40,12,,60,9),67,2,25If you want another forms control buffer, called LONG, to be exactly the same asSPEC with the exception that, at line 40, the spacing be 6 lines per inch, code thefollowing:fcb long,m,60,(1,1,8,40,12,6,60,9),67,2,25Using VMFHASM or VMFHLASM to Create a Text DeckAfter you have created the appropriate assemble files to modify a UCS or FCBbuffer image, use the VMFHASM or VMFHLASM EXEC to create a text deck. If youhave the High Level Assembler then use the VMFHLASM command. If you havethe H Assembler then use the VMFHASM command. ExampleTo create a text deck from the file 3203PN ASSEMBLE, enter:vmfhlasm 3203pn fnwhere:3203pnis the file name of the 3203PN ASSEMBLE file.fn is the file name of a control file whose file type is CNTRL. You can create yourown control file or you can use the HCPVM CNTRL file that is supplied by IBM.Refer to z/VM: VMSES/E Introduction and Reference for the format of a controlfile. The important thing about the control file that you use is that the CPmaclibs should precede the CMS maclibs on the "MACS" statement.Specifically, HCPOM2 must precede DMSOM so that the correct FCB MACROis used for the assembly.VMFHASM or VMFHLASM creates the file 3203PN TEXT, which you can then useto create an image library.For more information on the VMFHASM or VMFHLASM execs see the z/VM:VMSES/E Introduction and Reference book. For information on image libraries, see“Installing Your Own Image Library” on page 423.ImageLibrariesThis section describes the tasks associated with image libraries.Default Image Library NamesThe default image library used for a printer is IMAGnnnn, where nnnn is the devicetype of the printer.422 z/VM: CP Planning and Administration

Creating and Modifying Image LibrariesSome types of printers may be configured to emulate another type of printer. Inthese cases, nnnn is the device type of the emulated printer, because that is thedevice type that is defined to CP. For example, a 4248 may emulate a 3211. In thiscase, the default image library is IMAG3211 because the printer is defined to CP asa 3211.Whether you use the default image library name or override the default byspecifying a name on either the RDEVICE statement or CP START command,before an image library can be used, it must be installed as described below.Installing the Image Library That IBM ProvidesAs part of the z/VM System DDR tapes or CD-ROM, IBM provides sample imagelibrary control files. For example, the image library control file for a 3800 printer is ina CMS file named IMAG3800 CNTRL. These control files are normal CMS files thatcan reside in an accessed Shared File System directory or on a minidisk. If you findthat these control files do not meet your needs, you can change them or createyour own. Whether you use the control files supplied by IBM or create your own,you must issue the IMAGELIB utility to install the image library associated withthose control files. “Installing Your Own Image Library” below describes how to dothis.For additional information on the IMAGELIB utility, refer to the z/VM: CP Commandsand Utilities Reference book.Installing Your Own Image LibraryUse the IMAGELIB utility to install your own image library or the image libraryprovided by IBM. Before you issue IMAGELIB, you must create a control file whosefile name is the same as the image library you want to build and whose file type isCNTRL. The control file is a normal CMS file that can reside in an accessed sharedfile system directory or on a minidisk. The format of this file is one statement pertext deck you want included, with names in columns 1 to 8.The general format of IMAGELIB is as follows:imagelib libnameThe variable libname is the 1- to 8-character alphanumeric file name of theimage library you want to install. (Keep in mind that image library members mustbe in files with a file type of TEXT, and the names of the library parts must be ina CNTRL file.)Example 1To install an image library for which the components are listed in the file named3800LIB1 CNTRL, enter:imagelib 3800lib1Example 2To install an image library for which the components are listed in the file named3203LIB2 CNTRL, enter:imagelib 3203lib2For additional information about the IMAGELIB utility, refer to the z/VM: CPCommands and Utilities Reference book.Chapter 14. Creating and Modifying Image Libraries for Printers 423

Creating and Modifying Image LibrariesModifying Image LibrariesUse the IMAGEMOD utility to alter existing image libraries or to create a map of animage library. For additional information about the IMAGEMOD utility, refer to thez/VM: CP Commands and Utilities Reference book.Adding Files to an Image LibraryUse the ADD operand of IMAGEMOD to add files to an existing image library. Forexample, to ADD the images XT10 and XT12, from the IBM supplied text decksXTB1XT10 and XTB1XT2, to the image library named IMAG3800, enter:IMAGEMOD ADD IMAG3800 XTB1XT10 XTB1XT12Note: For names of other IBM supplied images for the 3800, refer to “Creating TextDecks for the 3800” on page 411.Deleting Members from an Image LibraryUse the DEL operand of IMAGEMOD to delete members from an existing imagelibrary. For example, to delete the members named XTB1ODA and XTB1ONA fromthe image library named IMAG3800, enter:IMAGEMOD DEL IMAG3800 XTB1ODA XTB1ONAReplacing Members or Modules in an Image LibraryUse the REP operand of IMAGEMOD to replace existing modules of an imagelibrary with modules of the same name. For example, to replace the modulesnamed XTB1GS10, XTB1GS12, and XTB1GS15, enter:IMAGEMOD REP IMAG3800 XTB1GS10 XTB1GS12 XTB1GS15Creating an Image Library MapUse the MAP operand of the IMAGEMOD command to create a map of an imagelibrary. Use the TERM, PRINT, and DISK options to specify where you want themap sent. Example 1To create a map of an image library named IMAG3800 and send the map to yourconsole, enter:imagemod map imag3800 (termExample 2To create a map of an image library named IMAG3211 and send the map to yourvirtual printer, enter:imagemod map imag3211 (printExample 3To create a map of an image library named IMAG3800 and place the map in aCMS file on your A disk, enter:imagemod map imag3800 (diskNote that the map will be contained in a file named IMAG3800 MAP A5.Displaying Information about Image LibrariesUse the QUERY IMG command to display information about your image libraries.(Note that QUERY IMG can be entered by class A, B, C, D, and E users.)For example, to display information about all of your image libraries, enter:424 z/VM: CP Planning and Administration

Creating and Modifying Image Librariesquery img allTo display information about a particular image library, for example, the one namedIMAG3800, enter:query img name imag3800In response to these commands, CP displays information similar to the following:OWNERID FILE TYPE CL RECS DATE TIME FILENAME FILETYPE ORIGINIDuserid spid IMG c nnnn mm/dd hh:mm:ss filename filetype originidFor the meanings of these fields, refer to the z/VM: CP Commands and UtilitiesReference book.Purging Image LibrariesUse the PURGE IMG command to get rid of unwanted files that contain imagelibraries. (Note that PURGE IMG can be entered by class A, B, C, D, and E users.)For example, to purge a 3800 image library named IMAGTEST, enter:purge img name imagtestAfter this command is entered, CP purges IMAGTEST unless a printer is still usingit. If a printer is still using IMAGTEST, CP places the file in a pending-purge state.CP purges the file as soon as the printer releases it.To determine whether a file is in pending-purge state, enter the QUERY IMGcommand. If the file is in pending-purge state, CP’s response shows that the file isclass P.Keeping Backup Copies of Image LibrariesCP uses system spooling space to store image libraries. Because you may notalways be able to recover spooling space after a CP abnormal termination, youshould use the CP SPXTAPE command to keep backup copies of image librarieson tape. (Note, however, that the system tries to preserve system data files [SDFs]over a cold start.) For more information, see the z/VM: System Operation or z/VM:CP Commands and Utilities Reference books.Where to Find More Information about PrintersFor information on using the GENIMAGE utility to create text decks that contain3800 FCB images, copy modifications, character arrangement tables, graphiccharacter modifications, and library character sets, see the z/VM: CP Commandsand Utilities Reference book.For information on operating a 3800 printer as a real spooling device, see the z/VM:System Operation book.For detailed information on the 3800 printer itself, see:v Introducing the IBM 3800 Printing Subsystem and Its Programmingv IBM 3800 Printing Subsystem Programmer’s Guide, OS/VS1, OS/VS2v Reference Manual for the IBM 3800 Printing Subsystem.For more information on other printers mentioned in this chapter, see:v IBM 3203 Printer Model 5 Component Description and Operator’s Guidev IBM 3262-1/11 Printer Component DescriptionChapter 14. Creating and Modifying Image Libraries for Printers 425

Creating and Modifying Image Librariesv IBM 3262-2/12 Printer Component Descriptionv IBM 3262-3/13 Printer Component Descriptionv IBM 3262-1/11 Printer Operator’s Guidev IBM 3262-2/12 Printer Operator’s Guidev IBM 3262-3/13 Printer Operator’s Guidev IBM 4245-1 Printer Component Description and Operator’s Guidev IBM 4248-1 Printer Operator’s Introduction and Referencev IBM 4248-2 Printer Operator’s Introduction and Reference.426 z/VM: CP Planning and Administration

Chapter 15. CCW TranslationUsing CCW TranslationThis chapter describes how to code the macroinstructions used at installation timeto change the way CP handles CCWs.An installation can control how CP handles specific CCWs. CP uses a set of tablesto translate the guest’s virtual channel programs into real channel programs that CPissues to the real device. These tables identify the characteristics of each CCWcommand (00 - FF) for the device class and type. An installation with onlysupported DASDs would not need to alter these tables. However, if the installationcontains devices that act slightly different from supported DASD, a systeminstallation programmer would want to slightly alter specific CCW entries in thesetables.The table name is the same as the file name of an ASSEMBLE file that must beupdated, assembled, and incorporated in place of the standard table TEXT filewhen building the CP system.Table 14 shows the table module’s file name and the macroinstruction nameassociated with each device class.Table 14. Table and Macroinstruction Names for Device ClassesTable Macroinstruction Device ClassHCPTCS HCPCHSCD Check sorterHCPTDD HCPDDPCD Dedicated DASDHCPFBD HCPDDPCD Dedicated FBA DASDHCPTUD HCPDDPCD DASD, unsupportedHCPTMD HCPMDPCD MinidiskHCPFBM HCPMDPCD FBA MinidiskHCPTTP HCPTPPCD TapeHCPUTT HCPTPPCD Tape, unsupportedHCPTMT HCPCONCD Terminal, 3215HCPTMT HCPDSPCD Terminal, 3270HCPTMT HCPTRMCD Terminal, TERMHCPTUT HCPTRMCD Terminal, unsupportedHCPTUR HCPURPCD Unit recordHCPUUR HCPURPCD Unit record, unsupportedCoding the Device Class MacroinstructionTo code a device macroinstruction to change the way that CP handles a specificCCW for the device:1. Display the filename ASSEMBLE file for the device class. (The filename is thesame as the table name in Table 14 for the device class. For example, to viewthe information for minidisks, display the HCPTMD ASSEMBLE file.)2. Locate the table name associated with the device type and model you want tochange. The table name appears in the specifications section of the assemblefile listing. For example, the table name for 9345 minidisks is TMD93451. Thespecification section of the assemble file contains other information and notesthat you may want to review; for example, the device macroinstructionparameters that are valid for the device class.© Copyright IBM Corp. 1991, 2004 427

CCW TranslationUnsupported Devices Tables3. Locate the CCW entry within the table that you want to change.4. Code the CCW exactly as it appears in the filename ASSEMBLE file but changethe conditions to satisfy your needs. You must code a change for each CCWyou want to redefine. See “Device Macroinstruction” on page 429 for the validparameter choices.5. When all CCW changes are coded, code one more entry with LAST=YES.6. Assemble the changed table and include the generated text deck when buildingthe CP system nucleus.The unsupported device tables each contain one table for how CP should treat thatclass of unsupported device. All unsupported devices of the same class are treatedidentically.CP treats an unsupported DASD, for example, in many of the same ways that ittreats a supported dedicated DASD. The only exceptions are those specified in theunsupported DASD table. CP handles channel program CCWs as you specifiedthem in the table.428 z/VM: CP Planning and Administration

CCW TranslationDevice Macroinstruction►► tname mnameLAST=NOYES►◄▼CCW=cmd,DATAXFR= NO,DIAGNOS= YES,MULTI=PREPROC=RONLY=SEEKREQ=SIMULAT=SPECIAL=STATMOD=SYSBUSY=VALID=MODE= LINE,FULL,BOTH,TYPE= WRITE,READ,SELECT,CTRL,Parameterstname mnameidentifies the device translation table and macroinstruction for the device class.These must match the table and macroinstruction names shown in Table 14 onpage 427. These cannot be changed because CP code references thesenames.CCW=cmdidentifies the command code. The cmd is expressed in hex in the range X'00' toX'FF'.DATAXFER=NODATAXFER=YESindicates if the command causes a data transfer on the channel.DIAGNOS=NODIAGNOS=YESindicates if the command is a diagnostic CCW.MULTI=NOMULTI=YESindicates if the command is a multitrack operation. This is an internal CP flag.PREPROC=NOPREPROC=YESindicates if preprocessing is required. This is an internal CP flag.RONLY=NORONLY=YESindicates if the command is prohibited (command rejected) on a read-onlydevice.Chapter 15. CCW Translation 429

CCW TranslationSEEKREQ=NOSEEKREQ=YESindicates if orientation is required. That is, this CCW must have been precededin the channel program by a SEEK CCW.SIMULATE=NOSIMULATE=YESindicates if CCW simulation is required. This is an internal CP flag.SPECIAL=NOSPECIAL=YESindicates that further checking is required, such as:v Certain opcodes need no data translationv Certain opcodes must be first in the channel programv For certain opcodes, user class is checked.This is an internal CP flag.STATMOD=NOSTATMOD=YESindicates if the device can set STATUS MODIFIED.SYSBUSY=NOSYSBUSY=YESindicates if the command is allowed to be issued to a tape device that iscurrently marked as busy with a system function such as SPXTAPE. If it is notallowed, a unit check is returned with command reject set in the sense data.VALID=NOVALID=YESindicates if the command is valid. VALID=NO causes a command reject for thisCCW.MODE=LINEMODE=FULLMODE=BOTHindicates the screen mode.TYPE=WRITETYPE=READTYPE=SELECTTYPE=CTRLindicates type of command.LAST=NOLAST=YESindicates if this is the last invocation for a particular device table. It must bespecified as YES for the last invocation in order to generate a device table.ExamplesExamples are not provided because you should be using the ASSEMBLE files asthe base for your changes.You cannot create new tables, labels, device classes, or supported device types.You can modify only existing tables and entries.430 z/VM: CP Planning and Administration

Part 3. User Planning and AdministrationChapter 16. Redefining Command Privilege Classes . . . . . . . . . 433IBM-Defined Privilege Classes . . . . . . . . . . . . . . . . . . . 433Planning a New User Class Structure . . . . . . . . . . . . . . . . 434Defining Users’ Needs . . . . . . . . . . . . . . . . . . . . . 434Assigning Commands to Types of Users . . . . . . . . . . . . . . 435Associating Privilege Classes with Users and Commands . . . . . . . . 436Further Considerations . . . . . . . . . . . . . . . . . . . . 437Preparing and Activating the Override File . . . . . . . . . . . . . . 438Creating a Class Override File . . . . . . . . . . . . . . . . . . 438Class Override File Example . . . . . . . . . . . . . . . . . . 439Verifying and Activating the Override File . . . . . . . . . . . . . . 441Querying the User Class Restructure File . . . . . . . . . . . . . . 442Changing Back to the IBM-Defined User Classes . . . . . . . . . . . 442Another Way of Changing the Privilege Class of Certain CP Functions 443Changing the Directory . . . . . . . . . . . . . . . . . . . . . 443Defining Privilege Classes for a Virtual Machine . . . . . . . . . . . 444Changing the Setting for a Logged-On Virtual Machine . . . . . . . . 444Changing the User Directory . . . . . . . . . . . . . . . . . 444How Users Can Find Which Commands They Can Enter . . . . . . . . 446Chapter 17. Creating and Updating a User Directory . . . . . . . . . 447Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 447Creating the User Directory . . . . . . . . . . . . . . . . . . . . 451Continued Directory Control Statements . . . . . . . . . . . . . . . 452Quoted String Operands . . . . . . . . . . . . . . . . . . . . . 452Running the User Directory Program . . . . . . . . . . . . . . . . 453Changing the Directory . . . . . . . . . . . . . . . . . . . . . 454Checking a Directory for Errors . . . . . . . . . . . . . . . . . . 454Specifying a Directory That Contains VM/SP Control Statements . . . . . . 455Creating Directory Profiles . . . . . . . . . . . . . . . . . . . . 455Determining How Much Space the Directory Needs . . . . . . . . . . . 455ACCOUNT Directory Control Statement (General) . . . . . . . . . . . 456ACIGROUP Directory Control Statement (General) . . . . . . . . . . . 458APPCPASS Directory Control Statement (General) . . . . . . . . . . . 459AUTOLOG Directory Control Statement (General) . . . . . . . . . . . 461CLASS Directory Control Statement (General) . . . . . . . . . . . . . 462CONSOLE Directory Control Statement (Device) . . . . . . . . . . . . 463CPU Directory Control Statement (General) . . . . . . . . . . . . . . 465CRYPTO Directory Control Statement (General) . . . . . . . . . . . . 468DASDOPT Directory Control Statement (Device) . . . . . . . . . . . . 472DATEFORMAT Directory Control Statement (General) . . . . . . . . . . 475DEDICATE Directory Control Statement (Device) . . . . . . . . . . . . 477DIRECTORY Directory Control Statement (Control) . . . . . . . . . . . 480D8ONECMD Directory Control Statement (General) . . . . . . . . . . . 483GLOBALDEFS Directory Control Statement (Control) . . . . . . . . . . 485GLOBALOPTS Directory Control Statement (Control) . . . . . . . . . . 486INCLUDE Directory Control Statement (General) . . . . . . . . . . . . 487IOPRIORITY Directory Control Statement (General) . . . . . . . . . . . 488IPL Directory Control Statement (General) . . . . . . . . . . . . . . 490IUCV Directory Control Statement (General) . . . . . . . . . . . . . 493LINK Directory Control Statement (Device) . . . . . . . . . . . . . . 500LOAD Directory Control Statement (Control) . . . . . . . . . . . . . 504LOADDEV Directory Control Statement (General) . . . . . . . . . . . 507© Copyright IBM Corp. 1991, 2004 431

432 z/VM: CP Planning and AdministrationLOGONBY Directory Control Statement (General) . . . . . . . . . . . 509MACHINE Directory Control Statement (General) . . . . . . . . . . . . 510MAXSTORAGE Directory Control Statement (General) . . . . . . . . . . 512MDISK Directory Control Statement (Device) . . . . . . . . . . . . . 513MINIOPT Directory Control Statement (Device) . . . . . . . . . . . . 524NAMESAVE Directory Control Statement (General) . . . . . . . . . . . 527NICDEF Directory Control Statement (Device) . . . . . . . . . . . . . 529NOPDATA Directory Control Statement (General) . . . . . . . . . . . . 532OPTION Directory Control Statement (General) . . . . . . . . . . . . 533POOL Directory Control Statement (General) . . . . . . . . . . . . . 540POSIXGLIST Directory Control Statement (General). . . . . . . . . . . 541POSIXGROUP Directory Control Statement (Control) . . . . . . . . . . 543POSIXINFO Directory Control Statement (General) . . . . . . . . . . . 545POSIXOPT Directory Control Statement (General) . . . . . . . . . . . 548PROFILE Directory Control Statement (Control) . . . . . . . . . . . . 551SCREEN Directory Control Statement (General) . . . . . . . . . . . . 553SHARE Directory Control Statement (General) . . . . . . . . . . . . . 555SPECIAL Directory Control Statement (Device) . . . . . . . . . . . . 557SPOOL Directory Control Statement (Device) . . . . . . . . . . . . . 562SPOOLFILE Directory Control Statement (General) . . . . . . . . . . . 565STDEVOPT Directory Control Statement (General) . . . . . . . . . . . 566STORAGE Directory Control Statement (General) . . . . . . . . . . . 568SYSAFFIN Directory Control Statement (Control) . . . . . . . . . . . . 569USER Directory Control Statement (Control) . . . . . . . . . . . . . 572XAUTOLOG Directory Control Statement (General) . . . . . . . . . . . 578XCONFIG Directory Control Statement (General) . . . . . . . . . . . . 580XCONFIG ACCESSLIST Operand . . . . . . . . . . . . . . . . . 581XCONFIG ADDRSPACE Operand . . . . . . . . . . . . . . . . . 583XSTORE Directory Control Statement (General) . . . . . . . . . . . . 585

Chapter 16. Redefining Command Privilege ClassesThe user class restructure feature allows an installation to extend the privilege-classstructure of CP commands, DIAGNOSE codes, and certain CP system functionsfrom eight classes to as many as 32 classes. By creating a more elaborate classstructure, an installation gains greater control over the functions that each user canperform. The user classes can thus become more focused and specialized,increasing system integrity and security.Note: An installation can place override requests into a system configuration file byusing MODIFY statements. However, you should use either the OVERRIDEutility or the MODIFY statements. If any MODIFY statement is detected atIPL time, the UCR (User Class Restructure) override changes will bebypassed. IBM recommends using the new MODIFY statements. For moreinformation on this method of extending the privilege-class structure of asystem, see the z/VM: CP Exit Customization book.This chapter tells you how to:v Use the user class restructure featurev Plan a new user class structurev Prepare and activate an override filev Display information about the current user class structurev Change back to the default IBM-defined class structurev Change the user directories.To redefine your user class structure, do the following:1. Plan your new structure by identifying each user group and the functions thatthey need to perform.IBM-Defined Privilege Classes2. Prepare an override file. This is a CMS file that contains a list of all commands,DIAGNOSE codes, and system functions for which you wish to define newclasses.3. Update the directory to assign the new classes to each user’s virtual machine.These steps are described in more detail in the sections that follow.z/VM CP commands are divided into eight groups, each represented by a privilegeclass. The privilege class indicates the type of user from whom the system acceptscommands.In general, the system programmer who creates the system directory assigns eachuser one or more privilege classes as part of the user’s entry in that directory.Privilege classes are denoted by the letters A through Z, the numbers 1 through 6,or the word “Any”. These classes, and the type of user who uses the commandsbelonging to each privilege class set, are summarized in Table 15 on page 434.Classes I through Z and numbers 1 through 6 are reserved so that your installationcan define them to suit its needs.Users whose password is NOLOG have no privilege class and can only receivespooled output as punched cards or printed forms. The NOLOG assignment© Copyright IBM Corp. 1991, 2004 433

Redefining Command Privilege Classescontrolled by directory control statements; see “USER Directory Control Statement(Control)” on page 572 for more information about NOLOG users.Table 15. IBM-Defined Privilege ClassesClass User and FunctionA System Operator: The class A user controls the z/VM system. The systemoperator is responsible for the availability of the z/VM system and itsresources. In addition, the system operator controls system accounting,broadcast messages, virtual machine performance options, and otheroptions that affect the overall performance of z/VM.Note: The class A user who is automatically logged on during CPinitialization is designated as the primary system operator.B System Resource Operator: The class B user controls all the real resourcesof the z/VM system, except those controlled by the system operator and thespooling operator.C System Programmer: The class C user updates or changes system-wideparameters of the z/VM system.D Spooling Operator: The class D user controls spool files and the system’sreal reader, printer, and punch equipment allocated to spooling use.E System Analyst: The class E user examines and saves system operationdata in specified z/VM storage areas.F Service Representative: The class F user obtains, and examines in detail,data about input and output devices connected to the z/VM system. Thisclass is reserved for IBM use.G General User: The class G user controls functions associate with a particularvirtual machine.Any Commands belonging to class “Any” are available to any user, regardless ofthe user’s privilege class. These commands are primarily those used to gainaccess to, or relinquish access from, the z/VM system.H Reserved for IBM use.I - Z 1 - 6 Classes I through Z are reserved for redefinition through user classrestructure as needed by each installation.Planning a New User Class StructureWhile planning the new class structure, you should:v Define each user’s needsv Assign commands to types of usersv Associate privilege classes with users and commandsDefining Users’ NeedsThe first step in restructuring command classes is to determine the different typesof users and what types of functions each user needs to perform.Consider a fictional insurance company with a variety of users and jobresponsibilities. The installation has decided to define a new class structure. Thesystem administrator examines the users’ needs and produces the categories asshown in Table 16 on page 435.434 z/VM: CP Planning and Administration

Redefining Command Privilege ClassesTable 16. A Sample Scenario: Different System Users and Their ResponsibilitiesJob Title Abbreviation DutiesSystemadministratorSenior systemprogrammersJunior systemprogrammersSAD General management of the system anddetermining how the system will be structuredand used.SSP Planning, generating, maintaining, extending, andcontrolling the use of the operating system withthe aim of improving the general productivity ofthe installation.JSP Similar to senior system programmers, but withless control over the system.System analysts SA Analyzing the system to determine what newapplications, system programs, and devices areneeded by the installation.Primary systemoperatorsDatabaseadministratorSO Ensuring the smooth running of the system andcarrying out such duties as changing tapes anddisk packs.DBA Administering resources associated with, andhaving access to, the main database of thesystem, and resources associated with spooling,printing, and archiving.Service engineers SE Obtaining and examining certain data about I/Odevices connected to the system. Also,controlling intensive error recording and somemachine check error recording.General users U1, U2 Two different types of general users with differentrequirements were identified, the first moresophisticated than the second. (All users, even ifclassified above, will also be classified as onetype of general user.)Assigning Commands to Types of UsersAfter you have produced these categories, you need to list all the commands,DIAGNOSE codes, and system functions that each user group will need to execute.In our insurance company example, the system administrator produces a list ofcommands with the user types listed across the top. (For the sake of brevity, thetable presented here lists only a few commands. In reality, all CP commands,DIAGNOSE codes, and system functions should be listed, except those with anIBM-defined class of ANY.) After you have produced this list, you need to identifywhich commands you want each user type to be able to access. For our example,an asterisk (*) is placed in the column for each user that should have access to thecommand in the first column. See Table 17 on page 436.Chapter 16. Redefining Command Privilege Classes 435

Redefining Command Privilege ClassesTable 17. Example of How to Assign Commands, Diagnose Codes, and System Functions to Types of UsersCommandIBM-DefinedClass New Class SAD SSP JSP SA SO DBA SE U1 U2ACNT A *ATTN G * *XAUTOLOG A * *XAUTOLOG B * * * *XAUTOLOG G *CHANGE D * *CHANGE G * *DEDICATE A *DEFINE A *DEFINE G * *IPL G * *MESSAGE A * *MESSAGE B *SAVESYS E * *SPOOL G * *DIAG04 C,E * * * *DIAG3C A,B,C * * * *SYSDFLT G *SYSOPR A * *SYSSERV F *Notes:1. Do not list commands with an IBM-defined class ANY. You cannot limit accessto these commands.2. Some commands have more than one IBM-defined class. For a list of thesecommands, see the z/VM: CP Commands and Utilities Reference book. Youneed to list these separately so that you can assign them to different usergroups.3. Restricting the user class on a console command does not restrict the functionof the directory control statement that does the same function. For example, ifthere is a link control statement in a user’s directory, that control statementtakes effect at logon time, even though you have restricted the LINK command.Associating Privilege Classes with Users and CommandsAfter you have associated the commands with the types of users, you can assign adifferent class to each type of user. Then, each command can be assigned a list ofclasses that correspond to the users who need access. In the example table, eachasterisk is replaced by a new user class, and then these classes are collected tothe “New Class” column for each command. See Table 18 on page 437.436 z/VM: CP Planning and Administration

Redefining Command Privilege ClassesTable 18. Example of How to Associate Privilege Classes with Commands and UsersCommandIBM-DefinedClassNew Class SAD I SSP J JSP K SA L SO M DBA N SE O U1 P U2 QACNT A L LATTN G PQ P QXAUTOLOG A IJ I JXAUTOLOG B KLMN K L M NXAUTOLOG G P PCHANGE D MN M NCHANGE G PQ P QDEDICATE A J JDEFINE A M MDEFINE G PQ P QIPL G PQ P QMESSAGE A JK J KMESSAGE B M MSAVESYS E IJ I JSPOOL G PQ P QDIAG04 C,E IJKM I J K MDIAG3C A,B,C IJKL I J K LSYSDFLT G P PSYSOPR A IJ I JSYSSERV F L LAn important distinction to make here is that the user classes with access to systemfunctions and resources (classes I through O) do not have access to anycommands that are useful for controlling their own virtual machines (for example,SPOOL). Only the two general user classes (P and Q) have access to thesecommands. Class P users have more access to more powerful commands than doclass Q users. With this arrangement, the system administrator can independentlycontrol a user’s access to system and virtual machine commands. To assignclasses to each user, the system administrator defines at least two classes to keysophisticated users such as system programmers. An unsophisticated general usermight be assigned to class Q; a system programmer would be assigned to classesJ and P. In this way, the system programmer gains access to both the class Jsystem commands and to the class P virtual machine commands.Note also that whereas the class A and B MESSAGE commands are listed, theclass ANY MESSAGE command is not. User class restructure does not affect classANY commands.FurtherConsiderationsWhile customizing the command privilege class structure of your system, youshould keep in mind: Help Files You may also want to update the HELP files ifchanges to the command classes affect a class G command. See the z/VM: CMSUser’s Guide for information on tailoring the HELP Facility. DocumentationConsiderationsChapter 16. Redefining Command Privilege Classes 437

Redefining Command Privilege ClassesIf you change the privilege class for commands, DIAGNOSE codes, or systemfunctions, the privilege classes documented in this and other publications may nolonger be correct for your installation.Preparing and Activating the Override FileTo assign new privilege classes to commands, DIAGNOSE codes, and systemfunctions, you must:1. Create a class override file2. Verify the class override file syntax3. Activate the class override file immediately or at the next IPL.Creating a Class Override FileTo override the IBM-defined privilege classes for commands, DIAGNOSE codes,and system functions, first create a class override file. (The CP OVERRIDE utilityuses the default file name and file type of CLASS OVERRIDE. The OVERRIDEutility is described in the z/VM: CP Commands and Utilities Reference). This is astandard CMS file (fixed format, 80-characters wide) that contains controlstatements that override privilege class assignments.The privilege classes for the system functions are defined by the PRIV_CLASSESsystem configuration file statement. For more information, see “PRIV_CLASSESStatement” on page 184 or “SYSFCN (Optional)” on page 673.Statements in the override file have this format:►► name NEWCLASS= ▼class(1)IBMCLASS=class►◄Notes:1 NEWCLASS and IBMCLASS can be specified in any order. IBMCLASS isnecessary only for commands that have more than one IBM-defined class. It isnot required for DIAGNOSE codes and system functions.The first field of each OVERRIDE control statement is the name of the command,DIAGNOSE code (using the form DIAGxx) or system function (using the formSYSxxxx—either SYSOPER, SYSCPRD, SYSCPWT, SYSSERV, or SYSDFLT).These system functions are described in Appendix B, “Defining Your System(HCPSYS Macroinstructions),” on page 643. Make sure that this field appears firston the control statement line, with no other characters preceding it.Note: Commands defined by the system as class ANY are not valid on theOVERRIDE control statement.The next two fields may appear in either order:v The NEWCLASS= parameter, which specifies the new privilege class to beassigned. You can specify more than one new class with this parameter. Forexample, the statement NEWCLASS=HIJKL defines classes H, I, J, K, and L.If a command, diagnose code, or system function is assigned to more than oneuser class, you must specify all the classes in the NEWCLASS parameter.Example:438 z/VM: CP Planning and Administration

Redefining Command Privilege Classes1. Adding user classes to a DIAGNOSE code: To add classes A and B toDIAGNOSE code X'04', code the control statement as follows:DIAG04 NEWCLASS=ABCEThe IBM defined class is C and E; therefore, by specifyingNEWCLASS=ABCE, you are adding classes A and B to the already existingclasses C and E.v The IBMCLASS= parameter, which specifies the original IBM-defined class forthat command. Use this parameter only if the command has more than oneIBM-defined class. It is not required for commands that have only oneIBM-defined privilege class, for DIAGNOSE codes, or for system functions. Youcan specify only one class with this parameter, as the examples below illustrate.Examples:1. Changing one class to another: To change the PURGE command fromclasses A and G to A and U, code the control statement as follows:PURGE NEWCLASS=U IBMCLASS=GThis would simply replace the old class G with the new class U. The class Acommand would remain unchanged.2. Adding a class: To change the PURGE command from classes A and G toA, G, and Y, code the control statement as follows:PURGE NEWCLASS=AY IBMCLASS=AorPURGE NEWCLASS=GY IBMCLASS=GYour choice between these two possibilities would depend on which versionof the PURGE command you wish to allow the class Y user to use, either thepowerful IBM class A command or the general class G command.3. Removing a class: To change the PURGE command from classes A and Gto just A, choose a dummy class (we use Z here) and code the controlstatement as follows:PURGE NEWCLASS=Z IBMCLASS=GIf you never give any user access to class Z commands, this controlstatement effectively removes the class G PURGE command from your classstructure.Class Override File ExampleUsing our example of the insurance company from the previous section (Table 18on page 437), the override file would contain the entries shown in Figure 28 onpage 440.Chapter 16. Redefining Command Privilege Classes 439

Redefining Command Privilege Classes** CP COMMAND OVERRIDES FOR ’OUR INSURANCE COMPANY’** USER CLASSES REPRESENT:** I = SYSTEM ADMINISTRATOR (SAD)* J = SENIOR SYSTEM PROGRAMMER (SSP)* K = JUNIOR SYSTEM PROGRAMMER (JSP)* L = SYSTEM ANALYST (SA)* M = SYSTEM OPERATOR (SO)* N = DATABASE ADMINISTRATOR (DBA)* O = SERVICE ENGINEER (SE)* P = COMPLEX USERS (U1)* Q = GENERAL USERS (U2)*ACNT NEWCLASS=LATTN NEWCLASS=PQXAUTOLOG NEWCLASS=IJ IBMCLASS=AXAUTOLOG NEWCLASS=KLMN IBMCLASS=BXAUTOLOG NEWCLASS=P IBMCLASS=GCHANGE NEWCLASS=MN IBMCLASS=DCHANGE NEWCLASS=PQ IBMCLASS=GDEDICATE NEWCLASS=JDEFINE NEWCLASS=M IBMCLASS=ADEFINE NEWCLASS=PQ IBMCLASS=GIPL NEWCLASS=PQMESSAGE NEWCLASS=JK IBMCLASS=AMESSAGE NEWCLASS=M IBMCLASS=BQUERY TIME NEWCLASS=ISAVESYS NEWCLASS=IJSET NEWCLASS=J IBMCLASS=GSPOOL NEWCLASS=PQDIAG04 NEWCLASS=IJKMDIAG3C NEWCLASS=IJKLSYSDFLT NEWCLASS=PSYSOPR NEWCLASS=IJSYSSERV NEWCLASS=LFigure 28. Class Override File ExampleThe privilege classes of the individual operands of the QUERY and SET commandscan be changed independently of the other operands for those commands. To dothis, specify the command and operand of any QUERY or SET command to berestructured. In the insurance company example, the QUERY TIME command willbe changed to a new class I command. To change the privilege class for an entireset of QUERY or SET commands with the same IBM-defined privilege class, usethe IBMCLASS= operand as in the above example. Here, all IBM-defined class GSET commands are changed to new class J.You must code the IBMCLASS= operand for XAUTOLOG, CHANGE, DEFINE, andMESSAGE, as they are associated with more than one class. To assign more thanone class to a command or command type, all new classes are placed on the sameoverride control statement.Note: Restricting the user class on a console command does not restrict thefunction of the directory control statement that does the same function. Forexample, if there is a LINK control statement in a user’s directory, thatcontrol statement takes effect at logon, even though you have restricted theLINK command.440 z/VM: CP Planning and Administration

Redefining Command Privilege ClassesVerifying and Activating the Override FileTo verify that the control statements in the class override file have the correctsyntax (without actually activating the new class structure), enter OVERRIDE(IBM-defined privilege classes A, B, or C) with the VALIDATE option:override fn ft fm (validatewhere the fn ft fm identifies the class override file. The OVERRIDE utility isdescribed in the z/VM: CP Commands and Utilities Reference; the default is CLASSOVERRIDE *. If an error is detected, the statement in error is displayed, and amessage informs you what the error is.After you create the class override file and verify the syntax of the controlstatements in it, enter OVERRIDE with either the IMMEDIATE option or the DEFERoption, as follows:override fn ft fm (immediateoroverride fn ft fm (deferwhere the file name (fn), file type (ft), and file mode (fm) identify the class overridefile. (Note that the file mode can represent an accessed minidisk or an accessedshared file system directory, and that the default is CLASS OVERRIDE *.)If you enter the OVERRIDE with no options, the DEFER option (the default) isassumed.The OVERRIDE utility’s processing checks for errors using a two-pass process, asfollows:1. On the first pass, syntax errors (such as incorrectly placed options or improperlyspecified new classes) are flagged with a message informing you of the error.No matter how you entered OVERRIDE (with DEFER, IMMEDIATE, orVALIDATE), processing continues in VALIDATE mode.2. On the second pass, other errors (such as incorrectly specified IBM-definedclasses or misspelled command names) are flagged with a message identifyingthe incorrect line. Processing continues in whichever mode (DEFER,IMMEDIATE, or VALIDATE) you specified.Whereas the class override file is the file you create to specify your class structurechanges, it is the user class restructure (UCR) file that actually activates thosechanges. The UCR file is a system data file (SDF). It is acted on through theoptions on the OVERRIDE utility, as Table 19 shows.Table 19. OVERRIDE Utility OptionsOptionActionDEFER (the default) Information from the class override file is written to a user classrestructure (UCR) file. This is a class D file, meaning that the newclass structure will take effect at the next system IPL. If an old UCRfile already exists, it remains in effect until the next system IPL.IMMEDIATE Information from the class override file is written to a UCR file. This isa class I file, meaning that the new class structure takes effectimmediately, along with any changes that were previously in effect.However, the UCR file that is created will replace any existing UCRfile.Chapter 16. Redefining Command Privilege Classes 441

Redefining Command Privilege ClassesTable 19. OVERRIDE Utility Options (continued)OptionActionVALIDATE The class override file is checked for syntax errors, but no UCR file iscreated.CLEAR The existing UCR file is removed at the next system IPL. You aretherefore reverting to the IBM-defined user classes.Querying the User Class Restructure FileUse the QUERY UCR command to display information about the user classrestructure file. Enter the command as follows:query ucr all (ALL is the default)orquery ucr name filename (to query by file name)orquery ucr spoolid (to query by spool ID)The response will be displayed in the following format (it is assumed here that theoverride file was named CLASS OVERRIDE):OWNERID FILE TYPE CL RECS DATE TIME FILENAME FILETYPE ORIGINID*UCR nnnn UCR n nnnn mm/dd hh:mm:ss CLASS OVERRIDE nNote: If you enter QUERY UCR and see that a class D user restructure file exists,this tells you only that the file has been created using the DEFER option onthe OVERRIDE utility. It does not tell you whether this file has been activatedyet. (In other words, it does not tell you whether the new class structuredescribed in that UCR file has been activated yet by a new system IPL.)As an alternative, you can enter the QUERY UCR COUNT command to display thenumber of user class restructure files:query ucr countThe response line will simply tell you how many user class restructure files thereare. For example:FILES: 0001 UCRChanging Back to the IBM-Defined User ClassesIf you want to cause the commands to be assigned their IBM-defined privilegeclasses again, enter OVERRIDE with the CLEAR option, as follows:override (clearand then IPL the system.Alternatively, you can use the PURGE UCR command, as follows:purge ucr name filename (to purge a file by file name)orpurge ucr spoolid (to purge a file by spool ID)and then IPL the system.442 z/VM: CP Planning and Administration

Redefining Command Privilege ClassesIf, after reverting to the IBM-defined classes, you wish to return to the classes youdefined in the override file, activate the class override file as described on “Verifyingand Activating the Override File” on page 441.Note: If your changes are extensive, you may need to install a different directoryeach time you switch between your own class structure and the IBM-definedclass structure.Another Way of Changing the Privilege Class of Certain CP FunctionsPrivilege classes for the following CP functions can be overridden without using theclass override file:Changing the Directoryv Logging on as the primary system operatorv Intensive error recordingv Using the read function of the CP IOCP utilityv Using the write function of the CP IOCP utilityv Specifying the default user class.If you want to change some or all the privilege classes assigned to these CPfunctions, you must specify your changes by using the PRIV_CLASSES statementin the system configuration file. For more information on the PRIV_CLASSESstatement, see “PRIV_CLASSES Statement” on page 184.In our insurance company example, the classes of three system functions:v Classes for the primary system operatorv Classes authorized to perform intensive error recordingv Default classes for users who do not have a class defined in their directoryentrieswere changed. Instead of including them in the class override file, the systemadministrator could have entered either the PRIV_CLASSES statement as:PRIV_CLASSES OPERATOR IJ HW_SERVICE L USER_DEFAULT Por, the SYSFCN macroinstruction as follows:SYSFCN OPER=IJ, SERV=L, DFLT=PYou can also use the CP SET PRIVCLASS command to change the privilegeclasses for individual users, who are logged on to the system, rather than an entireclass of users. This command lets you be more selective in the privileges that yougrant users. For a brief description of the SET PRIVCLASS command, see“Changing the Setting for a Logged-On Virtual Machine” on page 444. For adetailed description of the SET PRIVCLASS and QUERY PRIVCLASS commands,see the z/VM: CP Commands and Utilities Reference book.After preparing and activating the class override file, you must update the directory,as it contains the class or classes of commands that each user can successfullyexecute. The control statements in the directory that define the command privilegeclasses for a virtual machine are the USER and CLASS statements. (For moreinformation about the directory and how to generate it, see Chapter 17, “Creatingand Updating a User Directory,” on page 447.) Use the privilege class operand ofthe USER statement to define the new privilege classes for the virtual machine.Chapter 16. Redefining Command Privilege Classes 443

Redefining Command Privilege ClassesIf you cannot fit all the new privilege classes onto the USER statement, you canadd the optional CLASS statement to the directory immediately following the USERstatement. You can define up to 32 classes.Note: Make sure you have enough free disk space before editing and makingchanges to the existing directory so that you can file the updated directory.See “Directory Space” on page 608 for information on how to allocate DASDspace for the directory.Defining Privilege Classes for a Virtual MachineThe privilege classes for a virtual machine can be changed by changing thedefinition of a logged on virtual machine or changing the definition in the userdirectory.Changing the Setting for a Logged-On Virtual MachineAuthorized users can change the privilege classes definitions for logged on virtualmachines. These users are authorized by the FEATURES ENABLESET_PRIVCLASS statement in the system configuration file. To change theprivilege classes, the user just issues the CP SET PRIVCLASS command.For example, if you want the user whose virtual machine user ID is DATABASE tobe able to use commands with the privilege classes C, D, H, and I, you wouldenter:set privclass database =cdhiThe FEATURES ENABLE SET_PRIVCLASS statement is described in “FEATURESStatement” on page 136. For more information on the SET PRIVCLASS command,see the z/VM: CP Commands and Utilities Reference book.Changing the User DirectoryTo change the definition of privilege classes for a virtual machine, perform thefollowing steps:1. Use the XEDIT command to edit the user directory. Unless you have defined adifferent file name, this file has a file ID of USER DIRECT.2. Find the USER control statement for the virtual machine whose privilege classesyou wish to change.3. This next step depends on whether you can fit all the new classes onto theUSER control statement.If you can fit all the new classes onto the USER control statement:a. Change the privilege class operand to the classes that you want this virtualmachine to have. The privilege class operand consists of EBCDICcharacters (with no intervening blanks) that can be A through Z and 1through 6. These characters define privilege classes for the virtual machine.If you do not specify a privilege class, the default is G (or whatever youhave specified using either the USER_DEFAULT operand of thePRIV_CLASSES statement in the system configuration file or the DFLToperand of the SYSFCN macroinstruction).For example, if you want the user whose virtual machine user ID isDATABASE to be able to use commands with the privilege classes C, D, H,and I, code the USER control statement as follows:USER DATABASE pass stor mstor CDHI pri le ld cd esIf you cannot fit all the new classes onto the USER control statement:a. Change the privilege class operand to an asterisk (*).444 z/VM: CP Planning and Administration

Redefining Command Privilege Classesb. Following the USER control statement, insert a CLASS control statement.The format of the CLASS control statement is described under “CLASSDirectory Control Statement (General)” on page 462.For example, if you want to assign privilege classes A through Q to a virtualmachine that belongs to a user whose user ID is SYSADM, code the USERcontrol statement and the CLASS control statement as follows:USER SYSADM pass stor mstor * pri le ld cd esCLASS ABCDEFGHIJKLMNOPQ4. After you make all the desired changes to the directory, file the directory file.5. To verify that the CMS file can be used as a directory file, enter the DIRECTXAutility with the EDIT option. (For more on the DIRECTXA utility, see “Runningthe User Directory Program” on page 453.) If you made a syntax error, you willreceive an error message.6. When you have verified that the directory file is correct, replace the old directorywith the updated directory by entering the following:directxa filenameNote: The virtual machine that enters the DIRECTXA command must havewrite access to the volume that is to contain the new directory. If youcreate a directory that is to be written on the active VM/ESA systemresidence volume, your virtual machine’s current directory entry musthave write access to the volume that contains the current directory.7. After the directory is updated, directory changes for a virtual machine currentlylogged on to the system do not take effect until the user logs off the system andthen logs back on.Directory Entry Example: For our example of the insurance company, thedirectory might include the USER and CLASS control statements shown inFigure 29 on page 446.Chapter 16. Redefining Command Privilege Classes 445

Redefining Command Privilege ClassesDIRECTORY 250 3350 VMSRES* CP DIRECTORY FOR ’OUR INSURANCE COMPANY’** NOTES:* (1) KEY TECHNICAL USERS NEED PRIVILEGE CLASS ’P’ BESIDES* THEIR PRIMARY FUNCTIONAL CLASS. THIS ENABLES THEM* TO FULLY CONTROL A VIRTUAL MACHINE. GENERAL USERS* WILL NEED ONLY CLASS ’Q’.** (2) USERID ZZZMAINT IS SET ASIDE FOR EMERGENCY USE. THIS* USER HAS ACCESS TO ANY CP COMMAND NO MATTER WHAT* OVERRIDE FILE IS APPLIED. THE PASSWORD SHOULD BE* KNOWN BY ONLY A ***VERY*** FEW KEY PEOPLE.*USER ZZZMAINT SECRET 2M 8M *CLASS ABCDEFGHIJKLMNOPQRSTUVWXYZ123456(other control statements)*USER SAD1 XXXXXXXX 2M 8M IP(other control statements)*USER SSP1 XXXXXXXX 1M 2M JP(other control statements)*USER JSP1 XXXXXXXX 1M 2M KP(other control statements)*USER JSP2 XXXXXXXX 1M 2M KP(other control statements)*USER SA1 XXXXXXXX 1M 2M LP(other control statements)*USER OPERATOR XXXXXXXX 1M 2M MP(other control statements)*.(and so on)Figure 29. Directory Entry Example Using USER and CLASS StatementsHow Users Can Find Which Commands They Can EnterTo find out which commands are available, the user can enter the QUERYCOMMANDS command. For example, if the IBM-defined classes are in effect for allcommands, a user whose virtual machine is assigned privilege class B wouldreceive a list of all class B commands, DIAGNOSE codes, and system functions, aswell as all class ANY commands.To find out what operands of the QUERY and SET commands are available, theuser can enter QUERY COMMANDS QUERY or QUERY COMMANDS SET.446 z/VM: CP Planning and Administration

Chapter 17. Creating and Updating a User DirectoryOverviewThis chapter tells you how to:v Create the z/VM user directoryv Run the user directory programv Change the directoryv Check the directory for errorsv Specify a directory that contains VM/SP control statementsv Use directory profilesv Use each of the directory control statements summarized in Table 21 on page449.The z/VM user directory describes to CP the configuration and operatingcharacteristics of each virtual machine that can be created by z/VM. A z/VM userdirectory exists in two forms: a source form that consists of one or more CMS files,and an object form, compiled from the source, on a CP-formatted disk. Multipleobject directories can be accessed by z/VM, but only one object directory may beactive (online) at any given instant.During initialization, CP checks for a valid object directory on the system residencevolume. If CP finds a valid object directory, it makes that directory the activedirectory. Otherwise, CP looks for the first valid object directory on the CP-ownedvolumes brought online during initialization. CP checks the volumes in the order oftheir appearance in the CP-owned list. If you defined the CP-owned list usingCP_OWNED statements (page 73) in your system configuration file, CP checks thevolumes based on the slot number, in increasing order. If you defined theCP-owned list using the SYSCPVOL macro (page 664) in HCPSYS, CP checks thevolumes in the order that they appear on the SYSCPVOL macro.If CP does not find a valid object directory, the system comes up with a default userID of OPERATOR. You can use this virtual machine to create a valid directory. Inthis case, you can bring a directory online by:v Entering the DIRECTXA utility to install a directory on an appropriately formattedCP-owned volumev Attaching a valid directory volume whose volume ID appears in the CP-ownedvolume list but which was not brought online during initialization.After CP has brought a directory online, the volume on which it resides remains thedirectory volume for the duration of the IPL. Rewriting a directory on a differentvolume, even one higher in the search order, has no effect. (However, a directorywritten higher in the CP-owned volume search order becomes effective when thenext hardware or software IPL occurs.)The source form of the z/VM user directory consists of directory control statements.These statements define on which CP-formatted volume the object directory will becreated, and the configuration and operating characteristics of the virtual machinesthat will be known to the target VM operating system. A single source directory maydefine an object directory for one or more VM operating systems.© Copyright IBM Corp. 1991, 2004 447

Creating and Updating a User DirectoryThe source directory consists of virtual machine definitions. The source directorycan exist in two formats: the monolithic and the cluster. The monolithic formatconsists of a single CMS sequential file that contains all of the virtual machinedefinitions. The cluster form consists of an index file that points to one or moredefinition files that contain all of the virtual machine definitions. A definition file maybe, as a group, either a separate part file, a file that contains a single USERdefinition or a single PROFILE definition, or a cluster file, a file that containsmultiple USER or multiple PROFILE definitions. The index file consists of onlyLOAD directory control statements that point to other definition files to be includedduring the compile operation.Regardless of the format used for the source directory, the directory definitions mustbe processed in the following order:DIRECTORY Definition —Which consists of one or more DIRECTORY directory control statementsthat define the output object directories.Global Definition —This section must begin with the GLOBALDEFS directory control statement.It also includes directory control statements which define global settings tobe used across all user definitions.PROFILE Definitions —Each of which begins with a PROFILE directory control statement andconsolidates other directory control statements that are commonly usedacross multiple users.USER Definitions —(Also called virtual machine definitions) each of which begins with a USERdirectory control statement and defines an individual virtual machine.The Global definition section may appear only after all DIRECTORY statements andbefore any PROFILE or USER statements. The PROFILE and USER definitionsconsist of different types of control statements: control, general, and device. Not alldirectory control statements can be used in PROFILE and USER definitions. To seewhich ones can be used in which type of definition, refer to the individual statementdescriptions described in this chapter. Table 20 lists control statement categoriesand their placement requirements.Table 20. Directory Control Statement CategoriesCategory Statements Placement RequirementsGeneral ACCOUNT, ACIGROUP, APPCPASS,AUTOLOG, CLASS, CPU, CRYPTO,DATEFORMAT, D8ONECMD,INCLUDE, IOPRIORITY, IPL, IUCV,LOGONBY, MACHINE, NAMESAVE,NOPDATA, OPTION, POOL,POSIXGLIST, POSIXINFO,POSIXOPT, SCREEN, SHARE,SPOOLFILE, STDEVOPT,XAUTOLOG, XCONFIG, XSTOREThese statements may appear only before any of thedevice statements within either a USER definition or aPROFILE definition.Global GLOBALDEFS, GLOBALOPTS,POSIXGROUPThese statements may only appear after theDIRECTORY control statement(s) and before allPROFILE and USER statements. The first Globaldefinition statement must be a GLOBALDEFS statement.448 z/VM: CP Planning and Administration

Creating and Updating a User DirectoryTable 20. Directory Control Statement Categories (continued)Category Statements Placement RequirementsProfile PROFILE This statement may appear only after the lastDIRECTORY statement or the global definition sectionand before any USER statements.Device (type 1) CONSOLE, DASDOPT, DEDICATE,LINK, SPECIAL, SPOOLThese statements may appear only after all generalstatements within either a USER definition or a PROFILEdefinition. You may define up to 24,576 virtual devicesper virtual machine at logon.Device (type 2) MDISK, MINIOPT These statements may appear only after all generalstatements within a USER definition.System affinity SYSAFFIN The Prefix form may appear only before a USERstatement. The Internal form may appear anywhere withina Global, Profile, or User definition.Load LOAD This statement may appear only in a special form of thedirectory cluster format file.Blank lines and lines beginning with an asterisk (*) may appear. The information oneach control statement must appear in columns 1 through 71.Some directory control statements support mixed-case operands, so care must betaken when editing the directory source file so as to avoid accidentally altering thecase of these operands. Although the example statements in this section are inmixed case, the case is not significant for most of them. They are shown in mixedcase only to improve their readability.Table 21 describes the directory control statements. It shows the page on which thestatement is described, the statement category, and a brief summary of thestatement’s function. Although the directory control statements are listed inalphabetic order, this is not the order in which they would be coded in the directory.Table 21. Summary of User Directory Control StatementsStatement Category Function PageACCOUNT General Defines the account numbers to which a virtual machine may charge itscosts. It also defines a distribution code.ACIGROUP General Specifies the name of a group to which an individual user ID is assigned. 458APPCPASS General Allows a virtual machine to request an APPC/VM path without supplyingsecurity parameters, even when the equivalent of SECURITY (PGM) isindicated on the APPCVM CONNECT request.AUTOLOG General A synonym for XAUTOLOG. See XAUTOLOG on page 578. 461CLASS General Specifies the privilege class (or classes) assigned to an individual user. 462CONSOLE Device Defines a virtual machine operator’s console. 463CPU General Specifies a virtual processor that is to be defined automatically when theuser logs on to the system.CRYPTO General Authorizes a virtual machine to define virtual crypto facilities and specifiesthe crypto domain or domains the virtual machine is allowed to use. It alsospecifies whether the virtual machine is authorized to be enabled to enterkeys, and whether the special security mode may be used.DASDOPT Device An extension to the DEDICATE, LINK, and MDISK statements. 472DATEFORMAT General Specifies a user’s default date format for commands that provide multipledate formats.456459465468475Chapter 17. Creating and Updating a User Directory 449

Creating and Updating a User DirectoryTable 21. Summary of User Directory Control Statements (continued)Statement Category Function PageDEDICATE Device Specifies that a real device is to be used solely by the virtual machine, orthat a real tape device is to be shared with other users.DIRECTORY Control Defines the device on which the directory resides and must be the firststatement in the directory.D8ONECMD General Defines whether a virtual machine can issue multiple CP commands withDIAGNOSE code X'08'.GLOBALDEFS Control Signifies the beginning of the global definition section. 485GLOBALOPTS Control Used to define global settings to be used while processing user definitions. 486INCLUDE General Specifies the name of a PROFILE entry to be invoked as part of the USERentry.IOPRIORITY General Defines a virtual machine’s I/O priority queueing range. 488IPL General Designates a device number or named saved system that CP automaticallyloads (IPLs) when the user logs on to the system.IUCV General Authorizes a virtual machine to create an IUCV communication path withanother virtual machine.LINK Device Accesses another virtual machine’s minidisk. 500LOAD Control Specifies where the directory definition entry is to be found. The LOADstatement is valid only in a cluster file format directory.LOADDEV General Identifies the location of a program to be loaded as a result of an FCPList-Directed IPL. Parameters to be passsed to the program may also bedefined.LOGONBY General Designates up to eight user IDs that can use their own passwords to logonto and use a virtual machine.MACHINE General Defines the virtual machine mode (ESA, XA, or XC) and the number ofvirtual processors a virtual machine can define.MAXSTORAGE General Specifies the virtual storage size for a user. 512MDISK Device Defines virtual disks (minidisks): permanent minidisks, temporary minidisks,and virtual disks in storage.MINIOPT Device An extension to MDISK used when defining non-full-pack minidisks. 524NAMESAVE General Authorizes a virtual machine to access a restricted named saved system orsaved segment and authorizes the virtual machine to obtain an exclusivewriteable copy of a saved segment.NICDEF Device Defines virtual network adapters that are fully simulated by CP. 529NOPDATA General Authorizes a virtual machine to use NOP CCWs to transfer data to CPspool files.OPTION General Defines certain options available to the virtual machine. 533POOL General Allows a set of virtual machines to be defined with the same configurationor characteristics.POSIXGLIST General Specifies all POSIX groups of which the user is a member. 541POSIXGROUP Control Defines a POSIX group. 543POSIXINFO General Specifies a user’s POSIX information. 545POSIXOPT General Specifies option settings related to a user’s POSIX capabilities. 548PROFILE Control Defines the start of a PROFILE entry. 551SCREEN General Defines the extended color and extended highlighting options for the virtualmachine console.477480483487490493504507509510513527532540553450 z/VM: CP Planning and Administration

Creating and Updating a User DirectoryTable 21. Summary of User Directory Control Statements (continued)Statement Category Function PageSHARE General Specifies a virtual machine’s scheduler share. 555SPECIAL Device Defines virtual displays, communication lines, and channel-to-channeladapters that may or may not be connected to real devices when the userlogs on.SPOOL Device Defines virtual unit record devices (spooling devices). 562SPOOLFILE General Describes virtual machine spool file characteristics. 565STDEVOPT General Specifies the optional storage device management functions available tothe virtual machine.STORAGE General Specifies the virtual storage size for a user. 568SYSAFFIN Control Defines how, and to which systems of a multiple-system complex, thesubsequent statements apply.USER Control 1. Starts a user’s directory entry.2. Defines the virtual machine user’s logon identification (user ID) andpassword.3. Defines the virtual machine’s storage size.4. Defines the virtual machine user’s CP command privilege classes.XAUTOLOG General Designates user IDs that can enter an XAUTOLOG command for the virtualmachine.XCONFIG General Specifies control parameters for the extended-configuration facilitiesprovided in the ESA/XC virtual machine architecture: access lists and dataspaces.XSTORE General Authorizes a virtual machine for sole use of the Expanded Storage facility. 585Blank Line May appear anywhere in the directory control file. When the DIRECTXAutility processes the directory control file, it ignores blank lines.Asterisk (*) Any line in the source directory file that begins with an asterisk (*) is acomment. When the DIRECTXA utility processes the directory control file, itignores comment statements.557566569572578580||||Creating the User DirectoryTo create a user directory, you must:1. Create a CMS file (or edit an existing CMS file) that contains an entry for eachvirtual machine that will run on z/VM.2. Use the DIRECTXA utility to run the user directory creation program.Note: If you are migrating from VM/XA SP , you cannot use the z/VMDIRECTXA utility to install an object directory in z/VM format on theVM/XA SP system residence pack while your system is running onVM/XA SP. Instead, you should use a second physical pack for the z/VMobject directory.IBM provides a sample directory in a CMS file named USER DIRECT. You can editthe USER DIRECT file to tailor your system’s user directory.If you choose not to use the USER DIRECT file, you can create your own CMS fileand code directory control statements in it.Chapter 17. Creating and Updating a User Directory 451

Creating and Updating a User DirectoryFinally, to update the directory, your virtual machine must have write access to thevolume that contains the directory (by convention, the virtual machine with user IDMAINT or your chosen installation user ID usually has write access to the properminidisk).Continued Directory Control StatementsCertain directory control statements are permitted to continue across multiplerecords in the directory file. These statements continue from one record to the nextwhen the record’s last non-blank character in columns 1-71 is a comma (,). Thestatement is continued beginning in column 1 of the next non-comment, non-blankrecord. That is, since comment records and blank records are ignored byDIRECTXA, they do not terminate a continued statement.When DIRECTXA is processing a record that ends in a continuation comma, iteffectively deletes the continuation comma and concatenates the prior portion ofthis record with the next non-comment, non-blank record, with one intervening blank(see “Quoted String Operands” for the syntax rules for very long strings). Thisprocess is repeated until a non-continued, non-comment, non-blank record isencountered. The statement is then parsed according to its normal rules. Statementnames and keywords may not be split across multiple records.Some statements that support continuation may have additional rules for continuingcertain operands, such as quoted string operands, across multiple records. Theserules are described in the documentation for these operands.A continued statement may be no longer than 6144 characters. All characters,including blanks and the continuation comma count towards this limit. On the finalrecord of a continued statement, all characters, including blanks, from column 1 upto and including the last non-blank character count towards the limit.The following are some examples of directory control statements continued acrossmultiple records.POSIXINFO IWDIR /home,IUPGM /myself ,* This is a comment among records of a continued statement.* The POSIXINFO statement above continues on the next recordFSROOT VMBFS:FPOOL1:FSPACE1Quoted String Operands* The following statement has 63 characters that count towards the* 6144-character limit: 26 on the first record and 37 on the* next.POSIXGLIST GIDS 5402 450 ,GNAMES all DeptG63 DeptG30Certain operands on certain directory control statements are permitted to bespecified as quoted string operands, which consist of one or more quoted strings.Quoted strings are useful if an operand must be permitted to contain imbeddedblanks, single quotation marks, or double quotation marks. If the statement ispermitted to be continued across multiple records of the directory file, a quotedstring operand, with or without imbedded blanks, may continue across multiplerecords.Quoted strings and quoted string operands must obey the following rules:452 z/VM: CP Planning and Administration

Creating and Updating a User Directory1. A quoted string operand consists of one or more quoted strings.2. A character string may be surrounded by single or double quotation marks. Thisstring, along with its surrounding quotation marks, is referred to as a quotedstring. A string which is to contain blanks, single or double quotation marks mustbe surrounded by quotation marks (single or double). It is permissible to includeother characters inside the quotes.3. To include a single quote inside a quoted string surrounded by single quotestwo consecutive single quotes are required inside the string. Likewise, to includea double quote inside a quoted string surrounded by double quotes, twoconsecutive double quotes are required inside the string.4. To include a single quote inside a quoted string surrounded by double quotes,the single quote need not be duplicated. To include a double quote inside aquoted string surrounded by single quotes, the double quote need not beduplicated.5. The final result string of a quoted string is formed as follows: any duplicatedsingle or double quotes are reduced to on single or double quote, respectively,then the surrounding quotes are removed.6. The final result string of a quoted string operand is formed as follows: the resultstring from adjacent quoted strings are concatenated with no intervening blank.Note that this concatenation happens even if a continued record ends with aquoted string and the next record begins with a quoted string.7. A quoted string may not continue to the next record. It must begin and end onthe same record, just as statement names and keywords. A quoted stringoperand, however, may continue across multiple records by splitting it intoquoted strings and splitting the statement between quoted strings.8. A quoted string may not be imbedded in or concatenated with another quotedstring or a non-quoted string. For example, ’AB’″C″ and ABC’DEF’ are not validquoted strings.The following are some examples of directory control statements with valid quotedstring operands.POSIXINFO IWDIR ’/home’POSIXINFO IWDIR ’This is Larry’’s’,’"Initial Work’ ,’ing Directory"’ ,IUPGM ’The latest "Init’ ,"ial User Program"""Running the User Directory ProgramAs previously mentioned, you must use the DIRECTXA utility to run the userdirectory creation program. The general format of the command to execute theDIRECTXA utility is:directxafn ftfn is the file name of your directory. The default is USER.ft is the file type of your directory. The default is DIRECT.For example, to bring online the new version of a directory named USER DIRECT,enter:directxaTo bring online the new version of a directory named SPECIAL DIRECT, enter:Chapter 17. Creating and Updating a User Directory 453

Creating and Updating a User Directorydirectxa special||To bring online the new version of a directory named SECRET DRCT, enter:directxa secret drctNotes:1. To update the directory your installation is currently using, you must haveprivilege class A, B, or C (by convention, MAINT or your chosen installation userID usually has the appropriate class).2. The system does not check for overlapping extents in the directory. Therefore,while changing the directory source file, you should check your new directoryentries to ensure that the new MDISK allocations you are defining do notoverlap existing MDISK allocations. If an overlap occurs, one virtual machineuser could unknowingly destroy data belonging to another.3. If you are migrating from VM/XA SP, you cannot use the DIRECTXA utility toinstall an object directory in z/VM format on the VM/XA SP system residencepack while your system is running on VM/XA SP. Instead, you should use asecond physical pack for the z/VM object directory.Changing the DirectoryFor more information on the DIRECTXA command, see z/VM: CP Commands andUtilities Reference.To change your directory, you must:1. Edit the file that contains the source directory2. Add, delete, or change directory entries as required3. Bring your modified directory online by entering the command to start theDIRECTXA utility.As an alternative method of modifying specific pieces of information in the onlinedirectory, you can run an application program that uses DIAGNOSE code X'84' on aclass B virtual machine. (DirMaint, the Directory Maintenance licensed program, isone such application. Use of DIAGNOSE code X'84' allows DirMaint to makecertain changes in the online directory without reprocessing the source directory.)When used by an application such as DirMaint, DIAGNOSE X'84' improves theturnaround time needed to make the changes active and minimizes the need tototally reprocess the source directory. It cannot, however, delete existing entries noralter USER entries in the source directory. It only replaces existing online directorydata.For more information on this DIAGNOSE code, refer to z/VM: CP ProgrammingServices.Checking a Directory for ErrorsBefore you bring a directory online, if you want to check the directory for errors, usethe EDIT option of the DIRECTXA utility. For example, to check a directory namedMYDIRECT DIRECT for errors, enter:directxa mydirect (editIn response, DIRECTXA checks MYDIRECT DIRECT for errors but does not bring itonline (even if there are no errors).454 z/VM: CP Planning and Administration

Creating and Updating a User DirectoryTo check USER DIRECT for errors, enter:directxa (editSpecifying a Directory That Contains VM/SP Control StatementsIf you want to use a directory from a VM/SP system or VM/SP HPO system andsome of the statements or options are not supported by z/VM, specify the MIXEDoption of the DIRECTXA utility. For example, assume you have a VM/SP directoryin a file named SPDIRECT DIRECT. To bring this directory online, enter:directxa spdirect (mixedCreating Directory ProfilesIn response, DIRECTXA ignores most VM/SP or VM/SP HPO source statementsthat it doesn’t support, rather than flagging them as errors.Note: DIRECTXA sends you a warning when it encounters a VM/SP or VM/SPHPO statement but will continue to create the updated directory.If certain directory control statements are repeated for several users, you can makeuse of directory profiles to save space in the directory. Using directory profiles issimilar to creating a user entry in the directory. To create directory profile entries:1. Determine which control statements are commonly repeated for a designatedset of user entries.2. Create a directory profile that contains those control statements on the sourcedirectory using the PROFILE statement (page 551).3. Insert an INCLUDE control statement (page 487) immediately after the USERcontrol statement for those entries that will reference the profile.4. Remove the existing directory control statements in the user entries thatreference a profile except for those control statements that are unique to thoseuser entries.5. Run DIRECTXA in EDIT mode to ensure that there are no errors. Any errorconditions will result in appropriate messages to your console.6. Correct any errors and run DIRECTXA again to install the newly createddirectory.Determining How Much Space the Directory NeedsThe directory normally requires about two cylinders of CKD/ECKD space or 50pages of FBA DASD space. (If you do not allocate enough space for your directory,the DIRECTXA program sends you a message to this effect.) For additionalinformation on determining the space required for the directory, refer to “DirectorySpace” on page 608.Chapter 17. Creating and Updating a User Directory 455

ACCOUNTACCOUNT Directory Control Statement (General)(1)►► Account acctnum1distcode►◄▼acctnumn(2)Notes:1 The default distribution code is the user ID from the USER statement.2 Specify acctnumn up to 7 times.PurposeThe ACCOUNT statement specifies an account number to which a virtual machinemay charge its costs. It also includes the distribution code, a code that has nomeaning to CP but may be used by your installation as it needs it (for example, todesignate where printed output is to go).How to SpecifyIf specified, the ACCOUNT statement must go before the first device statement youcode in a user’s directory entry. (For a list of device statements, see Table 20 onpage 448.) Multiple ACCOUNT statements are allowed within a profile, but are onlyused if no ACCOUNT statements are in the user directory entry.Operandsacctnum1defines the primary account number. An account number can be 1 to 8characters long.distcodedefines the distribution code for printed and punched output. If you specifyacctnum1 and do not specify distcode, the distribution code is the user ID fromthe USER statement. If you are defining alternative account numbers, you mustspecify distcode. See the usage notes and examples.acctnumndefines up to seven alternative account numbers.UsageNotes1. You can code multiple ACCOUNT statements in the same user’s directory entry.The total number of account numbers you code for that entry cannot be morethan eight, whether you code one ACCOUNT statement or many.2. If you code several ACCOUNT statements, distcode must appear on the firststatement only, immediately after the primary account number.3. When logging on, a user has the option of specifying an alternative accountnumber on the LOGON command. If the specified alternative account number isin the user’s directory entry, CP charges that alternate account number. If a user456 z/VM: CP Planning and Administration

ACCOUNTlogs on without specifying an alternative account number on the LOGONcommand, CP charges the primary account number.4. If a virtual machine has several account numbers, the user can switch accountnumbers using the SET ACCOUNT command. For more information about theSET ACCOUNT command, see the z/VM: CP Commands and UtilitiesReference.Examples1. To specify JOB101 as a virtual machine’s account number, use the followingstatement in the virtual machine’s directory entry:Account job1012. To specify JOB101 as a virtual machine’s account number and BIN-99Z as avirtual machine’s distribution code, use the following statement in the virtualmachine’s directory entry:Account job101 bin-99z3. To specify:v JOB101 as a virtual machine’s account number,v BIN-99Z as a virtual machine’s distribution code, andv JOB102, JOB103, and PLAY999 as a virtual machine’s alternative accountnumbersuse the following statement in the virtual machine’s directory entry:Account job101 bin-99Z job102 job103 play999Chapter 17. Creating and Updating a User Directory 457

ACIGROUPACIGROUP Directory Control Statement (General)►► ACIgroup groupname ►◄PurposeThe ACIGROUP statement is an optional statement used to specify the name of thegroup to which this user (user ID) is assigned. To assign Access Control Interface(ACI) group names to users, you must include the ACIGROUP statement in thedirectory entries of all users you are specifying as members of groups. You cannotassign more than one ACI group name to each user in the directory, nor can youspecify more than one ACIGROUP statement per directory entry.How to SpecifyIf you use the ACIGROUP statement, it must precede any device statements youspecify in a user’s directory entry. (The device statements are: CONSOLE,DASDOPT, DEDICATE, LINK, SPECIAL, and SPOOL.) One ACIGROUP statementis allowed within a profile but is only used if no ACIGROUP statement is in the userdirectory entry.OperandsExamplesgroupnamespecifies the name of the ACI group to which this user is assigned. The variablegroupname may consist of any 1 to 8 characters. However, the applicationprograms that use this value (for example, IBM licensed program RACF) mayplace their own restrictions on the character set that can be used. Therefore, itmay be necessary to review the ACI group names, specified if any applicationsreference them. Only one ACIGROUP statement may be specified per USERdirectory entry.To specify that user ID JONES belongs to group MUNDANE, use the followingdirectory control statements:User jones ww11qq 8m 16m *.ACIgroup mundane458 z/VM: CP Planning and Administration

APPCPASSAPPCPASS Directory Control Statement (General)►► APPCpass gate_lu gate_known_lu userid password ►◄PurposeThe APPCPASS directory statement allows a virtual machine to request anAPPC/VM path without supplying security parameters (user ID and password), eventhough the equivalent of SECURITY (PGM) is indicated on the APPCVMCONNECT request. Each APPCPASS statement for a virtual machine identifies apossible target of APPCVM CONNECT requests that indicate SECURITY (PGM),and provides the user ID and password needed for security authorization tocomplete the connection. When a CONNECT request that requires user ID andpassword includes only user ID, CP searches for a corresponding APPCPASSstatement in the originating virtual machine’s directory entry to obtain the password.If the CONNECT request requires user ID and password, but includes neither, CPsearches for a corresponding APPCPASS directory statement to obtain both.How to SpecifyIf you use the APPCPASS statement, it must precede any device statements youcode in the user’s directory entry. (For a list of device statements, see Table 20 onpage 448.) Multiple APPCPASS statements are allowed within a profile entry. AnyAPPCPASS statements found within a profile entry are added to those found in theincluding user entry with no duplicate checking performed. A statement that appearswithin a user definition is processed before a statement that appears within anincluded profile definition.Operandsgate_luspecifies the 8 character GATEWAY_LU_NAME that is the first part of thelocally-known LU name. A shorter name must be padded on the right withblanks to a length of 8 characters.gate_known_luspecifies the 8 character GATEWAY_KNOWN_LU_NAME that is the secondpart of the locally-known LU name, which determines the target for whichsecurity parameters are being specified. When the GATEWAY_LU_NAME is*IDENT, the GATEWAY_KNOWN_LU_NAME must be 8 bytes of binary zeros(X'0000000000000000').useridspecifies the 1- to 8-character user ID.passwordspecifies the 1- to 8-character password that corresponds to the user ID valueat the target identified by the locally-known LU name.UsageNotes1. Multiple APPCPASS statements can be specified for a single virtual machine.2. The same gate_lu and gate_known_lu values may be on multiple APPCPASSstatements for a single virtual machine. Each of these APPCPASS statementscan have a different user ID value. In this manner, a virtual machine can useChapter 17. Creating and Updating a User Directory 459

APPCPASSmultiple user ID and password pairs to gain access to the target. If two or moresuch statements also have the same user ID value, only the first statement isused to obtain security parameters for the designated target.3. APPCPASS statements are an alternative to specifying security parameters forAPPCVM CONNECT requests from CMS applications in the CMS file thatsupports the Systems Application Architecture ® (SAA ® ) Common ProgrammingInterface for Communications (CPIC).ExamplesThe following APPCPASS statements in the directory definition of JOEUSER’svirtual machine define a list of LUs and their security parameters with whichJOEUSER’s virtual machine can establish communications. This is not a definitivelist. Programs running in JOEUSER’s virtual machine could develop and pass therequired LU and security information dynamically. The APPCPASS statementssimply provide default security parameters for the identified LUs for cases whenthey are not dynamically supplied.APPCpass Regional SalesOff Outlet01 pass01APPCpass HomeOffc Invntory Outlet01 pass02APPCpass HomeOffc Reports SalesMgr passsmgrAPPCpass HomeOffc MailBox MailMan passmmAPPCpass HomeOffc MailBox JoeUser passpersWith the first statement, JOEUSER could establish a connection with the LU namedREGIONAL SALESOFF and be known as user OUTLET01 with password PASS01.With the second, JOEUSER could establish a connection with the LU namedHOMEOFFC INVNTORY and also be known as OUTLET01 but with anotherpassword of PASS02. With the third, JOEUSER could establish a connection withthe LU named HOMEOFFC REPORTS and be known as SALESMGR with apassword of PASSSMGR. With the fourth, JOEUSER could establish a connectionwith the LU named HOMEOFFC MAILBOX and be known as MAILMAN with apassword of PASSMM. With the last, JOEUSER could establish a connection withthe LU named HOMEOFFC MAILBOX to be known as himself, JOEUSER with apassword of PASSPERS.460 z/VM: CP Planning and Administration

AUTOLOGAUTOLOG Directory Control Statement (General)PurposeThe AUTOLOG statement is a synonym for XAUTOLOG that is available forcompatibility reasons. Refer to “XAUTOLOG Directory Control Statement (General)”on page 578 for the format and for information on coding the XAUTOLOGstatement.How to SpecifyMultiple AUTOLOG statements are allowed within a profile but are only used if noAUTOLOG or XAUTOLOG statements are in the user directory entry.Chapter 17. Creating and Updating a User Directory 461

CLASSCLASS Directory Control Statement (General)►► CLass classes ►◄PurposeThe CLASS statement specifies the privilege class or classes assigned to anindividual user.How to SpecifyThe CLASS statement, if used, must be after the USER statement and mustprecede any device statements. (For a list of device statements, see Table 20 onpage 448.) One CLASS statement is allowed within a profile if the USER statementCLASS field of each of the including virtual machines is blank or contains only anasterisk (*). A CLASS statement within a user directory entry overrides a CLASSstatement in a profile.Operandsclassesspecifies up to 32 privilege classes of CP commands a user can enter.Command classes are A through Z, and 1 through 6. Each character representsa single privilege class, and may appear in any order, without duplication, andcannot be separated by blanks. See Chapter 16, “Redefining CommandPrivilege Classes,” on page 433 for information on how to restructure yourcommand privilege classes if you want them to be different from theIBM-defined default classes A, B, C, D, E, F, and G.UsageNotes1. If you do not specify a CLASS statement and you specify the class field of theUSER statement as either a blank or an asterisk (*), CP uses the default classor classes specified on the PRIV_CLASSES statement in your systemconfiguration file.2. If the CLASS field of the USER statement is not blank and is not an asterisk (*),the CLASS statement is not allowed.3. If you change the privilege classes for any DIAGNOSE codes, be aware that thechange can affect the user’s ability to enter, because some CMS commandsinvoke DIAGNOSE codes (for example, DUMPVIEW, GENIMAGE, andOVERRIDE).ExamplesTo specify that user ID BONES can enter commands with privilege classes Z, 1, 6,A, X, C, B, 2, 5, and G, use the following directory control statements:User Bones ww11qq 8m 16m *Class z16axcb25g462 z/VM: CP Planning and Administration

CONSOLECONSOLE Directory Control Statement (Device)►► Console vdev devtype(1)TclassuseridOBServer►◄Notes:1 The default is no secondary user ID.PurposeThe CONSOLE statement defines the virtual machine console for any virtualmachine whose user directory entry contains no CONSOLE statement but doescontain an INCLUDE statement referring to that profile.How to SpecifyOne CONSOLE statement is allowed within a profile entry. If you define aCONSOLE statement in both a user directory entry and its included profile entry, atlogon time two requests to define a console are presented to the system; the userdirectory entry is presented first.If you code a CONSOLE statement, it must follow any general statements you codein a user’s directory entry. (For a list of general statements, see Table 20 on page448.)When processing the CONSOLE statement, DIRECTXA checks for a maximum offive tokens: virtual device number, device type, spooling class, a secondary user IDor observer, in that order. If you specify more than five tokens, DIRECTXA ignoresthe extra tokens and system processing continues as if you had not specified theextra tokens.Operandsvdevis the virtual device number for the virtual console.devtypeis the device type. Valid device types are 3215 and 3270.classis a 1-character spooling class. With spooling classes, your installation cangovern the printing of the real spooled output. The class can be any singlealphanumeric character from A to Z or from 0 to 9. If you omit class, the defaultis T.useridIs the 1- to 8-character secondary user ID whose console is to be used whenthe primary user disconnects. If userid is specified, class must also bespecified.Chapter 17. Creating and Updating a User Directory 463

CONSOLEUsageNotesOBServerindicates that the specified user is in an observer rather than a secondary userfor the virtual machine whose console is being defined.1. A virtual machine can have a maximum of one console. Once logged on, userscan change the definition of their console to meet their needs. You can use thefollowing commands to change the definition of your console:CommandFunctionDEFINE v Changes the console addressDETACH Deletes the consolev Creates a console if one does not already exist.SPOOL Changes the spooling classTERMINAL CONMODE Changes the device typeThe user ID field cannot be changed or deleted by the user.2. To define a virtual machine console with a console mode (CONMODE) of 3270,the real terminal must be a graphics device. In addition, if the real terminal is anSNA/CCS terminal, the VTAM service machine (VSM) that controls the terminalmust support CONMODE 3270. VTAM service machines that use releases ofACF/VTAM ® earlier than Version 3 Release 1.1 support only CONMODE 3215.If either condition is violated, an informational message is issued during logonprocessing and the console mode defaults to 3215.Examples1. To define a 3215 console at address 009 that produces class T spooled output(the default value), use the following statement in the virtual machine’s directoryentry:Console 009 32152. To define a 3270 console at address 0A9 that produces class Y spooled output,use the following statement in the virtual machine’s directory entry:Console 0a9 3270 y3. To define a 3215 console at address 01F that produces class T spooled outputand the user ID whose console is to be used when this user ID is disconnectedis ALJONES, use the following statement in the virtual machine’s directory entry:Console 01f 3215 t aljones464 z/VM: CP Planning and Administration

CPUCPU Directory Control Statement (General)►► CPU cpuaddrVECtorNOVECtorBASE CPUID bbbbbbNODEDicateDEDicateCRYpto►◄PurposeThe CPU statement specifies a virtual processor that is to be defined automaticallyfor the virtual machine at LOGON time.How to SpecifyThe maximum number of CPU statements allowed in the user’s directory entry iscontrolled by the mcpu operand of the user’s MACHINE statement, if specified. Ifyou specify the CPU statement in a user’s directory entry, it must appear after theUSER statement and before any device statements. (For a list of devicestatements, see Table 20 on page 448.)Multiple CPU statements are allowed within a profile entry. If you specify CPUstatements in a user directory entry and a profile entry with the same processoraddress (cpuaddr), the user directory entry overrides the profile entry. Otherwise,the user and profile CPU entries are additive.If you do not specify a CPU statement in a user’s directory entry, the address of thebase virtual processor is X'00' by default.Operandscpuaddrdefines a virtual processor at the specified address. The address can be any2-digit hexadecimal number from X'00' to X'3F'.VECtorNOVECtorspecifies whether a virtual vector facility should be defined automatically for thevirtual CPU at LOGON time. For base virtual processors with at least one realvector facility installed, the default is VECTOR; otherwise, the default isNOVECTOR. For nonbase processors, the default is always NOVECTOR. Ifyou define the virtual processor as VECTOR and no real vector facility exists onthe real processor, CP issues a message that indicates that no real vectorfacility exists to service the virtual vector facility.BASEtells CP that this CPU statement defines the base virtual processor. You canonly specify BASE on one CPU statement. If you do not specify BASE on anyCPU statement, CP defines the base virtual processor as the CPU statementwith the lowest virtual processor address (cpuaddr).CPUID bbbbbbprovides the processor identification number to be stored in bits 8 through 31 ofthe CPU ID that is returned in response to the store processor ID (STIDP)instruction. The variable bbbbbb is a 6-digit hexadecimal number. (No checkingis done to ensure that this number is unique in the virtual configuration.) ForChapter 17. Creating and Updating a User Directory 465

CPUUsageNotesbase processors, this option overrides the CPUID operand on the OPTIONstatement. For nonbase processors, it overrides the CPU ID of the base CPU.For more information about the the CPUID operand on the OPTION statement,see page 533.DEDicateNODEDicatespecifies whether this virtual processor is to be dedicated at LOGON time to areal processor.If NODEDICATE is specified, this virtual processor is not to be dedicated to areal processor. It has the same effect as entering the UNDEDICATE commandfor this virtual CPU. NODEDICATE is the default.CRYPtospecifies whether a virtual Integrated Cryptographic Facility (ICRF) should bedefined automatically for the virtual CPU at LOGON time. If you define thevirtual CPU as CRYPTO and no real ICRF is installed on the real processor atLOGON time, CP issues a message that indicates that no real crypto facility isinstalled.1. If the virtual processor is to be dedicated, CP tries to dedicate a real processorthat has the same facilities as the virtual processor. For example, CP tries tomatch a real processor with a vector facility to a virtual CPU with a definedvirtual vector facility, and a real processor without a vector facility to a virtualCPU without a defined virtual vector facility.2. The order of virtual machine CPU dedication is the base CPU first, with anyother nonbase processors following in the same order as the CPU entries in theuser’s directory entry.3. If DEDICATE is specified on the CPU statement and dedication occurs as aresult of this, and if the processor becomes no longer dedicated later for anyreason, rededication does not occur.4. The DEDICATE and UNDEDICATE commands override this statement.5. The directory entry contains conflicting statements if multiple processors aredefined on CPU statements and OPTION CONCEAL is specified. An informationmessage is issued, the CONCEAL option is rejected, and directory processingcontinues.6. The protected application environment is supported only for virtual machinesrunning a single processor. If this virtual machine is running a multiprocessorconfiguration, the SET CONCEAL ON command is rejected.7. Use of the ICRF must be authorized by the CRYPTO statement if the CRYPTOoperand is to be specified. The default is to not define an ICRF.8. A maximum of two virtual crypto facilities may be defined for a virtual machine.If a virtual machine user has more than two CPU statements with CRYPTOspecified, CP defines virtual crypto facilities for only the first two CPUstatements specifying crypto. CP issues an error message to indicate that themaximum number of cryptos have already been defined.ExamplesTo define a vector-enabled base CPU at address X'3F', with a CPU ID of X'00003F',use the following CPU statement:CPU 3f vector base CPUid 00003f466 z/VM: CP Planning and Administration

CPUTo define a crypto-enabled base CPU at address X'DE', with a CPU ID ofX'0000DE', use the following CPU statement:CPU de novector base CPUid 0000de CryptoChapter 17. Creating and Updating a User Directory 467

CRYPTOCRYPTO Directory Control Statement (General)First (or only) CRYPTO statement:(1) CSU *►► CRYPto DOMAIN ▼ domains Additional OperandsCSU 01APVIRTual►◄Subsequent CRYPTO statements:CRYPtoDOMAIN▼domains(1)CSU 01*AdditionalOperandsAdditional Operands:▼KEYENTRYSPECIALMODIFYAPDEDicatedAPVIRTual▼apsNotes:1 Options after DOMAIN can be entered in any order. CSU, KEYENTRY, SPECIAL, MODIFY and APVIRT canonly be specified once.PurposeThe CRYPTO statement authorizes the user to define virtual cryptographic facilitiesand specifies which domains and CAM queues the virtual machine is allowed touse. It also specifies whether the virtual machine is authorized to be enabled toenter keys or issue PKSC Modify instructions, and whether the special securitymode can be used.How to SpecifyThe CRYPTO statement, if included in the directory entry, must appear after theUSER statement and before any device statements. (For a list of devicestatements, see Table 20 on page 448.)The CRYPTO statement cannot be used in a profile unless it is used with APVIRTonly.You can specify as many CRYPTO statements as you need to assign domains orAPs to the virtual machine. Once the DOMAIN operand is specified, additionalCRYPTO statements may be specified with the other operands. Also, the DOMAIN468 z/VM: CP Planning and Administration

CRYPTOor APDED operands may be specified again on additional CRYPTO statementsfollowed by the additional domains or APs to be assigned. Note, however, that theCSU, APVIRT, and other operands may only be specified once.OperandsDOMAIN domainsspecifies up to 16 domains the virtual machine may use. Domains are 0 through15, specified in decimal. They may appear in any order, without duplication. IfCAM queues are available, the virtual machine may also use the CAM queuescorresponding to the domains specified. If AP queues are available, and theAPDED operand is specified, the virtual machine may use the AP queuescorresponding to the domains specified. The DOMAIN operand may bespecified more than once on additional CRYPTO statements, but the DOMAINoperand must be specified before any additional operands other than APVIRTare specified.CSU *tells CP to assign this virtual machine’s virtual crypto facilities to real cryptounits. This operand also tells CP to allow this virtual machine to use bothCrypto Asynchronous Processors (CAPs) 1 and 0. If you do not specify CSU,the default is CSU *.CSU 0tells CP to assign this virtual machine’s virtual crypto facility to crypto unit 0.This operand also tells CP to allow this virtual machine to use CAP 0.CSU 1tells CP to assign this virtual machine’s virtual crypto facility to crypto unit 1.This operand also tells CP to allow this virtual machine to use CAP 1.KEYENTRYtells CP that this virtual machine is authorized to issue certain PCCF functionsthat operate on cryptographic keys.SPECIALtells CP that this virtual machine can use the special security mode.MODIFYtells CP that this virtual machine can issue the PKSC Modify instructions.APVIRTualtells CP that this virtual machine may share access with other virtual machinesto the clear-key functions of the Adjunct Processor (AP) cryptographic facility.The APVIRT operand may be specified once in any order. The APVIRT operandmay not be specified if the APDED operand is specified. It is not necessary tospecify the DOMAIN or CSU operands when specifying the APVIRT operand.APDEDicated apsspecifies up to 64 APs the virtual machine may use for dedicated access to theAdjunct Processor (AP) cryptographic facility. APs are 0 through 63, specified indecimal. They may appear in any order, without duplication. The DOMAINoperand also must be specified to indicate the AP queues to access. The APqueues equivalent to the domains specified by all of the DOMAIN operands willbe assigned to the guest for each AP specified on the APDED operand on allCRYPTO statements. The APDED operand may not be specified if the APVIRToperand is specified. The APDED operand may be specified more than once onadditional CRYPTO statements.Chapter 17. Creating and Updating a User Directory 469

CRYPTOUsage NotesExamples1. Only one virtual machine may use a domain at a time. If more than one virtualmachine has a CRYPTO statement for a given domain, only the first virtualmachine that logs on receives use of the domain.2. The domains specified must be installed on the real processor. If a specifieddomain is not installed on the real processor at LOGON time, a message isissued that the domain is not available.3. If there is more than one crypto unit in the real cryptographic facility, the CSUoption should be specified. CSU 0 or CSU 1 should be specified for virtualmachines that will have a virtual crypto facility on only one virtual CPU. CSU *should be specified for configurations that will have a virtual crypto facilitydefined on more than one virtual CPU.4. For CMOS cryptographic facilities, the use of CSU * is recommended. Thisallows the virtual machine to use both Crypto Asynchronous Processor (CAP) 0and CAP 1.5. The KEYENTRY parameter was necessary on older processors along with theSET CRYPTO KEYENTRY command to enable key-entry for one user at a time.Today, the KEYENTRY parameter is still necessary to allow use of the PCCFkey functions. However, the SET CRYPTO KEYENTRY command is not neededto enable individual key-entry because more than one user may issue thesefunctions at a time on current processors.6. It is recommended that multiple CRYPTO statements for a user be specifiedcontiguously in the user directory entry.7. The APs specified must be installed on the real processor. If a specified AP isnot installed on the real processor at LOGON time, a message is issued thatthe AP is not available.8. On real processors which have only the Adjunct Processor (AP) cryptographicfacility installed, it is not necessary to specify the CSU, KEYENTRY, SPECIAL,or MODIFY operands. If any of these operands are specified, they will beignored without generating any errors.9. If major changes are made to the configuration of the PCI crypto queues byupdating the APDED and APVIRT operands on the CRYPTO statements forusers without a subsequent system IPL, it is possible that no queues of the typeselected by z/VM will remain for queue-sharing, even though they may appearto be available when the QUERY CRYPTO APQS command is issued. If it isnecessary to change the type of queues available for queue-sharing, a systemIPL must be performed after the directory changes are made.1. To specify that a virtual machine can use domains 1 and 2, use the followingCRYPTO statement in the virtual machine’s directory entry:Crypto Domain 1 2 CSU * Special Modify KeyentryCP will assign the virtual crypto facilities to real crypto units. If the CryptoAsynchronous Processor (CAP) is provided in the processor configuration, thevirtual machine also will be able to use CAP 0 and CAP 1 and CAM queues 1and 2.2. To specify that the virtual machine may use the clear-key functions of theAdjunct Processor (AP) cryptographic facility, use the following CRYPTOstatement in the virtual machine’s directory entry:Crypto Apvirt470 z/VM: CP Planning and Administration

CRYPTO3. To specify that a virtual machine can use domains 3 and 7 and AP queues 3and 7 on APs 0, 2, and 3, use the following CRYPTO statement in the virtualmachine’s directory entry:Crypto Domain 3 7 CSU * Special Modify Keyentry Apded 0 2 34. To specify that a virtual machine can use AP queues 2, 10, 11, 12, and 13 onAP 4 use the following CRYPTO statement in the virtual machine’s directoryentry:Crypto Domain 2 10 11 12 13 Apded 4Chapter 17. Creating and Updating a User Directory 471

DASDOPTDASDOPT Directory Control Statement (Device)►►DASDOPT(1)DEVCTLSYSCTLNOCTLNOWRKALlegWRKALleg►◄Notes:1 Options can be entered in any order.PurposeThe DASDOPT statement is an extension to the MDISK, LINK, and DEDICATEstatements, and immediately follows them.How to SpecifyMultiple DASDOPT statements are allowed within a profile entry, but each mustdirectly follow a DEDICATE statement. A DASDOPT statement can follow a LINK orMDISK statement only if that statement defines a full-pack minidisk. DIRECTXAcannot detect every case when the MDISK preceding the DASDOPT is not afull-pack minidisk nor can it determine if the volume represented on the LINKstatement is a full-pack minidisk. In these situations, the characteristics of theDASDOPT operands are given to the disks. Unexpected results may occur.When processing the DASDOPT statement, DIRECTXA checks for two tokens: oneof the control tokens (DEVCTL, NOCTL, or SYSCTL) and WRKALLEG. If youspecify more than two tokens, DIRECTXA ignores the extra tokens and systemprocessing continues as if you had not specified the extra tokens.OperandsDEVCTLmeans that the device accepts CCWs that have an effect on resources andfunctions directly related to the device. See usage note 6 on page 473 fordefault values.SYSCTLmeans that the device accepts CCWs that have a direct global effect onsubsystem resources and function, not just those related to the device. Seeusage note 6 on page 473 for default values.NOCTLmeans that the device does not accept any CCWs that can control subsystemresources or functions, regardless of whether they directlyWRKALlegmeans working allegiance is active on the minidisk. This option is allowed onlyif DASDOPT is immediately preceded by the MDISK statement.NOWRKALlegmeans working allegiance is not active on the minidisk. This option is allowedonly if DASDOPT is immediately preceded by the MDISK statement.472 z/VM: CP Planning and Administration

DASDOPTUsage Notes1. If you are dedicating a DASD with logical addresses (for example, a DASDconnected to a paging storage director in a 3380 Storage Control Model 11 or21), the real device number you specify must be the base address for thedevice, and virtual device number you specify must follow the addressing rulesfor base addresses.2. If you are dedicating a device with logical addresses, both the real devicenumber and the virtual device number you specify must be the base address.3. When the cache status of a device is changed, the hardware presents anasynchronous state change interrupt to every vdev associated with that rdevthat has DASDOPT DEVCTL specified.4. WRKALLEG must be used when running two or more MVS guests as part of aSysplex configuration using the cross-system coupling facility (XCF) componentof MVS/ESA. This option must be used for any minidisk containing the XCFcouple dataset to maintain cross-system lock integrity (and thereby, dataintegrity) within the sysplex.5. WRKALLEG/NOWRKALLEG is valid only when the preceding MDISK statementgives the user write access to the minidisk. If the MDISK statement specifiesread-only access, CP rejects the WRKALLEG/NOWRKALLEG statement andissues an error message. Furthermore, working allegiance is simulated onlywhen a guest with write access initiates I/O.6. Levels of Control (DEVCTL, NOCTL, and SYSCTL)a. The default control level value is normally DEVCTL, unless DASDOPTfollows the LINK statement for a full-pack minidisk. In that case, NOCTL isalways the default.b. DASDOPT applies only to DASDs on a cached control unit. If you specifyDASDOPT for a noncached DASD, the statement is ignored.c. Specifying a level of control (NOCTL, DEVCTL, or SYSCTL) for a DASDconnected to a cache storage control unit authorizes CP to accept particularcontrol CCWs.Table 22 on page 474 shows you the additional control CCWs that CP acceptsfor a level of control. The DEVCTL column shows the CCWs that CP accepts inaddition to those it accepts for the NOCTL level of control. The SYSCTL columnshows the CCWs that CP accepts in addition to those it accepts for theDEVCTL and NOCTL levels of control.Chapter 17. Creating and Updating a User Directory 473

DASDOPTTable 22. DASD Control LevelsControl UnitTypeAdditional Control CCWs Accepted forDEVCTL3990-3,6 v Set subsystem mode– Activate caching for device– Deactivate caching for device– Activate DASD fast write– Deactivate DASD fast write– Force deactivate DASD fast writev Perform Subsystem Function– Establish Duplex Pair– Terminate Duplex Pair– Suspend Duplex Pair– Direct I/O to One Device of the Duplex Pair– Set Interface IDAdditional Control CCWs Accepted forSYSCTLv Set subsystem mode– Make cache available– Make cache unavailable– Force cache unavailable– Make NVS available– Make NVS unavailable– Activate cache fast write– Deactivate cache fast writev Perform Subsystem Function– Destage Modified Tracks– Set Cache Allocation Parameters– Suspend/Resume Function474 z/VM: CP Planning and Administration

DATEFORMATDATEFORMAT Directory Control Statement (General)►► DATEFormat SHOrtdateFULldateISOdateSYSdefault►◄PurposeThe DATEFORMAT statement specifies a user’s default date format for commandsthat provide multiple date formats.How to SpecifyOne DATEFORMAT statement is allowed in a user or profile entry. A DATEFORMATstatement in a user entry overrides a DATEFORMAT specification in a profile entry.If you specify the DATEFORMAT statement, it must precede any device statementsthat you specify in a profile or user entry. (For a list of device statements, seeTable 20 on page 448.)OperandsSHOrtdatespecifies that dates in command responses be displayed in mm/dd/yy, mm/dd,or yy/mm/dd format, where mm is the month, dd is the day of the month, and yyis the 2-digit year.FULldatespecifies that dates in command responses be displayed in mm/dd/yyyy oryyyy/mm/dd format, where mm is the month, dd is the day of the month, andyyyy is the 4-digit year.ISOdatespecifies that dates in command responses be displayed in yyyy-mm-dd format,where yyyy is the 4-digit year, mm is the month, and dd is the day of the month.SYSdefaultspecifies that the default date format for this user be set to the system-widedefault. The system-wide default date format may be set in the systemconfiguration file with the SYSTEM_DATEFORMAT statement, or with the CPSET DATEFORMAT command. Refer to “SYSTEM_DATEFORMAT Statement”on page 225 for a description of the SYSTEM_DATEFORMAT configurationstatement, and the z/VM: CP Commands and Utilities Reference for adescription of the SET DATEFORMAT command.UsageNotes1. The format of the dates, such as mm/dd/yy, mm/dd, and yy/mm/dd, aredependent upon the command or routine that displays or generates the date.2. If you omit the DATEFORMAT statement when you code a user’s directoryentry, the default format for that user will be the system-wide default(SYSdefault). The user may change their default date format with the CP SETDATEFORMAT command.Chapter 17. Creating and Updating a User Directory 475

DATEFORMAT3. If the user’s default date format is set to SYSDEFAULT, the system-wide defaultdate format that is in effect at logon time will be used until the user logs off orissues the SET DATEFORMAT command. If the system-wide default dateformat is changed, the user must logoff and log back on or issue the SETDATEFORMAT SYSDEFAULT command to switch to the new system-widedefaultExamples1. To specify the user’s default date format as SHORTDATE, use the followingDATEFORMAT statement in the user’s directory entry:DATEFORMAT SHORTDATE2. To specify the user’s default date format as FULLDATE, use the followingDATEFORMAT statement in the user’s directory entry:DATEFORMAT FULLDATE3. To specify the user’s default date format as ISODATE, use the followingDATEFORMAT statement in the user’s directory entry:DATEFORMAT ISODATE4. To specify that the user’s default date format should be the same as thesystem-wide default date format, use the following DATEFORMAT statement inthe user’s directory entry:DATEFORMAT SYSDEFAULT476 z/VM: CP Planning and Administration

DEDICATEDEDICATE Directory Control Statement (Device)►► Dedicate vdev DASDTape DeviceOther Device►◄DASD:|rdevVOLIDVOLIDvolidvolidR/O NOQIOASSIST USERACCESSID useridTape Device:rdevSINGLEUSERR/O NOASSIGN NOQIOASSISTNOASSIGN NOQIOASSISTMULTIUSEROther Device:|rdevNOQIOASSIST USERACCESSID useridPurposeThe DEDICATE statement specifies that a virtual machine has sole use of a realdevice or is serially sharing a real tape device with other users. The DASDOPTstatement is an extension to this statement. For more information about theDASDOPT statement, see “DASDOPT Directory Control Statement (Device)” onpage 472.How to SpecifyIf you specify DEDICATE statements, they must follow any general statements in auser’s directory entry. (For a list of general statements, see Table 20 on page 448.)IBM recommends that you place DEDICATE statements before any SPOOL, LINK,or SPECIAL directory statements. This helps CP assign the correct subchannelnumber to any virtual devices to which you want to dedicate a real device. Forexample, you should make sure the virtual subchannel number is the same as thereal subchannel number. You would do this by placing the DEDICATE statementsbefore the LINK and SPOOL statements.DEDICATE statements are allowed within a profile entry if no duplicate virtualdevice numbers are on DEDICATE statements within the profile. Any virtual devicenumber in a profile that duplicates a virtual device number within a user entry isresolved at logon time; the DEDICATE request from the user entry is presented tothe system first.Chapter 17. Creating and Updating a User Directory 477

DEDICATE||||||||||||Operandsvdevis the virtual device number.rdevrdev is the real device number.VOLID volidis the volume serial number of a disk pack mounted on a real disk storagedevice. The variable volid must be a 1- to 6-character string. If volid is less thanfive characters, VOLID is a required keyword; otherwise VOLID is optional.R/Ospecifies that the virtual device is to be in read-only mode.SINGLEUSERdedicates a real tape device to a single user. This is the default for a tapedevice.MULTIUSERattaches a real tape device to be serially shared with other users. See UsageNote 3.NOASSIGNindicates that the ATTACH process should not issue an ASSIGN channelcommand for this user. This lets the ATTACH work, even if the specified realdevice is assigned to another processor. For more information about theATTACH command, see the z/VM: CP Commands and Utilities Reference.NOQIOASSISTindicates the device is not eligible for Queued-I/O Assist.USERACCESSID useridto allow a user (guest) the ability to give FCP LUN access to the specifieduserid. In z/VM, authority to LUNs in a Fabric is normally set up by entries in anAccess Control Table (ACT). See Linux documentation for details on the ACTconfiguration tool. z/VM stores the userid into the subchannel when an FCPsubchannel is attached or reset. The adapter uses the stored userid names tocorrelate I/O requests with the rules in the ACT and allows access to the LUNsbased on those rules. The USERACCESSID option provides a proxy method toaccessing a LUN. The userid specified with the option will be stored in thesubchannel, rather than the invoker’s userid, when an FCP subchannel isattached or reset. It is assumed that the userid specified with USERACCESSIDis already in the ACT.UsageNotes1. You may dedicate a real device to only one virtual machine at a time. If morethan one virtual machine has a DEDICATE statement for a given real device,only the first virtual machine that logs on receives control of the device. Theonly exception is when the MULTIUSER operand is specified, which allowsserial sharing of an attached tape device.2. The DEDICATE directory statement defaults to DEVCTL if no DASDOPT ispresent.3. The MULTIUSER function is intended for guest operating systems that managetheir own assignment of tape devices. It is not intended for CMS unless someexternal means of managing assignments or serializing access to the tape478 z/VM: CP Planning and Administration

DEDICATE|||Examplesdevice among the sharing users is explicitly implemented. Third partyassignment and multiple system assignment (Control Access CCW) are notsupported.To share a tape device, the directory entry for that user must contain aDEDICATE statement for the device that includes the MULTIUSER operand, orthe user must specify the MULTIUSER option when using the CP ATTACHcommand to attach the device. If the first user to log on has a DEDICATEstatement for the device that does not include MULTIUSER, or issues theATTACH command for the device without specifying MULTIUSER, the devicebecomes dedicated to that user. The device then cannot be attached asMULTIUSER by any user until it is detached by the user to whom it isdedicated.The MULTIUSER function is valid only for 3424, 3480, 3490, and 3590 tapedevices.1. To dedicate the real device at real device number 100 to the virtual device atvirtual device number 100, use the following statement in the virtual machine’sdirectory entry:Dedicate 100 1002. To dedicate the real disk at real device number 200 (volume serial numberXA9999) to the virtual device at virtual device number 220, use the followingstatement in the virtual machine’s directory entry:Dedicate 220 200 volid xa99993. To dedicate in read-only mode the real disk at real device number 1300 (volumeserial number XB9999) to the virtual device at virtual device number 330, usethe following statement in the virtual machine’s directory entry:Dedicate 330 1300 volid xb9999 r/o4. To share the real tape device at real device number 500 and attach it to thevirtual machine as virtual device number 181, use the following statement in thevirtual machine’s directory entry:Dedicate 181 500 multiuser5. The USERACCESSID option applies only to first-level and second-level guests.If it is attempted on a third-level or higher virtual machine, the request istranslated into corresponding first-level and second-level information only.Chapter 17. Creating and Updating a User Directory 479

DIRECTORYDIRECTORY Directory Control Statement (Control)►► DIRectory vdev devtype volidaltvdevEDITnnnnnn-xxxxsysafnid►◄PurposeThe DIRECTORY statement defines to CP the device on which you have allocatedspace for the directory. (This device must also be a CP-owned volume.) If yoursystem is part of a multisystem complex, a DIRECTORY statement is required foreach logical system.How to SpecifyThe DIRECTORY statements must be the first statements in your source directoryor control DIRMPART file (cluster format directory). DIRECTORY statements are notallowed within a profile entry.If you specify the EDIT option on a DIRECTORY statement, that statement must:v Be the last DIRECTORY statement in the source directoryv Immediately follow another DIRECTORY statementv Be the only DIRECTORY statement with an EDIT option in the source directory.If any of these conditions is not met, an error message is issued.If you are sharing a single source directory among several systems, allDIRECTORY statements must be listed at the beginning of the source directory andbefore any other control statements.When processing the DIRECTORY statement, DIRECTXA checks for a maximum ofsix tokens: virtual device number, device type, volume serial number, alternatedevice number or the EDIT operand, the processor ID, and a system ID, in thatorder. If you specify more than six tokens, DIRECTXA ignores the extra tokens andsystem processing continues as if you had not specified the extra tokens.Operandsvdevis the virtual device number of the device that is to contain the object directory.devtypeis the device type. Valid device types are:3380 3390 9336 FB-512480 z/VM: CP Planning and AdministrationFB-512 is a generic value which may be used in place of specific FBA devicetypes. A 3390 in 3380 track compatibility mode must be coded as 3380. Ifmultiple DIRECTORY statements are used, the device types do not have to bethe same.volidis the volume serial number of the directory volume. The variable volid is a 1- to6-character alphanumeric string.

DIRECTORYUsageNotesaltvdevis an alternative virtual device number, on which to write the directory if theprimary virtual device number is unavailable.EDIT(Supported for compatibility with VM/SP HPO) defines a special work volume tobe used by the VM/SP HPO DIRECT command when it is entered with theEDIT option. You can only specify the EDIT option on one DIRECTORYstatement, and it must be the last of the set of DIRECTORY statements.DIRECTXA validates the syntax of this statement but ignores its contents.nnnnnn-xxxxis the processor ID of the system to which the DIRECTORY statement applies.Use the QUERY CPUID command to get the values for nnnnnn and xxxx,where nnnnnn is the processor identification number, and xxxx is the modelnumber of the real machine. For more information about the QUERY CPUIDcommand, see the z/VM: CP Commands and Utilities Reference.If your system is an n-way processor operating in single-image mode, you canspecify the processor ID as *nnnnn-xxxx. This allows you to use oneDIRECTORY statement to define all CPUIDs. See “Usage Notes” for moreinformation about defining processor IDs with one DIRECTORY statement.sysafnidis a 1- to 8-character alphanumeric string that identifies the system whoseobject directory is affected by the SYSAFFIN statements (page 569).1. CP dynamically updates the active z/VM directory if your virtual machine hasthe proper privilege class and one of the following is true:v The volume serial number specified is the one on which the directory wasfound during initialization.v No directory has yet been found, and the volume serial number specified iscurrently owned by CP (as specified using the CP_OWNED statement in thesystem configuration file or using the SYSCPVOL macroinstruction inHCPSYS). For more information about the CP_OWNED statement, see page73. For more information about the SYSCPVOL macroinstruction, see page664.2. An asterisk (*) in the first position of the processor ID, *nnnnn-xxxx, lets you useone DIRECTORY statement to define all of the processor IDs of an n-wayprocessor operating in single-image mode. Nevertheless, if a four-wayprocessor is partitioned into two logical two-way processors, you must create aDIRECTORY statement for each processor that specifies all 11 digits of theprocessor ID (nnnnnn-xxxx) for each logical processor. This is because theprocessor ID of the two logical systems would differ only in the first character ofthe processor ID.3. When multiple DIRECTORY statements contain the same system affinity ID, thedevice information (device number, device type, and volume serial number) onall of the statements must be identical.The maximum number of 16 unique system affinity IDs can be specified onmultiple DIRECTORY statements.ExamplesThe following examples show the various ways of coding the DIRECTORY controlstatement:Chapter 17. Creating and Updating a User Directory 481

DIRECTORY1. To specify that:v The FBA volume labeled XA0001, at virtual device number 0123, is to containthe new directoryv The volume at virtual device number 0223 should be used if CP encountersan error while trying to access the directory on virtual device number 0123code the following DIRECTORY statement:Directory 0123 fb-512 xa0001 02232. To specify:v A multiple system definition where a 2064 two-way processor is partitionedinto two uniprocessors, SYSTEMA (serial 012345) and SYSTEMB (serial112345)v A 3380 EDIT work volume with a virtual device number of 0243 and a volumeserial number of DRM19Fcode the following DIRECTORY statements:Directory 0123 3380 xa0001 0223 012345-2064 systemaDirectory 0223 3380 xa0002 0233 112345-2064 systembDirectory 0243 3380 drm19f edit3. To specify a 2064 four-way processor configured as a single-image processorso that the system can be IPLed on any of the four processors, use thefollowing DIRECTORY statements:Directory 0b64 3380 vmaipl 015211-2064 vmaDirectory 0b64 3380 vmaipl 115211-2064 vmaDirectory 0b64 3380 vmaipl 215211-2064 vmaDirectory 0b64 3380 vmaipl 315211-2064 vmaDirectory 0243 3380 drm19f editOr you can use:Directory 0b64 3380 vmaipl *15211-2064 vmaDirectory 0243 3380 drm19f edit4. To specify a 2064 partitioned into two 2-way images, you must use two pairs ofDIRECTORY statements, one pair for each image. Each statement in a pairdiffers only in the first character of the processor ID:Directory 0b64 3390 vmaipl 020893-2064 vmaDirectory 0b64 3390 vmaipl 220893-2064 vmaDirectory 0784 3380 vmbipl 120893-2064 vmbDirectory 0784 3380 vmbipl 320893-2064 vmbDirectory 0243 3390 drm19f edit5. To specify an n-way processor, such as a 2064, that is to be treated as a singleimage within a complex, use a DIRECTORY statement with an asterisk (*) in thefirst character of the processor ID. This ensures that the DIRECTXA commandcan be entered on any processor in the complex.Directory 0b64 3390 vmaipl *20893-2064 vma6. To specify a multiple system environment where four 2064 processors share asingle directory, use the following DIRECTORY statements:Directory 0123 9336 fba001 0223 012345-2064 fbasysaDirectory 0223 9336 fba002 0223 012355-2064 fbasysbDirectory 0323 9336 fba003 0223 012445-2064 fbasyscDirectory 0423 9336 fba004 0223 013345-2064 fbasysd482 z/VM: CP Planning and Administration

D8ONECMDD8ONECMD Directory Control Statement (General)►► D8ONECMD FAILLOGOFFUNLOCKLOCK►◄PurposeThe D8ONECMD statement is an optional statement that defines whether a virtualmachine can issue multiple CP commands using DIAGNOSE code X'08' andseparating the commands with X'15's. This statement also tells CP whether to logthe commands to the system operator’s console.How to SpecifyIf you specify a D8ONECMD statement, it must appear after the USER statement orin a profile for a user. You can only have one D8ONECMD statement for each userentry. If you specify more than one, you will receive an error message. If youspecify a D8ONECMD statement in a user entry and you also specify aD8ONECMD statement within the profile entry for that user, CP uses theD8ONECMD statement in the user entry and ignores the D8ONECMD statement inthe profile entry.If you do not specify a D8ONECMD statement, CP will not prevent users fromissuing multiple commands with DIAGNOSE code X'08' and will allow users tochange their D8ONECMD setting.OperandsOFFtells CP that this virtual machine can issue multiple commands with DIAGNOSEcode X'08' without any logging.FAILtells CP to prevent this virtual machine from issuing multiple commands withDIAGNOSE code X'08'. If the virtual machine tries to issue more than onecommand with DIAGNOSE code X'08', CP will log each command to thesystem operator’s console, process the first command, and reject anysubsequent commands in the sequence.LOGtells CP that this virtual machine can issue multiple commands with DIAGNOSEcode X'08' and tells CP to log the multiple commands to the system operator’sconsole.LOCKtells CP to lock the D8ONECMD setting for a specific user entry. This preventsusers from changing the D8ONECMD setting for their virtual machine.UNLOCKtells CP not to lock the D8ONECMD setting for a specific user entry. This allowsuser to change the D8ONECMD setting for their virtual machine.Chapter 17. Creating and Updating a User Directory 483

D8ONECMDUsage NotesExamples1. If you omit the D8ONECMD for any user entry, CP uses the defaults: OFF andUNLOCK. This means everything continues as you expected it to in previousreleases of VM. If you want to use the D8ONECMD statement but you areafraid to have CP start rejecting commands, we suggest you use the LOGoperand. Using the LOG operand does not cause CP to reject any commandsand it provides you with a list of all the commands by logging them to thesystem operator’s console. You can then monitor any multiple command activityuntil you feel comfortable in switching to the FAIL operand.2. If you are running a back level of CMS and D8ONECMD is set to FAIL, someCMS commands (such as SENDFILE, NETDATA, DISK LOAD, andREADCARD) may not work properly. Also a back level of the programmableoperator facility will not initialize if D8ONECMD is set to FAIL.1. If you wanted to:v Prevent a user from issuing more than one command using DIAGNOSE codeX'08' and X'15's,v Log each of the commands to the system operator’s console, andv Prevent that user from changing the D8ONECMD settinguse the following D8ONECMD statement:D8OneCmd Fail Lock2. If you wanted to:v Allow a user to issue multiple commands using DIAGNOSE code X'08' andX'15's,v Record each command, andv Allow that user to change the D8ONECMD settinguse the following D8ONECMD statement:D8OneCmd Log UnLock484 z/VM: CP Planning and Administration

GLOBALDEFSGLOBALDEFS Directory Control Statement (Control)►► GLOBALDefs ►◄PurposeThe GLOBALDEFS statement denotes the start of the global definition section. If noglobal definitions are specified, this statement is optional.How to SpecifyThe GLOBALDEFS statement, if specified, must directly follow the DIRECTORYcontrol statement(s) and precede all PROFILE and USER definitions. There can beonly one GLOBALDEFS directory control statement specified.ExamplesTo see an example of the use of this statement, see “GLOBALOPTS DirectoryControl Statement (Control)” on page 486.Chapter 17. Creating and Updating a User Directory 485

GLOBALOPTSGLOBALOPTS Directory Control Statement (Control)►►GLOBALOptsMACHinemachmode►◄PurposeThe GLOBALOPTS statement is used to define global settings that will be usedduring user processing.How to SpecifyThe GLOBALOPTS statement, if specified, must be within the global definitionsection of the source directory (after the GLOBALDEFS statement and before anyUSER or PROFILE definitions).OperandsExamplesMACHine machmodespecifies the virtual machine mode for any user definition that does not containa MACHINE directory control statement. The valid values that may be used forthe virtual machine mode are ESA, XA, and XC.In the examples that follow, assume this multisystem complex definition:Directory 07a4 3380 vmaipl *01234-2064 vmaDirectory 0b64 3380 vmbipl 104567-2064 vmbDirectory 0cF4 3380 vmcipl *15211-2064 vmcDirectory 0664 3380 vmdipl *00012-2064 vmdThe following global definition section would define a default machine mode of XAon system vma and a default machine mode of ESA on system vmb.GlobaldefsSysaffin vmaGlobalopts machine xaSysaffin vmbGlobalopts machine esa486 z/VM: CP Planning and Administration

INCLUDEINCLUDE Directory Control Statement (General)►► INclude profilename ►◄PurposeThe INCLUDE statement specifies the name of a profile entry to be invoked as partof the USER statement (page 572).How to SpecifyINCLUDE statements are not allowed within a profile entry. If you specify anINCLUDE statement, it must directly follow the USER statement. Normally, you canonly specify one INCLUDE statement in a user directory entry. However, in a CSEsystem you could have an INCLUDE statement separated by system affinityrecords, only one of which can apply to a given system.Operandsprofilenamespecifies the name assigned to the PROFILE entry and is used to reference thePROFILE. The variable profilename is a 1- to 8-character alphanumeric string.Only one profile name may be specified on an INCLUDE statement.UsageNotes1. DIRECTXA tries to locate the profile name coded on an INCLUDE statement bysearching the list of PROFILE entries already processed and being held in freestorage buffers. The PROFILE is then processed (included) into the userdirectory entry definition and analyzed with respect to the rest of the user’sdefinition data.2. In a system using cross system extensions, it is possible to tailor the user’s,PROFILE definition by system. This is accomplished by selective inclusion ofthe PROFILE using the internal form of the SYSAFFIN statement.Examples1. To specify PROFILE1 as a profile entry to be invoked as part of the USERstatement, use the following statements:User example ...Includeprofile1.2. To tailor a user’s profile selection by system in a CSE complex, use thefollowing statements:User example ...Sysaffin vmaInclude d123vmaSysaffin vmbIncluded123vmb.Chapter 17. Creating and Updating a User Directory 487

IOPRIORITYIOPRIORITY Directory Control Statement (General)►► IOPRIORity ABSoluteRELativelowlowhigh►◄PurposeThe IOPRIORITY statement defines a virtual machine’s I/O priority queueing range.How to SpecifyOne IOPRIORITY statement is allowed in a user or profile entry. An IOPRIORITYstatement in a user entry overrides an IOPRIORITY statement in a profile entry.If you specify the IOPRIORITY statement, it must precede any device statementsthat you specify in a profile or user entry. (For a list of device statements, seeTable 20 on page 448.)OperandsABSoluteindicates the type of I/O priority range. If LPAR I/O Priority Facility is enabled,the I/O priority range must fit onto the range to CP. If the range specified fallsoutside of the range available to CP, an informational message is displayedduring LOGON processing, and the requested range is clipped to fall within therange available to CP.If LPAR I/O Priority Facility is not enabled or not installed, CP simulates an I/Opriority range from 0 to 255.RELativeindicates the type of I/O priority range. The maximum I/O priority range is 0 to255. If LPAR I/O Priority Facility is installed and enabled, the maximum I/Opriority range maps proportionately onto the range available to CP, with thehighest I/O priority mapping directly to the highest value available to CP. Therequested RELATIVE I/O priority range is used to calculate a percentage of themaximum I/O priority range, and the user’s effective I/O priority range is thecorresponding percentage of the I/O priority range available to CP.If LPAR I/O Priority Facility is not enabled or not installed, CP simulates an I/Opriority range from 0 to 255. Thus, the maximum I/O priority range maps directlyonto the range simulated by CP.lowis the low value of the I/O priority range. It must be a number from 0 to 255.highis the high value of the I/O priority range. It must be a number from 0 to 255and greater than or equal to the low value. If not specified, the high value isequal to the low value.UsageNotes1. If an IOPRIORITY statement is not found, LOGON processing requestsRELATIVE I/O priority range with a low value of 0 and a high value of 0.488 z/VM: CP Planning and Administration

IOPRIORITY2. For more information on IOPRIORITY ranges, refer to the CP SET IOPRIORITYcommand in the z/VM: CP Commands and Utilities Reference.Examples1. To assign a RELATIVE range of 8 values, use the following IOPRIORITYstatement in a virtual machine’s directory entry:ioprior rel 0 7Chapter 17. Creating and Updating a User Directory 489

IPLIPL Directory Control Statement (General)►► Ipl vdevnssname LOADParm load_parameter PARM parameter_stringfcp_vdev►◄PurposeThe IPL statement designates a named saved system or the device number of adevice that CP automatically loads (IPLs) when the user logs on the virtualmachine.How to SpecifyIf you specify the IPL statement, it must precede any device statements in a user’sdirectory entry. (For a list of device statements, see Table 20 on page 448.)Multiple IPL statements are allowed within a profile but are used only if no IPLstatements are in the user directory entry. If multiple IPL statements are in anincluded profile entry, only the last one is used.Operandsvdevis the virtual device number of the device CP is to automatically IPL when theuser logs on. The variable vdev is any hexadecimal number from X'0000' toX'FFFF'.nssnameis the 1- to 8-character alphanumeric name of a named saved system.fcp_vdevIf the specified virtual device is an FCP-attached device, a guest IPL from SCSIdisk will be initiated. This feature requires that parameters have previously beendefined with the LOADDEV directory statement.PARM parameter_stringspecifies a parameter string to pass to the user’s virtual machine ingeneral-purpose registers at the completion of the IPL. When you specifyPARM, all characters that follow the statement are considered part of theparameter string. Therefore, you must code the PARM option last on the IPLstatement. Although the IPL command allows for 64 bytes of parameters, thestring on the directory statement is limited to the number of characters that canbe specified in the first 71 positions of the statement. The string begins with thefirst nonblank character in the statement. (This differs from the IPL command,where trailing blanks are included.)If you specify an IPL statement using a virtual device number, the parameterstring is inserted into the virtual machine registers, 4 bytes per register, startingwith register 0. One byte of binary 0’s is inserted after the string. If PARM isspecified without a parameter string (only blanks), byte 0 of register 0 containsbinary 0’s. If you omit PARM, the virtual machine’s registers remain unchanged.If you specify an IPL statement using a named saved system that was definedwith the PARMREGS=m-n operand of the CP DEFSYS command, theparameter string is inserted into the virtual machine registers m through n that490 z/VM: CP Planning and Administration

IPLUsageNotesare first initialized to binary 0’s. (For more information on the CP DEFSYScommand, see the z/VM: CP Commands and Utilities Reference.) If you enter astring larger than can fit in the designated registers, an error message is issuedduring LOGON and the IPL command is rejected. If you omit PARM or specify itwith no parameter string, the virtual machine registers contain all 0’s.If you specify an IPL statement using a named saved system that was definedwith the PARMREG=NONE operand on the CP DEFSYS command, anyparameter string causes an error message to be issued and the command to berejected.If you specify an IPL statement using a named saved system that was definedwithout the PARMREGS=m-n operand on the CP DEFSYS command, theparameter string is inserted into virtual machine registers 0 through 15. Theregisters are not initialized first to binary 0’s. If you omit PARM or specify it withno parameter string, the virtual machine’s registers remain unchanged.LOADParm load_parameterspecifies a 1 to 8 character load parameter that is used by the IPL’d system. Itmay be necessary to enclose the load parameter in single quotes. The loadparameter may be retrieved by the guest operating system during its IPLsequence. It is preserved until a system-reset-clear operation is performed onthe virtual machine; this operation resets it to 8 EBCDIC blanks.1. Although the CP IPL command allows up to 64 characters on the PARM option,the directory restricts each statement to a single card image. This restrictionlimits the number of characters that you can enter on the IPL statement in thedirectory.2. If a user IPLs a named saved system that was created with the VMGROUPoption on the CP DEFSYS command, that user’s virtual machine becomes amember of the virtual machine group known by the NSS name. Members of avirtual machine group can connect to the signal system service to providesignalling within the group, including awareness messages (signal-in andsignal-out) about members joining the group or leaving it.3. A user whose virtual machine is a member of a virtual machine group and hasthe appropriate privilege class may authorize trace data recording to a systemdata file for the group.4. See the z/VM: CP Commands and Utilities Reference for detailed information onthe IPL command (including information about the LOADPARM and PARMoptions).5. The IPL action may not be completed if the user does not have certain privilegeclasses. For example, if IPL CMS is coded in a nonclass G user’s directoryentry, the IPL fails because CMS issues class G CP commands usingDIAGNOSE code X'08'.6. Specifying the load parameter in single quotes gives you leading blanks,embedded blanks, or single quotes. Remember that any single quote that is apart of the load parameter must be doubled. For example, use 'BETSY''S' tospecify BETSY'S as a load parameter.7. You may specify both the LOADPARM and PARM options when IPLing by eithervdev or nssname. The PARM option must be the last option on the IPLstatement.Chapter 17. Creating and Updating a User Directory 491

IPLExamples1. To specify that CP is to automatically IPL virtual device number 490 for a virtualmachine, use the following IPL statement in the virtual machine’s directory entry:Ipl 4902. To specify that CP is to automatically IPL a named saved system called CMSfor a virtual machine, use the following IPL statement in the virtual machine’sdirectory entry:Ipl cms3. To specify that CP is to automatically IPL virtual device number 490 for a virtualmachine and pass parameters XYZ to that virtual machine, use the followingIPL statement in the virtual machine’s directory entry:Ipl 490 Parm xyz4. To specify that CP is to automatically IPL virtual device number 490 for a virtualmachine and pass parameters XYZ to the virtual machine and load parm dataof BETSY'S, code the following statement in the virtual machine’s directoryentry:Ipl 490 LOADParm 'betsy''s' Parm xyz492 z/VM: CP Planning and Administration

IUCVIUCV Directory Control Statement (General)►►IUCV(1)ALLOWANY Priority Msglimit limitcpsyservgatewayidresourceiduserid*IDENT GATEANY GATEWAYname LOCAL REVOKEGLOBALGATEWAYRESANY LOCALGLOBAL►◄Notes:1 The operands can be specified in any order.PurposeThe IUCV statement authorizes a virtual machine to create an inter-usercommunications vehicle (IUCV) communication path with another virtual machine ora CP system service, or to create APPC/VM communication paths. (Tocommunicate with itself, a virtual machine does not need an IUCV statement in itsdirectory entry.)You can pass information between virtual machines with IUCV. IUCV allows virtualmachines to send and receive any amount of data to and from other virtualmachines. To use IUCV, you must specify the IUCV statement for the virtualmachines that use IUCV. For more information on IUCV, see the z/VM: Connectivitybook.How to SpecifyIf you specify the IUCV statement, it must precede any device statements in auser’s directory entry. (For a list of device statements, see Table 20 on page 448.)You can specify multiple IUCV statements for each virtual machine.You can specify multiple IUCV statements within a profile entry. Any IUCVstatements within a profile entry are added to those in the including user entry withno duplicate checking performed.OperandsALLOWspecifies that any other virtual machine can establish a communication pathwith this virtual machine. No further authorization is required in the virtualmachine that initiates the communication.ANYis a general authorization indicating that a communications path can beestablished with any other virtual machine, local resource, system resource,Chapter 17. Creating and Updating a User Directory 493

IUCVglobal resource, or gateway residing on this VM/ESA system. This option doesnot indicate that a communication path can be established with a CP systemservice.cpsyservspecifies the 1- to 8-character identification of the CP system service to whichan IUCV communication path is authorized. The CP system service name mustbegin with an asterisk (*). The following CP system services are available:*ACCOUNTAccounting system service*BLOCKIODASD block I/O system service*CRMCollection resource management system service*LOGRECError recording system service*MONITOR*MONITOR system service*MSGMessage system service*MSGALLMessage all system service*RPIAccess verification system service*SIGNALSignal system service*SPLSpool system service*SYMPTOMSymptom system service*VSWITCHVirtual switch system serviceAlso, if you want to authorize the VSM to use IUCV to communicate withSNA/CCS, specify cpsyserv as *CCS. For more information on VSM andSNA/CCS, see Chapter 9, “Planning for SNA Console Communication Services(SNA/CCS),” on page 329.If the virtual machine is running the Enterprise Systems Connection Manager(ESCM) licensed program, specify cpsyserv as *CONFIG.gatewayidis a 1- to 8-character gateway name used to connect to the resources in theSNA network rather than to a specified virtual machine. The first byte of thegateway name must be alphanumeric. (IBM reserves the names beginning withnonalphanumeric characters for its own use.)Be sure that the gateway name you specify is not the same as a user ID orresource name on the system, ALLOW, ANY, or SYSTEM.resourceidis a 1- to 8-character resource identifier used to connect to a resource managerrather than to a specified virtual machine. The first byte of the name must bealphanumeric. (IBM reserves names beginning with the remaining characters forits own use.)Be sure you do not specify the same name as a user ID or gateway on thesystem; or as ALLOW, ANY, or SYSTEM.494 z/VM: CP Planning and Administration

IUCVSpecifying IUCV resourceid does not give authority to connect by user ID to thevirtual machine that owns the specified resource. At the same time, specifyingIUCV userid does not give authority to connect by resourceid to the specifiedvirtual machine.When you explicitly authorize each virtual machine (with IUCV name or IUCVANY), you should also give explicit directory authorization to the TSAF virtualmachine residing on the same system as the name (with IUCV name or IUCVANY).useridis the 1- to 8-character user ID of the virtual machine to which an IUCVcommunication path is authorized.Priorityindicates that a communication path with the specified virtual machine canhandle priority IUCV communications and IUCV communications that have nopriority. If you do not specify PRIORITY, paths authorized by this entry cannothandle priority messages. PRIORITY does not apply to APPC/VM paths. Forany communication path routed through ISFC, PRIORITY status is determinedby the IUCV directory control statement for the initial invoker of the IUCVCONNECT.Msglimit limitdefines the maximum number of outstanding messages allowed on any pathauthorized by this entry. If you omit MSGLIMIT or if the IUCV CONNECT andACCEPT functions specify a lower message limit, the message limit is takenfrom the CONNECT or ACCEPT parameter list. If you omit MSGLIMIT and theIUCV CONNECT and ACCEPT functions do not specify a message limit, thedefault value is 10. The maximum allowed value for MSGLIMIT is 65,535.MSGLIMIT does not apply to APPC/VM paths.Note: This directory specification does not apply to IUCV CONNECTs involvingsystem services.*IDENTallows the virtual machine to connect to the Identify System Service to identify aresource or gateway LU.GATEANYallows the virtual machine to identify any gateway LU name.Note: Be careful when you assign names and when you give authorization forGATEANY. A virtual machine that has authority for GATEANY canidentify a gateway LU name as gateany. Also, this virtual machine wouldbe authorized to identify any other gateway LU name.nameis a 1- to 8-character resource or gateway LU name that the virtual machine isauthorized to identify. The first byte of the name should be alphanumeric. (IBMreserves names beginning with the remaining characters for its own use.)Be sure that the name you specify is not the same as a user ID on the system.Also, do not specify the name as any of the following: ALLOW, ANY, orSYSTEM.Specify LOCAL or GLOBAL for the next operand if the name corresponds to aresource managed by the virtual machine. Specify GATEWAY as the nextparameter if the name corresponds to a gateway LU provided by the virtualmachine.Chapter 17. Creating and Updating a User Directory 495

IUCVRESANYallows the virtual machine to identify any resource name.Note: Be careful when you assign names and when you give authorization forRESANY. A virtual machine that has authority for RESANY can identify aresource name as resany. Also, this virtual machine would be authorizedto identify any other resource name.LOCALauthorizes the virtual machine to identify the resource as a local resourceknown only to the local system. If you specify LOCAL with RESANY, the virtualmachine can identify any resource as a local resource.GLOBALauthorizes the virtual machine to identify the resource as a global resourceknown to all systems in the collection. This operand allows the virtual machineto identify the resource as local also. If you specify GLOBAL with RESANY, thevirtual machine can identify any number of local or global resources.GATEWAYauthorizes the virtual machine to identify the gateway LU. If you specifyGATEANY as the system gateway name, the virtual machine can identify anygateway LU in the collection.REVOKEauthorizes the virtual machine to revoke the specified resource or gateway LUname without owning it. A resource manager can always revoke ownership ofresource that it owns by severing its session with the *IDENT system service. Avirtual machine that can revoke resources or gateway LUs can also identifythem.If you specify REVOKE with:v LOCAL, the virtual machine can revoke and identify the specified resourceonly on this z/VM system.v GLOBAL, the virtual machine can revoke and identify:– The specified global resource– A local or system resource on this z/VM system that has the same nameas the global resource.A virtual machine cannot revoke a global and local resource at the sametime. The virtual machine must specify which resource to revoke when theconnection is made to *IDENT.v GATEWAY, the virtual machine can revoke and identify the gateway LUanywhere within the collection.v GATEANY, the virtual machine can revoke and identify any gateway LU inthe collection. Since gateway LUs are always known throughout thecollection, there is no need for the LOCAL or GLOBAL authority keywords.v RESANY and LOCAL, the virtual machine can revoke and identify any localresource.v RESANY and GLOBAL, the virtual machine can revoke and identify anyresource, local or global.Because the TSAF virtual machines do not keep track of the local resources, avirtual machine cannot revoke a local resource on another system.496 z/VM: CP Planning and Administration

IUCVUsage Notes1. When a virtual machine invokes the IUCV CONNECT function, IUCV searchesdirectory entries in the following order:a. The invoker’s IUCV statements for the target’s user IDb. The invoker’s IUCV statements for an ANY entryc. The target’s IUCV statements for an ALLOW entry.Connections invoked from CP system code do not need directoryauthorization. Priority status and message limit are taken from the CONNECTparameter list.2. For information on how to specify the maximum number of IUCV connections avirtual machine can make, see the OPTION statement on page 533.3. For information on how to code IUCV programs, see z/VM: CP ProgrammingServices.4. Communications with the following system services require authorization usingan IUCV statement with the system service name as the cpsyserv name:System Service cpsyserv NameAccountingCollection resource management *CRM*ACCOUNTError recording *LOGRECAccess verification *RPINote: Before communications can be established with*RPI, an external security manager must be installedon the system.SpoolSymptom*SPL*SYMPTOMVirtual switch *VSWITCH5. Communications with SNA/CCS requires authorization using an IUCVstatement with *CCS as the cpsyserv name.6. A virtual machine running the Enterprise Systems Connection Manager(ESCM) licensed program requires authorization using an IUCV statement with*CONFIG as the cpsyserv name.7. Communications with the following system services do not requireauthorization by the virtual machine. If an IUCV statement is specified, thefollowing cpsyserv names should be used:System Service cpsyserv NameMessage*MSGMessage all *MSGALLNote: Although the PRIORITY and MSGLIMIT operand may bespecified on the IUCV statement for *MSG and *MSGALL, thespecifications are never used, because the virtual machine willonly be receiving messages.Signal system service *SIGNALDASD block I/O *BLOCKIO8. *MONITOR is the cpsyserv name required on the IUCV statement to authorizea virtual machine to receive information concerning the location of monitorrecords in a saved segment for monitor. Without *MONITOR on the IUCVChapter 17. Creating and Updating a User Directory 497

IUCVstatement, a user cannot issue IUCV CONNECT to *MONITOR. After a virtualmachine is connected, it receives notifications from IUCV SEND commandswhenever data is in the monitor saved segment. The IPARML points to theguest real addresses in the saved segment where the monitor control arealies. The control area points to each data area.Note: More than one virtual machine can have an IUCV *MONITORstatement. This means that every virtual machine with an IUCVstatement for *MONITOR can connect concurrently to *MONITOR.9. When the directory entry associated with a resource manager user ID contains*IDENT authority to identify or revoke any resources or gateway LUs, thisinformation is saved in storage and checked in place of a subsequent directorysearch. This reduces the number of directory searches required when aresource manager virtual machine identifies or revokes resources (therebyimproving performance). This means that if *IDENT authority is updated, it isnot recognized until the resource manager stops using IUCV support andrestarts.10. If a virtual machine must identify more than one resource, you can specifymore than one IUCV statement for *IDENT in the virtual machine’s directoryentry. To check whether a virtual machine is authorized to identify or revokethe resource or gateway LU named in the IUCV CONNECT request presentedto *IDENT, the Identify System Service searches the virtual machine’s directoryentry for IUCV statements in the following order:a. The first *IDENT entry that has either the resource name RESANY or thegateway LU name GATEANY (depending on the type of name). If *IDENTfinds a match, it checks whether the LOCAL or GLOBAL (for resources)and REVOKE operands have enough authority to do the requestedfunction.b. If it does not find a match, or if the other operands are not enoughauthority, *IDENT searches for the first *IDENT entry that has the sameresource name or gateway LU name as specified on the CONNECTrequest.c. If *IDENT does not find a match, or if it finds a match but authorization forthe LOCAL or GLOBAL (for resources) and REVOKE operands does notcorrespond to that specified in the CONNECT parameter list, *IDENTsevers the requested connection, and the resource or gateway LU is notidentified.Examples1. To indicate that a virtual machine can establish an IUCV communication path toSOURCE, use the following statement in the virtual machine’s directory entry:Iucv source2. To indicate that a virtual machine can establish both of the following:a. An IUCV communication path to SOURCEb. A priority IUCV communication path with a message limit of 100 to TARGETuse the following statements in the virtual machine’s directory entry:Iucv sourceIucv target Priority MsgLimit 1003. To indicate that a virtual machine can establish:a. A priority IUCV communication path with a message limit of 100 to TARGETb. IUCV communication paths with any other virtual machineuse the following statements in the virtual machine’s directory entry:498 z/VM: CP Planning and Administration

IUCVIucv target Priority MsgLimit 100Iucv Any4. To indicate that any virtual machine can establish a path to the virtual machinewhose directory entry you are creating, use the following statement:Iucv Allow5. The following examples show how to use multiple IUCV statements for *IDENT.a. A resource manager, RESMGR1, has the following IUCV statements:Iucv *Ident ResAny GlobalIucv *Ident residx Local RevokeThe first IUCV statement authorizes RESMGR1 to identify any resource(RESANY) as a local or global resource (GLOBAL). This includes the localresource, RESIDX. The second IUCV statement authorizes RESMGR1 torevoke (REVOKE) the resource RESIDX, if it is defined on the local systemas a local resource (LOCAL).b. A resource manager, RESMGR2, has the following IUCV statements:Iucv *Ident Gateany GatewayIucv *Ident gatewayx Gateway RevokeThe first IUCV statement authorizes RESMGR2 to identify any gateway LU.This includes the gateway LU, GATEWAYX. The second IUCV statementauthorizes RESMGR2 to revoke the gateway LU GATEWAYX, but no othergateway LUs.Because gateway LUs are always known throughout the collection, nokeyword is needed to authorize a user to identify a gateway LU that can beaccessed only by users on the local system.c. A resource manager, RESMGR3, has the following IUCV statements:Iucv *Ident residx GlobalIucv *Ident residy GlobalIucv *Ident ResAny Local RevokeRESMGR3 can identify the resources, RESIDX and RESIDY, as local andglobal resources. RESMGR3 is not authorized to revoke any globalresources. Because of the last IUCV statement, RESMGR3 can identify anyresource as a local resource. Also, RESMGR3 can revoke any resourceknown on the local system as a local resource.d. A resource manager, RESMGR4, has the following IUCV statements:Iucv *Ident residx LocalIucv *Ident residy GlobalIucv *Ident residx Global RevokeRESMGR4 can identify the resource RESIDX as a local resource and theresource RESIDY as either a local or global resource. RESMGR4 cannotrevoke any resources, because *IDENT searches for the first entry thatmatches the resource name specified on the CONNECT. If RESMGR4 triesto connect to *IDENT to identify or revoke the GLOBAL resource, RESIDX,*IDENT severs the connection. In this case, if you want RESMGR4 toidentify and revoke the global resource, RESIDX, you must delete the firstIUCV statement.Chapter 17. Creating and Updating a User Directory 499

LINKLINK Directory Control Statement (Device)►► Link userid*vdev1vdev2R(1)►◄modesuffixNotes:1 The default is a blank.PurposeThe LINK statement gets access to another user’s minidisk. The target minidiskmust be defined by an MDISK statement (page 513) in the target user’s directoryentry. The DASDOPT statement is an extension to the LINK statement. The LinkDirectory statement Defaults to NOCTL (works like the Link command) if noDASDOPT statement follows it. For more information on the DASDOPT statement,see “DASDOPT Directory Control Statement (Device)” on page 472.How to SpecifyIf you specify the LINK statement, it must follow any general statements you specifyin a user’s directory entry. (For a list of general statements, see Table 20 on page448.)Multiple LINK statements are allowed within a profile entry. Any LINK statementswithin a profile entry are added to those in the including user entry with nouser-to-profile duplicate virtual device number or address checking performed. LINKstatements with duplicate virtual device numbers or addresses within a profile entryare errors.When processing the LINK statement, DIRECTXA checks for a maximum of fivetokens: target user ID, virtual device number (or address) of the target minidisk,virtual device number (or address) for the linking virtual machine, access mode, anda suffix of S or E. If you specify more than five tokens, DIRECTXA ignores the extratokens and system processing continues as if you had not specified the extratokens.Operandsuseridis the virtual machine user ID of the target minidisk owner.* indicates that the user being processed owns the minidisk.vdev1is the virtual device number or virtual address of the target minidisk.vdev2is the virtual device number or virtual address that the linking virtual machineuses for the target minidisk. If you omit vdev2 , the definition of vdev1 is used.modeis the access mode for the minidisk. The first letter in the access mode is the500 z/VM: CP Planning and Administration

LINKprimary access mode (read-only, write, or multiple-write); the second letter(optional) is the alternate access (read-only or write). A suffix letter, S or E, maybe added to any of the one or two letter modes to provide this user specificauthorization for use of stable or exclusive link modes when linking thespecified minidisk using the LINK command, the CMS VMLINK command, orDIAGNOSE code X'E4'.The access modes are:R Read-only access. Read access is established, unless another user holds awrite or an exclusive mode (ER, EW) access to the disk. If you omit themode, R is the default.RRRead-only access. Read access is established, unless another user holdsan exclusive mode (ER, EW) access.W Write access. Write access is established, unless another user holdsaccess (any mode) to the disk.WRWrite access. Write access is established unless another user holds access(any mode) to the disk. If write access is denied, read access is establishedunless another user holds an exclusive (ER, EW) mode access for the disk.M Multiple-write access. Write access is established unless another user holdsa write, a stable (SR, SW, SM) or an exclusive (ER, EW) mode access tothe disk.MRMultiple-write access. Write access is established unless another user has awrite, stable mode (SR, SW, SM) or exclusive mode (ER, EW) access tothe disk. In the case of a previous write or stable access, read-only accessis established. In the case of an exclusive mode access existing, readaccess is also denied.MWMultiple-write access. Write access is established in all cases except whenanother user holds either a stable (SR, SW, SM) or an exclusive mode (ER,EW) access to the disk.suffixThe optional suffix letters authorize virtual reserve/release and the use of thestable and exclusive (data integrity) access modes of the LINK command andDIAGNOSE code X'E4'. The specification on the LINK statement allows theuser to enter a LINK command with the specified type of access mode, stableor exclusive, against the specified user’s minidisk. For more information aboutstable and exclusive access modes, see the z/VM: CP Commands and UtilitiesReference.The suffix letters can be combined as follows (note that CP requires they bespecified in this order):1. S, E, or null (S and E are mutually exclusive), plus2. D or null.Therefore, the only valid combinations are: S, E, D, SD, or ED. This suffix is inturn concatenated with the mode, with no intervening blanks. For example, RS,RRE, and MRSD are all valid.S Authorizes the virtual machine to use the LINK command stable accessmodes (SR, SW, SM) against the specified user’s minidisk.Chapter 17. Creating and Updating a User Directory 501

LINKUsageNotesE Authorizes the virtual machine to use the LINK command exclusive andstable access modes (ER, EW, SR, SW, SM) against the specified user’sminidisk.D Tells CP that the device should not be defined when the virtual machineinitially logs on or is autologged, but to defer doing so until an explicit LINKcommand is issued for that device.1. It is the responsibility of the operating system running in each virtual machine tokeep data from being destroyed or altered on shared disks.2. CMS allows many virtual machines to have read access to the same minidisk;however, CMS does not supervise virtual machines that have write access tothe same minidisk. If two or more CMS virtual machines have write access tothe same disk, all data on the disk may be destroyed.Also note that CP does not prevent a virtual machine with an MW access toanother virtual machine’s minidisk from formatting that minidisk.3. The use of the stable (SR, SW, and SM) and exclusive (ER and EW) linkmodes can be authorized in two different ways:v Globally, using the OPTION statement values, LNKSTABL and LNKEXCLU(page 533)v Specifically, using the mode suffix letters (S or E) on the LINK or MDISK(page 513) statements.4. Do not add LINK statements to the z/VM directory shared file system file poolminidisks. Shared file system file pool server machines link to the file poolminidisks when needed.5. Use the LINK statement to give a user direct access to another user’s minidisk,or indirect access by linking to a third user’s LINK or MDISK statement. You canhave up to 50 of these indirect links (LINK indirections). For example:USER0MDISK 393 3390 1 10 USRVOL ALL ALL ALLUSER1LINK USER0 393 393 RRUSER2LINK USER1 393 393 RRUSER3LINK USER2 393 393 RRSince USER1 has had to first access the 393 minidisk through a direct link toUSER0, USER2’s link to the 393 minidisk is considered an indirect link.USER3’s link to the 393 minidisk through USER2 is thus also an indirect link.Up to 50 of these indirect links are allowed before the following message isissued:HCP109Euserid vdev not linked; excessive LINK indirectionsNote: This limit of 50 indirect links includes the original link. (In the example,USER1 to USER0.)6. If the target minidisk is a virtual disk in storage that is defined in the specifieduser’s directory entry but currently does not exist, the virtual disk in storage iscreated to satisfy the request, as long its creation does not exceed the systemlimit on the storage available for virtual disks in storage. Note that a new virtualdisk in storage must be formatted before it can be used.7. If a minidisk is defined as virtual device number 192 in the linking virtualmachine, the following special rules apply when that virtual machine IPLs CMS:502 z/VM: CP Planning and Administration

LINKv If 192 is an unformatted virtual disk in storage, CMS formats it and accessedit as file mode D.v If 192 is a CP-formatted virtual disk in storage, CMS reformats it for CMS useand accesses it as file mode D.v If 192 is a CMS-formatted virtual disk in storage or permanent minidisk that isaccessed as a file mode other than D, CMS reaccesses it as file mode D.v If 192 is an unformatted or CP-formatted permanent minidisk, CMS does notautomatically format, reformat, access, or reaccess it.When CMS accesses a 192 minidisk as file mode D, any minidisk or SFSdirectory already accessed as D is released.8. If the directory definition of a permanent minidisk is changed while users arelinked to it, existing links are unchanged, but any new links are made using thenew definition of the minidisk. Unpredictable results may occur.9. If the directory definition of a virtual disk in storage is changed while users arelinked to it, existing links are unchanged, and any new links are made to theexisting virtual disk in storage. The existing virtual disk in storage is used untilthe last user detaches it or logs off, at which time the virtual disk in storage isdestroyed. After that, any new links use the new definition of the virtual disk instorage.Examples1. To link in read-only mode LINKMAN’s 191 disk to a virtual machine as a 192disk, use the following LINK statement in the virtual machine’s directory entry:Link linkman 191 192 rr2. To link in write mode LINKMAN’s 291 disk to a virtual machine as a 292 disk,use the following LINK statement in the virtual machine’s directory entry:Link linkman 291 292 wrWR indicates that write access is given only if no one else is linked to the disk;if someone else is linked to the disk, read access is given.3. To authorize a specific user the ability to enter the LINK command with one ofthe stable access modes, use the following LINK statement in the virtualmachine’s directory entry:Link linkman 191 291 rrsRRS ensures the virtual machine a default logon access of read to the specifieddisk and permits this virtual machine to issue the LINK command with one ofthe stable modes at a later time. If the virtual machine issues the LINKcommand specifying the issuer’s own directory and the stable read accessmode of SR, password-level authorization will not be necessary. However, if ahigher level of access (such as SW or SM) is requested, password-levelauthorization would be required.Chapter 17. Creating and Updating a User Directory 503

LOADLOAD Directory Control Statement (Control)►► LOAD C control DIRMPARTG globaldefs $DIRECTP profileU useridU poolid POOLPART$DIRECTPmode*CLSTnnnn startrec reccount*******►◄PurposeThe LOAD statement tells DIRECTXA where the specified directory definition entryis located in a separate file or in a cluster file.How to SpecifyUse this statement only if the entire directory is being maintained in cluster-fileformat. If it is, this is the only record type found in the USER DIRECT file.OperandsCGPU specifies the type of definition to be loaded; C for CONTROL, G for Globaldefinitions, P for PROFILE, and U for USER.controlspecifies the file name of the file if the control definition (consisting only ofDIRECTORY statements) is in a separate file. Otherwise, this operand isignored.globaldefsspecifies the file name of the file containing the global definitions. If the globaldefinitions are not in a separate file, this operand is ignored.profilespecifies the name of the profile; if the profile definition is in a separate part file,profile is also the file name of the file.useridspecifies the user ID; if the user definition is in a separate part file, userid isalso the file name of the file.poolidspecifies the pool ID (the 1- to 3-character user ID used to define the pool); ifthe pool definition is in a separate part file, poolid is also the file name of thefile.DIRMPART$DIRECTspecifies the file type of the file if the directory definition is in a separate partfile; otherwise, this operand is ignored.POOLPART$DIRECTPspecifies that the directory definition is for a pool of users. If the directory504 z/VM: CP Planning and Administration

LOADUsageNotesdefinition is in a separate part file, the file type of the file must be DIRMPART or$DIRECT (DIRMPART if POOLPART is specified; $DIRECT if $DIRECTP isspecified).mode* specifies the alphabetic portion of the file mode of the separate part file or ofthe cluster file that contains the directory definition. If the mode is an asterisk(*), CP uses the CMS search order to locate the files.CLSTnnnn*******specifies whether the directory definition entry is located in a separate part fileor in a cluster file. If this operand is specified as *******, the directory is locatedin a separate part file. Otherwise, the directory definition is located in the clusterfile identified by CLSTnnnn CLUSTER mode, where nnnn is a decimal numberfrom 0000 to 9999.startrecspecifies the starting record number of the directory definition in the specifiedcluster file. The number must be greater than 0 and in decimal format.reccountspecifies the record count of the specified directory definition in the cluster file.The number must be greater than 0 and in decimal format.1. The following restrictions apply to cluster format and content:v A USER DIRECT file maintained in cluster file format should contain only onetype C definition, followed by zero or one type G definitions, followed by azero or more type P definitions, followed by a zero or more type U definitions.v Each definition in a cluster format source directory should contain only thenamed definition: the type C should contain only the DIRECTORYstatements, the type G should only contain global definition statements, eachtype P should only contain the named PROFILE definition, and each type Ushould only contain the named USER definition.v The first control statement of each definition should match the definition type.Thus, the first control statement in a type C definition should be aDIRECTORY statement, the first control statement in a type G definitionshould be a GLOBALDEFS statement, the first control statement in a type Pdefinition should be a PROFILE statement, and the first control statement in atype U definition should be a USER statement. Note also that comments andblank lines cannot be the first line in a definition. (This restriction is due to therelationship between DIRECTXA and DIRMAINT.)2. DIRMPART and $DIRECT are the only file types recognized for separate partfiles in a cluster file installation. The file types DIRMPART and $DIRECT areinterchangeable. However, DIRMPART is preferred. $DIRECT is a temporary filetype used by DIRMAINT.3. When you define a pool of users, you must specify POOLPART (or $DIRECTP).If the definition is in a separate part file, the file type of the separate part filemust be DIRMPART (or $DIRECT).4. When you use the z/VM Directory Maintenance Facility (DIRMAINT) to maintainthe source directory, you should leave the creation and maintenance of theLOAD statements strictly to DIRMAINT.5. To migrate a manually created and maintained cluster format source directory toDIRMAINT, it must first be converted to the sequential format.Chapter 17. Creating and Updating a User Directory 505

LOADExamplesTo define a directory in cluster file format with:v Three POSIXGROUP definitions, GRP0001, GRP0002 and GRP0003, in aseparate global definition part filev Two profiles, DEPT0000 and DEPT0001, where one is in a separate part file andthe other is in a cluster filev Three users, USER0001, USER0002, and USER0003, where two are in a clusterfile and the third is in a separate part filev Two pools of users, USR00001 through USR00025, and USR00050 throughUSR00075, where one is a separate part file and the other is in a cluster fileyou might use the following LOAD statements:Load C $dirctl$ dirmpart e *******Load G glbdefs dirmpart e *******Load P dept0000 dirmpart e *******Load P dept0001 dirmpart e clst0000 1 20Load U user0001 dirmpart e clst0000 21 5Load U user0002 dirmpart e clst0000 26 5Load U user0003 dirmpart e *******Load U usr poolpart e *******Load U usr poolpart e clst0000 31 2506 z/VM: CP Planning and Administration

LOADDEVLOADDEV Directory Control Statement (General)►► ▼ LOADDEV PORTname hhhhhhhhhhhhhhhhLUN hhhhhhhhhhhhhhhhBOOTprog bootprog_numberBR_LBA hhhhhhhhhhhhhhhhSCPdata ’text’HEX ’hh...hh’►◄Note: The maximum SCPDATA that can be input is 4096 whether as a text stringin quotes, or as hex characters.PurposeUse the LOADDEV directory statement to identify the location of a program to beloaded as a result of a guest IPL from SCSI disk. Additionally, parameters to bepassed to the program may also be defined.How to SpecifyIf you specify the LOADDEV statement, it must precede any device statements youspecify in a profile or user entry. Multiple LOADDEV statements are allowed withina user or profile entry. Each operand may only be specified once within a user orprofile entry. LOADDEV values within a user entry override those in a profile entry.Each LOADDEV statement may only specify one parameter.OperandsPORTnameThe hexadecimal digits designating the one- to eight-byte fibre channel portname of the FCP-I/O device. It must be a value from X'0-FFFFFFFFFFFFFFFF'.There is no default.LUNThe hexadecimal digits representing the one- to eight-byte logical unit numberof the FCP-I/O device. It must be a value from X'0-FFFFFFFFFFFFFFFF'. Thedefault is 0.BOOTprogThe decimal value between 0 and 30 representing the script to IPL from.BR_LBAThe hexadecimal digits designating the logical-block address of the boot recordof the FCP-I/O device. It must be a value from X'0-FFFFFFFFFFFFFFFF'. Thedefault is 0.SCPDATADesignates information to be passed to the program which was loaded duringguest IPL. If the program does not require any information, then this parameteris optional. Up to 4096 (4K) characters of data (text or hex) may be entered forSCPDATA. The actual number of input characters could be less depending onthe translation to UTF-8. Because two hex characters are required to representeach UTF-8 data byte, the maximum number of UTF-8 data bytes that can beChapter 17. Creating and Updating a User Directory 507

LOADDEVdefined using the HEX option is 2048 (1/2 of the 4K character input limit). Thehex string must be an even number of digits. There is no default.HEXIndicates that the parameter value that follows is UTF-8 encoded hex(characters 0-F). If not specified, the value is assumed to be EBCDIC text(codepage 924).’text’The text string in quotation marks is assumed to be in codepage 924.508 z/VM: CP Planning and Administration

LOGONBYLOGONBY Directory Control Statement (General)►► LOGONBY ▼ byuserid ►◄PurposeThe LOGONBY statement designates up to eight user IDs that can use their ownpasswords to log on to and use the virtual machine.How to SpecifyThe LOGONBY statement must precede any device statements in a user’s directoryentry. (For a list of device statements, see Table 20 on page 448.) A directory entrycan contain several LOGONBY statements, specifying up to eight user IDs.You can use several LOGONBY statements within a profile, but only if noLOGONBY statements are in the including user directory entry.Operandsbyuseridis a 1- to 8-character user ID that is to log on to this virtual machine with the BYoperand. Up to eight user IDs can be specified.UsageNotes1. When an External Security Manager (ESM) such as RACF is installed, theauthorization provided by the LOGONBY statement may be overridden. Also,RACF support has been added to perform authorization checks for attempts tolog on to shared user IDs. Refer to documentation provided by your ESM forfurther details.2. When a user logs on with the BY operand, that user’s ID is the by-user ID forthe virtual machine.3. The password of the by-user ID is used for LOGON authorization checking. Seethe z/VM: CP Commands and Utilities Reference for information about the BYoperand of the CP LOGON command.4. The current by-user ID for a virtual machine can be queried by using the CPQUERY BYUSER command, DIAGNOSE X'260' subcode 4, or DIAGNOSEX'26C' subcode 4.Examples1. To authorize user ID LARRY to log on to a virtual machine with the BY operand,put this LOGONBY statement in the virtual machine’s directory entry:LOGONBY larry2. To authorize user IDs OPER1, OPER2, OPER3, and JONES to log on to avirtual machine with the BY operand, put this LOGONBY statement in the virtualmachine’s directory entry: LOGONBY oper1 oper2 oper3 jonesChapter 17. Creating and Updating a User Directory 509

MACHINEMACHINE Directory Control Statement (General)(1)►► MACHine ESAXAXCmcpu►◄Notes:1 The default value is either 1 or the number of CPU statements for this user, whichever is greater.PurposeThe MACHINE statement specifies the virtual machine architecture.How to SpecifyOne MACHINE statement is allowed within a profile, but is used only if noMACHINE statement is in the user directory entry. If you specify the MACHINEstatement, it must precede any device statements you specify in a user’s directoryentry. (For a list of device statements, see Table 20 on page 448.)OperandsWhen processing the MACHINE statement, DIRECTXA checks for a maximum oftwo tokens: architecture type and maximum virtual processors, in that order. If youspecify more than two tokens, DIRECTXA ignores the extra tokens and systemprocessing continues as if you had not specified the extra tokens.ESAdesignates an ESA virtual machine, which simulates ESA/390 architecture.XAA guest operating system may have the capability to issue an instruction toswitch the virtual machine to z/Architecture mode.designates an XA virtual machine, which is functionally equivalent to an ESAvirtual machine.XCdesignates an XC virtual machine, which simulates ESA/XC architecture.mcpudefines the maximum number of virtual processors the user can define. Thenumber must be between 1 and 64 (decimal). The default value is either 1 orthe number of CPU statements for this user, whichever is greater.UsageNotes1. If you omit the MACHINE statement when you code a user’s directory entry andno CPU statements are in the user’s entry, the user’s virtual machine mode isdefined by the mode specified by the GLOBALOPTS directory controlstatement, and the virtual machine has no virtual multiprocessor capabilities.However, if CPU statements are in the user’s entry, the number of thesestatements determines the allowable number of virtual processors.510 z/VM: CP Planning and Administration

MACHINE2. For information on globally changing the default architecture, see“GLOBALOPTS Directory Control Statement (Control)” on page 486.3. For information on defining multiple virtual processors for a virtual machine, seez/VM: Running Guest Operating Systems.4. For compatibility, z/VM continues to accept the designation XA and continues toreport XA as the virtual machine mode in response to the QUERY SET andINDICATE USER commands when the virtual machine has been defined usingthe XA designation. However, whether the virtual machine is defined as XA orESA makes no difference when running on z/VM. A virtual machine defined asXA has the capabilities of an ESA virtual machine and is considered by CP tobe an ESA virtual machine.Examples1. To specify that a virtual machine can simulate ESA/390 architecture, use thefollowing MACHINE statement in the virtual machine’s directory entry:Machine esa2. To specify that a virtual machine can simulate ESA/390 architecture and definea maximum of 12 virtual processors, use the following MACHINE statement inthe virtual machine’s directory entry:Machine esa 123. To specify that a virtual machine can simulate the ESA/XC architecture, use thefollowing MACHINE statement in the virtual machine’s directory entry:Machine xcChapter 17. Creating and Updating a User Directory 511

MAXSTORAGEMAXSTORAGE Directory Control Statement (General)►► MAXSTORAGE size ►◄PurposeThe MAXSTORAGE statement specifies the maximum virtual storage size for auser.How to SpecifyThe MAXSTORAGE statement, if used, must follow a USER statement and mustprecede any device statements. A MAXSTORAGE statement is allowed in a profileif the USER statement maximum storage size field of each of the including virtualmachines is either omitted or specified as an asterisk (*). A MAXSTORAGEstatement in a user directory entry overrides one in a profile.Operandssizeis the maximum storage size. Specify it as nu, where n is a decimal numberand u is the unit of measure:K kilobytes - 2¹⁰M megabytes - 2²⁰G gigabytes - 2³⁰T terabytes - 2⁴⁰P petabytes - 2⁵⁰E exabytes - 2⁶⁰UsageNotes1. A maximum storage setting on a USER statement overrides a MAXSTORAGEstatement in a profile.2. A MAXSTORAGE statement in a user’s directory entry overrides one in aprofile.512 z/VM: CP Planning and Administration

MDISKMDISK Directory Control Statement (Device)►► Mdisk vdev devtype Operands ►◄OperandsWcyl cyls volidEND &SYSRES modeblk blks volid modesuffix PasswordEND &SYSRESDEVNO rdevV-DISK blksT-DISK cylsblksPasswordprALLpwALLpmALLPurposeThe MDISK statement defines minidisks (virtual disks) for virtual machines:permanent minidisks, temporary minidisks, and virtual disks in storage. TheDASDOPT statement is an extension to the MDISK statement. The MDISKstatement defaults to DEVCTL if no DASDOPT statement follows. For moreinformation about the DASDOPT statement, see “DASDOPT Directory ControlStatement (Device)” on page 472. You can use one DASD to provide severalminidisks or you can use one DASD to provide one minidisk.Note: CP and the directory program do not completely prevent you from definingminidisks that overlap. Overlap defeats the integrity of link access modesand RESERVE/RELEASE. If you define such overlap, you assumeresponsibility for data integrity.How to SpecifyMDISK statements are not allowed within a profile entry. If you specify the MDISKstatement, it must follow any general statements you specify in a user’s directoryentry. (For a list of general statements, see Table 20 on page 448.)Operandsvdevis the virtual device number of the minidisk.devtypeis the device type of the minidisk.v For a permanent minidisk or temporary disk, this is the device type of thereal device on which the minidisk resides. Valid device types are:Chapter 17. Creating and Updating a User Directory 513

MDISKcylblk3380 3390 9336 FB-512FB-512 is a generic specification for FBA DASD and may be used in lieu of aspecific FBA device type (9336). A 3390 in 3380 track-compatibility modemust be coded as a 3380.v For a virtual disk in storage, which is not mapped to a real DASD, this is thedevice type of the device that is simulated in system storage. A virtual disk instorage simulates an FBA minidisk; therefore, the device type must beFB-512.is the starting cylinder (CKD/ECKD) or block number (FBA) on the real DASDyou specify on the volid operand.DEVNOspecifies a full-pack minidisk.V-DISKindicates that the minidisk is a virtual disk in storage. A virtual disk in storage istemporary but shareable; it is created when the first user links to it anddestroyed when the last user detaches it or logs off.T-DISKindicates that the minidisk is temporary, that is, it is created from a preselectedpool of temporary disk space when the virtual machine logs on and is returnedto the pool when the virtual machine logs off or the virtual device is detached.Temporary disks cannot have passwords.cylsblksis the number of cylinders (CKD/ECKD) or blocks (FBA) allocated to theminidisk. Table 23 on page 517 shows the number of cylinders or blocksavailable in each format for each device type on which you can put minidisks.ENDspecifies that the minidisk should be defined with the remaining availablecylinders or blocks. This is useful when defining a full-pack minidisk. See usagenote 4 on page 518 for more information.rdevis the real device number.volidis the volume serial number of the real DASD volume on which the minidiskresides.&SYSRESindicates that the minidisk resides on whichever real DASD is the VM systemresidence volume. This volume is established when VM is IPLed but canchange from one IPL to another.Use the &SYSRES option of the DIRECTXA command to assign a value to beused to represent the volum serial number of the system residence volume forminidisks defined using the &SYSRES operand on the MDISK statement.This value is used in responses from the VMUDQ LISTMDSK function. If the&SYSRES option is omitted on the DIRECTXA command, a value of +VMRESis used.514 z/VM: CP Planning and Administration

MDISKmodeis the access mode for the minidisk. The first letter in the access mode is theprimary access mode (read-only, write, or multiple-write); the second letter(optional) is the alternate access (read-only or write).The access modes are:R Read-only access. Read access is established, unless another user holds awrite or an exclusive mode (ER, EW) access to the disk.RRRead-only access. Read access is established, unless another user holdsan exclusive mode (ER, EW) access.W Write access. Write access is established, unless another user holdsaccess (any mode) to the disk. If you do not specify an access mode on theMDISK statement, the default is W.WRWrite access. Write access is established unless another user holds access(any mode) to the disk. If write access is denied, read access is establishedunless another user holds an exclusive (ER, EW) mode access for the disk.M Multiple-write access. Write access is established unless another user holdsa write, a stable (SR, SW, SM) or an exclusive (ER, EW) mode access tothe disk.MRMultiple-write access. Write access is established unless another user has awrite, stable (SR, SW, SM) or exclusive mode (ER, EW) access to the disk.In the case of a previous write or stable (SR, SW, SM) access, read-onlyaccess is established. In the case of an exclusive mode access existing,access is denied.MWMultiple-write access. Write access is established in all cases except whenanother user holds either a stable (SR, SW, SM) or an exclusive mode (ER,EW) access to the disk.modesuffixThe optional mode suffix letters authorize virtual reserve/release and the use ofthe stable and exclusive (data integrity) access modes of the CP LINKcommand and DIAGNOSE code X'E4'. The specification here on the MDISKstatement allows the user to enter a LINK command with the specified type ofaccess mode, stable or exclusive. For more information about stable andexclusive access modes, see the z/VM: CP Commands and Utilities Reference.The suffix letters can be combined as follows (note that CP requires they bespecified in this order):1. V or null, plus2. S, E, or null (S and E are mutually exclusive), plus3. D or null.Therefore, the only valid combinations are: V, S, E, D, VS, VE, VD, VSD, VED,SD, or ED. This suffix is in turn concatenated with the mode, with nointervening blanks. For example, RV, RRS, WVE, and MVSD are all valid.V Tells CP to use its virtual reserve/release support in the I/O operations forthe minidisk. For example, MWV means the minidisk functions with writelinkage using CP’s virtual reserve/release.S Authorizes the virtual machine in whose directory definition this statementChapter 17. Creating and Updating a User Directory 515

MDISKappears the ability to use the LINK command stable access modes (SR,SW, SM) against the specified user’s minidisk. For more information, seethe z/VM: CP Commands and Utilities Reference.E Authorizes the virtual machine in whose directory definition this statementappears the ability to use the LINK command exclusive and stable accessmodes (ER, EW, SR, SW, SM) against the specified user’s minidisk. Formore information, see the z/VM: CP Commands and Utilities Reference.D Tells CP that the device should not be defined when the virtual machineinitially logs on or is autologged, but to defer doing so until an explicit LINKcommand is issued for that device.prALLis the password that allows sharing the minidisk (by using the CP LINKcommand) in read mode. The variable pr is a 1- to 8-character string. If youspecify ALL, a user can link in read mode to this minidisk without using apassword.pwALLis the password that allows sharing the minidisk (by using the CP LINKcommand) in write mode. If you specify ALL, a user can link in write mode tothis minidisk without using a password.pmALLis the password that allows sharing the minidisk (by using the CP LINKcommand) in multiple-write mode. The variable pm is a 1- to 8-character string.If you specify ALL, a user can link in multiple-write mode to this minidisk withoutusing a password.516 z/VM: CP Planning and Administration

MDISK|||||||||||||Table 23. Maximum Minidisk SizesDevice Type ModelsCMS/VSAM, CMS512-Byte, 1 KB, 2 KB, or4 KB Format3380 A04, AA4, B04, AD4, BD4, AJ4, BJ4, CJ2 885 cylinders3380 AE4, BE4 1770 cylinders3380 AK4, BK4 2655 cylinders3390 ¹ A14, A18, B14, B18, B1C 1113 cylinders3390 ¹ A24, A28, B24, B28, B2C 2226 cylinders3390 ¹ A34, A38, B34, B38, B3C 3339 cylinders3390 ² A98, B9C 10017 cylinders9336 020 2147483640 blocksFB-512 (virtual disk in storage) (not applicable) 4194296 blocksNotes:¹ These capacities apply to 3390 mode and 3380 track compatibility mode.² 3380 track compatibility mode is not supported for these 3390 models.³ Minidisks used with VSAM are limited to 64 KB (65,536) tracks (4369 3390 cylinders). This is a limitation of theVSE/VSAM licensed program. This limit applies whether the minidisk is used by a VSE guest or by CMS/VSAM.⁴ Value can be up to the maximum number of cylinders on the DASD (CMS and GCS are limited to 32767cylinders).⁵ z/VM supports a SCSI disk, which is emulated as a 9336-020, up to a capacity of 2147483640 512-byte blocks(1 terabyte minus 1 page). Note, however, that directory, paging, and spooling allocations must reside within thefirst 16777216 blocks (blocks 0 to 16777215) of a CP-formatted disk.⁶Due to CMS file system limitations for status and control information to reside below 16 MB in virtual storage,there is a practical limitation on the size of CMS minidisks. As a minidisk increases in size, or more files reside onthe disk, the amount of virtual storage associated with the disk for CMS file system status and control increases instorage below 16 MB. The current ECKD DASD limitation is 32767 cylinders for a 3390 disk on an ESS device, orabout 22 GB of data. IBM suggests that customers defining FBA SCSI disks for use by CMS set a practical limit ofabout 22 GB. If larger disks are defined, they should be limited to contain very few files, or the CMS file systemmay not be able to obtain enough virtual storage below 16 MB to format or access those disks. For moreinformation, see the ACCESS command in the z/VM: CMS Commands and Utilities Reference. The maximum sizefor FBA SCSI disks supported for use by CMS or GCS is 381 GB.3, 4, 65, 6UsageNotes1. You must format a temporary minidisk or virtual disk in storage before you useit. If you want to format the disk for CP use, use the Device Support Facility(ICKDSF) program; it is the recommended method of CP volume maintenance.For more information about ICKDSF procedures, see the Device SupportFacilities User’s Guide and Reference, GC35-0033. If you want to format thedisk for CMS use, use the CMS FORMAT command as described in the z/VM:CMS Commands and Utilities Reference. To format minidisk space for otheroperating systems, use the commands of the operating system that controlsthe minidisk.2. If a user has written sensitive data on temporary disk space, he shouldreformat the disk before detaching it from his virtual machine. If the system isconfigured to clear all temporary disk space, this clearing is done by thesystem. You can determine whether temporary disk clearing is enabled byentering the QUERY TDISKCLR command. This action removes any risk ofsecurity exposure.Chapter 17. Creating and Updating a User Directory 517

MDISK518 z/VM: CP Planning and Administration3. If for some reason two or more volumes have the same label, CP defines theminidisk on the volume that is attached to the system. (You cannot attach twovolumes with the same label to the system at the same time.)4. To define a full-pack minidisk you must specify that the minidisk is to containall of a DASD’s primary cylinders or blocks. To do this, specify '0' to 'END' onthe MDISK statement. Note that:v A minidisk beginning with cylinder 1 or block 1 is not a full-pack minidisk.v You should use the keyword 'END' so your MDISK statement is notdependant on the size and type of DASD.You can optionally specify any of the DASD’s alternate cylinders or blocks, butthose cylinders or blocks, and all others, are accessible to anyone with afull-pack minidisk.5. Full-pack minidisks that overlap other minidisks are ignored during link accessmode checking. However, you should not define any other type of overlap. CPdoes the overlap checking to ensure the integrity of link access modes. This isnot a feature to exploit.If you do overlap other minidisks, you may be:v Prevented from linking to those minidisks and receive messages HCP104E,HCP105E, and HCP106E, orv Linked read only to those minidisks and receive messages HCP101E,HCP102E, and HCP103E.6. The 3990s used for CP volumes will be supported in either 3380 trackcompatibility mode or 3390 mode of operation on a volume basis except forthe 3390 Model 9 which does not support 3380 track compatibility mode. Theability to change modes is restricted to guests with the OPTION statementvalue MAINTCCW or DEVMAINT. The use of ICKDSF is the recommendedmethod to change modes.7. Read Special home address and Write Special home address CCWs are onlysupported for dedicated and full-pack minidisks for guests with the OPTIONstatement value MAINTCCW or DEVMAINT.8. The use of the stable (SR, SW, and SM) and exclusive (ER and EW) linkmodes can be authorized in two different ways, either globally using theOPTION statement values, LNKSTABL and LNKEXCLU, or specifically, usingthe mode suffix letter on the MDISK or LINK statements.9. The DEVNO operand allows the user to define a full-pack minidisk byspecifying the real device number of the minidisk. This operand must be usedwhen defining full-pack minidisks where the guest will control the duplexing ofthe device.10. The DEVNO operand should be used when defining multiple minidisks withidentical volume serial numbers.11. Refer to the appropriate storage control manuals for additional dual copyinformation.12. For information on the use of the MDISK statement for the CMS shared filesystem, refer to the z/VM: CMS File Pool Planning, Administration, andOperation book.13. If an external security manager (ESM) is installed, you may not be authorizedto use the MDISK statement for all minidisks and all access modes. The ESMmay downgrade certain requests for write access to read access. Foradditional information, contact your security administrator.14. Virtual disks in storage and FBA temporary minidisks are created in 8-blockpages. Therefore, the size of the virtual disk in storage or FBA temporaryminidisk that is created may be rounded up to the nearest page.

MDISK15. If you define a minidisk as virtual device number 192, the following specialrules apply when you IPL CMS:v If 192 is an unformatted temporary minidisk or virtual disk in storage, CMSformats it and accessed it as file mode D.v If 192 is a CP-formatted temporary minidisk or virtual disk in storage, CMSreformats it for CMS use and accesses it as file mode D.v If 192 is a CMS-formatted temporary minidisk, virtual disk in storage, orpermanent minidisk that is accessed as a file mode other than D, CMSreaccesses it as file mode D.v If 192 is an unformatted or CP-formatted permanent minidisk, CMS does notautomatically format, reformat, access, or reaccess it.When CMS accesses a 192 minidisk as file mode D, any minidisk or SFSdirectory already accessed as D is released.16. If you change the definition of a permanent minidisk while users are linked toit, existing links are unchanged, but any new links are made using the newdefinition of the minidisk. Unpredictable results may occur.17. If you change the definition of a virtual disk in storage while users are linked toit, existing links are unchanged, and any new links are made to the existingvirtual disk in storage. The existing virtual disk in storage is used until the lastuser detaches it or logs off, at which time the virtual disk in storage isdestroyed. After that, any new links use the new definition of the virtual disk instorage.18. Some programs may not support the use of &SYSRES, and require the use ofa synonym. The synonym is the value specified on the DIRECTXA commandwith the &SYSRES operand. If the &SYSRES option is omitted on theDIRECTXA command, a synonym of +VMRES is used. In other words, either&SYSRES or its synonym may be used to define a minidisk on the systemresidence volume.Examples1. To define a minidisk that:v Has the virtual device number 191v Takes up 5 cylinders beginning at cylinder 100 of the 3380 DASD withvolume serial MDDASDv Is accessible only in read-only modev Cannot be linked to in any mode (no passwords are specified)use the following MDISK statement in the virtual machine’s directory entry:Mdisk 191 3380 100 5 mddasd rr2. To define a minidisk that:v Has the virtual device number 291v Takes up 10 cylinders beginning at cylinder 105 of the 3380 DASD withvolume serial MDDASDv Is accessible only in read or write modev Can be linked to by anyone in read mode (but no other mode)use the following MDISK statement in the virtual machine’s directory entry:Mdisk 291 3380 105 10 mddasd mr all3. To define a minidisk that:v Has the virtual device number 198v Takes up 6000 blocks beginning at block 12,000 of a supported FBA DASDwith volume serial FBDASDChapter 17. Creating and Updating a User Directory 519

MDISKv Is accessible only in multiple-write (MW) modesv Can be shared using CP’s virtual reserve/releasev Has a read password of 12WE45use the following MDISK statement in the virtual machine’s directory entry:Mdisk 198 9336 12000 6000 fbdasd mwv 12we454. To define a minidisk that:v Has the virtual device number 198v Takes up 6000 blocks beginning at block 12,000 of the 9336 DASD withvolume serial FBDASDv Will have the default access mode of Write when the virtual machine islogged on, but will specifically authorize the user to access it with a stableaccess mode using the LINK command at a later time.v Can be shared using CP’s virtual reserve/releasev Has a read password of 12WE45use the following MDISK statement in the virtual machine’s directory entry:Mdisk 198 fb-512 12000 6000 fbdasd mvs 12we455. To define 5 cylinders of temporary 3380 DASD space at virtual device number391, use the following MDISK statement in the virtual machine’s directoryentry:Mdisk 391 3380 t-disk 56. To define 4000 blocks of temporary FBA DASD space at virtual device 392,use the following MDISK statement in the virtual machine’s directory entry:Mdisk 392 fb-512 t-disk 40007. To define a 3380 DASD full-pack minidisk at virtual device number 199, useone of the following MDISK statements in the virtual machine’s directory entry:Mdisk 199 3380 000 885 mddasd mrMdisk 199 3380 000 end mddasd mr8. To define a pair of full-pack minidisks that are candidates for duplexing and:v Have virtual device numbers 198 and 199v Have real device numbers 200 and 201v Are accessible in read or write modev Can be linked to by anyone in read modeuse the following MDISK statements in the virtual machine’s directory entry:mdisk 198 3390 devno 200 mr allmdisk 199 3390 devno 201 mr all9. To define a virtual disk in storage that:v Has virtual device number 401v Consists of 8000 blocksv Is accessible in read or write modev Can be shared using CP’s virtual reserve/releaseuse the following MDISK statement in the virtual machine’s directory entry:mdisk 401 fb-512 v-disk 8000 mwv10. To define a minidisk using a synonym of VM-RES instead of &SYSRES, usethe following MDISK statement:MDISK 123 3390 0 END VM-RES RRand use the following command to place the directory online:DIRECTXA USER DIRECT (&SYSRES VM-RES520 z/VM: CP Planning and Administration

MDISKMinidisk RestrictionsThe following restrictions exist for minidisks:1. In the following cases, z/VM modifies the cylinder data in user storage at thecompletion of the channel program:Read Home Address (with the skip bit off)Read Record Zero (with the skip bit off)Sense (with the skip bit off)Read Track (with the skip bit off)Read Device Characteristics.This is necessary because the addresses must be converted for minidisks.Therefore, the data buffer area may not be dynamically modified during the I/Ooperation in these cases.Note: For the Read Record Zero case, the above restriction does not apply todevices that do not provide alternate track recovery.2. On a minidisk, if a CCW string uses multitrack-search on I/O operations,subsequent operations to that disk must have preceding seeks or continue touse multitrack operations. There is no restriction for dedicated disks.3. If the user’s channel program for a count-key-data minidisk does not perform aseek operation, CP inserts a positioning seek operation into the user’s channelprogram to prevent accidental accessing. Thus, certain channel programs maygenerate a condition code (CC) of 0 on an SIO instead of the expected CC of1, which is reflected to a virtual machine. The final status is reflected to thevirtual machine as an interruption. The final states for some channel programsinitiated through an SIOF or SSCH may not indicate deferred CC 1.4. A DASD channel program may give results on dedicated DASD that differ fromresults on minidisks having nonzero relocation factors if the channel programincludes multiple-track operations and depends on a Search ID High or SearchID Equal or High to terminate the program. The record 0 count fields on thesedevices must contain the real cylinder number of the track on which theyreside. Therefore, a Search ID High, for example, based on a low virtualcylinder number, may terminate prematurely if a real record 0 is encountered.Minidisks with nonzero relocation factors are not usable under OS and OS/VSsystems. This is because the locate catalog management function employs aSearch ID Equal or High CCW to find the end of the VTOC.5. The IBCDASDI program cannot assign alternate tracks.Notes:a. Device-Support Facilities (ICKDSF) may assign alternate tracksb. Alternate track assignment is permitted for full-pack minidisks only.6. If the DASD channel programs include a Write Record Zero CCW or a WriteHome Address CCW, the results depend on whether the device is dedicated ornot dedicated. For a dedicated DASD, a Write Record Zero or a Write HomeAddress CCW is allowed, but the user must be aware that the track descriptorrecord may not be valid from one DASD to another. For a DASD that is notdedicated, a Write Record Zero or a Write Home Address CCW is acceptedonly if the device is a full-pack minidisk. CP rejects the command if the deviceissuing a Write Record Zero or a Write Home Address CCW on anondedicated DASD is not defined as a full-pack minidisk.7. When performing DASD I/O, if the record field of a Search ID Argument is zerowhen a virtual SIO, SIOF, or SSCH is issued, but the Search ID Argument isdynamically read by the channel program before the Search ID CCW isChapter 17. Creating and Updating a User Directory 521

MDISKexecuted, the real Search ID uses the relocated search argument instead ofthe argument that was read dynamically. To avoid this problem, the record fieldof a Search ID Argument should not be set to binary zero if the searchargument is to be dynamically read or if the search ID on record 0 is notintended.8. The following CCWs are restricted to virtual machines with MAINTCCWauthority. You specify this authority by coding the MAINTCCW operand on theOPTION statement in the virtual machine’s user directory entry.v Diagnostic Write Home Addressv Diagnostic Read Home Addressv Write Record Zerov Diagnostic Loadv Diagnostic Sense/Reset Allegiance: CP treats the command as a resetallegiance CCW and accepts it as long as it is the first CCW in the channelprogram.v Diagnostic Writev Diagnostic Sense/Readv Diagnostic Control9. Diagnostic Read Home Address and Diagnostic Write Home Addresscommands are supported only for dedicated and full-pack 3375, 3380, 3390,and 9345 minidisks.All Diagnostic CCWs are restricted to users with the OPTION statement valueMAINTCCW or DEVMAINT.10. Refer to OS/VS Device Support Facilities for procedures to format allsupported DASDs for use in an OS/VS operating system running in a virtualmachine.11. The 3390s used for CP volumes are supported in either 3380 trackcompatibility mode or 3390 mode of operation on a volume basis except forthe 3390 Model 9 which does not support 3380 track compatibility mode. Theability to change operating modes is restricted to guests with the OPTIONstatement value MAINTCCW or DEVMAINT. The use of ICKDSF is therecommended method to change modes.12. A user should never have an MDISK statement with the DEVNO operand andan MDISK statement with the volume serial number operand for the samevolume.13. Access to cache control units is controlled by the settings of level of control forthese units. For more information, see “DASDOPT Directory Control Statement(Device)” on page 472.14. Minidisks defined on an FBA volume which are not page-aligned will not beeligible for minidisk cache and will therefore not benefit from its performanceimprovement. Aligning minidisks on page boundaries is highly recommended.Minidisks as well as full-pack minidisk volumes that are not page-aligned mayresult in residual blocks that are not formatted and utilized. Additionalrestrictions apply for SFS Filepool minidisks which are not page-aligned. Formore information see the z/VM: CMS File Pool Planning, Administration, andOperation. If the starting block number is a multiple of eight and the number ofblocks is a multiple of eight, then the minidisk is defined to be page-aligned.Note: Under the conditions outlined in the above usage note, residual blockson FBA devices that have not been ICKDSF formatted may still bedefined and used as MDISK space.522 z/VM: CP Planning and Administration

MDISK15. Minidisks defined on an FBA volume which are not page aligned cannot bemapped to an address space using minidisk mapping.Chapter 17. Creating and Updating a User Directory 523

MINIOPTMINIOPT Directory Control Statement (Device)►►MINIOPT(1)CACHENOCACHEMDCNOMDCRECORDMDcNOWRKALlegWRKALleg►◄Notes:1 Options can be in any order.PurposeThe MINIOPT statement is an extension to the MDISK statement and mustimmediately follow an MDISK statement that defines a non-full-pack minidisk. If youwant to use a full-pack minidisk, you can use a DASDOPT statement with theMDISK statement.How to SpecifyMINIOPT statements are not allowed within a profile entry.OperandsCACHEmeans that the minidisk has access to the control unit cache. This is the defaultif neither CACHE or NOCACHE are specified.NOCACHEmeans that CP forces I/O for the minidisk to bypass the control unit cache.MDCspecifies that the minidisk will use the full track minidisk cache as long ascaching is set to DFLTON or DFLTOFF for the real device. If neither MDC,NOMDC, nor RECORDMDc is specified, then the minidisk will use the full trackminidisk cache as long as caching is set to DFLTON for the real device.NOMDCspecifies that the minidisk will not use the full track minidisk cache. If neitherMDC, NOMDC, nor RECORDMDc is specified, then the minidisk will use the fulltrack minidisk cache as long as caching is set to DFLTON for the real device.RECORDMDcspecifies that the minidisk will use record level minidisk caching rather thannormal full track minidisk caching as long as caching is set to DFLTON orDFLTOFF for the real device. If neither MDC, NOMDC, nor RECORDMDc isspecified, then the minidisk will use full track minidisk cache as long as cachingis set to DFLTON for the real device.524 z/VM: CP Planning and Administration

MINIOPTUsageNotesCAUTION:Use of this option is a last resort for very special and unusualcircumstances. It should only be used as the result of consultation withIBM support personnel who have concluded that no other problem exists.Its use should occur only after trials using the SET MDCACHE MDISK ONcommand’s RECORDMDc option have proven that this truly solves theperformance problem. Using this option for any other reason may mask aperformance problem which when corrected allows normal full trackminidisk cache to perform better than with the RECORDMDc option.WRKALlegcauses working allegiance to be simulated on the minidisk.NOWRKALlegcauses no simulated working allegiance for the minidisk. This is the default.1. IBM recommends that the defaults of both control unit caching and minidiskcaching be used. The default double caching of data should not degrade theperformance of normal minidisk operation. MINIOPT statements should be usedonly in cases of shared DASD and specific data/transaction-related performanceproblems.2. WRKALLEG must be used when running two or more z/OS guests as part of aSysplex configuration using the cross-system coupling facility (XCF) componentof z/OS. This option must be used for any minidisk containing the XCF coupledataset to maintain cross-system lock integrity (and thereby, data integrity)within the sysplex.3. WRKALLEG is valid only when the preceding MDISK statement gives the userwrite access to the minidisk. If the MDISK statement specifies read-only access,CP rejects the WRKALLEG statement and issues an error message.Furthermore, working allegiance is simulated only when a guest with writeaccess initiates I/O.4. Implementation of caching by the system depends on the following:v For the control unit if:– It is a cached control unit– The subsystem is enabled for cache operation– The caching function is turned on for the devicev For minidisk cache if:– Minidisk is on a device supported by minidisk cache.– Minidisk caching is enabled for the system.– Minidisk caching is set to DFLTON for the real device and either MINIOPTMDC is specified or no minidisk cache option is specified on the MINIOPTstatement for the minidisk; or minidisk caching is set to DFLTOFF for thereal device and MINIOPT MDC is specified for the minidisk:Cache setting for real device MINIOPTDefaultMINIOPTMDCDFLTON ON ON OFFDFLTOFF OFF ON OFFOFF OFF OFF OFFMINIOPTNOMDCFor example:- If DFLTON and MINIOPT is NOMDC, then caching is off.Chapter 17. Creating and Updating a User Directory 525

MINIOPT- If DFLTOFF and MINIOPT is MDC, then caching is on.– For FBA devices, the minidisk is page-aligned5. Optimization of cache use may be made after an analysis of your productionuse has been made. This is accomplished by adding MINIOPT statements thatcause the I/O subsystem to bypass the use of either or both of the cachingtechniques.6. MINIOPT is not valid for full-pack minidisks. For full-pack minidisks, use theDASDOPT statement (page 472).7. MINIOPT is ignored if it follows an MDISK statement that defines a virtual diskin storage.8. The RECORDMDc option should only be used when directed to do so by IBMsupport personnel. RECORDMDc is for use only when DASD cache as well asmain storage and expanded storage minidisk cache are all being overwhelmedby excessive unreferenced records being read by the full track cache support.Examples1. If the minidisk specified by the MDISK statement is to have access to thecontrol unit cache, use the following MINIOPT statement:MiniOpt Cache2. If the minidisk specified by the MDISK statement will not use the minidiskcache, use the following MINIOPT statement:MiniOpt NoMdc3. If the minidisk specified by the MDISK statement will have simulated workingallegiance, use the following MINIOPT statement:MINIOPT WRKALleg526 z/VM: CP Planning and Administration

NAMESAVENAMESAVE Directory Control Statement (General)►► NAMEsave ▼ (1)sysseg►◄Notes:1 Specify sysseg up to 8 times.PurposeThe NAMESAVE statement authorizes a virtual machine to access a restrictednamed saved system or saved segment. The NAMESAVE statement alsoauthorizes a virtual machine to access and load a private copy of a nonrestrictedsaved segment, using the load nonshared function of DIAGNOSE code X'64'. If thevirtual machine has the appropriate NAMESAVE entry, it can access a private copyof a saved segment (whether or not the saved segment is restricted) for debugging,using the load nonshared function of DIAGNOSE code X'64'. (For more information,see Usage Note 3.)How to SpecifyYou can specify multiple NAMESAVE statements for each virtual machine. If youspecify the NAMESAVE statement, it must precede any device statements youspecify in a user’s directory entry. (For a list of device statements, see Table 20 onpage 448.)OperandsMultiple NAMESAVE statements are allowed within a profile entry. NAMESAVEstatements within a profile entry are added to those in the including user entry withno duplicate checking performed.syssegis the 1- to 8-character alphanumeric name of the named saved system orsaved segment that you are authorizing a virtual machine to access. You canspecify a maximum of eight names.Note: sysseg cannot be a member name. Members are authorized by thesegment space they are in.UsageNotes1. Each NAMESAVE statement can specify up to eight named saved systems andeight saved segments.2. For information on creating named saved systems, see the z/VM: VirtualMachine Operation book.3. If you have the appropriate NAMESAVE entry, you can access a private copy ofa saved segment (whether or not the saved segment is restricted) for debuggingpurposes, using the load nonshared function of DIAGNOSE code X'64'. Whenyou do this, you receive exclusive read/write access to all the page ranges inthe saved segment, regardless of the type of access specified on the CPDEFSEG command when the saved segment was defined.Chapter 17. Creating and Updating a User Directory 527

NAMESAVE4. To access a private copy of a named saved system, you must IPL by devicenumber. You cannot specify that a private copy of a named saved systemshould be loaded.5. When packing DCSSs you must have the segment space name in aNAMESAVE statement.Examples1. To indicate that a virtual machine can access the restricted named savedsystems MVSXA1 and MVSXA2, use the following NAMESAVE statement in thevirtual machine’s directory entry:NameSave mvsxa1 mvsxa22. To indicate that a virtual machine can access both of the following:a. The restricted named saved systems MVSXA1 and MVSXA2b. The restricted saved segment XASEGuse the following NAMESAVE statement in the virtual machine’s directory entry:NameSave mvsxa1 mvsxa2 xaseg3. To indicate that a virtual machine can access a private copy of the nonrestrictedsaved segment XASEG1, use the following NAMESAVE statement in the virtualmachine’s directory entry:NameSave xaseg1528 z/VM: CP Planning and Administration

NICDEFNICDEF Directory Control Statement (Device)►►NICDEF vdev ▼ TYPE HIPERsocketsQDIODEVices devsLAN ownerid lanname*SYSTEM switchnmCHPID nnMACID xxxxxx►◄PurposeThe NICDEF statement defines virtual network adapters that are fully simulated byCP. Use NICDEF to create a virtual HiperSockets or QDIO adapter in the virtualmachine, and (optionally) connect it to a VM LAN or Virtual Switch.How to SpecifyIf you specify the NICDEF statement, it must follow any general statements youspecify in a user’s directory entry. (For a list of general statements, see Table 20 onpage 448.)The SPECIAL statement may also be used to define virtual network adapters in avirtual machine. However, there are additional configuration options available withthe NICDEF statement. NICDEF statements are not compatible with the SPECIALstatements for the same vdev. You cannot define some attributes on the SPECIALstatement and some attributes on a NICDEF statement.NICDEF statements are allowed within a profile entry if no conflicting statements forthe virtual device numbers are in the profile. When a NICDEF statement in the userentry matches the virtual device number in the profile, the USER entry replaces theprofile entry.Operandsvdevis the base (or first) device address in a series of virtual I/O devices that belongto the same unit.TYPE HIPERsockets | QDIOindicates the type of adapter to be created. This is a required keyword, and itmust be the first keyword specified.Use HIPERsockets for a simulation of the zSeries HiperSockets feature orQDIO for a simulation of the OSA Express feature in QDIO mode. If a LAN isidentified in this statement or another with the same vdev, the NIC isautomatically coupled to the specified ownerid lanname.DEVices devsis the number (decimal) of virtual I/O devices to be created for a simulatedNetwork Interface Card (NIC). This number is evaluated during LOGONprocessing.Chapter 17. Creating and Updating a User Directory 529

NICDEFTable 24. Number (Decimal) of Virtual I/O DevicesAdapter TYPE Minimum Maximum DefaultHiperSockets 3 3072 3QDIO 3 240 3UsageNotesLAN [ ownerid|* lanname ] [ SYSTEM switchnm ]identifies a virtual LAN segment for an immediate connection to the NetworkInterface Card (NIC). When ownerid is specified as an asterisk (*), it is resolvedas the user ID of the current virtual machine. When the LAN operand is omitted,the adapter is left in the default (uncoupled) state. When LAN ownerid lannameis identified in this statement or another with the same vdev, the adapter isconnected to the designated virtual LAN segment automatically.Ownerid may be specified as SYSTEM, indicating the virtual LAN segment maybe a virtual switch or a system-owned LAN.Note: If you must define an adapter type, ensure that it is compatible with theintended Guest LAN or virtual switch.CHPID xxis a two digit hexadecimal number that represents the Channel Path ID (CHPID)number to be allocated in the virtual machine I/O configuration for this adapter.If CHPID is omitted, an available CHPID is automatically assigned to thisadapter. This option is required when a HiperSockets adapter is being createdfor a z/OS guest because z/OS configurations require a predictable CHPIDnumber. During LOGON, CP attempts to use the specified CHPID number. Ifthe specified CHPID number is already in use, this adapter is not defined. Tocorrect this situation, you must eliminate the conflicting device or select adifferent CHPID.MACID xxxxxxis a unique identifier (up to six hexadecimal digits) used as part of the adapterMAC Address. During LOGON, your MACID (three bytes) is appended to thesystem MACPREFIX (three bytes) to form a unique MAC Address for thisadapter. If MACID is omitted from this definition, CP generates a uniqueidentifier for this adapter. If the specified MACID is already in use, this adapteris not defined. To correct this situation, you must eliminate the conflicting deviceor select a different MACID.1. When a simulated NIC is defined (HIPERsockets or QDIO device types), theNICDEF statement results in the creation of a series of I/O devices. The basedevice is validated by directory processing, but the remaining devices in therange are validated during LOGON processing. If another device is found in therange established by vdev and devs, the simulated NIC cannot be created.2. It is possible to define a simulated NIC that will be automatically coupled to aVM LAN or Virtual Switch by adding the optional LAN parameter. However, ifthe designated VM LAN or Virtual Switch is not available when this user signson, the COUPLE function cannot be performed. To make effective use of thisfeature, you must consider adding a DEFINE LAN or DEFINE VSWITCHstatement in the SYSTEM CONFIG file to create the target VM LAN or VirtualSwitch during system initialization.530 z/VM: CP Planning and Administration

NICDEFExamples1. Define a simulated QDIO adapter using I/O devices 0500–0507 (eight devices)which will be coupled to the SYSTEM-owned INEWS LAN during LOGONprocessing:NICDEF 500 TYPE QDIO DEV 8 LAN SYSTEM INEWS2. Define a simulated HiperSockets adapter using I/O devices FD20–FD2F (16devices) which will be coupled to the user’s own HSTEST LAN during LOGONprocessing:NICDEF FD20 TYPE HIPERSNICDEF FD20 DEVICES 16 LAN * HSTESTNote that this adapter cannot couple to the designated LAN during LOGONunless it has been defined earlier. This can be accomplished by adding thenecessary DEFINE LAN statement to the SYSTEM CONFIG file.Chapter 17. Creating and Updating a User Directory 531

NOPDATANOPDATA Directory Control Statement (General)►► NOPDATA ►◄PurposeThe NOPDATA statement authorizes a virtual machine to use NOP CCWs totransfer data to CP spool files. (Such data is not printed or punched with the file,and is not visible if the file is later read through a virtual card reader. It can only beaccessed using DIAGNOSE code X'14'.)How to SpecifyIf you specify the NOPDATA statement, it must precede any device statements youspecify in a user’s directory entry. (For a list of device statements, see Table 20 onpage 448.)Multiple NOPDATA statements are allowed within a profile entry.When processing the NOPDATA statement, DIRECTXA does not check for extratokens. If you specify anything after the NOPDATA keyword, DIRECTXA ignores theextra tokens and system processing continues as if you had not specified the extratokens.UsageNotes1. The NOPDATA statement should appear in the directory entry of the RSCSvirtual machine. For more information, see the RSCS Planning and Installationbook, SH24-5219.2. Do not use data chaining with NOP CCWs.ExamplesTo authorize a virtual machine to transfer data to CP spool files using NOP CCWs,use the following NOPDATA statement in the virtual machine’s directory entry:NoPData532 z/VM: CP Planning and Administration

OPTIONOPTION Directory Control Statement (General)►►OptionAcct APPLmon CFVMCFUSERCOMSRV CONceal Cpuid bbbbbb►►DEVInfo DEVMaint DIAG88 DIAG98 D84NOPAS IGNMAXU Lang langid►►LKFAC LNKExclu LNKNOPAS LNKStabl MAINTCCWMaxconn 64Maxconnmaxno►►►MAXVMCFI 2147483647MAXVMCFI maxno MIH NETAccounting NETRouter NOMDCFS QUICKDspRMCHINFO SETORIG STGEXempt SVC76VM SVMstat TODENable►►◄PurposeThe OPTION statement specifies special characteristics available to the virtualmachine.How to SpecifyIf you specify the OPTION statement, it must precede any device statements youspecify in a user’s directory entry. (For a list of device statements, see Table 20 onpage 448.)Any number of OPTION statements are allowed within a profile, and are added toany OPTION statements in the user directory entry.OperandsAcctspecifies that the virtual machine can issue a DIAGNOSE code X'4C' togenerate accounting records. For more information about DIAGNOSE codeX'4C', see the z/VM: CP Programming Services book.APPLmonauthorizes the virtual machine to issue DIAGNOSE code X'DC' by which anapplication may declare or delete a buffer for CP monitoring. After the bufferhas been declared for monitoring, all data in it is collected by CP into monitorrecords at each sample interval. For more information about DIAGNOSE codeX'DC', see the z/VM: CP Programming Services book.CFVMdefines the user as a virtual machine that will only run as a Coupling FacilityService Machine (CFVM). A CF Service Machine is a special disconnectedvirtual machine that is set up to IPL the Coupling Facility Control Code (CFCC).CFVM may not be specified with CFUSER or RMCHINFO.Chapter 17. Creating and Updating a User Directory 533

OPTIONCFUSERindicates that the user is allowed to define and couple Message Devices to aCoupling Facility Service Machine. CFUSER may not be specified with CFVM.COMSRVauthorizes the indicated virtual machine to act as a communication server, to:v Route communications on behalf of other virtual machines to other serversv Establish connections to other servers while handling requests for otherusers.With this option, the TSAF virtual machine or any other communications servercan put the user ID of the virtual machine that issued the APPC/VM CONNECTin the CONNECT parameter list.When TSAF sends the connect request to the target virtual machine, therequest contains this information about the originating virtual machine. Withoutthis operand, CP would send the connect request with the communicationsserver’s user ID.CONcealspecifies that the user’s virtual machine is to be placed in the protectedapplication environment when the user logs on. The environment remains activeuntil the user logs off or until it is made inactive by a CP SET CONCEAL OFFor a CP DEFINE CPU command. This environment is intended for theapplication end user who does not want to interact with CP. Instead ofpresenting the user with an unexpected CP READ on occurrence of certainerror conditions (for example, paging error, soft abend, disabled wait PSWloaded), the protected application facility forces an automatic re-IPL of thevirtual machine. The re-IPL is initiated by using the IPL statement last used forthe virtual machine.To prevent a re-IPL loop, CP does not force a re-IPL if a previous automaticre-IPL has occurred less than a minute before. Not more than 10 automaticre-IPLs are tried between activation and deactivation of the protectedapplication environment. If a re-IPL is not done, CP issues the samemessage(s) as when the protected application environment is not active andthen puts the terminal into CP READ state.A user whose directory entry specifies OPTION CONCEAL has the break key(for 3270 terminals) disabled at logon. If the user subsequently deactivates theprotected application environment using the CP SET CONCEAL OFF command,the break key is enabled again.Cpuid bbbbbbspecifies a processor identification number to be stored as part of theinformation stored by the STIDP instruction. This operand sets the CPU ID forall of the processors in a virtual MP configuration. This operand is overridden ifa CPU ID is specified on the CPU statement for this virtual CPU.DEVInfoauthorizes the specified virtual machine to use DIAGNOSE code X'E4' withsubcodes X'00' and X'01' to access the relocation and real device information ofthe specified DASD owned by this or another user ID. For more informationabout DIAGNOSE code X'E4', see the z/VM: CP Programming Services book.DEVMaintauthorizes the specified virtual machine to use DIAGNOSE code X'E4' withsubcode X'02' and X'03' to get a full-pack overlay read/write minidisk of thevolume on which the specified minidisk or cylinder/block resides. A user withthis option is also authorized to execute any function protected by the DEVINFO534 z/VM: CP Planning and Administration

OPTIONand MAINTCCW options. For more information about DIAGNOSE code X'E4',see the z/VM: CP Programming Services book.DIAG88specifies that the virtual machine is authorized to use DIAGNOSE code X'88' tovalidate user authorizations and link minidisks. A user whose directory entrycontains this operand can run programs that access other users’ minidiskswithout requiring passwords. For information about DIAGNOSE code X'88', seethe z/VM: CP Programming Services book.DIAG98specifies that the virtual machine is authorized to use the DIAGNOSE codeX'98' real I/O facility. A user whose directory entry contains this operand can runprograms that use the page locking and start real I/O subfunctions to enhanceI/O performance to dedicated devices. For information about DIAGNOSE codeX'98', see the z/VM: CP Programming Services book.D84NOPASspecifies that this virtual machine has the ability to issue all subfunctions ofDIAGNOSE code X'84' (except LOGPASS and MDISK) without the logonpassword of the target virtual machine ID. This option only takes effect if thereis no access control mechanism, such as RACF, in place. For more informationabout DIAGNOSE code X'84', see the z/VM: CP Programming Services book.IGNMAXUindicates that this virtual machine can log on to the system even if the numberof users already logged-on is equal to or greater than the maximum allowed.You set this maximum in one of three ways:1. Using the FEATURES statement with the MAXUSERS operand in yoursystem configuration file. For more information, see page 136.2. Using the CP SET MAXUSERS command. For more information, see thez/VM: CP Commands and Utilities Reference.3. Using the SYSMAXU macroinstruction in HCPSYS. For more information,see page 686.Lang langidspecifies the 1- to 5-character name of the language that should be set for thevirtual machine during logon.LKFACindicates that the specified virtual machine is authorized to use:v Multi-Path Lock Facility RPQ (MPLF) simulation support. MPLF is a lockfacility simulated for TPF guests.v Real Multi-Path Lock Facility (MPLF) support. MPLF is a lock facility availableon the D/T3990 model 6 control unit.This support allows multiple TPF guests, running in a loosely coupledconfiguration, to share a common database through simulation or real MPLFlocking channel commands used by the TPF system.LNKExcluspecifies that the virtual machine is authorized to use the stable and exclusiveaccess modes, ER (exclusive read) or EW (exclusive write) of the CP LINKcommand, the CMS VMLINK command, and DIAGNOSE code X'E4'. This is aglobal authority allowing the virtual machine to perform stable or exclusive linksto any minidisk to which it has password level authorization. Forminidisk-specific authorization of stable and exclusive access modes, see “LINKDirectory Control Statement (Device)” on page 500 and “MDISK DirectoryControl Statement (Device)” on page 513. The exclusive access modes negateChapter 17. Creating and Updating a User Directory 535

OPTIONthe ability of other users to acquire any access to the minidisk. This ensuresthat the issuing user is the only one with access to the minidisk.LNKNOPASspecifies that this virtual machine can link to any other virtual machine’s DASDwithout password authorization. When LNKNOPAS is specified, passwordauthorization may still be required when an external security manager (ESM) isinstalled. For more information, refer to the documentation provided by yourESM.LNKStablspecifies that the virtual machine is authorized to use the stable access modes,SR (stable read-only), and SW and SM (stable write), of the CP LINKcommand, the CMS VMLINK command, and DIAGNOSE code X'E4'. This is aglobal authority allowing the virtual machine to perform a stable link to anyminidisk to which it has password-level authorization. For minidisk-specificauthorization of stable access modes, see “LINK Directory Control Statement(Device)” on page 500 and “MDISK Directory Control Statement (Device)” onpage 513. These modes negate the ability of other users to acquire writeaccess the specified minidisk. This ensures that the data can not be changedunderneath the user.MAINTCCWauthorizes the specified virtual machine to use diagnostic CCWs, including:v Diagnostic Write Home Addressv Diagnostic Read Home Addressv Write Record Zerov Write Home Addressv Diagnostic Loadv Diagnostic Writev Diagnostic Sense/Readv Diagnostic Control.Maxconn maxnospecifies the maximum number of IUCV and APPC/VM connections allowed forthis virtual machine. If the MAXCONN operand is omitted, the default is 64. Themaximum is 65,535. The MAXCONN value has implications for users of filepool servers. See the z/VM: CMS File Pool Planning, Administration, andOperation for more information.MAXVMCFI maxnospecifies the maximum number of VMCF inbound send messages, includingthose initiated by SMSG, plus IDENTIFY final response interrupts that may bequeued for processing on this virtual machine. The variable maxno is a decimalnumber from 1 to 2147483647. If the MAXVMCFI operand is omitted, thedefault is 2147483647.MIHspecifies that CP simulate an interrupt for the virtual machine whenever itdetects a missing interrupt condition for an I/O operation it does on behalf of thevirtual machine.NETAccountingspecifies that Network Data Transmission account records (type 0C) should begenerated for this user. For more information on Network Data Transmissionaccount records, see “Accounting Records Network Data Transmissions(Record Type C)” on page 307.536 z/VM: CP Planning and Administration

OPTIONUsageNotesNETRouterspecifies that this user is a network router, and Network Data Transmissionaccount records (type 0C) should be generated for this user. Transmissions toand from a user designated as a router (over a VM LAN), will be reported inaccount records separate from transmissions with non-routers. For moreinformation on Network Data Transmission account records, see “AccountingRecords Network Data Transmissions (Record Type C)” on page 307.NOMDCFSspecifies that the virtual machine can use minidisk cache at a rate that is notlimited by the fair share limit. This allows virtual machines that have a very highI/O rate (such as the shared file system) to get the full benefit of minidiskcache.QUICKDspcauses a virtual machine to be added to the dispatch list immediately when ithas work to do, without waiting in the eligible list.RMCHINFOindicates that the specified virtual machine is authorized to access real-machineconfiguration information, without regard to the virtual machine's configuration. Itshould be used when OSA/SF (or any other application that may require realmachine configuration information) is running under CMS. RMCHINFO shouldnot be specified for guest operating systems.SETORIGspecifies that the virtual machine can issue DIAGNOSE code X'F8' subfunctioncode X'00' to associate originating node and user ID information with a virtualoutput device. For more information about DIAGNOSE code X'F8', see thez/VM: CP Programming Services book.STGEXemptspecifies that the virtual machine is exempt from CP free storage limit detection.This ensures that the machine will not be suspended or forced off if it causesCP to consume too much free storage on its behalf. This option isrecommended for non-general purpose virtual machines.SVC76VMspecifies that errors are not recorded by CP. All guest SVC 76 operations areprocessed by the virtual machine that issued the SVC 76.SVMstatspecifies that the virtual machine is a service virtual machine. The monitor datarecords associated with this virtual machine include the SVMSTAT setting. Theonly purpose is to allow products that process monitor data to report on servicevirtual machines separate from end-user virtual machines. No other operations,such as transaction or wait state classification, are affected by this operand.TODENablespecifies that the user may change the virtual machine’s Time-of-Day (TOD)clock with the SCK instruction or the SET VTOD CP command.1. To run the device support facilities (ICKDSF) program in a virtual machine, youmust specify the MAINTCCW operand.2. The CPU statement overrides the specification on the OPTION statement.3. The LKFAC option must be specified to authorize the user to use the SETLKFAC CP command to join a lock facility I/O configuration.Chapter 17. Creating and Updating a User Directory 537

OPTION4. You may not specify OPTION CONCEAL if the directory entry for this userdefines a multiprocessor configuration. The protected application facilitysupports only virtual uniprocessor systems.5. Use of the IPL statement is recommended for users of the protectedapplication facility. If the IPL statement is used with the OPTION CONCEALstatement and an appropriate SYSPROF EXEC, the user can be put directlyinto an application environment during logon and thus be protected fromfurther CP interaction.6. Though the break key is initially disabled at logon when the OPTIONCONCEAL statement is used, its setting may be enabled by using theTERMINAL BRKKEY command.7. When a user’s break key is disabled, the user whose virtual machine isrunning a full-screen application cannot enter CP commands or place thevirtual machine into CP READ unless the application provides a way. Theapplication can use DIAGNOSE code X'08' to pass CP commands or to passno command at all to enter into CP READ.8. The TERMINAL MODE CP command allows entry to CP on a consoleattention interrupt for users running in line mode. In addition, #CP may beused in this mode to enter CP commands and to enter into CP READ.9. The installation default language is set for the virtual machine if:v The LANG option is not specifiedv A valid CP message repository for the language specified by langid cannotbe accessed.10. STGEXempt ensures that the user ID is not subject to being suspended orforced due to the amount of CP free storage it causes CP to consume. Thisoption is recommended for:v Special purpose user IDs vital to the installationv User IDs running trusted codev User IDs which should never be forced off.ExamplesThe following examples show various ways of specifying the OPTION statement.Note that you can specify more than one operand on a single OPTION statement.1. To specify that:v The virtual machine can issue DIAGNOSE code X'4C'v 012345 is the virtual machine’s processor identification numberv CP is to inform the virtual machine of missing interrupts it detectsv The virtual machine is authorized to create up to 100 IUCV pathsuse the following OPTION statement in the virtual machine’s directory entry:Option Acct CpuID 012345 Mih MaxConn 1002. To specify that:v The virtual machine can issue DIAGNOSE codes X'4C' and X'98'v 012345 is the virtual machine’s processor identification numberv CP is to inform the virtual machine of missing interrupts it detectsv The virtual machine is authorized to create up to 100 IUCV pathsuse the following OPTION statement in the virtual machine’s directory entry:Option Acct CpuID 012345 Mih MaxConn 100 Diag983. To place a virtual machine in the protected application environment when theuser logs on, use the following OPTION statement in the user’s directory entry:538 z/VM: CP Planning and Administration

OPTIONOption Conceal4. To indicate that the virtual machine is to be added to the dispatch list withoutwaiting in the eligible list, use:Option QuickDsp5. To indicate that the virtual machine can issue DIAGNOSE code X'F8',subfunction code X'00', use:Option SetOrig6. To indicate that the virtual machine can issue DIAGNOSE code X'DC', use:Option ApplMon7. To give the virtual machine the authority to enter a CP LINK userid 291 392 SRcommand, use:Option LnkStabl8. To allow a virtual machine to operate as a communications server, use:Option ComSrv9. To give the virtual machine the authority to enter a CP SET LKFAC command,use:Option LKFACChapter 17. Creating and Updating a User Directory 539

POOLPOOL Directory Control Statement (General)►► POOL LOW lowbound HIGH highbound PROFile name ►◄PurposeThe POOL statement allows a set of virtual machines to be defined with the sameconfiguration or characteristics.How to SpecifyIf you specify the POOL statement, it must be the only control statement other thana USER statement that you code in a user’s directory entry. POOL statements arenot allowed within a profile entry.OperandsLOW lowboundspecifies the suffix number for the user ID of the first virtual machine in thepool. The variable lowbound must be a decimal number from 0 to 99999.HIGH highboundspecifies the suffix number for the user ID of the last virtual machine in thepool. The variable highbound must be a decimal number from lowbound to99999.PROFile namespecifies the name of the profile to be used for the definition of each virtualmachine in the pool.UsageNotes1. The directory statement before a POOL statement must be a USER statement.2. The user ID specified on the preceding USER statement must be from 1 to 3characters in length.3. A directory entry that contains a POOL statement must comprise only a USERstatement and a POOL statement. Any other directory statements specified areinvalid.ExamplesA group of 25 virtual machines with identical configurations could be defined by thefollowing directory entry:User GRP AutoOnly 4m 32mPool Low 1 High 25 Profile groupdefThis will generate directory entries for virtual machines GRP00001 throughGRP00025.Each machine would have a password of AUTOONLY, thus restricting it fromterminal logon. Each virtual machine would have 4 MB of virtual storage, which maybe reset up to a maximum of 32 MB. Also, each virtual machine would have aprivilege class of G. The rest of the configuration for each machine would be asdefined in the directory profile named GROUPDEF.540 z/VM: CP Planning and Administration

POSIXGLISTPOSIXGLIST Directory Control Statement (General)►► POSIXGLIST GIDS ▼gid►◄GNAMES▼gnameGNAMES▼gnamePurposeThe POSIXGLIST statement lists POSIX groups of which the user is a member.Each group on the list can be specified by either group ID (gid) or group name(gname). POSIXGLIST statements are the primary source for the GIDs that formthe user’s supplementary group list.How to SpecifyIf you specify the POSIXGLIST statement, it must precede any device statementsyou specify in a profile or user entry. (For a list of device statements, see Table 20on page 448.)Multiple POSIXGLIST statements are allowed within a user or profile entry. ThePOSIXGLIST information from a user entry completely replaces that from anincluded PROFILE.The POSIXGLIST statement may be continued across multiple records in thesource directory file. For detailed information about continued statement rules, see“Continued Directory Control Statements” on page 452. Note that some operandson this statement are case sensitive, so care should be taken to preserve the caseof them when editing the user directory file.OperandsGIDS gideach gid must identify a group defined on a POSIXGROUP statement or thedefault group implicitly defined by DIRECTXA.GNAMES gnamespecifies, by group name, POSIX groups of which the user is a member. Eachgname must identify a group defined on a POSIXGROUP statement or thedefault group implicitly defined by DIRECTXA. The case of each group name ispreserved; it is not converted to upper case by DIRECTXA. Each name mustmatch exactly the group name on a POSIXGROUP statement or the defaultgroup name.UsageNotes1. If your installation has installed an External Security Manager (ESM), theinformation specified on this directory control statement may be overridden byinformation provided by the ESM. Consult your ESM documentation for moreinformation.Chapter 17. Creating and Updating a User Directory 541

POSIXGLIST2. A group’s gid or gname may only be specified one time by GID or GNAME onthe POSIXGLIST statements in a user entry or a profile; that is, duplicate gidsor gnames are not permitted.3. DIRECTXA does not check for duplicate groups across the GIDS-GNAMESlists.4. The user’s primary group defined by a POSIXINFO statement may be listed ona POSIXGLIST statement, but it is not required to be listed. A user isautomatically considered a member of his/her primary group.5. If there is more than one group defined with the same GID, and the user is amember of any of these groups, then it is recommended that group names beused to list these groups on POSIXGLIST in order to avoid an ambiguousspecification.6. The user’s supplementary GID list consists of up to 32 unique GIDs. Theprimary GID (from the POSIXINFO statement) is always included in the initiallist. The remainder are taken from the POSIXGLIST statement(s) in the order inwhich they were specified.Examples1. To define user ID rick to be a member of POSIX groups VMCMS, VMCFT andVMCP, code following POSIXGLIST statement:GlobaldefsPosixGroup VMCFT 100PosixGroup VMCMS 200PosixGroup VMCP 300:User rick ...PosixGList gids 200 gnames VMCFT VMCP542 z/VM: CP Planning and Administration

POSIXGROUPPOSIXGROUP Directory Control Statement (Control)►► POSIXGROUP gname gid ►◄PurposeThe POSIXGROUP statement defines the group name and group ID (GID) for aPOSIX group.How to SpecifyWhen a POSIXGROUP statement is specified, it must be within the global definitionsection of the source directory (after the GLOBALDEFS directory control statementand before any USER or PROFILE definitions). There are no restrictions on thenumber of POSIXGROUP statements that may be specified. Note that someoperands on this statement are case sensitive, so care should be taken to preservethe case of them when editing the user directory file.Operandsgnamespecifies a unique 1- to 8-character mixed-case POSIX group name. The singleor double quotation mark is invalid in this operand. The case of this operand ispreserved; it is not converted to upper case by DIRECTXA. Any group namespecified on other directory control statements that refer to this group mustmatch this group’s name exactly.gidThe group name DEFAULT identifies the default group and is reserved byDIRECTXA; it may not be specified on a POSIXGROUP statement. DIRECTXAimplicitly defines a default group with a name of DEFAULT and a GID of4294967295 (X'FFFFFFFF'). This name or GID may be specified onPOSIXINFO and POSIXGLIST statements to identify the default group.specifies the POSIX group ID (GID) associated with gname. The gid is anumeric value from 0 to 4294967295 (X'FFFFFFFF').UsageNotes1. If your installation has installed an External Security Manager (ESM), theinformation specified on this directory control statement may be overridden byinformation provided by the ESM. Consult your ESM documentation for moreinformation.2. Duplicate group names are not permitted, but multiple groups may have thesame GID. If you define multiple groups with the same GID, do so with caution,because GIDs are used for various authority checks. Also, certain queries thatrequire a GID as input may return information about a group other than theintended one.3. It is permitted to define a group with no members. That is, a POSIXGROUPstatement may define a group that no users identify as one of which they are amember.Chapter 17. Creating and Updating a User Directory 543

POSIXGROUPExamples1. To define a POSIX group named VMcp and with a GID of 200, code thefollowing POSIXGROUP statement:GlobaldefsPosixGroup VMcp 200544 z/VM: CP Planning and Administration

POSIXINFOPOSIXINFO Directory Control Statement (General)►►POSIXINFO(1)UID uid GID gidGNAME gnameIWDIR string IUPGM string►►FSROOTstring►◄Notes:1 You must specify at least one of the following operands. If you want to specify more than oneoperand, you can specify them in any order.PurposeThe POSIXINFO statement specifies a user ID’s POSIX information. It containsPOSIX user database information such as POSIX user ID (UID), POSIX group ID(GID) or group name, initial working directory, initial user program and file systemroot.How to SpecifyIf you specify the POSIXINFO statement, it must precede any device statementsyou specify in a profile or user entry. (For a list of device statements, see Table 20on page 448.)Multiple POSIXINFO statements are allowed within a user or profile entry. Eachoperand may only be specified once within a user or profile entry. POSIXINFOvalues within a user entry override those in a profile entry.The POSIXINFO statement may be continued across multiple records in the sourcedirectory file. For detailed information about continued statement rules, see“Continued Directory Control Statements” on page 452. Note that some operandson this statement are case sensitive, so care should be taken to preserve the caseof them when editing the user directory file.OperandsUID uidspecifies the POSIX user ID (UID) assigned to this user. This will be the user’sreal UID, effective UID and saved set-UID when the user logs on. Care shouldbe taken in assigning zero as the UID, because UID zero is considered todenote appropriate privileges. A user with appropriate privileges can performmany authorized POSIX functions and will pass many security checks. The uidis a numeric value between 0 and ’4294967295 (X'FFFFFFFF'). A default valueof 4294967295 (X'FFFFFFFF') is assigned if there is no UID specification for auser.GID gidGNAME gnamespecifies the user’s primary group. The gid is a numeric value between 0 and4294967295 (X'FFFFFFFF'). The gname is a 1- to 8-character mixed-caseChapter 17. Creating and Updating a User Directory 545

POSIXINFOUsageNotesPOSIX group name. The single or double quotation mark is invalid in thegname. The case of the group name is preserved; it is not converted to uppercase by DIRECTXA. It must match exactly the group name on a POSIXGROUPstatement or the default group name implicitly defined by DIRECTXA. The gidor gname must identify a group defined on a POSIXGROUP directory controlstatement or the default group name implicitly defined by DIRECTXA. The GIDfor this group will be the user’s real GID, effective GID and saved-set GID whenthe user logs on.You may specify the group by either GID or GNAME, but not both. If GNAME isspecified, the user’s primary GID is obtained from the POSIXGROUP statementdefining the group with name gname. If GID is specified, the user’s primarygroup name is obtained from a POSIXGROUP statement defining a group withGID gid. If there is more than one group with this GID, then one of them ischosen as the user’s primary group; it is unpredictable which one is chosen.If there is no GID or GNAME specification for a user, the user’s primary groupis the default group, named DEFAULT with GID 4294967295 (X'FFFFFFFF').IWDIR stringspecifies the user’s initial working directory. Its rules for specification aredescribed below.IUPGM stringspecifies the user’s initial user program. Its rules for specification are describedbelow.FSROOT stringspecifies the user’s file system root. Its rules for specification are describedbelow.The string specifying an IWDIR, IUPGM or FSROOT results in a mixed-case 1- to1023-character string which may contain blanks, single quotation marks, doublequotation marks and other special characters. The string begins with the firstnon-blank character following its keyword and may be continued on multipledirectory records. If you do not want imbedded blanks or quotation marks in theresult, and string fits on a single directory record, you may specify string as a singleblank-delimited token. Otherwise, it must be specified as a quoted string operand.See “Quoted String Operands” on page 452 for detailed information on how tospecify these operands.1. If your installation has installed an External Security Manager (ESM), theinformation specified on this directory control statement may be overridden byinformation provided by the ESM. Consult your ESM documentation for moreinformation.2. UIDs are not required to be unique. The same value can be assigned tomultiple users, but this is not recommended. If you define multiple users withthe same UID, do so with caution, because UIDs are used for various authoritychecks and individual user control and accountability will be lost.3. POSIXINFO statements are permitted in profile entries, but specifying the UID ina profile entry is not recommended, because it is likely to result in many userswith the same UID. Since UIDs are used to identify individuals for the purposesof authorization and permission checking, extreme care should be used whenassigning UIDs via a profile entry. Similar consideration should be given toassigning GID/GNAME with a profile entry.546 z/VM: CP Planning and Administration

POSIXINFO4. POSIX user names, sometimes referred to as login names, are defined to bethe lower case version of the user’s VM user ID.Examples1. To define a userid CLYDE with 100 as UID, 200 as primary GID, /home/clyde asinitial working directory, pxshell as initial user program, and/../VMBFS:VMSYS:ROOT/ as the file system root, code the following directorystatements:GlobaldefsPosixGroup VMcp 200:User clyde ...PosixInfo uid 100 gid 200 iwdir /home/clyde ,iupgm pxshellPosixInfo fsroot /../VMBFS:VMSYS:ROOT/2. Assume you have several virtual machines, among them are SUE and DAMIAN,that have the same initial user program pxshell, and /../VMBFS:VMSYS:ROOT/as the file system root. SUE’s UID is 200, primary group has an ID of 101, andinitial working directory /home/sue. DAMIAN’s UID is 100, primary group isnamed VMcp, and initial working directory /home/damian. Code the followingdirectory statements:GlobaldefsPosixGroup VMcms 100PosixGroup VMcp 200:Profile posixdefPosixInfo iwdir /home iupgm pxshell fsroot /../VMBFS:VMSYS:ROOT/:User sue ...Include posixdefPosixInfo uid 200 gid 100 iwdir /home/sue:User damian ...Include posixdefPosixInfo uid 101 gname VMcp iwdir /home/damianChapter 17. Creating and Updating a User Directory 547

POSIXOPTPOSIXOPT Directory Control Statement (General)►►POSIXOPT(1)SETIDSSETIDSDISALLOWALLOWQUERYDBQUERYDBSYSDEFAULTDISALLOWALLOWEXEC_SETIDSEXEC_SETIDSSYSDEFAULTDISALLOWALLOW►◄Notes:1 You must specify at least one of the following operands. If you want to specify more than oneoperand, you can specify them in any order.PurposeThe POSIXOPT statement specifies option settings related to a user ID’s POSIXcapabilities. It includes authorization to query and set POSIX process and databaseinformation.How to SpecifyIf you specify the POSIXOPT statement, it must precede any device statements youspecify in a profile or user entry. (For a list of device statements, see Table 20 onpage 448.)Multiple POSIXOPT statements are allowed within a user or profile entry. Eachoperand may only be specified once within a user or profile entry. POSIXOPTvalues within a user entry override those in a profile entry.The POSIXOPT statement may be continued across multiple records in the sourcedirectory file. For detailed information about continued statement rules, see“Continued Directory Control Statements” on page 452.OperandsSETIDSspecifies whether the user is authorized to set other users’ POSIX UIDs orGIDs.DISALLOW(the default) specifies the user is not allowed to set other users’ POSIXsecurity values.ALLOWspecifies the user is allowed to set other users’ POSIX security values onbehalf of CP exec() processing. The users whose IDs are to be set musthave POSIXOPT EXEC_SETIDS ALLOW specified in their user entry. Youshould generally specify this option (SETIDS ALLOW) only for POSIX bytefile system (BFS) servers.QUERYDBspecifies whether the user is authorized to query other users’ POSIX databaseinformation.SYSDEFAULT(the default) specifies the system default authorization for querying POSIXdatabase information.548 z/VM: CP Planning and Administration

POSIXOPTUsageNotesThe system default authorization (SYSDEFAULT) is set up by theUSER_DEFAULTS system configuration file statement. See“USER_DEFAULTS System Configuration File Statement” on page 248 fordetails. If the QUERYDB option is specified, it will override the systemdefault. If it is not specified, then the system default applies.DISALLOWspecifies the user is not allowed to query other users’ POSIX databaseinformation.ALLOWspecifies the user is allowed to query other users’ POSIX databaseinformation.EXEC_SETIDSspecifies whether the user is authorized to have his POSIX security valueschanged on behalf of a POSIX exec() function call designating a file with thesetuid or setgid attributes. The byte file system server must have POSIXOPTSETIDS ALLOW specified in its user entry.SYSDEFAULT(the default) specifies the system default for having a user’s POSIX securityvalues changed by other users.The system default authorization (SYSDEFAULT) is set up by theUSER_DEFAULTS system configuration file statement. See“USER_DEFAULTS System Configuration File Statement” on page 248 fordetails. If the EXEC_SETIDS option is specified in the directory, it willoverride the system default. If it is not specified, then the system defaultapplies.DISALLOWspecifies the user is prohibited from having his POSIX security valueschanged on behalf of CP exec() processing.ALLOWspecifies the user is permitted to have his POSIX security values changedon behalf of CP exec() processing.1. If your installation has installed an External Security Manager (ESM), theinformation specified on this directory control statement may be overridden byinformation provided by the ESM. Consult your ESM documentation for moreinformation.2. If a user has EXEC_SETIDS DISALLOW specified, then any requests to changethis user’s POSIX security values on behalf of CP exec() processing will berejected even if the requestor is authorized to change POSIX security values.ExamplesThe following examples show various ways of specifying the POSIXOPT statement.Note that you can specify more than one operand on a single POSIXOPTstatement.1. To specify that:v A user can set any other users’ POSIX security valuesv The user can query any other users’ database informationv The user prohibits having his POSIX security values changed by other userson behalf of CP exec() processing.Chapter 17. Creating and Updating a User Directory 549

POSIXOPTuse the following POSIXOPT statement in the user’s directory entry:PosixOpt SetIds allow QueryDb allow Exec_Setids disallow2. To specify that:v The user cannot set other users’ POSIX security valuesv The user can not query other users’ database informationv The user takes the system default for the Exec_Setids optionuse the following POSIXOPT statement in the user’s directory entry:PosixOpt QueryDb disallow550 z/VM: CP Planning and Administration

PROFILEPROFILE Directory Control Statement (Control)►► Profile name ►◄PurposeA PROFILE statement defines the start of a profile entry in the source directory.How to SpecifyWhen PROFILE is specified, all profile entry definitions must follow the lastDIRECTORY statement and the global definition section and precede the firstUSER statement. There are no restrictions on the number of profile entries that maybe specified.PROFILE statements are not allowed within a profile entry.Directory profiles are implemented by defining a profile entry in the source directoryand specifying an INCLUDE statement in the user entries that refer to the profile.(For more information on the INCLUDE statement, see page 487).Operandsnamespecifies the name assigned to the profile entry and is used to reference theprofile. The variable name is an alphanumeric string of up to 8 characters. Avalid character is any character that can be used in a user ID name. Only oneprofile name may be specified on a PROFILE statement.UsageNotesProfile entries represent defaults to be set if not specified in the including userdefinition.Basically, when these directory control statements are used in a profile definition,they perform the same function as they do when used in a user definition. However,they may operate slightly differently when used in both the profile and userdefinitions.1. The following control statement types, when placed in the user definition,completely supersede their profile counterparts:ACCOUNTACIGROUPAUTOLOGCLASSCONSOLED8ONECMDIPLMACHINEPOSIXGLISTSHARESPOOLFILESTDEVOPTXAUTOLOGXSTORE2. Area operands of the SCREEN statements in the user definition supersede theirprofile counterparts. This relationship also holds true when the user definitionredefines a superset or subset of those areas defined by the profile.Chapter 17. Creating and Updating a User Directory 551

PROFILE3. STDEVOPT, POSIXINFO, and POSIXOPT statement operands explicitly codedin a user entry supersede their profile counterparts. However, these statements’operands explicitly coded in a profile supersede uncoded defaults in a userentry.4. When CPU statements are placed in the user definition, they supersede theirprofile counterparts where the CPU number is the same; where the CPUnumbers are different, however, the definitions are simply appended. The orderof concatenation is user entries followed by profile entries.5. The XCONFIG statement, when placed in the user definition, supersedes itsprofile counterpart where the first (major) operand is the same; where the firstoperands are different, the definitions are combined.6. When the following control statement types are used in a profile definition, theyare processed exactly as if they were multiple occurrences of the statementtypes within the including user definition. (See Usage Note 4.)APPCPASS IUCV NAMESAVE NOPDATA OPTION7. When the following control statement types are used in a profile definition, theyare processed as normal except that duplicate definition of an address in theprofile definition causes a duplication error. However, duplication of an addressused in the including user definition simply creates another device definition tobe resolved at logon time. That is, at logon, the including user’s device definitionfor the duplicated address will be processed first; if this definition fails, theprofile device definition for the duplicated address will be attempted.CONSOLE DASDOPT DEDICATE LINK SPECIALSPOOL8. The following control statements are not allowed in a profile definition:DIRECTORY GLOBALDEFS GLOBALOPTS INCLUDE LOADMDISK MINIOPT POOL POSIXGROUP PROFILEUSER9. A profile entry begins with a PROFILE statement and ends with the nextPROFILE statement or the first USER statement.ExamplesFor this example, assume you have several virtual machines that are CMS usersand that are also in a ACIGROUP called GROUP1. JOHN1 is a user in this group.Follow the directory statement by the following profile:Directory vdev devtype volidProfile grp1userAciGroup group1Ipl cms: ← other control statements common to this groupUser john1 ... ← USER statement operands for this userInclude grp1user: ← control statements unique to this userLink jack 495 495 rr ← for example, a link that this user needs: but other users in this group do not needUser ...:552 z/VM: CP Planning and Administration

SCREENSCREEN Directory Control Statement (General)►► SCReen area ▼ (1) DEFault NONEcolor hilight►◄Notes:1 You must specify at least one of the operands. If you want to specify more than one, you canspecify them in any order.PurposeSCREEN statements in a virtual machine’s directory entry define the extended colorand extended highlighting options for the virtual machine console.How to SpecifyYou may include as many SCREEN statements as you need to define any areas ofthe screen you want, but the SCREEN statements must be contiguous. If used,SCREEN statements must follow the USER statement and precede the first devicestatement. (For a list of device statements, see Table 20 on page 448.)Any number of SCREEN statements are allowed within a profile, and are added toany SCREEN statements in the user directory entry. Duplicate area specificationswithin a profile are not allowed. The user entry overrides a profile entry for anyuser-to-profile duplicate are a specification. This relationship also holds true whenthe user definition redefines a superset or subset of those areas defined by theincluded profile.Operandsareais the area of the screen. Area can be:ALL designating the entire screen. If this area is specified, none of the followingareas can be used.INArea the input areaSTAtarea the system status areaOUTarea the output areas. If this area is specified, none of the following areas canbe used.CPOut the output from CPVMOut the output from CMS or the virtual machine operating system running in theuser’s virtual machineINRedisp the input redisplaycoloris the color attribute to be assigned to an area of the screen. Color can be:BLUe GREen PINk REDTURquois WHIte YELlow DEFault (green and white)hilightis the extended highlight value to be assigned to an area of a screen. TheChapter 17. Creating and Updating a User Directory 553

SCREENhilight value can be:BLInkblinkingNONe (the default) no extended highlightingREVvideo reverse videoUNDerlin underliningUsageNotes1. A default value of NONE is applied for any unspecified extended highlightattribute. DEFAULT is used for any unspecified extended color attribute. TheDEFAULT color is monochrome (green and white).2. If the ALL operand is used, it must be the only operand specified on the onlySCREEN statement for the user.3. If the OUTAREA operand is used, CPOUT, VMOUT, or INREDISP cannot bespecified. If CPOUT, VMOUT, or INREDISP is specified, the OUTAREA operandcannot be specified.4. No SCREEN statement operands can appear more than once in a user’sdirectory entry.ExamplesTo define the screen output area of a user’s virtual console as red and blinking, andthe input area yellow and reverse video, use the following SCREEN statement inthe virtual machine’s directory entry:SCReen OutArea red blink InArea RevVideo yellow554 z/VM: CP Planning and Administration

SHARESHARE Directory Control Statement (General)►► SHARE ABSolute y%RELative zNOLimitLIMITSoftLIMITHardLIMITSoftABSolute a%RELative b LIMITHard►◄PurposeThe SHARE statement specifies a virtual machine’s share of CPU power.How to SpecifyIf you specify the SHARE statement, it must precede any device statements youspecify in a user’s directory entry. (For a list of device statements, see Table 20 onpage 448.)You can specify only one value (ABSOLUTE or RELATIVE) per statement. MultipleSHARE statements for a user entry are allowed but not recommended. If multipleSHARE statements are found in a user entry, only the last one is used.Multiple SHARE statements are allowed within a profile, but are only used if noSHARE statements are in the user directory entry. If multiple SHARE statementsare in an included profile, only the last one is used.If you specify more than five tokens, DIRECTXA ignores the extra tokens andsystem processing continues as if you had not specified the extra tokens.OperandsABSolute y%specifies absolute share of the all active processors in a system. The variable yis a decimal real number—no or one decimal place—from 0.1 to 100 (forexample, 20.5%, or 80%).RELative zspecifies a relative share of the system. The variable z is a decimal integerbetween 1 and 10000.ABSolute a%specifies a user’s maximum absolute share of the all active processors in asystem. The variable a is a decimal real number—no or one decimalplace—from 0.1 to 100 (for example, 20.5%, or 80%). If ABSOLUTE y% wasspecified, y must be less than or equal to a.RELative bspecifies a user’s maximum relative share of the system. The variable b is adecimal integer between 1 and 10000. If RELATIVE z was specified, z must beless than or equal to b.NOLimitspecifies that a user’s share of processing resource is not limited.Chapter 17. Creating and Updating a User Directory 555

SHAREUsageNotesLIMITSoftspecifies that a user’s share of processing resource is limited. However, thereare times when LIMITSOFT users will receive more than their limit. This occurswhen some users are not using all of their shares (for example, they are waitingfor I/O to complete), and there are no NOLIMIT users nor users who have notyet reached their limit and can use additional processing resource. If amaximum share is not specified, the minimum share is also the maximum.LIMITHardspecifies that a user’s share of processing resource is limited. WhenLIMITHARD is specified, a user will not receive more than its maximum shareof the processing resource. If a maximum share is not specified, the minimumshare is also the maximum.1. If you do not specify a SHARE statement for a virtual machine, CP assigns thatvirtual machine a relative share of 100.2. For more information on scheduler shares, see the z/VM: Performance book.3. If a limit is specified without a maximum share being specified, the user’sminimum share is also its maximum share.Examples1. To assign a minimum absolute share of 50%, use the following SHAREstatement in the virtual machine’s directory entry:Share Absolute 50%2. To assign a minimum relative share of 200, use the following SHARE statementin the virtual machine’s directory entry:Share Relative 2003. To assign a minimum absolute share of 50% and a maximum absolute share of60%, use the following SHARE statement in the virtual machine’s directoryentry:Share ABSOLUTE 50% ABSOLUTE 60%4. To assign a minimum relative share of 100 and a maximum absolute share of75%, where the maximum share is a hard limit, use the following SHAREstatement in the virtual machine’s directory entry:Share RELATIVE 100 ABSOLUTE 75% LIMITHARD556 z/VM: CP Planning and Administration

SPECIALSPECIAL Directory Control Statement (Device)►► SPEcial vdev 3270Ibm►◄2701 Tele27022703CTCA3088 useridSCTC *BCTCCNCFCTCMSGProc msgprocidHIPERsQDIOdevsdevsnownerid*lannameownerid lanname*SYSTEM switchnmPurposeThe SPECIAL statement defines special virtual devices, which are fully simulated byCP and not connected with real devices at definition time. Some SPECIAL devicesmay be connected with a real device during normal operation. Refer to the DIALcommand for 3270 and communication lines and to the COUPLE command forCTCA and 3088 devices. Refer to z/VM: CP Commands and Utilities Reference fordetails.Use SPECIAL HIPER to create a virtual HiperSockets adapter in the virtualmachine, and (optionally) connect it to a VM LAN segment. During LOGONprocessing, this statement is equivalent to a DEFINE NIC command followed by aCOUPLE command.How to SpecifyIf you specify the SPECIAL statement, it must follow any general statements youspecify in a user’s directory entry. (For a list of general statements, see Table 20 onpage 448.)SPECIAL statements are allowed within a profile entry if no duplicate virtual devicenumbers are in the profile. Any virtual device number in a profile that duplicates avirtual device number in a user entry is resolved at logon time, with the userSPECIAL request presented to the system first.OperandsvdevFor most SPECIAL devices, this is the virtual device address of the device toChapter 17. Creating and Updating a User Directory 557

SPECIALbe defined. For a MSGPROC , HIPERS, or QDIO device, this represents thebase (or first) device address in a series of virtual I/O devices that belong to thesame unit.A simulated adapter can also be created using the NICDEF directory statement.The NICDEF statement allows additional configuration options not available onthe SPECIAL statement.3270is the value for a virtual 3270 display device.CTCA3088SCTCBCTCCNCFCTCspecifies a CTCA, 3088, SCTC, BCTC, CNC or FCTC for a virtual 3088Multisystem Channel Communication Unit logical channel adapter. You mayalso specify:useridis the user ID of a virtual machine allowed to connect to this virtual CTCA,3088, SCTC, BCTC, CNC or FCTC using the CP COUPLE command. Formore information about the CP COUPLE command, see the z/VM: CPCommands and Utilities Reference.* tells CP that a CP COUPLE command is to be allowed only from anothervirtual CTCA, 3088, SCTC, BCTC, CNC, or FCTC owned by the samevirtual machine that owns the CTCA or 3088 defined by this SPECIALstatement.If you do not specify a user ID or an asterisk (*), a virtual machine with anyuser ID can connect to this virtual CTCA.270127022703is the value for a communication line. This value is optional and used forcompatibility only.Ibmis the virtual device type of the line you are defining. This is a 2741, 3767, orequivalent device. This is the default if it is used with the 270x operand.Teleis the virtual device type of the line you are defining. This is a 3101, 3151,3161, 3162, 3163, or equivalent device.MSGProc msgprocid nrestricts and defines a virtual message processor and associated messagedevices in the virtual I/O configuration. It creates a message facility environmentfor the user and establishes a connection to the specified Coupling Facility (CF)Service Machine supplying the message processor function.If this is being used to define a CFLINK, then n must be between 2 and 8; thedefault is 2. If this is being used to define a MSGPROC, then n must be aneven number between 4 and 16; the default is 4. However, if the MSGPROC isnot in z/Architecture mode, then the default value (2 or 4, as appropriate) istaken for n, no matter what is specified.558 z/VM: CP Planning and Administration

SPECIALDefining a message processor by the SPECIAL MSGPROC directory statementallows the system administrator to restrict the message processors a user isallowed to define with the DEFINE MSGPROC command. Once a SPECIALMSGPROC directory statement is specified in the user’s directory entry, theuser may only define message processors specified by SPECIAL MSGPROCstatements.The virtual message processor will only be defined if the following conditionsexist:v OPTION CFUSER is specified in the directory entry for this userv the vdev specified is the first of four available consecutive device numbers inthe users virtual configurationv the specified CF Service Machine user ID is running prior to the logging on ofthis virtual machine.Note: If the above conditions are not met, but OPTION CFUSER was specifiedin the user directory, the user will have to define the message processorwith the DEFINE MSGPROC command after logging on. Since theSPECIAL statement was specified, the user will still be restricted to onlydefining the message processors specified in his directory.HIPERsindicates that a simulated HiperSockets adapter should be created based onthis statement. A simulated Network Interface Card (NIC) is defined duringLOGON with devs devices (beginning with the base, vdev). If a VM LAN isidentified, the NIC is automatically coupled to ownerid lanname.QDIOindicates that a simulated QDIO adapter should be created based on thisstatement. A simulated Network Interface Card (NIC) is defined during LOGONwith devs devices (beginning with the base device, vdev). If a VM LAN orVirtual Switch is identified, the NIC is automatically coupled to the specifiedlanname or switchnm.devsis the number (decimal) of virtual I/O devices to be created for a simulatedNetwork Interface Card (NIC). This number is evaluated during LOGONprocessing. For a simulated HiperSockets adapter, devs must be a decimalvalue between 3 and 3,072 (inclusive). For a simulated QDIO adapter, devsmust be a decimal value between 3 and 240 (inclusive). The default for eitherHIPERS or QDIO is three (3) devices.ownerid|* lannameidentifies a VM LAN segment for an immediate connection to the NetworkInterface Card (NIC). When ownerid and lanname are omitted, the simulatedadapter is left in the default (uncoupled) state. When ownerid and lanname arespecified, the simulated adapter is automatically connected to the designatedVM LAN. Note that ownerid may be specified as asterisk (*) to represent theuser ID of the current virtual machine.SYSTEM switchnmidentifies a Virtual Switch for an immediate connection to the Network InterfaceCard (NIC). When SYSTEM switchnm is omitted, the simulated adapter is left inthe default (uncoupled) state. When SYSTEM switchnm is specified, thesimulated adapter is automatically connected to the designated Virtual Switch.Chapter 17. Creating and Updating a User Directory 559

SPECIALUsage NotesExamples1. When a simulated NIC is defined (HIPERS or QDIO device types), theSPECIAL statement results in the creation of a series of I/O devices. The basedevice is validated by directory processing, but the remaining devices in therange are validated during LOGON processing. If another device is found in therange established by vdev and devs, the simulated NIC cannot be created.2. It is possible to define a simulated HiperSockets NIC or QDIO NIC that will beautomatically coupled to a VM LAN (designated by ownerid lanname) or todefine a simulated QDIO NIC that will be automatically coupled to a VirtualSwitch (designated by SYSTEM switchnm). However, if the designated VM LANor Virtual Switch is not available when this user signs on, the COUPLE cannotbe performed. To make effective use of this feature, you should consider addinga DEFINE LAN or DEFINE VSWITCH statement in the SYSTEM CONFIG file tocreate the target VM LAN or Virtual Switch during system initialization.3. The virtual channel-to-channel adapter defined will be equivalent to aSystem/370 CTCA designed after 1 January 1981. To determine which I/Ocommands a CTCA supports, refer to the S/360 S/370 Channel-To-ChannelAdapter book.4. When SPECIAL MSGP is processed, if the creation of the CFLINK is delayed(in case the target was not logged on yet or not ready to be the receiver of aCFLINK), the following message is displayed:HCP2821I SPECIAL MSGP processing was deferredEach time a coupling facility virtual machine (CFVM) finishes logging on, theexisting CFVMs reevaluate their SPECIAL MSGPs to determine if any willnominate the new CFVM. Then each SPECIAL MSGP that matched is handled.5. The SPECIAL HIPER statement generates multiple virtual I/O devices. If anyother device exists in the range required for the vdev plus devs (minus 1), theHiperSockets adapter cannot be created.1. Define a simulated QDIO adapter using I/O devices 0500–0507 (eight devices)which will be coupled to the SYSTEM-owned INEWS LAN during LOGONprocessing:SPECIAL 500 QDIO 8 SYSTEM INEWS2. Define a simulated HiperSockets adapter using I/O devices FD20–FD2F (16devices) which will be coupled to the user’s own HSTEST LAN during LOGONprocessing:SPECIAL FD20 HIPERS 16 * HSTESTNote that this adapter cannot couple to the designated LAN during LOGONunless it has been defined earlier. This can be accomplished by adding thenecessary DEFINE LAN statement to the SYSTEM CONFIG file.3. To define a CTCA at virtual device number 2FF that may be coupled byLINKMAN, specify one of the following SPECIAL statements in the virtualmachine’s directory entry:Special 2ff Ctca linkmanSpecial 2ff 3088 linkman4. To define a 3088 at virtual device number 3F0 that may be coupled to by anyvirtual machine, specify one of the following SPECIAL statements in the virtualmachine’s directory entry:Special 3f0 3088Special 3f0 Ctca560 z/VM: CP Planning and Administration

SPECIAL5. To define virtual 3270 display devices at virtual device numbers 101, 102, and103, specify the following SPECIAL statements in the virtual machine’s directoryentry:Special 101 3270Special 102 3270Special 103 32706. To define a virtual communication line at virtual device numbers 301, 302, and303, specify the following SPECIAL statements in the virtual machine’s directoryentry:Special 301 2702 IbmSpecial 302 2702Special 303 IbmNote: Although the statements differ in content, they all define the same type ofline at their respective device numbers.7. To define a virtual HiperSockets adapter with I/O devices 0500–0507 (eightdevices) and connect it to the system-owned LAN named INEWS duringLOGON processing, specify the following SPECIAL statement in the virtualmachine’s directory entry:Special 500 hiper 8 system inewsChapter 17. Creating and Updating a User Directory 561

SPOOLSPOOL Directory Control Statement (Device)►► Spool vdev devtype(1)A 0F 22 4WCGM CFS NODATCKclass(1) 0F 22 4WCGM CFS NODATCKwidthlength4WCGM CFS NODATCK2WCGM BTS DATCK►◄Notes:1 The following variables are only recognized for a 3800 printer.PurposeThe SPOOL statement defines virtual unit record devices.How to SpecifyIf you specify the SPOOL statement, it must follow any general statements youspecify in a user’s directory entry. (For a list of general statements, see Table 20 onpage 448.)SPOOL statements are allowed within a profile entry if no duplicate virtual devicenumbers are in the profile. Any virtual device number in a profile that duplicates avirtual device number in a user entry is resolved at logon time, with the userSPOOL request presented to the system first.When processing the SPOOL statement, DIRECTXA checks for a maximum of eighttokens: virtual device number, device type, spooling class, width of the paper, lengthof the paper, number of writable characters, stacker type, and data check setting, inthat order. If you specify more than eight tokens, DIRECTXA ignores the extratokens and system processing continues as if you had not specified the extratokens.Operandsvdevis the virtual device number for the spooling device.devtypeis the device type. Valid device types are:1403 2540 Note 13800 Note 22501 3505 3800-1 Note 33203 3525 3800-3 Note 43211 4245 Printer Note 53262 4248 PRT Note 5PCH Note 6PUnch Note 6RDR Note 7Reader Note 7VAFP Note 8562 z/VM: CP Planning and Administration

SPOOLNotes:1. Specify 2540 for a reader or a punch.2. 3800 defaults to a 3800 Model 1 printer.3. Specify 3800-1 for a 3800 Model 1 printer.4. Specify 3800-3 for a 3800 Model 3 printer.5. Printer or PRT default to a 1403 printer.6. PCH or PUnch default to a 2540 punch.7. RDR or Reader default to a 2540 reader.8. Specify VAFP for a virtual advanced functional printer. For more information, see theDEFINE (Spooling Device) command in the z/VM: CP Commands and UtilitiesReference.classis the spooling class. If omitted, A is used as a default. The variable class is a1-digit alphanumeric character from A to Z, from 0 to 9, or an asterisk (*). Areader is the only valid device that can use an asterisk (*).For spooled output devices, the class governs the punching or printing of thereal spooled output. For spooled input devices, the class controls access tospool files by virtual card readers.width lengthspecifies the physical characteristics of the paper to be loaded into the 3800printer. The variable width is the hexadecimal form width code of the paper, andlength indicates the decimal length of the paper. Specify length as a decimalnumber using half-inches. If width and length are omitted, 14-7/8 x 11 inches isused as a default.The following table lists available form-width codes (values other than thoselisted below are rejected):Code Width in Inches Width in Millimeters01 6-1/2 16502 Reserved 18004 8-1/2 21506 9-1/2 23507 9-7/8 25008 10-5/8 27009 11 2800A 12 3050B Reserved 3220D 13-5/8 3400E 14-3/10 3630F 14-7/8 3782WCGM4WCGMspecifies the number of writable character generation modules (WCGM) for thevirtual 3800 printer. A WCGM is a 64-position portion of the 3800’s charactergeneration storage that holds the scan elements of one character set. A 3800-1can have either two or four WCGMs. A 3800-3 has four WCGMs. If omitted, thedefault is 4WCGM.BTSCFSspecifies the type of stacker for the virtual 3800 printer. You may specify eitherCFS (continuous forms stacker) or BTS (burster trimmer stacker). If omitted, thedefault is CFS.Chapter 17. Creating and Updating a User Directory 563

SPOOLDATCKNODATCKspecifies whether CP processes certain virtual 3800 data checks for the virtualmachine. If you specify DATCK, CP reflects all data checks to the virtualmachine (if the Block Data Check CCW is not issued). If you specifyNODATCK, only data checks due to invalid translate table specifications orunmatched FCB codes are reflected to the virtual machine. If omitted, thedefault is NODATCK.Note: Specifying DATCK severely increases the overhead associated withsimulation of Write and Skip CCWs to the virtual 3800. In general, thereflection of data checks due to overprinting and invalid EBCDIC codesis not necessary. Therefore, specify DATCK only when absolutelynecessary.Examples1. To define at 00C a spooled reader that can read any class of spool file, specifythe following SPOOL statement in the virtual machine’s directory entry:Spool 00c Reader *2. To define at 00D a spooled punch that creates only class P spool files, specifythe following SPOOL statement in the virtual machine’s directory entry:Spool 00d Punch p3. To define at 00E a spooled 1403 printer that processes class E spool files,specify the following SPOOL statement in the virtual machine’s directory entry:Spool 00e 1403 e4. To define at 00E a virtual 3800 printer with these characteristics:v Only class Z spool filesv 11 X 11 inch paperv Two WCGMsv The continuous forms stackerv No CP reflection of data checksspecify the following SPOOL statement in the virtual machine’s directory entry:Spool 00e 3800 z 09 22 2wcgm Cfs NoDatCk564 z/VM: CP Planning and Administration

SPOOLFILESPOOLFILE Directory Control Statement (General)►► SPOOLFile MAXSPOOL nnnn ►◄PurposeThe SPOOLFILE statement describes virtual machine spool file characteristics. Usethe MAXSPOOL nnnn operand to specify the maximum number of spool filesallowed for a virtual machine.How to SpecifyOnly one SPOOLFILE statement is allowed per user. If you specify the SPOOLFILEstatement, it must precede any device statements specified in a user’s directoryentry and must follow the USER statement. (For a list of device statements, seeTable 20 on page 448.) If the SPOOLFILE statement is omitted, the defaultmaximum number of spool files is 9999.One SPOOLFILE statement is allowed within a profile, but is used only if noSPOOLFILE statements are in the user directory entry.When processing the SPOOLFILE statement, DIRECTXA checks for a maximum oftwo tokens: the MAXSPOOL keyword and the decimal number of spool files, in thatorder. If you specify more than two tokens, DIRECTXA ignores the extra tokens andsystem processing continues as if you had not specified the extra tokens.OperandsMAXSPOOL nnnnspecifies the maximum number of spool files the user can have at one time.The variable nnnn is a decimal number from 1 to 9999. The spool file IDnumbers for this user will be in this range.UsageNotes1. If a virtual machine’s maximum is reset to a value below currently allocatedspool IDs, those files and spool IDs remain valid. No additional files will beallocated above the new maximum, and when an old file is deleted, that spoolID will no longer be available.2. The actual maximum number of spool files as defined in a shared CSE directoryis divided among the participating systems so that the total allowed on any onesystem may be far less than that specified by MAXSPOOL (see “Spool FileDirectory Statements” on page 341).The reason for this is that MAXSPOOL actually defines the highest spool ID thata virtual machine can have.ExamplesTo indicate that the virtual machine has a limit of 1000 spool files, specify thefollowing SPOOLFILE statement in the virtual machine’s directory entry:SpoolFile MaxSpool 1000Chapter 17. Creating and Updating a User Directory 565

STDEVOPTSTDEVOPT Directory Control Statement (General)►►STDEvopt(1)DASDSYSDASDSYSDASDSYSDASDSYSNOCONCOPYNODATAMOVERDATAMOVERCONCOPYLIBRARYLIBRARYNOCTLCTL►◄Notes:1 You must specify at least one of the operands. If you want to specify both, you can specify themin any order.PurposeThe STDEVOPT statement specifies the optional storage device managementfunctions available to a virtual machine.How to SpecifyIf you specify the STDEVOPT statement, it must precede any device statementsyou specify in the user entry or profile. (For a list of device statements, seeTable 20 on page 448.)Multiple STDEVOPT statements are allowed within a profile entry. Conflictingoperands are flagged as errors.OperandsDASDSYStells CP whether the virtual machine is authorized to control and processConcurrent Copy and peer-to-peer remote copy CCWs.NODATAMOVER(the default) tells CP that the virtual machine is not authorized forConcurrent Copy or peer-to-peer remote copy.NOCONCOPYsame as NODATAMOVER (left here to be compatible with previousreleases of VM).DATAMOVERtells CP that the virtual machine is authorized to issue Concurrent Copy andpeer-to-peer remote copy CCWs.CONCOPYsame as DATAMOVER (left here to be compatible with previous releases ofVM).LIBRARYtells CP whether the virtual machine is authorized to control a 3494 or 3495Tape Library Dataserver.NOCTL(the default) tells CP that the virtual machine is not authorized to control atape library.566 z/VM: CP Planning and Administration

STDEVOPTUsageNotesCTLtells CP that the virtual machine is authorized to issue tape library controlcommands.1. The status of a storage device management function not explicitly specified inthe user entry defaults to nonauthorization (NODATAMOVER or NOCTL), unlessthe authorization (DATAMOVER or CTL) is defined in a profile. An authorizationor nonauthorization explicitly specified in the user entry supersedes theauthorization status defined in a profile.2. With LIBRARY CTL authorization, tape library control commands can be used toaccess any volume in the library. To ensure integrity of the volumes in thelibrary, LIBRARY CTL authorization should be granted only to virtual machinesthat control the mounting and demounting of volumes, such as a guest virtualmachine for an operating system, or a service virtual machine for a tape librarycontrol program that provides automated mounting and demounting functions.3. LIBRARY CTL should not be used to authorize a virtual machine to access aparticular tape library. LIBRARY CTL allows a virtual machine to issue tapelibrary commands to any tape device, regardless of the library in which thedevice resides.4. CONCOPY and NOCONCOPY are still accepted for compatibility reasons. Theyprovide the same authorization control as DATAMOVER and NODATAMOVER,respectively. That is, specifying CONCOPY will authorize a virtual machine forboth Concurrent Copy commands and peer-to-peer remote copy commands.Specifying NOCONCOPY will disallow all Concurrent Copy commands andpeer-to-peer remote copy commands.5. Only one DASDSYS option (DATAMOVER, NODATAMOVER, CONCOPY,NOCONCOPY) is allowed in a user or profile directory. Specifying more thanone option will result in error message 776E being sent to the user console andthe directory will not get updated.Examples1. To specify that a guest virtual machine can initiate and control Concurrent Copyand peer-to-peer remote copy, specify the following STDEVOPT statement inthe virtual machine’s directory entry:STDEvopt DASDSYS DATAMOVER2. To specify that a virtual machine can control a 3494 or 3495 Tape LibraryDataserver, specify the following STDEVOPT statement in the virtual machine’sdirectory entry:STDEvopt LIBRARY CTL3. To specify that a guest virtual machine can control Concurrent Copy sessionsand peer-to-peer remote copy, and can control a tape library, specify thefollowing STDEVOPT statement in the virtual machine’s directory entry:STDEvopt LIBRARY CTL DASDSYS DATAMOVERChapter 17. Creating and Updating a User Directory 567

STORAGESTORAGE Directory Control Statement (General)►► STORAGE size ►◄PurposeThe STORAGE statement specifies the default virtual storage size for a user.How to SpecifyThe STORAGE statement, if used, must follow a USER statement and mustprecede any device statements. A STORAGE statement is allowed in a profile if theUSER statement default storage size field of each including virtual machine is eitheromitted or specified as an asterisk (*). A STORAGE statement in a user directoryentry overrides one in a profile.Operandssizeis the maximum storage size. specify it as nu, where n is a decimal number andu is the unit of measure:K kilobytes - 2¹⁰M megabytes - 2²⁰G gigabytes - 2³⁰T terabytes - 2⁴⁰P petabytes - 2⁵⁰E exabytes - 2⁶⁰UsageNotes1. A default storage setting on a USER statement override a STORAGE statementin a profile2. A STORAGE statement in a user’s directory entry overrides one in a profile.568 z/VM: CP Planning and Administration

SYSAFFINSYSAFFIN Directory Control Statement (Control)►► SYSaffin ▼ sysafnidnEXIST_ATLOGON_ATNOLOG_AT*►◄PurposeThe SYSAFFIN statement is an optional statement that can be used to define howand to which systems of a multisystem complex the subsequent statements apply.How to SpecifyA SYSAFFIN statement has two forms, prefix and internal. The prefix form is placedbefore user definitions to describe where or how the user is to be applied to thesystems of the complex. The internal form may be used to define which statementsapply to which systems in the complex. Only the internal form of the SYSAFFINstatement is allowed within a global or profile definition.Each SYSAFFIN prefix control statement applies only to the USER statement thatimmediately follows it.A SYSAFFIN internal control statement applies to the statements that immediatelyfollow it. It is active until the next SYSAFFIN prefix or internal control statement, oruntil the next PROFILE or USER statement, whichever comes first.Note: The system affinity ID, sysafnid, that is used in the following statements is a1- to 8-character alphanumeric value assigned to a system and used on aDIRECTORY statement in the beginning of the source directory. TheSYSAFFIN statement, and the control statements to which it applies, affectthe system identified by sysafnid.OperandsEXIST_AT sysafnidnspecifies that the following user definition is to be compiled into the objectdirectory by the DIRECTXA utility only when running on a system with one ofthe system affinity IDs (sysafnidn) listed on the SYSAFFIN statement. WhenDIRECTXA is running on any other system, this user definition is not to becompiled into the object directory. This means that any resources owned by thisuser definition (for example, minidisks) do not appear in the object directory ofthe other systems and, therefore, cannot be linked to by users on thosesystems.LOGON_AT sysafnidnspecifies that the user directory entry is to be compiled into the objectdirectories of all systems, but the associated virtual machine is to operate (forexample, LOGON) only on specified systems. On any other system, the logonpassword is replaced with the keyword NOLOG. However, the virtual machineChapter 17. Creating and Updating a User Directory 569

SYSAFFINUsageNoteswith this user ID and all its resources, including minidisks, exist in the objectdirectories of the other systems and can be referenced by users on thosesystems.NOLOG_AT sysafnidnspecifies that the specified user directory entry is to be compiled into the objectdirectories of all systems, but the associated virtual machine is not to beoperable on the identified systems (sysafnidn). However, the virtual machineand all its resources, including minidisks, are to exist as directory entries in theobject directories of these systems and can be referred to by users on thosesystems.*sysafnidnis a 1- to 8-character alphanumeric string that identifies the system that thesubsequent control statements apply to. Valid sysafnidns are defined on theDIRECTORY Control Statement. * indicates that the subsequent controlstatements apply to all systems.1. The default system affinity for user definitions not otherwise prefixed by aSYSAFFIN control statement is LOGON_AT *. This means that the userdefinition is applied to and that the defined user can log on at all systems in thecomplex. The default system affinity for all other control statements is *,meaning that all subsequent control statements apply to all systems in thecomplex.2. In a system that uses the LOGON_AT or NOLOG_AT operands of theSYSAFFIN statement, the class B virtual machine that does the DIAGNOSEcode X'84' operations should have D84NOPAS specified on the OPTIONstatement.3. Except for the logon status of the virtual machine (as defined by the use of aSYSAFFIN prefix statement), the data on the USER statement is common to allsystems in the complex where the user is defined to exist.4. EXIST_AT should not be used for systems sharing spool files in a CSEcomplex.5. The internal form of the SYSAFFIN control statement may be used in userdefinitions, profile definitions, and the global definition section. These statementsdefine which portions of the various definitions apply to which systems in thecomplex.ExamplesIn the examples that follow, assume this multisystem complex definition:Directory 07a4 3380 vmaipl *01234-2064 vmaDirectory 0b64 3380 vmbipl 104567-2064 vmbDirectory 0cF4 3380 vmcipl *15211-2064 vmcDirectory 0664 3380 vmdipl *00012-2064 vmd1. The PROFILE DEPT1234 definition will be available on all systems. Profilescannot use the prefix form of the SYSAFFIN statement. They can, however, betailored using the internal form:Profile dept1234SysAffin vmaAccount 00000001 00000002SysAffin vmbAccount 00000003 00000004SysAffin *Link deptdb 100 100 rr570 z/VM: CP Planning and Administration

SYSAFFINLink deptdb 101 101 rrSysAffin vmaLink deptdb 200 200 rrSysAffin vmbLink deptdb 201 200 rr2. Defined below are users of DEPTDB with different system affinity situations.v This is the department database, with common disks 100 and 101 andunique disks 200 and 201, depending on whether the system is VMA or VMB:SysAffin Exist_At vma vmbUser deptdb ...Mdisk 100 ...Mdisk 101 ...SysAffin vmaMdisk 200 ...SysAffin vmbMdisk 201 ...v User TOM has access to all systems and through the INCLUDE statementhas access to the department database. Depending on whether he is loggedon to VMA or VMB, he will have linked a different disk as his 200. He willalso have an appropriate set of R/W minidisks for each system.User tom ...Include dept1234Account 12340001SysAffin vmaMdisk 191 ...Mdisk 193 ...SysAffin vmbMdisk 191 ...Mdisk 193 ...v User MARY is limited to VMA access and will have access to the departmentdatabase on VMA only.SysAffin Logon_At vmaUser mary ...Include dept1234Account 12340002Mdisk 191 ...Mdisk 193 ...3. The following global definition section would define a default machine mode ofXA on system vma and a default machine mode of ESA on system vmb.GlobaldefsSysaffin vmaGlobalopts machine xaSysaffin vmbGlobalopts machine esaChapter 17. Creating and Updating a User Directory 571

USERUSER Directory Control Statement (Control)►► User userid passwordNOLOGNOPASSAUTOONLYLBYONLYstormstorclpriSymbols►◄Symbols:ON ON ON ONON ON ONONOFF ON ONle ONOFFld ONOFFcdONOFFesPurposeThe USER statement starts each virtual machine’s directory entry. It also defines auser ID and password, a logon and maximum virtual machine storage size,command privileges, and special symbol usage for the virtual machine.How to SpecifyUSER statements are not allowed within a profile entry.When processing the USER statement, DIRECTXA checks for a maximum of tentokens: userid, password, logon storage size, maximum storage size, privilegeclass, a place holder for compatibility with VM/SP, line-end symbol, line-deletesymbol, character-delete symbol, and escape character, in that order. If you specifymore than ten tokens, DIRECTXA ignores the extra tokens and system processingcontinues as if you had not specified the extra tokens.Operandsuseriddefines the virtual machine’s 1- to 8-character user ID. LOGNxxxx, LOGLxxxx,LOGVxxxx, LOGNSYSC, LOGNSYSG, and SYSTEM are reserved for CP use.You should not assign user IDs that are system keywords (such as commandnames, command operands, or 1- to 4-digit user IDs that could be spool IDs).Assigning system keywords as user IDs can cause unpredictable results. For alist of restricted user IDs, see z/VM: CP Commands and Utilities Reference.You should not assign user IDs that contain colons (:), periods (.), semicolons(;), or slashes (/). These characters are used, or may be used in the future, asdelimiters in several CP commands that also take a user ID as a parameter.Results are unpredictable when these commands are entered with a user IDcontaining any of these delimiter characters.572 z/VM: CP Planning and Administration

USERThe characters that you can use for user IDs are restricted by translation testtables in HCPTBL to:alphabeticsA through Znumerics0 through 9others@ # $ _ (underscore) - (hyphen)Note: It is recommended that the characters @, #, ¢, and ″ not be used in theuserid because the system, by default, assigns these characters aslogical line editing symbols. Refer to Appendix B in the z/VM: CPCommands and Utilities Reference for a discussion of the systemdefaults settings for logical line editing symbolsYou can override the translation tables in HCPTBL. See the“TRANSLATE_TABLE Statement” on page 243.passwordspecifies a 1- to 8-character password that a user enters during the log onprocedure.NOLOGspecifies that a user cannot log on. You can use the NOLOG option to createvirtual machines to which no one can log on. For example, you can placespecial system DASD areas (allocation, warm-start, and checkpoint areas) onminidisks and then assign the minidisks to virtual machines with NOLOGpasswords. This helps you identify areas on a DASD.Also, you can create minidisks for common user data and then assign theminidisks to virtual machines with NOLOG passwords. Users can then enter aCP LINK command to access those minidisks when they need the data.Note: It is recommended that the characters @, #, ¢, and ″ not be used in theuserid because the system, by default, assigns these characters aslogical line editing symbols. Refer to Appendix B in the z/VM: CPCommands and Utilities Reference for a discussion of the systemdefaults settings for logical line editing symbolsNOPASSspecifies that a user does not require a password to log on. It also specifiesthat a virtual machine may be automatically logged on using the XAUTOLOGcommand without password authorization.Even though a user ID is defined with the NOPASS operand, LOGON passwordauthorization may be required when an External Security Manager is installed.For more information, refer to documentation provided by your External SecurityManager.AUTOONLYspecifies that a user can be autologged, but not logged on at a terminal.LBYONLYspecifies that:v Logging on to this virtual machine with the LOGON command requires use ofthe BY option.v This user ID cannot be used to log on to any virtual machine with the BYoptionChapter 17. Creating and Updating a User Directory 573

USERFurthermore, this user ID may not be able to perform functions that requirepassword validation, since LBYONLY is not accepted as a valid password.CP allows an External Security Manager (ESM) to override these restrictions,so they are effective only when no ESM is installed or when the ESM defers toCP’s processing. See the ESM documentation for more information.storspecifies the virtual machine’s primary address space size at log on. Specifystor as nu where n is a one- to seven-digit decimal number and u is the unit ofmeasure (see Table 25). The maximum value you can specify is 16E or 16384P,though the actual maximum size supported may be restricted by the model ofthe processor where the directory is used.The storage field can also contain an asterisk (*) as a placeholder. If it isomitted or specified as an asterisk, this indicates that the storage size is definedby a MAXSTORAGE statement in either the user’s directory entry or a directoryprofile.Values below 16 MB are rounded up to 64 KB boundaries. Values above 16 MBare rounded up to 1 MB boundaries.Table 25. Storage Units of MeasureUnits suffixMaximumallowed as inputK - Kilobytes 2096128M - Megabytes 9999999G - Gigabytes 9999999T - Terabytes 9999999P - Petabytes 16384E - Exabytes 16574 z/VM: CP Planning and AdministrationNote: Allowing large numbers of V=V virtual machines to have large primaryaddress space sizes may affect real storage availability. See usage note1 on page 576.mstorspecifies a maximum virtual machine primary address space size that a usercan specify with the DEFINE STORAGE command. Specify mstor as nu, wheren is a one- to seven-digit decimal number and u is the unit of measure (seeTable 25). The default is 1M (1 MB).The storage field can also contain an asterisk (*) as a placeholder. If it isomitted or specified as an asterisk, this indicates that the maximum storage sizeis defined by a MAXSTORAGE statement in either the user’s directory entry ora directory profile.Note: Allowing large numbers of V=V virtual machines to have large primaryaddress space sizes may affect real storage availability. See usage note1 on page 576.cl specifies the privilege class or classes of CP commands a user can enter.Command classes are A through Z, and 1 through 6. You may specify up to 32classes (if they fit). Each character represents a single privilege class and mayappear in any order, without duplication, and must not be separated by blanks.The class field can also contain an asterisk (*) as a place holder. If the field isnot specified, or if it contains an asterisk (*) and there is no CLASS statement,

USERCP uses the default class or classes assigned by the PRIV_CLASSESstatement in the system configuration file (page 184) or by the SYSFCN macroin HCPSYS (page 673).Note: If you have not used the user class restructure function to change yourclasses from the IBM-defined defaults, only classes A through G arevalid. Refer to Chapter 16, “Redefining Command Privilege Classes,” onpage 433 for information on defining your own user class structure. For adescription of the different command classes, see the z/VM: CPCommands and Utilities Reference.pri is for VM/SP compatibility and serves no z/VM function. It must be a numberfrom 1 to 99. If the pri specification is not entered, the line-end (le), line-delete(ld), character-delete (cd), and escape (es) characters default to ON.leONOFFle is a 1-character line-end symbol or a 2-digit hexadecimal equivalent of thesymbol. Input following a line-end symbol begins a new logical line. ON meansthat the virtual machine uses the system value. OFF means that CP will notrecognize line-end symbols. If omitted, the default is ON.Note: If you want to set a system-wide default for the line-end symbol, use theCHARACTER_DEFAULTS statement in the system configuration file. Formore information about setting system-wide defaults, see page 67.ldONOFFld is a 1-character line-delete symbol or a 2-digit hexadecimal equivalent of thesymbol. A line-delete symbol causes the previous logical line input to beignored. ON means that the virtual machine uses the system value. OFF meansthat CP will not recognize line-delete symbols. If omitted, the default is ON.Note: If you want to set a system-wide default for the line-delete symbol, usethe CHARACTER_DEFAULTS statement in the system configuration file.For more information about setting system-wide defaults, see page 67.cdONOFFcd is a 1-character delete symbol or a 2-digit hexadecimal equivalent of thesymbol. A character-delete symbol causes the previous character input to beignored. ON means the virtual machine uses the system value. OFF means thatCP will not recognize character-delete symbols. If omitted, the default is ON.Note: If you want to set a system-wide default for the character-delete symbol,use the CHARACTER_DEFAULTS statement in the system configurationfile. For more information about setting system-wide defaults, see page67.esONOFFes is a 1-character escape symbol or a 2-digit hexadecimal equivalent of thesymbol. The escape symbol causes CP to treat the following character literally,Chapter 17. Creating and Updating a User Directory 575

USERUsageNoteswithout consideration as an le, ld, or cd character. ON means that the virtualmachine uses the system value. OFF means that CP will not recognize escapesymbols. If omitted, the default is ON.Note: If you want to set a system-wide default for the escape symbol, use theCHARACTER_DEFAULTS statement in the system configuration file. Formore information about setting system-wide defaults, page 67.1. For each virtual machine, CP creates a segment table to represent the virtualmachine storage. For a virtual machine of 32 MB or less, CP creates thesegment table inside the virtual machine definition block (VMDBK). For a largervirtual machine, CP creates the segment table outside the VMDBK in realstorage, as follows:v For a virtual machine larger than 32 MB but less than or equal to 1024 MB,one real storage frame is allocated for the segment table.v For a virtual machine larger than 1024 MB, two consecutive real storageframes are allocated for the segment table.CP creates the segment table at the start of the real storage frame, and anystorage remaining beyond the end of the segment table may be used for CPfree storage. However, if a large number of virtual machines are definedarbitrarily large, considerable real storage may be consumed by the segmenttables.2. The cl field may contain an asterisk (*) as a place holder. If no further optionsare to be specified on the USER statement, the asterisk (*) is not required. Ineither case, if the CLASS statement is not supplied, CP uses the default classor classes assigned by the PRIV_CLASSES statement in the systemconfiguration file (page 184) or by the SYSFCN macro in HCPSYS (page 673).3. If any of the options are specified, all prior options must also be specified. Thedefault for unspecified options is ON.4. The USER statement defines the special symbol usage for a specific virtualmachine. To override the special symbol usage for a specific virtual machine,have the user issue the CP TERMINAL command described in the z/VM: CPCommands and Utilities Reference. To set default special symbol usage for theentire system, use the CHARACTER_DEFAULTS statement in the systemconfiguration file (page 67).You cannot use any of the letters A through Z, the numbers 0 through 9, or thebytes X'0E' (shift out) or X'0F' (shift in) for the line-end, line-delete,character-delete, or escape symbols.Examples1. To start a directory entry for user ID BONES that specifies:v WW11QQ as BONES’s passwordv 8M as BONES’s virtual machine storage size at logonv 16M as the maximum virtual machine storage size BONES can definev BONES can enter only class S commandsspecify the following USER statement:User bones ww11qq 8m 16m s2. To start a directory entry for user ID WIZARD that specifies:v JK76TG as WIZARD’s passwordv 4M as WIZARD’s virtual machine storage size at logon576 z/VM: CP Planning and Administration

USERv 6M as the maximum virtual machine storage size WIZARD can definev WIZARD can enter class A, B, C, Z, 3, 4, and G commandsspecify the following USER statement:User wizard jk76tg 4m 6m abcz34g3. To start a directory entry for user ID SHARDATA that specifies the NOLOGoption, specify the following USER statement:User shardata NoLogChapter 17. Creating and Updating a User Directory 577

XAUTOLOGXAUTOLOG Directory Control Statement (General)►►XAUTOlogAUTOlog▼ (1) userid ►◄Notes:1 A total of 8 user IDs can be specified.PurposeThe XAUTOLOG statement designates up to eight users that can enter theXAUTOLOG command for the virtual machine. All users with class A or class Bprivileges can enter the XAUTOLOG command for any virtual machine. Therefore,their user IDs do not have to appear on the XAUTOLOG statement.How to SpecifyIf you specify the XAUTOLOG statement, it must precede any device statementsyou specify in a user’s directory entry. (For a list of device statements, see Table 20on page 448.) A directory entry may contain multiple XAUTOLOG statements, butonly a total of eight user IDs (including those in AUTOLOG statements) is allowed.Multiple XAUTOLOG statements are allowed within a profile, but are used only if noXAUTOLOG (or AUTOLOG) statements are in the including user directory entry.Operandsuseridspecifies a 1- to 8-character user ID of a user whom you authorize to enter theXAUTOLOG command for the virtual machine whose directory entry you arecreating. A total of eight user IDs (including those in AUTOLOG statements) canbe specified.UsageNotes1. AUTOLOG is an acceptable synonym for the XAUTOLOG statement. Theminimum abbreviation is AUTO. The XAUTOLOG statement, whether namedXAUTOLOG or AUTOLOG, authorizes the use of the XAUTOLOG commandand does not authorize the use of the AUTOLOG command. The AUTOLOGcommand authorization is through the use of a password only.2. In addition to being listed on an XAUTOLOG directory statement, a user musthave class G privileges to enter the XAUTOLOG command for the virtualmachine. (Users with class A or B privileges can enter the XAUTOLOGcommand for any virtual machine without being specified in an XAUTOLOGstatement.)Examples1. To authorize a user whose ID is LARRY (and has class G privileges) to enterthe XAUTOLOG command for a virtual machine, specify the followingXAUTOLOG statement in the virtual machine’s directory entry:XautoLog larry578 z/VM: CP Planning and Administration

XAUTOLOG2. To authorize users whose IDs are OPER1, OPER2, OPER3, and JONES (andhave class G privileges) to enter the XAUTOLOG command for a virtualmachine, specify the following XAUTOLOG statement in the virtual machine’sdirectory entry:XautoLog oper1 oper2 oper3 jonesChapter 17. Creating and Updating a User Directory 579

XCONFIGXCONFIG Directory Control Statement (General)PurposeThe XCONFIG statement specifies control parameters for the extendedconfigurationfacilities provided in the XC virtual machine architecture: access listsand address spaces. Some of the control parameters specified on the XCONFIGstatement are used only by XC virtual machines, whereas others are used in alltypes of virtual machines.Each XCONFIG statement contains one of the mutually exclusive major operandsACCESSLIST or ADDRSPACE and specifies control parameters for a single aspectof the extended-configuration facilities. For example, a single XCONFIG statementcan contain the ACCESSLIST operand with parameters for access lists, but cannotalso contain the ADDRSPACE option with parameters for address spaces.Descriptions of the ACCESSLIST and ADDRSPACE operands follow.To specify control parameters for more than one element of theextended-configuration facilities, you can specify multiple XCONFIG statements.However, each major option can each appear on, at most, one XCONFIG statementwithin a USER definition, and on, at most, one XCONFIG statement within aPROFILE definition.If a major option appears on an XCONFIG statement in both the USER definitionand in an included PROFILE definition, then any operands specified in the USERdefinition override those specified (or defaulted) in the PROFILE definition.Operands that are specified (or defaulted) in the PROFILE definition but not alsospecified in the USER definition are used as specified (or defaulted) in thePROFILE definition.How to SpecifyIf you specify any XCONFIG statements, they must precede any device statements,both when specified within a USER definition and when specified within a PROFILEdefinition. (For a list of device statements, see Table 20 on page 448.)UsageNotes1. The XCONFIG statements are processed by CP at the time of a user’s logon,and the control parameters in effect at logon are used for the user’s entiresession. If changes are made to XCONFIG statements in a user’s CP directoryentry, the user must log off and log on again for the changed parameters to takeeffect.580 z/VM: CP Planning and Administration

XCONFIGXCONFIG ACCESSLIST Operand►► XCONfig ACCEsslist ALSIZE alecount ►◄PurposeThe XCONFIG ACCESSLIST operand specifies the size of the host access list tobe provided for this virtual machine. CP creates a host access list for each virtualmachine. For XC virtual machines, each entry in the virtual machine’s host accesslist designates an address space that can be accessed when the virtual machine isin the access-register mode. For XA, or ESA virtual machines, each entry in thevirtual machine’s host access list designates an address space that can beaccessed using DIAGNOSE code X'248' (Copy to primary service). Valid hostaccess list entries are added and removed using the ALSERV macroinstruction(access list services). For more information about the ALSERV macroinstruction,see the z/VM: CP Programming Services book.How to SpecifyIf you do not specify an XCONFIG statement with an ACCESSLIST operand, CPwill give the virtual machine a 62-entry host access list, by default.OperandsALSIZE alecountspecifies the size, in number of access-list entries, for this virtual machine’shost access list. The variable alecount is a decimal number from 1 to 1022.CP allocates host access lists in sizes that contain 6, 14, 30, 62, 126, 254, 510or 1022 entries. If you do not specify alecount as one of these numbers, thenCP rounds alecount up to the next largest number in this set.UsageNotes1. A virtual machine’s host access list resides in host (CP) real storage. When ahost access list is initially created for a virtual machine, sufficient host realstorage for a 6-entry host access list is allocated for the access list. As morehost access list entries are required, additional host storage is allocated to holdthe next larger-sized host access list, until the access-list size reaches the sizespecified by this directory statement. CP will reuse any host access list entrythat is in the invalid state before expanding the host access list in this manner,but once a host access list has been expanded, it will not be compressed if hostaccess list entries subsequently return to being in the invalid state.2. A 254-entry host access list can require up to 1 page of host real storage and a1022-entry host access list can require up to 4 pages of host real storage.3. The host real storage allocated for a virtual machine’s host access list is notavailable for use by CP for paging or other operations. To minimize the hoststorage used for access lists, allocate the smallest-sized host access list thatmeets the requirements for a particular virtual machine.ExamplesTo specify that a virtual machine is to have a 126-entry host access list, use thefollowing statement in the user’s directory entry:Chapter 17. Creating and Updating a User Directory 581

XCONFIGXconfig AccessList ALsize 126582 z/VM: CP Planning and Administration

XCONFIGXCONFIG ADDRSPACE Operand►► XCONfig ADDRspaceMAXNUMBER nnnnn TOTSIZE nnnnnMnnnnGNOSHARESHARE►◄PurposeThe XCONFIG ADDRSPACE operand specifies the maximum number ofnonprimary address spaces (sometimes known as data spaces) and the total size inbytes of all nonprimary address spaces that the virtual machine can ownsimultaneously. These address spaces are created using the ADRSPACEmacroinstruction (address-space services) CREATE function. It also specifieswhether the virtual machine can allow other virtual machines to share its addressspaces. Only XC virtual machines can create and destroy address spaces using theCREATE and DESTROY functions of the ADRSPACE macroinstruction. ESA, XA,and XC virtual machines can allow other virtual machines to share their addressspaces by using the PERMIT function of the ADRSPACE macroinstruction. (This islimited to sharing the virtual machine’s primary address space.) For moreinformation about the ADRSPACE macroinstruction, see the z/VM: CP ProgrammingServices book.How to SpecifyIf you do not specify an XCONFIG ADDRSPACE statement, CP uses a default of 0for MAXNUMBER, which indicates no additional address spaces can be created.OperandsMAXNUMBER nnnnnspecifies the maximum number of nonprimary address spaces that this virtualmachine can create and have existing concurrently. The variable nnnnn is adecimal number from 0 to 32767.If you omit the MAXNUMBER and TOTSIZE operands from the XCONFIGADDRSPACE statement, the default is MAXNUMBER 0, that is, no additionaladdress spaces can be created.TOTSIZE nnnnnMTOTSIZE nnnnGspecifies the maximum total size, in bytes, of all address spaces that this virtualmachine can create and have existing concurrently. The variable nnnnnM is adecimal number from 1 megabyte to 99999 megabytes. The variable nnnnG isa decimal number from 1 gigabyte to 8192 gigabytes.The minimum value for TOTSIZE is 1M for each address space permitted bythe MAXNUMBER operand; if the TOTSIZE operand specifies a total less thanthis number, then an error message is issued. The maximum that can bespecified for TOTSIZE is 8192B.NOSHAREtells CP that the virtual machine cannot use the PERMIT function of theADRSPACE macroinstruction to make its address spaces available for accessby other virtual machines. The default is NOSHARE.Chapter 17. Creating and Updating a User Directory 583

XCONFIGUsageNotesSHAREtells CP that the virtual machine can use the PERMIT function of theADRSPACE macroinstruction to make its address spaces available for accessby other virtual machines.1. Allowing large numbers of nonprimary address spaces and/or a large totaladdress space size may affect real storage availability. For each address space,CP creates a segment table in real storage, as follows:v For each address space less than or equal to 1024 MB, one real storageframe is allocated for the segment table.v For each address space larger than 1024 MB, two consecutive real storageframes are allocated for the segment table.CP creates the segment table at the start of the real storage frame, and anystorage remaining beyond the end of the segment table may be used for CPfree storage. However, if users are permitted to create large numbers ofaddress spaces and/or very large size address spaces, considerable realstorage may be consumed by the segment tables.Examples1. To authorize a virtual machine to create up to 128 address spaces, with a totalof 1000 MB of storage, use the following statement in the user’s directory entry:Xconfig AddrSpace MaxNumber 128 TotSize 1000M2. To authorize a virtual machine to create up to 25 address spaces, with a total of2 GB of storage, and allow the virtual machine to share its primary addressspace and any of its created address spaces with other virtual machines, usethe following statement in the user’s directory entry:Xconfig AddrSpace MaxNumber 25 TotSize 2G Share3. To authorize a virtual machine to share its primary address space with othervirtual machines, but not to create any additional address spaces, use thefollowing statement in the user’s directory entry:Xconfig AddrSpace Share584 z/VM: CP Planning and Administration

XSTOREXSTORE Directory Control Statement (General)►►XSTOREALLsize►◄PurposeThe XSTORE statement authorizes a virtual machine that supports ExpandedStorage to use the Expanded Storage facility.How to SpecifyIf you specify the XSTORE statement, it must precede any device statements youspecify in a user’s directory entry. (For a list of device statements, see Table 20 onpage 448.) Refer to Chapter 19, “Expanded Storage Planning and Administration,”on page 591 for additional information about allocating Expanded Storage.OperandsMultiple XSTORE statements are allowed within a profile but are used only if noXSTORE statements are in the user directory entry. If multiple XSTORE statementsare in an included profile entry, only the first one is used.When processing the XSTORE statement, DIRECTXA checks for a maximum ofone token: the real Expanded Storage size. If you specify more than one token,DIRECTXA ignores the extra tokens and system processing continues as if you hadnot specified the extra tokens.ALLtells CP that all of Expanded Storage configured on the system be allowed tobe used for this user’s guest partition. If you specify XSTORE without anyoperands, the default is ALL.sizeis the size expressed as nnnnnnnnM megabytes of real Expanded Storage tobe allocated to the user’s virtual machine on megabyte boundaries. Themaximum size that can be specified is 16777216 MB.The real Expanded Storage may be allocated to any number of virtual machines atthe same time.User and operator commands are available to manage the allocation of ExpandedStorage after user logon (see the z/VM: CP Commands and Utilities Reference).UsageNotes1. Several commands allow you to attach, detach, and display information aboutthe Expanded Storage facility. These commands include ATTACH XSTORE,DETACH XSTORE, and QUERY XSTORE. For more information on thesecommands, see the z/VM: CP Commands and Utilities Reference.2. If the request for Expanded Storage cannot be satisfied at logon time, themaximum amount that can be attached at this time is attached to the virtualmachine.Chapter 17. Creating and Updating a User Directory 585

XSTORE3. Multiple users may have Expanded Storage attached to their virtual machines.ExamplesTo authorize a virtual machine to use all of Expanded Storage, specify the followingXSTORE statement in the virtual machine’s directory entry:Xstore586 z/VM: CP Planning and Administration

Part 4. Storage Planning and AdministrationChapter 18. Real Storage Planning and Administration . . . . . . . . 589Planning Real Storage Needs . . . . . . . . . . . . . . . . . . . 589Real and Virtual Storage Requirements for Generating a CP Module . . . . 589Determining the Size of the Dynamic Paging Area . . . . . . . . . . . 590Virtual Machine Considerations . . . . . . . . . . . . . . . . . . 590Chapter 19. Expanded Storage Planning and Administration . . . . . . 591Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 591Expanded Storage Considerations with Shared CMS Minidisks . . . . . . . 592Attaching Expanded Storage to a Virtual Machine . . . . . . . . . . . 592Mapping Expanded Storage . . . . . . . . . . . . . . . . . . . 593Fragmentation . . . . . . . . . . . . . . . . . . . . . . . . 593Discontinuous Expanded Storage . . . . . . . . . . . . . . . . 593Allocating Expanded Storage to CP . . . . . . . . . . . . . . . . . 596Allocating Retained Expanded Storage . . . . . . . . . . . . . . 596Pending Retained Expanded Storage . . . . . . . . . . . . . . . 597Using Expanded Storage as a Minidisk Cache . . . . . . . . . . . . . 597What Devices Can Be Cached . . . . . . . . . . . . . . . . . 600Turning Caching Off . . . . . . . . . . . . . . . . . . . . . 600Planning for and Using Minidisk Caching . . . . . . . . . . . . . . 600Special Considerations for CMS Minidisk Volumes Shared betweenProcessors . . . . . . . . . . . . . . . . . . . . . . . 601Performance Considerations . . . . . . . . . . . . . . . . . 602Chapter 20. Allocating DASD Space . . . . . . . . . . . . . . . . 603Direct Access Storage Requirements . . . . . . . . . . . . . . . . 603CKD Device Geometry . . . . . . . . . . . . . . . . . . . . 603FBA Device Geometry . . . . . . . . . . . . . . . . . . . . . 604Storage Calculations . . . . . . . . . . . . . . . . . . . . . 604CP Module . . . . . . . . . . . . . . . . . . . . . . . . . . 605Warm Start Data . . . . . . . . . . . . . . . . . . . . . . . . 606Example . . . . . . . . . . . . . . . . . . . . . . . . . . 607Checkpoint Data . . . . . . . . . . . . . . . . . . . . . . . . 607Directory Space . . . . . . . . . . . . . . . . . . . . . . . . 608Example . . . . . . . . . . . . . . . . . . . . . . . . . . 609Directory Size Constraints . . . . . . . . . . . . . . . . . . . 610Paging Space . . . . . . . . . . . . . . . . . . . . . . . . . 610Example . . . . . . . . . . . . . . . . . . . . . . . . . . 611Spooling Space . . . . . . . . . . . . . . . . . . . . . . . . 613Allocating Space for CP Abend Dumps . . . . . . . . . . . . . . 614Named Saved System . . . . . . . . . . . . . . . . . . . . . 615Spool Space Example . . . . . . . . . . . . . . . . . . . . . 615Switching Operating Modes for 3390 Devices . . . . . . . . . . . . . 615Mode Switch Procedure . . . . . . . . . . . . . . . . . . . . 616Migration Considerations for the 3390 Model 9 . . . . . . . . . . . . . 617Chapter 21. DASD Sharing . . . . . . . . . . . . . . . . . . . 619Sharing DASD among Multiple Virtual Machines by Using VirtualReserve/Release . . . . . . . . . . . . . . . . . . . . . . . 619When to Use Virtual Reserve/Release . . . . . . . . . . . . . . . 621Sharing DASD without Using Virtual Reserve/Release . . . . . . . . . . 622Sharing DASD Using the CMS Shared File System . . . . . . . . . . . 622© Copyright IBM Corp. 1991, 2004 587

Sharing DASD between One Virtual Machine and Other Systems Using RealReserve/Release . . . . . . . . . . . . . . . . . . . . . . . 622When to Use Real Reserve/Release . . . . . . . . . . . . . . . 624Sharing DASD among Multiple Virtual Machines and Other Systems UsingConcurrent Virtual and Real Reserve/Release . . . . . . . . . . . . 624When to Use Concurrent Virtual and Real Reserve/Release . . . . . . . 626Restrictions for Using Reserve/Release . . . . . . . . . . . . . . . 626Reserve/Release Summary . . . . . . . . . . . . . . . . . . . . 626Sharing DASD using the Multi-Path Lock Facility . . . . . . . . . . . . 627Cached DASD . . . . . . . . . . . . . . . . . . . . . . . . 628Cache Control . . . . . . . . . . . . . . . . . . . . . . . . 628Cache Control at the Subsystem Level . . . . . . . . . . . . . 629Cache Control at the Device Level . . . . . . . . . . . . . . . 629Cache Control at the Extent Level . . . . . . . . . . . . . . . 629Defining a Minidisk on a Cached DASD . . . . . . . . . . . . . . 629Defining a Cached DASD as a Dedicated Device . . . . . . . . . . . 630Using ESS Parallel Access Volumes . . . . . . . . . . . . . . . . 631Using PAV for Workload Balancing . . . . . . . . . . . . . . . . 631Using PAV for DASD Sharing . . . . . . . . . . . . . . . . . . 632z/VM Restrictions on Using PAV . . . . . . . . . . . . . . . . . 633Chapter 22. Defining and Managing SCSI FCP Disks . . . . . . . . . 635Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 635Defining SCSI Devices . . . . . . . . . . . . . . . . . . . . . 637Emulated FBA Disks on SCSI Disks . . . . . . . . . . . . . . . 637Real SCSI Disks . . . . . . . . . . . . . . . . . . . . . . . 638Additional Considerations . . . . . . . . . . . . . . . . . . . . 639588 z/VM: CP Planning and Administration

Chapter 18. Real Storage Planning and AdministrationThis chapter describes:v The real storage requirements for CPv How to define a dynamic paging areaPlanning Real Storage NeedsThe amount of real storage you need depends upon the type of work yourinstallation will be performing. A system might include many virtual machines. All ofthese virtual machines require real storage.For example, you may find that the processor does not have enough storage foryour system to provide acceptable response times. If you find your system’sresponse time to be slow or erratic, you may need to do one of the following:v Add more real storagev Run fewer virtual machines.If you are using the system configuration file to define your system, you do notneed to define the amount of real storage available to CP. CP assumes that it hasall of the storage on the machine available to it. If this assumption is not true, youmust specify the amount of real storage available to CP by specifying STORE as anIPL parameter passed by the Stand-Alone Program Loader (SAPL) to CP.Note: The minimum amount of real storage required for operation of z/VM is 10MB.Your installation can, within limits, change the size of every area of storage exceptthe CP module, which occupies approximately 10 MB. Use the CP commandQUERY FRAMES to display the status of real storage and to determine how realstorage is currently allocated. The z/VM: CP Commands and Utilities Referencebook contains a description of the QUERY FRAMES command.Real and Virtual Storage Requirements for Generating a CP ModuleThe CP module requires approximately 10 MB of real storage. This amount will varyslightly based on the parameters specified on the STORAGE statement and thenumber of devices specified on RDEVICE statements in the system configurationfile. Additional virtual storage in the virtual machine generating the CP module isrequired for CMS, the VMFBLD program, and access to the CMS disks containingthe CP module text decks and related files. A virtual machine size of 40 MB shouldbe sufficient.In order to IPL the system, there must be sufficient available storage to hold thewarmstart area. This storage is returned to general system use once spooling isinitialized. Usually, one cylinder of CKD DASD or 75 4 KB pages of FBA DASD aredefined for the spooling warmstart area. This is easily contained in a small virtualmachine. However, if you define a large warmstart area, the virtual machine sizemust be increased to accommodate it.Other factors affecting storage requirements include the size of the trace tables andthe number of devices defined in the system.© Copyright IBM Corp. 1991, 2004 589

Real Storage Planning and AdministrationDetermining the Size of the Dynamic Paging AreaThe dynamic paging area (DPA) holds the virtual storage of virtual machines andthe storage CP needs for pageable modules, spool buffers, trace tables, virtualdisks in storage, and other CP areas. The storage remaining after you allocate allother areas of storage is used for the DPA. When determining how large a DPA youneed, you should consider your installation’s paging capability. If your system hasenough high performance DASDs or enough cache control units of a size for yoursystem’s paging demands, you may be able to generate a relatively small DPA andstill achieve good performance. If, however, your installation has mostly lowerperformance DASDs you may need a larger DPA.Virtual Machine ConsiderationsAllowing large numbers of virtual machines to have large storage sizes (primaryaddress spaces and/or data spaces) may affect real storage availability:v For each primary address space larger than 32 MB but less than or equal to1024 MB, one real storage frame is allocated for the segment table.v For each nonprimary address space (data space) less than or equal to 1024 MB,one real storage frame is allocated for the segment table.v For each primary or nonprimary address space larger than 1024 MB, twoconsecutive real storage frames are allocated for the segment table.Although CP creates the segment table at the start of the real storage frame, andany storage remaining beyond the end of the segment table may be used for CPfree storage, you should consider the combined effect of giving many users largestorage sizes and/or allowing users to create many data spaces and/or large dataspaces. Considerable real storage may be consumed by the segment tables.590 z/VM: CP Planning and Administration

Chapter 19. Expanded Storage Planning and AdministrationOverviewThe Expanded Storage facility is an optional feature of certain processor models. Itcan be:v Dedicated to CPv Dedicated to one or more virtual machines for use by an operating systemv Partitioned for use between CP and one or more virtual machines.This chapter tells you what Expanded Storage is and how to:v Attach Expanded Storage to a virtual machinev Map Expanded Storagev Handle fragmentation of Expanded Storagev Allocate Expanded Storage to CPv Allocate retained Expanded Storagev Use Expanded Storage as a minidisk cache.Expanded Storage acts as another level of real storage. It allows for the rapidtransfer of 4 KB pages between itself and real storage. As real storage is dividedinto 4 KB page frames, Expanded Storage is divided into 4 KB units called blocks.It is available in increments whose size varies with the model of the processor.You can partition Expanded Storage. Part of it may be attached to one or morevirtual machines. Another part, the CP partition, is used for system paging and thecaching of certain kinds of data. For paging, CP uses blocks available in the pagingportion of the CP partition in preference to DASD slots.To retain some or all of Expanded Storage exclusively for CP use, the class Boperator can enter the RETAIN XSTORE command. The command assigns thespecified amount of storage to the CP partition. The CP partition size limits theamount of Expanded Storage available for virtual machine partitions.All or part of Expanded Storage can be retained for CP’s exclusive use. This CPpartition can occupy multiple discontinuous areas of Expanded Storage. All or partof the remainder can be dedicated to virtual machines.If there is a request for additional Expanded Storage to be retained by CP and notenough contiguous Expanded Storage is available, the request can be satisfied byretaining multiple discontinuous areas of Expanded Storage. If a request to retainExpanded Storage for CP use is for a larger amount than is available because it isin use by one or more virtual machines, CP retains the amount of ExpandedStorage currently available. It also issues a pending request for the remainder. Thepending request is satisfied when enough Expanded Storage is detached from oneor more virtual machines.z/VM treats Expanded Storage as another level of real storage. All paging goes toExpanded Storage if possible. Old pages from Expanded Storage are migrated toDASD when paging use exceeds a high threshold. For the most part, direct pagingto DASD occurs only if Expanded Storage is totally filled and migration cannotmake room in Expanded Storage quickly enough to keep up with the pagingdemand.© Copyright IBM Corp. 1991, 2004 591

Expanded Storage Planning and AdministrationBasically, you can configure Expanded Storage in any manner that meets yourinstallation’s needs. The granularity is in 1 MB sections, and you can attach it to asmany virtual machine guests as you have megabytes of Expanded Storage.In addition, CP uses Expanded Storage as a minidisk cache that shares ExpandedStorage with paging.Expanded Storage Considerations with Shared CMS MinidisksIf you have DASD volumes that contain CMS minidisks that are shared amongdifferent processors, you must take special action before IPLing z/VM. For eachDASD volume that contains CMS minidisks that are physically shared amongprocessors, specify one of the following:v SHARED YES on the RDEVICE TYPE DASD statement in the systemconfiguration filev SHARED YES on the SET RDEVICE TYPE DASD commandThis definition prevents all minidisks on these volumes from being eligible forminidisk caching. If you do not specify YES for the SHARED parameter or operand,a data integrity exposure can exist if any system other than the one that is cachingdata through the minidisk cache has write access to the volume.For more information on minidisk caching, see “Using Expanded Storage as aMinidisk Cache” on page 597. For information on the RDEVICE systemconfiguration file, see “RDEVICE Statement (DASD)” on page 195. For informationon the SET SHARED and SET RDEVICE commands, see the z/VM: CPCommands and Utilities Reference. For more information on the DASD RDEVICEmacroinstruction, see “DASD Types” on page 746.Attaching Expanded Storage to a Virtual MachineYou can use either the XSTORE user directory control statement or the ATTACHXSTORE command to attach Expanded Storage to a virtual machine for its directuse. The difference is that if you use the XSTORE user directory control statement,the area of Expanded Storage specified is automatically attached to the virtualmachine at logon. With the ATTACH XSTORE command, the area is attached whenthe command is entered. For more information on the XSTORE user directorycontrol statement, see “XSTORE Directory Control Statement (General)” on page585.When CP attaches Expanded Storage to a virtual machine, it looks for contiguousExpanded Storage that is not already attached to another virtual machine orassigned as CP-retained Expanded Storage. This search starts from ExpandedStorage block 0.The amount and location of the Expanded Storage that is attached depends on howExpanded Storage is currently allocated. The response from the ATTACH commandindicates the amount that is actually attached. The QUERY XSTORE MAPcommand can be used to determine its location.The term contiguous is emphasized because certain types of fragmentation canoccur that permit CP to attach Expanded Storage that is larger than what would betruly contiguous. See “Fragmentation” on page 593 for more information aboutfragmentation.592 z/VM: CP Planning and Administration

Expanded Storage Planning and AdministrationMapping Expanded StorageFragmentationYou should develop a map of Expanded Storage and determine which virtualmachines should have access to this valuable resource. Any Expanded Storage thatyou attach for CP’s exclusive use (retained) should be at the top of the map(highest block number), and any Expanded Storage attached to virtual machinesshould be drawn from the lowest block numbers. This ordering for the map matchesthe most likely format produced as the output of the QUERY XSTORE MAPcommand.With this map, you can check that Expanded Storage requirements are notover-committed. You can use the class B QUERY XSTORE MAP command todetermine how CP has actually attached Expanded Storage. This should matchyour map for this configuration.Since the amount of Expanded Storage varies from one configuration to another,this map only serves one particular configuration. One map for each configurationmay be useful. See “Attaching Expanded Storage to a Virtual Machine” on page592 for a description of how CP attaches Expanded Storage as users log on withXSTORE user directory control statements or enter ATTACH XSTORE commands.Two types of fragmentation can occur when Expanded Storage is attached to CPand virtual machines:v QUERY XSTORE MAP shows a section of Expanded Storage as N/A (notapplicable). This is caused by the hardware configuration. For example, thesecond and fourth sections of Expanded Storage could be partitioned to the otherside of a multiprocessor.This Expanded Storage is not available for use by CP or any virtual machine.When CP attaches Expanded Storage for a virtual machine, it can cross theseareas to attach the amount requested. The amount of N/A Expanded Storage isnot counted toward satisfying the request.v The portion of Expanded Storage is attached to a virtual machine or is retainedby CP.This is true fragmentation. CP cannot attach Expanded Storage to a virtualmachine that crosses an area already attached to a virtual machine or retainedfor CP.Discontinuous Expanded StorageGenerally, Expanded Storage is not expected to become fragmented. It is assignedwhen the system operator first IPLs the system and logs on critical virtualmachines. In general, this situation remains static.However, if Expanded Storage is attached to virtual machines, detached, andattached again with a different size, fragmentation can occur that the systemoperator may want to correct. By using the QUERY XSTORE MAP command, thesystem operator can keep track of how Expanded Storage is attached anddetermine whether fragmentation exists.If fragmentation does occur, the operator can use the RETAIN XSTORE, ATTACHXSTORE, and DETACH XSTORE commands to rearrange the attachment ofExpanded Storage. By doing this carefully, fragmentation can be reduced oreliminated.Chapter 19. Expanded Storage Planning and Administration 593

Expanded Storage Planning and AdministrationNote: The system operator must be certain that all virtual machines that haveExpanded Storage attached and that will be manipulated by thisrearrangement are not running a guest that would be affected by thedetaching of Expanded Storage. In general, you should do this when theguest is no longer using Expanded Storage, the guest operating system isreset, or the logged-on Expanded Storage is released.The example shown in Figure 30, Figure 31 on page 595, and Figure 32 on page596 shows how a normal attachment can become fragmented and then rearranged.In all cases where a virtual machine owns Expanded Storage, no guest is runningin that virtual machine at the time a detach is done.┌───────────────────────────┐ Top of Expanded Storage│ User D │││├───────────────────────────┤│ User C │││├───────────────────────────┤│││││ User B │││││├───────────────────────────┤│││ User A │││││││└───────────────────────────┘ Block 0Figure 30. Map of Expanded Storage Allocation—No FragmentationIf User C logs off and User X logs on with a request for a smaller amount ofExpanded Storage, a small amount of unattached Expanded Storage exists (seeFigure 31 on page 595, step 1). This by itself is not fragmentation. However, if UserB logs off and User Y logs on with a request for less than User C had but largerthan the previously unattached amount, fragmentation occurs (see Figure 31 onpage 595, step 2). The two discontinuous fragments cannot be joined. If User Qlogs on and requests an amount equal to the sum of the two pieces, User Q’svirtual machine only gets the amount associated with the larger piece (seeFigure 31 on page 595, step 3). QUERY XSTORE or QUERY XSTORE USER alsoshows this fragmentation, since the last response has the total amount that can beattached that is greater than the maximum that can be attached to a single virtualmachine.594 z/VM: CP Planning and Administration

Expanded Storage Planning and AdministrationStep 1 Step 2 Step 3┌───────────────────────┐ ┌────────────────────────┐ ┌────────────────────────┐│ │ │ │ │ ││ User D │ │ User D │ │ User D ││ │ │ │ │ ││ │ │ │ │ │├───────────────────────┤ ├────────────────────────┤ ├────────────────────────┤│ │ │ │ │ ││ Free │ │ Free │ │ Free ││ │ │ │ │ │├───────────────────────┤ ├────────────────────────┤ ├────────────────────────┤│ │ │ │ │ ││ User X │ │ User X │ │ User X ││ │ │ │ │ ││ │ │ │ │ │├───────────────────────┤ ├────────────────────────┤ ├────────────────────────┤│ │ │ │ │ ││ │ │ Free │ │ User Q ││ │ │ │ │ ││ User B │ ├────────────────────────┤ ├────────────────────────┤│ │ │ User Y │ │ User Y ││ │ │ │ │ │├───────────────────────┤ ├────────────────────────┤ ├────────────────────────┤│ User A │ │ User A │ │ User A ││ │ Blk │ │ Blk │ │ Blk└───────────────────────┘ 0 └────────────────────────┘ 0 └────────────────────────┘ 0Figure 31. Map of Expanded Storage Allocation—with FragmentationBy using several commands, this situation can be corrected. First, detach theExpanded Storage associated with User Q. This is the virtual machine that receivedthe wrong amount of Expanded Storage (see Figure 32 on page 596, step 1). Then,detach the Expanded Storage associated with User X. This is between the two freeareas (see Figure 32 on page 596, step 2). This creates a large contiguous portionof Expanded Storage. Now, attach Expanded Storage to User Q and User X withtheir original amounts. The fragmentation is now removed (see Figure 32 on page596, step 3).Chapter 19. Expanded Storage Planning and Administration 595

Expanded Storage Planning and AdministrationStep 1 Step 2 Step 3┌───────────────────────┐ ┌────────────────────────┐ ┌────────────────────────┐│ │ │ │ │ ││ │ │ │ │ ││ User D │ │ User D │ │ User D ││ │ │ │ │ ││ │ │ │ │ │├───────────────────────┤ ├────────────────────────┤ ├────────────────────────┤│ │ │ │ │ ││ Free │ │ │ │ ││ │ │ │ │ │├───────────────────────┤ │ │ │ User Q ││ │ │ │ │ ││ │ │ │ │ ││ User X │ │ Free │ │ ││ │ │ │ ├────────────────────────┤│ │ │ │ │ │├───────────────────────┤ │ │ │ User X ││ │ │ │ │ ││ │ │ │ │ ││ User B │ ├────────────────────────┤ ├────────────────────────┤│ │ │ User Y │ │ User Y ││ │ │ │ │ │├───────────────────────┤ ├────────────────────────┤ ├────────────────────────┤│ User A │ │ User A │ │ User A ││ │ Blk │ │ Blk │ │ Blk└───────────────────────┘ 0 └────────────────────────┘ 0 └────────────────────────┘ 0Figure 32. Map of Expanded Storage Allocation — Fragmentation RemovedThis example is a fairly simple one. The fragmentation might be worse. It could alsocontain some sections that are marked CP(RETAINED). In the cases whereCP(RETAINED) exists, you can enter RETAIN XSTORE NONE to start the process.After you have corrected the Expanded Storage fragmentation, use the RETAINXSTORE command to reinstate the amount to be retained for CP.Allocating Expanded Storage to CPSystem initialization attaches Expanded Storage to CP by default. Use the RETAINXSTORE command to set aside Expanded Storage for the exclusive use of CP.Retained Expanded Storage is not available to be attached to virtual machines.Note: The RETAIN XSTORE command is used to prevent a guest with anXSTORE user directory control statement in its directory entry from loggingon and taking enough Expanded Storage from the system to causeperformance problems. It controls inadvertent operational errors.Allocating Retained Expanded StorageWhen the RETAIN XSTORE command is entered, CP sets aside Expanded Storagefor CP’s exclusive use starting with the highest block number. This corresponds tothe top of the map discussed under “Mapping Expanded Storage” on page 593.If the amount to be retained cannot be found at the highest block numbers, CPtakes any Expanded Storage not assigned to virtual machines. This action couldcause fragmentation. To minimize fragmentation, the system operator should enterRETAIN XSTORE immediately after the system initializes. If the map for the596 z/VM: CP Planning and Administration

Expanded Storage Planning and Administrationconfiguration is followed, the presence of virtual machines logging on at the timeshould not cause a problem. Expanded Storage is attached to the virtual machinesstarting from the lowest block number.Pending Retained Expanded StorageIf not enough Expanded Storage is available to satisfy a RETAIN XSTOREcommand, the remaining amount is designated as pending retained ExpandedStorage. When a virtual machine detaches Expanded Storage, CP uses some or allof the amount detached to fulfill the pending retain. If the operator wants to deletepending retain, the RETAIN XSTORE command should be entered again with theamount given on the command equal to the current amount retained.Note: Since virtual machines can detach Expanded Storage in an unpredictableway, pending retain can also cause fragmentation.Using Expanded Storage as a Minidisk CacheExpanded Storage can also be used as a write-through minidisk cache for CMS orother guests’ data. (Write-through means that anything written to the minidisk isalso reflected in the cache.) This use of Expanded Storage is self-tuning and totallytransparent. It can help eliminate I/O bottlenecks and improve system responsetime. Response time may be improved because many reads become synchronousinstructions and less CP time is spent on I/O related tasks.Real storage can also be used for minidisk caching.Using Expanded Storage as a minidisk cache may also reduce the complexity ofconfiguring I/O and tuning. You may be able to eliminate replication of heavily usedread-only shared minidisks such as the CMS S and Y disks and the tools disks. Youcan limit load balancing to write activity on DASD volumes. You can allow moreDASD per control unit, while maintaining a given response time.Expanded storage is faster than DASD control unit caches. Control unit cachestransfer at channel speeds; Expanded Storage transfers at near central storagespeeds.CP-managed centralized cache has automatic load balancing. There is no need todecide which DASD to cover. It also uses space more efficiently.For cacheable I/O, data integrity is maintained by always updating the cache afteran I/O operation. (This includes I/O error conditions.) Where minidisk caching hasbeen specifically prohibited for an otherwise cacheable interface, cache invalidationmay be used to ensure data integrity.For non-cacheable I/O, CP cannot always determine which records on the minidiskare being referenced. CP causes cache invalidation if, after investigation of thechannel program it determines the data cannot be cached. Data integrity ismaintained by cache invalidation.Blocks are discarded from the cache when the data on the physical volume ischanged in a way that bypasses the cache. The cache is invalidated when:v An I/O error occurs on cacheable I/Ov A noncacheable I/O operation occurs to a writeable minidisk that either:– May have data in the cacheChapter 19. Expanded Storage Planning and Administration 597

Expanded Storage Planning and Administration– Overlaps another minidisk which may have data in the cachev DASD is detached from the systemv The Expanded Storage partition that contains minidisk caching blocks is attachedto a guest virtual machine.Unnecessary cache invalidation decreases performance by reducing the cache hitratio. To avoid problems, see “Planning for and Using Minidisk Caching” on page600.CP Minidisk Cache Enhancements:With the enhancements to the CP minidisk cache feature in Version 5 Release 1the following are potential items to consider when migrating from previous releasesof z/VM or VM/XA SP.v Reconfigure expanded storage as main storage if it is specifically for minidiskcache.Some processors allow a portion of main storage to be configured as expandedstorage. Installations that configure storage as expanded storage in order to useminidisk cache should consider reconfiguring this expanded storage as mainstorage.v Review storage allocation for minidisk cache.Prior to VM/ESA 1.2.2, the amount of expanded storage allocated for minidiskcache could be fixed or bounded (minimum and maximum) with the RETAINXSTORE MDC command. Now the amount of storage, either real or expanded,can be fixed or bounded with the SET MDCACHE command. The RETAINXSTORE MDC command is maintained for compatibility purposes. When theamount of storage allocated for minidisk cache is not a fixed amount, the arbiterfunction of minidisk cache determines how much storage to allocate.The arbiter was completely changed in VM/ESA 1.2.2. This eliminated somelimitations of the previous arbiter. If the arbiter was ineffective for your system inthe past, it may now be acceptable and should be tried. If the size of the minidiskcache was previously fixed or bounded, you will want to either allow the arbiter todynamically determine the minidisk cache size or you will want to alter the valuesin consideration of both real and expanded storage usage.A new method of influencing the arbiter is setting a bias with the SET MDCACHESTORAGE BIAS or SET MDCACHE XSTORE BIAS commands. This can bepreferable to setting a fixed minimum or maximum for systems where pagingand/or minidisk cache size requirements vary significantly over time.v Try letting the minidisk cache size default.For both MDC in real storage and MDC in expanded storage, the default is nocache size restrictions and no biasing (that is, a bias setting of 1.00). Underthese conditions, the real storage arbiter usually strikes a good balance betweenusing real storage for MDC and using it for demand paging. Likewise, theexpanded storage arbiter usually makes a good trade-off between usingexpanded storage for MDC and using it for paging. The default settings shouldbe good for most systems and are at least a good starting point. One potentialexception is when storage is very unconstrained. In that case, bias settings in therange of 0.1 to 0.5 may give better results.v When using expanded storage for minidisk cache, also use some real storage forminidisk cache.In situations where expanded storage is to be used for most minidisk caching, itis better to allow some real storage to also be used for minidisk caching ratherthan setting the real MDC size to 0 or setting it off.598 z/VM: CP Planning and Administration

Expanded Storage Planning and Administrationv Use SET MDCACHE or SET RDEVICE commands instead of SET SHARED toenable minidisk cache on volumes.Prior to z/VM 4.4.0, you could define all DASD volumes as shared volumes in thesystem generation or system configuration file and then enable particularvolumes for minidisk cache with the SET SHARE OFF command. Now you mustexplicitly use the SET MDCACHE RDEV command or the SET RDEVICEcommand with MDC option to enable minidisk cache.v Enable caching for minidisks that were poor candidates in the past.There may be minidisks that were disabled for caching because most of the I/Oto them were writes. It may now be reasonable to enable these minidisksbecause the writes will not cause inserts in the cache and the reads mightbenefit from caching. Some overhead to check for data in the cache whenperforming a write I/O (to maintain integrity) does exist. Therefore, disablingminidisk cache for write-only minidisks would save some system resources.v Disable caching for minidisks that are poor candidates.You may want to revisit and change the devices for which you disabled orenabled minidisk caching. There may be some minidisks that are poorcandidates for minidisk cache, but did not matter in the past since the type of I/Oor format made them ineligible for minidisk cache. With several restrictions beinglifted, (such as the 4 KB block size) it may be worthwhile to revisit theseminidisks and make sure they have minidisk cache disabled. VSE pagingvolumes may be candidates.v Consider using minidisk caching with guest operating systems.Because many of the restrictions formerly associated with minidisk caching havebeen removed, it can now often be used to improve the performance of guestoperating systems.The main benefits of minidisk caching are to reduce the load on the I/Osubsystem and to reduce elapsed time by eliminating read I/Os when therequested records are found in the cache.Minidisk caching uses a fair share concept to prevent any one virtual machinefrom flooding cache storage by inserting large amounts of data. As with serversthat support many users, you should normally use the directory optionNOMDCFS (no minidisk cache fair share) to turn off the minidisk cache fair sharelimit for production guest virtual machines.v Reformat some minidisks to smaller blocksize.Each CMS file consists of at least one DASD record even if the file is very small.The capacity of 4 KB formatted minidisks that consist of mostly small files maybe increased by reformatting them using 2 KB, 1 KB or 512 byte sizes. Prior toVM/ESA 1.2.2, reformatting to a smaller size would have made the minidiskineligible for minidisk caching. Care must be taken, however, because as therecord size gets smaller, the number of available bytes per track is reduced.v Prepare for minidisk caching on devices shared between first and second levelsystems.Prior to z/VM 4.4.0, most second level systems did not use minidisk cachebecause it required expanded storage, which most second level test systems donot have. Now that minidisk cache can use real storage instead of expandedstorage, second level systems benefit. Care should be used for minidisks sharedwith first level systems in order to have all changes reflected to the second levelsystem. For example, a minidisk is cached by a second level system and achange is made to the minidisk by the first level system. The change will not bereflected on the second level system if the data had been in the second levelChapter 19. Expanded Storage Planning and Administration 599

Expanded Storage Planning and Administrationsystem cache. You must purge the cache on the second level system with theSET MDCACHE MDISK FLUSH command and reaccess the minidisk to see thechanges.v Avoid mixing standard format and non-standard format records on the samecylinder.Mixing different format records on the same cylinder makes the minidisk cachefeature less efficient. The minidisk cache is more efficient for standard formatrecords. However, when both formats exist on the same cylinder, CP treats allI/O to that cylinder as non-standard.What Devices Can Be CachedMinidisk caching does not apply to:v DEVNO defined full-pack minidisksv FBA minidisks that are not page-alignedv Virtual disks in storagev Dedicated or attached DASDv Shared DASDv Devices other than DASD.Minidisk caching applies to linked minidisks. This includes:v Normal user minidisksv CMS S and Y disksv Temporary disksv Overlapping minidisksv Minidisks formatted and reserved for use by the *BLOCKIO system service, forexample:– SQL/DS minidisks– Shared file system minidisks.Turning Caching OffBy default, CP caches all eligible minidisks on all volumes unless minidisk cachinghas been turned off. To turn off minidisk caching for the system, enter the commandas follows:set mdcache system offTo turn off minidisk caching for all minidisks on a volume, you can do one of thefollowing:v SET MDCACHE RDEVv Define SHARED YES on the RDEVICE TYPE DASD system configuration filestatement for that volumeTo turn off minidisk caching for an individual minidisk, code the NOMDC option onthe MINIOPT user directory control statement in the CP directory. For moreinformation, see “MINIOPT Directory Control Statement (Device)” on page 524.Planning for and Using Minidisk CachingThe sharing of Expanded Storage between a minidisk cache and paging is doneautomatically. To control the sizes of the minidisk cache portion of ExpandedStorage, use the RETAIN or SET MDCACHE commands to set the minimum andmaximum size of Expanded Storage. The size of the minidisk cache can be fixed by600 z/VM: CP Planning and Administration

Expanded Storage Planning and Administrationsetting the maximum equal to the minimum. Use the QUERY MDCACHE commandto show the sizes. For the format and description of these commands, see thez/VM: CP Commands and Utilities Reference.To display the current size of the minidisk cache and the minimum and maximum ofits possible size, use the QUERY MDCACHE command.To display the rate per second at which information is read and written to theminidisk cache, use the INDICATE LOAD command. This command also displaysthe number of successful cache lookups. The INDICATE command statistics are forboth real and expanded storage MDC use.Attention: If different systems share a minidisk, use the MINIOPT user directorycontrol statement to avoid caching those minidisks. If the minidisk is used inread-only status, it can be shared between two systems. Special attention must bepaid to volumes that will be shared in a CSE complex. See “Sharing DASDVolumes” on page 336 for more detail.Special Considerations for CMS Minidisk Volumes Sharedbetween ProcessorsIf you have DASD volumes that contain CMS minidisks that are shared amongdifferent processors (such as in a CSE complex), you must take action beforeIPLing VM/ESA. This also applies if you are running VM/ESA as V=V guest whenthe guest will be using minidisk caching and the first-level system will be cachingusing minidisk caching.For each DASD volume that contains CMS minidisks and that more than oneprocessor physically shares, specify one of the following:v SHARED YES on the RDEVICE TYPE DASD statement in the systemconfiguration filev SHARED YES on the SET RDEVICE TYPE DASD commandv SHARED=YES on the RDEVICE macroinstruction in the HCPRIO ASSEMBLEfile.This prevents all minidisks on those volumes from being eligible for minidiskcaching. If you do not specify YES for the SHARED parameter or operand, a dataintegrity exposure can exist. The exposure is caused if any system other than theone that is using minidisk caching to cache data has write access to the disk, suchas in a CSE complex.Note, the SET SHARED ON command disables minidisk caching for all minidiskson a real DASD volume. The SET MDC RDEV command disables minidisk cachingon a volume, and the SET MDC MDISK disables caching for a single minidisk.Defining a shared device using either the SET RDEVICE command or theRDEVICE system configuration file statement or macroinstruction, described in theprevious list, is the recommended method for shared volumes. It prevents anycaching of data that might occur before the SET SHARED command can beentered. For example, caching might occur as part of initialization of operator andautologged virtual machines.Notes:1. One possible exception is that if only one processor among the sharingprocessors is writing, and the same processor is the only one trying to cachedata for that volume, for that processor only, minidisk caching may be allowedChapter 19. Expanded Storage Planning and Administration 601

Expanded Storage Planning and Administration(YES need not be specified for the SHARED parameter or operand). For allother sharing processors, YES should be specified for the SHARED parameteror operand.2. The SET SHARED command and either the SET RDEVICE SHARED YEScommand, the RDEVICE SHARED YES system configuration file statement, orthe RDEVICE SHARED=YES macroinstruction can also be used to specifywhether virtual reserve/release CCWs should be translated to realreserve/release CCWs (see Chapter 21, “DASD Sharing,” on page 619).Performance ConsiderationsMinidisk cache should be turned off for minidisks that are only read and written viaMAPMDISK and the corresponding data space. Minidisks which use a combinationof data space access/MAPMDISK and virtual I/O (Diagnose and channel program)should be evaluated on an individual basis to determine if minidisk cache shouldremain enabled.To prevent unnecessary cache invalidation, do the following:v Perform backup with read-only links whenever possible.v Consider restoring minidisks without full-pack writeable access as follows:– Link to the user’s minidisk rather than relocating it within a full-pack minidisk– Define another minidisk to exactly overlap the one being restored.v Consider disabling caching for minidisks that are accessed by both CMS usersrunning on the first-level VM/ESA system and by CMS users running on asecond-level guest where the second-level system has write access.In addition, to improve performance when using minidisk caching, do the following:v Eliminate replicated volumesv Aligned FBA minidisks on page boundariesv Consider moving the following to cached control units:– Minidisks frequently accessed through the noncacheable interfaces– Minidisks shared between first- and second-level systems– Real devices that are physically shared across processorsv Specify NOMDC on the MINIOPT user directory control statement for minidisksnot to be cached. Specifically, do this for write-only minidisks such as those usedfor journaling, logs, and tracking.Minidisk caching is generally self-tuning. You may either need to try some manualtuning (such as the recommendations above) or add additional Expanded or RealStorage if your installation experiences:v A large oscillation in the number of blocks in the cache. (Paging is causing lessExpanded Storage from being used for caching.)v A high I/O activity to DASDs that contain cacheable minidisksv A low minidisk caching hit ratio.602 z/VM: CP Planning and Administration

Chapter 20. Allocating DASD SpaceThis chapter tells you how to calculate disk space for the following CP storageareas:v CP modulev Warm start datav Checkpoint datav User directoryv Paging spacev Spooling space.It also describes switching operating modes for 3390 devices. The 3390 Model 9 isnot recommended for CP system areas and does not support 3380 trackcompatibility mode.Direct Access Storage RequirementsIn the following paragraphs you will find many references to disk space. It isimportant to understand the fundamentals of disk space to avoid confusion whendealing with various DASD types.It is helpful to understand z/VM’s requirements for disk space in general. It is alsohelpful to understand the differences and similarities between z/VM’s view ofCount-Key-Data (CKD) and fixed block architecture (FBA) devices. Examples ofthese devices are:CKD 3380, 3390FBA 9336, emulated 9336 on SCSI diskNote: z/VM may support some DASD types only as an emulation mode on otherDASD. See the list of supported devices in z/VM: General Information.z/VM’s reference to disk space is always done in units called pages. A disk page isa 4096–byte record on disk. This means that z/VM requires that all its disk space(warm start data, directory, and so on) be formatted as 4096-byte records. z/VMalso requires that you identify the use for which specific pages on disk are allocatedto each type of z/VM reference. For example, you must identify pages for paging,for the directory, and for other areas.CKD Device Geometryz/VM views CKD devices by their geometric characteristics (such as number ofcylinders). Each cylinder has a fixed page capacity, meaning that a fixed number of4K records fit on a cylinder. This number varies for each CKD DASD type. z/VMreferences its data by a cylinder number and a page number on that cylinder. Forz/VM space you must format and allocate pages in groups of cylinders.Note: z/VM supports only CKD devices that accept the Extended-Count-Key-Data(ECKD) channel program protocol. Space on these devices is alsoexpressed in units of cylinders. For more efficient disk I/O, an extendedchannel command architecture is used. This architecture is based primarilyon the CKD command set. Therefore the term CKD, as used in this andother z/VM books, really refers to ECKD.© Copyright IBM Corp. 1991, 2004 603

Allocating DASD SpaceLater in this chapter you are asked to figure your particular DASD requirements asa number of records or pages, then convert this number to an equivalent number ofcylinders. This means dividing the page requirements by the number of pages percylinder for particular device types. Allocating space for minidisks on z/VM-ownedECKD volumes is also done in units of cylinders. Use of space within this allocationis also done in units of cylinders by way of the MDISK directory control statement.This is convenient because no conversion is required in this case.FBA Device GeometryFBA devices appear as linear address spaces of 512-byte blocks. The blocks areconsecutively numbered from 0 to n, where n is the highest block number on thevolume. z/VM groups eight consecutive blocks to form a z/VM page and this pagemust begin on a 4K boundary. z/VM then views the volume as a collection of pagesnumbered from 0 to (n-7)/8. For example, blocks 0-7 make up page 0. There is noconcept of cylinder boundaries in this structure.You must allocate space on FBA volumes in units of pages (in contrast to units ofcylinders on CKD volumes). When you figure your disk space requirements as anumber of pages, you can use these numbers directly in system configuration filestatements or in the ICKDSF service program (pages). Page numbers must bemultiplied by 8 to convert them into block numbers used by the MDISK controlstatement. When assigning minidisk space, you must know the available extents ofyour disk in block numbers (see Table 27 on page 605).Note: It is recommended that all FBA minidisks as well as full-pack minidiskvolumes be aligned on page boundaries for optimization of disk space.Otherwise, the resulting residual blocks of disk space might not be formattedand utilized. Additional restrictions apply for SFS file pool minidisks that arenot page-aligned. For more information, see z/VM: CMS File Pool Planning,Administration, and Operation. If the starting block number is a multiple ofeight and the number of blocks is a multiple of eight, then the minidisk isdefined to be on a page boundary.It is helpful to understand how much disk space you need to allocate for CP storageareas. This chapter shows you how to calculate CP storage areas in terms of thenumber of cylinders on the various types of CKD devices and the number of 4 KBpages on FBA devices.StorageCalculationsFor each area of storage, a calculation to determine the number of cylinders or 4KB pages needed is given. You will need to refer to information in the systemconfiguration file for some of the calculations.Table 26. CKD DASD Storage CapacitiesTable 26 lists the storage capacity of various CKD devices. Table 27 on page 605lists the storage capacity of FBA devices.DASD Type Pages per Track Tracks per Cylinder Cylinders per Disk Pages per Cylinder3380Model3380ModelKE10 15 2655 15010 15 1770 150604 z/VM: CP Planning and Administration

Allocating DASD SpaceTable 26. CKD DASD Storage Capacities (continued)DASD Type Pages per Track Tracks per Cylinder Cylinders per Disk Pages per Cylinder338010 15 885 150All othermodels3390-1 12 15 1113 1803390-2 12 15 2226 1803390-3 12 15 3339 1803390-9 12 15 32760¹ 180Note:1Value can be up to the maximum number of cylinders on the disk.Note: One page of CP storage is equivalent to 4096 bytes of contiguous diskspace.|||||||||||||Table 27. FBA DASD Storage CapacitiesDASD Type Number ofBlocksNumber ofAccessPositionsNumber ofBlocks PerAccess Position9336-20 1,672,881 2153 777 111Emulated 9336-20 onSCSINotes:12,147,483,640 1, 2– 777 3Number ofPages PerAccessPositionFBA blocks allocated for CP use must be within the first 64 GB (134,217,728 blocks) of the volume.2Due to CMS file system limitations for status and control information to reside below 16 MB in virtual storage,there is a practical limitation on the size of CMS minidisks. As a minidisk increases in size, or more files reside onthe disk, the amount of virtual storage associated with the disk for CMS file system status and control increasesin storage below 16 MB. The current ECKD DASD limitation is 32767 cylinders for a 3390 disk on an ESS device,or about 22 GB of data. IBM suggests that customers defining FBA SCSI disks for use by CMS set a practicallimit of about 22 GB. If larger disks are defined, they should be limited to contain very few files, or the CMS filesystem may not be able to obtain enough virtual storage below 16 MB to format or access those disks. For moreinformation, see the ACCESS command in the z/VM: CMS Commands and Utilities Reference. The maximumsize for FBA SCSI disks supported for use by CMS or GCS is 381 GB.3These values are simulated for emulated 9336-20 on SCSI and are not directly related to the total number ofblocks allowed on real SCSI hardware.111 3CPModuleThe CP module resides on a CMS-formatted minidisk, usually the parm disk. Youneed to allocate sufficient disk space for the parm disk, which may contain:v System configuration filesv One or more CP modulesv Logo filesv Text decks for CP exitsThe size of the CP module depends on the size of:v IBM-supplied text decksv Customized HCPSYS (system definition) and HCPRIO (real I/O configuration)ASSEMBLE files, if usedChapter 20. Allocating DASD Space 605

Allocating DASD Spacev Other customized text decks included in the CP moduleThe HCPLDR option PAGEB causes the CP module to be greatly larger.The size of the system configuration file does not affect the size of the CP module.Therefore, if you are migrating from a previous VM release in which you used theHCPSYS and HCPRIO files to define your system, IBM strongly recommends thatyou migrate all of the data from your HCPSYS and HCPRIO files to the systemconfiguration file.Table 28 shows the minimum contiguous cylinders/4 KB pages required for the CPmodule when you are not using the HCPSYS and HCPRIO files or the HCPLDRPAGEB option.Table 28. Minimum Space Required for the CP ModuleDevice Number of Cylinders or Pages3380 18 cylinders3390 14 cylindersFBA 2600 pagesWarm Start DataYou specify the number of cylinders or 4 KB pages to allocate to the warm startarea. The number required is based on the maximum number of spool files that canexist at one time, which in turn is determined by the number of users defined in thedirectory and the number of spool files permitted each user, or the number ofcylinders or pages available for spool files. You can specify up to 9 cylinders (CKDDASD) or 2000 4 KB pages (FBA DASD) for the warm start area. The warm startand checkpoint save area cannot begin at cylinder 0 (CKD DASD) or before page16 (FBA DASD).Use the WARMSTART operand of the SYSTEM_RESIDENCE statement in thesystem configuration file to specify the location and size of the area to be used forwarm start data:v The starting location is specified as the cylinder or page number that designatesthe real starting location where the CP warm start information is to be saved. ForCKD device types, this value is a nonzero decimal cylinder number ranging from1 to 65535. For FBA devices, this value is a 4 KB page number beginning withpage 16 or greater.v The maximum size of the warm start area is specified as the number of cylindersor 4 KB pages to be allocated for the warm start information area. For CKDdevices, this must be a number from 1 to 9 that represents cylinders. For FBAdevices, this must be a number from 1 to 2000 that represents 4 KB pages. Youcan use one of the following formulas to calculate the size.If the warm start volume is a CKD DASD, use this formula to calculate number ofcylinders required:maxfilesn = ------------1022 x ppcIf the warm start volume is an FBA DASD, use this formula to calculate number of 4KB pages required:606 z/VM: CP Planning and Administration

Allocating DASD Spacemaxfilesp = ----------1022n is the number of cylinders required for the warm start area.p is the number of 4 KB pages required for the warm start area.maxfilesis the maximum number of spool files that can exist at one time.ppcis a device-dependent value selected from Table 26 on page 604. The valuerepresents the number of 4 KB pages that will fit on one cylinder.ExampleFor example, assume you chose a 3390 DASD as the device to be used for warmstart data. Each 4 KB page of a CKD DASD allows 1022 spool file pointers. A 3390DASD has 180 4 KB pages per cylinder. Therefore each cylinder of a 3390 DASDcan point to 183960 files. So a 9-cylinder warm start area (the maximum) allows asystem-wide maximum of more than 1.6 million (1655640) spool files.For information on how to specify the operands, see “SYSTEM_RESIDENCEStatement” on page 230.CheckpointDataYou specify the number of cylinders or 4 KB pages to allocate the checkpoint area.The number required for the checkpoint area is based on the number of CP-ownedvolumes in the configuration, the number of real spooling devices defined in the realI/O configuration, and the maximum number of users that will be logged on at thesame time. Accounting, EREP, and symptom records are also stored in thecheckpoint area. Normally, these records are retrieved by virtual machines identifiedin the system configuration file. But if those virtual machines are not activelyretrieving the records, they will accumulate and take up space in the checkpointarea.You can specify up to 9 cylinders (CKD DASD) or 2000 4 KB pages (FBA DASD)for the checkpoint area. The warm start and checkpoint save area cannot begin atcylinder 0 (CKD DASD) or before page 16 (FBA DASD).Use the CHECKPOINT operand of the SYSTEM_RESIDENCE statement in thesystem configuration file to specify the location and size of the area to be used forcheckpoint (system restart) data:v The starting location is specified as the cylinder or page number that designatesthe real starting location where the CP warm start information is to be saved. ForCKD devices, this value is a nonzero decimal cylinder number ranging from 1 to65535. For FBA devices, this value is a 4 KB page number beginning with page16 or greater.v The maximum size of the checkpoint area is specified as the number of cylindersor 4 KB pages to be allocated for the checkpoint information area. For CKDdevices, this must be a number from 1 to 9 that represents cylinders. For FBAdevices, this must be a number from 1 to 2000 that represents 4 KB pages. Youcan use one of the following formulas to calculate the size.If the checkpoint volume is a CKD DASD, use this formula to calculate number ofcylinders required:Chapter 20. Allocating DASD Space 607

Allocating DASD Spaceppc+4+((nvl+119)/120)+((nrs+60)/61)+(((nau*10)+39)/40)n = ------------------------------------------------------ppcIf the checkpoint volume is an FBA device, use this formula to calculate number of4 KB pages required:p = 100+((nvl+119)/120)+((nrs+60)/61)+(((nau*10)+39)/40)n is the number of cylinders required for the checkpoint area.p is the number of 4 KB pages required for the checkpoint area.ppcis a device-dependent value selected from Table 26 on page 604. The valuerepresents the number of 4 KB pages that will fit on one cylinder.nvlis the number of CP-owned volumes present in the configuration when thecheckpoint process began.nrsis the number of real spooling devices defined in the real I/O configuration.nauis the number of users active on the system when the checkpoint processbegan.DirectorySpaceTo allocate a disk so that it contains space for the directory, use the Device SupportFacilities program (ICKDSF). See the Device Support Facilities User’s Guide andReference book for additional information. The z/VM user directory cannot beginbefore page 16 on FBA DASD.If you follow the installation procedures in the z/VM: Guide for AutomatedInstallation and Service, you should have enough disk space for two directories.This allows you to build a new directory whenever needed, without reformatting andreallocating space each time. If you wish to reallocate the area on which thedirectory resides, you may use the ICKDSF program, which can be invoked by theCP utility CPFMTXA.A minimum of 4 cylinders (CKD DASD) or 600 pages (FBA DASD) should beallocated to the z/VM directory. This provides for two directories of 2 cylinders (CKDDASD) or 300 pages (FBA DASD) each. The space required for the directorydepends on the number and size of the virtual machine configurations defined. Ifyou have not allocated enough space for your directory, you will receive a messagesaying so.You can estimate the minimum disk space required for your directory by using oneof the following formulas:For CKD DASD, use the formula below (round up any fraction to the next wholenumber) to calculate the minimum number of cylinders required to contain theobject directory:tcbscylinders= -------- * 2ppc608 z/VM: CP Planning and Administration

Allocating DASD SpaceFor FBA DASD, use the formula below to calculate the minimum number of pagesrequired to contain the object directory:pages= tcbs * 2cylindersis the minimum number of cylinders of the CKD DASD type targeted to containthe object directory.To calculate the minimum disk space required for an object directory, use theformula below for total control block space (tcbs) to calculate the number ofpages. Then divide the result (tcbs) by the pages per cylinder value to obtainthe number of cylinders for that type of DASD.pagesis the minimum number of 4 KB pages of FBA DASD targeted to contain theobject directory.To calculate the minimum disk space required for an object directory, use theformula below for tcbs to calculate the number of pages.ppcis the number of pages per cylinder for the device type you intend to use foryour object directory, as listed in Table 26 on page 604.tcbsis an estimate of the total number of pages required for directory control blocks,comprising the index pages, the PROFILE definitions, and the USER definitions.It can be found by using the following formula:tcbs = 12 + ((512 + cpus x 16 + devices x 80 + iucvs x 32) / 4096) x userswherecpusis the number of virtual CPUs defined for a typical virtual machine.devicesis the number of virtual devices defined for a typical virtual machine,including those defined using SPOOL, CONSOLE, DEDICATE, MDISK,SPECIAL, and LINK statements. Include in the count for a user any devicesthat are defined in an imbedded PROFILE directory entry.iucvsis the number of IUCV statements defined for a typical virtual machine.usersis the number of virtual machines in the User Directory, including thosedefined using USER, PROFILE, and POOL statementsExampleFor an installation with 5000 users, the numbers might look like:users = 5000cpus = 1devices = 20iucvs = 2For these values, the number of pages of storage required would be:tcbs = 12 + ((512 + 1 x 16 + 20 x 80 + 2 x 32) / 4096) * 5000tcbs = 12 + 2676 = 2688Chapter 20. Allocating DASD Space 609

Allocating DASD Spacecylinders = 2688/180 x 2 = 15 x 2 = 30pages = 2688 x 2 = 5336For a 3390 at 180 pages per cylinder, the required space would be 30 cylinders.For an FBA device, the required space would be 5376 pages.This is the minimum amount of space to be allocated. You should apply a growthfactor to this amount to accommodate changes and additions to your system. Also,since this is only an approximation, if you make extensive use of directorystatements not mentioned in the explanation of operands in the forumla, you shouldapply a larger growth factor to the result.Directory Size ConstraintsThe constraining factors on the number of users in the directory are as follows:v The maximum size of the source directory that can be handled by the file editor.To maximize the effective size of the source directory, you can do the following:– Minimize the amount of virtual storage CMS is using by accessing as fewdisks as possible. This allows as much virtual storage as possible for thesource directory.– Decrease the average number of records needed to describe a virtualmachine by eliminating comments and by effective use of profiles.– Convert a very large monolithic source directory to cluster form.v Disk space. The object directory must fit on one disk volume. With the size ofdisk supported by CP, this should not be a problem. The other limitations willcome into play before this one is reached.PagingSpaceThe amount of paging space you need to allocate on disk depends on thesecharacteristics of your installation:v The number and size of logged-on virtual machinesv The number and size of data spacesv The work load running in each virtual machine.Use this formula to calculate the number of disk pages you need to allocate forpaging space:pages = (block paging factor) * (total virtual storage)Where:total virtual storage=(maximum number of logged-on users) * (average virtual machine size) +(maximum number of defined data spaces) * (average data space size)Notes:1. Multiplying the total virtual storage by block paging factor (a value from 2through 4) is needed to account for block paging. CP improves real storagemanagement with block paging support. With this feature, CP or a virtualmachine has faster access to disk for paging even without Expanded Storageattached. In block paging, multiple pages of related information move to andfrom disk as a single unit. The block paging feature requires more disk space to610 z/VM: CP Planning and Administration

Allocating DASD Spacetransfer pages at maximum efficiency and speed. Therefore, you should allocatetwo to four times more disk space than the total virtual storage used by loggedon virtual machines and data spaces.2. Number and average size of data spaces refers to data spaces provided by VMdata space support.3. For CKD devices, to calculate the number of cylinders of that device typeneeded, divide the number of disk pages needed for paging space by thenumber of pages per cylinder for that device type, and round up. For FBAdevices to determine the number of blocks needed for paging space, multiplythe number of pages by 8, since there are 8 512-byte blocks in a page.ExampleTable 29 shows the amount of space in cylinders on a 3390 DASD that you need toallocate as paging space based on the number of users and their average virtualmachine size. Table 30 on page 612 shows the amount of space in pages and inblocks on an FBA DASD that you need to allocate as paging space based on thesame factors. Note that:v The number of cylinders or pages shown are the minimums required.v Two is the multiplication factor used for block paging.v The calculations shown do not take into account that storage may be shared byseveral users. You should take this factor into account.To achieve best performance, use multiple DASD volumes. For example, if youneed to allocate 1000 cylinders on a 3390, try allocating 100 cylinders on each of10 different 3390s, or 200 cylinders on each of five different disks. Paging in CP isbased on MLOAD values whereby a device is chosen if its MLOAD value is equalto or less than the system average MLOAD value. MLOAD is the number of queuedpaging requests for a disk volume times the device service time.Table 29. 3390 Cylinders Needed for Paging Space Based on FormulaScenario Number of Cylinders100 users; average virtual machine size 500 KB 139100 users; average virtual machine size 2 MB 569500 users; average virtual machine size 2 MB 2845500 users; average virtual machine size 2 MB; 10 users with 2 data spaces each; averagedata space size 25 MB426710 users; average virtual machine size 16 MB 45510 users; average virtual machine size 32 MB 910Chapter 20. Allocating DASD Space 611

Allocating DASD SpaceTable 29. 3390 Cylinders Needed for Paging Space Based on Formula (continued)Scenario Number of CylindersExamples:1. For example, 2845 cylinders is obtained from the following computation:(2 X [(500 X 2 X 256) + (0 X 0 X 256)]) / 180 = 2845│ │ │ │ │ │ │ │ │multiplier ─────┘ │ │ │ │ │ │ │ │for block users │ │ number of │ │ │ 3390 cylinderspaging │ │ data │ │ ││ │ spaces │ │ pages per cylinder│ │ │ │virtual │ average │machine │ data │size (MB)│ space ││ size (MB) │││└ pages in 1MB ─┘Note: The actual number obtained by the formula is 2844.44. Rounding up to the next whole cylinder gives 2845cylinders.2. The following example shows the calculation for the same installation using VM data space support:(2 X [(500 X 2 X 256) + ((2 X 10) X 25 X 256)]) / 180 = 4267│ │ │ │ │ │ │ │ │ │multiplier ─────┘ │ │ │ │ │ │ │ │ │for block users │ │ number of │ │ │ │ 3390 cylinderspaging │ │ data │ │ │ ││ │ spaces users │ │ pages per cylinder│ │ │ │virtual │ average │machine │ data │size (MB)│ space ││ size (MB) │││└──── pages in 1MB ───┘Note: The actual number obtained by the formula is 4266.67 Rounding up to the next whole cylinder gives 4267cylinders.A properly configured 3390 DASD (see note below) in an ESS 2105-F20 and usedonly for paging can be expected to handle up to 200 pages a second. Thisassumes that there is adequate space defined on the volume to support blockpaging, as described earlier in this chapter. This information can be used toestimate the number of volumes required.Note: “Properly configured” means a volume that is allocated to paging only andwhose control unit is attached to other volumes that contain paging areas,spooling areas, and guest minidisks. Do not mix spooling and paging on thesame volume unless the rates are below 25 pages per second for pagingand spooling together. Temporary disk space should be isolated to its ownvolumes or distributed with minidisks on volumes that do not contain pagingor spooling areas. These recommendations allow VM to use seldom-endingchannel programs to increase the efficiency of its paging I/O. Placing othertypes of data on paging volumes may reduce the effectiveness of thesechannel programs.Table 30. FBA Pages Needed for Paging Space Based on FormulaScenarioFBANumber of Pages Number of Blocks100 users; average virtual machine size 500 KB 25000 200000612 z/VM: CP Planning and Administration

Allocating DASD SpaceTable 30. FBA Pages Needed for Paging Space Based on Formula (continued)ScenarioFBANumber of Pages Number of Blocks100 users; average virtual machine size 2 MB 102400 819200500 users; average virtual machine size 2 MB 512000 4096000500 users; average virtual machine size 2 MB; 10 users with 2data spaces each; average data space size 25 MB768000 614400010 users; average virtual machine size 16 MB 81920 65536010 users; average virtual machine size 32 MB 163840 131720Examples:1. For example, 512000 pages is obtained from the following computation:(2 X [(500 X 2 X 256) + (0 X 0 X 256)]) = 512000 pages│ │ │ │ │ │ │multiplier ─────┘ │ │ │ │ │ │for block users │ │ number of │ │paging │ │ data │ ││ │ spaces │ ││ │ │ │virtual │ average │machine │ data │size (MB)│ space ││ size (MB) │││└─ pages in 1MB ─┘2. The following example shows the calculation for the same installation using VM dataspace support:(2 X [(500 X 2 X 256) + ((2 X 10) X 25 X 256)]) = 768000 pages│ │ │ │ │ │ │ │multiplier ─────┘ │ │ │ │ │ │ │for block users │ │ number of │ │ │paging │ │ data │ │ ││ │ spaces users │ ││ │ │ │virtual │ average │machine │ data │size (MB)│ space ││ size (MB) │││└──── pages in 1MB ───┘SpoolingSpaceSpooling space is space on disk that CP requires to hold spool files on disk. Whenyou allocate spool space, you should take these requirements into consideration:v Normal spooling spacev The space required to write a dumpv The space required for a named saved system (NSS)v The space required for system data files, such as:– Saved segments– UCR data files– Trace data files– Image librariesChapter 20. Allocating DASD Space 613

Allocating DASD Space– NLS files.Allocating Space for CP Abend DumpsCP abend dumps share spooling space with spool files. Thus, dumps can be sentto spool as long as enough spool space overall is available to contain the categoryof dump requested. During system initialization, CP sets aside enough disk spaceto contain a hard abend dump, which changes dynamically as the system operates.A class B user can change the current dump setting with the SET DUMP command.The SET DUMP command also allows the class B user to specify a preferred orderfor multiple disk volumes to be used for allocation of CP abend dump space. Inaddition, the amount of disk space will be determined by the dump option specified,that is, CP or ALL. When the CP option is specified, CP sets aside enough diskspool space for a CP-only real storage dump.During system initialization, enough space should be available for a CP-only dump.Only if the SET DUMP command is entered with the ALL option will enough spoolspace be set aside for the contents of all of real storage, up to 2 GB.Table 31 shows you how much dump space in cylinders (CKD DASD) or 4 KBpages and blocks (FBA DASD) you need to allocate for an entire dump of realstorage, based on how much real storage you have and what type of DASD youuse.Table 31. Amount of Dump Space Based on Real Storage and Type of DASDReal Storage Size 3390 CylindersFBANumber of Pages Number of Blocks4 MB 6 1039 83128 MB 12 2063 1650416 MB 23 4112 3289632 MB 46 8213 6570464 MB 92 16416 131328128 MB 183 32821 262568256 MB 365 65632 525056CP uses dump space to write a dump of real storage if CP abends. Allocating dumpspace is optional. In general, your dump space should be large enough to containan entire dump of real storage.To calculate the approximate amount of storage needed on a disk, use the followingformula:number of pages needed = number of pages of real storage below 2G + xThe x in the formula above represents 9 pages for the dump file information record,1 page for the symptom record, 1 page for the bit map for each 128 MB of realstorage, 1 page for storage key data for every 16 MB, and 3 pages for anadjustment, for a total of 15.This formula applies to relatively small dumps. For larger dumps the x in theformula may have to be increased.614 z/VM: CP Planning and Administration

Named Saved SystemTo save a copy of an operating system running in a virtual machine, space must bereserved on a CP-owned volume for the named saved system. Named savedsystems require one page of spool space for each page saved, plus an additionalinformation page or pages. CP uses the information pages to save the virtualmachine’s register contents, PSW, and storage keys. The number of informationpages required depends on the number of virtual machine pages being saved. Thefollowing formula shows this relationship:information pages = 1 + virtual machine pages / 4096Round up the result of this calculation to the next whole number.Allocating DASD SpaceFor example, to save a 32 MB virtual machine, you need 8195 pages on disk (8192virtual machine pages plus 3 information pages).Spool Space ExampleThe following table shows you how much spooling space in files per pack you needto specify for CKD DASD based on the type of DASD you have and the averagespool file size on your system. Three average spool file sizes are given: small (2KB), medium (50 KB), and large (100 KB).Device Small (2 KB) Medium (50 KB) Large (100 KB)3390-1 100,170 15,411 8,0143390-2 200,340 30,822 16,028*3390-3 300,510 46,233 24,0423390-9 901,530 138,696 72,122* Large work load (100 KB) and using a 3390-22226 X 12 = 26712 X 15 = 400680 / 25 = 16,028 files/pack| | | |Number of Pages/Track Tracks/Cyl. Pages/FileCylindersThe table below shows you how much spooling space in files per pack you need tospecify for FBA DASD based on the type of DASD you have and the work loadrunning on your system. Three work load sizes are given: small (2 KB), medium (50KB), and large (100 KB).Device Small (2 KB) Medium (50 KB) Large (100 KB)9336-20 104,554 16,085** 8,364** Medium work load (50 KB) and using a 9336-201,672,881 / 8 = 209,110 - 2 = 209,108 / 13 = 16,085 files/pack| | | |Number of Blocks/Page Reserved Pages Pages/FileBlocksSwitching Operating Modes for 3390 DevicesAttention: All mode switches require the affected device to be formatted, so youshould move your data off the device before beginning this procedure.To switch operating modes for a 3390 device, you will need to vary the deviceoffline. If the device is defined to z/VM or is to be dynamically sensed, you mayChapter 20. Allocating DASD Space 615

Allocating DASD Spaceneed to perform a SET RDEVICE so that CP recognizes the new device type.Otherwise, the integrity of the control blocks associated with the device isjeopardized.If you have the devices defined in the system configuration file:When the device is defined as a 3380 it is necessary to update the RDEVICEstatement to define the device as a 3390. Defined in this manner, z/VM willrecognize the mode switch when the device is varied online. This should bedone at a convenient time, such that the next IPL of the system will have thenecessary definitions. Although it is not a requirement, for consistency, thedevice type can also be specified as 3390 in the I/O Configuration Dataset(IOCDS).If you are switching from 3380 track compatibility mode to 3390 mode, and thedevice type is not defined as a 3390, z/VM does not allow the device to bevaried back online without first performing a SET RDEVICE to change thedevice type. If the device type is not also changed in the system configurationfile, the device will remain offline and unusable after the next IPL.If the devices are dynamically sensed:No changes are required in the system configuration file. The SET RDEVICEcommand can be used to change the device definition for the current mode ofthe 3390 device. During IPL, the 3390 device will be brought online in its currentmode of operation.Remember that the 3390 Model 9 does not support 3380 track compatibility mode,so do not perform this procedure with this device.Mode Switch ProcedureUse the following procedure for switching 3390 operating modes:616 z/VM: CP Planning and Administration1. Prevent all applications and users from using the device. For example, if thedevice is being used by the system for minidisks, all users must detach thoseminidisks, and the device must be detached from the system. If the device isbeing used by one guest, that guest must detach the device.2. Move the data off the affected device. The procedure of switching modesdestroys the data on the device and changes the track format.If you wish to restore the data to the same device after switching modes, youshould not use service programs that require identical track formats (such asDASD Dump Restore). For information on moving data, see Using IBM 3390Direct Access Storage in a VM Environment, GC26-4575.3. Vary the device offline to all processors that have access to it, except the onefrom which you perform the mode switch.4. Attach the device to the virtual machine of the person who is performing themode switch; typically, this person is the system programmer. The virtualmachine to which the device will be attached must have Class F authority.5. Use the SETMODE parameter of the ICKDSF INSTALL command to change themode. For information about using ICKDSF for this operation, see Using IBM3390 Direct Access Storage in a VM Environment, GC26-4575.6. Reformat the affected device when all mode switches are made, being sure thatyou have moved the data off the device before you begin.You should use ICKDSF for formatting and allocating disks rather thanCPFMTXA, which has been used for those purposes in the past. For informationon using this option, see the Device Support Facilities User’s Guide andReference, GC35-0033.

Allocating DASD SpaceAny CMS minidisks on the device also must be formatted using CMS FORMAT.7. Detach the device from the virtual machine of the person who performed themode switch.8. If the mode switch is:v For a device defined in the system configuration file:– From 3380 track compatibility mode to 3390 mode and the device type isdefined as a 3380, you must redefine the device as a 3390 by first varyingthe device offline and then entering either of the following commands:set rdevice rdev type dasdset rdevice rdev clearThen vary the device back online. You must also change the definition ofthis device in the system configuration file.– From 3380 track compatibility mode to 3390 mode and the device type isdefined as a 3390, vary the device offline and then back online.– From 3390 mode to 3380 track compatibility mode, vary the device offlineand then back online.v For a dynamically sensed device:– From 3380 track compatibility mode to 3390 mode or from 3390 mode to3380 track compatibility mode, you must redefine the device by varyingthe device offline and entering either of the following commands:set rdevice rdev type dasdset rdevice rdev clearThen vary the device back online.For information on reformatting the volume for a particular use (CP and CMSminidisks), and moving CP-owned volumes and CMS minidisks, see the UsingIBM 3390 Direct Access Storage in a VM Environment, GC26-4575.Remember that the device type you use when restoring data is different fromthe one you used to back up the data in Step 2 on page 616.9. After the data is restored, attach the device again to the system or guest andallow applications to continue.Migration Considerations for the 3390 Model 9The z/VM support of 3390 Model 9 will not affect migration, but there are datamigration considerations if you plan to move data from other devices to a 3390Model 9.The 3390 Model 9 is formatted as a CKD device and is supported for formatting byICKDSF and the CPFMTXA utility. The allocation map format on a 3390 Model 9device will be an extent-based allocation map as opposed to the cylinder-basedallocation map currently used for existing CKD DASD. This is because the existing4K cylinder-based allocation record is not large enough to account for the numberof cylinders on a 3390 Model 9 device.Because the DDR command is capable of doing a straight copy from an existing3390 device to a 3390 Model 9 device, this may result in a Model 9 device having acylinder-based allocation map record. The 3390 Model 9 device will still be usableby z/VM, but because of the limitation of the cylinder-based allocation map record,only the first 4K cylinders of the device will be capable of being used.The reverse situation is also possible where a 3390 Model 1, 2 or 3 device couldhave an extent-based allocation map. This, however, will not be allowed by CP. If aChapter 20. Allocating DASD Space 617

Allocating DASD Space3390 contains an extent-based allocation map and an operator attempts to attachthis 3390 Model 1, 2 or 3 as a CP volume, a warning message will be issued.If either type of data movement is performed, the output disk should be reallocatedusing the ICKDSF CPVOLUME ALLOCATE command if the device is intended tobe used as a CP volume. ICKDSF will convert a cylinder-based allocation maprecord on a 3390 Model 9 device into the extent-based allocation record that isnecessary to use the entire device. An extent-based allocation record found on a3390 model 1, 2 or 3 can also be converted by ICKDSF into a cylinder-basedallocation map record.The following coexistence considerations should also be noted:v 3390 Model 9 devices can coexist in the same string with other 3390 devices,but cannot coexist in the same string with other 3380 devices.v 3390 Model 9 B-units (B9C) cannot be intermixed in a string with other models ofthe 3390.618 z/VM: CP Planning and Administration

Chapter 21. DASD SharingUnder z/VM, you can share information on a DASD volume among:v Multiple virtual machinesv One virtual machine and operating systems running on other processorsv Multiple virtual machines and operating systems running on other processors.v Among CMS minidisks on different systems using CSE. For more information onthis, see Chapter 10, “Setting Up Cross System Extensions (CSE),” on page 333.Note that the guest operating system or application must provide the protection byusing reserve/release. CP only grants access to the DASD and handles virtualreserve/release for MDISK and LINK definitions.This chapter tells you how to share DASD under various circumstances:v Among multiple virtual machines by using reserve/releasev Without using virtual reserve/releasev Using the CMS Shared File Systemv Between a virtual machine and other systemsv Among multiple virtual machines and other systems.It also includes sections on the restrictions for using reserve/release, using theMulti-Path Lock Facility (MPLF), using cached DASD as high-speed storagedevices, and using ESS Parallel Access Volumes.Sharing DASD among Multiple Virtual Machines by Using VirtualReserve/ReleaseIf you need to share data among virtual machines running under VM but do notneed to share it with operating systems running on other processors, the followingmethod of sharing DASD gives you the best results for non-CMS guests. Thismethod is called virtual reserve/release.Sharing data between virtual machines involves the use of minidisks. A minidisk is avirtual DASD for a specific virtual machine. This virtual DASD is mapped to anextent of cylinders on a real DASD. CP can manage DASD sharing in full-packminidisks and on smaller minidisks.Note: Virtual reserve/release is also supported for virtual disks in storage, whichare minidisks allocated from system storage rather than mapped to realDASD.To share a minidisk among virtual machines, you must do the following:1. Code the MDISK user directory control statement in the virtual machine’sdirectory entry. For example, the following MDISK user directory controlstatement for a virtual machine (VM1):MDISK 197 3390 001 100 WORKPK MWV VM1PASSv Defines a minidisk at VM1’s 197 virtual device numberv Specifies that this minidisk is to be on the 3390 DASD with the volume IDWORKPKv Specifies that this minidisk starts at cylinder 001 and encompasses 100cylinders. Ensure that no other MDISK user directory control statement is© Copyright IBM Corp. 1991, 2004 619

DASD Sharingdefined to use any of these same cylinders. DASD RESERVE/RELEASE isnot intended to control sharing of overlapping minidisks.v Includes an access mode of MW (multi-write) with a V (indicating that thisminidisk can be shared between virtual machines) and a password ofVM1PASS.2. Code the LINK user directory control statement in another virtual machine’sdirectory. The LINK user directory control statement and the CP LINK commandeach allow virtual machines to access another user’s minidisk. Suppose asecond virtual machine (VM2) has this LINK user directory control statement inits directory:LINK VM1 197 197 MWThis statement links VM2 to VM1’s minidisk. MW indicates that VM2 requestsmulti-write access to the minidisk. (The MW access mode on the MDISK userdirectory control statement permits VM2 to obtain write access to this minidiskat the same time that VM1 has write access to it.)If VM2 does not have this LINK statement in its directory, it can link to VM1’sminidisk with the CP LINK command. For example, entering:link vm1 197 197 mw vm1passwill perform this link. Or you can use the CMS VMLINK command to link andaccess the disk. VMLINK finds a free virtual device number and access modeletter:vmlink vm1 197 (noname pw vm1passWith the LINK and VMLINK commands, VM2 needed to specify the appropriatepassword (VM1PASS in this example) to be granted access. Using minidiskpasswords helps you to protect shared data, because only those users whoknow the correct password can link to the minidisk with the CP LINK commandand the CMS VMLINK command.Note: All DASD that do not respond to a sense ID request must be defined ineither the system configuration file using RDEVICE statements or in theHCPRIO ASSEMBLE file using an RDEVICE macroinstruction. All DASDthat hold minidisks must be attached to SYSTEM, either at systeminitialization by appearing in either the system configuration file usingCP_OWNED or USER_VOLUME_LIST statements or in the HCPSYSASSEMBLE file using a SYSCPVOL or SYSUVOL macroinstruction orlater by issuing the command ATTACH rdev TO SYSTEM.For more information about these system configuration file statements, see“RDEVICE Statement” on page 188, “CP_OWNED Statement” on page 73, and“USER_VOLUME_LIST Statement” on page 255. For more information aboutthese macroinstructions, see Appendix B, “Defining Your System (HCPSYSMacroinstructions),” on page 643 and Appendix C, “Defining I/O Devices UsingHCPRIO,” on page 705.3. Specify that the DASD will not be shared with another operating system. Thedefault setting of the SHARED operand of the RDEVICE system configurationfile statement (SHARED NO) and the RDEVICE macroinstruction(SHARED=NO) takes care of this for you. A NO setting means this volumecannot be shared with an operating system running on another processor. Youcan also use the CP SET SHARED command to accomplish this. For example,if you enter:set shared off for 197the device at real device number 197 cannot be shared with other operatingsystems. However, you should enter SET SHARED OFF only after careful620 z/VM: CP Planning and Administration

DASD Sharingconsideration. See the z/VM: CP Commands and Utilities Reference for moreinformation about the SET SHARED OFF command.Note: This method is for sharing a minidisk between virtual systems on thesame real system—not for sharing with another real system. Therefore,set the SHARED operand to NO (the default). Setting the SHAREDoperand to YES applies only to sharing full-pack minidisks betweenmultiple real systems. Sharing is managed by CP simulation of the guestreserve/release request through the MDISK block. Note that to invokethis support, the access mode must include V (for example, MWV forshared multiwrite mode). For information on sharing a dedicated devicewith another system running native on another processor, see “SharingDASD between One Virtual Machine and Other Systems Using RealReserve/Release” on page 622. For information on sharing a full-packminidisk among multiple virtual systems and other systems runningnative, see “Sharing DASD among Multiple Virtual Machines and OtherSystems Using Concurrent Virtual and Real Reserve/Release” on page624 and “Spool File Directory Statements” on page 341.Figure 33 shows two virtual machines sharing a minidisk defined on a DASDthrough virtual reserve/release.Real MachineVM1VM2VM3SharedminidiskSharedminidiskFigure 33. Virtual Reserve/ReleaseThree virtual machines sharing two different minidisks through virtualreserve/release support and one channel pathWhen to Use Virtual Reserve/ReleaseIn general, you should use virtual reserve/release when you need to share DASDamong virtual machines running under VM but do not need to share the DASD withother systems and the guest operating system is not CMS. If the operating systemChapter 21. DASD Sharing 621

DASD Sharingis CMS, use the Shared File System. Note that the operating system running in avirtual machine must support reserve/release CCWs for you to use virtualreserve/release.Sharing DASD without Using Virtual Reserve/ReleaseIf the guest operating systems do not support reserve/release CCWs, you can stillshare DASD between virtual machines. However, no write protection is providedusing this method. To do this, define a minidisk for one virtual machine and haveother virtual machines link to that minidisk. The process is similar to that describedfor virtual reserve/release with the following exceptions:1. You do not have to specify a V as part of the access mode on the MDISK userdirectory control statement.2. You do not have to be concerned with the SHARED setting.The major difference between this method of sharing DASD and virtualreserve/release is best illustrated by the case where you have included an accessmode of MW (multiple write) on the MDISK definition. With virtual reserve/release,although many virtual machines can obtain write access to the minidisk, only onevirtual machine can write to it at any one time if it uses virtual reserve release. Ifyou do not use virtual reserve/release, two virtual machines can both obtain writeaccess to the minidisk at the same time. To ensure data integrity, you should usevirtual reserve/release when you need to give multiple virtual machines write accessto a minidisk.Note: Sharing DASD without using virtual reserve/release is not recommended.You could read incomplete data or have an abend.The SET WRKALLEG command supports the MVS Sysplex Environment. SETWRKALLEG allows MVS guests running in a single virtual machine to shareminidisks without using reserve and release CCWs. For more information, see theSET command in the z/VM: CP Commands and Utilities Reference.Sharing DASD Using the CMS Shared File SystemThe CMS Shared File System allows users to organize their files into groups calleddirectories and selectively share those files and directories with other users. To dothis, a collection of minidisks is assigned to a single virtual machine called a filepool server machine. The collection of minidisks is called a file pool. A file poolcontains the files for many users, not just one. The file pool server virtual machinemanages all the files in the file pool.For additional information on the Shared File System, see the z/VM: CMS File PoolPlanning, Administration, and Operation book and the z/VM: CMS User’s Guide.Sharing DASD between One Virtual Machine and Other Systems UsingReal Reserve/ReleaseThis method of sharing DASD with other systems, called real reserve/release,involves the use of dedicated devices. A dedicated device is exclusively owned by asingle virtual machine. For example, suppose you want VM1 to have soleownership of the 3390 DASD with volume ID SYSPK. Assume that this 3390 wasdefined (in either the RDEVICE system configuration file statement or622 z/VM: CP Planning and Administration

DASD Sharingmacroinstruction) at real device number 872. The DEDICATE user directory controlstatement gives a virtual machine exclusive use of a device. For example, thestatement:DEDICATE 872 872in VM1’s directory gives VM1 ownership of the device at real device number 872,and defines the DASD at VM1’s 872 virtual device number. (It is generally a goodidea to keep real and virtual device numbers the same.)You can also use the ATTACH command to dedicate a device to a virtual machine.The command:attach 872 to vm1 as 872is equivalent to the previous DEDICATE user directory control statement.Then define DASD that are accessible from more than one processor as shared inthe system configuration file. (Define the DASD as shareable to CP by codingSHARED YES in the system configuration file.) Hardware and software are thenprepared for the sharing environment and reserve/release commands are handledby the control unit.VM1 can now share this dedicated DASD with another system, as shown inFigure 34 on page 624.Chapter 21. DASD Sharing 623

DASD SharingReal Machine 1 Real Machine 2VMVM2VM3VM1Shared diskdevice withfour channel pathsMVS/XAReal Machine 3 Real Machine 4MVS/XAMVS/SPFigure 34. Real Reserve/ReleaseVirtual machine 1 sharing a diskdevice with three operating systemsin three real machines using realreserve/release supportWhen to Use Real Reserve/Releasespot id=urrr xreftext=’When to Use Real Reserve/Release’. In general, you shoulduse real reserve/release when you need to share a DASD among one virtualmachine and other systems. Note, a dedicated DASD cannot be shared amongvirtual machines but can be shared among one virtual machine and other systems.Sharing DASD among Multiple Virtual Machines and Other SystemsUsing Concurrent Virtual and Real Reserve/ReleaseThe third method of sharing DASD, concurrent virtual and real reserve/release,combines virtual reserve/release and real reserve/release. It allows DASD to beshared among multiple virtual machines and operating systems running on otherprocessors. Figure 35 on page 625 shows VM sharing a DASD between two virtualmachines and a native system.624 z/VM: CP Planning and Administration

DASD SharingReal Machine 1Real Machine 2VMVM2VM3VM1Shared diskdevice withfour channelpathsMVS/XAReal Machine 3 Real Machine 4MVS/XAMVS/SPVirtual machines 1 and 2 sharing a diskdevice with three operating systems inthree real machines using concurrent virtualand real reserve/release supportFigure 35. Concurrent Virtual and Real Reserve/ReleaseConcurrent virtual and real reserve/release involves the use of full-pack minidisks. Afull-pack minidisk is a single minidisk allocated on an entire DASD volume. Afull-pack minidisk encompasses all the primary (or addressable) tracks of thevolume. In the example under “Sharing DASD among Multiple Virtual Machines byUsing Virtual Reserve/Release” on page 619, VM1 defined a minidisk on a portionof the volume called WORKPK. You need to do the following to use concurrentvirtual and real reserve/release:1. Define the DASD as a shareable full-pack minidisk. The following MDISK userdirectory control statement defines a full-pack minidisk:MDISK 199 3390 000 END SYSPK MWV FULLP1This statement allocates all addressable cylinders of the 3390 called SYSPK asminidisk space, thus making SYSPK a full-pack minidisk. (This method is thepreferred way of defining a full-pack minidisk because the number of cylindersdoes not need to be known when writing the MDISK statement.) The V at theend of the statement indicates that this DASD can be shared between virtualmachines. To access the DASD, another virtual machine must use the LINKuser directory control statement or the LINK command. The procedure is thesame as described for virtual reserve/release under “Sharing DASD amongMultiple Virtual Machines by Using Virtual Reserve/Release” on page 619.Chapter 21. DASD Sharing 625

DASD Sharing2. Define the DASD as shareable to CP by coding SHARED YES in the systemconfiguration file. As an alternative, you can use the CP SET SHARED ONcommand. For example, if you enter:set shared on for 199CP recognizes the full-pack minidisk at real device number 199 as a sharedDASD.When to Use Concurrent Virtual and Real Reserve/ReleaseIn general, you should use concurrent virtual and real reserve/release when youneed to share DASD among many virtual machines and other systems. Do not usethis method when you need to share DASD only among virtual machines, becausethe CP overhead is much greater than if you use virtual reserve/release.Restrictions for Using Reserve/ReleaseReserve/ReleaseTo use real reserve/release or concurrent virtual and real reserve/release, all of thefollowing must support reserve/release CCWs:v The operating system running under VMv The system with which the guest will be sharing DASDv The shared DASD.Virtual reserve/release must be enabled for any guest virtual machine reserve to beaccepted, even if only one guest is using the device. Virtual reserve/release allowsreserve/release CCWs to be issued by the guest. Real reserve/release allowsCCWs to reach the device. CP simulates reserve/release if virtual reserve/release isenabled and real reserve/release is not. CP issues the reserve/release CCWs ifboth are enabled.Note, concurrent virtual and real reserve/release support should be used only whenDASD must be shared among many virtual machines and operating systems onother real machines. When DASD must be shared only among virtual machines,virtual reserve/release support should be used because it requires much less CPoverhead.SummaryTable 32 summarizes the differences between different settings of SET SHAREDand the V attribute of the MDISK user directory control statement.Table 32. Reserve/Release SummarySET SHARED V Attribute on DescriptionMDISKON No V attribute The minidisk cannot be shared between a virtualmachine guest and a native system. There is novirtual reserve/release.ON V attribute Both real and virtual reserve/release are available.The minidisk can be shared between virtual machineguests and a native system.OFF V attribute Only virtual reserve/release is available; no realreserves are issued. The minidisk cannot be sharedwith a native system.OFF No V attribute No reserve/release support is available at all.626 z/VM: CP Planning and Administration

DASD SharingSharing DASD using the Multi-Path Lock FacilityDASD data can be shared between native systems, between VM guests, orbetween native systems and VM guests through the use of the Multi-Path LockFacility (MPLF) on the D/T3990 model 6 DASD control unit. The MPLF provideslocking serialization for data on the DASD, and the operating systems or programsuse the D/T3990 MPLF channel commands to control the locks. The TransactionProcessing Facility (TPF) is an example of an operating system that can exploit theMPLF.VM allows guests to use the D/T3990 model 6 MPLF for data that resides ondedicated devices or on full-pack minidisks.For dedicated devices, the real MPLF support is authorized by the LKFAC option ofthe directory control statement. Authorizing a guest for LKFAC automaticallyenables all of that guest’s dedicated devices to use the real MPLF. The guest mustthen issue the appropriate MPLF channel programs to exploit the function.For full-pack minidisks, the real MPLF support is also authorized by the LKFACoption of the directory control statement. In addition, the SET LKFACR ONcommand must be issued to enable each full-pack minidisk to use the real MPLF.Again, once the device is enabled, the guest must then issue the appropriate MPLFchannel programs to exploit the function.Unlike dedicated devices where guest authorization enables all dedicated guestdevices, full-pack minidisks are enabled on a device-by-device basis. This allowsone guest to use the real MPLF for some full-pack minidisks while at the same timeusing VM’s simulated MPLF for other full-pack minidisks in the virtual configuration.VM’s simulation of the MPLF can be used to share data between VM guests whenthe real hardware is unavailable. Simulation is available for both full-pack andnon-full-pack minidisks. Simulation is based on the D/T3990 model 3 MPLF RPQ,while real MPLF support is based on the D/T3990 model 6.Like the real MPLF, simulated MPLF requires the user to be authorized by theLKFAC option of the directory OPTION control statement. In addition, the user mustissue the SET LKFAC command to create the simulated MPLF environment. Thenthe guest must issue the appropriate MPLF channel programs to utilize the function.The SET LKFAC command assumes that all full-pack minidisks and all non-full-packminidisks in the configuration are part of the simulated MPLF. However, no action istaken until the first MPLF-related I/O request is issued to a device. At that time, thedevice and the 31 associated device addresses are considered to be ’active’ in thesimulated configuration. For example, I/O to device 191 would cause devices 180through 19F to be part of one simulated partition (simulating the 32 deviceaddresses on a real DASD subsystem).Even with the global nature of simulated MPLF, real MPLF can coexist. Forexample, if device 180 had been enabled for real MPLF (SET LKFACR ON) beforethe simulated MPLF was enabled or ’active’, then the real MPLF would override thesimulation for device 180.Note: Real MPLF and Simulated MPLF are mutually exclusive. It is recommendedthat the choice be made for each device range before the guest is IPL’d. If,after the guest is IPL’d, you decide to change a device from simulated to realor real to simulated, then the change will cause a SYSTEM RESET and theChapter 21. DASD Sharing 627

DASD SharingCachedDASDguest will have to be re-ipl’d. It is also recommended that all the deviceswithin one 32-address range use the same type of MPLF—either all usingreal MPLF, or all using simulated MPLF.Virtual machines can use cached DASD as high-speed storage devices. The termcached DASD refers to a DASD with a control unit that contains a cache. A cacheis a high-performance, random-access, electronic storage device. Frequently usedpages are kept in the cache where the processor can quickly access them withoutgoing to the DASD itself. See the z/VM: General Information book for a list ofsupported cached DASD control units and a description of which DASD can beconnected to them.A cached DASD control unit provides the high-speed cache as a connectionbetween the processor channels and certain DASD. Figure 36 shows a storagecontrol unit logically attached to a string of 3380 DASD.ProcessorStorage ControlStorage directorStorage directorCache3380 DASD stringFigure 36. 3380 Cached DASDI/O to and from the cache is performed electronically. This is faster than normalDASD access, which involves seeking and rotational delays.Note: CP limits the channel command support to the basic device support.Therefore, CP does not support the speed-matching buffer.CacheControlThere are three levels of cache control for combinations of 3880 and 3990 storagecontrols with 3380 and 3390 DASD: the subsystem level, the device level, and theextent level. To enable caching at a given level means to enable a DASD to accept628 z/VM: CP Planning and Administration

DASD SharingCCWs that activate or deactivate caching at that level: the Define Extent CCW forextent-level caching and the Set Subsystem Mode CCW for device- andsubsystem-level caching.Cache control is hierarchical. If subsystem caching is not enabled, then device- andextent-level caching can be enabled for DASD using that storage control, but nocaching can be performed. If device-level caching is not enabled, then extent-levelcaching can be enabled for that DASD, but it cannot be performed.Cache Control at the Subsystem LevelCaching at the subsystem level is controlled with the DASDOPT directory controlstatement, the ATTACH command, and the SET CACHE command.The DASDOPT statement with the SYSCTL operand, the ATTACH command withthe SYSCTL operand, and the SET CACHE command with the SUBSYSTEMoperand enable devices using the storage control to accept CCWs that activate anddeactivate caching at the subsystem level.The SET CACHE SUBSYSTEM command can also turn caching off for devicesusing the storage control.Cache Control at the Device LevelDevice-level caching is controlled with the DASDOPT directory statement, theATTACH command, and the SET CACHE command.The DASDOPT statement with the DEVCTL operand, the ATTACH command withthe DEVCTL operand, and the SET CACHE command with the DEVICE optionenable a device to accept CCWs that activate and deactivate caching for a device.When two users have full-pack minidisks on the same volume, both enabled forcaching, their choices to activate or deactivate caching can conflict. The conflict canbe moderated by using reserve/release (see “Sharing DASD among Multiple VirtualMachines and Other Systems Using Concurrent Virtual and Real Reserve/Release”on page 624).The SET CACHE DEVICE command can also turn off caching that was enabled bythe DASDOPT DEVCTL directory statement or the ATTACH DEVCTL command.Cache Control at the Extent LevelCaching at the extent level is controlled through the MINIOPT directory statement.The MINIOPT CACHE statement enables a device to accept CCWs that activateand deactivate extent-level caching for a device. MINIOPT CACHE is the default.Extent-level caching is not available for full-pack minidisks. MINIOPT NOCACHEturns off extent-level caching. Setting NOTRAN on can invalidate MINIOPT CACHE.Defining a Minidisk on a Cached DASDYou can define a minidisk on a 3390 DASD attached to a 3990 Storage Models 3 or6.The previous sections of this chapter told you how to define a minidisk on DASDother than cached DASD. To define a minidisk on a 3390 DASD attached to astorage control unit (with a cache), you must first define your 3390s by coding anRDEVICE system configuration file statement or macroinstruction. For example, youwould code the RDEVICE system configuration file statement as:RDEVICE 197-19A TYPE DASD SHARED YESChapter 21. DASD Sharing 629

DASD SharingOr, you would code the RDEVICE macroinstruction as:RDEVICE DEVNO=(197,4),DEVTYPE=3390,SHARED=YESBoth of these statements define real devices 197, 198, 199, and 19A.Next, you must decide whether you want to define a full-pack minidisk. Minidisksother than full-packs are discussed first.Non-Full-pack Minidisk: To define a 3390 as a minidisk for a virtual machine, codean MDISK user directory control statement (and, optionally, a MINIOPT userdirectory control statement) with this format:MDISK 198 3390 0001 0500 XARES MWV ALLMINIOPT CACHENotice that not all of the cylinders on this DASD have been allocated; therefore, thisis not a full-pack minidisk. The MINIOPT user directory control statement indicatesthis 3390 DASD has access to the cache of a storage control unit.After you define a minidisk on a cached DASD, other virtual machines can link tothat minidisk in the same way that they would link to a minidisk on a normal DASD.This procedure is explained in “Sharing DASD among Multiple Virtual Machines byUsing Virtual Reserve/Release” on page 619.Full-Pack Minidisk: To define a 3390 Model 3 as a full-pack minidisk, you need inyour virtual machine’s directory entry an MDISK user directory control statementand, optionally, a DASDOPT user directory control statement. For example:MDISK 197 3390 0 END XARES MWV ALLDASDOPT DEVCTLorMDISK 197 3390 0000 3339 XARES MWV ALLDASDOPT DEVCTLBecause all addressable cylinders of this 3390 (Model 3) have been allocated, thisis a full-pack minidisk. The DASDOPT user directory control statement and itsoperands (DEVCTL, SYSCTL, and NOCTL) determine which types of CCWs thedevice can accept. If you do not include a DASDOPT user directory controlstatement after the MDISK user directory control statement, the default is DEVCTL.For more information on the DASDOPT user directory control statement, see“DASDOPT Directory Control Statement (Device)” on page 472.Defining a Cached DASD as a Dedicated DeviceYou can give your virtual machine exclusive use of a cached DASD with theDEDICATE user directory control statement. In your virtual machine’s directory,code a DEDICATE user directory control statement and optionally a DASDOPT userdirectory control statement. To dedicate a cached DASD at real device number 199to virtual device number 199, include these statements in your directory:DEDICATE 199 199DASDOPT SYSCTLIf you do not include the DASDOPT user directory control statement, the default forany 3990 is DEVCTL.630 z/VM: CP Planning and Administration

DASD SharingUsing ESS Parallel Access Volumesz/VM provides support for the Parallel Access Volumes (PAV) feature of the IBMEnterprise Storage Server (ESS). The ESS must be defined to z/VM as 3390 Model2, 3, or 9 DASD on a 3990 Model 3 or 6 Storage Controller. 3380 track-compatibilitymode for the 3390 Model 2 or 3 DASD is also supported. z/VM supports the PAVfeature only for guest use where the device is dedicated (attached) to the guest.The PAV feature allows you to configure base and alias (logical) DASD volumes.Figure 37 illustrates the relationship between base and alias volumes. The basevolume is the real (physical) DASD space. It has a unique subchannel ID. Aliasvolumes (X and Y in this example) are logical volumes that map the physical spaceoccupied by the base. The alias volumes do not have their own space; they are“shadows” of the base. However, each alias volume also has a unique subchannelID. This allows concurrent I/O to a base volume and all of its associated aliasvolumes.Figure 37. Base and Alias Parallel Access VolumesFor z/VM, base volumes are defined in IOCP as UNIT=3990 (or 2105) on theCNTLUNIT statement and UNIT=3390B (or 3380B) on the IODEVICE statement.Alias volumes are defined as UNIT=3990 (or 2105) on the CNTLUNIT statementand UNIT=3390A (or 3380A) on the IODEVICE statement. Each volume (base oralias) can be assigned any available VM real device number. Use the ESSconfiguration console to initially define which volumes are base volumes, whichvolumes are alias volumes, and which alias volumes are associated with eachbase. Use the CP QUERY PAV command to view the current allocation of base andalias volumes.Using PAV for Workload BalancingThe main purpose of the PAV feature is to increase system throughput and reduceI/O bottlenecks by allowing multiple concurrent I/O operations to the same physicalDASD space. This allows the guest to use the PAV feature for workload balancing.GuestVMBase Alias X Alias YFigure 38. Using Parallel Access Volumes for Workload BalancingChapter 21. DASD Sharing 631

DASD SharingFigure 38 on page 631 illustrates the use of PAV for workload balancing. For thisapplication, the base volume and all its associated alias volumes (X and Y in thisexample) are dedicated to the guest with the CP ATTACH command. The virtualdevice numbers and subchannel IDs assigned to the volumes are immaterial. Tomaximize workload performance, the guest can schedule I/O on whichever of thebase and alias volumes seems most appropriate, and can schedule I/O concurrentlyon some or all of the associated volumes.To use PAV in this manner, the guest must contain support for managing andserializing the workload data across the volumes. z/VM acts only as the “pipe”between the guest and the hardware. Once the necessary base and associatedalias volumes are attached to the guest, the guest must manage their use.An example of a guest operating system that contains the necessary support forPAV workload balancing is z/OS. In addition to the workload support, a z/OS guesthas the ability to dynamically move an alias volume from its current base volume toa different base volume if the workload demands it. On z/VM, you can use the CPQUERY PAV command to keep track of the dynamic movement of alias volumesperformed by a z/OS guest.Using PAV for DASD SharingAnother use of the PAV feature is for sharing data across multiple operatingsystems running as guests on z/VM.GuestBGuestAVDISKVM632 z/VM: CP Planning and AdministrationFigure 39. Using Parallel Access Volumes for DASD SharingFigure Figure 39 illustrates the use of PAV for sharing data among multiple guests.In this example, alias X is attached (with the CP ATTACH command) to Guest A.Alias Y is attached to Guest B. Both alias X and alias Y are associated with thesame base volume. The base volume is not attached to either guest in thisexample, but it can also be used for sharing. The virtual disk in storage shown inthe example is linked to both Guest A and Guest B through the z/VM user directory.The linked virtual disk in storage is important because it demonstrates a method forserializing the data that is shared between the two guests. The virtual disk instorage could contain, for example, the VSE lock file. The virtual disk in storagewould not be necessary in a read-only environment. In that case, the alias volumescould be attached to the guests with the R/O option on the ATTACH command. A

DASD Sharingmethod to serialize access to the alias volumes must be devised, becausereserve/release is not supported on alias volumes (the CCWs will be rejected). Byusing a linked virtual disk in storage, reserve/release can be used against the virtualdisk in storage to control access to the alias volumes. Also, free (not attached) baseand alias volumes associated with the volumes being shared must be clear of allwrite activity.It is the sole responsibility of the guests to manage and serialize any datathat is shared using alias volumes. z/VM provides only the “pipe” for dataexchange between the hardware and the guests.z/VM Restrictions on Using PAV1. An alias volume cannot be IPLed.2. An alias volume cannot be attached to the SYSTEM user ID.3. An alias volume cannot be attached to a guest if its associated base volume iscurrently attached to SYSTEM. Alternatively, a base volume cannot be attachedto SYSTEM if any of its associated alias volumes are attached to one or moreguests.4. An alias volume will not come on-line to z/VM without an associated basevolume. Also, a base volume must have at least one associated alias volume forz/VM (for example, the QUERY PAV command) to recognize the device as aParallel Access Volume.5. A base volume cannot be changed or deleted with the SET RDEVICE, DELETERDEVICE, DELETE DEVICE, or MODIFY DEVICE command unless allassociated alias volumes have been deleted with the DELETE RDEVICEcommand.Chapter 21. DASD Sharing 633

DASD Sharing634 z/VM: CP Planning and Administration

Chapter 22. Defining and Managing SCSI FCP DisksOverviewz/VM supports SCSI FCP disk logical units (SCSI disks) for both system and guestuse. SCSI disks can be used directly by a guest operating system when an FCPsubchannel is dedicated to a guest. Such a guest must contain its own SCSI devicedriver – Linux on zSeries is one such guest.SCSI disks can also be used as emulated 9336 model 20 fixed-block-architecture(FBA) disks. CMS and CP rely almost exclusively on this emulated-FBA support fortheir SCSI usage. Specifically, this usage includes system paging, spooling,directory services, minidisks, and all other system functions and programmingservices that support FBA disks. Guests that support FBA disks (such as CMS,GCS, RSCS, Linux, and VSE) also can use SCSI disks through the emulated-FBAsupport, without requiring any specific SCSI support in the guests.||||||||||||||||z/VM supports emulated FBA disks and their underlying SCSI disks up to 1 terabyteminus 1 page (2,147,483,640 512-byte blocks) in size, without regard to thecapacity of real 9336 disks. Directory, paging, and spooling allocations, however,must reside within the first 64 GB (16,777,216 blocks) of a CP-formatted volume.Other types of CP allocations (TDSK, PERM, and PARM) may exist beyond the first64 GB.Note: Due to CMS file system limitations for status and control information toreside below 16 MB in virtual storage, there is a practical limitation on thesize of CMS minidisks. As a minidisk increases in size, or more files resideon the disk, the amount of virtual storage associated with the disk for CMSfile system status and control increases in storage below 16 MB. The currentECKD DASD limitation is 32767 cylinders for a 3390 disk on an ESS device,or about 22 GB of data. IBM suggests that customers defining FBA SCSIdisks for use by CMS set a practical limit of about 22 GB. If larger disks aredefined, they should be limited to contain very few files, or the CMS filesystem may not be able to obtain enough virtual storage below 16 MB toformat or access those disks. For more information, see the ACCESScommand in the z/VM: CMS Commands and Utilities Reference. Themaximum size for FBA SCSI disks supported for use by CMS or GCS is 381GB.An emulated FBA disk requires the following elements within its configurationdefinition:FCP device numberA real device number for a subchannel associated with an FCP channel,providing access to the fibre-channel fabric.Target worldwide port name (WWPN)The unique worldwide port name associated with a target port on a SCSIcontroller.Logical unit number (LUN)The number of a specific logical unit (i.e. logical device) associated with thetarget port.Refer to Figure 40 on page 636 for an illustration of these required elements.© Copyright IBM Corp. 1991, 2004 635

Defining and Managing SCSI FCP Disksz/VMLPARFCPSubchannel112FCPSubchannel2FCPChannelStorage Area Network(Fibre-Channel Fabric)1WWPNWWPN2StorageSubsystem12LUN 1LUN 2z/VM Configuration ElementFigure 40. Required Elements for SCSI FCP definitionFigure 41 on page 637 illustrates the overall system architecture related to z/VM’sSCSI support. The figure shows how channel programs for emulated FBA disks areprocessed through an emulation layer and a SCSI driver into the fibre-channelfabric. The figure also shows how guests with their own SCSI support can use adedicated FCP subchannel to access the fabric directly. Note that the elementsdescribed above in Figure 40 are contained in the “FCP Channel and Storage AreaNetwork” portions of Figure 41 on page 637.636 z/VM: CP Planning and Administration

Defining and Managing SCSI FCP DisksLinuxECKDz/OSECKDLinux CMS Linux z/VMFBA FBA SCSI SCSICPCCW TranslationI/O SchedulerFBA EmulationSCSI Driver StackDedicatedSubchannelChannelsFCPChannelESCON/FICONStorage Area Network(Fibre-Channel Fabric)Figure 41. SCSI System ArchitectureDefining SCSI DevicesEmulated FBA Disks on SCSI DisksA SCSI device is defined to the z/VM system by specifying an EDEVICE statementin the system configuration file (see z/VM: CP Planning and Administration), byissuing a CP SET EDEVICE command (see z/VM: CP Commands and UtilitiesReference), or by using z/VM’s HCM and HCD support (see z/OS and z/VM:Hardware Configuration Manager User’s Guide and z/VM: I/O Configuration). TheEDEVICE statement, SET EDEVICE command, and the HCM and HCD programsall provide the parameters to identify the SCSI device (FCP device number, targetWWPN, and LUN) to CP. The emulated FBA disk is assigned a real device numberChapter 22. Defining and Managing SCSI FCP Disks 637

Defining and Managing SCSI FCP Disksand becomes associated with a SCSI disk through an FCP device, which also hasa real device number. The device number of an emulated FBA disk must not conflictwith the device number of any real device in the z/VM system. That is, all emulatedFBA disks and all real devices must have unique real device numbers, even thoughthe emulated FBA disks are not real devices.When defining emulated FBA disks to represent SCSI disks, there must be aone-to-one relationship between each FBA disk and its underlying SCSI disk. A pathto a specific SCSI disk comprises the three elements described in “Overview” onpage 635: the FCP device number, target WWPN, and LUN. You can definemultiple paths to the SCSI disk associated with an emulated FBA disk – these pathsshould be routed through different network components to achieve the greatestavailability for the disk. In other words, the different paths must use different FCPchannels, the channels should be connected to different switches, and the pathsshould end at different target ports of the SCSI controller. You might want to keepthe paths completely separate by means of appropriate zoning within your fabric.All paths defined for an emulated FBA disk should represent physical paths throughthe fabric to the same real SCSI disk. If you define multiple paths for an emulatedFBA disk but the paths go to different SCSI disks, or if you define more than oneemulated FBA disk with the same underlying real SCSI disk, or if you definemultiple paths to the same SCSI disk using the same FCP channel, thenunpredictable results and/or data-integrity problems could occur.Once the emulated FBA disk is defined, it is managed on z/VM like a real 9336FBA disk. CP commands such as VARY, ATTACH, and QUERY execute as if theemulated disk were a real FBA disk. This also applies to user-directory andsystem-configuration-file statements.The following commands can be used to manage emulated FBA disks:v SET EDEVICE, to create, modify, or clear an emulated-device definitionv DELETE EDEVICE, to delete an emulated-device definitionv QUERY EDEVICE, to query an emulated-device definition.See the z/VM: CP Commands and Utilities Reference for more information on thesecommands.Note: The SET EDEVICE and DELETE EDEVICE commands are not allowedwhen HCM and HCD are controlling z/VM’s software configuration.Real SCSI DisksThe following commands can be used to manage an FCP device dedicated to aguest for direct access to SCSI disks through a SCSI device driver:vvATTACHDETACHv QUERY FCPv SET LOADDEVv QUERY LOADDEVSee the z/VM: CP Commands and Utilities Reference for more information on thesecommands.638 z/VM: CP Planning and Administration

Defining and Managing SCSI FCP DisksAdditional ConsiderationsThe following are restrictions for emulated SCSI devices:v For CP volumes (formatted with CPFMTXA), paging, spooling, and directoryallocations must not be allocated above page 16,777,216 (representing 64 GB ofdisk storage) on the emulated FBA disk.v As with all FBA minidisks, Reserve and Release CCW commands issued to anemulated FBA disk are supported only among guests within the same z/VMsystem image. If a guest operating system has access to either a dedicated FBAdisk or to an emulated FBA full-pack minidisk that has been defined as sharedamong multiple z/VM images, then Reserve and Release CCW commands willbe rejected.v A single FCP channel can be shared by multiple logical partitions and multiplevirtual machines, but the operating systems in those logical partitions and virtualmachines must not attempt to share a real SCSI device (as specified by aWWPN and LUN pair). All such operating systems will appear to the SCSIcontroller as being the same host system (or SCSI initiator), potentially leading toproblems with concurrent-write access to the disk and with error-recoveryprocedures. A real SCSI device can be shared (if it makes sense for theparticular device) if each operating system has its own path through separateFCP channels to the SCSI device.v IBM strongly recommends that you never assign different logical unit numbers(LUNs) to the same logical device within a SCSI controller. Otherwise, sharedaccess to a device may happen without being detected, and unpredictable resultscan occur.Chapter 22. Defining and Managing SCSI FCP Disks 639


Appendix A. Sample Utility ProgramsThis appendix describes a sample (unsupported) utility program, DRAWLOGO,which is supplied with z/VM. A sample XEDIT macro, X$DRWL$X, which is used byDRAWLOGO, is also supplied. The DRAWLOGO sample program is shipped with afile type of SAMPEXEC. The X$DRWL$X sample XEDIT macro has a file type ofSAMPXEDI. By default these files are loaded onto the MAINT 2C2 disk.To use the DRAWLOGO utility, you must change its file type from SAMPEXEC toEXEC and change the file type of X$DRWL$X from SAMPXEDI to XEDIT.© Copyright IBM Corp. 1991, 2004 641

DRAWLOGODRAWLOGO►► DRAWLOGO fnLOGOftAfm►◄PurposeUse DRAWLOGO to create logo screens for your z/VM system. DRAWLOGO letsyou edit the text of a logo file and modify the 3270 screen attributes in a logo file.For information on how to use this utility, see the “Creating Logo Screens” on page282.OperandsUsageReturnNotesCodesfn is the file name of the logo file.ft is the file type of the logo file. The default file type is LOGO.fm is the file mode of the logo file. The default file mode is A.1. When you enter DRAWLOGO, you are placed in an XEDIT session. If theDRAWLOGO utility does not recognize the type of logo (online message, bodyof logo, input area, or printer separator page), DRAWLOGO prompts you for thetype of logo.2. To put the new logo configuration file into production, use the CP REFRESHcommand. See the z/VM: CP Commands and Utilities Reference.3. DRAWLOGO invokes the X$DRWL$X XEDIT macro, which must be available.In addition to the return code listed, DRAWLOGO may return a return code from theCMS LISTFILE and CMS XEDIT commands. See the z/VM: CMS Commands andUtilities Reference for a list of return codes that the CMS LISTFILE and CMSXEDIT commands generate.CodeMeaning4 No minidisk accessed in R/W mode642 z/VM: CP Planning and Administration

Appendix B. Defining Your System (HCPSYSMacroinstructions)This appendix describes how to code the system control file, HCPSYS ASSEMBLE,and describes each of the HCPSYS macroinstructions, including the purpose,syntax, and examples, and how to use them.If you do not define your system using a system configuration file, you must codethe system control file, HCPSYS ASSEMBLE. You can code in the HCPSYSASSEMBLE file any of the macroinstructions listed in Table 33. You must code theones listed as Required; the others are optional. Table 33 shows you whereinformation on each macroinstruction can be found, and whether it is required oroptional, and gives a brief description of each macroinstruction. Although themacroinstructions are in alphabetic order, this is not the order in which you wouldcode them in HCPSYS ASSEMBLE. See “Coding HCPSYS ASSEMBLE” on page644 for the order in which the macroinstructions must appear in the file.Table 33. HCPSYS MacroinstructionsMacroCSELDEV(page 646)CSELVOLEXCLUDE(page 649)CSELVOLINCLUDE(page 650)CSESYS(page 653)CSETRACE(page 658)CSEUSER(page 659)SYSACNT(page 661)SYSADDIN(page 663)SYSCPVOL(page 664)RequiredorOptionalFunctionOptional Changes the defaults for the CSE tracklocation and format for particular devicetypes.Optional Defines the DASD volumes to be excludedfrom the cross system link operation.Optional Defines the DASD volumes to be included inthe cross system link operation.Optional Describes the topography of a CSEcomplex.Optional Establishes the number of pages of CPstorage allocated for the CSE trace tables.Optional Defines virtual machines that will notparticipate in cross system spooling andcross system message and querycommands.Optional Specifies the user IDs of up to two virtualmachines for which the CP accountingsystem service (*ACCOUNT) is toaccumulate records.Optional Specifies a list of installation-added entrypoints in CP which are to be called duringsystem initialization.Required Defines and generates a list of CP-ownedDASD volumes. (CP-owned DASD volumesinclude the CP system residence volumeand those DASD volumes that contain realsystem paging, spooling, dump, directory,and temporary disk space.)Can Be Replaced bySystem ConfigurationFile StatementXLINK_DEVICE_DEFAULTSXLINK_VOLUME_EXCLUDEXLINK_VOLUME_INCLUDEXLINK_SYSTEM_EXCLUDEXLINK_SYSTEM_INCLUDEXSPOOL_SYSTEMXSPOOL_TRACEXSPOOL_XLIST_INPUTXSPOOL_XLIST_OUTPUTSYSTEM_USERIDSCP_ADDON_INITIALIZE_ROUTINESCP_OWNED© Copyright IBM Corp. 1991, 2004 643

Defining Your SystemTable 33. HCPSYS Macroinstructions (continued)MacroSYSDUMP(page 667)SYSEND(page 668)SYSEREP(page 669)SYSEXCL(page 671)SYSFCN(page673)SYSFORM(page 675)SYSID(page 677)SYSINCL(page 680)SYSJRL(page 682)SYSMAXU(page 686)SYSOPR(page 687)SYSOPTS(page 689)SYSPCLAS(page 691)SYSRES(page 693)SYSSTORE(page 697)SYSSYMP(page 699)SYSTIME(page 701)SYSUVOL(page 703)RequiredorOptionalFunctionOptional Defines the user ID of the virtual machinethat receives system dump files.Can Be Replaced bySystem ConfigurationFile StatementSYSTEM_USERIDSRequired Ends the HCPSYS ASSEMBLE file. Not ApplicableOptional Specifies the user IDs of up to two virtualmachines for which the *LOGREC systemservice is to accumulate EREP records.Optional Defines the volumes that are to be excludedfrom the user volume list.Optional Contains the privilege classes authorized toperform internal CP functions that arecontrolled by privilege class.Optional Creates a list of user form names and theircorresponding operator form numbers.Optional Defines a system identifier for the processoron which you run VM/ESA.Optional Defines user volumes by means of a genericvolume identifier.Optional Specifies the inclusion of the journaling orpassword suppression facility.SYSTEM_USERIDSUSER_VOLUME_EXCLUDEPRIV_CLASSESFORM_DEFAULTUSERFORMSYSTEM_IDENTIFIERSYSTEM_IDENTIFIER_DEFAULTUSER_VOLUME_INCLUDEFEATURESJOURNALINGOptional Specifies the user logon limit. FEATURESRequired Defines the user ID of the primary systemoperator.SYSTEM_USERIDSOptional Sets CP initialization options. Not ApplicableOptional Specifies classification titles for specificclasses of printed output.Required Describes the layout of the CP systemresidence disk.PRINTER_TITLERequired Defines your real storage configuration. STORAGEOptional Specifies the user IDs of up to two virtualmachines for which the *SYMPTOM systemservice is to accumulate symptom records.Required Specifies information required to set thehardware time-of-day (TOD) clock.Optional Generates a list of DASD that containminidisks for users.FEATURESSYSTEM_RESIDENCESYSTEM_USERIDSTIMEZONE_BOUNDARYTIMEZONE_DEFINITIONUSER_VOLUME_LISTCoding HCPSYS ASSEMBLEThis appendix contains a section for each HCPSYS macroinstruction. Each sectiondescribes the function, syntax, operands (required and optional), and codingexamples for the macroinstruction. Some rules you must follow when you code theHCPSYS ASSEMBLE file are:644 z/VM: CP Planning and Administration

Defining Your Systemv SYSCPVOL, SYSOPR, SYSRES, SYSSTORE, and SYSTIME are required andmust be the first macroinstructions in HCPSYS ASSEMBLE. Except for being firstin the file, they do not have to appear in any order.v The SYSEND macroinstruction must be the last instruction in the HCPSYSASSEMBLE file.v The optional macroinstructions must appear after SYSCPVOL, SYSOPR,SYSRES, SYSSTORE, and SYSTIME, and before SYSEND. Except for this ruleand the following rule, the optional macroinstructions can appear in any order.v All CSExxxx macroinstructions must appear after all SYSxxxx macroinstructionsand before the SYSEND macroinstruction.v Do not code START, CSECT, or END assembler instructions—themacroinstruction expansions generate these instructions. If you do code theseinstructions, MNOTEs are generated.v You may code labels on the macroinstructions to identify them. Themacroinstruction expansions ignore the labels.Appendix B. Defining Your System (HCPSYS Macroinstructions) 645

CSELDEVCSELDEV (Optional)►►labelCSELDEVDEVTYPE=devtype,CLASS=n(1),CYL=nnnnn,TRK=nn►►,RECL=nnnnn,RECS=nn►◄Notes:1 Although this macro lets you change the definitions of CYL, TRK, RECL, and RECS, it is notrecommended. The following parameters can be specified in any order.PurposeCode the CSELDEV macroinstruction to change the defaults for the CSE tracklocation format for particular device types. You may specify as many CSELDEVmacros as you need. If CSELDEV macros are coded, they must appear after theCSESYS macro and before the SYSEND macro.See Usage Note 5 on page 648 for a warning about changing the defaults for thismacro.ParametersDEVTYPE=indicates that a device type is to be changed.devtypespecifies the type of DASDs that are to have their default values changed.CLASS=nwhenever DEVTYPE=device is specified, n defines the cylinder size group towhich the particular device being described belongs.When DEVTYPE=3380 is specified, n should have the following values (thedefault value is 3):CLASS Cylinders0 17701 17702 17703 2655When DEVTYPE=3390 is specified, n should have the following values:CLASS Cylinders1 11132 22263 33399 10017¹¹ Value can be up to the maximum number of cylinders on the DASD.646 z/VM: CP Planning and Administration

CSELDEVWhen DEVTYPE=9345 is specified, n should have the following values:CLASS Cylinders1 14402 2156UsageNotesIt is always correct to specify a class value which represents a number ofcylinders that is higher than the actual number of cylinders on the device or totake the default.CYL=nnnnndefines the cylinder where the CSE track is located for every DASD defined asdevtype within the above syntax diagram. The value of nnnnn should be from 0to the maximum cylinder on the volume. The default is 0. See Usage Note 5 onpage 648.TRK=nndefines the track on which the CSE track is located for every CKD DASDdefined as devtype within the above syntax diagram. The variable nn should bein the range of 0 to 64 but cannot be 0 if CYL=0. The default is 1. See UsageNote 5 on page 648.For ECKD capable CKD devices multiple tracks are used. The number of tracksused for ECKD capable CKD devices depends on the number of cylinders onthe volume. The value specified in TRK=nn is not used for an ECKD capableCKD device.RECL=nnnnndefines the number of cylinders made available for CSE use. This value shouldbe at least equal to the number of cylinders on the volume. If nnnnn is smallerthan the number of cylinders on the volume links to minidisks starting on acylinder with a number higher than nnnnn are denied. The value of nnnnnshould be in the range of 203 to the maximum cylinder on the volume. Table 34on page 652 shows the map record defaults for each device type. See UsageNote 5 on page 648.For CKD devices nnnnn also defines the record length of the map records. Onthese devices one byte in the map record corresponds to one cylinder. Allcylinders are mapped in one physical record per system. On ECKD-capableCKD devices there may be several physical records per system. One byte inthe map record corresponds to two cylinders. Each physical record is 256 bytesand maps 512 cylinders. The number of physical records needed depends onthe number of cylinders made available to CSE. See Usage Note 5 on page648.RECS=nndefines the number of map records on the CSE track. You should use as manyrecords as will fit on one track. Table 34 on page 652 shows the map recorddefaults for each device type. See Usage Note 5 on page 648.1. As many CSELDEV macros as are needed may be specified.2. The CYL, TRK, RECL, and RECS keywords allow you to specify CSE trackvalues that are different from the default values associated with the device type.This is not recommended unless there is a valid reason for doing so.3. If the CSELDEV CLASS operand is not coded for 3380 devices, CSE uses avalue of 2655 cylinders for all type K 3380 devices and 1770 for non-type Kdevices.Appendix B. Defining Your System (HCPSYS Macroinstructions) 647

CSELDEV4. The default parameters for model K devices are those associated with 3380CLASS=3, which are 2655 cylinders and 12 map records. If you want to makeall 3380s use the same parameters as model Ks, add the three followingCSELDEV macros to each HCPSYS ASSEMBLE file:CSELDEVCSELDEVCSELDEVDEVTYPE=3380,CLASS=0,RECL=2655,RECS=8DEVTYPE=3380,CLASS=1,RECL=2655,RECS=8DEVTYPE=3380,CLASS=2,RECL=2655,RECS=85. Although the CSELDEV macro lets you change the definitions of cylinder, track,record length, and map records for the CSE track, it is not recommended. Thislets you provide link support for new devices with new geometries, should thatbecome necessary in the future.Attention: Current upper limits may exceed capacities of present devices andcause errors when attempting to access beyond a particular device limit.Therefore, any change of defaults should be done with caution.MigrationAidsYou can achieve the function of the CSELDEV macroinstruction by using theXLINK_DEVICE_DEFAULTS statement in a system configuration file. See“XLINK_DEVICE_DEFAULTS Statement” on page 259.648 z/VM: CP Planning and Administration

CSELVOL EXCLUDECSELVOL EXCLUDE (Optional),►►labelCSELVOLEXCLUDE=( ▼ volid ) ►◄PurposeParametersCode the CSELVOL EXCLUDE macroinstruction to define DASD volumes to beexcluded from the cross system link operation. You may enter as many CSELVOLEXCLUDE macros as you need. If CSELVOL EXCLUDE macros are coded, theymust appear after the CSESYS macro and before the SYSEND macro. They shouldbe identical with the CSELVOL EXCLUDE macros for the other systems you aregenerating. If you omit the CSELVOL EXCLUDE macro, the default excludes allvolumes residing on the system that are not specified in the CSELVOL INCLUDEmacro.EXCLUDEindicates that the volumes specified as volid are not to be shared through crosssystem link. These volumes, if mounted and shared among systems, have noextended link protection.Note: If CSELVOL INCLUDE or EXCLUDE is not specified, all DASD volumesare included in cross system link.volidspecifies the 1- to 6-character volume identifier of a volume to be excluded fromsharing by cross system link. You can use generic volume IDs. A genericvolume identifier is a 1- to 6-character pattern that can use asterisks (*) in placeof any number of characters and percent signs (%) in place of exactly onecharacter. For example, CSELVOL EXCLUDE=(HC%P*) excludes all volumes whichbegin with HC and have a P as their fourth character.MigrationAidsYou can achieve the function of the CSELVOL EXCLUDE macroinstruction by usingthe XLINK_VOLUME_EXCLUDE statement in a system configuration file. See“XLINK_VOLUME_EXCLUDE Statement” on page 266.Appendix B. Defining Your System (HCPSYS Macroinstructions) 649

CSELVOL INCLUDECSELVOL INCLUDE (Optional)►►labelCSELVOLINCLUDE=( ▼ volid ),(1),CYL=0,CYL=nnnnn,TRK=1,TRK=nn,RECL=nnnnn►►,RECS=nn►◄Notes:1 Although this macro lets you change the definitions of CYL, TRK, RECL, and RECS, it is notrecommended. The following parameters may be specified in any order.PurposeCode the CSELVOL INCLUDE macroinstruction to define the DASD volumes to beincluded in the cross system link operation. You may enter as many CSELVOLINCLUDE macros as you need. If CSELVOL INCLUDE macros are coded, theymust appear after the CSESYS macro and before the SYSEND macro. They shouldbe identical with the CSELVOL INCLUDE macros for the other systems you aregenerating. If you do not use this macro, all volumes are included.See Usage Note 5 on page 651 for a warning about changing the defaults for thismacro.ParametersINCLUDEindicates that the volumes specified as volid are to be shared through crosssystem link.volidspecifies the 1- to 6-character volume identifier of a volume to be shared bycross system link. You can use generic volume IDs. A generic volume identifieris a 1- to 6-character pattern that can use asterisks (*) in place of any numberof characters and percent signs (%) in place of exactly one character. Forexample, CSELVOL INCLUDE=(HC%P*) includes all volumes which begin with HCand have a P as their fourth character.CYL=nnnnndefines the cylinder where the CSE track is located for every volid. The value ofnnnnn should be from 0 to the maximum cylinder on the volume. The default is0. Keep in mind that some devices do require multiple cylinders for the CSEarea. See Table 34 on page 652 for the cylinder defaults. If a volume which isto be included in cross system link is to be used as an IPL device for thestand-alone dump utility, a cylinder other than the default of 0 must be specifiedfor that volume. See Usage Note 5 on page 651.TRK=nndefines the track on which the CSE track is located for every CKD DASD650 z/VM: CP Planning and Administration

CSELVOL INCLUDEUsageNotesdefined as volid within the above syntax diagram. The value of nn should be inthe range of 0 to 64, but it cannot be 0 if CYL=0. The default is 1. See UsageNote 5.For ECKD capable CKD devices multiple tracks are used. The number of tracksused for ECKD capable CKD devices depends on the number of cylinders onthe volume. The value specified in TRK=nn is not used for an ECKD capableCKD device.RECL=nnnnndefines the number of cylinders made available for CSE use. This value shouldbe at least equal to the number of cylinders on the volume. If it is smaller thanthe number of cylinders on the volume, links to minidisks starting on a cylinderwith a number higher than nnnnn are denied. The value of nnnnn should be inthe range of 203 to the maximum cylinder on the volume. Table 34 on page 652shows the map record defaults for each device type. See Usage Note 5.For CKD devices nnnnn also defines the record length of the map records. Onthese devices one byte in the map record corresponds to one cylinder. Allcylinders are mapped in one physical record per system. On ECKD capableCKD devices there may be several physical records per system. One byte inthe map record corresponds to two cylinders. Each physical record is 256 bytesand maps 512 cylinders. The number of physical records needed depends onthe number of cylinders made available to CSE. See Usage Note 5.RECS=nndefines the number of map records on the CSE track. The variable nn shouldbe at least equal to the number of systems that share the volume. If nn issmaller than the number of sharing systems, then all links to minidisks on thisvolume are denied. It is recommended that you use as many records as can fiton one track. Refer to Table 34 on page 652 for the default values. See UsageNote 5.1. You can specify as many CSELVOL INCLUDE macros as you need. As manyCSELVOL macros as are required may be specified.2. All the CSELVOL INCLUDE macros must precede any CSELVOL EXCLUDEmacros.3. If CSELVOL INCLUDE or EXCLUDE macros are not specified, all DASDvolumes are included in cross system link.4. If CSELVOL INCLUDE macros are coded in HCPSYS, volumes not specified inthe CSELVOL INCLUDE statements are not included in cross system link.5. Although the CSELVOL INCLUDE macro lets you change the definitions ofcylinder, track, record length, and map records for the CSE track, we do notrecommend that you do so. Leaving the defaults alone enables you to providelink support for new devices with new geometries, should that support becomenecessary in the future.Attention: Current upper limits may exceed capacities of present devices andcause errors when attempting to access beyond a particular device limit.Therefore, any change of defaults should be done with caution.Appendix B. Defining Your System (HCPSYS Macroinstructions) 651

CSELVOL INCLUDETable 34 shows the map record defaults for each device type.Table 34. Map Record Defaults for Each Device TypeDevice TypeNumber ofMap RecordsMapRecordLengthNumber of Cylinders forCSE Area3380 non-type K 11 1770 13380 type K 8 2655 13390-1 12 1113 13390-2 8 2226 13390-3 8 3339 13390-9 56 65520 9OTHER 8 1024 16. The values selected for CYL and TRK must be valid for the device type or typeson which the specified volumes reside but are not checked by this macro, sincethe device type is unknown.7. These defaults support the current CKD and ECKD capable CKD DASD. Thelength of each map record is the maximum number of cylinders on any currentlyexisting model of that device type. The number of records defined for “other”devices is 8, but the actual number of records used is limited to the number thatfit on a track of such “other” device.8. You must use the XLINK FORMAT command to format any volids specified.(See “Generating the Cross System Link Facility” on page 349.) Otherwisewhen you IPL a system that uses CSE, CP does not permit access to, orminidisks on, that volume identifier. For more information about the XLINKFORMAT command, see z/VM: CP Commands and Utilities Reference.9. The number of cylinders for a CSE area (in Table 34) cannot be changed. Theydescribe the number of cylinders needed to hold the CSE information for ECKDDASD only. If the last cylinder on the volume is specified for the CSE area andmultiple cylinders are needed, CSE will not wrap to the beginning of the volumefor the other CSE area cylinders.MigrationAidsYou can achieve the function of the CSELVOL INCLUDE macroinstruction by usingthe XLINK_VOLUME_INCLUDE statement in a system configuration file. See“XLINK_VOLUME_INCLUDE Statement” on page 268.652 z/VM: CP Planning and Administration

CSESYSCSESYS (Optional)►►labelCSESYS CSEID=systemname ►►►(1) PVM 12,SYSTEM1=(sysname1 , , , )cvmname1 timeout1 alias1PVM 12,SYSTEM2=(sysname2, , , )cvmname2 timeout2 alias2►►►PVM 12,SYSTEM3=(sysname3, , , )cvmname3 timeout3 alias3►►PVM 12 (2),SYSTEM4=(sysname4, , , )cvmname4 timeout4 alias4►►,,,►,NOSPOOL=( ▼ sysnamea ) ,LNKONLY=( ▼ sysnameb ) ,LN2ONLY=( ▼ sysnamec )►,NOLINK=( ▼ sysnamed ),►◄Notes:1 The commas between the values in the SYSTEM1 through SYSTEM4 parameters are required ifa value is given or if a default value is assumed. The comma is not required after the last valuethat is specified and the closing parenthesis. For example, SYSTEM1=(KGNVHH,,10) orSYSTEM1=(KGNVHH)2 The following parameters may be specified in any order.PurposeCode the CSESYS macroinstruction to specify the topography of the CSE complex.The CSESYS macroinstruction is optional; if you code it, you must place it after allthe SYSxxxx macroinstructions in HCPSYS ASSEMBLE, but before the SYSENDmacroinstruction. Only one CSESYS macroinstruction may be specified.Appendix B. Defining Your System (HCPSYS Macroinstructions) 653

CSESYSParametersCSEID=establishes the identification of one system in the CSE complex. When thesystem is defined for CSE LNKONLY, systemname must be one of the namesspecified in SYSTEM[1,2,3,4] keywords but must not match the system namespecified in the SYSID macroinstruction.Normally, the specification of all other CSExxx macroinstructions for everysystem in the same complex is identical. CSEID is the only operand that mustbe different, so that every system’s CSEID is unique.systemnameis a 1- to 8-character name that identifies the hardware system where this CPnucleus with CSE active is to run, as it appears in the SYSID macroinstructionin HCPSYS.Although more than one name can be specified in the SYSID macroinstructionof HCPSYS, for integrity reasons a CP nucleus with CSE active depends on anexact relationship of all systems in the complex. Because of this, cross systemspooling and CSE commands are only active when executing on the hardwaresystem specified in CSEID.systemname must also be specified as the system name in one of theSYSTEM[1,2,3,4] keywords.SYSTEM1,SYSTEM2,...,SYSTEM4define the individual systems in the CSE complex. These operands are referredto collectively as SYSTEM[1,2,3,4] operands. At least two systems, SYSTEM1and SYSTEM2, must be specified. All SYSTEM[1,2,3,4] operands must becoded in the same order in the HCPSYS for every system in the CSE complex.sysname1,sysname2,...,sysname4is a 1- to 8-character name that identifies each system to be included in thecomplex. One of these system names must also be specified as systemname inthe CSEID operand. By default, these systems will be included in both crosssystem spooling and cross system link. However, the LNKONLY, LN2ONLY,NOLINK, and NOSPOOL operands allow additional control over which systemsare to be included in, or excluded from, cross system link and cross systemspooling.System names should not be ALL or *.cvmname1,cvmname2,...,cvmname4specifies the 1- to 8-character user ID of the communication virtual machine(CVM) used by CSE. This operand is optional. This user ID defaults to PVM.timeout1,timeout2,...,timeout4specifies the number of seconds that CSE is to wait for a response fromanother system. This waiting period is not associated with any particulartransaction but applies to the overall status of the communication link. It comesinto play only if this system has sent requests to another, and no response toany of those requests was received during the period specified. If the timeoutperiod expires, any incomplete requests are terminated with an error. CSEassumes that the CVM link to that system (or the system itself) is down. Theoperator is notified of this event by a message.No cross system spool processing can take place between these two systemsuntil the connection is restored. However, cross system link processingcontinues. This operand is optional. The default is 12 seconds.654 z/VM: CP Planning and Administration

CSESYSalias1,alias2,...,alias4specifies a second 1- to 8-character name that can be used in CP commandsinstead of sysname[1,2,3,4] to identify the system. This operand is optional.NOSPOOL=specifies that the systems within the parentheses are excluded from sharingspool files with this system but continue to participate in cross system link andcross system commands. Each system name specified in NOSPOOL must alsohave been specified in one of the SYSTEM[1,2,3,4] operands.sysnameaspecifies the 1- to 8-character name of a system to be excluded from sharingspool files.It is not meaningful to code the name of the main system in NOSPOOL. (Themain system is the system that was specified in the CSEID operand.) However,since it may be convenient to do so, no error message is issued if this is done.LNKONLY=specifies that the systems within the parentheses are included in cross systemlink only. None of these systems can share spool file access with any othersystem in the complex, nor can they send or receive CSE commands.LNKONLY, if coded, must appear after the required CSEID, SYSTEM1, andSYSTEM2 operands. Each system specified by LNKONLY is included in crosssystem link only if the system is not also specified on the NOLINK operand.sysnamebspecifies the 1- to 8-character names of the systems to be included in crosssystem link only. This name must not be the same as any of thesysname[1,2,3,4] operands specified in the SYSTEM1 through SYSTEM4keywords, since these are automatically included in cross system link unlessalso specified in a NOLINK statement. All systems with the LNKONLYparameter must be coded in the same order for all systems in the CSEcomplex. If they are not identical, multiple R/W access could be allowed for theshared DASD and may result in data loss.Note: You cannot generate a complex of exclusively LNKONLY systems, sinceSYSTEM1 and SYSTEM2 must always be specified. When you generateHCPSYS for a system that operates in LNKONLY mode, use thesystemname from one of the SYSTEM[1,2,3,4] keywords as the operandfor CSEID.LN2ONLY=specifies that the systems within the parentheses are included in cross systemlink only. None of these systems can share spool file access with any othersystem in the complex, nor can they send or receive CSE commands.LN2ONLY performs the same operation as LNKONLY. LN2ONLY, if coded,must appear after the required CSEID, SYSTEM1, and SYSTEM2 operands.Each system specified by LN2ONLY is included in cross system link only if thesystem is not also specified on the NOLINK operand.sysnamecspecifies the 1- to 8-character names of the systems to be included in crosssystem link only. This name must not be the same as any of thesysname[1,2,3,4] operands specified in the SYSTEM1 through SYSTEM4keywords, since these are automatically included in cross system link unlessalso specified in a NOLINK statement. All systems with the LN2ONLYparameter must be coded in the same order for all systems in the CSEAppendix B. Defining Your System (HCPSYS Macroinstructions) 655

CSESYSUsageNotescomplex. If they are not identical, multiple R/W access could be allowed for theshared DASD and may result in data loss.Note: You cannot generate a complex of exclusively LN2ONLY systems, sinceSYSTEM1 and SYSTEM2 must always be specified. When you generateHCPSYS for a system that operates in LN2ONLY mode, use thesystemname from one of the SYSTEM[1,2,3,4] keywords as the operandfor CSEID.NOLINK=specifies that the systems within the parentheses are excluded from crosssystem link and cannot access each other’s minidisks by using cross systemlink. This has no effect on their participation in cross system spooling or CSEcommands.If a system name is specified in both a LNKONLY (or LN2ONLY orSYSTEM[1,2,3,4]) and a NOLINK parameter, the NOLINK specificationoverrides LNKONLY and LN2ONLY.sysnamedspecifies the 1- to 8-character names of systems to be excluded from crosssystem link. This name must be the same as one of the sysname[1,2,3,4]operands specified in the SYSTEM1 through SYSTEM4 keywords.Note: Use of NOLINK is not compatible with the operation of DIRMAINTRelease 5 within the complex, since DIRMAINT depends on the sharedCMS minidisk protection provided by CSE.1. CSESYS is an optional macro, coded in HCPSYS only if CSE is to be active.2. If CSE is active, one of the SYSTEM[1,2,3,4] operands must be the same asthe CSEID operand.3. To include one or more systems in cross system link only, use LNKONLY,LN2ONLY, or both LNKONLY and LN2ONLY.4. The maximum number of systems that can be defined for cross system link is56 if the CSE complex uses only shared ECKD devices. If any shared CKDdevices are used, then the number of systems supported depends on thedevice type. If more than 56 systems are specified for cross system link,HCPSYS ASSEMBLE does not assemble, and an MNOTE is issued.5. If message 2890E is received when the system is IPLED or when a volume isattached to the system, check that the CSE system and volume tables inHCPSYS are correct and that the CSE track is on the correct volume. If thesystem is running an earlier VM release than z/VM 1.1 and this is an ECKDdevice, enter XLINK FORMAT for the volume.6. Migration Incompatibility Note — In previous releases of VM, you couldspecify different system IDs on the SYSID (page 677) and the CSESYSmacroinstructions. If you decide to migrate your HCPSYS ASSEMBLE file to thez/VM Release 2.1 system configuration file, you can only have one system ID.To specify the system ID in the system configuration file, use theSYSTEM_IDENTIFIER statement (page 226) or theSYSTEM_IDENTIFIER_DEFAULT statement (page 228). Use the system ID youdefine on these statements when you use the following system configuration filestatements:656 z/VM: CP Planning and Administration

CSESYSStatement Function PageXLINK_SYSTEM_EXCLUDE Tells CP which systems not to include in the cross system linkand which systems CP should prevent from accessing eachother’s minidisks. (This statement has no effect on the system’sparticipation in cross system spooling or cross systemcommands.)XLINK_SYSTEM_INCLUDE Tells CP which systems to include in the cross system link. 264XSPOOL_SYSTEM Tells CP the names of the systems participating in cross systemcommands and spooling operations.263271For more information about the system configuration file, see page Chapter 6, “TheSystem Configuration File,” on page 51.ExamplesIn this example of a three-system complex, two systems (KGNVHH and KGNVHB)are sharing fully, with the third system (KGNRMD) included only in minidisk sharing.SYSTEM1 is known as KGNVHH and SYSTEM2 as KGNVHB in the SYSIDmacroinstruction in the HCPSYS ASSEMBLE file and in the CSEID operand of theCSESYS macro. The system that is to be included only in minidisk sharing isdefined as KGNRMD in the SYSID macroinstruction of the HCPSYS ASSEMBLEfile. This LNKONLY system called KGNRMD may have a CSESYS macroinstructionthat looks like this:CSESYS CSEID=KGNVHH,SYSTEM1=(KGNVHH.....,SYSTEM2=(KGNVHB.....,LNKONLY=(KGNRMD)orCSESYS CSEID=KGNVHB,SYSTEM1=(KGNVHH.....,SYSTEM2=(KGNVHB.....,LNKONLY=(KGNRMD)The CSESYS macroinstruction for system KGNVHH looks like:CSESYS CSEID=KGNVHH,SYSTEM1=(KGNVHH.....,SYSTEM2=(KGNVHB.....,LNKONLY=(KGNRMD)The CSESYS macroinstruction for system KGNVHB looks like:CSESYS CSEID=KGNVHB,SYSTEM1=(KGNVHH.....,SYSTEM2=(KGNVHB.....,LNKONLY=(KGNRMD)Note: You cannot generate a complex of exclusively LNKONLY and LN2ONLYsystems, because SYSTEM1 and SYSTEM2 must always be specified.MigrationAidsYou can achieve the function of the CSESYS macroinstruction by using thefollowing statements in a system configuration file:v XLINK_SYSTEM_EXCLUDE (page 263)v XLINK_SYSTEM_INCLUDE (page 264)v XSPOOL_SYSTEM (page 271).Appendix B. Defining Your System (HCPSYS Macroinstructions) 657

CSETRACECSETRACE (Optional)►►labelCSETRACEPAGES=nnn►◄PurposeParametersCode the CSETRACE macroinstruction to establish the number of pages of CPstorage allocated for the CSE trace tables. If CSETRACE is coded, it must appearin the HCPSYS ASSEMBLE file immediately after the CSESYS macro. If theCSETRACE macro is not specified, 4 pages are allocated.PAGESspecifies the number of pages that CP is to allocate for the CSE trace tableswhen the system is initialized.nnnis an integer in the range of 0 to 255. If nnn=0, there are no pages allocated forCSE trace tables.UsageNotes1. The first trace table page provides enough space to hold 16 synchronizationrequests and 111 CVM communication requests. Each additional page providesspace for 127 more CVM communication requests. When this number isexceeded, the trace tables wrap around, and the previously recorded entries areoverwritten.MigrationAidsYou can achieve the function of the CSETRACE macroinstruction by using theXSPOOL_TRACE statement in a system configuration file. See “XSPOOL_TRACEStatement” on page 273.658 z/VM: CP Planning and Administration

CSEUSERCSEUSER (Optional),►►labelCSEUSEREXCLINP=( ▼ usern ),►◄,,EXCLOUT=( ▼ usern )EXCLOUT=( ▼ usern ),,EXCLINP=( ▼ usern )PurposeCode the CSEUSER macroinstruction to define virtual machines that will notparticipate in cross system spooling and cross system message and querycommands. If CSEUSER macros are coded, they must appear after the CSESYSmacro and before the SYSEND macro. Within ASSEMBLER limitations, any numberof CSEUSER macros may be specified.Input and output spool files owned by user IDs listed in the CSEUSER macro arenot accessible to the other systems in the CSE complex.ParametersUsageNotesEXCLINPindicates that input (reader) spool files owned by the user IDs specified asusern are not to be accessible to the other systems in the CSE complex.EXCLOUTindicates that output (printer and punch) spool files owned by the user IDsspecified as usern are not to be accessible to the other systems in the CSEcomplex.usernspecifies the 1- to 8-character user ID of the virtual machine whose input oroutput files are to be excluded from access to cross system spooling. Amaximum of 255 characters, including commas, are allowed in usern definitions.1. User IDs listed in the CSEUSER macro have operational characteristics that aredifferent from those that are not listed. The users associated with these userIDs:v Can log on to more than one system in the complex at the same time. Userswhose user IDs are not listed here are prevented from doing so.v Receive messages generated by the CP MSG, MSGNOH, WNG, and SMSGcommands, but only from users on the same system they are on, unless theuser entering the CP command specified the AT parameter.In addition, when these users:Appendix B. Defining Your System (HCPSYS Macroinstructions) 659

CSEUSERv Enter a CP QUERY userid or QUERY NAMES command, only the system onwhich the command was entered is queried, unless the AT parameter wasused.v Are the target of a CP QUERY userid command, only the system on whichthe command was entered is queried, unless the AT parameter was used.2. These service virtual machines operate only in a single system within the CSEcomplex. CSE automatically excludes:v The system operator (SYSOPR macro in HCPSYS).v The communication virtual machine (CVM). See “Preparing theCommunication Virtual Machine (CVM)” on page 350 for information on howto specify a CVM virtual machine.Do not code any CSEUSER macro for these virtual machines. Your installationmay decide that other service virtual machines should also be excluded, but forease of operation and administration of the CSE complex, keep exclusions to aminimum.3. The CSEUSER EXCLINP list for every system in the CSE complex must be thesame; the CSEUSER EXCLOUT list for every system in the CSE complex mustbe the same.MigrationAidsYou can achieve the function of the CSEUSER macroinstruction by using thefollowing statements in a system configuration file:v XSPOOL_XLIST_INPUT—See “XSPOOL_XLIST_INPUT Statement” on page274.v XSPOOL_XLIST_OUTPUT—See “XSPOOL_XLIST_OUTPUT Statement” onpage 276.660 z/VM: CP Planning and Administration

SYSACNTSYSACNT (Optional)►►labelSYSACNTUSERID=OPERACCTUSERID=userid(userid1,userid2)►◄PurposeCode the SYSACNT macroinstruction to specify user IDs of up to two virtualmachines for which the CP accounting system service (*ACCOUNT) is toaccumulate records. When the virtual machines thus identified to CP are connectedto *ACCOUNT, accounting records are sent to them.In addition, these virtual machines are automatically logged on during CPinitialization.The SYSACNT macroinstruction is optional; if you code it, you must place it afterthe first five required macroinstructions in HCPSYS ASSEMBLE (SYSCPVOL,SYSOPR, SYSRES, SYSSTORE, and SYSTIME) but before the SYSENDmacroinstruction. If this macro is not coded, CP processes the virtual machinehaving the user ID OPERACCT as the accounting record recording virtual machine.Note: Any virtual machine identified on the SYSACNT macro must contain anIUCV directory control statement that authorizes the application running inthe virtual machine to connect to the *ACCOUNT system service. Failure tosupply this required authority results in the failure of the connection requestfrom the virtual machine. If the RETRIEVE utility is used to collectaccounting records and this authority is not coded in the directory, theRETRIEVE utility will fail.ParametersUsageNotesUSERID=OPERACCTUSERID=useridUSERID=(userid1,userid2)specifies the user IDs of the virtual machines for which the *ACCOUNT systemservice is to accumulate and checkpoint accounting records. Either one or twouser IDs may be specified. The user IDs are alphanumeric character strings ofup to 8 characters. OPERACCT is the default user ID.1. If the user ID specified on the SYSACNT macro has an entry in the userdirectory, that user ID is logged on at system initialization.Examples1. To specify OPERACCT as the user ID of the accounting virtual machine, youcan do one of the following:v Omit the SYSACNT macrov Code the SYSACNT macro as follows:SYSACNT USERID=OPERACCTAppendix B. Defining Your System (HCPSYS Macroinstructions) 661

SYSACNT2. To specify DISKACNT as the user ID of the accounting virtual machine, codethe SYSACNT macro as follows:SYSACNT USERID=DISKACNT3. To specify OPERACCT and DISKACNT as the user IDs of the accountingrecord recording virtual machines, code the SYSACNT macro as follows:SYSACNT USERID=(OPERACCT,DISKACNT)MigrationAidsYou can achieve the function of the SYSACNT macroinstruction by using theSYSTEM_USERIDS statement in a system configuration file. See“SYSTEM_USERIDS Statement” on page 232.662 z/VM: CP Planning and Administration

SYSADDINSYSADDIN (Optional)►►labelSYSADDIN ▼ ,entry point name ►◄PurposeCode the SYSADDIN macroinstruction to generate a list of installation-added entrypoints in CP which are to be called during system initialization.The SYSADDIN macroinstruction is optional; if you code it, you must place it afterthe first five required macroinstructions in HCPSYS ASSEMBLE (SYSCPVOL,SYSOPR, SYSRES, SYSSTORE, and SYSTIME) but before the SYSEND orCSESYS macroinstruction.Parametersentry point nameis the installation-defined entry point which is to be called during systeminitialization. The variable entry point name is a 1-character to 8-characteridentifier. This must be a valid CP entry point, which can be located with the CPLOCATE command. The entry point must be MP (multi-processor)-capable anduse a dynamic savearea.UsageNotes1. Entry points listed must be included in the CP module.2. CP will schedule each of the specified entry points for execution during thesystem initialization process. However, the entry points may not run until afterinitialization is complete.ExamplesMigrationAidsTo specify LOCALMOD, USERMOD, and XMOD as entry points to be startedduring system initialization code the SYSADDIN macro as follows:SYSADDIN LOCALMOD,USERMOD,XMODYou can achieve the function of the SYSADDIN macroinstruction by using theCP_ADDON_INITIALIZE_ROUTINES statement in a system configuration file. See“CP_ADDON_INITIALIZE_ROUTINES Statement” on page 72.Appendix B. Defining Your System (HCPSYS Macroinstructions) 663

SYSCPVOLSYSCPVOL (Required)►►labelSYSCPVOL ▼ ,volid,OWN(volid ,D ),SHR►◄PurposeCode the SYSCPVOL macroinstruction to define and generate a list of up to 255CP-owned DASD volumes. CP-owned volumes are the CP system residencevolume and volumes that contain real system paging, spooling, dump, directory, ortemporary disk space. SYSCPVOL is required and must appear as one of the firstfive macroinstructions in the HCPSYS ASSEMBLE file.When CSE is not used, all the volumes listed in SYSCPVOL containing SPOLspace may be used to read and write spool files. (Spool files are written only once,at the time they are created.)When CSE is active, shared access to spool files for all systems in the complex isprovided by physically sharing the spooling DASD. Although physically this is bothread and write sharing, logically the sharing is on a read-only basis. This meansthat some volumes must be identified as available for writing the spool files that arecreated on this system, and others must be identified as available only for readingspool files created on other systems. The SYSCPVOL macro allows this byspecifying the SHR and OWN operands.Note: It is recommended that the system residence volumes and paging volumesnot be shared among systems in a CSE complex.Parametersvolidspecifies the 1- to 6-character volume identifier. All volids with SPOL spacemust be specified in exactly the same position in the SYSCPVOL lists for allsystems in the CSE complex. An example follows, but it does not define asmany volumes as would be expected in a production system.D indicates that the spool space on volume volid is to be reserved exclusively fordumps.SHRindicates that the identified volume is owned by another system in the CSEcomplex. This system cannot create or destroy spool files on it. It can, however,read spool files previously written by the owning system.OWNindicates that the volume identified is owned by this system (the system you aregenerating) and that only this system can create or destroy spool files on thisvolume. The other systems in the CSE complex, which have volid coded withthe SHR parameter, have shared access to this system’s spool files becausethey can read the data on this volume. OWN is the default and need not bespecified.664 z/VM: CP Planning and Administration

SYSCPVOLUsage Notes1. Before CP can use a DASD, you must format, label, and allocate space on theDASD. You may do this by using the Device Support Facilities program(ICKDSF) or the CMS utility CPFMTXA. However, ICKDSF is the recommendedmethod of CP volume maintenance and is required for certain DASD types.ECKD capable CKD devices should be formatted without filler records usingICKDSF. For more information on the ICKDSF program, see the Device SupportFacilities User’s Guide and Reference book. For more information on theCPFMTXA utility, see the z/VM: CMS Commands and Utilities Reference book.2. You must specify the system residence volume identification on the SYSCPVOLmacroinstruction. You must also identify, as CP-owned, volumes that containcheckpoint and warm-start data, paging, spooling, dump, directory, or temporarydisk space. You can identify all other volumes by coding the SYSUVOLmacroinstruction or by logically attaching (ATTACH command) the entire device.3. If a volume is specified in the SYSCPVOL statement but is not mounted whenCP is loaded, CP considers that volume unavailable. CP continues processing,if possible. The system operator may mount and attach the volume (using theclass A ATTACH command) to the system when it is needed. This providesextra space for future growth.4. If you want to add new volumes to the system after system generation, add newvolume identifications to the end of the SYSCPVOL list. Then reassembleHCPSYS ASSEMBLE, rebuild the CP nucleus, and reload CP (see thegeneration procedures in z/VM: Guide for Automated Installation and Service).This procedure allows you to warm start the system without disturbing therelative entry number that locates system spool buffers.Attention: If you delete any volume that contains spool space from theSYSCPVOL list, or any volume that contains spool space is moved to a differentposition in the SYSCPVOL list, a clean start is required. A clean start causesdeletion of spool files and system data files, including named saved systemsand saved segments. Files that are to be preserved over such a change shouldbe dumped to tape using the SPXTAPE DUMP command.After the clean start, SPXTAPE LOAD should be used to restore the spool filesand system data files from tape. This ensures that spool files and system datafiles that existed on the system before deletion of movement of volumes in theSYSCPVOL list are restored correctly.5. If you specify D for a volume and the spool space on that volume is already inuse for spool files when the system is IPLed, those spool files remain on thatvolume until an SPXTAPE or SPOOL command moves them.6. For a singlez/VM system, that is, one that is not associated with other systemsby means of CSE, all CP volumes should be owned by that system, and SHRshould not be specified. Since OWN is the default, no change to the traditionalcoding of SYSCPVOL is required.7. The following notes apply only when CSE is in use:a. All volumes that have SPOL extents must be included in the SYSCPVOLmacro for each system, with the same relative position in each system’sSYSCPVOL macro. It is suggested that all volumes with SPOL extents begrouped by system and placed first in the SYSCPVOL list.b. If D is specified for volid, CSE treats volid the same way as if OWN werespecified; only this system may allocate spool space (for dumps) on thisvolume.The variable volid must be coded with the SHR parameter in theSYSCPVOL lists of all the other systems in the CSE complex.Appendix B. Defining Your System (HCPSYS Macroinstructions) 665

SYSCPVOLc. In the SYSCPVOL list, you cannot change the order of the volumes thatcontain SPOL space unless a clean start is performed on all systems in thecomplex. If you do change the order, you may have to use SPXTAPE toavoid losing spool files. However, if you add new SPOL space volumes tothe end of the SYSCPVOL lists of the associated systems without disturbingthe position and sequence of existing volumes, a clean start is not required.8. At system initialization (IPL), if more than one DASD volume has the samevolume serial (volid) and that volid is in the CP or user volume list, the volumewith the lowest device number is attached to the system. This rule does notapply to duplicates of the system residence (IPLed) volume.9. The list of CP-owned volumes generated by CP_OWNED statements in thesystem configuration file completely supersedes the list of CP-owned volumesgenerated by the SYSCPVOL macroinstruction.Examples1. To designate the spool space on volume CPDSK1 for dumps only, code theSYSCPVOL macro as follows:SYSCPVOL CPDRM1,(CPDSK1,D),CPDSK22. To designate spool space on volumes to be used for CSE code the SYSCPVOLmacro as follows:SYSCPVOL list for system KGNRMD1:SYSCPVOLRD1RES,(SPOOL1,OWN),(SPOOL2,SHR),(SPOOL3,SHR),(SPOOL4,OWN),(SPOOL5,SHR),(SPOOL6,SHR),(SPOOL7,OWN),(SPOOL8,SHR),(SPOOL9,SHR)SYSCPVOL list for system KGNRMD2:SYSCPVOLRD2RES,(SPOOL1,SHR),(SPOOL2,OWN),(SPOOL3,SHR),(SPOOL4,SHR),(SPOOL5,OWN),(SPOOL6,SHR),(SPOOL7,SHR),(SPOOL8,OWN),(SPOOL9,SHR)SYSCPVOL list for system KGNRMD3:SYSCPVOLRD3RES,(SPOOL1,SHR),(SPOOL2,SHR),(SPOOL3,OWN),(SPOOL4,SHR),(SPOOL5,SHR),(SPOOL6,OWN),(SPOOL7,SHR),(SPOOL8,SHR),(SPOOL9,OWN)5.ExplanationEach system owns three volumes that contain CP spooling space. The position ofthe spooling volumes is the same in each list. The only nonspooling volumes listedare the system residence volumes RD1RES, RD2RES, and RD3RES. These arethree different volumes, but they occupy the same position in each list in order tokeep the position of the spooling volumes constant. Rather than allow an entry todefault to OWN, it has been explicitly stated in each case. This makes visualchecking of the lists less difficult.Note: System residence volume IDs should be unique.MigrationAidsYou can achieve the function of the SYSCPVOL macroinstruction by using theCP_OWNED statement in a system configuration file. See “CP_OWNED Statement”on page 73.666 z/VM: CP Planning and Administration

SYSDUMPSYSDUMP (Optional)►►labelSYSDUMPUSERID=OPERATNSUSERID=userid►◄PurposeCode the SYSDUMP macroinstruction to identify the user ID of the virtual machinethat receives system dump files. The SYSDUMP macroinstruction is optional; if youcode it, you must place it after the first five required macroinstructions in HCPSYSASSEMBLE (SYSCPVOL, SYSOPR, SYSRES, SYSSTORE, and SYSTIME) butbefore the SYSEND macroinstruction. If this macro is not coded, the virtual machinehaving the user ID OPERATNS receives the system dump files.ParametersUsageNotesUSERID=OPERATNSUSERID=useridis the user ID of the virtual machine that receives spooled system dumps. Thevariable userid must be an alphanumeric character string of up to 8 characterslong. OPERATNS is the default user ID.CP creates system dump files as a result of system abends and system restarts.You can also use the VMDUMP command to send virtual machine dumps to thevirtual machine you specify in the SYSDUMP macroinstruction.ExamplesMigrationAids1. To specify OPERATNS as the user ID of the virtual machine that receivessystem dump files you can do one of the following:v Omit the SYSDUMP macrov Code the SYSDUMP macro with no parametersv Code the SYSDUMP macro as follows:SYSDUMP USERID=OPERATNS2. To specify MRDUMP as the user ID of the virtual machine that receives systemdump files, code the SYSDUMP macro as follows:SYSDUMP USERID=MRDUMPYou can achieve the function of the SYSDUMP macroinstruction by using theSYSTEM_USERIDS statement in a system configuration file. See“SYSTEM_USERIDS Statement” on page 232.Appendix B. Defining Your System (HCPSYS Macroinstructions) 667

SYSENDSYSEND (Required)►►labelSYSEND►◄PurposeExamplesMigrationAidsUse the SYSEND macroinstruction to end the HCPSYS assembly. The SYSENDmacroinstruction is required and must appear as the last macroinstruction inHCPSYS ASSEMBLE.To end the HCPSYS assembly, code the SYSEND macro as follows:SYSENDThere is no equivalent statement in a system configuration file for the SYSENDmacroinstruction.668 z/VM: CP Planning and Administration

SYSEREPSYSEREP (Optional)►►labelSYSEREPUSERID=OPEREREPUSERID=userid(userid1,userid2)►◄PurposeCode the SYSEREP macroinstruction to identify the user IDs of one or two virtualmachines for which the *LOGREC system service is to accumulate records. Whenthe virtual machines thus identified to CP connect to the *LOGREC system service,EREP records are sent to them.These virtual machines are automatically logged on during CP initialization.The SYSEREP macroinstruction is optional; if you code it, you must place it afterthe first five required macroinstructions in HCPSYS ASSEMBLE (SYSCPVOL,SYSOPR, SYSRES, SYSSTORE, and SYSTIME) but before the SYSENDmacroinstruction. If this macro is not coded, CP processes the virtual machinehaving the user ID OPEREREP as the error recording virtual machine.Note: Any virtual machine identified on the SYSEREP macro must contain anIUCV directory control statement authorizing the application running in thevirtual machine to connect to the *LOGREC system service. Failure to supplythis required authorization will result in the failure of the connection requestfrom the virtual machine. If the RETRIEVE utility is used to collect errorrecords and this authorization is not coded in the directory, RETRIEVE willfail.ParametersUsageNotesUSERID=OPEREREPUSERID=useridUSERID=(userid1,userid2)are the user IDs of the virtual machines for which the *LOGREC system serviceis to accumulate and checkpoint error records. One or two user IDs can bespecified. The variable userid must be an alphanumeric character string of up to8 characters. OPEREREP is the default user ID.If the user ID specified on the SYSEREP macroinstruction has an entry in the userdirectory at system initialization, the associated virtual machine is logged on to thesystem.Examples1. To specify OPEREREP as the user ID of the error recording virtual machine,you can do one of the following:v Omit the SYSEREP macrov Code the SYSEREP macro as follows:SYSEREP USERID=OPEREREPAppendix B. Defining Your System (HCPSYS Macroinstructions) 669

SYSEREP2. To specify MISSEREP as the user ID of the error recording virtual machine,code the SYSEREP macro as follows:SYSEREP USERID=MISSEREP3. To specify OPEREREP and MISSEREP as the user IDs of the error recordingvirtual machines, code the SYSEREP macro as follows:SYSEREP USERID=(OPEREREP,MISSEREP)MigrationAidsYou can achieve the function of the SYSEREP macroinstruction by using theSYSTEM_USERIDS statement in a system configuration file. See“SYSTEM_USERIDS Statement” on page 232.670 z/VM: CP Planning and Administration

SYSEXCLSYSEXCL (Optional)►►labelSYSEXCL ▼ ,volid►◄PurposeCode the SYSEXCL macroinstruction to define volumes that are to be excludedfrom the user volume list. (User volumes are those volumes that you use to containminidisks.) During system IPL, CP attaches to the system any volume specified onthe SYSUVOL macro and any volume whose volume identifier (volid) matches ageneric volume identifier specified on the SYSINCL macro, unless the volume isalso specified on the SYSEXCL macro.The SYSEXCL macroinstruction is optional; if you code it, you must place it afterthe first five required macroinstructions in HCPSYS ASSEMBLE (SYSCPVOL,SYSOPR, SYSRES, SYSSTORE, and SYSTIME) but before the SYSEND orCSESYS macroinstruction.Parametersvolidis the user volume identification. The variable volid is a 1- to 6-characteridentifier. Each character can be a letter, number, or hyphen.The variable volid can also be specified as a generic volume identifier. Ageneric volume identifier is specified as 1 to 5 characters followed by anasterisk (*). For example, SYSEXCL EM* excludes all volumes whose volumeidentifiers begin with the letters “EM”.UsageNotes1. If a volume identifier matches a volid pattern specified on both the SYSINCLand SYSEXCL macros, CP does not attach the volume to the system duringinitialization.2. Dedicated devices are not user volumes. They must be attached to the user towhich they are dedicated and not to the system. Therefore, if you code aSYSINCL macro, you may want to specify dedicated devices on the SYSEXCLmacro.Examples1. To define as user volumes all volumes except VMTST1 and VMTST2, code thefollowing macros:SYSINCL *SYSEXCL VMTST1,VMTST22. To define as user volumes all volumes whose identifiers begin with “US” exceptfor any whose identifiers begin with “USER”, code the following macros:SYSINCL US*SYSEXCL USER*Appendix B. Defining Your System (HCPSYS Macroinstructions) 671

SYSEXCLMigration AidsYou can achieve the function of the SYSEXCL macroinstruction by using theUSER_VOLUME_EXCLUDE statement in a system configuration file. See“USER_VOLUME_EXCLUDE Statement” on page 251.672 z/VM: CP Planning and Administration

SYSFCNSYSFCN (Optional)►►labelSYSFCN(1),OPER=A,OPER=classes,CPRD=CE,CPRD=classes,CPWT=C,CPWT=classes►►,SERV=F,SERV=classes,DFLT=G,DFLT=classes►◄Notes:1 The following parameters can be specified in any order.PurposeCode the SYSFCN macroinstruction to change the privilege class authorizing thefollowing CP functions:v Logging on as the primary system operatorv Intensive error recordingv Using the read function of the CP IOCP utilityv Using the write function of the CP IOCP utilityv Specifying the default user class.A default SYSFCN macro is supplied in the sample HCPSYS ASSEMBLE file. If youwant to change some or all of the privilege classes assigned to these CP functions,you must include a SYSFCN macro statement in HCPSYS that specifies thechanges you want to make.The SYSFCN macroinstruction is optional; if you code it, you must place it after thefirst five required macroinstructions in HCPSYS ASSEMBLE (SYSCPVOL,SYSOPR, SYSRES, SYSSTORE, and SYSTIME) but before the SYSENDmacroinstruction. If SYSFCN is not coded, all the default privilege classes are used.ParametersOPER=classesOPER=Aspecifies the classes for the primary system operator. The default is A.CPRD=classesCPRD=CEspecifies the classes authorized to issue IOCP READ. The default is CE.CPWT=classesCPWT=Cspecifies the classes authorized to issue IOCP WRITE. The default is C.SERV=classesSERV=Fspecifies the classes authorized to perform intensive error recording. Thedefault is F.DFLT=classesAppendix B. Defining Your System (HCPSYS Macroinstructions) 673

SYSFCNUsageNotesDFLT=Gspecifies the default classes for users who do not have a class defined in theirdirectory entries. The default is G.Coding the OPER=classes operand allows any user ID with any of the specifiedclasses to become the system operator ID if the primary operator logs off.ExamplesMigrationAidsTo specify the class of the system operator as ABD, code the SYSFCN macro asfollows:SYSFCN OPER=ABDYou can achieve the function of the SYSFCN macroinstruction by using thePRIV_CLASSES statement in a system configuration file. See “PRIV_CLASSESStatement” on page 184.674 z/VM: CP Planning and Administration

SYSFORMSYSFORM (Optional)►►labelSYSFORM(1),,DEFPRT=STANDARD,DEFPRT=userform►▼(userform,operform ),NARROW►,DEFPUN=STANDARD,DEFPUN=userform,DEFCON=STANDARD,DEFCON=userform,DEFRDR=STANDARD,DEFRDR=userform►◄Notes:1 The following parameters can be specified in any order.PurposeCode the SYSFORM macroinstruction to create a list of user form names and theircorresponding operator form numbers. You can also use SYSFORM to (a) specifyforms as NARROW, so that a narrow separator page is printed and (b) generatedefault user form names to be used when files are created on virtual printers, virtualpunches, virtual consoles, or real card readers.The SYSFORM macroinstruction is optional; if you code it, you must place it afterthe first five required macroinstructions in HCPSYS ASSEMBLE (SYSCPVOL,SYSOPR, SYSRES, SYSSTORE, and SYSTIME) but before the SYSENDmacroinstruction.Parametersuserformis a 1- to 8-character user form name.operformis a 1- to 8-character operator form number.NARROWspecifies that the form be 86 columns wide. If you specify NARROW, separatorinformation does not print beyond the 86th column.DEFPRTspecifies the default user form for virtual printer spool files. If DEFPRT is notspecified, the default is DEFPRT=STANDARD.DEFPUNspecifies the default user form for virtual punch spool files. If DEFPUN is notspecified, the default is DEFPUN=STANDARD.DEFCONspecifies the default user (and, implicitly, operator) forms for virtual consolespool files. If DEFCON is not specified, the default is DEFCON=STANDARD.DEFRDRspecifies the default user (and, implicitly, operator) forms for files created on areal card reader. If DEFRDR is not specified, the default isDEFRDR=STANDARD.Appendix B. Defining Your System (HCPSYS Macroinstructions) 675

SYSFORMUsage NotesExamplesThe userform and operform operands establish the correspondence between theuser form and operator form. If no user form and operator form pairs are specified,no form list is generated, and CP makes no distinction between user forms andoperator forms.1. To use CP’s default values you can do one of the following:v Omit the SYSFORM macro from HCPSYSv Code the SYSFORM macro with no operands.CP assigns default forms of STANDARD for the printer, punch, console, andcard reader.2. You can specify the following default forms:v LISTING for virtual printer files and real card reader filesv PLAIN for virtual punch files.To do this, code the SYSFORM macro as follows:SYSFORM DEFPRT=LISTING,DEFPUN=PLAIN,DEFRDR=LISTING3. To specify the same default values as in the previous example:a. Create a list of user form names (for example, LISTING, DOCUMENT, andPLAIN) and the corresponding operator form numbers (G1PW and G1PN).b. Specify that G1PN is to be no more than 86 columns wide.c. Code the SYSFORM macro as follows:SYSFORM (LISTING,G1PW), *(DOCUMENT,G1PN,NARROW), *(PLAIN,G1PN,NARROW), *DEFPRT=LISTING, *DEFPUN=PLAIN, *DEFRDR=LISTINGNote that if you need more than one line to code the SYSFORM macro, you mustcode a continuation character in column 72 and start the next line in column 16.MigrationAidsYou can achieve the function of the SYSFORM macroinstruction by using thefollowing statements in a system configuration file:v FORM_DEFAULT—See “FORM_DEFAULT Statement” on page 150.v USERFORM—See “USERFORM Statement” on page 247.676 z/VM: CP Planning and Administration

SYSIDSYSID (Optional)►►labelSYSID(1),,systemid▼ (systemid,model,cpuid ),sysgate,NOSYSGAT►►DEFAULT=defid,defid(defid ),defgate,NOSYSGAT►◄Notes:1 The following parameters can be specified in any order.PurposeCode the SYSID macroinstruction to create a system identifier for the processor onwhich you run z/VM. If your installation has several processors, you can createsystem identifiers for each one. At CP initialization, CP matches the processormodel and CPU identification numbers with your system identifier. Then, the systemidentifier appears on printed output separator pages and in the status area of 3270display screens.The SYSID macro also identifies the system gateway name for a system. Thesystem gateway is identified automatically when CP initializes on the system. Asystem gateway provides a way to access private or global resources on a specificsystem within a CS or TSAF collection. It also provides access to private or globalresources in a CS collection from an adjacent TSAF collection. Similarly, resourcesin a TSAF collection can be accessed from an adjacent CS collection. See thez/VM: Connectivity book for more information about gateways.By default, the system gateway name is the same as the system ID for the system;this is the recommended naming convention. However, if this default conflicts withanother gateway name, you can use SYSID to specify a unique system gatewayname for the system.The SYSID macroinstruction is optional. If you code it, you must place it after thefirst five required macroinstructions in HCPSYS ASSEMBLE (SYSCPVOL,SYSOPR, SYSRES, SYSSTORE, and SYSTIME) but before the SYSENDmacroinstruction.Note: If you do not code the SYSID macroinstruction, the z/VM system will nothave a system identifier or system gateway name. Also, if the processormodel and CPU identification number do not match any SYSID entries andthe DEFAULT operand is not coded, a system identifier or system gatewaywill not be identified.Appendix B. Defining Your System (HCPSYS Macroinstructions) 677

SYSIDParametersUsageNotessystemidis the 1- to 8-character system identification.modelis a 3- or 4-digit hexadecimal number that identifies the processor unit modelnumber.cpuidis a 6-digit hexadecimal identification number of the processor in the processorcomplex. If you specify a 5-digit number, the high-order digit is set to 0. Only 5-or 6- digit numbers are accepted.sysgateis the 1- to 8-character name of the system gateway that will be identified whenthis system initializes. The sysgate name is optional; if not specified, the systemgateway name defaults to the systemid for the system. ISFC will then use thisvalue as its node name within a CS collection.If you specify NOSYSGAT as the sysgate value, a system gateway name is notidentified for the system. Also, the specified system cannot join a CS collection.DEFAULT=identifies the defaults that are used if VM is initialized on a processor that is notlisted in the SYSID macroinstruction.defidis the one- to eight-character default system identification. CP uses thedefid value when VM is loaded on a system whose model and CPUidentification number are unknown. If you do not code the DEFAULToperand, VM will not have a default system identifier.defgateis the one- to eight-character default name of the system gateway. If you donot specify a defgate value, the specified defid value is used as the defaultsystem gateway name.If you specify NOSYSGAT as the defgate value, a system gateway name isnot identified for the system. Also, the specified system cannot join a CScollection.1. Migration Incompatibility Note — In previous releases of VM, you couldspecify different system IDs on the CSESYS (page 653) and the SYSID macros.If you migrate your HCPSYS ASSEMBLE file to the system configuration file,you can only have one system ID.To specify the system ID in the system configuration file, use theSYSTEM_IDENTIFIER statement (page 226) or theSYSTEM_IDENTIFIER_DEFAULT statement (page 228).Use the system ID you define on these statements when you use the followingsystem configuration file statements:Statement Function PageXLINK_SYSTEM_EXCLUDE Tells CP which systems not to include in the cross system link and whichsystems CP should prevent from accessing each other’s minidisks. (Thisstatement has no effect on the system’s participation in cross systemspooling or cross system commands.)263678 z/VM: CP Planning and Administration

SYSIDStatement Function PageXLINK_SYSTEM_INCLUDE Tells CP which systems to include in the cross system link. 264XSPOOL_SYSTEM Tells CP the names of the systems participating in cross system commandsand spooling operations.271For more information about the system configuration file, see page Chapter 6, “TheSystem Configuration File,” on page 51.Examples1. If your installation has one processor and you want to specify ONLYSYS as thesystem identifier for printer separator pages and in the system screen logo,code the SYSID macro as follows:SYSID DEFAULT=ONLYSYSThe system gateway for this system will also be identified as ONLYSYS.2. As the following example shows, you can specify values for several systemswhen coding the SYSID macro:SYSID (SYSTEM1,2064,073499,SYS1), *(SYSTEM2,2064,123664), *(SYSTEM3,2064,123512,NOSYSGAT), *DEFAULT=(OTHERSYS,OTHERGAT)When SYSTEM1 initializes (processor model 2064, identification number073499), the system gateway SYS1 will be identified. Because a sysgate valueis not specified for SYSTEM2, the system gateway name for this system willalso be identified as SYSTEM2. On SYSTEM3, the NOSYSGAT value indicatesthat a system gateway will not be identified when this system initializes.Because the DEFAULT parameter was coded, any processor not specified onSYSID will be identified as system OTHERSYS; its system gateway will beidentified as OTHERGAT.Note: If you need more than one line to code the SYSID macro, you must code acontinuation character in column 72 and start the next line in column 16.MigrationAidsYou can achieve the function of the SYSID macroinstruction by using the followingstatements in a system configuration file:v SYSTEM_IDENTIFIER—See “SYSTEM_IDENTIFIER Statement” on page 226.v SYSTEM_IDENTIFIER_DEFAULT—See “SYSTEM_IDENTIFIER_DEFAULTStatement” on page 228.Appendix B. Defining Your System (HCPSYS Macroinstructions) 679

SYSINCLSYSINCL (Optional)►►labelSYSINCL ▼ ,v* ►◄PurposeCode the SYSINCL macroinstruction to define user volumes by means of a genericvolume identifier and to include those volumes in the user volume list. (Uservolumes are those volumes that you use to contain minidisks.) During system IPL,CP attaches to the system any volumes whose volume identifier matches a genericvolume identifier specified in the SYSINCL list, but will not use them for paging,spooling, directory or temporary disk space. A volume must be attached to thesystem before users can link to minidisks it contains.The SYSINCL macroinstruction is optional; if you code it, you must place it after thefirst five required macroinstructions in HCPSYS ASSEMBLE (SYSCPVOL,SYSOPR, SYSRES, SYSSTORE, and SYSTIME) but before the SYSEND orCSESYS macroinstruction.Parametersv is the generic volume identifier. The variable v consists of 0 to 5 characters.Each character can be a letter, number, or hyphen. The variable v must befollowed by an asterisk. A single asterisk (*) attaches all volumes to the system.UsageNotes1. You can specify volumes that you do not want to define as user volumes byspecifying them on the SYSEXCL macro (see page 671).2. If a volume identifier matches a generic volume identifier specified on both theSYSINCL and SYSEXCL macros, CP does not attach the volume to the systemduring initialization.3. If a volume is normally attached to the system through the SYSINCL list, CPdoes not notify the operator if the volume is not mounted. If a user volume isnecessary for normal system operation, specify it on the SYSUVOL macro sothat the operator is notified during system initialization that the volume is notmounted.Examples1. To define as user volumes all volumes not specified by the SYSEXCL macro, sothat CP attaches them to the system during initialization, code the SYSINCLmacro as follows:SYSINCL *2. To define as user volumes all volumes whose volume identifiers begin witheither “MVS”, “USER”, or “CMS”, so that CP attaches them to the system duringinitialization, code the SYSINCL macro as follows:SYSINCL MVS*,USER*,CMS*680 z/VM: CP Planning and Administration

Migration AidsYou can achieve the function of the SYSINCL macroinstruction by using theUSER_VOLUME_INCLUDE statement in a system configuration file. See“USER_VOLUME_INCLUDE Statement” on page 253.SYSINCLAppendix B. Defining Your System (HCPSYS Macroinstructions) 681

SYSJRLSYSJRL (Optional)►► label SYSJRLJOURNAL=NO(1)►◄JOURNAL=YESOptionsOptions:,STQUERY=NO,STQUERY=YES,LOGUID=OPERATOR,LOGUID=userid,LOGLOC=(10,60),LOGLOC=(n,m),LOGLMT=(2,3,4),LOGLMT=(x,y,z)►►,LNKUID=OPERATOR,LNKUID=userid,LNKLMT=(2,5,10),LNKLMT=(x,y,z),PSUPRS=NO,PSUPRS=YESNotes:1 The defaults you receive appear above the line in the Options fragment.PurposeCode the SYSJRL macroinstruction to specify the inclusion of the journaling orpassword suppression facility, or both.The SYSJRL macroinstruction is optional; if you code it, you must place it after thefirst five required macroinstructions in HCPSYS ASSEMBLE (SYSCPVOL,SYSOPR, SYSRES, SYSSTORE, and SYSTIME) but before the SYSENDmacroinstruction. If the SYSJRL macro is not coded, all the default values are used.ParametersJOURNAL=NOJOURNAL=YESspecifies whether the journaling facility is to be operative in the system beinggenerated.STQUERY=NOSTQUERY=YESspecifies whether the ability to use the SET and QUERY commands to set andquery the journaling function should be part of the system being generated.STQUERY=YES can be specified only if JOURNAL=YES is also specified.LOGUID=OPERATORLOGUID=useridspecifies the user ID that should receive the indication that an invalid logonpassword count has been reached or exceeded. If this user ID is disconnectedor logged off, the system operator receives the message generated.LOGLOC=(10,60)682 z/VM: CP Planning and Administration

SYSJRLLOGLOC=(n,m)specifies the maximum number of invalid password attempts and the delay timeuntil another logon is allowed. The variable n is the maximum number of invalidpassword attempts. The value of n may range from 1 to 255. The default is 10logon attempts.The variable m is the delay time in minutes until the next logon attempt. Thevalue of m may range from 0 to 255. The default is 60 minutes.If anyone makes more than n unsuccessful attempts to log on to a given userID or terminal, an error message is issued. Nobody can log on to that user ID,or at the terminal where the attempts were made, until m minutes have passed.Anyone who tries receives an error message.LOGLMT=(2,3,4)LOGLMT=(x,y,z)specifies the invalid LOGON/AUTOLOG/XAUTOLOG threshold. The valuesspecified apply to all unsuccessful logon attempts at a single terminal and for asingle user ID.The variable x is the value that when reached causes CP to generate a type 04accounting record for that and each subsequentLOGON/AUTOLOG/XAUTOLOG that contains an invalid password.The variable y is the value that when reached causes CP to send a message tothe virtual machine with the user ID specified by the LOGUID operand for thatand each subsequent LOGON/AUTOLOG/XAUTOLOG that contains an invalidpassword.The variable z is the value that determines how many logon attempts CP is topermit before it returns the terminal to the VM logo. When more than z logonattempts have been made with invalid passwords from a single terminal, CPdisplays a new VM logon screen and allows a new logon sequence to bestarted.The variable z also indicates how many AUTOLOG and XAUTOLOG attemptswith invalid passwords CP allows. No further AUTOLOG or XAUTOLOGcommands can be entered by a user who has entered more than z AUTOLOGor XAUTOLOG commands with invalid passwords for the duration of the logonsession. To dynamically set the system limit for the number of incorrectpasswords a user can enter on the AUTOLOG and XAUTOLOG commands,use the SET CMDLIMIT command. To query the system limit for the number ofincorrect passwords that are allowed, use the QUERY CMDLIMIT command.Note: The variable z can be any decimal number from 1 to 255. Variables xand y can be any decimal number from 0 to 255. The number 0 is aspecial case indicating that the applicable function should be bypassed.For example, if LOGLMT=(0,5,5) is specified, no accounting records aregenerated.LNKUID=OPERATORLNKUID=useridspecifies the user ID that should receive the indication that an invalid linkpassword count has been reached or exceeded. If this user ID is disconnectedor logged off, the system operator receives the message generated.LNKLMT=(2,5,10)LNKLMT=(x,y,z)specifies the invalid link password threshold. The value specified applies to asingle user ID for a single logon session. The variable x is the value that whenAppendix B. Defining Your System (HCPSYS Macroinstructions) 683

SYSJRLreached causes a type 06 accounting record to be generated for that and eachsubsequent LINK command that contains an invalid password. The variable y isthe value that when reached causes a message to be sent to the user IDspecified by the LNKUID operand for that and each subsequent LINK commandthat contains an invalid password. The variable z is the value that whenreached causes the LINK command to be disabled for the current logonsession.Note: The variable z (which in VM/XA has a limit of 10) can be any decimalnumber from 1 to 255. Variables x and y can be any decimal numberfrom 0 to 255. The number 0 is a special case indicating that theapplicable function is to be bypassed. For example, if LNKLMT=(2,0,10)is specified, no message is sent.|PSUPRS=NOPSUPRS=YESspecifies whether the facility that suppresses the password on the commandline is initially part of the system being generated. Coding PSUPRS=YESprevents passwords entered on the AUTOLOG, LINK, LOGON, or XAUTOLOGcommand line from being accepted. The status of the password suppressionfacility can be modified after system initialization with the SET PASSWORDcommand. Specifying PSUPRS=YES provides additional security for yourinstallation.ExamplesCode the SYSJRL macro as followsSYSJRL JOURNAL=YES, *STQUERY=YES, *LOGUID=LOGGER, *LOGLOC=(5,120), *LOGLMT=(5,5,5), *LNKUID=LOGGER, *LNKLMT=(5,5,5), *PSUPRS=YESto specify the following system security options:v The journaling facility is operative.v The ability to use the SET and QUERY commands to set and query journalingoptions is available.v User ID LOGGER receives the indication that an invalid logon password counthas been reached or exceeded.v A maximum of five invalid password attempts are allowed to a given user orterminal after which an error message is issued and logons from that user ID andterminal are not allowed for 2 hours.v After five unsuccessful logon attempts, CP writes a type 04 accounting recordand sends a message to LOGGER, and no more than five AUTOLOG andXAUTOLOG attempts with invalid passwords are allowed.v User ID LOGGER should receive the indication that an invalid link passwordcount has been reached or exceeded.v If five invalid link passwords are entered by a single user for a single logonsession, CP generates a type 06 accounting record, sends a message toLOGGER (specified by LNKUID) and disables the link command for that user forthe current logon session.v The password suppression on the command line is initially part of the system.684 z/VM: CP Planning and Administration

SYSJRLMigration AidsYou can achieve the function of the SYSJRL macroinstruction by using the followingstatements in a system configuration file:v FEATURES—See “FEATURES Statement” on page 136.v JOURNALING—See “JOURNALING Statement” on page 160.Appendix B. Defining Your System (HCPSYS Macroinstructions) 685

SYSMAXUSYSMAXU (Optional)►►labelSYSMAXU MAXUSERS= nnnnnOFF►◄PurposeCode the SYSMAXU macroinstruction to specify the user logon limit. TheSYSMAXU macro is optional. If you code it, you must place it after the first fiverequired macros in HCPSYS ASSEMBLE (SYSCPVOL, SYSOPR, SYSRES,SYSSTORE, and SYSTIME) but before the SYSEND macro. If the SYSMAX macrois not specified, the system does not set any limit.ParametersUsageNotesnnnnnis the maximum number of users that can be logged on. The range is from 1 to99999.OFFindicates that an unlimited number of users can log on.1. If this macro is not specified, the system does not set any limits.2. The operator or a virtual machine, if the user directory for the virtual machinewas created with the IGNMAXU operand of the OPTION control statement, canlog on or be logged on by the AUTOLOG or XAUTOLOG command even if thenumber of logged on users is equal to or greater than the maximum user limit.ExamplesMigrationAidsTo set the limit to 9999, code the SYSMAXU macro as follows:SYSMAXU MAXUSERS=9999You can achieve the function of the SYSMAXU macroinstruction by using theFEATURES statement in a system configuration file. See “FEATURES Statement”on page 136.686 z/VM: CP Planning and Administration

SYSOPRSYSOPR (Required)►►labelSYSOPR(1)SYSOPER=OPERATORSYSOPER=userid,DISCOPER=YES,DISCOPER=NO►◄Notes:1 The SYSOPR and DISCOPER parameters may be specified in any order, but must be separatedwith a comma.PurposeCode the SYSOPR macroinstruction to specify the primary system operator’s userID and disconnect status. SYSOPR is required and must appear as one of the firstfive macroinstructions in HCPSYS ASSEMBLE.ParametersUsageNotesSYSOPER=OPERATORSYSOPER=useridis the primary system operator’s user ID. The variable userid is analphanumeric character string up to 8 characters long. If you do not code theSYSOPER operand, the user ID is automatically OPERATOR.DISCOPER=YESDISCOPER=NOindicates whether CP should disconnect the primary system operator when asoftware-initiated IPL occurs and the primary system operator is not logged ontothe primary system console.If you specify DISCOPER=YES, and the primary system operator is not loggedonto the primary system console when a software-initiated IPL occurs, CPdisconnects the primary system operator. If you specify DISCOPER=NO, CPdoes not force the primary system operator to be disconnected. If you do notcode the DISCOPER operand, YES is assumed.Specifying DISCOPER=NO has implications for system security. For moreinformation, see usage note 3.1. CP logs on a system operator with the user ID you specify on the SYSOPERoperand, regardless of whether that user ID has an entry in the user directory.2. If you do not code a SYSOPR macroinstruction in HCPSYS ASSEMBLE, atsystem initialization CP logs on a virtual machine with the user ID OPERATOR.3. If you specify DISCOPER=NO, CP allows the primary system operator toremain logged onto the primary system console after all software-initiated IPLs.This makes the primary system operator’s user ID available to any user withaccess to the primary system console, which could lead to a system-widecompromise of security. If you specify DISCOPER=NO, make sure that theprimary system console and all alternate system consoles are in a secureenvironment and are continuously monitored by authorized personnel.Appendix B. Defining Your System (HCPSYS Macroinstructions) 687

SYSOPR4. When the primary system operator logs off, the next user that logs on with atleast one of the privilege classes required for the system operator will becomethe primary system operator. However, this can be overridden by either:v specifying alternate operators using the ALTERNATE_OPERATORSstatement in the system configuration filev selecting a new operator using the SET SYSOPER command.For more information about the ALTERNATE_OPERATORS statement, see“ALTERNATE_OPERATORS Statement” on page 58.For more information on defining operator privilege class, see the“PRIV_CLASSES Statement” on page 184 or “SYSFCN (Optional)” on page673.ExamplesMigrationAids1. To specify OPERATOR as the user ID of the primary system operator andenable the disconnect function, code the SYSOPR macro as one of thefollowing:SYSOPRSYSOPR DISCOPER=YESSYSOPR SYSOPER=OPERATORSYSOPR SYSOPER=OPERATOR,DISCOPER=YES2. To specify OP as the user ID for the primary system operator and disable thedisconnect function, code the SYSOPR macro as follows:SYSOPR SYSOPER=OP,DISCOPER=NOYou can achieve the function of the SYSOPR macroinstruction by using theSYSTEM_USERIDS statement in a system configuration file. See“SYSTEM_USERIDS Statement” on page 232.688 z/VM: CP Planning and Administration

SYSOPTSSYSOPTS (Optional)►►labelSYSOPTS CPCHECKING= OFFONABEND(ON, )VMSTOPSENSE=YESNO►◄PurposeCode the SYSOPTS macroinstruction to specify initialization options for CP. Youcan specify whether CP should attempt to dynamically allocate device blocks fordevices not already defined in the system configuration file or HCPRIO.The SYSOPTS macroinstruction is optional; if you code it, you must place it inHCPSYS ASSEMBLE before the SYSEND macroinstruction.ParametersCPCHECKING=OFFIndicates that CP internal checking is to be deactivated.CPCHECKING=ONtells CP to activate CP internal checking to confirm the assertions established inCP code and take the appropriate action based on whether ABEND orVMSTOP is specified.CPCHECKING=(ON,ABEND)Indicates that an abend should occur. Whether it is a hard abend or a softabend is controlled by the specific assertion case. It is typically a hard abend.CPCHECKING=(ON,VMSTOP)This parameter is permitted only when CP is itself running in a virtual machine,and is generally useful only for debugging CP. Specifying this parameter causesCP to issue a Diagnose X'8' instruction when an untrue assertion isencountered, specifying a command string length of zero. This causes thevirtual machine to stop and for CP to post a read to the console. A message issent to the console (via a Diagnose X'8' MESSAGE * command) providinginformation about the cause of the stop.SENSE=YEStells CP to sense devices dynamically and build device definition blocks fordevices not already defined in the system configuration file or HCPRIO.SENSE=NOtells CP not to sense devices dynamically and tells CP to build device definitionblocks for only those devices explicitly defined in the system configuration fileusing RDEVICE statements or in HCPRIO using RDEVICE macroinstructions.UsageNotes1. If you do not specify the SYSOPTS macro, or if you specify the SYSOPTSmacro without specifying the SENSE option, CP’s default action for devices thatyou did not explicitly define in the system configuration file or in HCPRIOASSEMBLE is SENSE=YES.Appendix B. Defining Your System (HCPSYS Macroinstructions) 689

SYSOPTS2. If you specify SENSE=NO, you must explicitly define all the devices required atIPL time in either the system configuration file or in HCPRIO ASSEMBLE. If youdo not define the minimum number of required CP-owned volumes in thesystem configuration file or in HCPRIO ASSEMBLE, CP will end the IPL byloading a disabled wait state.3. Even if you specify SENSE=NO, you can use the SET RDEVICE command todefine new devices after you initialize CP. For more information about the SETRDEVICE command, see the z/VM: CP Commands and Utilities Reference.ExamplesMigrationAidsTo have CP build device blocks for devices that have not been defined in thesystem configuration file or in HCPRIO ASSEMBLE, code the SYSOPTS macro asfollows:SYSOPTS SENSE=YESThere is no equivalent statement in a system configuration file for the SYSOPTSmacroinstruction.690 z/VM: CP Planning and Administration

SYSPCLASSYSPCLAS (Optional)►►labelSYSPCLAS,►◄▼(c,’title’ ),TOP,BOTTOMPurposeCode the SYSPCLAS macro to specify the printed output classes that are tocontain classification titles. CP prints classification titles on the output separatorpage and optionally, at the top or bottom of each page of output. You can specify adifferent classification title for each class of output (A through Z, 0 through 9). TheSYSPCLAS macroinstruction is optional; if you code it, you must place it after thefirst five required macroinstructions in HCPSYS ASSEMBLE (SYSCPVOL,SYSOPR, SYSRES, SYSSTORE, and SYSTIME) but before the SYSENDmacroinstruction.You can specify the SYSPCLAS macro only once. If you omit the SYSPCLASmacro, or you code the macro with no operands, CP does not print anyclassification titles. If more than one print class is to have a classification title, theoperand should be repeated for each class. Each operand is separated by acomma.ParametersUsageNotesc is one alphanumeric character specifying the spool file class.titleis a classification title for this class. It may be up to 46 characters long. It mustbe enclosed in single quotation marks.TOPspecifies that this title is to be printed both on the separator page and at the topof each page of output.BOTTOMspecifies that this title is to be printed both on the separator page and at thebottom of each page of output.1. The title line is inserted at the top or bottom of each page. To do this, CP insertsa CCW to print one space, followed by the title line before or after each Skip toChannel 1 CCW issued by the operating system running in the virtual machinethat is printing the file. There are several implications to this:v The titles are inserted as the file is being created. If the file is later changedto a different class, the titles in the file are not changed. However, the title onthe separator page always reflects the true class of the file.v Inserting the title on the output page adds a line of output to the printed page.If the virtual machine application is counting lines, its count will be incorrect.This can produce blank pages within the output listing.Appendix B. Defining Your System (HCPSYS Macroinstructions) 691

SYSPCLASv If the operating system running in the virtual machine that is printing the filedoes not use Skip to Channel 1, the title lines are never printed.2. If you specify the same class more than once, CP prints only the first title youspecify.Examples1. If you do not want to have CP print classification titles, omit the SYSPCLASoperand or code it as follows:SYSPCLAS2. If you want CP to print the title “SPECIAL PRIORITY—TOP SECRET” on theseparator page of all class R output, code the SYSPCLAS macro as follows:SYSPCLAS (R,’SPECIAL PRIORITY -- TOP SECRET’)3. If you want CP to print the title “SPECIAL PRIORITY—TOP SECRET” on theseparator page and at the top of each page of all class N output, code theSYSPCLAS macro as follows:SYSPCLAS (N,’SPECIAL PRIORITY -- TOP SECRET’,TOP)4. If you want CP to (a) print the title “NO PRIORITY” on the separator page of allclass B output, (b) print the title “INTERNAL PRIORITY” on the separator pageand at the bottom of each page of all class N output, and (c) print the title“SPECIAL PRIORITY—TOP SECRET” on the separator page and at the top ofeach page of all class Q output, code the SYSPCLAS macro as follows:SYSPCLAS (B,’NO PRIORITY’,), *(N,’INTERNAL PRIORITY’,BOTTOM), *(Q,’SPECIAL PRIORITY -- TOP SECRET’,TOP)Note: If you need more than one line to code the SYSPCLAS macro, you mustcode a continuation character in column 72 and start the next line incolumn 16.MigrationAidsYou can achieve the function of the SYSPCLAS macroinstruction by using thePRINTER_TITLE statement in a system configuration file. See “PRINTER_TITLEStatement” on page 182.692 z/VM: CP Planning and Administration

SYSRESSYSRES (Required)►►labelSYSRES SYSVOL= volid*,SYSRES=dev ,SYSTYPE=devtype ►► ,SYSNUC=startloc(startloc ),nunits,SYSCKP=startloc(startloc ),nunits,volid,devtype►► ,SYSWRM=startloc(startloc ),nunits,volid,devtype,SYSCLR=NO,SYSCLR=YES►◄PurposeCode the SYSRES macroinstruction to describe the layout of the CP systemresidence disk. The SYSRES macroinstruction is required and must appear as oneof the first five macroinstructions in HCPSYS ASSEMBLE.Note: For information on how to calculate the values for the SYSCKP andSYSWRM operands, refer to Chapter 20, “Allocating DASD Space,” on page603.ParametersSYSVOL=volidSYSVOL=*is not used; code any 1-character to 6-character string.SYSRES=devis not used; code any 1-character to 4-character string.SYSTYPE=devtypeis not used; code any 4-character string.SYSNUC=startlocSYSNUC=(startloc,nunits)is not used; code any 1-character to 6-character string.SYSCKP=startlocSYSCKP=(startloc,nunits,volid,devtype)specifies the real starting location and, optionally, the maximum number of unitsthe checkpoint process uses to preserve system restart data.Note: This definition is overridden by the SYSTEM_RESIDENCE statement inthe system configuration file.The variable startloc is either the cylinder or page number that designates thereal starting location where the CP checkpoint information is to be saved. ForCKD device types, this value is a nonzero decimal cylinder number rangingfrom 1 to 65535. For FBA devices, this value is a 1-digit to 6-digit 4 KB pagenumber that is greater than 3 (pages 0-3 are reserved).Appendix B. Defining Your System (HCPSYS Macroinstructions) 693

SYSRESThe variable nunits is a number designating the maximum number of cylindersor 4 KB pages to be allocated for the checkpoint information area. For CKDdevice types, this must be a number from 1 to 9 that represents cylinders. ForFBA devices, this must be a number from 1 to 2000 that represents 4 KBpages. If you do not specify the nunits option, the default depends on thedevice type:Device Type Cylinders Pages3380 (emulated) 13390 (real or emulated) 1FBA (emulated) 100For information on calculating the size of the checkpoint area, refer to“Checkpoint Data” on page 607.The variable volid defines the volume label of the device to be used as theSYSCKP device. If not specified, it defaults to the system resident volume.The variable devtype is the device type of the checkpoint volume and must bespecified when the volume label is explicitly coded:v For a 3390 in native mode, specify 3390.v For a 3390 in 3380 track compatibility mode, specify 3380.v For a RAMAC ® or 2105 emulating a 3380, specify 3380.v For a RAMAC or 2105 emulating a 3390, specify 3390.v For a 2105 emulating a 9336, specify 9336 or the generic FB-512.SYSWRM=startlocSYSWRM=(startloc,nunits,volid,devtype)is the real starting location and, optionally, the maximum number of units to beused for saving warm start data.Note: This definition is overridden by the SYSTEM_RESIDENCE statement inthe system configuration file.The variable startloc is either the cylinder or page number that designates thereal starting location where the CP warm start information is to be saved. ForCKD device types, this value is a nonzero decimal cylinder number rangingfrom 1 to 65535. For FBA devices, this value is a 1-digit to 6-digit 4 KB pagenumber that is greater than 3 (pages 0-3 are reserved).The variable nunits is a number designating the maximum number of cylindersor 4 KB pages to be allocated for the warm start information area. For CKDdevice types, this must be a number from 1 to 9 that represents cylinders. ForFBA devices, this must be a number from 1 to 2000 that represents 4 KBpages. If you do not specify the nunits option, the default depends on thedevice type:Device Type Cylinders Pages3380 (emulated) 13390 (real or emulated) 1FBA (emulated) 75For information on calculating the size of the warm start area, refer to “WarmStart Data” on page 606.694 z/VM: CP Planning and Administration

SYSRESUsageNotesThe variable volid defines the volume label of the device to be used as theSYSWRM device. If not specified, it defaults to the system resident volume.The variable devtype is the device type of the warm start volume and must bespecified when the volume ID is explicitly coded:v For a 3390 in native mode, specify 3390.v For a 3390 in 3380 track compatibility mode, specify 3380.v For a RAMAC or 2105 emulating a 3380, specify 3380.v For a RAMAC or 2105 emulating a 3390, specify 3390.v For a 2105 emulating a 9336, specify 9336 or the generic FB-512.SYSCLR=YESSYSCLR=NOspecifies automatic clearing of all previously written data and directory areasthat are on TDISK DASD space. This prevents other users from accidentallyaccessing these areas. If YES is specified, TDISK DASD space is cleared tobinary zeros at CP initialization and when CP attaches a CP-owned volume thatcontains TDISK allocations. TDISK space is also cleared when a user detachesa TDISK minidisk. Specifying SYSCLR=YES provides additional security foryour VM/ESA installation. If you specify NO and the TDISK is a CKD device,the system clears only cylinder 0. If you specify NO and the TDISK is an FBAdevice, the system clears only the first two pages. The SYSCLR option is notrequired. The default is NO.Note: This setting is overridden by the CLEAR_TDISK setting on theFEATURES statement in the system configuration file.1. The SYSVOL=, SYSRES=, SYSTYPE=, and SYSNUC= parameters are notused because CP is IPLed from a module.2. The SYSCKP and SYSWRM areas must not overlap.3. When preparing a system residence device, be sure to format CP paging,spooling, dumping, directory, warm start, and checkpoint areas in 4 KB format.You can use the Device Support Facilities program (ICKDSF), or the CMS utilityCPFMTXA. However, ICKDSF is the preferred method of CP volumemaintenance and is invoked by CPFMTXA.4. You must specify the system residence volume identification for the checkpointarea and the warm start area on the SYSCPVOL macroinstruction. For moreinformation about the SYSCPVOL macroinstruction, see “SYSCPVOL(Required)” on page 664.5. You can query the current setting of the SYSCLR option by entering the QUERYTDISKCLR command.Examples1. The following example shows how to code the SYSRES instruction so that:v The warm start area begins at cylinder 204 and occupies one cylinder on the3390 DASD identified by SYS001.v The checkpoint area begins at page 101 and occupies 300 pages the 9336DASD identified by SYS002.v CP clears:– All TDISK space during system IPLAppendix B. Defining Your System (HCPSYS Macroinstructions) 695

SYSRES– All TDISK space after IPL whenever it attaches a DASD volume to thesystem for use as temporary disk space because of an ATTACH command– TDISK minidisks whenever they are detached from a guest virtualmachine because of a DETACH command.SYSRES SYSVOL=xxxxxx,SYSRES=xxxx,SYSTYPE=xxxx,SYSNUC=xxxxxx, *SYSWRM=(204,1,SYS001,3390),SYSCKP=(100,300,SYS002,9336), *SYSCLR=YESNote: If you need more than one line to code the SYSRES macro, you mustcode a continuation character in column 72 and start the next line incolumn 16.MigrationAidsYou can achieve the function of the SYSRES macroinstruction by using thefollowing statements in a system configuration file:v FEATURES—See “FEATURES Statement” on page 136.v SYSTEM_RESIDENCE—See “SYSTEM_RESIDENCE Statement” on page 230.696 z/VM: CP Planning and Administration

SYSSTORESYSSTORE (Required)►►labelSYSSTORERMSIZE=MAXRMSIZE=yyyyM,TRACE=nnnn►◄PurposeCode the SYSSTORE macroinstruction to configure the use of real storage. Thismacroinstruction is required and must appear as one of the first fivemacroinstructions in HCPSYS ASSEMBLE.ParametersRMSIZE=MAXtells CP to use the maximum available real storage that you have installed.Because CP no longer creates static storage management tables, you need notspecify the exact amount of storage to be used.RMSIZE=yyyyMspecifies the amount of real storage available for CP. If the actual amount ofreal machine storage is greater than RMSIZE, the storage available to CP willbe the RMSIZE value. If the actual amount of real machine storage is less thanRMSIZE, the system displays a message to the operator at initialization timestating the amount of storage available.The variable yyyy is a one- to four-digit decimal number that states the numberof megabytes (M) of real storage. The value of yyyy can range from 1 to 2048.One megabyte is 1,048,576 bytes.Notes:1. CP no longer creates storage management tables according to the RMSIZEoperand you specify. Instead, it builds the necessary storage managementat IPL time based on the maximum available amount of storage. Therefore,if you specify an RMSIZE value greater than the actual storage available,you will not waste storage.2. The maximum values you specify for the remaining operands aredetermined by the actual amount of real storage your system has, notnecessarily by the value you specify on the RMSIZE operand.TRACE=nnnnspecifies the decimal number of 4 KB pages CP allocates to the internal tracetable for each processor in the configuration. For example, if you run z/VM on auniprocessor and you specify TRACE=4, CP allocates 4 pages as the internaltrace table. If you run z/VM on a dyadic processor and you specify TRACE=4,CP allocates 8 pages as the internal trace table (4 pages for each processor).If you do not specify the TRACE operand, CP allocates to the internal tracetable 1 page for each 64 pages (256 KB) of real storage or 100 pages,whichever is smaller.The minimum value you can specify is TRACE=3; the maximum value must beless than or equal to 1/4 of RMSIZE. For example, if you specify RMSIZE=16m(4096 pages), then you must then specify TRACE as less than or equal to 448.Appendix B. Defining Your System (HCPSYS Macroinstructions) 697

SYSSTOREExamples1. To specify 16 MB of real storage and allow CP default values for the internaltrace table, code the SYSSTORE macro as follows:SYSSTORE RMSIZE=16MCP assigns 64 pages per processor for the internal trace table (1 page for each256 KB of real storage, or 4 pages for each MB).MigrationAidsYou can achieve the function of the SYSSTORE macroinstruction by using theSTORAGE statement in a system configuration file. See “STORAGE Statement” onpage 222.698 z/VM: CP Planning and Administration

SYSSYMPSYSSYMP (Optional)►►labelSYSSYMP USERID= OPERSYMPuserid(userid1,userid2)►◄PurposeCode the SYSSYMP macroinstruction to specify the user IDs of one or two virtualmachines for which the CP *SYMPTOM system service is to accumulate symptomrecords. When the virtual machines identified to CP connect to the CP *SYMPTOMsystem service, symptom records are sent to them.In addition, these virtual machines are automatically logged on during CPinitialization.The SYSSYMP macroinstruction is optional; if you code it, you must place it afterthe first five required macroinstructions in HCPSYS ASSEMBLE (SYSCPVOL,SYSOPR, SYSRES, SYSSTORE, and SYSTIME) but before the SYSENDmacroinstruction. If this macro is not coded, CP processes the virtual machinehaving the user ID OPERSYMP as the symptom record recording virtual machine.Note: Any virtual machine specified by the SYSSYMP macro must contain anIUCV directory control statement that authorizes the application running inthe virtual machine to connect to the CP *SYMPTOM system service. Failureto supply this required authority results in the failure of the connectionrequest from the virtual machine. If the RETRIEVE utility is used to collectsymptom records and this authority is not coded in the directory, RETRIEVEwill fail.ParametersUSERID=OPERSYMPUSERID=useridUSERID=(userid1,userid2)specifies the user IDs of virtual machines for which the CP *SYMPTOM systemservice is to accumulate and checkpoint symptom records. One or two user IDscan be specified. The user IDs are alphanumeric strings of up to 8 characterseach. OPERSYMP is the default user ID.UsageNotesIf the user ID specified on the SYSSYMP macroinstruction has an entry in the userdirectory at system initialization, the virtual machine designated by that user ID islogged on to the system.Examples1. To specify OPERSYMP as the user ID of the symptom record recording virtualmachine, you can do one of the following:v Omit the SYSSYMP macrov Code the SYSSYMP macro as follows:SYSSYMP USERID=OPERSYMPAppendix B. Defining Your System (HCPSYS Macroinstructions) 699

SYSSYMP2. To specify DISKSYMP as the user ID of the symptom record recording virtualmachine, code the SYSSYMP macro as follows:SYSSYMP USERID=DISKSYMP3. To specify OPERSYMP and DISKSYMP as the user IDs of the symptom recordrecording virtual machines, code the SYSSYMP macro as follows:SYSSYMP USERID=(OPERSYMP,DISKSYMP)MigrationAidsYou can achieve the function of the SYSSYMP macroinstruction by using theSYSTEM_USERIDS statement in a system configuration file. See“SYSTEM_USERIDS Statement” on page 232.700 z/VM: CP Planning and Administration

SYSTIMESYSTIME (Required)►►labelSYSTIME(1),ZONE=0,ZONE=dif,LOC=EAST,LOC=WEST,ID=GMT,ID=xxx►◄Notes:1 The following parameters can be specified in any order.PurposeCode the SYSTIME macroinstruction to generate information that CP needs to setthe hardware time of day (TOD) clock. The value stored in the TOD clock alwaysrepresents Coordinated Universal Time (UTC); the SYSTIME macroinstruction letsyou correct the value to local time. The SYSTIME macroinstruction is required andmust appear as one of the first five macroinstructions in HCPSYS ASSEMBLE.ParametersZONE=0ZONE=difis the time zone differential from Coordinated Universal Time (UTC). If you donot specify ZONE, CP uses a differential value of 0 hours from UTC.The value dif is the time zone differential specified in hours, minutes, andseconds (h,m,s). The form for dif can be:(h,m,s)(h,m)(h,,s)(,m,s)(,,s)(,m)hNote that h,m, and s are positional; if not specified, they must be replaced bycommas. If you code only hours, you do not have to use parentheses. Forinstance, you can specify ZONE=5, or ZONE=(7,30,30), or ZONE=(6,,30).The total value of dif cannot exceed 13 hours.LOC=EASTLOC=WESTspecifies whether the time zone differential is to be taken as EAST or WEST ofCoordinated Universal Time. EAST is the default. If the value of ZONE is 0, themacro definition ignores the setting of LOC.ID=GMTID=xxxis the name of the time zone. The default is GMT (Greenwich Mean Time). Thevalue xxx is a 3-character alphanumeric string.Appendix B. Defining Your System (HCPSYS Macroinstructions) 701

SYSTIMEExamples1. If your installation is in the Eastern Standard Time zone, code the SYSTIMEmacro as follows:SYSTIME ZONE=5,LOC=WEST,ID=EST2. If your installation is in the Pacific Standard Time zone, code the SYSTIMEmacro as follows:SYSTIME ZONE=8,LOC=WEST,ID=PSTMigrationAidsYou can achieve the function of the SYSTIME macroinstruction by using thefollowing statements in a system configuration file:v TIMEZONE_BOUNDARY—See “TIMEZONE_BOUNDARY Statement” on page237.v TIMEZONE_DEFINITION—See “TIMEZONE_DEFINITION Statement” on page239.702 z/VM: CP Planning and Administration

SYSUVOLSYSUVOL (Optional)►►labelSYSUVOL ▼ ,volid►◄PurposeCode the SYSUVOL macroinstruction to generate a list of user DASD volumes.(User volumes are those volumes you use to contain minidisks.) At system IPL, CPattaches the specified user volumes to the system but does not use them forpaging, spooling, directory, or temporary disk space. A volume must be attached tothe system before users can link to minidisks it contains.The SYSUVOL macroinstruction is optional; if you code it, you must place it afterthe first five required macroinstructions in HCPSYS ASSEMBLE (SYSCPVOL,SYSOPR, SYSRES, SYSSTORE, and SYSTIME) but before the SYSEND orCSESYS macroinstruction.Parametersvolidis the user volume identification. The variable volid is a 1- to 6-characteridentifier. Each character can be a letter, number, or hyphen.UsageNotes1. If you do not specify user volumes in the SYSUVOL macroinstruction, a volumecan nevertheless be attached to a virtual machine or system. Use the CPATTACH command to do so.2. If a volume is specified in the SYSUVOL macroinstruction but is not mountedwhen CP is loaded, CP considers that volume as unavailable. CP notifies theoperator that the volume is not mounted and continues processing, if possible.The system operator can mount and attach (ATTACH command) the volume tothe system when it is needed. This provides extra space for future growth.3. You can also define user volumes by specifying a generic volume identifier. Formore information, see “SYSINCL (Optional)” on page 680.4. When more than one DASD volume is found at system initialization (IPL) tohave the same volume serial (volid), and that volume serial is in the CP or uservolume list, the volume attached to the system is the one at the lowest devicenumber. This rule does not apply to duplicates of the system residence (IPLed)volume.ExamplesMigrationAidsTo specify UDSK1, UDSK2, and UDSK3 as user volumes, code the SYSUVOLmacro as follows:SYSUVOL UDSK1,UDSK2,UDSK3You can achieve the function of the SYSUVOL macroinstruction by using theUSER_VOLUME_LIST statement in a system configuration file. SeeAppendix B. Defining Your System (HCPSYS Macroinstructions) 703

SYSUVOL“USER_VOLUME_LIST Statement” on page 255.704 z/VM: CP Planning and Administration

Appendix C. Defining I/O Devices Using HCPRIOCoding HCPRIO ASSEMBLEThis appendix describes how to define your I/O devices to CP using the RDEVICEmacroinstruction in the real I/O configuration file (HCPRIO ASSEMBLE).Note: Now that z/VM uses device sensing to dynamically determine the devicecharacteristics, most devices no longer require an RDEVICEmacroinstruction to be coded in HCPRIO. However, some older devices don’tsupport device sensing and need to be explicitly defined in either the systemconfiguration file or HCPRIO. To determine if a given device can be definedin the system configuration file refer to Chapter 5, “Defining I/O Devices,” onpage 45. If the device is not listed in any of the configuration guide tables forthe system configuration file, then you must define this device in HCPRIO.Devices that are defined in HCPRIO are considered static definitions andcannot be changed with either the RDEVICE statement in the systemconfiguration file or the SET RDEVICE command.No additional device support is being provided in HCPRIO. New device support willonly be provided in the SYSTEM CONFIGURATION file.To define your installation’s real I/O configuration in the real I/O configuration file,HCPRIO ASSEMBLE, you must code macroinstructions in the file. HCPRIOASSEMBLE has two macroinstructions:RDEVICEUse this macroinstruction to define each real I/O device or group of I/Odevices in your installation’s I/O configuration.RIOGENUse this macroinstruction to end the HCPRIO assembly and to define yourinstallation’s primary and alternate system consoles.Note: On 3090 processor complexes, you must define the real I/O configurationto the hardware. This means that rdev will be device specific on theseprocessors. While the HCPRIO macroinstruction will assemble correctly withany real device number between X'0000' and X'FFFF', the input/outputconfiguration program (IOCP) for each processor has different restrictions.See the 3090 Input/Output Configuration Program User’s Guide andReference book.The following rules apply to the HCPRIO ASSEMBLE file.1. You may code the RDEVICE macroinstructions in any order. z/VM does notsupport multiple RDEVICE macroinstruction statements for a single physicaldevice.2. You can specify a maximum of 4096 devices for the real system.3. The RDEVICE macroinstruction definition ignores any labels that you specify onRDEVICE macroinstructions. The macro definition appends the device numberto the characters RDEV to generate its own label. For example, the macrodefinition generates the label RDEV0234 for device number 0234.4. You must code the RIOGEN macroinstruction last in HCPRIO ASSEMBLE.© Copyright IBM Corp. 1991, 2004 705

Defining I/O Devices5. You must not code START, CSECT, or END statements in the HCPRIOASSEMBLE—the macroinstruction expansions generate these records. If youcode these statements, an MNOTE is issued.6. Device initialization is started in the order listed in the HCPRIO, but each deviceis initialized asynchronously. This results in device initializations completing in adifferent order from that listed in the HCPRIO. If duplicate DASD volume labelsare in the HCPRIO, the volume with the lowest real device number is attachedto the system and brought online.7. You must be very careful when coding statements before the first RDEVICEmacroinstruction because many statements that may not generate code dogenerate implicit CSECT definitions that will cause problems later. SPACE,TITLE, EJECT, and COMMENT cards are always specifically allowed before thefirst RDEVICE macro.RDEVICEMacroinstructionsYou must code an RDEVICE macroinstruction for each real I/O device or group ofdevices in the real I/O configuration. During system initialization, CP brings onlineall devices you define in HCPRIO for which there are real counterparts. CP bringsDASDs online based on the lowest physical address.The general format of the RDEVICE macroinstruction is as follows:►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE=type,UIRATE=DEFAULT,UIRATE=INFINITYvalue►►options►◄706 z/VM: CP Planning and AdministrationDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies the real I/O device number you assign a device. Thevariable rdev must be a one- to four-digit hexadecimal number in the range 0through FFFF.DEVNO=(rdev,nnnn) specifies the real I/O device numbers you assign a rangeof devices. The variable rdev must be a one- to four-digit hexadecimal numberin the range 0 through FFFF. The variable nnnn is a decimal number that tellsCP to create a group of real device specifications with consecutive devicenumbers. For example, if you specify DEVNO=(0100,8), real device numbers0100, 0101, 0102, 0103, 0104, 0105, 0106, and 0107 are defined. The defaultvalue for nnnn is 1.DEVTYPE=typeDEVTYPE=type specifies the type of device.UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.

Defining I/O DevicesDEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.optionsoptions are device-specific options you specify for the device.RDEVICE—General Usage NotesDedicated AFP* Printers1. Appendix D, “Configuration Guide for Printers,” on page 769 lists according todevice:v The DEVTYPE operand you must specifyv Other required operands you must specifyv Optional operands you can specifyv The place in this chapter where coding of the RDEVICE macroinstruction forthat device is described.2. “Unsupported Devices” on page 763 describes how to code the RDEVICEmacroinstruction for any unsupported devices.3. Remember to code the RIOGEN macroinstruction at the end of your HCPRIOASSEMBLE file. See “RIOGEN” on page 766 for details on the RIOGENmacroinstruction.Appendix C. Defining I/O Devices Using HCPRIO 707

AFP PrintersCommon Control Unit (CCU) Printers►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE=AFP1,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄PurposeThe following printers are supported as advanced function printers using advancedfunction printing licensed programs:3825 3827 3828 3835 3900Note: Printers defined as advanced function printers that follow the CCUspecifications can be used only as dedicated devices. For information aboutprinters that follow CCU specifications, see the AFP Printer Information book.The printers listed above, that are useable only when dedicated, are Group 3printers.ParametersDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. It must be a one- to four-digithexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice control blocks with consecutive device numbers. The default value fornnn is 1.DEVTYPE=AFP1specifies an advanced function printer (AFP) that follows the CCU specification.Note that printers defined in this manner can only be used as dedicateddevices.UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.708 z/VM: CP Planning and Administration

AFP Printersvalue can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a Hot I/O conditionis detected.For more information about advanced function printers, see the PSF/VM SystemProgramming Guide.Usage Notes1. When the RDEVICE macro is used with DEVTYPE=AFP1 to define anadvanced function printer, only the DEVNO and DEVTYPE operand may bespecified.Examples1. To specify an advanced function printer at device number 0110, code theRDEVICE macro as follows:RDEVICE DEVNO=0110,DEVTYPE=AFP12. To specify three advanced function printers at device numbers 0111, 0112, and0113, code the RDEVICE macro as follows:RDEVICE DEVNO=(0111,3),DEVTYPE=AFP1Appendix C. Defining I/O Devices Using HCPRIO 709

AFP Printers3820 Printer►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE=3820,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄PurposeThe dedicated 3820 printers are defined using this RDEVICE format.ParametersDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. It must be a one- to four-digithexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice control blocks with consecutive device numbers. The default value fornnn is 1.DEVTYPE=3820specifies that a 3820 advanced function printer is being defined. Note thatprinters defined in this manner can be used only as dedicated devices.UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.Usage NotesWhen the RDEVICE macro is used with DEVTYPE=3820 to define a 3820 printer,only the DEVNO and DEVTYPE operand may be specified.Examples1. To specify a 3820 printer at device number 0110, code the RDEVICE macro asfollows:RDEVICE DEVNO=0110,DEVTYPE=3820710 z/VM: CP Planning and Administration

AFP Printers2. To specify three 3820 printers at device numbers 0111, 0112, and 0113, codethe RDEVICE macro as follows:RDEVICE DEVNO=(0111,3),DEVTYPE=3820Appendix C. Defining I/O Devices Using HCPRIO 711

Display PrintersPrinters Attached to a Display Control Unit712 z/VM: CP Planning and Administration

Display PrintersDisplay Printers►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE= 3286328732883289,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄PurposeThe following display printers are supported (display printers are printers that allowkey-operator-initiated copy only):3262 3287 3812 1 24224 13268 3288 3816 1 24234 13286 3289 4214 424552106262Notes:1. Supported as advanced function printers using Print Services Facility/VirtualMachine (PSF/VM), Program Number 5684-141.2. You can download fonts using PSF/VM.ParametersDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. It must be a one- to four-digithexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice control blocks with consecutive device numbers. The default value fornnn is 1.DEVTYPE=3286DEVTYPE=3287DEVTYPE=3288DEVTYPE=3289specifies the type of device (3286, 3287, 3288, or 3289).Other display printers supported are the 3262, 3268, 3812, 3816, 4214, 4224,4234, 4245, 5210, and 6262. For these printers, however, DEVTYPE must becoded as 3287.UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.Appendix C. Defining I/O Devices Using HCPRIO 713

Display PrintersATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.Examples1. To specify three 3286 display printers, at device numbers 0171, 0172, and0173, code the RDEVICE macro as follows:RDEVICE DEVNO=(0171,3),DEVTYPE=32862. To specify a 3262 or 3268 display printer at device number 0174, code theRDEVICE macro as follows:RDEVICE DEVNO=0174,DEVTYPE=32873. To specify a 3288 display line printer at device number 0180, code theRDEVICE macro as follows:RDEVICE DEVNO=0180,DEVTYPE=32884. To specify 3289 display line printers at device numbers 0181, 0182, and 0183,code the RDEVICE macro as follows:RDEVICE DEVNO=(0181,3),DEVTYPE=32895. To specify a 4234 display line printer at device number 0184, code theRDEVICE macro as follows:RDEVICE DEVNO=0184,DEVTYPE=3287714 z/VM: CP Planning and Administration

Impact PrintersCP System-Managed Impact PrintersAppendix C. Defining I/O Devices Using HCPRIO 715

Impact PrintersImpact Printers►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE=3203,MODEL=532113262 ,MODEL=n42454248(1)►►,AFP=YES,AFP=NO (2),CHARS=ucsname,CLASS=A,CLASS=,(3)▼ cl( )(4)NONE*►►,DEST=OFF,DEST=,(3)▼ dest( )*,FCB=fcbname (2),FEATURE=UNVCHSET►►,FOLD=NO,FOLD=YES,FORM=STANDARD,FORM=operform*,IMAGE=imagelib,INDEX=1(5),INDEX=nn,SEP=YES,SEP=NO►►,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄Notes:1 The following parameters can be specified in any order.2 The CHARS and FEATURE parameters can be specified for only 3203 and 3211 printers.3 The left and right parentheses are required if you are coding more than one cl or dest, optional ifcoding one cl or dest.4 If you specify CLASS=NONE (meaning that the printer is to be dedicated to a virtual machine),you cannot specify the AFP, CHARS, FCB, FEATURE, FOLD, FORM, and SEP parameters.5 The INDEX parameter can be specified for only 3211 printers.PurposeThe CP system-managed 3203, 3211, 3262, 4245, 4248, and 6262 impact printersare defined using this RDEVICE format.ParametersDEVNO=rdev716 z/VM: CP Planning and Administration

Impact PrintersDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. It must be a one- to four-digithexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice control blocks with consecutive device numbers. The default value fornnn is 1.DEVTYPE=devtypespecifies the device type and model.Notes:1. The default is MODEL=5 for the 3262, and MODEL=1 for the 4245 and the4248.2. Although the 4248 Model 2 is supported, it must be specified as MODEL=1.3. The 3262 Model 5 is supported as a 3262 or in 4248-compatibility mode.Specify it as a 4248 when it is used in 4248-compatibility mode.4. The 4245 Model 1 is supported as a 4245 or in 3262-compatibility mode.Specify it as a 3262 MODEL=5 when it is used in 3262-compatibility mode.5. The 4248 Models 1 and 2 are supported as 4248s or in 3211-compatibilitymode. Specify it as a 3211 when it is used in 3211-compatibility mode.6. The 6262 Model 14 must be specified as a 4248 MODEL=1.7. The 6262 Model 22 must be specified as a 4248 MODEL=1.AFP=YESAFP=NOspecifies whether the printer is to process files with advanced function printer(AFP) characteristics, XABs, or X'5A' CCWs. The default is YES.CHARS=ucsnameFor a printer with the UNVCHSET feature, CHARS=ucsname specifies the 1- to4-character suffix of the name of the default universal character set (UCS)buffer image to be used. The variable ucsname must correspond to one of theUCS images stored in the image library. For example, if you specify:RDEVICE DEVNO=0003,DEVTYPE=3203,CHARS=ANThe image library must contain a member named 3203AN.CLass=clCLass=ACLass=*CLass=NONEspecifies the output spooling class(es) the printer can print. (To change thespooling classes without recoding and reassembling the HCPRIO file, use theCP START command.)You can specify CLASS in one of the following ways:v If you omit the CLASS parameter, class A is assumed by default.v CLASS=cl,... to list up to eight output spooling classes, separated bycommas. The spooling class, cl, is one alphanumeric character. If you codeonly one spooling class, you do not have to use parentheses. For example,you can specify multiple classes as CLASS=(A,B,C) and a single class asCLASS=A or CLASS=(A).v CLASS=NONE specifies that CP will not use the printer for spooling.v CLASS=* specifies that the printer processes files regardless of class.Appendix C. Defining I/O Devices Using HCPRIO 717

Impact PrintersNote: If you specify CLASS=NONE (meaning that the printer is to be dedicatedto a virtual machine), you cannot specify the AFP, CHARS, FCB,FEATURE, FOLD, FORM, and SEP parameters.DEST=destDEST=OFFDEST=*specifies the output destination value(s) the printer can print. (To change thespooling destination values without having to recode and reassemble theHCPRIO file, use the CP START command.)You can specify DEST in one of the following ways:v By default—if you omit the DEST parameter, DEST OFF is assumed.v DEST=dest,...—to list up to four output destination values, separated bycommas. Each value, dest, is one to eight alphanumeric characters in length.If you code more than one destination, you must use parentheses. Forexample, you can specify multiple destinations as:DEST=(FLOOR3,SOUTH3RD,PERCIVAL)When you code only one destination, parentheses are not necessary. Forexample:DEST=FLOOR3v DEST=*—specifies that the printer processes files regardless of destination.FCB=fcbnamespecifies the 1- to 4-character suffix of the name of the default forms controlbuffer (FCB) image to be used after a cold start or force start. This mustcorrespond to one of the forms control buffer images added to an image library.For example, if you specify:RDEVICE DEVNO=0008,DEVTYPE=4248,FCB=FCB8the image library must contain a member named 4248FCB8.FEATURE=UNVCHSETspecifies that the printer is a universal character set printer.FEATURE=UNVCHSET can be specified only for 3203 and 3211 printers.FOLD=NOFOLD=Yesspecifies whether lowercase should be folded (translated) into uppercase. Thedefault is NO.FORM=operformFORM=*FORM=STANDARDis the current spooling form number that the printer can process. This formimplicitly determines the default operator form for the real printer when theoperator starts the device after a cold start without specifying a form. Specifythis parameter in one of the following ways:v FORM=STANDARD, where STANDARD indicates that the type of paper tobe mounted on the printer is the type of paper that the installation hasassigned the name STANDARD. The default value is FORM=STANDARD.v FORM=operform, where operform specifies a 1- to 8-character operator formnumber for the files the printer can process.v FORM=*, where the asterisk specifies that the printer can process filesregardless of form number.718 z/VM: CP Planning and Administration

Impact PrintersEach installation establishes its own set of form names, assigns those formnames to types of paper, and informs the operations staff and end users of thecorrelation between form names and types of paper.IMAGE=imagelibspecifies the image library to be used after a cold start. The default isIMAGnnnn, where nnnn is the device type number.INDEX=nnINDEX=1specifies the position at which to start printing, where nn can be from 1 to 31, 1being the default. This parameter is only for devices that emulate the 3211.SEP=YESSEP=NOspecifies whether a separator is desired for output files. The default is YES.UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.Examples1. To specify a 3203 printer at device number 0110 that prints only class A spoolfiles (the default value), code the RDEVICE macro as follows:RDEVICE DEVNO=0110,DEVTYPE=3203,MODEL=52. To specify three 4245 printers at device numbers 0111, 0112, and 0113 that arenot to be used to print spool files, code the RDEVICE macro as follows:RDEVICE DEVNO=(0111,3),DEVTYPE=4245,CLASS=NONE3. To specify a 3262 printer at device number 0110 that prints only class A spoolfiles (the default value), code the RDEVICE macro as follows:RDEVICE DEVNO=0110,DEVTYPE=3262,MODEL=5Appendix C. Defining I/O Devices Using HCPRIO 719

3800 PrintersCP System-Managed 3800 Printers720 z/VM: CP Planning and Administration

3800 Printers3800 Printer►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE=3800,MODEL=1,MODEL=3,MODEL=8(1) (2)►►,AFP=YES,AFP=NO,CHARS=ffff,CLASS=A,►,CLASS=▼ cl(3) )((4)NONE*►,DEST=OFF,,DPMSIZE=1,DPMSIZE=n,FCB=6,FCB=lpi,FEATURE=4WCGMS►,DEST=▼ dest(3) )(*►,FLASH=flashlib,FORM=STANDARD,FORM=operform*,IMAGE=IMAG3800,IMAGE=imagelib,SEP=YES,SEP=NO►►,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄Notes:1 If you specify MODEL=8, you cannot specify the AFP, CHARS, CLASS, DEST, DPMSIZE, FCB,FLASH, FORM, IMAGE, and SEP parameters.2 The following parameters can be specified in any order.3 The left and right parentheses are required if you are coding more than one cl or dest, optional ifcoding one cl or dest.4 If you specify CLASS=NONE (meaning that the printer is to be dedicated to a virtual machine),you cannot specify the AFP, CHARS, DEST, DPMSIZE, FCB, FEATURE, FLASH, FORM, IMAGE,and SEP parameters.PurposeUse this RDEVICE format to define the CP system-managed 3800 printers.Appendix C. Defining I/O Devices Using HCPRIO 721

3800 PrintersParametersDEVNO=rdevspecifies a real I/O device number. The variable rdev must be a 1- to 4-digithexadecimal number from X'0000' to X'FFFF'.DEVNO=(rdev,nnn)specifies the real I/O device numbers for a range of devices. The variable nnnis a decimal repetition count and creates a group of real device control blockswith consecutive device numbers. The default is 1.DEVTYPE=3800specifies the device type.MODEL=1MODEL=3MODEL=8specifies the model number of the 3800 printer. The default is 1.Notes:722 z/VM: CP Planning and Administration1. The 3800 Models 3 and 6 are supported in Model 1 compatibility mode,defined as a Model 1, or by using the Advanced Function Printinglicensed program, defined as a Model 3. If you are using them asadvanced function printers, code AFP=YES.2. The 3800 Model 8 is supported using an Advanced Function Printinglicensed program; code AFP=YES.3. If you specify MODEL=8, you cannot specify the following parameters:AFP, CHARS, CLASS, DEST, DPMSIZE, FCB, FLASH, FORM, IMAGE,and SEP.AFP=YESAFP=NOspecifies whether the printer is to process files with advanced function printer(AFP) characteristics, XABs, or X'5A' CCWs. The default is YES.Note: If you specify MODEL=8 or CLASS=NONE, you cannot specify AFP.CHARS=ffffspecifies the name of a character-arrangement table for the separator page tobe used after a cold start. The default values for 3800 printers are:For Model 1, CHARS=GF10.For Model 3 or Model 6, CHARS=GF12.Note: If you specify MODEL=8 or CLASS=NONE, you cannot specify CHARS.CLASS=clCLASS=NONECLASS=*specifies the output spooling class or classes the 3800 Model 1, Model 3, orModel 6 printer can print. (To change the spooling classes without having torecode and reassemble the HCPRIO file, use the CP START UR command.)You can specify CLASS in one of the following ways:v If you omit CLASS, the default is class A.v CLASS=cl,... to list up to eight output spooling classes, separated bycommas. The spooling class, cl, is one alphanumeric character. If you codeonly one spooling class, you do not have to use parentheses. For example,you can specify multiple classes as CLASS=(A,B,C) and a single class asCLASS=A or CLASS=(A).

3800 Printersv CLASS=NONE specifies that CP will not use the printer for spooling.v CLASS=* specifies that the 3800 processes files regardless of class.Notes:1. If you specify MODEL=8, you cannot specify CLASS.2. If you specify CLASS=NONE (meaning that the 3800 is to be dedicated to avirtual machine), you cannot specify the following parameters: AFP, CHARS,DEST, DPMSIZE, FCB, FEATURE, FLASH, FORM, IMAGE, and SEP.DEST=OFFDEST=destDEST=*specifies the output destination value or values the 3800 Model 1, Model 3, orModel 6 printer can print. (To change the spooling destination values withouthaving to recode and reassemble the HCPRIO file, use the CP START URcommand.)You can specify DEST in one of the following ways:v If you omit DEST, the default is OFF. A 3800 with DEST set to OFF will onlyprocess files with DEST specifically set to, or defaulted to, OFF.v DEST=dest,... to list up to four output destinations, separated by commas.The destination value, dest, is a 1- to 8-character alphanumeric string. If youcode only one destination, you do not have to use parentheses. For example,you can specify multiple destinations asDEST=(FLOOR3,SOUTH3RD,PERCIVAL) and a single destination asDEST=FLOOR3.v DEST=* specifies that the 3800 processes files regardless of destination.Note: If you specify MODEL=8 or CLASS=NONE, you cannot specify DEST.DPMSIZE=nspecifies the maximum size of the delayed purge queue (see note 1) that the3800 Model 1, Model 3, or Model 6 printer uses after a cold start. The defaultvalue for n is 1, the maximum, 9.Notes:1. After the 3800 prints a file, CP places the file on the delayed purge queue.CP puts all files on the delayed purge queue in system hold status. Whenthe queue is full, CP purges the oldest file. This delay helps ensure that the3800 (a) transfers the last page of the file from the page buffer in the 3800printer to paper and (b) stacks the printed page.2. If you specify MODEL=8 or CLASS=NONE, you cannot specify DPMSIZE.3. Specifying 0 for DPMSIZE saves some spool DASD space because filesprinted on the 3800 are purged immediately. However, this decreases thepossibility of recovering a printer file which has failed during printing.FCB=lpispecifies the name of the forms control buffer for the separator page to be usedafter a cold start. Note that you can override this value by naming a formscontrol buffer on the CP START UR command. The default value for lpi is 6.Note: If you specify MODEL=8 or CLASS=NONE, you cannot specify FCB.FEATURE=4WCGMSspecifies that the 3800 has the 4-writable-character generation module feature.For a 3800 model 1, the default is 2WCGMS. For a 3800 model 3 and model 8,the default is 4WCGMS.Appendix C. Defining I/O Devices Using HCPRIO 723

3800 PrintersNote: If you specify CLASS=NONE, you cannot specify FEATURE.FLASH=flashlibspecifies the flash overlay for use with this device.Note: If you specify MODEL=8 or CLASS=NONE, you cannot specify FLASH.FORM=STANDARDFORM=operformFORM=*is the current spooling form number that the printer can process. This formimplicitly determines the default operator form for the real printer when theoperator starts the device after a cold start without specifying a form.You can specify FORM in one of the following ways:v FORM=STANDARD, where STANDARD indicates that the type of paper tobe mounted on the printer is the type of paper that the installation hasassigned the name STANDARD. Each installation establishes its own set ofform names, assigns those form names to types of paper, and informs theoperations staff and end users of the correlation between form names andtypes of paper. The default is STANDARD.v FORM=operform to specify a 1- to 8-character operator form number for thefiles the printer can process.v FORM=* specifies that the printer can process files regardless of formnumber.Note: If you specify MODEL=8 or CLASS=NONE, you cannot specifyFORM.IMAGE=IMAG3800IMAGE=imagelibspecifies the name of the image library to be used after a cold start. Note thatyou can override this value by specifying an image library name on the CPSTART UR command. The default is IMAG3800.Note: If you specify MODEL=8 or CLASS=NONE, you cannot specify IMAGE.SEP=YESSEP=NOtells CP whether the printer should use a separator page between output files.The default is YES.Note: If you specify MODEL=8 or CLASS=NONE, you cannot specify SEP.UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP from724 z/VM: CP Planning and Administration

3800 Printersbroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.Examples1. To specify a Model 3 3800 printer at device number 0500 that is to be dedicatedto a virtual machine, use the following RDEVICE macroinstruction:RDEVICE DEVNO=0500,DEVTYPE=3800,MODEL=3,CLASS=NONE2. To specify three Model 8 3800 printers at device numbers 0501, 0502, and 0503that are to be dedicated to virtual machines, use the following RDEVICEmacroinstruction:RDEVICE DEVNO=(0501,3),DEVTYPE=3800,MODEL=83. To specify a Model 1 3800 printer at device number 0505 that has all of thefollowing characteristics:v Is to be used to print spool filesv Prints any class spool filesv Has the 4-writable-character generation module (WCGM) featurev Has a delayed purge queue length of 5use the following RDEVICE macroinstruction:RDEVICE DEVNO=0505,DEVTYPE=3800,MODEL=1,CLASS=*, *FEATURE=4WCGMS,DPMSIZE=5Note: If you need more than one line to code the RDEVICE macroinstruction,you must code a continuation character in column 72 and start the nextline in column 16.Appendix C. Defining I/O Devices Using HCPRIO 725

Unit Record DevicesUnit Record Devices726 z/VM: CP Planning and Administration

Unit Record Devices3505 Card Reader►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE=3505,CLASS=A,CLASS=clNONE►►,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄ParametersDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. It must be a one- to four-digithexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice control blocks with consecutive device numbers. The default value fornnn is 1.DEVTYPE=3505specifies the type of device (3505).CLASS=clCLASS=ACLASS=NONEspecifies the spooling class the card reader assigns to spool files it creates. (Tochange the spooling class the card reader assigns without recoding andreassembling the HCPRIO file, use the CP START command.)You can specify CLASS in one of the following ways:v If you omit the CLASS operand, class A is assumed by default.v CLASS=cl, where the spooling class, cl, is one alphanumeric character.v CLASS=NONE to specify that CP will not use the card reader for spooling.UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.Appendix C. Defining I/O Devices Using HCPRIO 727

Unit Record Devicesvalue can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.Examples1. To specify three 3505 card readers at device numbers 00C1, 00C2, and 00C3that are not to be used to read spool files, code the RDEVICE macro as follows:RDEVICE DEVNO=(00C1,3),DEVTYPE=3505,CLASS=NONE2. To specify a 3505 card reader at device number 00C4 that reads information inas class R spool files, code the RDEVICE macro as follows:RDEVICE DEVNO=00C4,DEVTYPE=3505,CLASS=R728 z/VM: CP Planning and Administration

Unit Record Devices3525 Card Punch►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE=3525(1)►►,CLASS=A,CLASS=▼ cl(2) )((3)NONE,,FORM=STANDARD,FORM=operform*,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄Notes:1 The following parameters may be specified in any order.2 The left and right parentheses are required if you are coding more than one cl or optional if codingone cl.3 If you specify CLASS=NONE (meaning that the punch is to be dedicated to a virtual machine),you cannot specify the FORM parameter.ParametersDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. It must be a one- to four-digithexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice control blocks with consecutive device numbers. The default value fornnn is 1.DEVTYPE=3525specifies the type of device (3525). Note that the 3525 is supported only forpunching; the printing features are not supported.CLASS=(cl)CLASS=ACLASS=*CLASS=NONEspecifies the output spooling classes. (To change these spooling classeswithout recoding and reassembling the HCPRIO file, use the CP STARTcommand.)You can specify CLASS in one of the following ways:v If you omit the CLASS operand, class A is assumed by default.v CLASS=cl to list up to eight output spooling classes, separated by commas.The spooling class, cl, is one alphanumeric character. If you code only onespooling class, you do not have to use parentheses. For example, you canspecify multiple classes as CLASS=(A,B,C) and a single class as CLASS=Aor CLASS=(A).Appendix C. Defining I/O Devices Using HCPRIO 729

Unit Record Devicesv CLASS=NONE specifies that CP will not use the card punch for spooling.v CLASS=* specifies that the punch can process files regardless of class.Note: If you specify CLASS=NONE (meaning that the punch is to be dedicatedto a virtual machine), you cannot specify the FORM operand.FORM=operformFORM=*FORM=STANDARDis the current spooling form number that the punch can process. This formimplicitly determines the default operator form for the real punch when theoperator starts the device after a cold start without specifying a form. Specifythis operand in one of the following ways:v FORM=operform, where operform specifies a 1- to 8-character operator formnumber for the files the punch can process.v FORM=*, where the asterisk specifies that the punch can process filesregardless of form number.v Do not specify FORM. The default value is FORM=STANDARD.UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.Examples1. To specify a 3525 punch at device number 00D0 that punches only class Aspool files (the default value), code the RDEVICE macro as follows:RDEVICE DEVNO=00D0,DEVTYPE=35252. To specify three 3525 punches at device numbers 00D1, 00D2, and 00D3 thatare not to be used to punch spool files, code the RDEVICE macro as follows:RDEVICE DEVNO=(00D1,3),DEVTYPE=3525,CLASS=NONE3. To specify a 3525 punch at device number 00D4 that punches class E, F, and Gspool files, code the RDEVICE macro as follows:RDEVICE DEVNO=00D4,DEVTYPE=3525,CLASS=(E,F,G)730 z/VM: CP Planning and Administration

Unit Record Devices3890 Document Processor►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE=3890,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄PurposeThe 3890 Document Processor is supported as a dedicated-only device.ParametersDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. The variable rdev must be aone- to four-digit hexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice control blocks with consecutive device numbers. The default value fornnn is 1.DEVTYPE=3890specifies the type of device (3890).UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.ExamplesTo specify a 3890 document processor at device number 100,RDEVICE DEVNO=(100),DEVTYPE=3890Appendix C. Defining I/O Devices Using HCPRIO 731

Display Terminals and AdaptersDisplay Terminals and Adapters732 z/VM: CP Planning and Administration

Display Terminals and Adapters3250 Display►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE=3250,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄PurposeThe 3250 is supported as a dedicated-only device.ParametersDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. The variable rdev must be aone- to four-digit hexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice control blocks with consecutive device numbers. The default value fornnn is 1.DEVTYPE=3250specifies the type of device (3250).UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.Examples1. To specify a 3250 display at device number 0006, code the RDEVICE macro asfollows: RDEVICE DEVNO=0006,DEVTYPE=32502. To specify three 3250 displays at device numbers 0007, 0008, and 0009, codethe RDEVICE macro as follows: RDEVICE DEVNO=(007,3),DEVTYPE=3250Appendix C. Defining I/O Devices Using HCPRIO 733

Display Terminals and Adapters3270-Family Displays►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE= 31903290,MODEL=231783179 ,MODEL=modelno31803270327732783279►►,FEATURE=OPRDREMUL3270(OPRDR,EMUL3270)(EMUL3270,E3270HLD)(OPRDR,EMUL3270,E3270HLD),UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄ParametersDEVNO=rdevis the real I/O device number. The variable rdev must be a 1- to 4-digithexadecimal number from X'0000' to X'FFFF'.DEVNO=(rdev,nnn)are the real I/O device numbers for a range of devices. The variable rdev mustbe a 1- to 4-digit hexadecimal number from X'0000' to X'FFFF'. The variablennn is a decimal repetition count and creates a group of real device controlblocks with consecutive device numbers. If omitted, the default for nnn is 1.DEVTYPE=devtypeis the type of device. Valid device types are: 3178, 3179, 3180, 3190, 3270,3277, 3278, 3279, or 3290. However, CP only recognizes two categories ofdisplay devices, 3277 and all others. The 3277 must be specified as a 3277;other device types may be specified as any of the other valid device types. Forexample, a 3191 display could be specified as a 3270, a 3190, or any othervalid device number, except 3277.Notes:1. The 3270-PC is supported in control-unit terminal mode anddistributed-function terminal (DTF) mode when defined as a 3270.2. The 3101 must be connected to a 7171 Control Unit. You must also specifyFEATURE=EMUL3270.3. If you want to see what other displays are supported, see the z/VM: GeneralInformation book, which lists all displays supported for this release.MODEL=modelno (do not specify for a 3190 or 3290)specifies the model number which determines the display screen format. Ifomitted, the default is 2. Note that CP determines the real size of the screenwhen the terminal is powered-on or enabled. Table 35 on page 735 shows theoptions. (Also see Usage Note 2 on page 736.)734 z/VM: CP Planning and Administration

Display Terminals and AdaptersTable 35. Model Options Depending on Screen SizeModel(modelno)Number ofCharactersScreenSize Valid for DEVTYPE=2 1920 24 x 80 3178, 3179, 3180, 3191, 3192, 3193,3194, 3270, 3277, 3278, 32792A 1600 20 x 80 3270, 32782C 1600 20 x 80 3270, 32793 2560 32 x 80 3178, 3179, 3180, 3192, 3193, 3270,3278, 32794 3440 43 x 80 3178, 3180, 3192, 3193, 3270, 32785 3564 27 x 132 3178, 3180, 3270, 3278The model number is set to 2 if the terminal is attached to a 7171 DeviceAttachment Control Unit or ASCII Subsystem (EMUL3270 is specified).FEATURE=specifies one to three display features. The features can be coded in any order.If you specify more than one feature, you must separate the features with acomma and surround them by parenthesis. The features are:OPRDRspecifies an operator identification card reader on a 327X display. If youspecify FEATURE=OPRDR, the virtual machine operator can gain access tothe system (log on) only by inserting a magnetically encoded card. Usingthe badge reader is optional for each user ID and not required. It cannot beused instead of a correct password but may be used after a correctpassword is supplied for an additional security measure. If you do not wantaccess authorization by a card reader, do not code FEATURE=OPRDR.EMUL3270specifies that the device is a TTY ASCII display terminal connected to thesystem through a 7171 ASCII DACU or ASCII Subsystem (an emulated3270).E3270HLDspecifies that the display terminal telecommunications connection to the7171 ASCII DACU or ASCII Subsystem is to remain after logging off ordisconnecting. E3270HLD is valid only if EMUL3270 is also coded.UIRATE=This optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.Appendix C. Defining I/O Devices Using HCPRIO 735

Display Terminals and AdaptersUsage Notes1. If you specify DEVTYPE=3270, device type 3278 is generated in the HCPRIOfile. All device types except for the 3277 are equivalent to device type 3278.2. The MODEL=modelno is optional. If not specified, MODEL=2 is the default.Otherwise, the model specified is generated. The actual value of MODEL isdetermined by CP during display initialization and is set accordingly. TheMODEL parameter is used when CP cannot determine the real devicecharacteristics.Note that for the RDEVICE macro, the model number refers to the displayscreen format as shown in Table 35 on page 735. The model number, asspecified on the RDEVICE statement, may or may not correspond to the modelnumber on the display itself. MODEL defaults to 2 if the screen size does notmatch 2A, 2C, 3, 4, or 5.For example, a 3192 that has the same screen size as a 3278 Model 2 can begenerated that way or it can be generated as a 3190 (with no model specified).A 3192 that is the same size as a 3278 Model 3 should be generated that wayor as a 3190 (with no model specified).A 3192 that is the same size as a 3278 Model 4 should be generated that wayor as a 3190 (with no model specified).All of the above is true for 3191, 3192, 3193, and 3194.The RDEVICE macroinstruction only accepts models types of 2, 3, 4, 5, 2A, or2C. Other model types that are supported for various terminal types include:3178 C1,C2,C3,C43179 1,G1,G23180 13279 2B,2X,3A,...3290 220,230,T30These terminals and models are supported but can only be coded as modeltypes 2, 3, 4, 5, 2A, or 2C. However, when they are logged on to, CPdetermines the real size of the screen and uses it.3. You must ensure that the device numbers specified by the DEVNO parametercorrespond to the device numbers required for that category of display terminalin the controller.4. Refer to the 7171 ASCII Device Attachment Control Unit Description andPlanning Guide to determine which type of device (DEVTYPE) to code for aTTY ASCII terminal attached to a 7171 DACU or ASCII Subsystem.Examples1. To specify a 3277 display at device number 0140, code the RDEVICEmacroinstruction as follows:RDEVICE DEVNO=0140,DEVTYPE=32772. To specify Model 2A 3278 displays at device numbers 0141, 0142, and 0143that do use the operator identification card reader, code one of the followingRDEVICE macroinstructions:RDEVICE DEVNO=(0141,3),DEVTYPE=3278,MODEL=2A,FEATURE=OPRDRRDEVICE DEVNO=(141,3),DEVTYPE=3278, FEATURE=OPRDR3. To specify a 3279 Model 3 display device number 0144 that does not use theoperator identification card reader, code the RDEVICE macroinstruction asfollows:RDEVICE DEVNO=0144,DEVTYPE=3279,MODEL=3736 z/VM: CP Planning and Administration

Display Terminals and Adapters4. To specify a 3180 Model 1 display with a screen format of 43 by 80, code theRDEVICE macroinstruction as follows:RDEVICE DEVNO=0145,DEVTYPE=3278,MODEL=45. To specify a 3179 Model 1 display, code the RDEVICE macroinstruction asfollows:RDEVICE DEVNO=0146,DEVTYPE=3279,MODEL=26. To specify a 3290 display at device number 0145, code the RDEVICEmacroinstruction as follows:RDEVICE DEVNO=0145,DEVTYPE=32907. To specify a series of 3278 or 3279 displays that are a variety of models,beginning at device number 2C0, code the RDEVICE macroinstruction asfollows:RDEVICE DEVNO=(2C0,8),DEVTYPE=32708. To specify a TTY device attached to a 7171 DACU or ASCII Subsystem atdevice number FE0 that emulates a 3278 and to which the telecommunicationline is always held, code the RDEVICE macroinstruction as follows:RDEVICE DEVNO=FE0,DEVTYPE=3278,FEATURE=(EMUL3270,E3270HLD)9. To specify a TTY device attached to a 7171 DACU or ASCII Subsystem atdevice number 220 that emulates a 3277 and for which the user controls theholding of the telecommunication line, code the RDEVICE macroinstruction asfollows:RDEVICE DEVNO=220,DEVTYPE=3277,FEATURE=EMUL3270Appendix C. Defining I/O Devices Using HCPRIO 737

Display Terminals and AdaptersTeleprocessing Integrated Adapters►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE=ICA ,ADAPTER= ELANHDLCILANTELE2►►,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄ParametersDEVNO=rdevDEVNO=(rdev,nnn)specifies a real I/O device number or numbers. The variable rdev must be a 1-to 4-digit hexadecimal number in the range X'0000' through X'FFFF'. If you arespecifying a range of devices using DEVNO=(rdev,nnn), rdev is the first real I/Odevice in the range and nnn is a decimal number indicating the total number ofconsecutive devices. The default for nnn is 1.DEVTYPE=ICAtells CP that the device is an integrated communication adapter.ADAPTER=tells CP what teleprocessing protocol being defined. The valid protocols andtheir meanings are:ELAN802.3 local area networkHDLCHigh-level data link control (X.25 network)ILANIBM Token Ring Local Area NetworkTELE2U.S. Telegraph Terminal Control—type 2.UIRATE=This optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.738 z/VM: CP Planning and Administration

Display Terminals and Adaptersvalue can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.ExamplesTo specify an integrated adapter attachment to an IBM Token Ring Local AreaNetwork, code the RDEVICE macro as follows:RDEVICE DEVNO=(220,12),DEVTYPE=ICA,ADAPTER=ILANAppendix C. Defining I/O Devices Using HCPRIO 739

Display Terminals and Adapters5080 and 6090 Graphics Display►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE= 5080HFGD,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄PurposeThe 5080 is supported as a dedicated-only device.ParametersDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. The variable rdev must be aone- to four-digit hexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice control blocks with consecutive device numbers. The default is 1.DEVTYPE=5080DEVTYPE=HFGDspecifies the type of device. HFGD (high function graphics device) isinterchangeable with 5080. It is listed here for compatibility with VM/SP HPO.To specify 6090, code 5080.UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.Examples1. To specify a 5080 display at device number 0006, code the RDEVICE macro asfollows:RDEVICE DEVNO=0006,DEVTYPE=5080 (or DEVTYPE=HFGD)2. To specify three 5080 displays at device numbers 0007, 0008, and 0009, codethe RDEVICE macro as follows:740 z/VM: CP Planning and Administration

Display Terminals and AdaptersRDEVICE DEVNO=(0007,3),DEVTYPE=5080 (or DEVTYPE=HFGD)3. To specify a 6090 display at device numbers 0010, code the RDEVICE macroas follows:RDEVICE DEVNO=0010,DEVTYPE=5080Appendix C. Defining I/O Devices Using HCPRIO 741

Tape UnitsTape Units742 z/VM: CP Planning and Administration

Tape Units3422, 3480, 3490 and 3590 Tape Drives►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE= 3422348034903590,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄ParametersDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. The variable rdev must be aone- to four-digit hexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice control blocks with consecutive device numbers. The default is 1.DEVTYPE=devtypespecifies the type of device (3422, 3480 or 3490).For 3480s and 3490s, specify the devtype based on the model of your tapedevice:Device Model Specify Type3480 A11, B11, A22, B22 34803490 A01, A02, B02, B04, D31, D32 34803490 A10, A20, B20, B40, C10, C11, C22,D41, D423490UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.Examples1. To specify a 3422 tape drive at device member 0422, code the RDEVICE macroas follows:Appendix C. Defining I/O Devices Using HCPRIO 743

Tape UnitsRDEVICE DEVNO=0422,DEVTYPE=34222. To specify a 3480 tape drive at device number 0450, code the RDEVICE macroas follows:RDEVICE DEVNO=0450,DEVTYPE=34803. To specify a 3490 tape drive, Model A01, A02, B02, B04, D31, or D32, at devicenumber 0462, code the RDEVICE macro as follows:RDEVICE DEVNO=0462,DEVTYPE=34904. To specify a 3490 tape drive Model A10, A20, B20, B40, D41, or D42, at devicenumber 0480, code the RDEVICE macro as follows:RDEVICE DEVNO=0480,DEVTYPE=3490744 z/VM: CP Planning and Administration

DASDDASDAppendix C. Defining I/O Devices Using HCPRIO 745

DASDDASD Types►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE= 338033903851,SHARED=NO,SHARED=YES►►,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄PurposeThis section describes how to code the RDEVICE macro for the following devices:3380 DASD 3390 DASD3850 Mass Storage SystemSee also “FBA DASD” on page 749.Notes:1. A 3380 attached to a 3880-11 or 3880-13 requires no special treatment.2. 3995 Models 131, 132 (Optical Library Dataserver), look like 3088’s and mustbe defined as such. For a description of how to code RDEVICE for a 3088 see“CTCA, 3088 Multisystem Channel Communication Unit, and 3737 RemoteChannel-to-Channel Unit” on page 760.3. 3995 Models 151, 152 (Optical Library Dataserver), look like 3390’s and mustbe defined as such.ParametersDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. The variable rdev must be aone- to four-digit hexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice control blocks with consecutive device numbers. The default value fornnn is 1.DEVTYPE=devtypespecifies the device type plus model for 3330. Code this parameter as follows:For a Specify3380 DEVTYPE=3380 (The use of the CUTYPE keyword isignored.)3390 DEVTYPE=3390 (The use of the CUTYPE keyword isignored.)746 z/VM: CP Planning and Administration

DASDFor a Specify3390 in 3380 trackcompatibility mode3850 DEVTYPE=3851.DEVTYPE=3380 or 3390 except when device is usedfor the SYSRES device. If the IPL device is operatingin 3380 track compatibility mode, you must specifyDEVTYPE=3380 and on the SYSRES macroSYSTYPE=3380.SHARED=YESSHARED=NOindicates whether the device is to be shared concurrently between multiple realsystems. The default is SHARED=NO. For more information on sharing DASDs,see Chapter 21, “DASD Sharing,” on page 619.Note: VM/ESA supports the 3850 Mass Storage System only when it isdedicated to a virtual machine. Because hardware that is supported asdedicated-only cannot be shared concurrently between multiple realsystems, do not code the SHARED operand for the 3851 Mass StorageFacility nor for the DASD attached to the 3850 Mass Storage System.Devices that contain CMS minidisks that will be shared in a CSE orVM/ISF complex should be specified as SHARED=YES (see “Spool FileDirectory Statements” on page 341).UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.Usage Notes1. If you generate a 3390 DASD attached to a 3990 Models 3 or 6 StorageControl, and that device is physically attached to the system, the operator mayrequest I/O to an offline device.2. The following commands may be entered to an offline device:v SET CACHEv SET DASDFWvDISCARDv QUERY PINNEDv QUERY RSAWv QUERY CACHEAppendix C. Defining I/O Devices Using HCPRIO 747

DASDv QUERY DASDFW.Note: The only way to ensure that the operating system never requests I/O to adevice is not to generate it, or to ensure that it is physically inaccessible.Restrictions1. DASDs on ESCON channels must be formatted without filler records. This isbecause you must use ECKD channel programs to control DASD on an ESCONchannel and the ECKD command, LOCATE RECORD, may fail if there are fillerrecords. Also, system performance will be seriously degraded if you issuenon-ECKD channel programs to an ESCON-attached DASD.2. Any minidisks being used by the shared file system (SFS) that are participatingin virtual machine data-space mappings that are on ESCON channels must beformatted without filler records because virtual machine data-space mappedminidisks use CP paging routines to perform I/O.There are two cases depending on the ownership of the ESCON attachedvolume:a. CP owned:Cylinder 0 and all CP-owned extents must have been formatted for CP. CPwill do I/O operations to the volume based on how cylinder 0 was formatted;that is, with or without filler records. If the volume is a 3380 formatted withfiller records, paging forces CKD usage for the packs and CKD usage willcause command rejects.b. Non CP-owned:The format of the volume is not known because the mapped minidisk isformatted however the user or application wanted. CP will always use ECKDchannel programs when doing mapped minidisk paging. This may cause theECKD command, LOCATE RECORD, to fail if there are filler records.3. The 3990 Models 3 and 6 Storage Control are track caching control units.Therefore, it is not recommended that DASD attached to 3990 Models 3 and 6Storage Control units be used for paging, or if they are, the cache should beturned off for any paging devices attached to them.4. If you issue QUIESCE/RESUME while running VM/ESA with a 3990 StorageControl attached, you will receive a message indicating that these commandsare not supported.Examples1. To specify a Model AE4 or BE4 3380 DASD at device number 0A70, code theRDEVICE macro as follows:RDEVICE DEVNO=0A70,DEVTYPE=33802. To specify a 3390 DASD at device number 0A80, code the RDEVICE macro asfollows:RDEVICE DEVNO=0A80,DEVTYPE=33903. To specify the 3851 Mass Storage Facility of the 3850 Mass Storage System atdevice number 0A90, code the RDEVICE macro as follows:RDEVICE DEVNO=0A90,DEVTYPE=3851748 z/VM: CP Planning and Administration

DASDFBA DASD►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE= 9336FB-512,SHARED=NO,SHARED=YES►►,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄PurposeThis section describes how to code the RDEVICE macro for FBA DASD.ParametersDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. The variable rdev must be aone- to four-digit hexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice specifications with consecutive device numbers. The default is 1.DEVTYPE=9336DEVTYPE=FB-512specifies the type of device. If you specify 9336, this indicates the specific FBAdevice type. If you specify FB-512, this implies that the device is one of thecurrently supported FBA device types.SHARED=YESSHARED=NOindicates whether the device is to be shared concurrently between multiple realsystems. The default is SHARED=NO.UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.Appendix C. Defining I/O Devices Using HCPRIO 749

DASDUsage Notes1. During device initialization time, the device model information will be obtaineddynamically from the hardware. If the MODEL= parameter is specified, it will beignored.2. If execution of the Read Device Characteristics (RDC) CCW is unsuccessfulduring DASD initialization time, the device will be brought online as dedicatedsupported.Examples1. To specify an FBA DASD generically at device number 220, code the RDEVICEmacro as follows:RDEVICE DEVNO=220,DEVTYPE=FB-5122. To specify a 9336 DASD at device numbers 0336, 0337, and 0338, code theRDEVICE macro as follows:RDEVICE DEVNO=(336,3),DEVTYPE=9336,SHARED=YES750 z/VM: CP Planning and Administration

Communication DevicesCommunication DevicesAppendix C. Defining I/O Devices Using HCPRIO 751

Communication Devices2701 Data Adapter►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE=2701 ,ADAPTER= BSCAIBM1TELE2►►,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄ParametersDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. The variable rdev must be aone- to four-digit hexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice control blocks with consecutive device numbers. The default is 1.DEVTYPE=2701specifies the type of device.ADAPTER=BSCAADAPTER=IBM1ADAPTER=TELE2specifies the terminal control adapter that connects to the device it controls.The BSCA adapter is supported as a dedicated-only device.UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.Examples1. To specify a 2701 line adapter at device number 00F0, code the RDEVICEmacro as follows:752 z/VM: CP Planning and Administration

Communication DevicesRDEVICE DEVNO=00F0,DEVTYPE=2701,ADAPTER=BSCA2. To specify three 2701 line adapters at device numbers 00F1, 00F2, and 00F3,code the RDEVICE macro as follows:RDEVICE DEVNO=(00F1,3),DEVTYPE=2701,ADAPTER=BSCAAppendix C. Defining I/O Devices Using HCPRIO 753

Communication Devices3705, 3725, and 3745 Line Adapters, 2741 Terminal, and 3151, 3161,3162, 3163, and 3167 Display Terminals►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE=3705 ,ADAPTER= IBM1TELE2BSCA,BASEADD=rdev►►,SETADDR=4,SETADDR=sadnum,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄PurposeNote: To define 3705, 3720, 3725, and 3745 communication controllers, see “37xxCommunications Controllers and 3x74 Controllers” on page 757.ParametersDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. The variable rdev must be aone- to four-digit hexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice control blocks with consecutive device numbers. The default is 1.DEVTYPE=devtypespecifies the type of device. For 3705, 3725, or 3745 line adapters, specifyDEVTYPE=3705. For a 2741, 3151, 3161, 3162, 3163, or 3167, specifyDEVTYPE=3705.ADAPTER=IBM1ADAPTER=TELE2ADAPTER=BSCAis the terminal control or transmission adapter used to connect atelecommunication I/O device to its control unit. Specify one of the followingvalues for adapter:v IBM1 specifies that an IBM Terminal Adapter Type I attaches a 1050 or 2741to a 3705, 3725, or 3745 (generated as a 3705).v TELE2 specifies that a CPT-TWX (Models 33/35) Terminal, 3101, 3151,3161, 3162, or 3163 attaches to a Line Interface Base Type I in a 3705,3725, or 3745 (generated as a 3705).v BSCA specifies an IBM Binary Synchronous Terminal Control Type II for a3705, 3725, or 3745 (generated as a 3705).The BSCA adapter is supported as dedicated-only.BASEADD=rdevis the one- to four-digit hexadecimal device number of the communicationscontroller to which the line adapter attaches.754 z/VM: CP Planning and Administration

Communication DevicesSETADDR=sadnumis the set address (SAD) command to be entered for a telecommunication lineattached to a control unit. The default is 4.sadnumCommand0 SADZERO1 SADONE2 SADTWO3 SADTHREE4 (No SAD command is entered)UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION It is not recommended that you set the UIRATE value to INFINITYfor any great length of time. Hot I/O detection protects CP from brokenhardware that floods the system with unsolicited interrupts. If you turn Hot I/Odetection off, you may experience performance degradation or a system abend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.Usage NotesVM/ESA supports native ASCII devices.Examples1. To specify at device number 0451 an IBM Binary Synchronous Terminal ControlType II that:a. Attaches to the 3705 communication controller at device number 0441b. Enters the SADZERO command,code the RDEVICE macro as follows:RDEVICE DEVNO=0451,DEVTYPE=3705,ADAPTER=BSCA, *BASEADD=0441,SETADDR=02. To specify at device number 0452 an IBM Terminal Adapter Type I that:a. Attaches a 1050 to the 3725 communication controller at device number0442b. Enters the SADONE command,code the RDEVICE macro as follows:RDEVICE DEVNO=0452,DEVTYPE=3705,ADAPTER=IBM1, *BASEADD=0442,SETADDR=13. To specify a 2741 at device number 0460, code the RDEVICE macro as follows:RDEVICE DEVNO=0460,DEVTYPE=3705,ADAPTER=IBM1,BASEADD=04224. To specify a 3151 at device number 0462, code the RDEVICE macro as follows:RDEVICE DEVNO=0462,DEVTYPE=3705,ADAPTER=TELE2,BASEADD=0422Appendix C. Defining I/O Devices Using HCPRIO 755

Communication DevicesNote: If you need more than one line to code the RDEVICE macro, you must codea continuation character in column 72 and start the next line in column 16.756 z/VM: CP Planning and Administration

37xx Communications Controllers and 3x74 ControllersCommunication Devices►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE=3705 ,ADAPTERS=TYPE4 ,MODEL=modelno ►►,CPNAME=cpname,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄PurposeThe 370x communication controllers are supported as dedicated-only devices or bySNA attachment through VM/VTAM or VCNA. The 3720, 3725, and 3745, ifspecified as dedicated-only devices, must be specified as 3705s.The 3x74 controllers are supported as follows:3174-1L, -11LThrough non-SNA channel attachment or through VM/VTAM or VCNA3174-1R, 51R, 81R, 11R, 61R, 91RThrough remote SNA attachment through VM/VTAM or VCNA or dedicated-onlyfor remote non-SNA attachment3174-2R, 3R, 52R, 53R, 82R, 12R, 13R, 62R, 63R, 92RThrough remote SNA attachment through VM/VTAM or VCNA3274-1A, 21A, 31A, 31A, 41AThrough SNA channel attachment through VM/VTAM or VCNA3274 1B, 21B, 1D, 21D, 31D, 41DFull support for non-SNA attachment3274-1C, 21C, 31C, 51CDedicated-only for non-SNA attachment3274-1C, 21C, 31C, 41C, 51C, 61CThrough remote SNA attachment through VM/VTAM or VCNAParametersDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. The variable rdev must be aone- to four-digit hexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice control blocks with consecutive device numbers. The default is 1.DEVTYPE=3705specifies the type of device. For a 3174, 3274, 3705, 3720, 3725, or 3745,specify DEVTYPE=3705.ADAPTER=TYPE4specifies the transmission adapter used to connect a communication controllerto the channel. For a 3174, 3274, 3705, 3720, 3725, or 3745, specifyADAPTER=TYPE4.Appendix C. Defining I/O Devices Using HCPRIO 757

Communication DevicesMODEL=modelnospecifies the model code for the device or device group you are defining. Themodel number can be any model number that is valid for the device or devicegroup as follows:A1 A2B1 B2 B3 B4C1 C2 C3 C4 C5 C6D1 D2 D3 D4 D5 D6 D7 D8E1 E2 E3 E4 E5 E6 E7 E8F1 F2 F3 F4 F5 F6 F7 F8G1 G2 G3 G4 G5 G6 G7 G8H1 H2 H3 H4 H5 H6 H7 H8J1 J2 J3 J4K1 K2 K3 K4L1 L2 L3 L41 2 3 4 5 6 7 8CPNAME=cpnameis the 1- to 8-character name of an emulation program. Note that CP will notautomatically load this (see “Setting Up a Virtual Machine for CommunicationController Support for Emulator Program (EP)” on page 321).UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.Usage Notes1. z/VM supports the 3174 Subsystem Control Unit Model 1L for local channelattachment. For bisynchronous communications attachment, z/VM supports theModels 1R, 51R, and 81R as dedicated-only through the VM/Pass-ThroughFacility (PVM) Release 3 or through RSCS networking.2. To define 3705, 3725, and 3745 line adapters, see “3705, 3725, and 3745 LineAdapters, 2741 Terminal, and 3151, 3161, 3162, 3163, and 3167 DisplayTerminals” on page 754.Examples1. To specify three Model B1 3705 communications controllers at device numbers0462, 0463, and 0464 that have emulation programs named X6000, code theRDEVICE macro as follows:RDEVICE DEVNO=(0462,3),DEVTYPE=3705,MODEL=B1, *ADAPTER=TYPE4,CPNAME=X6000758 z/VM: CP Planning and Administration

Communication DevicesNote: If you need more than one line to code the RDEVICE macro, you mustcode a continuation character in column 72 and start the next line incolumn 16.2. To specify a 3725 as a Model D1 3705 communications controller at devicenumber 0465, code the RDEVICE macro as follows:RDEVICE DEVNO=0465,DEVTYPE=3705,MODEL=D1,ADAPTER=TYPE43. To specify a Model 41A 3274 controller at device number 0E0, code theRDEVICE macro as follows:RDEVICE DEVNO=0E0,DEVTYPE=3705,ADAPTER=TYPE4,MODEL=E8Appendix C. Defining I/O Devices Using HCPRIO 759

Communication DevicesCTCA, 3088 Multisystem Channel Communication Unit, and 3737Remote Channel-to-Channel Unit►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE=CTCA3088,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄PurposeThe CTCA, 3088 MCCU, and 3737 are supported as dedicated-only devices.ParametersDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. The variable rdev must be aone- to four-digit hexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice control blocks with consecutive device numbers. The default value is 1.DEVTYPE=CTCADEVTYPE=3088specifies the type of device. Specify the 3737 Remote Channel-to-Channel UnitModel 2 as a CTCA.UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.Examples1. To specify a 3088 multisystem channel communication unit logical channeladapter at device number 0100, code the RDEVICE macro as follows:RDEVICE DEVNO=0100,DEVTYPE=30882. To specify CTCAs at device numbers 0101, 0102, and 0103, code theRDEVICE macro as follows:RDEVICE DEVNO=(0101,3),DEVTYPE=CTCA760 z/VM: CP Planning and Administration

Dynamic Switching DevicesDynamic Switching DevicesAppendix C. Defining I/O Devices Using HCPRIO 761

Dynamic Switching Devices9032 and 9033 ES Connection Directors (ESCDs)►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE= 90329033,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄ParametersDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. The variable rdev must be aone- to four-digit hexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice control blocks with consecutive device numbers. The default is 1.DEVTYPE=9032DEVTYPE=9033specifies the type of device (9032 or 9033).UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.ExamplesTo specify a 9032 ES Connection Director at device number 100, code theRDEVICE macro as follows:RDEVICE DEVNO=0100,DEVTYPE=9032762 z/VM: CP Planning and Administration

Unsupported DevicesUnsupported Devices►►labelRDEVICE DEVNO= rdev(rdev,nnn),DEVTYPE=nnn►► ,CLASS=DASDTAPE ,FEATURE= DPSRESERVE(DPS,RESERVE)(RESERVE,DPS)TERMDISPLAYRDRPRTPUNSWITCH,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄PurposeNote: When you generate a device as an unsupported device, you must dedicatethe device to a virtual machine. Dedicate a device to a virtual machine bycoding the DEDICATE control statement in the virtual machine’s directoryentry or by entering the CP ATTACH command.ParametersDEVNO=rdevDEVNO=(rdev,nnn)DEVNO=rdev specifies a real I/O device number. The variable rdev must be aone- to four-digit hexadecimal number in the range 0 through FFFF.DEVNO=(rdev,nnn) specifies real I/O device numbers for a range of devices.The variable nnn is a decimal repetition count and creates a group of realdevice control blocks with consecutive device numbers. The default is 1.DEVTYPE=nnnnwhere nnnn is an unsupported device type.CLASS=DASDCLASS=TAPECLASS=TERMCLASS=DISPLAYCLASS=RDRCLASS=PRTCLASS=PUNCLASS=SWITCHis the device class of the unsupported device; valid classes for unsupporteddevices include:Class ValueClass For Unsupported DeviceDASD Direct access storage devicesTAPE Tape devicesTERM TerminalsAppendix C. Defining I/O Devices Using HCPRIO 763

Unsupported DevicesDISPLAYDisplay mode devicesRDR Unit record input devicesPRT Unit record printer devicesPUN Unit record punch devicesSWITCHDynamic switching devices.FEATURE=DPSFEATURE=RESERVEFEATURE=(DPS,RESERVE)FEATURE=(RESERVE,DPS)specifies the optional features for an unsupported DASD or tape device.v DPS should be specified whenever a device is defined as an unsupporteddevice and it contains support for the dynamic path selection (DPS) function:CCW command codes X’34’, Sense Path Group Identifier (SNID), and X’AF’,Set Path Group Identifier (SPID).When DPS is specified, VM’s control program places VM’s path groupidentifier (PGID) in the device’s control unit for each path to the control unit.This enables the use of a single PGID for all devices connected to thecontrol unit, regardless of the number of guests that might be using thedifferent devices on the control unit, how many times a given guest isre-IPLed, or how a given device might be shifted from one guest to anotherover time. A guest operating system such as IBM’s MVS/XA andMVS/ESA has an ″alternate-PGID″ capability to deal with the VM PGID onthese channel paths.When DPS is not specified, VM takes no action with regard to path groups orPGIDs. It is the responsibility of the guest to which the unsupported device isdedicated or attached to form and maintain path groups, if desired, using theguest’s own PGID. The use of a guest’s PGID is often operationallycumbersome if not unworkable for DPS devices, because a PGID on achannel path to a control unit applies to all devices connected to the controlunit, and a PGID can only be changed after clearing any previous PGID witha system-reset of the channel path(s).DPS should not be specified if the guest operating system to which thedevice will be dedicated or attached does not contain “alternate PGID”support.The DPS parameter does not apply to devices that are defined to VM assupported devices. In all other cases the DPS parameter, if specified,generates an MNOTE and processing for that particular RDEVICE macro isterminated.v RESERVE should be specified whenever a device is defined as anunsupported device and the device contains support for the reserve/releasefunction: CCW command codes X’B4’, Device Reserve (RES), X’94’, DeviceRelease (REL), and X’14’, Unconditional Reserve (UR).When RESERVE is specified for an unsupported device, VM’s controlprogram issues the Device Release CCW command to the device wheneverthe virtual machine to which the device is dedicated or attached is reset (bythe System Clear, System Reset, or IPL commands).If RESERVE is not specified for an unsupported device that contains supportfor the reserve/release function, a malfunction of the guest to which thedevice is dedicated or attached might leave a device reservation held by theguest, preventing the device from being accessed by other sharing systems.764 z/VM: CP Planning and Administration

Unsupported DevicesThe RESERVE parameter does not apply to devices that are defined to VMas supported devices. In these cases the RESERVE parameter, if specified,generates an MNOTE and processing for that particular RDEVICE macro isterminated.You can code DPS and RESERVE in any order. A single feature does not needto be enclosed in parentheses.UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP frombroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.ExamplesTo specify a type 9000 unsupported DASD, code the RDEVICE macroinstruction asfollows:RDEVICE DEVNO=0FFF,DEVTYPE=9000,CLASS=DASDTo specify an unsupported DASD, that supports dynamic path selection, pick adevice type value that does not correspond to any IBM device type; for example,device type 8000 and code the RDEVICE macroinstruction as follows:RDEVICE DEVNO=0FE0,DEVTYPE=8000,CLASS=DASD, *FEATURE=DPSTo specify an unsupported DASD, that supports both dynamic path selection andreserve/release, pick a device type value that does not correspond to any IBMdevice type; for example device type 7000 and code the RDEVICE macroinstructionas follows:RDEVICE DEVNO=0FD0,DEVTYPE=7000,CLASS=DASD, *FEATURE=(DPS,RESERVE)To specify an unsupported tape that supports dynamic path selection, select adevice type value that does not correspond to any IBM device type; for exampledevice type 9100 and code the RDEVICE macroinstruction as follows:RDEVICE DEVNO=0FE0,DEVTYPE=9100,CLASS=TAPE,FEATURE=DPSAppendix C. Defining I/O Devices Using HCPRIO 765

RIOGENRIOGEN►►labelRIOGENCONS=DYNAMICCONS=rdev,,UIRATE=DEFAULT,UIRATE=INFINITYvalue►◄,ALTCONS= ( ▼ rdev )PurposeParametersUse the RIOGEN macroinstruction to complete the real I/O definition and define theprimary and alternate system consoles. It must appear as the last macroinstructionin the HCPRIO file.CONS=DYNAMICtells CP that the console addresses are defined in the system configuration file.CONS=rdevspecifies the real hexadecimal device number of the CP primary systemconsole. You must specify the real device number in an RDEVICEmacroinstruction. This device must be a locally attached 3270-type supporteddisplay (see “3270-Family Displays” on page 734 for a list of 3270-type displayssupported).ALTCONS=(rdev)ALTCONS=(rdev,...,rdev)specifies the device number or a list of device numbers to be used as alternatesystem consoles. The maximum number of primary and alternate consoles is32. If you specify a single device number, you can omit the parentheses.Although you do not need to specify alternate device numbers in an RDEVICEmacroinstruction, you receive an MNOTE if you decide not to do so. Analternate device can be any locally attached 3270-type device. If the primarysystem console is not operational at system initialization, CP tries to access thefirst alternate console. If the first alternate console is not operational, CP tries tostart the next alternate console, and so on. If CP finds an operational console, ituses it as the primary system operator’s console. If CP cannot find anoperational alternate console (or if you specified no alternate console), CPenters a disabled wait state with a wait state code of X'1010' in the PSW.UIRATE=DEFAULTUIRATE=INFINITYUIRATE=valueThis optional parameter allows the detection of a hot I/O occurrence to becustomized for a device.DEFAULT results in 16 unsolicited interrupts per second before a hot I/Ocondition is detected. This value is the same rate used for those devices thathave no UIRATE parameter specified.INFINITY turns hot I/O recovery off for the device.ATTENTION: It is not recommended that you set the UIRATE value toINFINITY for any great length of time. Hot I/O detection protects CP from766 z/VM: CP Planning and Administration

RIOGENUsageNotesbroken hardware that floods the system with unsolicited interrupts. If you turnHot I/O detection off, you may experience performance degradation or a systemabend.value can be a decimal number from 1 to 62500 which specifies the number ofconsecutive unsolicited interrupts allowed per second before a hot I/O conditionis detected.1. For practical purposes, alternate system consoles should be close to primarysystem consoles. Because the system operator may have to respond tomessages on an alternate console, the most convenient location for an alternateconsole is near the primary console.2. 3250 displays are not valid for the RIOGEN macroinstruction.3. During a software re-IPL caused by either a system incident or the SHUTDOWNREIPL command, CP determines whether the operator virtual machine isconnected to the primary system console. If the operator virtual machine isdisconnected, logged off, or logged onto a console other than the primaryconsole, CP disconnects the operator virtual machine when the system isreinitialized. This is a security measure to reduce the risk of CP logging theoperator virtual machine on to an unattended console.ExamplesThe following example defines a primary system console (001F) with an alternateconsole (0050).RIOGEN CONS=001F,ALTCONS=0050You can indicate that you are defining console addresses in the systemconfiguration file by coding:RIOGEN CONS=DYNAMICAppendix C. Defining I/O Devices Using HCPRIO 767

RIOGEN768 z/VM: CP Planning and Administration

Appendix D. Configuration Guide for PrintersTable 36 gives the following information for each printer:v The printer type and the page in Appendix C, “Defining I/O Devices UsingHCPRIO” that describes in detail how to code the RDEVICE macroinstruction forthe printer (including examples)v The DEVTYPE operand you must specifyv The DEVNO operand you must specifyv Optional operands you can specify.In the tables, the less than () signs indicate that you have achoice of values or operands, one of which you must choose. The “logical or bar” (|)means or. For example, means you must choose YES or NO as avalue. Never include the , or | in the macroinstruction. When an option appearsin bold, underlined letters, that option is the default.Before coding the RDEVICE macroinstruction for a device, make sure you consultany pertinent notes that appear at end of the table.Important NoteMany of the printers discussed in this appendix can be sensed by CP ordefined in the system configuration file using the RDEVICE statement. Formore information about sensing devices, see Chapter 5, “Defining I/ODevices,” on page 45. For more information about the RDEVICE statement,see page 188.Table 36. Configuration Guide for PrintersDevice Type DEVTYPE Required Operands Optional OperandsAdvanced FunctionPrinters: see page 708AFP1DEVNO=3203 printer: see page 716 3203 DEVNO=Devices that emulate a3211 printer: see page 7163211 DEVNO=MODEL=5CLASS=CHARS=DEST=AFP=FCB=FEATURE=UNVCHSETFORM=SEP=IMAGE=FOLD=CLASS=CHARS=DEST=AFP=FCB=FEATURE=UNVCHSETFORM=SEP=IMAGE=FOLD=INDEX=© Copyright IBM Corp. 1991, 2004 769

Configuration Guide for PrintersTable 36. Configuration Guide for Printers (continued)Device Type DEVTYPE Required Operands Optional Operands3216 display printer: seepage 7083262 display printer: seepage 7133262 impact printer: seepage 7163286 display printer: seepage 7133268 display printer: seepage 7133287 display printer: seepage 7133288 display line printer:see page 7133289 display line printer:see page 7133800 printer: see pages721 and 708AFP1DEVNO=3287 DEVNO=3262Note 1DEVNO=3286 DEVNO=3287 DEVNO=3287 DEVNO=3288 DEVNO=3289 DEVNO=3800Note 2DEVNO=3812 printer: see page 708 AFP1 DEVNO=3816 printer: see page 708 AFP1 DEVNO=3820 printer: see page 708 AFP1 DEVNO=3827 printer: see page 708 AFP1 DEVNO=3835 printer: see page 708 AFP1 DEVNO=4214 display printer: seepage 7134224 display printer: seepage 7133287 DEVNO=3287 DEVNO=MODEL=5CLASS=CHARS=DEST=AFP=FCB=FORM=SEP=IMAGE=FOLD=MODEL=CLASS=CHARS=ffffDEST=AFP=DPMSIZE=FCB=FEATURE=4WCGMSFLASH=flashlibFORM=IMAGE=SEP=770 z/VM: CP Planning and Administration

Configuration Guide for PrintersTable 36. Configuration Guide for Printers (continued)Device Type DEVTYPE Required Operands Optional Operands4234 display printer: seepage 7134245 display printer: seepage 7134245 impact printer: seepage 7163287 DEVNO=3287 DEVNO=42454248 printer: see page 716 42485210 display printer: seepage 7136262 display printer: seepage 7136262 impact printer: seepage 716Notes:Note 3Note 4DEVNO=DEVNO=3287 DEVNO=3287 DEVNO=4248 DEVNO=1. If a 3262 is in 4248-compatibility mode, specify DEVTYPE=4248.MODEL=CLASS=DEST=AFP=FCB=FORM=SEP=IMAGE=FOLD=MODEL=1CLASS=DEST=AFP=FCB=FORM=SEP=IMAGE=FOLD=MODEL=1CLASS=DEST=AFP=FCB=fcbnameFORM=SEP=IMAGE=imagelibFOLD=2. If a 3800-3 or 3800-6 is run in 3800-1 compatibility mode, specify MODEL=1. If a 3800-3, 3800-6, or 3800-8 isused as an advanced function printer, specify DEVTYPE=AFP1.3. If the 4245-1 is in 3262-compatibility mode, specify DEVTYPE=3262.4. If a 4248-1 or 4248-2 is in 3211-compatibility mode, specify DEVTYPE=3211. When specifying a 4248-2 as a4248, specify MODEL=1.Appendix D. Configuration Guide for Printers 771

Configuration Guide for Printers772 z/VM: CP Planning and Administration

Appendix E. Device Class and Type CodesDevice Class DefinitionsThis appendix is the HCPDVTYP copy file and can be found in macro libraryHCPOM1.DEVCLAS BIT DEFINITIONS DEVICE CLASSESCLASAIF EQU X’FF’ Adapter-Interrupt-Facility (AIF) ClassCLASTERM EQU X’80’ TERMINAL DEVICE CLASSCLASGRAF EQU X’40’ GRAPHIC DISPLAY DEVICE CLASSCLASGRFR EQU X’41’ GRAPHIC DISPLAY DEVICE CLASS (REMOTE)CLASPOOL EQU X’20’ UNIT RECORD SPOOLING DEVICE CLASSCLASTAPE EQU X’08’ MAGNETIC TAPE DEVICE CLASSCLASDASD EQU X’04’ DIRECT ACCESS STORAGE DEVICE CLASSCLASSPEC EQU X’02’ SPECIAL DEVICE CLASSCLASSVCM EQU X’10’ SIMULATED DEVICE CLASSCLASSWCH EQU X’01’ SWITCH DEVICE CLASSDevice Type Definitions within Device ClassesDEVTYPE BIT DEFINITIONS DEVICE TYPES BY DEVICE CLASSESTYP2700 EQU X’80’ TERM - 2700 BISYNC LINETYPBSC EQU X’88’ TERM - BISYNC LINE FOR 3270REMOTE STATIONTYPCONS EQU X’40’ TERM - CONSOLE DEVICETYP3215 EQU X’40’ TERM - 3215 CONSOLETYP1052 EQU X’40’ TERM - 1052 CONSOLETYPTTY EQU X’20’ TERM - USASCII-8 TELEGRAPH TERMINALTYPIBM1 EQU X’10’ TERM - IBM TERMINAL CONTROL TYPE 1TYPUNDEF EQU X’1C’ TERM - TERMINAL TYPE UNDEFINEDTYP2741 EQU X’18’ TERM - 2741 COMMUNICATIONS TERMINALTYP3767 EQU X’18’ TERM - 3767 IN 2741 COMPATIBILITY MODETYP1050 EQU X’14’ TERM - 1050 COMMUNICATIONS TERMINALTYPSDLC EQU X’08’ TERM - SDLC INTEGRATED ADAPTERTYPTELE2 EQU X’20’ TERM - TELE2 INTEGRATED ADAPTERTYPHDLC EQU X’24’ TERM - HDLC INTEGRATED ADAPTERTYPILAN EQU X’28’ TERM - ILAN INTEGRATED ADAPTERTYPELAN EQU X’28’ TERM - ELAN INTEGRATED ADAPTERTYPIC EQU X’04’ TERM - Integrated consoleTYP3270 EQU X’40’ GRAF - 3270 GENERIC DISPLAY STATIONTYP3277 EQU X’80’ GRAF - 3277 DISPLAY STATIONTYP3278 EQU X’40’ GRAF - 3278 DISPLAY STATIONTYP3178 EQU X’40’ GRAF - 3178 DISPLAY STATIONTYP3279 EQU X’40’ GRAF - 3279 DISPLAY STATIONTYP3179 EQU X’40’ GRAF - 3179 DISPLAY STATIONTYP3180 EQU X’40’ GRAF - 3180 DISPLAY STATIONTYP3290 EQU X’40’ GRAF - 3290 DISPLAY STATIONTYP3190 EQU X’40’ GRAF - 3190 DISPLAY STATIONTYP3271 EQU X’20’ GRAF - 3271 CONTROLLER (REMOTE)*YP3274 EQU X’21’ GRAF - 3274 CONTROLLER (REMOTE)TYP3275 EQU X’10’ GRAF - 3275 DISPLAY STATION*YP3276 EQU X’11’ GRAF - 3276 DISPLAY STATIONTYP3284 EQU X’08’ GRAF - 3284 PRINTERTYP3286 EQU X’08’ GRAF - 3286 PRINTERTYP3287 EQU X’09’ GRAF - 3287 PRINTERTYP3288 EQU X’08’ GRAF - 3288 PRINTERTYP3289 EQU X’09’ GRAF - 3289 PRINTERTYP3287L EQU X’08’ GRAF - 3287 LOGICAL PRINTERTYP3289L EQU X’08’ GRAF - 3289 LOGICAL PRINTERTYP2250 EQU X’04’ GRAF - 2250 DISPLAY UNIT© Copyright IBM Corp. 1991, 2004 773

Device Class and Type CodesTYP3250 EQU X’04’ GRAF - 3250 DISPLAY UNITTYP5080 EQU X’06’ GRAF - 5080 DISPLAY UNITTYPCLUST EQU X’30’ GRAF - CLUSTER CTLR (3271 OR 3275)TYPRDR EQU X’80’ SPOL - CARD READER DEVICETYP2501 EQU X’81’ SPOL - 2501 CARD READERTYP2540R EQU X’82’ SPOL - 2540 CARD READERTYP3505 EQU X’84’ SPOL - 3505 CARD READERTYPPUN EQU X’40’ SPOL - CARD PUNCH DEVICETYP2540P EQU X’42’ SPOL - 2540 CARD PUNCHTYP3525 EQU X’44’ SPOL - 3525 CARD PUNCHTYPPRT EQU X’20’ SPOL - PRINTER TYPE DEVICETYP1403 EQU X’21’ SPOL - 1403 PRINTERTYP32XX EQU X’22’ SPOL - 3203 OR 3211 PRINTERTYP3203 EQU X’26’ SPOL - 3203 PRINTERTYP3211 EQU X’22’ SPOL - 3211 PRINTERTYP3800 EQU X’28’ SPOL - 3800 PRINTERTYP3262 EQU X’23’ SPOL - 3262 PRINTERTYP4245 EQU X’24’ SPOL - 4245 PRINTERTYP4248 EQU X’29’ SPOL - 4248 PRINTERTYP3820 EQU X’25’ SPOL - 3820 PRINTER - DEDICATED ONLYTYPAFP1 EQU X’27’ SPOL - AFP1 PRINTER - DEDICATED ONLYTYPVAFP EQU X’2A’ SPOL - VAFP PRINTER - SIMULATED ONLYTYPSYS EQU X’10’ SPOL - SYSTEM VIRT DEVICE FOR DUMPSTYP3420 EQU X’10’ TAPE - 3420 TAPE DRIVETYP3422 EQU X’80’ TAPE - 3422 TAPE DRIVETYP3424 EQU X’42’ TAPE - 3424 TAPE DRIVETYP3430 EQU X’20’ TAPE - 3430 TAPE DRIVETYP3480 EQU X’40’ TAPE - 3480 TAPE DRIVETYP3490 EQU X’81’ TAPE - 3490 TAPE DRIVETYP3590 EQU X’83’ TAPE - 3590 TAPE DRIVETYP9348 EQU X’44’ TAPE - 9348 TAPE DRIVETYP3330 EQU X’40’ DASD - 3330 DISK STORAGE FACILITYTYP3340 EQU X’20’ DASD - 3340 DISK STORAGE FACILITYTYP3350 EQU X’10’ DASD - 3350 DISK STORAGE FACILITYTYP3350C EQU X’11’ DASD - 3350 4 X 8 PAGING STORAGETYP3350D EQU X’12’ DASD - 3350 4 X 4 PAGING STORAGETYP2305 EQU X’08’ DASD - 2305 FIXED HEAD STORAGE FACILITYTYP3380 EQU X’04’ DASD - 3380 DISK STORAGE FACILITYTYP3390 EQU X’82’ DASD - 3390 DISK STORAGE FACILITYTYP3375 EQU X’80’ DASD - 3375 DISK STORAGE FACILITYTYP3370 EQU X’02’ DASD - 3370 DISK STORAGE FACILITYTYP9345 EQU X’81’ DASD - 9345 DISK STORAGE FACILITYTYP9332 EQU X’21’ DASD - 9332 FBA DASDTYP9335 EQU X’22’ DASD - 9335 FBA DASDTYP9336 EQU X’24’ DASD - 9336 FBA DASDTYPFBA EQU X’28’ DASD - GENERIC FBA DASDTYP9033 EQU X’40’ SWCH - 9033 SWITCH DEVICETYP9032 EQU X’80’ SWCH - 9032 SWITCH DEVICETYP2032 EQU X’20’ SWCH - 2032 FICON Switch deviceTYPCTCA EQU X’80’ SPEC - CHANNEL TO CHANNEL ADAPTERTYP3088 EQU X’80’ SPEC - 3088 MULTISYSTEM CHANNELCOMMUNICATION UNITTYP3704 EQU X’40’ SPEC - 3704 PROGRAMMABLECOMMUNICATION CONTROL UNITTYP3705 EQU X’40’ SPEC - 3705 PROGRAMMABLECOMMUNICATION CONTROL UNITTYPOSA EQU X’20’ SPEC - OPEN SYSTEMS ADAPTER DEVICETYP3851 EQU X’02’ SPEC - MSS MASS STORAGE COMMUNICATORTYP3890 EQU X’08’ SPEC - 3890 DOCUMENT PROCESSORTYPUNSUP EQU X’01’ SPEC - DEVICE UNSUPPORTED BYTHE VM/370 MIGRATION AIDTYPFCP EQU X’10’ SPEC - Open FCP Adapter (FCP)TYPDYNIO EQU X’02’ VCM - Dynamic I/OTYPMSGF EQU X’01’ VCM - Message Facility774 z/VM: CP Planning and Administration

Device Class and Type CodesTYPAIF0 EQU X’00’ AIF - AIF Adapter Type 0Device Features by Class and TypeDevice Model DefinitionsDEVFEAT BIT DEFINITIONS FEATURES OF DEVICES BY CLASS/TYPEFTROPRDR EQU X’80’ GRAF - OPERATOR ID CARD READERFTRDIAL EQU X’01’ GRAF - 3275 WITH SWITCHED LINE SUPPORTFTRUCS EQU X’01’ SPOL - UCS FEATUREFTR4WCGM EQU X’80’ SPOL - 3800 WITH FOUR WRITEABLECHARACTER GENERATION MODULESFTR7TRK EQU X’80’ TAPE - 7-TRACK FEATUREFTRDUAL EQU X’40’ TAPE - DUAL DENSITY FEATUREFTRTRAN EQU X’20’ TAPE - TRANSLATE FEATUREFTRCONV EQU X’10’ TAPE - DATA CONVERSION FEATUREFTRCMPCT EQU X’08’ TAPE - DATA COMPACTION FEATUREFTRRPS EQU X’80’ DASD - ROTATIONAL POSITIONAL SENSINGFTRDYNP EQU X’40’ DASD/TAPE - DYNAMIC PATHING FEATUREFTRVUA EQU X’20’ DASD - 3330V THAT MAY BE DEDICATEDTO A VIRTUAL MACHINE*TRSYSV EQU X’10’ DASD - 3330V THAT MAY BE USED BYVM FOR MOUNTING MSS SYSTEMVOLUMESFTR35MB EQU X’08’ DASD - 35 MB DATA MODULE (3340)FTR70MB EQU X’04’ DASD - 70 MB DATA MODULE (3340)FTRRSRL EQU X’02’ DASD/TAPE/SPEC - RESERVE/RELEASECCW FEATUREFTRCOMP EQU X’01’ DASD - 3350 IN 3330 COMPAT. MODEFTRTERM EQU X’80’ SPEC - UNSUPPORTED TERMINAL DEVICEFTRGRAF EQU X’40’ SPEC - UNSUPPORTED GRAPHIC DISPLAYDEVICEFTRSPOOL EQU X’20’ SPEC - UNSUPPORTED UNIT RECORDSPOOLING DEVICEFTRTAPE EQU X’08’ SPEC - UNSUPPORTED MAGNETIC TAPEDEVICEFTRDASD EQU X’04’ SPEC - UNSUPPORTED DIRECT ACCESSDEVICEFTRSWCH EQU X’01’ SPEC - UNSUPPORTED DYNAMIC SWITCHFTRTYP1 EQU X’10’ SPEC - TYPE ONE CHANNEL ADAPTERFTRTYP4 EQU X’40’ SPEC - TYPE FOUR CHANNEL ADAPTERNote: This list contains only commonly compared model numbers. It is NOT acomplete list of supported devices or models.DEVMODEL CODE DEFINITIONS RDEVDVMN DEVICE MODEL NUMBERSM230502 EQU X’02’ DASD - 2305 MODEL 2M333001 EQU X’01’ DASD - 3330 MODEL 1 (404 CYLINDERS)M333002 EQU X’01’ DASD - 3330 MODEL 2 (404 CYLINDERS)M333011 EQU X’11’ DASD - 3330 MODEL 11(808 CYLINDERS)M3380E EQU X’0A’ DASD - 3380 MODEL EM3380K EQU X’1E’ DASD - 3380 MODEL KM3390N EQU X’02’ DASD - 3390 MODEL 1 NATIVE MODEM3390E EQU X’96’ DASD - 3390 MODEL 1 EMULATION MODEM3391N EQU X’06’ DASD - 3390 MODEL 2 NATIVE MODEM3391E EQU X’8A’ DASD - 3390 MODEL 2 EMULATION MODEM3393N EQU X’0A’ DASD - 3390 MODEL 3 NATIVE MODEM3393E EQU X’9E’ DASD - 3390 MODEL 3 EMULATION MODEM3399N EQU X’0C’ DASD - 3390 MODEL 9 NATIVE MODEM934500 EQU X’00’ DASD - 9345 MODEL 1M934504 EQU X’04’ DASD - 9345 MODEL 2Appendix E. Device Class and Type Codes 775

Device Class and Type CodesM380001 EQU X’01’ SPOL - 3800 PRINTER MODEL 1M380003 EQU X’03’ SPOL - 3800 PRINTER MODEL 3M380008 EQU X’08’ SPOL - 3800 PRINTER MODEL 8M327702 EQU X’02’ GRAF - 3277 DISPLAY STATION MODEL 2M308861 EQU X’61’ SPEC - 3088 CTCA PCA adaptor cardwith CLAW support.M308862 EQU X’62’ SPEC - 3088 OSA cardCUT1731 EQU X’1731’ SPEC - OSA Express Control Unit TypeDVT1731 EQU X’1731’ SPEC - OSA Direct Express Agent DEVDVT1732 EQU X’1732’ SPEC - OSA Direct Express Device Type776 z/VM: CP Planning and Administration

Appendix F. Stand-Alone Dump FormatsThe following sections describe the tape, DASD, and printer formats of stand-alonedumps.TapeFormatA tape used with the stand-alone dump facility has the format shown in Figure 42on page 778.v If the IPL tape and the dump device are not the same, the IPL tape includessections A, B, and C.v If the dump device is a tape, but not the same tape as the IPL tape, the dumpoutput tape includes sections C and D.v If the IPL device and the dump device are the same, the tape includes sectionsA, B, C, and D.© Copyright IBM Corp. 1991, 2004 777

Stand-Alone Dump Formats┌─────────┬─────────┬─────────┐│ │ │ ││ IPL │BOOTSTRAP│ SAD ││Sequence │ │ Program ││ │ │ │└─────────┴─────────┴─────────┘│◄──────────── A ────────────►│┌─────────┬─────────┬─────────┬────┬─────────┬─────────┐│ │ │ │ // │ │ ││Predumped│Predumped│Predumped│ // │Predumped│Predumped││ Page │ Page │ Page │ // │ Page │ Page ││ 0 │ 1 │ 2 │ // │ 8 │ 9 ││ │ │ │ // │ │ │└─────────┴─────────┴─────────┴────┴─────────┴─────────┘|◄─────────────────────────── B ────────────────────────┌────────┐│ ****** ││ *Tape* ││ *Mark* ││ ****** │└────────┘│◄─ C ──►│┌─────────┬─────────┬─────────┬──────────┬───┬─────────┬───────┬───────┐│ │ Symptom │Dump File│Dump File │// │Dump File│Dumped │Address││ Tape │ Record │ Map │ Info │// │ Info │ Access│ Space ││ Label │ │ Record │ Record │// │ Record │ List │ Info ││ │ │ │ Page 1 │// │ Page 5 │ Block │ Block │└─────────┴─────────┴─────────┴──────────┴───┴─────────┴───────┴───────┘│◄──────────────────────────────────── D ───────────────────────────────┌──────────┬──┬────────┬───────────┬──┬────────┐│ 1st Bit │//│ Last │ First │//│ Last ││ Map │//│ Bit Map│ Storage │//│ Storage││ Record │//│ Record │ Key │//│ Key ││ │//│ │ Record │//│ Record │└──────────┴──┴────────┴───────────┴──┴────────┘───────────────── D ─────────────────────────────┌─────────┬──────────┬──┬─────────┬─────────┬────────┬────────┐│ 1st Page│ 2nd Page │//│Last Page│ EOV or │ ****** │ ****** ││ Dumped │ Dumped │//│ Dumped │ EOT │ *TAPE* │ *TAPE* ││ Storage │ Storage │//│ Storage │ Record │ *MARK* │ *MARK* ││ │ │//│ │ │ ****** │ ****** │└─────────┴──────────┴──┴─────────┴─────────┴────────┴────────┘───────────────── D ─────────────────────────────────────────►|A Written by the stand-alone dump utility on the IPL tape at generation time.B Written by BOOTSTRAP on the IPL tape.C Written by BOOTSTRAP if the IPL tape is the same as the dump tape.Written by the stand-alone dump program if the IPL tape is not the same asthe dump tape.D Written by the stand-alone dump program on the dump tape.Figure 42. Stand-Alone Dump Facility Tape Format778 z/VM: CP Planning and Administration

Stand-Alone Dump FormatsDASD FormatWhen you use a DASD device to IPL the stand-alone dump program, the systemuses cylinder 0 to hold the program. Cylinder 0 must be CP-formatted and allocatedas permanent space. The stand-alone dump facility has the format shown inFigure 43.┌─────────┬─────────┬─────────┬─────────┐│ C0T0R1 │ COT0R2 │ C0T0R3 │ C0T0R4 │├─────────┼─────────┼─────────┼─────────┤│ │ │ │ ││ IPL │BOOTSTRAP│ VOLUME │ ALLOC. ││Sequence │ Part 1 │ LABEL │ MAP ││ │ │ │ │└─────────┴─────────┴─────────┴─────────┘│◄─────── A ───────►│◄─────── B ───────►│┌─────────┬─────────┬─────────┬─────────┐│ C0T1R1 │ C0T1R2 │ C0T2R1 │ C0T3R1 │├─────────┼─────────┼─────────┼─────────┤│ │ │ │ ││BOOTSTRAP│ SAD │ SAD │Predumped││ Part 2 │ Part 2 │ Part 3 │ Page ││ and SAD │ │ │ 0 ││ Part 1 │ │ │ │└─────────┴─────────┴─────────┴─────────┘│◄──────────── A ────────────►│◄── C ──►|┌─────────┬─────────┬─────────┬─────────┬─────────┐│ C0T3R2 │ C0T4R1 │ C0T4R2 │ C0T5R1 │ C0T5R2 │├─────────┼─────────┼─────────┼─────────┼─────────┤│ │ │ │ │ ││Predumped│Predumped│Predumped│Predumped│Predumped││ Page │ Page │ Page │ Page │ Page ││ 1 │ 2 │ 3 │ 4 │ 5 ││ │ │ │ │ │└─────────┴─────────┴─────────┴─────────┴─────────┘│◄────────────────────── D ────────────────────────┌─────────┬─────────┬─────────┬─────────┐│ C0T6R1 │ C0T6R2 │ C0T7R1 │ C0T7R2 │├─────────┼─────────┼─────────┼─────────┤│ │ │ │ ││Predumped│Predumped│Predumped│Predumped││ Page │ Page │ Page │ Page ││ 6 │ 7 │ 8 │ 9 ││ │ │ │ │└─────────┴─────────┴─────────┴─────────┘│◄────────────────────── D ─────────────|A Written by the stand-alone dump utility on the IPL DASD at generation time.B Written by the FORMAT/ALLOCATE program.C Written by the BOOTSTRAP Part 1 on the IPL DASD.D Written by the BOOTSTRAP Part 2 on the IPL DASD.CnTnRn identifies cylinder, track, and record numbers.Figure 43. Stand-Alone Dump Facility DASD FormatAppendix F. Stand-Alone Dump Formats 779

Stand-Alone Dump FormatsPrinter FormatDumps to printer devices are printed as follows:v CP formats the following data fields for each processor, beginning with theprocessor where the stand-alone dump program was IPLed:– The CPU address– General purpose registers– Control registers– Access registers (only if multiple address spaces [MAS] is installed)– Floating point registers 0, 2, 4, and 6– The TOD clock (only for the processor where the stand-alone dump programwas IPLed)– CPU timer values– The TOD clock comparator– The prefix register (when valid)– The stored-status PSW (only for non-IPL processors and only if there is avalid prefix register)– Old/new PSWs for the IPL processor when there is a valid prefix register:- External interrupt- SVC- Program check- Machine check- I/O interrupt.– The print storage start at absolute page 0.v Lines of duplicate data evoke a suppression message after the first line of thedata is printed.v A full page (4096 bytes) of all zeros has one line of zeros printed with the key,followed by a line-suppressed message.v The dump page is interpreted on the right-hand side of the printout.780 z/VM: CP Planning and Administration

NoticesIBM may not offer the products, services, or features discussed in this document inall countries. Consult your local IBM representative for information on the productsand services currently available in your area. Any reference to an IBM product,program, or service is not intended to state or imply that only that IBM product,program, or service may be used. Any functionally equivalent product, program, orservice that does not infringe any IBM intellectual property right may be usedinstead. However, it is the user’s responsibility to evaluate and verify the operationof 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 give you anylicense to these patents. You can send license inquiries, in writing, to:IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, New York 10594-1785U.S.A.For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106, JapanThe 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, EITHER EXPRESSOR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIESOF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR APARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not apply toyou.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 improvements and/orchanges in the product(s) and/or the program(s) described in this publication at anytime without notice.Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of thoseWeb sites. The materials at those Web sites are not part of the materials for thisIBM product and use of those Web sites is at your own risk.IBM may use or distribute any of the information you supply in any way it believesappropriate without incurring any obligation to you.Licensees of this program who wish to have information about it for the purpose ofenabling: (i) the exchange of information between independently created programs© Copyright IBM Corp. 1991, 2004 781

and other programs (including this one) and (ii) the mutual use of the informationwhich has been exchanged, should contact:IBM CorporationMail Station P3002455 South RoadPoughkeepsie, New York 12601-5400U.S.A.Attention: Information RequestSuch information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.The licensed program described in this information 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 of thoseproducts, their published announcements, or other publicly available sources. IBMhas not tested those products and cannot confirm the accuracy of performance,compatibility, or any other claims related to non-IBM products. Questions on thecapabilities of non-IBM products should be addressed to the suppliers of thoseproducts.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 illustrates programming techniques on various operating platforms. You maycopy, modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing, or distributing applicationprograms conforming to IBM’s application programming interfaces. These exampleshave not been thoroughly tested under all conditions. IBM, therefore, cannotguarantee or imply reliability, serviceability, or function of these programs.Programming Interface InformationThis book documents intended Programming Interfaces that allow the customer towrite programs to obtain services of z/VM.782 z/VM: CP Planning and Administration

TrademarksThe following terms are trademarks of the International Business MachinesCorporation in the United States, or other countries, or both:Advanced Function PrintingAFPDFSMS/VMDirMaintECKDEnterprise Storage ServerESCONeServerFICONHiperSocketsIBMIBMLinkLanguage EnvironmentMVSMVS/ESAMVS/XAOpenExtensionsOS/390Performance Toolkit for VMPrint Services FacilityRACFRAMACRETAINS/360S/370SAASQL/DSSystem/370System/390Systems Application ArchitectureTotalStorageVM/ESAVTAMz/Architecturez/OSz/VMzSeries30903890Linux is a trademark of Linus Torvalds in the United States, other countries, or both.Other company, product, and service names may be trademarks or service marksof others.Notices 783


GlossaryFor a list of z/VM terms and their definitions, seethe z/VM: Glossary book.The glossary is also available through the onlineHELP Facility. For example, to display thedefinition of “cms”, enter:help glossary cmsYou will enter the glossary HELP file and thedefinition of “cms” will be displayed as the currentline. While you are in the glossary HELP file, youcan also search for other terms.If you are unfamiliar with the HELP Facility, youcan enter:helpto display the main HELP menu, or enter:help cms helpfor information about the HELP command.For more information about the HELP Facility, seethe z/VM: CMS User’s Guide.© Copyright IBM Corp. 1991, 2004 785


BibliographyThis bibliography lists the books in the z/VMproduct library. For abstracts of these books andinformation about current editions and availablemedia, see z/VM: General Information.Where to Get z/VM Booksz/VM books are available from the followingsources:v IBM Publications Center atwww.ibm.com/shop/publications/order/v z/VM Internet Library atwww.ibm.com/eserver/zseries/zvm/library/v IBM eServer zSeries Online Library: z/VMCollection CD-ROM, SK2T-2067z/VM Base LibraryThe following books describe the facilities includedin the z/VM base product.SystemOverviewz/VM: General Information, GC24-6095z/VM: Glossary, GC24-6097z/VM: License Information, GC24-6102z/VM: Migration Guide, GC24-6103Installation and Servicez/VM: Guide for Automated Installation andService, GC24-6099z/VM: Service Guide, GC24-6117z/VM: VMSES/E Introduction and Reference,GC24-6130Planning and Administrationz/VM: CMS File Pool Planning, Administration,and Operation, SC24-6074z/VM: CMS Planning and Administration,SC24-6078z/VM: Connectivity, SC24-6080z/VM: CP Planning and Administration,SC24-6083z/VM: Getting Started with Linux on zSeries,SC24-6096z/VM: Group Control System, SC24-6098z/VM: I/O Configuration, SC24-6100z/VM: Performance, SC24-6109z/VM: Running Guest Operating Systems,SC24-6115z/VM: Saved Segments Planning andAdministration, SC24-6116z/VM: Secure Configuration Guide, SC24-6138z/VM: TCP/IP Planning and Customization,SC24-6125eServer zSeries 900: Planning for the OpenSystems Adapter-2 Feature, GA22-7477eServer zSeries: Open SystemsAdapter-Express Customer’s Guide andReference, SA22-7935eServer zSeries: Open SystemsAdapter-Express Integrated Console ControllerUser’s Guide, SA22-7990z/OS and z/VM: Hardware ConfigurationManager User’s Guide, SC33-7989Customizationz/VM: CP Exit Customization, SC24-6082Operationz/VM: System Operation, SC24-6121z/VM: Virtual Machine Operation, SC24-6128ApplicationProgrammingz/VM: CMS Application Development Guide,SC24-6069z/VM: CMS Application Development Guide forAssembler, SC24-6070z/VM: CMS Application Multitasking,SC24-6071z/VM: CMS Callable Services Reference,SC24-6072z/VM: CMS Macros and Functions Reference,SC24-6075z/VM: CP Programming Services, SC24-6084z/VM: CPI Communications User’s Guide,SC24-6085z/VM: Enterprise SystemsArchitecture/Extended Configuration Principlesof Operation, SC24-6094z/VM: Language Environment User’s Guide,SC24-6101z/VM: OpenExtensions Advanced ApplicationProgramming Tools, SC24-6104© Copyright IBM Corp. 1991, 2004 787

Endz/VM: OpenExtensions Callable ServicesReference, SC24-6105z/VM: OpenExtensions Commands Reference,SC24-6106z/VM: OpenExtensions POSIX ConformanceDocument, GC24-6107z/VM: OpenExtensions User’s Guide,SC24-6108z/VM: Program Management Binder for CMS,SC24-6110z/VM: Reusable Server Kernel Programmer’sGuide and Reference, SC24-6112z/VM: REXX/VM Reference, SC24-6113z/VM: REXX/VM User’s Guide, SC24-6114z/VM: Systems Management ApplicationProgramming, SC24-6122z/VM: TCP/IP Programmer’s Reference,SC24-6126Common Programming InterfaceCommunications Reference, SC26-4399Common Programming Interface ResourceRecovery Reference, SC31-6821OS/390: DFSMS Program Management,SC27-0806z/OS: Language Environment Concepts Guide,SA22-7567z/OS: Language Environment DebuggingGuide, GA22-7560z/OS: Language Environment ProgrammingGuide, SA22-7561z/OS: Language Environment ProgrammingReference, SA22-7562z/OS: Language Environment Run-TimeMessages, SA22-7566z/OS: Language Environment Writing ILCApplications, SA22-7563Usez/VM: CMS Commands and UtilitiesReference, SC24-6073z/VM: CMS Pipelines Reference, SC24-6076z/VM: CMS Pipelines User’s Guide,SC24-6077z/VM: CMS Primer, SC24-6137z/VM: CMS User’s Guide, SC24-6079z/VM: CP Commands and Utilities Reference,SC24-6081z/VM: Quick Reference, SC24-6111z/VM: TCP/IP User’s Guide, SC24-6127z/VM: XEDIT Commands and MacrosReference, SC24-6131z/VM: XEDIT User’s Guide, SC24-6132CMS/TSO Pipelines Author’s Edition,SL26-0018Diagnosisz/VM: Diagnosis Guide, GC24-6092z/VM: Dump Viewing Facility, GC24-6093z/VM: System Messages and Codes - AVS,Dump Viewing Facility, GCS, TSAF, andVMSES/E, GC24-6120z/VM: System Messages and Codes - CMSand REXX/VM, GC24-6118z/VM: System Messages and Codes - CP,GC24-6119z/VM: TCP/IP Diagnosis Guide, GC24-6123z/VM: TCP/IP Messages and Codes,GC24-6124z/VM: VM Dump Tool, GC24-6129z/OS and z/VM: Hardware ConfigurationDefinition Messages, SC33-7986Books for z/VM Optional FeaturesThe following books describe the optional featuresof z/VM.Data Facility StorageManagement Subsystem for VMz/VM: DFSMS/VM Customization, SC24-6086z/VM: DFSMS/VM Diagnosis Guide,GC24-6087z/VM: DFSMS/VM Messages and Codes,GC24-6088z/VM: DFSMS/VM Planning Guide, SC24-6089z/VM: DFSMS/VM Removable Media Services,SC24-6090z/VM: DFSMS/VM Storage Administration,SC24-6091Directory Maintenance Facilityz/VM: Directory Maintenance FacilityCommands Reference, SC24-6133z/VM: Directory Maintenance FacilityMessages, GC24-6134z/VM: Directory Maintenance Facility Tailoringand Administration Guide, SC24-6135788 z/VM: CP Planning and Administration

Performance Toolkit for VM z/VM: Performance Toolkit, SC24-6136Resource Access Control FacilityExternal Security Interface (RACROUTE)Macro Reference for MVS and VM,GC28-1366Resource Access Control Facility: Auditor’sGuide, SC28-1342Resource Access Control Facility: CommandLanguage Reference, SC28-0733Resource Access Control Facility: DiagnosisGuide, GY28-1016Resource Access Control Facility: GeneralInformation, GC28-0722Resource Access Control Facility: GeneralUser’s Guide, SC28-1341Resource Access Control Facility: Macros andInterfaces, SC28-1345Resource Access Control Facility: Messagesand Codes, SC38-1014Resource Access Control Facility: Migrationand Planning, GC23-3054Resource Access Control Facility: SecurityAdministrator’s Guide, SC28-1340Resource Access Control Facility: SystemProgrammer’s Guide, SC28-1343Bibliography 789


IndexSpecialcharacters*ACCOUNT system service 233, 494, 661*BLOCKIO system service 494*CONFIG system service 494*CRM system service 494*IDENT system service 496*LOGREC system service 314, 494, 669*MONITOR system service 494*MSG system service 494*MSGALL system service 494*RPI system service 494*SIGNAL system service 494*SPL system service 494*SYMPTOM system service 318, 494specifying virtual machines for 699*VSWITCH system service 494+ operand and − operandTIMEZONE_DEFINITION statement 239Numerics2250 displayrestriction against using 1242701 data adaptercoding an RDEVICE macro 7522741 terminalcoding an RDEVICE macro 7543088 MCCUcoding an RDEVICE macro 760defining in system configuration file 50requirement for CSE 335virtual, defining for virtual machine 557virtual, defining for virtual network adapters 5293101 displaycoding an RDEVICE macro 7343151 display terminalcoding an RDEVICE macro 7543161 display terminalcoding an RDEVICE macro 7543162 display terminalcoding an RDEVICE macro 7543163 display terminalcoding an RDEVICE macro 7543167 display terminalcoding an RDEVICE macro 7543172 controllerdefining 205defining in system configuration file 503174 controllercoding an RDEVICE macro 7573178 displaycoding an RDEVICE macro 734defining 1973179 displaycoding an RDEVICE macro 734defining 1973180 displaycoding an RDEVICE macro 734defining 1973190 displaydefining 1973191 displaycoding an RDEVICE macro 7343192 displaycoding an RDEVICE macro 7343193 displaycoding an RDEVICE macro 7343194 displaycoding an RDEVICE macro 7343203 printercoding an RDEVICE macro 716defining 201defining in system configuration file 47FCB imageadding 418example for coding new 419provided 413UCS buffer imageadding 414example of new 416provided 4123211 printercoding an RDEVICE macro 716defining 201defining in system configuration file 47FCB imageadding 418example for coding new 419provided 413UCS buffer imageadding 414example of new 417provided 4123250 displaycoding an RDEVICE macro 733, 734restriction against using 1243262 printercoding an RDEVICE macro 713, 716defining 201FCB imageadding 414, 418provided 413UCS buffer imageexample of new 417provided 4133268 display printercoding an RDEVICE macro 713defining in system configuration file 473270 console modedefining 4643270 displaydefining 197, 1983270_DISPLAY operandRDEVICE statement 210© Copyright IBM Corp. 1991, 2004 791

3270_PRINTER operandRDEVICE statement 2103270-PCcoding an RDEVICE macro 7343274 controllercoding an RDEVICE macro 7573277 displaycoding an RDEVICE macro 734defining 197, 198exit for installation-supplied code 3123277 operandRDEVICE statement 1983277_APL operandTRANSLATE_TABLE statement 2443277_TEXT operandTRANSLATE_TABLE statement 2453278 displaycoding an RDEVICE macro 734defining 1973278_APL operandTRANSLATE_TABLE statement 2453278_TEXT operandTRANSLATE_TABLE statement 2453279 displaycoding an RDEVICE macro 734defining 1973286 printercoding an RDEVICE macro 7133287 printercoding an RDEVICE macro 713defining in system configuration file 473288 printercoding an RDEVICE macro 7133289 printercoding an RDEVICE macro 713defining in system configuration file 473290 displaycoding an RDEVICE macro 734defining 1973350 DASDcoding an RDEVICE macro 746in 3330 compatibility mode 7463370 DASDcoding an RDEVICE macro 7493375 DASDcoding an RDEVICE macro 7463380 DASDcapacity information 605coding an RDEVICE macro 746defining 195defining in system configuration file 46using as a cached storage device 6283390 DASDcapacity information 605coding an RDEVICE macro 746defining 195defining as a full-pack minidisk 625defining in system configuration file 46migration considerations 617switching operating modes 615using as a cached storage device 6283420 tape unitdefining 2073422 tape unitcoding an RDEVICE macro 743defining 2073423 optical media attachmentdefining in system configuration file 503430 tape unitcoding an RDEVICE macro 7433480 tape unitcoding an RDEVICE macro 743defining in system configuration file 473490 tape drivecoding an RDEVICE macro 743defining in system configuration file 473495 tape library dataservercontrolled by a virtual machine 566defining in system configuration file 473505 card readercoding an RDEVICE macro 727defining 192defining in system configuration file 483525 card punchcoding an RDEVICE macro 729defining 190defining in system configuration file 483590 tape unitcoding an RDEVICE macro 743defining in system configuration file 473705 communication controllercoding an RDEVICE macro 754, 757defining 193defining in system configuration file 493705 operandRDEVICE statement 1943720 communication controllercoding an RDEVICE macro 757defining 193defining in system configuration file 493725 communication controllercoding an RDEVICE macro 754, 757defining 193defining in system configuration file 493737 remote channel-to-channel unitcoding an RDEVICE macro 760defining 205defining in system configuration file 503745 communication controllercoding an RDEVICE macro 754, 757defining 193defining in system configuration file 493800 operandRDEVICE statement 2123800 printercoding an RDEVICE macro 721creating a text deck for 411defining 189, 212defining in system configuration file 47image librarycreating 424description 411792 z/VM: CP Planning and Administration

3812 printercoding an RDEVICE macro 713defining in system configuration file 483816 printercoding an RDEVICE macro 713defining in system configuration file 483820 printercoding an RDEVICE macro 710defining 189defining in system configuration file 483825 printercoding an RDEVICE macro 708defining 189defining in system configuration file 483827 printercoding an RDEVICE macro 708defining 189defining in system configuration file 483828 printercoding an RDEVICE macro 708defining 189defining in system configuration file 483835 printercoding an RDEVICE macro 708defining 189defining in system configuration file 483850 DASDcoding an RDEVICE macro 7463890 document processorcoding an RDEVICE macro 731defining in system configuration file 503900 printercoding an RDEVICE macro 708defining 189, 212defining in system configuration file 484214 display printercoding an RDEVICE macro 7134224 display printercoding an RDEVICE macro 7134234 display printercoding an RDEVICE macro 7134245 printercoding an RDEVICE macro 713, 716defining 201defining in system configuration file 48FCB imageadding 418provided 4134248 printercoding an RDEVICE macro 716defining 201defining in system configuration file 48FCB imageadding external 420adding new 418provided 413FCB macro, example for coding 4214753 network security processordefining in system configuration file 505080 graphics displaycoding an RDEVICE macro 7405210 display printercoding an RDEVICE macro 7135550 displaycoding an RDEVICE macro 7346090 graphics displaycoding an RDEVICE macro 7406262 printercoding an RDEVICE macro 713, 716defining 201defining in system configuration file 487171 device attachment control unitcoding an RDEVICE macro 734defining in system configuration file 50802.3 local area network 7388232 LAN channel stationdefining 205defining in system configuration file 509032 ESCON Director Model 2defining 762sensed by CP 509033 ESCON Director Model 1defining 762sensed by CP 509034 ESCON Converter Model 1 509035 ESCON Converter Model 2 509221 integrated ethernetdefining in system configuration file 499221 integrated token ringdefining in system configuration file 499336 DASDcapacity information 605defining 1959345 DASDcoding an RDEVICE macro 746AABBREVLENGTH operandDEFINE ALIAS statement 82DEFINE CMD statement 85DEFINE COMMAND statement 85abnormal end (abend)list of consoles to receive messages about 124ACCEPTED operandDEVICES statement 105accessdisksby CP 70list control parameters 580modesdefined 501exclusive 327, 387exclusive, authorized to use 535minidisk definitions 515stable 327, 387stable, authorized to use 536read/write 349to spool files 370account number, defining for a virtual machine 456ACCOUNT operandJOURNALING statement 162Index 793

ACCOUNT user directory control statement 456ACCOUNT1 operandSYSTEM_USERIDS statement 233ACCOUNT2 operandSYSTEM_USERIDS statement 233accountingadding your own source code 310disassociating a user ID from retrieval of 298exit, CP 310recordadding your own 310dedicated device 300format of 299Inter-System Facility for Communications 304journaling 301SET PRIVCLASS 306, 307, 309SNA/CCS 304temporary disk space 301type 04 301type 05 302type 06 302type 07 304type 08 302type 09 304type 0A 306type 0I 303type 1 299type 2 300type 3 301type B 307type C 307type C0 310type D 309user-initiated 310virtual disk space 307virtual machine resource usage 299recordsspecifying user ID to accumulate 232setting up virtual machines for 295system service (*ACCOUNT) 233virtual machine, defining a user ID for 661virtual machine, logon identification 661ACCT option 394accumulateaccounting recordsspecifying user ID to 232EREP recordsdisassociating a user ID from retrieval of 317specifying user ID to 232symptom recordsspecifying user ID to 232system dump recordsspecifying user ID to 232ACIGROUP user directory control statement 458ACNT command 299activatean override file 438cross system spool 355adapterchannel-to-channeldefining 205adapter (continued)data, coding an RDEVICE macro 752linedefining 193line, coding an RDEVICE macro 754Local Area Network (LAN)defining 205teleprocessing integrated, coding an RDEVICEmacro 738addfiles to an image library 424forms control buffer 418, 420print buffer image 414real devicesto system’s definition 188your own accounting records and source code 310addressconsolealternate 766defining list for operator 180operator 766to receive emergency messages 124spacesdefining maximum nonprimary 583defining total size of nonprimary 583address space control parameters 580ADDRSPACE macrousing to create or delete address spaces 583administrationconsiderations summary 3CSE 358performance tasks 12real and virtual storage 7system tasks 4task overview 5user tasks 5advanced function printer (AFP)coding an RDEVICE macro 708defining 189AFP operandRDEVICE statement3800 printers 213advanced function printers 189impact printers 202AFTER_LOGON operandDEFINE CMD statement 85DEFINE COMMAND statement 85aliascreatingnew for existing CP command 81ALIAS operandXSPOOL_SYSTEM statement 271ALL operandDRAIN statement 118HOT_IO_RATE statement 152START statement 220allocatedevice blocks 689spaceXSPOOL trace tables 273794 z/VM: CP Planning and Administration

allocate (continued)storagewith STORAGE statement 222with SYSSTORE macro 697ALSERV macroadding and deleting entries with 581ALTCONS operandRIOGEN macro 766alternateparm disk 51system consoledefining on OPERATOR_CONSOLESstatement 180defining on RIOGEN macro 766ALTERNATE_OPERATORS statement 58ANYTIME operandDEFINE CMD statement 85DEFINE COMMAND statement 85AOFPARM parameter list 314AONPARM parameter list 312APAR (Authorized Program Analysis Report)process 400APPC/VM path 459APPCPASS user directory control statement 459architecture, System/390 397area, CSE 359ART (Access Register Translation)maintains storage protection 391translates addresses 390ASCII_1977 operandTRANSLATE_TABLE statement 244ASCII_1980 operandTRANSLATE_TABLE statement 244ASCII_LINE_DELETE operandCHARACTER_DEFAULTS statement 67ASCII-APL operandTRANSLATE_TABLE statement 244assigncommands to types of users 435exit point with entry points 60, 64exit point with external symbols 60, 64new classes 438associateclasses with users and commands 436exit point with entry points 60, 64exit point with external symbols 60, 64ASSOCIATE EXIT statement 51, 60ASSOCIATE MESSAGES statement 51, 64ASSOCIATE MSGS statement 51, 64attachexpanded storage to a virtual machine 592retained Expanded Storage 596ATTACH command 478, 623, 665ATTACH XSTORE command 592, 593AUDIT operandDEFINE CMD statement 85DEFINE COMMAND statement 85DEFINE DIAGNOSE statement 90auditing and protectingusing an external security manager 384authorization bypassdirectory password 385AUTO_WARM_IPL operanddisabling on FEATURES statement 140enabling on FEATURES statement 142AUTOLOG command 296, 299journaling 385prompting for password on 144AUTOLOG operandSYSTEM_USERIDS statement 233AUTOLOG user directory control statement 461, 578AUTOLOG1 service virtual machine 6automaticdeactivation of restricted passwords 386auxiliary storage 7avoiding DASD bottlenecks during I/O 337Bbackup and recovery, DASD for 337BEFORE_LOGON operandDEFINE CMD statement 85DEFINE COMMAND statement 85block, command table entrydefining new CP 84BOTTOM operandPRINTER_TITLE statement 182BSC_ADAPTER operandRDEVICE statement 193buffer, retrievespecifyingdefault number of 136maximum number of 136bypassing directory password authorization 385Ccabling, hardware 341cacheDASDdefining a minidisk for 629defining as a dedicated device 630description 628minidiskdevices available for 600performance considerations 602planning for 600special considerations 601turning off 600using 600using Expanded Storage as a 597capacity, DASDstorage 604card punch3525defining 190coding an RDEVICE macro 729configuration guide 48dedicating to virtual machine 477defining 190defining in system configuration file 48Index 795

card punch (continued)spooled, virtual machine 562card readercoding an RDEVICE macro 727configuration guide 48dedicating to virtual machine 477defining 192defining 3505 192defining in system configuration file 48generating default user form name for 150spooled, defining for virtual machine 562case used in system configuration files 56CCDUMP utility 321CCLOAD EXEC 323CCLOAD utility 321CCU (Common Control Unit) printercoding an RDEVICE macro 708CCW translation 427device macroinstruction 429ceasenew operations on real DASD 118use of X'15' 483users issuing multiple CP commands 483changeback to IBM-defined user classes 442command classes in directory 443defaultsCSE track location format 259for text of status fields 293logical character delete symbol 67logical escape symbol 67logical line delete symbol 67logical line end symbol 67logical tab symbol 67dynamic I/O 105, 141exit point 172hot I/O rate 152online message 292privilege class of CP functions 673privilege classes 433privilege classes authorizing CP functions 184CHANGE command 368change CSE track location format default 646changing information on minidisks 34channel path 12, 210, 764channel programs 390, 394, 397channel-to-channel linkdefining addresses 350CHAR_DELETE operandCHARACTER_DEFAULTS statement 67character delete symboldefinition 67CHARACTER_DEFAULTS statement 51, 67CHARS operandRDEVICE statement 202, 213checking syntax of statements in a system configurationfile 57checkpointdataallocating DASD space for 607SYSTEM_RESIDENCE statement 230choose local time zone at IPL 237CHOOSE_LOGO statement 279, 285choosing storage sizedynamic paging area 590CKD (Count-Key-Data)DASD 335, 603device geometry 603devicesdefining length of map records 269finding CSE track 269using for cross system link 650classassociating with users and commands 436command privilege defining for virtual machine 572IBMdefining for new CP command 84override fileactivating 440creating 438example 439verifying 440privilege 392authorizing CP functions, changing 184controlling which users can change 136defining for new CP command 84spool filecontaining classification titles 182specifying for impact printers 202CLASS statement 395CLASS user directory control statement 443, 445, 462CLASSES operandRDEVICE statement 190, 192, 213RDEVICE statement for impact printers 202classification titleprinted output classes containing 182classification titles, printer output 691clearminidisks 398T-disks 398TDISK space, specifying whether CP should 136CLEAR option on OVERRIDE utility 442CLEAR_TDISK operanddisabling on FEATURES statement 141enabling on FEATURES statement 142CMS (Conversational Monitor System)commandDIRECTXA 448SFS (Shared File System)DASD sharing using 622shared minidisk expanded storageconsiderations 592utilityCPFMTXA 665GENIMAGE 411IMAGELIB 423IMAGEMOD 424VMFHASM 412, 422codedistribution, defining for a virtual machine 456code, executableloading into CP’s system execution space 76796 z/VM: CP Planning and Administration

codingHCPRIO ASSEMBLE 705collectsetting up VM for 297commandACNT 299assigning new classes 438assigning to types of users 435ATTACH 478, 623, 665ATTACH XSTORE 592, 593AUTOLOG 144, 296, 299CHANGE 368conventions, notational xviCPSYNTAX 57creatingnew CP 84new version of existing CP 84DEDICATE 6, 630DEFINE CPU 5, 534DEFSEG 527DEFSYS 491DETACH XSTORE 593DISABLE 331DISABLE SNA 332DISCARD 747ENABLE 331FORCE 299, 332INDICATE LOAD 601IPL 491LINK 144, 299, 359, 501, 515, 535, 620LOGON 144, 299, 326MESSAGE 142MODIFY 165MSG 276MSGNOH 276notational conventions xviORDER 368preventing from issuing multiple 483privilege classdefining for virtual machine 462, 572IBM-defined 433redefining 433PURGE 369PURGE IMG 425PURGE UCR 442QUERYLOGMSG 143RETRIEVE 146QUERY (User ID) 277QUERY CACHE 747QUERY COMMANDS 446QUERY DASDFW 748QUERY FILES 369QUERY FRAMES 589QUERY IMG 424QUERY NAMES 277QUERY PINNED 747QUERY READER/PRINTER/PUNCH 369QUERY RSAW 747QUERY UCR 442QUERY UCR COUNT 442command (continued)QUERY XSTORE 594QUERY XSTORE MAP 592, 593response suppression 86, 166RETAIN XSTORE 591, 593, 596SET CACHE 747SET CONCEAL OFF 534SET D8ONECMD 381SET DASDFW 747SET DUMP 614SET MAXUSERS 535SET PRIVCLASS 382SET SHARED 601, 620SET SHARED OFF 620SET SHARED ON 626SET SRM 332, 537SHUTDOWN 299SMSG 276, 353SPOOL 665SPXTAPE 665START CSECOM 353supported by CSE 335syntax, explanation of xviTAG 369TERMINAL LINESIZE 331TRANSFER 369WNG 276XAUTOLOG 299, 332XLINK CHECK 353XLINK FORMAT 340, 652XLINK FORMAT (CP) 350XLINK RESET 359XSPOOL QUERY 354command table entry blockdefining new CP 84command, cross systemexcluding virtual machines’ input spool filesfrom 274excluding virtual machines’ output spool filesfrom 276specifying systems participating in 271commandsRECORDING command (CP)specifying EREP virtual machine 316comments field on SAPL screen 41comments in a system configuration file 55communicationcontrollercoding an RDEVICE macro 757configuration guide 49defining in system configuration file 49setting up a virtual machine for 321enabling SNA 331virtual machine (CVM)establishing connections between 350preparing 350verifying its functioning 353communication controller3705defining 193Index 797

communication controller (continued)3725defining 1933745defining 193defining 193COMMUNICATIONS_USERID operandXSPOOL_SYSTEM statement 271COMPONENT operandASSOCIATE MESSAGES statement 64ASSOCIATE MSGS statement 64composite reader file 396concurrent copy sessions 566concurrent virtual and real reserve/releasewhen to use 626configurationguideprinters 769guide for printers 769overview 23real storage 222real storage, defining 697specifying information 23configuration filelogodescription 279specifying file name and file type 164summary of statements 279systemignoring errors in 241imbedding files into 155summary of statements 51user defaultsstatements 279configuration guidecard punches 48card readers 48communication controllers 49DASD 46display devices 49ESCON devices 49other devices 50printers 47tape drives 47unit record devices 48CONS operandRIOGEN macro 766consoleaddressdefining list for emergency messages 124defining list for operator consoles 180alternate, defining on RIOGEN macro 766alternatesdefining 180, 766changing 464defining extended color 553defining extended highlighting 553emergency messagedefining 124mode, defining 3270 464console (continued)operatordefining 180, 766primarydefining 180, 766primary system, defining on RIOGEN macro 766CONSOLE operandFORM_DEFAULT statement 150CONSOLE user directory control statement 463continuations in system configuration files 55CONTROL operandCPXLOAD statement 77controllercoding an RDEVICE macro 757communication, defining 193conventionnotationalfor commands xviCoordinated Universal Time (UTC)SYSTIME macro 701copy sessions, concurrent 566copy spool descriptor 368CPstarting communication with manuallyEREP virtual machine 316CP (Control Program)accounting exit 310assigning new classes 438attaching Expanded Storage to 596commandACNT 299ATTACH 478, 623, 665ATTACH XSTORE 592, 593AUTOLOG 144, 296, 299CHANGE 368CPSYNTAX 57DEDICATE 6, 630DEFINE CPU 5, 534defining new 84DEFSEG 527DEFSYS 491DETACH XSTORE 593DISABLE 331DISABLE SNA 332DISCARD 747ENABLE 331FORCE 299, 332INDICATE LOAD 601IPL 491LINK 144, 299, 359, 501, 515, 535, 620LOGON 144, 299, 326MESSAGE 142MSG 276MSGNOH 276ORDER 368preventing from issuing multiple 483PURGE 369PURGE IMG 425PURGE UCR 442QUERY (User ID) 277QUERY CACHE 747798 z/VM: CP Planning and Administration

CP (Control Program) (continued)command (continued)QUERY COMMANDS 446QUERY DASDFW 748QUERY FILES 369QUERY FRAMES 589QUERY IMG 424QUERY LOGMSG 143QUERY NAMES 277QUERY PINNED 747QUERY RDR/PRT/PUN 369QUERY RETRIEVE 146QUERY RSAW 747QUERY UCR 442QUERY UCR COUNT 442QUERY VDISK 145QUERY XSTORE 594QUERY XSTORE MAP 592, 593RETAIN XSTORE 591, 593, 596SET CACHE 747SET CONCEAL OFF 534SET D8ONECMD 381SET DASDFW 747SET DUMP 614SET LOGMSG 141SET MAXUSERS 535SET PFnn RETRIEVE 145SET PRIVCLASS 136, 146, 382SET RETRIEVE 146SET SHARED 601, 620SET SHARED OFF 620SET SHARED ON 626SET SRM 332, 537SET VDISK 145SHUTDOWN 299SMSG 276, 353SPOOL 665SPXTAPE 665TAG 369TERMINAL LINESIZE 331TRANSFER 369WNG 276XAUTOLOG 299, 332XLINK CHECK 353XLINK FORMAT 340, 350, 652XLINK RESET 359disk accessestablishing 70exitsaccounting records 310HCPACU module 310HCPMSU module 373message function 373functionschanging privilege classes authorizing 184link feature 358macrosHCPDROP 311, 374HCPENTER 311, 374HCPEPILG 311, 374HCPEXIT 311, 374CP (Control Program) (continued)macros (continued)HCPPROLG 311, 374HCPUSING 311message commands, altering output 373moduleallocating DASD space for 605specifying initialization options for 689starting CP extensions at initialization time 663storageallocating for XSPOOL trace tables 273configuring 222, 697symptom recordspecifying user ID to accumulate 232system execution spaceloading CP routines into 76system residence disk 693system residence volumedefining 73describing layout 230use of devices 105volumedefining list 73identifying for cross system spooling 73CP LINK commandand CSL 359journaling 385CP storage for CSE trace tables, establish number ofpages 658CP_ACCESS statement 52, 70CP_ADDON_INITIALIZE_ROUTINES statement 52,72CP_OWNED statement 52, 73, 158CP-accessed minidisks 31, 33, 34CP-owned volume listchecking for valid object directory 447cross system extensions considerations 337defining 73generate a list of 664HCD 7HCM 7sequence of statements 57system use 7CPACCESS command 393CPCACHE command 393CPCACHE FILES file 33CPCHECKING operanddisabling on FEATURES statement 141enabling on FEATURES statement 142CPFMTXA (CMS utility) 7, 665CPREAD operandSTATUS statement 293CPRELEASE command 393CPSYNTAX command 57CPU power, allocating to users in user directory 555CPU user directory control statement 465CPXLOAD statement 52, 76createa class override file 438default system identifier 228default user form names 150Index 799

create (continued)image librarymap 424list of operator form numbers 247list of user DASD volumes 255list of user form names 247logo configuration file 279logo screens 282newalias for existing CP command 81CP command 84DIAGNOSE code 90exit point 94version of existing CP command 84stand-alone dump utility 403system configuration file 55system date format 225system identifier 226, 228text deckfor impact printers 412for the 3800 printer 411the user directory 451cross systemlinkdefining 359described 358facility utility program 349, 357generating 349in CSE 333initializing 349initializing minidisks for 349maximum number of systems supported 334,338maximum systems supported 656synchronizing directories 340verifying 353MESSAGE and QUERY commandsdefine virtual machines that will not participatein 659in CSE 334overview of statements 26spoolactivating 355and CSECOM task 371and PVM 371commands 368define virtual machines that will not participatein 659described 366enabling 353in CSE 334verifying 354cross system commandexcluding virtual machines’ input spool filesfrom 274excluding virtual machines’ output spool filesfrom 276specifying systems participating in 271cross system linkexcluding systems 263excluding volumes 266cross system link (continued)including systems 264including volumes 264, 268, 650cross system spoolingexcluding virtual machines’ input spool filesfrom 274excluding virtual machines’ output spool filesfrom 276identifying volumes for 73specifying systems participating in 271trace tablesallocating space for 273CRYPTO user directory control statement 468CSE (Cross-System Extensions)administering 358areadefault values for 365description of 359format 361formatting 350location 361map records on 363placing 340protecting 361track location format default, change 259, 646capabilities 333choosing minidisks to share 338commands and cross system spool 368complex, system topography 653components 333controlling CSL 359cross systemlink 333spool 334defining volumes containing minidisks to beshared 340enabling cross-system extensions 345example secondary pre-PROFILE EXEC 344generating CSL 349INCLUDE statement and 487initializing CSL 349installation planning 334installingcross-system extensions 345PVM 345the preparation package 335joining systems 353macroinstructionCSELDEV 646CSELVOL EXCLUDE 649CSELVOL INCLUDE 650CSESYS 653CSETRACE 658CSEUSER 659MDC (minidisk caching feature) 339MDISK statement 339MESSAGE and QUERY commands 334networking implications 357normal operation 368operation, define DASD volumes included in 650operation, define excluded DASD volumes 649800 z/VM: CP Planning and Administration

CSE (Cross-System Extensions) (continued)outages, preparing for 372overview 333performance considerations for CMS minidisks 339phasing into production environment 356preparing for 341preparing the CVM 350PVM networks 357requirements 334restrictions 335returning to non-CSE operation 372RSCS networks 357setting up 334SNA networks 358spool file limits 341supported features 335synchronizing directories 340SYSAFFIN statement and 487system definition using SYSTEM CONFIG 346trace tables, establish number of pages for CPstorage 658trackformat 361formatting 350location 361map records on 363users supported 334CSE area, multiple cylinders 350CSECOM taskand cross system spool 371starting 353, 357CSELDEV macro 646CSELVOL EXCLUDE macro 359, 649CSELVOL INCLUDE macro 359CSESYS (HCPSYS macroinstruction) 653CSETRACE (HCPSYS macroinstruction) 658CSEUSER macro 371, 659CSEVOL macroinstructionEXCLUDE list 338INCLUDE list 338, 650CTCA (Channel-to-Channel Adapter)coding an RDEVICE macro 760defining 205defining in system configuration file 50requirement for CSE 335virtual, defining for virtual machine 557CTCA operandRDEVICE statement 205CYL operandCSELVOL INCLUDE macro 650CYLINDER operandXLINK_VOLUME_INCLUDE statement 268DD8ONECMD settingfor server virtual machines 381D8ONECMD user directory control statement 483DASD (Direct Access Storage Device)administration overview 7allocating space on 603DASD (Direct Access Storage Device) (continued)avoiding bottlenecks during I/O 337backup and recovery 337coding an RDEVICE macro3350 7463350 (in 3330 compatibility mode) 7463370 7493375 7463380 7463390 7463850 7469332 7499335 7499336 7499345 746FB-512 749FBA DASD 749configuration guide 46count-key-data (CKD) 335CP-owneddefining 73CSE area 361dedicated 8, 622defining 195defining in system configuration file 46defining list of CP-owned volumes 73excluding volumes from cross system link 266extended count-key-data (ECKD) 335including volumes in cross system link 268performance measurement 365planning overview 7preparing volumes 361preventing new operations 118preventing shared devices 105restarting 220sharedaccess to minidisks 338defining in system configuration file 46I/O behavior 365performance 365spool files 337sharingamong multiple virtual machines and othersystems 624using CMS Shared File System 622using concurrent virtual and realreserve/release 625using MPLF 627using Parallel Access Volumes 632using real reserve/release 622without using virtual reserve/release 622sharing devices 105spacecheckpoint data 607dumps 614named saved systems 615paging space 610spooling space 613used for shared file pools 9warm start data 606stopping new operations 118Index 801

DASD (Direct Access Storage Device) (continued)storage capacities 604storage requirements 603unsupporteddefining 209used for minidisks 8user owned volumes, generating a list of 703volumes excluded from CSE 649volumes included in CSE 650DASD format, stand-alone dump 779DASD operandDRAIN statement 118HOT_IO_RATE statement 152RDEVICE statement 195, 209START statement 220DASDOPT user directory control statement 472DAT (Dynamic Address Translation)maintains storage protection 391translates addresses 390dataadaptercoding an RDEVICE macro 752transfer to CP spool files 532DATAMOVR virtual machine 380DATEFORMAT user directory control statement 475deactivation of restricted passwordautomatic 386DEDICATE command 6, 630DEDICATE user directory control statement 477, 623dedicatedAFP printers 708cached DASD 630DASD 8, 622device 477device accounting record 300devices 622HCD 11HCM 11unit record devices 11dedicated advanced function printerdefining 189defaultfor logical character delete symbol 67for logical escape symbol 67for logical line delete symbol 67for logical line end symbol 67for logical tab symbol 67number of RETRIEVE buffers 136system identifier 228text of status fields 293user form names 150DEFAULT operandCHOOSE_LOGO statement 286HOT_IO_RATE statement 153DEFAULTS command 396define3800 printers 2123900 printers 212access list size, host 581accounting virtual machine logon identification 661accounting virtual machine user ID 661define (continued)advanced function printers 189card punch 190card readers 192channel-to-channel adapters 205communication controllers 193configuration of real storage 697console mode 3270 464consoles for emergency messages 124DASD 195DASD excluded from cross system link 266DASD to be included in cross system link 268DASD volumes excluded from CSE 649DASD volumes included in CSE 650default system identifier 228dynamic paging area 590file for input area 291graphic display devices 197host access list size 581I/O devices 45, 705impact printers 201journaling facility 160LAN adapters 205line adapters 193list of CP-accessed disks 70list of cp-owned DASD volumes 664list of CP-owned DASD volumes 73list of installation-added entry points 72logo picture file 285maximum number of nonprimary addressspaces 583newalias for existing CP command 81CP command 84DIAGNOSE code 90exit point 94version of existing CP command 84online message 292primary system operator 687privilege classes for a virtual machine 444real devices 188real storage 697size of host access list 581SNA/CCS to VSCS 331special devices 205system console 157, 180, 766system date format 225system identifier 226, 228systems in cross system spooling 271systems participating in cross systemcommands 271tape units 207text of status fields 293time zone 239total size of nonprimary address spaces 583unsupported devices 209user IDs to perform special functions 232user owned DASD volumes 680users’ needs 434virtual machines for use during hardwareoutages 372802 z/VM: CP Planning and Administration

define (continued)virtual machines that will not participate in crosssystem spooling and cross system message andquery commands 659virtual processor 465volumes excluded from user volume list 251, 671volumes to be included in user volume list 253your system 51, 643DEFINE ALIAS statement 52, 81DEFINE CMD statement 52, 84DEFINE COMMAND statement 52, 84DEFINE CPOWNED command 393DEFINE CPU command 5, 534DEFINE DIAGNOSE statement 52, 90DEFINE EXIT statement 52, 94DEFINE LAN statement 52, 97DEFINE TIMEZONE command 393DEFINE VSWITCH statement 52, 100defining an emulated device 121defining global settings for use during userprocessing 486defining virtual LAN segment 97defining virtual switch segment 100definition ofset of real devices, adding to 188DEFSEG commandNAMESAVE statement relationship 527DEFSYS command 491degaussing 398DELAY operandCPXLOAD statement 78deleteexit point 172members from an image library 424delete symbol, defining for virtual machine 572describe topography of CSE complex 653DEST operandRDEVICE statement 202, 213DETACH XSTORE command 593determine local time zone 237DEVCLASS operandRDEVICE statement 209deviceadding real 188blockbuilding 105dynamic allocation of 689bringing online 105class definitions 773defining 45, 529, 557, 705defining for virtual machine expanded storagefacility 585disabling for dynamic I/O changes 105enabling for dynamic I/O changes 105features by class and type 775initializingafter IOMCK 136at IPL 105when added to the system 136limiting I/O rate 105measuring subchannels 105device (continued)model definitions 775preventingDASD sharing 105initialization at IPL 105sensing 46sharing DASD 105stand-alone dump 405supported 45tables for unsupported devices 428taking offline 105type definitions 773unit record 11unsupported 46coding an RDEVICE macro 763device class assemble files 427device number field on SAPL screen 40Device Support Facilityallocating DASD space for a directory 608used in switching 3390 operating modes 616DEVICES statement 52, 105DFSMS/VMsetting up virtual machines for 327DIAGNOSE codeassigning new classes 438creating new 90defining new 90restriction of 394using to initiate accounting records 310X'04' 394X'08' 381, 394, 483, 538X'14' 532X'28' 394X'3C' 394X'4C' 310, 394, 533, 538X'64' 527X'7C' 394X'84' 394, 535X'88' 535X'98' 380, 390, 394, 535, 538X'98' option 395, 397X'A0' 384X'DC' 533X'E4' 382, 501, 515, 534, 535, 536X'F8' 537directoryallocated space for 480calculating DASD space for 455changing 443changing a user 447CLASS 443controlMDISK 339SPOOLFILE 341CP system 395creating a user 447definition entry location 504entryexample for user class restructure 445nonshared 342options, RSCS 395Index 803

directory (continued)password authorization bypass 385profiles 455Shared File System 622single sourcebringing online 357defining volumes and cylinders 341space 338update-in-place 396updating a user 447DIRECTORY user directory control statement 350,448, 480DIRECTXA utility 448checking directory for errors 454checking directory for VM/SP directorystatements 455checking for VM/SP statements 455creating user directory with 451running the directory creation program 453DIRMAINT (Directory Maintenance) licensed programavoiding manual updates 381DATAMOVR virtual machine 380dual registration 381general description 379disabledynamic I/O changesfor specific devices 105on your processor 136I/O throttling 105log on password suppression 136DISABLE CMD statement 52, 110DISABLE command 331DISABLE COMMAND statement 52, 110DISABLE DIAGNOSE statement 52, 112DISABLE EXITS statement 52, 114DISABLE operandASSOCIATE EXIT statement 61DEFINE ALIAS statement 82DEFINE CMD statement 85DEFINE COMMAND statement 85DEFINE DIAGNOSE statement 90FEATURES statement 140JOURNALING statement 162DISABLE SNA command 332disabled wait state if parm disk is notCMS-formatted 51DISCARD command 747DISCONNECT operandSYSTEM_USERIDS statement 233disconnect status of system operator, specifying 232disconnectingEREP virtual machine 317primary system operatorfor EREP 316discontinuousexpanded storage 593saved segmentmodifying read-only 390diskclearing temporary 384disk (continued)CP-owneddefining 73preventing new operations 118stopping new operations 118DISK LOAD command 396displaydevicesdefining 197unsupported, defining 209DISPLAY HOST command 393display printers 713, 769display terminalcoding an RDEVICE macro 733, 7543101 7343178 7343179 7343180 7343191 7343192 7343193 7343194 7343250 7343270-PC 7343277 7343278 7343279 7343290 7345080 7405550 7346090 7407171 Device Attachment Control Unit 734coding an RDEVICE macro for 734configuration guide 49defining in system configuration file 49establishing the SNA environment 330graphiccoding an RDEVICE macro for 5080 740coding an RDEVICE macro for 6090 740operator identification card 49planning for 10DISPLAY_STORAGE operandTRANSLATE_TABLE statement 243displayingcommands available to a user 446distributed IUCV 116document processorcoding an RDEVICE macro 731documentationconsiderations when redefining classes 438DPA (Dynamic Paging Area)size considerations 590DPMSIZE operanddelayed purge queue 213RDEVICE statement 213DPS operandRDEVICE statement 210DRAIN statement 52, 118DRAWLOGO sample utility programdescription 642usage 282804 z/VM: CP Planning and Administration

DROPBUF command 399DTIGEN macro 330dual registration 381dumpspaceallocating DASD space for 614stand-alone, utility 403symptom recordsspecifying user ID to accumulate 232DUMP HOST command 393DUMP operandCP_OWNED statement 74SYSTEM_USERIDS statement 233dumps 396dynamicI/O reconfiguration 12switching devicecoding an RDEVICE macro 762dynamic I/Odisablingfor specific devices 105on your processor 136enablingfor specific devices 105on your processor 136on your processor 136dynamic I/O featureson your processor 136dynamic switching devicedefining 209EEAST operandTIMEZONE_DEFINITION statement 239ECKD (Extended Count Key Data)devicesdefining length of map records 269finding CSE tracks 269using for cross system link 650EDEVICE statement 52, 121ELAN 738emergency messagedefiningconsoles to receive 124EMERGENCY_MESSAGE_ CONSOLESstatement 52, 124emulated device, defining 121EMULATED_3270 operandRDEVICE statement 198enablecross system spool 353dynamic I/O changesfor specific devices 105on your processor 136I/O throttling 105log on password suppression 136SNA communication 331steps for CSE 345system to set and query journaling facility 160ENABLE CMD statement 52, 126ENABLE command 331ENABLE COMMAND statement 52, 126ENABLE DIAGNOSE statement 52, 128ENABLE EXITS statement 52, 130ENABLE operandASSOCIATE EXIT statement 61DEFINE ALIAS statement 82DEFINE CMD statement 85DEFINE COMMAND statement 85DEFINE DIAGNOSE statement 91FEATURES statement 142enabling, CP exit 43endnew operations on real DASD 118use of X'15' 483users issuing multiple CP commands 483end HCPSYS assembly 668ENFORCE_BY_VOLid statement 52, 132enforcingattachment of DASD devices by their VOLIDs 132link protocols 358entry block, command tabledefining new CP 84entry pointassigning to exit point 60, 64specifying for new CP command 84EP (Emulation Program)setting up a virtual machine for 321used with 3720 49EPNAME operandASSOCIATE EXIT statement 61ASSOCIATE MESSAGES statement 65ASSOCIATE MSGS statement 65DEFINE CMD statement 85DEFINE COMMAND statement 85DEFINE DIAGNOSE statement 91EXTERNAL_SYNTAX statement 135MODIFY CMD statement 166MODIFY COMMAND statement 166MODIFY DIAGNOSE statement 170EQUATE statement 52, 133EREP (Environmental Record Editing and Printing)specifying user ID to accumulate records 232EREP operandof RECORDING command 316EREP recordsretrieval ofstarting manually 316EREP virtual machinespecifying 316starting record retrieval manually 316EREP1 operandSYSTEM_USERIDS statement 233EREP2 operandSYSTEM_USERIDS statement 233errorignoring system configuration file 241recordingsetting up virtual machine(s) for 314virtual machine, defining a user ID for 669Index 805

escape characterdefault 67setting 67, 572ESCAPE operandCHARACTER_DEFAULTS statement 67ESCM (Enterprise Systems Communication Manager)*CONFIG system service 494, 497ESCON devicesconfiguration guide 49defining in system configuration file 49ESM (External Security Manager)using to audit security 384using to protect security 384establishdefault forlogical character-delete symbol 67logical escape symbol 67logical line-delete symbol 67logical line-end symbol 67logical tab symbol 67number of RETRIEVE buffers 136system identifier 228text of status fields 293file mode 70maximum number of users 136system attributes 136system date format 225system identifier 226establish number of pages for CP storage for CSE tracetables 658Ethernet communication adapterdefining in system configuration file 49example3203 UCS buffer image 4163211 UCS buffer image 4173262 UCS buffer image 417alias, creating for CP command 83assigning commands to kinds of users 435assigning entry points to exit points 63associating privilege classes with commands andusers 436changing privilege classes 168, 171CHOOSE_LOGO statements 289CKD-formatted CSE area map 361, 362class override file 439coding FCB macroinstruction for 4248 printer 421commands, disabling CP 111commands, enabling CP 127communications controller functions 322configuration file statementALTERNATE_OPERATORS 59ASSOCIATE EXITS 63ASSOCIATE MESSAGES 66ASSOCIATE MSGS 66CHARACTER_DEFAULTS 69CP_ACCESS 71CP_ADDON_INITIALIZE_ ROUTINES 72CP_OWNED 75, 159CPXLOAD 80DEFINE COMMAND 83, 88DEFINE DIAGNOSE 93example (continued)configuration file statement (continued)DEFINE EXIT 96DEVICES 108DISABLE CMD 111DISABLE COMMAND 111DISABLE DIAGNOSE 113DISABLE EXITS 115DRAIN 119EMERGENCY_MESSAGE_ CONSOLES 125ENABLE CMD 127ENABLE COMMAND 127ENABLE DIAGNOSE 129ENABLE EXITS 131EQUATE 134FEATURES 134, 147, 156FORM_DEFAULT 150HOT_IO_RATE 154IMBED 155INIT_MITIME 157JOURNALING 163LOGO_CONFIG 164MODIFY COMMAND 168MODIFY DIAGNOSE 171MODIFY EXIT 174OPERATOR_CONSOLES 181PRINTER_TITLE 183PRIV_CLASSES 185RDEVICE (3800 printers) 215RDEVICE (AFP) 189RDEVICE (card punches) 191RDEVICE (card readers) 192RDEVICE (DASD) 196RDEVICE (graphic display devices) 199RDEVICE (impact printers) 204RDEVICE (line adapters) 194RDEVICE (special devices) 205RDEVICE (tape units) 207RDEVICE (unsupported devices) 211START 119, 221STORAGE 224SYSTEM_DATEFORMAT 225SYSTEM_IDENTIFIER 227, 228SYSTEM_IDENTIFIER_ DEFAULT 227, 228SYSTEM_RESIDENCE 231SYSTEM_USERIDS 234THROTTLE 236TIMEZONE_BOUNDARY 237, 238TIMEZONE_DEFINITION 239TOLERATE_CONFIG_ ERRORS 242TRANSLATE_TABLE 245USER_DEFAULTS 250USER_VOLUME_EXCLUDE 252USER_VOLUME_INCLUDE 254USER_VOLUME_LIST 256USERFORM 247XLINK_SYSTEM_EXCLUDE 263XLINK_SYSTEM_INCLUDE 264XLINK_VOLUME_EXCLUDE 266XLINK_VOLUME_INCLUDE 270XSPOOL_SYSTEM 272806 z/VM: CP Planning and Administration

example (continued)configuration file statement (continued)XSPOOL_TRACE 273XSPOOL_XLIST_INPUT 275XSPOOL_XLIST_OUTPUT 277CP command, creating alias for 83CP system execution space, loading CP routinesinto 80CPACCESS command 32, 36CPCACHE command 33CPCACHE FILES file 33CPLISTFILE command 33, 34CPRELEASE command 32, 35CPTYPE command 34creating alias for CP command 83CSE spooling commands 369dedicated DASD 622dedicating a device 622defining minidisk on a cached DASD 630DIAGNOSE codes, disabling 113DIAGNOSE codes, enabling 129directory calculation 609directory entries for CSE 342directory entries for user class restructure 445disabling CP commands 111disabling DIAGNOSE codes 113displayingDIAGNOSE codes 93ECKD-formatted CSE area map 364enabling CP commands 127enabling DIAGNOSE codes 129entry points, assigning to exit points 63exit pointassigning entry points to 63defining 96modifying 174start having CP use 131stopping CP from using 115expanded storage fragmentation 594generating the stand-alone dump utility 406GENIMAGE utility 411INPUT_AREA statement 291IPL command 39LINK command 35, 620loading CP routines into CP’s system executionspace 80macroCSESYS 657SYSACNT 661SYSADDIN 663SYSCPVOL 666SYSDUMP 667SYSEND 668SYSEREP 669SYSEXCL 671SYSFCN 674SYSFORM 676SYSID 679SYSINCL 680SYSJRL 684SYSMAXU 686example (continued)macro (continued)SYSOPR 688SYSPCLAS 692SYSRES 695SYSSYMP 699SYSTIME 702SYSUVOL 703message repositories, using local 66named saved system calculation 615ONLINE_MESSAGE statement 292operator restrictions to increase systemsecurity 382OVERRIDE control statement 439overriding commands 168overriding DIAGNOSE codes 171paging space calculation 611pre-profile exec 342PVM 323QUERY CPDISKS command 31, 35QUERY LOGMSG command 31, 35RDEVICE macro2741 7553151 7553161 7553162 7553163 7553167 7553800 printer 725advanced function printers 709card punch 730card readers 728communication controllers 755, 758CTCA 760DASD 748defining system console 767display printers 714display terminals 733, 736, 740document processor 731FBA DASD 750line adapters 752MCCU 760printers 710, 719tape drives 743telecommunication integrated adapters 739unsupported DASD 765redefining commands 168redefining DIAGNOSE codes 171RIOGEN macro 767SAPL screen 40secondary pre-PROFILE EXEC 344SET SHARED command 620SET SHARED ON command 626share minidisk among virtual machines 619spooling space calculation 615start having CP use exit point 131STATUS statement 294stopping CP from using exit point 115SYSEXCL macro 671SYSINCL macro 680SYSOPTS macro 690Index 807

example (continued)SYSSTORE macro 698system execution space, loading CP routinesinto 80turning on or offDIAGNOSE codes 113, 129user directory control statementACCOUNT 457ACIGROUP 458APPCPASS 460CLASS 462CONSOLE 464CPU 466CRYPTO 470D8ONECMD 484DATEFORMAT 476DEDICATE 479DIRECTORY 481INCLUDE 487IPL 492IUCV 498LINK 503LOAD 506LOGONBY 509MACHINE 511MDISK 519MINIOPT 526NAMESAVE 528NICDEF 531NOPDATA 532OPTION 538POOL 540POSIXGLIST 542POSIXGROUP 544POSIXINFO 547POSIXOPT 549PROFILE 552SCREEN 554SHARE 556SPECIAL 560SPOOL 564SPOOLFILE 565SYSAFFIN 570USER 576XAUTOLOG 578XCONFIG 584XSTORE 586using local message repositories 66utility programs 641VMLINK CMS command 620warm start area calculation 607excludeDASD volumes from cross system link 266, 649input spool files from cross system spooling andcommands 274, 276systems from cross system link 263volumes from user volume list 251, 671exclusion listincluding user ID on 371exclusiveaccess mode 327, 387exclusive (continued)access mode, authorized to use 535EXECHCPSADMP 409executable codeloading into CP’s system execution space 76exit pointassigning entry points and external symbols to 60assigning entry points to 64changing 172creating 94permitting CP to call entry points and externalsymbols associated with 130preventing CP from calling entry points and externalsymbols associated with 114removing 172exitsaccountingCP 310CPaccounting records 310HCPACU module 310HCPMSU module 373message function 373HCPACU modulecontents 311entry point HCPACUOF 313entry point HCPACUON 312function 310usage notes 311when called by CP 310HCPMSU modulecontents 373entry point HCPMSUEX 374function 373process flow 377usage notes 373when called by CP 373installation-wideaccounting, CP 310CP accounting records 310CP message function 373HCPACU module 310HCPMSU module 373expanded storage facilityadministration overview 7attaching to a virtual machine 592attaching to CP 596considerations with shared CMS minidisks 592dedicating to a virtual machine 585discontinuous 593fragmentation 593mapping 593overview 591planning 9planning overview 7retained 596, 597use as a minidisk cache 597extendedcolor optiondefining 553808 z/VM: CP Planning and Administration

extended (continued)count-key-data (CKD)DASD 335highlighting optiondefining 553extended-configuration facility control parameters 580extensions, initialization time starting CP 663extent field on SAPL screen 41external symbolassigning to exit point 60, 64EXTERNAL_SYNTAX statement 53, 135FFACILITIES operandJOURNALING statement 161FAIL operandD8ONECMD statement 483FBA (Fixed-Block Architecture)DASD 603coding an RDEVICE macro 749device geometry 604fundamentals 603FCB (Forms Control Buffer)3203 printer 4133211 printer 4133262 printer 4134245 printer 4134248 printer 413adding a new image3203 printer 4183211 printer 4183262 printer 4184245 printer 4184248 printer 418, 420example of new image 419, 421IBM provided 418macroinstruction 418, 420naming convention 416FCB operandRDEVICE statement 202, 214FCP operandRDEVICE statement 205FEATURES statement 53, 136fileadding to an image library 424CPCACHE FILES 33defining for input area 291list used by SAPL 42logo configurationdescription 279specifying file name and file type 164statements 279summary of statements 279logo picturechoosing 285selection 288separator pages 289, 290width 288major VM/ESA to know 3file (continued)pooldefined 622server machine 622spoolclass, specifying for impact printers 202system configurationignoring errors in 241imbedding files into 155summary of statements 51USER_DEFAULTS 248user class restructure HELP 437user defaultsspecifying default attributes 248file modeestablishing 70file nameof logo configuration file, specifying 164of system configuration file, specifying 42FILE operandCHOOSE_LOGO statement 287file typeof logo configuration file, specifying 164of system configuration file, specifying 43FILTER operandTRANSLATE_TABLE statement 243FLASH operandRDEVICE statement 214FOLDUP operandRDEVICE statement 203FOLLOWING operandASSOCIATE EXIT statement 60ASSOCIATE MESSAGES statement 64ASSOCIATE MSGS statement 64FORCE command 299, 332formnames, creating list of user 247numbers, creating list of operator 247specifying default values 675FORM operandRDEVICE statement for 3800 printers 214RDEVICE statement for card punches 190RDEVICE statement for impact printers 203FORM_DEFAULT statement 53, 150formatCKD-formatted CSE area 361CSE area 350ECKD-formatted CSE area 363system configuration file 55fragmentationexpanded storage 593free storage used by CP for a user ID 538full-pack minidisk 625, 630restricting and auditing 382FULLPROMPT 396Ggatewaysystemidentifying 226, 228Index 809

GATEWAY operandSYSTEM_IDENTIFIER statement 226SYSTEM_IDENTIFIER_ DEFAULT statement 228generatedefault system identifier 228default user form names 150list of cp-owned DASD volumes 664list of CP-owned volumes 73list of operator form numbers 247list of user DASD volumes 255list of user form names 247system date format 225system identifier 226, 228XLINK utility program 349GENIMAGE utility 411global attributes 257GLOBALDEFS user directory control statement 485GLOBALOPTS user directory control statement 486GLOBALV variables 399glossary information 785GRAF operandHOT_IO_RATE statement 152graphic display devicesdefining 197GRAPHICS_APL operandTRANSLATE_TABLE statement 243GRAPHICS_NONAPL operandTRANSLATE_TABLE statement 243GRAPHICS_TEXT operandTRANSLATE_TABLE statement 243group name, defining for virtual machine 458group of systems, naming 133guest devices, attaching 478Hhaltnew operations on real DASD 118use of X'15' 483users issuing multiple CP commands 483hardware, cabling 341HCDCP-owned DASDs 7DASDs used for minidisks 8dedicated DASDs 8dedicated unit record devices 11I/O reconfiguration 12IODF statement 53, 158NOHCD IPL opton 43spooled unit record devices 11terminals 10HCMCP-owned DASDs 7DASDs used for minidisks 8dedicated DASDs 8dedicated unit record devices 11I/O reconfiguration 12IODF statement 53, 158NOHCD IPL opton 43spooled unit record devices 11terminals 10HCPACU exit modulecontents 311function 310HCPACUOF entry pointAOFPARM parameter list 314function 313input registers 312, 314return code 314when called by CP 313HCPACUON entry pointAONPARM parameter list 312function 312input registers 312return codes 313when called by CP 312usage notes 311when called by CP 310HCPBOX ASSEMBLE fileoverriding 282HCPDROP macroHCPACU module 311HCPMSU module 374HCPENTER macroHCPACU module 311HCPMSU module 374HCPEPILG macroHCPACU module 311HCPMSU module 374HCPEXIT macroHCPACU module 311HCPMSU module 374HCPMSU exit modulecontents 373function 373HCPMSUEX entry pointfunction 374input registers 374parameter list 374return codes 374when called by CP 374process flow 377usage notes 373when called by CP 373HCPPROLG macroHCPACU module 311HCPMSU module 374HCPRIO ASSEMBLE filecoding 705device support 45macroinstructions 45, 705HCPSADMP example 407HCPSADMP EXEC 403, 409HCPSAVBK save areacontents 312used by CP accounting exit 312used by CP message function exit 374HCPSDC ASSEMBLE file 404HCPSDC TEXT file 404HCPSYS ASSEMBLE filecoding 644macroinstruction 643810 z/VM: CP Planning and Administration

HCPSYS ASSEMBLE file (continued)CSELDEV 646CSELVOL EXCLUDE 649CSELVOL INCLUDE 650CSESYS 653CSETRACE 658CSEUSER 659SYSACNT 661SYSADDIN 663SYSCPVOL 447, 664SYSDUMP 667SYSEND 668SYSEREP 669SYSEXCL 671SYSFCN 575, 673SYSFORM 675SYSID 677SYSINCL 680SYSJRL 682SYSMAXU 686SYSOPR 687SYSPCLAS 691SYSRES 693SYSSTORE 697SYSSYMP 699SYSTIME 701SYSUVOL 703HCPUSING macro, HCPACU module 311header for global definition section 485HELP files 437high-level data link control (X.25 network) 738HIPERSockets operandRDEVICE statement 205HOLD operandRDEVICE statement 198HOLDING operandSTATUS statement 293host access list size, defining 581hot I/O ratechanging 152setting 152HOT_IO_RATE statement 53, 152HW_SERVICE operandPRIV_CLASSES statement 184II/O (input/output)avoiding DASD bottlenecks 337configurationIOCP 184, 673, 705task overview 12devicedefinitions 45distributing load among them 336sensing 45devicessetting hot I/O rate for 152dynamicdisabling for specific devices 105disabling on your processor 136I/O (input/output) (continued)dynamic (continued)enabling for specific devices 105enabling on your processor 136machine checkinitializing devices after 136performance measurementfor shared DASD 365reconfiguration 12reconfiguration by z/VM 12I/O rate, hotchanging 152setting 152IBM-defined user classchanging back to 442IBM1_ADAPTER operandRDEVICE statement 193IBMCLASS operandDEFINE ALIAS statement 82DEFINE CMD statement 86DEFINE COMMAND statement 86DISABLE CMD statement 110DISABLE COMMAND statement 110ENABLE CMD statement 126ENABLE COMMAND statement 126MODIFY CMD statement 166MODIFY COMMAND statement 166identification of users, requirements for 391identify4-digit years 225minidisk to CP 70processor running z/VM 226, 228system gateway 226, 228volumes for cross system spooling 73ignoresystem configuration file errors 241ILAN 738image libraryadding files to 424deleting members from 424description of 411displaying information about 424installing 423keeping backup copies of 425map creating 424modifying 424printercreating 411modifying 411purging 425replacing members 424replacing modules 424IMAGE_LIBRARY operandRDEVICE statement 203, 214IMAGELIB utility 423IMAGEMOD utility 424imbed files into system configuration file 155IMBED statement 53, 155impact printer 716creating image library for 424creating text deck for 412Index 811

impact printer (continued)defining 201image library, description 411IMPACT_PRINTER operandRDEVICE statement 202includeDASD in cross system link 268DASD volumes in cross system link 650journaling facility in system 160password suppression facility in system 136systems in cross system link 264volumes in user volume list 253, 680INCLUDE user directory control statement 487INDEX operandRDEVICE statement 203INDICATE LOAD command 601INIT_MITIME statement 53, 157initial state of CP file system 31initializedevicesafter IOMCK 136when added to the system 136minidisk volumes for cross system link 349options for CP, specifying 689preventing devices at IPL 105specific devices at IPL 105inputarea, defining file for 291INPUT operandTRANSLATE_TABLE statement 244INPUT_AREA statement 279, 291input/output configuration (IOCP) utility 176, 184, 673,705installcross system extension 345CSE, planning 334image library 423integrated communication adaptersdefining 738defining in system configuration file 49Integrated Cryptographic Facility 383defining for virtual machines 388maximum number of users 388use with VM/ESA 387integrity problems, reporting 400internal trace tableallocating space for 222, 697interpretive-execution mode 390interrupt, unsolicitedchanging 152setting 152INVAR operandDEFINE DIAGNOSE statement 91INVXC operandDEFINE DIAGNOSE statement 91IOCP (input/output configuration) 184, 673, 705IOCP_READ operandPRIV_CLASSES statement 184IOCP_WRITE operandPRIV_CLASSES statement 184IOPRIORITY user directory control statement 488IPL (Initial Program Load)imbedding files into system configuration file 155parameters on SAPL screen 41parameters passed via SAPL 42process 31IPL at log on 490IPL command 491IPL user directory control statement 490IPOLL function, with GCS 332ISFC (Inter-System Facility for Communications)accounting record 304isolation 337IUCV (Inter-User Communication Vehicle)authorizing virtual machines that use 493IUCV user directory control statement 493Jjoining systems 353journalaccounting record 301AUTOLOG command 385including 682LINK command 385LOGON command 385XAUTOLOG command 385journalingsecurityincluding facility in system 160JOURNALING statement 53, 160LLAN (Local Area Network)802.3 738adaptersdefining 205IBM Token Ring 738LAN_ADAPTER operandRDEVICE statement 205LDEV operandCHOOSE_LOGO statement 286LET operandCPXLOAD statement 78limitI/O rate for specific devices 105number of retrieve buffers 136number of users 136LIMIT operandRDEVICE statement 203, 214line adapterscoding an RDEVICE macro 754defining 193line delete characterdefining for virtual machine 572definition 67line end characterdefining for virtual machine 572definition 67LINE_DELETE operandCHARACTER_DEFAULTS statement 68812 z/VM: CP Planning and Administration

LINE_END operandCHARACTER_DEFAULTS statement 68linkaccess modes 387cross systemexcluding systems 263excluding volumes 266, 649including systems 264including volumes 264, 268, 650defining 359defining minidisk 358protocols 358verifying 353LINK command 299, 501, 515, 535, 620prompting for password on 144LINK operandJOURNALING statement 161LINK statements 395LINK user directory control statement 9, 500, 620LINKS optionDRAIN statement 119START statement 220listdefining size of host access 581of consoles to receive emergency messages 124of CP-owned volumes, defining 73of possible system consoles, defining 180of user DASD volumes, generating 255user form names, creating 247loadCP routines into CP’s system execution space 76load origin field on SAPL screen 41LOAD user directory control statement 504LOADDEV user directory control statement 507LOCAL operandCHOOSE_LOGO statement 286local time zonechoosing at IPL 237defining 239determining 237LOCATE command 393location, CSE area 361LOCK operandCPXLOAD statement 77D8ONECMD statement 483lock pages 394, 397LOCKOUT operandJOURNALING statement 162logmessagesQUERY LOGMSG command 31specifying whether CP should display 136log onautomaticallyrecording invalid attempts 160defining new CP command to issue before 84identificationaccounting virtual machine 661error recording virtual machine 669primary system operator 687system dump virtual machine 667log on (continued)identification, defining virtual machine user 572limitoverriding 535specifying 686maximum number of usersspecifying 136password defining for virtual machine user 572password suppression 387including facility in system 136LOG operandD8ONECMD statement 483logical character delete symbolestablishing default 67logical devicechoosing logo 285logical escape characterestablishing default 67logical line delete characterestablishing default 67logical line end characterestablishing default 67logical symbol, establishing defaultfor character delete 67for escape 67for line delete 67for line end 67for tab 67logical tab characterestablishing default 67LOGMSG_FROM_FILE operanddisabling on FEATURES statement 141enabling on FEATURES statement 142logo configuration filecontents 28description 279limit and audit access 380overview 28specifying file name and file type 164statements 279CHOOSE_LOGO 285INPUT_AREA 291ONLINE_MESSAGE 292STATUS 293summary of statements 279logo picture filechoosing 285selection 288separator pages 289, 290width 288logo screens, creating 282LOGO_CONFIG statement 53, 164LOGON command 299, 326journaling 385prompting for password on 144LOGON operandJOURNALING statement 162LOGONBY user directory control statement 509Index 813

MMAC operandDEFINE CMD statement 86DEFINE COMMAND statement 86DEFINE DIAGNOSE statement 91machine checkI/Oinitializing devices after 136MACHINE user directory control statement 510macroinstructionCPHCPDROP 311, 374HCPENTER 311, 374HCPEPILG 311, 374HCPEXIT 311, 374HCPPROLG 311, 374HCPUSING 311CSELDEV 646CSELVOL EXCLUDE 338, 359, 649CSELVOL INCLUDE 338, 359, 650CSESYS 653CSETRACE 658CSEUSER 371, 659DTIGEN 330FCB 418, 420HCPSYS 643RDEVICE 706RIOGEN 766SYSACNT 6, 661SYSADDIN 663SYSCPVOL 337, 447, 620, 664SYSDUMP 6, 667SYSEND 668SYSEREP 6, 669SYSEXCL 671SYSFCN 575, 673SYSFORM 675SYSID 677SYSINCL 680SYSJRL 682SYSMAXU 686SYSOPR 6, 687SYSOPTS 689SYSPCLAS 691SYSRES 391, 605SYSSTORE 697SYSSYMP 699SYSTIME 701SYSUVOL 8, 620, 703UCSI 415UCSICCW 415main storage, allocation of 397MAINT virtual machine 32MAKEBUF command 399map recordand number of sharing VM systems 359defaults 652displaying indicators 363length 652number 652on CSE area 363MAP_RECORD_LENGTH operandXLINK_VOLUME_INCLUDE statement 268MAP_RECORDS operandXLINK_VOLUME_INCLUDE statement 268mappingexpanded storage 593maximumnumber of users, specifying 136maximum systems supportedfor cross system link 334, 338, 656maximum user limitoverriding 535MAXSTORAGE user directory control statement 512MAXUSERS operandFEATURES statement 144MCCU (Multisystem Channel Communications Unit)requirement for CSE 335MDC (minidisk caching feature)in CSE 339MDISK user directory control statement 9, 339, 513,625memberdeleting from an image library 424replacing in an image library 424MEMBER operandCPXLOAD statement 77messagecommands, CP, altering output 373log onspecifying whether CP should display 136online, changing 292MESSAGE and QUERY commandsin CSE 334MESSAGE command, altering output 373MESSAGE operandJOURNALING statement 162migrationincompatibility note 656, 678planning 3minidiskaccess modes 515accessingby CP 70as units of data control 358available for caching 600cache performance considerations 602cache using expanded storage as a 597cache, special considerations 601caching 600clearing 398CP-accessed 33, 34DASDs used for 8defining for a virtual machine 513defining full-pack minidisk 630defining links to 500full-pack 630full-pack, defining 625full-pack, restricting and auditing 382full-pack, using to share DASD 625initializing CSE area on 349non-full-pack 630814 z/VM: CP Planning and Administration

minidisk (continued)offset field on SAPL screen 41parm disk 51restrictions 521shared CMS expanded storage considerations 592used to share data 619using to share DASD between virtual machines 619using with cached DASD 629write-through 597minidisk cache enhancements 598minimum content of a system configuration file 25MINIMUM operandCHOOSE_LOGO statement 287MINIOPT user directory control statement 524MINIPROMPT 396mode switch procedure for 3390 devices 616MODEL operandCHOOSE_LOGO statement 286RDEVICE statement 198, 213modifyimage library 411read-only saved segments 390MODIFY DIAGNOSE statement 53, 169MODIFY EXIT statement 53, 172MODIFY LAN statement 53, 175MODIFY PRIV_CLASSES Statement 53, 176MODIFY VSWITCH Statement 53, 178modifying virtual LAN segment 175modifying virtual switch segment 178modulename field on SAPL screen 41replacing in an image library 424XLINK 349MORE operandSTATUS statement 293MP operandCPXLOAD statement 77MPLF (Multi-Path Lock Facility)realOPTION user directory control statement 535,627sharing DASD 627RPQOPTION user directory control statement 535,627sharing DASD 627MSG command 276MSGNOH command 276altering output 373multisystem complex, defining statements thatapply 569Nname groups of systems 133NAMESAVE user directory control statement 527naming conventionFCB 416UCS buffer image 416NCP (Network Control Program)used with 3720 49NCP (Network Control Program) (continued)used with 3745 49networking implications of CSE 357newaliascreating for existing CP command 81commandscreating CP 84DIAGNOSE codescreating 90exitcreating 94versioncreating for existing CP command 84NICDEF user directory control statement 529NO_SPOOLING operandRDEVICE statement 190, 192, 202, 213NOAUTOLOG operandSYSTEM_USERIDS statement 233NOCONTROL operandCPXLOAD statement 78NODELAY operandCPXLOAD statement 78NODISCONNECT operandSYSTEM_USERIDS statement 233NOLET operandCPXLOAD statement 78NOLIMIT operandFEATURES statement 144NOLOCK operandCPXLOAD statement 77NOMP operandCPXLOAD statement 77non-disruptive transition support 392non-full-pack minidisk 630NONMP operandCPXLOAD statement 77NOPDATA user directory control statement 532NOPROMPT 397NOREPLACE 397NOTACCEPTED operandDEVICES statement 106STATUS statement 293notational conventionfor commands xvinotices 781NOTSILENT operandMODIFY CMD statement 167MODIFY COMMAND statement 167NSS (named saved system)allocating DASD space for 615restricted, authorizing virtual machines to use 527number ofOretrieve buffers, specifying maximum 136users, specifying maximum 136OFF operandD8ONECMD statement 483HOT_IO_RATE statement 153Index 815

onlinebringing specified devices 105messages 279changing 292ONLINE_MESSAGE statement 292OpenExtensions planning 13OPER_IDENT_READERRDEVICE statement 198operating modes for 3390 devices, switching 615operatorconsoledefining 766defining list of possible 180defining directory entry 342form numbers, creating list of 247identification card for displays 49primary system, specifying a user ID for 687systemspecifying disconnect status 232specifying user ID 232OPERATOR operandPRIV_CLASSES statement 185SYSTEM_USERIDS statement 233OPERATOR_CONSOLES statement 53, 180OPERSYMP virtual machinesample directory entry 318SYSSYMP macroinstruction 699system configuration fileSYSTEM_USERIDS statement 234optionfor CP, specifying initialization 689specifying IPL parameters 42OPTION user directory control statement 533ORDER command 368order of statements in a system configuration file 57organization review of CP-owned DASD 337original spool descriptor 368OSA operandRDEVICE statement 205outages 372outputchoosing logo for separator pages 285devices for stand-alone dump utility 403, 406OUTPUT operandTRANSLATE_TABLE statement 244overrideCP command 165OVERRIDE control statement 438override file 433, 438OVERRIDE utility 382, 441overriding console that CP will use 39overriding SAPL defaults 39overviewplanning and administration tasks 3OWN operandCP_OWNED statement 73Ppage allocationfor XSPOOL trace tables 273PAGE operandDRAIN statement 119START statement 220page protection 390PAGES operandXSPOOL_TRACE statement 273pages, lock and unlock 394, 397paging 398space 338, 610Parallel Access Volumes 631parameter listAOFPARM 314AONPARM 312HCPACUOF entry point 314HCPACUON entry point 312HCPMSUEX entry point 374parm disk 51limit and audit access 380number 43offset 43placing information on 23purpose 23real address 43passwordautomatic deactivation of restricted 386defining for virtual machine user 572directoryauthorization bypass 385suppression facility, including 682suppression facility, including in system 136PASSWORDS_ON_CMDS operandFEATURES statement 144pending retained Expanded Storage 597PEP (partitioned emulation program)used with 3720 49performanceadministration tasks 12allocating directory space 608CP file system 33DASD considerations for sharing spool files 337DASD for dynamic paging area 590GCS 332planning 12SET D8ONECMD command 381SNA/CCS 332PERM spacefor CSE area 340PERMANENT operandCPXLOAD statement 78picture file, logochoosing 285selection 288separator pages 289, 290width 288planningconsiderations 3CSE installation 334migration from a previous VM release 3overview 5performance tasks 12real and virtual storage 7816 z/VM: CP Planning and Administration

planning (continued)SNA/CCS 329system 4tasks 4user class structure 433user tasks 5POOL user directory control statement 540POSIXdirectory definitions 448POSIXGLIST directory control statement 541POSIXGROUP directory control statement 543POSIXINFO directory control statement 545POSIXOPT directory control statement 548user planning and administration 6POSIX groupscontinuation comma 452continued directory control statements 452directory definition order 448Global definitions 448LOAD user directory control statement 504POSIXGLIST 541POSIXGROUP 543POSIXINFO 545POSIXOPT 548quoted string operands 452POSIXGLIST user directory control statement 541POSIXGROUP user directory control statement 543POSIXINFO user directory control statement 545POSIXOPT user directory control statement 548PRECEDING operandASSOCIATE EXIT statement 61ASSOCIATE MESSAGES statement 65ASSOCIATE MSGS statement 65preparation package 335preparean override file 438DASD volumes for CSE 361for CSE 341preventnew operations on real DASD 118systems from accessing other system’sminidisks 263use of X'15' 483users issuing multiple CP commands 483primary systemconsoledefining on OPERATOR_CONSOLESstatement 180defining on RIOGEN macro 766operatorspecifying a user ID for 687print buffer imageadding 414IBM provided 412printer3800defining 189, 2123820defining 1893825defining 189printer (continued)3827defining 1893828defining 1893835defining 1893900defining 189, 212advanced functiondefining 189coding an RDEVICE macro3203 7163211 7163262 7163800 7213820 7104245 7164248 7166262 716advanced function 708common control unit 708configuration guide 47, 769dedicating to virtual machine 477defining in system configuration file 47filenot accessible to other systems 659form printer default 675format, stand-alone dump 780image library 411impactdefining 201output classification titles 691output separator pages 289, 290sharing with other users 477specifying default form values 675spooled, defining for virtual machine 562unsupporteddefining 209PRINTER operandFORM_DEFAULT statement 150RDEVICE statement 210PRINTER_TITLE statement 53, 182PRIV_CLASSES statement 53, 184PRIVCLASSANY operandDEFINE CMD statement 86DEFINE COMMAND statement 86DEFINE DIAGNOSE statement 91MODIFY CMD statement 166MODIFY COMMAND statement 166MODIFY DIAGNOSE statement 170PRIVCLASSES operandDEFINE CMD statement 86DEFINE COMMAND statement 86DEFINE DIAGNOSE statement 91MODIFY CMD statement 166MODIFY COMMAND statement 166MODIFY DIAGNOSE statement 170privilege classesaccounting record 306, 307, 309assigning to commands and DIAGNOSE codes 438Index 817

privilege classes (continued)authorizing CP functions, changing 184changing 433changing CP function of 673changing individual operands of QUERY and SETcommands 440controlling which users can change 136defining for a virtual machine 444definition of 392IBM-defined 433overriding 392, 396tailoring 392, 396problems, reporting 400PROC operandDEFINE CMD statement 86DEFINE COMMAND statement 86DEFINE DIAGNOSE statement 91processordefining a system identifier for 677defining virtual 465production environmentphasing CSE into 356profiledirectory 455entry, defining start of in source directory 551invoked as part of USER statement 487PVM modifications for CSE 350PROFILE user directory control statement 551Programmable Operator Facilitysecurity 382programming interface information 782prompt at start-up, requesting 43proprietary data protection 391PROT operandDEFINE CMD statement 86DEFINE COMMAND statement 86DEFINE DIAGNOSE statement 91protection keys 397protocols, link 358PSF/VM (Print Services Facility/VM)setting up virtual machines 326PTF (Program Temporary Fix) 401PUN operandRDEVICE statement 190punchunsupporteddefining 209punch filenot accessible to other systems 659PUNCH operandFORM_DEFAULT statement 150RDEVICE statement 210PURGE command 369PURGE IMG command 425PURGE UCR command 442PVM (VM/Pass-Through Facility)directories 395functions for cross system spool 371need for CSE 335networks in CSE 357PVM (VM/Pass-Through Facility) (continued)PVM CONFIGmodifications for CSE 350run by the CVM 345Qqualifiers in system configuration files 56queryjournaling facility, enabling system to 160QUERY (User ID) command 277QUERY and MESSAGE commandin CSE 334QUERY CACHE command 747QUERY COMMAND command 446QUERY command operandchanging privilege classes of 440QUERY DASDFW command 748QUERY FILES command 369QUERY FRAMES command 589QUERY IMG command 424QUERY LOGMSG command 143QUERY NAMES command 277QUERY operandDEFINE ALIAS statement 81DEFINE CMD statement 84DEFINE COMMAND statement 84DISABLE CMD statement 110DISABLE COMMAND statement 110ENABLE CMD statement 126ENABLE COMMAND statement 126MODIFY CMD statement 165MODIFY COMMAND statement 165QUERY PINNED command 747QUERY READER/PRINTER/PUNCH 369QUERY RETRIEVE command 146QUERY RSAW command 747QUERY UCR command 442QUERY UCR COUNT command 442QUERY XSTORE command 594QUERY XSTORE MAP command 592, 593Queued-I/O assist, control by DEDICATEstatement 478quoted string operandsquoted string 452rules 452with control statements 452RRACF/VM (Resource Access Control Facility/VM)dual registration 381general description 379rate, hot I/Ochanging 152setting 152RDEVICE macrogeneral format 706how to code2701 data adapter 7522741 terminal 754818 z/VM: CP Planning and Administration

RDEVICE macro (continued)how to code (continued)3088 multisystem channel communicationunit 7603101 display 7343151 display terminal 7543161 display terminal 7543162 display terminal 7543163 display terminal 7543167 display terminal 7543174 controller 7573178 display 7343179 display 7343180 display 7343191 display 7343192 display 7343193 display 7343194 display 7343203 printer 7163211 printer 7163250 display 733, 7343262 display printer 7133262 printer 7163268 display printer 7133270-PC 7343274 controller 7573277 display 7343278 display 7343279 display 7343286 display printer 7133287 display printer 7133288 display printer 7133289 display printer 7133290 display 7343350 DASD 7463350 DASD (in 3330 compatibility mode) 7463370 7493375 DASD 7463380 DASD 7463390 DASD 7463422 tape drive 7433430 tape drive 7433480 tape drive 7433490 tape drive 7433505 card reader 7273525 card punch 7293590 tape drive 7433705 communication controller 7573705 line adapter 7543720 communication controller 7573725 communication controller 7573725 line adapter 7543737 Remote Channel-to-Channel Unit 7603745 communication controller 7573745 line adapter 7543800 printer 7213812 printer 7133816 printer 7133820 7103850 DASD 7463890 document processor 731RDEVICE macro (continued)how to code (continued)4214 display printer 7134224 display printer 7134234 display printer 7134245 display printer 7134245 printer 7164248 printer 7165080 graphics display 7405210 display printer 7135550 display 7346090 graphics display 7406262 display printer 7136262 printer 7167171 Device Attachment Control Unit 7349332 7499335 7499336 7499345 DASD 746advanced function printer 708alternate system console 766common control unit printer 708CTCA 760dynamic switching devices 762FB-512 749FBA DASD 749primary system console 766teleprocessing integrated adapter 738unsupported devices 763RDEVICE statement 53, 1883800 printers 2123900 printers 212advanced function printers 189card punch 190card readers 192channel-to-channel adapters 205communication controllers 193DASD 195graphic display devices 197impact printers 201LAN adapters 205line adapters 193special devices 205tape units 207unsupported devices 209READCARD command 396readerdefining 192unsupporteddefining 209reader filecomposite 396not accessible to other systems 659READER operandFORM_DEFAULT statement 150RDEVICE statement 192, 210realchannel program support 397device set, adding to 188reserve/releasewhen to use 624Index 819

eal storageadministration 7, 589configuration, defining 697configuring 222, 697planning 7, 589requirements, CP module 589RECEIVE command 396RECL operandCSELVOL INCLUDE operand 651record qualifiers in system configuration files 56RECORDING commandEREP operand of 316RECS operandCSELVOL INCLUDE operand 651redefinecommand privilege classes 433CP command 165text of status fields 293Remote Spooling Communications SubsystemNetworking (RSCS)directory options 395in CSE 357replacemembers in an image library 424modules in an image library 424translate tables 243REPLACE operandASSOCIATE EXIT statement 60ASSOCIATE MESSAGES statement 64ASSOCIATE MSGS statement 64reporting z/VM integrity problems 400requestsense IDusing information from 105requirementsystemfor CSE 334reserve release 210RESERVE_RELEASE operandRDEVICE statement 210reserve/releaseconcurrent virtual and real, when to use 626description 619real, when to use 624restrictions 626typeconcurrent virtual and real 625real 622virtual 619virtualDASD sharing without using 622when to use 621RESERVED operandCP_OWNED statement 73XSPOOL_SYSTEM statement 271RESET operandMODIFY CMD statement 166MODIFY COMMAND statement 166MODIFY DIAGNOSE statement 169residence disk, CP 693resident pages dumped with stand-alone dumputility 403resourcemanaging 495response suppression, command 86, 166restartreal DASD 220restrictusers issuing multiple CP commands 483restricted passwordautomatic deactivation of 386restriction3525 card punch 1903705, 3720, 3725, and 3745 BSC line adapters 1933850 Mass Storage System 195about migration incompatibilities 656, 678against using 2250 display 124against using 3250 display 124defining advanced function printers 189DIAGNOSE codes 394minidisk 521removedissuing multiple CP commands 483specifying real storage available for CP 697reserve/release 626turning off hot I/O rate 153users migrating from VM/XA SP 451, 454VM/ESA commands 393RETAIN XSTORE command 591, 593, 596retained Expanded Storage 596, 597retrieve bufferspecifyingdefault number of 136maximum number of 136RETRIEVE command (CP)retrieving EREP records 316RETRIEVE operandFEATURES statement 145RIOGEN macro 766RMSIZE operandSYSSTORE macro 697RUNNING operandSTATUS statement 294running programsutilities 37SSAMPEXEC files 641sample utility programDRAWLOGO 282, 642SAMPXEDI files 641save area, HCPSAVBKcontents 312used by CP accounting exit 312used by CP message function exit 374saved segmentmodifying read-only 390nonrestricted, authorizing virtual machines touse 527restricted, authorizing virtual machines to use 527820 z/VM: CP Planning and Administration

SAY statement 53, 217, 219SCIF (Single Console Image Facility)restricting use of 381screenlogochoosing picture file 285SCREEN user directory control statement 553SCSI disks 635securityconsiderations 379, 380external security manager 383facilities 379, 383guidelines 380Integrated Cryptographic Facility 383maintaining system integrity 389, 401of z/VM installation 142products that enhance 379security journaling 160system 234use badge reader to log on 198using an Integrated Cryptographic Facility 387semantic statements in system configuration file 27sense ID requestspecifying whether CP should issue 689using information from 105SENSE operandSYSOPTS macro 689sensing devices at IPL time 46SEPARATOR operandRDEVICE statement 203, 215separator pagelogochoosing 285serialization 392servicepooldefinition 325manager 326virtual machines, setting up 325virtual machinedefining directory entry 342excluding from spooling 659setting up 295service, system*ACCOUNT 233*BLOCKIO 494*CONFIG 494*CRM 494*IDENT 496*LOGREC 314, 494, 669*MONITOR 494*MSG 494*MSGALL 494*RPI 494*SIGNAL 494*SYMPTOM 318, 494*SYMPTOM, specifying virtual machines for 699accounting 295, 661collecting accounting records 297collecting EREP records 315collecting symptom records 319service, system (continued)communication requirements 497CP recording 295symptom record recording 295sessionconcurrent copy 566multiple concurrent 371sethot I/O rate 152I/O throttling rate 105journaling facility, enabling system to 160time of (TOD) clock 701SET CACHE command 747SET command operandchanging privilege classes of 440SET CONCEAL OFF command 534SET D8ONECMD command 381, 393SET DASDFW command 747SET DUMP command 614SET LOGMSG command 141SET MAXUSERS command 535SET MDCACHE SYSTEM 393SET OBSERVER command 393SET operandDEFINE ALIAS statement 82DEFINE CMD statement 84DEFINE COMMAND statement 84DISABLE CMD statement 110DISABLE COMMAND statement 110ENABLE CMD statement 126ENABLE COMMAND statement 126MODIFY CMD statement 166MODIFY COMMAND statement 166SET PFnn RETRIEVE command 145SET PRIVCLASS command 393controlling which users can use 136SET RDEVICE command 393SET RETRIEVE command 146SET SECUSER command 393SET SHARED command 601, 620SET SHARED OFF command 620SET SHARED ON command 626SET SRM command 332, 537SET statement 53SET SYSOPER command 393SET TIMEZONE command 394set upa CSE complex 334data storage management virtual machines 327Print Services Facility/VM virtual machines 326service pool virtual machine 325SET VDISK SYSLIM command 394SET_ADDRESS operandRDEVICE statement 193SET_AND_QUERY operandJOURNALING statement 161SET_PRIVCLASS operanddisabling on FEATURES statement 141enabling on FEATURES statement 144SHARE user directory control statement 555Index 821

SHARE_SPOOL operandXSPOOL_SYSTEM statement 271sharedaccess to minidisks, DASD for 338CMS minidisks expanded storageconsiderations 592DASD 365defining 195omitting devices 105specifying devices 105datareserve/release 210file pools, DASD space used for 9segment 391, 398spool files, DASD for 337Shared File System (SFS)sharing DASD 622SHARED operandCP_OWNED statement 74RDEVICE statement 195sharingCPU power 555DASD 619, 622using Parallel Access Volumes 632volumes 336SHOW_ACCOUNT operandFEATURES statement 143SHUTDOWN command 299, 394SILENT operandDEFINE CMD statement 86DEFINE COMMAND statement 86MODIFY CMD statement 166MODIFY COMMAND statement 166single source directory 341SLOT operandXLINK_SYSTEM_INCLUDE 264XSPOOL_SYSTEM 271SMSG command 276altering output 373to start CSECOM task 353SNA (Systems Network Architecture)enabling communication 331environment 329networks in CSE 358SNA/CCS (System Network Architecture/ConsoleCommunication Services)accounting record 304defining to VSCS 331defining VCNA to 330functions 329improving performance of 332planning 329terminal environment, establishing 330terminalschoosing logo picture file for 285SNAPDUMP command 394source code, adding your own 310spaceallocatingfor internal trace tables 222, 697for XSPOOL trace tables 273space (continued)clearing TDISK 136storageconfiguring 222, 697used for shared file pools 9special devicesdefining 205SPECIAL operandHOT_IO_RATE statement 152SPECIAL user directory control statement 557specifyaccess list size, host 581CP’s displaying of log messages 136DASD excluded from cross system link 266, 649DASD to be included in cross system link 268DASD volumes included in cross system link 650default number of RETRIEVE buffers 136file for input area 291file name and type of logo configuration file 164forms as NARROW 247host access list size 581inclusion of journaling facility 160inclusion of password suppression facility 136initialization options for CP 689maximum number of nonprimary addressspaces 583maximum number of RETRIEVE buffers 136maximum number of users 136replacements for standard translate tables 243size of host access list 581spool file class for impact printers 202systems excluded from cross system link 263systems in cross system spooling 271systems participating in cross systemcommands 271systems to be included in cross system link 264total size of nonprimary address spaces 583user IDs to perform special functions 232volumes excluded from user volume list 251, 671volumes included in user volume list 680volumes to be included in user volume list 253whether CP builds device blocks 105whether CP uses use sense ID information 105spoolactivate CVM 355cross system 366descriptor 368enabling 353fileaccess to 370characteristics 565maximum number allowed 565transfer data to 532files, DASD for 337synchronization request tracing 371verifying 354SPOOL command 665spool fileclassescontaining classification titles 182specifying for impact printers 202822 z/VM: CP Planning and Administration

spool file (continued)inputcopying (reader) 369excluding from cross system spooling 274numberingnumbering 370outputclasses containing classification titles 182copying (print and punch) 370excluding from cross system spooling 276SPOOL operandSTART statement 220SPOOL user directory control statement 562spooled unit record devices 11SPOOLFILE user directory control statement 565in CSE 341spooling spaceexample 615spooling, cross systemexcluding virtual machines’ input spool filesfrom 274excluding virtual machines’ output spool filesfrom 276identifying volumes for 73specifying systems participating in 271trace tablesallocating space for 273SPXTAPE command 665stable access mode 327, 387stable access mode, authorized to use 536StackBufferCreate 399StackBufferDelete 399stacks, program 398stand-alone dump utilitycreating 403description of 403devices to IPL 405devices to send dump output 406example of configuring 406HCPSADMP EXEC 409output devices 406overview 403processing dump data on tape 409taking a dump 408Stand-Alone Loader Creation Utility (SALIPL)using 37Stand-Alone Program Loader (SAPL)creating 37file list 42overriding console that CP will use 39overriding defaults 39overview 37passing IPL parameters 42startprompt 31, 43real DASD 220START CSECOM command 353START statement 53, 220starting CP extensions at initialization time 663starting VSM 332statementALTERNATE_OPERATORS 58ASSOCIATEEXIT 60MESSAGES 64MSGS 64ASSOCIATE EXIT 51ASSOCIATE MESSAGES/MSGS 51CHARACTER_DEFAULTS 51, 67CHARACTER_OPERators 51CHOOSE_LOGO 279, 285configurationlogo 279system 51CP_ACCESS 52, 70CP_ADDON_INITIALIZE_ ROUtines 52CP_ADDON_INITIALIZE_ ROUTINES 72CP_OWNED 52, 73CPXLOAD 52, 76DEFINECMD 84COMMAND 84DEFINE ALIAS 81DEFINE EXIT 94DIAGNOSE 90DEFINE ALIAS 52DEFINE COMMAND/CMD 52DEFINE DIAGNOSE 52DEFINE EXIT 52DEFINE LAN 52DEFINE VSWITCH 52DEVICES 52, 105DISABLECMD 110COMMAND 110DIAGNOSE 112EXITS 114DISABLE COMMAND/CMD 52DISABLE DIAGNOSE 52DISABLE EXITS 52DISTRIBUTE 52, 116DRAIN 52, 118EDEVICE 52, 121EMERGENCY_MESSAGE_ CONSOLES 52, 124ENABLECMD 126COMMAND 126DIAGNOSE 128EXITS 130ENABLE COMMAND/CMD 52ENABLE DIAGNOSE 52ENABLE EXITS 52ENFORCE_BY_VOLIDS 52EQUATE 52, 133EXTERNAL_SYNTAX 53, 135FEATURES 53, 136FORM_DEFAULT 53, 150HOT_IO_RATE 53, 152IMBED 53, 155INIT_MITIME 53, 157INPUT_AREA 279, 291Index 823

statement (continued)IODF 53, 158JOURNALING 53, 160LOGO_CONFIG 53, 164MODIFYDIAGNOSE 169MODIFY EXIT 172MODIFY CMD 165MODIFY COMMAND 165MODIFY COMMAND/CMD 53MODIFY DIAGNOSE 53MODIFY EXIT 53MODIFY LAN 53MODIFY PRIV_CLASSES 53, 176MODIFY VSWITCH 53ONLINE_MESSAGE 279, 292OPERATOR_CONSOLES 53, 180PRINTER_TITLE 53, 182PRIV_CLASSES 53, 184PRODUCT 53RDEVICE 53, 1883800 printers 2123900 printers 212advanced function printers 189card punch 190card readers 192channel-to-channel adapters 205communication controllers 193DASD 195graphic display devices 197impact printers 201LAN adapters 205line adapters 193special devices 205tape units 207unsupported devices 209SAY 53, 217SET 53, 219START 53, 220STATUS 279, 293STORAGE 53, 222summary 279summary of system configuration file 51SYSTEM_DATEFORMAT 53, 225SYSTEM_IDENTIFIER 54, 226SYSTEM_IDENTIFIER_ DEFAULT 228SYSTEM_IDENTIFIER_DEFAULT 54SYSTEM_RESIDENCE 54, 230SYSTEM_USERIDS 54, 232THROTTLE 54, 236TIMEZONE_BOUNDARY 54, 237TIMEZONE_DEFINITION 54, 239TOLERATE_CONFIG_ ERRORS 241TOLERATE_CONFIG_ERRORS 54TRANSLATE_TABLE 54, 243USER_DEFAULTS 54, 248USER_VOLUME_EXCLUDE 54, 251USER_VOLUME_INCLUDE 54, 253USER_VOLUME_LIST 54, 255USERFORM 54, 247VMLAN 54statement (continued)XLINK_DEVICE_DEFAULTS 54, 259XLINK_SYSTEM_EXCLUDE 54, 263XLINK_SYSTEM_INCLUDE 54, 264XLINK_VOLUME_EXCLUDE 54, 266XLINK_VOLUME_INCLUDE 54, 268XSPOOL_SYSTEM 54, 271XSPOOL_TRACE 54, 273XSPOOL_XLIST_INPUT 54, 274XSPOOL_XLIST_OUTPUT 55, 276statusfields on screen, changing text 293STATUS statement 279, 293STDEVOPT user directory control statement 566STIDP instruction 465stopnew operations on real DASD 118use of X'15' 483users issuing multiple CP commands 483storageaccess verification 384administration 7allocation 397for XSPOOL trace tables 273calculations 604capacities, DASD 604configuration, defining 697DASD 603dynamic paging area 590expanded 591expanded, planning 9free, used by CP 538organizationconfiguring 222, 697planning 7protectionmain storage 397paging 398shared segments 398specifying amount of real storage used by CP 44task overview 7using expanded storage as a minidisk cache 597virtual defining for virtual machine user 572virtual machine considerations 590virtual storage, planning 9STORAGE statement 53, 222STORAGE user directory control statement 568STORE HOST command 394SUBCMD operandDEFINE ALIAS statement 81DEFINE CMD statement 84DEFINE COMMAND statement 84DISABLE CMD statement 110DISABLE COMMAND statement 110ENABLE CMD statement 126ENABLE COMMAND statement 126MODIFY CMD statement 165MODIFY COMMAND statement 165summary oflogo configuration file statements 279system configuration file statements 51824 z/VM: CP Planning and Administration

supported devices 45suppresspassword on command line 136, 387SWITCH operandHOT_IO_RATE statement 153RDEVICE statement 210switching devices, dynamiccoding an RDEVICE macro 762defining 209switching operating modes for 3390 devices 615symbolcharacter deleteestablishing default 67escapeestablishing default 67line deleteestablishing default 67line endestablishing default 67tabestablishing default 67symbol, externalassigning to exit point 60, 64symbols, defining for virtual machine 572symptom recordspecifying user ID to accumulate 232symptom record recordingdisassociating a user ID from retrieval of 320OPERSYMP symptom recording virtualmachine 318setting up virtual machines for 318SYMPTOM1 operandSYSTEM_USERIDS statement 233SYMPTOM2 operandSYSTEM_USERIDS statement 233syntactic statements in system configuration file 27syntax diagramexamplesdefault xviifragment xviireturn arrow xvisymbols xvivariable xvitable xvisyntax, checking statements in system configurationfile 57syntax, explanation of, notational xviSYSACNT macro 6, 661SYSADDIN macro 663SYSAFFIN user directory control statement 569SYSCLEAR 398SYSCLR operand of SYSRES macro 391SYSCPVOL macro 620, 664list 447search order 447SYSDUMP macro 6, 667SYSEND macro 668SYSEREP macro 6, 669SYSEXCL macro 671SYSFCN macro 575, 673SYSFORM macro 675SYSID macro 677SYSINCL macro 680SYSJRL macro 682SYSMAXU macro 686SYSOPR macro 6, 687SYSOPTS macro 689SYSPCLAS macro 691SYSRES macro 391, 605, 693SYSSTORE macro 697SYSSYMP macro 699systemadministration tasks 4attributes, establishing 136bring-up virtual machine 6control files 3definitionof set of real devices 188dump virtual machine, defining a user ID for 667functionassigning new classes 438, 443identifier, processor 677integrity 383general definition 389guidelines 390maintaining 389joining 353maximum number supported for cross systemlink 334, 338modification requirements 390naming groups 133not active after start CSECOM 355operator, automatic exclusion of 659operator, primary user ID 687outages, hardware 372participating in cross system commands andspooling, specifying 271planning tasks 4processor identifier 677residence disk 693residence volume 338time zone, defining 239system command, crossexcluding virtual machines’ input spool filesfrom 274excluding virtual machines’ output spool filesfrom 276specifying systems participating in 271system configuration file 51advantages 23case 56checking statement syntax 57comments 55content overview 25continuations 55converting to xxCP file system, overview 27format 55general rules 55ignoring errors in 241imbedding files into 155limit and audit access 380Index 825

system configuration file (continued)minimum content 25order of statements 57overview 23real devices, overview 25record qualifiers 56semantic statements 27specifying file name via SAPL 42specifying file type via SAPL 43spool file processing, overview 27statementsALTERNATE_OPERATORS 58ASSOCIATE EXIT 60ASSOCIATE MESSAGES 64ASSOCIATE MSGS 64CHARACTER_DEFAULTS 67CP_ACCESS 70CP_ADDON_INITIALIZE_ ROUTINES 72CP_OWNED 73CPXLOAD 76DEFINE ALIAS 81DEFINE CMD 84DEFINE COMMAND 84DEFINE DIAGNOSE 90DEFINE EXIT 94DEVICES 105DISABLE CMD 110DISABLE COMMAND 110DISABLE DIAGNOSE 112DISABLE EXITS 114DISTRIBUTE 116DRAIN 118EMERGENCY_MESSAGE_ CONSOLES 124ENABLE CMD 126ENABLE COMMAND 126ENABLE DIAGNOSE 128ENABLE EXITS 130ENFORCE_BY_VOLid 132EQUATE 133EXTERNAL_SYNTAX 135FEATURES 136FORM_DEFAULT 150HOT_IO_RATE 152IMBED 155INIT_MITIME 157IODF 158JOURNALING 160LOGO_CONFIG 164MODIFY CMD 165MODIFY COMMAND 165MODIFY DIAGNOSE 169MODIFY EXIT 172MODIFY PRIV_CLASSES 176OPERATOR_CONSOLES 180PRINTER_TITLE 182PRIV_CLASSES 184RDEVICE 188SAY 217SET 219START 220STORAGE 222system configuration file (continued)statements (continued)summary 51SYSTEM_DATEFORMAT 225SYSTEM_IDENTIFIER 226SYSTEM_IDENTIFIER_ DEFAULT 228SYSTEM_RESIDENCE 230SYSTEM_USERIDS 232THROTTLE 236TIMEZONE_BOUNDARY 237TIMEZONE_DEFINITION 239TOLERATE_CONFIG_ ERRORS 241TRANSLATE_TABLE 243USER_DEFAULTS 248USER_VOLUME_EXCLUDE 251USER_VOLUME_INCLUDE 253USER_VOLUME_LIST 255USERFORM 247XLINK_DEVICE_DEFAULTS 259XLINK_SYSTEM_EXCLUDE 263XLINK_SYSTEM_INCLUDE 264XLINK_VOLUME_EXCLUDE 266XLINK_VOLUME_INCLUDE 268XSPOOL_SYSTEM 271XSPOOL_TRACE 273XSPOOL_XLIST_INPUT 274XSPOOL_XLIST_OUTPUT 276statements, summary 25syntactic statements 27updating 34USER_DEFAULTS 248using 23XLINK_VOLUME_EXCLUDE statement 338XLINK_VOLUME_INCLUDE statement 338system consolealternatedefining on RIOGEN macro 766definingalternate 766list of possible 180primary 766primarydefining on RIOGEN macro 766system data fileuser class restructure 441system directoryDIAGNOSE code X'3C' 394DIAGNOSE code X'84' 394, 396overview 395system dumpspecifying user ID to accumulate records 232system execution space, CPloading CP routines into 76system generationCSELVOL EXCLUDE generation macro 649CSELVOL INCLUDE generation macro 650RIOGEN generation macro 766screen logo filechoosing 285SYSEXCL generation macro 671SYSINCL generation macro 680826 z/VM: CP Planning and Administration

system generation (continued)SYSOPTS generation macro 689SYSSTORE generation macro 697system identifiercreating 226, 228system link, crossexcluding DASD 266excluding DASD volumes 649excluding systems 263including DASD 268including DASD volumes 650including systems 264system log messagespecifying whether CP should display 136system operatorspecifying disconnect status 232specifying user ID 232system programmingjournalingincluding facility in system 160system residence volumedefining 73describing layout 230system service*ACCOUNT 233*BLOCKIO 494*CONFIG 494*CRM 494*IDENT 496*LOGREC 314, 494, 669*MONITOR 494*MSG 494*MSGALL 494*RPI 494*SIGNAL 494*SYMPTOM 318, 494*SYMPTOM, specifying virtual machines for 699accounting 295, 661collecting accounting records 297collecting EREP records 315collecting symptom records 319communication requirements 497CP recording 295symptom record recording 295system spooling, crossexcluding virtual machines’ input spool filesfrom 274excluding virtual machines’ output spool filesfrom 276identifying volumes for 73specifying systems participating in 271trace tablesallocating space for 273system storageconfiguring 222, 697SYSTEM_IDENTIFIER statement 53, 54, 225, 226SYSTEM_IDENTIFIER_DEFAULT statement 54, 228SYSTEM_RESIDENCE statement 54description 230SYSTEM_USERIDS statement 54, 232system-managed 3800 printersdelayed purge queue 721system-wide defaultfor logical character-delete symbol 67for logical escape symbol 67for logical line-delete symbol 67for logical line-end symbol 67for logical tab symbol 67System/390 architecture 397SYSTIME macro 701SYSUVOL macro 8, 620, 703Ttab characterdefinition 67TAB operandCHARACTER_DEFAULTS statement 68tablecolors for the CHOOSE_LOGO andONLINE_MESSAGE files 283input area fields 284logo configuration file statements 279map record defaults for DASD 652syntax diagram xvisystem configuration file statements 51table entry block, commanddefining new CP 84table, traceallocating space forinternal 222, 697XSPOOL 273table, translatereplacing 243TAG command 369tailoringprivilege classes 392, 396tapeclearing 398drivecoding an RDEVICE macro 743configuration guide 47defining in system configuration file 47formatstand-alone dump 777library dataserver 566unitsdefining 207unsupported, defining 209TAPE operandHOT_IO_RATE statement 153RDEVICE statement 210TDISK (temporary disk)accounting record 301clearing 136, 384, 398space 338TDISK operandDRAIN statement 119START statement 221TDSK operandDRAIN statement 119Index 827

TDSK operand (continued)START statement 221TELE2_ADAPTER operandRDEVICE statement 193Telegraph Terminal Control type 2 193, 738teleprocessing integrated adaptercoding an RDEVICE macro 738TEMPDISK operandDRAIN statement 119START statement 221TEMPORARY operandCPXLOAD statement 78terminalchoosing logo 285coding an RDEVICE macro 754input linedefining file for 291unsupporteddefining 209TERMINAL LINESIZE command 331TERMINAL operandHOT_IO_RATE statement 153RDEVICE statement 210textof status fields, redefining 293text deckcreating for impact printer 412description 411for impact printer 422input file for image library 411TEXT operandCPXLOAD statement 77THROTTLE statement 54, 236time zonechoosing at IPL 237defining 239determining local 237Time-Of-Day (TOD) clocknot changing during IPL 142SYSTIME macro 701TIMEOUT operandXSPOOL_SYSTEM statement 272TIMEZONE_BOUNDARY statement 54, 237TIMEZONE_DEFINITION statement 54, 239token ring communication adapterdefining in system configuration file 49Token Ring local area network 738tolerateerrors in system configuration file 241TOLERATE_CONFIG_ERRORS statement 54, 241TOP operandPRINTER_TITLE statement 182topography of CSE complex, describe 653TPF (Transaction Processing Facility)OPTION user directory control statement 535tracespool synchronization request 371TRACE operandSTORAGE statement 223SYSSTORE macro 697trace tableallocating space forinternal 222, 697XSPOOL 273track location format default, change CSE 259, 646TRACK operandXLINK_VOLUME_INCLUDE statement 269TRANSFER command 369transfer data to CP spool files 532transition support, non-disruptive 392TRANSLATE operandTRANSLATE_TABLE statement 243translate tablereplacing 243TRANSLATE_TABLE statement 54, 243translating guest virtual channel programs 427TRK operandCSELVOL INCLUDE macro 650TXTLIB operandCPXLOAD statement 77TYPE operand for RDEVICE statement3800 printers 212advanced function printers 189card punches 190card readers 192communication controllers 193DASD 195graphic display devices 198impact printers 202line adapters 193special devices 205unsupported devices 209UU. S. Telegraph Terminal Control type 2 738UCS (Universal Character Set)buffer imagesnaming convention 416examples of new buffer images3203 printer 4163211 printer 4173262 printer 417UCSI macroinstruction 415UCSICCW macroinstruction 415unit record deviceconfiguration guide 48dedicated 11defining for virtual machinespooled unit record device 562defining in system configuration file 48planning 11spooled 11UNIT RECORD operandHOT_IO_RATE statement 153UNIVERSAL_CHARSET operandRDEVICE statement 203UNLOCK operandD8ONECMD statement 483unlock pages 394, 397828 z/VM: CP Planning and Administration

unsolicited interruptchanging 152setting 152unsupported deviceCCW translation 428coding an RDEVICE macro 763defining 209device tables 428not guaranteed to run properly 46UNSUPPORTED operandRDEVICE statement 209useraccounting record 299administration 5class restructureactivating a class override file 441activating an override file 438assigning commands to types of users 435assigning new classes 438associating classes with users andcommands 436changing back to IBM-defined user classes 442changing QUERY and SET operand privilegeclasses 440changing the directory 443CLASS control statement 443, 445class override file 438, 439, 441CLEAR option on OVERRIDE utility 442commands 438COMMANDS command 446creating a class override file 438defining privilege classes for a virtualmachine 444defining users’ needs 434description 433diagnose codes 438directory entry example 445directory, changing 443displaying commands available to a user 446documentation considerations 438file 441HELP files 437IBM-defined user classes, changing back to 442OVERRIDE control statement 438override file 438OVERRIDE utility 441overview 433planning a new user class structure 433preparing an override file 438sample class override file 439security 383system functions 438system integrity 383USER control statement 443VALIDATE option on OVERRIDE utility 441verifying a class override file 441directorybringing online 31changing 447, 454checking for errors 454checking VM/SP directory statements 455user (continued)directory (continued)continuation comma 452continued across multiple records 452continued directory control statements 452creating 447, 451determining how much space is required for 608quoted string operands 452running the directory creation program 453size constraints 610updating 447directory control statementACCOUNT 456ACIGROUP 458APPCPASS 459AUTOLOG 461, 578CLASS 462CONSOLE 463CPU 465CRYPTO 468D8ONECMD 483DASDOPT 472DATEFORMAT 475DEDICATE 477DIRECTORY 480GLOBALDEFS 485GLOBALOPTS 486INCLUDE 487introduction 447IOPRIORITY 488IPL 490IUCV 493LINK 500LOAD 504LOGONBY 509MACHINE 510MAXTORAGE 512MDISK 513MINIOPT 524NAMESAVE 527NICDEF 529NOPDATA 532OPTION 533overview 447POOL 540POSIXGLIST 541POSIXGROUP 543POSIXINFO 545POSIXOPT 548PROFILE 551SCREEN 553SHARE 555SPECIAL 557SPOOL 562SPOOLFILE 565STORAGE 568summary 447SYSAFFIN 569USER 572XAUTOLOG 578XCONFIG 580Index 829

user (continued)directory control statement (continued)XSTORE 585IDaccounting virtual machine 661defining for virtual machine user 572error recording virtual machine 669primary system operator 687system dump virtual machine 667system operator 232to perform special functions, specifying 232identification requirements 391logon limit 686owned DASD volumes, generating a list of 703planning 5supported in CSE 334tasks 5user defaults configuration filespecifying default attributes 248user form namecreating list of 247generating default 150user owned volumedefining with generic volume ID 253, 680excluding DASD from list 671excluding from user volume list 251generating list of 255USER user directory control statement 443, 448, 572user volume list 26excluding volumes from 251, 671including volumes in 253, 680USER_DEFAULT operandPRIV_CLASSES statement 185USER_DEFAULTS statement 54, 248USER_VOLUME_EXCLUDE statement 54, 251USER_VOLUME_INCLUDE statement 54, 253USER_VOLUME_LIST statement 54, 255user-initiated accounting records 310USERFORM statement 54, 247USERID operandCHOOSE_LOGO statement 286users, specifying maximum number 136usingprograms 37z/VM stand-alone programs 37utilitiesRETRIEVEretrieving EREP records 316utilityCCDUMP 321CCLOAD 321CPFMTXA (CMS) 7, 665DIRECTXA 448checking directory for errors 454checking for VM/SP statements 455creating user directory with 451, 453GENIMAGE 411ICHUT100 381IMAGELIB 423IMAGEMOD 424IOCP 184, 673, 705utility (continued)OVERRIDE 382, 441RETRIEVE 661SALIPL 37sample programs 641SAPL 37stand-alone dump 403VMFHASM 412XLINK 349utility program, sampleDRAWLOGO 282, 642VVAFP, virtual advanced functional printer 563VALIDATE option on OVERRIDE utility 441validationrequirements 392VCNA (VTAM Communications Network Applications)defining SNA/CCS to 330verifyaccuracy of system configuration file statementsyntax 57links 353spool status 354storage access 384versioncreating new for existing CP 84virtualand real reserve/releasewhen to use concurrent 626devicespooled, defining 562planning 9processor, defining 465reserve/releaseDASD sharing without using 622when to use 621storageadministration 7CP module requirements 589defining for virtual machine user 572planning 7virtual consolegenerating default user form name for 150virtual disks in storageaccounting record 307allocating system storage availability 136virtual LAN segment, defining 97virtual LAN segment, modifying 175virtual machinearchitecture 510attaching expanded storage to 592authorized for concurrent copy sessions 566authorizing to use IUCV 493characteristics, special 533consoledefining 180, 766for emergency messages, defining 124defining forcommand privilege class 572830 z/VM: CP Planning and Administration

virtual machine (continued)defining for (continued)delete symbol 572escape character 572expanded storage facility 585line delete symbol 572line end symbol 572password 572privilege classes 444storage 572user ID 572defining one to use during outages 372defining set of with same characteristics 540error recording 314file pool server 622host access list size, defining 581log on limitspecifying 136multiple, DASD sharing with other systems 624operator’s console, define 463resource usage accounting record 299security facilitiesincluding in system 160service 295service pool, setting up 325setting up data storage management 327setting up for accounting 295setting up for collecting accounting records 297setting up for collecting EREP records 315setting up for collecting symptom records 319setting up PSF/VM 326setting up symptom record recording 318special characteristics 533specifying for *SYMPTOM system service 699spool file characteristics 565Virtual Machine/ESAdefining VSM logos 330defining VSM to 330features 335I/O reconfiguration 12major files 3security 142security facilities 383VIRTUAL operandDEFINE ALIAS statement 81DEFINE CMD statement 84DEFINE COMMAND statement 84DISABLE CMD statement 110DISABLE COMMAND statement 110ENABLE CMD statement 126ENABLE COMMAND statement 126MODIFY CMD statement 165MODIFY COMMAND statement 165virtual printergenerating default user form name for 150virtual punchgenerating default user form name for 150virtual switch segment, defining 100virtual switch segment, modifying 178VM_LOGO operandJOURNALING statement 162VM_READ operandSTATUS statement 294VM/ESA commands, restriction of 393VMAC operandDEFINE CMD statement 87DEFINE COMMAND statement 87DEFINE DIAGNOSE statement 91VMFHASM utility 412, 422VMFHLASM utility 422VMLAN statement 54, 257VMLINK CMS command 620VOLID operandDRAIN statement 118START statement 220SYSTEM_RESIDENCE statement 230volume identifierexcluding from user volume list 671using generic to define user volumes 253, 680using to exclude volumes from user volume list 251volume listCP-owned, defining 73excluding user volumes from 251, 671including user volumes in 253, 680VPROT operandDEFINE CMD statement 87DEFINE COMMAND statement 87DEFINE DIAGNOSE statement 92VSCSdefining SNA/CCS to 331VSM (VTAM Service Machine)choosing logo 285defining logos 330defining to z/VM 330starting 332termination 332VSM_VMID operandCHOOSE_LOGO statement 287Wwait state if parm disk is not CMS-formatted 51warm startdataallocating DASD space for 606specifying whether CP should attempt 136warning3525 card punch 1903705, 3720, 3725, and 3745 BSC line adapters 1933850 Mass Storage System 195about migration incompatibilities 656, 678against using 2250 display 124against using 3250 display 124calling entry point after loading CP routines 78changing defaults on CSELVOL INCLUDEmacro 651CONTROL operand of CPXLOAD 78data integrity loss 264defining advanced function printers 189moving volumes containing spool space 74removedissuing multiple CP commands 483Index 831

warning (continued)removed (continued)specifying real storage available for CP 697sharing system residence and paging volumes 73system security 234turning off hot I/O rate 153users migrating from VM/XA SP 451, 454WARNING command, altering output 373WEST operandTIMEZONE_DEFINITION statement 239WNG command 276write-through minidisk 597XX.25 network (high-level data link control) 738X$DRWL$X SAMPXEDI file 641X$DRWL$X XEDIT file 641X'15', preventing use of 483XAUTOLOG commandjournaling 385specifying invalid password 299using during initialization 332XAUTOLOG user directory control statement 578XCONFIG user directory control statement 580XLINK CHECK command 353XLINK FORMAT commandusing to format volume 350, 652using to specify CSE area 340XLINK RESET command 359XLINK utility program 349XLINK_DEVICE_DEFAULTS statement 54, 259XLINK_SYSTEM_EXCLUDE statement 54, 263XLINK_SYSTEM_INCLUDE statement 54, 264XLINK_VOLUME_EXCLUDE statement 54, 266, 338XLINK_VOLUME_INCLUDE statement 54, 268, 338XSPOOL QUERY command 354XSPOOL trace tableallocating space for 273XSPOOL_SYSTEM statement 54, 271XSPOOL_TRACE statement 54, 273XSPOOL_XLIST_INPUT statement 54, 274XSPOOL_XLIST_OUTPUT statement 55, 276XSTORE user directory control statement 585, 592Zzone, timechoosing at IPL 237defining 239determining local 237832 z/VM: CP Planning and Administration

Readers’ Comments — We’d Like to Hear from Youz/VMCP Planning and AdministrationVersion 5 Release 1Publication No. SC24-6083-01Overall, how satisfied are you with the information in this book?Very Satisfied Satisfied Neutral Dissatisfied Very DissatisfiedOverall satisfaction h h h h hHow satisfied are you that the information in this book is:Very Satisfied Satisfied Neutral Dissatisfied Very DissatisfiedAccurate h h h h hComplete h h h h hEasy to find h h h h hEasy to understand h h h h hWell organized h h h h hApplicable to your tasks h h h h hPlease tell us how we can improve this book:Thank you for your responses. May we contact you? h Yes h NoWhen you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in anyway it believes appropriate without incurring any obligation to you.NameAddressCompany or OrganizationPhone No.

Readers’ Comments — We’d Like to Hear from YouSC24-6083-01SC24-6083-01_________________________________________________________________________________________Fold and Tape Please do not staple Fold and TapeBUSINESS REPLY MAILFIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORKPOSTAGE WILL BE PAID BY ADDRESSEEIBM CorporationDepartment 55JA, Mail Station P3842455 South RoadPoughkeepsie, New York 12601-5400NO POSTAGENECESSARYIF MAILED IN THEUNITED STATES_________________________________________________________________________________________Fold and Tape Please do not staple Fold and Tape___________________________________________________________________________________________________Cut or FoldAlong LineCut or FoldAlong Line

Program Number: 5741-A05Printed in USASC24-6083-01

Spine information: z/VM CP Planning and Administration Version 5 Release 1

z/VM: CP Planning and Administration - z/VM - IBM

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?