z/OS MVS Programming: Callable Services for High-Level Languages
Previous topic | Next topic | Contents | Contact z/OS | Library | PDF


Parameters

z/OS MVS Programming: Callable Services for High-Level Languages
SA23-1377-02

Start of change
The parameters are explained as follows:
ReturnCode
Returned parameter
  • Type: Integer (non-REXX), character representation of an integer (REXX)
  • Length: 4 bytes (non-REXX)

ReturnCode contains the return code from the service.

ConnectToken
Supplied parameter
  • Type: Character string
  • Length: 16 bytes

ConnectToken specifies the connect token that this command is executed against. A ConnectToken represents a logical connection between the application and a CPC or an image, and is returned as an output parameter on the HWICONN service call.

A ConnectToken representing a user-defined image group may also be specified. In this case, the command will be executed on all members in the group, and not just on a single image.

The ConnectToken specified must have originated from a HWICONN service call that was issued from the same address space as this service call.

CmdType
Supplied parameter
  • Type: Integer (non-REXX), character representation of an integer (REXX)
  • Length: 4 bytes (non-REXX)

CmdType specifies the type of the requested command.

See the following publications for more information about how the various commands operate, what inputs are required, and what outputs are expected:
  • System z Application Programming Interfaces (SB10-7030-13)
  • System z10 and eServer zSeries Application Programming Interfaces (SB10-7030-09)
  • System z9 and eServer zSeries Application Programming Interfaces (SB10-7030-08)
  • zEnterprise System Support Element Operations Guide (SC28-6896-02)
  • System z10 Support Element Operations Guide (SC28-6858-02)
  • System z9 Support Element Operations Guide (SC28-6858-01)
Constant in Hexadecimal (Decimal) Equate Symbol Description
1

(1)

HWI_CMD_ACTIVATE

 Activate request to start target systems with the default activation profile name (HWI_APROF) associated with a CPC or an image.
Note: The input connection token represents a CPC connection, an image connection, or an image group connection. This command cannot be issued specifying a connect token that represents either the local CPC or the local image.
2

(2)

HWI_CMD_DEACTIVATE

 Deactivate request to close down target systems.
Note: The input connection token represents a CPC connection, an image connection, or an image group connection. This command cannot be issued specifying a connect token that represents either the local CPC or the local image.
3

(3)

HWI_CMD_HWMSG

 Hardware messages request.
Note: The input connection token must only represent a CPC connection.
4

(4)

HWI_CMD_CBU

 Capacity backup CPC feature operation.
Note: The input connection token must only represent a CPC connection.
5

(5)

HWI_CMD_OOCOD

 On/Off capacity on demand request.
Note: The input connection token must only represent a CPC connection.
6

(6)

HWI_CMD_PROFILE

 Access CPC activation profiles.
Note: The input connection token must only represent a CPC connection.
7

(7)

HWI_CMD_RESERVE

 Set exclusive CPC control.
Note: The input connection token must only represent a CPC connection.
8

(8)

HWI_CMD_SYSRESET

 System reset request for target systems. See Cmdtype HWI_CMD_SYSRESET_IPLT for the latest version of the Sysreset command.
Note: The input connection token must only represent an image connection or an image group connection. This command cannot be issued specifying a connect token that represents the local image.
9

(9)

HWI_CMD_START

 Start request for all CPs on target systems.
Note: The input connection token must only represent an image connection or an image group connection. This command cannot be issued specifying a connect token that represents the local image.
A

(10)

HWI_CMD_STOP

 Stop request for all CPs on target systems.
Note: The input connection token must only represent an image connection or an image group connection. This command cannot be issued specifying a connect token that represents the local image.
B

(11)

HWI_CMD_PSWRESTART

 Restart request for one CP on target system. The first CP that is found to be in the correct state is reset.
Note: The input connection token must only represent an image connection or an image group connection. This command cannot be issued specifying a connect token that represents the local image.
C

