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: 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:

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:

The success output message is made up of three header sections and a repeating detail section:

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: 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:

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:

  1. Create a new message set that has a binary physical format called COBOL.
  2. Expand the new message set, right-click the Message definition folder, and click New > Message definition file from > COBOL file.
  3. Browse to find the file DFSSAM7.cbl (either obtained from your own system or extracted from DFSSAM7).
  4. 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.
  5. 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.
  6. 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:
  1. Open the Message definition DSPALLI in the editor, right-click Messages, click Add message.
  2. Name the new message msg_IMSMessage.
  3. Right-click Types, click Add Complex Type.
  4. Name the type segmentType.
  5. Add a new element called IMSSegment to msg_IMSMessage of type segment. Ensure that it has a max occur value of -1 (unbounded).
  6. 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.
    IMSMessage structure
  7. Select the ZZdata field and switch from Overview to Properties.
  8. Change the COBOL physical representation from Length to Length Reference.
  9. Set the Length Reference field to LL.
  10. Select Inclusive Length Reference because the LL field is the length of the whole segment including LL and ZZ. IMS message physical format

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:

  1. Open the Message definition DSPALLI in the editor, right-click Messages, and click Add message.
  2. Name the new message type msg_COBOLRESPONSE.
  3. Add two elements to the new type: one called IMSSegment of type segmentType and another called msg_DETAILOUT of type DETAILOUT.
  4. The IMSSegment must have a min occurs and a max occurs of 3 (for the three header segments that are not parsed).
  5. The msg_DETAILOUT segment must have min occurs 0 and max occurs unbounded (-1). COBOL reponse data structure

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:

IMS request message flow

The node-by-node processing is described in the following list:

  1. The MQInput node takes the message from the queue IMS_SYNC_REQUEST_IN1 and parses it with the XML parser.
  2. 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.
  3. 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).
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. The RestoreMQMD Compute node adds the original MQMD.
  9. 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:

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