| Sun Mainframe Transaction Processing Software Developer's Guide
|
   
|
This chapter describes how to use IBM MQSeries, Version 5 with the Sun MTP software. It contains the following topics:
The following figure shows the interaction between a Sun MTP region and MQSeries.
FIGURE 12-1 MQSeries Process Flow
[ D ]
The elements shown in FIGURE 12-1 are:
Client Application: Creates messages on the input data queue. The client application is independent of Sun MTP.
Data Queue: If configured, it places trigger messages on the trigger queue that define Sun MTP transactions.
Trigger Queue: Receives automated messages through procedures configured in the queue manager. Trigger messages contain information used by the region to start transactions, and used by the transaction processors to find the original data messages that spawned the trigger event.
unikixqm: Monitors the trigger queue and starts the transaction based on the application ID in the trigger message. The application ID must be equal to the value of a transaction ID configured in the Program Control Table (PCT).
Transaction: Can put or receive messages to the data queue.
Types of Applications Supported by MQSeries
MQSeries is messaging software that enables applications to put and get messages. The message transmission is asynchronous between the sender and the receiving applications. Sun MTP/MQSeries applications can be initiated in two ways:
- Using the MQSeries triggering mechanism
MQSeries has a mechanism that can trigger an application for MQSeries events. Sun MTP uses this mechanism to initiate a transaction and provide the queue manager name and queue name to the application for processing. The transactional aspect of the updates to the queues are controlled by the application.
- Using user-initiated transactions
The applications know the queue manager and queue names. Transactions initiated by any Sun MTP-supported mechanism can issue MQSeries API calls. The transactional aspects of the updates to the queues can be synchronized with Sun MTP.
Application Design Guidelines for MQSeries
When designing an application in the Sun MTP/MQSeries environment, follow these guidelines:
- The program must interact with Sun MTP through the CICS API.
- The program must interact with MQSeries to obtain asynchronous message services.
- Because Sun MTP does not interact directly with MQSeries, the developer must determine how to process errors in a transaction program. If Sun MTP transactional support is not selected when building the system with kixinstall, it is the application's responsibility to ensure transactional integrity with MQSeries and between MQSeries, VSAM, and databases.
Using the MQSeries Triggering Mechanism describes the use of MQSeries triggering. The transaction executed as part of triggering is only one of the possible MQSeries applications that can be written for the Sun MTP environment. Triggered Transaction Example describes the application design for such a triggered transaction.
Using the MQSeries Triggering Mechanism
MQSeries implements a triggering mechanism that enables you to configure an MQSeries queue manager to automatically place a message on a separate trigger queue when the number of messages on a particular data queue meets a predefined criterion. Multiple queues can generate trigger messages that are placed automatically on the single trigger queue. Refer to the MQSeries documentation for a full description of the triggering mechanism.
Defining a Trigger Queue
For Sun MTP to connect to MQSeries, you must define the trigger capability in the MQSeries configuration. The following example defines a data queue that has the trigger capability enabled.
CODE EXAMPLE 12-1 Configuring MQSeries Triggers
DEF QL (UNIKIXMQ1) REPLACE +
DESCR ('Sun MTP MQSeries Sample Queue 1') +
TRIGGER +
TRIGTYPE (FIRST) +
INITQ (UNIKIX.TRIGGER.QUEUE) +
PROCESS (MQTX.TRIGGER.PROC)
DEF QL (TRANS.TRIGGER.QUEUE) REPLACE +
DESCR ('Sun MTP trigger queue')
DEF PROCESS (MQTX.TRIGGER.PROC) REPLACE +
DESCR ('Invoke transaction') +
APPLICID (MQTX) +
APPLTYPE (CICS)
|
In this example, the data queue is named UNIKIXMQ1. Associated with this queue is a trigger queue named UNIKIX.TRIGGER.QUEUE. MQSeries will manage these two queues and place a message on the trigger queue whenever the data queue requires that a new trigger be generated. The purpose of the trigger message is to start the Sun MTP transaction named MQTX (as defined by the attribute APPLICID).
Support for MQSeries triggering means that Sun MTP transactions are invoked when trigger messages are created by the system. A Sun MTP transaction can be written to read messages from the data queue and then process them. When this transaction is started automatically by the region, it is passed sufficient information to read and process the data message(s).
When a transaction is started as a result of a trigger message, details of the trigger message are passed into the transaction. The transaction obtains the data using the EXEC CICS RETRIEVE command. The format of this data is defined in the MQSeries copybook CMQTML. The fields in this structure are:
10 MQTM.
15 MQTM-STRUCID PIC X(4).
15 MQTM-VERSION PIC S9(9) BINARY.
15 MQTM-QNAME PIC X(48).
15 MQTM-PROCESSNAME PIC X(48).
15 MQTM-TRIGGERDATA PIC X(64).
15 MQTM-APPLTYPE PIC S9(9) BINARY.
15 MQTM-APPLID PIC X(256).
15 MQTM-ENVDATA PIC X(128).
15 MQTM-USERDATA PIC X(128).
|
The structure does not define the queue manager name. Therefore, Sun MTP trigger support provides an extra field at the end of the structure containing the information. Your application program must provide the following data definition for this field:
01 PARAMS.
COPY CMQTML.
10 MQTM-QMGR-NAME PIC X(48).
|
Triggered Transaction Example
To process the MQSeries message, a triggered transaction must connect to the Queue Manager and read the messages. The recommended method is for the transaction to empty the queue, and then terminate. With this method, many messages are being put onto queues, there are few trigger messages, and the triggered transaction works continually processing the input.
The pseudo-code for such an application is provided in CODE EXAMPLE 12-2. Note the following about this application design:
- Messages continue to be processed until the queue is empty. Most applications should adhere to this design.
- The MQGET() calls to get the messages should be non-blocking. This means that the transaction terminates once the queue is drained. It also means that the region's resources are not tied up waiting for an MQSeries message to arrive.
CODE EXAMPLE 12-2 Pseudo-Code for MQSeries Triggered Transaction
Retrieve the start data (Using EXEC CICS RETRIEVE)
Connect to Queue Manager
(Using MQCONN() with the QueueManagerName as MQTM-QMGR-NAME)
Open the Queue
(Using MQOPEN() with the queue name as MQTM-QNAME)
Read a message from Queue (Using MQGET())
while (Message was read)
do
Process the message
Read a message from the queue (Using MQGET())
end
Close the Queue (Using MQCLOSE())
Disconnect from the Queue Manager (Using MQDISC())
|
Securing Resources and Transactions
MQSeries controls access to MQSeries resources. Use the MQSeries security functionality to guard MQSeries resources.
Use Sun MTP transaction security to guard the Sun MTP MQSeries transactions. Because transaction level security does not control triggered transactions, your program should rely on MQSeries security features to prevent the transactions from doing unauthorized work.
Configuring Sun MTP to Run MQSeries Applications
This section describes the tasks to perform to enable Sun MTP to run MQSeries applications:
|
Note - If the MQSeries trigger mechanism is required, transactional support is not provided by Sun MTP.
|
 To Configure MQSeries
