Agenda

• Introduction to Online Concepts

• IMS DC Introduction
• Types of IMS DC Programs
• Programming elements of IMS DC
• Programming Integrity and Recovery Considerations
• Message Formatting Service MFS
• Writing DLI calls for Transaction Management
• Programming Examples in IMS DC

IMS DC 1
 Objectives
• To answer, what is IMS DC?

• To develop an understanding of the processing available under IMS/DC.

• To develop the ability to write programs involving IMS DC Screens.

IMS DC 2
Online Concepts

General Online Concepts

• Interactive sessions of the user with the computer

• Interactions are driven by transactions
• User enters input through a screen, programs edit/validate the input data and
processes the information for display back to the user
• More emphasis on response time, security, data integrity and system
performance
• Applications where quick response to a given request is required are good
candidates for online
• Applications such as Reservation systems and Account Inquiry are real life
online applications

Copyright © 2006 Accenture All Rights Reserved. Accenture, its logo, and Accenture
3 High Performance Delivered are trademarks of Accenture.
Online Concepts
Batch and online Differences

Batch Online

• Driven by input records Driven by user requests

• Submitted thru JCLs Transaction oriented
• Processing time is longer Processing time is kept
at its minimum
• Only one user can process Multiple users allowed
• Batch programs have exclusive Shared access
control over data
• Security is easy to maintain Restricted security for
unauthorized access

IMS DC 4
Online Concepts
Types of Online Programs

• Inquiry Programs
- Programs retrieve appropriate information for display

• Data Entry programs

- Programs validate the input and retrieves/updates relevant information

• Maintenance programs
- Programs add/update/delete information based on the input

• Menu programs
- A navigational system which allows users to choose from a set of multiple
options

IMS DC 5
IMS DC Concepts
Types of DC Programs

1. Conversational Message processing program (MPP)

2. Non-conversational message processing program (MPP)
3. Batch Message Processing(BMP)

Conversational MPP
• It intended specifically for maintaining data between terminal interactions.
• You can store data
* on the terminal screen
* in a database
* in an IMS provided scratch pad area.
Non-conversational MPP
• Entire transaction is completed in one cycle
• Data cannot be transferred from 1 cycle of transaction to another cycle.
• Useful when entire processing is completed based on inputs

IMS DC 6
IMS DC Concepts
Batch Message Processing programs (BMPs)

There are two types of BMP’s :

1. Transaction-orientated
 can access the on-line message queues.
 Can process input from and output to OS/VS files and databases.

2. Batch-orientated
 access on-line database in batch mode
 can send messages to the message queue
 are scheduled by the operator using JCL

IMS DC 7
IMS DC Concepts

Messages,queueing,Segment,IO-PCB,Input-output
You do have to be concerned with the data that terminal user enters is eventually
passed to your program as input message.
There are three types of input messages:
 Transactions
 Terminal-to-terminal message switches
 IMS commands
You can Identify input message type
 If IMS uses the value in 8 bytes characters name in an application
program i.e transaction.(transaction code)
 If the first 8 characters contain an LTERM name i.e message
switch (Its used generally when master terminal communicates
with other set of terminals)
 If the input message begins with a slash IMS interprets it as a
command. (it’s a message that is directed to Ims itself)

IMS DC 8
IMS DC Concepts

Output msg MVS address

space
Printer

I/p msg (msg switch)

Display MVS Address
station space

I/P msg(transaction) IMS control MPP Region

Display region
station Application
program

I/p msg command)

Display
station

IMS DC 9
IMS DC Concepts
* Message queueing:
 When IMS receives a message from a terminal it’s not passed
immediately to the destination, instead they go for either IMS
basic editing or MFS edit.
 The entry a terminal user makes to invoke a transaction and the
execution of the application program with which it is associated
are not synchronous.
 The IMS stores the transaction temporarily, which is message
queuing and the IMS modules that performs this are collectively
called the queue manager (QPOOL).
* How to retrieve segments:
 If an input message consists of just one segment occurrence all
you need to do is issue one GU call to retrieve it.
 The MPP issues a DC GU call to retrieve the input message
from the IMS message queue, then it does database processing
based on the input message queue.

IMS DC 10
IMS DC Concepts

 When the program gets a QC status code (instead of blanks) as a result

of its DC GU call, it knows there are no more messages for it on the
queue and it ends.
 To retrieve first segment of a multiple segment message your program
issues a GU call that specifies the I/O PCB.
 To retrieve subsequent segments for that message it issues GN call
repeatedly until it encounters a QD status code.

* Note:
If you issue another GU call before issuing all the GN calls necessary to retrieve all the
segments of a single message, those remaining segments will be lost.

IMS DC 11
IMS DC Concepts
* IO-PCB in DC call:

 A DC call must specify a linkage section PCB mask similar to the way it is
done in a DB call.

 This is not a database PCB mask, it’s for the message processing, in
IMS terminology it’s called the I/O PCB

 It must be the first PCB listed on the ENTRY statement

 All you have to do is specify the name of the I/O PCB on the ISRT call
that sends an output message.

IMS DC 12
IMS DC Concepts
* Input-output area (I/O AREA):
• How to define i/o area for an input message segment
01 INPUT-MESSAGE-IO-AREA.
05 IM-LL PIC S9(3) COMP. (length of entire input message)
05 IM-ZZ PIC S9(3) COMP. (reserved for IMS for input)
05 IM-TRANS-CODE PIC X(9). (1-8 byte value followed by space)
05 IM-INVOICE-NO PIC X(6). (enough area to hold i/p message)
 How to define i/o area for output message segment;
01 OUTPUT-MESSAGE-IO-AREA
05 OM-LL PIC S9(3) COMP VALUE +706. (Can modify in o/p only)
05 OM-ZZ PIC S9(3) COMP VALUE ZERO. (reserved by IMS)
05 OM-TEXT PIC X(702).
 Before you issue an ISRT call you need to be sure that the LL field in the i/o area
contains the actual length of the message that’s to be sent including initial 4 bytes.

IMS DC 13
IMS DC Concepts
MESSAGE FORMATTING SERVICE (MFS)

 It is a part of IMS TM that uses control blocks that you define to format
messages between a terminal and an MPP.

 The MFS control blocks indicate to IMS TM how you want your input and
output messages arranged.

 MFS makes it possible for an MPP to communicate with different types of

terminals without having to change the way it reads and builds messages.

IMS DC 14
IMS DC Concepts
"Processing Messages: MPPs“

Message processing programs, or MPPs, are online application

programs whose primary purpose is to answer processing requests
from users at terminals. The requests and the MPPs' replies are
messages. IMS collects input messages and schedules an MPP
when a message is available. The program then retrieves the
message, processes it, and sends a reply to the terminal.

"Processing Messages: IFPs“

An IMS Fast Path (IFP) program is an online program that allows

you to quickly process and reply to messages from the terminal.
An IFP is similar to an MPP except that an IFP bypasses IMS
message queuing.

IMS DC 15
IMS DC Concepts
"Batch Message Processing: BMPs"

Batch message processing programs, or BMPs, can perform

batch-type processing and message processing. BMPs are flexible in
terms of the data available to them and the processing they can
perform. BMPs are not scheduled by IMS.

You start a BMP with JCL.

IMS DC 16
MFS Concepts

Basic concepts of MFS

• The IMS message format service (MFS) is a facility of the IMS Transaction
Manager environment that formats messages to and from terminal devices.
• MFS uses control blocks you specify to indicate to IMS how input and output
messages are arranged.
• For input messages, MFS control blocks define how the message sent by the
device to the application program is arranged in the program's I/O area.
• For output messages, MFS control blocks define how the message sent by the
application program to the device is arranged on the screen or at the printer.
• MFS makes it possible for an MPP to communicate with different types of
terminals without having to change the way it reads and builds msg.

IMS DC 17
MFS Concepts
MFS Control Blocks
There are three types of control statements
* device format control statements
* message descriptor control statements
* compilation control statements

There are four types of MFS control blocks

