IWMWMCON — WLM modify connect

The purpose of this service is to modify a particular connection to WLM with respect to the associated subsystem type and/or name for work manager services, described below, and so could replace the use of the pair of services disconnect (IWM4DIS) and connect (IWM4CON) for the new values of subsystem type and/or name. This change only affects work manager related services, and does not affect the subsystem identify for queue manager or server manager services. For this reason, the caller must be connected to the WLM work management services, i.e. IWM4CON WORK_MANAGER=YES must be specified. Queue manager and/or server manager may also be specified at connect, but are not affected by use of IWMWMCON. The PSW key and topology list associated with the connect may not be changed via this service.

Use of this service needs to be coordinated with the use of other work manager services which depend on the connect token and the associated subsystem related information to ensure that the desired results are obtained. Among these services are classify (IWMCLSFY), report (IWMRPT), notify (IWMMNTFY) where it is an optional input, and enclave create (IWM4ECRE). Note that use of IWMWMCON is not appropriate prior to creation of enclaves with TYPE(Dependent) or TYPE(Montkn).

Environment

The requirements for the caller are:

Minimum authorization: Supervisor state or program key mask (PKM) allowing keys 0-7.
Dispatchable unit mode: Task or SRB
Cross memory mode: Any P,S. Current Home address space must be the same as Home when the corresponding Connect was invoked.
AMODE: 31-bit
ASC mode: Primary
Interrupt status: Enabled for I/O and external interrupts
Locks: No locks may be held.
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.

Restrictions

  1. If the key specified on IWM4CON was a user key (8-F), then the following must ALL be true:
    • caller must be in non-cross-memory mode (P=S=H). This implies that the current primary must match the primary at the time that IWM4CON was invoked. Running in a subspace is not supported.
    • must be in TCB mode (not SRB)
    • current TCB must match the TCB at the time that IWM4CON was invoked.
  2. It is the caller's responsibility to serialize use of this service with use of IWMCLSFY and other services using the connect token. Failure to do so may result in classification to a service and/or report class which is other than the intended one.
  3. This service should not be invoked while in a RTM termination routine (resource manager) for the TCB owning the connect token since MVS will have its own resource cleanup routine and unpredictable results would occur. It is legitimate to use this service while in a recovery routine, however, or in mainline processing.

Input register information

Before issuing the IWMWMCON 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

main diagram

Read syntax diagramSkip visual syntax diagramnamebIWMWMCONbCONNTKN= conntkn,SUBSYS= subsys,SUBSYSNM= subsysnm,RETCODE= retcode,RSNCODE= rsncode,PLISTVER=IMPLIED_VERSION,PLISTVER=MAX,PLISTVER=0,MF=S,MF=(L, list addr,0D, attr),MF=(E, list addr,COMPLETE)

Parameters

The parameters are explained as follows:

name
An optional symbol, starting in column 1, that is the name on the IWMWMCON macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
CONNTKN=conntkn
A required input parameter, which contains the connect token for the environment to be modified.

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

,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.
,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=0
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, 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, if you use the currently available parameters.
To code: Specify one of the following:
  • IMPLIED_VERSION
  • MAX
  • A decimal value of 0
,RETCODE=retcode
An optional output parameter into which the return code is to be copied from GPR 15. If you specify 15, GPR15, REG15, or R15 (within or without parentheses), the value will be left in GPR 15.

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

,RSNCODE=rsncode
An optional output parameter into which the reason code is to be copied from GPR 0. If you specify 0, 00, GPR0, GPR00, REG0, REG00, or R0 (within or without parentheses), the value will be left in GPR 0.

To code: Specify the RS-type address of a fullword field, or register (0) or (2)-(12), (00), (GPR0), (GPR00), REG0), (REG00), or (R0).

,SUBSYS=subsys
A required input parameter, which contains the generic subsystem type (e.g. IMS, CICS, etc.).

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

,SUBSYSNM=subsysnm
A required input parameter, which contains the name of the specific subsystem instance

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 IWMWMCON macro returns control to your program:
  • GPR 15 (and retcode, when you code RETCODE) contains a return code.
  • When the value in GPR 15 is not zero, GPR 0 (and rsncode, when you code RSNCODE) contains a 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 IWMWMCON Macro
Return Code Reason Code Equate 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 xxxx0409 Equate Symbol: IwmRsnCodeNoConn

Meaning: Input connection token does not reflect an active connection to WLM.

Action: None required.

8 Equate Symbol: IwmRetCodeInvocError

Meaning: Invalid invocation environment or parameters.

8 xxxx0802 Equate Symbol: IwmRsnCodeXmemUserKeyTkn

Meaning: Caller is in cross-memory mode while the token was requested in user key.

Action: Avoid requesting this function while in cross-memory mode.

8 xxxx0803 Equate Symbol: IwmRsnCodeDisabled

Meaning: Caller is disabled.

Action: Avoid requesting this function while disabled.

8 xxxx0804 Equate Symbol: IwmRsnCodeLocked

Meaning: Caller is locked.

Action: Avoid requesting this function while locked.

8 xxxx0809 Equate Symbol: IwmRsnCodeSrbUserKeyTkn

Meaning: Caller is in SRB mode, while the token was obtained in a user key (8-F).

Action: Avoid requesting this function in SRB mode for tokens associated with user key.

8 xxxx080A Equate Symbol: IwmRsnCodeTcbNotOwnerUserKeyTkn

Meaning: Current TCB is not the owner, while the token was obtained in a user key (8-F).

Action: Avoid requesting this function under a TCB other than the owner for a token associated with user key.

8 xxxx080B Equate Symbol: IwmRsnCodeBadPl

Meaning: Error accessing parameter list.

Action: Check for possible storage overlay.

8 xxxx0823 Equate Symbol: IwmRsnCodeDatoff

Meaning: Caller invoked service while DATOFF

Action: Avoid requesting this function in this environment.

8 xxxx0824 Equate Symbol: IwmRsnCodeAmode24

Meaning: Caller invoked 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: Caller invoked service but was not DAT on Primary ASC mode.

Action: Avoid requesting this function in this environment.

8 xxxx0826 Equate Symbol: IwmRsnCodeTaskTerm

Meaning: Caller invoked service while task termination is in progress for the TCB associated with the owner.

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: Version number in parameter list is not valid.

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

8 xxxx082F Equate Symbol: IwmRsnCodeWrongHome

Meaning: Caller invoked the service from the wrong home address space.

Action: Invoke the function with the correct home address space.

8 xxxx0840 Equate Symbol: IwmRsnCodeServiceNotEnabled

Meaning: Caller's space connection is not enabled for this service. The caller is not connected to the WLM work management services.

Action: Avoid requesting this function under the input connection. IWM4CON options must be specified previously to enable this service. Check the specification of the WORK_MANAGER keyword on the IWM4CON macro invocation.

10 Equate Symbol: IwmRetCodeCompError

Meaning: Component error.

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

Examples

To override the subsystem name and subsystem type provided on a previous call to IWM4CON, specify:
IWMWMCON  SUBSYS=GENSUB,SUBSYSNM=SUBNAME,
     CONNTKN=CONNTOKEN,RETCODE=RC,RSNCODE=RSN,
Where the following are declared:
GENSUB    DS    CL4          Generic subsystem type
SUBNAME   DS    CL8          Subsystem name
CONNTOKEN DS    FL4          Connect token