The following figure is a general example of how a transaction scheduler uses APPC/MVS services. Each number in Figure 1 corresponds to a possible step, and to an explanation in the text immediately following the diagram.

Figure 1. Transaction Schedulers in APPC/MVS

Explanations:

1. Each transaction scheduler must join the APPC XCF group. The transaction scheduler must supply the address of its XCF message user routine, which will receive messages from APPC/MVS. Join_Sysappc_Group returns a value to be used as the member token parameter of Identify. A transaction scheduler must invoke Join_Sysappc_Group before invoking Identify.
2. The transaction scheduler optionally calls the Set_AS_Attributes service to prevent conversations allocated by a subordinate address space from being associated with the system default LU. This prevention takes effect in cases when the subordinate address space is not connected to a transaction scheduler.
3. The transaction scheduler issues the Identify service to make itself known to APPC/MVS. The Identify service indicates to APPC/MVS that the transaction scheduler is fully operational and is ready to receive and schedule requests from APPC/MVS. The Identify service also identifies possible exit routines for TP profile conversion and information extraction.
4. APPC/MVS notifies all members of the APPC group of significant events, such as APPC initialization and termination.
5. When an inbound allocate request is received, APPC/MVS performs checking, obtains related data, and sends an XCF message requesting the transaction scheduler to attach the TP. The transaction scheduler's XCF message user routine must recognize that the message describes the TP to be attached, and process it.
6. Any time a new subordinate address space is created, the transaction scheduler must issue Connect on behalf of the subordinate address space to inform APPC/MVS that the newly created subordinate address space is owned by the transaction scheduler. Connect must be issued for the subordinate address space before any other APPC/MVS services are used in that address space. Connect is only required for a transaction scheduler managing one or more subordinate address spaces.
7. When a transaction scheduler receives a transaction request from APPC/MVS, the transaction scheduler has the option of passing that work on to a subordinate address space, or of processing the work itself. If the transaction scheduler decides to pass the transaction on to a subordinate address space to process, the transaction scheduler or subordinate address space must invoke the Associate service. If the scheduler specifies a TP profile conversion exit on the Identify service, and the requested transaction has a TP profile entry that requires conversion, the exit is invoked to convert the entry. APPC/MVS then saves the converted copy for future requests, avoiding repeated conversion.
8. After the TP starts running, it might request information about the environment in which it was scheduled. The transaction program can invoke the APPC/MVS Extract_Information service to obtain information about its environment. The Extract_Information service will use the transaction scheduler extract exit to obtain the information to return to the transaction program.
9. Cleanup_TP can be called to cleanup a TP after it is processed, or reject an inbound TP that cannot be processed (for example, because the TP was not available). If the TP is rejected, you can use Cleanup_TP to send error log data to the partner system or TP that submitted the request.
10. Cleanup_Address_Space can be issued to clean up all transaction programs in an address space. The transaction scheduler will probably issue Cleanup_Address_Space after each transaction program completes in a subordinate address space. Cleanup_Address_Space can be used to clean up conversations normally in error situations. In error situations, all conversations are terminated, and the partner TPs are notified of termination with a Deallocate_ABEND_SVC sense code.
11. The transaction scheduler can use the Control request to temporarily halt or resume processing of inbound allocate requests received for a specific LU or all LUs for that transaction scheduler.
12. The transaction scheduler can issue Define_Local_TP to create a TP instance in its address space.
13. Disconnect is the opposite of Connect and is issued by the transaction scheduler to inform APPC/MVS that the specified address space is no longer under the control of the transaction scheduler. Address space termination is an automatic Disconnect.
14. The transaction scheduler issues an Unidentify request to terminate use of APPC/MVS services. Unidentify is the opposite of Identify.

Additional Considerations:

• The transaction scheduler can also issue IXCLEAVE to undo the effects of Join_Sysappc_Group. IXCLEAVE is an XCF macro that disassociates a member from its XCF group (in this case, the APPC XCF group). The input to the IXCLEAVE macro is the member token that was passed back from Join_Sysappc_Group. For more information about the IXCLEAVE macro, including syntax, see z/OS MVS Programming: Sysplex Services Reference.
• The transaction scheduler may process protected conversations (conversations with a synchronization level of syncpt). To do so, you must:
  • Define it to an LU that is capable of handling conversations with a synchronization level of syncpt. See the session management section of z/OS MVS Planning: APPC/MVS Management for further information about enabling LUs for protected conversations support.
  • Be aware of changes for the following APPC/MVS system services:
    • Cleanup_Address_Space (all versions)
    • Cleanup_TP (all versions)
    • Control
    • Unidentify
• Additionally, the transaction scheduler may register as a resource manager of protected conversations. Doing so allows the scheduler to obtain a privately managed context that it can use to associate with the inbound Allocate request.

  Note that designing and coding a scheduler to act as a resource manager is relatively difficult. If you want to code an alternate transaction scheduler to manage the contexts for protected conversations, you need to understand the concepts and requirements for resource recovery in z/OS MVS Programming: Resource Recovery. Design the scheduler to use APPC/MVS system services, along with registration and context callable services, in the following sequence:

  1. Join the APPC XCF group by calling the Join_Sysappc_Group service. Optionally, call the Set_AS_Attributes service.
  2. Register through the Register_Resource_Manager service, supplying a resource manager name. The service returns a resource manager token that the scheduler uses on subsequent calls to registration and context services.
  3. Use the Identify service to identify itself to APPC/MVS; on this service call, provide the resource manager name. After receiving an inbound Allocate request for the LU associated with this scheduler, APPC/MVS creates a privately managed context, and passes the context token to the scheduler through an XCF message.
  4. Change to the correct state to call context services. To do this, call the Set_Exit_Information service to cause the server resource manager state to change to SET state. The server is now in the correct state with context services to issue context callable services.
  5. Switch to the context passed through the XCF message, by issuing a call to the Switch_Context service. After the service returns, the privately managed context is the current context.
  6. Receive the inbound protected conversation by issuing the Get_Conversation service. As part of processing this service, APPC/MVS expresses interest in the unit of recovery under the privately managed context, and sets the logical unit of work identifier (LUWID) for the current context.

  Depending on the design of the scheduler routines, either the scheduler or its subordinate address space invoke the Associate service, and perform steps 4 through 6. If the scheduler uses subordinate address spaces, it must pass to them the context token for the privately managed context.