TCS

CICS Handbook
Study Material
Juhi Gaur

CICS Handbook
Table of Contents
TABLE OF CONTENTS ..............................................................................................................................2
INTRODUCTION .........................................................................................................................................4
BMS (BASIC MAPPING SUPPORT).......................................................................................................11
PRIMARY FUNCTIONS ............................................................................................................................... 11
MAPSET AND MAP .................................................................................................................................... 13
MAP TYPES .............................................................................................................................................. 13
Map Definition Macros....................................................................................................................... 13
BMS Macro Rules ............................................................................................................................... 14
DFHMSD Macro ................................................................................................................................ 15
DFHMDI Macro ................................................................................................................................. 17
DFHMDF Macro ................................................................................................................................ 17
MDTs and their manipulation ........................................................................................................... 18
MDT Manipulation FRSET.............................................................................................................. 19
Ending a Mapset Definition ................................................................................................................ 20
Symbolic Map Contents ...................................................................................................................... 20
Code for Sample Layout...................................................................................................................... 21
Symbolic Map for Sample Layout ....................................................................................................... 22
I/O Operations .................................................................................................................................... 24
AIDKEY .............................................................................................................................................. 27
APPLICATION PROGRAMMING..........................................................................................................28
CICS COMMAND FORMAT ........................................................................................................................ 28
Argument Values................................................................................................................................. 28
STRUCTURE OF CICS APPLICATION PROGRAM.......................................................................................... 30
EXEC INTERFACE BLOCK (EIB) .............................................................................................................. 31
STORAGE TYPES ....................................................................................................................................... 31
CICS PROGRAM CONTROL ..................................................................................................................33
PROGRAM TO PROGRAM TRANSITION ....................................................................................................... 33
LINK Command .................................................................................................................................. 33
XCTL Command ................................................................................................................................. 35
RETURN Command ............................................................................................................................ 36
Static Call ........................................................................................................................................... 36
Dynamic Call ...................................................................................................................................... 36
Conversational modes......................................................................................................................... 37
Error conditions in Program Control Commands .............................................................................. 37
INTERVAL AND TASK CONTROL .......................................................................................................38
INTERVAL CONTROL................................................................................................................................. 38
Interval control commands ................................................................................................................. 38
Starting an Asynchronous transaction using START command.......................................................... 39
Retrieving data in a STARTed Transaction RETRIEVE Command ................................................. 40
CANCEL Command ............................................................................................................................ 40
TASK CONTROL ........................................................................................................................................ 41
Task Control Command ...................................................................................................................... 41
SUSPEND Command.......................................................................................................................... 41
ENQ and DEQ Commands ................................................................................................................. 41
EXCEPTION AND ERROR HANDLING ...............................................................................................42
EXCEPTION HANDLING ............................................................................................................................. 42
HANDLE CONDITION Command ..................................................................................................... 42

Reference Guide

Page 2

CICS Handbook
IGNORE CONDITION Command ...................................................................................................... 43
NOHANDLE Option ........................................................................................................................... 43
RESP Option ....................................................................................................................................... 44
PUSH and POP Commands................................................................................................................ 44
System Default action ......................................................................................................................... 45
HANDLE ABEND Command.............................................................................................................. 45
ABEND Command .............................................................................................................................. 46
CICS DATA ACCESS .............................................................................................................................47
FILE HANDLING ........................................................................................................................................ 47
File Access Methods ........................................................................................................................... 47
ESDS Entry Sequenced Data Set...................................................................................................... 47
KSDS - Key Sequenced Data Set......................................................................................................... 48
RRDS Relative Record Data Set ...................................................................................................... 48
Record Identification (RIDFLD)......................................................................................................... 48
VSAM File Access ............................................................................................................................... 49
READ Command................................................................................................................................. 49
WRITE Command ............................................................................................................................... 51
File Update ......................................................................................................................................... 51
Delete From File................................................................................................................................. 52
Browse Option .................................................................................................................................... 52
File Handling Exception Conditions................................................................................................ 54
File Handling Program Organization .............................................................................................. 55
CICS Database Access..................................................................................................................... 55
CICS - DB2 Program Preparation ..................................................................................................... 56
Files - Database Tables ...................................................................................................................... 57
CICS QUEUE HANDLING .......................................................................................................................58
TEMPORARY STORAGE QUEUE (TSQ) ...................................................................................................... 58
Temporary Storage - Output ............................................................................................................... 59
Temporary Storage Input ................................................................................................................. 59
Temporary Storage Deletion............................................................................................................ 60
TSQ Exceptional Conditions............................................................................................................ 60
TRANSIENT DATA QUEUE (TDQ) ............................................................................................................. 61
TDQ Intrapartition........................................................................................................................... 62
TDQ Intrapartition DCT Entry ..................................................................................................... 62
ATI Automatic Task Initiation.......................................................................................................... 63
TDQ Extrapartition.......................................................................................................................... 63
TDQ Extrapartition - DCT Entry..................................................................................................... 64
TRANSIENT STORAGE COMMANDS ........................................................................................................... 64
Transient Storage Output................................................................................................................. 64
Transient Storage Output................................................................................................................. 65
Transient Storage Deletion .............................................................................................................. 65
Exception Conditions:......................................................................................................................... 66
CICS IBM SUPPLIED TRANSACTIONS ............................................................................................66

Reference Guide

Page 3

CICS Handbook

Introduction
CICS is a powerful teleprocessing system designed to control information in an online
environment. It provides the environment necessary for development and execution of
on-line applications thereby freeing the application developer from the dependencies of
the Operating System, Hardware, etc.
The primary objective of CICS is to provide the control and service functions of the
database/data communication (DB/DC) system as a package.
Note:
Batch System It has a system environment where jobs run one by one in a
conventional way.
Online System It has a system environment where many transactions run
concurrently.
CICS is available as following:
CICS/ESA on IBM Mainframe running MVS
CICS/400 on AS/400 running OS/400
CICS/6000 on RISC/6000 systems running AIX
CICS/OS2 on PS/2 systems running OS/2
Features of CICS:
Multi-tasking - Ability to control many tasks running concurrently in an address
space. CICS provides for concurrent execution of multiple tasks, including tasks
of the same type, like Order Entry. CICS has its own task management
capabilities for execution of tasks within a single region partition and does not use
the multitasking feature of the O/S.
Multi-threading - Ability to use only one copy of the program when more than
one task of the same type is active thereby minimizing main storage.
Re-entrant - Ability to continue processing after an interruption. Since CICS
performs task management and provides a separate copy of the working storage
for each task currently active, CICS programs are also known as quasi re-entrant
programs.
Priority processing - Ability to execute tasks based on the priority set by the user
for a transaction(program), terminal, terminal operator, etc.
Services provided by CICS:
Data Communication Services
- Free application programs from handling terminal hardware
- Interface to telecommunication methods such as VTAM, TCP/IP
- Provide Communication capabilities between CICS regions and non-CICS
regions across hardware.
Data Management/Data Handling Services
Reference Guide

Page 4

CICS Handbook
-

Interface for handling files such as VSAM, BDAM etc.

Interface for databases such as DB2, DL/I etc.
Maintain Data Integrity through
- Control of data Updates
- Protection of data due to abnormal termination of application or
system faults like CICS or O/S crash.
Application Program Services
- Interface with programming languages such as COBOL, C, PL/I
- Program translation
- Command Interpretation
System Services
- Interface with the Operating System for
- program load and release
- memory management
- scheduling of tasks based on priority, etc
Monitoring Services
- Event Monitoring, Statistics collection for system tuning, etc.

Transaction:
A unit of work that is done as an atomic operation - that is, the operation succeeds or fails
as a whole.
In CICS, a transaction is identified by a 4 character ID, for e.g. TXN1 and is initiated,
usually, by typing the transaction id in the top left hand corner of a screen.
Task:
An instance of the execution of a particular transaction type is a task. That is, one
execution of a transaction, with a particular set of data, usually on behalf of a particular
user at a particular terminal.
Logical Unit of Work (LUW):
A LUW is a collection of updating activity that is treated as a single unit.
In other words, the period between the start of a particular set of changes and the point at
which they are complete is called a logical unit of work (LUW). The LUW is a
fundamental concept of CICS recovery.
From the application designer's point of view, an LUW is a sequence of actions that
needs to be complete before any of the individual actions can be regarded as complete as
shown below.
- - - - - - - - - - - - - - - LUW - - - - - - - - - - - - - - Task A |----------------|---------------------|---------------------------
SOT
Update
Delete
EOT
File - 1
2 records
(SP)

Reference Guide

Page 5

CICS Handbook
Synchronization Point:
Synchronization point is a point during processing activities of a program where all
resource updates are complete and the resources are in good condition. The beginning of
a task and normal completion of a task are considered to be syncpoints. Between the
beginning and end of a task any number of syncpoints might be declared, they are called
intermediate syncpoints.
The end of a logical unit of work is indicated to CICS by a synchronization point
(abbreviated to syncpoint).
A syncpoint arises in the following ways:
Implicitly at the end of a transaction, by an EXEC CICS RETURN command at
the highest logical level.
Explicitly by EXEC CICS SYNCPOINT commands issued (to commit the
changes made to the resources such as files, database tables etc.) by the
application programmer at appropriate points in the transaction.
Every time an EXEC CICS SYNCPOINT command is issued,
the existing LUW is completed and
A new LUW is started.
A LUW is the activity which a task does between two syncpoints.
A task is called In-flight task until its LUW completes.
Normally each LUW corresponds to a single task execution. But, this may not be true
always. Consider a process that is updating a master file from a transaction file. If the
program abends after processing 100 records, CICS will back out all the changes since
the LUW is the end of the task. Hence to limit the scope of the LUW, we use
SYNCPOINTs.
If a failure occurs within a LUW, CICS backs out all changes to recoverable resources, to
the beginning of the LUW.
E.g.:
1) EXEC CICS SYNCPOINT
END-EXEC.
2) EXEC CICS SYNCPOINT
ROLLBACK
END-EXEC.
SYNCPOINT command is used to issue intermediate syncpoints. When a syncpoint
command is issued, all the updates made by the task so far are committed and the
resources maintained by the dynamic log are released. The SYNCPOINT command also
releases the locks from the resources.

Reference Guide

Page 6

CICS Handbook
SYNCPOINT with ROLLBACK option is used to recover the recoverable resources up
to the last syncpoint.
CICS automatically issues a SYNCPOINT at the end of each task.

Conversation:
In a typical online system, data is entered by the terminal user/operator. By pressing a
terminal key, a transaction is triggered. Subsequent to the processing, the results are sent
back to the terminal based on which the user responds by keying in additional data. This
results in a sort of conversation between the terminal user and the transaction.
Transactions, and thus programs, can be classified as:
Conversational Program
Pseudo conversational Program
Pseudo conversational programs are more efficient than Conversational programs but
involve a bit of programming.

TASK 1

TASK 2

TXNA

TXNA

working
storage for
task 1

working
storage for
task 2

TASK 1 started at terminal1 by user1

executes TXNA.
TASK 2 started at terminal2 by user2
executes the same TXNA.
These two tasks use the same load
module associated with TXNA.
However, the working storage for
each task is different.

The difference between a task and transaction is shown above. Visualize a Library
Information System. To add a new book, a record is to be added into the book-master
database. Normally a transaction will be used for performing this operation. It is possible
that several users may work at several terminals at the same time and add different book
records to the master. All these users will use the same transaction, but CICS initiates a
different task for each one of them.
Each task will acquire a working storage section; however all the tasks will use the same
load module. This feature is called multi-threading. Since several tasks can be running at
the same time, CICS is a multi-tasking system.

Reference Guide

Page 7

CICS Handbook
Once a task is initiated, CICS will keep processing it till an I/O or external input is
required. It then suspends that task and releases its resources. When the I/O is complete,
CICS will then resume the task. This is called Quasi-reentrancy.

