CICS or Customer Information Control System is IBM s online transaction processing product.

It allows companies to develop systems to access data in real time. The current version of CICS - CICS Transaction Server - provides various facilit ies to interface with web technology while providing continuing access to legacy systems. The CICS Application Program Interface (API) lets you write programs that will w ork with CICS in a variety of programming languages (Cobol, PL/1, C and HLASM). Within this section of the website you will find information to help you learn a bout programming for CICS. Introduction CICS is a transaction processing system, it allows a user to input data online. A transaction can be thought of as a unit of work, usually it is a single progra m that performs an update or returns the result of an enquiry. CICS appears to the user to be a separate environment, but is actually a job tha t runs under the main operating system (OS/390, Z/OS, etc). CICS has a number of programs that handle resources, such as storage. There are various CICS tables which define files programs and transactions to the CICS sy stem. When developing programs you can access files, storage and other programs and r esources using the application programming interface (API). The API lets you iss ue CICS commands from within the program. This is known as Command Level Program ming. In the first versions of CICS the API was not available and you had to acc ess CICS resources using Assembler Macros, this was known as Macro Level program ming. Macro Level is no longer supported under newer versions of CICS, so it wil l not be covered here. A transaction is started in CICS by entering a 4 character transaction id. When you enter the transaction id this starts the program associated with that transa ction id. Note that this is not intended to be a complete course in CICS, it merely introd uces some CICS concepts. Top of Page General Concepts Pseudo Conversational Programming Executing CICS Commands Differences between batch and CICS Cobol programs Passing Data between Programs Defining Resources to CICS CICS Screens Calling Other Programs CICS Supplied Transactions Pseudo Conversational Programming

The majority of CICS application programs are coded to take advantage of a techn ique called pseudo conversational programming. Ordinary conversational programs run and stay in memory for the duration of the interaction between the computer and the operator. This means that all the reso urces that the program requires are held and not released, so if an operator wen t off for lunch, say, leaving the terminal logged in and running a transaction, no one else would be able to access the resources held by that program. Pseudo conversational program overcomes this limitation by terminating the trans action when the screen is displayed. This frees up the resources while the opera tor is typing at the terminal (or off for lunch). The transaction is re-initiate d when the user presses the Enter or a PF Key. This involves a bit more programmin g effort, but is usually worth it Top of Page Executing CICS commands from COBOL programs When you want to execute a CICS command from your program, you start the command by specifying EXEC CICS before the CICS command. You terminate the CICS command with the END-EXEC terminator. The EXEC CICS . END-EXEC structure must start after column 12 as with normal COBOL commands. The CICS command can be spread over a number of lines, without the need for a co ntinuation character. Top of Page Differences between batch COBOL and CICS COBOL programs. The biggest difference you will notice in CICS programs is that you do not defi ne files in your program. The usual file access commands like OPEN, CLOSE, READ, WRITE are not used. The reson you do not define files in the program, is that the files should be de fined to CICS in the File Control Table (FCT). The FCT contains all the informat ion needed by CICS to access the file. (If you are going to be using a new file then you will need to have it defined in the FCT before you can use it.). The Op ening and Closing of files is handled by CICS. I/O operations on files are carri ed out using CICS commands in your program. To terminate a CICS program you should use the CICS RETURN command instead of a STOP RUN, GOBACK or END PROGRAM. The RETURN command will return control to the c alling program, or if there was no calling program, control is returned to CICS. You can also specify a Transid to which control returns. In order to compile a CICS Cobol program you must first run the program through a Pre-Compiler . The Pre compiler will read your program and convert the CICS comma nds into COBOL CALL commands. This is required because the Cobol compiler does n ot understand CICS commands. In newer versions of CICS (CICS TS V2 and above) th e pre-compile step is not required, because the pre-compiler has been integrated into the compiler. Top of Page Passing data between CICS Cobol Programs

Data is passed between programs in a number of different ways. 1)The Execute Interface Block (EIB). This is een programs. It contains system information by your program. The EIB is copied into your riables are populated by the system when the a special block of data passed betw that can be used (but not changed) program when you compile it. The va program runs.

2)COMMAREA (DFHCOMMAREA). The commarea is used to pass user data between program s. The Commarea is specified in the LINKAGE SECTION of your program. There will always be a DFHCOMMAREA in your program whether you specify it or not. If you do n t specify a DFHCOMMAREA in the program then a one byte DFHCOMMAREA is placed in the Linkage Section at compile time. (The compiler will also insert the USING DF HCOMMAREA after the Procedure Division statement). The maximum size of DFHCOMMAR EA is 32K, however it is recommended (by IBM) that it not exceed 24K. The length of the Commarea is returned to your program in the variable EIBCALEN. 3)Temporary Storage and Transient Data Queues. These are special areas of stora ge that you can use to keep information and pass it between programs. Temporary Storage Queues (TS Queues) can be accessed either sequentially or randomly, whil e Transient Data Queues (TD Queues) can only be accessed sequentially. In additi on Transient Data Queues must be declared to CICS before use. 4)Files. You can, of course, use files to pass data between programs. Top of Page Defining Resources to CICS. As mentioned above, you must define resources such as files to CICS, before you can use them. Files are defined to CICS in the FCT (File Control Table). The information requi red include an 8 character ID that uniquely identifies the file, the File name, key length and types of I/O allowed on the file. Programs must be defined in the PCT (Program Control Table). The information req uired includes the program name and program language. Transactions are defined in the PPT (Program Process Table). The transaction nam e is 4 characters. The information required in the PPT includes the Program name that the transaction is to run. Definitions of CICS resources are stored in the CICS System Definitions (CSD) fi le. There are two usual methods of adding and defining resources to CICS. The first method is to use Resource Definition Online (RDO). There are a number of transactions in CICS which allow you to define resources to CICS. The second method is to use the CSD offline update utility, DFHCSDUP. This is r un as a batch job, and the definitions normally become available when CICS is re started. It s possible that security restrictions at your site mean that you cannot define resources to CICS, you may have to rely on support or change management procedur es to have CICS updated. Top of Page

