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
TXNA working storage for task 1

TASK 2
TXNA 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 2 Function & Bit Settings Value determined by the contents of bits 2 to 7. 0 - Unprotected 1 - Protected 0 - Alphanumeric 1 - Numeric 11 Auto-skip 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)

2, 3 4, 5

6 7

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 X

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

CICS Handbook
LABEL LABEL : Op-Code : Parameters : Specifies the instruction to be executed - DFHMSD, DFHMD or DFHMDF Begins in Column 10 specifies the symbolic name specified in Column 1 Must begin with a letter Can be upto seven characters long 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] 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])]

Description: setname TYPE

MODE

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. Page 15

Reference Guide

CICS Handbook
MODE=IN MODE=OUT 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.

LANG TERM STORAGE

TIOAPFX

CTRL

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. Page 17

Reference Guide

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. Characteristic Binary Halfword (S9(4) COMP) Single Char (PIC X) Single Char (PIC X) Suffix L A F Example NAMEL NAMEA NAMEF

Field Length Attribute

Field Modification Input Field Output Field Reference Guide

As defined in Map As defined in Map

I O

NAMEI NAMEO 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. X

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. DATA DIVISION. WORKING- STORAGE SECTION. 77 --------------------- . 01 --------------------- . 05 ---------------- . LINKAGE SECTION. 01 DFHCOMMAREA. 05 -----------------. 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 - DISPLAY - STOP RUN - EXHIBIT - TRACE <=== LINKAGE SECTION IS MANDATORY <=== COMMUNICATION AREA reqd for passing data for subsequent execs. <=== THIS DIVISION MUST BE EMPTY <=== FILE SECTION IS OMITTED

Reference Guide

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. Page 31

Reference Guide

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 ) The length of the data specified using the RETURN command with length option is outside the valid range of 1 to 32763. Resource or command security check has failed.

LENGERR

NOAUTH

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 o FORMATTIME o DELAY o START o RETRIEVE command. o CANCEL command To request current data and time. To select format of date and time. To delay the processing of a task. To initiate a transaction from current task. To retrieve data passed by START

To cancel the effect of the previous interval control

Reference Guide

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. Specifies the data area which contains the data to be passed, i.e. to pass a field in the Working Storage Section. The length of the data-area should be specified in the LENGTH option. 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.

FROM

LENGTH TERMID

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

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.

ERROR

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. to reactivate the previously cancelled HANDLE ABEND r request.

RESET

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 E.g.: EXEC CICS ABEND ABCODE(ERR1) END-EXEC

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

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 01 WS-REC-LEN WS-FILE-NAME PIC S9(4) COMP. PIC X(8) VALUE ACCTMSTR

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

FILENOTFOUND DISABLED NOTOPEN NOSPACE INVREQ -

ILLOGIC

Reference Guide

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). Page 62

Reference Guide

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 TYPE = EXTRA , DESTID=queue_name, DSCNAME=name, [OPEN]=INITIAL|DEFERED] TYPE=SDSCI, DSCNAME=name, TYPEFILE=INPUT|OUTPUT|RDBACK

DFHDCT

Description: TYPE=EXTRA DESTID OPEN

Indicates its an extrapartition TDQ. Defines the name of the TDQ (1 to 4 characters). 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. 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.

DSCNAME

Transient Storage Commands

WRITEQ TD READQ TD : : To sequentially write a record in a TDQ. To sequentially read a record in a TDQ. To delete an intrapartition TDQ. Not valid for extrapartition TDQ.

DELETEQ TD :

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. Page 64

Reference Guide

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 Q-data

is the name of the TDQ as in the DCT. is the name of the working storage variable from which data is to be written. indicates the length of the record.

Q-length

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. : The destination ID specified in READ TD, WRITE TD or DELETE TD is not a valid destination ID.

QIDERR

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