IWM4HLTH — Setting server health indicator

The IWM4HLTH service is used to inform WLM about the health state of a server. The health indicator is a number which shows, in percent, how well the server is performing. It can be an integer value between 0 and 100.
Value
Meaning
100
The server is fully capable to do work without any health problems.
0
The server is not able to do any work.
Any value between 0 and 100
Indicates the level of health of the server.

IWM4HLTH provides two functions: SET and RESET. With the SET function, which is the main intended use and default function, a caller informs WLM about its view of the health state of a server. WLM then sets the server's health indicator to the minimum number of all the current settings from the different callers of the service since the last RESET.

The RESET function primarily refers to reliability, availability, and serviceability (RAS) considerations regarding a server's health state. RESET restarts setting the health indicator by specifying an initial value and discarding any values reported by other callers before.

Callers can identify themselves by a subsystem type and subsystem name. The service uses these parameters to recognize different callers of the service. If no subsystem type is passed, the job name of the caller address space is used instead. This information will then also be available to callers of the IWM4QHLT (Query Server Health Indicators) service.

The health indicator is activated when one of the routing services IWM4SRSC or IWMSRSRS with FUNCTION=SPECIFIC are used to get routing recommendations. The weights are reduced to the percentage given by the health indicator of the server address space.

The health indicator of a server keeps its value until it is modified by resetting it with the IWM4HLTH service, or with the IWMSRSRG service.

Environment

The requirements for the caller are:

Minimum authorization:

FUNCTION=SET:

Problem state with any PSW key if the address space token specified with STOKEN=stoken equals the address space token of the home address space. That is, the caller provides a health indicator for itself. When providing a health indicator for an address space other than the home address space, the minimum authorization is one of the following:
  • Supervisor state.
  • Program key mask (PKM) allowing at least one of the keys 0-7.
  • The caller has UPDATE authority to the resource IWM.SERVER.HEALTH in the FACILITY class.

FUNCTION=RESET:

The minimum authorization is one of the the following:
  • Supervisor state.
  • Program key mask (PKM) allowing at least one of the key 0-7.
  • The caller has CONTROL authority to the resource IWM.SERVER.HEALTH in the FACILITY class.
Dispatchable unit mode: Task or SRB
Cross memory mode: Any PASN, any HASN, any SASN
AMODE: 31-bit or 64-bit. If in 64-bit addressing mode, code SYSSTATE AMODE64=YES before invoking this macro.
ASC mode: Primary
Interrupt status: Enabled for I/O and external interrupts
Locks: The caller may hold locks, but is not required to hold any. FRRs may be established.
Control parameters: Control parameters must be in the primary address space.

Programming requirements

  1. The macro CVT must be included to use this macro.
  2. The macro IWMYCON must be included to use this macro.
  3. The macro IWMPB must be in the library concatenation, since it is included by IWMYCON.
  4. Note that the high-order halfword of register 0, and the reason code variable when specified, may be non-zero and represents diagnostic data which is NOT part of the external interface. The high-order halfword should thus be excluded from comparison with the reason code values described above. The constant, IWMRSNCODE_MASK_CONST defined in IWMYCON, may be used for this purpose.
  5. All character data, unless otherwise specified, is assumed to be left-justified and padded with blanks on the right, as needed, to occupy the specified number of bytes.

Restrictions

This macro supports multiple versions. Some keywords are unique to certain versions. See the PLISTVER parameter description.

Input register information

Before issuing the IWM4HLTH macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller, the GPRs contain:
Register
Contents
0
Reason code if GR15 return code is non-zero
1
Used as work register by the system
2-13
Unchanged
14
Used as work registers by the system
15
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as work registers by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

The syntax of the IWM4HLTH macro is as follows:

Read syntax diagramSkip visual syntax diagramnameIWM4HLTHSTOKEN= stoken,FUNCTION=SET,FUNCTION=RESET,HEALTH= health,SUBSYS=NO_SUBSYS,SUBSYS= subsys,SUBSYSNM=NO_SUBSYSNM,SUBSYSNM= subsysnm,HEALTHRSN=NO_RSN,HEALTHRSN= healthrsn,RETCODE= retcode,RSNCODE= rsncode,PLISTVER=IMPLIED_VERSION,PLISTVER=MAX,PLISTVER=0,PLISTVER=1,MF=S,MF=(L, list addr,0D, attr),MF=(E, list addr,COMPLETE)

Parameters

The parameters are explained as follows:
STOKEN
A required input parameter which contains the space token of the server.

To code: Specify the RS-type address, or address in register (2)-(12), of a 64 bit field.

FUNCTION
An optional parameter which indicates the function to perform. The default is FUNCTION=SET.
FUNCTION=SET
Informs WLM about the caller's view of the health state of a server. WLM then sets the server's health indicator to the minimum number of all the current settings from the different callers of the service since the last RESET.
FUNCTION=RESET
Restarts setting the health indicator by specifying an initial value and discarding any values reported by other callers before. RESET primarily refers to reliability, availability, and serviceability (RAS) considerations regarding a server's health state.
HEALTH
A required input parameter, which contains the health indicator associated with the address space. This value is the percentage up to which this address space is capable to handle requests.

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field.

SUBSYS
An optional input parameter which contains the generic name or type of the caller of the service. It is used by WLM together with the SUBSYSNM parameter to recognize different callers of this service. This data is also available to callers of the IWM4QHLT service.

The default is NO_SUBSYS which indicates that no type was passed.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

