z/VM V6.4 Systems Management Application Programming · This edition applies to version 6, r elease 4, modification 0 of IBM z/VM (pr oduct number 5741-A07) ... Part 1. Overview

z/VM

Systems ManagementApplication ProgrammingVersion 6 Release 4

SC24-6234-13

IBM

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

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

This edition replaces SC24-6234-12

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

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

About This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvIntended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvWhere to Find More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Links to Other Documents and Websites . . . . . . . . . . . . . . . . . . . . . . . . xv

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

Summary of Changes for z/VM Systems Management Application Programming. . . . xixSC24-6234-013, z/VM Version 6 Release 4 (March 2018) . . . . . . . . . . . . . . . . . . . . xix

New APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xixSC24-6234-012, z/VM Version 6 Release 4 (January 2017) . . . . . . . . . . . . . . . . . . . . xix

Configuration Wizard Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . xixInstallation Verification Program Enhancements . . . . . . . . . . . . . . . . . . . . . . xixOther Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

SC24-6234-011, z/VM Version 6 Release 4 . . . . . . . . . . . . . . . . . . . . . . . . . xxRemove zManager Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxAlternate Deployment Provisioning Support . . . . . . . . . . . . . . . . . . . . . . . xxOPNCLOUD Virtual Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxOther Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx

SC24-6234-10, z/VM Version 6 Release 3 (March 2016) . . . . . . . . . . . . . . . . . . . . . xxSC24-6234-09, z/VM Version 6 Release 3 (September 2015) . . . . . . . . . . . . . . . . . . . xxSC24-6234-08, z/VM Version 6 Release 3 (March 2015) . . . . . . . . . . . . . . . . . . . . . xxiSC24-6234-07, z/VM Version 6 Release 3 (September 2014) . . . . . . . . . . . . . . . . . . . xxiSC24-6234-06, z/VM Version 6 Release 3 (June 2014) . . . . . . . . . . . . . . . . . . . . . xxi

Part 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3The Directory Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4The Socket-based Server Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . 4The Extreme Cloud Administration Toolkit (xCAT) for z/VM . . . . . . . . . . . . . . . . . . . 5

The Cloud Manager Appliance (CMA). . . . . . . . . . . . . . . . . . . . . . . . . . 6The Non-CMA Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 2. API Functions Overview . . . . . . . . . . . . . . . . . . . . . . . . 9ABEND Dump Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Directory Manager Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Directory Manager Local Tag and Scan . . . . . . . . . . . . . . . . . . . . . . . . . . 10Directory Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Directory Updates Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Disk Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Event Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Image Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Image Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Image CPUs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Image Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Image IPL Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Image Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

© Copyright IBM Corp. 2003, 2018 iii

Image Volume Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17List-Directed IPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Name List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Network Interface Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Profile Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Prototype Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Response Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Server Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Shared Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Single System Image (SSI) Cluster Management . . . . . . . . . . . . . . . . . . . . . . . 20System Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Virtual Machine Reader Management. . . . . . . . . . . . . . . . . . . . . . . . . . . 21VMRM Configuration Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Part 2. Installation and Configuration . . . . . . . . . . . . . . . . . . . . . 23

Chapter 3. Defining the Servers . . . . . . . . . . . . . . . . . . . . . . . . . 25Request Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Worker Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26LOHCOST. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28DTCSMAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28PERSMAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29OPERATNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Chapter 4. Setting up and Configuring the Server Environment . . . . . . . . . . . 31Shared File System Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31The Server Names File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31The Server Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Configuring CMA Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Configuring the CMA Using the Configuration Wizard . . . . . . . . . . . . . . . . . . . . 41Configuring the DMSSICNF COPY File . . . . . . . . . . . . . . . . . . . . . . . . . 46DMSSICNF COPY File Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Tailoring the DMSSICMO COPY File . . . . . . . . . . . . . . . . . . . . . . . . . . 55Using a Single CMA xCAT MN and Multiple CMA ZHCP Servers . . . . . . . . . . . . . . . . 55Using One xCAT MN Server and One ZHCP Server on Each Member of an SSI Cluster . . . . . . . . . 56Defining the xCAT Image Repository for z/VM Images . . . . . . . . . . . . . . . . . . . 57User Definition of xCAT and ZHCP Virtual Switches . . . . . . . . . . . . . . . . . . . . 57Changing the Administrator Password . . . . . . . . . . . . . . . . . . . . . . . . . 58Defining a System as an xCAT Node . . . . . . . . . . . . . . . . . . . . . . . . . . 59Discovering Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

TCP/IP Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Client Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Authorizing API Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

How Authorizing Requests Are Processed . . . . . . . . . . . . . . . . . . . . . . . . 82Name Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Starting and Restarting the Server Environment . . . . . . . . . . . . . . . . . . . . . . . 89Stopping the Server Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Defining Additional Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Activating or Deactivating Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Running the Installation Verification Programs . . . . . . . . . . . . . . . . . . . . . . . 91

Overview of IVP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Verifying the xCAT Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Tailoring the IVP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Part 3. User's Guide and Reference . . . . . . . . . . . . . . . . . . . . . . 99

Chapter 5. Programming Considerations . . . . . . . . . . . . . . . . . . . . 103Sockets Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

iv z/VM V6.4 Systems Management Application Programming

||

Call Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Name of Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Input Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Response 1 – Immediate Request Verification . . . . . . . . . . . . . . . . . . . . . . . 109Response 2 – Output Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Usage Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Return and Reason Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Chapter 6. Socket Application Programming Interfaces . . . . . . . . . . . . . . 111Asynchronous_Notification_Disable_DM . . . . . . . . . . . . . . . . . . . . . . . . . 112Asynchronous_Notification_Enable_DM . . . . . . . . . . . . . . . . . . . . . . . . . 116Asynchronous_Notification_Query_DM . . . . . . . . . . . . . . . . . . . . . . . . . 121Authorization_List_Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Authorization_List_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Authorization_List_Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Check_Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Delete_ABEND_Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Directory_Manager_Local_Tag_Define_DM . . . . . . . . . . . . . . . . . . . . . . . . 143Directory_Manager_Local_Tag_Delete_DM . . . . . . . . . . . . . . . . . . . . . . . . 146Directory_Manager_Local_Tag_Query_DM . . . . . . . . . . . . . . . . . . . . . . . . 149Directory_Manager_Local_Tag_Set_DM. . . . . . . . . . . . . . . . . . . . . . . . . . 152Directory_Manager_Search_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Directory_Manager_Task_Cancel_DM . . . . . . . . . . . . . . . . . . . . . . . . . . 160Event_Stream_Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Event_Subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Event_Unsubscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Image_Activate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Image_Active_Configuration_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Image_Console_Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Image_CPU_Define . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Image_CPU_Define_DM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Image_CPU_Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Image_CPU_Delete_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Image_CPU_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195Image_CPU_Query_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Image_CPU_Set_Maximum_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Image_Create_DM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Image_Deactivate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210Image_Definition_Async_Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Image_Definition_Create_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Image_Definition_Delete_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Image_Definition_Query_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235Image_Definition_Update_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Image_Delete_DM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254Image_Device_Dedicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257Image_Device_Dedicate_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260Image_Device_Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263Image_Device_Undedicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266Image_Device_Undedicate_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269Image_Disk_Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272Image_Disk_Copy_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Image_Disk_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281Image_Disk_Create_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285Image_Disk_Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Image_Disk_Delete_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295Image_Disk_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298Image_Disk_Share . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302Image_Disk_Share_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306Image_Disk_Unshare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310Image_Disk_Unshare_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

Contents v

