Load Logical Partition

Edit online

The Load Logical Partition operation resets a logical partition, to prepare it for loading an operating system, and loads the operating system. This operation is supported using the BCPii interface.

HTTP method and URI

POST /api/logical-partitions/{logical-partition-id}/operations/load

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

Request body contents

The request body is expected to contain a JSON object with the following fields. If none of the optional fields are included, an empty request body must be supplied.

Field name	Type	Rqd/ Opt	Description
`load-address`	String (1-5)	Optional	The hexadecimal address of an I/O device that provides access to the control program to be loaded. The input value is right justified and padded with zeros to 5 characters. Valid values are in the range "00000" to "nFFFF" where "n" is the number of subchannel sets provided by the CPC minus 1. So, for example, on a CPC that provides 3 subchannel sets, the valid range is "00000" to "2FFFF". When load-address is not supplied, the operation will try to load using the address used in the last load.
`load-parameter`	String (0-8)	Optional	Some control programs support the use of this property to provide additional control over the outcome of a Load operation. Refer to the configuration documentation for the control program to be loaded to see if this parameter is supported and if so, what values and format is supported. Valid characters are 0-9, A-Z, blank and period. Three additional characters, (@, $, #) are also allowed when the se-version property of the associated CPC is "2.14.0" or later.
`clear-indicator`	Boolean	Optional	Whether memory should be cleared before performing the Load (true) or not cleared (false). The default value is true.
`timeout`	Integer (60- 600)	Optional	Amount of time, in seconds, to wait for the Load to complete. The default timeout value is 60 seconds.
`store-status-indicator`	Boolean	Optional	Whether status should be stored before performing the Load (true) or not stored (false). The default is false.
`force`	Boolean	Optional	Whether this operation is permitted when the logical partition is in "operating" status (true) or not (false). The default is false.
`os-ipl-token`	String (1-16)	Optional	Applicable only to z/OS®, this parameter requests that this operation only be performed if the provided value matches the current value of the os-ipl-token property. This ensures that this operation is targeting the same IPL instance as when the os-ipl-token property was retrieved. IBM® recommends that this parameter only be provided by callers that fully understand how the os-ipl-token parameter is managed by z/OS. The value is a string of hexadecimal characters (0-9, A-Z), left justified.

Response body contents

Once the operation 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 Job status and reason codes. The job-results field is null when this operation is successful. When it is partially successful or 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 partially successful or not successful.

Description

This operation is not permitted for a logical partition whose activation-mode property is "zaware" or "ssc".

When the operation is initiated, a 202 (Accepted) status code is returned. The response body includes a URI that may be queried to retrieve the status of the operation. See Query Job Status for information on how to query job status. When the operation has completed, an asynchronous result message is sent. See Job status and reason codes.

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 Load task.
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 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 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.
	264	The specified IPL Token value does not match the current IPL Token value.
	306	This operation is not valid in the current activation mode.
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.
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.
500 (Server Error)	280	An IO exception occurred during the scheduling of the asynchronous request.

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

Job status and reason codes

HTTP error status code	Reason code	Description
204 (No Content)	N/A	Operation completed successfully.
500 (Server Error)	263	Operation failed or was rejected due to the current logical partition status and use of the force=false parameter. If rejected due to force=false, the logical partition status is unchanged. If the operation failed, the logical partition status is unknown. Refer to the message parameter in the error response body for details.