Return codes

Return Code in Hexadecimal Equate Symbol Meaning and Action

0

HWI_OK

Meaning: Successful completion.

Action: None.

4

HWI_CMD_NOT_SUPPORTED_WARNING

Meaning: Successful completion. This warning return code is informational.

The target CPC being connected to has a microcode level (MCL) that does not support HWICMD, or the target CPC is at a lower hardware level than HWICMD supports (BCPii requires the target of an HWICMD to be at least at the z9 hardware level). If a subsequent HWICMD is issued with this returned connect token, the call will be rejected with a return code of HWI_CMD_NOT_SUPPORTED.

Action: Install the MCL/EC that supports HWICMD for the target CPC. The required MCL/EC are G40965.133 for a z9 CPC, and F85906.116 for a z10 CPC.

100

HWI_CONNECT_TOKEN_INV
Meaning: Program error. The specified input connection token is not valid. This return code indicates that one of the following conditions has occurred:
  • The input connection token does not exist. A previous HWICONN service call has never returned the value specified on OutConnectToken.
  • The input connection token does not represent an active connection. The connection specified might have already been disconnected by the HWIDISC service call, or have been implicitly disconnected by BCPii because of loss of connectivity with the target CPC.
  • The input connection token is not associated with the address space of the caller. The InConnectToken specified is associated with a different address space than the caller of this service call.

Action: Check for probable coding error.

101

HWI_COMMUNICATION_ERROR

Meaning: A communication error is detected. The hardware management console application API (HWMCA) or the BCPii transport layer has returned with a failing return code.

Action: See the DiagArea for further diagnostic information. The Diag_CommErr indicates the return code that is returned from HWMCA APIs or the BCPii transport layer.

HWMCA API and BCPii transport return codes are provided in BCPii communication error reason codes.

102

HWI_DIAGAREA_INV

Meaning: Program error. The DiagArea is not accessible.

Action: Check for probable coding error. Verify that the specified DiagArea is defined as a 32-byte character field.

103

HWI_CONNECT_TOKEN_INACTIVE

Meaning: The specified connect token is no longer valid. The connection has been disconnected or it is in the progress of being disconnected.

Action: Check for probable coding error. Verify that the specified connect token is still active. If connectivity to the targeted CPC connection no longer exists, all connections associated with that CPC will no longer have a connect token that can be used.

104

HWI_TARGET_CPC_CHANGED
Meaning: The CPC name represented by the specified token is valid but does not represent the same physical machine that was targeted by the initial HWICONN call. All connections that were established prior to the name change can no longer be used.

Action: The application should cease using this connect token. If the application intends to target the CPC using the name represented by the specified connect token, it must first reconnect to the CPC before issuing any BCPii service call.

201

HWI_CONNTYPE_INV

Meaning: Program error. The connection type specified in the call is not valid. The system rejects the service call.

Action: Check for probable coding error. Validate that the conntype value passed to the service is one of the accepted values.

202

HWI_CONNTYPE_VALUE_INV
Meaning: Program error. This return code indicates that one of the following conditions has occurred:
  1. The connection name specified in the call is not valid. The specified connection name is not syntactically valid, it does not exist, or it is currently not available. The system rejects the service call.
  2. When targeting a z14 or higher CPC, the BCPii request does not have proper permission granted by the SE for the target object.

Action: Check for probable coding error. Verify that the connection name is syntactically correct, valid in the current HMC configuration, and currently available. If the target CPC/LPAR is a z14 or higher, verify that the proper BCPii firmware security has been granted to allow this BCPii application to access the CPC/LPAR.

203

HWI_CONNTYPE_VALUE_ INACCESSIBLE

Meaning: Program error. The connection type value data area is either partially or completely inaccessible by the application, or the Base Control Program internal interface (BCPii) address space, or both.

Action: Check for probable coding error. Verify that the ConnectTypeValue_Ptr points to a data area where the connect type value is, and make sure that the data area is accessible.

204

HWI_MAX_CONNECTIONS_REACHED

Meaning: The number of connections has reached the maximum number of system-wide connections (Start of change5000End of change) that BCPii permits, or BCPii has run out of system resources to satisfy the HWICONN request, or both.

Action: Disconnect connections that are no longer needed, and try the request again.

205

HWI_CONNTYPE_NOT_SUPPORTED

Meaning: The targeted hardware of the HWICONN request does not support the connect type specified.

Action: Verify that the targeted hardware supports the type of request being made.

F00

HWI_NOT_AVAILABLE

Meaning: BCPii services are not available, and the system rejects the service request.

Action: Notify the system programmer to start the BCPii address space and try the request again. See Restarting the HWIBCPii address space about how to start the BCPii address space.

Programs can also listen to ENF68 to determine when BCPii services are available. See z/OS MVS Programming: Authorized Assembler Services Reference EDT-IXG for how to listen for BCPii activation messages.

F01

HWI_AUTH_FAILURE

Meaning: The caller is PKM8-15 problem state and the program does not reside in an APF-authorized library.

Action: Check the calling program for a probable coding error.

F02

HWI_NO_SAF_AUTH

Meaning: The user does not have correct SAF authorization for the request.

Action: Check for probable error. Consider one or more of the following possible actions:
  • Define read access authorization to the FACILITY class resource profile HWI.APPLNAME.HWISERV.
  • Define read access authorization to the FACILITY class resource profile HWI.TARGET.netid.nau for a CPC, activation profile, image group connectionStart of change, group profile, or LPAR Capacity group connectionEnd of change.
  • Define read access authorization to the FACILITY class resource profile HWI.TARGET.netid.nau.imagename for an image connection.
  • Define read access authorization to the FACILITY class resource profile HWI.CAPREC.netid.nau.caprecid for a capacity record connection.
  • Ensure that the referenced Facility Class Profiles are RACLIST-specified.
  • For CPC connections only: The SNMP community name specified in the security product (SAF) for a particular target CPC does not match the SNMP community name defined in the support element of the target CPC. See Community name defined in the security product for each CPC for further information regarding community name setup.

F03

HWI_INTERRUPT_STATUS_INV

Meaning: The calling program is disabled. The system rejects this service request.

Action: Check the calling program for a probable coding error.

F04

HWI_MODE_INV

Meaning: The calling program is not in task mode. The system rejects this service request.

Action: Check the calling program for a probable error.

F05

HWI_LOCKS_HELD

Meaning: The calling program is holding one or more locks. The system rejects this service request.

Action: Check the calling program for a probable coding error.

F06

HWI_UNSUPPORTED_RELEASE

Meaning: The system level does not support this service. The system rejects this service request.

Action: Remove the calling program from the system, and install it on a system that supports BCPii services. Then run the calling program again.

F07

HWI_UNSUPPORTED_ENVIRONMENT

Meaning: The system does not support execution of the service from the current environment (for example, calling a BCPii service from within a BCPii ENF exit routine).

Action: Issue the BCPii service from a different execution environment.

FFF

HWI_UNEXPECTED_ERROR

Meaning: System error. The service that was called encountered an unexpected error. The system rejects the service call.

Action: Search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center.