Understanding Programming Flows

Download Docs

e-docs > WebLogic Java Adapter for Mainframe > Programming Guide > Understanding Programming Flows

Programming Guide

Understanding Programming Flows

This section illustrates the interaction between WebLogic Server and mainframe programs. The following topics are discussed:

Distributed Program Link Programming Flows

The following examples of DPL programming flows are discussed:

Java Client Request/Response to CICS DPL

Figure 5-1 illustrates a Java Client Request/Response to CICS DPL programming flow.

Figure 5-1 Java Client Request/Response to CICS DPL

The following steps describe the Java Client Request/Response to CICS DPL programming flow.

A Java client class (such as a stand-alone client, EJB, etc.) makes a call to the BaseClient.toupper method with a Chardata DataView as the parameter.
In the toupper method, a call is made to the EgenClient.callService method.

Note: The BaseClient extends EgenClient, so the BaseClient inherits the callService method from EgenClient.

The value of the first parameter is TOUPPER. TOUPPER is the name of the DPL Service that is mapped to the CICS DPL program TOUPCICS in the WebLogic Administrative Console.
The host mirror transaction starts the TOUPCICS program and passes the contents of the inputBuffer byte array as the commarea.
The TOUPCICS program processes the data.
The CICS server returns the commarea. The data is returned from the EgenClient.callService method as the byte array rawResult.

CICS Request/Response DPL to WebLogic Server EJB

Figure 5-2 illustrates a CICS request/response DPL to WebLogic Server EJB programming flow.

Figure 5-2 CICS Request/Response DPL to WebLogic Server EJB

The following steps describe the CICS request/response DPL to WebLogic Server EJB programming flow.

The user-entered transaction TRCL invokes the TRADCLNT program.

The EXEC CICS LINK command causes the advertised service TRADSERV to execute. The SYSID value is set to the name of the connection associated with the CRM Logical Unit. The SYNCONTRETURN parameter indicates that the WebLogic Server EJB will not be involved in the CICS transaction.
In the WebLogic Administration Console, the TRADSERV service is mapped to the JNDI name jam.TradeServer for the TradeServer EJB. This causes the dispatch method of TradeServerBean to be invoked.
The buy method is invoked from the dispatch method.
The business logic is performed, and the result is returned to the dispatch method.
The data is returned from the dispatch method into the COMMAREA.

CICS DPL Asynchronous No Reply to WebLogic Server Application

Figure 5-3 illustrates a CICS DPL asynchronous no reply to Java server programming flow.

Figure 5-3 CICS DPL asynchronous no reply to Java server

The following steps describe the CICS DPL asynchronous no reply to Java server programming flow.

The user-entered transaction CTOJ invokes the JMSCLNT program.
The EXEC CICS LINK command causes the advertised service CTOJMSSV to execute. The SYSID value is set to the name of the connection associated with the CRM Logical Unit. The SYNCONTRETURN parameter indicates that the WebLogic Server EJB will not be involved in the CICS transaction.
The Gateway sends the message to the JMS Event CTOJMSSV. In the WebLogic Administration Console, the CTOJMSSV service name is mapped to the JMS topic Jam.examples.CICS.EventTopic.
Data that is identical to the request data is returned in the COMMAREA to JMSCLNT.

Transactional Java Client Request/Response to CICS DPL

Figure 5-4 illustrates a transactional Java client request/response to CICS DPL programming flow.

Figure 5-4 Transactional Java Client Request/Response to CICS DPL

The following steps describe the transactional Java client request/response to CICS DPL programming flow.

A Java client class calls the begin method of a UserTransaction object to start a transaction.
Within the boundaries of that transaction, the Java client class makes a call to the BaseClient.toupper method with a Chardata DataView as the parameter.
In the toupper method, a call is made to the EgenClient.callService method.

Note: The BaseClient extends EgenClient, so the BaseClient inherits the callService method from EgenClient.

The value of the first parameter is TOUPPER. TOUPPER is the name of the DPL Service that is mapped to the CICS DPL program TOUPCICS in the WebLogic Administration Console.
The host mirror transaction starts the TOUPCICS program and passes the contents of the inputBuffer byte array as the commarea.
The TOUPCICS program processes the data.
The CICS server returns the commarea. The data is returned from the EgenClient.callService method as the byte array rawResult.
The Java client class calls the commit method of the UserTransaction object to indicate the successful completion of the transaction. This causes the commit of the WebLogic managed resources, as well as the resources held by the Host Mirror Transaction.

