Friday, September 21, 2007

CICS about TABLES

CICS LEVEL II

MODULE 1

First Class presents an advanced course in CICS/VS for COBOL application programmers. The course is designed to aid the application programmers. The course is designed to aid the
programmer in developing applications quickly and easily.

The Customer Information Control System, which is commonly referred to as CICS.

The new version of CICS:

_ offered its users a number of services which aided operating system efficiency.
_ shared resources in an efficient manner.
_ predefined resources for easy access.
_ provided only minimal user protection for efficiency.

CICS is a very efficient system but it is also a very complicated environment.

Computer professionals must design application programs to ensure the integrity of the data.

Third party tools are often used when developing programs to help destroyed.

CICS has been evolving for a number of years and it continues to change to meet today's high on-line transaction volume.

Your mainframe computer's memory stores everything it needs to run the system and needs to run the system and to run user applications.

The MVS operating system is used here for illustration purposes, however, other systems are similar.

MVS/XA is divided into a number of regions. A region can be running a batch job, servicing a single time sharing user or it could be running CICS.

If it's running CICS, it's servicing hundreds of users.

CICS contains different areas for storage. Some areas store:
_ CICS system software
_ CICS control tables
_ application programs
_ the user's working storage

Application programs never talk directly to the operating system. It is always done through CICS.

How many CICS regions do you think can run on a single machine?
The number of CICS regions is only limited by the resources available.

The number of terms are frequently used throughout this course. Here are four of them:

- task
- conversational mode
- pseudoconversational mode
- transaction

TASK

When the user enters a 1 - 4 character TRANSID at a terminal, a task is initiated.

The program associated with the TRANSID is loaded and executed.

As the program runs, it may acquire storage for execution purposes or for passing data.

When the program ends:
- storage disappears
- the task disappears

Do you think the program also disappears?
No. The program remains inactive but is written over if other users require space.

If the program needs to keep information for later use, it must be specifically saved.

A task can also span more than one program and/or subroutine.

When an EXEC CICS LINK statement is executed, control is passed to the linked program or subroutine.

An EXEC CICS RETURN statement passes control back to the calling program and the subroutine disappears.

What do you think happens when control is passed back to the program?
Execution continues from where the program left off. However, the program may choose to end at that time.

We already know that a task can be started by entering a TRANSID. Do you think a task could be started from another task?
Yes. By executing a START TRANSID command, a new task is initiated and the corresponding
program located.

If the new task is to start on the same terminal that initiated it, then it must wait until the current task finishes executing.

Are the following statements (T)rue or (F)alse?

T - Control is passed back to a calling program when EXEC CICS RETURN is executed in the inked program.
F - The task always terminates when a LINKed program finishes executing.
T - The START TRANSID command initiates a task from within a program.

CONVERSATIONAL MODE

When a task is initiated, the program uses the SEND command to relay output to the terminal.

The program then sits in memory, waiting for user input.
­
When the user types in the data and presses enter, the program's RECEIVE command accepts the input.

This process of sending, waiting and receiving continues until the program and the task end.

PSEUDO CONVERSATIONAL MODE

In pseudoconversational mode, a task is initiated and output is sent the same as it was in conversational mode.
However, this time the program does not sit in memory waiting for input. Instead, a RETURN RANSID command stores information such as:
- Terminal ID
- TRANSID

When the user enters input, CICS detects the input and initiates the TRANSID which invokes the program.
A new task is initiated and
- the program executes from the beginning.
- previously recorded data is read to determine where to start executing.
- the input data is processed.
- The task ends.
Input is RECEIVEd from the terminal.
Output is sent to the terminal. Output is likely sent to the terminal before the task ends.

This process of:
- task initiated
- program starts
- program reads input
- input processed
- output sent
- store TRANSID/environment information
- program ends
- task ends
continues until the user chooses to quit.

Complete the following statements:

- When the user enters the TRANSID, program execution begins.
- In CONVERSATIONAL mode, the program responds with output and awaits input from the user.
- In PSEUDOCONVERSATIONAL mode, the transaction is initiated whenever input is received and program execution is triggered.
- In pseudoconversational mode, user input at the terminal will cause the TRANSID to be retrieved and a new task initiated. Program execution will then continue from where it left off.

A transaction can be: .

- the programmer sees a transaction in terms of the system as a whole.
- "How did the finance transaction go?"
- "Good! The accounting office ran 50,000 transactions."
- operators see a transaction as an interaction with a user.
- In pseudoconversational mode, a transaction is equal to a task.
- In conversational mode, it's like a SEND/RECEIVE.
- "Good! We ran 10,000 transactions".
- the accountant sees a transaction as a logical Accountant unit of work.(An accounting
transaction may take five or six user interactions.)

These statements describe a situation. What is the type of mode, task and transaction?

- a screen is presented.
- the user inputs all data related to the customer
- when the user presses enter, a new task is initiated.
- the program receives the data, validates the fields and processes the order.

The computer does not wait around while the user inputs all the fields. Rather, it accepts them all at the same time. This is one transaction and one task in pseudoconversational mode.

Here's another set of processing steps for the same customer order. What type of mode, task and transaction do these statements describe? .

- a screen is presented.
- the user inputs the first Name field.
- the program receives and validates the data.
- the screen is returned for input in the next field.

The program processes this data one field at a time. It is a multiple task, multiple transaction order in pseudoconversational mode.

The first thing loaded into a CICS region is the CICS system software (ie. the nucleus).

This software manages CICS operation and its communications between transactions and the
operating system.

CICS Control Tables are also loaded into the region.

These tables contain information which is specific to the organization's resources.

Who do you think creates and maintains these tables?
Typically, these tables are created and maintained by SYSTEMS PROGRAMMERS. ¦ Special CICS routines aid in this process.

There are 16 Control Tables (or blocks of information required by CICS). Some that you will see in upcoming modules are related to:

- Files (FCT)
- Transaction ID's (PCT)
- Programs and Maps (PPT)
- Destination (DCT)
- Terminals (TCT)

Using assembler macros is one way of defining entries in CICS Control Tables.

the table name (PCT- Program Control Table).
DFHPCT TYPE=ENTRY,
TRANSID=ORDR,
- a macro entry other than the first list definition.
RSLC=NO,
PROGRAM=ORDERENT
- a 4 character TRANSID code.
- resource security level checking parameter.
- the program name associated with the TRANSID.

