Writing XML for use with the IBM Z tempoary capacity SNMP APIs

The IBM Z SNMP Application Programming Interfaces (SB10-7179) document describes the various APIs that may be used on IBM Z hardware. Two of these commands are of particular concern for users of temporary capacity records. The commands are:

• HWMCA_ADD_CAPACITY_COMMAND - used to activate and add additional capacity to temporary capacity records. This is equivalent to the "Add processors" selection on the Perform Model Conversion task
• HWMCA_REMOVE_CAPACITY_COMMAND - used to remove capacity from, and deactivate temporary capacity records. This is equivalent to the "Remove processors" selection on the Perform Model Conversion task

Both of these commands require the passing of XML strings as part of the command. This document will describe the layout of the XML, and the proper way to use them, with examples.

The HWMCA_ADD_CAPACITY_COMMAND, takes an XML string as follows:

<add> 
     <recordid>M0021740</recordid>
     <softwaremodel>717</softwaremodel>
     <processorinfo>
          <type>ICF</type> 
          <procstep>3</procstep> 
     </processorinfo>
     <priority>false</priority> 
     <test>true</test> 
</add> 

The HWMCA_REMOVE_CAPACITY_COMMAND takes an XML string as follow

<remove> 
     <recordid>M0021740</recordid>
     <softwaremodel>717</softwaremodel>
     <processorinfo>
          <type>ICF</type> 
          <procstep>3</procstep> 
     </processorinfo>
</remove> 

The following table describes each of the possible XML fields:

Any addition of processors must be done with the HWMCA_ADD_CAPACITY_COMMAND. Removal of processors can only be done with the HWMCA_REMOVE_CAPACITY_COMMAND. The two actions cannot be combined. So if the goal is to convert two active temporary IFLs to ICFs, then first the HWMCA_REMOVE_CAPACITY_COMMAND should be used to remove the two IFLs, and then the HWMCA_ADD_CAPACITY_COMMAND should be used to add the two ICFs.

Examples

The examples below are done with the following machine configuration:

• CP software model = 520
• ICF 20
• IFL 20
• zIIP 20

There are 3 temporary records.

System Recovery Boost upgrade record M0039393 limits:

• 20 zIIP engines

CBU record M0021740 limits:

• 20 CP features
• 10 IFL engines
• 10 zIIP engines
• 10 ICF engines

On/Off CoD record CRABCDEF limits:

• 100% CP capacity
• 20 IFL engines
• 20 zIIP engines
• 20 ICF engines

Example 1: SRB Upgrade activation and deactivation

The following XML will activate an SRB Upgrade record when passed via the HWMCA_ADD_CAPACITY_COMMAND:

<add>
    <recordid>M0039393</recordid>
    <softwaremodel>520</softwaremodel>
    <processorinfo>
        <type>IIP</type> 
        <procstep>20</procstep>
    </processorinfo>
    <test>false</test> 
</add>

After activation, the total number of zIIPs active is now 40.

To deactivate the SRB Upgrade record, you must remove all active zIIP engines. The following XML should be passed to the HWMCA_REMOVE_CAPACITY_COMMAND:

<remove>
    <recordid>M0039393</recordid>
    <softwaremodel>520</softwaremodel>
    <processorinfo>
        <type>IIP</type> 
        <procstep>20</procstep>
    </processorinfo>
</remove>

After the remove, the record is no longer active, and the zIIP count returns to 20.

Example 2: CBU activation and deactivation

The following XML will activate the entire CBU record for M0021740 when passed to the HWMCA_ADD_CAPACITY_COMMAND. Activation is as a CBU test.

<add>
    <recordid>M0021740</recordid>
    <softwaremodel>720</softwaremodel>
    <processorinfo>
        <type>ICF</type> 
        <procstep>10</procstep>
    </processorinfo>
    <processorinfo>
        <type>IIP</type> 
        <procstep>10</procstep>
    </processorinfo>
    <processorinfo>
        <type>IFL</type> 
        <procstep>10</procstep>
    </processorinfo>
    <priority>false</priorityt> 
    <test>true</test> 
</add>

After activation, the machine configuration is:

• CP software model = 720
• ICF 30
• IFL 30
• zIIP 30

To deactivate the CBU record, you must remove all active engines. To do that, you will:

• Specify the original SW model of 520
• For each active engine type, specify the number of engines of that type to deactivate, in this case 10. This engine count, is a positive number.

