Managing CMOS Processors › Hardware Access Facility (HAF) › HAF Message Format

HAF Message Format

The messages sent from the HMCs through the API are in MIB format; that is, they consist mostly of sectioned numbers (for example, 1.2.3.4.5…) called object IDs or OIDs.

Wherever possible, these object IDs are translated into the English text that they represent (for example, the name of an LPAR or command).

Whether the HAF translates the object IDs or not, it does not reorder the pieces of information provided by the API.

Note: A multi-line message is an exception.

Because the HAF does not reorder pieces of information in messages, you can use the IBM API documentation to determine what data displays in the message and the order in which it displays. For example, if the HMC Access Facility receives a message containing 1.9243.7 (new status), 121.3.459.87.33874295.0 (the fictional LPAR ID for MVS001), and 11.259.44.783.91 (the event), it translates this to "Powered Off MVS001 Status Change." You might thing that rearranging the elements of the message so that it says "MVS001 Status change: Powered Off" would make the message easier to understand, but such re-ordering of data chunks would make it impossible to use the manufacturer's documentation to determine what the format of each message should be.

HAF message have the following format:

HAFImmnny name type event keyword1 = value1 keyword2 = value2 …hmc_name MMM NNN

mm

Specifies a number that indicates the type of message. To determine an mm value for a given event type, see the section Determining HAF Message Numbers later in this chapter. This number corresponds to the event portion of the message.

Note: Each time you change the code level of your HMC, look at the messages that it generates to ensure that the mm section of the message numbers has not changed for any of the messages that you are automating.

nn

Specifies a number that indicates the version of the message. Each time IBM changes the format of a particular message type, this number changes as well. This allows you to write an appropriate rule for the new data layout.

Note: Each time you change the code level of your HMC, look at the messages that it generates to ensure that the nn section of the message numbers has not changed for any of the messages that you are automating.

y

When a single HMC message is split up into multiple HAF messages, this single letter indicates which portion of the split HMC message this HAF message belongs to. (For more information about split messages, see the following descriptions of MMM and NNN.) Values are:

S (Single)

Indicates that HAF was able to present this HMC message as a single HAF message.

F (First)

Indicates that this HAF message is the first line of a split HMC message.

L (Last)

Indicates that this HAF message is the last line of a split HMC message.

M (Middle)

Indicates that this line is between the first and last lines of a split message.

name

Specifies the name of the HMC, SE, PEP, CPC, or LPAR that this message is about. In rare cases, the HAF cannot determine the name of the object from the object ID that displays in the raw message. If this is the case, the object IDs are shown.

type

Specifies the type of object (CPC_IMAGE_GROUP, CPC_Image, and so on) that this message is for.

event

Specifies the type of event that this message describes (STATUS_CHANGE, OBJECT_CREATED, and so on).

keywordN = valueN

Specifies a keyword/value pair that is part of a series that makes up the HMC message. The keyword portion is a MIB that describes what kind of data the value portion of the pair represents. The value portion contains the actual data that the pair is meant to convey. For example, two pairs could have a value portion of 2, but the first pair could have the MIB for RETURN_CODE as the keyword portion, and the second pair could have the MIB for MACHINE_STATUS as the keyword portion.

Each keyword/value pair in the HMC message is presented in the form keyword = value:

keyword

Specifies the ASCII text name for the type of object ID

value

Specifies the numeric value or the name of the specific instance of the type of object ID

Examples

• Suppose that in the IBM keyword/value pair, 1.3.6.1.4.1.2.6.42.0 and 1.3.6.1.4.1.2.6.42.0.3329843724 are the object ID for a CONSOLE_ID and the object ID for console MVS45C01, respectively. This object ID type/value pair would be displayed in the CA Automation Point message as CONSOLE_ID = MVS45C01.
• Suppose that in the IBM keyword/value pair, 1.3.6.1.4.1.2.6.42.0.20.0 and 1234567890 are the object ID for a CPC_SERIAL and the numeric value of the CPC serial number. This pair would be displayed as CPC_SERIAL = 1234567890.

Notes:

• Spaces are present on either side of the equal sign (=) in the keywordN = valueN pairs. This allows you to more easily use the word functions to parse the object names out of the message when you are using CA Automation Point rules.
• A hexadecimal value that has been translated to a name is also translated into a decimal number and included in parentheses after the name. For example, the condition code X'14' is presented as COMMAND_CONDITION_CODE = REQUEST_RECV_ERROR (20), rather than COMMAND_CONDITION_CODE = REQUEST_RECV_ERROR.
• Within a single code level of a manufacturer's API for a given event type, the position and number of keywordN = valueN pairs will not change. However, although highly unlikely, the manufacturer may change the order of pairs or add or remove pairs when it changes the code level of the HMC. See the previous description of the nn portion of the message number for details.

hmc_name

The name of the HMC that generated this message. Use this along with MMM and NNN to relate the pieces of an HMC message to one another in the rules that you write.

MMM

A six-digit number, called the message number, that is incremented each time a message is received by HAF from an HMC. Each HMC has its own counter; that is, you will see message number 000001, message number 000002, and so on from each HMC. This value is useful in cases when HMC messages have been split into multiple HAF messages. You can use it to relate the pieces of a message to one another in the rules that you write. (See the NNN description for more information on split messages.)

NNN

A six digit number that starts with a value of 000001 for each new HMC message. This number is incremented for each new message that HAF creates when presenting the HMC message. As with MMM, you can use NNN to relate the pieces of an HMC message to one another in rules. HMC messages are split for one of two reasons; either the HMC message itself contains formatting characters that request that the HMC message be split into multiple HAF messages, or the HMC message contains more data than can be passed into rules in a single HAF message. Each HAF message in a multi-line HMC message has the same message ID (HAFxmmnn) and the same message number (MMM), but NNN will be incremented by one for each HAF message that is generated from the HMC message.

Notes:

• NNN (with a value of 1) is placed on the end of the first message for a raw message even if the data from the raw message requires only one message; that is, the data will not be split into multiple messages.
• As described previously, the keywordN/valueN pairs of a message are only reordered in special circumstances. Some messages, such as hardware event messages, contain preformatted multi-line text as part of their data. When a message contains such known multi-line components, those keyword/value pairs are moved to the end of the data. This makes it easier to write rules against the message because NNN will vary for any piece of data that comes after any multi-line component of a message.
• ASCII text for a keywordN or valueN never splits across lines unless it contains formatting characters or is so long that a single value exceeds the maximum size of the rules buffer.
• In rare instances, a long message may split in a different place each time the message is passed through rules. If this happens, contact CA Technical Support.

As with z/OS or other operating system messages, you must study the format of the HAF messages that are received by CA Automation Point and write rules accordingly. The IBM HMC API manuals contain detailed information about the content of each of the HMC messages that HAF translates and presents.