(12)

HWI_CMD_OSCMD

 Send operating system command request.
Note: The input connection token must only represent an image connection.
D

(13)

HWI_CMD_LOAD

 Load request to IPL target operating systems.
Note: The input connection token must only represent an image connection or an image group connection. This command cannot be issued specifying a connect token that represents the local image.
E

(14)

HWI_CMD_TEMPCAP

 Addition or removal of temporary capacity.
Note: The input connection token must only represent a CPC connection.
F

(15)

HWI_CMD_SYSRESET_IPLT

 System reset request for target systems with IPL token correlation. This is an enhanced version of HWI_CMD_SYSRESET.
Note: The input connection token must only represent an image connection.
10

(16)

HWI_CMD_ACTIVATE _WITH_ACTPROF

 Activate request to start target systems using a supplied activation profile name. This is an enhanced version of the HWI_CMD_ACTIVATE command.
Note: The input connection token must only represent a CPC connection or an image connection.
11

(17)

HWI_CMD_POWER_CONTROL

 Control the power usage characteristics.
Note: The input connection token must only represent a CPC connection.
12

(18)

HWI_CMD_SCSI_LOAD

 SCSI Load from FCP (Fibre Channel Protocol for SCSI) attached SCSI (Small Computer System Interface) disks.
Note: The input connection token must only represent an image connection or an image group connection.
13

(19)

HWI_CMD_SCSI_DUMP

 SCSI Dump to FCP (Fibre Channel Protocol for SCSI) attached SCSI (Small Computer System Interface) disks.
Note: The input connection token must only represent an image connection.
14

(20)

HWI_CMD_SYSPLEX_TIME _SWAP_CTS

 In a configured STP-only coordinated timing network (CTN), one CPC has the role of current time server (CTS). If the CTN has both a preferred time server and a backup time server configured, either one can be the CTS. This command swaps the role of CTS from preferred time server to backup time server or vice versa. The target system must be the system that will become the CTS.
Note: The input connection token must only represent a CPC connection.
15

(21)

HWI_CMD_SYSPLEX_TIME _SET_STP_CONFIG

 This command sets the configuration for an STP-only coordinated timing network (CTN). The target system must be the system that will become the current time server (CTS).
Note: The input connection token must only represent a CPC connection.
16

(22)

HWI_CMD_SYSPLEX_TIME _CHANGE_STP_ONLY_CTN

 This command, sent to the defined CPC with the role of current time server (CTS) in an STP-only coordinated timing network (CTN), changes the STP_ID portion of the CTN ID for the entire STP-only CTN.
Note: The input connection token must only represent a CPC connection.
17

(23)

HWI_CMD_SYSPLEX_TIME _JOIN_STP_ONLY_CTN

 This command allows a CPC to join an STP-only coordinated timing network (CTN). The target system cannot be the current time server. If the CPC is already participating in an STP-only CTN, it will be removed from that CTN and joined to the specified one. If the CPC has an ETR ID, it will be removed.
Note: The input connection token must only represent a CPC connection.
Attention: Use extreme caution when issuing this command. Joining the STP-only CTN may result in a disabled wait state for all images that are in a parallel sysplex on the target CPC.
18

(24)

HWI_CMD_SYSPLEX_TIME _LEAVE_STP_ONLY_CTN

 This command removes a CPC from an STP-only coordinated timing network (CTN). The target system cannot be the current time server.
Note: The input connection token must only represent a CPC connection.
Attention: Use extreme caution when issuing this command. Leaving the STP-only CTN may result in a disabled wait state for all images that are in a parallel sysplex on the target CPC.
Start of changeCmdParm_Ptr (non-REXX)End of change
Start of changeCmdParm. (REXX)End of change
Start of changeSupplied parameter
  • Type: Pointer (non-REXX), stem variable (REXX)
  • Length: 4 bytes (non-REXX)
