XCF Message User Routine

XCF Message User Routine

z/OS MVS Programming: Writing Transaction Schedulers for APPC/MVS
SA23-1398-00

APPC/MVS invokes a transaction scheduler's XCF message user routine to inform the transaction scheduler of general events affecting APPC/MVS, and to pass to it all inbound Allocate requests that are addressed to the transaction scheduler's LU. Depending on the message that APPC/MVS passes, the message user routine might have to issue the XCF IXCMSGI macro to obtain additional information.

The transaction scheduler identifies its XCF message user routine to APPC/MVS on the Join_Sysappc_Group service.

References

See z/OS MVS Programming: Sysplex Services Guide for more information about designing an XCF message user routine.
See z/OS MVS Programming: Sysplex Services Reference for the coding details for the IXCMSGI macro.
See IXCYMEPL in z/OS MVS Data Areas, Vol 3 for complete field names and lengths, offsets, and descriptions of the fields in the message user routine parameter list, which is mapped by the IXCYMEPL mapping macro.
See ATBXCFMS in z/OS MVS Data Areas, Vol 1 for complete field names and lengths, offsets, and descriptions of the fields in XCF messages sent by APPC/MVS, which are mapped by the ATBXCFMS mapping macro.

Environment

The XCF message user routine receives control in the following environment:

Authorization:

Supervisor state and PSW key 0

Dispatchable unit mode:

SRB mode

Cross memory mode:

PASN = HASN = SASN. The primary address space equals the primary address space of the transaction scheduler, and can be swappable or nonswappable.

AMODE:

31-bit

ASC mode:

Primary

Interrupt status:

Enabled for I/O and external interrupts

Locks:

The user routine does not hold any locks on entry.

Processing

All XCF messages sent by APPC/MVS contain a type code to indicate the type of message being sent. The type code is the first four bytes of the 32-byte message control area passed in the parameter list (mapped by IXCYMEPL) to the message user routine. The user routine must examine the type code to determine whether it is a general event message or an Allocate request message. The user routine should be optimized to handle requests to allocate TPs, because these will be the most common.

Note: Messages requesting the transaction scheduler to allocate a TP will not be sent until APPC/MVS activates at least one of the transaction scheduler's LUs. However, because XCF messages might be delivered out of sequence, the XCF message user routine might receive an Allocate TP request message before it receives the message reporting that the LU is active. Also, the message user routine is not single-threaded; several processors may execute the user routine simultaneously, with each processor handling a different message.

z/OS MVS Programming: Sysplex Services Guide contains general information about designing and coding an XCF message user routine; you should be familiar with that information before coding the message user routine for a transaction scheduler. The rest of this section contains guidance that applies only to designing a message user routine for use with a transaction scheduler for APPC/MVS.

Message Types

The contents of the 32-byte message control area (MEPLCNTL field) indicate that the XCF message is one of the following types:

APPC Initialization or Termination
LU Activation or Deactivation
Allocate TP request.

The ATBXCFMS mapping macro maps these APPC/MVS messages. The general event message for APPC initialization/termination is small enough to be contained in the 32-byte message control area. However, the LU activation/deactivation and the Allocate TP request messages are each too large to fit in the 32-byte message control area. Also, for the LU activation/deactivation message, additional information is available if optional data was supplied for the transaction scheduler's LU in the USERVAR, ALTLU, and GRNAME keywords on the LUADD statement in the APPCPMxx parmlib member. In these cases, the message user routine must issue the XCF IXCMSGI macro to receive the rest of the message or the additional information.

When you design the message user routine to issue the IXCMSGI macro, provide the message token value in the MEPLMTOK field of the parameter list. Also provide a buffer to contain the data returned by IXCMSGI; the storage key for the buffer must match the PSW key of the caller of Join_Sysappc_Group.

You may receive data in a single or in multiple buffers. See z/OS MVS Programming: Sysplex Services Guide for information about designing a message user routine to use single or multiple buffers without encountering errors.

Programming Notes for LU Activation/Deactivation Messages

For LU activation/deactivation messages:

In the XCF 32-byte control area, a flag indicates whether the LU is capable of handling outbound Allocate requests that use a network-qualified name to identify the partner LU.
In the IXGMSGI buffer:
- If the LU is a member of a VTAM generic resource group, a field contains the generic resource name associated with the LU.
- Optional USERVAR data might indicate that a transaction scheduler has an alias name defined for its local LU. Depending on the release of VTAM your installation is using, one of the following results:
  - With VTAM 4.3 or earlier, conversation allocations from that LU will fail if the partner LU name on the Allocate request is the USERVAR alias of the local LU name.
  - With VTAM 4.4 or later, conversation allocations from that LU will be accepted if the partner LU name on the Allocate request is the USERVAR alias of the local LU name.