Conversational Program
Program(transaction) remains idle when waiting for user response
Program, data areas, control blocks remain in main storage resulting in
high virtual storage utilization
In a conversational program, after processing the data, the same will be
sent to the terminal and the program will be in a wait state for the
terminal user to complete further data entry
Only when the terminal user completes the data entry and/or presses the
Enter/PA keys, will the transaction re-start
Till such time, the resources allocated to the task will have to be retained
by CICS. A few such tasks will result in CICS going short of main storage
allocated to it, thus affecting overall system performance
Pseudo-conversational Program
Program is in storage only when processing data, otherwise storage
released for other transactions/tasks
EXEC CICS SEND
SEND MAP(map_name) MAPSET(mapset_name)
FROM(data_area)
END_EXEC.
IF CONVERSATION-TYPE = CONVERSATIONAL THEN
EXEC CICS RECEIVE
MAP(map_name) MAPSET(mapset_name)
INTO(data_area)
END_EXEC.
END-IF
EXEC CICS RETURN
TRANSID(txn_name)
END_EXEC.
The above three CICS commands are defined here to illustrate the concept of
Conversational & Pseudo conversational programs.

EXEC CICS SEND MAP sends a stream of data as defined in the map map_name
to the terminal screen from the data_area.

Reference Guide

Page 8

CICS Handbook

EXEC CICS RECEIVE MAP receives a stream of data from the terminal screen
into the data_area as defined by the map map_name.

EXEC CICS RETURN transfers control from the application program to CICS.
Optionally a transaction id - txn_name can be specified to CICS to start the
transaction next time a terminal action such as pressing of Enter, PA keys occurs.

MVS
VSA
M/
DB

CICS

App.
Pgms
.

VTAM /
TCAM

CICS is a subsystem executing under the MVS address space. It acts as an interface
between the application programs and the operating system and other system components
such as the DB2 database subsystem.
CICS provides the required command interfaces for an application program with the
Operating System, Database system and for Communication requirements.
CICS Control Programs (IBM-Supplied)
1.
2.
3.
4.
5.
6.
7.
8.

FCP File Control Program

JCP Journal Control Program
KCP Task Control Program
PCP Program Control Program
SCP Storage Control Program
TCP Terminal Control Program
TDP Transient Data Program
TSP Temporary Storage Program, etc

Reference Guide

Page 9

CICS Handbook
CICS Control Tables (User-Specified)
1.
2.
3.
4.
5.
6.
7.

FCT File Control Table

JCT Journal Control Table
PCT Program Control Table
PPT Processing Program Table
TCT Terminal Control Table
DCT Destination Control Table
TST Temporary Storage Table, etc

Actually, the core portion of CICS (called the CICS nucleus) consists of IBMsupplied CICS control programs and corresponding user-specified CICS control
tables.
File Control Program (FCP) / File Control Table (FCT): Manages all the I/O
operations of files under CICS. All the files used by the application program should be
registered in FCT.
Task Control Program (KCP) / Program Control Table (PCT): Controls the flow of
Tasks. All CICS transactions should be registered in the PCT.
Program Control Program (PCP) /Processing Program Table (PPT): Manages flow
of CICS application program. All the CICS application programs should be registered in
PPT.
Transient Data Program (TDP) / Destination Control Table (DCT): Manages I/O
operations of a transient Data Queue (TDQ).
Temporary Storage Program (TSP) / Temporary Storage Table (TST): Manages I/O
operations on a Temporary Storage Queue (TSQ).
Journal Control Program (JCP) / Journal Control Table (JCT): Performs logging of
data onto external files called Journals. System log file and other user journal files should
be registered in JCT.
Storage Control Program (SCP): It manages request of dynamic storage by the
CICS control program and application programs.

Advantages:
Constructing the CICS nucleus by the control programs and corresponding control tables
provides unique advantages. CICS control programs achieve their primary tasks based on
their corresponding tables. Once installed in the computer facility, CICS control
programs can be kept as they are, while system programmers can keep adding or
modifying the control table entries as hardware configuration changes or as application
programs are added.
This approach makes the CICS system flexible and easy to maintain. From an
application programming point of view, application programs are almost free from the
considerations for hardware, and they can concentrate on the application specifications.

Reference Guide

Page 10

CICS Handbook

BMS (Basic Mapping Support)

Basic Mapping Support (BMS) provides functions to handle formatted screens.
The 3270 family of display terminal devices has been the standard for
CICS
applications, although other terminal types can also be used with CICS.
The 3270 display terminal comprises of a monitor, a keyboard and an electronics unit to
support the monitor and the keyboard. The 3270 terminal is a character based terminal
displaying 24 lines 80 characters each.
In order to display the data contents on a 3270 terminal, the terminal must receive the
information in a series of data stream. For the 3270 family of devices, this stream is
known as the 3270 data stream. The data stream is a mixture of control characters known
as BCC and text data.
To relieve the task of building and decoding complicated strings of control characters
and data, and to remove device dependant codes from the application programs, CICS
provides a facility known as the Basic Mapping Support (BMS).
BMS is an interface between the application program and the terminal control. BMS
allows creating a Map that specifies the format of data as it appears on the terminal
device.

Primary Functions
Map is a set of fields formatted on a terminal and used in an application program for easy
reference by the program statements.
Device independence
The device dependent codes are removed from the application programs by placing
them in maps.
Constant Information Handling
The application need not handle the default constant information (e.g., titles,
headers, etc.). The constant information is coded in the maps.
Access to data fields of the screen
The data fields in the maps can be accessed by symbolic field names. The data
fields can be repositioned without changing the application program.
Terminal paging
Using this facility a combination of several small mapped areas can be sent to
one or more pages of output.
Message Routing
Messages can be sent to one or more terminals.

Reference Guide

Page 11

CICS Handbook

The Fields in a screen can be classified into:

Unprotected Field wherein data entry can be performed.

Protected field wherein data entry cannot be performed.
Constant Field such as Labels, titles

In addition, a skipper field and stopper fields are defined for unprotected and protected
fields respectively:

The skipper fields results in the cursor to automatically skip to the next
unprotected field. A skipper field is usually defined to mark the end of data
entry for unprotected fields.
The stopper field results in the cursor to stop when the end of a field is reached. A
stopper field is usually defined for protected fields and will lock the key board,
serving as a warning of field overrun. When defined for an unprotected field, the
user has to press the tab key to advance to the next data entry field.

Every field is preceded by an attribute field. The attribute field is a 1 byte field and
consists of the following bit positions:
Bit
0, 1

Function & Bit Settings

Value determined by the contents of bits 2 to 7.

0 - Unprotected
1 - Protected

0 - Alphanumeric
1 - Numeric

2, 3

11 Auto-skip

4, 5

00 Normal Intensity / Non-detectable

01 - Normal Intensity / Detectable
10 - High Intensity / Detectable
11 Dark / Non-detectable

0 - Must be zero

0 Not Modified (MDT off)

1 - Modified (MDT on)

Reference Guide

Page 12

CICS Handbook
Mapset and Map
A Map is a set of instructions that specifies the format of each of the data and constant
information such as literals, headings, titles etc. as they appear on the screen.
A Mapset is a collection of one or more maps. The mapset is an assembler language
program which defines the following information about the maps contained in the
mapset:
the language that will be used for the application program,
the mode in which the map will be used such as Input mode, Output mode
or Input as well as Output also and
other attributes such as the terminal types to which the application will be
communicating with, etc.
For efficiency and ease of maintenance, it is recommended that each screen layout be
defined in a separate mapset, i.e., one mapset contains only one map definition.

Map Types
The Physical Map is a load module that contains a table that BMS uses to
determine the screen locations of data transmitted to and received from the
display terminal.
The Physical map contains the information BMS needs to:
Build the screen with all the titles and labels in their proper places and
with the proper attributes for the various fields.
Merge the variable data from your program in the proper places on the
screen when the screen is sent to the terminal.
Extract the variable data for your program when the screen is read.
The Symbolic map is a program structure (COBOL structure in our case)
which defines all the variable fields in the screen. When an application
program requests that a map is to be sent to a terminal, BMS takes the data
from the symbolic map, formats or maps it according to the physical map and
transmits it to the terminal. This symbolic map structure should be placed in
your program using COPY statement. Using this data structure variable,
fields can be referred to in the CICS application program.

Map Definition Macros

The DFHMSD macro is used to define a mapset and its characteristics. Only one map set
definition is allowed within one assembly run. It is also used to end a map set definition
The DFHMDI macro is used to mark the beginning of each map and its characteristics
within the mapset. As mentioned earlier, since it is possible to define more than one map
Reference Guide

Page 13

CICS Handbook
within a mapset, it is possible to define as many DFHMDI macros corresponding to that
many screens within one DFHMSD macro.
The DFHMDF macro is used to define a field in a map and its characteristics. For each
field in the screen, there will be a corresponding DFHMDI instruction within the map
definition.
A BMS mapset definition contains one or more maps. Each map in turn contains the
fields contained in that map. The mapset definition is terminated by the mapset end
definition macro.

E.g.:
DFHMSD
Mapset Definition - Start
DFHMDI
Map Definition - Map 1
DFHMDF
Field Definition in a Map - Field 1
DFHMDF
Field Definition in a Map - Field 2

DFHMDI
Map Definition - Map 2
DFHMDF
Field Definition in a Map - Field 1
DFHMDF
Field Definition in a Map - Field 2

DFHMSD
Mapset Definition - End

Map 1

Map 2

BMS Macro Rules

Col.
Col.
Col.
Col
1
9
16
72
+---------------+--------------+-----------------------------------------------+
LABEL
Op-Code
Parameters separated
continuation
by commas(parm1=..)
char Col.72

Example
MAPSTNM DFHMSD TYPE=MAP,MODE=INOUT,
LANG=COBOL,TIOAPFX=YES

The BMS macro rules are similar to those of assembler language statements. The
following is the pattern :
Reference Guide

Page 14

CICS Handbook
LABEL

Op-Code

Parameters

LABEL :

specifies the symbolic name

specified in Column 1
Must begin with a letter
Can be upto seven characters long

Specifies the instruction to be executed - DFHMSD, DFHMD or

DFHMDF
Begins in Column 10

Op-Code :

Parameters :

Begins from Column 17 onwards

Separated by Commas without any intervening spaces
Continuation char X in column 72 (, to be the last non-space Char)
Asterisk character in Column 1 specifies a Comment line.

Within one mapset definition, the map definition can be specified as many times as you
wish. Within one map definition, the field definition can be specified as many times as
you wish.

DFHMSD Macro
[setname]

Description:
setname
TYPE

MODE

DFHMSD TYPE=&SYSPARM | DSECT | MAP | FINAL

[ ,MODE=IN | OUT | INOUT]
[ ,LANG=ASM | COBOL | C | PLI]
[ ,TERM=terminal_type]
[ ,STORAGE=AUTO]
[ ,TIOAPFX=YES | NO]
[ ,CTRL=([, FREEKB] [, ALARM] [ ,FRSET])]

Specifies the Mapset name , 1-7 chars long. It must be specified as the
symbol to the DFHMSD macro.
To define the map type.
TYPE=MAP
specifies that a physical map will be generated.
TYPE=DSECT
specifies that a symbolic map will be generated.
TYPE=&SYSPARM can be specified and the values MAP or DSECT
can be specified as parameters in the map
generation JCL (for special assembly procedure).
TYPE=FINAL
is used to indicate the end of a mapset coding.
To indicate input/output operation.

Reference Guide

Page 15

CICS Handbook
MODE=IN
MODE=OUT

LANG
TERM
STORAGE

TIOAPFX

CTRL

For the input map

For the output map. (Recommended for maps
involving output only)
MODE=INOUT
For the input/output map. (Recommended for maps
involving both input and output)
To define the language of the application program (COBOL, ASM, PLI,
or RPG)
Required if other than the 3270 terminal is used. This ensures device
independence by means of providing the suffix.
If STORAGE=AUTO is coded, the symbolic maps for the maps in the
mapset will occupy separate storage areas. Else the same memory is used
for all the maps in the mapset.(i.e. to acquire a separate symbolic map area
for each mapset.)
YES causes inclusion of a 12-byte prefix filed at the beginning of each
symbolic maps. It is required for the CICS command level. Must for
COBOL maps.
Specifies the control options in effect for each map.
FREEKB
To unlock the keyboard.
ALARM
To set an alarm at screen display time i.e. it results in audio
alarm to sound whenever a map is sent to the terminal.
FRSET
To reset MDT to zero (i.e. not modified) status.