Image_IPL_Delete_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316Image_IPL_Query_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319Image_IPL_Set_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322Image_Lock_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325Image_Lock_Query_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Image_MDISK_Link_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332Image_Name_Query_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336Image_Password_Set_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339Image_Pause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342Image_Query_Activate_Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345Image_Query_DM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348Image_Recycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351Image_Replace_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355Image_SCSI_Characteristics_Define_DM . . . . . . . . . . . . . . . . . . . . . . . . . 358Image_SCSI_Characteristics_Query_DM . . . . . . . . . . . . . . . . . . . . . . . . . 362Image_Status_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366Image_Unlock_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369Image_Volume_Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372Image_Volume_Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378Image_Volume_Share . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384Image_Volume_Space_Define_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . 387Image_Volume_Space_Define_Extended_DM . . . . . . . . . . . . . . . . . . . . . . . . 391Image_Volume_Space_Query_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . 396Image_Volume_Space_Query_Extended_DM . . . . . . . . . . . . . . . . . . . . . . . . 400Image_Volume_Space_Remove_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . 404Metadata_Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408Metadata_Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411Metadata_Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414Metadata_Space_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417Name_List_Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420Name_List_Destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423Name_List_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426Name_List_Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429Network_IP_Interface_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432Network_IP_Interface_Modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439Network_IP_Interface_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443Network_IP_Interface_Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450Page_or_Spool_Volume_Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454Process_ABEND_Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459Profile_Create_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462Profile_Delete_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465Profile_Lock_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468Profile_Lock_Query_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471Profile_Query_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475Profile_Replace_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478Profile_Unlock_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481Prototype_Create_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484Prototype_Delete_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487Prototype_Name_Query_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490Prototype_Query_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493Prototype_Replace_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496Query_ABEND_Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499Query_All_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503Query_API_Functional_Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508Query_Asynchronous_Operation_DM . . . . . . . . . . . . . . . . . . . . . . . . . . 511Query_Directory_Manager_Level_DM . . . . . . . . . . . . . . . . . . . . . . . . . . 514Response_Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517Shared_Memory_Access_Add_DM . . . . . . . . . . . . . . . . . . . . . . . . . . . 520Shared_Memory_Access_Query_DM. . . . . . . . . . . . . . . . . . . . . . . . . . . 524Shared_Memory_Access_Remove_DM . . . . . . . . . . . . . . . . . . . . . . . . . . 528Shared_Memory_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531

vi z/VM V6.4 Systems Management Application Programming

||

Shared_Memory_Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536Shared_Memory_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539Shared_Memory_Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543SMAPI_Status_Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547SSI_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551Static_Image_Changes_Activate_DM . . . . . . . . . . . . . . . . . . . . . . . . . . 556Static_Image_Changes_Deactivate_DM . . . . . . . . . . . . . . . . . . . . . . . . . . 559Static_Image_Changes_Immediate_DM . . . . . . . . . . . . . . . . . . . . . . . . . . 562System_Config_Syntax_Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565System_Disk_Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569System_Disk_Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572System_Disk_IO_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575System_Disk_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580System_EQID_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584System_FCP_Free_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588System_Image_Performance_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . 592System_Information_Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595System_Page_Utilization_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599System_Performance_Information_Query . . . . . . . . . . . . . . . . . . . . . . . . . 603System_Performance_Threshold_Disable . . . . . . . . . . . . . . . . . . . . . . . . . 610System_Performance_Threshold_Enable . . . . . . . . . . . . . . . . . . . . . . . . . 613System_RDR_File_Manage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616System_RDR_File_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619System_SCSI_Disk_Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622System_SCSI_Disk_Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626System_SCSI_Disk_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629System_Service_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633System_Shutdown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637System_Spool_Utilization_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641System_WWPN_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645Virtual_Channel_Connection_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . 649Virtual_Channel_Connection_Create_DM . . . . . . . . . . . . . . . . . . . . . . . . . 652Virtual_Channel_Connection_Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . 655Virtual_Channel_Connection_Delete_DM . . . . . . . . . . . . . . . . . . . . . . . . . 658Virtual_Network_Adapter_Connect_LAN . . . . . . . . . . . . . . . . . . . . . . . . . 661Virtual_Network_Adapter_Connect_LAN_DM . . . . . . . . . . . . . . . . . . . . . . . 665Virtual_Network_Adapter_Connect_Vswitch . . . . . . . . . . . . . . . . . . . . . . . . 669Virtual_Network_Adapter_Connect_Vswitch_DM . . . . . . . . . . . . . . . . . . . . . . 672Virtual_Network_Adapter_Connect_Vswitch_Extended . . . . . . . . . . . . . . . . . . . . 675Virtual_Network_Adapter_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . 678Virtual_Network_Adapter_Create_DM . . . . . . . . . . . . . . . . . . . . . . . . . . 681Virtual_Network_Adapter_Create_Extended . . . . . . . . . . . . . . . . . . . . . . . . 685Virtual_Network_Adapter_Create_Extended_DM . . . . . . . . . . . . . . . . . . . . . . 689Virtual_Network_Adapter_Delete. . . . . . . . . . . . . . . . . . . . . . . . . . . . 693Virtual_Network_Adapter_Delete_DM . . . . . . . . . . . . . . . . . . . . . . . . . . 696Virtual_Network_Adapter_Disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . 699Virtual_Network_Adapter_Disconnect_DM . . . . . . . . . . . . . . . . . . . . . . . . 702Virtual_Network_Adapter_Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . 705Virtual_Network_Adapter_Query_Extended . . . . . . . . . . . . . . . . . . . . . . . . 709Virtual_Network_LAN_Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715Virtual_Network_LAN_Access_Query . . . . . . . . . . . . . . . . . . . . . . . . . . 718Virtual_Network_LAN_Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721Virtual_Network_LAN_Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725Virtual_Network_LAN_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728Virtual_Network_OSA_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733Virtual_Network_VLAN_Query_Stats . . . . . . . . . . . . . . . . . . . . . . . . . . 737Virtual_Network_Vswitch_Create. . . . . . . . . . . . . . . . . . . . . . . . . . . . 742Virtual_Network_Vswitch_Create_Extended . . . . . . . . . . . . . . . . . . . . . . . . 750Virtual_Network_Vswitch_Delete. . . . . . . . . . . . . . . . . . . . . . . . . . . . 756Virtual_Network_Vswitch_Delete_Extended . . . . . . . . . . . . . . . . . . . . . . . . 762Virtual_Network_Vswitch_Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . 765

Contents vii

||

||||

Virtual_Network_Vswitch_Query_Byte_Stats . . . . . . . . . . . . . . . . . . . . . . . . 773Virtual_Network_Vswitch_Query_Extended . . . . . . . . . . . . . . . . . . . . . . . . 778Virtual_Network_Vswitch_Query_Stats . . . . . . . . . . . . . . . . . . . . . . . . . . 789Virtual_Network_Vswitch_Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794Virtual_Network_Vswitch_Set_Extended . . . . . . . . . . . . . . . . . . . . . . . . . 802VMRELOCATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811VMRELOCATE_Image_Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . 816VMRELOCATE_Modify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820VMRELOCATE_Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 824VMRM_Configuration_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 828VMRM_Configuration_Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . 832VMRM_Measurement_Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836

Chapter 7. Return and Reason Code Summary . . . . . . . . . . . . . . . . . . 841All Return Codes (Including Internal) . . . . . . . . . . . . . . . . . . . . . . . . . . 841Syntax Error Reason Codes (RC = 24) . . . . . . . . . . . . . . . . . . . . . . . . . . 853Internal Return Codes (RC = 396, 592, or 596) . . . . . . . . . . . . . . . . . . . . . . . 854

Return Code 396 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855Return Code 592, 596. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860

Part 4. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863

Appendix A. The Directory Manager Exit. . . . . . . . . . . . . . . . . . . . . 865Directory Manager Exit Input Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 865Directory Manager Exit Output Interface . . . . . . . . . . . . . . . . . . . . . . . . . 872

Appendix B. Creating Custom APIs . . . . . . . . . . . . . . . . . . . . . . . 873Designing the Custom API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873Writing the Custom Exec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874Installing the Custom Exec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874Return and Reason Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875Step-by-step Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875

Example: Designing the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875Example: Writing the Custom Exec . . . . . . . . . . . . . . . . . . . . . . . . . . 876Example: Installing the Custom Exec . . . . . . . . . . . . . . . . . . . . . . . . . 878