CICS Screens You can design screens for your programs to display the screens are usually refe rred to as Maps or BMS Maps . Screens are defined using special Assembler Macros. You don t have to be an assembler programmer to use the macros, it is fairly easy to code the macros, they tend to be very similar for each screen. If you use assembler macros to define your screens then you will define the attr ibutes of each field that will appear on the screen, such as colour, size, etc. Another way to define screens is to use one of the many screen painters availabl e. These take the hard work out of coding macros, because they allow you to desi gn the screen on-line and automatically generate the required macros. Examples o f screen painters are IBM s SDF II and BMS/GT. See the CICS BMS Maps page for details of how to create Maps Top of Page Calling other Programs You can call other programs from a CICS Cobol program in a number of ways. LINK - Similar to a standard Cobol CALL command. Once the called program has fin ished control is returned to the calling program at the next statement after the LINK. XCTL - This command transfers control to the called program, and the calling pro gram is terminated, Control is NOT returned to the calling program. You can also use the Cobol l to another program. Top of Page CICS Supplied Transactions There a number of transaction that are supplid with the CICS system. These trans actions let you manage and view CICS resources online, amongst other things. Exa mples of CICS transactions are CEMT, CEDA, CESN and CSSF. The CEDF CICS supplied transaction is a debugging aid, It stops your program bef ore and after each CICS command and lets you view storage areas. The CECI transaction lets you execute CICS commands without needing to write a p rogram. File Handling in CICS Note: only some of the command options are specified here, please see the CICS m anuals for a full list of available options. READ REWRITE DELETE Writing a Browse Program STARTBR WRITE UNLOCK READNEXT CALL ... USING ... command to transfer temporary contro

ENDBR The READ Command READ DATASET (file name) INTO (data area) RIDFLD (record key area) [UPDATE] [EQUAL / GTEQ] [LENGTH (record length area)] [GENERIC] [KEYLENGTH (data value)] [SYSID (system name)]

READPREV

The DATASET, INTO and RIDFLD options are required in every READ command. DATASET gives the name, in quotes, of the file that you wish to read. INTO names the da ta area within your program into which the record should be copied from the file . RIDFLD stands for Record IDentification FieLD. This option names the data area that contains the key value of the record you wish to read from the file. The UPDATE option is used to establish exclusive control over a record. This is necessary to prepare CICS to update or delete a record later in your program. EQUAL and GTEQ refer to the collating sequence in which record keys occur in the file. By default, the READ command will only read a record whose key is equal t o the key specified in RIDFLD. If GTEQ is specified, the first record whose key is greater than or equal to the RIDFLD is read. The LENGTH option is mandatory for reading variable length records. It specifies a data area that contains the maximum length input record that the program is e xpecting. When CICS executes the READ it stores the actual length of the record it reads into the data area specified in the LENGTH option. If this length excee ds the maximum length that the program had specified, the LENGERR exception cond ition is raised. GENERIC tells CICS that the RIDFLD specifies only a partial key. KEYLENGTH, whic h is mandatory with the GENERIC option, tells CICS how many bytes of the RIDFLD key should be used to retrieve the record. The data value associated with the KE YLENGTH option may be a constant number, or it may be a variable data area defin ed in working storage. The SYSID option is needed only if your installation uses the Intersystem Commun ication (ISC) facility to communicate with other systems. The four character sys tem ID that you specify tells Cics on which system the file to be read is locate d. Whenever you specify the SYSID option, the LENGTH and KEYLENGTH options must be specified. The WRITE command WRITE DATASET (file name) FROM (data area) RIDFLD (record key area) [LENGTH (data value)] [KEYLENGTH (data value)] [SYSID (system name)] With the exception of FROM and LENGTH, all of these options are coded in the sam e way that they are coded for the READ command. The FROM option indicates the name of the data area in working storage from whic

