CICS TS Programming 11/14/2017

Finding Your Way

with
CICS Maps

Presented by:
 Mary Abdill
 Creative Data Movers
 [email protected]
 www.CreativeDataMovers.Inc
© 2017 Creative Data Movers, Inc.

Introduction M
o
d
BMS and the UI
u
l
e
COBOL: SEND/RECEIVE MAP
T
o
Altering attribute bytes, setting p
cursor, etc. in COBOL i
c
© 2017 Creative Data Movers, Inc.
s

1
CICS TS Programming 11/14/2017

Possible Reasons to Learn About Maps

You are coding actual maps

You maintain code that uses maps

You use map generators, such as

SDF2, and need to learn the concepts
You use a WEB 3270 Bridge, HATS, or
similar to convert maps to web pages
You are converting maps to HTML,
JavaScript, CSS

3 © 2017 Creative Data Movers, Inc.

Possible Data Flow Scenerios

3270
CICS SEND,
Emulator BMS
RECEIVE MAP
Green Screen

CICS
Web
browser SEND,
mapping (BMS)
web page RECEIVE
solution
MAP

BMS provides the data mapping between

the screen and the application © 2017 Creative Data Movers, Inc.

2
CICS TS Programming 11/14/2017

What are maps

Mapset
• Contains one or more maps

Compiled & decompiled code

• Handles I/O between the CICS application
and the user's terminal

Physical Map
• Compiled assembler macro code

Symbolic Map
• copybook of the map inputs/outputs
5 © 2017 Creative Data Movers, Inc.

BMS: Formatted
Terminal Displays

 Basic Mapping Support

 BMS allows you to format the user's screen
 Allows the application to simply deal with the user
data that is entered or changed
© 2017 Creative Data Movers, Inc.

3
CICS TS Programming 11/14/2017

BMS Concepts

• "This method of map

Describes definition is still widely used"
the UI • IBM manual—CICS TS v5.3.0

• Three assembler language

Assembler macros for defining maps
• Tools available for drawing

7 © 2017 Creative Data Movers, Inc.

Map Preparation

Physical A Load
assemble
map(s) module
Code
BMS
mapsets
& maps
Symbolic A
disassemble
map(s) copybook

Then, NEWCOPY the mapset load module:

CEMT SET PROG(mapset) NEW
Then check if map looks good:
CECI SEND MAP(map) MAPSET(mapset) ERASE FREEKB

8 © 2017 Creative Data Movers, Inc.

4
CICS TS Programming 11/14/2017

Fields
3270 screens are character-based and mark
fields with attribute bytes

attribute attribute
field
byte byte

Field starts immediately after attribute byte

Generally goes up to the next attribute byte
Output and text fields do not need ending attribute
Field has a length
But length does not stop user from typing
Length controls amount of data transferred
9 © 2017 Creative Data Movers, Inc.

Attribute bytes
Mark beginning and usually end of field
Are protected
User cannot type over an attribute byte
Provide features for the upcoming field
Is input or output (unprotected or protected)
Bold
Is autoskip on?
Is MDT on? etc.

attribute attribute
field
byte byte

10 © 2017 Creative Data Movers, Inc.

5
CICS TS Programming 11/14/2017

Stopper byte
Without a stopper byte
attribute
field
byte

User types into the field, but is not

stopped if typing goes beyond the end
With a stopper byte
User cannot type past stopper byte
Stopper byte is a protected attribute byte

attribute stopper
field
byte byte

11 © 2017 Creative Data Movers, Inc.

Autoskip (skipper) byte

Without an autoskip byte
attribute
field
byte

User not stopped if typing goes too far

With an autoskip byte
When user types last byte in field, cursor
automatically skips to next input field
Autoskip byte is a special attribute bit

attribute autoskip
field
byte byte

12 © 2017 Creative Data Movers, Inc.

6
CICS TS Programming 11/14/2017

Stopper and Skipper Bytes

A byte that causes the cursor to lock or skip

when the end of a field is reached

Immediately follows an unprotected field

Can be defined as ASKIP to cause the cursor to

jump to the next unprotected field

Can be defined as PROT which will cause the

keyboard to lock if it encounters this area

Take up one byte position on the screen