Appendix C. ENROLL and GRANT Commands Performed Automatically During z/VMInstallation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 879

Appendix D. Sample Code . . . . . . . . . . . . . . . . . . . . . . . . . . . 881Sample C Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881Sample Java Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 893

Appendix E. Diagnosing Configuration Errors During Server Startup . . . . . . . . 899

Appendix F. Using SMAPI with an External Security Manager. . . . . . . . . . . . 903Using SMAPI with RACF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903

Enabling RACROUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903Making the SMAPI Service Machines Exempt From Certain Command Checking. . . . . . . . . . . 904Making the ZHCP Service Machine Exempt from Transfer Command Access Validation . . . . . . . . 905Enabling SMAPI to Access DIAGNOSE X'88' . . . . . . . . . . . . . . . . . . . . . . . 905Enabling SMAPI to Access Needed Resources . . . . . . . . . . . . . . . . . . . . . . 906

viii z/VM V6.4 Systems Management Application Programming

||

Appendix G. Capturing SMAPI Data for Problem Resolution . . . . . . . . . . . . 909

Appendix H. OPNCLOUD Directory Entry . . . . . . . . . . . . . . . . . . . . 911

Appendix I. Utilities and Common Procedures . . . . . . . . . . . . . . . . . . 913Using the Script Panel in the xCAT User Interface . . . . . . . . . . . . . . . . . . . . . . 913Exchanging SSH Key Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915XCAT and ZHCP Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 916CONFIGUR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 918

CONFIGUR Subcommands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920SMCFGDM EXEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924

Appendix J. xCAT Commands . . . . . . . . . . . . . . . . . . . . . . . . . 925chdef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928chhypervisor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931chtab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934chvm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936dumpxCATdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942imgcapture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 943imgexport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 946imgimport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948lsdef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 951lsvm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 954makehosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 955makeknownhosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957mkdef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 958mkdummyimage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961mkvm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963nodeadd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966nodech . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 968nodediscoverdef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 970nodediscoverls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 972nodediscoverstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974nodediscoverstatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 978nodediscoverstop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 979nodels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 980nodeset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 982nodestat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 985pping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988restorexCATdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 989rinv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 990rmdef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994rmimage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 996rmvm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 998rpower . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999tabdump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000tabgrep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002tabprune . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003verifynode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005xdsh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1007zvmMsg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015zxcatCopyCloneList.pl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016zxcatexport.pl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017zxcatimport.pl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1018zxcatIVP.pl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1020Using the noderange option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025Using the xCAT stanza file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1028

Appendix K. Security Considerations for xCAT . . . . . . . . . . . . . . . . . 1031CP Commands Required for Guests Managed by xCAT . . . . . . . . . . . . . . . . . . . . 1031

Contents ix

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033Programming Interface Information . . . . . . . . . . . . . . . . . . . . . . . . . . 1035Trademarks and Service Marks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1035Terms and Conditions for Product Documentation . . . . . . . . . . . . . . . . . . . . . 1035IBM Online Privacy Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1036

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1037

Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1039Where to Get z/VM Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 1039z/VM Base Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1039z/VM Facilities and Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1040Prerequisite Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1041

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043

x z/VM V6.4 Systems Management Application Programming

Figures

1. The Socket-based Server Environment . . . . . . . . . . . . . . . . . . . . . . . . . 52. The Non-CMA Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73. Sample Panel of Configuration Wizard . . . . . . . . . . . . . . . . . . . . . . . . 434. Example of a Field Help Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . 445. Verify Service Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456. Verify Service Level Summary Results . . . . . . . . . . . . . . . . . . . . . . . . 457. Missing APARs Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458. PTFs in Production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459. The Settings Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

10. The Change Password Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . 5911. Specifying the Unlock Action . . . . . . . . . . . . . . . . . . . . . . . . . . . 6112. Specifying the Root Password . . . . . . . . . . . . . . . . . . . . . . . . . . . 6213. "Unlock System" Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6714. xCAT and OpenStack Discovery Panel . . . . . . . . . . . . . . . . . . . . . . . . 7015. Selecting A Group on Nodes Panel . . . . . . . . . . . . . . . . . . . . . . . . . . 7216. Preventing xCAT from Destroying the Virtual Server. . . . . . . . . . . . . . . . . . . . 7317. Newly Discovered Instances on Horizon Dashboard . . . . . . . . . . . . . . . . . . . . 7418. Instance Details for a Discovered Instance . . . . . . . . . . . . . . . . . . . . . . . 7519. Quotas Page for a Discovered Instance . . . . . . . . . . . . . . . . . . . . . . . . 7620. Verifying That a Project Exists . . . . . . . . . . . . . . . . . . . . . . . . . . . 7921. Verifying That a User Exists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8022. VSMWORK1 Server Authorization File . . . . . . . . . . . . . . . . . . . . . . . . 8223. xCAT GUI Help Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9324. IVP Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9425. Response Area of IVP Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . 9626. Selecting the xcat Node Checkbox on the Nodes Panel . . . . . . . . . . . . . . . . . . . 91327. Selecting “Run script” on the Actions Pulldown of The Nodes Panel . . . . . . . . . . . . . . 91428. Entering Commands in the Script Box . . . . . . . . . . . . . . . . . . . . . . . . 91429. Yellow Status Box Showing Results of Commands . . . . . . . . . . . . . . . . . . . . 91530. Unlock Panel for Node Checkbox on demonode . . . . . . . . . . . . . . . . . . . . . 916

© Copyright IBM Corp. 2003, 2018 xi

xii z/VM V6.4 Systems Management Application Programming

Tables

1. CMA Roles and the Services they Run . . . . . . . . . . . . . . . . . . . . . . . . . 72. Fields in the DMSSISVR NAMES File . . . . . . . . . . . . . . . . . . . . . . . . . 323. Summary of DMSSICNF COPY File Properties and Whether They are Required . . . . . . . . . . 544. Input Keywords and Values for Image_Definition_Create_DM . . . . . . . . . . . . . . . . 2185. MDISK= Keywords by Directory Manager Operation . . . . . . . . . . . . . . . . . . . 2256. Input Keywords and Values for Image_Definition_Delete_DM . . . . . . . . . . . . . . . . 2297. Output Keywords and Values for Image_Definition_Query_DM. . . . . . . . . . . . . . . . 2378. Input Keywords and Values for Image_Definition_Update_DM . . . . . . . . . . . . . . . . 2449. MDISK= Keywords by Directory Manager Operation . . . . . . . . . . . . . . . . . . . 251

10. Maximum Starting Location Allowed, by Allocation Unit . . . . . . . . . . . . . . . . . . 27911. Maximum Starting Location and image_disk_size Value Allowed, by Allocation Unit . . . . . . . . 29012. Input Keywords and Values for Query_All_DM . . . . . . . . . . . . . . . . . . . . . 50513. Output Keywords and Values for System_Disk_IO_Query . . . . . . . . . . . . . . . . . 57714. Output Keywords and Values for System_Information_Query . . . . . . . . . . . . . . . . 59715. Input Keywords and Values for System_Performance_Information_Query . . . . . . . . . . . . 60416. Output Keywords and Values for System_Performance_Information_Query . . . . . . . . . . . . 60617. SEGTPRC DSECT field names corresponding to System_Performance_Information_Query

DETAILED_CPU=output_subkeyword=value pairs . . . . . . . . . . . . . . . . . . . . . 60818. Input Keywords and Values for System_Service_Query . . . . . . . . . . . . . . . . . . 63419. Output Keywords and Values for System_Service_Query . . . . . . . . . . . . . . . . . . 63520. Output Keywords and Values for Virtual_Network_Adapter_Query_Extended . . . . . . . . . . . 71121. All Return Codes (Including Internal) . . . . . . . . . . . . . . . . . . . . . . . . 84122. Internal Return Codes (RC = 396, 592, or 596). . . . . . . . . . . . . . . . . . . . . . 85423. CP Commands Used by Systems Management APIs . . . . . . . . . . . . . . . . . . . 85524. Directory Manager Function-Specific Arguments . . . . . . . . . . . . . . . . . . . . . 86625. Configuration Errors, With Explanation and Affected Areas . . . . . . . . . . . . . . . . . 89926. xCAT Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92527. Sample Monsetting Table Values . . . . . . . . . . . . . . . . . . . . . . . . . . 987