h the record will be written. The LENGTH option specifies the exact length of the record to be written. There is no need for CICS to return a length value to the program after the record has been written. Therefore, in the WRITE command, the LENGTH option can be specifi ed by a constant number instead of by the name of the data area, as in the READ command. As with the READ command, the LENGTH option is required for variable le ngth records. The REWRITE Command REWRITE DATASET (file name) FROM (data area) [LENGTH (data value)] [SYSID (system name)] After a record has been READ from a file with the UPDATE option, and the program has updated fields within the record, the REWRITE command can be issued to rewr ite the record to the file and complete the update option. Notice that the options that affect the WRITE command also affect the REWRITE co mmand with the exception of the RIDFLD and KEYLENGTH options. These options are unnecessary because, if used at all they must be specified in the READ UPDATE co mmand which must precede a REWRITE. The DELETE Command DELETE DATASET (file name) [RIDFLD (record key area)] [LEYLENGTH (data value) [SYSID (system name)] The DELETE command can be used in two ways to delete records. One way is to issu e a DELETE command using the DATASET and RIDFLD options. The other, safer, method is to issue a READ UPDATE command prior to deleting the record. The program can the inspect fields within the record to help determine whether the record should be deleted. If a record is deleted after being retriev ed with a READ UPDATE command, the DELETE command may be issued without the RIDF LD option. RIDFLD is unnecessary in this instance because it was already specifi ed on the READ UPDATE command. The KEY LENGTH and SYSID options need to be issued only when the record to be de leted resides in a file on another system. The UNLOCK Command UNLOCK DATASET (file name) [SYSID (system name)] When a record is read with the UPDATE option, exclusive control for that record remains in effect until the record is either rewritten or deleted or until the t ransaction is terminated. If once the record has been read, it is determined that an update is not necessa

ry, exclusive control should be released from the record so that it can be acces sed by other transactions. The UNLOCK command releases the program's exclusive control over a record. Writing a Browse Program A browse transaction reads and displays multiple records from a file in a single transaction. Browse programs are usually coded to allow the user to continue br owsing the file by pressing enter. All browse programs contain the following CICS commands: * STARTBR - Initiates the browse by establishing the key of the first record to be read. * READNEXT - Reads the first and all subsequent records in a browse * ENDBR - Terminates the Browse. The STARTBR Command STARTBR DATASET (file name) RIDFLD (data area) [GTEQ / EQUAL] [GENERIC] [KEYLENGTH (data value)] [SYSID (system name)] Most of these options are the same as for the READ command, except that STARTBR does not have INTO or LENGTH options. These options are unnecessary because STAR TBR does not actually read a record into the program. It merely sets up a starti ng record key from which the READNEXT command works. Also note that, unlike the READ command, STARTBR takes GTEQ as a default option. When a STARTBR command is issued with the GENERIC option the transaction is know n as a generic browse. The READNEXT command READNEXT DATASET (file name) INTO (data area) RIDFLD (data area) [LENGTH (data area)] [KEYLENGTH (data value)] [SYSID (system name)] The READNEXT command reads just one record each time it is executed, therefore a browse program must include a loop that issues the READNEXT command multiple ti mes. The loop should terminate after enough records have been read to fill up th e screen, or until some earlier end point (such as end of file) has been reached . The READNEXT command looks a lot like the READ command. Unlike STARTBR it does i nclude the INTO and LENGTH options, records are actually being read into the pro gram. Unlike READ, READNEXT does not have the GTEQ and GENERIC options, because these options establish the starting browse key, which is taken care of by START BR. The KEYLENGTH and SYSID options are required if the file to be read resides on another system.

The ENDBR Command ENDBR DATASET (file name) [SYSID (system name)] The ENDBR command has two options, DATASET and SYSID. They perform the same func tions in ENDBR as they do in all the other file handling commands. Using the COMMAREA After issuing the ENDBR command, you must issue a RETURN command to return contr ol of the program to CICS. Use the COMMAREA option of the RETURN command in case the user wishes to continue the browse. It is common practice to store the last record key returned by the READNEXT command into a COMMAREA field. When the use r resumes execution of the program, the key stored in DFHCOMMAREA may be moved t o the data area referenced by the RIDFLD option of the STARTBR command. The READPREV Command A browse that reads a file in descending key sequence is called a reverse browse . A reverse browse program is coded using the READPREV command instead of the RE ADNEXT command. The options of the READPREV command are identical to those of th e READNEXT command. A reverse browse program is coded just like a normal browse, except that, after an initial mandatory READNEXT command is issued, the program loop executed the READPREV command instead of the READNEXT command. The RESETBR Command The RESETBR combines the effects of an ENDBR and a STARTBR. It's options are ide ntical to those of the STARTBR. The RESETBR command can be used for a skip-seque ntial browse. During this type of application, the starting key of the browse is reset one or more times during the same transaction. Exceptional Conditions Like any CICS commands, a file handling command may raise an exceptional conditi on when executed. Your programs should include either a HANDLE CONDITION or RESP options and some corresponding routines to handle the more common conditions th at may occur Note: only some of the command options are specified here, please see the CICS m anuals for a full list of available options. On this page you can find out how to use Temporary Storage and Transient Data Qu eues and the CICS commands used to access them. Temporay Storage Queues Transient Data Queues

Temporary Storage Queues WRITEQ TS QUEUE (queue name) FROM (data area) [LENGTH (data value)] [ITEM (data area)] [MAIN / AUXILLIARY] [SYSID (name)]

READQ TS QUEUE (queue name) INTO (data area) [LENGTH (data area)] [ITEM (data value) / NEXT] [NUMITEMS (data area)] [SYSID (name)] WRITEQ TS QUEUE (queue name) FROM (data area) [LENGTH (data value)] [ITEM (data area) [REWRITE]] [MAIN / AUXILLIARY] [SYSID (name)] DELETEQ TS QUEUE (queue name) [SYSID (name)] Temporary Storage Queues Temporary storage provides a means for storing data records in queues. Like file s, these records are identified by a unique symbolic name. Temporary storage que ues do not have to be predefined to CICS. They can be created in main storage or on auxiliary storage devices. Once created, these records can be read either se quentially or randomly by any other CICS program. Temporary storage queues are not directly attached to a task. This means that te mporary storage queues are task independent. Once a temporary storage queue is w ritten, it remains intact after the task that created it has terminated. Temporary Storage Queue Commands There are three commands that process data in temporary storage queues. * The WRITEQ TS command allows you to write records to a temporary storage queue . If no queue exists when this command is issued, one will be created and the re cords will be written to it. * The READQ TS command allows you to read records, either sequentially or random ly, from a temporary storage queue. * Records in a temporary storage queue can be updated and rewritten by using the REWRITE option of the WRITEQ TS command * The DELETEQ TS command allows you to delete an entire temporary storage queue. Individual records cannot be deleted * The queue name specified in a temporary storage command must not exceed eight characters in length Transient Data Queues Like temporary storage queues, transient data queues are task dependent. However transient data queues can only be read sequentially. Unlike temporary storage queues, transient data queues must be defined before th ey are used. This definition takes place in a special Cics table called the Dest ination Control Table (DCT). The DCT is usually maintained by a sys prog. One of the fields in each DCT entry tells whether the queue is an intrapartition or ex trapartition queue. Intrapartition Data Queues Intrapartition transient data queus may only reside on auxilliary storage and ca n only be read sequentially by other CICS programs. Reading an intrapartition da ta queue is destructive. Intrapartition queues may also be associated with Automatic Task Initiation. Whe n the number of records in an intrapartition queue reaches a predefined count a special task is automatically initiated.

Extrapartition Data Queues Unlike intrapartition queus, extrapartition queues can be accessed by other Cics programs as well as batch programs executing outside of the CICS partition or r egion. They can reside on any sequential device, such as disk or tape, or be sen t directly to an off line printer. Reading records in an extrapartition queue is non-destructive. WRITEQ TD QUEUE (queue name) FROM (data area) [LENGTH (data value)] [SYSID (name)] READQ TD QUEUE (queue name) INTO (data area) [LENGTH (data area)] [SYSID (name)] DELETEQ TD QUEUE (queue name) [SYSID (name)] * The WRITEQ TD command allows you to write records sequentially to a transient data queue * The READQ TD command allows you to read sequentially from a transient data que ue * The DELETEQ TD command allows you to delete the contents of an intrapartition TD queue. * Transient Data Queues are referenced by these commands using a symbolic name w hich must be predefined in the DCT * The queue name specified in transient data commands must not exceed four chara cters in length Exceptional Conditions IOERR - An undetermined error has occured during input or output ISCINVREQ - an undetermined error has occured on a remote system ITEMERR - The requested item number is invalid LENGERR - The length of a record is invalid or missing NOSPACE - A write has failed due to lack of space QIDERR - The requested queue cannot be found QZERO - A read has been attempted on an empty queue SYSIDERR - The specified remote system is unavailable or not defined CICS maps are created using special Assembler Language macros. It is not necessa ry to know much about assembler to create CICS maps. There are special screen painters available (eg IBM's SDF II) which take the ha rd work out of coding assembler macros, these screen painters will generate the necessary assembler macros to create your map. This page will show you how to code the assembler macros necessary to create a CICS map for your program. This page is intended as a quick guide only, many other options are available, if you want to know more, check out the CICS Application Programming Guide. Symbolic and Physical Maps

Creating a Map Coding the Map Generating the Load module (Physical Map) and Copybook (Symbolic Map) Using The Generated Copybooks (Symbolic Map) Arrays Symbolic and Physical Maps Two terms commonly used when creating maps are the Symbolic Map and the Physical Map. The symbolic map is essentially a copy library member which allows you to refer to fields on the map from your COBOL (or PL/1 or C or Assembler) program. The physical map is the code generated by the assembler to allow the system to d isplay the map i.e. the object module. Some Rules Before coding your map you must be aware of some rules for coding the assembler statements. There may seem to be a lot of rules, but don't worry they are fairl y simple to get your head round. Columns: Columns 1 to 71 are where you code your assembler statements. Column 72 is for a continuation marker if you need to continue a line. Columns 73 to 80 are for a line sequence number of comment. Continuation Lines: Any statement can have only two continuation lines. The text of the continuatio n line must start in column 16. To continue a line you put any character (except blank) in column 72. Comments: Comment line are indicated by placing an asterisk ('*') in column 1. A comment line can NOT be placed between continuation lines. and comment lines can NOT be continued. You cannot have blank lines in the assembler program. The Assembler Statement: The statement consists of four components: The optional name, starting in colum n1 (max length seven characters), the mandatory operation specifying the assembl er instruction or macro, the operands which specify the parameters and an option al comment.

Creating A Map Once you have created your map, you need to run it through the assembler. The m ap must be assembled twice with different parameters. The first pass throught th e assembler, you specify TYPE=DSECT, this will create a copy library member that you can copy into your CICS/COBOL program. The second pass through the assemble r, you specify TYPE=MAP, this will create an object module which will be passed through the link editor (binder) to produce a CICS load library member. Coding the CICS Map. There are normally 3 macro nd DFHMDF. The DFHMSD macro defines a The DFHMDI macro defines a The DFHMDF macro defines a

used when coding your map. They are DFHMSD, DFHMDI a mapset. map within a mapset defined by by DFHMSD field within the map defined by DFHMDI.

Don't worry too much about the first two macros, they won't change much from map to map. The first statement in your program should be a DFHMSD macro statement, this wi

ll define the mapset. It will look something like this: MAPSN DFHMSD TYPE=DSECT, CTRL=FREEKB,DATA=FIELD,LANG=COBOL, MODE=INOUT,TERM=3270,TIOAPFX=YES X X

"MAPSN" is the name of the mapset to be created. "TYPE=" is used to specify whet her a copybook member is to be generated (TYPE=DSECT) or an object library membe r is to be created (TYPE=MAP). "CTRL=" specifies the characteristics of the 3270 terminal "DATA=FIELD" specifies that data is passed as contiguous fields. "LANG=COBOL" specifies the source language for generating the copy library memb er. "MODE=INOUT" specifies that the mapset is to be used for both input and output. "TERM=" specifies the terminal type associated with the mapset. "TIOAPFX=YES" specifies that fillers should be included in the generated copy l ibrary member. The next statement you should include is the DFHMDI macro statement to define th e map charcteristics. It will look something like this: MAPNM DFHMDI COLUMN=1,DATA=FIELD, JUSTIFY=(LEFT,FIRST),LINE=1, SIZE=(24,80) X X

"MAPMN" is the name of the map. "COLUMN=1","LINE=1" and "JUSTIFY=(LEFT,FIRST)" establish the position of the ma p on the page. "DATA=FIELD" specifies that the data is passed as a contiguous stream. Most of the time the DFHMSD and DFHMDI operands will not need to be changed. th e only changes will be the mapset name and map name. Once you have coded these statements you can now get on with defining the field s that will appear in your map. (ie the important bit). We'll start out with a couple of sample definintions: FNAME DFHMDF POS=(1,5),LENGTH=10, ATTRB=(UNPROT,BRT,FSET), INITIAL='XXXXXXXXXX',PICIN='X(10)', PICOUT='X(10)',COLOR=RED * DOB DFHMDF POS=(2,5),LENGTH=8, ATTRB=(UNPROT,NORM,NUM,ASKIP), INITIAL='00000000',PICOUT='9(8)'

X X X X X

First in the definition is the field name ("FNAME" and "DOB") followed by the ma cro DFHMDF "POS=(x,y)" specifies where on the screen the field is to be placed. x is the l ine and y is the column. "LENGTH=" specifies the length of the field to be generated. "ATTRB=" specifies a list of attributes for the field. UNPROT means you can typ e data in to the field, BRT means the field intensity is BRighT, NUM that the fi

eld is numeric only. "INITIAL=" specifies an initial value for the field. "PICIN=" and "PICOUT=" allows you to specify a picture clause for the field. Th is lets you specify editing characters such as Z to suppress leading zeros. "COLOR=" is used to define the colour of the field. Note that you must specify MAPATTS=COLOR on the DFHMDI macro to use the COLOR option . Once you have specified all the fields to be included on the map (the maximum n umber of fields is 1023) you must then specify a final macro to indicate the end of the map. You specify the DFHMDF macro with the operand TYPE=FINAL, like this : DFHMDF TYPE=FINAL And that's it. Here's a quick example mapset definition (note this has not been tested): MAPS1 DFHMSD TYPE=&SYSPARM,MODE=INOUT,TIOAPFX=YES,LANG=COBOL, X TERM=3270-2 MAP1 DFHMDI SIZE=(24,80),CTRL=FREEKB,MAPATTS=COLOR FNAME DFHMDF POS=(1,5),LENGTH=10, X ATTRB=(UNPROT,BRT,FSET), X PICIN='X(10)',PICOUT='X(10)' LNAME DFHMDF POS=(1,25),LENGTH=10, X ATTRB=(UNPROT,BRT,FSET), X COLOR=RED, X PICIN='X(10)',PICOUT='X(10)' CRLIM DFHMDF POS=(3,5),LENGTH=8, X ATTRB=(UNPROT,NUM,NORM,FSET), X PICOUT='ZZZZ9.99' DFHMSD TYPE=FINAL END

Generating the Load module (Physical Map) and Copybook (Symbolic Map)

Once you have defined your map,you must then 'Assemble' the map. The code you ha ve created has to be passed through the assembler twice. The first time is to cr eate the load module, the second time is to create the Copybook layout. As menti oned above, to create the load module the TYPE parameter of the DFHMSD macro mus t be set to MAP, and to create the copybook the TYPE parameter must be set to DS ECT. To make life easier you can specify TYPE=&SYSPARM. This will let you pass t he MAP or DSECT parms when you assemble the map. There is an IBM supplied JCL PROC called DFHMAPS which can be used to assemble the maps, this will handle the assembling of maps for you and pass the appropria te value for TYPE when required, or you site may have it's own way of assembling maps.

Using The Generated Copybooks (Symbolic Map). When your map has been generated you will have a new Copybook. If you take a loo k at the copybook you will see that there are two main definitions (Level 01). T he first is the mapname suffixed by an 'I' , for Input, the second is the mapnam e suffixed by an O, for Output. The input definition is used to display the map field via the SEND MAP CICS command. Within the Input definition you will see al l the fields you specified defined. For each of these fields there will also be a length field suffixed by 'L', and an Attribute field, suffixed by 'A'. There w

ill also be a Flag field suffixed by F, this isn't normally used. You can change the colour, and protection attributes by changing the A field. T o do this you should copy the DFHBMSCA copybook into working storage. This conta ins definitions for attributes eg DFHBMASK to set a field to SKIP. Then move the required attribute to the 'A' field. The length field can be used to set where the cursor will be positioned when the map is displayed. Simply move -1 to the length field, prior to the SEND MAP. The output part of the copybook definition should be used as a receive area aft er the user has pressed Enter (or a PF Key) - RECEIVE MAP...... INTO...

Arrays You can use BMS Macros to define an array of fields with the same name. However using Assembler Macros you can only specify a horizontal array. To do this you u se the OCCURS= parameter on the DFHMDF macro. If you want to specify a Vertical array then you must specify each field in the array seperatley using BMS Macros and then edit the generated symbolic map (Copy book). When using a screen painter such as IBM s SDF II you can specify the array direct ion, and the screen painter will generate the correct symbolic map to let you us e horizontal arrays.without the need for editing the generated code.

It is possible to submit commands to a CICS region from a jcl jobstream. The JCL uses the MVS Modify command to execute the CICS commands. Note: In order for this to work, a console entry in the CSD must have been defi ned. For CICS running under MVS prior to SP 4.1 it will be CONSOLE(00), for CICS running under SP 4.1 or later it will be CONSNAME(INTERNAL). The following job shows you how to submit commands: //CICSMOD01 (acct-info),CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1) //* //* //STEP01 EXEC PGM=IEFBR14 // F CICSREG1,'CEMT SET PROG(EBR001) NEW' // F CICSREG1,'CEMT I TER' // The format of the modify command is : F jname,cicscommand jname is the job name or taskid of the CICS region. cicscommand is the CICS command to be executed. You can omit the apostrophes ro und the command if you wish, but if there are sequence numbers at the end of the line a warning message is displayed on the console (the command will be execute d never-the-less.)

External CICS Interface - An Overview Introduction

This document will provide a quick overview of the External CICS interface, what it is and options available. Overview The external CICS interface (EXCI for short) allows programs running in batch, t o execute a program that exists in an CICS environment. The batch program is known as the client program and the CICS program is known as the server program. Data is passed between the programs via a commanications area. The CICS (server) program is invoked as if it was called/linked to by anot her CICS program. The interface lets you open a session (also known as a pipe) in the CICS region and pass a request (or several requests) to CICS (known as a distributed program link request or DPL request). Using the External CICS interface you can udate resources while CICS is using th em or alternatively take resources offline at the start of a job and put them ba ck online when the job finishes. (You can open and close files and enable or dis able individual transactions) Requirements To run programs using the external CICS interface you must be using CICS/ESA Ver sion 4.1 or later. The client program can only connect to the server CICS region only through the i nterregion communication program DFHIRP, which must be installed in the extended link pack area. In order to connect the client program to the CICS region a connection definitio n must be defined to CICS using the CONNECTION and SESSIONS resource definition facility (via RDO or DFHCSDUP). Programming Interfaces Two forms of interface are provided by the External CICS Interface: 1) The EXCI Call Interface. This consists of six commands which let you initiali ze and open the interface, submit a request or requests and close the interface. 2) The EXEC CICS interface. This provides a single command (EXEC CICS LINK) to s ubmit a request, the opening , closing and initialization is done automatically. Choosing the correct Interface. Your choice of interface will depend on the requirements of the application. For single requests or infrequent requests it is recommended that you use the EX EC CICS LINK command. This should be used in these circumstances because all DPL functions must be executed for each invocation of the LINK command causing addi tional overheads. Where your application requires frequent or multiple requests you should use the EXCI Call Interface. This is more efficient because you only have to perform th e Initialize and Allocate once at the beginning of your program. You can then op en and close the pipe as necessary and issue as many DPL calls as required, befo re deallocating the pipe at the end of the program

