Perform Hardware Configuration Operation (QYHCHCOP) API

The Perform Hardware Configuration Operation (QYHCHCOP) API allows for viewing, changing, and checking the status of certain parts of the system's hardware configuration. This API allows the following activities:

• view the logical partition configuration
• change the logical partition configuration
• check the status of a logical partition configuration change
• view the disk unit and ASP configuration
• change the disk unit and ASP configuration
• check the status of disk unit and ASP configuration change

Note: The logical partition configuration activities of this API cannot be performed on systems that use POWER5 processors or newer systems.

Authorities and Locks

This API is shipped with *EXCLUDE public authority.

To use this API you must:

• be explicitly authorized to the API, or call the API from a program that adopts enough authority to call the API and have *IOSYSCFG and *SERVICE special authority.
  
  
• have set the password level of the Dedicated Service Tools (DST) to level 2. This is done through the service tools security data option, followed by the password level option.
  
  
• have a service tools user ID and password that has been authorized to perform the task you are requesting. Service tools user IDs are configured by using the DST.
  
  
• have a service tools user ID and password that match the IBM i user profile and password of the user that is calling this API. Service tools passwords must use uppercase characters. (Note: This is necessary only if the optional parameter group is not specified.)

The port name "as-sts" must be unblocked and enabled for this API to process successfully. If the port name is not unblocked, this API will return a CPFBA03 message.

The service authority required to perform an operation depends on the operation you are trying to perform. To see what authority a specific operation requires, consult the logical partition configuration markup language document or the disk management configuration markup language document. The following table summarizes the authority required for various operations.

Operation Type	Authority Required
View LPAR configuration	LPAR operator
Check LPAR operation status	LPAR operator
Perform LPAR operator operation	LPAR operator
Perform LPAR administrator operation	LPAR administrator
View disk configuration	None
Check disk operation status	None
Perform disk operator operation	Disk operator
Perform disk administration operation	Disk administrator

Required Parameter Group

Hardware Configuration Request

INPUT; CHAR(*)

The information for the request. The type of information provided is described in the request type parameter.

Hardware Configuration Request Length

INPUT; BINARY(4) Unsigned

The length of the hardware configuration request buffer.

Request type

INPUT; BINARY(4) Unsigned

The type of request being made. The following constants are defined for the request type.

LPARRequest = 1	Change, view, or check the status of the logical partition configuration using the Logical Partition Markup Language. For the format of the markup language, see LPARConfigurationScript Specification, Version 10.
DiskRequest = 2	Change, view, or check the status of the disk and ASP configuration using the Disk Management Markup Language. For the format of the markup language, see DMConfigurationScript Specification, Version 50.

Receiver variable

OUTPUT; CHAR(*)

The receiver variable that is to receive the response from the hardware configuration request. The format of this variable is determined by the type of hardware configuration request submitted.

Length of receiver variable

INPUT; BINARY(4) Unsigned

The length of the receiver variable, in bytes.

Bytes of return data available

OUTPUT; BINARY(4) Unsigned

The number of bytes that is available for return. If this value is larger than the receiver variable, some of the return data was lost.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Optional Parameter Group

Requesting service tools user ID

INPUT; CHAR(*)

The service tools user ID requesting the hardware configuration operation. This value is converted to uppercase.

Length of requesting service tools user ID password

INPUT; BINARY(4) Unsigned

The length, in bytes, of the password contained in the requesting service tools user ID password parameter. The requesting service tools user ID password parameter should be padded with trailing blank characters, if necessary, to the size specified by this parameter. This parameter accepts values from 1 to 512. However, values greater than 128 should only be used if multi-byte characters are specified for the service tools user ID password. The number of characters, as interpreted by the CCSID of the service tools user ID password parameter, cannot exceed 128.

CCSID of requesting service tools user ID password

INPUT; BINARY(4)

The valid values are:

0	The CCSID of the job is used to determine the CCSID of the data to be converted. If the job CCSID is 65535, the CCSID from the default CCSID (DFTCCSID) job attribute is used.
1 - 65533	A valid CCSID in this range.

Error Messages

Message ID	Error Message Text
CPF2203 E	User profile &1 not correct.
CPF2204 E	User profile &1 not found.
CPF225C E	Requesting service tools user ID not correct.
CPF225D E	Requesting service tools user ID password is not correct.
CPF22E2 E	Password not correct for user profile &1.
CPF22E3 E	User profile &1 is disabled.
CPF22E4 E	Password for user profile &1 has expired.
CPF22E5 E	No password associated with user profile &1.
CPF24B4 E	Severe error while addressing parameter list.
CPF3BC7 E	CCSID &1 outside of valid range.
CPF3BDE E	CCSID &1 not supported by API.
CPF3C24 E	Length of the receiver variable is not valid.
CPF3C36 E	Number of parameters, &1 entered for this API was not valid.
CPF3C4B E	Value not valid for field &1.
CPF3CF1 E	Error code parameter not valid.
CPF3CF2 E	Error(s) occurred during running of &1 API.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.
CPFB0CE E	&1 special authority is required.
CPFBA01 E	Incorrect authorization to perform operation.
CPFBA02 E	Request typeout of range.
CPFBA03 E	Error connecting to service.
CPFBA04 E	Error sending request to service.
CPFBA05 E	Error retrieving data from service.

---

API introduced: V5R1

---

[ Back to top | >Configuration APIs | APIs by category ]