© Copyright IBM Corp. 2003, 2018 xiii

xiv z/VM V6.4 Systems Management Application Programming

About This Document

This document contains socket-based application programming interfaces (APIs) toperform system management functions for virtual images (guests) in an IBM®

z/VM® environment.

Important: This document contains information pertaining to the new socket-basedAPIs introduced in z/VM V5.3. The Remote Procedure Calls used in earlierreleases are no longer supported.

Intended AudienceThis document is intended for systems programmers and applicationsprogrammers who will be writing programs to perform system management ofvirtual systems in a z/VM environment.

You should have experience with z/VM and z/VM guests. You should also have aworking knowledge of programming with sockets.

Where to Find More InformationSee “Bibliography” on page 1039 at the back of this document.

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

© Copyright IBM Corp. 2003, 2018 xv

xvi z/VM V6.4 Systems Management Application Programming

How to Send Your Comments to IBM

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

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

zvmforms/webqs.html).

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

z/VM V6.4 Systems Management Application ProgrammingSC24-6234-13

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

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

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

If You Have a Technical Problem

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

© Copyright IBM Corp. 2003, 2018 xvii

http://www.ibm.com/systems/z/os/zvm/zvmforms/webqs.htmlhttp://www.ibm.com/systems/z/os/zvm/zvmforms/webqs.htmlhttp://www.ibm.com/vm/service/http://www.ibm.com/support/entry/portal/Overview/

xviii z/VM V6.4 Systems Management Application Programming

Summary of Changes for z/VM Systems ManagementApplication Programming

This document contains terminology, maintenance, and editorial changes. Technicalchanges or additions to the text and illustrations are indicated by a vertical line tothe left of the change. Product updates are provided as program temporary fixes(PTFs) for authorized program analysis reports (APARs).

SC24-6234-013, z/VM Version 6 Release 4 (March 2018)With the PTF for APAR VM66120, this edition includes changes to support productchanges provided or announced after the general availability of z/VM V6.4.

New APIsThe following APIs have been added:v Pause a running image and restart a paused image. See “Image_Pause” on page

342.v Retrieve virtual machine performance data. See

“System_Image_Performance_Query” on page 592.v Manipulate the reader files of a target user ID. See “System_RDR_File_Manage”

on page 616.v Query the reader files of a target user ID. See “System_RDR_File_Query” on

page 619.v Query the byte information statistics of a virtual switch. See

“Virtual_Network_Vswitch_Query_Byte_Stats” on page 773.

SC24-6234-012, z/VM Version 6 Release 4 (January 2017)

With the PTF for APAR VM65893, this edition includes changes to support productchanges provided or announced after the general availability of z/VM V6.4.

Configuration Wizard SupportYou can use the configuration wizard to configure the CMA. See “Configuring theCMA Using the Configuration Wizard” on page 41 and “CONFIGUR” on page 918.

Installation Verification Program EnhancementsThe Installation Verification Programs (IVP) can now be invoked from the xCATGUI. See “Running the Installation Verification Programs” on page 91.

Other Changesv New xCAT commands have been added. See “verifynode” on page 1005,

“zvmMsg” on page 1015, and “zxcatIVP.pl” on page 1020.v The SMCFGDM EXEC configures the Directory Maintenance Facility (DirMaint)

so that DirMaint is in sync with SMAPI. See “SMCFGDM EXEC” on page 924.v A new API has been added to obtain information about metadata space used

and available.. See “Metadata_Space_Query” on page 417.

© Copyright IBM Corp. 2003, 2018 xix

SC24-6234-011, z/VM Version 6 Release 4

This edition includes changes to support product changes provided or announcedfor the general availability of z/VM V6.4.

Remove zManager SupportThe IBM z Unified Resource Manager (zManager) is no longer supported. Thevswitch types of IEDN and INMN have been removed from various externals.

Alternate Deployment Provisioning SupportThe following commands are new to support alternate deployment provisioning:

“mkdummyimage” on page 961“zxcatCopyCloneList.pl” on page 1016

OPNCLOUD Virtual MachineThe xCAT MN and the ZHCP server now both run within the OPNCLOUD virtualmachine. Various changes have been made throughout this document to reflect theintroduction of the OPNCLOUD virtual machine and the OPNCLOUD user ID.

Other ChangesThe appendix "Migrating to an Integrated xCAT MN and ZHCP Server in theSame CMA" has been removed. This information does not apply to z/VM 6.4.

SC24-6234-10, z/VM Version 6 Release 3 (March 2016)

This edition includes changes to support product changes provided or announcedafter the general availability of z/VM V6.3.v Integration of xCAT functions into the Cloud Manager Appliance. This support

allows you to run a fully functional z/VM OpenStack solution in a single virtualserver, without the need for separate ZHCP servers. The following changes havebeen made to reflect this support:– The description of the Cloud Manager Appliance has been updated. See “The

Cloud Manager Appliance (CMA)” on page 6.– The section “Configuring CMA Servers” on page 40 has been updated.– Information is provided to help you migrate from using separate z/VM user

IDs for xCAT and ZHCP to using one z/VM user ID for both. See AppendixK.

v The following xCAT commands are new:“nodestat” on page 985.“zxcatexport.pl” on page 1017.“zxcatimport.pl” on page 1018.

SC24-6234-09, z/VM Version 6 Release 3 (September 2015)

This edition includes changes to support product changes provided or announcedafter the general availability of z/VM V6.3.

Appendix J, “xCAT Commands,” on page 925 is added.

xx z/VM V6.4 Systems Management Application Programming

Support is added to allow OpenStack and xCAT to discover Linux on z Systemsservers on a z/VM hypervisor and then to add those servers to their respectivedatabases. At the end of this process, the servers will be unlocked and ready to bemanaged. See “Discovering Systems” on page 62 for more information.

This support includes a new API:v “Virtual_Network_Adapter_Query_Extended” on page 709.

In addition, the following xCAT command is updated with new options:v “xdsh” on page 1007.

and the following xCAT commands are added:v “nodediscoverdef” on page 970v “nodediscoverls” on page 972v “nodediscoverstart” on page 974v “nodediscoverstatus” on page 978v “nodediscoverstop” on page 979.

The following APIs are updated to support multi-vswitch link aggregation, whichallows an OSA-Express port group to span multiple virtual switches within asingle host or between multiple systems running z/VM:v “Virtual_Network_Vswitch_Create_Extended” on page 750v “Virtual_Network_Vswitch_Query_Extended” on page 778v “Virtual_Network_Vswitch_Set_Extended” on page 802.

SC24-6234-08, z/VM Version 6 Release 3 (March 2015)


Appendix I, “Utilities and Common Procedures,” on page 913 is added.

“Configuring CMA Servers” on page 40 is expanded with new information.

SC24-6234-07, z/VM Version 6 Release 3 (September 2014)


“The Cloud Manager Appliance (CMA)” on page 6 is added.

“Configuring CMA Servers” on page 40 is expanded with new information.

SC24-6234-06, z/VM Version 6 Release 3 (June 2014)


“Using a Single CMA xCAT MN and Multiple CMA ZHCP Servers” on page 55 isexpanded with new information.

“Using One xCAT MN Server and One ZHCP Server on Each Member of an SSICluster” on page 56 is added.

Summary of Changes for z/VM Systems Management Application Programming xxi

xxii z/VM V6.4 Systems Management Application Programming

