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.

Note: It is recommended to use the equivalent service, IWM4TAF, which also supports 64-bit addressing. For more information, see IWM4TAF — WLM temporal affinity service.

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

  1. Make sure no EUT FRRs are established.
  2. The macro CVT must be included to use this macro.
  3. The macro IWMYCON must be included to use this macro.
  4. The macro IWMPB must be in the library concatenation, since it is included by IWMYCON.
  5. 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. This macro may not be used during task/address space termination.
  2. 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

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

Read syntax diagramSkip visual syntax diagramnameIWMTAFFAFFINITY=YESAFFINITY=NO,REGION_TOKEN=0,REGION_TOKEN= region_token,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 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

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

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

To start a temporal affinity from the server region, specify the following:
  IWMTAFF AFFINITY=YES
          RETCODE=RC,
          RSNCODE=RSN
*
* Storage areas
*
RC       DS    F               Return code
RSN      DS    F               Reason code