Non-REXX:
CmdParm_Ptr specifies the address of the command parameter that contains a structure of the input parameters for the requested command.
Take the following action according to the different conditions:
  • For all optional parameters, callers are required to initialize the parameters to zero for BCPii to interpret them as null parameters unless otherwise specified.
  • For commands with one or more required parameters and also with one or more optional parameters, callers are required to initialize each optional parameters to zero if they require BCPii to take the default action for that parameter.
  • For commands that have only optional parameters, callers can initialize the CmdParm_Ptr to zero if they require BCPii to take the default action for all parameters.
  • For commands that have no parameters, the CmdParm_Ptr is ignored.
  • All string type parameters are required to be padded with trailing blanks unless otherwise specified.
  • For commands that target image groups, the parameters specified in the CmdParm must be appropriate for all the images in the image group.
REXX:
CmdParm stem contains compound (stem) variables which represent input parameters for the requested command. The tail names of the stem variable are constants which must match the parameter names in the table below.

For optional parameters that are not initialized, BCPii interprets them as null parameters.

Table 1. Structure pointed to by CmdParm_Ptr (non-REXX); CmdParm stem variable (REXX)
CmdType : HWI_CMD_ CmdParm (non-REXX) Parameters in Structure (non-REXX) / Tail name constant of the user-defined CmdParm stem (REXX) Parameter Values
ACTIVATE HWI_CMD_ACT_PARM ForceType A 4-byte integer (optional, the default is FORCE):
  • 1 – means Force YES (HWI_CMD_FORCE)
  • 2 – means Force NO (HWI_CMD_NOFORCE)
Note: Only a ForceType of HWI_CMD_FORCE will result in a successful activation of the target CPC or image if the target CPC or image is already active.
DEACTIVATE HWI_CMD_DEACT_PARM ForceType A 4-byte integer (optional, the default is FORCE):
  • 1 – means Force YES (HWI_CMD_FORCE)
  • 2 – means Force NO (HWI_CMD_NOFORCE)
HWMSG HWI_CMD_HWMSG_PARM HWMSGType A 4-byte integer (required):
  • 1 – means REFRESH (HWI_CMD_HWMSG_REFRESH)
  • 2 – means DELETE (HWI_CMD_HWMSG_DELETE)
  HWMSGTimestamp

A null-terminated character string, up to 32 characters long. Required only for HWMSGType = HWI_CMD_HWMSG_DELETE.

The timestamp specified must be an exact match of a timestamp returned on a HWMSGType = HWI_CMD_HWMSG_REFRESH request. An example of a timestamp: '08-20-2010 11:01: 23:145'.

To delete a message, first run an HWI_CMD_HWMSG_REFRESH request to obtain the full timestamp and then issue the HWI_CMD_HWMSG_DELETE request, specifying the timestamp.
CBU HWI_CMD_CBU_PARM CBUType A 4-byte integer (required):
  • 1 – means ACTIVATE (HWI_CMD_ACT)
  • 2 – means UNDO (HWI_CMD_UNDO)
    ActivateType A 4-byte integer (required only for CBUType = HWI_CMD_ACT):
  • 1 – means REAL CBU (HWI_CMD_REAL)
  • 2 – means TEST CBU (HWI_CMD_TEST)
OOCOD HWI_CMD_OOCOD_PARM OOCODType A 4-byte integer (required):
  • 1 – means ACTIVATE (HWI_CMD_ACT)
  • 2 – means UNDO (HWI_CMD_UNDO)
    OrderNumber Required for OOCODType = HWI_CMD_ACT
PROFILE HWI_CMD_PROFILE_PARM ProfileType A 4-byte integer (required):
  • 1 – means IMPORT (HWI_CMD_PROFILE_ IMPORT)
  • 2 – means EXPORT (HWI_CMD_PROFILE_EXPORT)
    AreaNumber A 2-byte integer area number is required and must be in the range of 1 to 4.
