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

  1. The macro IWMYCON must be included to use this macro.
  2. The macro IWMPB must be in the library concatenation, since it is included by IWMYCON.
  3. 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

  1. The caller is responsible for error recovery
  2. Only limited checking is done against the input monitoring token.
  3. 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.
  4. The caller must serialize to prevent any delay monitoring services from being invoked concurrently for the environment represented by the monitoring token.
  5. 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

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 registers 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 IWMMEXTR macro is as follows:

Read syntax diagramSkip visual syntax diagramnameIWMMEXTRMONTKN= montkn,OWNER_TOKEN= owner_token,OWNER_DATA= owner_data,ARRIVALTIME= arrivaltime,TRXNAME= trxname,USERID= userid,SERVCLS= servcls,ASID= asid,ENCLAVE_TOKEN= enclave_token,TTRACETOKEN= ttracetoken,ABNORMAL_COND= abnormal_cond,EWLM_CHCORR= ewlm_chcorr,EWLM_PACTKN= ewlm_pactkn,EWLM_S_CURCORR= ewlm_s_curcorr,RETCODE= retcode,RSNCODE= rsncode,PLISTVER=IMPLIED_VERSION,PLISTVER=MAX,PLISTVER=0,PLISTVER=1,PLISTVER=2,PLISTVER=3,PLISTVER=4,MF=(M, list addr,COMPLETE,NOCHECK)

Parameters

The parameters are explained as follows:
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

When the IWMMEXTR 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.

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.

Table 1. Return and Reason Codes for the IWMMEXTR Macro
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.