Update Tape Link Environment Report

The Update Tape Link Environment Report operation triggers asynchronous storage discovery for a tape link. The system will check the configuration for the tape link and create an environment report indicating the status of the configuration. Because the system periodically performs storage discovery for tape link and creates an environment configuration report for those tape links, it is not necessary to use this operation; however, issuing this operation may cause the discovery to be performed sooner than it would have otherwise.

HTTP method and URI

POST /api/tape-links/{tape-link-id}/operations/update-tape-link-environment-report

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

Request body contents

An optional request body can be specified as a JSON object with the following fields:

Table 1.
Field name Type Rqd/Opt Description
force-restart Boolean Optional Indicates if there is an in-progress discovery operation for the specified tape link, it should be terminated and started again. If false and there is an in-progress discovery operation for the specified tape link, no new discovery is started.

Default value: false

Response body contents

Once the request is accepted, the response body contains a JSON object with the following fields:

Field name Type Description
job-uri String/ URI URI that may be queried to retrieve status updates.

Asynchronous result description

Once the operation has completed, a job-completion notification is sent, and results are available for the asynchronous portion of this operation. These results are retrieved using the Query Job Status operation directed at the job URI provided in the response body.

The result document returned by the Query Job Status operation is specified in the description for the Query Job Status operation. When the status of the job is "complete", the results include a job completion status code and reason code (fields job-status-code and job-reason-code) which are set as indicated in Table 3. The job-results field is null when this operation is successful. When it is not successful, the job-results field contains an object with the following field:
Field name Type Description
message String The message text describing the detailed error that occurred when the operation was not successful.

Description

This operation triggers detection of the tape drives (logical units or LUNs) for the WWPNs that are assigned to this tape link. Once the LUN discovery operation is completed, a report is generated for the tape link, indicating the status of the environment configuration. The Get Tape Link Environment Report operation can be used to retrieve it. The API user must have action/task permission to the Configure Storage - System Programmer task or the Configure Storage - Storage Administrator task; otherwise, status code 403 (Forbidden) is returned. A 404 (Not Found) status code is returned if the object ID {tape-link-id} does not identify a Tape Link object to which the API user has object-access permission.

Authorization requirements

This operation has the following authorization requirements:
  • Object-access permission to the tape link whose object-id is {tape-link-id}.
  • Action/task permission to the Configure Storage – System Programmer or the Configure Storage - Storage Administrator task.

HTTP status and reason codes

On success, HTTP status code 202 (Accepted) 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 the associated error message.

Table 2. Update Tape Link Environment Report: 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 API user does not have action/task permission to the Configure Storage – System Programmer or Configure Storage - Storage Administrator tasks.
404 (Not Found) 1 A tape link with the object-id {tape-link-id} does not exist on the HMC or the API user does not have object-access permission for it.
409 (Conflict) 1

The state of the CPC to which the tape link is associated is not valid to perform the operations. It must be one of the following states: "active", "service-required", "degraded", or "exceptions".

503 (Service Unavailable) 1 The request could not be processed because the HMC is not currently communicating with the SE needed to perform the requested operation.

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

Job status and reason codes

Table 3. Update Tape Link Environment Report: Job status and reason codes
HTTP error status code Reason code Description
200 (OK) N/A The operation completed successfully.
404 (Not Found) 1 A tape link with the object-id {tape-link-id} does not exist on the HMC or the API user does not have object-access permission for it.
500 (Server Error) 263 The update tape link environment report operation failed and there will be no automatic retry.

Example HTTP interaction

Figure 1. Update Tape Link Environment Report: Request
POST /api/tape-links/ed5f229c-5700-11eb-b4b6-00106f0d81c9/operations/
  update-tape-link-environment-report HTTP/1.1
x-api-session: 2ing9v6hkdfb6sytlg7jq510iawu064iafiaymo5jlvlmbjhv1 content-type: application/json
Figure 2. Update Tape Link Environment Report: Response (Part 1)
202 Accepted
server: Hardware management console API web server / 2.0
location: /api/jobs/0f5cb98a-5716-11eb-8353-00106f23d08c
cache-control: no-cache
date: Fri, 15 Jan 2021 09:43:02 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
   "job-uri":"/api/jobs/0f5cb98a-5716-11eb-8353-00106f23d08c"
}

Usage notes

  • At any point in time, there will be at most one in-progress discovery operation checking configuration for a given tape link. While a discovery operation is in progress, any new request for the same tape link from the APIs or the Graphical User Interface will be linked to that in-progress discovery operation. An in-progress discovery operation can be interrupted for various reasons, such as starting a partition to which this tape link is attached, modifying adapters of the virtual resources of the tape link, or invoking the Update Tape Link Environment Report operation with a force-restart flag set to true. If an in-progress discovery operation is interrupted for any reason, the operation will be automatically retried, and the previous requests associated with that in-progress discovery operation will be linked to the new operation.
  • If the request fails for any reason, all requests associated with that in-progress request will fail and an error code will be returned in the asynchronous result.
  • If the HMC stops communicating with the Support Element or if the CPC enters into an invalid state, when the discovery operation for a tape link is in progress, the operation will be retried when the HMC starts communicating with the SE again or if the CPC enters a valid state, respectively. The valid CPC states for the discovery operation are "active", "service-required", "degraded", and "exceptions".