1 Message Output Descriptors (MODs) define the layout of messages MFS receives from
the application program.
2 Device Output Formats (DOFs) describe how MFS formats messages for each of the
devices the program communicates with.
3 Device Input Formats (DIFs) describe the formats of messages MFS receives from each of
the devices the program communicates with.
4 Message Input Descriptors (MIDs) describe how MFS further formats messages so that
the application program can process them.

IMS DC 18
MFS Concepts
Advantages of Using MFS

• MFS simplifies developing and maintaining terminal-oriented applications by performing

common application functions and providing independence from specific devices or
remote programs.

• MFS improves online performance by using control blocks for online processing.

IMS DC 19
MFS Concepts
Types of message formatting

1. Input messages

• Input data from MFS-supported devices in formatted mode is formatted

based on the contents of two MFS control blocks--the message input
descriptor (MID) and the device input format (DIF).

• The MID defines how the data should be formatted for presentation to the IMS
TM application program and points to the DIF associated with the input device.

• The DIF describes the data as the data is received from the device.

IMS DC 20
MFS Concepts
Types of message formatting

2. Output messages

* Output processed by MFS are formatted based on the contents of two MFS control
blocks:the message output descriptor (MOD) and the device output format (DOF).

* The MOD defines output message content and, optionally, literal data to be considered
part of the output message. Message fields (MFLDs) refer to device field locations via
device field (DFLD) definitions in the DOF.

* The device output format (DOF) specifies the use of hardware features, device field
locations and attributes, and constant data considered part of the format.

IMS DC 21
MFS Concepts
Basic MFS code for any given screen: DOF/DIF

PAYF FMT
DEV TYPE=(3270,2),FEAT=IGNORE,DSCA=X'00A0'
DIV TYPE=INOUT
DPAGE CURSOR=((5,15))
DFLD '**********************',POS=(1,21)
DFLD '* EMPLOYEE PAYROLL *',POS=(2,21)
DFLD '**********************',POS=(3,21)
DFLD 'FIRST NAME:',POS=(5,2)
FNAME DFLD POS=(5,15),LTH=16
DFLD 'LAST NAME:',POS=(5,36)
LNAME DFLD POS=(5,48),LTH=16
DFLD 'EMPLOYEE NO:',POS=(7,2)
EMPNO DFLD POS=(7,16),LTH=6
DFLD 'SOC SEC NO:',POS=(9,2)
SSN DFLD POS=(9,15),LTH=11
DFLD 'RATE OF PAY: $',POS=(11,2)
RATE DFLD POS=(11,17),LTH=9
DFLD 'INPUT:',POS=(16,2)
INPUT DFLD POS=(16,10),LTH=30
FMTEND

IMS DC 22
MFS Concepts
MID
PAYIN MSG TYPE:INPUT,SOR=(PAYF,IGNORE)
SEG
MFLD 'PAYUP ' SUPPLIES TRANCODE
MFLD LNAME,LTH=16
MFLD FNAME,LTH=16
MFLD EMPNO,LTH=6
MFLD SSN,LTH=11
MFLD RATE,LTH=9
MFLD INPUT,LTH=30,JUST=R,FILL=C'0'
MSGEND
MOD
PAYDAY MSG TYPE:OUTPUT,SOR=(PAYF,IGNORE)
SEG
MFLD LNAME,LTH=16,ATTR=YES
MFLD FNAME,LTH=16
MFLD EMPNO,LTH=6
MFLD SSN,LTH=11
MFLD RATE,LTH=9
MFLD INPUT,LTH=30,JUST=R,FILL=C'0'
MSGEND

IMS DC 23
MFS Concepts
PAGING CONCEPT
Paging is a facility that lets messages be broken down into components for
display, for processing or for both.

MFS provides two kinds of paging:-

1.Physical paging: A message with a fixed number of segments is further divided into parts
that are sized properly for a particular device.
* You can define this through the DFLD statement like pos=(8,12)
* If you want multiple physical pages just specify MULT=YES in the DPAGE statement in format
set.

2.Logical paging: A logical page is simply a group of related fields either

on the terminal screen or in a message.
* Can send multiple occurrences of the same screen but with different data, as part of one
output message.
* You can define it by coding device page(DPAGE)message page(LPAGE) statements

IMS DC 24
MFS Concepts
PF KEY OPERATIONS

* The PFK parameter specifies a name that can be referred to by the MFLD statement that
defines the input message field that will receive literal data as a result of a PF key
operations,this should not be the name of device field.

* If the PF key you press is specified in the PFK parameter of the DEV statement MFS
moves literal data that you have specified for that PF key to a field in the input message
before it pass to IMS for queuing.

* If the literal data specifies the destination of the message (a program, terminal,IMS
command) then PF key can be used to request programs or IMS functions.

* If the field is embedded in the message the literal data is passed with the rest of the
message to its destination through PF key data as a control information to the application
program.

IMS DC 25
MFS Concepts
Control attributes & cursor positioning
To change attributes dynamically your Cobol program passes control information to
* identify and define fields that eligible for dynamic attribute modification (DAM).
* know the format and content of the control bytes you use for DAM.
* code your Cobol program so it can pass the correct control information to MFS.
suppose a device format includes a six byte field used to display an invoice number,

If you don't want DAM then MFLD INVNO, LTH=6.

If you want DAM then MFLD INVNO, LTH=8, ATTR=YES.

Note: although 2 byte prefix is not displayed it is a part of the data sent to MFS

*A cursor is mark on the terminal screen that identifies where the next data
the operator enters will be displayed.
* You can specify cursor positioning through MFS on the DPAGE statement
DPAGE CURSOR=(3,17)

IMS DC 26
MFS Concepts
Syntax rules for MFS control statements

• Columns 1-8 : Label field .If you code label value it must begin in column-1and first
character must be alphabetic.The maximum length of label is 8 characters.
• Columns 10-14: Operation field like FMT,DFLD,MSG,DEV these are called operation
codes. After operation field code the operand field, which contains one or more
parameters that indicate what the statement is to do,it must be separated from the
operation field by one or more spaces, if you leave column-15 blank, the operand field
can begin in column-16.
• When the MFS language utility encounters a space after the parameter,it considers the
operand field to have ended, and it ignores any data that follows column 71, as a result
you can code brief comments in this comment field.
• If you need to code a statement that’s too long to fit on a single line you can use
continuation lines, to do so you code a non-blank value in column-72 of all lines that
make up the statement except the last.

IMS DC 27
MFS Concepts
MFS control statement looks like an assembler language.

Format of an MFS control statement

Continuation
Label Operation Operand/comments
character
(pos 1-8) (pos 10-14) (pos16-71)
(pos 72)

IMS DC 28
MFS Concepts
DEVICE FORMAT CONTROL STATEMENTS

 FMT : Identifies the beginning of a device format.

 DEV: Identifies the beginning of a series of control statements for a particular device type;
you can code multiple DEV statements within a device format.

 DIV: Identifies the beginning of a series of control statements for a particular format type
subordinate to a DEV statements, for 3270 display station, you code only one DIV
statement subordinate to the DEV statement.

 DPAGE: Identifies the beginning of a series of control statements for a device page
subordinate to a DIV statement.

 DFLD: Identifies a device field within a device page.

 FMTEND: Identifies the end of a device format.

IMS DC 29
MFS Concepts
Figure below shows the device format control statements:

FMT
DEV
DIV
DPAGE
DFLD
.
DPAGE
DFLD
.
DFLD

FMTEND

IMS DC 30
MFS Concepts
The DEV control statement
• For each different device type for which you want MFS support for a given application
you code DEV statement
• If three different device types were to be used for the same application you’d code three
DEV statements one for each,subordinate to each of these three DEV statements you’d
code a set of DIV,DPAGE,DFLD statements to define screen format.
• A device statement not only identifies a particular kind of device also specifies its
characteristics as well.
• Figure below shows the format of DEV control statement:
DEV TYPE=(3270,1)
,FEAT=IGNORE
[,PFK=(pfkeyfield,[integer=]{‘literal’} [,….] ) ]
[,DSCA=X’nnnn’]

[,SYSMSG=msgfield]

IMS DC 31
MFS Concepts
The DEV control statement

