HOME | SEARCH | CONTACT | PDF FILES | WHAT'S NEW
TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC
|
|
|
BEA eLink for Mainframe SNA 3.1 Information Center |
|
HOME | SEARCH | CONTACT | PDF FILES | WHAT'S NEW |
||
|
TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC |
||
This section covers the following topics:
This section is intended for application programmers who implement and integrate BEA TUXEDO and host enterprise applications using Application Program-to-Program Communication (APPC). Although primarily oriented toward BEA TUXEDO application developers, it is also useful for non-TUXEDO application developers seeking to understand the relationship between the environments.
BEA eLink for Mainframe SNA software gives BEA TUXEDO applications access to host APPC programs acting as servers. At the same time, APPC applications can act as clients and access BEA TUXEDO system services. Because the client and server programs must be written for separate and very different environments, eLink SNA allows the applications to be written using native programming facilities:
Overview
Programmers in each environment can continue to use the tools with which they are familiar to develop application software. It is not important that a programmer be well versed in the programming facilities of the other environments. What is important, however, is proper coordination between the applications running in each environment.
This section explains the various options offered by the eLink SNA domain and illustrates the most effective ways to implement these options.
The eLink SNA system supports non-transactional IMS servers using either the implicit APPC support for IMS or the explicit APPC interface using APPC/MVS calls from a user application.
Implicit APPC is similar and more convenient than the CICS/ESA DPL. Any IMS program that gets from and puts messages to the IMS message queue can be used without change as either a client or server.
Note:
BEA eLink for Mainframe SNA does not currently support CONFIRM and SYNCPOINT IMS operations. When specifying synchronization levels for IMS operations, you must use MAXSYNCLVL=0 (none) in the DM_SNALINKS section of the DMCONFIG file. That is the default.
To use the implicit APPC capabilities of IMS, you must modify the APPCM file in the SYS1.PARMLIB library provided with your eLink SNA software. The configuration parameters in this file associate the LU with the IMS scheduler. You must identify the LU representing the application name used by eLink SNA to access the IMS region and the IMS system ID which provides scheduling for inbound requests.It is important to discuss with mainframe support personnel the changes you make to the APPCM file.
In Listing 6-1, the VTAM application major node is designated to be MVSLUO1 and the scheduling facility is designated to be the IMS control region IVP4.
APPC/IMS Programming
Listing 6-1
APPCM File in SYS1.PARMLIB Library (Example Only)
SYS1.PARMLIB(APPCMxx)
LUADD ACBNAME(MVSLU01) BASE TPDATA(SYS1.APPCTP),
SCHED(IVP4),
SIDEINFO DATASET(SYS1.APPCSI)
SYS1.VTAMLST(MVSLU01)
MVSLU01 APPL ACBNAME=MVSLU01, ACBNAME FOR APPC C
APPC=YES, C
AUTOSES=3, C
DDRAINL=NALLOW, C
DLOGMOD=APPCHOST, C
DMINWNL=3, C
DMINWNR=3, C
DRESPL=NALLOW, C
DSESLIM=6, C
LMDENT=19, C
MODETAB=APPCTAB, C
PARSESS=YES, C
SECACPT=CONV, C
SRBEXIT=YES, C
VPACING=1
The job which starts the IMS subsystem should have the APPC parameter set to Y. The example in Listing 6-2 illustrates such a job, but is not intended to be used under actual conditions. Use your own custom job for starting IMS.
Listing 6-2 IMS Subsystem Start Job (Example Only
)IVP51F41 EXEC,PROC=IMSFP,TIME=(1440),,
AGN=IVP, AGN NAME
SOUT='*', SYSOUT CLASS
MBR=DFSIVAG, PROGRAM NAME
PSB=DFSIVPG, PSB NAME
NBA=06, INITIAL FAST PATH DB BUFFERS
OBA=05, SECONDARY FAST PATH DB BUFFERS
TLIM=10, IFP TERMINATION LIMIT
SOD=, SPIN-OFF DUMP CLASS
IMSID=IVP4, IMSID OF IMS CONTROL REGION
APPC=Y, ENABLE IMPLICIT APPC
PREINIT=DC PROCLIB DFSINTXX MEMBER
This subsection covers the following topics:
The CICS/ESA Intersystem Communications (ISC) facility permits multiple independent CICS/ESA systems, normally executing on different hosts and possibly different computing platforms, to cooperate while performing various computing tasks.
CICS/ESA defines a set of five distinct services with ISC as a common foundation:
About CICS/ISC
The first four ISC services are categorized as implicit. These services are not used directly by user-written CICS/ESA applications, but are employed indirectly and automatically by the CICS/ESA system on behalf of them. The services are supported between peer CICS/ESA systems; for example, between two mainframe CICS/ESA systems connected by an ISC link. Currently, eLink SNA software supports DPL for BEA TUXEDO.
DTP, on the other hand, is an explicit service that can be used by CICS/ESA applications to cooperatively distribute business functionality. The eLink SNA software supports DTP services between peer CICS/ESA systems, as well as between CICS/ESA systems and non-CICS/ESA systems (for example, a DTP application conversing with an APPC/MVS application). The eLink SNA software also supports DTP for BEA TUXEDO ATMI applications.
CICS/ESA applications may also use another form of intersystem communication, called Multi-Region Operation (MRO). MRO is typically used to improve the performance of a CICS/ESA system by partitioning it into multiple, physically distinct regions.
MRO can be compared to a BEA TUXEDO Multi-Processor (MP) environment. In a two-platform MP application domain, the first platform might be dedicated to handle terminal and workstation clients, and the second platform might be dedicated to handle the application logic and file services. In a similar MRO configuration, all terminals might be placed in one CICS/ESA region (called a terminal-owning region), and applications and data stores might be placed in another CICS/ESA region (called an application-owning or file-owning region).
The biggest difference between this MP environment and the MRO configuration is that the MP environment spans multiple platforms, whereas the MRO configuration resides on a single host.
The eLink SNA software does not relate directly to the MRO single platform nature. However, it does support ISC operations.
The ISC facility provides a mechanism for multiple CICS/ESA systems operating on different host computers to communicate with each other, but ISC is more than a simple communications mechanism. It implements a well-defined set of protocols by which connected CICS/ESA systems cooperate in the execution of recoverable, distributed units of work. This important concept is fundamental to understanding the relationship between connected CICS/ESA systems.
IBM's Systems Network Architecture (SNA) defines the protocols for communications between IBM systems in a multi-system environment. ISC is an implementation of a specific SNA protocol known as Advanced Program-to-Program Communications (APPC, also referred to as LU TYPE 6.2 or LU 6.2).
The ISC for APPC is not a strict implementation of the SNA architecture specification. In particular, CICS/ESA makes use of special Function Management Headers (FMH) which are not part of the SNA architecture specification. Other deviations are documented in the IBM Distributed Transaction Programming Guide.
Although ISC can be used to connect CICS/ESA systems residing on a single host computer, ISC is normally used to connect CICS/ESA systems which reside on physically-distinct host computers. Furthermore, systems which are geographically separated may be connected.
IBM's Advanced Communication Facility / Virtual Telecommunications Access Method (AFC/VTAM) is used to define and implement a logical connection between two CICS/ESA systems. Using the VTAM facilities, CICS/ESA systems establish one or more concurrent sessions for communications. Each session supports one logical conversation between the two systems. These logical conversations carry the inter-system traffic associated with the various ISC functions.
Similar to BEA TUXEDO conversational service requests, LU 6.2 is a half-duplex protocol; that is, session traffic can flow in only one direction at a time. The session partners are responsible for coordinating their use of the session such that when one is sending, the other is receiving. Both session partners cannot send (or receive) at the same time.
This ISC service allows an application to start a transaction on a remote system. Unlike DPL and Function Request Shipping, the calling application does not wait for the remote task to complete. The calling transaction initiates an asynchronous process with the CICS/ESA interval START command. Information can be passed to the back-end transaction in the FROM option of the START COMMAND. The back-end transaction can then issue a RETRIEVE command to get this data. The transaction can be defined as remote, indicating the system on which the transaction is to be run, or the remote system can be named explicitly in the SYSID option of the START command.
Remote resources, such as VSAM files, DLI requests, Transient Data Queues, and Temporary Storage Queues can be made available to a local application. The application is not necessarily aware that the requested resource is on another CICS/ESA region. Files and Queues are defined as remote with system administration utilities, but could optionally be specified as remote using the SYSID option of the resource request command.
Transaction routing provides a terminal connected to a CICS/ESA region with the ability to run a transaction on another CICS/ESA region in a fashion transparent to the terminal user. A transaction can be defined as a remote transaction in the system initialization table. This definition indicates on which remote system the transaction is to run.
Distributed Program Link (DPL) allows a CICS/ESA program to call (link to) another CICS/ESA program located on a remote system. This is a synchronous process; control does not return to the calling program until the called program has finished executing. See Figure 6-1 for a generic example of the DPL process.
In most cases, DPL is completely transparent to both the calling and called programs. An application program is not aware that it is calling a program located on a remote system.
The remote program is minimally constrained. It can access files and databases, as well as link to other programs, but it cannot perform terminal I/O. Also, it does not provide recovery and restart of CICS/ESA-controlled resources, such as files and databases; implicit support is provided automatically by the CICS/ESA system.
Note:
If a client sends a data buffer to a remote CICS/ESA system as part of a DPL and no data is modified, the remote system returns no data and the length is zero.
Multi-Region versus Multi-Processor Operations
ISC Operations
Asynchronous Processing
Function Request Shipping
Transaction Routing
Distributed Program Link
Figure 6-1 Generic DPL Transaction
Step-by-Step Description: Generic DPL Transaction
TRN1, executing on CICS/ESA System A, issues an
EXEC CICS LINK to program PRG002, which resides on CICS/ESA System B.
TRN1 "waits" while the LINK request is processed.
Distributed Transaction Processing (DTP) is the only ISC services that provides for direct, application-to-application communications. DTP takes place between two conversation partners, both of which are normally user-written CICS/ESA applications. One conversation partner initiates a conversation with a counterpart on a remote system, and must explicitly identify the remote system. The conversation partner on the remote system must accept the requested conversation. Using the full capabilities of ISC, DTP applications send and receive application-defined data streams and engage in a series of application-defined interactions. See Figure 6-2 for a generic example of the DTP process.
Figure 6-2 Generic DTP Transaction
TRN1, invokes program PGM0001 executing on CICS/ESA System A.
TRN2, executing on CICS/ESA System B, invokes program PGM002.
PGM0001 sends data to program PGM0002, then relinquishes control to
PGM002.
PGM0001 and PGM0002 synchronize the data, acknowledge the conversation, and
end the conversation.
DTP offers the best of two worlds. On one hand, it provides support for completely customized application protocol semantics. On the other hand, it allows the applications to select the desired level of support for resource recovery and restart:
Note:
It is important to understand that, by definition, ISC operates only at sync-level 2.
DTP conversations are LUTYPE 6.2 conversations. They are a half-duplex form of data exchange between two transactions. It is half-duplex because only one side of the conversation can send data at a time. A conversation is initiated by the application using the Application Program-to-Program Communication (APPC) protocol. Because of this, the application must be coded to respect the various conversation states. These states are documented in the IBM CICS/ESA Intercommunication Guide and identify which APPC verbs are legal at the various stages of a conversation. LUTYPE 6.2 conversations can be mapped or unmapped conversations.
Unmapped or base-level conversation support is the minimum support level required for LUTYPE 6.2 product implementation. Mapped conversations are at a higher level than base conversations and do not require the application to be aware of the SNA data stream format. The state transitions are less restrictive and the command set is more robust. In addition to this, the application has access to CICS/ESA data areas to determine the status of the conversation and the results of certain APPC commands.
In general, the synchronization level determines the cooperation between communicating partners needed to coordinate changes to their respective resources (such as files and databases). It also defines specific protocol flows required to support a requested synchronization level. The APPC architecture defines three distinct levels of synchronization. These three levels are Level 0, Level 1, and Level 2 (corresponding to the SNA-defined levels of NONE, CONFIRM, and SYNCPOINT, respectively).
No synchronization at the protocol level is provided. This level is used when synchronization is not required or supported. This is very similar to non-transactional TUXEDO System service requests.
This level supports the exchange of private, application-level, synchronization requests between conversing partners. These partners, or applications, are totally responsible for defining and executing the synchronization process to ensure the integrity of all resources. The CICS/ESA system is not involved in the synchronization process at this level. There is no confirm capability in the TUXEDO System. Any CICS/ESA application attempting to initiate a sync-level 1 operation with TUXEDO causes an error condition.
At this level, the CICS/ESA system is fully involved in the synchronization process and provides complete, automatic support of sync-pointing, including rollback. The CICS/ESA system defines and coordinates the synchronization process and is responsible for ensuring the integrity of all CICS/ESA-managed resources.
In the case of DTP, the communicating applications participate in the synchronization process and are responsible for the management and integrity of any non-CICS/ESA resources to which they gain access.
Because DTP takes place between two application-level conversation partners, it may operate at any of the three defined synchronization levels. In other words, the conversation partners are permitted to specify the desired level of synchronization and participate in the synchronization process only to the extent specified.
If the user DTP conversation is at sync-level 0 or 1, the CICS/ESA system does not propagate sync-points from one system to another via the conversation. Thus the user can explicitly suspend CICS/ESA ACID Properties. A DTP conversation at sync-level 2 causes a CICS/ESA system to propagate sync-points automatically via the conversation as well as via subordinate conversations.
DPL can also operate at sync-level 1, in which case the user is responsible for maintaining the ACID properties. Sync-level 1 DPL conversations usually occur because one or both of the systems are incapable of operating at sync-level 2. The eLink SNA software can support DPL requests at both sync-levels 1 and 2, and can support DTP conversations at sync-levels 0 and 1.
The /Domain's global timer is used to determine excessive time for a service request. If a time-out occurs, a FAILURE indication is raised and The eLink SNA software sets Refer to Appendix D, "Error Messages," for error code listings.
This section provides Transaction scenarios for the following programming environments supported by eLink SNA:
CICS/ESA Sync-Levels
Level 0 (NONE)
Level 1 (CONFIRM)
Level 2 (SYNCPOINT)
Time-out and Error Handling
tperrno is set to TPETIME. The domain gateway cleans up any resources allocated to the failed communication.
tperrno values when an error occurs. Appendix B, "ATMI to CPI-C Function Mapping," describes the CPI-C return codes and their mapping to ATMI return codes.
Application-to-Application Programming
Using the eLink SNA gateway, BEA TUXEDO applications can make ATMI service calls to invoke programs running in a remote CICS/ESA DPL environment. CICS/ESA programs can in turn use the Consider the program issuing the distributed link request or ATMI service request to be the Client program. Consider the executing remote program or service to be the Server program. The client does not have to be aware of the server's location.
BEA TUXEDO programs can use both the request/response and conversational models to invoke programs on the host. (However, request/response models are preferred.)
Local and remote services are defined with the Host DPL requests, in turn, can also be compared to BEA TUXEDO services using either call model. The request/response model is very similar to DPL. The conversational model, although supported in DTP, is less efficient and programmatically more complex than the request/response model. It is recommended that you use a DTP model when invoking conversational transactions.
It is also recommended you use a DPL model when invoking the same request/response or conversational request multiple times in a single transaction. With DPL, ISC starts a long-running mirror transaction to the CICS/ESA DPL server, enabling the server to process each of the requests over the same conversation. With DTP, each of the requests establishes a separate conversation with the server and the conversation remains outstanding until the transaction is committed.
The eLink SNA software employs a special feature that enables BEA TUXEDO clients to invoke CICS/ESA server programs and, conversely, CICS/ESA client programs to invoke BEA TUXEDO services. Based on the IBM CICS/ESA mirror transaction, this feature facilitates DPL requests to/from a remote region. The feature is called Mirror Transaction Identifier Support and it involves special treatment of the transaction ID ( This subsection discusses DPL fundamentals related to this feature and describes how eLink SNA software does the following:
Distributed Program Link (DPL)
EXEC CICS LINK command to invoke user-defined BEA TUXEDO services. This feature is available to either new or existing CICS/ESA programs and BEA TUXEDO applications. DPL can only be used by BEA TUXEDO application domains connected to a CICS/ESA system.
FUNCTION=DPL option in the DM_LOCAL_SERVICES and DM_REMOTE_SERVICES section in the DMCONFIG file, indicating that the DPL ISC function is invoked.
Special Treatment of TRANSID for DPL
TRANSID) that is part of every DPL request.
TRANSID to outbound requests only
In the CICS/ESA context, DPL requests are treated as mirror transactions, which include attachment of the server program to the requestor's When a server program receives a DPL request from a remote region, the mirror task services the request. The task attaches the request to a mirror transaction, typically CVMI for SYNCONRETURN requests or CSMI for transactional requests. The mirror task then attaches the appropriate mirror transaction to the requestor's
Note:
Implicit attachment of alternate mirror transaction identifier is not supported for inbound DPL requests to BEA TUXEDO services.
The other scenario is explicit attachment. The DPL requestor names the For outbound requests from BEA TUXEDO domains to remote CICS/ESA regions, this For inbound requests from a remote CICS/ESA region to a local BEA TUXEDO domain, the Figure 6-3 depicts an implicit attachment using the requestor's
Note:
The eLink SNA software does not support implicit attachment of TRANSID to inbound requests for BEA TUXEDO services.
CICS/ESA Fundamentals Relating to Alternate Mirror TRANSID
TRANSID. Two scenarios are possible: implicit attachment (default) and explicit attachment.
TRANSID, found in the requestor's EIBTRNID field. This is implicit attachment (default).
TRANSID that should be attached to the request instead of the default CSMI or CVMI.
TRANSID can be included in the API command (tpcall). The TRANSID must be defined in the program resource definition for the destination region and it must point to the mirror task DFHMIRS.
TRANSID is paired with a PROGRAM name to explicitly name an advertised service.
Implicit Attachment of TRANSID
TRANSID. The outbound tpcall invokes a service from the remote CICS/ESA region, but does not explicitly name a TRANSID. Instead, the TRANSID of the requestor is passed to the region as an invoking TRANSID. The mirror transaction (CSMI or CVMI) is attached and starts the mirror program, which attaches the requestor's TRANSID found in its EIBTRNID field. The mirror task then calls the application program.
Figure 6-3 Implicit Attachment of TRANSID (Outbound Requests Only)
TRN1DATA, which is
advertised as a remote service in the DMCONFIG file. It is a DPL request to a
program named SVC1 in the CICS/ESA region.
Explicit attachment names the TRANSID to be attached instead of the default mirror transaction, CSMI or CVMI. The client might use the explicit method for the following reasons:
TRANSID, or impose scheduling constraints on the transaction itself.
Explicit attachment can be used for both outbound and inbound DPL requests. You can specify the The following example shows how to provide a A where:
TRANSID in the API command or in the RNAME parameter for the service definition in the DMCONFIG file.
TRANSID in the API command:
EXEC CICS LINK PROGRAM("SERVICE1")
SYSID("AIX1")
TRANSID("TRN1")TRANSID for an outbound DPL request is specified in the DM_REMOTE_SERVICES section of the DMCONFIG file. Conversely, a TRANSID for an inbound DPL request is specified in the DM_LOCAL_SERVICES section. The format for the TRANSID and server name in the DMCONFIG file entry is as follows:
RNAME=AAAA:BBBBBBBB
AAAA
TRANSID
BBBBBBBB
The colon is required to indicate the TRANSID/program name combination. The TRANSID must be composed of acceptable CICS/ESA characters:
A-Za-z0-9$@#./-_%&Q¢?!|"=,;<>
The following paragraphs discuss explicit attachment of TRANSID to both outbound requests for remote CICS/ESA services and to inbound requests for BEA TUXEDO services.
Figure 6-4 depicts the explicit attachment of the TRANSID to an outbound request for services in a remote CICS/ESA region. The TRANSID can be provided in the API command or in the remote-service definition in the DMCONFIG file. The RNAME value in the DMCONFIG file is used to create the alternate mirror ID and invoke the remote server.
The request passes the transaction ID of the mirror transaction to the remote CICS/ESA region. This transaction ID is defined in the remote region and must point to the mirror program DFHMIRS. When the mirror program invokes the application program, the transaction ID is passed to the program in the EIBTRNID field.
Figure 6-4 Explicit Attachment of TRANSID for Outbound Requests
SERVICE1, which is
advertised as a remote service in the DMCONFIG file. The FUNCTION option
indicates the remote service is invoked as a DPL.
Figure 6-5 depicts the explicit attachment of the TRANSID to inbound request for services in a BEA TUXEDO local domain. The TRANSID can be provided in the API command or in the local-service definition in the DMCONFIG file. The TRANSID named in the API command or in the requested program name must exactly match an RNAME in the DM_LOCAL_SERVICES section of the DMCONFIG file.
Figure 6-5 Explicit Attachment of TRANSID for Inbound Requests
INSVC1, which is a local BEA
TUXEDO service. The SYSID and PROGRAM values in the request identify the local
system and the name of the local service. The TRANSID option indicates the mirror
transaction to be initiated.
SERVICE1, which is advertised locally in the BEA TUXEDO
application, is initiated.
You must enter the alternate mirror transaction and remote server name as RNAME values in both the DM_LOCAL_SERVICES and DM_REMOTE_SERVICES sections of the DMCONFIG file, using the format shown previously in the "Inbound Requests" section.
For outbound requests to a CICS/ESA server, the RNAME value in the DMCONFIG file is used to create the alternate mirror ID and invoke the remote server.
For inbound requests, the TRANSID named in the API command or in the PROGRAM definition is used along with the requested program name to exactly match an RNAME associated with a local service entry.
Note:
If an RNAME is not found with both the transaction ID and the PROGRAM name, an error is returned to the CICS/ESA client.
Do not insert trailing spaces between the TRANSID and colon in the RNAME option. The eLink SNA software automatically discards trailing spaces before attempting to match RNAME values.
If the specified TRANSID/PROGRAM combination in a service name (either local or remote) is not a DPL, eLink SNA software returns an error which is not detected until run time.
To translate a TUXEDO ATMI request to an EXEC CICS LINK request, the eLink SNA gateway uses the INBUFTYPE and OUTBUFTYPE of the remote service to create the COMMAREA for the DPL program.
For each remote service defined in the DMCONFIG file REMOTE_SERVICES section, INBUFTYPE is a description of the data that the service receives (the format of the request) and OUTBUFTYPE is a description of the data that the service sends as a response.
When a DPL program is invoked, it receives the request data in a COMMAREA. When the program completes, it returns this same COMMAREA to the program that invoked it. The DPL program cannot change the size of the COMMAREA; therefore, the COMMAREA must be large enough to hold both the request and the reply.
Before the gateway invokes a DPL program, it uses the INBUFTYPE and OUTBUFTYPE to calculate this size. Because CARRAY and STRING do not have sizes associated with them, the maximum size is used (4096 bytes).
Note:
You cannot specify a response buffer in a tpcall or a tpacall for the purpose of sizing a COMMAREA. The gateway is unaware of the size of the response buffer that is specified in the tpcall, and in tpacall, the response buffer is not specified until the reply is retrieved with tpgetreply.
The best approach is to use VIEW types as the INBUFTYPE and OUTBUFTYPE of DPL programs. This allows the size of the request and response to be described in exact detail. Refer to the examples below:
Listing 6-3 Example of DMCONFIG File Entry Specifying VIEWS to Size the COMMAREA
*DM_REMOTE_SERVICES
SIMPDPLV AUTOTRAN=N
LDOM="simpsnad"
RDOM=SIMPSNAG
CONV=N
RNAME="TOUPDPLS"
INBUFTYPE="VIEW:reqstr"
OUTBUFTYPE="VIEW:respstr"
FUNCTION="DPL
The following listing shows the corresponding view descriptions:
Listing 6-4 Descriptions of VIEWS for Sizing COMMAREA
VIEW reqstr
#TYPE CNAME FBNAME COUNT FLAG SIZE NULL
string reqstring - 1 - 20 " "
END
VIEW respstr
#TYPE CNAME FBNAME COUNT FLAG SIZE NULL
string respstring - 1 - 50 " "
END
The following listing shows the code used for a client that requests the SIMPDPLV application:
Listing 6-5 Program Using Views to Size COMMAREA
/* Include header file generated by views -n myviews.v */
#include "myviews.h"
sendbuf = (struct reqstr *) tpalloc("VIEW", "reqstr", sizeof(struct reqstr)); rcvbuf = (struct respstr *) tpalloc("VIEW", "respstr", sizeof(struct respstr)); tpcall("SIMPDPLV", (char *) sendbuf, 0, (char **) &rcvbuf, &rcvlen, (long)0);In the previous examples, the two VIEWs describe a request string of length 20 and a response string of length 50; therefore, the COMMAREA created can hold a string of 50 characters.
The examples in this section represent a few of the many programming scenarios available for using DPL and BEA TUXEDO service invocations. These examples employ the most natural and efficient approaches.
Note: To run Transaction client/server scenarios, the eLink SNA software must be licensed for sync-level 2 operations.
(This page intentionally blank.)
Figure 6-6 TUXEDO Client Request/Response to CICS/ESA DPL
toupsrv service.
TOUPDPLS program and passes idata buffer
contents for processing.
TOUPDPLS program processes data.
commarea into the client's odata buffer.
Figure 6-7 TUXEDO Client Asynchronous Request/Response to CICS/ESA DPL
toupsrv service.
TOUPDPLS program and passes idata buffer
contents for processing.
TOUPDPLS program processes data.
commarea into the client's tpgetreply
odata buffer.
Figure 6-8 TUXEDO Client Asynchronous Request/Response with No Reply to CICS/ESA DPL
toupsrv service.
TOUPDPLS program and passes idata buffer
contents for processing.
HOPL invokes MIRRDPLC program.
tpreturn call returns the data into the COMM-AREA buffer.
Figure 6-10 CICS/ESA DPL to TUXEDO Request/Response Server, Service in Autonomous Transaction
H0PL invokes MIRRDPLC program.
MIRROR service request tpbegin incorporates all further operations in a
transaction.
MIRROR service processes the data.
tpreturn call returns the data into the commarea buffer.
Figure 6-11 TUXEDO Client Request/Response to CICS/ESA DPL, in Autonomous Transaction
toupsrv service.
toupsrv service issues tpbegin to start the transaction.
TOUPDPLS program and passes idata buffer
contents for processing.
TOUPDPLS program processes data.
commarea into the client's odata buffer.
Figure 6-12 Transactional TUXEDO Client Multiple Requests/Responses to CICS/ESA DPL
toupsrv service.
toupsrv service issues tpbegin to start the transaction.
TOUPDPLS program processes data.
commarea into the client's odata buffer.
toupsrv service loop end conditions
are met.
Figure 6-13 Transactional CICS/ESA DPL to TUXEDO Request/Response Server
H2PL invokes MIRRDPLC program.
MIRROR service processes the data.
tpreturn call returns the data into the commarea buffer.
The following examples represent a few programming scenarios for using DTP and BEA TUXEDO service invocations.
The recommended method of performing DTP services is to use BEA TUXEDO conversational services instead of request/response services. The conversational service enables a client and a server to communicate as needed over the eLink SNA session conversation.
Although it is most suited for the DPL environment, the tpcall is used in the examples for a request/response to a DTP server.
It is recommended you use a DPL model when invoking multiple request/response calls in a single transaction. With DPL, a long-running mirror transaction to the CICS/ESA DPL server is started, enabling the server to process each of the requests over the same conversation. With DTP, each of the ATMI requests will establish a separate conversation; the conversation remains outstanding until the transaction is committed.
The examples in this section represent a few of the many programming scenarios available for using DTP and BEA TUXEDO service invocations. These examples employ the most natural and efficient approaches.
Note: To run transactional client/server scenarios, the eLink SNA software must be licensed for sync-level 2 operations.
Figure 6-14 TUXEDO Client Request/Response to CICS/ESA DTP
toupsrv service.
DTPS starts TOUPDTPS program.
EXEC CICS RECEIVE command receives the idata buffer contents for
processing.
TOUPDTPS program processes data.
Figure 6-15 TUXEDO Client Asynchronous Request/Response to CICS/ESA DTP
toupsrv service.
TOUPDTPS program.
EXEC CICS RECEIVE command receives the idata buffer contents for
processing.
TOUPDTPS program processes data.
Figure 6-16 TUXEDO Client Asynchronous Request/Response with No Reply to CICS/ESA DTP
toupsrv service.
TOUPDTPS program.
EXEC CICS RECEIVE command receives the idata buffer contents for
processing.
TOUPDTPS program processes data.
Figure 6-17 TUXEDO Conversational Client to CICS/ESA DTP, Server Gets Control
toupsrv service.
TOUPDTPS program.
EXEC CICS RECEIVE command receives the idata buffer contents for
processing.
TOUPDTPS program processes data.
Figure 6-18 TUXEDO Conversational Client to CICS/ESA DTP, Client Sends/Receives Data
toupsrv service.
TOUPDTPS program.
EXEC CICS RECEIVE command receives the tpconnect idata buffer
contents for processing.
TOUPDTPS program processes data.
EXEC CICS RECEIVE command receives the tpsend idata contents into
the server's IN-BUFFER.
Figure 6-19 TUXEDO Conversational Client to CICS/ESA DTP, Client Grants Control
toupsrv service.
TOUPDTPS program.
EXEC CICS RETURN ends the conversation, communicated to the tprecv as
TPEV_SVCSUCC.
Figure 6-20 CICS/ESA DTP to TUXEDO Conversational Server, Client Retains Control
H0TP invokes MIRRDTPC program.
EXEC CICS ALLOCATE acquires a session to the remote BEA TUXEDO
domain.
Figure 6-21 CICS/ESA DTP to TUXEDO Conversational Server, Client Relinquishes Control
MIRRDTPC program.
EXEC CICS ALLOCATE acquires a session to the remote BEA TUXEDO
domain.
EXEC CICS SEND command relinquishes control with the INVITE WAIT
option.
EXEC CICS RECEIVE command receives the tpsend idata buffer contents
into the IN-BUFFER.
Figure 6-22 Transactional TUXEDO Client Request/Response to CICS/ESA DTP
Note: This is not the recommended method of performing a DTP transactional service. Please refer to the transactional DPL using request/response for the recommended method.
toupclt invokes toupsrv service. (Note that each tpcall
made in the program must be bookended with a tpbegin and a tpcommit.)
tpbegin to start a transaction.
TOUPDTPS program.
EXEC CICS RECEIVE command receives the idata buffer contents for
processing.
TOUPDTPS program processes data.
Figure 6-23 Transactional TUXEDO Conversational Client to CICS/ESA DTP, Server Gets Control
toupsrv service.
toupsrv service issues tpbegin to start the transaction.
TOUPDTPS program.
EXEC CICS RECEIVE command receives the idata buffer contents for
processing.
MIRRDTPC program.
EXEC CICS ALLOCATE acquires a session to the remote BEA TUXEDO
domain.
EXEC CICS ISSUE CONFIRMATION verb responds positively to the confirm
request.
EXEC CICS FREE verb explicitly frees the outstanding conversation.
The Common Programming Interface for Communications (CPI-C) is an implementation choice for program-to-program communications. The reason that CPI-C may be used over other implementations is that CPI-C defines a single programming interface to the underlying network protocols across many different programming languages and environments.
Also, you can use the CPI Resource Recovery interface to provide a consistent interface to system services that allow your programs to coordinate data exchange and updates of databases and resources.
The examples in this section show the protocol exchanges between the local BEA TUXEDO and remote host application program. With BEA TUXEDO, the type of ATMI service request determines the nature of the client/server communication model. For requests initiated by the host application, the configuration information for the local service determines the protocol exchanges on the conversation.
The recommended method of performing APPC services is to use BEA TUXEDO conversational services instead of request/response services. The conversational service enables a client and a server to communicate as needed over the eLink SNA session conversation.
Although it is most suited for the DPL environment, the tpcall is used in the examples for a request/response to an APPC server.
It is recommended you use a DPL model when invoking multiple request/response calls in a single transaction. With DPL, a long-running mirror transaction to the CICS/ESA DPL server is started, enabling the server to process each of the requests over the same conversation. With APPC, each of the ATMI requests will establish a separate conversation; the conversation remains outstanding until the transaction is committed.
The examples in this section represent a few of the many programming scenarios available for using CPI-C and BEA TUXEDO service invocations. These examples employ the most natural and efficient approaches.
Note: To run transactional client/server scenarios or the CPI Resource Recovery interface, the eLink SNA software must be licensed for sync-level 2 operations.
Figure 6-25 TUXEDO Client Request/Response to Host CPI-C
toupsrv service.
tpname TPNCPIC invokes TOUPCPIC program.
cmrcv request receives the idata buffer contents for processing
TOUPCPIC program processes data.
cmsst request prepares the next send request by setting the send type to
CM_SEND_AND_DEALLOCATE.
Figure 6-26 TUXEDO Client Asynchronous Request/Response to Host CPI-C
toupsrv service.
tpname TPNCPIC invokes TOUPCPIC program.
cmrcv request receives the idata buffer contents for processing.
TOUPCPIC program processes data.
cmdeal flushes the data to the client, and indicates the conversation is
finished.
Figure 6-27 TUXEDO Client Asynchronous Request/Response to Host CPI-C with No Reply
toupsrv service.
tpname TPNCPIC invokes TOUPCPIC program.
TOUPCPIC program processes data.
Figure 6-28 TUXEDO Conversational Client to Host CPI-C, Server Gets Control
toupsrv service
tpname TPNCPIC invokes TOUPCPIC program.
cmrcv request receives the idata buffer contents for processing.
TOUPCPIC program processes data
cmsst request prepares the next send request by setting the send type to
CM_SEND_AND_FLUSH.
cmdeal request ends the conversation.
Figure 6-29 TUXEDO Conversational Client To Host CPI-C, Client Retains Control
toupsrv service.
tpname TPNCPIC invokes TOUPCPIC program.
TOUPCPIC program processes data.
Figure 6-30 TUXEDO Conversational Client to Host CPI-C, Client Grants/gets Control
toupsrv service.
tpname TPNCPIC invokes TOUPCPIC program.
cmrcv requests receives the indicator that control has been granted to the
server.
cmptr request flushes the data to the client, and grants control to the client.
cmdeal indicates a successful completion of the conversation to the tprecv;
no data is passed.
Figure 6-31 Host CPI-C to TUXEDO Asynchronous Request/Response Server with No Reply
MIRRCPIC is invoked using environment start-up
specifications.
Figure 6-33 Host CPI-C to TUXEDO Conversational Service, Client Retains Control
Figure 6-34 Host CPI-C TUXEDO to Conversational Service, Client Grants Control
MIRRCPIC is invoked using environment start-up
specifications.
Figure 6-35 Transactional TUXEDO Client Request/Response to Host CPI-C
toupsrv service.
toupsrv service issues tpbegin to start the transaction.
tpname TPNCPIC invokes TOUPCPIC program.
cmrcv request receives the idata buffer contents for processing.
Figure 6-36 Transactional TUXEDO Conversational Client to Host CPI-C, Server Gets Control
toupsrv service.
toupsrv service issues tpbegin to start the transaction.
tpname TPNCPIC invokes TOUPCPIC program.
cmrcv request receives the idata buffer contents sent on the tpconnect
for processing.
TOUPCPIC program processes the data.
Figure 6-37 Transactional Host CPI-C to TUXEDO Conversational Server, Client Grants Control
MIRRCPIC is invoked using environment start-up
specifications.
cmcfmd.
Additional information on the subject of CICS/ESA Intersystem Communications may be found in the following IBM publications:
