Many organizations require fast and accurate exchanges of data to perform their business functions, and they depend on communication networks to facilitate such data exchange. To address data processing and communication needs, IBM designed the SNA architecture as a guide for connecting products in a communications network.

The SNA architecture provides formats and protocols that define a variety of physical and logical SNA components. One such logical component, called the logical unit (LU), is responsible for handling communication between end users and provides each end user with access to the network. SNA defines different types of logical units to meet the needs of specific end users, whether the end user is an application program, a stand-alone terminal, or a terminal and an operator. LU 6.2 is a type of logical unit that is specifically designed to handle communications between application programs.

Figure 1 depicts a logical view of an SNA network that handles communication from different users through LUs.

Figure 1. Network Communications between LUs and Users

A typical SNA network consists of a diverse collection of processors or nodes. Some nodes may be running the z/OS or VM operating systems. Using LU 6.2, an APPC application running on one of these processors can communicate with a remote APPC application running on another processor, regardless of the type of processor on which the remote application is running.

A product that makes such communication possible between applications on diverse processors is Virtual Telecommunications Access Method (VTAM). VTAM and APPC/VTAM are implementations of SNA architecture, which direct data between programs and devices. Figure 2 represents an SNA network that is directing data among unlike systems.

Figure 2. An SNA Network for Communications between Different Systems

Before data can flow over a network, the application programs that cause the exchange of data must request communication services. For programmers who code these applications, it is desirable to use a consistent interface to the communications services, regardless of the environment. To address the need for a consistent interface across different environments, IBM introduced Common Programming Interface Communications (CPI-C). CPI-C defines how applications written in high-level languages can be integrated and ported across various platforms, such as z/OS, OS/390, AS/400, VM/ESA, and workstations.

The following example (Figure 3) represents a network application of two transaction programs (A and B) that use CPI Communications calls to establish the APPC type of communication called a conversation. The conversation is directed by the CMxxxx calls, which initialize and allocate the conversation (CMINIT and CMALLC), send and receive data (CMSEND and CMRCV), and eventually deallocate the conversation (CMDEAL).

The sample conversation shown could represent an application in which a workstation program (Program A) sends input to its partner in z/OS (Program B), which then processes and stores the input in a database.

Figure 3. CPI Communications Program Scenario

This book tells how to write such APPC applications using both CPI Communications and a set of callable services that is specific to APPC/MVS.

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.

Logical Units (LUs) and LU 6.2

A logical unit is an SNA addressable unit that manages the exchange of data and acts as an intermediary between an end user and the network. There are different types of logical units. Some LU types support communication between application programs and different kinds of workstations. Other LU types support communication between two programs. LU type 6.2 specifically supports program-to-program communication. The actual implementation of LU 6.2 on a given system is APPC.

Local LU/Partner LU

Whether an LU is a local LU or a partner LU depends on point of view. From the point of view of an z/OS system, LUs defined to the z/OS system are local LUs and LUs defined to remote systems are partner LUs. However, from the point of view of the remote system, the names are reversed: the LUs that are defined to its system are local LUs and the ones on z/OS are the partner LUs.

A partner LU might or might not be on the same system as the local LU. When both LUs are on the same system, the LU through which communication is initiated is the local LU, and the LU through which communication is received is the partner LU.

LUs are defined to VTAM on z/OS by APPL statements in SYS1.VTAMLST. LUs managed by APPC/MVS must also be defined by LUADD statements in APPCPMxx parmlib members.

Sessions

A session is a logical connection that is established or bound between two LUs of the same type. A session acts as a conduit through which data moves between the pair of LUs.

The following figure shows how a session spans two LUs that are defined on two different systems.

Figure 4. A Session between Two LUs

A session can support only one conversation at a time, but one session can support many conversations in sequence. Because sessions are reused by multiple conversations, a session is a long-lived connection compared to a conversation.

If no session exists when a TP issues an Allocate call to start a conversation, VTAM binds a session between the local LU and the partner LU. After a session is bound, TPs can communicate with each other over the session in a conversation. This sending of data between a local TP and its partner occurs until one TP ends the conversation with a Deallocate call.