RESERVE HWI_CMD_RESERVE_PARM ReserveType A 4-byte integer (required):
  • 1 – means ADD (HWI_CMD_RESERVE_ ADD)
  • 2 – means DELETE (HWI_CMD_RESERVE_DELETE)
    ApplName An 8-character application name (required) padded with trailing blanks.
SYSRESET HWI_CMD_SYSRESET_PARM ResetType A 4-byte integer (required):
  • 1 – means NORMAL (HWI_CMD_RESET_NORMAL)
  • 2 – means CLEAR (HWI_CMD_RESET_CLEAR)
    ForceType A 4-byte integer (optional, the default is FORCE):
  • 1 – means Force YES (HWI_CMD_FORCE)
  • 2 – means Force NO (HWI_CMD_NOFORCE)
Note: Only a ForceType of HWI_CMD_FORCE will result in a successful sysreset of the target CPC or image if the target CPC or image is already active.
START 0 N/A N/A
STOP 0 N/A N/A
PSWRESTART 0 N/A N/A
OSCMD HWI_CMD_OSCMD_PARM PriorityType A 4-byte integer (required):
  • 1 – means Priority (HWI_CMD_PRIORITY)
  • 2 – means Non-Priority (HWI_CMD_NONPRIORITY)
    Note: For WTOR replies targeting a z/OS image, a PriorityType of Non-Priority may need to be specified to allow z/OS to receive the reply command.
    OSCMDString A 126-null-terminated character operating system command string (required).
LOAD HWI_CMD_LOAD_PARM LoadAddr A 4-character string consisting only of hexadecimal characters identifying the device address to be used when performing the load (optional).
    LoadParm An 8-character string as determined by the operating system being loaded (optional).
    ForceType A 4-byte integer (optional, the default is FORCE):
  • 1 – means Force YES (HWI_CMD_FORCE)
  • 2 – means Force NO (HWI_CMD_NOFORCE)
Note: Only a ForceType of HWI_CMD_FORCE will result in a successful load of the target CPC or image if the target CPC or image is already active.
TEMPCAP HWI_CMD_TEMPCAP_Parm TEMPCAPType A 4-byte integer (required):
  • 1 – means Add (HWI_CMD_TEMPCAP_ADD)
  • 2 – means Remove (HWI_CMD_TEMPCAP_REMOVE)
    XML_Ptr (non-REXX) A character string pointer that points to the address of the XML information that illustrates the markup used to perform activation of the temporary capacity (required).
    XML (REXX) XML information that illustrates the markup used to perform activation of the temporary capacity (required).
    XML_Size (non-REXX) A 4-byte integer (required).

Length in bytes of the XML that the XML_Ptr points to.
SYSRESET

_IPLT

 HWI_CMD_SYSRESET

_IPLT_PARM

 ResetType A 4–byte integer (required):
  • 1 – means NORMAL (HWI_CMD_RESET_NORMAL)
  • 2 – means CLEAR (HWI_CMD_RESET_CLEAR)
    ForceType A 4-byte integer (optional, the default is FORCE):
  • 1 – means Force YES (HWI_CMD_FORCE)
  • 2 – means Force NO (HWI_CMD_NOFORCE)
Note: Only a ForceType of HWI_CMD_FORCE will result in a successful sysreset of the target CPC or image if the target CPC or image is already active.
    IPL_Token_Ptr (non-REXX) A character string pointer that specifies the address of the IPL token used to correlate a SYSRESET with other outstanding HMC-related activities. This ensures that this SYSRESET is operating with the same IPL instance as when the IPL_Token was retrieved (required).
    IPL_Token (REXX) IPL token used to correlate a SYSRESET with other outstanding HMC-related activities. This ensures that this SYSRESET is operating with the same IPL instance as when the IPL_Token was retrieved (required).
    IPL_Token_Len (non-REXX) A 4-byte integer (required).

