Overview

Skill Level: Any Skill Level

This recipe describes the lifecycle of events in an IMS Connect transaction by stepping through the corresponding log records. Understanding these events can help you to understand how your own systems work and to diagnose problems.

Ingredients

Reading this recipe might be enough. You don't need any ingredients for that. Reading this recipe will help you to understand the events in a successful IMS Connect send-then-commit, sync level confirm OTMA transaction.

To view this lifecycle of events for your own IMS Connect transactions, you will need:

This recipe is also available on video.

The IBM Z YouTube channel shows this lifecycle in the video "The Lifecycle of an IMS Connect Transaction". The video also demonstrates browsing the corresponding log records in IMS Problem Investigator.

 

The diagrams in this recipe are also available as a poster (PDF).

The diagrams in this recipe can be a useful reference for analyzing IMS Connect transactions. The two main diagrams from this recipe are available as a single-page PDF file on SlideShare: "IMS Connect send-then-commit sync level confirm transaction lifecycle: Poster".

 

How is this a recipe?

How is stepping through a transaction lifecycle a "recipe"? What does this recipe create?

This recipe helps you to understand the lifecycle of IMS Connect transactions. That understanding can help you to solve problems; to recognize when and where something has gone wrong.

So, this recipe "creates understanding"? Really?!

Okay. Perhaps I'm subverting the concept of what a developerWorks recipe ought to be.

Either way, I hope you find the content useful. If you do, you'll find more to like in the video.