SUBSYSNM
An optional input parameter which contains the name of a specific instance of the caller of the service. It is used by WLM together with the SUBSYS parameter to recognize different callers of this service. This data is also available to callers of the IWM4QHLT service.

The default is NO_SUBSYSNM which indicates that no name was passed.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

HEALTHRSN
An optional input parameter that allows the caller to pass additional information, such as the reason for changing the health indicator. This data is available to callers of the IWM4QHLT service.

The format is undefined. The default is NO_RSN which indicates that no additional information is passed.

To code: Specify the RS-type address or address in register (2)-(12) of an of an 16-character field.

RETCODE
An optional output parameter into which the return code is to be copied from GPR 15.

To code: Specify the RS-type address or address in register (2)-(12) of a fullword field.

RSNCODE
An optional output parameter into which the reason code is to be copied from GPR 0.

To code: Specify the RS-type address or address in register (2)-(12) of a fullword field.

,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
,PLISTVER=1
An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:
IMPLIED_VERSION
The lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
MAX
Indicates that you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.

If you can tolerate the size change, IBM® recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.

0
Indicates to use version 0 of the macro, which supports all parameters except those specifically identified in higher versions.
1
Supports the following parameters and those from version 0:
  • FUNCTION
  • SUBSYS
  • SUBSYSNM
  • HEALTHRSN
To code: Specify one of the following:
  • IMPLIED_VERSION
  • MAX
  • A decimal value of 0 or 1
,MF=S
,MF=(L,list addr)
,MF=(L,list addr,attr)
,MF=(L,list addr,0D)
,MF=(E,list addr)
,MF=(E,list addr,COMPLETE)
An optional input parameter that specifies the macro form.

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.

Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.
,list addr
The name of a storage area to contain the parameters. For MF=S and MF=E, this can be an RS-type address or an address in register (1)-(12).
,attr
An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.

ABEND codes

None.

Return codes and reason codes

When the IWM4HLTH macro returns control to your program:
  • GPR 15 (and retcode, if you coded RETCODE) contains a return code.
  • When the value in GPR 15 is not zero, GPR 0 (and rsncode, if you coded RSNCODE) contains reason code.
Table 1 identifies the hexadecimal return and reason codes and the equate symbol associated with each reason code. IBM support personnel may request the entire reason code, including the xxxx value.
Table 1. Return codes and reason codes for the IWM4HLTH Macro
Return code Reason code Equate symbol, meaning, and action
0 Equate symbol: IwmRetCodeOk

Meaning: Successful completion.

Action: None required.

8 Equate symbol: IwmRetCodeInvocError

Meaning: Invalid invocation environment or parameters.

8 xxxx0807 Equate symbol: IwmRsnCodeBadSTOKEN

Meaning: Bad STOKEN passed.

Action: Check for possible storage overlay.

8 xxxx080B Equate symbol: IwmRsnCodeBadPl

Meaning: Error accessing parameter list.

Action: Check for possible storage overlay.

8 xxxx0823 Equate symbol: IwmRsnCodeDatoff

Meaning: The caller invoked the service while DATOFF

Action: Avoid requesting this function in this environment.

8 xxxx0824 Equate symbol: IwmRsnCodeAmode24

Meaning: The caller invoked the service but was in 24-bit addressing mode.

Action: Request this function only when you are in 31-bit addressing mode.

8 xxxx0825 Equate symbol: IwmRsnCodeAscModeNotPrimary

Meaning: The caller invoked the service but was not DAT on Primary ASC mode.

Action: Avoid requesting this function in this environment.

8 xxxx0827 Equate symbol: IwmRsnCodeRsvdNot0

Meaning: Reserved field in parameter list was non-zero.

Action: Check for possible storage overlay of the parameter list.

8 xxxx0828 Equate symbol: IwmRsnCodeBadVersion

Meaning: The version number in the parameter list or the version length field is not valid. Or this service was called on a z/OS® release where it is not supported.

Action: Check for possible storage overlay of the parameter list.

8 xxxx0829 Equate symbol: IwmRsnCodeBadOptions

Meaning: Parameter list omits required parameters, supplies mutually exclusive parameters, or provides data associated with options not selected.

Action: Check for possible storage overlay of the parameter list.

8 xxxx08A2 Equate symbol: IwmRsnCodeBadHealth

Meaning: Health Value out of range

Action: Check for possible storage overlay.

C Equate symbol: IwmRetCodeEnvError

Meaning: Environmental error.

C xxxx0C01 Equate symbol: IwmRsnCodeNoStg

Meaning: Storage is not available for the request.

Action: There is a storage shortage. The function may work successfully at a later time.

C xxxx0C0E Equate symbol: IwmRsnCodeInsufAccess

Meaning: Minimum authorization requirements are not fulfilled.

Action: Invoke the service with one of the following authorization requirements fulfilled:
  • Change the caller's authorization to supervisor state or PKM allowing at least one of the keys 0-7.
  • Give the user ID associated with the program UPDATE authority to the resource profile IWM.SERVER.HEALTH.
10 Equate symbol: IwmRetCodeCompError

Meaning: Component error.

Action: No action required. The function may be successful if invoked again.

Example

To set the health indication value for a particular server, specify:
         IWM4HLTH STOKEN=STKN
                  HEALTH=HLTH
                  RETCODE=RC,RSNCODE=RSN
*
* Storage areas
*
STKN     DS    CL8             Contains the STOKEN
*                              associated with the address
*                              space
HLTH     DS    F               Field to input the health value
RC       DS    F               Return code
RSN      DS    F               Reason code