• TYPE Statement identifies the type of Terminal. For e.g. (3270,2) is 24 X 80, (3270,1) is 12
X 80 etc.
• FEAT = IGNORE -- This is default and it ensures that DIF and DOF generated with this
terminal type will work on all terminals of the same type regardless of the special features
installed on it.
• PFK Parameter -- This is used to define the PF Key actions. This has two parts
PFK=(Fieldname,parameters....). This fieldname is a Pseudo field name that has to be
defined in DIF with a length of 2. And the "parameters" can be positional or keyword.
• DSCA -- means default system control area. DSCA = X'00A0' ==> erase unprotected fields
on screen before new data is written on it. DSCA = X'00C0' ==> clear entire device buffer
before output is written on the screen.
• SYSMSG -- this parameter is used to route any system messages to the screen field
associated to it.

IMS DC 32
MFS Concepts
The DIV Control statement

• After the DEV statement you code a DIV statement, you always code to indicate that
the same device format specifications should be used to generate both a DIF and
DOF.

• You code INOUT for a 3270 display station because an output format becomes the
input format for the next message.
DIV TYPE=INOUT

• This generates both DIF and DOF

IMS DC 33
MFS Concepts
The DPAGE statement
The primary function of the DPAGE control statement is to let you specify a device format that
will handle multiple logical pages. You may need to use DPAGE statement for initial cursor
positioning and field Fill.
Label DPAGE
[CURSOR=((line,column,cfield]…..) ]
[, FILL = fill char]
[, MULT=YES]

• It has the CURSOR parameter which identifies the Static Cursor Positioning. For e.g. CURSOR
= ((5,12)).
• It has the FILL parameter that specifies what character should be used to pad device fields
when output data sent to them doesn't fill them.
• FILL = PT is default ==> The program tab character avoids transmitting blanks to fill partially full
fields but at the same time it erases previously displayed data that would otherwise be left in the
unused parts of those fields. .

IMS DC 34
MFS Concepts
THE DFLD CONTROL STATEMENTS

DFLD indicates the Device Field. The Format of the DFLD is as shown below

Label DFLD [ ‘literal’ ]

,pos=(line,column [ , page] )
[, LTH =length]
[,ATTR =( [ALPHA,NUM] [, NOPROT/PROT] [, NORM/NODIS,HI]
[,NOMOD/MOD] ) ]
[,EATTR=([HD/HBLINK,HREV,HUL] [,CD/BLUE,RED,PINK/GREEN/NEUTRAL] ) ]

IMS DC 35
MFS Concepts
The DFLD control statement

• The POS parameter tells IMS where a device field is located.

• ATTR parameter is used to provide attributes to a Field or Label.
• For Fields, the default attribute parameter is alphanumeric, unprotected and normal
intensity.
• For Labels, the default attribute parameter is protected and normal intensity.
• ATTR = ( ALPHA / NUM , NOPROT / PROT, NORM / NODISP / HI, NOMOD / MOD ).
• If MOD is specified, the data will be transmitted to the program even if the user has not
modified the data in the screen.
• If NOMOD is specified, the data will NOT be transmitted to the program even if the user
has modified the data in the screen.
• If you have coded a literal for a device field, you don't have to code the LTH Parameter.

IMS DC 36
MFS Concepts
Message descriptor control statements

• MSG : Identifies the beginning of a message descriptor.

• LPAGE : Identifies the beginning of a series of control statements for a logical page
subordinate to a MSG statement.
• PASSWORD : Identifies the beginning of a series of MFLD statements that are used to
construct the password for an input message.You may code only one PASSWORD
statement subordinate to an LPAGE statement.
• SEG : Identifies the beginning of a series of MFLD statements the make up a message
segment.You may code multiple SEG statements subordinate to an LPAGE statement.
• MFLD : Identifies a message field subordinate to either a PASSWORD
statement or a SEG.
• MESGEND : Identifies the end of a message descriptor.

IMS DC 37
MFS Concepts
The message descriptor control statements are arranged hierarchically

MSG
LPAGE
PASSWORD
MFLD
SEG
MFLD
MFLD
SEG
MFLD…….
MFLD
MSGEND

IMS DC 38
 MFS Concepts
Syntax for Message Descriptor

• To produce a message descriptor you code either a MID or MOD.

• Unlike the situation for a DIF and DOF you must code separate groups of statements to define
a MID and a MOD.

• Each segment of code that describes a message, whether it’s an input message or an
output message, begins with a MSG statement and ends with a MESGEND statement.
Syntax:
Msgname MSG TYPE = { INPUT/OUTPUT}
, SOR=(dfname, IGNORE)
[ , NXT= nextmsgname}
[ , PAGE = YES]
MSGEND

IMS DC 39
MFS Concepts
• TYPE = INPUT for MID and TYPE = OUTPUT for MOD

• SOR Parameter is used to give the Device Format Name. IGNORE is same as FEAT =
IGNORE in DEV Statement.

• NXT Parameter is used for Performance reasons . FOR MID its MOD and vice versa.

IMS DC 40
MFS Concepts
THE MFLD CONTROL STATEMENT

• There is typically a one-to-one relationship between fields in the message segment

descriptor and fields in the application program’s I/O area.
• For each MFLD statement you must code the first parameter.
• For an input message, the first parameter specifies the contents or source of the field.
• For output message the first parameter specifies the destination for the data the field
contains.

Syntax:
MFLD { source/destination}
[ , LTH=length]
[ , JUST={L/R} ]
[ ,FILL = fillchar ]
[ , ATTR = (YES) ]

IMS DC 41
MFS Concepts
• The SEG control statement identifies the segment that makes up the message.

• MFLD parameter is for the message field. We can code literals and length OR variable
name and length OR variable name, default value and length OR MFLD (CURDATE
DATE2) which implies MAP the system date DATE2 to the device Field CURDATE.

• When we are using such system referrals there are two points worth noting
– Do not Specify LTH parameter on MFLD statement
– Do not code this field in the Output Message IO Area in the program.

• JUST = L/R (Default is L)

• FILL = C' ' or X'40' for Spaces and FILL = C'0' for numeric fields initialized to Zeroes.
Note : The FILL parameter is coded only in MID and not in MOD.

IMS DC 42
MFS Concepts
HOW TO CODE THE COMPILATION CONTROL STATEMENTS

In addition to the control statements that define message descriptors and

device Format, you can also code several statements to control the way the
MFS language utility works, these are called compilation control statements.
Structure:
PRINT [ {ON/OFF} ] [ GEN/NOGEN ]
END
EJECT
TITLE ‘literal’
COPY membername
Advanced structure:
EQU ‘literal’
DO count
ENDDO

IMS DC 43
MFS Concepts

IMS has two editing procedures:

• Message Format Service (MFS) uses control blocks that define what a
message should look like to the person at the terminal and to the
application program.

• Basic edit is available to all IMS application programs. Basic edit

removes control characters from input messages and inserts the control
characters you specify in output messages to the terminal.

IMS DC 44
MFS Concepts
Using MFS Edit

MFS uses 4 control blocks to format messages between a pgm & terminal.
The two control blocks that describe input messages to IMS are:
• The device input format (DIF) describes to IMS what the input message will look like when
it is entered at the terminal.
• The message input descriptor (MID) tells IMS how the application program expects to
receive the input message in its I/O area.
By using the DIF and the MID, IMS can translate the input message from the way that it is
entered at the terminal to the way it should appear in the program's I/O area.

The two control blocks that describe output messages to IMS are:
• The message output descriptor (MOD) tells IMS what the output message will look like in
the program's I/O area.
• The device output format (DOF) tells IMS how the message should appear on the terminal.

IMS DC 45
MFS Concepts
Using Basic Edit

Basic edit removes the control characters from an input message before the application
program receives it, and inserts the control characters you specify when the application
program sends a message back to the terminal.

To format output messages at a terminal using basic edit, you need to supply the
necessary control characters for the terminal you are using.

If your application will use basic edit, you should describe how you want the data to be
presented at the terminal, and what it will look like in the program's I/O area.