even if they have zero length

13 © 2017 Creative Data Movers, Inc.

Choice – stopper or autoskip byte

Autoskip is appropriate if input value
always the same length
Area code for US phone number
5-digit zip code
A one character code such as N/S/E/W
Stopper best if input is different lengths
Name, Address,
Comments, etc.
User uses tab to go to next field
User gets stopped if they try to type more
Reset – Ctrl+r, or other
14 © 2017 Creative Data Movers, Inc.

7
CICS TS Programming 11/14/2017

MDT = Modified Data Tag

Purpose
If MDT is 0, data is not transferred; an if
MDT is 1, then data is transferred.
Turn MDT on to transmit data from UI
Turned on when user enters data, deletes
data, or uses "end" or "clear to erase data
FRSET
Turns off all MDTs in Map; recommended
FSET
Turns on MDT for a specific field
Allows that field to be returned, even if
15 user makes no changes to it © 2017 Creative Data Movers, Inc.

3 Assembler macros—define BMS maps

DFHMDF

• Defines an individual field on a screen or web page

DFHMDI

• Defines a map as a collection of fields

• Fields can be:
• input (unprotected)
• output (protected)
• text (not seen by application program)

DFHMSD

• Groups maps into a single mapset

16 © 2017 Creative Data Movers, Inc.

8
CICS TS Programming 11/14/2017

Creating BMS Maps

Code BMS macros:

• Assembler macros
• Assemble and link
• Disassemble

Tools to draw screens and

create maps include:
• SDF
• SDF II screen
• RDz
• Micro Focus CICS/MTS
• Various CASE tools
• Etc.
18 © 2017 Creative Data Movers, Inc.

Screen Illustration

24 © 2017 Creative Data Movers, Inc.

9
CICS TS Programming 11/14/2017

27 © 2017 Creative Data Movers, Inc.

BMS Macro Format Source Columns

1 9 or 10 16 72

name opcode parameter,parameter comments

* comments

opcode parameter,parameter, comments X

parameter

28 © 2017 Creative Data Movers, Inc.

10
CICS TS Programming 11/14/2017

Mapset Definition: DFHMSD Syntax

Symbolic Physical Last
Map Map Line

pptname DFHMSD TYPE={&SYSPARM/DSECT/MAP/FINAL}

[MODE={IN/OUT/INOUT}] Usually INOUT
[LANG=COBOL/COBOL2/PLI/C]
Mapset [STORAGE={AUTO/BASE=name}] Generally AUTO
name [TERM=type] Usually 3270
and [CTRL=(controlvalues)] Features for all MAPs in MAPSET
Member
name [MAPATTS=(list of values)]
[DSATTS=(list of values)]
[COLOR=DEFAULT/colorname]
[TIOAPFX={YES/NO}] YES for 3270
[CURSLOC={YES/NO}] YES for testing input loc
etc.

29 © 2017 Creative Data Movers, Inc.

DFHMSD Examples

MAPSET
NAME

Free keyboard Beep on Turn off

on send send MDTs

30 © 2017 Creative Data Movers, Inc.

11
CICS TS Programming 11/14/2017

Map Definition: DFHMDI Syntax