Part 1. OverviewChapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3The Directory Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4The Socket-based Server Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . 4The Extreme Cloud Administration Toolkit (xCAT) for z/VM . . . . . . . . . . . . . . . . . . . 5

The Cloud Manager Appliance (CMA). . . . . . . . . . . . . . . . . . . . . . . . . . 6The Non-CMA Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 2. API Functions Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 9ABEND Dump Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Directory Manager Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Directory Manager Local Tag and Scan . . . . . . . . . . . . . . . . . . . . . . . . . . 10Directory Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Directory Updates Subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Disk Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Event Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Image Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Image Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Image CPUs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Image Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Image IPL Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Image Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Image Volume Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17List-Directed IPL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Name List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Network Interface Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Profile Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Prototype Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Response Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Server Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Shared Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Single System Image (SSI) Cluster Management . . . . . . . . . . . . . . . . . . . . . . . 20System Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Virtual Machine Reader Management. . . . . . . . . . . . . . . . . . . . . . . . . . . 21VMRM Configuration Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

© Copyright IBM Corp. 2003, 2018 1

||

2 z/VM V6.4 Systems Management Application Programming

Chapter 1. Introduction

One of the major advantages of z/VM has always been its ability to provide eachuser with an individual working environment, a virtual machine (virtual image). Thevirtual machine simulates a dedicated, real machine, including processor functions,memory, and input/output resources. A variety of operating systems andapplications can run in a virtual machine. Managing a large number of guestoperating systems (virtual images), however, requires a thorough understanding ofVM concepts and the knowledge and skill to execute a complex set of commands.

The Systems Management APIs simplify the task of managing many virtual imagesrunning under a single z/VM image. A standard, platform-independent clientinterface reduces the amount of z/VM-specific programming skills required. TheSystems Management APIs include a basic set of interfaces that can be used to:v Create new virtual images in a variety of operating environments:

– Linux on z Systems– z/OS®

– z/VM– z/VSE™

– z/TPF– CMS

v Allocate and manage resources for virtual imagesv Change a virtual image configurationv Manage connectivity between virtual imagesv Activate and deactivate:

– Individual virtual images– Multiple virtual images

v Manage DASD volumes and groupsv Update Virtual Machine Resource Manager Service Virtual Machine (VMRM

SVM) configuration files and query data without logging onto the VMRM server.v Support the directory manager's ability to manage subscriptions to directory

updates, with the ability to add new subscriptions, delete old subscriptions, andquery existing subscriptions

v Support the directory manager's tag and scan functionsv Allow creation and updating of the LOADDEV directory statement for a virtual

image, as well as queries of a virtual image's LOADDEV settingsv Query the time when a virtual image was activated.

Note the following when using SMAPI:v VSMGUARD must always be used to start SMAPI, regardless of whether the

system in running in a Unified Resource Manager environment.v A Directory Manager license is not required. If a Directory Manager is not

purchased and installed, a “SMAPI USE ONLY” instance of DirMaint will beinstalled and configured.

v A Performance Toolkit license is not required. SMAPI will install and configure a“SMAPI USE ONLY” instance of the Performance Toolkit to obtain performancedata for use in provided SMAPI APIs.

In addition:


v SMAPI supports the Extreme Cloud Administration Toolkit (xCAT) appliancethat is shipped with z/VM V6.3 and later releases. See “Configuring CMAServers” on page 40 for information on configuring xCAT, and Appendix H,“OPNCLOUD Directory Entry,” on page 911 for the directory entries for theZHCP and XCAT servers.For more information on setting up and using xCAT, see xCAT z/VM(sourceforge.net/p/xcat/wiki/XCAT_zVM/). See also the xCAT YouTubechannel (www.youtube.com/user/xcatuser) for demonstrations on managingyour systems through the xCAT user interface.

v SMAPI also supports the z/VM Cloud Manager Appliance (CMA), which is astack of software designed to provide an easy way to deploy OpenStack withthe z/VM driver, and to provide an entry level of CMA.

v LOHCOST, the SMAPI database server, is supported in all SMAPI installations.v The IBM z Unified Resource Manager, first supported in z/VM V6.1, is no

longer supported in z/VM 6.3 and later releases.v The Remote Procedure Calls used in releases prior to z/VM V5.3 are no longer

supported.

The Directory ManagerNote that the Systems Management APIs require a directory manager. If the IBMz/VM Directory Maintenance Facility (DirMaint) is your directory manager, thenFunction Level 640 or later is required with the new socket-based environment. Formore information on DirMaint, please consult the following publications:v z/VM: Directory Maintenance Facility Commands Referencev z/VM: Directory Maintenance Facility Tailoring and Administration Guidev z/VM: Directory Maintenance Facility Messages

Note that if you have installed the full DirMaint product, you should review theconfiguration steps documented in “Appendix B. DirMaint Support for SystemsManagement APIs”, in the z/VM: Directory Maintenance Facility Tailoring andAdministration Guide.

If you are using a different directory manager, you'll need to replace the directorymanager exit as defined in Chapter 3, “Defining the Servers,” on page 25. For moreinformation on this exit, see Appendix A, “The Directory Manager Exit,” on page865.

The Socket-based Server EnvironmentThe socket-based server environment consists of one or more request servers andtwo or more worker servers. The request server listens for socket connectionsinitiated by a client program. The server accepts the connection, receives the data,and then calls the appropriate worker server to process the request, while theclient program waits for the response.

Three types of API functions are supported:v IBM-supplied directory manager functionsv IBM-supplied non-directory manager functionsv Customer-defined functions.

Figure 1 on page 5 shows how the socket-based servers work together.

Introduction


http://sourceforge.net/p/xcat/wiki/XCAT_zVM/http://sourceforge.net/p/xcat/wiki/XCAT_zVM/http://www.youtube.com/user/xcatuserhttp://www.youtube.com/user/xcatuser

See Chapter 3, “Defining the Servers,” on page 25 for more information.

The Extreme Cloud Administration Toolkit (xCAT) for z/VM

The Extreme Cloud Administration Toolkit (xCAT) appliance shipped with z/VMV6.3 is an Open Source scalable distributed computing management andprovisioning tool that provides a unified interface for hardware control, discovery,and OS diskful/diskfree deployment. The toolkit can be used for the deploymentand administration of Linux clusters. Its features are based on user requirements,and take advantage of IBM System x, IBM z Systems™ and Power Systemshardware.

Notes:1. The xCAT appliance shipped with z/VM manages z/VM systems only.2. The xCAT appliance shipped with z/VM does not support Ganglia.3. The xCAT appliance shipped with z/VM does not provide a full xCAT

command line interface.4. The default URL for logging in to xCAT is https://x.x.x.x/xcat, where x.x.x.x is

the IP address of the xCAT MN. Users must log in via HTTPS so that traffic isencrypted and therefore more secure.

5. The default login user name/password is admin/admin.

xCAT consists of a pair of servers: a management node (xCAT MN) with which theuser or some other program communicates to request management changes, and aZHCP server that interacts with the z/VM System Management API servers andwith other z/VM management servers and the directory manager on an instance ofthe z/VM hypervisor. Both the xCAT MN server and the ZHCP server run withinthe same virtual machine, called the OPNCLOUD virtual machine. Only oneinstance of the xCAT management server is necessary, as is one instance of theZHCP server per z/VM hypervisor instance. xCAT supports REST APIs and a GUI.

Additional information on setting up and using xCAT can be found at xCATz/VM (sourceforge.net/p/xcat/wiki/XCAT_zVM/). See also the xCAT YouTubechannel (www.youtube.com/user/xcatuser) for demonstrations on managing yoursystems through the xCAT user interface.

RequestLayer

WorkerLayer

Functions

Socket-based Server Environment

Web Server

SE

CMS

Other

Client

Customer-definedFunctions

IBM-suppliedFunctions

WorkerServers

RequestServers

Figure 1. The Socket-based Server Environment

Introduction

Chapter 1. Introduction 5