IMS DC 46
MFS Concepts
Editing Considerations in Your Application

Provide the following information about your program's editing needs:

• How you want the screen to be presented to the person at the terminal for the person to
enter the input data.
• What the data should look like when the person at the terminal enters the input
message.
• What the input message should look like in the program's I/O area.
• What the data should look like when the program builds the output message in its I/O
area.
• How the output message should be formatted at the terminal.
• The length and type of data that your program and the terminal will be exchanging.

IMS DC 47
MFS Concepts
Gathering Requirements for Conversational Processing

• Conversational processing means that the person at the terminal can converse with the
application program.
• When you use conversational processing, the person at the terminal enters some
information, and an application program processes the information and responds to the
terminal. The person at the terminal then enters more information for an application
program to process.
• Each of these interactions between the person at the terminal and the program is called
a cycle in the conversation.

What Happens in a Conversation

A conversation is a dialog between a person at a terminal and IMS through one or more
application programs. The person at the terminal enters a request, receives the information
from IMS, and enters another request.

IMS DC 48
MFS Concepts
What happens in a Conversation

• For a program to continue a conversation, the program must have the necessary
information to continue processing.
• IMS stores data from one step of the conversation to the next in a scratchpad area
(SPA).
• When a program continues the conversation (the same program or a different one),
IMS gives the program the SPA for the conversation associated with that terminal.

In an airlines example, the first program might save the flight number and the names of
the people traveling, then pass control to another application program to reserve seats for
those people on that flight. The program saves this information in the SPA. If the second
application program did not have the flight number and names of the people traveling, it
would not be able to do its processing.

IMS DC 49
MFS Concepts

To end the conversation a Program can:

• Move a blank to the first byte of the transaction code area of the SPA and then return
the SPA to IMS.

• Respond to the terminal and pass control to a non conversational program. This is
also called a deferred switch, but Program A ends the conversation before passing
control to another application program.

• The second application program can be an MPP or a transaction-oriented BMP that

processes transactions from the conversational program.

IMS DC 50
MFS Concepts
Identifying Output Message Destinations

An application program can send messages to another application program or to IMS

terminals. To send output messages, the program issues a call and references the I/O PCB
or an alternate PCB. The I/O PCB and alternate PCBs represent logical terminals and other
application programs with which the application program communicates.

The Originating Terminal

To send a message to the logical terminal that sent the input message, the program uses
an I/O PCB. IMS puts the name of the logical terminal that sent the message in the I/O
PCB when the program receives the message.

IMS DC 51
MFS Concepts
To Other Programs and Terminals

When you want to send an output message to a terminal other than, or in addition to, the
terminal that sent the input message, you use an alternate PCB. An alternate PCB is a
data communication program communication block (DCPCB) you define to describe output
Message destinations other than the terminal that originated the input message.

You can set the alternate PCB for a specific logical terminal when the program's PSB is
generated, or you can define the alternate PCB as being modifiable. A program can
change the destination of a modifiable alternate PCB while the program is running, so you
can send output messages to several alternate destinations.

IMS DC 52
Programming in IMS DC
Writing Application Programs

How Application Programs Work with the IMS Transaction Manager

Your application program uses IMS Transaction Manager (IMS TM) to process input and
output messages, and uses Data Language I (DL/I) to communicate with IMS.

Topics to be covered
- Application Programming Interface
- Getting Started with DL/I
- Using DL/I Calls
- Status Codes, Return Codes, and Reason Codes
- How Your Program Processes Messages
- How IMS TM Edits Messages
- DB2 Considerations

IMS DC 53
Programming in IMS DC
Application Program Environments

IMS has various environments in which you can execute application

programs. The three IMS online environments are:

- DB/DC
- DBCTL
- DCCTL

The two IMS batch environments are:

- DB Batch, which is generated from DB/DC and DBCTL class system

- TM Batch, which is generated from DCCTL class system generations

IMS DC 54
Programming in IMS DC
Messages from terminals and application programs are processed by the IMS control
region. The requested database segments or messages from other parts of the system
(for example, status codes, system messages, or responses from terminals) are also
processed by IMS and returned to the application.

The online environment can be used to access other types of database subsystems using
the External Subsystem Attach facility (ESAF). It permits applications running with IMS to
obtain data from external subsystems, such as DB2.

The transaction management portion of the IMS DB/DC environment can be used
separately to provide transaction management for external subsystems. This is the DCCTL
environment.

IMS DC 55
Programming in IMS DC
The DCCTL Environment

The DCCTL environment functions like IMS TM in a DB/DC environment, except that DCCTL
has no inherent database facilities. Instead, the DCCTL environment is used to access
external subsystems, such as DB2. GSAM databases, which contain sequential non-IMS
data sets, can be accessed by BMPs.

Most DL/I message processing and system service calls are supported in DCCTL. DL/I calls
that require access to IMS databases are not valid. Application programs in the DCCTL
environment can execute in the MPP, BMP, or IFP dependent regions. Except for the
restriction on DL/I calls to databases, application programs in the DCCTL environment are
the same as IMS TM applications.

IMS DC 56
Programming in IMS DC
How IMS TM Schedules Application Programs

IMS TM begins the scheduling process for an application program when a message
generated from a terminal or another application program requires processing. The
transaction manager assigns this input message, or transaction, to an available dependent
region and verifies that the application program is available to process the message. While
The application processes the message, IMS TM controls availability to other requests for
scheduling.

The PSB (defined by the PSBGEN utility) describes an application program to IMS TM and
contains the program control blocks (PCBs) required by the application.

IMS DC 57
Programming in IMS DC
Using DL/I Calls

A DL/I call consists of a call statement and a list of parameters. The parameters for the
call provide information IMS needs to execute the call. This information consists of the call
function, the name of the data structure IMS uses for the call, the data area in the program
into which IMS returns, and any condition the retrieved data must meet.

You can issue calls to perform transaction management functions (message calls) and to
obtain IMS TM system services (system service calls):

Two type of call functions :

1 Message Call Functions

2 System Service Call Functions

IMS DC 58
Programming in IMS DC
The IMS TM message processing calls are:

AUTH Authorization
CHNG Change
CMD Command
GCMD Get Command
GN Get Next
GU Get Unique
ISRT Insert
PURG Purge
SETO Set Options

IMS DC 59
Programming in IMS DC
System Service Call Functions

The IMS TM system service calls are:

APSB Allocate PSB

CHKP Checkpoint (Basic)
CHKP Checkpoint (Symbolic)
DPSB Deallocate PSB
o GMSG Get Message
GSCD (2) Get System Contents Directory
o ICMD Issue Command
INIT Initialize
INQY Inquiry
LOG Log

IMS DC 60
Programming in IMS DC
The additional IMS TM system service calls are:

o RCMD Retrieve Command

ROLB Roll Back
ROLL Roll
ROLS Roll Back to SETS
SETS Set Synchronization Point
SETU Set Synchronization Point (Unconditional)
SYNC Synchronization
XRST Extended Restart

IMS DC 61
Programming in IMS DC
Status Codes, Return Codes, and Reason Codes

To provide information on the results of each call, IMS TM places a 2-character status code in
the PCB after each IMS TM call your program issues. Your program should check the status
code after every IMS TM call it issues. If it does not, it might continue processing even
though the last call caused an error.

Exceptional Conditions

Some status codes do not mean that your call was successful or unsuccessful; they just give
you information about the results of the call. Your program uses this information to determine
what to do next. The meanings of these status codes depend on the call.

IMS DC 62
Programming in IMS DC
Error Routines

If, after checking for blanks and exceptional conditions in the status code, you find that
there has been an error, your program should branch to an error routine and print as much
information as possible about the error before terminating. Print the status code as well.
Information that is helpful in understanding the error include: which call was being executed
when the error occurred, what were the parameters of the IMS call, and what were the
contents of the PCB.

Two kinds of errors can occur in your program. First, programming errors are usually your
responsibility; they are the ones you can find and fix. These errors are caused by things
like an invalid parameter, an invalid call, or an I/O area that is too long. The other kind of
error is something you cannot usually fix; this is a system or I/O error.