These macros are compiled and combined with other information to create the control tables needed to run CICS. (In Module 6 you'll learn about another method: - using the CEDA transaction in RDO (Resource Definition On-line)).

PCT - PROGRAM CONTROL TABLE

- The Program Control Table is a list of all valid CICS TRANSID's.
- When a TRANSID is entered, CICS checks the PCT to determine which program the user wants executed.
- The Security parameter ensures that a user is allowed to access the program.
- Using the program name, CICS can now use the PPT (Program Processing Table) to find the program location.

PPT - PROGRAM PROCESSING TABLE

- The Program Processing Table contains program and mapset information.
- Using the program name retrieved from the PCT, the program location is checked in the PPT.
- The disk location tells CICS where to find the program on a DASD.
- The memory location tells CICS where to find the program in main memory.
- If memory location is zero, the program is not presently in memory.

FCT - FILE CONTROL TABLE

- The File Control Table contains an entry for every accessible file.
- For example, the type of allowable operations will be listed. (eg: ADD, BROWSE, DELETE)
- The value in the status parameter describes whether a file is open or closed.
- Files specified in an application program are located through this table. (A file must be opened before it can be accessed.)
- An entry contains the name and parameters associated with that file.
- This is essentially an access security feature. Users are allowed only those operations listed in the table.

DCT - DESTINATION CONTROL TABLE

- Using the DCT or Destination Control Table,a transaction can be identified with a set of instructions for processing data.
- Each destination name is associated with a terminal, a printer, or a file.
- Each destination name is also associated with a transaction which will do the actual processing.

PPT contains the description of the program.

FCT contains parameters associated with files.

DCT associates a TRANSID with a destination.

PCT associates a TRANSID with a program.

In addition to storing Control Tables, CICS sets aside storage space for user programs and mapsets.

When a program is copied into CICS program storage, multiple users can access different statements within the same program.

You might be wondering how different users can access the same program and not affect the contents of each others variables???

The answer lies in the way in which CICS handles Working Storage. We'll explore that aspect next.

If three users are accessing the same program, each gets a copy of Working Storage for their exclusive use.

Recall our task discussion. It stated that the program disappears when the task ends.

Do you think that Working Storage also disappears when the task ends?
When a task ends, Working Storage disappears so that the space can be used for another task.
Each time a program starts, it gets a fresh copy of working storage. (Module 4 discusses saving working storage data between tasks.)


MODULE 2

BMS Features
- Attention Identifier Keys
- Cursor Position
- Attribute Override

You will want to use some special keys found on 3270-type terminals..

ATTENTION IDENTIFIER (AID) KEYS

The Attention Identifier Keys are:













.
.
.



The location of these keys on the keyboard varies depending on the model of CICS terminal you have.
The key is usually on the left side of a 3270-type keyboard.
The rest of the Attention Identifier Keys are usually on the right side, or along the top row of the keyboard.
When an Attention Identifier key is pressed, the program specified in the previous TRANSID is started.
The program can then do different functions depending on which key is pressed.


PERS FIRST CLASS SYSTEMS 10/6/85


EMPLOYEE NO <>

FIRST NAME <>

LAST NAME <>

SALARY < $30000 >



ENTER> - INQUIRE - REWRITE - ADD - DELETE

- QUIT


For this CICS/VS program, and are all Attention identifier Keys that initiate the program, and tell it to perform a certain task.

In order to write a program which uses Attention Identification Keys, you need to do two things to the program.

1. Copy DFHAID into your working storage section.

2. Place conditional statements in your program to tell what action is to be taken when an Attention Identification Key is pressed.

The first step is to copy DFHAID into the WORKING-STORAGE SECTION of your program. For example:

DATA DIVISION.
WORKING STORAGE SECTION.
01 EMPLOYEE-RECORD.
05 EMP-ID-NUMBER PIC X(05).
05 EMP-NAME PIC X(30).
05 EMP-DEPARTMENT PIC X(30).
05 SALARY PIC S9(05)V9(2).
05 FILLER PIC X(08).
COPY DFHAID.
COPY PERSM20.
PROCEDURE DIVISION.

Here is the WORKING- STORAGE code that would be copied in when you COPY DFHAID.

01 DFHAID .
02 DFHNULL PIC X VALUE IS ' '.
02 DFHENTER PIC X VALUE IS QUOTE.
02 DFHCLEAR PIC X VALUE IS '!'.
02 DFHPEN PIC X VALUE IS '@'.
02 DFHOPID PIC X VALUE IS '#'.
02 DFHPA1 PIC X VALUE IS '$'.
02 DFHPA2 PIC X VALUE IS '%'.
02 DFHPA3 PIC X VALUE IS '^'.
02 DFHPF1 PIC X VALUE IS '&'.
02 DFHPF2 PIC X VALUE IS '*'.
02 DFHPF3 PIC X VALUE IS ''.
02 DFHPF4 PIC X VALUE IS ''.
02 DFHPF5 PIC X VALUE IS '.
02 DFHPF6 PIC X VALUE IS '?'.
02 DFHPF7 PIC X VALUE IS '
'.
02 DFHPF8 PIC X VALUE IS '¤'.
02 DFHPF9 PIC X VALUE IS '§'.
02 DFHPF10 PIC X VALUE IS 'Û'.
02 DFHPF11 PIC X VALUE IS '='.
02 DFHPF12 PIC X VALUE IS ' '.

Every Attention Identifier Key is assigned a variable name.

e.g. DFHENTER
DFHCLEAR
DFHPA1
DFHPF12

The second step is placing conditional statements in your program to tell what action is to be taken when an Attention Identifier Key is pressed.

PROCEDURE DIVISION
:
EXEC CICS RECEIVE
MAPSET ('PERSM20')
MAP ('PERSM21')
INTO (PERSMAPI)
END-EXEC.
:

IF EIBAID = DFHCLEAR
PERFORM 100-TERMINATE-PROGRAM.

IF EIBAID = DFHPA1
PERFORM 200-DISPLAY-HELP.

MOVE DEPTI TO EMP-DEPARTMENT.
MOVE NAMEI TO EMP-NAME.

If the key is pressed, the program will end in the 100-TERMINATE- PROGRAM paragraph.

If the key is pressed the program will go to the 200-DISPLAY-HELP paragraph.

The code for the Attention Identifier key that was pressed is stored in the variable EIBAID.

The DFHAID defines all the codes and gives them names like DFHCLEAR, so you don't have to write the hex codes yourself. For example:

IF EIBAID = '%'
That means hex code.

EIBAID is a field in the Exec Interface Block. The fields in the EIB that we already know are:

EIBTRNID - Contains the TRANSID.
EIBCALEN - Contains the length of the communications area passed from the previous application program.
EIBRCODE - Contains the return code after an error condition occurs.
EIBAID - Contains the Attention Identifier code associated with the last BMS input.





INVENTORY MANAGEMENT SYSTEM

DISPLAY CURRENT STATUS

DISPLAY MONTHLY INVENTORY

DISPLAY ACCT PAYABLES

QUIT


This is an example of a program where all the sub-programs are chosen using the Attention Identifier
keys.

PROCEDURE DIVISION.
:
EXEC CICS RECEIVE
MAPSET ('INVTM30')
MAP ('INVTM31')
INTO (INVTM31I)
END-EXEC.
:
IF EIBAID=DFHPF1
PERFORM DISPLAY-CURRENT-STATUS
IF EIBAID=DFHPF2
PERFORM DISPLAY-MONTHLY-INVENTORY
IF EIBAID=DFHPF3
PERFORM DISPLAY-ACCT-PAYABLES.
IF EIBAID=DFHCLEAR
PERFORM QUIT.

Another special feature of BMS is the Attribute Override Function .


F I R S T C L A S S S Y S T E M


I - Inquire

U - Update

A - Add

D - Delete

Q - Quit


Enter your choice ==>



The CHOICE input field is defined in the BMS macros to have the attributes IC, NORM, UNPROT, and FSET.
The operator can only type one of five different letters: (I,U,A,D,Q)
If the operator makes a mistake, we could bring the error to the operator's attention by changing the
attribute to bright.
This is called attribute override.

Indicate whether each question about symbolic maps is either (T)rue or (F)alse.

T - BMS macros are compiled 2 times: Once for a physical map, and once for a symbolic map.

T - A symbolic map contains only named fields.

T - The symbolic map is copied into the working storage section of your program.

Let's look at a named data field used for input in a BMS map.

DFHMDF POS=(19,25),LENGTH=25,ATTRB=(ASKIP,NORM),
INITIAL='PLEASE ENTER YOUR CHOICE:'

CHOICE DFHDMF POS=(19,52),LENGTH=01,ATTRB=(IC,UNPROT,NORM,FSET)

DFHMDF POS=(19,54),LENGTH=01,ATTRB=(ASKIP,NORM)

CHOICE is a named data field with a length of 1 and this field designed for INPUT.

01 MENUB1I.
05 FILLER PIC X(12).
05 CHOICEL PIC S9(01) COMP.
05 CHOICEF PIC X(01).
05 FILLER REDEFINES CHOICEF.
10 CHOICEA PIC X(01).
05 CHOICEI PIC X(01).
01 MENUB1O.
05 FILLER PIC X(12).
05 FILLER PIC X(03).
05 CHOICEO PIC X(01).

This is what the symbolic map looks like if CHOICE is the only named variable defined in the BMS macros.

CHOICEL - contains input length.
CHOICEF - indicates whether the key was used.
CHOICEA - contains the attributes of the field to be displayed.
CHOICEI - contains input from terminal.
CHOICEO - contains data to be output.

Let's now see how we can override the attributes of a display field.
(e.g. - Change the content of CHOICEA)

EXEC CICS RECEIVE
MAPSET ('MENUM31')
MAP ('MENUM30')
INTO ('MENUM31I')
END-EXEC.

IF CHOICEI = 'I' OR 'U' OR 'A' OR 'D' OR 'Q'
NEXT SENTENCE
ELSE
MOVE ATTR-UNPROT-BRT TO CHOICEA.

EXEC CICS SEND
MAPSET ('MENUM31')
MAP ('MENUM30')
DATAONLY
END-EXEC.

EXEC CICS RETURN
TRANSID ('MENU')

After receiving input from the terminal, we check to see if the input was one of the proper choices.
If it is not a proper choice, CHOICEA is changed to be BRT.
After changing the attributes of CHOICE, a SEND command turns the CHOICE field on the screen to BRIGHT.

The systems programmers should have a list of all the useful combinations of attributes and hex codes for each combination in a COPYLIB, which you can copy into working storage.

Here is an example list of useful combinations of attributes, put together by a systems programmer.

01 ATTRIBUTE-COMBINATIONS.
05 ATTR-UNPROT PIC X VALUE ' '.
05 ATTR-UNPROT-FSET PIC X VALUE ' '.
05 ATTR-UNPROT-PEN-FSET PIC X VALUE ' '.
05 ATTR-UNPROT-BRT-PEN PIC X VALUE ' '.
05 ATTR-UNPROT-BRT-PEN-FSET PIC X VALUE ' '.
05 ATTR-UNPROT-DRK PIC X VALUE ' '.
05 ATTR-UNPROT-DRK-FSET PIC X VALUE '('.
05 ATTR-UNPROT-NUM PIC X VALUE ' '.
05 ATTR-UNPROT-NUM-FSET PIC X VALUE ' '.
05 ATTR-UNPROT-NUM-PEN PIC X VALUE ' '.
05 ATTR-UNPROT-NUM-PEN-FSET PIC X VALUE ' '.
05 ATTR-UNPROT-NUM-BRT-PEN PIC X VALUE ' '.
05 ATTR-UNPROT-NUM-BRT-PEN-FSET PIC X VALUE ' '.
05 ATTR-UNPROT-NUM-DRK PIC X VALUE '*'.
05 ATTR-UNPROT-NUM-DRK-FSET PIC X VALUE ')'.
05 ATTR-PROT PIC X VALUE '-'.
05 ATTR-PROT-FSET PIC X VALUE '/'.
05 ATTR-PROT-PEN-FSET PIC X VALUE ' '.
05 ATTR-PROT-BRT-PEN PIC X VALUE ' '.


- The PIC values on the right contain HEX codes to match each combination of attributes.

Some possible uses of attribute override are:

Changing a key field (like employee number) to ASKIP after it has been entered.

- Changing input to PROT,ASKIP for a terminal that is not allowed to do updating.
- Changing error fields to BRT,UNPROT to draw attention to the error.

This is another example of an application that could use attribute override.



PERSONNEL INQUIRY

EMPLOYEE NUMBER < >


FIRST NAME < >

LAST NAME < >

DATE OF BIRTH < / / > SEX < >
D M Y M/F


If errors are typed into the employee number, date of birth or sex fields, we want the error to turn BRIGHT on the screen.

Now you fill in the code to respond to operator errors.

IF EMPNOI < 10000
MOVE ATTR-UNPROT-BRT TO EMPNOA.

IF DAYI > 31
MOVE ATTR-UNPROT-BRT TO DAYA.

IF MONTHI > 12
MOVE ATTR-UNPROT-BRT TO MONTHA.

IF SEXI = 'M' OR 'F' NEXT SENTENCE
MOVE ATTR-UNPROT-BRT TO SEXA.

Often programmers do not highlight every error, they just highlight the first error on the screen.

This can be accomplished by placing an ELSE statement between each condition.

IF EMPNOI < 10000
MOVE ATTR-UNPROT-BRT TO EMPNOA
ELSE
IF DAYI > 31
MOVE ATTR-UNPROT-BRT TO DAYA
ELSE
IF MONTHI > 12
MOVE ATTR-UNPROT-BRT TO MONTHA
ELSE
IF SEXI = 'M' OR 'F' NEXT SENTENCE
MOVE ATTR-UNPROT-BRT TO SEXA.

If an operator makes an error when typing an input field, the field should be changed to BRIGHT.

Also, it would be helpful if the cursor automatically moved to the field in error.

We know how to change the field in error to bright, but how do we move the cursor to the field in error?

This will be explained in the following screens.

Remember how the named fields of a BMS map are defined in WORKING-STORAGE?

Enter the correct letter at the end of the field name on the left to match the description on the right.

CHOICEI ... contains input from the terminal.
CHOICEA ... contains the attributes of the field to be displayed.
CHOICEL ... contains the length of the input.
CHOICEO ... contains data to be output in this field.
CHOICEF ... indicates if the
CHOICEL reports the length of the input when receiving, but it also has a special cursor positioning function when SENDING a map.

You can override the normal cursor positioning on a BMS map by moving a -1 into the field length variable.

EXAMPLE:

MOVE -1 TO CHOICEL.

To use this for the field in error, we move -1 to the length field within an IF ... THEN statement:

EXAMPLE:

IF CHOICE = 'I' OR 'U' OR 'A' OR 'Q'
NEXT SENTENCE
ELSE
MOVE -1 TO CHOICEL.

You can code both an attribute override and cursor positioning.
This is coding for attribute override, changing error fields to BRT.

IF EMPNOI > 10000
MOVE ATTR-UNPROT-BRT TO EMPNOA
ELSE IF DAYI > 31
MOVE ATTR-UNPROT-BRT TO DAYA
ELSE IF MONTHI > 12
MOVE ATTR-UNPROT-BRT TO MONTHA
ELSE IF SEXI NOT = 'M' OR 'F'
MOVE ATTR-UNPROT-BRT TO SEXA

Let's add the code to move the cursor into the error field.

IF EMPNOI > 10000
MOVE ATTR-UNPROT-BRT TO EMPNOA
MOVE -1 TO EMPNOL
ELSE IF DAYI > 31
MOVE ATTR-UNPROT-BRT TO DAYA
MOVE -1 TO DAYL
ELSE IF MONTHI > 12
MOVE ATTR-UNPROT-BRT TO MONTHA
MOVE -1 TO MONTHL
ELSE IF SEXI NOT = 'M' OR 'F'
MOVE ATTR-UNPROT-BRT TO SEXA
MOVE -1 TO SEXL

Often a message is moved to a message field to explain the error to the operator.

IF EMPNOI > 10000
MOVE ATTR-UNPROT-BRT TO EMPNOA
_MOVE -1 TO EMPNOL
MOVE 'EMPLOYEE NUMBERS ARE BETWEEN 10000 AND99999' TO MESSAGEO
ELSE IF DAYI > 31
MOVE ATTR-UNPROT-BRT TO DAYA
MOVE 'THERE CAN BE ONLY 31 DAYS IN A MONTH' TO MESSAGEO
ELSE IF MONTHI > 12
MOVE ATTR-UNPROT-BRT TO MONTHA
MOVE 'THERE ARE ONLY TWELVE MONTHS IN A YEAR' TO MESSAGEO
ELSE IF SEXI NOT = 'M' OR 'F'
MOVE ATTR-UNPROT-BRT TO SEXA
MOVE 'PLEASE ENTER M OR F TO SEX' TO MESSAGEO

Now you know most of the things you would ever want to do with BMS maps.

When using maps a system error can occur and cause your program to ABEND.

This type of error is called a MAPFAIL condition.

A MAPFAIL condition occurs if an operator presses the key without having typed any input.

There are 2 ways to deal with a MAPFAIL condition...

Method 1:

In the DFHMDF macro, specify ATTR=FSET.
This ensures that the field is read, whether anything was typed or not.

Example:

CHOICE DFHMDF POS(20,15),LENGTH=0, ...*
ATTR=(IC,UNPROT,NORM,FSET)

Method 2:

In your program, use the IGNORE CONDITION command to avoid ABENDing the program, and carry on.

Example:

EXEC CICS IGNORE CONDITION
MAPFAIL
END-EXEC.

Indicate whether each of these questions is either (T)rue or (F)alse.

F - MAPFAIL error occurs when a blank screen is sent to the terminal.
F - One way to avoid a MAPFAIL error is to specify CTRL=FREEKB in the DFHMSD macro.
T - Another way to deal with the MAPFAIL condition is to ignore it using an IGNORE CONDITION command.

To use Attention Identifier keys, DFHAID should be copied into your program in which area?
WORKING-STORAGE SECTION.

Fill in the blanks to code for the 2 Attention Identifier keys.

PROCEDURE DIVISION.
.
.
EXEC CICS RECEIVE
MAPSET ('BMOLM20')
MAP ('BMOLM21')
INTO (BMOLM21I)
END-EXEC.
.
IF EIBAID = DFHPA1
PERFORM 100-HELP.
IF EIBAID = DFHCLEAR
PERFORM 200-QUIT.

EXEC CICS SEND

EXEC CICS IGNORE CONDITION
MAPFAIL
END-EXEC.

Fill in the code to highlight the first error, move the cursor to the error position and print an error message.

IF INVNOI <> 9999
MOVE ATTR-UNPROT-BRT TO INVNOA
MOVE -1 TO INVNOL
MOVE 'ENTER A NO. BETWEEN 1000 AND * 9999' TO MESSAGEO
ELSE IF AMOUNTI > 10000
MOVE ATTR-UNPROT-BRT TO AMOUNTA
MOVE -1 TO AMOUNTL
MOVE 'MUST NOT BE MORE THAN $10,00 * 0.00' TO MESSAGEO
ELSE IF
.
.
.

CICS/XA LEVEL II MODULE 3

BMS PAGE FUNCTIONS

- Multiple maps
- ACCUM
- Overflow Processing
- PAGING
- CSPG ¦

Let's begin with a review of macros to define a mapset holding a single map.

INV DFHMSD TYPE=...............
M1 DFHMDI SIZE=...............
DFHMDF POS=...............
DFHMDF POS=...............

MAPSET called 'INV'
MSD - Map Set Definition
MAP called 'M1'
MDI - Map Definition (Initial)
Map Field
MDF - Map Definition (Field)

You can also define more than one map within a single mapset.

INV DFHMSD TYPE=...............

M1 DFHMDI SIZE=...............

DFHMDF POS=...............

DFHMDF POS=...............

M2 DFHMDI SIZE=...............

DFHMDF POS=...............

Some installations may use a mapset to hold all maps for one application; others may use a mapset to hold the maps for a single screen display.

Screens can be made of multiple maps.

__________________________________________________
A map can be placed at the top of the screen.

The middle section is a map or a collection of maps to display details.

A map is positioned at the bottom of the screen.

When you are using multiple maps on a screen, you are responsible for their positioning.

The positioning is defined in the parameters of the map definition (DFHMDI) macro.

M1 DFHMDI SIZE=(5,80),LINE=1,COLUMN=1

First, you specify the SIZE of the map in lines and columns. Then you can specify where each
map is positioned by using the LINE and COLUMN parameters.

Finally, you can specify whether the column position should be counted from the left or right of the screen.

For example...

MAPA DFHMDI SIZE=(3,19),LINE=2,COLUMN=3,JUSTIFY=LEFT

MAPA DFHMDI SIZE=(3,10),LINE=2,COLUMN=3,JUSTIFY=RIGHT

If JUSTIFY=LEFT, the upper left corner of the map will be placed on LINE and COLUMN coordinates which are counted from the LEFT.

If JUSTIFY=RIGHT, the upper right corner of the map will be placed on LINE and COLUMN coordinates which are counted from the RIGHT.

So far, you've looked at map positions which are hard-coded in the definitions.

However, maps can also be displayed on a screen in positions relative to each other.

Look at the maps on the screen, then try to add a name to each map definition.

M1 M2

M3

M4

Altogether, the map definitions for this screen might look like this:

MAPSET1 DFHMDS ...
* -----------------------

M1 DFHMDI SIZE=(2,4), JUSTIFY=FIRST

M2 DFHMDI SIZE=(2,19), LINE=SAME

M3 DFHMDI SIZE=(3,14), COLUMN=3, LINE=NEXT

M4 DFHMDI SIZE=(3,8), COLUMN=SAME, JUSTIFY=LAST

For positioning maps, the JUSTIFY parameter can replace the LINE parameter, the COLUMN parameter.....or both.

Now that you've coded all the map definitions, how do you actually get them on the screen?

Each map is sent to the terminal screen with its own SEND command.

EXEC CICS SEND
MAPSET('TCOB10')
MAP('HMAP1')
FROM(HMAP1O)
ERASE
END-EXEC.

EXEC CICS SEND
MAPSET('TCOBM10')
MAP('DMAP2')
FROM(DMAP2O)
END-EXEC.
+---------------
EXEC CICS SEND
MAPSET('TCOBM10')
MAP('DMAP3')

Notice that the first map is sent with ERASE to clear the screen.

MSET DFHMDS ....
M1 DFHMDI SIZE=(2,4),LINE=1,COLUMN=1
M2 DFHMDI SIZE=(2,19),LINE=1,COLUMN=8
M3 DFHMDI SIZE=(3,14),LINE=5,COLUMN=3

Using the above macros, fill in the blanks to send the first 3 maps to the terminal (in order).

EXEC CICS SEND
MAPSET('MSET')
MAP('M1')
ERASE
:
END-EXEC.

EXEC CICS SEND
MAPSET('MSET')
MAP('M2')
:
END-EXEC.

EXEC CICS SEND
MAPSET('MSET')
MAP('M3')
:
END-EXEC.

When you send the maps in this way, a user sees the screen built map by map.

For more efficient processing, the maps can be collected and built into one page, and then sent as a unit to the terminal.

The ACCUM operand is used to accumulate maps in the page buffer. (This is called page building or building a logical message.)

EXEC CICS SEND
MAPSET('MSET1')
MAP('M1')
ACCUM
:
END-EXEC.

EXEC CICS SEND
MAPSET('MSET1')
MAP('M2')
ACCUM
:
END-EXEC.

EXEC CICS SEND
MAPSET('MSET1')
MAP('M3')
ACCUM
END-EXEC.

EXEC CICS SEND
PAGE
END-EXEC.

The SEND PAGE command can then be used to send the entire page to the terminal screen.

ACCUM - Collects maps in the page buffer.
SEND PAGE - Can send a page to the terminal.
ERASE - Can erase previous maps from a screen.

Overflow Processing

Again, one screen display is designed using three different maps ...


Product Num: 1111
Product Name: Widgits

Parts

0031 Handles Acme 1984
0032 Forks Acme 1983
1068 Dome Acme 1988

Instructions to continue ...


0031 Handles Acme 1995
0032 Forks Rork 1993
1068 Dome Acme 1996
1122 Wings Fome 1996
1234 Clutch Ster 1988
1256 Pump Gree 1990
1279 Pedals Acme 1990
1456 Bulbs NRG 1993
1784 Trays Rork 1993
1790 Plugs NRG 1995
2122 Bolts Whit 1990

... and the whole list of data available for map M2 won't fit on one screen.

In this case, you must build "pages" of detail information.

How would you do this?

First of all, you need to code the map definition somewhat differently.

M1 DFHMDI SIZE=(5,80),JUSTIFY=FIRST,HEADER=YES
M2 DFHMDI SIZE=(3,80) LINE=NEXT
M3 DFHMDI SIZE=(2,80),JUSTIFY=LAST,TRAILER=YES

Notice that JUSTIFY will still control position of the 3 maps.HEADER and TRAILER are used for handling overflow.

REMEMBER TWO IMPORTANT POINTS:

When a map is sent with HEADER=YES as an operand, previous pages are erased.
A page always "reserves" enough space to hold the largest TRAILER=YES map.

LET'S EXAMINE HOW IT WORKS -

--- PROGRAM ----
Send header map
Read record 1
Send detail map

--- Page Buffer -----
Dept : _____
Dept #: _____

PARTS
~~~~~


-----------------------

The current screen can hold a page of 10 lines.
The program sends M1, a header map of 5 lines, to the page buffer.
Because TRAILER=YES on M3, the page buffer "reserves" space (2 lines) for it.

How many lines are left for the detail map M2? 3 lines

Detail maps are sent one by one and accumulated in the page buffer.
When the 4th record is read an overflow condition occurs.

---- Page Buffer -----
Dept: _____
Dept #: _____

PARTS
~~~~~
record 1
record 2
record 3
-------------------------

An EXEC CICS HANDLE CONDITION OVERFLOW must be added to the code. This allows the program to detect overflow conditions and to execute an overflow handling routine.

The overflow routine should:
- send the trailer map to finish the page.
- send the header map to
1) put the old page on the terminal screen
2) clear the page buffer and start a new page
- send the detail map (Remember that record 4 was read but there was no room to send it to the old page.)

