Developing Applications Using BEA MessageQ LU6.2 Services

 

This chapter provides an overview of how to use BEA MessageQ LU6.2 Services for OpenVMS to develop programs that communicate between IBM mainframes and VAX or Alpha systems running OpenVMS.

This chapter describes:

• Applications Development Overview

• Structure of BEA MessageQ LU6.2 Services Applications

• Development Checklist

Applications Development Overview

BEA MessageQ LU6.2 Services can be used to develop a wide range of distributed applications that integrate BEA MessageQ applications and LU6.2 APPC clients.

BEA MessageQ LU6.2 Services support three types of applications:

• Inbound applications

• Outbound applications

• Hybrid applications

Inbound Applications

Inbound applications initiate APPC conversations with partner programs in the SNA network based on events that occur in the BEA MessageQ network (for example, user input at a terminal or workstation, receipt of a message from another BEA MessageQ client program, and so on). Inbound applications are typically used to trigger application actions in the SNA network based on events and data generated in the BEA MessageQ network.

Outbound Applications

Outbound applications accept APPC conversations initiated by partner programs in the SNA network based on events that occur in the SNA network (such as user input at a terminal or workstation, receipt of a message from other APPC client programs, and the like). Outbound applications are typically used to trigger application actions in the BEA MessageQ network based on events and data generated in the SNA network.

Hybrid Applications

Hybrid applications both initiate APPC conversations with partner programs in the SNA network and accept APPC conversations initiated by partner programs in the SNA network. Hybrid applications are typically used to route application traffic among BEA MessageQ and APPC clients based on application-specific criteria.

The LU6.2 Services port server is a very general form of a hybrid application: it both initiates inbound APPC conversations and accepts outbound conversations.

Target Registration

A BEA MessageQ client that is to receive messages on outbound sessions must be registered with the LU6.2 Port Server before a connection can be established. A BEA MessageQ client is registered by sending a message to the LU6.2 Port Server. This message contains the following information:

• The name of the target (as known to the LU6.2 Port Server) to be used by the IBM client to establish communication with the BEA MessageQ client

• The BEA MessageQ group ID and queue number of the BEA MessageQ client

After registering the target, the system returns the REGISTER_TARGET message to the BEA MessageQ client.

A BEA MessageQ client can register itself or it can be registered by another application. Each target may be registered by only one BEA MessageQ client application. Applications are automatically deregistered when they exit.

Note: A permanent outbound target is permanently registered with the BEA MessageQ group ID and queue number provided on the target definition. BEA MessageQ clients that receive output from permanent outbound targets do not need to register.

Structure of BEA MessageQ LU6.2 Services Applications

BEA MessageQ LU6.2 Services applications are BEA MessageQ applications that use the services of the BEA MessageQ LU6.2 Services Port Server to conduct APPC conversations with partner programs running in the SNA network.

In its simplest form, such an application will attach a queue, by calling pams_attach_q, and conduct a dialog with the port server, by calling pams_put_msg and pams_get_msg (or pams_get_msgw), to exchange the seven predefined port server message types with the port server.

Simple Linear Conversations

It is possible to write an application that performs this dialog in a linear manner. In its simplest form, an application may conduct an LU6.2 conversation as follows:

