TCS
CICS Handbook Study Material Juhi Gaur
CICS Handbook
Table of Con tents TABLE OF CONTENTS................... CONTENTS................................. ............................ ............................ ............................ ............................ ............................ ............................ .......................2 .........2 INTRODUCTION.......................... INTRODUCTION........................................ ............................ ............................ ............................ ............................ ............................ ............................ ...........................4 .............4 BMS (BASIC MAPPING SUPPORT)...................... SUPPORT).................................... ............................ ............................ ............................ ............................ .........................11 ...........11 UNCTIO NS .............. PRIMARY FUNCTIO ............................ ............................ ............................ ............................ ............................ ............................ ............................ ............................ ................ 11 MAPSET AND MAP .............. ............................ ............................ ............................ ............................ ............................ ............................ ............................ ............................ .................... ...... 13 MAP TYPES ............. ........................... ............................ ............................ ............................ ............................ ............................ ............................ ............................ ............................ ................. ... 13
Map Definition Definition Macros.................................. Macros................................................ ............................ ............................ ............................ ............................ ............................ ................ 13 BMS Macro Rules Rules ............................ .......................................... ............................ ............................ ............................ ............................ ............................ ............................ ................ 14 DFHMSD Macro Macro .................... .................................. ............................ ............................ ............................ ............................ ............................ ............................ ........................ .......... 15 DFHMDI Macro Macro ............................ .......................................... ............................ ............................ ............................ ............................ ............................ ............................ ................. ... 17 DFHMDF Macro ........................... ......................................... ............................ ............................ ............................ ............................ ............................ ............................ ................. ... 17 MDT’s and their their manipulation manipulation ........................ ...................................... ............................ ............................ ............................ ............................ ........................... ............. 18 MDT Manipulation Manipulation – FRSET........................... FRSET......................................... ............................ ............................ ............................ ............................ ........................... ............. 19 Ending a Mapset Definition............. Definition ........................... ............................ ............................ ............................ ............................ ............................ ............................ ................ 20 Symbolic Map Contents ............................ .......................................... ............................ ............................ ............................ ............................ ............................ .................... ...... 20 Code for Sample Layout.......................... Layout........................................ ............................ ............................ ............................ ............................ ............................ ...................... ........ 21 Symbolic Map for Sample Layout ........................... ......................................... ............................ ............................ ............................ ............................ .................... ...... 22 I/O Operations........................................ Operations...................................................... ............................ ............................ ............................ ............................ ............................ ...................... ........ 24 AIDKEY ........................... ......................................... ............................ ............................ ............................ ............................ ............................ ............................ ............................ ................. ... 27 APPLICATION PROGRAMMING...................... PROGRAMMING.................................... ............................ ............................ ............................ ............................ ............................28 ..............28
CICS COMMAND FORMAT .............. ............................ ............................ ............................ ............................ ............................ ............................ ............................ ...................... ........ 28 Argument Values......................... Values....................................... ............................ ............................ ............................ ............................ ............................ ............................ .................... ...... 28
STRUCTURE OF CICS APPL ICATION PROGRAM .............. ............................ ............................ ............................ ............................ ............................ .................... ...... 30 EXEC I NTERFACE BLOCK (EIB) ............. ........................... ............................ ............................ ............................ ............................ ............................ ........................... ............. 31 STORAGE TYPES ............. ........................... ............................ ............................ ............................ ............................ ............................ ............................ ............................ ........................ .......... 31 CICS PROGRAM CONTROL ............................ .......................................... ............................ ............................ ............................ ............................ ............................ ................33 ..33
PROGRAM TO PROGRAM TRANSITION ............. ........................... ............................ ............................ ............................ ............................ ............................ .................... ...... 33 LINK Command Command .......................... ........................................ ............................ ............................ ............................ ............................ ............................ ............................ .................... ...... 33 XCTL Command Command ..................... ................................... ............................ ............................ ............................ ............................ ............................ ............................ ........................ .......... 35 RETURN Command............. Command ........................... ............................ ............................ ............................ ............................ ............................ ............................ ........................... ............. 36 Static Call ............................ .......................................... ............................ ............................ ............................ ............................ ............................ ............................ ........................... ............. 36 Dynamic Call........................................ Call...................................................... ............................ ............................ ............................ ............................ ............................ ........................ .......... 36 Conversational modes............................. modes........................................... ............................ ............................ ............................ ............................ ............................ ...................... ........ 37 Error conditions conditions in Program Control Commands Commands ............................ .......................................... ............................ ............................ ...................... ........ 37 INTERVAL AND TASK CONTROL .......................... ........................................ ............................ ............................ ............................ ............................ .....................38 .......38
I NTERVAL CONTROL .............. ............................ ............................ ............................ ............................ ............................ ............................ ............................ ............................ ................. ... 38 Interval control control commands ............................ .......................................... ............................ ............................ ............................ ............................ ............................ ................ 38 Starting an Asynchronous transaction using START command............................. command............................................ ............................. .............. 39 Retrieving data data in a STARTed STARTed Transaction – RETRIEVE RETRIEVE Command............. Command ........................... ............................ ...................... ........ 40 CANCEL Command Command ........................... ......................................... ............................ ............................ ............................ ............................ ............................ ........................... ............. 40
TASK CONTROL .............. ............................ ............................ ............................ ............................ ............................ ............................ ............................ ............................ ........................ .......... 41 Task Control Command ............................ .......................................... ............................ ............................ ............................ ............................ ............................ .................... ...... 41 SUSPEND Command.............................. Command............................................ ............................ ............................ ............................ ............................ ............................ ...................... ........ 41 ENQ and DEQ DEQ Commands ............................ .......................................... ............................ ............................ ............................ ............................ ............................ ................ 41 EXCEPTION AND ERROR HANDLING ............................ .......................................... ............................ ............................ ............................ .........................42 ...........42
EXCEPTION HANDLING .............. ............................ ............................ ............................ ............................ ............................ ............................ ............................ ........................... ............. 42 HANDLE CONDITION CONDITION Command ............................ .......................................... ............................ ............................ ............................ ............................ ................. ... 42
Reference Guide
Page 2
CICS Handbook IGNORE CONDITION CONDITION Command .......................... ........................................ ............................ ............................ ............................ ............................ .................... ...... 43 NOHANDLE NOHANDLE Option .......................... ........................................ ............................ ............................ ............................ ............................ ............................ ........................... ............. 43 RESP Option Option ........................... ......................................... ............................ ............................ ............................ ............................ ............................ ............................ ........................ .......... 44 PUSH and POP Commands......................... Commands....................................... ........................... ........................... ............................ ............................ ............................ .................. .... 44 System Default action ........................... ......................................... ............................ ............................ ............................ ............................ ............................ ........................ .......... 45 HANDLE ABEND Command................................ Command.............................................. ............................ ............................ ............................ ............................ ...................... ........ 45 ABEND Command Command ........................... ......................................... ............................ ............................ ............................ ............................ ............................ ............................ ................ 46 CICS – DATA ACCESS ........................... ......................................... ............................ ............................ ............................ ............................ ............................ ............................47 ..............47
FILE HANDLING .............. ............................ ............................ ............................ ............................ ............................ ............................ ............................ ............................ ........................ .......... 47 File Access Methods .......................... ........................................ ............................ ............................ ............................ ............................ ............................ ........................... ............. 47 ESDS – Entry Sequenced Data Set.............. Set............................ ............................ ............................ ............................ ............................ ............................ .................. .... 47 KSDS - Key Sequenced Data Set............................. Set........................................... ............................ ............................ ............................ ............................ .................... ...... 48 RRDS – Relative Relative Record Data Data Set ............... ............................. ........................... ........................... ............................ ............................ ............................ .................. .... 48 Record Identification Identification (RIDFLD)............... (RIDFLD)............................. ............................ ............................ ............................ ............................ ............................ .................... ...... 48 VSAM File Access.......................... Access........................................ ............................ ............................ ............................ ............................ ............................ ............................ ................. ... 49 READ Command....................... Command..................................... ............................ ............................ ............................ ............................ ............................ ............................ ...................... ........ 49 WRITE Command ............................ .......................................... ............................ ............................ ............................ ............................ ............................ ............................ ................ 51 File Update .......................... ........................................ ............................ ............................ ............................ ............................ ............................ ............................ ........................... ............. 51 Delete From File................................ File.............................................. ............................ ............................ ............................ ............................ ............................ ........................... ............. 52 Browse Option Option ................... ................................. ............................ ............................ ............................ ............................ ............................ ............................ ............................ ................ 52 File Handling – Exception Conditions......................... Conditions....................................... ............................ ............................ ............................ ............................ ................ 54 File Handling –Program Organization ............................ ......................................... ........................... ............................ ............................ ......................... ........... 55 CICS – Database Access.............................. Access............................................ ............................ ............................ ............................ ............................ ............................ ................. ... 55 CICS - DB2 Program Preparation ..................................... ................................................... ............................ ............................ ............................ ...................... ........ 56 Files - Database Tables ............................ .......................................... ............................ ............................ ............................ ............................ ............................ .................... ...... 57 CICS QUEUE HANDLING ............................ .......................................... ............................ ............................ ............................ ............................ ............................ .....................58 .......58
TEMPORARY STORAGE QUEUE (TSQ) ............ .......................... ............................ ............................ ............................ ............................ ............................ .................... ...... 58 Temporary Storage - Output.............. Output ............................ ............................ ............................ ............................ ............................ ............................ ........................... ............. 59 Temporary Storage – Input.............. Input ............................ ............................ ............................ ............................ ............................ ............................ ............................ ................ 59 Temporary Storage – Deletion......................... Deletion....................................... ............................ ............................ ............................ ............................ ........................... ............. 60 TSQ – Exceptional Conditions....................... Conditions..................................... ............................ ............................ ............................ ............................ ............................ ................ 60 ANSIENT DATA QUEUE (TDQ) ............ TR ANSIENT .......................... ............................ ............................ ............................ ............................ ............................ ........................... ............. 61
TDQ – Intrapartition................. Intrapartition............................... ............................ ............................ ............................ ............................ ............................ ............................ ...................... ........ 62 TDQ – Intrapartition – DCT Entry ............................ .......................................... ............................ ............................ ............................ ............................ ................. ... 62 ATI – Automatic Automatic Task Initiation................................. Initiation.............................................. ........................... ............................ ............................ ............................ .................. .... 63 TDQ – Extrapartition..................... Extrapartition................................... ............................ ............................ ............................ ............................ ............................ ............................ ................. ... 63 TDQ – Extrapartition - DCT Entry................................ Entry.............................................. ............................ ............................ ............................ ........................... ............. 64
TRANSIENT STORAGE COMMANDS ............. ........................... ............................ ............................ ............................ ............................ ............................ ........................ .......... 64 Transient Storage – Output.............................. Output............................................ ............................ ............................ ............................ ............................ ........................... ............. 64 Transient Storage – Output.............................. Output............................................ ............................ ............................ ............................ ............................ ........................... ............. 65 Transient Storage – Deletion ........................... ......................................... ............................ ............................ ............................ ............................ ........................... ............. 65 Exception Conditions:............... Conditions:............................. ............................ ............................ ............................ ............................ ............................ ............................ ...................... ........ 66 CICS – IBM SUPPLIED TRANSACTIONS TRANSACTIONS ........................... ......................................... ............................ ............................ ............................ .......................66 .........66
Reference Guide
Page 3
CICS Handbook
Introduction CICS is a powerful teleprocessing system designed to control information in an online environment. It provides the environment necessary for development and execution of on-line applications thereby freeing the application developer from the dependencies of the Operating System, Hardware, etc. The primary objective of CICS is to provide the control and service functions of the database/data communication (DB/DC) system as a package. Note:
Batch System – It has a system environment where jobs run one by one in a conventional way. Online System – It has a system environment where many transactions run concurrently. CICS is available as following: • CICS/ESA on IBM Mainframe running MVS • CICS/400 on AS/400 running OS/400 • CICS/6000 on RISC/6000 systems running AIX • CICS/OS2 on PS/2 systems running OS/2 Features of CICS:
•
• •
•
Multi-tasking - Ability to control many tasks running concurrently in an address space. CICS provides for concurrent execution of multiple tasks, including tasks of the same type, like Order Entry. CICS has its own task management capabilities for execution of tasks within a single region partition and does not use the multitasking feature of the O/S. Multi-threading - Ability to use only one copy of the program when more than one task of the same type is active thereby minimizing main storage. Re-entrant - Ability to continue processing after an interruption. Since CICS performs task management and provides a separate copy of the working storage for each task currently active, CICS programs are also known as quasi re-entrant programs. Priority processing - Ability to execute tasks based on the priority set by the user for a transaction(program), terminal, terminal operator, etc.
Services provided by CICS:
•
•
Data Communication Services - Free application programs from handling terminal hardware - Interface to telecommunication methods such as VTAM, TCP/IP - Provide Communication capabilities between CICS regions and non-CICS regions across hardware. Data Management/Data Handling Services
Reference Guide
Page 4
CICS Handbook -
•
•
•
Interface for handling files such as VSAM, BDAM etc. Interface for databases such as DB2, DL/I etc. Maintain Data Integrity through - Control of data Updates - Protection of data due to abnormal termination of application or system faults like CICS or O/S crash. Application Program Services - Interface with programming languages such as COBOL, C, PL/I - Program translation - Command Interpretation System Services - Interface with the Operating System for - program load and release - memory management - scheduling of tasks based on priority, etc Monitoring Services - Event Monitoring, Statistics collection for system tuning, etc.
Transaction:
A unit of work that is done as an atomic operation - that is, the operation succeeds or fails as a whole. In CICS, a transaction is identified by a 4 character ID, for e.g. TXN1 and is initiated, usually, by typing the transaction id in the top left hand corner of a screen. Task:
An instance of the execution of a particular transaction type is a task. That is, one execution of a transaction, with a particular set of data, usually on behalf of a particular user at a particular terminal. Logical Unit of Work (LUW):
A LUW is a collection of updating activity that is treated as a single unit. In other words, the period between the start of a particular set of changes and the point at which they are complete is called a logical unit of work (LUW). The LUW is a fundamental concept of CICS recovery. From the application designer's point of view, an LUW is a sequence of actions that needs to be complete before any of the individual actions can be regarded as complete as shown below. - - - - - - - - - - - - - - - LUW - - - - - - - - - - - - - - Task A |----------------|---------------------|---------------------------¦ SOT Update Delete EOT File - 1 2 records (SP)
Reference Guide
Page 5
CICS Handbook Synchronization Point:
Synchronization point is a point during processing activities of a program where all resource updates are complete and the resources are in good condition. The beginning of a task and normal completion of a task are considered to be syncpoints. Between the beginning and end of a task any number of syncpoints might be declared, they are called intermediate syncpoints. The end of a logical unit of work is indicated to CICS by a synchronization point (abbreviated to syncpoint). A syncpoint arises in the following ways: • Implicitly at the end of a transaction, by an EXEC CICS RETURN command at the highest logical level. • Explicitly by EXEC CICS SYNCPOINT commands issued (to commit the changes made to the resources such as files, database tables etc.) by the application programmer at appropriate points in the transaction. Every time an “EXEC CICS SYNCPOINT” command is issued, • the existing LUW is completed and • A new LUW is started. A LUW is the activity which a task does between two syncpoints. A task is called ‘In-flight task’ until its LUW completes. Normally each LUW corresponds to a single task execution. But, this may not be true always. Consider a process that is updating a master file from a transaction file. If the program abends after processing 100 records, CICS will back out all the changes since the LUW is the end of the task. Hence to limit the scope of the LUW, we use SYNCPOINTs. If a failure occurs within a LUW, CICS backs out all changes to recoverable resources, to the beginning of the LUW. E.g.: 1) EXEC CICS SYNCPOINT END-EXEC. 2) EXEC CICS SYNCPOINT ROLLBACK END-EXEC. SYNCPOINT command is used to issue intermediate syncpoints. When a syncpoint command is issued, all the updates made by the task so far are committed and the resources maintained by the dynamic log are released. The SYNCPOINT command also releases the locks from the resources.
Reference Guide
Page 6
CICS Handbook SYNCPOINT with ROLLBACK option is used to recover the recoverable resources up to the last syncpoint. CICS automatically issues a SYNCPOINT at the end of each task. Conversation:
In a typical online system, data is entered by the terminal user/operator. By pressing a terminal key, a transaction is triggered. Subsequent to the processing, the results are sent back to the terminal based on which the user responds by keying in additional data. This results in a sort of “conversation” between the terminal user and the transaction. Transactions, and thus programs, can be classified as: • Conversational Program • Pseudo conversational Program Pseudo conversational programs are more efficient than Conversational programs but involve a bit of programming.
TASK 1
TASK 2
TXNA
TXNA
working storage for task 1
working storage for task 2
TASK 1 started at terminal1 by user1 executes TXNA. TASK 2 started at terminal2 by user2 executes the same TXNA. These two tasks use the same load module associated with TXNA. However, the working storage for each task is different.
The difference between a task and transaction is shown above. Visualize a Library Information System. To add a new book, a record is to be added into the book-master database. Normally a transaction will be used for performing this operation. It is possible that several users may work at several terminals at the same time and add different book records to the master. All these users will use the same transaction, but CICS initiates a different task for each one of them. Each task will acquire a working storage section; however all the tasks will use the same load module. This feature is called multi-threading . Since several tasks can be running at the same time, CICS is a multi-tasking s ystem.
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/PAk eys, 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 a s 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. 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):I t manages request of dynamic storage by the CICS control program and application programs. File Control Program (FCP) / File Control Table (FCT):
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 Mappi ng Suppo rt) 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
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)
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 Definitio n Macro s 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
Op-Code
Parameters…
LABEL :
• • • •
specifies the symbolic name specified in Column 1 Must begin with a letter Can be upto seven characters long
•
Specifies the instruction to be executed - DFHMSD, DFHMD or DFHMDF Begins in Column 10
Op-Code :
• Parameters :
• • • •
Begins from Column 17 onwards Separated by Commas without any intervening spaces Continuation char ‘ X’ in column 72 (‘ ,’ to be the last non-space Char) Asterisk character in Column 1 specifies a Comment line.
Within one mapset definition, the map definition can be specified as many times as you wish. Within one map definition, the field definition can be specified as many times as you wish.
DFHMSD Macro [setname]
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 mapw ill be generated. TYPE=&SYSPARM can be specified and the values MAP or DSECT can be specified as parameters in the map generation JCL (for special assembly procedure). TYPE=FINAL is used to indicate the end of a mapset coding. To indicate input/output operation.
Reference Guide
Page 15
CICS Handbook MODE=IN MODE=OUT
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) 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. IBM’s 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 Macr o 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 Macr o 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 field’s color. Can specify BLUE, RED, PINK, GREEN TURQUOISE, YELLOW or NEUTRAL. If omitted, the default terminal color is assumed.
Reference Guide
Page 17
CICS Handbook HILIGHT ATTRB
Specifies the field’s 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.
MDT’s and their manipulatio n MDT indicates whether a field is modified or not MDT on will ensure that data is received into the program • •
MDT’s 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 map’s 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 Manipul atio n – FRSET •
an attribute of DFHMSD macro
•
turns off all MDT’s 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 Definiti on 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 Modification
Single Char (PIC X)
“F”
NAMEF
Input Field
As defined in Map
“I”
NAMEI
Output Field
As defined in Map
“O”
NAMEO
Reference Guide
Page 20
CICS Handbook
Code for Sample Layout MAPSETS DFHMSD TYPE=&SYSPARM,MODE=INOUT,TERM=ALL, LANG=COBOL,TIOAPFX=YES,STORAGE=AUTO MAPSMP DFHMDI SIZE(24,80),LINE=1,COLUMN=1 DFHMDF POS(8,7),LENGTH=10,INITIAL=‘NAME :’, ATTRIB=ASKIP NAME DFHMDF POS(8,18),LENGTH=20,ATTRIB(UNPROT,IC) DFHMDF POS(8,40),LENGTH=1,ATTRIB=PROT DFHMDF POS(10,7),LENGTH=10,INITIAL=‘ITEM NO :’, ATTRIB=ASKIP ITEM DFHMDF POS(10,18),LENGTH=6,ATTRIB=NUM) DFHMDF POS(10,25),LENGTH=1,ATTRIB=ASKIP DFHMDF POS(12,7),LENGTH=10,INITIAL=‘QUANTITY :’, ATTRIB=ASKIP QTY DFHMDF POS(12,18),LENGTH=6,ATTRIB=NUM DFHMDF POS(12,25),LENGTH=1,ATTRIB=PROT
X X
X
X
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 f ield, 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 f ields are coded to limit the input area for fields.
Reference Guide
Page 21
CICS Handbook
Symbolic Map for Sample Layout 01
MAPSMPI 02 FILLER X(12). 02 NAMEL S9(4) COMP. 02 NAMEF PIC X. 02 FILLER REDEFINES NAMEF. 03 NAMEA PIC X. 02 NAMEI PIC X(20). 02 ITEML S9(4) COMP. 02 ITEMF PIC X 02 FILLER REDEFINES ITEMF. 03 ITEMA PIC X. 02 ITEMI PIC X(06). 02 QTYL S9(4) COMP. 02 QTYF PIC X 02 FILLER REDEFINES QTYF. 03 QTYA PIC X. 02 QTYI PIC X(06).
01
MAPSMPO REDEFINES MAPSMPI. 02 FILLER PIC X(12). 02 FILLER PIC X(3). 02 NAMEO PIC X(20). 02 FILLER PIC X(3). 02 ITEMO PIC X(06). 02 FILLER PIC X(3). 02 QTYO PIC X(06).
The symbolic map for the screen defined in the sample layout is shown above. The first observation to make here is the naming convention. The mapname MAPSMP used in DFHMDI macro definition of the previous slide is used to denote the input and output areas MAPSMPI and MAPSMPO respectively. Note that the output area redefines the input area. Secondly, the label names (NAME, ITEM, etc.) used in the BMS macro definitions are used here to indicate the field names (NAMEI, ITEMI, NAMEO, ITEMO, etc.). Note that only those field macros with labels are defined in the symbolic map. Under the input variable definition, each field name has a 2-byte length field, followed by an one-byte flag field and then the input field itself. The one-byte flag field is also redefined to be a one-byte attribute field. Correspondingly, there is a 3-byte filler and the output field under the output variable definition. For e.g., under MAPSMPI, we find Reference Guide
Page 22
CICS Handbook NAMEL, NAMEF and NAMEI with NAMEA redefining NAMEF. Under MAPSMPO, we find a 3-byte filler and NAMEO. The 12-byte filler at the beginning of both MAPSMPI and MAPSMPO is the control information that is required for COBOL programs which is generated by coding TIOAPFX=YES in the mapset definition. We have some products such as SDF (Screen Definition Facility) which eliminate the cumbersome task of coding BMS macros. Tools like SDF allow the screen to be painted and automatically generate the symbolic and physical maps. In subsequent visuals we will see how the attribute and length variables of each field can be manipulated in the symbolic map to control the display of the map. NOTE :
The symbolic map starts with the 01 level definition of map name specified in the DFHMDI macro with the suffix of “I” for the input map or “O” for the output map. Next is the definition of FILLER PIC X(12), which is the TIOA prefix created by the TIOAPFX=YES of the DFHMSD macro, and this is required by BMS under the CICS command level. For each field name (1 to 7 characters) you specified in the DFHMDF macro, BMS creates 3 fields for inputs and another 3 fields for outputs, by placing 1 character suffix to the original field name. The meanings of these fields are as follows : Name+L: The half-word binary (PIC S9(4) COMP) field. For the input filed, the actual number of characters typed in the filed will be placed by BMS when the map is received. For the output field, this is used for the dynamic cursor positioning. Name+F: Flag Byte. For an input field, it will be X’80’ if field has been modified but no data is sent (i.e. the field is cleared). Otherwise, this field is X’00’. Name+A: The attribute byte for both input and output fields. Name+I: The input data field. X’00’ will be placed if no data is entered. Note the space X’40’ is data. The application program should differentiate X’00’ from space (X’40’). 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 before this this page of output output is displayed, displayed, all unprotected unprotected character locations screen are to be erased. e rased. 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 def default ault data from from the map is to be written. written. If neither MAPONLY nor DATAONLY 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 prepared before SENDing SENDing the MAP : – Field Length : fieldname +L – Field Attribute : fieldname +A – Field Content Content : fieldname 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 positioning – Direct cursor c ursor positioning – Symbolic cursor positioning
1) INITIAL CURSOR: 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 CURSOR POSITION POSITIONING: ING:
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 the screen layout changes. 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 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 fieldname 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 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 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 x’80’ or X’82’. 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 X’82’ or X’02’ 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 Pr ogramming 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.
Ar gument 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
Name o
A Valid COBOL data name Full word Binary - PIC S9(8) COMP. Half word Binary - PIC S9(4) COMP. A Valid COBOL data name(Character string).
Label A COBOL paragraph or a section name. Time in hhmmssf ormat o PIC S9(7) COMP - 3. Pointer Reference o Pointer name. o
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
Structu re of CICS appl ication p rog ram IDENTIFICATION DIVISION. PROGRAM-ID . XXXXXXXX. ENVIRONMENT DIVISION.
<=== THIS DIVISION MUST BE EMPTY
DATA DIVISION.
<=== FILE SECTION IS OMITTED
WORKING- STORAGE SECTION. 77 --------------------- . 01 --------------------- . 05 ---------------- . LINKAGE SECTION.
<=== LINKAGE SECTION IS MANDATORY <=== COMMUNICATION AREA reqd for passing data for subsequent execs.
01 DFHCOMMAREA.
05 -----------------. PROCEDURE DIVISION .
( COBOL STATEMENTS) + <=== CICS statements mixed with COBOL statements. Some COBOL verbs not ( CICS STATEMENTS) allowed. . GOBACK. Description: ENVIRONMENT DIVISION.
• •
Only the header is required in this section . INPUT-OUTPUT SECTION , FILE CONTROL, SELECT statements not required. Instead, Files will have to be defined in the File Control Table (FCT) in CICS.
DATA DIVISION.
• •
FILE SECTION is not required. LINKAGE SECTION is required.
PROCEDURE DIVISION.
The following COBOL statements cannot be issued in a CICS application program. - ACCEPT - RELEASE
- DATE - SORT
Reference Guide
- DISPLAY - STOP RUN
- EXHIBIT - TRACE
Page 30
CICS Handbook - Any I/O statements ( OPEN ,CLOSE, START)
READ, WRITE, REWRITE, DELETE ,
EXEC Interface Bl ock (EIB)
CICS Control Block containing useful CICS system information Automatically given to each CICS application program in LINKAGE SECTION at the time of program translation Copy book DFHEIBLK is inserted by the translator before the DFHCOMMAREA variable Information in EIB can be used for handling error/exceptions. Usage of EIBRESP for checking CICS command result
The EIB Block contains, apart from information related to CICS communications, the following (the fields are prefixed with ‘EIB’, as in EIBDATE, EIBTIME, etc.): • TRNID - the current Transaction Id • DATE, TIME - Date and Time at which the transaction was started or the time it was refreshed using the ASKTIME command • TRMID - the terminal id associated with the transaction • FN - the CICS function which was accesses lately • RCODE - the error code resulting from the last CICS command • RESP - the response code for the last CICS command • RESP2 - additional response code information • AID - the function key associated with the transaction • CALEN - the COMMAREA length; used in pseudo-conversational pgms EIBRESP:
The value returned in the attribute EIBRESP can be used for checking whether a CICS command was executed successfully by CICS or not. The EIB variables are available in the copy book DFHEIBLK
Storage Types CICS provides a variety of facilities for storing data within and between transactions. •
Provides following storage sources – COMMAREA : A communication area (COMMAREA) is a facility used to transfer information between two programs within a transaction or between two transactions from the same terminal. – COMMON WORK AREA (CWA) : The common work area (CWA) is a single control block that is allocated at system start-up time and exists for the duration of that CICS session. The size is fixed, as specified in the system initialization parameter, WRKAREA.
Reference Guide
Page 31
CICS Handbook There is almost no overhead in storing or retrieving data from the CWA. Data in the CWA is not recovered if a transaction or the system fails. – TRANSACTION WORK AREA (TWA) Dynamic Storage Allocation & De-allocation – GETMAIN – FREEMAIN Prevent one application program from overwriting CICS storage areas storage keys – CICS key : CICSDATAKEY – User key : USERDATAKEY
•
•
When you use the GETMAIN command to acquire main storage, there is the possibility that one program may accidentally overwrite the storage used by another program. Or an application program may overwrite CICS control blocks crucial for the operation of CICS, thereby crashing the system. Storage used by CICS is CICS key storage and that used by an application is user key storage . Every program in CICS runs under an execution key that determines the types of storage it can access. A program under CICS key can access CICS key or user key storage, whereas a program under user key can access only user key storage. CICS system programs run under CICS key, and application programs run under use key. Coding CICSDATAKEY or USERDATAKEY as an option to Get main will determine which type of storage is allocated. The default is USERDATAKEY because storage allocated by CICSDATAKEY cannot be modified.
Reference Guide
Page 32
CICS Handbook
CICS Program Contro l 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 LINK’ed program runs at the next lower logical level from the linking program. • A XCTL’ed program runs at the same logical level as the XCTL’ing 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: 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. It’s 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. PROGRAM
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. COMMAREAA n 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 user’s 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 conditi ons in Program Control Commands INVREQ
TRANSID is specified on a RETURN command in a program that was not at the highest logical level ( i.e.., a RETURN that would not terminate the transaction by returning control to CICS )
LENGERR
The length of the data specified using the RETURN command with length option is outside the valid range of 1 to 32763.
NOAUTH
Resource or command security check has failed.
PGMIDERR The program to which control is passed on a LINK or XCTL
command, cannot be found in the list of installed program definitions, or it is not in the library or it has been disabled.
Reference Guide
Page 37
CICS Handbook
Interval and Task Contr ol 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
Reference Guide
Page 38
CICS Handbook Starting an Asynchr onous transaction usin g START command The START command is used to start a transaction at the specified terminal and at the specified time or interval. Optionally, data can be passed to the to-be-initiated transaction. EXEC CICS START TRANSID(data-value) [ TIME(hhmmss) | INTERVAL (hhmmss)] [ REQID(NAME)] [ FROM(data-area) [ LENGTH(data-value) [FMH]] [ TERMID(data-value)] END-EXEC
Description: TRANSID
defines the transaction id of the transaction to be initiated.
TIME or INTERVAL indicates the time or time interval of the transaction initiation,
respectively, in the form of hhmmss. If omitted, the transaction will be initiated immediately. If the time specified in the TIME parameter has expired, then also, the transaction will be initiated immediately. REQID
Specifies an 8 byte value that identifies this START command so that the started task can be cancelled with a CANCEL command. If omitted, CICS still generates the REQID and the same is available in the EIB variable EIBREQID.
FROM
Specifies the data area which contains the data to be passed, i.e. to pass a field in the Working Storage Section.
LENGTH
The length of the data-area should be specified in the LENGTH option.
TERMID
defines the terminal id of a terminal against which you initiate the transaction. If it is omitted, the specified transaction will be initiated against the terminal with which the current transaction is associated.
Data can be passed to the transaction by specifying the FROM and LENGTH options. Interval Control stores the data passed in a TSQ for a later RETRIEVE (retrieval). For example the command EXEC CICS START TRANSID (‘TRN1’) TIME (083000) will result in the transaction ‘TRN1’ to be started at 8.30 hrs. If this is issued after 08:30 hrs, the transaction will be started immediately.
Reference Guide
Page 39
CICS Handbook Retrieving data in a STARTed Transacti on – 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 LENGTH
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.
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 Contro l 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 Contr ol Command o o o
SUSPEND ENQ 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 Handli ng 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.
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 Comm and – 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 Command s 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 actio n – CICS checks possible exceptions after each CICS command – If exceptional conditions are not taken care of, CICS by default, may SUSPEND the task or abnormally terminate the execution – Issuing an ABEND CODE For each CICS command, CICS checks the results of the command execution. Following are the common ABEND codes related to exceptional conditions. APIA - ERROR AEID - EOF AEIM - NOTFND AEIN - DUPKEY AEIP - INVREQ AEIQ - IOERR AEIR - NOSPACE AEIS - NOTOPEN AEIT - ENDFILE AEIV - LENGERR AEIW - QZERO AEIZ - ITEMERR AE19 - MAPFAIL AEYH - QIDERR Following are the common Abend codes not related to exceptional conditions. AEY7 Resource security failed. AEY9 Unsupported command issued. AKCS Deadlock or timeout ASRB ABEND due to OS ABEND intercepted by CICS. ASRA ABEND due to program interruption (error in COBOL statement).
HANDLE ABEND Command It is an abend control command. It is used to intercept an abnormal termination (ABEND) within a program, and to activate, cancel, or reactivate an exit for the ABEND processing.
Reference Guide
Page 45
CICS Handbook EXEC CICS HANDLE ABEND [ PROGRAM (name) | LABEL (label) | CANCEL | RESET ] END-EXEC.
Description: PROGRAM or LABEL used to activate an exit to a program or a paragraph,
respectively, for the ABEND processing. CANCEL
used to cancel the previously established HANDLE ABEND request.
RESET
to reactivate the previously cancelled HANDLE ABEND r request.
ABEND Comm and It is an abend control command. It is used to terminate a task intentionally, causing an ABEND. EXEC CICS ABEND [ABCODE(name)] END-EXEC
Description: ABCODE
used to specify the user abend code (1 to 4 characters).
E.g.: EXEC CICS ABEND ABCODE(‘ERR1’) END-EXEC
Reference Guide
Page 46
CICS Handbook
CICS – DATA ACCESS File Handling •
• • •
Supports VSAM – BDAM supported in earlier versions of CICS Files to be defined to CICS as resources File Opening, Closing done by CICS Provides interface for – Random access – Sequential access – Read, Write, Update, Delete
The files to be accessed in CICS application programs are to be defined to CICS in the File Control Table (FCT). The CICS File Control Program (FCP) along with the FCT provides application programs with services to read, update, add and delete records in a file. The file definitions in the application program and the file opening and closing operations need not be performed. During record updates CICS provides exclusive control over records to maintain data integrity.
File Acc ess Method s • •
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: 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 DATASET
Eg: WORKING- STORAGE SECTION. 77 77
WS-REC-LEN WS-FILE-NAME
PIC S9(4) COMP. PIC X(8) VALUE ‘ACCTMSTR’
01
WS-FILE-REC 05 WS-REC-KEY PIC X(6). 05 WS-REC-DATA PIC X(34).
PROCEDURE DIVISION. MOVE 40 TO WS-REC-LEN. MOVE ‘ABC451’ TO WS-REC-KEY. EXEC CICS READ DATASET(WS-FILE-NAME) INTO (WS-FILE-REC) RIDFLD(WS-REC-KEY) LENGTH(WS-REC-LEN) END-EXEC.
The file ‘ACCTMSTR’ should have been registered in FILE Control Table (FCT) in CICS and must be enabled. After execution WS-FILE-REC will have the data record read from Reference Guide
Page 50
CICS Handbook ‘ACCTMSTR’, whose key value is ‘ABC451’.
WRITE Command EXEC CICS WRITE DATASET( file-name) FROM( file-rec) LENGTH( rec-length) RIDFLD( rec-key) [RBA | RRN] END-EXEC.
Description: RIDFLD Specifies the key of the record to be written. If RBA or RRN is specified, this field is interpreted as a Relative Byte Address or Relative Record Number respectively. RBA Specifies that the file is ESDS and the RIDFLD option should be
interpreted as the Relative Byte Address. RRN Specifies that the file is RRDS and the RIDFLD option should be
interpreted as the Relative Record Number.
File Update EXEC CICS REWRITE DATASET ( file-name) FROM ( data-area) [LENGTH ( rec-len) END-EXEC.
Description: DATASET FROM LENGTH
Specifies the name of the file which has to be updated. Specifies the data-area from which the data is to be written. Is a binary halfword that indicates the length of the record to be re-written. Not required for VS COBOL II.
The REWRITE command is used to update a record already read. Before issuing a REWRITE command, READ command must have been issued with the UPDATE option. The key field in the record cannot be changed. Reference Guide
Page 51
CICS Handbook Delete From File EXEC CICS DELETE DATASET ( file-name) RIDFLD(rec-key) [KEY-LENGTH(key-length)] [GENERIC[NUMREC(rec-number)]] [RBA | RRN] END-EXEC.
The DELETE command may be issued to delete record(s) from a data set in two ways : • Issued after a READ command with the UPDATE option to delete the record that is read. • Issued with the RIDFLD option when there is no prior READ with UPDATE option. This will delete the record whose key matches with the RIDFLD. Records from VSAM KSDS and RRDS files can be deleted, but not from VSAM ESDS files. The NUMREC option will return the number of records deleted on a GENERIC delete. KEYLENGTH must be specified for a GENERIC delete.
Browse Option The browse operation is used for fetching the records sequentially from the underlying VSAM file based on a selection criteria. The browse operation consists of three steps : • Establish the position from where to begin the sequential retrieval. • Retrieve records sequentially and process them as required. • Terminate the browse when no further sequential retrieval is required. The starting position for browse may be re-established at anytime during the browse operation. A record that has been retrieved as part of a browse cannot be updated during browse. For that, browse operation should be terminated and the record should be read again with update option.
Reference Guide
Page 52
CICS Handbook The various Browse commands used are: STARTBR - Establish Position The STARTBR command establishes the position within the file, but does not retrieve a record. READNEXT - Retrieve records in the ascending The READNEXT command retrieves the records sequentially in the order set by the STARTBR command. The RIDFLD is automatically updated by CICS for the next READ; application programs NEED NOT update this. RIDFLD can be set to a value greater than the present RIDFLD that is fetched. If a READNEXT is performed in this manner, it is called ‘skip sequential processing’. READPREV - Retrieve Records in Descending The READPREV command retrieves records in the reverse order as set by the STARTBR command. RESETBR - Change Position To restart browsing from a different file location. This is similar to an ENDBR followed by a STARTBR, but is more efficient because the VSAM resources will be reallocated rather than de-allocation and fresh allocation. ENDBR - Terminate Browse Terminates the browse operation. Normally not required, but recommended for efficiency sake as the ENDBR will release the VSAM resources allocated for the browsing. Eg: MOVE ‘VALUE’ TO KEY-REC EXEC CICS STARTBR FILE(‘FILEA’) RIDFLD(RECKEY) RESP(ERR-CODE) END-EXEC.
IF ERR-CODE = DFHRESP(NORMAL) PERFORM UNTIL ERR-CODE = DFHRESP(ENDFILE). PERFORM 2000-REC-FROM-FILE UNTIL 2000-REC-FROM-FIL-EXIT EXEC CICS READNEXT FILE(‘FILEA’) INTO(FILEREC) RIDFLD(RECKEY) RESP(ERR-CODE) END-EXEC.
END-PERFORM EXEC CICS ENDBR FILE(‘FILEA’)
ELSE Reference Guide
Page 53
CICS Handbook PERFORM 9000-HANDLE-ERROR ….. END-IF. The key field is updated after every browse retrieval with the actual key of the record retrieved. ENDFILE occurs when a read is issued • After the last record on the file has been retrieved for READNEXT command • After the first record on the file has been retrieved for READPREV command. The file position can be changed by moving the new key value to the RIDFLD before READNEXT or READPREV command.
contents of
File Handling – Exception Conditions Following Exceptional Conditions to be handled
NOTFND LENGERR
-
FILENOTFOUND DISABLED NOTOPEN NOSPACE INVREQ -
ILLOGIC
Reference Guide
-
Record with specified key is not in the use. The length of the record to be rewritten is either too long or not specified. File name is not in FCT. File has status of disabled. File is closed. There is no space on the file for write or rewrite. There are several reasons for this exception condition No previous READ UPDATE issued for REWRITE. Second REWRITE issued before releasing the exclusive control of the first REWRITE. This identifies VSAM error not covered by other CICS exceptional conditions. The 2nd byte of the EIBRCODE contains the VSAM error code
Page 54
CICS Handbook File Handling –Prog ram 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 Ac cess
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 NOTb e 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
B ind A pplication
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 Handli ng 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 Sto rage 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.
Tempor ary Storage - Output EXEC CICS WRITEQ TS QUEUE(queue-name) FROM( data-area) LENGTH(queue-length) [ITEM( data-area)] [REWRITE] [MAIN|AUXILIARY] END-EXEC.
Description: 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). QUEUE
Tempor ary 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: 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. NEXT
Reference Guide
Page 59
CICS Handbook
Tempor ary Stor age – 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 Condi tion s
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 – Intr aparti tion • • • • • • • •
All queues share the same VSAM data set (ESDS) Reading a TDQ is destructive. Read is sequential - No random access Updates not possible Records in a TDQ can be of variable length TDQ is associated with a transaction Trigger levels can be specified for Automatic task initiation Queue can be specified as – Logically or physically recoverable – Not recoverable
All Intrapartition TDQs are stored in only one physical file (VSAM -ESDS) in a CICS region Only sequential access is allowed for a queue. Once a record is read from the queue it will be logically removed from the queue and it cannot be read again. The records can be of variable length. Each TDQ is to be defined in the DCT as Intrapartition. Additionally, a CICS transaction can be defined with the TDQ along with the trigger level. When the number of entries in a TDQ reaches the trigger level, CICS automatically initiates the transaction associated with the TDQ. This is known as Automatic Task Initiation. CICS will initiate only one task per TDQ. It is the responsibility of the application program to read records from the queue recursively and deplete the queue. The TDQ can be defined as recovery is required or not.
TDQ – Intrapartition – DCT Entry DFHDCT
TYPE = INTRA , DESTID=queue-name, [TRANSID= txn-id-name,] [TRIGLEV= number,] [REUSE=YES|NO]
DCT entries can be defined using the macro DFHDCT. Description: TYPE=INTRA DESTID
Indicates that TDQ is an intrapartition TDQ.
Defines the name of the TDQ ( 1 to 4 chars).
Reference Guide
Page 62
CICS Handbook REUSE
Once a record of intrapartition TDQ is read, the record is logically removed. But it still occupies the space. If REUSE = YES is specified, this space for logically deleted record will be used for other TDQ records. But the records are not recoverable. If REUSE=NO, the records are recoverable.
TRANSID & TRIGGER LEVEL Used for automatic task initiation (see next page)
ATI – Automati c Tas k In it iation 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 – Extr aparti tion • • • •
Each destination is a physical data set Destination can be input or output (not both) Automatic task initiation not supported Only sequential access
Extrapartition TDQs are used to interface batch programs with CICS applications. Each extrapartition TDQ is a separate physical file and it may be on the disk, tape or printer. Each extrapartition file (i.e. TDQ) must be open within the CICS region when it is used by the CICS transaction. The DCT entry determines the initial OPEN|CLOSE status of the file. The file can also be opened or closed through the Master terminal transaction (CEMT) during a CICS session.
Reference Guide
Page 63
CICS Handbook TDQ – Extrapartition - DCT Entry DFHDCT
DFHDCT
TYPE = EXTRA , DESTID=queue_name, DSCNAME=name, [OPEN]=INITIAL|DEFERED] TYPE=SDSCI, DSCNAME= name, TYPEFILE=INPUT|OUTPUT|RDBACK
Description: TYPE=EXTRA
Indicates its an extrapartition TDQ.
DESTID
Defines the name of the TDQ (1 to 4 characters).
OPEN
Defines the initial file status. If INITIAL is specified the file will be opened at CICS start up time. If DEFERED is specified the file will be closed until it is specifically opened by the CEMT transaction.
DSCNAME
Defines the data control block name. For every DSCNAME a corresponding DFHDCT entry must be made with TYPE=SDSCI and the same DSCNAME. This in effect indicates the DDname of the extrapartition dataset in the JCL of the CICS job.
Transient Storage Command s WRITEQ TD
: To sequentially write a record in a TDQ.
READQ TD
: To sequentially read a record in a TDQ.
DELETEQ TD : To delete an intrapartition TDQ. Not valid for extrapartition TDQ.
Transient Storage – Outpu t EXEC CICS WRITEQ TD QUEUE(queue-name) FROM(queue-data) LENGTH(queue-length) END-EXEC.
Description: queue-name is the name of the TDQ as in the DCT.
Reference Guide
Page 64
CICS Handbook queue-data
is the name of the working storage variable from which data is to be written.
queue-length indicates the length of the record.
Transient Storage – Outpu t EXEC CICS READQ TD QUEUE(Q-name) INTO (Q-data) LENGTH(Q-length) END-EXEC.
Description: Q-name
is the name of the TDQ as in the DCT.
Q-data
is the name of the working storage variable from which data is to be written.
Q-length
indicates the length of the record.
Transient Stor age – 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
