Return codes

When the service returns control to the caller, GPR 15 and the ReturnCode contain a hexadecimal return code.


0 HWI_OK	Meaning: The command has been accepted by the support element. Action: Determine the final command completion result by consulting the return code value found in the data returned by the command response event. This ENF event is signaled if the application has already registered to receive this event (HWIEVENT or HwiManageEvents service).
100 HWI_CONNECT_TOKEN_INV	Meaning: Program error. The specified connect token is not valid. This return code indicates that one of the following conditions has occurred: The connect token does not exist. A previous HWICONN service call has never returned the value specified on OutConnectToken. The connect token does not represent an active connection. The connection specified might have already been disconnected using the HWIDISC service call. The connect token is not associated with the caller’s address space. The ConnectToken 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.
602 HWI_CMDTYPE_INV	Meaning: Program error. The requested CMDTYPE specified in the call is not valid. The system rejects the service call. This return code indicates that one of the following conditions has occurred: The CmdType specified is not in the acceptable value range of possible command types. The Diag_Text indicates this error with the text of 'Invalid Cmd'. The CmdType specified applies only to CPC connections, but the ConnectToken specified represents an image connection. The Diag_Text indicate this error with the text of 'Mismatch'. The CmdType specified applies only to image connections, but the ConnectToken specified represents a CPC connection. The Diag_Text indicates this error with the text of 'Mismatch'. The CmdType specified applies only to image connections, but the ConnectToken specified represents an image group connection. The Diag_Text will indicate this error with the text of ‘Mismatch'. Action: Check for probable coding error. Verify that the specified CmdType is in the acceptable value range. See the CmdType parameter section to verify that the specified connect token is applied for the requested command. See the DiagArea for further diagnostic information.
603 HWI_CMDPARM_INV	Meaning: Program error. This return code indicates that one of the following conditions has occurred: Required parameters are missing. One or more parameters specified are not valid. Action: Check for probable coding error. See the DiagArea for additional diagnostic information. The Diag_Index specifies the value of the CmdType parameter. The Diag_Text specifies the name of the parameter in the CmdParm structure. Note that the name might be abbreviated because of the limited size of the Diag_Text field.
604 HWI_CMD_TARGET_DEST_NOT_ALLOWED	Meaning: Program error. Certain commands are not allowed to be targeted to the same CPC and image on which the BCPii application is currently running. Such commands can cause the local system to be inoperable. Commands that cannot target the local CPC are: Hwi_Cmd_Activate Hwi_Cmd_Activate_With_Actprof Hwi_Cmd_Deactivate Commands that cannot target the local image include: Hwi_Cmd_Activate_With_Actprof Hwi_Cmd_Sysreset_IPLT Commands that cannot target the local image (by itself or as a member of a user-defined image group) are: Hwi_Cmd_Activate Hwi_Cmd_Deactivate Hwi_Cmd_Load Hwi_Cmd_PswRestart Hwi_Cmd_Start Hwi_Cmd_Stop Hwi_Cmd_Sysreset Hwi_Cmd_SCSI_Load Hwi_Cmd_SCSI_Dump Action: BCPii does not allow this command to be executed against the local CPC or local image. Validate the name of the target represented by the input connection token. If the target is correct, the command can only be issued from another CPC for a CPC-related command, or from another image for an image-related command. If the ConnectToken represents a user-defined image group, verify that the group does not contain the local image where this command is executing.
605 HWI_CMDPARM_INACCESSIBLE	Meaning: Program error. The CmdParm data area cannot be accessed. This return code indicates that one of the following conditions has occurred: The CmdParm data area is either partially or completely not accessible by the application, or BCPii, or both. The CmdParm data area can be too small. Action: Check for probable coding error. Validate that the CmdParm_Ptr points to a data area where the CmdParm is and that the data area is accessible.
606 HWI_CMDTYPE_NOT_SUPPORTED	Meaning: The targeted hardware of the HWICMD request does not recognize the type of command being requested. Action: Verify that the targeted hardware is at a level that supports the type of command being issued.
607 HWI_CMD_NOT_SUPPORTED	Meaning: HWICMD is not supported with the current microcode level (MCL) installed on the target CPC, 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). The warning return code, HWI_CMD_NOT_SUPPORTED_WARNING, should have been returned on the previous HWICONN service call when the requested connect token was created to establish a connection to the CPC. See the return code section in HWICONN — Establish a BCPii connection for more information. Action: Install the MCL that supports HWICMD on the target CPC or refrain from issuing HWICMD with a target older than the z9 hardware level. See the HWI_CMD_NOT_SUPPORTED_WARNING return code in the HWICONN section for the microcode level/engineering change (MCL/EC) that is required for HWICMD service call.
608 HWI_CMD_IMAGE_GROUP_IS_EMPTY	Meaning: Command did not execute because the connect token represents an image group that contains no images. Action: Ensure that the correct connect token was specified on the HWICMD request. If so, check with the SE/HMC engineer to determine the members that are in the group.
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 control access authorization to the FACILITY class resource profile HWI.TARGET.netid.nau for a CPC or image group connection. Define control access authorization to the FACILITY class resource profile HWI.TARGET.netid.nau.imagename for an image connection. Define CONTROL access authorization to the FACILITY class resource profile HWI.TARGET.netid.nau.imagename for each image within the target image group for an image group connection. Note: It is possible that an application may have the proper authority to all images in a user-defined image group returned on a prior HWILIST invocation, yet still receive this error return code. This could be because HWILIST will only return image names that the user has the proper authority to view. In this case, it will be necessary to contact the HMC/SE administrator to find out if there are other image names contained in the user-defined image group that were not returned on the HWILIST invocation. Once these names have been acquired, the security administrator may be contacted to give CONTROL or higher access to these additional image names. Ensure that the referenced Facility Class Profile is RACLIST-specified.
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: In many cases, BCPii has taken an abend to gather further diagnostic information. Search problem reporting data bases for a fix for the problem. If no fix exists, contact the IBM Support Center.