Transactional CICS Request/Response DPL to WebLogic Server EJB

Figure 5-5 illustrates a transactional CICS request/response DPL to WebLogic Server EJB programming flow.

Figure 5-5 Transactional CICS Request/Response DPL to WebLogic Server EJB

The following steps describe the transactional CICS request/response DPL to WebLogic Server EJB programming flow.

The user-entered transaction TRCL invokes the TRADCLNT program.
The EXEC CICS LINK command causes the advertised service TRADSERV to execute. The SYSID value is set to the name of the connection associated with the CRM Logical Unit. When the SYNCONRETURN command is not included in the EXEC CICS LINK, this indicates that the WebLogic Server is involved in the CICS transaction.

In the WebLogic Administration Console, the TRADSERV service is mapped to the JNDI name jam.TradeServer for the TradeServer EJB. This causes the dispatch method of TradeServerBean to be invoked.
The buy method is invoked from the dispatch method.
The business logic is performed, and the result is returned to the dispatch method.
The data is returned from the dispatch method into the COMMAREA.
If necessary, further processing can be done in TRADCLNT before the EXEC CICS SYNCPOINT that ends the transaction.

IMS Implicit APPC Programming Flows

The following examples of IMS implicit APPC programming flows are discussed:

Java Client Request/Response to IMS Transaction Program

Figure 5-6 illustrates a Java Client Request/Response to IMS programming flow.

Figure 5-6 Java Client Request/Response to IMS Transaction Program

The following steps describe the Java Client Request/Response to IMS programming flow.

A Java client class (such as a stand-alone client, EJB, etc.) makes a call to the BaseClient.toupper method with a Chardata DataView as the parameter.
In the toupper method, a call is made to the EgenClient.callService method.

Note: The BaseClient extends EgenClient, so the BaseClient inherits the callService method from EgenClient.

The value of the first parameter is TOUPPER. TOUPPER is the name of the APPC Service that is mapped to the IMS transaction TOUPIMS in the WebLogic Administrative Console.
IMS starts the TOUPIMS transaction. This transaction executes the associated program TOUPIMS. The contents of the inputBuffer byte array are placed on an IOPCB as request data.
The TOUPIMS program accesses the request data by performing a get unique on the IOPCB.
The TOUPIMS program processes the data and creates a response message.
The TOUPIMS program inserts the response data to the IOPCB.
IMS returns the response data back to the requester. The data is returned from the EgenClient.callService method as the byte array rawResult.

IMS Asynchronous No Reply Transaction Program to Java Server

Figure 5-7 illustrates an IMS asynchronous no reply transaction program to a Java server programming flow.

Figure 5-7 IMS Asynchronous No Reply Transaction Program to Java Server

The following steps describe the IMS transaction program to asynchronous no reply Java Server programming flow.

IMS starts the IMSTOJMS transaction. This transaction executes the associated program IMSTOJMS.
The IMSTOJMS program accesses the input data by doing a get unique on the IOPCB.
The IMSTOJMS program composes the request message.
The IMSTOJMS program issues a call with the CHNG function code to store the appropriate logical terminal name in a modifiable alternate PCB.

Note: To use an alternate PCB, you must include a PCB statement in your PSB (see Listing 5-1).

Listing 5-1 IMS PSBGEN for a Modifiable Alternate PCB for the IMS Client

PCB   TYPE=TP,MODIFY=YES
PSBGEN PSBNAME=IMSTOJMS,CMPAT=YES,LANG=COBOL

Note: The logical terminal name, in this case JAMIMS01, must be mapped to an LU name and a transaction name in a LU 6.2 Descriptor. In Listing 5-2, JAMIMS01 is mapped to the LU CRMLU and the transaction ITOJMSSV.

Listing 5-2 LU 6.2 Descriptor

A JAMIMS01 LUNAME=CRMLU TPNAME=ITOJMSSV SYNCLEVEL=N

The IMSTOJMS program issues an insert call with the request message to the alternate PCB, ALTPCB.
The IMSTOJMS program issues a PURG call to the alternate PCB, ALTPCB, to tell IMS to send the request message.
IMS sends the request message to the indicated LU, the LU configured for the CRM. The request message is forwarded to the Gateway.
The gateway sends the message to the JMS Event ITOJMSSV. ITOJMSSV is the transaction name in the LU 6.2 descriptor in Listing 5-2. In the WebLogic Administration Console, the ITOJMSSV service name is mapped to the JMS topic JAM.examples.IMS.EventTopic.

