Associate

Use the Associate service to associate a particular transaction program and its conversations with either the transaction scheduler address space or one of the transaction scheduler's subordinate address spaces. Any previous association established between this TP and another address space is broken.

When a transaction scheduler receives an inbound allocate request from APPC/MVS, the targeted TP is automatically associated with the transaction scheduler. If the transaction scheduler passes that work to an awaiting subordinate address space, the transaction scheduler or subordinate address space must invoke the Associate service. If you do not use the Associate service for TPs running in subordinate address spaces, APPC/MVS cannot clean up conversation resources when the subordinate address space is terminated.

You can associate multiple transaction programs with a transaction scheduler, but you can only associate one transaction program with a subordinate address space at a time. A transaction scheduler is responsible for ensuring the integrity of TPs that run at the same time in the transaction scheduler's address space.

You can also use the Associate service to provide or change a unit_of_work_id for the transaction program.

Environment

Authorization:

Supervisor state or PSW key 0-7

Dispatchable unit mode:

Task or SRB mode

Cross memory mode:

Any PASN, any HASN, any SASN

AMODE:

31-bit

ASC mode:

Primary or access register (AR)

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. ATBASOC - Associate

CALL ATBASOC (TP_ID,
              Current_ASCB_ptr,
              New_ASCB_ptr,
              Unit_of_work_id,
              Return_code
             );

Parameters

TP_ID

Supplied/Returned parameter

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

Specifies the transaction program instance assigned to this transaction by APPC/MVS. The TP_ID is a token that uniquely identifies an instance of a program using APPC/MVS services. The TP_ID is passed to the transaction scheduler in the inbound allocate request message. The TP_ID is also generated when a program calls Define_Local_TP or is not started through APPC and calls an allocate service.

A zero TP_ID can be specified if the Current_ASCB_ptr points to a subordinate address space. A zero TP_ID specifies that the transaction program instance in the current address space is to be associated to the new address space. If the Current_ASCB_ptr points to the transaction scheduler address space (that is, a transaction scheduler address space is the one that called Identify), a zero TP_ID will not be allowed.

A transaction scheduler cannot have the TP_ID for a locally started transaction in a subordinate address space. In this situation, the transaction scheduler sets this value to zero, and APPC/MVS sets the TP_ID upon return to the caller.

Current_ASCB_ptr

Supplied parameter

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

Specifies the pointer to the address space control block (ASCB) of the address space where the transaction program currently resides.

New_ASCB_ptr

Supplied parameter

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

Specifies the pointer to the address space control block (ASCB) of the new address space to associate with the transaction program instance.

Unit_of_work_id

Supplied parameter

Type: Character string
Char Set: 01134
Length: 8 Bytes

Specifies an ID assigned to this program instance by the transaction scheduler (for example, a job number or transaction code). This is an optional parameter used only in APPC/MVS diagnostics. It correlates APPC activity to program instances as they are known in APPC/MVS to program instances as they are known to other components and subsystems. To specify no Unit_of_work_ID, set the parameter to 8 blanks. If Unit_of_work_id is specified, TP_ID must also be specified.

Return_code

Returned parameter

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

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

Decimal: Meaning
0: The transaction program association is successful.
8: The specified TP_ID does not exist.
12: Associate failed; this address space is already associated with another TP_ID.
16: The Current_ASCB_ptr is a transaction scheduler address space and not a subordinate address space. A TP_ID of zero cannot be specified for a transaction scheduler address space.
20: The value specified on the New_ASCB_ptr parameter is not valid.
24: The value specified on the Current_ASCB_ptr parameter is not valid.
28: The transaction program to be associated has an active APPC request outstanding.
30: The combination of parameters is not valid.
32: The requested service is not supported in the caller's environment. For example, this return code will be given if the caller invokes any of the transaction scheduler services while holding a lock.
36: The requested transaction scheduler service must be invoked from the transaction scheduler address space or from a transaction scheduler subordinate address space.
38: The specified program is an APPC/MVS server. It cannot be associated with another address space.
44: APPC/MVS is not active.
48: APPC/MVS services failure.

Characteristics and Restrictions

The caller does not have to reside in the current or new associated address space of the TP instance.
This service cannot be called while there is an APPC request outstanding from the transaction program instance (TP_ID) specified on the call. If the Associate service is called while there is an outstanding APPC request, the system does not perform the Associate service function, and the caller receives a return code of 28 (decimal).
You cannot associate a TP that's currently registered for an allocate queue (through the Register_for_Allocates service). If the Associate service is called while the TP is registered for an allocate queue, the system does not perform the Associate service function, and the caller receives a return code of 38 (decimal). For more information about the Register_for_Allocates service, see z/OS MVS Programming: Writing Servers for APPC/MVS.
The new address space specified on the New_ASCB_ptr parameter cannot be a subordinate address space that is currently running a TP. If the new address space is a subordinate address space that is running a TP, the system does not perform the Associate service function, and the caller receives a return code of 12 (decimal).
Transaction schedulers that call the Associate service while in task mode should not have any enabled unlocked task (EUT) functional recovery routines (FRRs) established. For more information about EUT FRRs, see the section on providing recovery in z/OS MVS Programming: Authorized Assembler Services Guide.
Two process identifiers (TP_ID and New_ASCB_ptr) are supported to accommodate different types of Associate scenarios. Table 1 describes the action taken by APPC/MVS based upon how all these parameters are specified on the Associate service.

Table 1. Relationship between TP_ID and address space parameters
TP_ID	Current ASCB_ptr	New ASCB_ptr	Action taken by APPC/MVS
0	0	0	Parameters not valid - Associate will give return code 30.
0	variable	0	The transaction program residing in the subordinate address space is associated with the home address space of the caller. If the transaction program does not reside in a subordinate address space, Associate gives a return code of 16. If no active transaction program exists, Associate gives a return code of 8.
0	0	variable	The transaction program residing in the home address space of the caller is associated with the new address space identified. If the transaction program does not reside in a subordinate address space, Associate gives a return code of 16. If no active transaction program exists, Associate gives a return code of 8.
0	variable	variable	The transaction program residing in the current subordinate address space identified is associated with the new address space identified. If the transaction program does not reside in a subordinate address space, Associate gives a return code of 16. If no active transaction program exists, Associate gives a return code of 8.
variable	-	0	The specified TP_ID is associated with the home address space of the caller.
variable	-	variable	The specified TP_ID is associated with the new address space specified by New_ASCB_ptr.