pams_attach_q 
pams_put_msg(connect_req) 
pams_get_msgw(connect_accept) 
pams_put_msg(data_message+change_direction) 
pams_get_msgw(data_message) 
pams_get_msgw(change_direction) 
pams_put_msg(connection_terminated  
pams_exit()

However, this approach assumes that the message to be received by a pams_get_msg is the message that the application expects. Because the BEA MessageQ system is a distributed queuing system, and because many things can happen in a distributed application, the message that arrives might not be the message expected by the application logic at that point in the conversation.

A better approach is to design the application as a simple state machine that performs initial application housekeeping and receives messages. Otherwise, extensive exception processing must be added to the logic to handle unexpected message types, which leads to more complex applications and a possible increase in logic errors.

State Machines

A simple state machine application performs initial application housekeeping, enters a loop in which a pams_get_msgw is issued to receive a message, and processes the message based on its type (see Figure 2-1 ).

In the routing that deals with the particular message type received, the application checks the current state to see if the message is a valid one, processes the message, sets a new state, and returns to the top of the loop.

For the application loop described in Figure 2-1, assume that the application must receive a Type 1 message before it can receive a Type 2 message, and that all types other than 1 and 2 are invalid. A simple state machine implements this scheme as follows:

The application begins at STATE=0.

If a Type 1 message arrives and STATE=0, the message is valid and the new STATE is 1.

If a Type 2 message arrives and STATE=1, the message is valid, the new STATE is 0, and the process starts over.

Figure 2-1 Application Loop

Overview of State/Event/Action Table

State machines can be simply documented using a state/event/action table. Table 2-1 describes the preceding application and shows each possible state in column 1, all events that can occur in that state in column 2, the action to be taken when that event occurs in column 3, and the new state in column 4.

Table 2-1 Sample State/Event/Action Table

State	Event	Action	New State
STATE=0	Type 1 msgs	process message	STATE=1
	Other msgs	report error	STATE=0
STATE=1	Type 2 msgs	process message	STATE=0
	Other msgs	report error	STATE=1

In some cases, the new state is the same as the original state; this allows the application to deal with unexpected events. In STATE 0, for example, receiving anything other than a Type 1 message leaves the application in STATE 0, so the next message received is subject to the same rules. This keeps the application from processing any mesages until a Type 1 message has been received.

The following sections provide basic State/Event/Action tables for inbound and outbound LU6.2 applications. The events listed in the Event column are the messages used to communicate with the port server (refer to Chapter 3). These tables were used to build the example programs listed in Appendix F.

Inbound State/Event/Action Listing

Table 2-2 describes an application that asks for a connection to an APPC partner program, sends it a message, waits for a response, and disconnects the conversation. This State/Event/Action table handles unexpected events and unexpected message types.

Table 2-2 Inbound State/Event/Action Table
State	Event	Action	New State
connecting	N/A	send connect	wait_connect
wait_connect	connect_accept	send data message and change direction	wait_response
	connect_reject	log error	exiting
	other	log error	wait_connect
wait_response	data_message	process response	wait_complete
	change_direction	log error and send abort message	exiting
	other	log error	wait_response
wait_complete	change_direction	send connection terminated (normal)	exiting
	data_message	log error and send abort message	exiting
	other	log error	wait_complete
exiting	N/A	call pams_exit()	application done

Outbound State/Event/Action Listing

Table 2-3 describes an application that registers to accept connections from a remote APPC partner program and then waits for data. After receiving a data message, it waits to become the sender, sends a response, and waits for a disconnect from the remote partner program.

Table 2-3 Outbound State/Event/Action Table
State	Event	Action	New State
registering	N/A	send register target message	wait_register
wait_register	register_target	N/A	wait_data
	connection_terminated	log error	exiting
	other	log error	wait_register
wait_data	data_message	process message	wait_to_send
	change_direction	log error and send abort message	exiting
	other	log error	wait_data
wait_to_send	change_direction	send data message plus change_direction	wait_disconnect
	data_message	log error and send abort message	exiting
	other	log error	wait_to_send
wait_disconnect	connection_terminated	N/A	exiting
	other	log error	wait_disconnect
exiting	N/A	call pams_exit()	application done

Development Checklist

When developing a distributed application, make sure that your process includes the following development steps:

1. Define the application boundaries.

2. Identify the communicating partners.

3. Design the application conversations.

4. Develop the application.

5. Define the communications environment.

6. Test the application.

Step 1: Define the Application Boundaries

The first step in developing a distributed application, especially one that will run in a heterogeneous network, is to determine the application boundaries. This process consists of analyzing the functions that must be performed and the data that those functions will act upon, and then identifying the location (domain) in the network where those data and functions "naturally" reside.

For example, if the application is intended to integrate customer order entry with manufacturing control, you might determine that the customer order database is stored in DB2 under CICS on an MVS system, and the shop floor control database is stored in Rdb on an OpenVMS system. Functions that manipulate the customer order data will "naturally" reside on the MVS system and functions that manipulate the shop floor control data will "naturally" reside on the OpenVMS system. Figure 2-2 describes application domains.

Figure 2-2 Integrated Application Domains

Step 2: Identify the Communicating Partners

After the functions and data have been associated with network locations (the BEA MessageQ part of the network and the SNA part of the network, respectively), the functions must be mapped onto the processes that will implement them. As shown in Figure 2-2, you can assume that the customer order functions and manufacturing control functions have already been implemented in the existing application systems. In this case, you are concerned with identifying the new processes that will implement the new communications functions. Assume you must add the following functions:

• New Order Transfer: When the Customer Order system accepts a new order, the order is to be transferred immediately to the manufacturing control system for execution.

• Order Status Update: As the order is moved through the manufacturing process, a status update is to be delivered to the Customer Order system indicating:

  • Last manufacturing step completed

  • Scheduled start and end time of the next operation

  • Updated estimated time of delivery of the finished order

• Order Completion: When the order is completed and ready for shipment, an order complete status must be delivered to the Customer Order system.

Each of these three functions requires two communicating partners---one in the BEA MessageQ domain and one in the SNA domain (see Figure 2-3).

Figure 2-3 Communication Partners in Application

Now you can see what new processes must be added to the applications running in each domain, who the communicating partners will be, and how the communications flow will be initiated.

In this example, there is one outbound conversation, initiated by the New Order Send function, and two inbound conversations, initiated by the Status Update Send and Order Completion Send functions, respectively.

Step 3: Design the Application Conversations

For each pair of communicating partners, you must design the application conversation. This is the actual exchange of messages between communicating partners.

To design the application dialog, you must know:

• Who will initiate the conversation

• The format of each message

• How and when the roles of sender and receiver will be exchanged

• Who will terminate the conversation

• How errors will be handled

  For this example, assume that the rules are very simple (which is usually true):

• The party initiating the conversation is responsible for terminating it.

• All errors are fatal; the conversation is terminated immediately when an error occurs.

• All conversations consist of one or more messages sent by the initiating party.

• When the initiating party is finished sending, it becomes the receiver.

• When the accepting party sees the initiating party become a receiver, it sends an acknowledgment, and switches itself back to a receiver.

• When the initiating party receives acknowledgment and regains control of the conversation (in other words, becomes the sender), it terminates the conversation.

The application conversation between New Order Send and New Order Receive looks like this:

New Order Send	New Order Receive
Initiate conversation	Accept new conversation
Send New Order message	Receive New Order message
Become receiver	Receive OK_TO_SEND
Receive acknowledgment	Send acknowledgment
Receive OK_TO_SEND	Become receiver
Terminate conversation	Accept termination

Step 4: Develop the Application

After the application conversations and message formats have been defined, the normal processes of application development (detail design, coding, and unit testing) can take place.

Note: Refer to Configuring the LU6.2 Port Server, Port Server Messages, and LU6.2 User Callback Services, for information on Port Server and User Callback messages.

Note: Refer to the BEA MessageQ Programmer's Guide for BEA MessageQ programming information.

Step 5: Define the Communications Environment

Before integration testing can occur, the communications environment must be defined. The full set of definitions that must be in place varies, based on the specific hardware, operating systems, and application subsystems involved.

Assuming a typical configuration consisting of a channel-attached SNA Gateway and MVS with VTAM and CICS, the following definitions must be available:

• Physical devices (the gateway) must be defined to VTAM.

• LU6.2 logical units that the gateway will provide must be defined to VTAM.

• LU6.2 "terminals" must be defined to CICS and mapped onto the LUs defined to VTAM.

  Note: Most sites use the CICS Resource Definition Online task to manage this function.

• CICS programs must be assigned Transaction Program Names (TPNs).

• Access names must be defined to identify the specific groups of gateway LUs that BEA MessageQ LU6.2 Services will use.

• BEA MessageQ programs that will accept outbound conversations must be assigned TPNs.

• An LU configuration file must be created that defines the gateway node names, access names, and specific LUs that LU6.2 Services will use (defined earlier in this step).

• A target configuration file must be created that defines the "target" names used by BEA MessageQ applications in connecting the LU6.2 Port Server and maps them onto TPNs defined in steps 4 and 6.

  Note: Refer to Configuring the LU6.2 Port Server, for more information on LU and target configuration files and the use of the LU6.2 Port Server.

Step 6: Test the Application

With the communications environment defined, you can now begin testing your application. If your application implements a state machine that is documented with a state/event/action table, developing a test plan that will validate correct behavior in each state is relatively straightforward.

Refer to Examples of BEA MessageQ LU6.2 Inbound and Outbound Applications, for samples of inbound and outbound applications.

Developing a Sample Application

The following are the specifications of a sample application. For the purposes of the example, assume that:

• The gateway node name is SNAGWY.

• The access name is ORDERS.

• This application is assigned LU numbers 1, 2, and 3.

• The two inbound CICS programs are given the following TPNs:

  • ORDU-Order Update Receive

  • ORDC-Order Completion Receive

• One outbound BEA MessageQ program is given the following TPN: NEWORDER -New Order Receive

Using the development process described in this section, this example produces the two BEA MessageQ LU6.2 Port Server initialization files: ORDERS.LU (inbound or resources file) and ORDERS.TGT (outbound or target file). Refer to Configuring the LU6.2 Port Server, for information about recalling and editing these initialization files.

Listing 2-1 shows these two initialization files.

Listing 2-1 Sample Resources and Target Initialization Files

---

ORDERS.LU 

! 

!  One LU for use by OUTBOUND Conversations 
    ! 
    !Resource   Gateway   Access   LU  Type 
    CICSOUT     SNAGWY    ORDERS   1   2 
    ! 
    ! Two LUs for use by INBOUND Conversations 
    ! 
    !Resource   Gateway   Access   LU   Type 
    CICSIN      SNAGWY    ORDERS   2    1 
    CICSIN      SNAGWY    ORDERS   3    1 
 
ORDERS.TGT 
! 
    ! One Target definition for OUTBOUND Conversations 
    ! 
    !Target TPN     Resource     Type      Comm    Deallocate 
    !                                      Type    Type 
    NEWORDER        NEWORDER     CICSOUT   2       2        1 
    ! 
    ! Two Target Definitions for INBOUND Coinversations 
    ! 
    !Target TPN     Resource     Type      Comm    Deallocate 
    !                                      Type    Type 
    UPDATE          ORDU         CICSIN    1       2        1 
    COMPLETE        ORDC         CICSIN    1       2        1 
 

---