Transactional Java Client Request/Response to IMS Transaction Program

Figure 5-8 illustrates a transactional Java client request/response to an IMS transaction programming flow.

Figure 5-8 Transactional Java Client Request/Response to an IMS Transaction Program

The following steps describe the transactional Java client request/response to IMS transaction programming flow.

A Java client class calls the begin method of a UserTransaction object to start a transaction.
Within the boundaries of that transaction, the Java client class makes a call to the BaseClient.toupper method with a Chardata DataView as the parameter.
In the toupper method, a call is made to the EgenClient.callService method.

Note: The BaseClient extends EgenClient, so the BaseClient inherits the callService method from EgenClient.

The value of the first parameter is TOUPPER. TOUPPER is the name of the APPC Service that is mapped to the IMS transaction TOUPIMS in the WebLogic Administration Console.
IMS starts the TOUPIMS transaction that executes the associated program TOUPIMS. The contents of the inputBuffer byte array are placed on an IOPCB as request data.
The TOUPIMS program accesses the request data by doing a get unique on the IOPCB.
The TOUPIMS program processes the data and creates a response message.
The TOUPIMS program inserts the response data to the IOPCB.
IMS returns the response data back to the requester. The data is returned from the EgenClient.callService method as the byte array rawResult.
The Java client class calls the commit method of the UserTransaction object to indicate the successful completion of the transaction. This causes the commit of the WebLogic managed resources, as well as the resources managed by IMS.

Common Programming Interface for Communications Programming Flows

The following examples of CPI-C programming flows are discussed:

Java Client Request/Response to Host CPI-C

Figure 5-9 illustrates a Java client request/response to a host CPI-C programming flow.

Figure 5-9 Java Client Request/Response to Host CPI-C

The following steps describe the Java client request/response to host CPI-C programming flow.

A Java client class (such as a stand-alone client, EJB, etc.) makes a call to the BaseClient.toupper method with a Chardata dataview as the parameter.
In the toupper method, a call is made to the EgenClient.callService method.

Note: The BaseClient extends EgenClient, so the BaseClient inherits the callService method from EgenClient.

The value of the first parameter is SIMPCPIC. SIMPCPIC is the name of the APPC Service that is mapped to the CPI-C Transaction Program ID TPNCPIC in the WebLogic Administration Console.
The transaction program TPNCPIC invokes the TOUPCPIC program.
TOUPCPIC accepts the conversation with the cmaccp call. The conversation ID returned in convid is used for all other requests on this conversation.
The cmrcv request receives the inputBuffer buffer contents for processing.
The TOUPCPIC program processes that data.
The cmsst request prepares for the send request by setting the send type to CM_SEND_AND_DEALLOCATE.
The cmsend request returns the obuffer contents. The data is returned from the EgenClient.callService method as the byte array rawResult.

Host CPI-C Request/Response to WebLogic Server EJB

Figure 5-10 illustrates a host CPI-C request/response to WebLogic Server EJB programming flow.

Figure 5-10 Host CPI-C Request/Response to WebLogic Server EJB

The following steps describe the host CPI-C request/response to WebLogic Server EJB programming flow.

The CPI-C application program TRADCPIC is invoked using the environment start-up specifications.
The TRADCPIC client requests cminit to establish conversation attributes and receive a conversation ID that will be used on all other requests on this conversation. The remote server and service are named in the CPI-C side information entry TRADSIDE.
The cmallc request initiates the advertised service TRADSERV. In the WebLogic Administration Console, the TRADSERV service is mapped to the JNDI name jam.TradeServer for the TradeServer EJB.
The cmsst request prepares the next send request by setting the send type to CM_SEND_AND_PREP_TO_RECEIVE.
The cmsend request immediately sends the contents of the obuffer to the dispatch method of TradeServerBean in the commarea byte array and relinquishes control.
The buy method is messaged from the dispatch method.
The business logic is performed, and the result is returned to the dispatch method.
The cmrcv request receives the contents of the byte array returned from the dispatch method in the ibuffer buffer, and notification that the conversation has ended with the return code value of CM_DEALLOCATED_NORMAL.

Host CPI-C Asynchronous No Reply to Java Server

Figure 5-11 illustrates a Host CPI-C asynchronous no reply to Java server programming flow.

Figure 5-11 Host CPI-C Asynchronous No Reply to Java Server