Length in bytes of the IPL token to which the IPL_Token_Ptr points.
ACTIVATE_ WITH

_ACTPROF

 HWI_CMD_ACT_WITH_ ACTPROF_PARM ActProfName A 16–character activation profile name padded with trailing blanks (required).
    ForceType A 4-byte integer (optional, the default is FORCE):
  • 1 – means Force YES (HWI_CMD_FORCE)
  • 2 – means Force NO (HWI_CMD_NOFORCE)
Note: Only a ForceType of HWI_CMD_FORCE will result in a successful activation of the target CPC or image if the target CPC or image is already active.
POWER

_CONTROL

 HWI_CMD_POWER

_CONTROL_PARM

 XML_Ptr (non-REXX) A character string pointer that points to the address of the XML fragment describing the power characteristics to be applied to the CPC specified by the connect token (required).
    XML (REXX ) XML fragment describing the power characteristics to be applied to the CPC specified by the connection token (required).
    XML_Size (non-REXX) A 4-byte integer (required).

Length in bytes of the XML that the XML_Ptr points to.
SCSI_LOAD HWI_CMD_SCSI_LOAD_PARM LoadAddr A 4-character string (optional) consisting only of hexadecimal characters (0-9, A-F) identifying the device address to be used when performing the SCSI load. Defaults to value last used when previous SCSI Load was performed.
    LoadParm An 8-character string (optional) as determined by the operating system being loaded. Defaults to value last used when previous SCSI Load was performed.
    WW_Portname A 16-character string (optional) identifying the World Wide Port Name to be used when performing a SCSI Load. Defaults to value last used when previous SCSI Load was performed. The character string must be comprised of hexadecimal values only (0-9, A-F).
    LU_Num A 16-character string (optional) identifying the logical unit number (LUN) to be used when performing the SCSI Load. Defaults to value last used when previous SCSI Load was performed. The character string must be comprised of hexadecimal values only (0-9, A-F).
    Boot_Pgm_Selector A 4-byte integer (optional) identifying the boot program selector to be used for the SCSI Load. Defaults to value last used when previous SCSI Load was performed.
    Opsys_Loadparm A 256-character string (optional) representing the operating system-specific load parameters to be used for the SCSI Load. Defaults to value last used when previous SCSI Load was performed.
    Bootrec_Blk_Addr A 16-character string (optional) representing the boot record logical block address to be used for the SCSI Load. Defaults to value last used when previous SCSI Load was performed. The character string must be comprised of hexadecimal values only (0-9, A-F).
    ForceType A 4-byte integer (optional, the default is FORCE):
  • 1 – means Force YES (HWI_CMD_FORCE)
  • 2 – means Force NO (HWI_CMD_NOFORCE)
Note: Only a ForceType of HWI_CMD_FORCE will result in a successful load of the target CPC or image if the target CPC or image is already active.
SCSI_DUMP HWI_CMD_SCSI_DUMP_PARM LoadAddr A 4-character string (optional) consisting only of hexadecimal characters (0-9, A-F) identifying the device address to be used when performing the SCSI Dump. Defaults to value last used when previous SCSI Dump was performed.
    LoadParm An 8-character string (optional) used when performing the SCSI dump. Defaults to value last used when previous SCSI Dump was performed.
    WW_Portname A 16-character string (optional) identifying the World Wide Port Name to be used when performing a SCSI Dump. Defaults to value last used when previous SCSI Dump was performed. The character string must be comprised of hexadecimal values only (0-9, A-F).
    LU_Num A 16-character string (optional) identifying the logical unit number (LUN) to be used when performing the SCSI Dump. Defaults to value last used when previous SCSI Load was performed. The character string must be comprised of hexadecimal values only (0-9, A-F).
    Boot_Pgm_Selector A 4-byte integer (optional) identifying the boot program selector to be used for the SCSI Dump. Defaults to value last used when previous SCSI Load was performed.
    Opsys_Loadparm A 256-character string (optional) representing the operating system-specific load parameters to be used for the SCSI Dump. Defaults to value last used when previous SCSI Dump was performed.