Extended Attributes
MAPATTS = (COLOR,HILIGHT)
DSATTS = (COLOR,HILIGHT)
EXTATT = {YES, NO, MAPONLY }
- To define color, high intensity, etc., as per CUA standards.
- Results in additional variables for each attribute in the symbolic map.
IBMs CUA standards specify the use of various colors for different types of messages. It
also specifies that error fields should be highlighted.
To specify these extended attributes, in BMS, we have to code the MAPATTS and
DSATTS options in the mapset definition (DFHMSD).
The MAPATTS is for the physical map and the DSATTS is for the symbolic map. The
attributes coded in both should be the same.
For each extended attribute that is specified, a separate variable is generated in the
symbolic map.
The EXTATT is only for versions of CICS before version 1.7.
E.g.:
MSBINP2 DFHMSD TYPE=&SYSPARM,
MODE=INOUT,
LANG=COBOL,
Reference Guide

X
X
X
Page 16

CICS Handbook
STORAGE=AUTO,
TIOAPFX=YES,
CTRL= ( FREEKB,FRSET)

X
X
X

DFHMDI Macro
mapname DFHMDI SIZE=(lines,columns),
LINE=line_number,
COLUMN=column_number,
JUSTIFY={ LEFT | RIGHT },
CTRL=(ctrl1,ctrl2...)
Description:
mapname
SIZE(ll,cc)
LINE
COLUMN
JUSTIFY
CTRL

Specifies the map name as the symbol, 1 - 7 chars.

Specifies the size of the map in line size (ll) and column size (cc). Usually
coded as SIZE=(24,80) for 24x80 screen.
Specifies the starting position of the map in line number.
Specifies the starting position of the map in column number.
To specify the map to be LEFT justified or RIGHT justified.
Same as the CTRL option for the DFHMSD macro

In addition, the DFHMDI macro has the same options used in the DFHMSD macro, such
as TIOAPFX. If the DFHMDI macro has the same options specified in the DFHMSD
macro, the options specified in the DFHMDI macro override the ones specified in the
DFHMSD macro.

DFHMDF Macro
fldname DFHMDF POS=(line,column),
LENGTH=number,
INITIAL=text,
ATTRB=(attr1,attr2,attr3,attr4,attr5)
OCCURS=number,
Description:
fldname
POS(ll,cc)
LENGTH
INITIAL
COLOR

Specifies a 1 - 7 character field name for the field. If not specified, the
field is not included in the symbolic map.
Specifies the starting position of the field in the line number(ll) and
column number(cc) including the attribute character.
Specifies the length of the field. (This does not include the attribute
byte for the field.)
Specifies the initial value for the field. If omitted, the default is
hexadecimal zeroes(LOW-VALUES).
Specifies the fields color. Can specify BLUE, RED, PINK, GREEN
TURQUOISE, YELLOW or NEUTRAL. If omitted, the default terminal
color is assumed.

Reference Guide

Page 17

CICS Handbook
HILIGHT
ATTRB

Specifies the fields extended highlighting. Valid values are: BLINK,

REVERSE, UNDERLINE and OFF. Default is OFF.
It defines the attribute character of the field which defines the
characteristics of the field.

Field Attributes
1. Field Intensity : NORM / BRT / DRK
2. Field protection attribute : PROT / UNPROT / ASKIP
3. Field Characteristic : NUM
4. Initial Cursor Positioning : IC
5. Field Modification Indication : FSET

The following attributes are applicable :

attr1 - Intensity of the field. Values applicable are :
BRT
- Field displayed with high intensity (i.e. highlight)
NORM - Field displayed with normal intensity
DRK
- Field displayed with no intensity (i.e. invisible). This is useful
for the password field.
attr2 - Field protection attribute. Values applicable are :
PROT - Field is protected. The data cannot be entered into the field. If
data is entered, it will cause the input-inhibit status.
ASKIP - Autoskip. Field is protected, the data cannot be entered into the
field. The cursor skips to the next field.
UNPROT- Field is unprotected. The data can be entered. This should be
specified for all input fields.
attr3 - If coded, this field is presumed to be numeric, right justified and
zero
filled. If omitted, it is assumed to be alphanumeric, left justified and space
filled.
attr4 - Specifies that cursor should be located at the start of this field when the
map is sent to the screen. When there is more than one field specifying
this option, the cursor is positioned in the last such field.
attr5 - Specifies that the MDT(Modified Data Tag) bit in the attribute byte should
be turned on before the map is sent to a terminal.

MDTs and their manipulation

MDT indicates whether a field is modified or not

MDT on will ensure that data is received into the program

MDTs can be turned on by

Specifying the FSET attribute in the physical map
Setting the attribute byte to FSET in the symbolic map
Keying data into the field
Reference Guide

Page 18

CICS Handbook
Whenever data is entered into an unprotected field, the MDT is turned on for that field.
This will cause the data on the screen to be returned to the program when a map is
received. When one of the fields is in error, we would resend the map and require only
that field to be returned in a subsequent receive. (We would not want the rest of the data
to be received again as it is inefficient). To achieve this, we turn on the MDT for the field
in error before we resend the map. This ensures that when we subsequently receive the
map, this field will be passed to the program.
Three ways to turn on the MDT are:
We can specify ATTRIB=(UNPROT,FSET) in the field definition (DFHMDF)
of the map and issue a send with the physical map.
We can move the standard attribute for FSET to the symbolic maps attribute
before issuing a send with the symbolic map. E.g.,
MOVE UNPROT-FSET to fieldname+A
(fieldname+A : The attribute byte for both input and output fields.)
This is used to turn on the MDT from an application program.
Keying data into an unprotected field will turn on its MDT.

MDT Manipulation FRSET

an attribute of DFHMSD macro

turns off all MDTs on the screen before sending a map

requires the physical map field attribute or the symbolic override to control the
MDT status

The FRSET attribute can be specified :

in the DFHMSD macro of the BMS map or
on the SEND MAP command.
It will cause all the MDTs to be turned off prior to sending a map.
When this is done, only data that is re-entered at the terminal will be passed on to the
program. Previously entered data are not sent to the program even though they are
present on the screen. This is because their MDTs are turned off. Unless those data are reentered, the MDT for those fields will be off.
We can include the attributes ASKIP,FSET in the symbolic map for all the correct input
fields before we send the map. For the fields in error, we can code the UNPROT,FSET
attributes in the symbolic map before we send the map. This will ensure that all the data
will be available in a subsequent receive.

Reference Guide

Page 19

CICS Handbook
Ending a Mapset Definition
Col.
Col.
Col.
Col
1
9
16
72
+---------------+--------------+-----------------------------------------------+
DFHMSD TYPE=FINAL
END
DFHMSD TYPE=FINAL specifies the end of the mapset definition.
As in the case of assembler, the statement END is also required for BMS macro
instructions.
Once completed, the BMS macro instructions can be assembled. The instructions are
assembled twice:
for generation of the physical map and
for generation of the symbolic map
The physical map is a load module which must be defined in the PPT.
The symbolic map will be a copy library of COBOL variable names which must be
included in the COBOL program which will be using the map.

Symbolic Map Contents

Two 01-level items generated based on map name

01-level Item names suffixed with I or O for Input & Output respectively
Additional level items defined for
Field for Length
Field for Attribute
Field for Modified Data Indication
Field for Input data
Field for Output Data.
01-level Item for Output REDEFINES Input area.

Field

Characteristic

Suffix

Example

Length

Binary Halfword (S9(4) COMP)

NAMEL

Attribute

Single Char (PIC X)

NAMEA

Field
Modification

Single Char (PIC X)

NAMEF

Input Field

As defined in Map

NAMEI

Output Field

As defined in Map

NAMEO

Reference Guide

Page 20

CICS Handbook

Code for Sample Layout

MAPSETS DFHMSD TYPE=&SYSPARM,MODE=INOUT,TERM=ALL,
LANG=COBOL,TIOAPFX=YES,STORAGE=AUTO
MAPSMP DFHMDI SIZE(24,80),LINE=1,COLUMN=1
DFHMDF POS(8,7),LENGTH=10,INITIAL=NAME :,
ATTRIB=ASKIP
NAME
DFHMDF POS(8,18),LENGTH=20,ATTRIB(UNPROT,IC)
DFHMDF POS(8,40),LENGTH=1,ATTRIB=PROT
DFHMDF POS(10,7),LENGTH=10,INITIAL=ITEM NO :,
ATTRIB=ASKIP
ITEM
DFHMDF POS(10,18),LENGTH=6,ATTRIB=NUM)
DFHMDF POS(10,25),LENGTH=1,ATTRIB=ASKIP
DFHMDF POS(12,7),LENGTH=10,INITIAL=QUANTITY :,
ATTRIB=ASKIP
QTY
DFHMDF POS(12,18),LENGTH=6,ATTRIB=NUM
DFHMDF POS(12,25),LENGTH=1,ATTRIB=PROT

DFHMSD TYPE=FINAL
END
Note that even though the map has the constant fields starting in column 8, the field
definitions in BMS indicate that they are to start from column 7. This is because of a 1byte attribute field associated with each field name, that defines how the characteristics of
the field.
The first DFHMDF definition defines the constant NAME and the following colon with
auto-skip attribute coded as ATTR=ASKIP. The next DFHMDF definition has a label
NAME and is coded with attributes UNPROTECT and IC. (Unprotect - since it requires
input and IC since this is the Initial Cursor position). The label NAME will be used to
generate the different variable names of the symbolic map. The third DFHMDF field
defines a 1-byte stopper field, at column 40 of row 8, which limits the input length for the
unprotected field labeled NAME. The next sets of three DFHMDF macros pertain to the
ITEM-NO and QUANTITY.
Stopper and skipper fields are coded to limit the input area for fields.

Reference Guide

Page 21

CICS Handbook

Symbolic Map for Sample Layout

01

MAPSMPI
02
FILLER
X(12).
02
NAMEL
S9(4) COMP.
02
NAMEF
PIC X.
02
FILLER REDEFINES NAMEF.
03
NAMEA
PIC X.
02
NAMEI
PIC X(20).
02
ITEML
S9(4) COMP.
02
ITEMF
PIC X
02
FILLER REDEFINES ITEMF.
03
ITEMA
PIC X.
02
ITEMI
PIC X(06).
02
QTYL
S9(4) COMP.
02
QTYF
PIC X
02
FILLER REDEFINES QTYF.
03
QTYA
PIC X.
02
QTYI
PIC X(06).

01

MAPSMPO REDEFINES MAPSMPI.

02
FILLER
PIC
X(12).
02
FILLER
PIC X(3).
02
NAMEO
PIC X(20).
02
FILLER
PIC X(3).
02
ITEMO
PIC X(06).
02
FILLER
PIC X(3).
02
QTYO
PIC X(06).

The symbolic map for the screen defined in the sample layout is shown above.
The first observation to make here is the naming convention. The mapname MAPSMP
used in DFHMDI macro definition of the previous slide is used to denote the input and
output areas MAPSMPI and MAPSMPO respectively. Note that the output area redefines
the input area.
Secondly, the label names (NAME, ITEM, etc.) used in the BMS macro definitions are
used here to indicate the field names (NAMEI, ITEMI, NAMEO, ITEMO, etc.). Note
that only those field macros with labels are defined in the symbolic map.
Under the input variable definition, each field name has a 2-byte length field, followed by
an one-byte flag field and then the input field itself. The one-byte flag field is also
redefined to be a one-byte attribute field. Correspondingly, there is a 3-byte filler and the
output field under the output variable definition. For e.g., under MAPSMPI, we find
Reference Guide

Page 22