The following steps describe the Host CPI-C asynchronous no reply to Java server programming flow.

The CPI-C application program JMSCPIC is invoked using the environment start-up specifications.
The JMSCPIC client requests cminit to establish conversation attributes and receive a conversation ID that will be used on all other requests on this conversation. The remote server and service are named in the CPI-C side information entry JMSSIDE.
The cmallc request initiates the advertised service CTOJMSSV.
The cmsend request sends the contents of the obuffer to the CTOJMSSV service.
The cmdeal request flushes the data and indicates the conversation is finished. The request message is forwarded to the Gateway.
The Gateway sends the message to the JMS Event CTOJMSSV. In the WebLogic Administration Console, the CTOJMSSV service name is mapped to the JMS topic JAM.examples.CPIC.EventTopic.

Transactional Java Client Request/Response to Host CPI-C

Figure 5-12 illustrates a transactional Java client request/response to a Host CPI-C programming flow.

Figure 5-12 Transactional Java Client Request/Response to a Host CPI-C

The following steps describe the transactional Java client request/response to a host CPI-C programming flow.

A Java client class calls the begin method of a UserTransaction object to start a transaction.
Within the boundaries of that transaction, the Java client class (stand-alone client, EJB, etc.) makes a call to the BaseClient.toupper method with a Chardata DataView as the parameter.
In the toupper method, a call is made to the EgenClient.callService method.

Note: The BaseClient extends EgenClient, so the BaseClient inherits the callService method from EgenClient.

The value of the first parameter is SIMPCPIC. SIMPCPIC is the name of the APPC Service that is mapped to the CPI-C transaction program ID TPNCPIC in the WebLogic Administration Console.
The transaction program with the tpname TPNCPIC invokes the TOUPCPIC program.
TOUPCPIC accepts the conversation with the cmaccp call. The conversation ID returned in convid is used for all other requests on this conversation.
The cmrcv request receives the inputBuffer buffer contents for processing.
The TOUPCPIC program processes that data.
The cmsst and cmsptr prepare the next send request by setting the send type to CM_SEND_AND_PREP_TO_RECEIVE and by setting the prepare-to-receive type to CM_PREP_TO_RECEIVE_CONFIRM. The CONFIRM indicates that the service has completed successfully.
The cmsend request returns the obuffer contents. The data is returned from the EgenClient.callService method as the byte array rawResult.
The Java client class calls the commit method of the UserTransaction object to indicate the successful completion of the transaction and request the commit of all updated resources. The cmrcv request receives the commit request, and responds explicitly to the request with the SAA Resource/Recovery commit call srrcmit. The conversation is ended after the successful commit exchange.

Transactional Host CPI-C Request/Response to WebLogic Server EJB

Figure 5-13 illustrates a transactional host CPI-C request/response to WebLogic Server EJB programming flow.

Figure 5-13 Transactional Host CPI-C Request/Response to WebLogic Server EJB

The following steps describe the transactional host CPI-C request/response to WebLogic Server EJB programming flow.

The CPI-C application program TRADCPIC is invoked using the environment start-up specifications.
The TRADCPIC client requests cminit to establish conversation attributes and receive a conversation ID that will be used on all other requests on this conversation. The remote server and service are named in the CPI-C side information entry TRADSIDE.
The cmssl sets the conversation attribute to sync-level 2 with CM_SYNCPOINT. This allows the WebLogic EJB to participate in the transaction.
The cmallc request initiates the advertised service TRADSERV. In the WebLogic Administration Console the TRADSERV service is mapped to the JNDI name jam.TradeServer for the TradeServer EJB.
The cmsst request prepares the next send request by setting the send type to CM_SEND_AND_PREP_TO_RECEIVE.
The cmsend request immediately sends the contents of the obuffer to the dispatch method of TradeServerBean in the commarea byte array and relinquishes control.
The buy method is messaged from the dispatch method.
The business logic is performed, and the result is returned to the dispatch method.
The cmrcv request receives the contents of the byte array returned from the dispatch method in the ibuffer buffer. The cmrcv receives a confirm request indicating the conversation should terminate.
The client replies positively to the confirm request with cmcfmd.
The TRADCPIC client prepares to free the conversation with the cmdeal request. The conversation in CM_DEALLOCATE_SYNC_LEVEL commits all updated resources in the transaction and waits for the SAA resource recovery verb, srrcmit. After the commit sequence has completed, the conversation terminates.