Note: If less than 256 bytes, a null terminator signifies the end of the string.
    Bootrec_Blk_Addr A 16-character string (optional) representing the boot record logical block address to be used for the SCSI Dump. Defaults to value last used when previous SCSI Dump was performed. The character string must be comprised of hexadecimal values only (0-9, A-F).
    ForceType A 4-byte integer (optional, the default is FORCE):
  • 1 – means Force YES (HWI_CMD_FORCE)
  • 2 – means Force NO (HWI_CMD_NOFORCE)

Currently, either ForceType value listed above will cause the same result. The target image will be dumped in either case. IBM recommends that an application omit this parameter.
SYSPLEX_TIME _SWAP_CTS HWI_CMD_SYSPLXTIME_SWAP _CTS_PARM STP_ID An 8-character non-terminated string (required) representing the current STP identifier associated with this CPC.
SYSPLEX_TIME _SET_STP _CONFIG HWI_CMD_SYSPLXTIME_SET _STP_CONFIG_PARM STP_ID An 8-character non-terminated string (required) representing the current STP identifier associated with this CPC.
    ForceType A 4-byte integer (required):
  • 1 – means Force YES (HWI_CMD_FORCE)
  • 2 – means Force NO (HWI_CMD_NOFORCE)
    XML_Ptr (non-REXX) A character string pointer (required) points to the address of the XML fragment describing the configuration for the STP-only CTN.
    XML (REXX) XML fragment describing the configuration for the STP-only CTN. (required)
    XML_Size (non-REXX) A 4-byte integer (required).

Length in bytes of the XML that the XML_Ptr points to.
SYSPLEX_TIME _CHANGE_STP _ONLY_CTN HWI_CMD_SYSPLXTIME_CHG _STPONLYCTN_PARM STP_ID An 8-character non-terminated string (required) representing the desired STP identifier for the CPC and all CPCs that are members of the same STP-only CTN.
SYSPLEX_TIME _JOIN_STP _ONLY_CTN HWI_CMD_SYSPLXTIME_JOIN _STPONLYCTN_PARM STP_ID An 8-character non-terminated string (required) representing the current STP identifier for the CPC.
SYSPLEX_TIME _LEAVE_STP _ONLY_CTN 0 N/A N/A
End of change
DiagArea (non-REXX)
DiagArea. (REXX)
Returned parameter
  • Type: Character string (non-REXX), stem variable (REXX)
  • Length: 32 bytes (non-REXX)
DiagArea contains diagnostic data to help determine the cause of a failure from the service. For many return codes, the DiagArea can contain further information to help determine the cause of the failure. See the descriptions of different return codes for a partial list of data returned in this area.
Note: For all environmental errors (with return code X'F00' and higher), the DiagArea might not be filled in, and the data returned in the area should be ignored.
Field Name (non-REXX) / Tail name constant of the user-defined DiagArea stem (REXX) Field Type (non-REXX) Description
Diag_Index 32-bit integer The array index to the parameter field that causes the error.
Diag_Key 32-bit integer The constant value represents the field that causes the error.
Diag_Actual 32-bit integer The incorrect actual value that is specified.
Diag_Expected 32-bit integer The expected value to be used.
Diag_CommErr 32-bit integer The returned code that is returned from the console application API or the BCPii transport layer.
Diag_Text Character (12) Additional diagnostic information in text format.

See BCPii communication error reason codes for a partial list of the descriptive communication transport error return codes and suggested actions.

Parent topic: Description
End of change

Go to the previous page Go to the next page

Notices | Terms of use | Support | Contact z/OS | zFavorites



Copyright IBM Corporation 1990, 2014