Programming Notes for Allocate TP Request Messages

If the message user routine issues IXCMSGI for more data, but the IXCMSGI macro fails, the message user routine should call the Cleanup_TP service to clean up any outstanding APPC/MVS resources, supplying the TP_ID that was passed to the message user routine in the 32-byte control area.

If the IXCMSGI macro successfully returns to the message user routine, the buffer contains the Allocate TP request message, which includes such data as:

TP_ID

A token that uniquely identifies a transaction to MVS. Transaction schedulers use it to inform APPC/MVS:

Where the transaction executes (through the Associate service)
When the transaction terminates normally or abnormally (through the Cleanup_TP service).

PROFILE

The TP profile entry contents, if a profile was available. The profile can be mapped by the ATBDFTP mapping macro, which is in z/OS MVS Data Areas, Vol 1 the format and content of the TP_Profile is transaction-scheduler dependent.

CONV_CORR

The conversation correlator associated with this TP. The conversation correlator, which is specified in the FMH-5 that contains the input for the allocate request, associates that request with a response from the transaction scheduler. See z/OS MVS Programming: Writing Transaction Programs for APPC/MVS for more information about how partner TPs and transaction schedulers can use a conversation correlator.

CONV_SYNC_LEVEL

The synchronization level of the conversation associated with this TP. The synchronization level is one of the following:

Value: Meaning
0: None
1: Confirm
2: Syncpt

LUWID

The logical unit of work ID is used to identify the most recent sync point, or for accounting purposes.

CONTEXT_TOKEN

A token that identifies the context representing a transaction program's unit of work. This field is meaningful only for protected conversations.

SECTOKN

A token that identifies the security environment created for the user by RACF. If your installation uses RACF, the alternate transaction scheduler can use this token to create a security environment in the program's execution address space. When recalling the RACF ACEE associated with the security token, for performance reasons, code STAT=NO on the RACROUTE macro.

ENVR

A RACF object that the transaction scheduler can use quickly recreate a security environment in the program's execution address space.

For more information about the RACF Security_Token and ENVR_Object, see z/OS Security Server RACROUTE Macro Reference.

Programming Considerations

The message user routine can reside either in the private storage of the address space from which the Join_Sysappc_Group service is invoked, or in common storage.
The message user routine should return to its caller as soon as possible, because system resources are held until the message user routine gives up control.
To avoid performance degradation in the XCF signalling service, and in the system as a whole, do not issue the SUSPEND macro within the message user routine.

Entry Specifications

XCF passes information to the message user routine in registers and in a parameter list.

Registers at Entry

On entry to the message user routine, the registers contain the following information:

Register	Contents
GPR 0	Does not contain any information for use by the message user routine.
GPR 1	Address of the message user routine parameter list.
GPRs 2 - 12	Do not contain any information for use by the message user routine.
GPR 13	Address of a standard save area. (The message user routine does not have to save and restore XCF's registers in this save area. The message user routine can use this save area to save its own registers when it uses services that might overwrite the contents of registers.)
GPR 14	Return address
GPR 15	Entry point address of message user routine.
ARs 0 - 15	Do not contain any information for use by the message user routine.

Parameter List Contents

The parameter list that XCF passes to the message user routine is mapped by the IXCYMEPL mapping macro and is pointed to by GPR 1. The parameter list is addressable from the primary address space in which the message user routine runs, and includes the following information:

A message token (MEPLMTOK) for the message user routine to use when issuing the IXCMSGI macro.
The member data value (MEPLMDAT) provided on return from the Join_Sysappc_Group service (XCFMSGIN_memdata parameter).
The length of the message (MEPLMLEN).
The message control area (MEPLCNTL), which contains the message information from APPC/MVS. The message user routine must look at this 32-byte area to determine the type and contents of the APPC/MVS message.

Figure 1 illustrates how APPC/MVS messages are mapped.

Figure 1. How APPC/MVS Messages are Mapped

Return Specifications

On return, the message user routine does not have to set any return codes or place any information in the GPRs. The message user routine must return control through a BR 14 or a BSM 0,14.