CICS Storage Violations CICS Storage violations can seem to be one of the most difficult problems to dea l with when debugging. Storage Violations can in the worst cases bring down CICS and can sometimes go undetected by CICS which could lead to problems in the fut ure. Storage violations involving overwriting CICS control blocks or CICS storag e will in most cases lead to CICS falling over . Storage violations of user storage areas can sometimes go undetected and may not cause a CICS failure. By understanding how CICS detects storage violations, you can make the task of d ebugging a storage violation easier. When you request an area of storage in CICS, such as for the program s commarea, C ICS will add 16 bytes of storage to the area of storage. It adds 8 bytes at the start and 8 bytes at the end. CICS will then put a value in each of these areas. If the value changes then CICS will detect a storage violation! However, CICS w ill not necessarily detect the storage violation when it happens. This is becaus e CICS will only check for a violation when the area of storage is freed up. So the storage violation could occur at the start of your program but not actually be detected until later, for example when the program terminates or calls anothe r program. The most common reasons for storage violations are programming errors. Common re asons are different length DFHCOMMAREAs when your program calls or is invoked by another program, or subscript errors causing data to be stored beyond the end o f the storage area. It is also possible that another program has overwritten your storage, your prog ram may detect that it s storage has been overwritten by the other program. If you suspect that it is not your program that is at fault, try doing a CEMT New Copy of your program. As CICS has evolved new methods of protecting storage have been added to CICS (F rom version 3.3 of CICS it has been possible to switch storage protection on in a CICS region) , however many sites still do not take advantage of them this may be because some older software may require that the storage protection options be switched off. If you switch on storage protection in a CICS region, then you may find that yo u get a lot more storage violations in existing programs, this could be because the storage violations went undetected previously.

