List OS Messages of a Logical Partition

The List OS Messages of a Logical Partition operation lists all currently available operating system (OS) messages for a logical partition. This operation is supported using the BCPii interface.

HTTP method and URI

GET /api/logical-partitions/{logical-partition-id}/operations/list-os-messages

In this request, the URI variable {logical-partition-id} is the object ID of the target logical partition.

Query parameters:

Name Type Rqd/ Opt Description
begin-sequence-number Long Optional A message sequence number to limit returned messages. OS messages with a sequence number less than this are omitted from the results. If not specified, then no such filtering is performed.
end-sequence-number Long Optional A message sequence number to limit returned messages. OS messages with a sequence number greater than this are omitted from the results. If not specified, then no such filtering is performed.
is-held Boolean Optional A Boolean value used to limit the returned messages to held or non-held messages. A value of true will result in only held messages being returned, while a value of false will result in only non-held messages being returned.
is-priority Boolean Optional A Boolean value used to limit the returned messages to priority or non-priority messages. A value of true will result in only priority messages being returned, while a value of false will result in only non-priority messages being returned.
max-messages Integer Optional An integer value greater than zero that indicates the maximum number of messages to be returned. If specified, this query parameter can only be specified once. Use of this query parameter allows for the data returned to be limited. Using the sequence-number of the last message returned as the begin-sequence-number value on a subsequent invocation of this operation can get the next set of messages.
Note: For operations using the BCPii interface this query parameter is required and cannot be a value greater than 100.

Response body contents

On successful completion, the response body is a JSON object with the following fields:

Field name Type Description
os-messages Array of os-message-info objects Array of nested os-message-info objects as described in the next table. The array elements are in order of increasing sequence number, unless that number has wrapped back around to 0 in which case the element with sequence number 0 follows the element with the highest sequence number, thus maintaining the temporal order of the messages.

Each nested os-message-info object contains the following fields:

Field name Type Description
sequence-number Long The sequence number assigned to this operating system message by the HMC. Although sequence numbers may wrap over time, this number can be considered a unique identifier for the message. It can be used for filtering purposes.
message-text String The text of the operating system message.
message-id Long The message identifier of the operating system message.
timestamp Timestamp The time when the operating system message was created or -1 if this information is not available from the corresponding operating system.
sound-alarm Boolean Specifies whether the operating system message should cause the alarm to be sounded (true) or not (false).
is-priority Boolean Specifies whether the operating system message is a priority message (true) or not (false). A priority message indicates a critical condition that requires immediate attention.
is-held Boolean Specifies whether the operating system message is a held message (true) or not (false). A held message is one that requires a response.
prompt-text String Specifies the prompt text that is associated with this operating system message or null indicating that there is no prompt text for this operating system message. The prompt text is used when responding to a message. The response is to be sent as an operating system command where the command is prefixed with the prompt text and followed by the response to the message.
os-name String Specifies the name of the operating system that generated this operating system message or null indicating there is no operating system name associated with this operating system message. This name is determined by the operating system itself and may be unrelated to the name of the logical partition in which the operating system is running.

Description

This operation lists the currently available messages from the operating system running in the specified logical partition. Only a certain amount of OS message data from each logical partition is preserved for retrieval by this operation. If the OS produces more than that amount, the oldest non-held, non-priority OS messages are no longer available. A gap in the sequence numbers indicates a loss of messages. A loss may be due to that space limitation, or it may be due to the deletion of messages by a console user or the OS.

If the request URI does not identify a Logical Partition object to which the API user has access permission, HTTP status code 404 (Not Found) is returned. For the web services interface, in addition to having object-access permission to the logical partition, the API user must also have permission to the Operating System Messages task or the Operating System Messages task in view-only mode, otherwise status code 403 (Forbidden) is returned. Status code 409 (Conflict) is returned when the message interface for the operating system running in the target logical partition is not available. Some examples are when the logical partition is not active, there is no operating system running in the logical partition, or when the operating system is not enabled for console integration.

If the begin-sequence-number query parameter is specified, then any OS messages with a sequence-number less than that are omitted from the response. If the end-sequence-number query parameter is specified, then any OS messages with a sequence-number greater than that are omitted from the response. If the is-held query parameter is specified as true, then non-held messages are omitted. If the is-held query parameter is specified as false, then held messages are omitted. If the is-priority query parameter is specified as true, then non-priority messages are omitted. If the is-priority query parameter is specified as false, then priority messages are omitted. If the max-messages query parameter is specified, then the number of returned messages will not exceed this value.

If there are no available OS messages for the specified logical partition or if no OS messages are to be included in the response due to filtering, an empty list is provided and the operation completes successfully.

Authorization requirements

This operation has the following authorization requirements:
  • For the web services interface:
    • Object-access permission to the Logical Partition object designated by {logical-partition-id}
    • Action/task permission for the Operating System Messages task, or the Operating System Messages task in view-only mode.
  • For the BCPii interface the source partition must have receive BCPii security controls permissions for the Logical Partition object designated by {logical-partition-id}.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in Response body contents.

The following HTTP status codes are returned for the indicated errors. The response body is a standard error response body providing the reason code indicated and associated error message.

HTTP error status code Reason code Description
400 (Bad Request) Various Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes.
403 (Forbidden) 0 The request used the BCPii interface and the source partition does not have receive BCPii security controls permission for the Logical Partition object.
1 The user under which the API request was authenticated does not have the required authority to perform this operation.
404 (Not Found) 1 The request URI does not designate an existing resource of the expected type, or designates a resource for which the API user does not have object-access permission.
409 (Conflict) 332 The messages interface is not available.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Example HTTP interaction

Figure 1. List OS Messages of a Logical Partition: Request
GET /api/logical-partitions/d39347d9-855a-3199-9ef6-a1701b7b17b4/operations/
   list-os-messages HTTP/1.1
x-api-session: 2cckypxdonb44w6n8dvyly3vpw9hekwr2soasrhax41oetlbni
Figure 2. List OS Messages of a Logical Partition: Response
200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 28 Aug 2017 19:59:00 GMT
content-type: application/json;charset=UTF-8
content-length: 665
{
   "os-messages":[
      {
         "is-held":true,
         "is-priority":false,
         "message-id":69166,
         "message-text":"*IOS002A AB4D,NO PATHS AVAILABLE\n",
         "os-name":"S50     ",
         "prompt-text":"",
         "sequence-number":10541,
         "sound-alarm":false,
         "timestamp":1503926847000
      },
      {
         "is-held":true,
         "is-priority":false,
         "message-id":69167,
         "message-text":"*IOS002A AB11,NO PATHS AVAILABLE\n",
         "os-name":"S50     ",
         "prompt-text":"",
         "sequence-number":10542,
         "sound-alarm":false,
         "timestamp":1503926847000
      },
      {
         "is-held":true,
         "is-priority":false,
         "message-id":69169,
         "message-text":"*IOS002A AB42,NO PATHS AVAILABLE\n",
         "os-name":"S50     ",
         "prompt-text":"",
         "sequence-number":10543,
         "sound-alarm":false,
         "timestamp":1503926847000
      }
   ]
}