The following figure shows a single conversation between TP1 and TP2 that is occurring over a session.

Figure 5. A Conversation between Two TPs

If the hardware permits and the two LUs are configured as independent LUs, they can have multiple, concurrent sessions called parallel sessions. When a TP from either LU issues an allocate call and sessions exist but are being used by other conversations, an LU can request a new session unless the defined session limit is reached.

Default session limits are defined for an LU in a VTAM APPL statement. Session-limit values can be changed by entering the VTAM MODIFY CNOS and MODIFY DEFINE operator commands, or by modifying the VTAM APPL definition statement and then restarting APPC/MVS. For more information about these commands, see z/OS Communications Server: SNA Operation.

The following figure shows three parallel sessions, each of which is carrying a conversation.

Figure 6. Parallel Sessions between LUs

An installation can define different types of sessions, but sessions are ultimately defined by the LUs they span and by the session characteristics contained in the VTAM logon mode table that is associated with the session.

Sessions can span LUs on the same system, LUs on two like systems, and LUs on two unlike systems that are LU 6.2 compatible. The following figure shows three sessions bound from a single LU on SYS2. Session 1 spans LUs on two different systems. Session 2 spans the same two systems but is bound from a different LU on SYS1. Session 3 is bound between two LUs on the same system.

Figure 7. Different Types of Sessions between Two LUs

Logon Modes

A logon mode contains the parameters and protocols that determine a session's characteristics. Logon modes are defined in a VTAM logon mode table, a compiled version of which exists in SYS1.VTAMLIB.

Contention

When a TP from each LU in a session simultaneously attempts to start a conversation, the situation that results is called contention. To control which TP can allocate the conversation, a system programmer can define for each LU the number of sessions in which it is the contention winner and the number of sessions in which the LU is the contention loser.

The APPC/MVS callable services can be divided into five types as shown in Figure 8. Each type is explained in more detail following the figure.

Figure 8. Types of APPC/MVS Callable Services

CPI Communications Calls

Common Programming Interface (CPI) Communications calls allow high-level language programs to communicate regardless of the system on which they are running. High-level language programs use the CPI Communications calls to establish conversations and pass data back and forth. When programs in z/OS use these calls, the underlying implementation may be different from another system, but the results are equivalent.

For example, a distributed application written in C could have part of the application on a workstation configured for APPC and the other part on an z/OS system running APPC/MVS. The two parts of the application could communicate using the same CPI Communications calls, even though their underlying environments are different. Programs that use only the CPI Communications calls can be ported to many other systems.

The CPI Communications calls use the SNA LU 6.2 architected verbs. Each communication call is prefixed by the letters CM; for example, CMALLC (Allocate). For more information, including languages supported, see z/OS MVS Programming: Writing Transaction Programs for APPC/MVS Using CPI Communications.

APPC/MVS TP Conversation Calls

The APPC/MVS TP conversation calls are the z/OS implementation of the SNA LU 6.2 architected verbs and are prefixed by the letters ATB. These conversation calls are similar to the CPI Communications calls except that the z/OS versions take advantage of specific z/OS functions. For example, the z/OS Send_Data call (ATBSEND) can send data residing in a data space—something the CPI Communications Send call cannot do.

Like the CPI Communications calls, the APPC/MVS TP conversation calls can be issued from a high-level language such as COBOL, C, PL/I, FORTRAN, and REXX, or from assembler language programs.

Unlike the CPI Communications calls, programs issuing the z/OS calls are not portable to other systems.

APPC/MVS TP Advanced Calls

The z/OS advanced TP calls provide unique, non-LU 6.2 architected services to TPs running in z/OS. These calls provide specific z/OS functions, such as the ability to extract information about communications resources used by APPC/MVS transaction programs.

The advanced calls can be issued from high-level languages other than REXX, and from assembler language programs.

APPC/MVS Allocate Queue Services Calls

The APPC/MVS allocate queue services calls allow a server address space on z/OS to own and manage inbound allocate requests. Servers own allocate requests by registering for them through the Register_For_Allocates callable service.