CICS Handbook
NAMEL, NAMEF and NAMEI with NAMEA redefining NAMEF. Under MAPSMPO,
we find a 3-byte filler and NAMEO.
The 12-byte filler at the beginning of both MAPSMPI and MAPSMPO is the control
information that is required for COBOL programs which is generated by coding
TIOAPFX=YES in the mapset definition.
We have some products such as SDF (Screen Definition Facility) which eliminate the
cumbersome task of coding BMS macros. Tools like SDF allow the screen to be painted
and automatically generate the symbolic and physical maps.
In subsequent visuals we will see how the attribute and length variables of each field can
be manipulated in the symbolic map to control the display of the map.
NOTE :
The symbolic map starts with the 01 level definition of map name specified in the
DFHMDI macro with the suffix of I for the input map or O for the output map. Next
is the definition of FILLER PIC X(12), which is the TIOA prefix created by the
TIOAPFX=YES of the DFHMSD macro, and this is required by BMS under the CICS
command level.
For each field name (1 to 7 characters) you specified in the DFHMDF macro,
BMS creates 3 fields for inputs and another 3 fields for outputs, by placing 1 character
suffix to the original field name. The meanings of these fields are as follows :
Name+L:
The half-word binary (PIC S9(4) COMP) field. For the input filed, the
actual number of characters typed in the filed will be placed by BMS
when the map is received. For the output field, this is used for the dynamic
cursor positioning.
Name+F:
Flag Byte. For an input field, it will be X80 if field has been modified
but no data is sent (i.e. the field is cleared). Otherwise, this field is X00.
Name+A:
The attribute byte for both input and output fields.
Name+I:
The input data field. X00 will be placed if no data is entered. Note the
space X40 is data. The application program should differentiate X00
from space (X40).
Name+O:
The output data field.

Reference Guide

Page 23

CICS Handbook
I/O Operations
BMS COMMANDS FOR I/O OPERATIONS
SEND MAP
RECEIVE MAP
SEND CONTROL
SEND TEXT
SEND PAGE
SEND MAP
EXEC CICS SEND
MAP (map_name)
MAPSET(mapset_name)
[FROM(data-area)]
[CURSOR(data-value)]
[ERASE|ERASEUP]
[DATA|MAP ONLY]
[ALARM]
END-EXEC
The SEND MAP command sends mapped data to a terminal.
ALARM
specifies that the 3270 audible alarm feature is to be activated.
CURSOR
specifies the location to which the cursor is to be returned upon
completion of a SEND MAP command.
ERASE
specifies that the screen buffer is to be erased and the cursor returned to
the upper left corner of the screen. The first output operation in any
transaction, or in a series of pseudo conversational transactions, should
always specify ERASE.
ERASEUP specifies that before this page of output is displayed, all unprotected
character locations screen are to be erased.
DATAONLY specifies that only application program data is to be written. The attribute
characters must be specified for each field in the supplied data.
MAPONLY specifies that only default data from the map is to be written.
If neither MAPONLY nor DATAONLY are used, the physical map
attributes will be used for the first SEND MAP. For subsequent sends, the
existing attributes will be used.
Data to be prepared before SENDing the MAP :
Field Length : fieldname +L
Field Attribute : fieldname +A
Field Content : fieldname +O
These variables must have valid data before a map is sent using the DATAONLY option.

Reference Guide

Page 24

CICS Handbook
The attribute byte of the symbolic map can be modified to supersede the physical map
attributes. For this, there is a CICS copy member called DFHBMSCA. This has special
one byte characters for combination of several attribute types that can be used. The
names in the copy member may not be meaningful and it will be a good practice to
develop a new member using mnemonic names for public use.
Cursor Positioning

Cursor positioning required for positioning the cursor

In the first data entry field during data entry
In the first field resulting in data entry error
Cursor Positioning Techniques :
Initial cursor positioning
Direct cursor positioning
Symbolic cursor positioning

1) INITIAL CURSOR:
a) As defined in the DFHMDF macro
b) Appropriate for maps containing only one input field
c) For maps containing more than one input field, not flexible enough
2) DIRECT CURSOR POSITIONING:
a) By specifying the actual cursor position. For example if cursor is to be positioned
in the 24th column of line number 18, the cursor position is computed as follows:
(18-1) * 80 + (24 - 1) = 1383.
b) Use the CURSOR option, with the displacement value specified as a data-value or
as a binary halfword parameter
c) Not flexible if the screen layout changes.
3) SYMBOLIC CURSOR POSITIONING :
a) By specifying the field where the cursor is to be positioned rather than the
displacement
b) By setting the value -1 to the length field in the symbolic map for the field
c) Use the CURSOR option, without the displacement value
d) The map must be defined as INOUT
Changing Attributes

Need for changing Field attributes

Highlighting fields in error
Protecting fields during deletion
IBM Supplied copy library DFHBMSCA contains all possible attribute
combinations
Can be copied into the application program

Reference Guide

Page 25

CICS Handbook
The standard attribute and printer character control list are contained in the copybook
DFHBMSCA. The copybook contains a set of 01 level statements that can be copied into
the working storage section. To define an attribute for a field, move the corresponding 01
level statement to the fieldnameA symbolic variable before SENDing the map.
If the map is sent without specifying DATAONLY or MAPONLY option, then
based on the contents of the symbolic map, the attributes are defined for the fields
and the contents of the physical map, BMS constructs the 3270 data stream and
SENDs the map to the terminal.
E.g. :
EXEC CICS SEND MAP(MAPSMP)
MAPSET(MAPSETS)
END EXEC.
If the MAPONLY option is used, the physical map alone is used by BMS to
construct the 3270 data stream.
E.g.:
EXEC CICS SEND MAP(MAPSMP)
MAPSET(MAPSETS)
MAPONLY
END-EXEC.
If the DATAONLY option is used, only the data and the associated attributes,
cursor positioning information is picked from the symbolic map and the 3270 data
stream constructed.
E.g.:
EXEC CICS SEND MAP(MAPSMP)
MAPSET(MAPSETS)
DATAONLY
END-EXEC.
RECEIVE MAP
EXEC CICS RECEIVE
MAP(map_name)
MAPSET(mapset_name)
[INTO (data-area)]
ASIS
END-EXEC.
The format of the RECEIVE MAP command is shown above. The data-area
corresponds to the symbolic map into which the field values will be moved into.
The receive map command receives data from the terminal. The symbolic map
will contain the data.

Reference Guide

Page 26

CICS Handbook
If a field has been cleared, then the flag field fieldname + F contains x80 or
X82. The input date field, fieldname+I contain LOW-VALUES.
Detecting cursor position
DIRECT CURSOR POSITIONING:
The EIB field EIBCPOSN is set to the absolute cursor position on the
screen following the execution of a RECEIVE command.
Not flexible if the screen layout changes.
SYMBOLIC CURSOR POSITIONING :
To use this option the CURSLOC=YES should be specified in the
DFHMDI macro definition.
The flag subfield fieldname+F has its 7th bit set to 1 in case the cursor
was in a named field. This would result in a value of X82 or X02
depending on whether the field contents were erased or not.
You could avoid hard coding these hexadecimal values by moving the
fieldname+F to DFHBMFLG field of DFHBMSCA copy book and then
checking for the defined condition name DFHCURSR or DFHERASE
depending on whether you want to check for the cursor or for field
erasure.

AIDKEY
DFHAID is an IBM supplied copybook that contains the standard definitions for BMS
attribute bytes and AID (Attention IDentifier) keys.
The key pressed by the terminal operator can be obtained from one of the EIB variables EIBAID. Based on the value of the EIBAID, the program can take appropriate action,
viz., continue processing or exit from the application.
E.g.:
WORKING STORAGE SECTION.
COPY DFHAID.

PROCEDURE DIVISION.
EXEC CICS RECEIVE MAP(MAPSMP)
EXEC

MAPSET(MAPSETS) END-

EVALUATE TRUE
W HEN EIBAID = DFHPF12
EXEC CICS RETURN END-EXEC
W HEN EIBAID = DFHENTER
PERFORM 1000-PROCESS-DATA
THRU 1000-PROCESS-DATA-EXIT
Reference Guide

Page 27

CICS Handbook
W HEN EIBAID = OTHER
MOVE Invalid Key Pressed TO MESSAGEO
END-EVALUATE.

Application Programming
CICS supports the host languages - COBOL, C, PL/1 and Assembler.

CICS Command format

EXEC CICS function
[option ( argument value)]
[option ( argument value)]
...
[RESP ( argument value)]
END-EXEC
CICS commands can be embedded within a COBOL application program.
Every CICS command must start with the keyword EXEC CICS and end with a
delimiter. The delimiter for COBOL is END-EXEC.
For C and PL/I it is a semi-colon(;).
The function is the CICS service requested. An example will be reading a file.
The option is one of the options available/applicable for the function requested. For
example, for reading a file, a file name is to be given.
The argument value determines the characteristics of the value to be placed for the
option.
The response of the CICS command execution will be made available by CICS in the
argument value associated with the key word RESP. The argument value for RESP
option is of data type - half word binary, i.e., S9(4) COMP. The response is also stored
in a special variable called EIBRESP.

Argument Values
The arguments to the CICS command options can be one of the following:
Data Value
o Constants are also permitted, for e.g., LENGTH(10). For alphanumeric
constants, the value must be contained within quotes.
Data Area
Reference Guide

Page 28

CICS Handbook

o A Valid COBOL data name Full word Binary - PIC S9(8) COMP.
Half word Binary - PIC S9(4) COMP.
Name
o A Valid COBOL data name(Character string).
Label
o A COBOL paragraph or a section name.
Time in hhmmss format
o PIC S9(7)
COMP - 3.
Pointer Reference
o Pointer name.

E.g.:
1. EXEC CICS RECEIVE
INTO (WS-INPUT)
LENGTH(WS-IN-LENGTH)
RESP(WS-CICS-RESP-CODE)
END-EXEC.
The RECEIVE command is used to receive data from the terminal. It moves the
information received from the terminal into the specified Working Storage variable.
The maximum length of the input should be specified in LENGTH. If the input exceeds
the specified LENGTH, CICS places the actual length in the LENGTH data-area and
truncates the message to the specified LENGTH.
2. EXEC CICS SEND
FROM (WS-OUTPUT)
LENGTH(WS-OUT-LENGTH)
RESP(WS-CICS-RESP-CODE)
END-EXEC.
The SEND command is used to send out data to a terminal.
3. EXEC CICS
RETURN
TRANSID(WS-NXT-TRANSID)
COMMAREA(WS-COMM-AREA)
END-EXEC.

The RETURN command terminates the transaction and returns control to a parent
program or to CICS. The TRANSID option indicates the next transaction to be started.
The COMMAREA option specifies the data to be used for the next transaction.
After the execution of each command, the response will be available in the RESP dataarea.
Reference Guide

Page 29

CICS Handbook

Structure of CICS application program

IDENTIFICATION DIVISION.
PROGRAM-ID . XXXXXXXX.
ENVIRONMENT DIVISION.

<=== THIS DIVISION MUST BE EMPTY

DATA DIVISION.

<=== FILE SECTION IS OMITTED

WORKING- STORAGE SECTION.

77 --------------------- .
01 --------------------- .
05 ---------------- .
LINKAGE SECTION.
01 DFHCOMMAREA.
05 -----------------.

<=== LINKAGE SECTION IS MANDATORY

<=== COMMUNICATION AREA reqd for
passing data for subsequent execs.

PROCEDURE DIVISION .
( COBOL STATEMENTS) + <=== CICS statements mixed with COBOL
( CICS STATEMENTS)
statements. Some COBOL verbs not
.
allowed.
GOBACK.
Description:
ENVIRONMENT DIVISION.
Only the header is required in this section .
INPUT-OUTPUT SECTION , FILE CONTROL, SELECT statements not
required. Instead, Files will have to be defined in the File Control Table (FCT) in
CICS.
DATA DIVISION.
FILE SECTION is not required.
LINKAGE SECTION is required.
PROCEDURE DIVISION.
The following COBOL statements cannot be issued in a CICS application
program.
- ACCEPT
- RELEASE

- DATE
- SORT

Reference Guide

- DISPLAY
- STOP RUN

- EXHIBIT
- TRACE

Page 30

CICS Handbook
- Any I/O statements ( OPEN ,CLOSE,
START)

READ, WRITE, REWRITE, DELETE ,

EXEC Interface Block (EIB)

