Programming Terms

Transaction Program (TP)

An application program that uses APPC communication calls is a transaction program, or TP. A TP on one system can communicate with a TP on another system to access resources on both systems. Both TPs can be considered a single cooperative processing application that happens to reside on two different systems.

Local TP/Partner TP

Whether a TP is a local TP or a partner TP usually depends on point of view. From the point of view of a z/OS system, TPs residing on the system are local TPs, and TPs on remote systems are partner TPs. However, from the point of view of the remote system, the names are reversed: the TPs that reside on its system are local TPs and the ones on z/OS are the partner TPs.

A local TP can initiate communication with one or more partner TPs. The partner might or might not reside on the local system. The TP does not need to know whether the partner TP is on the same system or on a remote system.

Other terms for TPs are inbound TP and outbound TP, which convey who establishes the communication. An outbound TP is the one that starts a conversation and an inbound TP is the one that responds. In Figure 3, program A is the outbound TP and program B is the inbound TP. On z/OS, any program that calls APPC/MVS services to start a conversation is considered an outbound TP, while an inbound TP requires special processing by z/OS, such as scheduling and initiation, or processing by an APPC/MVS server.

Client TP

A client transaction program is one that requests the services of an APPC/MVS server.

APPC/MVS Server

An APPC/MVS server is an MVS application program that uses the APPC/MVS Receive_Allocate callable service to receive allocate requests from one or more client TPs. An APPC/MVS server can serve multiple requestors serially or concurrently.

Conversation

The communication between TPs is called a conversation. Like a telephone conversation, one TP calls the other and they “converse,” one TP “talking” at a time, until one TP ends the conversation. The conversation uses predefined communication services that are based on SNA-architected LU 6.2 services called verbs. These verb services are implemented in APPC/MVS as callable services.

To start (allocate) a conversation, a TP issues an allocate call that contains specific information, such as the name of the partner TP, the LU in the network where the partner TP resides, and other network and security information. The conversation is established when the partner TP accepts the conversation. After a conversation is established, other calls can transfer and receive data until a TP ends (deallocates) the conversation with a Deallocate call.

Note: The CPI Communications protocol requires an Initialize_Conversation (CMINIT) call before an Allocate call.

Conversation_ID

A conversation_ID is an 8-byte token that the Allocate, Initialize_Conversation, Accept_Conversation, and Receive_Allocate calls return. APPC provides the conversation_ID to uniquely identify the conversation on subsequent APPC calls.

TP_ID

A TP_ID is a unique 8-byte token that APPC/MVS assigns to each instance of an inbound transaction program. When multiple instances of a TP are running simultaneously under APPC/MVS, they have the same TP name, but each has a unique TP_ID. The TP_ID can be used to trace a specific instance of a TP in the system.

Conversation State

To ensure orderly conversations and prevent both TPs from trying to send or receive data at the same time, APPC enforces conversation states. TPs enter specific conversation states by calling specific APPC services, and the states determine what services the TP may call next. For example, when a local TP allocates a conversation, the local TP is initially in send state; and when the partner TP accepts the conversation, the partner is in receive state. As the need arises, the local TP can call a receive service to enter receive state and put its partner in send state, allowing the partner to send data.

Inbound/Outbound Allocate Request

An inbound allocate request is one that starts a conversation with a TP on z/OS; an outbound allocate request is a request to start a conversation from a local TP on z/OS.

Inbound/Outbound Conversation

Whether a conversation is inbound or outbound, similar to whether a TP is a local TP or a partner TP, depends on point of view. From the point of view of an z/OS system, an inbound conversation originates from a TP that issues an inbound allocate request for a TP on the z/OS system. An outbound conversation originates from a TP on the z/OS system that issues an outbound allocate request for its partner.

The significant difference between inbound and outbound conversations generally has to do with whether the conversation will initiate work that requires special processing by z/OS. Inbound conversations might allocate local TPs on z/OS that need to be scheduled by a transaction scheduler, or inbound conversations might need to be queued for an APPC/MVS server.