CICS Handbook - Reference V1.5

TCS

CICS Handbook Study Material

Juhi Gaur

CICS Handbook

Reference Guide Page 2

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

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

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

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)

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.

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.

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.

TASK 1 TASK 2

TXNA TXNA

working storage for task 1

working storage fortask 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.

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.

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.

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. FCP File Control Program 2. JCP Journal Control Program 3. KCP Task Control Program 4. PCP Program Control Program 5. SCP Storage Control Program 6. TCP Terminal Control Program 7. TDP Transient Data Program 8. TSP Temporary Storage Program, etc

MVS

CICS App. Pgms

.

VTAM / TCAM

VSAM/ DB

CICS Handbook


CICS Control Tables (User-Specified)

1. FCT File Control Table 2. JCT Journal Control Table 3. PCT Program Control Table 4. PPT Processing Program Table 5. TCT Terminal Control Table 6. DCT Destination Control Table 7. TST Temporary Storage Table, etc Actually, the core portion of CICS (called the CICS nucleus) consists of IBM-supplied 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.

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.

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 Function & Bit Settings 0, 1 Value determined by the contents of bits 2 to 7. 2 0 - Unprotected 1 - Protected 3 0 - Alphanumeric 1 - Numeric 2, 3 11 Auto-skip 4, 5 00 Normal Intensity / Non-detectable 01 - Normal Intensity / Detectable 10 - High Intensity / Detectable 11 Dark / Non-detectable 6 0 - Must be zero 7 0 Not Modified (MDT off) 1 - Modified (MDT on)

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

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 Map 1 DFHMDF Field Definition in a Map - Field 1 DFHMDF Field Definition in a Map - Field 2

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

DFHMSD Mapset Definition - End

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, X LANG=COBOL,TIOAPFX=YES The BMS macro rules are similar to those of assembler language statements. The following is the pattern :

CICS Handbook


LABEL Op-Code Parameters LABEL :

specifies the symbolic name specified in Column 1 Must begin with a letter Can be upto seven characters long

Op-Code :

Specifies the instruction to be executed - DFHMSD, DFHMD or DFHMDF

Begins in Column 10 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 Specifies the Mapset name , 1-7 chars long. It must be specified as the

symbol to the DFHMSD macro. TYPE 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. MODE To indicate input/output operation.

CICS Handbook


MODE=IN For the input map MODE=OUT 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) LANG To define the language of the application program (COBOL, ASM, PLI, or RPG) TERM Required if other than the 3270 terminal is used. This ensures device

independence by means of providing the suffix. STORAGE 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.)

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

CTRL Specifies the control options in effect for each map. FREEKB To unlock the keyboard. ALARM To set an alarm at screen display time i.e. it results in audio

alarm to sound whenever a map is sent to the terminal. FRSET To reset MDT to zero (i.e. not modified) status.

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

CICS Handbook


STORAGE=AUTO, X TIOAPFX=YES, X CTRL= ( FREEKB,FRSET) X

DFHMDI Macro mapname DFHMDI SIZE=(lines,columns), LINE=line_number, COLUMN=column_number, JUSTIFY={ LEFT | RIGHT }, CTRL=(ctrl1,ctrl2...) Description: mapname Specifies the map name as the symbol, 1 - 7 chars. SIZE(ll,cc) Specifies the size of the map in line size (ll) and column size (cc). Usually coded as SIZE=(24,80) for 24x80 screen. LINE Specifies the starting position of the map in line number. COLUMN Specifies the starting position of the map in column number. JUSTIFY To specify the map to be LEFT justified or RIGHT justified. CTRL 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 Specifies a 1 - 7 character field name for the field. If not specified, the field is not included in the symbolic map. POS(ll,cc) Specifies the starting position of the field in the line number(ll) and

column number(cc) including the attribute character. LENGTH Specifies the length of the field. (This does not include the attribute byte for the field.) INITIAL Specifies the initial value for the field. If omitted, the default is hexadecimal zeroes(LOW-VALUES). COLOR Specifies the fields color. Can specify BLUE, RED, PINK, GREEN TURQUOISE, YELLOW or NEUTRAL. If omitted, the default terminal color is assumed.

CICS Handbook


HILIGHT Specifies the fields extended highlighting. Valid values are: BLINK, REVERSE, UNDERLINE and OFF. Default is OFF. ATTRB 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

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 re-entered, 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.

CICS Handbook


Ending a Mapset Definition Col. Col. Col. Col 1 9 16 72 +---------------+--------------+-----------------------------------------------+ DFHMSD TYPE=FINAL END DFHMSD TYPE=FINAL specifies the end of the mapset definition. As in the case of assembler, the statement END is also required for BMS macro instructions. Once completed, the BMS macro instructions can be assembled. The instructions are assembled twice:

