IWMTAFF — WLM temporal affinity service
The IWMTAFF service should be used to inform WLM when a temporal affinity for a specific server region starts and when it ends. WLM will ensure that server regions will not be terminated as long as temporal affinities exist.
The caller must have previously connected to WLM using the IWMCONN as server or as queue manager.
Environment
The requirements for the caller are:
Minimum authorization: | Problem state. Any PSW key |
---|---|
Dispatchable unit mode: | Task |
Cross memory mode: | PASN=HASN=SASN |
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
- Make sure no EUT FRRs are established.
- 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
- This macro may not be used during task/address space termination.
- Before using this macro the caller must connect to WLM via IWMCONN Server_Manager=YES, Server_Type=Queue or IWMCONN Queue_Manager=YES.
Input register information
Before issuing the IWMTAFF 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 IWMTAFF macro is as follows:
Parameters
The parameters are explained as follows:
- name
- An optional symbol, starting in column 1, that is the name on the IWMTAFF macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
- AFFINITY=YES
- AFFINITY=NO
- A required parameter indicating whether a temporal affinity begins or ends
- AFFINITY=YES
- A new temporal affinity for the server region begins. WLM will ensure that the server regions is not terminated before all temporal affinity have ended.
- AFFINITY=NO
- A temporal affinity for the server region has ended. WLM will start to terminate server regions if all temporal affinities have ended.
- ,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
- ,REGION_TOKEN=region_token
- ,REGION_TOKEN=0
- An optional input parameter, which contains the region token. The region token is not required
if the macro is invoked from the server region for which the temporal affinity should be started or
stopped. The region token must be used if the service is used from the queueing manager. The region
token is returned by the IWM4CON and IWMSSEL macro.
The caller must be supervisor state or have PSW key mask 0-7 authority to use this service with the REGION_TOKEN parameter.
Coding REGION_TOKEN=0 is equivalent to omitting the REGION_TOKEN keyword. The default is 0.
To code: Specify the RS-type address, or address in register (2)-(12), of a 16-character field.
- ,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).
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 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. Action: None required. |
4 | xxxx0439 | Equate Symbol: IwmRsnCodeNoAffinityFound Meaning: The service has been invoked to tell WLM that an existing server region affinity has been terminated but WLM has no affinity defined for this server region. Action: If region token was not specified make sure to use the service properly at the beginning and end of each affinity. If the region token has been defined make sure that it is used for the correct server region. |
4 | xxxx043A | Equate Symbol: IwmRsnCodeRegionNotFound Meaning: The region token does not identify a valid server region. Action: Please specify the correct region token. |
8 | — | Equate Symbol: IwmRetCodeInvocError Meaning: Invalid invocation environment or parameters. |
8 | xxxx0801 | Equate Symbol: IwmRsnCodeSrbMode Meaning: Caller is in SRB mode. Action: Avoid requesting this function while in SRB 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 | xxxx080B | Equate Symbol: IwmRsnCodeBadPl Meaning: Error accessing parameter list. Action: Check for possible storage overlay. Also check if you call this macro in 64-bit address mode. Refer to the description of reason code xxxx089E for further information. |
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 in primary ASC mode. Action: Avoid requesting this function in this environment. |
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 | xxxx0840 | Equate Symbol: IwmRsnCodeServiceNotEnabled Meaning: Caller's space connection is not enabled for this service Action: Make sure that SERVER_MANAGER=YES and SERVER_TYPE=QUEUE is specified on the IWMCONN request to enable this service. |
8 | xxxx0841 | Equate Symbol: IwmRsnCodeXmemMode Meaning: Caller is in cross-memory mode. Action: Request this function only when you are not in cross-memory mode. |
8 | xxxx0842 | Equate Symbol: IwmRsnCodeNoWLMConnect Meaning: Caller's space is not connected to WLM. Action: Invoke the IWMCONN macro before invoking this macro. |
8 | xxxx084D | Equate Symbol: IwmRsnCodeNotAuthConnect Meaning: The caller must be supervisor state or have PSW key mask 0-7 authority to use the requested WLM service. This applies only if the caller provides a region token for a server address space for which it wants to set the affinity. Action: Avoid requesting this function in this environment. |
8 | xxxx089E | Equate Symbol: IwmRsnCodeServiceAModeMismatch Meaning: The caller is in 64-bit address mode and tried to invoke a service macro that is only enabled for a 31-bit environment. Action: Use the 64-bit enabled service macro (IWM4TAF) or change the address mode of the caller to 31-bit. |
10 | — | Equate Symbol: IwmRetCodeCompError Meaning: Component error. Action: Contact your system programmer. |
Example
IWMTAFF AFFINITY=YES
RETCODE=RC,
RSNCODE=RSN
*
* Storage areas
*
RC DS F Return code
RSN DS F Reason code