http://sourceforge.net/p/xcat/wiki/XCAT_zVM/http://sourceforge.net/p/xcat/wiki/XCAT_zVM/http://www.youtube.com/user/xcatuserhttp://www.youtube.com/user/xcatuser

z/VM supports two basic environments for using OpenStack to manage z/VM.This document, along with the appropriate version of Enabling z/VM for OpenStack,guides you in the configuration of these environments.

The first environment uses an appliance which is installed in a z/VM virtualmachine, usually the virtual machine named OPNCLOUD. The term z/VM CloudManager Appliance or CMA is used to refer to this environment. For moreinformation on how the CMA can be configured, see “The Cloud ManagerAppliance (CMA).”

The second environment, non-CMA, runs the OpenStack services in a separateLinux (or Linux for System z) machine that the customer has setup for thispurpose. This machine is considered to be a non-CMA machine. It interacts withan xCAT MN running in a z/VM virtual machine, usually the virtual machinenamed OPNCLOUD, which is usually defined using the CMA. The xCAT MN isconsidered a CMA system. See “The Non-CMA Environment” on page 7 for moreinformation.

The Cloud Manager Appliance (CMA)

The z/VM Cloud Manager Appliance (CMA) provides an easy method to deployz/VM OpenStack enablement. OpenStack products and solutions can beconstructed to use as many or as few of the services as is appropriate, whether thatmeans that the CMA runs cloud controller services, compute node services, or onlyservices needed by OpenStack z/VM drivers running in other virtual machines oron other platforms.

The z/VM CMA DVD provided with z/VM V6.4 is no longer available, nor is theCMA code available for download from IBM Fix Central. The CMA is stabilized atthe Newton release level. The CMA will continue to be supported for security fixesand client-reported problems. However, no support for newer releases ofOpenStack or functional enhancements are planned.

If you are interested in performing a new installation of the z/VM CMA, contactthe IBM z/VM level 2 support team for the installation media or a digitaldownload. IBM does not plan to ship OpenStack or xCAT support with the z/VMhypervisor once the CMA is discontinued from service.

z/VM supports the following system roles, which control the set of servicesrunning inside the OPNCLOUD virtual machine:

controllerRuns cloud controller services (such as the glance image services) inaddition to all services listed under the compute role. z/VM also runs thexCAT MN and ZHCP services to allow the controller to manage OpenStackz/VM hosts. For more information on cloud controller services, seehttp://docs.openstack.org/ops-guide/arch-cloud-controller.html.

computeRuns compute services (nova-compute service), networking services(neutron-zvm-agent service), and telemetry services (ceilometer-polling) forthe z/VM hypervisor. z/VM also runs the ZHCP service to allow a remotexCAT MN service to manage the host.

compute_mnRuns compute, networking, and telemetry services (listed under thecompute role) for the z/VM hypervisor. It also runs the xCAT MN and

Introduction


|||||

||||

http://docs.openstack.org/ops-guide/arch-cloud-controller.html

ZHCP services. This type of node is used in an environment whereOpenStack controller services are run on a non-CMA node (for example, onother platforms). The xCAT MN and ZHCP services allow a controller tomanage the z/VM host without requiring cloud controller services to berunning on the host.

mn Runs the xCAT MN and ZHCP services. This is useful when all OpenStackservices are running in non-CMA nodes or when you want to use xCATand not OpenStack.

zhcp Runs only the ZHCP service. This is useful when all OpenStack servicesare running in non-CMA nodes or when the you want to use xCAT andnot OpenStack. Note that another z/VM host must run an xCAT MNservice to manage the host through the ZHCP service.

Table 1 summarizes the services that run in each configured CMA role.

Table 1. CMA Roles and the Services they Run

Servicescontroller

rolecompute

rolecompute_mn

role mn role zhcp role

Cloud control servicessuch as glance, cinder,keystone, neutron-server,etc.

X

nova-compute,neutron-zvm-agent,ceilometer-polling

X X X

xCAT services (used bythe OpenStack z/VMdriver to interact withz/VM)

X X X

ZHCP service X X X X X

The Non-CMA Environment

The non-CMA environment, as shown in Figure 2, refers to the environment whereOpenStack services are not running in a CMA. In this example, OpenStack servicesrun in a Linux compute node.

OPNCLOUD

XCATMN

ServerOpenStack

Services(e.g. Nova)

LinuxCompute

Node

ZHCPServer

OpenStack compute node running in a non-z/VM server

z/VM

Figure 2. The Non-CMA Environment

Introduction

Chapter 1. Introduction 7

Running the xCAT MN and the ZHCP server in separate virtual machines is notsupported in z/VM 6.4 and later releases.

Introduction


Chapter 2. API Functions Overview

The various functions of the Systems Management APIs may be categorized asfollows:

ABEND Dump ManagementThese APIs are called for maintenance of ABEND dumps.

Delete_ABEND_DumpInstruct the dump processing userid to remove a specified ABEND dumpfrom the reader or from the dump processing location specified in theDMSSICNF COPY file.

Process_ABEND_DumpInstruct the dump processing userid to process one or more ABENDdumps from its reader and place them in the dump processing locationspecified in the DMSSICNF COPY file.

Query_ABEND_DumpDisplay the current ABEND dumps that appear in the OPERATNS userid'sreader or have already been processed to the dump processing locationspecified in the DMSSICNF COPY file.

AuthorizationThese APIs are called for maintenance of the systems management serverauthorization file.

Authorization_List_AddAdd an entry to the authorization file.

Authorization_List_RemoveRemove an entry from the authorization file.

Authorization_List_QueryQuery the entries in the authorization file.

Directory Manager ControlThese APIs control the behavior of the directory manager.

Directory_Manager_Task_Cancel_DMCancel a specific asynchronous task being performed by the directorymanager.

Query_Asynchronous_Operation_DMQuery the status of an asynchronous directory manager operation.

Query_Directory_Manager_Level_DMQuery the directory manager that is being used and its functional level.

Static_Image_Changes_Activate_DMEnable changes to the source directory to be made available to virtualimages.


Static_Image_Changes_Deactivate_DMPrevent changes to the source directory from being made available tovirtual images.

Static_Image_Changes_Immediate_DMMake changes to the source directory immediately available to virtualimages regardless of the current status of static image changes (active orinactive).

Directory Manager Local Tag and ScanThese APIs manage tags in the directory and perform searches of the directory.

Directory_Manager_Local_Tag_Define_DMDefine a local tag or named comment record to contain installation-specificinformation about a virtual image.

Directory_Manager_Local_Tag_Delete_DMRemove a local tag or named comment record from the directorymanager's internal tables, so that users will no longer be able to set orquery the tag.

Directory_Manager_Local_Tag_Query_DMObtain the value of a virtual image’s local tag or named comment record.

Directory_Manager_Local_Tag_Set_DMSet the value of a virtual image's local tag or named comment record.

Directory_Manager_Search_DMSearch the directory for records that match the specified pattern.

Directory ParsingThese APIs parse directory statements.

Image_Definition_Async_UpdatesChange the completion notification for Image_Definition_Update_DM,Image_Definition_Delete_DM, or Image_Definition_Create_DM.

Image_Definition_Create_DMCreate a new virtual machine directory entry for a particular system.

Image_Definition_Delete_DMRemove a directory statement for a user or profile.

Image_Definition_Query_DMExtract directory records and parse them into certain keywords.

Image_Definition_Update_DMUpdate (replace) a directory statement for a user or profile – or create oneif not found.

Metadata_DeleteDelete metadata values associated with a textual identifier (typically adirectory entry name).

Metadata_GetObtain metadata values associated with a textual identifier (typically adirectory entry name).

Metadata_SetSet metadata values associated with a textual identifier (typically adirectory entry name).


Metadata_Space_QueryObtain information about metadata space used and available.

Query_All_DMObtain the contents of the entire system directory.

Directory Updates SubscriptionThese APIs manage subscriptions to directory updates.

