Create Image Activation Profile
The Create Image Activation Profile operation creates a new Image activation profile. This operation is supported using the BCPii interface. [Added by feature create-delete-activation-profiles]
HTTP method and URI
POST /api/cpcs/{cpc-id}/image-activation-profiles
In this request, the URI variable {cpc-id} is the object ID of the target CPC object.
Request body contents
Name | Type | Rqd/ Opt | Description |
---|---|---|---|
name | String (1-8) | Required | The Image activation profile name, which uniquely identifies this profile within the set of Image activation profiles for the CPC object designated by {cpc-id}. |
copy-name | String (1-8) | Optional |
The name of an existing Image activation profile on the CPC object designated by {cpc-id}. If this field is provided, the name must be a valid name of an existing profile, which will then be loaded as the initial values for the Create operation. If this field is not sent in the request, the new image profile will use the fields from the DEFAULT image profile as the initial values for the created profile. |
description | String (0-50) | Optional | The image profile description of the profile to be created. |
partition-identifier | String (2) | Optional | The two-digit hexadecimal partition identifier to be used for the logical partition. |
operating-mode | String Enum | Optional |
The operating mode for the logical partition:
|
clock-type | String Enum | Optional |
One of:
|
liccc-validation-enabled | Boolean | Optional | If true, ensure that the image profile data conforms to the current maximum Licensed Internal Code Configuration Control (LICCC) configuration. |
group-profile-uri | String/ URI | Optional | The name of the Group Profile associated with the logical partition. |
global-performance-data-authorization-control | Boolean | Optional | If true, the logical partition can be used to view the processing unit activity data for all other logical partitions activated on the same CPC. |
io-configuration-authorization-control | Boolean | Optional | If true, the logical partition can be used to read and write any Input/Output Configuration Data Set (IOCDS) in the configuration. |
cross-partition-authority-authorization-control | Boolean | Optional | If true, the logical partition can be used to issue control program instructions that reset or deactivate other logical partitions. |
logical-partition-isolation-control | Boolean | Optional | If true, reconfigurable channel paths assigned to the logical partition are reserved for its exclusive use. |
security-bcpii-send-commands | Boolean | Optional | If true, configure the logical partition to allow the sending of commands through BCPii. |
security-bcpii-receive-commands | Boolean | Optional | If true, configure the logical partition to allow the receiving of BCPii commands |
security-bcpii-receive-selection | String Enum | Optional |
Determine the BCPii commands this image is allowed to receive. This value is only valid if security-bcpii-receive-commands is True. One of:
|
security-bcpii-receive-partition-list | Array of String | Optional |
The list of specified system/partitions from which the image, when configured to allow, can receive BCPii commands. The format for each String entry to the Array is as follows:
Example: NNNNNNNN.SSSSSSSS.PPPPPPPP |
basic-cpu-counter-authorization-control | Boolean | Optional | If true, the basic CPU counter facility for the logical partition is enabled. |
problem-state-cpu-counter-authorization-control | Boolean | Optional | If true, the problem state CPU counter facility for the logical partition is enabled |
crypto-activity-cpu-counter-authorization-control | Boolean | Optional | If true, the crypto activity CPU counter facility for the logical partition is enabled. |
extended-cpu-counter-authorization-control | Boolean | Optional | If true, the extended CPU counter facility for the logical partition is enabled |
basic-cpu-sampling-authorization-control | Boolean | Optional | If true, the basic CPU sampling facility for the logical partition is enabled. |
diagnostic-sampling-authorization-control | Boolean | Optional | If true, the diagnostic sampling authorization control is enabled. |
permit-des-key-import-functions | Boolean | Optional | If true, importing of Data Encryption Standard (DES) keys for the logical partition is enabled. |
permit-aes-key-import-functions | Boolean | Optional | If true, importing of Advanced Encryption Standard (AES) keys for the logical partition is enabled. |
permit-ecc-key-import-functions | Boolean | Optional | If true, importing of Elliptic Curve Cryptography (ECC) keys for the logical partition is enabled. |
central-storage | Integer | Optional | Defines the amount of central storage, measured in megabytes (MB), to be allocated for the logical partition's exclusive use at activation. This value must be a multiple of the storage granularity value. |
reserved-central-storage | Integer | Optional | Defines the amount of central storage, measured in megabytes (MB), dynamically reconfigurable to the logical partition after activation. This value must be a multiple of the storage granularity value. |
user-specified-central-storage-origin | Boolean | Optional | If true, enable user specification of the central storage origin. |
central-storage-origin | Long | Optional | The central storage origin. This is only used if user-specified-central-storage-origin is true. |
initial-vfm-storage | Long | Optional | Defines the amount of Virtual Flash Memory (VFM) storage, measured in gigabytes (GB), to be allocated for the logical partition's exclusive use at activation. The valid range is 0 to the value indicated on the storage-vfm-total property in a multiple of the value indicated on the storage-vfm-increment-size property for the associated CPC. This value must not be greater than the value specified in the maximum-vfm-storage property in this Image Activation Profile. |
maximum-vfm-storage | Long | Optional | Defines the maximum amount of VFM storage, measured in gigabytes (GB), that can be allocated to the logical partition while it is running. The valid range is 0 to the value indicated on the storage-vfm-total property in a multiple of the value indicated on the storage-vfm-increment-size property for the associated CPC. This value must not be smaller than the value specified in the initial-vfm-storage property in this Image Activation Profile. |
minimum-io-priority-queueing | Integer (0-255) | Optional |
The minimum I/O priority queueing. Note: This value must be greater than or equal to 0 and less than the
maximum-io-priority-queueing value.
|
maximum-io-priority-queueing | Integer (0-255) | Optional |
The maximum I/O priority queueing. Note: This number must be greater than or equal to minimum-io-priority-queueing.
|
logical-cluster-name | String (0-8) | Optional | The CP management cluster name. |
defined-capacity | Integer | Optional |
The defined capacity expressed in terms of Millions of Service Units (MSU)s per hour. MSU is a
measure of processor resource consumption. The amount of MSUs a logical partition consumes is
dependent on the model, the number of logical processors available to the partition, and the amount
of time the logical partition is dispatched. The defined capacity value specifies how much capacity
the logical partition is to be managed by z/OS Workload Manager for the purpose of software pricing.
|
load-at-activation | Boolean | Optional | If true, the logical partition will be loaded at the end of the activation. |
load-timeout | Integer (60-600) | Optional | Amount of time, in seconds, to wait for the Load to complete |
store-status-indicator | Boolean | Optional | Whether status should be stored before performing the Load (true) or not stored (false). |
ipl-type | String Enum | Optional | One of:
|
ipl-address | String (0-5) | Optional | The hexadecimal address of an I/O device that provides access to the control program to be loaded. An empty string indicates that the value for this property is to be retrieved from the IOCDS used during a subsequent Load operation. When this property is intended to be used for ipl-type of "ipltype-nvmeload" or "ipltype-nvmedump", the input value shall be an empty string or a four-digit hexadecimal function ID (FID) of the NVMe device. If it’s an FID, it will be right justified and padded with zeros. The values shall be in the range "0000" to "FFFF". For any other ipl-type, the input value shall be an empty string or a five-digit hexadecimal address of the I/O device. If it's an address, it will be right justified and padded with zeros. 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". |
ipl-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. An empty string indicates that the value for this property is to be retrieved from the IOCDS used during a subsequent Load operation. Valid characters are 0-9, A-Z, blank, and period. Three additional characters, (@, $, #) are also allowed. A non-empty string is leading whitespace trimmed and right padded with blanks to 8 characters |
boot-record-location-cylinder | String (1-7) | Optional |
The boot record location cylinder value in hexadecimal. Note: This property is only applied to ipl-type of "ipltype-eckd-ld-load" and
"ipltype-eckd-ld-dump".
|
boot-record-location-head | String (1) | Optional |
The boot record location head in hexadecimal. Note: This property is only applied to ipl-type of "ipltype-eckd-ld-load" and
"ipltype-eckd-ld-dump".
|
boot-record-location-record | String (0-2) | Optional |
The boot record location record in hexadecimal. The record may not be set to "0" or "00". Note: This property is only applied to ipl-type of "ipltype-eckd-ld-load" and
"ipltype-eckd-ld-dump"
|
boot-record-location-use-volume-label | Boolean | Optional |
Whether the boot-record-location-cylinder, boot-record-location-head and boot-record-location-record should be determined by the volume label. On a create, this value cannot be set to true if the boot-record-location-cylinder, boot-record-location-head, or boot-record-location-record is specified in the same request. If this value is true, it overrides the boot-record-location-cylinder, boot-record-location-head, and boot-record-location-record when a load is completed with this profile. Note: This property is only applied to ipl-type of "ipltype-eckd-ld-load" and
"ipltype-eckd-ld-dump".
|
worldwide-port-name | String (1-16) | Optional |
Worldwide port name value for the activation profile, used for SCSI load and SCSI dump, in hexadecimal. Note: This property is only applied to ipl-type of "ipltype-scsi"
or"ipltype-scsidump".
|
logical-unit-number | String (1-16) | Optional | Logical unit number value for the activation profile, used for SCSI load and
SCSI dump, in hexadecimal. Note: This property is only applied to ipl-type of
"ipltype-scsi" or"ipltype-scsidump".
|
disk-partition-id | Integer (0-30) | Optional |
The disk partition number (also called the boot program selector) for the activation profile, used for a list-directed OS load or dump. This value is ignored when the disk-partition-id-automatic value is true. When the disk-partition-id-automatic property is set to true, the value in this field is overridden and not used to complete the load. Note: This property is only applied to ipl-type of "ipltype-scsi",
"ipltype-scsidump", "ipltype-nvmeload", "ipltype-nvmedump",
"ipltype-eckd-ld-load", "ipltype-eckd-ld-dump".
|
disk-partition-id-automatic | Boolean | Optional |
Whether the value in disk-partition-id (also known as the boot program selector) should be ignored, and instead, the value should be determined automatically. When this field is set to true, it will override any value in disk-partition-id. Note: This property is only applied to ipl-type of "ipltype-scsi",
"ipltype-scsidump", "ipltype-nvmeload", "ipltype-nvmedump",
"ipltype-eckd-ld-load", "ipltype-eckd-ld-dump".
|
boot-record-lba | String (1-16) | Optional |
Boot record logical block address for the activation profile, used for SCSI load and SCSI dump, in hexadecimal. Note: This property is only applied to ipl-type of "ipltype-scsi",
"ipltype-scsidump", "ipltype-nvmeload", or "ipltype-nvmedump".
|
os-specific-load-parameters | String (0-256) | Optional |
Operating system specific load parameters for the activation profile, used for a list-directed load or list-directed dump. On a Create, value is left justified and right-padded with blanks to 256 characters. Note: This property is only applied to ipl-type of "ipltype-scsi",
"ipltype-scsidump", "ipltype-nvmeload", "ipltype-nvmedump",
“ipltype-eckd-ld-load”, or “ipltype-eckd-ld-dump”.
|
secure-boot | Boolean | Optional |
If true, the software signature of what is loaded will be checked against what the distributor signed it with. The load will fail if the signatures do not match. Note: This property is only applied to ipl-type of "ipltype-scsi",
"ipltype-scsidump", "ipltype-nvmeload", "ipltype-nvmedump",
"ipltype-eckd-ccwload", "ipltype-eckd-ccwdump", "ipltype-eckd-ld-load",
"ipltype-eckd-ld-dump".
|
initial-processing-weight | Integer (1-999) | Optional | The relative amount of shared general purpose processor resources allocated to the logical partition at activation. |
number-shared-general-purpose-processors | Integer | Optional | The number of shared general purpose processors allocated to the logical partition. |
number-reserved-shared-general-purpose-processors | Integer | Optional | The number of shared general purpose processors reserved for the logical partition. |
number-dedicated-general-purpose-processors | Integer | Optional | The number of general purpose processors allocated to the logical partition. |
number-dedicated-reserved-general-purpose-processors | Integer | Optional | The number of general purpose processors reserved for the logical partition. |
intial-processing-weight-capped | Boolean | Optional |
Whether the initial processing weight for general purpose processors is a limit or a target.
|
minimum-processing-weight | Integer (0-999) | Optional |
The minimum relative amount of shared general purpose processor resources allocated to the
logical partition. This value must be less than or equal to the value of
maximum-processing-weight.
|
maximum-processing-weight | Integer (0-999) | Optional |
The maximum relative amount of shared general purpose processor resources allocated to the logical partition. This value must be greater than or equal to the value of minimum-processing-weight.
|
absolute-capping | absolute-capping object | Optional | The amount of absolute capping applied to the general purpose processor. |
number-shared-ifl-processors | Integer | Optional | The number of shared Integrated Facility for Linux (IFL) processors allocated to the logical partition. |
number-reserved-shared-ifl-processors | Integer | Optional | The number of shared Integrated Facility for Linux (IFL) processors reserved for the logical partition. |
number-dedicated-ifl-processors | Integer | Optional | The number of Integrated Facility for Linux (IFL) processors allocated to the logical partition. |
number-reserved-dedicated-ifl-processors | Integer | Optional | The number of Integrated Facility for Linux (IFL) processors reserved for the logical partition. |
initial-ifl-processing-weight | Integer (1-999) | Optional | The relative amount of shared Integrated Facility for Linux (IFL) processor resources allocated to the logical partition at activation. |
initial-ifl-processing-weight-capped | Boolean | Optional |
Whether the initial processing weight for Integrated Facility for Linux (IFL) processors is a
limit or a target.
|
minimum-ifl-processing-weight | Integer (0-999) | Optional |
The minimum relative amount of shared Integrated Facility for Linux (IFL)processor resources allocated to the logical partition. This value must be less than or equal to the value of maximum-ifl-processing-weight.
|
maximum-ifl-processing-weight | Integer (0-999) | Optional |
The maximum relative amount of shared Integrated Facility for Linux (IFL)processor resources
allocated to the logical partition. This value must be greater than or equal to the value of
minimum-ifl-processing-weight.
|
absolute-ifl-capping | absolute-capping object | Optional | The amount of absolute capping applied to the Integrated Facility for Linux (IFL) processor. |
number-shared-icf-processors | Integer | Optional | The number of shared Internal Coupling Facility (ICF) processors allocated to the logical partition. |
number-reserved-shared-icf-processors | Integer | Optional | The number of shared Internal Coupling Facility (ICF) processors reserved for the logical partition. |
number-dedicated-icf-processors | Integer | Optional | The number of Internal Coupling Facility (ICF) processors allocated to the logical partition. |
number-reserved-dedicated-icf-processors | Integer | Optional | The number of Internal Coupling Facility (ICF) processors reserved for the logical partition. |
initial-internal-cf-processing-weight | Integer (1-999) | Optional | The relative amount of shared Internal Coupling Facility (ICF) processor resources allocated to the logical partition at activation. |
initial-internal-cf-processing-weight-capped | Boolean | Optional |
Whether the initial processing weight for Internal Coupling Facility (ICF) processors is a limit or a target.
|
minimum-internal-cf-processing-weight | Integer (0-999) | Optional | The minimum relative amount of shared Internal Coupling Facility (ICF)
processor resources allocated to the logical partition. This value must be less than or equal to the
value of maximum-internal-cf-processing-weight.
|
maximum-internal-cf-processing-weight | Integer (0-999) | Optional |
The maximum relative amount of shared Internal Coupling Facility (ICF) processor resources allocated to the logical partition. This value must be greater than or equal to the value of minimum-internal-cf-processing-weight.
|
absolute-internal-cf-capping | absolute-capping object | Optional | The amount of absolute capping applied to the Internal Coupling Facility (ICF) processor. |
number-shared-ziip-processors | Integer | Optional | The number of shared z Integrated Information Processors (zIIP) processors allocated to the logical partition. |
number-reserved-ziip-processors | Integer | Optional | The number of shared z Integrated Information Processors (zIIP) processors reserved for the logical partition. |
number-dedicated-ziip-processors | Integer | Optional | The number of z Integrated Information Processors (zIIP) processors allocated to the logical partition. |
number-reserved-dedicated-ziip-processors | Integer | Optional | The number of z Integrated Information Processors (zIIP) processors reserved for the logical partition. |
initial-ziip-processing-weight | Integer (1-999) | Optional | The relative amount of shared z Integrated Information Processors (zIIP) processor resources allocated to the logical partition at activation. |
initial-ziip-processing-weight-capped | Boolean | Optional |
Whether the initial processing weight for z Integrated Information Processors (zIIP) processors is a limit or a target.
|
minimum-ziip-processing-weight | Integer (0-999) | Optional | The minimum relative amount of shared z Integrated Information Processors
(zIIP) processor resources allocated to the logical partition. This value must be less than or equal
to the value of maximum-ziip-processing-weight
|
maximum-ziip-processing-weight | Integer (0-999) | Optional |
The maximum relative amount of shared z Integrated Information Processors (zIIP) processor resources allocated to the logical partition. This value must be greater than or equal to the value of minimum-ziip-processing-weight.
|
absolute-ziip-capping | absolute-capping object | Optional | The amount of absolute capping applied to the Integrated Facility for Linux(IFL) processor. |
workload-manager-enabled | Boolean | Optional | Whether or not z/OS Workload Manager is allowed to change processing weight
related properties.
|
crypto-controls-domain | Array of Integer | Optional | The crypto control domain index. Note: If included in the request, this
array must contain at least one value.
Valid values are unique entries from 0 through a
maximum set by the CPC. |
crypto-usages-domain | Array of Integer | Optional | The crypto usage domain index. Note: Values are invalid if there are no
matching values in the crypto-controls-domain.
Valid values are unique entries from 0
through a maximum set by the CPC. |
crypto-candidate-list | Array of Integer | Optional | The crypto candidate list Note: Values are unique entries from 0
through a maximum set by the CPC.
|
crypto-online-list | Array of Integer | Optional | The crypto target online mask. Note: Values are invalid if there are no
matching values in the crypto-candidate-list.
Valid values are unique entries from 0
through a maximum set by the CPC. |
time-offset-days | Integer (0-999) | Optional | The number of days the logical partition's clock is to be offset from the External Time Source's time of day. |
time-offset-hours | Integer (0-23) | Optional | The number of hours the logical partition's clock is to be offset from the External Time Source's time of day. |
time-offset-minutes | Integer Enum | Optional | The number of minutes the logical partition's clock is to be offset from the External Time Source's time of day. Allowable values are 0, 15, 30 or 45. |
time-offset-increase-decrease | String Enum | Optional |
One of:
|
ssc-host-name | String (1-64) | Optional | The Secure Service Container host name. Valid characters are: a-z, A-Z,0-9, period(.), minus(-) and colon(:). This is only used when operating-mode is "ssc". |
ssc-primary-userid | String (1-32) | Optional | The Secure Service Container master user ID. Valid characters are: a-z,A-Z, 0-9, period(.), minus(-) and underscore(_). This is only used when operating-mode is "ssc". |
ssc-primary-pw | String (8-256) | Optional | The Secure Service Container master password. Valid characters are: a-z,A-Z, 0-9, and !@#$%^&*()_+{}|<>?-=. This is only used when operating-mode is "ssc". |
ssc-network-info | Array of ssc-network objects | Optional | The set of networks available to the Secure Service Container. A minimum of 1 network and a maximum of 100 networks are permitted. This is only used when operating-mode is "ssc". |
ssc-gateway-info | ip-info object | Optional | The IPv4 default gateway IP address information for the Secure Service Container. A null object indicates no IPv4 default gateway IP address is specified. This is only used when operating-mode is "ssc". |
ssc-gateway-ipv6-info | ip-info object | Optional | The IPv6 default gateway IP address information for the Secure Service Container. A null object indicates no IPv6 default gateway IP address is specified. This is only used when operating-mode is "ssc". |
ssc-dns-info | Array of ip-info object | Optional | The DNS IP address information for the Secure Service Container. A minimum of 0 entries and a maximum of 2 entries are permitted. This is only used when operating-mode is "ssc". |
ssc-boot-selection | String Enum | Optional |
Indicates whether to run the Secure Service Container appliance installer or the Secure Service Container appliance itself. One of:
|
Response body contents
On successful completion, the response body contains a JSON object with the following fields:
Field name | Type | Description |
---|---|---|
element-uri | String/ URI | The element URI of the newly created Image activation profile. |
Description
The Create Image Activation Profile operation creates a new image profile on the Support Element. This new profile will be created with the name indicated in the name field and will be created using the values from the DEFAULT Image profile, unless the copy-name field is provided in the request, in which case the profile will be created with the values from the copy-name identified profile as initial values. The copy-name field, if provided, must contain a valid existing profile name of the same type. Users of this operation can override specific properties by specifying them in the request body.
If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation error encountered. On successful execution, the Image Activation Profile is created, and a status code 201 (Created) is returned.
Authorization requirements
This operation has the following authorization requirements:
- Action/Task permission for the Customize/Delete Activation Profiles task.
For the BCPii interface, the source partition must have receive BCPii security controls permissions for the CPC object designated by {cpc-id}.
HTTP status and reason codes
On success, HTTP status code 201 (Created) is returned, and the response body is provided as described in Response body contents, and the Location response header contains the URI of the newly created object.
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. |
8 | The name value for this profile type already exists on the CPC with object-id {cpc-id}. | |
300 | The provided update values would result in an illegal state. Verify that the values are both internally consistent and consistent with the current state of the profile. | |
403 (Forbidden) | 0 | The request used the BCPii interface and the source partition does not have receive BCPii security controls permission for the CPC object. |
1 | The user under which the API request was authenticated does not have the required authority to perform the requested action. | |
404 (Not Found) | 1 | The object ID in the URI ({cpc-id}) does not designate an existing CPC object, or the API user does not have object-access permission to the object. |
4 | The object designated by the request URI does not support the requested operation. | |
260 | The activation profile name in the copy-name field does not designate an existing activation profile. | |
409 (Conflict) | 2 | The operation was rejected by the Support Element (SE), because the SE is currently performing processing that requires exclusive control of the SE. Retry the operation at a later time. |
329 | The operation cannot be performed because the CPC designated by the request URI is an unmanaged CPC, which is not supported by this operation. | |
399 | The operation cannot be performed as it would exceed the maximum number of Image Activation profiles allowed on the CPC. Retry the operation after an Image Activation profile is deleted from the CPC. | |
500 (Server Error) | 281 | An unexpected error occurred during the operation. |
503 (Service Unavailable) | 1 | The request could not be processed because the HMC is not 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.