Some of the more common CICS abends are briefly described below.These are only b rief descriptions and do not cover all possible reasons. You should check the ap propriate IBM manual(s) for full details ASRA This is the most common abend in CICS. It indicates a Program Check Exception, r oughly equivalent to having an S0C7 in a batch program. Check for spaces in a pa cked decimal numeric field and changes to the file and record layouts. AEIx and AEYx

There are numerous abends that start with AEI or AEY. They indicate that an exce ption has occured, and RESP (or NOHANDLE) is not is use. The last character indi cates the exact error AEI0 indicates a PGMIDERR. AEI9 is a MAPFAIL condition, AEIO indicates a duplicate key (DUPKEY) condition. AEIN indicates a duplicatebrecord (DUPREC) condition. AEID indicates an End of file condition. AEIS indicates that a file is not open (NOTOPEN) AEIP indicates an invalid request condition (INVREQ) AEY7 indicates that you are not authorised to use a resource (NOTAUTH)

See the CICS Messages & Codes Manual for more details. AICA This abend usually occurs if your program is looping. There are CICS parameters that determine how long a task can run without giving up control. The ICVR para meter in the CICS SIT table can be used to specify a value for all tasks running in CICS, or you can specify a RUNAWAY value when you define a transaction . If a program is looping then you may not get an AICA abend, because the timer can b e reset when certain events occur, eg some EXEC CICS commands may reset the time r to zero. ATCH and ATCI These abends indicates that the task was purged. The task may have been purged b y someone issuing a CEMT command to purge the task, or by CICS because the Deadl ock timeout limit has been exceeded or because there was not enough virtual stor age available to run all the tasks in CICS (Short on Storage) APCT A program was not found or was disabled. Check the transaction definition to see if the program name was misspelled. Check that the program is enabled. Check th at the program is in an appropriate Load Library (ie one defined to the current CICS system). AKCP and AKCT These abends indicate that a timeout of the task occurred. This may be due to a deadlock. AFCA A dataset could not be accessed because it was disabled. ABM0 The specified map was not found in the specified mapset. Check that you have not