|
Configure MQSeries server appropriately for your MQSeries transactions.
Define all queues, procedures, channels, and so on. If transactional support is required, you must install the MQSeries server libraries. Otherwise, install the MQSeries client libraries on the host running Sun MTP.
To Build Sun MTP to Use MQSeries
|
1. Verify that the following environment variables are set:
a. Set $MQSERIES to the installation path of the MQSeries product.
b. Set $PATH to include $MQSERIES/bin.
c. Set $LD_LIBRARY_PATH to include $MQSERIES/lib.
2. Rebuild the unikixtran transaction server:
a. Execute the kixinstall utility.
b. Select the MQSeries option you want on the Third Party Packages screen.
- Select the MQSeries option if:
Transactional support is not required.
Transactional support is not required and if the MQ triggering mechanism is required.
- Select the MQSeries with transactional support option if transactional support is required.
c. Build the executables as described in the Sun Mainframe Transaction Processing Software Administrator's Guide.
To Configure the Region to Use MQSeries
|
1. Identify the region or regions that are to use MQSeries.
2. In the region setup file, add the following:
a. Add the MQSERIES environment variable, which points to the installation path of the MQSeries product.
b. Add $MQSERIES/bin to the PATH environment variable.
c. Add $MQSERIES/lib to the LD_LIBRARY_PATH environment variable
d. If client libraries are used, add the MQSERVER environment variable with the appropriate values.
Refer to MQSeries Clients Guide for more information.
To Configure the Region to Use the MQSeries Triggering Mechanism
|
1. Identify the region that will use the MQSeries triggering mechanism.
2. Edit the $KIXSYS/unikixrc.cfg file to add the MQServer* entries.
If your region does not have a unikixrc.cfg file, copy the unikixrc file from $UNIKIX/lib to $KIXSYS and rename it unikixrc.cfg. Add the MQServer* entries:
MQServer*Active: True
MQServer*QueueManagerName: "QueueManagerName"
MQServer*QueueName: "TriggerQueueName"
|
where QueueManagerName is the name of the queue manager running on the host specified in the MQSERVER environment variable (or left blank ("") to use the default queue manager), and TriggerQueueName is the name of the queue that the unikixqm process monitors for trigger messages.
Preparing Your Applications
Compile the application programs written to the MQSeries API in the same way that you compile any other Sun MTP application programs. Refer to the MQSeries documentation for any setup information required to compile the programs, such as where to find C language include files, COBOL copybooks, and so on.
Running the MQSeries Sample Application
A sample triggered transaction named KIXMQ01.clt is available in source and object form in the $UNIKIX/test/mq/cobol directory. The sample, which acts like a file transfer program, includes MQSeries definitions and Sun MTP definitions for the resources used in the process. You can use the sample transaction as the model for any triggered application.
The sample contains:
- A README.doc file that contains instructions for running the application
- A C language program that copies lines from a file into an MQSeries queue
- A COBOL program that reads the messages from the MQSeries queue and places the data in a Sun MTP temporary storage queue
- An MQSeries configuration file
The sample application's README.doc file shown in the following example contains the steps to run the sample application.
CODE EXAMPLE 12-3 MQSeries README.doc File
#**********************************************************************#
#* *#
#* Copyright (c) 2001 by Sun Microsystems, Inc. *#
#* All rights reserved. *#
#* *#
#**********************************************************************#
Files in $UNIKIX/test/mq/cobol
-------------------------------
### Sun MTP Sources ###
-----------------------
KIXMQ01.cl2
### 'C' program (kixmqtst) for loading the MQSeries queue data ###
------------------------------------------------------------------
kixmqtst.c
kixmqerr.c
kixmqerr.h
### MQSeries configuration command file ###
-------------------------------------------
kixmqtst.mqconfig
### Resource control tables for the Sun MTP region ###
------------------------------------------------------
pct.tbl
ppt.tbl
### Comm Mgr resource to define and enable trigger queue ###
------------------------------------------------------------
unikixrc.cfg
### Other ###
-------------
makefile : for building the sample application and data loading program
kx_cobopt: COBOL compilation options used by the makefile
Requirements
------------
MQSeries Client must be available on the same machine running MTP.
MQSeries Server must be available on a host that is accessible to the MTP
host via TCP communication. This example assumes that MTP and MQSeries
Server are running on the same host. If this is not the case, then the
kixmqtst program must be compiled on the host that is running MQSeries Server.
Copy the C source files and the data file MQJMSAppl_GetAlias.data to the
host running MQSeries server and build according to compiler and MQSeries
specifications for that host.
Procedure
----------
MQSeries Setup
---------------
Perform these commands on the MQSeries Server host machine.
1. Run the crtmqm command to create an MQSeries queue manager named TESTQM.
crtmqm -lf64 -q TESTQM
2. Start the TESTQM queue manager using the 'strmqm' command.
strmqm TESTQM
3. Put the sample configuration into the queue manager using the runmqsc
command.
runmqsc TESTQM < kixmqtst.mqconfig
The kixmqtst.mqconfig file is in the $UNIKIX/test/mq/cobol directory. It
contains definitions of the Queues, Procedures and Channel used by the
test application. If you are running MQSeries Server on a different host
than your MTP region, you will need to copy this file to that host.
4. Put data into the queue.
kixmqtst -m TESTQM -q UNIKIXMQ1 -i <text file>
where <text file> is any ascii data file. This file (README.doc) can be
used for testing purposes. This will cause both the data to be loaded on
the input queue and a trigger message to be placed on the trigger queue.
MTP Setup
----------
1. In addition to the required environment setup for running an MTP region,
add (or verify the existence of) the following environment variables
UNIKIX Sun MTP's home directory
KIXSYS $UNIKIX/test/mq/cobol
KIXPROGS $KIXSYS
KIXMAPS $KIXSYS
KIXDATA $KIXSYS
KIXLIB $KIXSYS
KIXLICDIR Sun MTP license file directory
MQSERIES Install path for MQSeries (i.e., /opt/mqm)
MQSERVER CHANNEL1/TCP/hostname
where hostname is the name or IP address of the
host running MQSeries Server. If the host is the
same as the host running MTP, the value is
localhost, otherwise specify the appropriate name
or IP address.
COBDIR The install path of cobol (e.g., /opt/cobol/1.1)
COBCPY Include $UNIKIX/copy and MQ copy books
(e.g. /opt/mqm/inc)
PATH Include $UNIKIX/bin and $MQSERIES/bin
LD_LIBRARY_PATH Include $COBDIR/lib, $UNIKIX/bin and $MQSERIES/lib
2. If not already done, build the Transaction Processor so that it can
call MQSeries functions. This is done using the 'kixinstall' program.
3. Run make in the $UNIKIX/test/mq/cobol directory to build the example.
Note: on UNIX platforms you will have to uncomment the platform
specific lines in the makefile.
4. Ensure the following lines are in your $KIXSYS/unikixrc.cfg file:
(If you don't have a unikixrc.cfg file copy the unikixrc file from
$UNIKIX/lib and rename it unikixrc.cfg)
MQServer*Active: True
MQServer*QueueManagerName: "TESTQM"
MQServer*QueueName: "UNIKIX.TRIGGER.QUEUE"
5. Start Sun MTP using kixstart. The 'unikixqm' daemon process will monitor
the queue UNIKIX.TRIGGER.QUEUE. The trigger monitor will start the KMQ1
transaction as a result of the trigger message waiting from the MQSeries
Setup step 4 (above).
6. The transaction KMQ1 will put the data read from the queue into the TS queue
MQTEST01. You can now use the CEBR transaction to look at the file that
was placed upon the MQSeries queue. On the MQSeries Server host, repeat
the MQSeries Setup step 4 with other files to verify that the trigger queue
is continually being monitored.
|
This sample application reads in a configuration file, $UNIKIX/test/mq/cobol/kixmqtst.mqconfig, that defines the MQSeries queues, a Sun MTP trigger queue, and two trigger processes. The following example shows the contents of the configuration file.
CODE EXAMPLE 12-4 MQSeries Sample Application Configuration File
DEFINE QLOCAL('UNIKIXMQ1') REPLACE +
DESCR('Sun MTP MQSeries Sample Queue 1') +
PUT(ENABLED) +
GET(ENABLED) +
DEFPSIST(NO) +
MAXDEPTH(1000) +
MAXMSGL(2000) +
SHARE +
DEFSOPT(EXCL) +
USAGE(NORMAL) +
INITQ(UNIKIX.TRIGGER.QUEUE) +
TRIGGER +
TRIGDATA('Trigdata from UNIKIXMQ1') +
TRIGTYPE(FIRST) +
PROCESS(KMQ1.TRIGGER.PROC)
DEFINE QLOCAL('UNIKIXMQ2') REPLACE +
DESCR('Sun MTP MQSeries Sample Queue 2') +
PUT(ENABLED) +
GET(ENABLED) +
DEFPSIST(NO) +
MAXDEPTH(1000) +
MAXMSGL(2000) +
SHARE +
DEFSOPT(EXCL) +
USAGE(NORMAL) +
INITQ(UNIKIX.TRIGGER.QUEUE) +
TRIGGER +
TRIGDATA('Trigdata from UNIKIXMQ2') +
TRIGTYPE(FIRST) +
PROCESS(KMQ2.TRIGGER.PROC)
DEFINE QLOCAL('UNIKIX.TRIGGER.QUEUE') REPLACE +
DESCR('Sun MTP trigger queue') +
PUT(ENABLED) +
GET(ENABLED) +
DEFPSIST(NO) +
MAXDEPTH(1000) +
MAXMSGL(2000) +
SHARE +
DEFSOPT(EXCL) +
USAGE(NORMAL) +
TRIGTYPE(NONE)
DEFINE PROCESS('KMQ1.TRIGGER.PROC') REPLACE +
DESCR('Invoke an instance of the KMQ1 tran') +
ENVRDATA('Environ for KMQ1') +
USERDATA('Some Userdata for KMQ1') +
APPLTYPE(CICS) +
APPLICID('KMQ1')
DEFINE PROCESS('KMQ2.TRIGGER.PROC') REPLACE +
DESCR('Invoke an instance of the KMQ2 tran') +
ENVRDATA('Environ for KMQ2') +
USERDATA('Some Userdata for KMQ2') +
APPLTYPE(CICS) +
APPLICID('KMQ2')
|
| Sun Mainframe Transaction Processing Software Developer's Guide
|
816-5329-11
|
|
Copyright © 2004, Sun Microsystems, Inc. All rights reserved.