Use the XML below in the HWMCA_REMOVE_CAPACITY_COMMAND

<remove>
    <recordid>M0021740</recordid>
    <softwaremodel>520</softwaremodel>
    <processorinfo>
        <type>ICF</type> 
        <procstep>10</procstep>
    </processorinfo>
    <processorinfo>
        <type>IIP</type> 
        <procstep>10</procstep>
    </processorinfo>
    <processorinfo>
        <type>IFL</type> 
        <procstep>10</procstep>
    </processorinfo>
</remove>

After the remove, the CBU record is no longer active, and the engine counts return to the base level

Note: Removal of all resources from a CBU record ends the test or real activation.

Example 3: On/Off CoD activation and deactivation

We will activate the record by increasing the capacity level from 520 to 620. This is done with the HWMCA_ADD_CAPACITY_COMMAND. As we are only changing the CP capacity, we only need to specify the software model. No processor info entries are required.

<add>
    <recordid>CRABCDEF</recordid>
    <softwaremodel>620</softwaremodel>
    <test>false</test> 
</add>

The CP capacity is now 620.

With the current capacity of 620, to change the capacity to 522, the HWMCA_ADD_CAPACITY_COMMAND must be used. We are adding additional CP engines, even though the overall capacity, as measured in MSUs, will decrease

<add>
    <recordid>CRABCDEF</recordid>
    <softwaremodel>522</softwaremodel>
    <test>false</test> 
</add>

The CP capacity is now 522.

From the 522 capacity level, to return to the 620 capacity level, the HWMCA_REMOVE_CAPACITY_COMMAND must be used, as this is removing active CP engines

<remove>
    <recordid>CRABCDEF</recordid>
    <softwaremodel>620</softwaremodel>
</remove>

To fully deactivate the On/Off CoD record, specify the original base capacity level for all engine types with the HWMCA_REMOVE_CAPACITY_COMMAND.

<remove>
    <recordid>CRABCDEF</recordid>
    <softwaremodel>520</softwaremodel>
</remove>

The CP capacity level is now 520, and the On/Off CoD record is no longer active.

Legacy SNMP APIs

Prior to the introduction of the HWMCA_ADD_CAPACITY_COMMAND and the HWMCA_REMOVE_CAPACITY_COMMAND, there were specific commands for the activation of CBU and On/Off CoD record types. With the introduction of the HWCMA_ADD_CAPACITY_COMMAND and the HWMCA_REMOVE_CAPACITY_COMMAND these commands are no longer required, but have been left to support command scripts written for prior systems. These legacy commands have a number of limitations:

• You cannot specify a record ID. For CBU, the CBU record targeted must be the defined as the default record
• The command activates the entire record, for all engine types. Partial activations are not supported.
• The UNDO command deactivates the entire record. Partial deactivation of a record is not supported.
• You cannot use these commands on CPE, SRB Upgrade, or LOANER records.

The recommendation is to use the HWMCA_ADD_CAPACITY_COMMAND and HWMCA_REMOVE_CAPACITY_COMMAND versus the legacy commands. The legacy commands are included here for completeness. For more details on these commands, see the SNMP API guide.

HWMCA_ACTIVATE_CBU_COMMAND: activates the default CBU record on the machine. The entire record is activated. Takes as a paramter HWMCA_TRUE to activate the real CBU activation, or HWMCA_FALSE to activate as a CBU test. Activations are always a "force" activate. The password parameter is no longer required.

HWMCA_UNDO_CBU_COMMAND: deactivates the default CBU record on the machine. The entire record is deactivated. The command takes no arguments.

HWMCA_ACTIVATE_OOCOD_COMMAND: activates the entire On/Off CoD record to the maximum specified for all engine types.

HWMCA_UNDO_OOCOD_COMMAND: deactivates the active On/Off CoD record

BCPii equivalent commands

The z/OS Base Control Program internal interface (BCPii) provides a z/OS interface to the SNMP commands. When using BCPii, the HWI_CMD_TEMPCAP is used to call both the HWMCA_ADD_CAPACITY_COMMAND and the HWMCA_REMOVE_CAPACITY_COMMAND. Which command is called is based on the TEMPCAPType parameter; a 1 is used to add capacity, and a 2 is used to remove capacity. The XML strings passed to the TEMPCAP command are as shown above.

For more details, see the Base Control Program internal interface (BCPii) HWICMD documentation in the IBM Knowledge Center.