--- PROGRAM ----
Handle overflow
Send header map
Read one record
Send detail map
Overflow routine
Send trailer
Send header
Send detail
------------------------

Control should then be passed back to reading records and accumulating maps in the buffer.
This continues until all the data has been sent.

Which piece of code could be used to detect an overflow condition?

EXEC CICS
HANDLE CONDITION OVERFLOW(OVRFLO)
END EXEC.

Which piece of code could start a new page in the page buffer?

EXEC CICS SEND
MAPSET ('PRODUCTS')
MAP ('M1')
ACCUM ...

Which piece of code sends a page to the terminal screen?

EXEC CICS
SEND PAGE
END EXEC.

In the previous example, each page is sent to the terminal when it is completely built.
It is sometimes more convenient to have all the pages built and kept in storage for later use.
You can do this by adding the PAGING operand to SEND MAP code.

EXEC CICS SEND
MAPSET('MSET1')
MAP('M1')
ACCUM
PAGING
END-EXEC.
:
EXEC CICS SEND
MAPSET('MSET1')
MAP('M2')
:
ACCUM
PAGING
END-EXEC.
:
As each new header map is sent to the page buffer, the PAGING operand sends the old page
to temporary storage - not to the terminal.



---- Page Buffer -----
Dept: _____
Dept #: _____
-------------------------
PARTS
-------------------------
record 5
record 6

-------------------------
Instructions to
-------------------------

----TEMPORARY STORAGE ----
Page 1
Page 2
Page 3
-------------------------------------------

Two final questions need to be answered before we leave this module.

How do you code an overflow routine to send pages to temporary storage instead of to the terminal screen?

---Overflow routine----
Send trailer
Send header
Send detail
-----------------------------
Actually, the only difference is a PAGING operand when sending maps.

How can you browse, delete, and manipulate pages which have been sent to temporary storage?

IBM supplies the CSPG transaction to browse, delete and manipulate pages. (Of course, you could write your own code.)
CSPG is automatically initiated at the end of transactions which put pages into temporary storage.

Mark the following statements (T)rue or (F)alse

F - CSPG is an IBM supplied transaction for handling overflow conditions.
F - The page buffer will reserve enough space for the largest detail map.
T - When a header map is sent to the page buffer, the page buffer is cleared.


CICS/XA LEVEL II MODULE 4

Temporary Storage Transient Data

When a CICS/VS program is terminated, all data in working storage is lost... unless a programmer stores it for later.
You are probably already familiar with one way of storing data for later use -
EXEC CICS RETURN
TRANSID( )
COMMAREA(data-area)
LENGTH(data-value)
END-EXEC.

What operand would you have to include in the above command to specify the data AREA you wish to pass?
The COMMAREA operand specifies a data area to pass to the next program. It is also included in the LINK and XCTL commands.

RETURN TRANSID actually saves ONE record in temporary storage.

If you have more than a single record to save, you can use TEMPORARY STORAGE directly.

You can think of temporary storage as a scratch pad. Just as you write notes on a scratch pad for later use you write data out to temporary storage for later use.

Temporary storage records are written into queues. A queue will hold as many records as you want.
You can also use as many queues as you need. Temporary storage can pass data across tasks. Data from one program can be put in temporary storage for later use. For example...

A map in working storage is presented to a user during the execution of a task.
The map is then written to temporary storage and the current task and working storage are terminated.
When the user enters input, a new task and new working storage are created.
The program can check for modifications by comparing the data saved in temporay storage to the current data content of the map.
WRITE

Here's an example of a WRITEQ TS command.

WORKING-STORAGE SECTION.
01 EMPLOYEE-RECORD.
05 EMP-ID-NUM PIC X(5).
05 EMP-NAME PIC X(30).
05 EMP-DEPT PIC X(15).
01 TS-ITEM PIC S9(2) COMP.
01 TS-QUEUE.
05 TS-TERMID PIC X(4).
05 TS-TRANSID PIC X(4).
.
EXEC CICS WRITEQ TS

QUEUE (TS-QUEUE)

FROM (EMPLOYEE-RECORD)

LENGTH (50)

ITEM (TS-ITEM)

END-EXEC.

QUEUE......names the TS queue where data is to be sent.
FROM.......specifies where the TS data comes FROM.
LENGTH.....specifies the length of the saved data.
ITEM.......is set to the record number within the Queue.
(You can rewrite a particular record.)

With CICS/VS it is possible for two users at different terminals to use the same program at the same time. This could cause problems if the queue name is hard-coded (in quotes) in the program. If the queue name is hard coded, the data from both users will be sent to the same temporary storage queue. To get around this problem, we need a way to give each user a queue and give each queue a unique name. A common naming convention uses a combination of transaction id and terminal id.

WORKING-STORAGE SECTION.
01 EMPLOYEE-RECORD.
05 EMP-ID-NUM PIC X(05).
05 EMP-NAME PIC X(30).
05 EMP-DEPT PIC X(15).
01 TS-QUEUE.
05 TS-TERMID PIC X(04).
05 TS-TRANID PIC X(04).
.
.
PROCEDURE DIVISION.
MOVE EIBTRMID TO TS-TERMID.
MOVE EIBTRNID TO TS-TRANID.
.
.
EXEC CICS WRITEQ TS
QUEUE (TS-QUEUE)
FROM (EMPLOYEE-RECORD)
LENGTH (50)
END-EXEC.

In this example TS-QUEUE is the variable which will contain the queue name.

TS-QUEUE is declared in the WORKING-STORAGE SECTION. The first 4 bytes contain the TERMINAL ID; the last 4 hold a TRANSACTION ID.
The Exec Interface Block (EIB) has the ID of the current transaction and the ID of the terminal used.
In the PROCEDURE DIVISION, the information that we need is moved from the EIB into the appropriate field.

Each terminal has its own ID, so when we concatenate it with transaction ID, we have a pretty safe method of assigning unique names to temporary storage queues.

Temporary storage can be written to either main memory or auxiliary storage (disk).

Which do you think is used the most?
Auxiliary storage is usually used so main storage is not tied up. However, main storage can be used to save small amounts of data (less than 200 bytes) which you need to access quickly.

REWRITE

REWRITE is another operand that you can use when you have modified a record already in temporary storage. It updates the changed record in the temporary storage queue. The ITEM parameter specifies which record is to be rewritten.

EXEC CICS WRITEQ TS
QUEUE (TS-QUEUE)
FROM (EMPLOYEE-RECORD)
LENGTH (50)
ITEM (TS-ITEM)
REWRITE
END-EXEC.

In the WRITEQ TS statement, you can specify which kind of storage you want with a MAIN/AUXILIARY operand. AUXILIARY is the default.

So, for a quick review, let's assume that you've defined the WORKING-STORAGE SECTION of your program as follows:

WORKING-STORAGE SECTION.
01 EMPLOYEE-RECORD.
05 EMP-ID-NUM PIC X(05).
05 EMP-NAME PIC X(30).
05 EMP-DEPT PIC X(15).
01 TS-QUEUE.
05 TS-TERMID PIC X(04).
05 TS-TRANID PIC X(04).

Fill in the blanks to complete a command which will write the EMPLOYEE-RECORD to a temporary storage queue.

EXEC CICS WRITEQ TS
QUEUE (TS-QUEUE)
FROM (EMPLOYEE-RECORD)
LENGTH (50)
END-EXEC.

What operand would you include in the WRITEQ TS command when You have modified a record and now you want to update that record in the TS queue.
You need the REWRITE operand.

READQ

The READQ TS command is used to read a record from a queue in temporary storage. The format is as follows.

WORKING-STORAGE SECTION.
01 EMPLOYEE-RECORD.
05 EMP-ID-NUM PIC X(5).
05 EMP-NAME PIC X(30).
05 EMP-DEPT PIC X(15).
01 TS-QUEUE.
05 TS-TERMID PIC X(4).
05 TS-TRANSID PIC X(4).
.
.
EXEC CICS READQ TS
QUEUE (TS-QUEUE)
INTO (EMPLOYEE-RECORD)
LENGTH (TS-LENGTH)
ITEM (1)
END-EXEC.

Read record 1 from PAYROLL1. It is 50 bytes in length. Put it into EMPLOYEE.

MOVE 50 INTO REC-LEN.
:
EXEC CICS READQ TS
QUEUE ('PAYROLL1')
INTO (EMPLOYEE)
LENGTH (REC-LEN)
ITEM (1)
END-EXEC.

Notice that the value for the LENGTH operand is a variable. For READQ TS, LENGTH must be coded as a variable or CICS will return an error code. If the record is shorter than the specified length, CICS adjusts the variable accordingly. If the record is longer than the specified length, CICS will truncate the record read. When you WRITE to a queue, the LENGTH value can be a constant.

DELETEQ

When a temporary storage queue is no longer needed it should be deleted. Here is the command which
allows you to do this.


EXEC CICS DELETEQ TS
QUEUE (TS-QUEUE)
END-EXEC.

The only thing you need to specify is the name of the queue you wish to delete. You can only delete whole queues. It is important to note that there is no command that allows you to delete individual records within a queue.

Why do you think deleting temporary storage queues which are no longer needed is so important?
You must delete unused temporary storage queues because CICS/VS will not do it for you.
If you do NOT delete unused queues, all storage areas would be full of queues before too long.
Deleting them will free temporary storage areas for others to use.

You should now be familiar with RETURN TRANSID and TEMPORARY STORAGE for saving
data. There is a third way:

Transient data is like temporary storage in a number of ways.
First of all, temporary storage and transient data both have information stored in queues.
Secondly, temporary storage data and transient data can both be passed across tasks.
An application program could write data out to a transient data queue.
A print program could read the data from the queue and send it to the printer.

Difference between TD and TS


TEMPORARY STORAGE TRANSIENT DATA

Data is read randomly. Data must be read sequentially.
A data item can be read many times A data item can be read once.
and it remains in the queue until To reuse a record, the TD file
the entire queue is purged. must be closed and reopened.
Data can be changed. Data cannot be changed.
Temporary storage can be written Transient data items are always
to auxiliary or main storage. written to disk.
Temporary storage is a "holding Transient Data is ALWAYS
place" or "storage place" for data. associated with a destination.


Indicate whether each statement below is about TS (Temporary Storage) or TD (Transient Data):

Each record in the queue is usually read once - TD
A TD record can't be read again unless the file is reopened.

You cannot remove a record from a temporary storage queue.

Each record in the queue can be randomly accessed - TS

Transient data can ONLY be read sequentially.

The queue can be updated when a record is modified. - TS

Transient data CANNOT be changed.

Small amounts of data can be written to main storage - TS

Transient data CANNOT be written to main storage.

A queue name is always associated with a destination - TD

Let's take a look at how it works.

To use temporary storage, the programmer dynamically defines the queue name in the program.
Data is moved from a data area to a temporary storage queue.
A program reads records from the queue as they are needed.

EXEC CICS WRITEQ TS
:
END-EXEC.

EXEC CICS READQ TS
QUEUE('ABCDTCOB')
INTO(EMPLOYEE)
:
END-EXEC.

To use transient data, the programmer MUST use a queue name defined in the DCT.
The data is moved from a data area to a transient data queue.
CICS then looks up the queue name in the DCT to find the instructions associated with that particular queue name.

EXEC CICS WRITEQ TD
QUEUE(SYS1)
FROM(EMPLOYEE)

END-EXEC.

Start transaction PRNT to print a formatted report with the data.

Note ...
An application usually uses TEMPORARY STORAGE to pass information from task to task.
An application usually uses TRANSIENT DATA to accumulate records before processing or to send data out for processing external to CICS. ¦

There are four types of destinations (or instructions) which can be defined for transient data in the DCT...

Indirect destination
Remote destination
Extrapartition destination
Intrapartition destination

Let's look at the two most commonly used destinations.

EXTRAPARTITION

EXTRAPARTITION destinations are used for input / output outside of the CICS region.
For example:
In one CICS transaction, a new record is entered and the local data base is updated.
The transaction then stores the new record in a transient data queue.
In turn, the transient data is written to the associated external dataset.
At the end of the day, the external dataset is transmitted to head-office and used to update a regional data base.

The DCT links the transient data queue and the external dataset information in the DCT is the only way of getting at and using files which are external to CICS.

INTRAPARTITION

It is logical to think that an INTRAPARTITION destination is used for input and output within the CICS system. This is partly true - but it is only part of the whole picture.
INTRAPARTITION transient data is used for intermediate storage. An amount of data is collected in the data set before processing.

Before closing let us look at Transient data queue commands:

EXEC CICS WRITEQ TD
QUEUE(P001)
FROM(EMPLOYEE)
LENGTH(REC-LEN)
END-EXEC.

EXEC CICS READQ TD
QUEUE(P001)
INTO(EMPLOYEE)
LENGTH(REC-LEN)
END-EXEC.

EXEC CICS DELETEQ TD
QUEUE(P001)
END-EXEC.

Note that only INTRAPARTITION transient queues can be deleted.

1. Mark the following statements (T)rue or (F)alse:

F - Temporary storage is written in sets called files.
T - Temporary storage can be used to pass information across tasks.
F - Temporary Storage queue names must be defined in the DCT.
T - Temporary storage can be thought of as a scratch pad used to save data that will be used later.
F - Temporary storage is often used to save short programs.
T - You can write as many records in a queue as you want.

2. Fill in the blanks to complete the command which will write EMPLOYEE-RECORD to
temporary storage.

WORKING-STORAGE SECTION.
01 EMPLOYEE-RECORD.
05 EMP-ID-NUM PIC X(05).
05 EMP-NAME PIC X(30).
05 EMP-DEPT PIC X(15).
01 TS-LENGTH S9(4) COMP VALUE +6.
01 TS-QUEUE.
05 TS-TERMID PIC X(04).
05 TS-TRANID PIC X(04).
.
.
PROCEDURE DIVISION.
MOVE EIBTRMID TO TS-TERMID.
MOVE EIBTRNID TO TS-TRANID.
.
.
EXEC CICS WRITEQ TS
QUEUE (TS-QUEUE)
FROM (EMPLOYEE-RECORD)
LENGTH (50)
END-EXEC.

3. In the last question you wrote the EMPLOYEE-RECORD data to temporary storage. Suppose you wish to read this data back into EMPLOYEE-RECORD. Fill in the blanks so the code will do this.

WORKING-STORAGE SECTION.
01 EMPLOYEE-RECORD.
05 EMP-ID-NUM PIC X(05).
05 EMP-NAME PIC X(30).
05 EMP-DEPT PIC X(15).
01 TS-LENGTH S9(4) COMP VALUE +6
01 TS-QUEUE.
05 TS-TERMID PIC X(04).
05 TS-TRANID PIC X(04).
.
PROCEDURE DIVISION.
MOVE EIBTRMID TO TS-TERMID.
MOVE EIBTRNID TO TS-TRANID.
.
MOVE 50 TO TS-LENGTH.
EXEC CICS READQ TS
QUEUE (TS-QUEUE)
INTO (EMPLOYEE-RECORD)
LENGTH (TS-LENGTH)
ITEM (1)
END-EXEC.

4. Assume you no longer need the queue in temporary storage. Complete the code so you can delete the temporary storage queue.

WORKING-STORAGE SECTION.
01 EMPLOYEE-RECORD.
05 EMP-ID-NUM PIC X(05).
05 EMP-NAME PIC X(30).
05 EMP-DEPT PIC X(15).
01 TS-LENGTH S9(4) COMP VALUE +6
01 TS-QUEUE.
05 TS-TERMID PIC X(04).
05 TS-TRANID PIC X(04).
.
.
PROCEDURE DIVISION.
MOVE EIBTRMID TO TS-TERMID.
MOVE EIBTRNID TO TS-TRANID.
.
.
EXEC CICS DELETEQ TS
QUEUE (TS-QUEUE)
END-EXEC.

5. Select the choice which best completes the statement.

When no longer needed, temporary storage queues should be deleted ... because pseudoconversational programs require it.

In order to free storage areas for other users. so no one else can use these queues. because every WRITEQ TS command requires a DELETEQ TS command.

6. Indicate whether each of the following is a use of (I)ntrapartition or (E)xtrapartition Transient Data:

In a queue, a CICS program accumulates any incorrect password entries from a terminal. If the number of incorrect entries exceeds 2, a warning is displayed on the master terminal. - I
The same program then stores a second copy of the incorrect password entries in a different queue. This queue is printed when convenient. - E


