ERserver zSeries Application Programming Interfaces SB10-7030-06 Level 06a, November 2004 ER s er ver zSeries Application Programming Interfaces SB10-7030-06 Level 06a, November 2004 Level 06a, November 2004 Note! Before using this information and the product it supports, be sure to read the general information under Appendix F, “Notices,” on page F-1. Seventh Edition (October 2004) ™ ® | This edition, SB10-7030-06, applies to zSeries Processors and S/390 Processors. | This edition replaces SB10-7030-05 and -05a. A technical change to the text or illustration is indicated by a vertical line to the left of the change. ™ There may be a newer version of this document in PDF format available on Resource Link . Go to http://www.ibm.com/servers/resourcelink and click on Library on the Navigation bar. A newer version is indicated by a lower-case, alphabetic letter following the form number suffix (for example: 00a, 00b, 01a, 01b). © Copyright International Business Machines Corporation 2000, 2004. All rights reserved. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Level 06a, November 2004 Contents Safety and Environmental Notices . vii Laser Safety Information . vii Laser Compliance . vii Environmental Notices . vii Product Recycling and Disposal . vii Refrigeration . vii Battery Return Program . vii IBM Cryptographic Adapter Card Return Program . viii Cable Warning . viii Preface . .ix Message Event Notification . .x Load Command Support . .x Hardware Message Refresh Command Support . .x Hardware Message Event Data . .x Activation Profile Support . .x Hardware Message Delete Command Support . .x Reset Clear Command Support . .xi || Security Log Event Support . .xi Processing Weight Support . .xi Activate CBU Command Support . .xi Import/Export Profiles Support . .xi External Interrupt Command Support . .xi Reserve Command Support . .xi Alert Event Support . xii Object Name Added to Event Data . xii Degrade Indicator Enhancements . xii Partition Identifier . xii SCSI Load/Dump Support . xii Event Qualification . xii How to Send your Comments . xii Chapter 1. APIs Objectives . 1-1 Chapter 2. Overview . 2-1 Chapter 3. Console Application APIs . 3-1 Management APIs . 3-1 Data Exchange APIs . 3-1 Commands API . 3-17 Data Exchange APIs and Commands API Structures and Definitions . 3-36 Constant Definitions . 3-36 Data Exchange APIs SNMP Target Structure (HWMCA_SNMP_TARGET_T) 3-43 Data Exchange APIs Initialize Structure (HWMCA_INITIALIZE_T) . 3-44 Data Exchange APIs Datatype Structure (HWMCA_DATATYPE_T) . 3-45 Function Prototypes . 3-46 Data Exchange APIs and Commands API Example . 3-48 Chapter 4. Console Application Managed Objects . 4-1 Console Application Object Identifier Conventions . 4-1 prefix . 4-1 attribute . 4-2 group . 4-2 © Copyright IBM Corp. 2000, 2004 iii Level 06a, November 2004 object . 4-2 Console Application Object . 4-3 Console Application Name Bindings . 4-3 Console Attributes . 4-3 Console Application Commands . 4-3 Console Application Notifications . 4-3 Group . 4-5 Group Name Bindings . 4-5 Group Attributes . 4-5 Group Commands . 4-6 Group Notifications . 4-6 Defined CPC . 4-7 Defined CPC Name Bindings . 4-7 Defined CPC Attributes . 4-7 Defined CPC Relationships . 4-12 Defined CPC Commands . 4-13 Defined CPC Notifications . 4-13 CPC Image . 4-14 CPC Image Name Bindings . 4-14 CPC Image Attributes . 4-15 CPC Image Relationships . 4-20 CPC Image Commands . 4-20 CPC Image Notifications . 4-21 Coupling Facility . 4-22 Coupling Facility Name Bindings . 4-22 Coupling Facility Attributes . 4-22 Coupling Facility Relationships . 4-26 Coupling Facility Commands . 4-26 Coupling Facility Notifications . 4-26 Reset Activation Profile Object . 4-28 Reset Activation Profile Name Bindings . 4-28 Reset Activation Profile Attributes . 4-28 Image Activation Profile Object . 4-28 Image Activation Profile Name Bindings . 4-28 Image Activation Profile Attributes . 4-28 Load Activation Profile Object . 4-32 Load Activation Profile Name Bindings . 4-32 Load Activation Profile Attributes . 4-32 Chapter 5. Rexx Management Functions . 5-1 ACTZSNMP . 5-1 Rexx Initialization Functions . 5-1 Data Exchange Functions . 5-1 Commands API . 5-16 Data Exchange APIs (Rexx Sample) . 5-30 Chapter 6. Configuring for the Data Exchange APIs . 6-1 Configuring for SNMP . 6-1 Configuring the Console for API . 6-3 Configuration Problems . 6-3 Appendix A. Building an Application . A-1 Appendix B. HWMCA_EVENT_COMMAND_RESPONSE Return Codes B-1 Appendix C. API Return Codes . C-1 iv zSeries: Application Programming Interfaces Level 06a, November 2004 Data Exchange API Call Return Codes . C-1 Command API Call Return Codes . C-4 HWMCA_EVENT_COMMAND_RESPONSE Return Codes . C-6 Data Exchange and Command API (Rexx Version) Return Codes . C-7 Appendix D. Alert Reference . D-1 Problem Analysis . D-1 How Problem Analysis Works . D-1 Alert Definitions . D-2 00E99C34 – Unsuccessful Call Report . D-2 0A7800EB – Channel Problem with a Device in ESA Mode . D-3 2CC61C39 – Power Problem . D-4 52742EDE – Remote Logon Attempts Exceeded . D-5 571EEC23 – Channel Problem in ESA Mode . D-6 5EFE0FDA – Serial Link Failure Detected . D-7 84D6CA01 – Storage Subsystem Failure . D-8 8AC7ED9E – Serial Node Failure Detected . D-9 8B77BE67 – High Error Rate Detected on Serial Link . D-10 935292FD – Processor Machine Check . D-11 9BD7CD6F – CPC Entered Hard Wait . D-12 A07484B8 – CPC Operations Management Threshold Exceeded . D-13 A65E0999 – Support Element Problem . D-14 AABEAE27 – Multiple Channel and Device Problems . D-15 AB1D2F40 – System Check Stop . D-16 B2E74D53 – Operating System Problem Detected . D-17 CBAE437E – IPL Failure in ESA Mode . D-18 D9D9CE57 – I/O Error in ESA Mode . D-19 DB5DBEF4 – Storage Problem . D-20 EFFA5171 – Sysplex Timer Problem Detected . D-21 F3937A7B – ESCON Director Problem Detected . D-22 Action Notes . D-23 Appendix E. APIs for Java (com.ibm.hwmca.api) . E-1 Appendix F. Notices . F-1 Trademarks . F-2 Glossary . G-1 Contents v Level 06a, November 2004 vi zSeries: Application Programming Interfaces Level 06a, November 2004 Safety and Environmental Notices Laser Safety Information All zSeries models can use I/O cards such as PCI adapters, ESCON, FICON, OSA-Express, InterSystem Coupling-3 (ISC-3), or other I/O features which are fiber optic based and utilize lasers or LEDs. Laser Compliance All lasers are certified in the U.S. to conform to the requirements of DHHS 21 CFR Subchapter J for class 1 laser products. Outside the U.S., they are certified to be in compliance with IEC 60825 as a class 1 laser product. Consult the label on each part for laser certification numbers and approval information. CAUTION: Data processing environments can contain equipment transmitting on system links with laser modules that operate at greater than Class 1 power levels. For this reason, never look into the end of an optical fiber cable or open receptacle. (C027) CAUTION: This product contains a Class 1M laser. Do not view directly with optical instruments. (C028) Environmental Notices Product Recycling and Disposal This unit contains materials such as circuit boards, cables, electromagnetic compatibility gaskets and connectors which may contain lead and copper/beryllium alloys that require special handling and disposal at end of life. Before this unit is disposed of, these materials must be removed and recycled or discarded according to applicable regulations. IBM offers product-return programs in several countries. Information on product recycling offerings can be found on IBM’s Internet site at http://www.ibm.com/ibm/environment/products/prp.shtml. IBM encourages owners of information technology (IT) equipment to responsibly recycle their equipment when it is no longer needed. IBM offers a variety of programs and services to assist equipment owners in recycling their IT products. Information on product recycle offerings can be found on IBM’s Internet site at http://www.ibm.com/ibm/environment/products/prp.shtml. Refrigeration These systems contain R-134A refrigerant under high pressure. This refrigerant must not be released or vented to the atmosphere. To avoid risk of personal injury or damage to the system, adding refrigerant or any repair of the refrigerant system must be done by an experienced technician. In some countries, technicians must be certified to specific government requirements. Battery Return Program This product may contain sealed lead acid, nickel cadmium, nickel metal hydride, lithium, or lithium ion battery(s). Consult your user manual or service manual for specific battery information. The battery must be recycled or disposed of properly. © Copyright IBM Corp. 2000, 2004 vii Level 06a, November 2004 Recycling facilities may not be available in your area. For.