About the IMS Synchronous Request sample
The IMS Synchronous Request sample uses the IMSRequest node. For an
overview of how this node works and is configured, see
IBM Information Management System (IMS)
in the WebSphere Message Broker documentation.
The sample uses the Display All Invoices (DSPALLI) transaction, which is an IMS sample
transaction that is typically installed on an IMS system. Check with
your system administrator that it is installed before you try to use
this sample. The DSPALLI transaction can be set up to run a REXX program
(DFSSAM07) or a COBOL program (DFSSAM7) to retrieve details about
invoices. Although these programs perform the same function and produce the
same logical data, they have different physical
formats on the wire (for example, different size fields and extra segments). By
default, DSPALLI is set up to use REXX. You can change DSPALLI to use
COBOL, but you must also compile and link the COBOL
program because it is not shipped ready-built. This sample
works with both programs. Use the REXX version to get started and to
understand how to design message flows that use the request node. However, the COBOL
version runs faster than the REXX version.
The sample flow shows how a WebSphere Message Broker message flow can be designed to
interact with an IMS system.
The following two elements are important to consider when interacting with IMS:
- The connection and interaction with IMS Connect
- The construction of the IMS message that is used to drive an IMS
transaction (or command)
It is important to understand the distinction between these two elements
because the IMS message itself does not contain just data to be
processed, but also structural information about the size of
the data (LLZZ data at the beginning of each segment in the message),
and metadata about how the data is to be processed (the transaction
or command name is the first part of the data).
For an explanation of the structure of these messages,
see IBM Information Management System (IMS).
The IMSRequest node provides connectivity to IMS Connect and
allows the choice of commit mode and sync level under which the transaction
is run. In the sample, these properties are set to the default values: the commit mode is
send_then_commit and the sync level is
confirm. These values are
typically used when performing a synchronous request. The node
expects to receive a message tree that it can serialize into an IMS message
with the LLZZ already set, and it routes the response bit stream from IMS to
the parser that is configured on the
Response Message Parsing tab of the Request node.
Message structures used by DSPALLI
The DSPALLI transaction that is used in this sample requires a single-segment
input message and creates a multiple-segment output message. The number
of segments that are produced on output can vary depending on the processing in
the program. When using the REXX version of the
program, a success message has five segments at the beginning of the
message that form a header, and one segment per invoice being
displayed. The COBOL version has three segments followed by the invoices.
You can differentiate between the two formats because the third
segment of the REXX format has no data and the COBOL format contains data.
Information in this topic refers only to the COBOL version unless the REXX version is specified,
because most applications are written in COBOL rather than
REXX, and because WebSphere Message Broker supports the importing of COBOL copybooks,
which facilitates development of the required message set.
When a failure occurs, only one segment exists in the response from
DSPALLI, which contains the cause of the failure.
The COBOL structures for the COBOL version are contained in the program SRC
DFSSAM7.
The structures are defined here for each segment that the program uses.
The three main segments that this sample uses are:
- TERM-IN-AREA. The input segment that contains the transaction
name and data to be processed
- DETAIL-OUT. The segment that is repeated for each invoice and
contains the details for each invoice
- REJECT-MESSAGE. The segment that is used to return an error
message when the transaction fails to run correctly
Data structures for other segments also exist in this program but
they are header structures that are not relevant to this sample and therefore do not need to
be imported. Those segments can remain unparsed as just LL plus the
rest of the data.
The TERM-IN-AREA segment is like many other transactions' input segments that
are prefixed by the transaction:
006010 01 TERM-IN-AREA. 00350000
006020 02 CHAR-COUNT PICTURE S99 COMPUTATIONAL. 00360000
006030 02 FILLER PICTURE S99 COMPUTATIONAL. 00370000
006040 02 TRANS-CODE PICTURE X(7). 00380000
006050 02 MESSAGE-TEXT-START PICTURE X(125). 00380000
The key structures are:
- CHAR-COUNT: The LL field. The program can give any name to this field
(in this case, CHAR-COUNT) and is always the data type S99.
- FILLER: The ZZ field. The program never uses this field
but must allow for the space that the field uses in the bit stream.
In this instance, the program has
identified it as a filler field.
- TRANS-CODE: The transaction that was run to call
this program. The standard rules state that this field is the size of the transaction code
plus one character for a space unless the transaction contains eight
characters. In the case of DISAPPI, the field is the size of the
transaction without a space. The MESSAGE-TEXT-START must therefore
start with a space.
- MESSAGE-TEXT-START: The input data, which is 125 bytes
long. Different programs can have a different size for this field. The
maximum size is 32 KB. When constructing a message definition in
the MRM, you can set the Length Units property to End of Bitstream,
rather than setting a specific value for the length of this field.
The success output message is made up of three header sections and
a repeating detail section:
- HEADER-1-AREA
- HEADER-2-AREA
- HEADER-3-AREA
- DETAIL-OUT
The sample parses only the detail section
and leaves the header sections unparsed. The following section,
Constructing an MRM message set for DSPALLI,
shows how this parsing can be achieved in the MRM.
The following sample shows the first few lines of the DETAIL-OUT segment; for the full structure, see
DFSSAM7.
010010 01 DETAIL-OUT. 00900000
010020 02 DO-CHAR-CNT PICTURE S99 VALUE +84 COMP. 00910000
010030 02 FILLER PICTURE S99 VALUE +0 COMP. 00920000
010050 02 DO-LINE-CNT PICTURE Z9. 00930000
010055 02 FILLER PICTURE X VALUE '.'. 00940000
010060 02 FILLER PICTURE XX VALUE SPACES. 00950000
The key structures are:
- DO-CHAR-CNT: The LL field. No naming convention exists for this field.
This is a field
size segment and therefore always has a size of 84, which simplifies the construction of
a message type that models this format.
- FILLER: The first filler is used for
the ZZ data. The other fillers exist for formatting. Many transactions
do not have the formatting fillers because they rely
on MFS for formatting to an end terminal. The IMSRequest node always
deals with transaction data that has not been converted by MFS.
- DO-LINE-CNT: The first application
data in the DETAIL-OUT structure. This field provides the line number of the detail
segment (multiple instances of this segment can exist).
- ...: and so on for all the other
application data fields.
The final segment that the sample uses is
REJECT-MESSAGE, which occurs when
the transaction has a problem getting the invoice details (typically due to
an invalid part number):
015010 01 REJECT-MESSAGE. 01450000
015020 02 REJ-CHAR-CNT PICTURE S99 COMPUTATIONAL. 01460000
015030 02 FILLER PICTURE S99 COMPUTATIONAL VALUE +0. 01470000
015050 02 FILLER PICTURE X(8) VALUE '.PART = '. 01480000
015060 02 REJ-PN PICTURE X(16) VALUE SPACES. 01490000
015070 02 REJECT-REASON PICTURE X(110). 01500000
The key structures are:
- REJ-CHAR-CNT: The LL field.
- FILLER: The first filler is used for the ZZ data. The
other fillers exist for formatting. Many transactions
do not have the formatting fillers because they rely on MFS for
formatting to an end terminal. The IMSRequest node always deals with
transaction data that has not been converted by MFS.
- REJ-PN: The reason code for
the failure. This field is not used by the sample.
- REJECT-REASON: The reason
text for the rejection.
Constructing an MRM message set for DSPALLI
All the data
structures that are required for DSPALLI are contained in the program
DFSSAM7. The first step in constructing an MRM
message set is to import the required structures into a message set by
using the COBOL importer. The steps are:
- Create a new message set that has a binary physical format
called COBOL.
- Expand the new message set, right-click the Message definition
folder, and click New > Message definition file
from > COBOL file.
- Browse to find the file DFSSAM7.cbl (either obtained from your
own system or extracted from DFSSAM7).
- Click Next to display the
Message and Structure Selection screen. Add the three structures TERM-IN-AREA,
DETAIL-OUT, and REJECT-MESSAGE to the Import
Structure section.
- Select the check boxes next to TERM-IN-AREA and REJECT-MESSAGE so
that message types are created for these elements. DETAIL-OUT is not a
message type itself because it is only one part of the response message.
Do not change any other options.
- Click Next, then click Finish .
A new message definition called DSPALLI is created
that contains two message types: msg_TERMINAREA
and msg_TERMINAREA.
The transaction DSPALLI can return different structures based on what
happens in the program (for example, if an error occurs). To handle this
situation, the sample first parses the response with a general structure,
which breaks it into segments, then re-parses it with the correct
structure when it has identified which structure to use. To construct the
general purpose structure (which can be used for any response from an
IMS transaction), perform the following steps:
- Open the Message definition DSPALLI in the editor, right-click
Messages, click Add message.
- Name the new message msg_IMSMessage.
- Right-click Types,
click Add Complex Type.
- Name the type segmentType.
- Add a new element called IMSSegment to
msg_IMSMessage of type segment.
Ensure that it has a max occur value of -1 (unbounded).
- Add two local elements to the type: one called LL and the other
called ZZdata. The LL field must have a data type of
int and
the ZZdata field must have a data type of string.