misspelled the map name.

The Execute Interface Block (EIBLK) contains a variable called EIBFN.This contai ns a value that tells you what CICS command was last executed. This value can be displayed as part of an error message, to aid in the debugging of your code or when an exception condition occurs The values for EIBFN are show below. Code 0202 0204 0206 0208 020A 020C 020E 0210 0402 0404 0406 0408 040A 040C 040E 0410 0412 0414 0416 0418 041A 041C 041E 0420 0422 0424 0426 0428 042A 042C 042E 0430 0432 0434 0436 0438 043A 043C 043E 0602 0604 0606 0608 060A 060C 060E 0610 0612 Command ADDRESS HANDLE CONDITION HANDLE AID ASSIGN IGNORE CONDITION PUSH POP ADDRESS SET RECEIVE SEND CONVERSE ISSUE EODS ISSUE COPY WAIT TERMINAL ISSUE LOAD WAIT SIGNAL ISSUE RESET ISSUE DISCONNECT ISSUE ENDOUTPUT ISSUE ERASEAUP ISSUE ENDFILE ISSUE PRINT ISSUE SIGNAL ALLOCATE FREE POINT BUILD ATTACH EXTRACT ATTACH EXTRACT TCT WAIT CONVID EXTRACT PROCESS ISSUE ABEND CONNECT PROCESS ISSUE CONFIRMATION ISSUE ERROR ISSUE PREPARE ISSUE PASS EXTRACT LOGONMSG EXTRACT ATTRIBUTES READ WRITE REWRITE DELETE UNLOCK STARTBR READNEXT READPREV ENDBR

0614 0802 0804 0806 0A02 0A04 0A06 0C02 0C04 0E02 0E04 0E06 0E08 0E0A 0E0C 0E0E 1002 1004 1006 1008 100A 100C 1202 1204 1206 1208 1402 1404 1602 1802 1804 1806 1808 180A 180C 180E 1810 1812 1C02 1E02 1E04 1E06 1E08 1E0A 1E0C 1E0E 1E10 1E12 1E14 2002 4802 4804 4A02 4A04 5602 5604 5606 5610 5E06 5E22

RESETBR WRITEQ TD READQ TD DELETEQ TD WRITEQ TS READQ TS DELETEQ TS GETMAIN FREEMAIN LINK XCTL LOAD RETURN RELEASE ABEND HANDLE ABEND ASKTIME DELAY POST START RETRIEVE CANCEL WAIT EVENT ENQ DEQ SUSPEND WRITE JOURNALNUM WAIT JOURNALNUM SYNCPOINT RECEIVE MAP SEND MAP SEND TEXT SEND PAGE PURGE MESSAGE ROUTE RECEIVE PARTN SEND PARTNSET SEND CONTROL DUMP ISSUE ADD ISSUE ERASE ISSUE REPLACE ISSUE ABORT ISSUE QUERY ISSUE END ISSUE RECEIVE ISSUE NOTE ISSUE WAIT ISSUE SEND BIF DEEDIT ENTER TRACENUM MONITOR ASKTIME ABSTIME FORMATTIME SPOOLOPEN SPOOLREAD SPOOLWRITE SPOOLCLOSE CHANGE TASK WAIT EXTERNAL

