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
- 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.
Restrictions
- 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.
- 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.
- 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
- 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
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
- 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.
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
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