- Select the ZZdata field and switch from
Overview to Properties.
- Change the COBOL physical representation from Length to
Length Reference.
- Set the Length Reference field to LL.
- Select Inclusive Length Reference because
the LL field is the length of the whole segment including LL and ZZ.
You can now use the message type
msg_IMSMessage
to parse any IMS response message into individual segments (but
not to parse the segments themselves). The sample uses this message type to parse the
response back from the IMS system and then, based on the number and
size of segments, re-parse it with another message type.
The error message type msg_REJECTMESSAGE
has already been defined for dealing with rejected messages.
The last message type that is required is the
success message type, which contains all the DETAIL-OUT segments:
- Open the Message definition DSPALLI in the editor, right-click
Messages, and click Add message.
- Name the new message type
msg_COBOLRESPONSE.
- Add two elements to the new type: one called
IMSSegment of type
segmentType and another called msg_DETAILOUT of type
DETAILOUT.
- The IMSSegment must
have a min occurs and a
max occurs of 3 (for the three header
segments that are not parsed).
- The msg_DETAILOUT segment
must have min occurs 0 and
max occurs unbounded (-1).
All the required data structures have been
created. The sample message flow shows how these structures can be used to map XML
documents to IMS requests and then to parse IMS responses, which can be
mapped back to XML documents.
How the message flow works
The basic function of the sample is to take an XML message from an
WebSphere MQ queue, transform it to an IMS request, run the transaction on
IMS, and format the response back to an XML message on an
WebSphere MQ queue. The following diagram shows what the message flow looks like:

The node-by-node processing is described in the following list:
- The MQInput node takes the message from the queue
IMS_SYNC_REQUEST_IN1 and parses it with the XML parser.
- The InputMapping node maps the XML structure to the
msg_TERMINAREA.
The node also calculates the LL value, which cannot be generated automatically
by the message type.
- The SaveMQMD Compute node saves the MQMD so that message identifiers and
correlation identifiers are saved. (This node can be omitted if you are using other transports or
if the message identifiers and correlation identifiers are not required in the response message).
- The IMSRequest node serializes the data and sends it to IMS to run.
The node parses the returning bit stream by using the generic message type
msg_IMSMessage,
which splits the bit stream into individual segments.
- The Reject? Filter node counts the number of segments: if there is one segment, the
response is an error; if there is more than one, it is a successs.
- The ProcessSuccessReponse subflow causes the re-parsing of the
bit stream by using the msg_COBOLRESPONSE format,
and maps it to make an XML format.
- The ProcessRejectResponse subflow causes the re-parsing of the
bit stream by using the msg_REJECTMESSAGE message type,
and maps it to an XML response.
- The RestoreMQMD Compute node adds the original MQMD.
- The MQOutput node puts the XML message to queue IMS_SYNC_REQUEST_OUT1.
The most important part of the message flow is the parsing of the response message.
This parsing is complicated by the fact that IMS transactions are not strongly
typed and can return any number or combination of segments. The flow
handles this situation by first parsing the response with a generic segment
message type, which works for anything that the IMSRequest node can return,
then by using logic in a Filter node (or any routing node) to route the
message to processing that can re-parse it with a well-known
type. The general logic here can be used with
any IMS transaction, provided that the segment
definitions can be imported (or constructed by hand), and some
data exists in the segments that help to identify which message type to use.
The message flow uses ResetContentDescriptor nodes to perform the re-parsing, but the re-parsing
can also be performed by using ESQL statements.
How a message flow works with the REXX version
The preceding description refers largely to COBOL. The message flow also works
with the REXX version of the program because the REXX
version has the same input message as the COBOL program. The main
difference is in the response message. The two main differences between the
response message are:
- REXX has five header segments before the details section.
- The REXX version has different physical formats for each of
the data fields (but the same number and types of fields).
The sample therefore needs two response formats:
msg_COBOLRESPONSE
and msg_REXXRESPONSE. The main difference between
these formats is that the REXX version has five header segments before the details segment.
The detail segment is the same but a new REXX physical format has been
added that deals with the different data types. When parsing the REXX
response, the message type msg_REXXRESPONSE with the format REXX is
used.
Back to sample home