Desk Refer
i
PROGRAMMER’S REFERENCE
murach’s
CICS
desk
reference
Raul Menendez
Doug Lowe
Unit 10
(Excerpt)
Mike Murach & Associates
Toll-free: 1-800-221-5528 • Fax: 559-440-0963
murachbooks@murach.com • www.murach.com
Copyright © 2004 Mike Murach & Associates. All rights reserved.
Unit 10
Creating HTML documents
from BMS mapsets
With IBM’s 3270 Bridge facility, all you have to do to web-enable your CICS
applications is convert your BMS mapsets to HTML templates that format
HTML pages instead of 3270 displays. Then, all of the CICS application code
stays the same, but the screen display is suitable for a web browser. Although
there are other ways to web-enable CICS applications that provide more
flexibility, this approach is the easiest. So this unit from Murach’s CICS Desk
Reference shows you how to create HTML templates from BMS source code,
and how to enhance the HTML output in some basic ways.
By the way, the main unit in the Desk Reference (Unit 8) gives you
syntax, exceptional conditions, and coding advice and examples for 121
CICS commands, including the web commands for handling HTML
documents. To see the complete table of contents, please go to
www.murach.com.
How to prepare an HTML template ........................................ 504
The conversion process .................................................................................... 504
JCL that invokes the DFHMAPT procedure .................................................... 504
The DFHMAPT procedure .............................................................................. 505
Generated HTML output ......................................................... 506
Standard output ................................................................................................ 506
Customized output ........................................................................................... 507
How to create a customizing macro definition with DFHMDX ...................... 508
The DFHMDX macro ............................................................... 509
The DFHWBOUT macro .......................................................... 512
504
Unit 10 How to prepare an HTML template
How to prepare an HTML template
Beginning with CICS TS 1.3, IBM added a JCL cataloged procedure named
DFHMAPT that allows you to generate an HTML template from BMS macro
source code. You use this procedure instead of DFHMAPS to assemble your
mapset, as shown in figure 10-1. Figure 10-2 shows you how to invoke the proce-
dure, and figure 10-3 shows you the procedure itself (the beginning of the new
assembly step is shaded).
The conversion process
BMS mapset
source
Assembler
(DFHMAPT)
Physical map
Symbolic map
HTML template
•
If your BMS mapset specifies TYPE=&SYSPARM in the DFHMSD macro, the
DFHMAPT procedure will produce an HTML template as well as the physical
and symbolic map. Otherwise, you need to code TYPE=TEMPLATE to pro-
duce the HTML template.
Figure 10-1
JCL that invokes the DFHMAPT procedure
//MM01HTML JOB 36512,'R.MENENDEZ',NOTIFY=MM01
//JOBPROC JCLLIB ORDER=CICSTS13.CICS.SDFHPROC
//MAPASM EXEC DFHMAPT,
// MAPLIB='MM01.CICS.LOADLIB', TARGET LOADLIB FOR MAP
// DSCTLIB='MM01.CICS.COPYLIB', TARGET COPYLIB FOR DSECT
// TEMPLIB='MM01.CICS.TEMPLIB', TARGET FOR TEMPLATE
// MAPNAME=INQSET1 MAPSET NAME
//COPY.SYSUT1 DD DSN=MM01.CICS.SOURCE(INQSET1),DISP=SHR MAPSET SOURCE
/*
•
Most of the JCL is the same as for invoking DFHMAPS. But besides specify-
ing DFHMAPT in the EXEC statement, you may need to add a TEMPLIB
parameter to identify the library that will contain the HTML template. You may
also want to include a JCLLIB statement to specify the library where
DFHMAPT is stored. And if your mapset includes a macro for customizing the
HTML output, you may need to add a PARM parameter for the ASMTEMPL
step (you’ll see how to do this later in this unit).
Figure 10-2
Unit 10 How to prepare an HTML template
505
The DFHMAPT procedure
//DFHMAPT PROC INDEX='CICSTS13.CICS', FOR SDFHMAC
// MAPLIB='CICSTS13.CICS.SDFHLOAD', TARGET FOR MAP
// DSCTLIB='CICSTS13.CICS.SDFHMAC', TARGET FOR DSECT
// TEMPLIB='CICSTS13.CICS.SDFHHTML', TARGET FOR TEMPLATES
// MAPNAME=, NAME OF MAPSET - REQUIRED
// A=, A=A FOR ALIGNED MAP
// RMODE=24, 24/ANY
// ASMBLR=ASMA90, ASSEMBLER PROGRAM NAME
// REG=2048K, REGION FOR ASSEMBLY
// OUTC=A, PRINT SYSOUT CLASS
// WORK=SYSDA WORK FILE UNIT
//COPY EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=&OUTC
//SYSUT2 DD DSN=&&TEMPM,UNIT=&WORK,DISP=(,PASS),
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=400),
// SPACE=(400,(50,50))
//SYSIN DD DUMMY
//* SYSUT1 DD * NEEDED FOR THE MAP SOURCE
//ASMMAP EXEC PGM=&ASMBLR,REGION=®,
// PARM='SYSPARM(&A.MAP),DECK,NOOBJECT'
//SYSPRINT DD SYSOUT=&OUTC
//SYSLIB DD DSN=&INDEX..SDFHMAC,DISP=SHR
// DD DSN=SYS1.MACLIB,DISP=SHR
//SYSUT1 DD UNIT=&WORK,SPACE=(CYL,(5,5))
//SYSUT2 DD UNIT=&WORK,SPACE=(CYL,(5,5))
//SYSUT3 DD UNIT=&WORK,SPACE=(CYL,(5,5))
//SYSPUNCH DD DSN=&&MAP,DISP=(,PASS),UNIT=&WORK,
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=400),
// SPACE=(400,(50,50))
//SYSIN DD DSN=&&TEMPM,DISP=(OLD,PASS)
//LINKMAP EXEC PGM=IEWL,PARM='LIST,LET,XREF,RMODE(&RMODE)'
//SYSPRINT DD SYSOUT=&OUTC
//SYSLMOD DD DSN=&MAPLIB(&MAPNAME),DISP=SHR
//SYSUT1 DD UNIT=&WORK,SPACE=(1024,(20,20))
//SYSLIN DD DSN=&&MAP,DISP=(OLD,DELETE)
//ASMDSECT EXEC PGM=&ASMBLR,REGION=®,
// PARM='SYSPARM(&A.DSECT),DECK,NOOBJECT'
//SYSPRINT DD SYSOUT=&OUTC
//SYSLIB DD DSN=&INDEX..SDFHMAC,DISP=SHR
// DD DSN=SYS1.MACLIB,DISP=SHR
//SYSUT1 DD UNIT=&WORK,SPACE=(CYL,(5,5))
//SYSUT2 DD UNIT=&WORK,SPACE=(CYL,(5,5))
//SYSUT3 DD UNIT=&WORK,SPACE=(CYL,(5,5))
//SYSPUNCH DD DSN=&DSCTLIB(&MAPNAME),DISP=OLD
//SYSIN DD DSN=&&TEMPM,DISP=(OLD,PASS)
//ASMTEMPL EXEC PGM=&ASMBLR,REGION=®,
// PARM='SYSPARM(TEMPLATE),DECK,NOOBJECT'
//SYSPRINT DD SYSOUT=&OUTC
//SYSLIB DD DSN=&INDEX..SDFHMAC,DISP=SHR
// DD DSN=SYS1.MACLIB,DISP=SHR
//SYSUT1 DD UNIT=&WORK,SPACE=(CYL,(5,5))
//SYSUT2 DD UNIT=&WORK,SPACE=(CYL,(5,5))
//SYSUT3 DD UNIT=&WORK,SPACE=(CYL,(5,5))
//SYSPUNCH DD UNIT=&WORK,SPACE=(CYL,(5,5)),DISP=(,PASS)
//SYSIN DD DSN=&&TEMPM,DISP=(OLD,DELETE)
//UPDTEMPL EXEC PGM=IEBUPDTE,REGION=®,PARM=NEW
//SYSPRINT DD SYSOUT=&OUTC
//SYSIN DD DSN=*.ASMTEMPL.SYSPUNCH,DISP=(OLD,DELETE)
//SYSUT2 DD DSN=&TEMPLIB,DISP=SHR
Figure 10-3
506
Unit 10 Generated HTML output
Generated HTML output
Although generating an HTML template from a BMS mapset requires no
additional BMS coding, chances are, you won’t be happy with the result. That’s
because DFHMAPT simply translates the BMS macro code “as is,” resulting in a
basic screen that is not too appealing. Fortunately, IBM provides additional BMS
macros that you can use to enhance the appearance of the HTML page.
Standard output
Figure 10-4 shows an example of the HTML template that’s generated when
you run DFHMAPT without adding any code to the BMS mapset. The HTML
template contains all of the fields from the BMS mapset and functions in a manner
similar to its 3270-display counterpart. In general, a standard generation will
produce the following:
•
Labels and fields from the map.
•
Buttons for the Enter and Clear keys, PA1, PA2, and PA3 keys, function keys
PF1 to PF24, and the Reset key.
•
Additional hidden variables used to manage the HTML page.
•
A JavaScript function called dfhsetcursor that sets the cursor position to the
field whose name is the value in the DFH_CURSOR hidden variable.
Generated HTML output without any customization
Figure 10-4
Unit 10 Generated HTML output
507
Customized output
Figure 10-5 shows the HTML template from figure 10-4 with some
customization. There are two additional macro commands you can add to your
BMS source code to customize an HTML template. If all you want to do is add text
to the HTML template that will not be seen on the 3270 display, you simply code a
DFHWBOUT macro at the place in the mapset where you want the text to appear.
However, if you want to add options that affect the look and feel of the HTML
display, you use the DFHMDX macro. And to do that, you have to write your own
macro definition, as summarized in the next topic. Among other things, the param-
eters of the DFHMDX macro allow you to:
•
Modify the BMS colors for the text.
•
Change the background color or specify a special background.
•
Provide an HTML title for the HTML page.
•
Suppress the generation of buttons for attention keys the program doesn’t use.
•
Change the appearance of the button keys, including the text associated with
them.
•
Include a masthead graphic for the HTML page.
Generated HTML output customized with the DFHMDX macro
Note: You can customize the HTML template manually by editing the HTML code,
but be careful! The order in which the fields appear on the HTML page must be
kept. Otherwise, the 3270 Bridge facility won’t be able to process the page.
Figure 10-5
508
Unit 10 Generated HTML output
How to create a customizing macro definition with
DFHMDX
To customize an HTML template using the DFHMDX macro, you have to
supply a complete macro definition that is invoked by the CICS-supplied assembler
macros for BMS mapsets. This customizing macro definition must contain the
following elements:
1. A MACRO statement to begin the definition.
2. The name of the macro. CICS assumes a default name of DFHMSX, so if you
use a different name, you need to include a PARM parameter for the template
assembly step in the JCL that invokes the DFHMAPT procedure, like this:
PARM.ASMTEMPL='SYSPARM(TEMPLATE,macro-name),DECK,NOOBJECT'
3. Any number of DFHMDX macros.
4. A MEND statement to end the definition.
Figure 10-6 shows the customizing macro definition for the HTML page in
figure 10-5. Like standard BMS macro definitions, a continuation character must be
placed in column 72 to continue a macro on more than one line.
The definition of a customizing macro named DFHMSX
MACRO
DFHMSX
DFHMDX MAPSET=*, X
MAP=INQMAP1, X
ENTER='Enter', X
RESET=NO, X
CLEAR='Clear', X
PF3='Exit',PF12='Cancel', X
TITLE='Customer Inquiry', X
BGCOLOR=WHITE, X
SUPPRESS=((1,*),(24,*)), X
MASTHEAD=www.murach.com/images/murachlogo.gif
MEND
Figure 10-6
Unit 10 The DFHMDX macro
509
The DFHMDX macro
Function
The DFHMDX macro lets you customize the HTML template generated from the
BMS macro code. With the exception of the MAPSET and MAP parameters, all of
the parameters are optional.
Syntax
DFHMDX MAPSET= { name | * }
,MAP= { name | * }
[, MODULE=name ]
[, DOCTYPE=doctype ]
[, TITLE='title-text' ]
[, MASTHEAD= { url | url,'alternate-text' } ]
[, BACKGROUND=url ]
[, BGCOLOR=color ]
[, TEXT=color ]
[, LINK=color ]
[, VLINK=color ]
[, ALINK=color ]
[, bmscolor=color ]
[, key=button ]
[, RESET= { YES | NO | 'text' } ]
[, SUPPRESS= ( (line,column...)[,...] [,HEAD] [,FOOT] ) ]
[, ONLOAD='text' ]
[, ONUNLOAD='text' ]
[, PROPFONT= { NO | YES } ]
[, CODEPAGE(data-value) ]
Parameters
MAPSET
Specifies the name of the mapset that contains the map the other
parameters refer to. If you specify MAPSET=*, any parameters used
become the default for subsequent mapsets within the same source file
unless another DFHMDX macro is encountered.
MAP
Specifies the name of the map that the other parameters refer to. If you
specify MAP=*, any parameters used become the default for subsequent
maps within the same mapset unless another DFHMDX macro is
encountered.
MODULE
Specifies the name of the link-edited load module.
DOCTYPE
Specifies the DTD (Document Type Definition) public identifier part of
the <!doctype> tag that will appear in the HTML page.
TITLE
Specifies the value of the HTML title used in the first <h1> tag of the
HTML page.
MASTHEAD
Specifies the URL location of a masthead graphic that’s inserted into the
HTML page before the first <h1> tag. If you specify a value for alternate-
text, that text is inserted instead if the graphic can’t be found.
510
Unit 10 The DFHMDX macro
BACKGROUND
Specifies the URL location of a graphic file that’s used as a back-
ground for the HTML page.
BGCOLOR
Specifies the color of the HTML page background.
TEXT
Specifies the color for normal text.
LINK
Specifies the color for unvisited hypertext links on the HTML page.
VLINK
Specifies the color for visited hypertext links on the HTML page.
ALINK
Specifies the color for activated hypertext links on the HTML page.
bmscolor
Specifies a substitute color that replaces the bmscolor on the BMS
map. For example:
BLUE=green
Valid bmscolors are BLUE, GREEN, NEUTRAL, PINK, RED,
TURQUOISE, and YELLOW.
key
Specifies the text or image that’s assigned to the simulated button for
the corresponding 3270 attention key. For example:
PF1='HELP'
Valid key names are PF1-PF24, PA1-PA3, CLEAR, ENTER, and
PEN.
RESET
Specifying YES allows the HTML reset function to be supported, so
a Reset button is placed on the HTML page. You can also specify
your own text to replace the default legend for the button.
SUPPRESS
Allows you to suppress map fields that you don’t want to appear on
the HTML page. The basic line,column format is the same as that for
the POS option on the DFHMDF macro. You can specify an entire
line by coding an * for the column value. You can also code multiple
line,column pairs by enclosing each pair in parentheses, and separat-
ing them with commas. The HEAD and FOOT keywords let you
suppress the heading and footer information for the HTML page.
ONLOAD
Specifies the JavaScript text that replaces the standard onLoad
exception handler for the HTML page.
ONUNLOAD
Specifies the JavaScript text that’s used as the onUnload exception
handler for the HTML page.
PROPFONT
Specifying YES causes the text to be displayed in a proportional font
where consecutive spaces are reduced to just a single space.
CODEPAGE
Specifies the IBM code page number specified in either the
HOSTCODEPAGE option of a CICS DOCUMENT command or the
SRVERCP option of the DFHCNV macro selected by the analyzer
program.
Unit 10 The DFHMDX macro
511
Coding example (a single DFHMDX macro)
In this example, lines 1 and 24 of the maps within the INQSET2 mapset will not be
displayed on the HTML page. Typically, you’ll do this to remove any text that may
be specific to the 3270 display.
DFHMDX MAPSET=INQSET2,MAP=*,SUPPRESS=((1,*),(24,*))
Coding example (multiple DFHMDX macros)
This example shows how two DFHMDX macros are applied to a map named
INQMAP2. The first invocation of DFHMDX sets the default values that will be
applied to all of the maps in this and subsequent mapsets. In this case, the PF3
button on all subsequent maps will display “Exit” and a Reset button won’t be
included in any of the maps. The second invocation of DFXMDX applies only to
INQMAP2. It assigns name values to additional attention keys found only on that
map, assigns an H1 title and a masthead company logo to be displayed at the top of
the HTML page, and sets the page background color to neutral (white).
DFHMDX MAPSET=*, X
MAP=*, X
PF3='Exit', X
RESET=NO
DFHMDX MAPSET=*, X
MAP=INQMAP2, X
ENTER='Enter', X
PF5='First',PF6='Last', X
PF7='Prev',PF8='Next', X
PF12='Cancel', X
TITLE='Customer Inquiry', X
MASTHEAD=www.murach.com/images/murachlogo.gif, X
BGCOLOR=NEUTRAL
512
Unit 10 The DFHWBOUT macro
The DFHWBOUT macro
Function
The DFHWBOUT macro lets you add text to an HTML page that does not appear
on a 3270 display. If the macro is used before the first occurrence of a DFHMDF
macro in a map, the text is placed in the <head> section of the HTML page.
Otherwise, the text is placed in the body of the HTML page immediately following
any text generated by a preceding DFHMDF macro.
Syntax
DFHWBOUT 'text'
[, SOSI= { YES | NO } ]
Parameters
text
The text that’s inserted into the HTML page.
SOSI
Specify YES if the text contains DBCS characters.
Coding example
In this example, a text message is inserted after a constant field. As you can see,
this is a message that’s appropriate for an HTML display, but not for a 3270
display.
DFHMDF POS=(1,20), X
LENGTH=16, X
ATTRB=(NORM,PROT), X
COLOR=BLUE, X
INITIAL='Customer Inquiry'
DFHWBOUT 'Do not use the browser Back button'