for generation of the physical map and for generation of the symbolic map

The physical map is a load module which must be defined in the PPT. The symbolic map will be a copy library of COBOL variable names which must be included in the COBOL program which will be using the map.

Symbolic Map Contents

Two 01-level items generated based on map name 01-level Item names suffixed with I or O for Input & Output respectively Additional level items defined for

Field for Length Field for Attribute Field for Modified Data Indication Field for Input data Field for Output Data.

01-level Item for Output REDEFINES Input area.

Field Characteristic Suffix Example Length Binary Halfword (S9(4) COMP) L NAMEL Attribute Single Char (PIC X) A NAMEA Field Single Char (PIC X) F NAMEF Modification Input Field As defined in Map I NAMEI Output Field As defined in Map O NAMEO

CICS Handbook


Code for Sample Layout MAPSETS DFHMSD TYPE=&SYSPARM,MODE=INOUT,TERM=ALL, X LANG=COBOL,TIOAPFX=YES,STORAGE=AUTO MAPSMP DFHMDI SIZE(24,80),LINE=1,COLUMN=1 DFHMDF POS(8,7),LENGTH=10,INITIAL=NAME :, X 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 :, X 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 :, X 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 1-byte 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.

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

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.

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.

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

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.

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) MAPSET(MAPSETS) END-EXEC EVALUATE TRUE W HEN EIBAID = DFHPF12 EXEC CICS RETURN END-EXEC W HEN EIBAID = DFHENTER PERFORM 1000-PROCESS-DATA THRU 1000-PROCESS-DATA-EXIT

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

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 data-area.

CICS Handbook


Structure of CICS application program IDENTIFICATION DIVISION. PROGRAM-ID . XXXXXXXX. ENVIRONMENT DIVISION.

CICS Handbook


- Any I/O statements ( OPEN ,CLOSE, READ, WRITE, REWRITE, DELETE , START)

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.

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.

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.

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)

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)

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.

CICS Handbook


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

Error conditions in Program Control Commands INVREQ TRANSID is specified on a RETURN command in a program that was not at the highest logical level ( i.e.., a RETURN that would not terminate the transaction by returning control to CICS ) LENGERR The length of the data specified using the RETURN command with length option is outside the valid range of 1 to 32763. NOAUTH Resource or command security check has failed. PGMIDERR The program to which control is passed on a LINK or XCTL command, cannot be found in the list of installed program definitions, or it is not in the library or it has been disabled.

CICS Handbook


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

Interval Control The Interval Control Features provided by the CICS interval control program (ICP) are:

providing the current date and time in the desired formats (supported by CICS),

Task initiation at specific time or after an interval

Interval control commands

o ASKTIME To request current data and time.

o FORMATTIME To select format of date and time.

o DELAY To delay the processing of a task.

o START To initiate a transaction from current task.

o RETRIEVE To retrieve data passed by START command.

o CANCEL To cancel the effect of the previous interval control

command

CICS Handbook


Starting an Asynchronous transaction using START command The START command is used to start a transaction at the specified terminal and at the specified time or interval. Optionally, data can be passed to the to-be-initiated transaction.

EXEC CICS START TRANSID(data-value) [ TIME(hhmmss) | INTERVAL (hhmmss)] [ REQID(NAME)] [ FROM(data-area) [ LENGTH(data-value) [FMH]] [ TERMID(data-value)] END-EXEC

Description: TRANSID defines the transaction id of the transaction to be initiated. TIME or INTERVAL indicates the time or time interval of the transaction initiation,

respectively, in the form of hhmmss. If omitted, the transaction will be initiated immediately. If the time specified in the TIME parameter has expired, then also, the transaction will be initiated immediately.

REQID Specifies an 8 byte value that identifies this START command so that the

started task can be cancelled with a CANCEL command. If omitted, CICS still generates the REQID and the same is available in the EIB variable EIBREQID.

FROM Specifies the data area which contains the data to be passed, i.e. to pass a

field in the Working Storage Section. LENGTH The length of the data-area should be specified in the LENGTH option. TERMID defines the terminal id of a terminal against which you initiate the

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

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

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. LENGTH It indicates the LENGTH of the INTO field. 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.

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 To suspend a task. o ENQ To gain exclusive control over a resource o DEQ 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:

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.

ERROR The general error condition can be specified within the same list to specify

that all other conditions cause control to be passed to the label specified. Although more than one HANDLE CONDITION can be issued in a program, no more than 12 conditions can be specified in a single HANDLE CONDITION command. Scope: The HANDLE CONDITION command for a given condition applies only to the program in which it is specified.

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

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.

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

CICS Handbook - Reference V1.5

Documents

Transcript of CICS Handbook - Reference V1.5