CICS Control Block containing useful CICS system information
Automatically given to each CICS application program in LINKAGE SECTION
at the time of program translation
Copy book DFHEIBLK is inserted by the translator before the
DFHCOMMAREA variable
Information in EIB can be used for handling error/exceptions.
Usage of EIBRESP for checking CICS command result
The EIB Block contains, apart from information related to CICS communications, the
following (the fields are prefixed with EIB, as in EIBDATE, EIBTIME, etc.):
TRNID
- the current Transaction Id
DATE, TIME - Date and Time at which the transaction was started or
the time it was refreshed using the ASKTIME command
TRMID
- the terminal id associated with the transaction
FN
- the CICS function which was accesses lately
RCODE
- the error code resulting from the last CICS command
RESP
- the response code for the last CICS command
RESP2
- additional response code information
AID
- the function key associated with the transaction
CALEN
- the COMMAREA length; used in pseudo-conversational pgms
EIBRESP:
The value returned in the attribute EIBRESP can be used for checking whether a CICS
command was executed successfully by CICS or not.
The EIB variables are available in the copy book DFHEIBLK

Storage Types
CICS provides a variety of facilities for storing data within and between transactions.

Provides following storage sources

COMMAREA : A communication area (COMMAREA) is a facility used
to transfer information between two programs within a transaction or
between two transactions from the same terminal.
COMMON WORK AREA (CWA) : The common work area (CWA) is a
single control block that is allocated at system start-up time and exists for
the duration of that CICS session. The size is fixed, as specified in the
system initialization parameter, WRKAREA.

Reference Guide

Page 31

CICS Handbook

There is almost no overhead in storing or retrieving data from the

CWA.
Data in the CWA is not recovered if a transaction or the system
fails.
TRANSACTION WORK AREA (TWA)
Dynamic Storage Allocation & De-allocation
GETMAIN
FREEMAIN
Prevent one application program from overwriting CICS storage areas storage keys
CICS key : CICSDATAKEY
User key : USERDATAKEY

When you use the GETMAIN command to acquire main storage, there is the possibility
that one program may accidentally overwrite the storage used by another program. Or an
application program may overwrite CICS control blocks crucial for the operation of
CICS, thereby crashing the system.
Storage used by CICS is CICS key storage and that used by an application is user key
storage. Every program in CICS runs under an execution key that determines the types of
storage it can access. A program under CICS key can access CICS key or user key
storage, whereas a program under user key can access only user key storage. CICS
system programs run under CICS key, and application programs run under use key.
Coding CICSDATAKEY or USERDATAKEY as an option to Get main will determine
which type of storage is allocated. The default is USERDATAKEY because storage
allocated by CICSDATAKEY cannot be modified.

Reference Guide

Page 32

CICS Handbook
CICS Program Control
Program to Program Transition

CICS LINK : To pass control to a program at a lower logical level expecting

control to be returned to the program at the higher logical level.

CICS XCTL : To pass control to another program at the same level not
expecting the control to be returned.

COBOL CALL : To perform a COBOL Call from one CICS program to another
COBOL program.

CICS RETURN : To return to the next logical higher level program or to CICS.

The application programs under CICS run under various logical levels. At the highest
level is CICS (Level 0). All application programs run at lower logical levels.
A LINKed program runs at the next lower logical level from the linking
program.
A XCTLed program runs at the same logical level as the XCTLing
program.
The RETURN command always passes control back to the program at one
logical level higher.
All programs involved in a LINK, XCTL or dynamic call must be defined in the PPT.

LINK Command
When one program LINKs to another, the first program stays in the main storage while
the second program is executing.
When the second ( LINKed to) program ends and returns control, the first program
resumes at the point after the LINK statement. The LINKed to program is considered to
be operating at one logical level lower than the LINKing program.
LINK must be used for programs which need to return to the program that invoked it. All
LINKed to programs must have a RETURN command.
When a program LINKs to another program, it can pass data to the linked program
through the COMMAREA. In such a case, the address of the COMMAREA is effectively
passed. Any changes to the COMMAREA in the linked program, will be available to the
linking program after RETURN.

Reference Guide

Page 33

CICS Handbook
Data from the linking program to the linked to program can be passed using the
COMMAREA option.
If the COMMAREA OPTION is used in the LINKing program, the area must be
defined in the working storage section. In the LINKed to program, the area must be
defined as the first area in the linkage section, under the reserved name
DFHCOMMAREA.
The COMMAREA is shared between the two programs. When the LINKing program
regains control, any changes made to the COMMAREA by the LINKed-to program are
accessible.
The WORKING STORAGE Section of the LINKing program is retained till its execution
ends. But the Working storage of the LINKed to program is automatically released after
the RETURN command.
Both the linking and the linked programs execute under the same task.
Format of command :
EXEC CICS LINK
PROGRAM (pgm-name)
[ COMMAREA (data-area) ]
[ LENGTH (data-value) ]
END-EXEC.
Description:
PROGRAM

The name of the called program to which control is passed must be

specified. If the name is a literal, it should be enclosed in quotes.
Program name can be upto eight character long. The program must be
defined in the PPT.
LENGTH
It is used to specify the length of the COMMAREA (in the calling
program). It must be defined as a halfword binary field (S9(4) COMP).
The maximum length which can be specified is 65,536 bytes. This
parameter is required only if COMMAREA is present.
COMMAREA It is used to pass data to a called program. Its an optional parameter,
specifying the data area containing the data to be passed to the LINKed
to program. This option is required only if you want to pass information
to the program being linked to.
E.g.:
EXEC CICS LINK
PROGRAM (PROG000C)
COMMAREA (WS-DATA)
LENGTH (WS-DATA-LENGTH)
Reference Guide

Page 34

CICS Handbook
END-EXEC.

XCTL Command
When one program XCTLs to another, i.e.., transfers control, the first program is
considered terminated, and the second program operates at the same level as the first
program.
When the execution of the second program ends the control is returned not to the first
program, but to a program which is at a higher logical level or to CICS, if the first
program was invoked directly under CICS.
Data from the XCTLing program to XCTLed program can be passed using the
COMMAREA option.
If the COMMAREA is used in the program which is performing the XCTL, the area
must be defined in the working storage section. In the called program the area must be
defined as the first area in the LINKAGE SECTION, using the DFHCOMMAREA. Only
a copy of the data is passed and not the address.
Both the XCTLing and the XCTLed programs execute under the same task.
Format of command :
EXEC CICS XCTL
PROGRAM (pgm-name)
[ COMMAREA (data-name) ]
[ LENGTH(data-value) ]
END-EXEC.
Description:
PROGRAM is the name of the program to which you wish to transfer control.
If the name is a literal, it should be enclosed in quotes. Program
name can be eight character long and defined in PPT.
COMMAREA An optional parameter. When specified, it is the name of the
area containing the data to be passed. This option is required
only if you want to pass information to the XCTLed to program.
LENGTH
Specifies the length of the commarea. This parameter is required
only if COMMAREA is present. Like the length parameters in
other commands it must be half word binary.
E.g.:
EXEC CICS XCTL
PROGRAM(PGMSAMP)
Reference Guide

Page 35

CICS Handbook
COMMAREA (WS-COMMAREA)
LENGTH(WS-COMM-LENGTH)
END-EXEC.

RETURN Command
The RETURN command passes control to the next higher level. When the program is at
the highest logical level under CICS (level 1), the RETURN command will pass the
control back to CICS.
When control is passed back to CICS, you can specify two additional options to the
RETURN command:
1. You can specify the next transaction to be executed when the next input comes from
the same terminal. This option is used to develop applications in pseudo
conversational mode.
2. You can specify what data is to be passed to the next transaction.
Format of command :
EXEC CICS RETURN
[ TRANSID(next-id) ]
[ COMMAREA(comm-area) ]
[ LENGTH(length) ]
END-EXEC.
Description:
TRANSID

Specifies the next transaction identifier to be executed from the terminal

associated with the current transaction. This is the transaction that is
executed the next time that terminal sends input. This can be issued only
by transactions at the logical level 1.

COMMAREA is an optional parameter. It is the name of the area containing the data to
be passed to the next transaction that will be executed at that terminal.
LENGTH

Specifies the length of the COMMAREA.

Static Call
The called program must be link edited with the calling program. If many programs are
calling the same program, this will result in more memory occupation. A statically called
program does not require to be registered in PPT.

Dynamic Call
The dynamic call is available only in VS-COBOL II and CICS 2.1 or later. Dynamically
called programs are separate load modules and are therefore shareable by multiple
callers. During execution, CICS will dynamically load the called program. The
dynamically called program requires to be registered in PPT.
Reference Guide

Page 36

CICS Handbook

Conversational modes
Non conversational mode does not involve any interaction with the terminal user. For
this mode of operation the transaction has to be initiated by special ways. They are
- Automatic task initiation.
- Using START command from another transaction.
In a Conversational transaction the program converses with the user using SEND and
RECEIVE command pair. The program waits until the user responds. The resources are
held till user responds. Since the human response is slower than the CPU speed, a
significant amount of resources will be held in the CICS address space just waiting for
the user to respond. So the applications written in conversational mode are very
inefficient.
In a pseudo conversational mode, when a program attempts to converse with a terminal
user, it terminates after sending a message with a pointer to the next task. Since the task
is terminated and resources are freed while waiting for the users response, this approach
is much more efficient than the conversational approach. When the user completes the
response, the next task is automatically initiated by CICS. This task receives the
information from the terminal buffer and processes it.

Error conditions in Program Control Commands

INVREQ

TRANSID is specified on a RETURN command in a program

that was not at the highest logical level ( i.e.., a RETURN
that would not terminate the transaction by returning control to
CICS )

LENGERR

The length of the data specified using the RETURN command

with length option is outside the valid range of 1 to 32763.

NOAUTH

Resource or command security check has failed.

PGMIDERR The program to which control is passed on a LINK or XCTL

command, cannot be found in the list of installed program
definitions, or it is not in the library or it has been disabled.

Reference Guide

Page 37

CICS Handbook
Interval and Task Control
CICS provides timer facilities such as getting current date and time, initiating tasks at
specific time or after an interval of time, etc. and task control features such as task
synchronization, automatic task initiation, etc. These are provided by the CICS modules CICS Interval Control Program (ICP) and Task Control Program.

Interval Control
The Interval Control Features provided by the CICS interval control program (ICP) are:
providing the current date and time in the desired formats (supported by
CICS),
Task initiation at specific time or after an interval

Interval control commands

o ASKTIME

To request current data and time.

o FORMATTIME

To select format of date and time.

o DELAY

To delay the processing of a task.

o START

To initiate a transaction from current task.

o RETRIEVE
command.

To

o CANCEL
command

Reference Guide

retrieve

data

passed

by

START

To cancel the effect of the previous interval control

Page 38