CICS/XA LEVEL II MODULE 5

STORAGE CONTROL
- CICS Control Blocks
- Address Lists
- Dynamic Storage Acquisition
- COBOL II / COBOL VS

Occasionally, you will need to query CICS about the system related information that it stores.
For example ...
- the current time
- the ID of the terminal running the progrm
- the length of the COMMAREA are all stored by CICS and can be accessed when required.

Can you guess the name of the storage area where CICS keeps this information?
System information is stored in the EIB (Exec Interface Block).

The EIB (Exec Interface Block) is inserted into your LINKAGE SECTION by the translator.

LINKAGE SECTION.

01 DFHEIBLK.

01 DFHCOMMAREA PIC X.

01 TERMINAL-USER-AREA.


Some of the variables contained in the EIB include ...

EIBTIME - contains the current time
EIBTRMID - contains the terminal ID
EIBCALEN - contains the COMMAREA length
... as well as a number of other pieces of information.

Where does CICS/VS get the information to put into the EIB?

The EIB is actually a selection of information found in various CICS/VS control blocks.

WORKING STORAGE.

LINKAGE SECTION.
01 DFHEIBLK.

PROCEDURE DIVISION.


These control blocks are small areas of main memory that CICS/VS uses to control its own operation.

- Some control blocks stand by themselves
- Some are associated with terminals
- Some are associated with tasks

Let's take a closer look at control blocks and how they are used by CICS.

CSA - COMMON SYSTEM AREA

There is exactly one CSA (Common System Area) in memory at any given time.
It records which task is currently executing, and generally, the state of the system as a whole.

CWA -Common Work Area

The CWA (Common Work Area) is an extension of the CSA. It is an area set aside for use by the individual installation in whatever way they like. Normally it contains security tables, and other global data.

TCTUA (Terminal Control Table User Area)

There is usually a TCTUA (Terminal Control Table User Area) for each terminal connected to CICS/VS. This installation-defined control block contains information such as user ID, the user's security level and any other information the organization wants to keep from one task to the next.

TCA - TASK CONTROL AREA

For every task running in the system, there is one TCA (Task Control Area) which contains information about the execution environment. Some of the information it contains is related to the running program and whether or not a terminal is connected to that program.

TWA - TASK WORK AREA

The TWA (Task Work Area) is an extension of the TCA. It can be used by programs within the task to record data associated with the task. It is sometimes used to pass data between programs within the same task instead of using the COMMAREA. This would be used by system utilities, purchased software packages and various pre-command level COBOL programs (i.e. MACRO level).

Lets see how many of those acronyms you remember.

CSA - Contains information about the program that is running, along with other global system information.
TWA - Used by system utilities for inter-program communication within a task.
CWA - Contains installation-defined, global information.
TCTUA Can be used for organization defined user data such as user ID.
TCA - Records the state of a single TASK.

Now that you know what is kept in the control storage blocks, let's see how the data is accessed ...
Suppose we want to determine if a particular user is allowed to update salary data. You would need to know the user ID and the user's security level.

Which control block is most likely to be used to contain this information?
The TCTUA (Terminal Control Table User Area) contains all installation defined information.

Here's an example of a TCTUA definition coded in Working Storage.

01 TCTUA.
05 TCTUA-DEPARTMENT-CODE PIC X(04).
05 TCTUA-LOCATION PIC X(06).
05 TCTUA-OPERATOR-NAME PIC X(20).
05 TCTUA-SECURITY-LEVEL PIC 9.

The executing program can evaluate the data in these variables to determine if a particular user is allowed to update salary data.
For example:
If the department code is PAYR (PAYROLL), and the security level is 3 or less, then the user is allowed to update salary data.

Now, how do we get this information into our COBOL program? ...

The LINKAGE section is where we define all data areas which are not in our own working storage.

.LINKAGE SECTION..
01 DFHEIBLK.

01 DFHCOMMAREA PIC X.

01 TERMINAL-USER-AREA.
05 TCTUA-DEPARTMENT-CODE PIC X(04).
05 TCTUA-LOCATION PIC X(06).
05 TCTUA-OPERATOR-NAME PIC X(20).
05 TCTUA-SECUTITY-LEVEL PIC 9.

How does COBOL know that the TCTUA data is located in the TERMINAL-USER-AREA variable
definition?

The answer is: it doesn't. So, we have to go through a process known as ESTABLISHING ADDRESSABILITY.

We'll look at the process of ESTABLISHING ADDRESSABILITY in a moment, but first ...

Are the following statements (T)rue or (F)alse?

F - CICS control block variables are defined in the Working Storage section of a COBOL program.
T - CICS control block variables are defined in COBOL programs.
T - Control block information can be accessed by a COBOL program.

ESTABLISHING ADDRESSABILITY

There are 2 steps to establishing addressability:

1. Find out where the block of storage is located in memory (i.e. its address).
2. Tell COBOL which item in the LINKAGE SECTION can be found at this address.

STEP 1 - LOCATE STORAGE BLOCK

CICS knows where the TCTUA for each terminal is located but your program doesn't (at least not yet). The obvious thing to do is to ask CICS where it is!
The command to do this is ...

EXEC CICS ADDRESS
TCTUA (TERMINAL-USER-AREA-ADDR)
END-EXEC.

This command asks CICS to put the TCTUA address into TERMINAL-USER-AREA-ADDR.

STEP2 - IDENTIFY LINKAGE SECTION VARIABLES

Now that we know where the TCTUA is located, we have to add this variable to the LINKAGE SECTION of our COBOL program.

LINKAGE SECTION.
01 DFHEIBLK.

01 DFHCOMMAREA PIC X.
01 ADDRESS-LIST.
05 ADDRESS-LIST-ADDR PIC S9(8) COMP.
05 TERMINAL-USER-AREA-ADDR PIC S9(8) COMP.

01 TERMINAL-USER-AREA.
05 TCTUA-DEPARTMENT-CODE PIC X(05).
05 TCTUA-LOCATION PIC X(06).
05 TCTUA-OPERATOR-NAME PIC X(20).
05 TCTUA-SECURITY-LEVEL PIC 9.

A new item, we'll call ADDRESS-LIST, contains the address of itself and ALL subsequent
01 items in the LINKAGE SECTION.
Notice the order of the LINKAGE SECTION code. The first entry is always DFHEIBLK.
CICS automatically adds this EIB description to your COBOL code. The next item coded is DFHCOMMAREA. The ADDRESS-LIST is always coded in third position, immediately after DFHCOMMAREA. Address list entries must be PIC S9(8)COMP. As soon as you put a value into an ADDRESS-LIST variable, the corresponding 01 item is located.
ADDRESSABILITY is established and the information can be used.

What is always coded as the third LINKAGE SECTION item?
The DFHEIBLK and DFHCOMMAREA are coded in first and second position.¦ The variables pointing at control blocks are always in third position.

What statement initiates the loading of the address?
The EXEC CICS ADDRESS statement determines the control block address.

Into which variable is the address loaded?
The address of the TCTUA control block is placed in the variable TERMINAL-USER-AREA-ADDR.

Which data item is pointed at by TERMINAL-USER-AREA-ADDR?
This variable is pointing at the 01 level TERMINAL-USER-AREA.

Fill in the blanks to define the LINKAGE SECTION so we can access TCTUA.

LINKAGE SECTION.
.
.
01 DFHCOMMAREA PIC X.

01 ADDRESS-LIST.
05 ADDRESS-LIST-ADDR PIC S9(8) COMP.
05 TERMINAL-USER-AREA-ADDR PIC S9(8) COMP
01 TERMINAL-USER-AREA.

Let's put everything together, and see what our installation defined check on salary update looks like ...

CHECK-SECURITY.

EXEC CICS ADDRESS
TCTUA (TERMINAL-USER-AREA-ADDR)
END-EXEC.

After the TCTUA address is loaded by a utility ...

IF TCTUA-DEPARTMENT-CODE = 'PAYR' AND TCTUA-SECURITY-LEVEL NOT > 3
MOVE 'Y' TO SALARY-UPDATE-ALLOWED
ELSE
MOVE 'N' TO SALARY-UPDATE-ALLOWED.

... the information is checked to see if the user's department code and security level are allowed to update salaries.

Next, let's see how multiple control blocks are addressed.

01 ADDRESS-LIST.
05 ADDRESS-LIST-ADDR PIC S9(8) COMP.
05 TERMINAL-USER-AREA-ADDR PIC S9(8) COMP.
05 COMMON-WORK-AREA-ADDR PIC S9(8) COMP.
05 TASK-WORK-AREA-ADDR PIC S9(8) COMP.

01 TERMINAL-USER-AREA.

01 COMMON-WORK-AREA.

01 TASK-WORK-AREA.

PROCEDURE DIVISION.

EXEC CICS ADDRESS
TCTUA (TERMINAL-USER-AREA-ADDR)
CWA (COMMON-WORK-AREA-ADDR)
TWA (TASK-WORK-AREA-ADDR)
END-EXEC.

Recall that the first item coded in the ADDRESS-LIST is the address of that list. All other variables must be coded in the same order as they appear in the LINKAGE SECTION.
Up to four (4) control block addresses can be accessed in one EXEC CICS ADDRESS statement.
A second EXEC CICS ADDRESS statement is required if more than four control block addresses are accessed.

Remember that the EIB is entered into your COBOL program by the translator. The CICS programmer is not concerned with locating the address of the EIB or COMMAREA.
ADDRESSABILITY to these control blocks is automatically provided by the translator.

Here we have the storage blocks defined in the LINKAGE SECTION.

LINKAGE SECTION.

01 DFHCOMMAREA PIC X.

01 ADDRESS-LIST.
05 ADDRESS-LIST-ADDR PIC S9(8) COMP.
05 TERMINAL-USER-AREA-ADDR PIC S9(8) COMP.
05 COMMON-WORK-AREA-ADDR PIC S9(8) COMP.

01 TERMINAL-USER-AREA.
05 TCTUA-DEPARTMENT-CODE PIC X(04).

01 COMMON-WORK-AREA.
05 CWA-GREGORIAN-DATE PIC 9(09).

So far, you've seen how CICS control blocks are defined and accessed.
Let's now take a look at establishing addressability to storage required by your application program.

What if you have a situation where your COBOL program may or may not require access to a large table?
.
WORKING STORAGE.
01 VARIABLES.
.
01 TABLE.
.
PROCEDURE DIVISION.
.
IF SALARY = MIN
.
ELSE
PERFORM LOAD-TABLE.

If the table is declared in Working Storage, space is allocated for the entire time the program is running.
If the table isn't declared, space is not allocated and your program won't be able to access the table.

How do you get the storage only when it is needed so you don't waste space?
The answer is: acquire it dynamically.

LINKAGE SECTION.

01 DFHCOMMAREA PIC X.

01 ADDRESS-LIST.
05 ADDRESS-LIST-ADDR PIC S9(8) COMP.
05 BLOCK-1-ADDR PIC S9(8) COMP.

01 BLOCK-1 PIC X(2500).

PROCEDURE DIVISION.

EXEC CICS GETMAIN
SET (BLOCK-1-ADDR)
LENGTH (2500)
END-EXEC.

CICS allows your program to dynamically acquire additional storage during execution.

GETMAIN

This GETMAIN statement:
- requests additional storage.
- stores the address pointer.
- defines the bytes required.


BLOCK-1-ADDR is defined in the ADDRESS-LIST and points to the storage block in the same way
CICS control blocks are defined.

LINKAGE SECTION.

01 DFHCOMMAREA PIC X.

01 ADDRESS-LIST.
05 ADDRESS-LIST-ADDR PIC S9(8) COMP.
05 BLOCK-1-ADDR PIC S9(8) COMP.

01 BLOCK-1.
05 BLOCK-1-TBL OCCURS 100.
10 VAR-1 PIC X(20).
10 VAR-2 PIC X(10).

PROCEDURE DIVISION.

EXEC CICS GETMAIN
SET (BLOCK-1-ADDR)
LENGTH (3000)
END-EXEC.

COMPUTE BLOCK-2-ADDR =
BLOCK-1-ADDR + 4096.

BLOCK-1 is a table which will dynamically GET storage from MAIN memory when it is required.

How many bytes do you think you should request for this array?
This table requires:
(20 + 10) x 100 = 3000 bytes of storage.

One GETMAIN statement can access a maximum of 64K. However, each address list variable can only address a maximum of 4096 bytes.

If the array occurs 200 times, how many bytes do you now require?
You will need: (20 + 10) x 200 = 6000 bytes of storage.

This means that a second address list variable is needed to address the (6000 - 4096 = 1904) bytes.
BLOCK-2-ADDR is then accessed by coding a COMPUTE statement.
The address of the remaining 1904 bytes is now located.
Code ALL the CICS statements and variables that dynamically acquire storage for the product table.
(Make the first pointer TABLE-1-ADDR and the second TABLE-2-ADDR.)

01 ADDRESS-LIST.
05 ADDRESS-LIST-ADDR PIC S9(8) COMP.
05 TABLE-1-ADDR PIC S9(8) COMP.____
05 TABLE-2-ADDR PIC S9(8) COMP.

01 TABLE-1. -
05 PRODUCT-TBL OCCURS 200.
10 PRODUCT-NO PIC X(10).
10 PRODUCE-NAME PIC X(24).
10 PRODUCT-PRICE PIC S9(4)V99.

PROCEDURE DIVISION.

EXEC CICS GETMAIN
SET (TABLE-1-ADDR)
LENGTH (8000)
END-EXEC.
COMPUTE TABLE-2-ADDR = TABLE-1-ADDR + 4096.

EXEC CICS FREEMAIN (TABLE-1) -
END-EXEC.

When the 8000 bytes are no longer needed, they should be released so that CICS can reuse this storage space. The FREEMAIN statement releases the block of storage acquired in a GETMAIN statement.
Notice that the FREEMAIN statement names the block of storage being released. The pointer to the storage block is not affected.

01 ADDRESS-LIST.
05 ADDRESS-LIST-ADDR PIC S9(8) COMP.
05 TABLE-1-ADDR PIC S9(8) COMP.

05 TABLE-15-ADDR PIC S9(8) COMP.
05 TABLE-16-ADDR PIC S9(8) COMP.

01 TABLE-1.
05 CLIENT-TBL OCCURS 300.
10 CLIENT-NAME PIC X(20).
10 CLIENT-ADDRESS PIC X(30).
10 CLIENT-INFO PIC X(200).

EXEC CICS GETMAIN
SET (TABLE-1-ADDR)
LENGTH (65536)
END-EXEC.

EXEC CICS GETMAIN
SET (TABLE-16-ADDR)
LENGTH (9464)
END-EXEC.

In this example, 75,000 bytes are needed to store CLIENT-TBL. (20 + 30 + 200) x 300 = 75,000)
To obtain 75,000 bytes, the first 64K (65,536 bytes) is accessed with a GETMAIN and fifteen pointers are coded to access the storage block.

The remaining 9,464 bytes are accessed in a second GETMAIN command. Pointers are also set for this block of storage. Once again, COMPUTE statements would be used to determine the address of all variables not accessed with the SET command.

There's just one more thing that needs to be mentioned about establishing addressability...
Whenever you change an entry in the address list, you must tell COBOL what you have done
so that it can update its internal registers.

If you don't, unpredictable results can occur. The SERVICE RELOAD statement tells COBOL that the address list item pointing to the storage block has changed.
Suppose a GETMAIN statement SETs TABLE-ADDR as the address of a block of storage.
A file can then be read and a specified number of records processed at a time.
When processing begins, TABLE-ADDR is pointing to the first record in STORAGE-BLOCK.
During processing, NEXTREC is incremented to reflect the address of the NEXT RECord to be read.
The address contained in NEXTREC can be MOVEd to TABLE-ADDR.
TABLE-ADDR now points to the next record to be read, rather than the beginning of the file.
The SERVICE RELOAD statement updates the internal registers so that COBOL knows which record to READ.
When an EXEC CICS GETMAIN statement is executed, the STORAGE-BLOCK-ADDR pointer is established with the SET command.
If an EXEC CICS FREEMAIN statement releases STORAGE-BLOCK and a second GETMAIN is executed, COBOL no longer knows that STORAGE-BLOCK-ADDR points to storage block.
In COBOL/VS, the SERVICE RELOAD statement must follow an address change to insure addressability.