IMS DC 63
Programming in IMS DC
How Your Program Processes Messages

To retrieve and send messages, an IMS TM application program issues calls to IMS TM.
When your program issues a call to retrieve a message, IMS TM places the input
message in the I/O area you name in the call. Before you issue a call to send a
message, you must build the output message in an I/O area in your program.

Message Types

An operator at a terminal can send four kinds of messages to IMS TM. The destination
of an IMS TM message identifies which kind of message is being sent:
* Another terminal.
* An application program.
* IMS TM.
* Message switch service.

IMS DC 64
Programming in IMS DC
What Input Messages Look Like

The input message that an application program receives from a terminal or

another program always has these fields: the length field, the ZZ field,
and the text field. Figure below shows the format of an input message.

For the
AIBTDLI
ASMTDLI
CBLTDLI |----|----|--------|----------------|
CEETDLI | LL | ZZ |TRANCODE| Text |
CTDLI and |----|----|--------|----------------|
PASTDLI | 2 | 2 | 8 | variable |
interfaces: |----|----|--------|----------------|

Input Message Format

IMS DC 65
Programming in IMS DC
What Output Messages Look Like

The format of the output message that you build to send back to a terminal or to
another program is similar to the format of the input message, but the fields
contain different information.

Output messages contain four fields: the length field, the Z1 field, the Z2 field, and
the text field. Figure shows the format of an output message.

For the
CBLTDLI |---- |---- |--- -|-------------------------|
CEETDLI | LL | Z1 | Z2 | Text |
CTDLI and |----|----|----|-------------------------|
PASTDLI interface | 2 | 1 | 1 | variable |
|----|----|----|-------------------------|
Output Message Format

IMS DC 66
Programming in IMS DC
What Happens When a Message is Processed

What a program does when it receives a message depends on the kind of message it
receives. A transaction code associates a request for information from a terminal with the
application program that can process and respond to that request. IMS TM schedules an
MPP when there are messages to be processed that contain the transaction code
Associated with that MPP.

| Physical Terminal |-----------> | Transaction Queue |

|
|
| Application Program |
|
| Physical Terminal | <-----------|Logical Terminal Queue|
(Transaction Message Flow)

IMS DC 67
Programming in IMS DC
Results of a Message: I/O PCB
After your program issues a call, IMS TM returns information about the results of the call
in the I/O PCB. To find out about the results of the call, your application program must
check the information that IMS TM returns to the I/O PCB.

When your application program retrieves a message, IMS TM returns the following
information about the message to the I/O PCB:

* The name of the terminal that sent the message.

* A 2-character status code describing the results of the call. If the program receives
a status code of QC after issuing a call to retrieve a message, no more messages are
available for the program to process.
* The current date, time, and sequence number for the message.
* The user ID of the person at the terminal or the transaction code for the program that sent
the message.

IMS DC 68
Programming in IMS DC
DB2 Considerations
For the most part, the message processing function of a dependent region that accesses
DB2 databases is similar to that of a dependent region that accesses only DL/I databases.

The method each program uses to retrieve and send messages and back out database
changes is the same.
* DL/I statements are coded differently from SQL statements.
* When an IMS TM application program receives control from IMS TM, IMS has
already acquired the resources the program is able to access.
* When an application issues a successful checkpoint call or a successful message GU
call, DB2 closes any cursors that the program ‘s IMS TM and DB2 work together to
keep data integrity in these ways:
* When your program reaches a commit point, IMS TM makes any changes that the
program has made to DL/I databases permanent,. DB2 then makes any changes that
the program has made to DB2 databases permanent.

IMS DC 69
Programming in IMS DC
Part 6. Understanding Application Program Elements

Defining Application Program Elements

Your application program must define formatting DL/I calls for language interfaces and
provides language calls information for assembler language, C language, COBOL, Pascal,
and PL/I.
- Formatting DL/I Calls for Language Interfaces
- Relationship of Calls to PCB Types
- Specifying the I/O PCB Mask
- Specifying the Alternate PCB Mask
- Specifying the I/O Areas
- Using the AIBTDLI Interface
- Specifying the Language-Specific Entry Point
- Using Language Environment
- Special DL/I Situations

IMS DC 70
Programming in IMS DC
Formatting DL/I Calls for Language Interfaces

When you use DL/I calls in a programming language supported by IMS (assembler
language, C language, COBOL, Pascal, or PL/I), you must call the DL/I language interface
to initiate the functions specified with the DL/I calls. IMS offers several interfaces for DL/I
calls:
* A language-independent interface for any programs that are Language Environment-
conforming (CEETDLI)
* Language-specific interfaces for all supported languages (xxxTDLI)
* A non-language-specific interface for all supported languages (AIBTDLI)

Because the exact syntax for calling the language interfaces varies among
the programming languages, there are different language-specific formats.

IMS DC 71
Programming in IMS DC
Application Programming for COBOL Format

| >>--CALL--|-'CBLTDLI'--USING | |-parmcount,-|
-|------------|--function-----|
|-,i/o pcb--|-| |
| <A> |
| | |-,alt pcb--|---------|-| | |
| | | <A> |-| ||
| | | <B> |-| |
<A>:
| |--,i/o area--|-----------------------------------||
| |-,mod name-------------------------|
| |-,token----------------------------||
| |-,options list--|----------------||
| |-,feedback area-| |
<B>:
| |--,destination name--||
|-,options list-|----------------|
| |-,feedback area-|

IMS DC 72
Programming in IMS DC
Application Programming for COBOL - Parameters :

parmcount
function
i/o pcb
alternate pcb
aib
i/o area
i/o area length
token
options list
feedback area
mod name
destination name

IMS DC 73
Programming in IMS DC
Example DL/I Call Formats

DL/I CEETDLI interface:

CALL 'CEETDLI' USING function, aib,i/o area.

DL/I AIBTDLI interface:

CALL 'AIBTDLI' USING function, aib,i/o area.

DL/I language-specific interface:

CALL 'CBLTDLI' USING function, i/o pcb, i/o area.

IMS DC 74
Programming in IMS DC
Specifying the I/O PCB Mask
After your program issues a call with the I/O Program Communications Block (I/O PCB), IMS
returns information about the results of the call to the I/O PCB. To determine the results of
the call, your program must check the information that IMS returns. Issuing a system service
call requires an I/O PCB. Because the I/O PCB resides outside your program, you must
define a mask of the PCB in your program to check the results of IMS calls. The mask must
contain the same fields, in the same order, as the I/O PCB.

Your program can then refer to the fields in the PCB through the PCB mask.
An I/O PCB contains nine fields :
1. Logical Terminal Name 5. Current Time
2. Reserved for IMS 6. Input Message Sequence Number
3. Status Code 7. Message Output Descriptor Name
4. Current Date 8. Userid 9. Group Name

IMS DC 75
Programming in IMS DC
Specifying the Alternate PCB Mask

An alternate PCB mask contains three fields. Table 1 shows these fields, the
field length, and in which environment the field applies.

Table 1. Alternate PCB Mask |

|---------------------|--------------|------|------|-------|------|------|
| | | | | | DB | TM |
| Descriptor | Byte Length | DB/DC| DBCTL| DCCTL | Batch| Batch|
|---------------------|--------------|------|------|-------|------|------|
| Logical terminal | | | | | | |
| name (1) | 8 bytes | X | | X | | |
|---------------------|--------------|------|------|-------|------|------|
| Reserved for IMS | | | | | | |
| (2) | 2 bytes | X | | X | | |
|---------------------|--------------|------|------|-------|------|------|
| Status code (3) | 2 bytes | X | | X | | |
|---------------------|--------------|------|------|-------|------|------|

IMS DC 76
Programming in IMS DC
Specifying the AIB Mask

The AIB is used by your program to communicate with IMS, when your application does not
have a PCB address or the call function does not use a PCB.The AIB mask enables your
program to interpret the control block defined.
1. AIB Identifier (AIBID) 10. Reason Code (AIBREASN)
2. DFSAIB Allocated Length (AIBLEN) 11. Reserved
3. Sub function Code (AIBSFUNC) 12. Resource Address AIBRSA1
4. Resource Name (AIBRSNM1) 13. Reserved
5. Reserved
6. Maximum Output Area Length (AIBOALEN)
7. Used Output Area Length (AIBOAUSE)
8. Reserved
9. Return code (AIBRETRN)