CICS Handbook
Starting an Asynchronous transaction using START command
The START command is used to start a transaction at the specified terminal and at the
specified time or interval. Optionally, data can be passed to the to-be-initiated
transaction.
EXEC CICS START
TRANSID(data-value)
[ TIME(hhmmss) | INTERVAL (hhmmss)]
[ REQID(NAME)]
[ FROM(data-area)
[ LENGTH(data-value) [FMH]]
[ TERMID(data-value)]
END-EXEC
Description:
TRANSID

defines the transaction id of the transaction to be initiated.

TIME or INTERVAL indicates the time or time interval of the transaction initiation,
respectively, in the form of hhmmss. If omitted, the transaction will be
initiated immediately. If the time specified in the TIME parameter has
expired, then also, the transaction will be initiated immediately.
REQID

Specifies an 8 byte value that identifies this START command so that the
started task can be cancelled with a CANCEL command. If omitted, CICS
still generates the REQID and the same is available in the EIB variable
EIBREQID.

FROM

Specifies the data area which contains the data to be passed, i.e. to pass a
field in the Working Storage Section.

LENGTH

The length of the data-area should be specified in the LENGTH option.

TERMID

defines the terminal id of a terminal against which you initiate the

transaction. If it is omitted, the specified transaction will be initiated
against the terminal with which the current transaction is associated.

Data can be passed to the transaction by specifying the FROM and LENGTH options.
Interval Control stores the data passed in a TSQ for a later RETRIEVE (retrieval).
For example the command EXEC CICS START TRANSID (TRN1) TIME (083000)
will result in the transaction TRN1 to be started at 8.30 hrs. If this is issued after 08:30
hrs, the transaction will be started immediately.

Reference Guide

Page 39

CICS Handbook
Retrieving data in a STARTed Transaction RETRIEVE Command
The RETRIEVE command is used to retrieve the data passed by the START command
which was issued in the other transaction in order to initiate the current transaction.
EXEC CICS RETRIEVE
INTO (data-area)
LENGTH(data-value)
END-EXEC.
Description:
INTO

It defines the field in the Working Storage Section to which the data field
passed by the FROM option of the START command is to be placed.
It indicates the LENGTH of the INTO field.

LENGTH
E.g.:
EXEC CICS RETRIEVE
INTO (WS-DATA)
LENGTH(100)
END-EXEC

CANCEL Command
The CANCEL command is used to cancel the Interval Control commands, such as
DELAY or START, which have been issued earlier. The Interval Control commands are
identified by the REQID parameter of these commands.

To Cancel a previously issued START command

Transaction to be cancelled identified by REQID
Cannot be cancelled if the transaction had already started.
EXEC CICS CANCEL
REQID(data-value)
END-EXEC

Example
EXEC CICS START
TRNSID(TRN1)
REQID(START1)
TIME (084000)
END-EXEC.
....
EXEC CICS CANCEL
REQID(START1)
END-EXEC
In the example shown above, at the completion of the CANCEL command, the START
command identified by START1 will be cancelled.
Reference Guide

Page 40

CICS Handbook
Task Control
Task control features provided by the CICS Task Control Program (KCP) are:
Automatic Initiation of task
task synchronization
Asynchronous transaction initiation
Gives exclusive control of resources

Task Control Command

o SUSPEND
o ENQ
o DEQ

To suspend a task.
To gain exclusive control over a resource
To release exclusive control from a resource

SUSPEND Command
The SUSPEND command is used to suspend a task. During the execution of this
command, the task will be suspended, and control will be given to other tasks with higher
priority. As soon as all higher-priority tasks have been executed, control will be returned
to the suspended task.
Because of the quasi-reentrancy of the CICS programs, if a CPU intensive processing is
performed in a program, it is a good practice to issue this command from time to time in
order to allow other tasks to proceed. This practice will improve the transaction
throughput of the CICS region as a whole.
EXEC CICS SUSPEND
END-EXEC.

ENQ and DEQ Commands

The ENQ command is used to gain exclusive control over a resource.
The DEQ command is used to free the exclusive control from the resource.
CICS automatically provides exclusive control over resources to a task in most cases.
Therefore, a CICS application systems can be developed in such a way that an
application program does not have to issue the ENQ, DEQ commands.
EXEC CICS ENQ
RESOURCE(resource-id)
END-EXEC.
EXEC CICS DEQ
RESOURCE(resource-id)
END-EXEC.
Description:
Reference Guide

Page 41

CICS Handbook
resource-id

is the name of a resource and is 1-255 characters long.

Exception and Error Handling

An abnormal situation can arise during the execution of a CICS command. This is known
as an exception condition. Each CICS command has its own set of possible exception
conditions. It is strongly recommended to check possible exception conditions after every
CICS command.

Exception Handling
Exceptions can be handled in three ways :
Pass control to a specified label.
Let the application continue.
Do nothing, and rely on the system (CICS) default action.

HANDLE CONDITION Command

To pass control to a specified label

EXEC CICS HANDLE CONDITION
condition (label)
[Condition (label)]
[ ERROR(label)]
END-EXEC.

Description:
condition

ERROR

represents an exception error. If a label is specified, control will be passed

to the labeled paragraph of the program when the specified error condition
occurs. If no label is specified, it has the effect of cancelling the
previously set HANDLE CONDITION, and the default system action is
taken.
The general error condition can be specified within the same list to specify
that all other conditions cause control to be passed to the label specified.

Although more than one HANDLE CONDITION can be issued in a program, no more
than 12 conditions can be specified in a single HANDLE CONDITION command.

Scope: The HANDLE CONDITION command for a given condition applies only to the
program in which it is specified.

Reference Guide

Page 42

CICS Handbook

The HANDLE CONDITION command:

1. Remains active while the program is being executed, or until:
An IGNORE CONDITION command for the same condition is
encountered, in which case the HANDLE CONDITION command is
overridden
Another HANDLE CONDITION command for the same condition is
encountered, in which case the new command overrides the previous one.
2. Is temporarily deactivated by the NOHANDLE or RESP option on a command.

IGNORE CONDITION Command

To specify that no action is to be taken if a condition occurs

EXEC CICS IGNORE CONDITION
Condition
[Condition]
END-EXEC.

The IGNORE CONDITION command causes no action to be taken if the condition

specified occurs in the program. The control will be returned to the next instruction
following the command which encountered the exceptional condition.
The IGNORE CONDITION command for a given condition applies only to the program
in which it is specified, and it remains active while the program is being executed, or
until a HANDLE CONDITION command for the same condition is encountered, in
which case the IGNORE CONDITION command is overridden.
Upto 12 conditions can be specified within the same IGNORE CONDITION command.
The IGNORE CONDITION command causes no action to be taken if the condition
specified occurs in the program. The control will be passed to next instruction following
the command which encountered the exception. The request by the ignore condition is
valid until the subsequent HANDLE CONDITION command is issued.
Scope: The IGNORE CONDITION command is applicable only to the program in which
it is coded. It is active during program execution till a HANDLE command for the same
CONDITION is encountered.

NOHANDLE Option
When NOHANDLE option is specified in a CICS command, no action will be taken for
the exception condition. The control will be passed to the next instruction which
immediately follows. However, CICS sets the return code in the system field EIBRESP

Reference Guide

Page 43

CICS Handbook
in the EIB. The application program can check EIBRESP for possible error conditions
and take required action.
E.g.:
EXEC CICS SEND
FROM (WS-DATA)
LENGTH(WS-LENGTH)
NOHANDLE
END-EXEC.

RESP Option
CICS makes it easy to test the response value in EIBRESP by supplying a built-in
function called DFHRESP.
The RESP option can be specified in any CICS command. Its function is similar to the
return code in the batch program. If the RESP option is specified in the command, CICS
places a response code at a completion of the command. The application program can
check this code, then proceed to the next processing. This approach has an advantage
over the HANDLE CONDITION command approach, because it makes the program
more structured.
When RESP is used in a command, the NOHANDLE option is applied to this command.
Therefore, the HANDLE CONDITION command will have no effect in this case.
Following procedures should be followed to utilize the RESP option:
Define a fullword binary field (PIC S9(8) COMP) in the Working Storage
Section as the response field.
Place the RESP option with the response field in a CICS command.
After the command execution, check the response code in the response
field with DFHRESP(XXXX) where XXXX is the symbolic name for the
exceptional conditions or NORMAL for normal completion.

PUSH and POP Commands

The HANDLE CONDITION and IGNORE CONDITION commands remain in effect
until the program ends.
PUSH and POP commands are used to suspend and reactivate, respectively, all the
HANDLE CONDITION requests currently in effect.
These are useful while performing a subroutine embedded in a main program. A called
routine can use the PUSH command to suspend the existing HANDLE CONDITION
requests, whereas, before returning control to the caller, the called routine can restore the
original requests using the POP command.
Reference Guide

Page 44

CICS Handbook
Between the PUSH and POP commands, any HANDLE CONDITION request can be
issued, independent of those in mainline routine. These HANDLE CONDITION
commands will also be active in mainline routine after the POP command is executed.
Formats :
EXEC CICS PUSH HANDLE
END-EXEC.
EXEC CICS POP HANDLE
END-EXEC.

The PUSH and POP commands CAN ALSO BE USED TO suspend and reactivate,
respectively, HANDLE AID and HANDLE ABEND commands also.

System Default action

CICS checks possible exceptions after each CICS command

If exceptional conditions are not taken care of, CICS by default, may
SUSPEND the task or abnormally terminate the execution
Issuing an ABEND CODE

For each CICS command, CICS checks the results of the command execution. Following
are the common ABEND codes related to exceptional conditions.
APIA - ERROR
AEID - EOF
AEIM - NOTFND
AEIN - DUPKEY
AEIP - INVREQ
AEIQ - IOERR
AEIR - NOSPACE
AEIS - NOTOPEN
AEIT - ENDFILE
AEIV - LENGERR
AEIW - QZERO
AEIZ - ITEMERR
AE19 - MAPFAIL
AEYH - QIDERR
Following are the common Abend codes not related to exceptional conditions.
AEY7 Resource security failed.
AEY9 Unsupported command issued.
AKCS Deadlock or timeout
ASRB ABEND due to OS ABEND intercepted by CICS.
ASRA ABEND due to program interruption (error in COBOL statement).

HANDLE ABEND Command

It is an abend control command. It is used to intercept an abnormal termination (ABEND)
within a program, and to activate, cancel, or reactivate an exit for the ABEND
processing.

Reference Guide

Page 45

CICS Handbook
EXEC CICS HANDLE ABEND
[ PROGRAM (name) | LABEL (label) | CANCEL | RESET ]
END-EXEC.
Description:
PROGRAM or LABEL used to activate an exit to a program or a paragraph,
respectively, for the ABEND processing.
CANCEL

used to cancel the previously established HANDLE ABEND

request.

RESET

to reactivate the previously cancelled HANDLE ABEND r

request.

ABEND Command
It is an abend control command. It is used to terminate a task intentionally, causing an
ABEND.
EXEC CICS ABEND
[ABCODE(name)]
END-EXEC
Description:
ABCODE

used to specify the user abend code (1 to 4 characters).

E.g.:
EXEC CICS ABEND
ABCODE(ERR1)
END-EXEC

Reference Guide

Page 46

CICS Handbook

CICS DATA ACCESS

File Handling

Supports VSAM
BDAM supported in earlier versions of CICS
Files to be defined to CICS as resources
File Opening, Closing done by CICS
Provides interface for
Random access
Sequential access
Read, Write, Update, Delete

The files to be accessed in CICS application programs are to be defined to CICS in the
File Control Table (FCT). The CICS File Control Program (FCP) along with the FCT
provides application programs with services to read, update, add and delete records in a
file.
The file definitions in the application program and the file opening and closing operations
need not be performed.
During record updates CICS provides exclusive control over records to maintain data
integrity.

File Access Methods

VSAM is the primary data access method for CICS

VSAM file types supported
Key Sequenced Data Set (KSDS)
Entry Sequenced Data Set (ESDS)
Relative Record Data Set (RRDS)

ESDS Entry Sequenced Data Set

In a VSAM ESDS, records are maintained in the file in the sequence in which they are
added. Typically, the records are added at the end of the data set.
A record is identified for retrieval by its displacement from the beginning of the data set It is known as the Relative Byte Address (RBA).
Reference Guide

Page 47

CICS Handbook
Records can be updated but their length cannot change.
Records cannot be deleted.

The Relative Byte Address (RBA) is the offset of the record from the beginning of the
data set.
To retrieve records directly in an ESDS, RBA of the records must be known. Normally
RBA of the records are associated with the content of the records.

KSDS - Key Sequenced Data Set

The organization of a KSDS data set includes an index (primary index) and a data
component.
Records can be accessed using a key which has a fixed length and position within each
record. Records can also be retrieved using RBA.
Records can be read sequentially or randomly.
Records are created within the file based on the key value. The records can also be
updated or deleted.
Alternate indexes and paths can be defined for accessing the file in a different order than
the primary index order.

RRDS Relative Record Data Set

The data set consists of a number of fixed length slots, which are sequenced in ascending
relative record number.
A slot can contain record data or it can be empty.
Records can be accessed sequentially or directly by the Relative Record Number (RRN).

Record Identification (RIDFLD)

RECORD KEY
PARTIAL KEY
RELATIVE BYTE ADDRESS (RBA)
RELATIVE RECORD NUMBER (RRN)

Reference Guide

Page 48

CICS Handbook
For accessing the VSAM files, the key field known as the record identification field
(RIDFLD) is required.
The RIDFLD contains the key of the record to be read. Its format and contents vary
depending on the VSAM file organization.

For KSDS files, the key specified can be a full key value or a partial key,
also known as the Generic Key. The length of the generic key must be
provided when using the partial (generic) key. In addition the relative byte
address can also be used, instead of the actual key value.
For ESDS, RIDFLD contains a four byte binary RBA.
For RRDS, RIDFLD contains a four byte binary relative record number.

VSAM File Access

Random Access
Read
Update
Delete
Write
Sequential Read (Browsing)
Start Browsing
Read Next
Read Previous
End Browsing
Reset Browsing conditions
For random access to VSAM/KSDS, the following commands are available:
READ :
To read a record directly
WRITE :
To newly write a record
REWRITE : To update an existing record
DELETE :
To delete a record
UNLOCK : To release exclusive control acquired for update

READ Command
EXEC CICS READ DATASET(file-name)
INTO (rec-area)
[LENGTH(record_length)]
RIDFLD(key-value)
[RBA | RRN]
[GENERIC]
[KEYLENGTH(key-length)]
[UPDATE]
[GTEQ | EQUAL]
END-EXEC.
Reference Guide

Page 49

CICS Handbook
Description:
DATASET is the name of the file which has to be read. This is the symbolic file
name which identifies the FCT entry for the file.
INTO is the name of the data area into which the record is to be read. It is
a structure defined in the working storage of the application program.
LENGTH
is the maximum number of characters that may be read into recarea. It must be defined as halfword binary. COBOL II does not
require a length option if the records are fixed length.
RIDFLD
is the data area containing the key value of the record to be read.
GENERIC For partial key requests, the GENERIC option can be used. The
length of the partial key must be specified in KEYLENGTH option.
EQUAL
means only record whose key exactly matches the key specified in
RIDFLD must be read.
GTEQ
means the first record whose key greater than are equal to the key
specified in RIDFLD must be read.
UPDATE
Record is read for updation or deletion later.
RBA Specifies that the file is ESDS and the RIDFLD option should be
interpreted as the Relative Byte Address.
RRN Specifies that the file is RRDS and the RIDFLD option is RRN

Eg:
WORKING- STORAGE SECTION.
77
77

WS-REC-LEN
WS-FILE-NAME

PIC S9(4) COMP.

PIC X(8) VALUE ACCTMSTR

01

WS-FILE-REC
05 WS-REC-KEY
PIC X(6).
05 WS-REC-DATA PIC X(34).

PROCEDURE DIVISION.
MOVE 40 TO WS-REC-LEN.
MOVE ABC451 TO WS-REC-KEY.
EXEC CICS READ DATASET(WS-FILE-NAME)
INTO (WS-FILE-REC)
RIDFLD(WS-REC-KEY)
LENGTH(WS-REC-LEN)
END-EXEC.
The file ACCTMSTR should have been registered in FILE Control Table (FCT) in
CICS and must be enabled.
After execution WS-FILE-REC will have the data record read from
Reference Guide

Page 50

CICS Handbook
ACCTMSTR, whose key value is ABC451.

WRITE Command
EXEC CICS WRITE
DATASET(file-name)
FROM(file-rec)
LENGTH(rec-length)
RIDFLD(rec-key)
[RBA | RRN]
END-EXEC.
Description:
RIDFLD Specifies the key of the record to be written. If RBA or RRN is
specified, this field is interpreted as a Relative Byte Address or
Relative Record Number respectively.
RBA Specifies that the file is ESDS and the RIDFLD option should be
interpreted as the Relative Byte Address.
RRN Specifies that the file is RRDS and the RIDFLD option should be
interpreted as the Relative Record Number.

File Update
EXEC CICS REWRITE
DATASET (file-name)
FROM (data-area)
[LENGTH (rec-len)
END-EXEC.
Description:
DATASET
FROM
LENGTH

Specifies the name of the file which has to be updated.

Specifies the data-area from which the data is to be
written.
Is a binary halfword that indicates the length of the
record to be re-written. Not required for VS COBOL II.

The REWRITE command is used to update a record already read. Before issuing a
REWRITE command, READ command must have been issued with the UPDATE
option. The key field in the record cannot be changed.
Reference Guide

Page 51

CICS Handbook
Delete From File
EXEC CICS DELETE
DATASET (file-name)
RIDFLD(rec-key)
[KEY-LENGTH(key-length)]
[GENERIC[NUMREC(rec-number)]]
[RBA | RRN]
END-EXEC.
The DELETE command may be issued to delete record(s) from a data set in two ways :
Issued after a READ command with the UPDATE option to delete the
record that is read.
Issued with the RIDFLD option when there is no prior READ with
UPDATE option. This will delete the record whose key matches with the
RIDFLD.
Records from VSAM KSDS and RRDS files can be deleted, but not from VSAM ESDS
files.
The NUMREC option will return the number of records deleted on a GENERIC delete.
KEYLENGTH must be specified for a GENERIC delete.

Browse Option
The browse operation is used for fetching the records sequentially from the underlying
VSAM file based on a selection criteria.
The browse operation consists of three steps :
Establish the position from where to begin the sequential retrieval.
Retrieve records sequentially and process them as required.
Terminate the browse when no further sequential retrieval is required.
The starting position for browse may be re-established at anytime during the browse
operation.
A record that has been retrieved as part of a browse cannot be updated during browse.
For that, browse operation should be terminated and the record should be read again with
update option.

Reference Guide

Page 52

CICS Handbook
The various Browse commands used are:
STARTBR
- Establish Position
The STARTBR command establishes the position within
the file, but does not retrieve a record.
READNEXT
- Retrieve records in the ascending
The READNEXT command retrieves the records
sequentially in the order set by the STARTBR command.
The RIDFLD is automatically updated by CICS for the
next READ; application programs NEED NOT update
this. RIDFLD can be set to a value greater than the
present RIDFLD that is fetched. If a READNEXT is
performed in this manner, it is called skip sequential
processing.
READPREV
- Retrieve Records in Descending
The READPREV command retrieves records in the
reverse order as set by the STARTBR command.
RESETBR
- Change Position
To restart browsing from a different file location. This is
similar to an ENDBR followed by a STARTBR, but is
more efficient because the VSAM resources will be reallocated rather than de-allocation and fresh allocation.
ENDBR
- Terminate Browse
Terminates the browse operation. Normally not required,
but recommended for efficiency sake as the ENDBR will
release the VSAM resources allocated for the browsing.
Eg:
MOVE VALUE TO KEY-REC
EXEC CICS STARTBR FILE(FILEA)
RIDFLD(RECKEY)
RESP(ERR-CODE)
END-EXEC.
IF ERR-CODE = DFHRESP(NORMAL)
PERFORM UNTIL ERR-CODE = DFHRESP(ENDFILE).
PERFORM 2000-REC-FROM-FILE
UNTIL 2000-REC-FROM-FIL-EXIT
EXEC CICS READNEXT FILE(FILEA)
INTO(FILEREC) RIDFLD(RECKEY)
RESP(ERR-CODE)
END-EXEC.
END-PERFORM
EXEC CICS ENDBR FILE(FILEA)
ELSE
Reference Guide

Page 53

CICS Handbook
PERFORM 9000-HANDLE-ERROR ..
END-IF.
The key field is updated after every browse retrieval with the actual key of the record
retrieved.
ENDFILE occurs when a read is issued
After the last record on the file has been retrieved for READNEXT
command
After the first record on the file has been retrieved for READPREV
command.
The file position can be changed by moving the new key value to the
RIDFLD before READNEXT or READPREV command.

contents of

File Handling Exception Conditions

Following Exceptional Conditions to be handled
NOTFND
LENGERR

FILENOTFOUND DISABLED
NOTOPEN
NOSPACE
INVREQ
-

ILLOGIC

Reference Guide

Record with specified key is not in the use.

The length of the record to be rewritten is either too long
or not specified.
File name is not in FCT.
File has status of disabled.
File is closed.
There is no space on the file for write or rewrite.
There are several reasons for this exception condition
No previous READ UPDATE issued for REWRITE.
Second REWRITE issued before releasing the exclusive
control of the first REWRITE.
This identifies VSAM error not covered by other CICS
exceptional conditions. The 2nd byte of the EIBRCODE
contains the VSAM error code

Page 54

CICS Handbook
File Handling Program Organization
WORKING STORAGE
RECORD LAYOUT DEFINITION
RECORD ID FIELD
LINKAGE SECTION
EIB
PROCEDURE DIVISION
IDENTIFY KEY OF THE RECORD TO BE READ
EXEC CICS READ FILE....

All the VSAM files used in a CICS application program should be

registered in the File Control Table (FCT).
The FCT entry contains all the required information for that file.
The application programmer does not need to define the physical
organization and other attributes of the file in the program.
The files are opened immediately after system initialization, if it is
specified as such in the FCT definition.
They can also be opened using the master terminal transaction (CEMT).
So, opening a file is not the responsibility of the application program.

CICS Database Access

Provides Interface to
Hierarchical Database - IMS/DB
Relational Database - DB2
CICS provides the required interface for the application programs to access databases
other than VSAM files. It provides the required interface to DB2 and DL/I databases.
DB2 and CICS execute as separate sub-systems under MVS. When a database call in the
form of an EXEC SQL .END-EXEC statement is issued in a CICS application
program, CICS passes the statement to the DB2 subsystem. DB2 processes the statement
and returns the results to CICS which is in turn made available to the application
program.

Reference Guide

Page 55

CICS Handbook
CICS manages such communications with DB2 with a special interface modules called
the CICS/DB2 Attachment Facility. These modules are loaded into storage along with
other CICS modules. When SQL statements are requested from CICS application
programs, CICS requests that the attachment facility establish a connection with DB2
known as a thread.
To facilitate DB2 to access the database tables through the CICS application program
(CICS transaction), the connection between the CICS transaction and DB2 is made
through a set of definitions in one of the CICS Control Tables known as Resource
Control Table (RCT). The RCT contains the list of CICS transactions that request DB2
services. For each transaction, the DB2 application plan, the DB2 authorizations for
CICS, etc., are maintained in the RCT. The total no. of threads that will be available
between CICS and DB2 is also maintained.

CICS - DB2 Program Preparation

Pre-compilation is an additional step to be performed prior to the translation of the CICS
program. It generates the Database Request Module (DBRM) which is a collection of all
the SQL statements in the program.
The DBRM is the input for the Bind process along with parameters that define how DB2
should lock resources, when the authorizations should be validated, when the allocation
and release of resources are to be done, etc. The output of the bind will result in a plan or
package that defines how DB2 will access the data required.
The Link-edit step has to include the interface to the CICS-DB2 attachment facility DSNCLI. This and all other object modules will be link-edited into a load module.
DB2 Rollback and DB2 Commit should NOT be coded in CICS-DB2 programs.
Source Program Precompile (PreCompile Listing) Translate (Translator Listing)
Translated Source Compile (Compiler Listing) Object Module Link-Edit
Load Module
Also Precompile DBRM Bind Application Plan
CICS provides an interface to DL/I, independent of IMS. Through this
interface, all DL/I services can be used under CICS.
The Command format for accessing DL/I database is :.
EXEC DLI function
[options]
END-EXEC.

Reference Guide

Page 56

CICS Handbook
Where function is a DL/I function and options are the options of the DL/I service.

Files - Database Tables

New feature of storing VSAM files in virtual storage
Improved performance
User Maintained Table(UMT)
CICS Maintained Table (CMT)
Shared Data Tables
Transparent to application program
To provide better performance while accessing files, CICS provides the facility of data
tables which is nothing but a virtual storage copy of a VSAM file stored in disk.
At start-up, CICS copies the records from the VSAM file(s), known as the source data
set, into the data table. Any access to the file will be done from the virtual storage rather
than from the disk thus improving performance.
The data tables are classified as: CICS Maintained Data Tables (CMT) and User
Maintained Data Table (UMT) and Shared Data Tables.
In the case of a CMT, whenever any updates are made to the table, CICS automatically
updates records in the source data set.
In an UMT, CICS will NOT update records in the source data set - it has to be done by an
application program.
Shared Data Tables can be accessed by more than one CICS system. This is done by
placing the data table in a separate address space that can be accessed by different CICS
regions under the same MVS system.
The definition of a file whether a file is an ordinary file or a CMT or an UMT is done in
the File Control Table (FCT).

Reference Guide

Page 57

CICS Handbook
CICS Queue Handling
The Queues can be classified into two kinds namely:
Temporary storage Queue (TSQ) and
Transient Data Queue (TDQ)
The queuing facilities are provided by the CICS Control Programs - Temporary Storage
Program and Destination Control Program. These control programs along with the
Temporary Storage Table (TST) and Destination Control Table (DCT) offer the above
queuing facilities.
As the name indicates, Temporary Storage is the place where an application program can
store data temporarily. Temporary Storage is divided into Temporary Storage Queues
(TSQs). Each queue contains one or more records, known as items. A TSQ is identified
by a 1 - 8 character queue name. TSQs are stored in a single ESDS VSAM file.
Another queuing facility provided by CICS is the Transient Data Queue (TDQ) facility.
As the name indicates, the information in TDQ is transient, i.e., once read, the
information is lost. The TDQ facility can be used for scheduling/starting CICS tasks
automatically. TDQs are identified by a 1 - 4 character queue name. Unlike TSQs, TDQs
are to be defined in the Destination Control Table (DCT)

Temporary Storage Queue (TSQ)

Additional storage facility for a transaction

Variable length record
Queue IDs Need not be predefined
Queues can be defined as Recoverable
Random or Sequential Access
Records can be updated
Data In TSQ remains until it is deleted
Can be used as a scratchpad area

TSQs can be created in main or auxiliary storage. TSQs in main storage can be accessed
fast. However due to the limited storage available for CICS, it is recommended that
auxiliary storage be used for creating TSQs.
TSQs in auxiliary storage can be defined as recoverable but TSQs in main storage are not
recoverable. TSQs which are to be treated as recoverable need to be pre-defined in the
Temporary Storage Table (TST).
Records of variable length upto 32768 can be written in a TSQ. Once written, the records
in TSQ remain accessible until the entire TSQ is explicitly deleted.

Reference Guide

Page 58

CICS Handbook
The records in TSQ can be read sequentially or randomly. Records in a TSQ can also be
updated.
TSQs can be accessed by any transaction in the same CICS region.

Temporary Storage - Output

EXEC CICS WRITEQ TS
QUEUE(queue-name)
FROM(data-area)
LENGTH(queue-length)
[ITEM(data-area)]
[REWRITE]
[MAIN|AUXILIARY]
END-EXEC.
Description:
QUEUE

Specifies the name (1- 8 characters) of the temporary storage where the
data is written.
FROM
Specifies the data area that contains the record to be written.
LENGTH
Specifies the length in binary halfword, of the FROM area.
ITEM
Specifies the item number which is being written or updated.
REWRITE Specifies that an existing record as indicated by ITEM is being updated.
MAIN
Specifies that the TSQ will reside in the main storage.
AUXILIARY Specifies that the TSQ will reside on disk in the temporary storage file
(DFHTEMP).

Temporary Storage Input

EXEC CICS READQ TS
QUEUE(queue-name)
INTO (data-area)
LENGTH(data-area)
[ ITEM(data-area) | NEXT ]
[ NUMITEMS(data-area) ]
END-EXEC.
Description:
NEXT

This option is used to retrieve records sequentially. This option specifies

that the next record in the sequence should be read.
ITEM
For direct retrieval, you must specify the item number of the record in this
option.
NUMITEM If this option is coded, number of items in the queue is placed in this filed.
Reference Guide

Page 59

CICS Handbook

Temporary Storage Deletion

EXEC CICS
DELETEQ TS
QUEUE(queue_name)
END-EXEC.
This command is used to delete all the records in the temporary storage queue and release
the associated storage.
It is important to issue this command at the earliest possible time, especially when the
main storage is used.
Deleting an individual record in a temporary storage queue is not possible.

TSQ Exceptional Conditions

ITEMERR

The specified item number is not found. In sequential read,

this condition occurs if the end of a TSQ is reached.
NOSPACE - Sufficient space is not available. The default action is to
suspend the task until space becomes available.
QIDERR - Queue Name specified in READTS or DELETE TS command
is not found.
Eg:
WORKING-STORAGE SECTION.
01 WS-TSQ-DTLS.
05 WS-TS-REC-LEN
PIC S9(4) COMP.
05 WS-TS-ERR-CODE
PIC S9(8) COMP.
05 WS-TS-ITEM-NO
PIC S9(4) COMP.
05 WS-TS-ID
PIC X(8).
01 WS-TSG-DATA

PIC X(80).

PROCEDURE DIVISION.
STRING EIBTRMID EIBTRNID DELIMITED SIZE INTO WS-TS-ID
EXEC CICS WRITEQ TS QUEUE(WS-TS-ID)
FROM(WS-TSQ-DATA) LENGTH(WS-TS-REC-LEN)
ITEM(WS-TS-ITEM-NO) RESP(WS-TS-ERR-CODE)
END-EXEC.

Reference Guide

Page 60

CICS Handbook
IF WS-TS-ERR-CODE NOT EQUAL DFHRESP(NORMAL)
PERFORM 9000-ERROR-PARA
END-IF
In the example shown above, the temporary storage ID is dynamically created. The first
four characters contain the terminal id obtained from EIB field EIBTRMID and the last
four characters contain the transaction id. This results in a unique TSQ-ID for a
transaction executing at different terminals.
After the WRITEQ TS command is executed, the field WS-TS-ITEM-NO will contain
the number of the record just written.
In a pseudo-conversational design, temporary storage may be used to hold the record data
that is presented to the user in the first part of the conversation.
When the record is read for the update in the second part of the conversation, it is
compared against the saved record data retrieved from temporary storage.
If the record was not modified by some other task, the update process continues.
Otherwise, the user should be notified that the record data has changed and should choose
what to do next.

Transient Data Queue (TDQ)

The CICS Transient data control program allows a CICS transaction to deal with
sequential data called Transient data files also known as Transient Data Queues (TDQ).
There are two types of TDQs.
Intrapartition TDQ: An intrapartition TDQ is a group of sequential records
produced and processed by the same or different transactions within a CICS
region.
Extrapartition TDQ: An extrapartition TDQ is a group of sequential records
which interfaces between the transactions of the CICS region and the systems
outside of the CICS region.
Regardless of the type, a TDQ is identified by a 1 to 4 character identifier called
Destination id.
The destination id must be registered in the Destination control table (DCT).
The commands available for operations on TDQ are almost same for both types.

Reference Guide

Page 61

CICS Handbook
TDQ Intrapartition

All queues share the same VSAM data set (ESDS)

Reading a TDQ is destructive.
Read is sequential - No random access
Updates not possible
Records in a TDQ can be of variable length
TDQ is associated with a transaction
Trigger levels can be specified for Automatic task initiation
Queue can be specified as
Logically or physically recoverable
Not recoverable

All Intrapartition TDQs are stored in only one physical file (VSAM -ESDS) in a CICS
region
Only sequential access is allowed for a queue. Once a record is read from the queue it
will be logically removed from the queue and it cannot be read again. The records can be
of variable length.
Each TDQ is to be defined in the DCT as Intrapartition. Additionally, a CICS transaction
can be defined with the TDQ along with the trigger level. When the number of entries in
a TDQ reaches the trigger level, CICS automatically initiates the transaction associated
with the TDQ. This is known as Automatic Task Initiation. CICS will initiate only one
task per TDQ. It is the responsibility of the application program to read records from the
queue recursively and deplete the queue.
The TDQ can be defined as recovery is required or not.

TDQ Intrapartition DCT Entry

DFHDCT

TYPE = INTRA ,
DESTID=queue-name,
[TRANSID=txn-id-name,]
[TRIGLEV=number,]
[REUSE=YES|NO]

DCT entries can be defined using the macro DFHDCT.

Description:
TYPE=INTRA
DESTID

Indicates that TDQ is an intrapartition TDQ.

Defines the name of the TDQ ( 1 to 4 chars).

Reference Guide

Page 62

CICS Handbook
REUSE

Once a record of intrapartition TDQ is read, the record

is logically removed. But it still occupies the space. If
REUSE = YES is specified, this space for logically
deleted record will be used for other TDQ records. But
the records are not recoverable. If REUSE=NO, the
records are recoverable.

TRANSID &
TRIGGER LEVEL Used for automatic task initiation (see next page)

ATI Automatic Task Initiation

Automatic task initiation (ATI) is a facility through which a CICS transaction can be
initiated automatically. When the number of records in an intrapartition TDQ reaches the
trigger level specified, ATI occurs.
The transaction ID to be triggered must be defined in the DCT entry of the
intrapartition TDQ, with nonzero trigger level.
In the example, the task TRNA writes into the TDQ - TDQA. The DCT entry for this
destination, TDQA, contains TRNB as the transaction ID and trigger level as 2. As soon
as the number of records in TDQA reaches 2, the transaction TRNB will be
automatically initiated.

TDQ Extrapartition

Each destination is a physical data set

Destination can be input or output (not both)
Automatic task initiation not supported
Only sequential access

Extrapartition TDQs are used to interface batch programs with CICS applications.
Each extrapartition TDQ is a separate physical file and it may be on the disk, tape or
printer. Each extrapartition file (i.e. TDQ) must be open within the CICS region when it
is used by the CICS transaction. The DCT entry determines the initial OPEN|CLOSE
status of the file. The file can also be opened or closed through the Master terminal
transaction (CEMT) during a CICS session.

Reference Guide

Page 63

CICS Handbook
TDQ Extrapartition - DCT Entry
DFHDCT

DFHDCT

TYPE = EXTRA ,
DESTID=queue_name,
DSCNAME=name,
[OPEN]=INITIAL|DEFERED]
TYPE=SDSCI,
DSCNAME=name,
TYPEFILE=INPUT|OUTPUT|RDBACK

Description:
TYPE=EXTRA

Indicates its an extrapartition TDQ.

DESTID

Defines the name of the TDQ (1 to 4 characters).

OPEN

Defines the initial file status. If INITIAL is specified the file will
be opened at CICS start up time. If DEFERED is specified the file
will be closed until it is specifically opened by the CEMT
transaction.

DSCNAME

Defines the data control block name. For every DSCNAME a

corresponding DFHDCT entry must be made with TYPE=SDSCI
and the same DSCNAME. This in effect indicates the DDname of
the extrapartition dataset in the JCL of the CICS job.

Transient Storage Commands

WRITEQ TD

To sequentially write a record in a TDQ.

READQ TD

To sequentially read a record in a TDQ.

DELETEQ TD :

To delete an intrapartition TDQ. Not valid for

extrapartition TDQ.

Transient Storage Output

EXEC CICS WRITEQ TD
QUEUE(queue-name)
FROM(queue-data)
LENGTH(queue-length)
END-EXEC.
Description:
queue-name

is the name of the TDQ as in the DCT.

Reference Guide

Page 64

CICS Handbook
queue-data

is the name of the working storage variable from which

data is to be written.

queue-length indicates the length of the record.

Transient Storage Output

EXEC CICS READQ TD
QUEUE(Q-name)
INTO (Q-data)
LENGTH(Q-length)
END-EXEC.
Description:
Q-name

is the name of the TDQ as in the DCT.

Q-data

is the name of the working storage variable from which

data is to be written.

Q-length

indicates the length of the record.

Transient Storage Deletion

EXEC CICS
DELETEQ TD
QUEUE(name)
END-EXEC.
The DELETEQ TD command applies only to intrapartition transient queues.
It is used to delete all the records associated with the named destination. All storage
associated with the queue on the intrapartition dataset is released.
Deletion of individual records is not possible.

Reference Guide

Page 65

CICS Handbook
Exception Conditions:
QZERO

: Indicates empty TDQ or end of the TDQ.

LENGERR : The length specified is greater than the maximum record length specified
in DCT.
NOSPACE : No space on the intrapartition data set.
NOTOPEN : Extrapartition destination is closed.
QBUSY

: Attempt to access a record in an intrapartition TDQ that is being written to

or deleted by another task.

QIDERR

: The destination ID specified in READ TD, WRITE TD or DELETE TD is

not a valid destination ID.

CICS IBM Supplied Transactions

Some of the commonly used CICS testing /debugging utilities are,

CESN : CICS-supplied Extended Sign-on transaction. It allows a user to start

a CICS session.
CESF : CICS-supplied Sign-off transaction. This terminates a CICS session.
CECI : CICS-supplied Command Interpreter transaction. It verifies the syntax
of a CICS command and executes the command.
CEDF : CICS-supplied Execution Diagnostic Facility transaction. It provides
interactive program execution and debugging functions of a CICS
program.
CEMT : CICS-supplied Extended Master Terminal transaction. It displays or
manipulates CICS control environment interactively.
CEBR : CICS-supplied Temporary Storage Browse transaction. It displays
the content of Temporary Storage Queue.

Reference Guide

Page 66