Let's put the SERVICE RELOAD statement in our security routine example.

01 ADDRESS-LIST.
05 ADDRESS-LIST-ADDR PIC S9(8) COMP.
05 TERMINAL-USER-AREA-ADDR PIC S9(8) COMP.
01 TERMINAL-USER-AREA.
.
.
CHECK-SECURITY.

EXEC CICS ADDRESS
TCTUA (TERMINAL-USER-AREA-ADDR)
END-EXEC.
SERVICE RELOAD TERMINAL-USER-AREA
IF TCTUA-DEPARTMENT-CODE = 'PAYR'
AND TCTUA-SECURITY-LEVEL NOT > 3
MOVE 'Y' TO SALARY-UPDATE-ALLOWED
ELSE
MOVE 'N' TO SALARY-UPDATE-ALLOWED.

Two more things about SERVICE RELOAD ...

As you recall, the first entry in the address list is the address of the list itself.
CICS loads the ADDRESS-LIST-ADDR for you, but you should still do a SERVICE RELOAD statement.

01 ADDRESS-LIST.
05 ADDRESS-LIST-ADDR PIC S9(8).
05 TCTUA-ADDR PIC S9(8).
05 TWA-ADDR PIC S9(8).

01 TCTUA.
.
.
01 TWA.
.
.
PROCEDURE DIVISION.
ADDRESS-LIST
SERVICE RELOAD .

Many programmers code the SERVICE RELOAD ADDRESS-LIST as the first line of their PROCEDURE DIVISION so they don't forget to code this statement.
It is important to realize that SERVICE RELOAD is a COBOL statement; however, you will not find it in your COBOL manuals.
This statement was added to the language to handle he problem of addressability and is documented in
the CICS Programmer's Guide.
Now that you understand the concept of ADDRESSING, here is another way that it can be used.

Remember the file READ command?

EXEC CICS READ
DATASET ('EMPFILE')
RIDFLD (EMP-KEY)
INTO (EMP-RECORD)
END-EXEC.

The INTO option tells CICS where to put the record. What CICS actually does is ...
- allocate a block of storage in memory
- read the record into the storage block
- copy it into WORKING STORAGE

We can eliminate the "copy" step by defining EMP-RECORD in the LINKAGE SECTION, and asking CICS where it is.
The SET option tells CICS to return the address of the just read record and put it into EMP-REC-ADDR.

LINKAGE SECTION

01 ADDRESS-LIST.
05 ADDRESS-LIST-ADDR ...
05 EMP-RECORD-ADDR ...

01 EMP-RECORD.

EXEC CICS READ
DATASET ('EMPFILE')
RIDFLD (EMP-KEY)
SET (EMP-RECORD-ADDR)
END-EXEC.

In which RECORD should EMP-REC-ADDR be defined?
The variable should be defined in the ADDRESS-LIST.

Here is some code which is meant to read a record, but not copy it into Working Storage. Fill in the blanks, using the extension "-ADDR" where applicable.

LINKAGE SECTION.

01 ADDRESS-LIST.
05 ADDRESS-LIST-ADDR PIC S9(8)COMP.
05 TCTUA-ADDR PIC S9(8)COMP.
05 EMP-RECORD-ADDR PIC S9(8)COMP.
01 TCTUA PIC X(10).
01 EMP-RECORD.
05 EMP-NUMBER PIC X(10).
05 EMP-FNAME PIC X(15).


EXEC CICS READ
DATASET ('EMPFILE')
RIDFLD (EMPKEYI)
SET (EMP-RECORD-ADDR)
END-EXEC.
SERVICE RELOAD EMP-RECORD.

The principles of control and storage block addressability discussed in this module are relevant to all COBOL/VS organizations.

For those organizations using the VS COBOL II compiler, address coding is handled somewhat differently.

Let's take a look at those differences now ...

With the VS COBOL II compiler, it is no longer necessary to code the address list. This section is completely removed.
The next difference is in the addressability of blocks larger than 4096 bytes.
Multiple pointers are no longer required, neither is the LENGTH command. CICS calculates the length from the definition and handles the pointers for you.
Finally, the SERVICE RELOAD statement is no longer required.
Each time an address variable is changed, the internal registers are updated.

01 TERMINAL-USER-AREA.
05 TCTUA-DEPARTMENT-CODE PIC X(04).

01 TABLE-1.
05 PRODUCT-TBL OCCURS 1000.
10 PRODUCT-NO PIC X(10).
10 PRODUCE-NAME PIC X(24).
10 PRODUCT-PRICE PIC S9(4)V99.

PROCEDURE DIVISION.

EXEC CICS GETMAIN
SET (TABLE-1-ADDR)

END-EXEC.

What are Control Blocks used for?

Controlling the operations of a task
Assigning security to a terminal
Providing global installation data

Fill in the blanks to finish the following CICS COBOL segment.

LINKAGE SECTION.
.
.
01 ADDRESS-LIST.
05 ADDRESS-LIST-ADDR PIC S9(8) COMP.
05 TWA-ADDR PIC S9(8) COMP.
.
01 TWA.
05 TWA-FUNCTION PIC X(01).
05 TWA-USER PIC X(15).
.
PROCEDURE DIVISION.
.
EXEC CICS ADDRESS
TWA (TWA-ADDR)
END EXEC.
SERVICE RELOAD TWA.

What is the purpose of the SERVICE RELOAD statement?
To note an item's change of address

What variable is referred to in the SERVICE RELOAD statement?
The one whose address has changed

Indicate whether each of the following statements are (T)rue or (F)alse.

T - The SET option on a READ command saves space in main memory.
T - The INTO option of a READ command causes items to be copied into WORKING STORAGE.
T - The SET option makes programs more CPU efficient.

Complete this segment of CICS code to dynamically acquire storage.

LINKAGE SECTION.

01 ADDRESS-LIST.
05 ADDRESS-LIST-ADDR PIC S9(8) COMP.
05 A-TABLE-ADDR PIC S9(8) COMP.

01 A-TABLE.
05 TABLE-STORAGE OCCURS 100.
10 FIELD1 PIC X(20).
10 FIELD2 PIC X(10).

PROCEDURE DIVISION.

EXEC CICS GETMAIN
SET (A-TABLE-ADDR)
LENGTH (3000)
END-EXEC.

Which of the following LINKAGE SECTION coding is correct for dynamically acquiring storage in a CICS COBOL program.

01 DFHCOMMAREA.

01 ADDRESS-LIST.
05 ADDRESS-LIST-ADDR
05 TCTUA-ADDR
05 TCA-ADDR

01 TCTUA.

01 TCA.



CICS/XA LEVEL II MODULE 6

CICS Service Transactions
- General Information
- Master Terminal Facility
- Temporary Storage Browse
- Command Level Interpreter
- Online Resource Definition

IBM supplies a number of service transactions with the CICS system. These transactions provide tools
for application development, data set manipulation, and online modifications of the CICS environment.

You'll be learning how to use some of these service transactions but first, some general discussion...

CICS service transactions have 4 character identification codes.
CICS service transactions always begin with the letter "C". ¦

CEBR, CECI, CECS, CEDA, CEMT

To start any CICS service transaction, you generally type the transaction code on the command
line of the screen.


Start the service transaction CECS.
The next screen to appear is one example of the standard 4 part display used in CICS service transactions.


STATUS: ENTER ONE OF THE FOLLOWING

ABend ENDbr POSt SPOOLClose
ADdress ENQ PURge SPOOLOpen
ALlocate ENTer PUSh SPOOLRead
ASKtime EXtract READ SPOOLWrite
BIf FOrmattime READNext START
BUild FREE READPrev STARTBr
CAncel FREEMain READQ SUspend
CONNect Getmain RECeive SYncpoint
CONverse Handle RELease Trace
DELAy IGnore RESEtbr Unlock
: : : :

PF 1 HELP 2 HEX 3 END 4 EIB 5 VAR 6 USER

Use arrow keys and ENTER for more information about each part.
The second line is the STATUS LINE. The status line can prompt the programmer or indicate how a
command will be processed.
Middle portion :This area is used for INFORMATION. This part of screen displays processing results or extra information.
The PF KEY LINE displays other user options...

PF1....HELP
PF2....HEX
PF3....END
PF4....Exec Interface Block
PF5....VARiables
PF6....USER Display
PF7....Scroll Back Half
PF8....Scroll Forward Half
PF9....MeSsaGes
PF10...Scroll Back
PF11...Scroll Forward

A command or keyword can be entered on the command line by itself or with data.
If the additional information is wrong or incomplete, you will be prompted.

Before we go further, let's look at interpreting the prompts given.

These rules are standard for all CICS service transactions.

- Enter your own information when lowercase letters are displayed.
e.g. CEBR xxxxxxxx

Note: Do not get this confused with the upper and lower case letters that CICS displays to show you the short form of a keyword.
For example: READNext

- Parentheses must be entered as shown to act as delimiters.
e.g. FILE ()

- Select one of the items enclosed in braces {} and separated by .
e.g. CEMT {INQSETADDREMOVE}

- Items enclosed in [] or <> symbols are optional parameters.
e.g. [DATE(value)]

The screen on the left is an example of a syntax prompt for the READ FILE command in a CECS transaction.

Now for some specific CICS service transactions...

First, we'll be looking at the

CEMT - CICS Enhanced Master Terminal

CEMT is used by an operator to control CICS.
For example, with CEMT, the operator can:

- open or close files
- control tuning parameters
- diagnose terminal problems
- disable or enable transactions
- shut CICS down

Most of the time, you will use CEMT to inquire (INQ) about the status of some resource on the system or to (SET) the status of some resource.
By using CEMT we can get do following.

You could load a fresh copy of a program.
You could find out if a TERMINAL is available for use.
You could open and close a transient storage queue.
You could force a TASK to terminate abnormally.

These are only a few ways in which CEMT can be used. It performs many other functions
as well...

INQUIRE about the TAsks(s) which are currently running.
Which task is suspended?

CEBR - Temporary Storage Browse

CEBR allows you to access data on a temporary storage queue.
With CEBR, queues can be
- browsed
- copied
- deleted

Now let's look at the commands available in the CEBR service transaction...
QUEUE xxxx - Names the queue you want to be current.
TERMINAL...- Changes the terminal part of a queue name.
LINE n.. - Displays LINE n on line 2 of the screen.
COLUMN n. - Moves the display to the n th queue column.
FIND /str - Finds the next occurrence of the specified string.
TOP - Shows the first page of the current queue.
BOTTOM - Shows the last page of the current queue.
GET - Moves transient data to temporary storage.
PUT - Copies temporary data to a transient queue.
PURGE - Erases the contents of the queue being browsed.

Browsing transient data queues is a bit different.
For one thing, you must first move transient data into temporary storage.
Notice that as soon as data is read from a transient queue, it is erased from the transient

If you are having difficulty moving transient data into temporary storage, it may be because
the transient data queue has not been opened.

What service transaction opens and closes files?
CEMT is used to open and close files.

CECI - CICS Enhanced Command Interpreter

- CECI will walk you through the syntax of a CICS command.
- CECI will execute a CICS command interactively.
- CECI will give feedback on the execution success.
- CECI is used to execute tasks without having to put CICS commands into a COBOL program.
- CECI is used in a variety of test situations - for example, trying out some parameters with a command.

CECI and CEBR can be used to create temporary storage.
CECI could be used to repair corrupted data base records.
CECI could be used to try out an unfamiliar CICS command.
CECI is a CICS tool.

Start the command interpreter service transaction.
CECI
Imagine you want to try the CICS START command. Type the appropriate command on the command line.

START
STATUS: ENTER ONE OF THE FOLLOWING

ABend ENDbr POSt SPOOLClose
ADdress ENQ PURge SPOOLOpen
ALlocate ENTer PUSh SPOOLRead
ASKtime EXtract READ SPOOLWrite
BIf FOrmattime READNext START
BUild FREE READPrev STARTBr
CAncel FREEMain READQ SUspend
CONNect Getmain RECeive SYncpoint
CONverse Handle RELease Trace
DELAy IGnore RESEtbr Unlock
: : : :

PF 1 HELP 2 HEX 3 END 4 EIB 5 VAR 6 USER 9 MSG
_________________________________________________

Notice that CECI prompts you for more information.















START
STATUS: COMMAND SYNTAX CHECK
EXEC CICS START
TRansid()
<>
<>
<>>>
<>
<>
<>
<>
:

S TRANSID MUST BE SPECIFIED

PF 1 HELP 2 HEX 3 END 4 EIB 5 VAR 6 USER 9 MSG


Up to this point, CECI and CECS are identical. CECS (Command Syntax) is a subset of CECI.
However, CECI can actually execute the commands.


Enter TRANSID(PAYR)

TRANSID(PAYR)
STATUS: COMMAND SYNTAX CHECK
EXEC CICS START
TRansid()
<>
<>
<>>>
<>
<>
<>
<>

CECI would now execute transaction PAYR.

CEBR is used to BRowse the temporary and transient queues.
CECI (Command Interpreter) is often used to try commands.
Use CEMT to INQuire about tasks and transactions, etc.
CECS (or CECI) can check and prompt for command syntax.

Let's continue with service transactions used for online resource definition.
As you know, resource definitions are stored in CICS tables.

ie. PCT, PPT, DCT, FCT

Online resource definition means being able to change CICS tables while the CICS system is running.
Of course, changing tables online could have some disastrous results.

CEDA, CEDB, and CEDC are often used with groups of resources.
For example:
one payroll transaction uses the same resources from different tables every time it is invoked.






- CEDA can be used to install new groups.
- CEDB can modify existing groups (but not install).
- CEDC can be used to browse existing groups

CEDF - CICS Execution Diagnostic Facility.

CEDF is a CICS command debugging tool.
It allows you....
- to monitor execution of a program.
- to interrupt execution at given points.
- to change values in Working Storage during execution.
- to prevent commands from being executed.

Enter the appropriate information to invoke CEDF.

Enter CEDF.

THIS TERMINAL: EDF MODE ON

This message then appears.

To monitor a transaction, type the TRANSID on the command line overwriting the previous message. Extra characters are erased.
A transaction named MENU is used as an example ...

CICS will respond with an INITIATION screen much like the 4 part screen in other CICS service transactions. However, there are important differences.


TRANSACTION: MENU PROGRAM: MENUP01 TASK NUMBER: 0000897 DISPLAY: 00
STATUS: PROGRAM INITIATION  ‑‑‑
EIBTIME = 121518
EIBDATE = 91046 +------------------------------------------+
EIBTRNID = 'MENU' ¦
EIBTASKN = 897 ¦
EIBTRMID = 'AS10'. ¦
 .¦
EIBCPOSN = 0 ¦ ¦
EIBCALEN = 0 ¦
EIBAID = X'6D' ¦. ¦
EIBFN = X'0000' +------------------------------------------+
+ EIBRCODE = X'000000000000' AT X'0005CCAD'
:
ENTER: CONTINUE ­­­
PF1 : UNDEFINED PF2 : SWITCH HEX/CHAR PF3 : END EDF SESSION
PF4 : SUPPRESS DISPLAYS PF5 : WORKING STORAGE PF6 : USER DISPLAY
: : PF9 : STOP CONDITIONS



The COMMAND LINE is mostly informational. Only the display number can be changed.

CEDF can remember up to 10 displays. By changing the display number, you can move backward and forward through these. The most recent display is always numbered 00. The display immediately before this is numbered -1.

What is the oldest possible display number?
-10 because CEDF can remember up to 10 displays.
The most recent display is always numbered 00.
The display immediately before this is numbered -1.
Normally, CEDF remembers only command displays.

The STATUS LINE gives the reason for CEDF's interruption of execution.
Here, execution was "interrupted" because CEDF is ready to begin.

CEDF interrupts execution
- at transaction initiation
- before and after every CICS command
- at program or task termination.

The interrupt conditions can be changed from the STOP CONDITIONS display.
This display can be reached by pressing the PF 9 key.
Overtyping the fields in the INFORMATION ARE is one of the most important ways
of interacting with CEDF.
When a field is overtyped, the new value is used in the execution of your program.
Most of the PF KEY menu below will already be familiar to you.
The ENTER key starts execution of the current transaction and changes the display to ...

THE COMMAND DISPLAY

The information area in this display contains
- the current command,
- its absolute address and line number,
- and the response condition (if any).
Notice that the status line indicates that execution of READQ TS is about to begin.


