Conversational structure

Structuring your conversational program depends on the interactions between your program and the person at the terminal.

Before structuring your program, you need to know:

What should the program do in an error situation?
When a program in a conversation terminates abnormally, IMS TM backs out only the last cycle of the conversation. A cycle in a conversation is one terminal/program interaction. Because the conversation can terminate abnormally during any cycle, you should be aware of some things you can do to simplify recovery of the conversation:
- The ROLB or ROLS call can be used in conversational programs to back out database updates that the program has made since the last commit point. ROLL can also be used in conversational programs, but terminates the conversation.
- If possible, updating the database should be part of the last cycle of the conversation so that you do not have different levels of database updates resulting from the conversation.
- If your program encounters an error situation and it has to terminate, it can use an express alternate (program communication block) PCB to send a message to the originating terminal, and, if desired, to the master terminal operator.
  To do this, the program issues a CHNG call against the express alternate PCB and supplies the name of the logical terminal from the TP PCB, then an ISRT call that references that PCB and the I/O area that contains the message. The program can then issue another CHNG call to set the destination of the express alternate PCB for the master terminal, and another ISRT call that references that PCB, and the I/O area that contains the output message.
Does your application program process each cycle of the conversation?
A conversation can be processed by one or several application programs. If your program processes each stage of the conversation (in other words, your program processes each input message from the terminal), the program has to know what stage of the conversation it is processing when it receives each input message.

When the person at the terminal enters the transaction code that starts the conversation, IMS TM clears the SPA to binary zeros and passes the SPA to the program when the program issues a GU call. On subsequent passes, however, the program has to be able to tell which stage of the conversation it is on so that it can branch to the section of the program that handles that processing.

One technique that the program can use to determine which cycle of the conversation it is processing is to keep a counter in the SPA. The program increments this counter at each stage of the conversation. Then, each time the program begins a new cycle of the conversation (by issuing a GU call to retrieve the SPA), the program can check the counter in the SPA to determine which cycle it is processing, then branch to the appropriate section.
How can your program pass control of the conversation to another conversation program?
Sometimes it is more efficient to use several application programs to process a conversation. This does not affect the person at the terminal. It depends on the processing that is required.

In the car loan example, one MPP could process the first part of the conversation (processing the name, address, and number of years), and another MPP could process the second part of the conversation (processing the data about the car and responding with the status of the loan).

A conversational program can perform two types of program switching:

Deferred program switch

Responds to the originating terminal but causes the next input from the terminal to go to another conversational program.

Immediate program switch

Passes the conversation directly to another conversational program. The program passes the SPA (and, optionally, a message) to another conversational program without responding to the terminal. In this case, it is the next program's responsibility to respond to the originating terminal.

A conversational program must:
1. Retrieve the SPA and the message using GU and GN calls.
  If your MPP is starting this conversation, test the variable area of the SPA for zeros to determine if this is the beginning of the conversation. If the SPA does not contain zeros, it means that you started the conversation earlier and that you are now at a later stage in the conversation. If this is true, you would branch to the part of your program that processes this stage of the conversation to continue the conversation.
  
  If another MPP has passed control to your MPP to continue the conversation, the SPA contains the data you need to process the message, so you do not have to test it for zeros. Start processing the message immediately.
2. Process the message, including handling any necessary database access.
3. Send the output message to the terminal by using an ISRT call against the I/O PCB. This step can follow step 4.
4. Store the data (that your program, or the program that you pass control to, needs to continue processing) in the SPA using an ISRT call to the I/O PCB. (This step can precede step 3.) IMS TM determines which segment is the SPA by examining the ZZZZ field of the segment shown in the tables below.
To end the conversation, move blanks to the area of the SPA that contains the transaction code, and then insert the SPA back to IMS TM by issuing an ISRT call and referencing the I/O PCB.

If your MPP passes the conversation to another conversational program, the steps after the program processes the message are somewhat different.

Also, your program should be designed to handle the situation that occurs when the first GU call to the I/O PCB does not return a message to the application program. This can happen if the person at the terminal cancels the conversation by entering the /EXIT command before the program issues a GU call. (This happens if the message from this terminal was the only message in the message queue for the program.)

The contents of SPA

The SPA that IMS TM gives your program when you issue a GU contains the four parts shown in the following tables.

Table 1. SPA format for AIBTDLI, ASMTDLI, CBLTDLI, CEETDLI, CTDLI, and PASTDLI interfaces
Field Name	Field Length
LL	2
ZZZZ	4
TRANCODE	8
User Work Area	Variable

Table 2. SPA format for the PLITDLI interface
Field Name	Field Length
LLLL	4
ZZZZ	4
TRANCODE	8
User Work Area	Variable

The SPA format fields are:

LL or LLLL: A length field that gives the total length of the SPA. This length includes 2 bytes for the LL field. (For the PLITDLI interface, use a 4-byte field. Its contents include 4 bytes for LLLL, minus 2.)
ZZZZ: A 4-byte field reserved for IMS TM that your program must not modify.
TRANCODE: The 8-byte transaction code for this conversation.
User Work Area: A work area that you use to save the information that you need to continue the conversation. The length of this area depends on the length of the data you want to save. This length is defined at system definition.

When your program retrieves the SPA with a GU to start the conversation, IMS TM removes the transaction code from the message. In your first message segment, you receive only the data from the message that the person at the terminal entered.

The following list indicates the ways that an application program processes the SPA. The program must:

Not modify the first 6 bytes of the SPA (LL and ZZZZ). IMS TM uses these fields to identify the SPA.
If the program modifies the SPA, the program must return the SPA to IMS TM (or, for a program switch, to the other program).
Not return the SPA to IMS TM more than once during one cycle of the conversation.
Not insert the SPA to an alternate PCB that represents a nonconversational transaction code or a logical terminal. The program can use an alternate response PCB if it represents that same physical terminal as the originating logical terminal.

Restriction: If you are using MFS, the IMS TM does not always remove the transaction code.

The appearance of messages in a conversation

Because the first segment contains the SPA, conversational input messages are made up of at least two segments. The input message starts in the second message segment.

The input message segment in a conversation contains only the data from the terminal. During the first step in the conversation, IMS TM removes the transaction code from the input message and places it in the SPA. When the program issues the first GU, IMS TM returns the SPA. To retrieve the first message segment, the program must issue a GN.

The format for the output messages that you send to the terminal is no different than the format for output messages in nonconversational programs.

Saving information in the SPA

After you have processed the message and are ready to reply to the terminal, you can save the necessary data in the SPA. The part of the SPA in which you save data is the work area portion. Use the ISRT call to save data to the work area. This is a special use of the ISRT call, because you are not sending the SPA to a terminal, but rather saving it for future use.

If your program processes each stage of the conversation, you just issue an ISRT call to the I/O PCB and give the name of the I/O area that contains the SPA. For example:

ISRT   I/O PCB, I/O AREA

This returns the updated SPA to IMS TM so that IMS TM can pass it to your program at the next cycle of the conversation.

If you do not modify the SPA, you do not need to return it to IMS. However, the SPA will be passed by IMS TM to your program at the next cycle of the conversation.