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

This operation has the following 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.

Table 1. Open OS Message Channel: HTTP status and reason codes
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.

Example HTTP interaction

Figure 1. Open OS Message Channel: Request
POST /api/logical-partitions/c7eb8134-826e-3a71-8d1a-00d706c874e9/operations/
   open-os-message-channel HTTP/1.1
x-api-session: 2ltfe2c2q3ti2b2pwq1wfwuzifoi4qymqa8ktzjep7dbyrll0k
content-type: application/json
content-length: 37
{ “include-refresh-messages”: true }
Figure 2. Open OS Message Channel: Response
200 OK
server: zSeries management console API web server / 1.0
cache-control: no-cache
date: Sat, 14 Sept 2013 18:03:00 GMT
content-type: application/json;charset=UTF-8
{ “topic-name”: “mikeuser.1osmsg.cpc1.lpar1” }