Step-by-step

  1. IMS Connect receives request from client, sends it to IMS

    IMS Connect transaction lifecycle  with IMS Connect Extensions trace events: request and response

    The lifecycle begins with an IMS 08¬†“application start” log record, marking the scheduling of the program specification block (PSB) for the requested transaction code. This record appears first because the PSB was scheduled before this transaction was requested.

    IMS Connect transaction lifecycle  with IMS Connect Extensions trace events: IMS Connect receives request from client

    IMS Connect event 3C is a start-of-frame event for an IMS Connect transaction. This event reads the start of the message from the client.

    Event 49 reads the remainder of the message.

    Event 3D marks the entry to the user message exit routine.

    IMS Connect Extensions trace event A4 exposes the IMS request message (IRM). This record is useful for diagnosing communication issues with the client; it shows you exactly what the client sent.

    If you set IMS Connect Extensions tracing to level 2, trace event records will include application data, such as the transaction request data that typically follows an IRM.

    Trace event A3 exposes the OTMA message built by the exit routine. This message contains the information from the IRM translated into the OTMA protocol.

    IMS Connect event 3E marks the return from the user message exit.

    Event 41 sends the OTMA message to IMS via the cross-system coupling facility, XCF.

    The transaction request has left IMS Connect and is bound for IMS.

  2. IMS processes request, returns response to IMS Connect

    IMS Connect transaction lifecycle  with IMS Connect Extensions trace events: IMS processes request

    The IMS 01 log record is the first IMS log record for this transaction instance. This record marks the point where IMS adds the input message to the message queue buffer.

    The 35 record marks the point where IMS adds the message to the message queue.

    The 5607 record marks the start of the unit of recovery for this transaction.

    We’re now in application code; the message processing program (MPP).

    The 31 record marks the point where the MPP gets the input message from the queue.

    The 5616 record marks the start of the unit of work.

    IMS 5E log records describe sequential buffer activity.

    IMS log records with code prefix 50 indicate database changes. Inserting just a single record typically triggers multiple database changes, hence multiple 50nn records.

    The 03 record marks the point where the MPP adds its output message to the message queue buffer.

    We’ve now left the application code.

    This 31 record marks the point where IMS OTMA processing gets the output message from the message queue.

    IMS returns the output to IMS Connect as an OTMA message via XCF.

  3. IMS Connect receives response from IMS, sends it to client

    IMS Connect transaction lifecycle  with IMS Connect Extensions trace events: IMS Connect receives response from IMS

    IMS Connect event 42 marks the arrival of the OTMA response message from IMS.

    IMS Connect Extensions trace event A3 exposes the OTMA message received from IMS.

    IMS Connect calls the same exit routine that it called for the input message. This time, IMS Connect calls the transmit function of the routine, not the read function.

    Trace event A6 exposes the response message built by the exit routine.

    IMS Connect event 3E marks the return from the exit routine.

    Event 4A writes the response to the client.

    Let’s review what’s happened so far.

    The client sent a request to IMS Connect; IMS Connect forwarded the request to IMS; the application processed the request; IMS forwarded the response to IMS Connect; IMS Connect returned the response to the client.

    IMS has sent a response to the client, but has not yet committed the database updates. This example is a send-then-commit (also known as commit mode 1) transaction with sync level confirm. This means that IMS sends the response, then waits for an acknowledgment from the client before committing changes.

    This wait time is a significant performance factor, because IMS holds syncpoint processing, and prevents the message processing region from processing another transaction, until it receives the acknowledgment from the client. To avoid delays caused by waiting for client acknowledgments, you might need more message processing regions. For now, let’s stay focussed on this transaction.

  4. IMS Connect receives acknowledgment from client, sends it to IMS

    IMS Connect transaction lifecycle  with IMS Connect Extensions trace events: acknowledgment and confirmation

    The next events in the lifecycle are two IMS Connect 49 events, which read a new message: the acknowledgment from the client.

    IMS Connect transaction lifecycle  with IMS Connect Extensions trace events: IMS Connect receives acknowledgment from client

    The next few events follow the same pattern as events for the original request message.

    We see the user exit routine being called and returning, trace records for the IRM and OTMA message, and then the OTMA message being sent to IMS.

    IMS Connect sends the ack in an OTMA message to IMS.

  5. IMS receives ack, begins two-phase commit, returns commit confirmation

    IMS Connect transaction lifecycle  with IMS Connect Extensions trace events: IMS receives ack, returns confirmation

    IMS receives the client acknowledgment.

    The IMS 33 log record marks the point where IMS frees the output message from the IMS message queue.

    How do we know this “free message” record refers to the output message; not, say, the input message?

    Two reasons:

    • First, our understanding of IMS transaction processing leads us to expect that IMS will free the output message here, after receiving the client acknowledgment, and free the input message later, when IMS commits the changes.
    • Second, we can use either the device relative record number (DRRN) of each message or the processing token in the corresponding log records.
      For example, we can see that the DRRN of the output message in the IMS 03 log record matches the DRRN of the message freed in this IMS 33 log record. (Note that DRRNs are reused, whereas processing tokens are unique.)

    IMS now proceeds with the two-phase commit.

    The 5610 record marks the start of phase 1.

    The 3730 record marks the crossover between the end of phase 1 and the start of phase 2.

    IMS returns a commit confirmation message to IMS Connect, and then completes the commit processing.

    The IMS 33 log record marks the point where IMS frees the input message from the queue.

    The 5612 record marks the end of the two-phase commit.

  6. IMS Connect sends commit confirmation to the client

    IMS Connect transaction lifecycle  with IMS Connect Extensions trace events: IMS Connect sends confirmation to the client

    IMS Connect event 42 marks the arrival of the commit confirmation message from IMS.

    Event 46 de-allocates the OTMA session with IMS.

    The next few events follow the same pattern as events for the output message.

    IMS Connect sends the commit confirmation to the client.

    Event 48 is the end-of-frame event for an IMS Connect transaction.

    IMS Connect has completed its processing for this transaction.

  7. MPP terminates

    IMS Connect transaction lifecycle  with IMS Connect Extensions trace events: MPP terminates

    Later, possibly after processing subsequent transactions, the message processing program terminates. This event is marked by the IMS 07 log record.

Join The Discussion