5E32 6A02 6C02 6C12 7402 7404 7406 7408 7E02

WAITCICS QUERY SECURITY WRITE OPERATOR ISSUE DFHWTO SIGNON SIGNOFF VERIFY PASSWORD CHANGE PASSWORD DUMP TRANSACTION

Multiple CICS Regions (MRO) What is MRO ? MRO (or Multiple Region Option) is the term used to describe a set of inter-link ed CICS regions. Each region may perform a different function, such as an FOR (F ile Owning Region). An FOR would contain all the definitions for the files that will be used by CICS. When an action such as READ or WRITE is requested, the req uest can be routed to the FOR. The CICS regions communicate with each other usin g Inter System Communication (ISC). The CICS regions must be in the same MVS ima ge or in the same MVS sysplex to use MRO. Why use MRO ? In the early days of CICS, before MRO, all definitions for files, terminals, pro grams etc would be stored in one CICS region. These definitions all take up CICS storage, as the numbers of terminals, files etc increase so the amount of stora ge available for running programs is reduced. This could often lead to problems with CICS because of a lack of available storage. The CICS system might eventual ly grind to a halt and have to be re started. The term for this kind of problem is Virtual Storage Constraint (VSC). Using MRO can help to relieve the problems of VSC. Resource definitions could be stored in different CICS regions that were linked together in order to reduce the amount of storage required in the main C ICS region. Different resource types are generally grouped together in a particu lar region which gives rise to the term owning Region . So a CICS region that has a ll the terminal definitions is called a Terminal Owning Region or TOR, the regio n that contains the applications programs is called the Apication Owing Region o r AOR. Another reason for using MRO might be that you have seperate development teams t hat require access to the same files or database, but are developing different a pplications. You could specify different Application Regions, which are both con nected to the same File Owning Region. Team 1 could develop their applications i n AOR 1, and Team2 could develop their applications in AOR 2. If there are any p roblems with the applications in AOR 1, then Team 2 could continue working in AO R 2.

Transaction Routing. Transaction routing lets you run a transaction in any connected CICS system. Whe n you enter the transaction id the transaction might run in any one of the conne cted CICS regions. Function Shipping. Function Shipping lets your program access resources by 'shipping' requests to a nother CICS region. For example if your program requests access to a file, the f ile control request might be shipped to the File Owning Region. You can also shi

p requests for access to TSQs, TDQs and databases owned by another CICS region. When you write an application you do not need to know where the resource is loca ted. The CICS resource definitions will specify where the required resources are . Connecting to other Regions in MRO. When you logon to CICS you will (in most cases) be logging in to the Application Owning Region. If you want to look at (say) a definition of a file in the FOR y ou might find that you cannot see the details of the file because it is in anoth er region, or you may want to change the definition of the file and are unable t o, because it is in the FOR. So how do you get into the FOR? Many sites use some form of session manager (NC-ACCESS, MULTSESS, Tubes, etc) which will only let y ou login to the AORs. To overcome this problem you should login to the CICS regi on as you would normally do. Then you can use the CRTE transaction to login to a nother region. eg CRTE SYSID=xxxx , where xxxx is the name of the region you want to go to (You can find out names of the connected regions using CEMT INQUIRE CONNECTION). You then login using the CESN transaction. Once you have done all the work you w ant to, you return to the original CICS region by entering 'cancel'

CICS FEPI What is FEPI? FEPI stands for Front End Programming Interface. It is a terminal emulator imple mented via a Programming Interface. FEPI is integrated into CICS, so if you have CICS (CICS/ESA V3.3 or above) then you already have access to FEPI. FEPI can co mmunicate with transactions running on CICS or IMS systems. What can I do with FEPI? FEPI can be used to integrate your existing CICS applications into one system wi thout needing to alter the existing systems. For example if two companies merge, FEPI can be used to provide a single user i nterface to both of the merged companies' systems. Another example, if you want to be able to access all a customer's details from a number of different systems in one single system - you could have a single screen where the user enters the customer's name and the FEPI interface will go to, for example, the Home Insura nce system, the Motor Insurance system and Accounts system retrieve details from each of these systems. The information from each of these different systems wil l be returned and be available for displaying on one screen. This could be usefu l, for example, for cross selling. You might be able to see that a customer has Motor Insurance, but not Home Insurance, you could then ask the customer if they had considered buying your company's Home Insurance product! You could also use FEPI to add new functions to a system. Say you want to keep a n existing system stable, but want to add new functionality, you could write a p rogram which would use FEPI to access the stable system, and access the programs which contain the new functionality when it is required. As part of your company's Web enablement you could use FEPI to provide an interf ace between your CICS systems and your Web site. You could keep the existing CIC S systems, but have a FEPI based system to handle enquiries from the Web. The FE PI programs would extract the required information from the existing system and return it to the Web server. Further Reading CICS Front End Programming Interface User's Guide (IBM SC33-1629-02) The CICS Programmer's Guide to FEPI (McGraw Hill ISBN 0-07-7077793-8)

CICS Program Compilations under TS V2 CICS Transaction Server Version 2 now includes an integrated translator component . This means that you can compile programs to be used under CICS using a single j ob step no more CICS Translate Step. The CICS Translate step was required to translate any EXEC CICS commands into so mething that the language compiler could understand, in COBOL for example EXEC C ICS commands were converted into CALLs. Once the translator had completed the ge nerated code was passed to the compiler and finally the compiled code was passed to the link editor. For DB2 CICS Programs you would have to feed the source code firstly to the DB2 Preprocessor, then through the CICS translator, and then that would go to the co mpile and link edit steps. The integrated translator in CICS TS combines the translate and compile into on e. The integrated translator can handle CICS API commands, CICS SPI (System Prog ramming Interface) commands, CICSPlex SM API commands and DL/I EXEC DLI commands . DB2 commands (EXEC SQL) are translated using the SQL integrated coprocessor . You now only need two steps in your job, the Compile and the Link Edit. All the diagnostic messages will now appear in the one listing, And the compiler statement numbers will be the same as they are in the original source code. The combining of the translator and compiler now means it is possible to have CI CS and DB2 commands inside copybooks. Previously the copybooks were not expanded until the compile step, so any CICS or DB2 Commands in a copybook would be miss ed by the translate and preprocessor phases. Another feature of using the integrated translator is that when you CALL anothe r program you no longer have to pass DFHEIBLK and DFHCOMMAREA as arguments. Thes e two areas are defined as GLOBAL in the outermost program and so are available to any called programs. An important change has taken place with the Execute Interface Block (DFHEIBLK) definitions. All binary (COMP) fields are now defined as COMP-5. This means that they are unaffected by what you specify in the TRUNC compiler option, which has been the source of some problems in the past. For more information visit http://www.ibm.com/software/ts/cics/v2