mapname DFHMDI SIZE=(lines,columns)
[LINE={NEXT/line#/SAME}]
[COLUMN={SAME/NEXT/column#}]
[JUSTIFY=({LEFT/RIGHT},
{FIRST/LAST})
[CURSLOC={YES/NO}]
[CTRL=(controlvalues)]
[MAPATTS=(list of values)]
[DSATTS=(list of values)]
[HILIGHT={OFF/BLINK/REVERSE/UNDERLINE}]

31 © 2017 Creative Data Movers, Inc.

DFHMDI Example

Up to 7
characters

32 © 2017 Creative Data Movers, Inc.

12
CICS TS Programming 11/14/2017

Screen Field Definition: DFHMDF Macro

fldname DFHMDF POS=(line,column),

LENGTH=length
[ATTRB=({ASKIP/PROT/UNPROT[,NUM],
{NORM/BRT/DRK},IC,FSET)]
Up to 30
[{INITIAL='LITERAL'/XINIT='hexlit'}]
characters [PICIN='COBOL picture']
[PICOUT='COBOL picture']
[JUSTIFY=({LEFT/RIGHT,BLANK/ZERO})]
[GRPNAME=prev defined fldname]
[OCCURS=number]
[HILIGHT={OFF/BLINK/REVERSE/UNDERLINE}]
[COLOR={DEFAULT/BLUE/RED/PINK/GREEN/
YELLOW/TURQUOISE/NEUTRAL}]
[ASIS]

ASIS depends on a CICS system

setting for whether it actually works
34 © 2017 Creative Data Movers, Inc.

DFHMDF ATTRB Options

Protection Options Shift Option

• ASKIP causes cursor to • NUM forces the keyboard
jump to the next into numeric lock and
unprotected field right aligns input
• PROT means no input • Does not work for some
allowed here; the 3270 emulation software,
keyboard will lock so do not count on it
• UNPROT indicates an
input field

cont.
36 © 2017 Creative Data Movers, Inc.

13
CICS TS Programming 11/14/2017

DFHMDF ATTRB Options (cont.)

Intensity Options Other Options

• NORM makes the • FSET turns on the
brightness normal Modified Data Tag
intensity (MDT) bit
• BRT makes the field bright • IC causes the
• DRK makes the field cursor to be
hidden (not displayed); inserted in this
for example, Password field when map
input is sent

37 © 2017 Creative Data Movers, Inc.

BMS Example

cont.
38 © 2017 Creative Data Movers, Inc.

14
CICS TS Programming 11/14/2017

BMS Example (cont.)

cont.
39 © 2017 Creative Data Movers, Inc.

How to count positions

length = 11
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1

Attribute Attribute
POS=(07,003) POS=(07,015)
byte byte
40 © 2017 Creative Data Movers, Inc.

15
CICS TS Programming 11/14/2017

BMS Example (cont.)

cont. © 2017 Creative Data Movers, Inc.

42

BMS Example (cont.)

45 © 2017 Creative Data Movers, Inc.

16
CICS TS Programming 11/14/2017

Symbolic Map Example

cont.
47 © 2017 Creative Data Movers, Inc.

Symbolic Map Example (cont.)

48
cont. © 2017 Creative Data Movers, Inc.

17
CICS TS Programming 11/14/2017

Symbolic Map Example (cont.)

cont. © 2017 Creative Data Movers, Inc.

49

Symbolic Map Example (cont.)

cont.
50 © 2017 Creative Data Movers, Inc.

18
CICS TS Programming 11/14/2017

Symbolic Map Example (cont.)

51 © 2017 Creative Data Movers, Inc.

Sample BMS JCL

52 © 2017 Creative Data Movers, Inc.

19
CICS TS Programming 11/14/2017

CICS Programming
with BMS Objects

Embed CICS commands in your COBOL

source to SEND and RECEIVE MAPs

© 2015 Creative Data Movers, Inc.

Pseudo-Conversational Programming
SEND MAP
MOVE '1' TO COMMAREA
cudt
RETURN with COMMAREA
program ends

starts again
Book code: ci02999999 RECEIVE MAP ci02999999
READ ci02999999 RECORD
prepare map
course update SEND MAP with book information
cudt ci02 MOVE '2' & book code to COMMAREA
Date: 10/01/12 RETURN with COMMAREA
Book info: CICS pgm program ends
© 2016 Creative Data Movers, Inc.

User changes book info starts again

RECEIVE MAP with updates
course update READ and REWRITE updates
cudt ci02 prepare map
Date: 11/11/16 SEND map
Book info: CICS MOVE '3' to COMMAREA
RECORD UPDATED RETURN with COMMAREA
program ends
** CLEAR to END **
starts again
RETURN without transid or commarea
User presses CLEAR key program and transaction both end

20
CICS TS Programming 11/14/2017

Using a BMS mapset in a COBOL Program

SEND MAP places Programs can

Programs can
the physical override some
alter attribute
and/or Symbolic control options
values prior to a
map data on the like FREEKB,
SEND MAP
screen ALARM, FRSET

BMS will NEVER

RECEIVE MAP retrieves data transmit LOW-VALUES
from the screen fields that have even if a MDT tag
MDT on and places it in the is on.
corresponding variables in the
COBOL program symbolic map Check length if
MDT is on.

© 2016 Creative Data Movers, Inc.

SEND MAP Format

EXEC CICS SEND

MAP ('dfhmdi name')
[MAPSET('dfhmsd name')]
[FROM(data name)]
[{MAPONLY/DATAONLY}]
[{ERASE/ERASEAUP}]
[CURSOR [(number)]]
[FREEKB]
[ALARM]
[FRSET]
[RESP (dataname)]
END-EXEC

© 2016 Creative Data Movers, Inc.

21
CICS TS Programming 11/14/2017

SEND MAP Example

EXEC CICS SEND MAP('CUSTMAP')

MAPSET('CUSTSCR')
FRSET
ERASE
RESP(WS-RESP-CD)
END-EXEC

© 2011 Creative Data Movers, Inc.

RECEIVE MAP Format

After RECEIVE MAP, WS-RESP-CD contains:

NORMAL or EOC - Successful
MAPFAIL - All input data has a length of zero
Other - Failure
EIBLK values are filled in © 2016 Creative Data Movers, Inc.

22
CICS TS Programming 11/14/2017

RECEIVE MAP – Two Ways

EXEC CICS RECEIVE MAP('CRSEMAP')

MAPSET('CUSTSCR')
RESP(WS-RESP-CD)
END-EXEC

EXEC CICS RECEIVE MAP('CRSEMAP')

MAPSET('CUSTSCR')
SET (ADDRESS OF CRSEMAPI)
RESP(WS-RESP-CD)
END-EXEC

© 2011 Creative Data Movers, Inc.

After RECEIVE MAP

L - Length F/A - I - Input

• Contains actual Field/Attribute • The actual text
length or zero • If not low- or data
values, then
user erased
input with
ERASE EOF and
turned on MDT

© 2011 Creative Data Movers, Inc.

23
CICS TS Programming 11/14/2017

Altering Attributes
Set attribute bytes in your program using the fields
in the symbolic map that end with 'A'

Values in the symbolic map sent to BMS will override

defaults originally defined for the field

Attribute byte x'00' is never sent

Attributes are bit flags

CICS comes with a copybook called DFHBMSCA

containing bit pattern values for various attributes

COPY DFHBMSCA – or code your own attributes

© 2016 Creative Data Movers, Inc.

Attribute Byte Bit Flag Configuration

Bits are numbered 01 23 45 67

Attribute byte bits 0 and 1 depend on the

values in bits 2 to 7

Bits 2 and 3 are for Protection and

Shift (numeric):
• 00 is Unprotected Alphanumeric
• 01 is Unprotected Numeric
• 10 is Protected
• 11 is Autoskip cont.
© 2016 Creative Data Movers, Inc.

24
CICS TS Programming 11/14/2017

Attribute Byte Bit Flag Configuration (cont.)

Bits 4 and 5 determine intensity:

• 00 is Normal
• 01 is also Normal
• 10 is Bright
• 11 is Dark

Bit 6 is always 0 (but not always)

Bit 7 is the Modify Data Tag (MDT):

• 0 means the field has not been changed so CICS will NOT
return data for that field
• 1 means a change was made, so CICS will return that data

© 2016 Creative Data Movers, Inc.

Manually setting Attributes

For unprot, alphanumeric, norm, MDT on
bits 2, 3 = 00 (unprot, alpha)
bits 4, 5 = 00 or 01 (normal intensity)
bit 6 = 0 (usually off)
bit 7 = 1 (MDT on)
0000 0101 = x'05'
MOVE x'05 TO fieldA
If all bits become zero, make bit 6 =1
0000 0100 = x'04
MOVE X'04 to fieldA

72 © 2017 Creative Data Movers, Inc.

25
CICS TS Programming 11/14/2017

Program Example: Modifying Attributes

IF CUSTNUMI NOT NUMERIC

MOVE DFHBMBRY TO CUSTNUMA
MOVE 'CUSTOMER NUMBER MUST BE NUMERIC '
TO ERRMSGO
GO TO SEND-MAP-RTN.
.
.
SEND-MAP-RTN.
EXEC CICS SEND MAP ('CRSEMAP')
MAPSET('CUSTSCR')
ERASE
RESP(WS-RESP-CD)
END-EXEC

© 2012 Creative Data Movers, Inc.

Cursor Positioning Techniques

IC option on the ATTRB parameter can supply the
cursor location

Programs can override IC by specifying CURSOR

on SEND

There are two forms of the CURSOR option

Symbolic cursor positioning lets us flag the

desired field by moving -1 to the length field and
specifying CURSOR

Direct cursor positioning is inadvisable. CURSOR

is followed by a number in parentheses that
represents displacement to cursor position.

© 2015 Creative Data Movers, Inc.

26
CICS TS Programming 11/14/2017

Symbolic Cursor Positioning Example

MOVE DFHBMFSE TO CUSTNUMA
IF CUSTNUMI IS NOT NUMERIC
MOVE -1 TO CUSTNUML
MOVE DFHBMBRY TO CUSTNUMA
MOVE 'CUST NUM MUST BE NUMERIC'
TO ERRMSGO
PERFORM SEND-MAP-RTN
.
SEND-MAP-RTN.
EXEC CICS SEND MAP ('CUSTMAP')
MAPSET('CUSTSCR')
ERASE
CURSOR
RESP(WS-RESP-CD)
END-EXEC
IF. . .
© 2011 Creative Data Movers, Inc.

Before SEND MAP

Field A Field O Field L

• Move new • Move data • Move -1 to
value to to output set cursor
attribute fields to this
bytes field

If error, MOVE message to ERRMSGO

© 2015 Creative Data Movers, Inc.

27
CICS TS Programming 11/14/2017

DFHMDF GRPNAME – A Complex Field

Group definition in DFHMDF
MM DFHMDF POS=(10,1),LENGTH=2,ATTRB=BRT,GRPNAME=DATE
HYPHEN1 DFHMDF POS=(10,3),LENGTH=1,GRPNAME=DATE,INITIAL='-'
DD DFHMDF POS=(10,4),LENGTH=2,GRPNAME=DATE
HYPHEN2 DFHMDF POS=(10,6),LENGTH=1,GRPNAME=DATE,INITIAL='-'
YY DFHMDF POS=(10,7),LENGTH=2,GRPNAME=DATE

Generated copybook
02 DATE.
03 FILLER PIC X(2).
03 MMA PIC X.
03 MMO PIC X(2).
03 HYPHEN1 PIC X(1).
03 DDO PIC X(2).
03 HYPHEN2 PIC X(1).
77
03 YRO PIC X(2). © 2017 Creative Data Movers, Inc.

DFHMDF OCCURS – a Repeated Field

DFHMDF
MAPFLD DFHMDF POS=(7,1),LENGTH=9,ATTRB=NORM,OCCURS=40

COPYBOOK
02 MAPFLDG OCCURS 40.
03 FILLER PIC X(2).
03 MAPFLDA PIC X.
03 MAPFLDO PIC X(9).

COBOL PROGRAM CODE

PERFORM VARYING I FROM 1 BY 1 UNTIL I > 40
MOVE INPUT-FLD(I) TO MAPFLDO (I)
IF DAYS-USED(I) < 30 MOVE DFHBMBRY to MAPFLDA(I)
END-PERFORM
.
78 © 2017 Creative Data Movers, Inc.

28
CICS TS Programming 11/14/2017

References
IBM manual: access to CICS via Browser
https://www-03.ibm.com/systems/z/os/zvse/
solutions/cicsaccess.html
BMS CICS TS v5.2
https://www.ibm.com/support/knowledgecenter/
en/SSGMCP_5.2.0/com.ibm.cics.ts.applicationpro
gramming.doc/topics/dfhp370.html
BMS CICS TS v5.3
https://www.ibm.com/support/knowledgecenter/
en/SSGMCP_5.3.0/com.ibm.cics.ts.applicationpro
gramming.doc/topics/dfhp373.html

86 © 2017 Creative Data Movers, Inc.

Questions and Answers

Thank You
Mary Abdill

Creative Data Movers, Inc.

www.CreativeDataMovers.com
[email protected]

87 © 2017 Creative Data Movers, Inc.

29