Open OS Message Channel
The Open OS Message Channel operation opens a message channel to the operating system running in a logical partition for a client of the JMS notification facility (see the "JMS basics" section of Chapter 4 for more information). SSE clients should refer to the Server-Sent Events Stream operations in Chapter 7 for asynchronous OS message support.
HTTP method and URI
POST /api/logical-partitions/{logical-partition-id}/operations/open-os-message-channel
In this request, the URI variable {logical-partition-id} is the object ID of the target Logical Partition object.
Request body contents
An optional request body can be specified as a JSON object with the following field:
Field name | Type | Rqd/Opt | Description |
---|---|---|---|
include-refresh-messages | Boolean | Optional | An indication of whether refresh operating system messages should be sent. Set to true to receive refresh messages, or false to prevent refresh messages. The default is true. |
Response body contents
On successful completion, the response body contains a JSON object with the following field:
Field name | Type | Description |
---|---|---|
topic-name | String (1-128) | The name of the os-message-notification topic. |
Description
This operation opens a message channel to the operating system running in the Logical Partition targeted by the request URI. The message channel is implemented as a JMS topic, specifically as an os-message-notification topic. See Asynchronous notification for information on JMS usage on the HMC. The API user can connect to this topic to start the flow of new (and refreshed) operating system messages.
The URI path must designate an existing Logical Partition object and the API user must have object-access permission to it. If either of these conditions is not met, status code 404 (Not Found) is returned. 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 partition, or when the operating system is not enabled for console integration.
If an os-message-notification topic already exists for this logical partition for the current API session, the operation fails.
On successful execution, the message channel is opened and the os-message-notification topic name is returned in the response body.
Authorization requirements
- 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.
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, and 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) | 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 object ID in the URI ({logical-partition-id}) does not designate an existing Logical Partition object, or the API user does not have object-access permission to the object. |
409 (Conflict) | 331 | An os-message-notification topic already exists for this logical partition for the current API session. Use the Get Notification Topics operation to determine the topic name. |
332 | The messages interface is not available. |
Additional standard status and reason codes can be returned, as described in Invoking API operations.