Multi-Trans Processing

A multi-trans program is typically coded with a multi-trans shell, an environment that performs initialization and termination processing, surrounding the part of the TP that holds conversations.

Table 1 shows, at a very high level, how a multi-trans TP might work in an electronic mail application. It also shows how processing costs (resource responsibility) are divided between the multi-trans shell and individual users.

Table 1. Example of Multi-trans Resource Processing
Action	Resource Responsibility
1. John is the first person to arrive in the morning, and requests his electronic mail.	none
2. John's request starts the system's mail log facility, a multi-trans TP named MLF.	shell
3. MLF performs initialization processing, and loads the notes for all users from permanent storage to a data space.	shell
4. MLF processes John's request and sends John his notes.	John
5. The APPC/MVS transaction scheduler causes MLF to wait.	shell
6. Janet requests her mail. MLF immediately sends Janet her notes.	Janet
7. A new note comes in for John, and MLF is signalled.	shell
8. The new note is read from permanent storage to MLF's data space. John is notified of the new note.	shell
9. John requests his new mail. MLF immediately sends John his new note.	John
10. MLF ends, and performs clean-up processing.	shell

When the multi-trans program is scheduled in response to an inbound allocate request, the multi-trans shell gets control first and allocates general resources. It then calls for the initial inbound request with the Get_Transaction (ATBGTRN) callable service. When the conversation ends, the shell regains control and uses the Get_Transaction call again to get the next conversation request on the queue.

Figure 1 gives an overview of initialization and termination processing in a multi-trans TP.

Figure 1. Initialization and Termination in Multi-trans Processing

                                ┌───────────────────────────┐
                                │                           │
                                │    Multi-Trans Shell      │
                                │                           │
                                │    Initialization         │
                                │       allocate data...    │
                                │                           │
                  ←─────────────┼─── Call ATBGTRN  ←─────┐  │
            Get_Transaction     │     IF RC > 4 THEN     │  │
                                │       terminate        │  │
                                │    │ELSE               │  │
                                │    │ ┌────────────┐    │  │
                                │    └─→            │    │  │
                                │      │Transaction │    │  │
                   ←────────────┼──────┼──          │    │  │
            Accept_       .     │      │            │    │  │
            Conversation  .     │      │            │    │  │
                          .     │      │            │    │  │
                          .     │      └─────┬──────┘    │  │
                                │            ↓           │  │
                  ←─────────────┼──────  Call ATBRTRN    │  │
            Return_transaction  │      ┌───────────────┐ │  │
                                │      │ clean-up      │ │  │
                                │      │ reallocate... │ │  │
                                │      └─────┬─────────┘ │  │
                                │            └───────────┘  │
                                └───────────────────────────┘

To use multi-trans scheduling, a TP must define in its TP profile both a schedule type of multi-trans, and a special user ID (generic ID) for multi-trans shell processing.

The generic ID contained in the TP profile entry identifies the environment for the multi-trans shell. The shell runs under this generic ID during initialization, while it allocates general resources for the TP to use. The generic ID remains in effect until the first successful Get_Transaction call, when the environment is personalized to the user ID associated with the inbound request. That personalized environment covers the entire conversation and remains in effect until the next Get_Transaction call, or until the shell explicitly returns to its generic environment, typically to perform cleanup or data set reallocations between conversations. To return to its generic user ID, the shell can call the Return_Transaction (ATBRTRN) service.

The multi-trans shell can process an initial inbound Allocate request without first issuing Get_Transaction; in this case, the generic ID— not the user ID associated with the inbound request— identifies the conversation being processed. Using the multi-trans shell's generic ID this way can be useful when:

A trusted, remote partner TP cannot supply a user ID on its inbound Allocate requests, or
The installation wants the work that an APPC/MVS TP processes on behalf of its partners to run under only one user ID, rather than under several individual IDs.