IWM4HLTH — Setting server health indicator
- 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:
FUNCTION=RESET: The minimum authorization is one
of the the following:
|
---|---|
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
- The macro CVT must be included to use this macro.
- The macro IWMYCON must be included to use this macro.
- The macro IWMPB must be in the library concatenation, since it is included by IWMYCON.
- 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.
- 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
- 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
- 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:
Parameters
- 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
- 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.
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:
|
10 | — | Equate symbol: IwmRetCodeCompError Meaning: Component error. Action: No action required. The function may be successful if invoked again. |
Example
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