Asynchronous_Notification_Disable_DMEnd notification of updates to specified entities as they occur.

Asynchronous_Notification_Enable_DMBegin notification of updates to a specified entity as the updates occur.

Asynchronous_Notification_Query_DMQuery which users are subscribed to receive notification of updates tospecified entities.

Disk ManagementThese APIs manage disks.

Page_or_Spool_Volume_AddAdd a full volume page or spool disk to the system.

System_Disk_AccessibilityVerify that a device is available to be attached.

System_Disk_AddDynamically add an ECKD disk to a running z/VM system.

System_Disk_IO_QueryObtain DASD read and write byte counts for SCSI EDEV and ECKDvolumes owned by z/VM, and for which the control units haveinformation.

System_Disk_QueryQuery a real ECKD disk or all real ECKD disks.

System_EQID_QueryObtain a list of the system devices assigned a device equivalency ID.

System_FCP_Free_QueryQuery free FCP disk information.

System_SCSI_Disk_AddDynamically add a SCSI disk to a running z/VM system.

System_SCSI_Disk_DeleteDelete a real SCSI disk.

System_SCSI_Disk_QueryQuery a real SCSI disk or all real SCSI disks.

System_WWPN_QueryQuery all FCPs on a z/VM system and return a list of WWPNs.

Event ManagementThese APIs manage system events.

Chapter 2. API Functions Overview 11

Event_Stream_AddAdd an event to the event stream.

Event_SubscribeArrange to be asynchronously notified of events of interest.

Event_UnsubscribeEnd asynchronous notification of events of interest.

System_Performance_Threshold_DisableDisable thresholds for asynchronous event production.

System_Performance_Threshold_EnableEnable thresholds for asynchronous event production.

Image CharacteristicsThese APIs invoke the directory manager to define and modify virtual images andtheir characteristics.

Image_Create_DMDefine a new virtual image in the directory.

Image_Delete_DMDelete a virtual image's definition from the directory.

Image_Lock_DMLock a virtual image’s directory entry or a specific device in a virtualimage’s directory entry so that it cannot be changed.

Image_Lock_Query_DMQuery the status of directory manager locks in effect for a specific virtualimage.

Image_Name_Query_DMObtain a list of defined virtual images.

Image_Password_Set_DMSet or change a virtual image’s password.

Image_Query_DMObtain a virtual image’s directory entry.

Image_Replace_DMReplace a virtual image’s directory entry.

Image_Unlock_DMUnlock a virtual image’s directory entry or a specific device in a virtualimage’s directory entry so it can be changed.

Image ConnectivityThese APIs are called to establish and manage connectivity between virtual images.They may be used to:v Change or query the configuration of an active virtual image, orv Change the static configuration of a virtual image in the directory (these APIs

end in "_DM").

New APIs are provided to extend support for connectivity between virtual images:

Virtual_Channel_Connection_CreateEstablish a virtual network connection between two active virtual images.


A virtual network connector (CTCA) is added to each virtual image’sconfiguration if one is not already defined.

Virtual_Channel_Connection_Create_DMAdd a virtual network connection between two virtual images to theirdirectory entries. A virtual network connector (CTCA) is added to eachvirtual image’s directory entry if one is not already defined.

Virtual_Channel_Connection_DeleteTerminate a virtual network connection between two active virtual imagesand remove the virtual network connector (CTCA) from the virtual image’sconfiguration.

Virtual_Channel_Connection_Delete_DMRemove a virtual network connection from a virtual image’s directoryentry and remove the virtual network connector (CTCA) from the virtualimage’s directory entry.

Virtual_Network_Adapter_Connect_LANConnect an existing virtual network adapter on an active virtual image toan existing virtual network LAN.

Virtual_Network_Adapter_Connect_LAN_DMDefine a virtual network LAN connection for an existing virtual networkadapter in a virtual image’s directory entry.

Virtual_Network_Adapter_Connect_VswitchConnect an existing virtual network adapter on an active virtual image toan existing virtual switch.

Virtual_Network_Adapter_Connect_Vswitch_DMDefine a virtual switch connection for an existing virtual network adapterin a virtual image’s directory entry.

Virtual_Network_Adapter_Connect_Vswitch_ExtendedConnect an existing virtual network adapter on an active virtual image toan existing virtual switch (extended version ofVirtual_Network_Adapter_Connect_Vswitch).

Virtual_Network_Adapter_CreateAdd a virtual network interface card (NIC) to an active virtual image.

Virtual_Network_Adapter_Create_DMAdd a virtual network interface card (NIC) to a virtual image’s directoryentry.

Virtual_Network_Adapter_Create_ExtendedAdd a virtual network interface card (NIC) to an active virtual image(extended version of Virtual_Network_Adapter_Create).

Virtual_Network_Adapter_Create_Extended_DMAdd a virtual network interface card (NIC) to a virtual image’s directoryentry (extended version of Virtual_Network_Adapter_Create_DM).

Virtual_Network_Adapter_DeleteRemove a virtual network interface card (NIC) from an active virtualimage.

Virtual_Network_Adapter_Delete_DMRemove a virtual network interface card (NIC) from a virtual image’sdirectory entry.


Virtual_Network_Adapter_DisconnectDisconnect a virtual network adapter on an active virtual image from avirtual network LAN or virtual switch.

Virtual_Network_Adapter_Disconnect_DMRemove a virtual network LAN or virtual switch connection from a virtualnetwork adapter definition in a virtual image’s directory entry.

Virtual_Network_Adapter_QueryObtain information about the specified adapter for an active virtual image.

Virtual_Network_Adapter_Query_ExtendedObtain information about the specified adapter for an active virtual image(extended version of Virtual_Network_Adapter_Query).

Virtual_Network_LAN_AccessGrant users access to a restricted virtual network LAN.

Virtual_Network_LAN_Access_QueryQuery which users are authorized to access a specified restricted virtualnetwork LAN.

Virtual_Network_LAN_CreateCreate a virtual network LAN.

Virtual_Network_LAN_DeleteDelete a virtual network LAN.

Virtual_Network_LAN_QueryObtain information about a virtual network LAN.

Virtual_Network_OSA_QueryQuery data about real OSA devices.

Virtual_Network_VLAN_Query_StatsQuery a virtual LAN's statistics.

Virtual_Network_Vswitch_CreateCreate a virtual switch.

Virtual_Network_Vswitch_Create_ExtendedCreate a virtual switch (extended version ofVirtual_Network_Vswitch_Create).

Virtual_Network_Vswitch_DeleteDelete a virtual switch.

Virtual_Network_Vswitch_Delete_ExtendedDelete a virtual switch (extended version ofVirtual_Network_Vswitch_Delete).

Virtual_Network_VSwitch_QueryObtain information about the specified virtual switch or switches.

Virtual_Network_Vswitch_Query_ExtendedObtain information about the specified virtual switch or switches(extended version of Virtual_Network_Vswitch_Query).

Virtual_Network_Vswitch_Query_StatsQuery a virtual switch's statistics.

Virtual_Network_Vswitch_SetChange the configuration of an existing virtual switch.


Virtual_Network_Vswitch_Set_ExtendedChange the configuration of an existing virtual switch (extended version ofVirtual_Network_Vswitch_Set).

Image CPUsThese APIs manage virtual processors used by virtual images.

Image_CPU_DefineAdd a virtual processor to an active virtual image’s configuration.

Image_CPU_Define_DMAdd a virtual processor to a virtual image’s directory entry.

Image_CPU_DeleteDelete a virtual processor from an active virtual image’s configuration.

Image_CPU_Delete_DMDelete a virtual processor from a virtual image’s directory entry.

Image_CPU_QueryQuery the virtual processors in an active virtual image’s configuration.

Image_CPU_Query_DMQuery a virtual processor in a virtual image’s directory entry.

Image_CPU_Set_Maximum_DMSet the maximum number of virtual processors that can be defined in avirtual image’s directory entry.