Rather than directing such requests to a transaction scheduler, APPC/MVS places allocate requests for which a server has registered on a structure called an allocate queue. APPC/MVS queues allocate requests on a first-in, first-out (FIFO) basis. Servers process allocate requests by selecting them from allocate queues and performing the requested function.

The allocate queue services, which can be called from a high-level language such as COBOL, C, PL/I, FORTRAN, and REXX, or from assembler language programs, are described in z/OS MVS Programming: Writing Servers for APPC/MVS.

The allocate queue services calls are not based on the LU 6.2 architecture.

APPC/MVS System Service Calls

Another type of APPC/MVS callable service provides access to system services not normally used by transaction programs. These services are used by other z/OS components, subsystems, and transaction schedulers, which run in supervisor state or PSW key 0-7. The system services calls can be called from assembler and high-level languages other than REXX, and are documented in z/OS MVS System Messages, Vol 3 (ASB-BPX).

The z/OS system service calls are not based on the LU 6.2 architecture.

APPC/MVS operates primarily in two startable MVS address spaces, APPC and ASCH. The APPC/MVS communication functions run in the APPC address space and the APPC/MVS transaction scheduler functions run in the ASCH address space.

Transactions residing in z/OS can be scheduled by the APPC/MVS transaction scheduler or by an installation-defined scheduler. Transactions can also be routed directly to an APPC/MVS server address space, rather than being scheduled.

If an installation or product requires a specialized scheduler, APPC/MVS provides system services that allow you to write a customized transaction scheduler, or to specify a scheduler in addition to the APPC/MVS transaction scheduler. However, before using an alternate transaction scheduler, you should first investigate using an APPC/MVS server.

1. Make basic design decisions:
   • What functions (including MVS services or data) do you want the application to provide?
   • Do you want to use CPI Communications for portability, use APPC/MVS services for MVS-specific functions like the use of data spaces or asynchronous processing, or combine the two types of services?
   • Will the transaction program on z/OS run under the APPC/MVS transaction scheduler with a schedule type of standard or multi-trans, will it run under another transaction scheduler, or will it be processed by an APPC/MVS server?
2. Code the transaction program and its partner:
   • Code the APPC/MVS TP to hold a conversation with a partner program, using appropriate callable services based on your design decisions.
   • Code the partner program and have it installed on the desired system. Ensure that the appropriate system programming steps are taken (Steps 1-3 shown in System Programming Steps) if the partner program is to run under the APPC/MVS transaction scheduler.
   • Test the transaction program and its partner:
     • For inbound TPs, write a TP test shell or use TSO/E TEST.
     • Optionally, supply TP profile information.
     • Supply side information, if the TP allocates a conversation using a symbolic destination name.
     • Test an inbound TP under its test shell or under the control of a user-level TP profile.

For details about these system programming steps needed to prepare your MVS/ESA system for APPC/MVS communications, see z/OS MVS Planning: APPC/MVS Management.

1. Create one or more TP profile files and make entries for all inbound APPC/MVS transaction programs that are to be scheduled in response to inbound allocate requests. Inbound requests that are destined for an APPC/MVS server are not scheduled, and therefore do not require a TP profile.
2. Create a side information data set and make entries for any symbolic destination names that local programs use to identify their partners on outbound allocate requests or Register_For_Allocates requests.
3. Define local LUs and associate a TP profile file name and scheduler for them through LUADD statements in APPCPMxx members of the parmlib concatenation. You can also define LUs that are not to be associated with a transaction scheduler (with the NOSCHED option on the LUADD statement).
4. Define the APPC/MVS local LUs in SYS1.VTAMLST and the logon mode names in SYS1.VTAMLIB.
5. Define classes for the APPC/MVS transaction scheduler in parmlib member ASCHPMxx, and assign TPs to those classes in their TP profile entries.
6. Optionally, define LUs, TPs, and APPC/MVS servers to RACF for security checking. For information about defining security for APPC/MVS servers, see z/OS MVS Programming: Writing Servers for APPC/MVS.

SYS1.SAMPLIB contains examples showing how to install and run APPC applications. The examples are contained in the SYS1.SAMPLIB members whose names begin with ATBCA and ATBLA. See the ATBALL member of SYS1.SAMPLIB for descriptions of the examples.