IWMMEXTR — Monitoring environment extract
The purpose of this service is to extract information about the monitoring environment which was previously passed through IWM4MINI/IWMMRELA. When IWMMRELA was invoked for a management monitoring environment, owner token, owner data and abnormal conditions are always available. Arrival time, user ID and transaction name are only available when IWM4MINI was previously invoked. Arrival time, however, is only available for management monitoring environments.
When the service class token is requested for a management monitoring environment, the value may represent a token from a prior active policy. Furthermore, when the monitoring environment was established via IWMMRELA, the token may be zero, which does not represent a valid service class or report class. IWMWQRY may be used to obtain the service and/or report class name, along with other information about these classes. The SERVCLS keyword is not applicable for report-only monitoring environments. The returned token is zero, which does not represent a valid service class.
The ENCLAVE_TOKEN and ASID keywords are only applicable for report-only monitoring environments.
The EWLM_S_CURCORR keyword should only be specified, if a work unit has been started by IWMMSTRT.
When no output keywords are specified, the service merely checks whether a monitoring environment was established and passes short form checking.
Environment
The requirements for the caller are:
Minimum authorization: | Either problem state or supervisor state. Any PSW key. |
---|---|
Dispatchable unit mode: | Task or SRB |
Cross memory mode: | Any PASN, any HASN, any SASN |
AMODE: | 31-bit |
ASC mode: | Primary |
Interrupt status: | Enabled for I/O and external interrupts |
Locks: | Suspend locks are allowed. |
Control parameters: | Control parameters must be in the primary address space. |
Programming requirements
- 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.
Restrictions
- The caller is responsible for error recovery
- Only limited checking is done against the input monitoring token.
- If the key specified on IWM4MCRE was a user key (8-F), then the primary addressability must exist to the performance block IWM4MCRE obtained. This condition is satisfied by ensuring that current primary matches primary at the time that IWM4MCRE was invoked. If this service is invoked in a subspace, the condition may be satisfied by ensuring that the performance block is shared with the base space.
- The caller must serialize to prevent any delay monitoring services from being invoked concurrently for the environment represented by the monitoring token.
- This macro supports multiple versions. Some keywords are only supported by certain versions. Refer to the PLISTVER parameter description for further information.
Input register information
Before issuing the IWMMEXTR 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 registers 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 IWMMEXTR macro is as follows:
Parameters
- name
- An optional symbol, starting in column 1, that is the name on the IWMMEXTR macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
- ,ABNORMAL_COND=abnormal_cond
- An optional output parameter, which contains the current information
about abnormal conditions which were either recorded in the input
monitoring environment or which were propagated to it via IWMMXFER
Function(Return). Multiple conditions may exist.
The mask, Iwmmabnl_Scope_LocalMVS, may be used to determine whether an abnormality which only affects work on the current MVS™ image was recorded.
The mask, Iwmmabnl_Scope_Sysplex, may be used to determine whether an abnormality which affects work on all MVS images in the sysplex was recorded.
To determine whether a condition was recorded, merely AND the field supplied for ABNORMAL_COND with the relevant mask. The result will be nonzero when the condition is true, zero when the condition is false.
To code: Specify the RS-type address, or address in register (2)-(12), of a 32 bit field.
- ,ARRIVALTIME=arrivaltime
- An optional output parameter, which contains the work arrival
time in STCK format.
To code: Specify the RS-type address, or address in register (2)-(12), of a 64-bit field.
- ,ASID=asid
- An optional output parameter,which contains the address
space ID. When the monitoring environment is not associated with an
address space, the output will be a halfword of binary zeros.
To code: Specify the RS-type address, or address in register (2)-(12), of a 16-bit field.
- ,ENCLAVE_TOKEN=enclave_token
- An optional output parameter, which contains the enclave token.
When the monitoring environment is not associated with an enclave,
the output will be a doubleword of binary zeros.
To code: Specify the RS-type address, or address in register (2)-(12),of a 64 bit field.
- ,EWLM_CHCORR=ewlm_chcorr
- An optional output parameter, which contains the cross-platform
Enterprise Workload Management (EWLM) correlator of the work request
associated with the monitoring environment.
To code: Specify the RS-type address, or address in register (2)-(12), of a character field.
- ,EWLM_PACTKN=ewlm_pactkn
- An optional output parameter, which contains the cross-platform
Enterprise Workload Management (EWLM) parent correlator token of the
work request associated with the monitoring environment.
To code: Specify the RS-type address, or address in register (2)-(12), of a character field.
- ,EWLM_S_CURCORR=ewlm_s_curcorr
- An optional output parameter, which contains the current correlator
of the work unit started by IWMMSTRT. Normally this correlator is
different from the child correlator of the work request created by
IWM4MINI.
To code: Specify the RS-type address, or address in register (2)-(12), of a character field.
- MONTKN=montkn
- A required input parameter, which contains the delay monitoring
token
To code: Specify the RS-type address, or address in register (2)-(12), of a 32 bit field.
- ,OWNER_DATA=owner_data
- An optional output parameter, which is to receive the data established
by the user/owner of the monitoring environment. The format is undefined
to MVS. When the monitoring environment
is not associated with an OWNER_TOKEN value, the output will be a
word of binary zeros.
To code: Specify the RS-type address, or address in register (2)-(12), of a 32 bit field.
- ,OWNER_TOKEN=owner_token
- An optional output parameter, which is to receive the token established
by the user/owner of the monitoring environment. The format is undefined
to MVS. When the monitoring environment
is not associated with an OWNER_TOKEN value, the output will be a
word of binary zeros.
To code: Specify the RS-type address, or address in register (2)-(12), of a 32 bit field.
- ,PLISTVER=IMPLIED_VERSION
- ,PLISTVER=MAX
- ,PLISTVER=0
- ,PLISTVER=1
- ,PLISTVER=3
- 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, which is 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, if 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; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
- 0, which supports all parameters except those specifically referenced in higher versions.
- 1, which supports the following parameter and those from
version 0: TTRACETOKEN
- 2, which supports the following parameters and those from
version 0 and 1: ASID
ENCLAVE_TOKEN - 3, which supports the following parameters and those from
version 0, 1, and 2: EWLM_CHCORR
EWLM_PACTKN - 4, which supports the following parameter and those from
version 0, 1, 2, and 3: EWLM_S_CURCORR
To code: Specify one of the following:- IMPLIED_VERSION
- MAX
- A decimal value of 0, 1, 2, 3, or 4
- ,RETCODE=retcode
- An optional output parameter into which the return code is to
be copied from GPR 15.
To code: Specify the RS-type address of a fullword field, or register (2)-(12).
- ,RSNCODE=rsncode
- An optional output parameter into which the reason code is to
be copied from GPR 0.
To code: Specify the RS-type address of a fullword field, or register (2)-(12).
- ,SERVCLS=servcls
- An optional output parameter, which contains the service class
token. When the monitoring environment is not associated with a service
class token, the output will be a word of binary zeros.
To code: Specify the RS-type address, or address in register (2)-(12), of a 32 bit field.
- ,TRXNAME=trxname
- An optional output parameter, which contains the transaction name.
The field will be all blanks when NO_TRXNAME was specified on IWM4MINI.
To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.
- ,TTRACETOKEN=ttracetoken
- An optional output parameter, which contains the transaction trace
token associated with the work request. The field will be all zero
when NO_TTRACETOKEN was specified on IWM4MINI.
To code: Specify the RS-type address, or address in register (2)-(12), of a 32-character field.
- ,USERID=userid
- An optional output parameter, which contains the local user ID
associated with the work request. The field will be all blanks when
NO_USERID was specified on IWM4MINI.
To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.
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.
The following table 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.
Return code | Reason code | Equates symbol, meaning, and action |
---|---|---|
0 | — | Equate Symbol: IwmRetCodeOk Meaning: Successful completion. Action: None required. |
4 | — | Equate Symbol: IwmRetCodeWarning Meaning: Successful completion, unusual conditions noted. |
4 | xxxx0402 | Equate Symbol: IwmRsnCodeNoMonEnv Meaning: Monitoring token indicates that no monitoring environment exists. Action: None required. |
4 | xxxx040C | Equate Symbol: IwmRsnCodeMonEnvLacksInfo
Meaning: Input monitoring environment does not contain the necessary information to return the data requested. Action: None required. |
8 | — | Equate Symbol: IwmRetCodeInvocError Meaning: Invalid invocation environment or parameters. |
8 | xxxx0820 | Equate Symbol: IwmRsnCodeBadMonEnv Meaning: Monitoring environment does not pass short form verification. Action: Check for possible storage overlay. |
8 | xxxx0895 | Equate Symbol: IwmRsnCodeEWLMServNotEnabled
Meaning: Service is not enabled because monitoring environment can not be associated with EWLM work requests. Action: Specify the parameter EWLM_CHCORR or EWLM_PACTKN only when the monitoring environment is created with IWMMCREA EWLM=YES or the address space is connected with IWMCONN EWLM=YES and the connect token is passed to IWMMCREA when creating the monitoring environment. |
8 | xxxx08AC | Equate Symbol: IwmRsnCodeTranNotStarted
Meaning: A work unit has not been started. Action: Start a work unit by IWMMSTRT macro, before specifying the EWLM_S_CURCORR parameter. |