IMS DC 77
Programming in IMS DC
Specifying the I/O Areas

Use an I/O area to pass segments between the application program & IMS TM. What the
I/O area contains depends on the type of call issued :

• When your program retrieves a segment, IMS TM places the segment your program
requested in the I/O area.
• When your program adds a new segment, your program first builds the new segment
in the I/O area.
• Before modifying a segment, your program must first retrieve the segment. When
your program retrieves the segment, IMS TM places the segment in an I/O area.
• The I/O area for transaction management calls must be large enough to hold the
largest message segment your program retrieves from or sends to IMS TM.

IMS DC 78
Programming in IMS DC
Specifying the Language-Specific Entry Point in COBOL
IMS gives control to an application program through an entry point. Your entry point must
refer to the PCBs in the order in which they have been defined in the PSB.

The procedure statement must refer to the I/O PCB first, then to any alternate PCB it
uses, and last to the DB PCBs it uses.

The alternate PCBs and DB PCBs must be listed in the order in which they are defined in
the PSB. Procedure division using the PCB-AME-1 Ö,...,PCB-NAME-NÜ If only IMS is
used, the PCBs can be referenced with the program entry statement.

The entry statement must appear as the first executable statement in the procedure
division. When IMS passes control to your program, it passes the addresses of each of
the PCBs your program uses. The parameters in this statement are the names of the
PCBs.
ENTRY 'anyname' USING pcb-name-1 ...,pcb-name-2....... GOBACK.

IMS DC 79
Programming in IMS DC
Format of a PCB List
PSBs have the following format:
IOPCB
Alternate PCB1 ... Alternate PCB2
DB PCB1 ... DB PCB2
GSAM PCB1 ... GSAM PCB2
Each PSB must contain at least one PCB. An I/O PCB or alternate PCB is required for
transaction management calls, and an I/O PCB is required for most system service calls.
DB PCBs for DL/I databases are used only with the IMS Database Manager, but can be
present even though your program is running under DCCTL. (A DB PCB can be a full-
function PCB, a DEDB PCB, or an MSDB PCB.) GSAM PCBs can be used with DCCTL.

Alternate PCBs are always included in the list of PCBs supplied to the program by IMS
TM. The I/O PCB is always present in the PCB list regardless of the CMPAT options
specified in PSBGEN.

IMS DC 80
Programming in IMS DC
Writing DL/I Calls for Transaction Management
Transaction management calls must use either i/o pcb or aib parameters. The DL/I calls
used for database management are described in IMS/ESA Application Programming:
DCCTL users can issue calls using GSAM database PCBs.

Each call description contains:

• A syntax diagram
• A definition for each parameter that can be used in the call
• Details on how to use the call in your application program
• Restrictions on the use of the call
Note: Each parameter is described as an input or output parameter.
"Input" refers to input to IMS from the application program.
"Output" refers to output from IMS to the application program.

IMS DC 81
Programming in IMS DC
AUTH Call

An Authorization (AUTH) call verifies each user's security authorization.

It determines whether a user is authorized to access the resources specified on the
AUTH call.
Format
|------------------------------------------------------------------------|
| |
| >>--AUTH--|-i/o pcb-|--i/o area------------------------------------->< |
| |-aib-----| |
| |
|------------------------------------------------------------------------|

|-----------|-----------|------------|-----------|-----------|-----------|
| Call Name | DB/DC | DBCTL | DCCTL | DB Batch | TM Batch |
|-----------|-----------|------------|-----------|-----------|-----------|
| AUTH | X | | X | | |
|-----------|-----------|------------|-----------|-----------|-----------|

IMS DC 82
Programming in IMS DC
CHNG Call

The Change (CHNG) call sets the destination of a modifiable alternate PCB to the logical
terminal, LU 6.2 descriptor, or transaction code that you specify. You can also use the
CHNG call with the Spool application Program Interface (Spool API) to specify print data
set characteristics.
|------------------------------------------------------------------------|
| |
| >>--CHNG--|-alternate pcb-|--destination name------------------------> |
| |-aib-----------| |
| |
| >--|---------------------------------|------------------------------>< |
| |-options list--|---------------|-| |
| |-feedback area-| |
| |
|------------------------------------------------------------------------|
|-----------|-----------|------------|-----------|-----------|-----------|
| Call Name | DB/DC | DBCTL | DCCTL | DB Batch | TM Batch |
|-----------|-----------|------------|-----------|-----------|-----------|
| CHNG | X | | X | | |
|-----------|-----------|------------|-----------|-----------|-----------|

IMS DC 83
Programming in IMS DC
GN Call

If an input message contains more than one segment, a Get Unique (GU) call retrieves
the first segment of the message and Get Next (GN) calls retrieve the remaining
segments

Format |------------------------------------------------------------------------|
| |
| >>--GN--|-i/o pcb-|--i/o area--------------------------------------->< |
| |-aib-----| |
| |
|------------------------------------------------------------------------|

|-----------|-----------|------------|-----------|-----------|-----------|
| Call Name | DB/DC | DBCTL | DCCTL | DB Batch | TM Batch |
|-----------|-----------|------------|-----------|-----------|-----------|
| GN | X | | X | | |
|-----------|-----------|------------|-----------|-----------|-----------|

IMS DC 84
Programming in IMS DC
GU Call

The Get Unique (GU) call retrieves the first segment of a message

Format

|------------------------------------------------------------------------|
| |
| >>--GU--|-i/o pcb-|--i/o area--------------------------------------->< |
| |-aib-----| |
| |
|------------------------------------------------------------------------|

|-----------|-----------|------------|-----------|-----------|-----------|
| Call Name | DB/DC | DBCTL | DCCTL | DB Batch | TM Batch |
|-----------|-----------|------------|-----------|-----------|-----------|
| GU | X | | X | | |
|-----------|-----------|------------|-----------|-----------|-----------|

IMS DC 85
Programming in IMS DC
ISRT Call

The Insert (ISRT) call sends one message segment to the destination that you specify in
the call. The destination is represented by the I/O PCB, alternate PCB, or AIB you specify
in the call parameters. For Spool API functions, the ISRT call is also used to write data to
the JES Spool.
Format
|------------------------------------------------------------------------|
| |
| >>--ISRT--|-i/o pcb-------|--i/o area--|----------|----------------->< |
| |-alternate pcb-| |-mod name-| |
| |-aib-----------| |
| |
|------------------------------------------------------------------------|
|-----------|-----------|------------|-----------|-----------|-----------|
| Call Name | DB/DC | DBCTL | DCCTL | DB Batch | TM Batch |
|-----------|-----------|------------|-----------|-----------|-----------|
| ISRT | X | | X | | |
|-----------|-----------|------------|-----------|-----------|-----------|

IMS DC 86
Programming in IMS DC
PURG Call

The Purge (PURG) call allows your application program to send one or more output
message segments (specified with the ISRT call) to the specified destination before the
application program retrieves the next input message or issues a commit point. For Spool
API services, the PURG call can also be used to release a print data set for immediate
printing.
Format
|------------------------------------------------------------------------|
| |
| >>--PURG--|-i/o pcb-------|--|------------------------|------------->< |
| |-alternate pcb-| |-i/o area--|----------|-| |
| |-aib-----------| |-mod name-| |
| |
|------------------------------------------------------------------------|
|-----------|-----------|------------|-----------|-----------|-----------|
| Call Name | DB/DC | DBCTL | DCCTL | DB Batch | TM Batch |
|-----------|-----------|------------|-----------|-----------|-----------|
| PURG | X | | X | | |
|-----------|-----------|------------|-----------|-----------|-----------|

IMS DC 87
Programming in IMS DC
More about Message Processing

1. Sending Messages to Other Terminals and Programs

2. Communicating with Other IMS TM Systems Using MSC IMS Conversations.