TRANSACTION: MENU PROGRAM: MENUP01 TASK NUMBER: 0000897 DISPLAY: 00
STATUS: COMMAND EXECUTION ABOUT TO BEGIN
EXEC CICS READQ TS
QUEUE ('AS10SECD')
INTO (' .)
LENGTH (200)
ITEM (1)

OFFSET:X'BCD074' LINE:00225 EIBFN=X'0A04'
RESPONSE: NORMAL

ENTER: CONTINUE
PF1 : UNDEFINED PF2 : SWITCH HEX/CHAR PF3 : END EDF SESSION
PF4 : SUPPRESS DISPLAYS PF5 : WORKING STORAGE PF6 : USER DISPLAY
PF7 : SCROLL BACK PF8 : SCROLL FORWARD PF9 : STOP CONDITIONS


When you are in the command display, you may overtype ...

A command. (The command can only be overwritten with NOP or NOOP to suppress command execution.)

The WORKING STORAGE DISPLAY allows you to view and change the contents of Working Storage.









TRANSACTION: MENU PROGRAM: MENUP01 TASK NUMBER: 0000897 DISPLAY: 00
ADDRESS: 0005F84C WORKING STORAGE
0005F840 000000
0005F850 00000
0005F860 00001
0005F870 00002
0005F880 00003
0005F890 00004
0005F8A0 00005
0005F8B0 00006
0005F8C0 00007
0005F8D0 00008
0005F8E0 000094 00000000 00000000 00000000 00000000 ................
0005F8F0 0000A4 00000000 00000000 00000000 00000000 ................
0005F900 0000B4 00000000 00000000 00000000 00000000 ................
0005F910 0000C4 00000000 00000000 00000000 00000000 ................

ENTER: CURRENT DISPLAY
PF1 : UNDEFINED PF2 : BROWSE TEMP STORAGE PF3 : UNDEFINED
PF4 : EIB DISPLAY PF5 : WORKING STORAGE PF6 : USER DISPLAY
PF7 : SCROLL BACK HALF PF8 : SCROLL FORWARD HALF PF9 : UNDEFINED
PF10: SCROLL BACK FULL PF11: SCROLL FORWARD FULL PF12: REMEMBER DISPLAY



You can move through Working Storage either by changing the start address or by using the scroll keys.

Working Storage displays ...

- the HEXADECIMAL contents of Working Storage
- the EBCDIC equivalents of Working Storage contents
- the Absolute Address of the first location in each row
- and the offset from the start address of the first location in each row.

It was mentioned earlier that CEDF allows you to set conditions for interrupting your transaction.
This is done from the STOP CONDITIONS DISPLAY.

Press PF9 now for the STOP CONDITIONS DISPLAY.
If you overtype fields in the STOP CONDITIONS display, CEDF will interrupt execution of your transaction only when it finds one of the conditions you have set.



















TRANSACTION: MENU PROGRAM: MENUP01 TASK NUMBER: 0000897 DISPLAY: 00
DISPLAY ON CONDITION:-

COMMAND: EXEC CICS ________
OFFSET: X'......
LINE NUMBER: ........
CICS EXCEPTIONAL CONDITION:
ANY CICS ERROR CONDITION YES
TRANSACTION ABEND YES
NORMAL TASK TERMINATION YES
ABNORMAL TASK TERMINATION YES


NTER: CU
F1 : UNDEÈ
F4 : SUPPRESS DISPLAYS PF5 : WORKING STORAGE PF6 : USER DISPLAY
F7 : UNDEFINED PF8 : UNDEFINED PF9 : UNDEFINED
F10: UNDEFINED PF11: UNDEFINED PF12: REMEMBER DISPLAY


Select the fields you'd use if you wanted your transaction to be interrupted ...
... at the CICS command in line number 260.
... at all SEND MAP commands.

Once you have set the STOP CONDITIONS you want, press ENTER to return to the command display ...
... and then press PF4!!

The stop conditions you have selected will not take effect until you press this key!

When you wish to end the CEDF session, press PF3 (END EDF SESSION).

The current transaction will continue, but will not be monitored by CEDF.

You may use PF12 (ABEND USER TASK) to stop execution before you press PF3.

Are the following statements (T)rue or (F)alse?

CEDF is used for debugging COBOL commands. - F
CEDF can be used to browse Working Storage. - T
CEBR can be accessed from within CEDF. - T

1. Which one of the following could not be a CICS service transaction?

CEDC,CEOT,PAYR,CEDA
Ans : PAYR

2. Mark the following (T)rue or (F)alse:

T - A transient data queue must be copied into a temporary storage queue before it can be browsed, etc. with CEBR.
T - CEBR is used to view the contents of a transient data queue without permanently destroying it.
F - When a transient data queue is read into temporary storage, a copy of the data remains in the transient data queue.





CICS/XA LEVEL II MODULE 7

EXECUTION AND DEBUGGING
- Translating and Compiling
- ABEND commands
- HANDLE ABEND commands
- ABEND codes
- Debugging with ABEND Dumps

Before COBOL programs can be executed,
- they must be COMPILED to create Object Code ...
- and then LINK-EDITED to create a load module.

COBOL compilers do NOT understand CICS Commands!

Programs which use CICS commands must be TRANSLATED before they can be compiled.

The translator creates COBOL code which can be compiled and link-edited.
When a program is translated, its CICS commands are commented out and equivalent COBOL code is added.

000130 HIHO.
000131
000132 MOVE ZERO TO GOOSE-EGG.
000133
000134 COMPUTE GOOSE-EGG = 1 / GOOSE-EGG.
000135
000200*---------------------------------------------------
EXEC CICS RETURN END-EXEC.
000210

000220*---------------------------------------------------
000240
000250 GOBACK.

When the program is then compiled, the Compiler adds new line numbers to allow for the additional lines.
00176 **000130 HIHO.
00177 **000131
00178 **000132 MOVE ZERO TO GOOSE-EGG.
00179 **000133
00180 **000134 COMPUTE GOOSE-EGG = 1 / GOOSE-EGG.
00181 **000135
00200 000200*---------------------------------------------------
00201 ** *EXEC CICS RETURN END-EXEC.
00210 000210 MOVE ' 00020 ' TO DFHEIVO
00211 ** CALL 'DEFEI1' USING DFHEIVO.
00220 000220*---------------------------------------------------
00240 000240
00250 000250 GOBACK.

- Translating, compiling, and link-editing are all batch processes.
- These not only produce system files, but also create printouts for your use.
- The printouts contain information which you will need to debug your program.
- We will look at these in detail when we look at debugging.

Are the following statements true.

T - Link-editor Combines Object Code files into a single Load Module.
T - Translator Replaces CICS commands with COBOL code.
T - Complier Converts COBOL Source Code into Object Code.

ABEND CODES

- When CICS is unable to execute a command (usually because of a programming error!) it generates an ABEND or ABnormal task ENDing.
- When this occurs, CICS issues a 4-character ABEND CODE. This code is sent to the terminal running the task, and is attached to the ABEND DUMP.
(We'll talk about ABEND dumps later.)
- The ABEND code that is issued depends on the error that was encountered.

Common ABEND Codes

Code Meaning Common causes

ASRA System run-time error. Division by 0
Subscript overrun
ABMO BMS mapping request Check your spelling!
for map not in mapset.
APCT Call for nonexistent program. PPT not yet updated.
AExx Exceptional condition Duplicate records (AEIN)
encountered during run. End of file (AEIT)


* A complete list of ABEND codes and their meanings can be found in the CICS Messages and Codes Manual.

ABENDS can be trapped by the HANDLE ABEND command.

EXEC CICS HANDLE ABEND
.......
END-EXEC.

The HANDLE ABEND command can be used either
- to trap and handle errors,
- or simply to permit some system clean-up before a task ABENDS.

The HANDLE ABEND command has 4 possible options.
When using this command, you must select 1 and only 1 of these options.

- PROGRAM(name) transfers control to the program named in the argument.

EXEC CICS HANDLE ABEND
PROGRAM('TRAP')
END-EXEC.

- LABEL(label) transfers control to the program label in the argument.

EXEC CICS HANDLE ABEND
LABEL('LINE4')
END-EXEC.

- CANCEL keeps earlier HANDLE ABENDS from being executed.

EXEC CICS HANDLE ABEND
CANCEL
END-EXEC.

- RESET reactivates HANDLE ABEND commands which were previously cancelled.

EXEC CICS HANDLE ABEND
RESET
END-EXEC.

As each new HANDLE ABEND command is encountered during execution, it replaces the previous one as the active HANDLE ABEND.

- ABENDs can be caused by ABEND command as well as by programming errors.

EXEC CICS ABEND
[ABCODE(code)]
[NODUMP]
[CANCEL]
END-EXEC.

ABEND COMMAND OPTIONS

- When the ABCODE option is used, task-related memory is dumped.
- The ABEND code argument is used as a label for this dump.
- In contrast, the NODUMP option prevents a dump from occurring.
- Finally, the CANCEL option causes all HANDLE ABEND commands to be ignored.

Select the correct options for this ABEND command so that
- any HANDLE ABEND commands are ignored and
- a memory dump is performed. Label this dump PNT2.

EXEC CICS ABEND
ABCODE(PNT2)
CANCEL
END-EXEC.

The ABCODE option causes a dump, and the CANCEL option causes HANDLE ABENDs
to be ignored.

When a program ends abnormally, the system memory contains information which could
be very useful for debugging.

This includes:
- the address of the command which caused the ABEND,
- the contents of the program's variables, and
- a list of other processes being executed by the system.

When a CICS ABEND occurs, this information is collected and copied into a disk file called the CICS Dump Data Set. The Dump Data Set can then be printed using the CICS Dump Utility, DFHDUP.

- Unfortunately, a memory dump is just what the name suggests: the contents of large blocks of memory are dumped out through the printer, with little or no selection.
- Finding the information you need can be difficult, unless you know where to look and what to look for.

Let's see how it's done ...

First, we want to find the command that caused our program to ABEND. To do this, we need its RELATIVE ADDRESS.

In an ABEND dump, all addresses are ABSOLUTE ADDRESSES.
- RELATIVE ADDRESS:
An address calculated from the beginning of a program.
- ABSOLUTE ADDRESS:
An address calculated from the beginning of a storage block.

Example :
A program is loaded in memory at address 2500.
If a SEND command begins 357 bytes from the beginning of that program,it has a RELATIVE ADDRESS of _357 and an ABSOLUTE ADDRESS of _2857 .
Notice that ABSOLUTE ADDRESS - LOAD ADDRESS = RELATIVE ADDRESS.
So ...
if we take the ABSOLUTE ADDRESS of the command which ABENDed a program, and subtract the PROGRAM LOAD ADDRESS, we can find the RELATIVE ADDRESS of the ABENDing command.

If a command has an ABSOLUTE ADDRESS of 1580 and the LOAD ADDRESS for the program is 1320, what is the command's RELATIVE ADDRESS?
The RELATIVE ADDRESS is 260.
ABSOLUTE ADDRESS - LOAD ADDRESS = RELATIVE ADDRESS.
1580 - 1320 = 260.

- Actually, an ABEND dump does not tell us the address of the ABENDing command.
- However, it does tell us which machine language instruction would have been executed NEXT if the program had not ABENDed.
- The ABENDing command will be the last command before this.

Now, all we need is the Program Load Address.

An ABEND dump DOES contain a load address for the ABENDed program.

However, because your program contains CICS commands, the Link-Editor adds an extra Control Section or CSECT to the front of your program.

The load address given in an ABEND dump is for this CSECT, and NOT for your program.

Your program begins after this CSECT (which is called DFHECI).

So, if we take the load address from the dump and add the length of this CSECT ...
we get the actual load address of your program.

Now we can collect the information we need to find the ABENDing command in a program.

- Here's the beginning of an ABEND dump for the transaction TCOB.
- This application was terminated by an ASRA (run-time system error) ABEND.


O TADCIST --- CICS TRANSACTION DUMP --- CODE=ASRA TASK=TCOB

O SYMPTOMS= AB/UASRA PIDS 566540301 FLDS/F000KC RIDS/TCOBP01

O CICS/VS LEVEL = 0211

O PSW 078D2000 00350576 0006000B 00000000
O REGS 14-4 504EA802 003506A8 00000000 00000000 904EC40C
O REGS 5-11 80000000 0013698C 00136D63 00136D64 00350642


Notice that the information is presented
- in 32-bit words,
- with 4 bytes per word,
- and with 2 characters per byte.




Notice that the information is presented
- in HEXADECIMAL form!

Let's start by finding the program's load address. To find this address, we will need ...

- the load address for the program given in the dump and the length of the CSECT added by the Link-Editor.
- A program's load address can be found in the PROGRAM STORAGE section of an ABEND dump.
- An ABEND dump may contain more than one PROGRAM STORAGE section.
- The section we need will have the name of our program (TCOBP01) in the EBCDIC columns on the left side of the printout.


O 00000120 00000000 00000000 F6F2F6F0 F1F14040 E4000000 00000000 04000970
00000140 C28B0005 00004040 40404040 40404040 40404040 40404040 85100158
O

O PROGRAM STORAGE ADDRESS 00350008 TO 00350FD7

O 00000000 C4C6C8E8 C3F2F1F0 58F00010 58F0F000 58F0F004 58F0F0D0 58F0F014
00000020 58FF000C 07FF58F0 001058F0 F00058F0 F00458F0 F0D058F0 F01458F0
O 00000040 00C858FF 018407FF 90ECD00C 185D05F0 4580F010 E3C3D6C2 D7F0F140
00000060 0700989F F02407FF 96021034 07FE41F0 000107FE 00350642 00350050
O 00000080 003504F8 00136B5C 00350528 00350602 00000000 50350688 904EC40C



- These are the EBCDIC columns from the left side of the PROGRAM STORAGE section we have been looking at.
- As you can see, TCOBP01 appears near the top of this area: this is the PROGRAM STORAGE section we need.

PROGRAM LOAD ADDRESS FROM DUMP

- The program load address for TCOBP01 is simply the first of the two addresses at the head of this section.

What is the program load address for TCOBP01? 00350008

- To find the length of the CSECT, DFHECI, we need to look at the listing that was created when the program was LINK-EDITED.
- We need the CONTROL SECTION section of this listing.
- DFHECI will be the first CSECT listed, and its length will be listed beside it.
What is the length of DFHECI? 48

CROSS REFERENCE TABLE

CONTROL SECTION

NAME ORIGIN LENGTH NAME LOCATION NAME
DFHECI 00 48
DFHEI1 8 DLZEI01
DLZEI04 8 DFHCBLI
TCOBP01 48 656
ILBOCOM0* 6A0 173
ILBOCOM 6A0


- These 4 words are the contents of the PSW or Program Status Word.
- The second word of the PSW always contains the address of the next instruction to be executed.



O TADCIST CICS TRANSACTION DUMP CODE=ASRA TASK=TCOB

O SYMPTOMS= AB/UASRA PIDS 566540301 FLDS/F000KC RIDS/TCOBP01

O CICS/VS LEVEL = 0211

O PSW 078D2000 00350570 0006000B 00000000

O REGS 14-4 504EA802 003506A8 00000000 00000000 904EC40C

O REGS 5-11 80000000 0013698C 00136D63 00136D64 00350642
_



ABSOLUTE ADDRESS OF NEXT INSTRUCTION 00350570
ACTUAL PROGRAM LOAD ADDRESS 00350050
RELATIVE ADDRESS OF NEXT INSTRUCTION 00350570 - 00350050 = 520.


O 9 TCOBP01 K Mc 10.37.30K Kc KJAN 26,1991 lLK Kc
K Mc K MK K Kc K LcK lLK Kc
O K MK K Kc K KCONDENSEDKLISTINGKc
K Kc K JcK lLK k Kc
O 173 ENTRY 0004D8 174 CALL 0004F4 Lc 175 SERVICE 000510
178 MOVE 000510 180 COMPUTE 000514 210 MOVE 000536
O 211 CALL 000546 250 GOBACK 000570 K k Kc
c


This is the Condensed Listing section of the COMPILER listing for our program.
- This section lists all the COBOL commands used in a program.

RELATIVE ADDRESS OF NEXT INSTRUCTION 520

_ their relative addresses,
_ and their line numbers.,


O 9 TCOBP01 K Mc 10.37.30K Kc KJAN 26,1991 lLK Kc
K Mc K MK K Kc K LcK lLK Kc D
O K MK K Kc K KCONDENSEDKLISTINGKc
K Kc K JcK lLK k Kc l
O 173 ENTRY 0004D8 174 CALL 0004F4 175 SERVICE 000510
178 MOVE 000510 180 COMPUTE 000514 210 MOVE 000536l
O 211 CALL 000546 250 GOBACK 000570 K k Kc


The COBOL statement which caused this program to ABEND will have the highest relative address lower than 520.

What is the line number of this command?
The line number of the command we want is 180.

RELATIVE ADDRESS OF NEXT INSTRUCTION 520



O 00178 **000132 MOVE ZERO TO GOOSE-EGG.
00179 **000133 D
O 00180 **000134 COMPUTE GOOSE-EGG = 1 / GOOSE-EGG.
00181 **000135
O 00200 000200*
00201 ** *EXEC CICS RETURN END-EXEC.
O 00210 000210 MOVE ' 00020 ' TO DFHEIV0


- This is part of the Procedure Division listing from the Compiler listing for our program.
- The command in line number 180 is the one which caused our program to ABEND.

Now, let's see how much you've learned.

- Let's take another look at the command which caused our program to ABEND.

00180 **000134 COMPUTE GOOSE-EGG = 1 / GOOSE-EGG.

- The ABEND code we found in the dump was ASRA. This is the code for a run-time system error.
- Since the ABENDing command involves division, it is likely that the ABEND was caused by an attempt to divide by 0.
- Just to be sure (and to see how it's done), let's check the value of GOOSE-EGG in Working Storage.

To check the value of GOOSE-EGG, we need to
1) find GOOSE-EGG's offset in WORKING STORAGE
2) find WORKING STORAGE in our ABEND dump, and
3) use GOOSE-EGG's offset to locate it in the dump.

