Join_Sysappc

Use the Join_Sysappc_Group service to join the XCF group used by APPC/MVS. Each transaction scheduler must join the APPC XCF group. Other system applications can also join the APPC XCF group to be notified of APPC events.

APPC/MVS communicates with members of its XCF group by invoking their XCF message user routines. APPC/MVS notifies all group members of general interest events such as APPC initialization and termination. APPC/MVS also notifies individual transaction schedulers when inbound allocate requests arrive for them. To notify individual schedulers, APPC/MVS uses a member_token that the transaction scheduler passes in on the Identify service. A transaction scheduler must call the Join_Sysappc_Group service, which provides the member token, before calling the Identify service. Unlike Identify and most other scheduler services, the Join_Sysappc_Group service can be called when APPC/MVS is not active.

If you do not use the Join_Sysappc_Group service to join the APPC XCF group, you must use APPC_GROUP_NAME as the group name with the IXCJOIN macro. A different group name is chosen on each system; therefore, each of these groups is “local to a system” and APPC/MVS can use the facilities of XCF regardless of whether XCF can perform cross-system communication. Also, the service performs IXCJOIN with the LASTING=NO option; thus, XCF “system-local mode” can be tolerated.

Environment

Authorization:

Supervisor state or PSW key 0-7

Dispatchable unit mode:

Task mode

Cross memory mode:

PASN = HASN = SASN

AMODE:

31-bit

ASC mode:

Primary

Interrupt status:

Enabled for I/O and external interrupts

Locks:

Unlocked

Control parameters:

All parameters must be addressable by the caller and in the primary address space.

Format

Figure 1. ATBJGP1 - Join_Sysappc_Group

CALL ATBJGP1 (XCFMSGIN_exit_address, 
              XCFMSGIN_memdata, 
              Member_token, 
              XCF_return_code, 
              XCF_reason_code, 
              Return_code
             );

Parameters

XCFMSGIN_exit_address

Supplied parameter

Type: Address
Char Set: N/A
Length: 32 bits

XCFMSGIN_exit_address specifies the address of the transaction scheduler's XCF message user routine. The routine takes control when a message becomes available for this member from another member of the group. For details about the requirements for and processing of the XCF message user routine, see XCF Message User Routine.

XCFMSGIN_memdata

Supplied parameter

Type: Character
Char Set: No restriction
Length: 8 bytes

XCFMSGIN_memdata is an optional parameter that specifies an 8-byte member data field. This field is provided to the message user routine for this member. If you do not specify a value, XCF sets the member data field to binary zero. The transaction scheduler can use this field to pass the address and ASID or ALET of a particular control structure to the XCF message user routine.

Member_token

Returned parameter

Type: Character
Char Set: No restriction
Length: 8 bytes

Member_token specifies the location where this service places the member token that represents the caller of this service.

XCF_return_code

Returned parameter

Type: Integer
Char Set: N/A
Length: 32 bits

The return code passed back from the XCF IXCJOIN macro, if XCF rejects the Join request.

XCF_reason_code

Returned parameter

Type: Integer
Char Set: N/A
Length: 32 bits

The reason code passed back from the XCF IXCJOIN macro, if XCF rejects the Join request.

Return_code

Returned parameter

Type: Integer
Char Set: N/A
Length: 32 bits

Join_Sysappc_Group may return one of the following decimal values in the return code parameter:

Decimal: Meaning
0: Request successful.
8: Request unsuccessful - XCF failed or request denied by XCF.
40: The caller was not running in supervisor state or PSW key 0-7.
48: APPC/MVS services failure.

Characteristics and Restrictions

This service will execute successfully even if XCF is operating in XCF local mode.
The caller must issue the IXCLEAVE macro to undo the effects of Join_Sysappc_Group. IXCLEAVE processing is performed automatically if the caller's address space or task terminates.
The message buffer that is provided in the message user routine must be accessible using the same protect key that is in effect at invocation of Join_Sysappc_Group.
The task that calls this service might end abnormally if a privileged program issues the XCF IXCTERM macro against this member. In that case, the task terminates with system completion code 00C, reason code 4, and the task's recovery routine cannot retry. Transaction schedulers can handle this by attaching a subtask that invokes Join_Sysappc_Group, and reattaching the subtask if it terminates with completion code 00C, reason code 4.
A transaction scheduler may join XCF groups other than the APPC group joined by this service.
The name of APPC's XCF group might vary from system to system and might change during re-IPL. If you need to know the XCF group name used by APPC (to dedicate specific resources to it, for example), you can use the ATBAPPCA mapping macro. The ATBAPPCA mapping macro is described in z/OS MVS Data Areas, Vol 1.
Transaction schedulers that call the Join_Sysappc_Group service should not have any enabled unlocked task (EUT) functional recovery routines (FRRs) established. For more information about EUT FRRs, see the information on providing recovery in z/OS MVS Programming: Authorized Assembler Services Guide.