3. Backing Out to a Prior Commit Point: The ROLL, ROLB, and ROLS Calls

4. Writing a Message-Driven Program

IMS DC 88
Programming in IMS DC
Sending Messages to Other Terminals and Programs

• If you want to send output messages to one alternate destination, define the alternate PCB
for that destination.
• If you want to send output messages to more than one alternate destination, and you want
to be able to change the destination of the alternate PCB, define the alternate PCB as
modifiable during PSB generation. Then, before you issue the ISRT call, you issue a
change call, or CHNG, to set the destination of the alternate modifiable PCB for the
destination program or terminal.
• The express alternate PCB is a special kind of alternate PCB that is defined during PSB
generation, by specifying EXPRESS=YES.
• A PSBGEN can also specify an alternate PCB as an alternate response PCB defined during PSB
generation.
• If you want to send a message to an LU 6.2 device, you can specify the LU 6.2 descriptor name
that is associated with that device.

IMS DC 89
Programming in IMS DC
Sending Messages to Other Terminals

To reply to a different terminal, also use the ISRT call, but use an alternate PCB instead of
the I/O PCB. Just as the I/O PCB represents the terminal that sent the message, an
alternate PCB represents the terminal to which you want to send the message.

Sending Messages to One Alternate Terminal

If you are going to send messages to only one alternate terminal, you can define the
alternate PCB for that terminal during PSB generation. When you define an alternate PCB
for a particular destination, you cannot change that destination during program execution.
Each time you issue an ISRT call that references that PCB, the message goes to the logical
terminal whose name was specified for the alternate PCB.

IMS DC 90
Programming in IMS DC
Sending Messages to Other Application Programs

• Create an I/O area large enough to hold the largest segment that you are sending.
• Use an alternate PCB, not the I/O PCB, to send the message.
• Issue a CHNG call before the ISRT call to place the program's transaction code in the
first field of the alternate PCB. If the alternate PCB was set to this transaction code in
the PSBGEN, then you just issue the ISRT call.
• IMS TM must know the transaction code. Define it at system definition.
• A nonconversational program can do a program-to-program message switch to another
nonconversational program, but not to a conversational program.
• A conversational program can do a program-to-program message switch to either
another conversational program or a nonconversational program.

IMS DC 91
Programming in IMS DC

Receiving Messages from Other IMS TM Systems

When an application program retrieves an input message, the program can determine
whether the input message is from a terminal or program in its IMS TM system, or from a
terminal or program in another IMS TM system.

There might be situations in which the application program's processing is changed if the
input message is from a remote terminal, rather than from a local terminal.
|---------| | MPP1 | |----------|
| MASTER | | | | MASTER |
|----|----| | | |-----|----|
| |----|---| |
| | |
| | |
|------|----------------|-------| LINK1 |-----------|-----------|
| |---------->| |
| SYSTEM A |<----------| SYSTEM B |
| | LINK2 | |
|-------------------------------| |-----------------------|
MSC Example

IMS DC 92
Programming in IMS DC

Sending Messages to Alternate Destinations in Other IMS TM Systems

To send an output message to an alternate terminal in another IMS TM system, your
system must have an MSC link with the system to which you want to send the message.
To do this, issue a CHNG call against an alternate PCB and supply the name of the MSC
link that connects the two IMS TM systems.
For the
AIBTDLI,
ASMTDLI,

CBLTDLI, |----|----|-----------|---|--------------|
CEETDLI, | LL | ZZ | DESTNAME | b | TEXT |
CTDLI and |----|----|-----------|---|--------------|
PASTDLI interfaces: | 2 | 2 | 1 - 8 | 1 | variable |
|----|----|-----------|---|--------------|

Directed Routing Output Message Format

IMS DC 93
Programming in IMS DC
IMS Conversations

• A conversational program is an MPP that processes transactions made up of several

steps. It does not process the entire transaction at once.
• A conversational program divides processing into a connected series of terminal-to-
program-to-terminal interactions. You use Conversational processing when one
transaction contains several parts.
• A nonconversational program receives a message from a terminal, processes the
request, and sends a message back to the terminal.
• A conversational program receives a message from a terminal, and replies to the
terminal, but saves the data from the transaction in a scratchpad area, or SPA. Then,
when the person at the terminal enters more data, the program has the data it saved from
the last message in the SPA, so it can continue processing the request without the person
at the terminal having to enter the data again.

IMS DC 94
Programming in IMS DC
A Conversational Example

For this example, suppose that you want to find out if someone can qualify for a car loan.
This inquiry contains two parts.

First, you give the name and address of the person requesting the loan and the number of
years for which the person wants the loan.

After you give this information, IMS TM asks you for the information on the car: model,
year, and cost.

You enter this information, IMS TM invokes the program that processes this information,
and the program tells you whether the loan can be granted.

IMS DC 95
Programming in IMS DC
If you use MFS, this process involves six steps:

1. Enter the format command (/FORMAT) and the MOD name.

2. Enter the customer's name and address, and the length of the loan.
3. IMS TM reads the transaction code, CARLOAN, and invokes the program that handles
that transaction code.
4. Next, the MPP processes the input data from the terminal and does two things. It moves
the data that it will need to save to the SPA, and it builds the output message for the
terminal in the I/O area.
5. IMS TM again uses the DIF and MID associated with the transaction code, and sends the
information back to the MPP..
6. IMS TM returns the updated SPA to the MPP when the MPP issues a GU, then returns the
message to the MPP when the MPP issues a GN.

IMS DC 96
Programming in IMS DC
Conversational Structure

1. Retrieve the SPA and the message using GU and GN calls.

2. 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.
3. 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.
4. Process the message, including any necessary database access.
5. Send the output message to the terminal by using another ISRT call against the I/O PCB.
This step can follow step 6.
6. Store the data that your program will need to continue processing in the SPA using an ISRT
call to the I/O PCB. (This step can precede step 7.)
7. To end the conversation, move blanks to the area of the SPA.

IMS DC 97
Programming in IMS DC
Replying to the Terminal

For a conversation to continue, the originating terminal must receive a response to each of
its input messages. The person at the terminal cannot enter any more data to be processed
(except IMS TM commands) until the response has been received at the terminal.

To continue the conversation, the program must respond to the originating terminal by
issuing the required ISRT calls to send the output message to the terminal. To send a
message to the originating terminal, the ISRT calls must reference either the I/O PCB or
an alternate response PCB.

Use an alternate response PCB in a conversation when the terminal you are responding
to has two components for example, a printer and a punch and you want to send the output
message to a component that is separate from the component that sent the input message.

IMS DC 98
Programming in IMS DC

If the program references an alternate response PCB, the PCB must be defined for the
same physical terminal as the logical terminal that sent the input message.

The program can send only one output message to the terminal for each input message.

Output messages can contain multiple segments, but the program cannot use the PURG
call to send multiple output messages.

If a conversational program issues a PURG call, IMS TM returns an AZ status code to the
application program and does not process the call.

IMS DC 99
Programming in IMS DC
Using ROLB, ROLL, and ROLS in Conversations

Issuing a ROLB or ROLS in a conversational program causes IMS TM to back out the
messages that the application program has sent.This means that, if the program issues a
ROLB or ROLS and then reaches a commit point without sending the required response
to the originating terminal, IMS TM terminates the conversation and sends the message

DFS2171I NO RESPONSE CONVERSATION TERMINATED. to the originating

terminal.

If you issue ROLL during a conversation, IMS TM backs out the updates and cancels
output messages, but it also terminates the conversation.

IMS DC 100
Programming in IMS DC
Passing the Conversation to Another Conversational Program

A conversational program can pass the conversation to another conversational program in

two ways:
• A deferred switch.
The program can respond to the terminal but cause the next input from the terminal to
go to another conversational program by:
Issuing an ISRT call against the I/O PCB to respond to the terminal
Placing the transaction code for the new conversational program in SPA
Issuing an ISRT call referencing the I/O PCB and the SPA to return the SPA to
IMS TM
• An immediate switch.
The program can pass the conversation directly to another conversational program by
issuing an ISRT call against the alternate PCB that has its destination set to the other
conversational program.