This is the DATA DIVISION MAP (DMAP) from the compiler listing we saw earlier.

This gives us ...


O TCOBP01 10.37.30 JAN 26, 1991
_
O INTRNL NAME LVL SOURCE NAME BASE DISPL INTRNL NAME
DNM=1-035 01 STRANGE BL=1 000 DNM=1-035
O DNM=1-043 01 GOOSE-EGG BL=1 008 DNM=1-043
DNM=1-062 01 DFHLDVER BL=1 028 DNM=1-062
O DNM=1-080 01 DFHEID0 BL=1 036 DNM=1-080
DNM=1-097 01 DFHEIB0 BL=1 038 DNM=1-097
O DNM=1-114 01 DFHEICB BL=1 046 DNM=1-114
DNM=1-131 01 DFHEIV16 BL=1 048 DNM=1-131


... GOOSE-EGG'S offset or displacement ... and its BASE LOCATOR.

This tells us where we will find the base address from which this offset is calculated.
So GOOSE-EGG is located at an offset of 008 from the address in BASE LOCATOR 1.
- At the bottom of the DMAP ....
- is a section which defines the registers used as Base Locators.

Register 6 contains the address 00136980. 00136980

GOOSE-EGG is at an offset of 008 from this address. + 008
So GOOSE-EGG is located in address 00136988. 00136988

- The actual contents of Working Storage can be found in the TRANSACTION STORAGE sections of an ABEND dump.


- These sections contain all the pieces of memory given to a task by CICS during its execution.
- Each section is labelled with the addresses it contains.

1. Indicate whether each of the following statement is either (T)rue or (F)alse.

F - COBOL programs which contain CICS commands must be compiled before they can be translated.
T - The Link-Editing process produces a load module.
T - The ABEND code for a run-time system error is ASRA.
F - When an ABEND occurs, CICS automatically prints an ABEND dump.
T - The LABEL option in a HANDLE ABEND command transfers control to a specific line.

2. Complete the following ABEND command so that a dump labelled 'MESS' is produced.

EXEC CICS ABEND
ABCODE('MESS')
END EXEC

3. Write the HANDLE ABEND command which will transfer control to a program called CLEANUP.

EXEC CICS HANDLE ABEND
PROGRAM('CLEANUP')
END EXEC

4. For each of the resources below, select a number to match with where it can be located.

Program Load Address - Program storage section
Length of DFHECI - Control section (CSECT)
Line Number of ABENDing Command - Condensed Listing
Absolute Address of Next Command - PSW Word 2

5. You have collected the following information:

00502600 Program Load Address from Dump
00502950 Absolute Address of Next Command
40 Length of DFHECI

Using the above information, calculate the value of the following:

00502640 Actual Program Load Address
310 Relative Address of Next Command

CICS/XA LEVEL II MODULE 8

IMS DATA BASE CALLS

- Addressing IMS/VS data bases from CICS/VS

IMS/VS (Information Management System/Virtual Storage) is an IBM data base system. DL/I (Data Language/I) is the IMS/VS data base manager which lets you create and access data bases.

CICS/VS allows you to access IMS/VS data bases using DL/I calls. This module shows us how, but since it is intended for those already familiar with IMS/VS, thorough explanations for IMS/VS will not be given.

If you are already familiar with IMS/VS it is possible that you used it with batch COBOL.
For review, let's take a look at a batch COBOL program which accesses an IMS/VS data base
using DL/I calls.

001 IDENTIFICATION DIVISION.
002 PROGRAM-ID. EXAMPLE.
003 ENVIRONMENT DIVISION.
004 DATA DIVISION.
005 WORKING-STORAGE SECTION.
006
007 01 GU PIC X(04) VALUE 'GU '.

