Parameters

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.

InConnectToken

Supplied parameter

Type: Character string
Length: 16 bytes

InConnectToken represents a connect token that was returned by a previous HWICONN HWI_CPC invocation. For image, capacity record, activation profile, and user-defined image group connections, the input connection token must represent an active CPC connection.

Start of change In most cases, the ConnectToken specified must have originated from a HWICONN service call that was issued from the same address space as this service call. For BCPii REXX execs running under TSO/E or ISV-provided REXX environments, the ConnectToken specified must have originated from a HWICONN service call that was issued from the same task as this service call. End of change

InConnectToken is not relevant to a connect type of HWI_CPC, and it is ignored.

OutConnectToken

Returned parameter

Type: Character string
Length: 16 bytes

OutConnectToken returns a connect token that uniquely represents a connection to BCPii. This parameter can be used as input on subsequent BCPii invocations to identify which connection the service wants to communicate.

A connect token returned for an HWI_CPC connection can be specified on subsequent services to perform operations against this particular CPC, or on a subsequent HWICONN as the InConnectToken parameter when attempting a connection to a particular image (LPAR), capacity record (CAPREC), or activation profile.

Likewise, a connect token returned for an HWI_IMAGE or HWI_CAPREC connection can be specified on subsequent services to perform operations against this particular image (LPAR) or capacity record (CAPREC) respectively.

A connect token returned for an HWI_RESET_ACTPROF, HWI_IMAGE_ACTPROF, or HWI_LOAD_ACTPROF connection can be specified on subsequent HWIQUERY or HWISET service calls to query or set specific values associated with the specified Reset, image, or Load activation profile respectively.

A connection token returned for an HWI_IMAGE_GROUP can be specified on a subsequent HWIQUERY service call to query values associated with the group profile, on a subsequent HWICMD service call to issue commands to all members in the image group, or on a subsequent HWILIST service call to list the images in the image group.

ConnectType

Supplied parameter

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

ConnectType specifies the type of connection to be established.

Constant in Hexadecimal (Decimal) Equate Symbol	Description
1 (1) HWI_CPC	Requests to establish a connection to a target CPC that the application is to communicate with.
2 (2) HWI_IMAGE	Requests to establish a connection to an image of a CPC that the application is to communicate with. The input connection token must represent an active CPC connection.
3 (3) HWI_CAPREC	Requests to establish a connection to a capacity record of a CPC that the application is to communicate with. The input connection token must represent an active CPC connection.
4 (4) HWI_RESET_ACTPROF	Requests to establish a connection to a reset activation profile associated with a particular CPC. The input connection token must represent an active CPC connection.
5 (5) HWI_IMAGE_ACTPROF	Requests to establish a connection to an image activation profile associated with a particular CPC. The input connection token must represent an active CPC connection.
6 (6) HWI_LOAD_ACTPROF	Requests to establish a connection to a load activation profile associated with a particular CPC. The input connection token must represent an active CPC connection.
7 (7) HWI_IMAGE_GROUP	Requests to establish a connection to a user-defined image group on a particular CPC. The input connection token must represent an active CPC connection. Note: This ConnectType is only available when targeting a z10 or higher CPC.

ConnectTypeValue_Ptr (non-REXX)

ConnectTypeValue (REXX)

Supplied parameter

Type: Pointer (non-REXX), character (REXX)
Length: 4 bytes (non-REXX)

Non-REXX:: ConnectTypeValue_Ptr specifies the address of the name of the requested target to be connected to. The type of connection determines the value required.
REXX:: ConnectTypeValue is the name of the requested target to be connected to. The type of connection determines the value required.

Connect Types	Values to be specified
HWI_CPC	A 17-character network address (sometimes referred to as the SNA address) that uniquely represents a CPC in the attached process control network. The network address should be in the form of a 1- through 8-character network identifier (netid), followed by a period, and then followed by a 1- through 8-character network addressable unit (NAU) name. The network address should be padded with trailing blanks if the total string length of the network address is less than 17 characters. Example: net1.cpc01 Note: netid.nau is 1- to 17- character symbolic NAU name. The network ID and name of a resource must both begin with a letter (A-Z), @, #, or $. The remaining characters can be letters (A-Z), numbers (0-9), @, #, or $. An ‘’ is a special value that can also be specified with this ConnectType. If specified, this allows the application to connect to the local host CPC without having to know the network address of the local host CPC (netid.nau). Note: An HWILIST HWI_LIST_CPCS operation returns a list of CPCs available to be connected to in the form of netid.nau*.
HWI_IMAGE	An 8-character image name padded with trailing blanks. Note: The LPAR name is a 1- through 8-alphanumeric (0-9, A-Z) character name that must have an alphabetic first character. Special characters ($, #, @), although currently allowed, are being reserved for future use. See PR/SM Planning Guide for details.
HWI_CAPREC	An 8-character capacity record (CAPREC) name padded with trailing blanks. Note: The CAPREC name is a 1- through 8-alphanumeric (0-9, A-Z) character name.
HWI_RESET_ACTPROF	A 16–character alphanumeric (0-9, A-Z) reset activation profile name padded with trailing blanks.
HWI_IMAGE_ACTPROF	A 16–character alphanumeric (0-9, A-Z) image activation profile name padded with trailing blanks.
HWI_LOAD_ACTPROF	A 16–character alphanumeric (0-9, A-Z) load activation profile name padded with trailing blanks.
HWI_IMAGE_GROUP	A 30 character null-terminated image group name.

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.