IMS DC 101
Programming in IMS DC
Message Switching in APPC Conversations

With the system service DFSAPPC, you can transfer messages between separate LU 6.2
devices and between an LU 6.2 device and another terminal supported by IMS TM.

Message delivery with DFSAPPC is asynchronous, so messages are held on the IMS TM
message queue until they can be delivered.

To send a message with DFSAPPC, specify the logical terminal name of an IMS TM
terminal or the Transaction Program (TP) name of an LU 6.2 device.

IMS DC 102
Programming in IMS DC
Processing Conversations with APPC

APPC/IMS has three different types of application programs:

• Standard -- No explicit use of CPI Communications facilities.

• Modified -- Uses the I/O PCB to communicate with the original input terminal. Uses CPI
Communications calls to allocate new conversations and to send and receive data.

• CPI Communications driven -- Uses CPI Communications calls to receive the

incoming message and to send a reply on the same conversation. Uses the DL/I APSB
call to allocate a PSB to access IMS databases and alternate PCBs.

IMS DC 103
Programming in IMS DC
Standard IMS Application Programs

Standard IMS application programs use the existing IMS call interface.

Application programs that use the IMS standard API can take advantage of the LU 6.2
protocols. Standard IMS application programs use a DL/I GU call to get the incoming
transaction. These standard IMS application programs also use DL/I ISRT calls to generate
output messages to the same or different terminals, LU 6.2 or not. (3) Note that the identical
program can work correctly for both LU 6.2 and non-LU 6.2 terminal types. IMS generates
the appropriate calls to MVS/APPC services.

A non-message-driven BMP is considered a standard IMS application program when it does

not use the explicit API.

IMS DC 104
Programming in IMS DC
Modified IMS Application Programs

Modified IMS application programs use a DL/I GU call to get the incoming transaction.
These modified IMS application programs also use DL/I ISRT calls to generate output
messages to the same or different terminals, LU 6.2 or not. Unlike standard IMS application
programs, modified IMS application programs use CPI communications calls to allocate new
conversations, and send and receive data.
GU IOPCB
ALLOCATE
SEND
RECEIVE
DEALLOCATE
ISRT IOPCB
Figure 1. General Format of a Modified DL/I Application Program

IMS DC 105
Programming in IMS DC
Coding a Conversational Program

Before coding a conversational program, obtain the following:

• The transaction code to use for a program to which you pass control
• The data that you should save in the SPA
• The maximum length of that data

An SPA contains 4 fields:

• The 2-byte length field.
• The 4-byte field that is reserved for IMS TM.
• The 8-byte transaction code.
• The work area where you store the conversation data. The length of this field is
defined at system definition.

IMS DC 106
Programming in IMS DC
Backing Out to a Prior Commit Point: The ROLL, ROLB, and ROLS Calls
When a program determines that some of its processing is invalid, you can use the following
calls to remove the effects of its incorrect processing:

Roll Back calls ROLL, ROLS using a database PCB, ROLS with no I/O area or token, and
ROLB. When you issue one of these calls, IMS
* Backs out the database updates that the program has made since the program's most
recent commit point.
* Cancels the non-express output messages that the program has created since the
program's most recent commit point.
The main difference among these calls is that ROLB returns control to the program after
backing out updates and canceling output messages, ROLS does not return control to the
application program, and ROLL terminates the program with a user abend code of 0778.
ROLB can return to the program the first message segment since the most recent commit
point, but ROLL and ROLS cannot.

IMS DC 107
Programming in IMS DC
Backing Out to an Intermediate Backout Point: SETS/SETU and ROLS
Figure below SETS and ROLS Calls Working Together
---|--- Program Starts
|
|
| SETS Token=n
|
| GHU
| REPL
| ISRT MSG1-Segment 1 to I/O PCB
|
|-------|--> SETS Token=B
| |
Backs out | | GHU
program to | | DLET
SETS Token=B | | ISRT MSG1-Segment 2 to I/O PCB
| |
|-------|--- ROLS Token=B
|
|
|
v

IMS DC 108
Programming in IMS DC
Writing a Message-Driven Program
A message-driven program is similar to an MPP: it retrieves messages and processes them,
and it can read and update MSDBs, DEDBs, and full-function databases.

Message-driven programs can send messages to the following destinations:

* The logical terminal that sent the input message, by issuing an ISRT call referencing the
I/O PCB
* A different component of the physical terminal that sent the input message, by issuing
an ISRT call referencing an alternate response PCB
* A different physical terminal from the one that sent the input message, by issuing an
ISRT call referencing an alternate PCB.
The transactions are in the response mode. This means that you must respond before the
next message can be sent. You cannot use SPAs because a message-driven program
cannot be a conversational program.

IMS DC 109
Programming in IMS DC
Coding DC Calls and Data Areas Your Input

The way you code DC calls and data areas depends on the application programming
language you use. Information you need about your program's design:
• The names of the logical terminals that your program will communicate
• The transaction codes, if any, for the application program's MPP skeleton to which
your program will send messages
• The DC call structure for your program
• The destination for each output message that you send
• The names of any alternate destinations to which your program sends messages

IMS DC 110
Programming in IMS DC
Information you need about input messages:

* The size and layout of the input messages your program will receive
* The format in which your program will receive the input messages
* The editing routine your program uses
* The range of valid data in input messages
* The type of data that input messages will contain
* The maximum and minimum length of input message segments
* The number of segments in a message

IMS DC 111
Programming in IMS DC
Skeleton MPP

1. The program retrieves an input message segment from a terminal by issuing a GU call
to the I/O PCB. This retrieves the first segment of the message. Unless this message
contains only one segment, your program issues GN calls to the I/O PCB to retrieve the
remaining segments of the message. IMS places the input message segment in the
I/O area that you specify in the call. In the examples below, this is MSG-SEG-IO-AREA.

2. The program retrieves a segment from the database by issuing a GU call to the DB
PCB. This call specifies an SSA, SSA-NAME, to qualify the request. IMS places the
database segment in the I/O area specified in the call. In this case, the I/O area is
called DB-SEG-IO-AREA.

IMS DC 112
Programming in IMS DC

3. The program sends an output message to an alternate destination by issuing an ISRT

call to the alternate PCB. Before issuing the ISRT call, the program has to build the
output message segment in an I/O area, then the program specifies the I/O area in the
ISRT call. The I/O area for this call is ALT-MSG-SEG-OUT.

IMS DC 113
Programming in IMS DC
Coding Your Program in COBOL
Figure 1 COBOL MPP Skeleton
| | ENVIRONMENT DIVISION.
| | DATA DIVISION.
| | WORKING-STORAGE SECTION.
| 1 | 77 GU-CALL PICTURE XXXX VALUE 'GU '.
|
| | 77 ISRT-CALL PICTURE XXXX VALUE 'ISRT'.
| | 77 CT PICTURE S9(5) COMPUTATIONAL VALUE +4. |
| | 01 SSA-NAME. |
| 2 | 01 MSG-SEG-IO-AREA.
| | 01 DB-SEG-IO-AREA.
| | 01 ALT-MSG-SEG-OUT.

IMS DC 114
Programming in IMS DC
| | LINKAGE SECTION. |
| 3 | 01 IO-PCB. |
| | 01 ALT-PCB. |
| | 01 DB-PCB. |
| | PROCEDURE DIVISION. |
| 4 | ENTRY 'DLITCBL' USING IO-PCB, ALT-PCB, DB-PCB. |
| | .
|

IMS DC 115
Programming in IMS DC
| 5 | CALL 'CBLTDLI' USING GU-CALL, IO-PCB,
| | MSG-SEG-IO-AREA.
|
| 6 | CALL 'CBLTDLI' USING GU-CALL, DB-PCB,
| | DB-SEG-IO-AREA, SSA-NAME.
| | .
| 7 | CALL 'CBLTDLI' USING ISRT-CALL, ALT-PCB, ALT-MSG-SEG-OUT.
| 8 | GOBACK. |
| 9 | COBOL LANGUAGE INTERFACE |

IMS DC 116
 Thanks

IMS DC 117