009 01 EMPL-SEGMENT
010 05 EMPL-ID PIC X
011 05 EMPL-SURNAME PIC X(2
012 05 EMPL-GIVEN-NAME PIC X(2
013 05 EMPL-SALARY PIC S9
014 05 EMPL-DEPT-CODE PIC X
015
016 01 SSA-EMPL
017 10 FILLER PIC X(0
018 10 FILLER PIC X(1
019 10 SSA-EMPL-KEY PIC X(0¦
020 10 FILLER PIC X(

The first 4 lines of the code should look familiar to you. IMS/VS, like CICS/VS, only requires this code for the IDENTIFICATION, ENVIRONMENT and DATA divisions. These lines are required for both batch and CICS/VS programs.

Next, on line 7 of the WORKING- STORAGE SECTION, we define the variable 'GU '. It will be used to pass data to a subroutine.

In this example, what value does the variable GU contain?
GU, plus two character spaces produce a four character function name to be passed.

Next, we code EMPL-SEGMENT. This field defines the IMS/VS data base layout. It
is included so our program has somewhere to store the segment accessed by IMS/VS.

Next comes the Segment Search Argument (SSA). It is used to identify the key to search for in
the IMS data base. We define it in this way in Working Storage so we can pass it in a call
statement.

So actually the SSA-EMPL field would contain:
EMPL (EMPLKEY = XXXXXX)
where XXXXXX would be the key we would search for in the data base.

If you wished to find the person with an EMPL-ID of 968758, in which field would you move this value?
SSA-EMPL-KEY is where you would move the employee's ID.

001 IDENTIFICATION DIVISION.
002 PROGRAM-ID. EXAMPLE.
003 ENVIRONMENT DIVISION.
004 DATA DIVISION.
005 WORKING-STORAGE SECTION.
006
007 01 GU PIC X(04) VALUE 'GU '.

009 01 EMPL-SEGMENT.
010 05 EMPL-ID PIC X(06).
011 05 EMPL-SURNAME PIC X(20).
012 05 EMPL-GIVEN-NAME PIC X(20).
013 05 EMPL-SALARY PIC S9(7)V9(2).
014 05 EMPL-DEPT-CODE PIC X(04).
015
016 01 SSA-EMPL.
017 10 FILLER PIC X(04) VALUE 'EMPL'.
018 10 FILLER PIC X(11) VALUE '(EMPLKEY = '.
019 10 SSA-EMPL-KEY PIC X(06).
020 10 FILLER PIC X(01) VALUE ')'.
021 LINKAGE SECTION.
022
023 01 PCB.
024 05 PCB-DBD-NAME PIC X(08).
025 05 PCB-SEG-LEVEL PIC X(02).
026 05 PCB-STATUS-CODE PIC X(02).
027 05 PCB-PROC-OPTIONS PIC X(04).
028 05 FILLER PIC S9(5) COMP.
029 05 PCB-SEGMENT-NAME PIC X(08).
030 05 PCB-KEY-LENGTH PIC S9(5) COMP.
031 05 FILLER PIC S9(5) COMP.
032 05 PCB-KEY-FEEDBACK PIC X(06).
033

Now for the LINKAGE SECTION. In a batch COBOL program that accesses IMS data bases, all you code is the PCB or Program Communication Block.
This is used to transfer information between the data base system and your program.

034 PROCEDURE DIVISION.
035
036 ENTRY 'DLITCBL' USING PCB.
037 PERFORM GET-EMPL-SEGMENT.
038
039 GOBACK.
040
041

Now let's look at the PROCEDURE DIVISION.
Line 36 establishes an entry point in your program which DL/I can use. It also establishes addressability to the PCB.
Now we perform the GET-EMPL-SEGMENT SECTION. We will see that next.

040
041 GET-EMPL-SEGMENT SECTION.
042
043 MOVE '968758' TO SSA-EMPL-KEY.
044
045 CALL 'CBLTDLI' USING
046 GU, PCB, EMPL-SEGMENT,
047 SSA-EMPL.
048
049 IF PCB-STATUS-CODE NOT = SPACES AND 'GE'
050 PERFORM ABEND.
051
052 FETCH-PSB-END.
053 EXIT.

This is the section which will access the IMS data base. In line 43 we move the key we will be searching for into the SSA-EMPL-KEY field. Then we issue the DL/I call.

We will take a closer look at the call statement later in the module.
One of the fields in the PCB is PCB-STATUS-CODE. After a DL/I call this field tells us the status of the call. If this field contains spaces, everything is fine. If it contains GE, it means that the
segment wasn't found. Anything else in this field would mean a problem. ABEND is a routine which deals with the problem.

Here is the DL/I data base call statement. Note the order of the arguments.

CALL 'CBLTDLI' USING
GU, PCB, EMPL-SEGMENT,
SSA-EMPL.

The subroutine CBLTDLI is the interface between IMS/VS and your batch program.

The first argument is the variable which contains the name of the function to be performed. In this example we are using GU or Get Unique segment function.

In which section did we find the field GU defined?
It is defined in the WORKING-STORAGE SECTION as follows:

WORKING-STORAGE SECTION.

01 GU PIC X(04) VALUE 'GU '.

The second argument is the PCB corresponding to the data base we wish to call.
Here's how it's defined in the LINKAGE SECTION.
LINKAGE SECTION.
01 PCB.
05 PCB-DBD-NAME PIC X(08).
05 PCB-SEG-LEVEL PIC X(02).
05 PCB-STATUS-CODE PIC X(02).
05 PCB-PROC-OPTIONS PIC X(04).
05 FILLER PIC S9(5) COMP.
05 PCB-SEGMENT-NAME PIC X(8).
05 PCB-KEY-LENGTH PIC S9(5) COMP.
05 FILLER PIC S9(5) COMP.
05 PCB-KEY-FEEDBACK PIC X(06).

The third argument specifies the field which will contain a retrieved segment. We define it in
WORKING-STORAGE as follows...

01 EMPL-SEGMENT.
05 EMPL-ID PIC X(06).
05 EMPL-SURNAME PIC X(20).
05 EMPL-GIVEN-NAME PIC X(20).
05 EMPL-SALARY PIC S9(7)V9(2).
05 EMPL-DEPT-CODE PIC X(04).

The fourth argument is the name of the Segment Search Argument we use to identify segments of the DL/I data base. This is what it looks like in the WORKING-STORAGE SECTION.

01 SSA-EMPL.
05 FILLER PIC X(04) VALUE 'EMPL'.
05 FILLER PIC X(11) VALUE '(EMPLKEY = '.
05 SSA-EMPL-KEY PIC X(06).
05 FILLER PIC X(01) VALUE ')'.

In summary, the arguments are:

1. GU - function to be performed.

2. PCB - PCB corresponding to the data base specified.

3. EMPL-SEGMENT - work area to contain the returned segment.

4. SSA - name of the SSA.

Which of the following would you use to issue a DL/I data base call?

CALL 'CBLTDLI' USING doesn't complete the call. Arguments are also needed. Here is a list that you could use:
A. EMPL-SEGMENT - work area
B. GU - function name
C. PCB - PCB of data base
D. SSA-EMPL - Segment Search Argument

In which order would these appear in the DL/I call?

The CALL statement would look like this:
CALL 'CBLTDLI' USING GU, PCB, EMPL-SEGMENT, SSA-EMPL.

You've just seen an example of how to issue a DL/I data base call from a batch COBOL program.

The format of the call to request DL/I services doesn't change in a CICS COBOL program. As a
matter of fact, we can use the same GET-EMPL-SEGMENT SECTION from the batch COBOL program in the CICS COBOL program.

Let's look at it now.

182 GET-EMPL-SEGMENT SECTION.
183
184 MOVE EMPLNOI TO SSA-EMPL-KEY.
185
186 CALL 'CBLTDLI' USING
187 GU, PCB, EMPL-SEGMENT,
188 SSA-EMPL.
189
190 IF PCB-STATUS-CODE NOT = SPACES AND 'GE'
191 PERFORM ABEND.
192
193 FETCH-PSB-END.
194 EXIT.
195

This is from a CICS COBOL program. The only thing different, (besides the line numbers) is the field we move to SSA-EMPL-KEY in line 184. In this example we move a variable which is defined in the input map.

While the actual DL/I call to access the IMS data base is the same, a CICS COBOL program requires more steps than a batch COBOL program.

In a batch program, the PCBs are available at the start of the program. In a CICS/VS program, PCBs must be dynamically accessed. In order for us to access these PCBs, we must schedule the PSB (Program Specification Block).

The Program Specification Block (PSB) contains one or more Program Communication Blocks (PCB's). Remember the PCB describes the access requirements of each data base.

We'll talk about how we schedule a PSB in more detail, but before we do, let's look at how we set up the WORKING-STORAGE SECTION and the LINKAGE SECTION in a CICS/VS application program.


001 IDENTIFICATION DIVISION.
002 PROGRAM-ID. EXAMPLE.
003 ENVIRONMENT DIVISION.
004 DATA DIVISION.
005 WORKING-STORAGE SECTION.
006 COPY EXAM12.
007 01 GU PIC X(04) VALUE 'GU '.
008 01 GET-PSB-CODE PIC X(04) VALUE 'PCB '.
009 01 RELEASE-PSB-CODE PIC X(04) VALUE 'TERM'.
010 01 PSB-NAME PIC X(08).
011
012 01 EMPL-SEGMENT.
013 05 EMPL-ID PIC X(06)
014 05 EMPL-SURNAME PIC X(20)
015 05 EMPL-GIVEN-NAME PIC X(20)
016 05 EMPL-SALARY PIC S9(7)
017 05 EMPL-DEPT-CODE PIC X(04)
018
019 01 SSA-EMPL.
020 10 FILLER PIC X(04)
021 10 FILLER PIC X(11)
022 10 SSA-EMPL-KEY PIC X(06).

This part of the program should look familiar to you. It's very similar to the batch COBOL example we looked at. We have added a few fields in lines 8 - 10 which will be used in DL/I calls.

In line 6 we copy the symbolic map into WORKING-STORAGE.

023 LINKAGE SECTION.
024
025 01 DFHEIBLK.
.
. .
.
068 01 DFHCOMMAREA PIC X(100).
069

This part of the LINKAGE SECTION should also be familiar to you.
The DFHEIBLK is generated by the translator. The DFHCOMMAREA is a communication area. Immediately after the DFHCOMMAREA is the ADDRESS-LIST.
Recall that it contains the address of itself and all subsequent 01 level entries in the LINKAGE SECTION.

70 01 ADDRESS-LIST.
71 05 ADDRESS-LIST-ADDR
72 05 UIB-ADDR
73 05 PSB-ADDR
74 05 PCB-ADDR
75
76 COPY DLIUIB.
77
78 01 PSB.
79 05 PSB-PCB-ADDR OCCURS 4 PIC S9
80
81 01 PCB.
82 05 PCB-DBD-NAME PIC X(08).
83 05 PCB-SEG-LEVEL PIC X(02).
84 05 PCB-STATUS-CODE PIC X(02).
85 05 PCB-PROC-OPTIONS PIC X(04).
86 05 FILLER PIC S9(5) COMP.
87 05 PCB-SEGMENT-NAME PIC X(08).
88 05 PCB-KEY-LENGTH PIC S9(5) COMP.
89 05 FILLER PIC S9(5) COMP.
90 05 PCB-KEY-FEEDBACK PIC X(06).

UIB-ADDR contains the address of the User Interface Block (UIB).

This DL/I code is added for you by including a COPY DLIUIB statement.

The UIB is supplied by IBM and this is what it would look like in your program.
DL/I uses the UIB to pass PSB scheduling information to the application program.

01 DLIUIB.
* DLIUIB EXTENDED CALL USER INTERFACE BLOCK
02 UIBPCBAL PICTURE S9(8) USAGE IS COMPUTATIONAL.
* UIBPCBAL PCB ADDRESS LIST
02 UIBRCODE
* UIBRCODE DL/I RETURN CODES
03 UIBFCTR PICTURE X.
* UIBFCTR RETURN CODES
88 FCNORESP VALUE ' '.
88 FCNOTOPEN VALUE '<'.
88 FCINVREQ VALUE 'H'.
88 FCINVPCB VALUE '&'.
03 UIBDLTR PICTURE X.
* UIBDLTR ADDITIONAL INFORMATION
88 DLPSBNF VALUE 'A'.
88 DLTASKNA VALUE 'B'.
88 DLPSBSCH VALUE 'C'.
88 DLLANGCON VALUE 'D'.
88 DLPSBFAIL VALUE 'E'.
88 DLPSBNA VALUE 'F'
88 DLTERMNS VALUE 'G'.
88 DLFUNCNS VALUE 'H'.

The UIBPCBAL field contains the address of the PSB. UIBRCODE is a return code which tells you the status of the scheduling request. If UIBRCODE contains LOW-VALUES after a call, everything is okay.

So UIB-ADDR contains the address of the UIB.
PSB-ADDR would contain the address of which 01 level entry?
PSB-ADDR contains the address of PSB which is defined in line 78.

A PSB contains the address of 1 or more PCB's. Generally there is a PCB for each data base to be
accessed by the program. In this example the PSB contains 4 PCB addresses.

Before you can use a PCB you must load its address into PCB-ADDR in the address list.
This must then be followed by a SERVICE RELOAD statement.

PCB-ADDR contains the address of the PCB as defined in line 81.

The PCB is defined the same as in a batch COBOL program.

Now for a quick review of the LINKAGE SECTION, answer the following questions.

ADDRESS-LIST is coded immediately after which 01 level entry?
The correct answer is DFHCOMMAREA. It looks like this:

01 DFHCOMMAREA PIC X(100).
01 ADDRESS-LIST.
05 ADDRESS-LIST-ADDR PIC S9(8) COMP SYNC.
05 UIB-ADDR PIC S9(8) COMP.
05 PSB-ADDR PIC S9(8) COMP.
05 PCB-ADDR PIC S9(8) COMP.

Indicate which LINKAGE section 01 level entry each of these statements refers to. Use the acronyms: UIB, PSB or PCB.

PSB - Contains the address of the PCBs
UIB - Contains the address of the PSB
UIB - Supplied by IBM and copied into your program
PCB - Describes access requirement for
a single data base to be accessed

Now lets examine the PROCEDURE DIVISION.

The missing lines might include code to send output to, and receive input from the terminal.

091 PROCEDURE DIVISION.
.
. .
.
150 SERVICE RELOAD ADDRESS-LIST.
151
152 PERFORM FETCH-PSB.
153
154 PERFORM GET-EMPL-SEGMENT.
155
156 PERFORM RELEASE-PSB.
157
158 EXEC CICS RETURN END-EXEC.
159
160

In Module 5 we talked about the SERVICE RELOAD statement.
Line 150 makes sure that everything is ready to go.

In accessing an IMS data base there are 3 main steps to follow.

1. Schedule the PSB and obtain PCB addresses.
2. Issue DL/I call(s) to access the required data base.
3. Issue a DL/I call to release the PSB.

The PERFORM statements in lines 152-156 will accomplish these steps. We'll take a closer look at each of these steps in a moment.

After we have accessed the data base all we have left to do is return to CICS/VS.

Fill in the blank so that this command will release our program.
The correct answer is RETURN. Now let's go back and look at the steps in accessing DL/I data bases.

First, we'll look at PSB scheduling in more detail. FETCH-PSB is the section which does this.

In the batch program we used ENTRY 'DLITCBL'. In a CICS/VS program we schedule the PSB
instead.

162 FETCH-PSB SECTION.
163
164 MOVE 'BKSB01' TO PSB-NAME.
165
166 CALL 'CBLTDLI' USING
167 GET-PSB-CODE, PSB-NAME, UIB-ADDR.
168
169 IF UIBFCTR NOT = LOW-VALUES
170 PERFORM ABEND.
171
172 SERVICE RELOAD DLIUIB.
173
174 MOVE UIBPCBAL TO PSB-ADDR.
175 SERVICE RELOAD PSB.
176
177 MOVE PSB-PCB-ADDR (1) TO PCB-ADDR.
178 SERVICE RELOAD PCB.
179
180 FETCH-PSB-END.
181 EXIT.

BKSB01 is the name of the PSB we wish to use. Remember, the PSB is generated off-line using a PSB generating utility program. We move this name into the field PSB-NAME so we can pass it in a CALL statement.

This is the DL/I call to schedule the PSB.

GET-PSB-CODE is the name of the field which contains the value 'PCB' - - the function.

This was defined in WORKING STORAGE.

NOTE:
The function is PCB and not PSB like you might expect.

PSB-NAME contains the name of the PSB we wish to use.
What name would be in PSB-NAME in this example?
In line 164 we moved BKSB01 into PSB-NAME.

UIB-ADDR is the pointer which will be set to the address of UIB after the call is completed.

In the UIB is the field UIBPCBAL which contains the address of the PSB.

What we now have is the UIB-ADDR pointing to the UIB.
In the UIB is UIBPCBAL. Which address does it contain?
It contains the address of the PSB.

Another field in the UIB is UIBFCTR. This is the return code for the call. If it contains low values
(binary zeros), then the call to schedule the PSB is successful. If it is not successful, we go to a
section that will deal with the problem.

If scheduling was successful, we have to obtain the PSB address.

The first thing to do now is a SERVICE RELOAD DLIUIB so we can make sure that addressability is
properly established.

UIBPCBAL contains the address of the PSB. We move this value to PSB-ADDR which is in the ADDRESS-LIST.

We do a SERVICE RELOAD PSB so that we can access the fields in the PSB.

What do the fields in the PSB point to?
It contains addresses of the PCBs.

In line 177, we move the address of the first PCB into the appropriate field of the ADDRESS-LIST.

Once again we do a SERVICE RELOAD, since the address of the PCB was changed.
So now we move the address of the PCB into PCB-ADDR, which points to PCB.
Finally, we have the PSB scheduled and the PCB addressed.

After we schedule the PSB and obtain the PCB address we can now carry on.

The next section we perform is GET-EMPL- SEGMENT.

182 GET-EMPL-SEGMENT SECTION.
183
184 MOVE EMPLN0I TO SSA-EMPL-KEY.
185
186 CALL 'CBLTDLI' USING
187 GU, PCB, EMPL-SEGMENT,
188 SSA-EMPL.
189
190 IF PCB-STATUS-CODE NOT = SPACES AND 'GE'
191 PERFORM ABEND.
192
193 FETCH-PSB-END.
194 EXIT.
195

This is the section which actually accesses the data base. We won't say much about this section because you have already seen it earlier in this module.

One thing worth mentioning is the functions you can perform besides GU. Other functions include:
DLET GNP GHN ISRT
GN GHU GHNP REPL

If you use any of these, remember that you must assign it a variable name in Working Storage.
After we access the data base, the only thing left is to release the PSB.

196 RELEASE-PSB SECTION.
197
198 CALL 'CBLTDLI' USING RELEASE-PSB-CODE.
199
200 RELEASE-PSB-END
201 EXIT.

You should release the PSB when all DL/I operations are complete. This is so the PSB can be used by other programs. Since you are allowed only one PSB at any given time, your releasing it will allow you to access another PSB.
If you don't release the PSB, CICS/VS will do it for you when the task ends.

196 RELEASE-PSB SECTION.
197
198 CALL 'CBLTDLI' USING RELEASE-PSB-CODE.
199
200 RELEASE-PSB-END
201 EXIT.

Line 198 is the DL/I call to release the PSB. The field RELEASE-PSB-CODE contains the function name 'TERM'.

Now you should have some idea of how to issue DL/I calls from a CICS/VS COBOL program.

To review, the steps in accessing DL/I data bases are ...

1. Issue a DL/I call to schedule the PSB and obtain PCB addresses.
2. Issue DL/I call(s) to access the data base and check results of the call.
3. Issue a DL/I call to release the PSB.

1. Indicate which call statement corresponds to each of the steps in accessing a DL/I database by entering the appropriate letter in the blank.


Issue a DL/I call to schedule the PSB -
CALL 'CBLTDLI' USINGGET-PSB-CODE,PSB-NAME,UIB-ADDR.

Issue a DL/I call to access the required database -
CALL 'CBLTDLI' USING GU,PCB,EMPL-SEGMENT,SSA-EMPL.

Issue a DL/I call to release the PSB -
CALL 'CBLTDLI' USING RELEASE-PSB.

2. When scheduling a PSB what order are the following blocks accessed?
UIB,PSB,PCB

3. You wish to release a PSB. In the WORKING-STORAGE SECTION you have defined RELEASE-PSB as follows:
01 RELEASE-PSB PIC X(04) VALUE 'TERM'.
Complete the DL/I called to release the PSB.

CALL 'CBLTDLI' USING RELEASE-PSB.

CICS/XA LEVEL II MODULE 9

DB2 and CICS
- Syntax
- Translate, Compile, Link-edit
- SQLCA
- Programming Aids

SQL commands are added to COBOL in much the same way that CICS commands are added. For example:

- Start with an EXEC statement
- Add a command.
- Code associated parameters.
- Terminate with END-EXEC.

EXEC CICS
READNEXT
FILE(PAYRROLL)
INTO(EMPLOYEE)
:
END-EXEC.

EXEC SQL
SELECT EMPNAME, EMPADDR
INTO :EMPNAME, :EMP-ADDR
FROM DSN8210.EMPTABLE
WHERE EMPNUM = :EMP-NUM
END-EXEC.

Now let's look at examples
of common SQL commands:

INSERT, UPDATE, DELETE, SELECT

INSERT

The SQL command INSERT is used to put records into a DB2 table.
Let's take a look at a typical example of an INSERT command.

MOVE '899' TO EMP-NUM.
MOVE 'JON DOE' INTO EMP-NAME.
MOVE '104 ST.' INTO EMP-ADDR.
EXEC SQL
INSERT INTO DSN210.EMPTABLE VALUES (:EMP-NUM, :EMP-NAME, :EMPADDR)
END-EXEC.

The SQL statement indicates that the record is inserted into a table called DSN210.EMPTABLE.

UPDATE

A record field is changed with UPDATE.

MOVE 819 TO EMP-NUM.
MOVE 33 TO EMP-AGE.
EXEC SQL
UPDATE DSN210.EMPTABLE
SET EMPAGE = :EMP-AGE
WHERE EMPNUM = :EMP-NUM
END-EXEC.

DELETE

You can delete a record from a table with the SQL DELETE command.

MOVE 720 TO EMP-NUM.
EXEC SQL
DELETE
FROM DSN210.EMPTABLE
WHERE EMPNUM = :EMP-NUM
END-EXEC.

SELECT

Record fields within a table can be read with the use of the SELECT statement.

MOVE 933 TO EMP-NUM.
EXEC SQL
SELECT EMPNAME, EMPADDR, EMPAGE
INTO :EMPNAME, :EMPADDR, :EMP-AGE
FROM DSN210.EMPTABLE
WHERE EMPNUM = :EMP-NUM
END-EXEC.

SQLCA

For a program to execute SQL statements the program must have an SQL communication area (SQLCA).

DB2 uses the SQLCA to return information about the program execution.
For example:
- successful execution
- flags

- return codes

In a COBOL program the SQLCA is declared in the WORKING-STORAGE SECTION located in the program's DATA DIVISION.

*-----------------------
COBOL PROGRAM
*-----------------------
:
::
DATA DIVISION.
WORKING-STORAGE SECTION.
::
EXEC SQL
INCLUDE SQLCA
END-EXEC.
::
:
As you know CICS commands must be translated into COBOL before the program can be compiled.

*** COBOL PROGRAM ***
-------------------------------------
:
EXEC CICS
READNEXT
FILE(PAYRROLL)
INTO(EMPLOYEE)
LENGTH(REC-LEN)
RIDFLD(EMP-NUM)
END-EXEC.
:
OPEN-INPUT FILE-IN.
:
EXEC SQL
SELECT EMPNAME, EMPADDR, EMPAGE
INTO : EMPNAME, :EMP-ADDR, :EMP-AGE
FROM DSN8210.EMPTABLE
WHERE EMPNUM = :EMP-NUM
END-EXEC.
:

SQL statements must also be translated before the COBOL code can be compiled.
However, the SQL processing is just a bit different from CICS.

When SQL wants to perform some function on a DB2 table, DB2 does not want to interpret the
code every time it is used. So ...
The SQL statements must be put through a binding utility. This process translates the SQL into
a form (called a plan) which DB2 can understand immediately.

This plan is stored in DB2. A simple call to that plan is left within the COBOL code.

DB2 Interactive (DB2I)

As we close, take a brief look look at a useful DB2 utility - DB2 Interactive (DB2I)






________________________________________________________________
DB2PRIM DB2 MAIN MENU
OPTION ===>

1 - DB2I - SPUFI,DCLGEN,Program Prep,DB2 Commands,Utilities

2 - QMF - Query Management Facility for DB2FLEX

3 - QMF - Query Management Facility for DB2FIX

4 - DBEDIT - for DB2FLEX

5 - QMF Message Tool

6 - QMF - Query Management Facility for DB2DEVL

N NEWS - News and Information About DB2 Services

4BU Aa C1--MVS R 2 C 15 12:51 5/09/91


DB2I is the first menu option on the DB2 Main Menu.

Enter '1' to select the DB2I option.


DB2I PRIMARY OPTION MENU
===>

Select one of the following DB2 functions and press ENTER.

1 SPUFI (Process SQL statements)
2 DCLGEN (Generate SQL and source language declarations)
3 PROGRAM PREPERATION (Prepare a DB2 application program to run)
4 PRECOMPILE (Invoke DB2 precompilers)
5 BIND/REBIND/FREE (BIND, REBIND, or FREE application plans)
6 RUN (RUN an SQL program)
7 DB2 COMMANDS (Issue DB2 commands)
8 UTILITIES (Invoke DB2 utilitie
D DB2I DEFAULTS (Set global paramete¦ special interest to us.
X EXIT (Leave DB2I)

PRESS: END to exit HELP for more information


In the DB2I menu, two of the options are of special interest to us.

SPUFI can be used to "try out" an SQL statement without the surrounding COBOL program -
much like CECI is used for CICS.

You'll remember that BIND is the process required before COBOL can use SQL statements.

1. Complete the code in this COBOL program to remove a record from the DB2 table.


PROCEDURE DIVISION.
:
MOVE '60103' to CUST-NUM.
EXEC SQL
DELETE FROM CUST.INF
WHERE CUSTNUM = :CUST-NUM
END-EXEC.
PERFORM VALIDITY-CHECK.

2. Indicate whether each of the following statements are (T)rue or (F)alse.

F - A COBOL program requires a COMMAREA declared in WORKING STORAGE SECTION to execute SQL statements.
T - DB2 returns status messages to the SQLCA. These can indicate successful execution of SQL statements.
T - Within DB2 Interactive, you can try out SQL commands without running them within a COBOL program.

3. Complete the code to add the SQL communication area to WORKING STORAGE.

:
DATA DIVISION.
WORKING-STORAGE SECTION.
:
EXEC SQL
INCLUDE SQLCA
END-EXEC.
:
:

4. Number these operations in the correct order for creating a load module for a COBOL program with CICS and SQL statements.

4 Link-edit.
2 Bind.
1 Translate.
3 Compile.