Occasionally you may wish to submit a batch job (JCL) to JES from CICS. CICS pro vides an interface to JES to allow you to submit JCL to the internal reader. You submit JCL using the SPOOLOPEN, SPOOLWRITE and SPOOLCLOSE commands. To access the SPOOL: 1) First you must open a spool for output using SPOOLOPEN

EXEC CICS SPOOLOPEN OUTPUT NODE('*') USERID(INTRDR) TOKEN(report_token) RESP(response field) END-EXEC. NODE('*') specifies a destination node to send the JCL to. USERID is set to the name of the internal reader INTRDR A unique token will be allocated by CICS when the SPOOLOPEN is executed and plac ed in the field you specify using TOKEN(report_token). The token will be used as a sending field on subsequent commands. The token will be 8 bytes long. RESP must be coded, allowing you to check if the command executed successfully. 2) To write each line of the job to the spool use the SPOOLWRITE command. EXEC CICS SPOOLWRITE FROM(io_area) TOKEN(report_token) RESP(resonse_field) END-EXEC. The "io_area" field should be the name of a data item containing the line of JCL . The "report_token" field should be the same as the 8 byte token returned from SPOOLOPEN. An end of job statement ('//' or '/*EOF') should be written as the last line. 3) Finally you must close the spool using SPOOLCLOSE. (Note if you do not explic itly close the spool it will be closed when the transaction terminates, However it is good practice to close the spool explicitly) EXEC CICS SPOOLCLOSE TOKEN(report_token) RESP(response_field) END-EXEC. Again the "report_token" field must be the same as the one allocated at SPOOLOPE N. Notes: The RESP option should be coded on all the Commands and it is recommended that you also code RESP2, because additional information is returned for some excepti on conditions in this field. DCT entries and JCL DD statements are not needed when using this method. Note that in order to use this method DFHSIT SPOOL=YES must be coded in the CICS System Initialization Table. Check with your friendly local SysProg if you are unsure. Under OS/VS COBOL the SPOOLWRITE command had to have FLENGTH specified. FLENGTH specifies the length of the data being written in a fullword binary field. This field is optional in newer versions, if it is omitted then the length is assumed to be the length of the data item (io-area) specified in FROM. Be aware of the performance considerations for writing to the spool, IBM says "T ransactions that process SYSOUT data sets larger than 1000 records, either for I NPUT or for OUTPUT, are likely to have a performance impact on the rest of CICS" . (Source: CICS/ESA V4R1 Application Programming Reference SC33-1170-00)

EDF If you are using CICS Transaction Server, you can now use the CEDX transaction to start EDF. CEDX turns on EDF for a transaction rather than a terminal. CEDX i s useful for non-terminal based programs (ie programs that use no screens or ter minal input/output). The EDF session behaves in exactly the same way as CEDF. Se e the CICS Application Programming Guide for more details.

CEBR For Transient Data Queues. You can browse TD Queues using CEBR. To browse a TDQ enter CEBR as usual, and is sue the GET command. This will copy the TDQ to a TSQ so that you can browse it. See the CICS Application Programming Guide for more details.

DFHBMSUP Utility. The DFHBMSUP utility reads the Load Module for a CICS BMS map and creates the BM S macros required to produce the map, ie it does some reverse engineering on you r map. This can be useful if the BMS Macros have been lost. DFHRPL should point to the load library and BMSOUT tells the utility where to st ore the Macro definitions. //HERC01BM JOB (HERC01),'DFHBMSUP',CLASS=A,MSGCLASS=X, // MSGLEVEL=(1,1),NOTIFY=HERC01 //* //* CREATE BMS MACRO DEFINITIONS FROM A MAP LOAD MODULE //* //* INPUT MEMBER NAME IS SPECIFIED IN THE PARM FIELD //GENMACRO EXEC PGM=DFHBMSUP,PARM='JC010M04' //STEPLIB DD DSN=CICS.CTS.SDFHLOAD,DISP=SHR //* //DFHRPL DD DSN=HERC01.DEV.LOADLIB,DISP=SHR //* //BMSOUT DD DSN=HERC01.DEV.CICSMAP(TEST1),DISP=SHR //* //SYSUDUMP DD SYSOUT=* //SYSPRINT DD SYSOUT=* //*..

CMAC Transaction. This CICS transaction lets you look up CICS messages and codes online.

DFHCSDUP Utility. You can use this utility to add, alter, view and remove definitions. This can be used instead of RDO. (see the CICS Operations and Utility Guide).

CICS Dump utility The following job will print a CICS dump. It reads the CICS Dump dataset defined as DDName DFHDMPDS and produces a listing. You select which dump you want using control statements in SYSIN. In this case Dumps for the TRANID HM05 are selecte d. The program name may vary depending on which CICS version you are using. //HERC01DP JOB (HERC01),'PRINT DUMP',MSGLEVEL=(1,1), // CLASS=A,MSGCLASS=X,REGION=2M //* //* CICS TRANSACTION DUMP FORMAT UTILITY //* FOR CICS V5R3M0 (CICS TS 1.3) //* //* //STEP010 EXEC PGM=DFHDU530,PARM='SINGLE' //STEPLIB DD DSN=CICS.CTS.SDFHLOAD,DISP=SHR //* //DFHDMPDS DD DSN=CICS0.CICS.DFHDMPA,DISP=SHR //*DFHDMPDS DD DSN=CICS0.CICS.DFHDMPB,DISP=SHR //DFHTINDX DD SYSOUT=8 //DFHPRINT DD SYSOUT=8,DCB=(BLKSIZE=133) //SYSPRINT DD SYSOUT=8 //SYSIN DD * SELECT TYPE=OR TRANID=HM05 END /*