Image DevicesThese APIs manage devices used by virtual images. They may be used to:v Change the configuration of an active virtual image, orv Change the static configuration of a virtual image in the directory (these APIs

end in "_DM").

Image_Device_DedicateAdd a dedicated device to an active virtual image’s configuration.

Image_Device_Dedicate_DMAdd a dedicated device to a virtual image’s directory entry.

Image_Device_ResetClear all pending interrupts from the specified virtual device.

Image_Device_UndedicateDelete a dedicated device from an active virtual image’s configuration.

Image_Device_Undedicate_DMDelete a dedicated device from a virtual image’s directory entry.

Image_Disk_CopyClone a disk in an active virtual image’s configuration.

Image_Disk_Copy_DMClone a disk in a virtual image’s directory entry.

Image_Disk_CreateAdd a disk that is defined in a virtual image’s directory entry to thatvirtual image’s active configuration.


Image_Disk_Create_DMAdd a disk to a virtual image’s directory entry.

Image_Disk_DeleteDelete a disk from an active virtual image’s configuration.

Image_Disk_Delete_DMDelete a disk from a virtual image’s directory entry.

Image_Disk_QueryDisplay the status of all DASDs accessible to a virtual image, includingtemporary disks and virtual disks in storage.

Image_Disk_ShareAdd a disk that is defined in a virtual image’s directory entry to a differentactive virtual image’s configuration.

Image_Disk_Share_DMAdd a disk that is defined in a virtual image’s directory entry to a differentvirtual image’s directory entry.

Image_Disk_UnshareDelete a shared disk from an active virtual image’s configuration.

Image_Disk_Unshare_DMDelete a shared disk from a virtual image’s directory entry.

Image_MDISK_Link_QueryQuery the links to an image's MDISK.

Image IPL ManagementThese APIs manage the named saved system or device number that CPautomatically loads (IPLs) when a virtual image is activated.

Image_IPL_Delete_DMDelete the IPL statement from a virtual image’s directory entry or a profiledirectory entry.

Image_IPL_Query_DMQuery the information about the operating system, or device containingthe operating system, that is specified on the IPL statement in a virtualimage’s directory entry or a profile directory entry.

Image_IPL_Set_DMAdd an IPL statement to a virtual image’s directory entry or a profiledirectory entry.

Image OperationsThese are operational APIs that can be requested for virtual images.

Image_ActivateActivate a virtual image or list of virtual images.

Image_Active_Configuration_QueryObtain current configuration information for an active virtual image.

Image_DeactivateStop a virtual image or list of virtual images.

Image_PausePause a running virtual image or restart a paused virtual image.


||

Image_Query_Activate_TimeObtain the date and time when a virtual image was activated.

Image_RecycleDeactivate and then reactivate a virtual image or list of virtual images.

Image_Status_QueryDetermine whether virtual images are active (logged on or logged ondisconnected) or inactive.

System_Image_Performance_QueryObtain performance data for a virtual image.

Image Volume ManagementThese APIs manage DASD volumes.

Image_Volume_AddAdd a DASD volume to be used by virtual images to the z/VM systemconfiguration file.

Image_Volume_DeleteDelete a DASD volume definition from the z/VM system configurationfile.

Image_Volume_ShareIndicate a full-pack minidisk is to be shared by the users of many real andvirtual systems.

Image_Volume_Space_Define_DMDefine space on a DASD volume to be allocated by the directory managerfor use by virtual images.

Image_Volume_Space_Define_Extended_DMDefine space on a DASD volume to be allocated by the directory managerfor use by virtual images (extended version ofImage_Volume_Space_Define_DM).

Image_Volume_Space_Query_DMQuery how space on a DASD volume is allocated by the directorymanager.

Image_Volume_Space_Query_Extended_DMQuery how space on a DASD volume is allocated by the directory manager(extended version of Image_Volume_Space_Query_DM).

Image_Volume_Space_Remove_DMRemove the directory manager’s space allocations from a DASD volume.

List-Directed IPLThese APIs create, update, and query the LOADDEV directory statement for avirtual image.

Image_SCSI_Characteristics_Define_DMDefine or change the location of a program to be loaded as a result of anFCP list-directed IPL, and the data to be passed to the loaded program, ina virtual image’s directory entry.


||

Image_SCSI_Characteristics_Query_DMObtain the location of a program to be loaded as a result of an FCPlist-directed IPL, and the data to be passed to the loaded program, from avirtual image’s directory entry.

Name ListThese APIs help manage lists of names in the systems management server namelist file. Names in lists may include virtual images or functions.

Name_List_AddAdd a name to a list in the name list file. If the list that is specified intarget_identifier does not exist, a new list will be created.

Name_List_DestroyDelete a list from the name list file.

Name_List_QueryQuery the names that are in a list in the name list file.

Name_List_RemoveDelete a name from a list in the name list file. If there are no namesremaining in the list, the list is also deleted.

Network Interface ConfigurationThese APIs manage the network interface configuration for the z/VM TCP/IPstack.

Network_IP_Interface_CreateCreate the initial network interface configuration for the z/VM TCP/IPstack.

Network_IP_Interface_ModifyChange the configuration of the existing network interface.

Network_IP_Interface_QueryObtain interface configurations for a specified TCP/IP stack virtualmachine.

Network_IP_Interface_RemoveRemove the existing network interface.

Profile ManagementThese APIs manage profile directory entries.

Profile_Create_DMCreate a profile directory entry to be included in the definition of a virtualimage in the directory.

Profile_Delete_DMDelete a profile directory entry.

Profile_Lock_DMLock a profile directory entry so that it cannot be changed.

Profile_Lock_Query_DMQuery the status of directory manager locks in effect for a specific profile.

Profile_Query_DMQuery a profile directory entry.


Profile_Replace_DMReplace the definition of a profile to be included in a virtual image in thedirectory.

Profile_Unlock_DMUnlock a profile directory entry so it can be changed.

Prototype ManagementThese APIs manage virtual image prototype definitions, which the directorymanager uses to create new images.

Prototype_Create_DMCreate a new virtual image prototype.

Prototype_Delete_DMDelete an image prototype.

Prototype_Name_Query_DMObtain a list of names of defined prototypes.

Prototype_Query_DMQuery the characteristics of an image prototype.

Prototype_Replace_DMReplace an existing prototype.

Response RecoveryThis API performs response recovery.

Response_RecoveryObtain response data from previous calls that may have failed.

Server ManagementThese APIs validate a userid/password pair, query the support level of the APIserver and functions, and capture data to assist with identification and resolutionof a problem with the SMAPI servers.

Check_AuthenticationValidate a userid/password pair.

Query_API_Functional_LevelObtain the support level of the server and functions.

SMAPI_Status_CaptureCapture data to assist with identification and resolution of a problem withthe SMAPI servers. (Note that you can use the stand-alone SMSTATUSEXEC to perform this same function when SMAPI_Status_Capture cannotbe executed because SMAPI is not responsive.)

Shared Memory ManagementThese APIs manage shared memory on your virtual images through z/VM'sshared physical segment functions.

Shared_Memory_Access_Add_DMAdd restricted (RSTD) access to a shared memory segment.

Shared_Memory_Access_Query_DMQuery the restricted (RSTD) access to a shared memory segment.


Shared_Memory_Access_Remove_DMRemove restricted (RSTD) access from a shared memory segment.

Shared_Memory_CreateCreate a memory segment that can be shared among virtual images.

Shared_Memory_DeleteDelete a shared memory segment.

Shared_Memory_QueryQuery information about system data files that are contained in the savedmemory segment.

Shared_Memory_ReplaceReplace a shared memory segment previously defined byShared_Memory_Create.

Single System Image (SSI) Cluster ManagementThese APIs manage relocations of virtual machines within a z/VM SSI cluster.

SSI_QueryObtain SSI and system status.

VMRELOCATERelocate, test