DTL

Interactive System Productivity Facility (ISPF)
ISPF Panels – Dialog Tag

Language (DTL)
SHARE 112
Session 2627
Peter Van Dyke

IBM Australia
SHARE 112, Winter 2009
pvandyke@au1.ibm.com
© 2009 IBM Corporation
Interactive Program Development Facility (ISPF)
Sessions 2600 2602 2603 2614 2627 2628 2632 2633 Room 16A
SHARE 112 Sessions 2625 2626 Room 17A
Austin, Texas Sessions 2605 2606 8301 8302 8303 Room 18C
Session Timetable Sessions 2612 2613 Room 19A
Attendance counts towards ISPF certification

Attendance counts towards ISPF/REXX certification
8:00 9:30 11:00 13:30 15:00 16:30 18:00
Sunday 2612 2613

10tth August ISPF Users Boot Camp 1 of ISPF Users Boot Camp 2
2 of 2
Monday 2600
11tth August ISPF Project Opening and
Keynote Topic
Tuesday 8301 8302 8303 2625 2626

12th August REXX Hands-on REXX Hands-on REXX Hands-on ISPF Hidden Treasures ISPF Hidden Treasures
Lab 1 of 3 Lab 2 of 3 Lab 3 of 3 Part 1 of 2 Part 2 of 2
Wednesday 2602 2603 2604 2627 2628

13th August ISPF Dialog Developer’s ISPF Dialog Developer’s ISPF Panels - Advanced ISPF Panels – Dialog
ISPF Dialog Developer’s
Boot Camp 1 of 3 Boot Camp 2 of 3 Boot Camp 3 of 3 Tag Language (DTL)
Thursday 2605 2606 2632 2633

14th August ISPF Hands-on Lab 1 of 2 ISPF Hands-on Lab 2 of 2 ISPF Productivity Tool ISPF Productivity Tool
for z/OS – for z/OS –
Live Demos Live Demos
Part 1 of 2 Part 2 of 2
Friday
2614
15th August
ISPF Editor –Beyond the
Basics
2 ISPF Panels - Advanced | Session 2627 © 2009 IBM Corporation

Agenda
Introduction to DTL
Basic Syntax
Some Examples
Basic Text
Data Fields
Selection Fields
Data columns
Help
Entities
Regions
ISPDTLC - Conversion Utility
References
This presentation provides a a broad overview of the Dialog Tag Language (DTL)
by covering the following topics:
•An introduction to DTL
•The basic syntax, and...
•Describe a couple of examples - a help panel, and an application panel
•How to define basic text on panels
•How to create data fields so users can interact with a panel
•How to define selection fields for single choice, multiple choice and menu
selections
•How to create data columns, including list fields used for Table displays
•A brief look at Help panels
•Defining and using ENTITIES
•How to divide a panel into Regions for easier coding
•The DTL Conversion Utility that is shipped with ISPF
•References and samples
What is DTL?
DTL stands for Dialog Tag Language
A markup language based on ISO SGML

Other examples include:
BookManager, BookMaster, DCF, HTML
You use DTL to define:

Panels
Messages
Command tables
Keylists
A Conversion Utility, ISPDTLC, is shipped with ISPF
DTL is the acronym for Dialog Tag Language.

It is a markup language based on ISO SGML -
•ISO - International Standards Organization
•SGML - Standard Generalized Markup Language
Other examples of SGML include Bookmanager, Bookmaster, DCF, and HTML
(although with the fancy GUI interfaces available these days most people don't code
using native HTML anymore).
In ISPF you can use DTL to define:
•Panels
•Messages
•Command Tables
•Keylists
ISPF ships the conversion utility ISPDTLC to convert the DTL into standard ISPF
panels, messages, command tables and keylist.
•ISPDTLC is a REXX program
•in z/OS 1.10 it comprises 42,500 lines of code
Why Use DTL?
Allows for simplified creation of CUA compliant dialogs
Flexible to use
Revisions are fast and easy
Provides consistency
Allows for common imbed files at compile-time

Action bars
Common logic
Variable definitions
Once you get started, it's easy to use
•DTL allows for simple creation of CUA (Common User Access) compliant dialogs
•CUA guidelines define a user interface in terms of common elements, such
as the way information appears on a screen, and interaction techniques, such
as the way users respond to what appears on a screen
•DTL enforces some formatting rules defined by the CUA so you do not
have to be familiar with all of the CUA formatting rules.
•DTL lends flexibility to application development. Revisions are fast and easy
because there is no need to tediously line up text and fields. This gives you greater
control over application development and updates.
•DTL provides consistency when many programmers are working on the same
application, or when programmers who are new to your company must update
existing applications. Since each programmer is using the same tags, only minor
adjustments may be needed to achieve complete uniformity. DTL provides tags
which assign standard attribute definitions for items such as the panel title and
command line.
•DTL supports the use of common imbed files which are included in the panel
definition at conversion time. An imbed file can contain definitions and code that is
common across multiple panels, such as:
•action bars
•common panel logic
•variable definitions
•and, once you get familiar with DTL, it IS easy to use (although it’s a good idea to
keep the DTL reference guide handy)
What Can DTL Do?

Automatic generation of some constructs
Mnemonics for action bars and pull-down choices
Check boxes
Automatic space filling (no more counting spaces!)

Indentation (primarily in help and tutorial panels)
Line spacing (top and bottom instructions)
Paragraph spacing and word wrapping
Include processing (imbed files at conversion time)
Quick changes from one construct to another

Radio buttons
List boxes
Drop-down lists
Combo boxes
Simple lists
Ordered lists
Unordered lists
•DTL simplifies coding by its automatic generation of some constructs, for

example:
•Mnemonic for action bars and pull down choices
•Check boxes
•Field attributes
•DTL will automatically allocate space for the fields - no need to count spaces
particularly for input fields. Tasks such as coding indentation, line spacing,
paragraph spacing and word wrapping are a thing of the past.
•The DTL conversion utility supports the processing of imbed files.
•DTL makes it easy to change constructs from one type to another. DTL will handle
the reformatting.
Do I Have to Use it Everywhere?

Use DTL only where you want to
You may only want to define keylists or command tables
You may only want to define new panels
DTL is merely an alternate way of defining panels, messages, and command tables
It is the best and most foolproof way to define keylists for an application
•Do you have to use DTL everywhere?

•NO - only use DTL where you want to
•you may choose to use it just to define keylist or command tables, or...
•you may choose to use it just to define panels
•DTL provides an alternate way to define ISPF panels, messages and command
tables.
•DTL provides the best way to define the ISPF tables that define keylists used by an
application.
Basic DTL Tag Syntax Notes

DTL is not a WYSIWYG language
DTL is a freeform language

Most tags are not dependent on spacing
DTL is not case sensitive

exception being the entity name on the <!ENTITY> declaration
A tag consists of the tag name inside delimiters (< >):

<tag-name>
Many tags are sets of a "start-tag“

<panel>
and an "end-tag“
</panel>
•DTL is NOT a WYSIWYG (What You See Is What You Get) Language.
•DTL is a free form language using tags and ...
•most tags are not dependant on spacing
•DTL is not Case SeNsItIvE
•As usual there has to be an exception. Entity names specified with the
<!ENTITY> declaration are case sensitive.
•A TAG consists of the tag name inside the delimiters Less Than (<) and Greater
Than (>) characters.
•Many tag definitions are have a start tag and end tag.
•ALL end tags have the (forward slash (/) character before the tag name
Basic DTL Tag Syntax …

Text after the > (closing delimiter) defines text to display
Field prompts
Titles
Descriptions
<PANEL NAME=EXAMPLE1>Panel Title
DTL will automatically word-wrap text with some exceptions

Panel titles are truncated if larger than the panel width
Action bars and pull-down descriptions truncated at 64 bytes
Messages truncated after 512 bytes
Some tags will not wrap
<LINES>
<XMP>
<FIG>
•Text after the closing delimiter > character defines the text to display. This
includes items such as field prompts, titles, and descriptions.
•In most cases, DTL automatically word-wraps text. Some exceptions are:
•Panel titles are truncated if larger than the panel width
•Action bar and pull-down descriptions are truncated at 64 bytes
•Long Messages are truncated if greater than 512 bytes, and ...
•Short message are truncated if greater than 24 bytes
•Text for tags such as LINES, XMP and FIG will not wrap
Basic DTL Tag Syntax …

Tags can have attributes (e.g. NAME=xxxx)
Attribute values must follow the '=' sign
The value must be in single quotes if it contains special characters or spaces
<tag-name attr1=value1 attr2>
Some end-tags are optional

Suggestion: Code all end-tags
Easier to not have to remember which are required
You can indent to show nesting, and the end-tag marks the end of a nesting
level
Many attributes have defaults that will be used if not coded

Suggestion: Code the default
Easier to read and understand (but it's a little more typing)
•Some DTL tags have attributes

•Not all attributes require a value. If a value is required the attribute name
precedes the EQUAL (=) sign and the attribute value must follow the
EQUAL sign.
•The attribute value MUST be in single quotes if it contains special
character or spaces.
•Some end tags are optional, although it is recommend that you code the end tags
•You don not have to remember which are optional and which are required,
and ...
•you can indent to show nesting and the end tag marks the end of a nesting
level
•Many tag attributes have default values that will be used if not coded
•Again, it is recommended to code the defaults
•makes it easier for others to read and understand the code
Example - Simple Help Panel

<!doctype dm system()>
<help name=help1 width=50 depth=18 keylist=isrhlp2 applid=isr>
Help Panel Title

<info>
<p>This is a simple help panel. It should show how to use:
</p>
<ul>
<li>Help tag
<li>Information area tag
<ol compact>
<li>Paragraph tag
<li>Unordered list tag
<li>Ordered list tag
<li>List item tag
</ol>
</ul>
</info>
</help>
•Let’s look at an example of a simple help panel.

•ALL DTL source files (members) start with the <!doctype> tag to define the
document type
•DM defines the document type as Dialog Manager (the source file contains
tags used to define dialog elements for a Dialog Manager application)
•SYSTEM indicates the syntax rules for defining elements are contained in
an external file
•The <help> tag defines a help panel
•name defines the name of the panel as help1. The generated panel
language which will be stored as panel member name help1.
•width=50 specifies the width of the help panel (50 is default)
•depth=18 defines the depth of the panel (10 is default)
•keylist=isrhlp2 defines the keylist that will be used with the panel.
•ISRHLP2 is the standard HELP keylist that is shipped with ISPF.
•applid=isr identifies ISR as the application ID used to locate the
keylist table for the panel
•The keylist application ID can also be specified during DTL
conversion but if specified here will override the value specified on
the conversion utility.
•Add clarity to the code and prevent dialog errors by specifying it in
the DTL source
•'Help Panel Title' is the panel title.
•NOTE: the leading spaces are ignored, so the panel title can be indented for
clarity
•Comments start with the character string 
Help Panel Display

Paragraph text is wrapped
Unordered list is double-spaced
Ordered list is single-spaced due to compact attribute on <ol> tag
•Shown here is a display of the panel HELP1 generated from the DTL on the
previous slide.
•The DTL conversion utility has:
•Formatted and wrapped the paragraph text
•Formatted the unordered list double-spaced (a blank line between each list
item)
•Formatted the ordered list single-spaced (no lines between each list item)
Simple Help Panel Example

<!doctype> tag
Required in each DTL file
Defines the "document type" to SGML processors
<!doctype dm system>
All types of lists are coded in the same manner

Ordered lists display with numbers/letters (1., a., 1), a))
Unordered lists display with bullets (o, -, --)
Simple lists display with no bullets or numbers
Lists can be nested within other lists
DTL handles all of the indenting
To add a command line to this help panel

Add a <cmdarea> tag before the </help> tag
Reconvert using ISPDTLC to update the generated panel
Revisiting some of the elements we have seen with our simple Help panel
•The <!doctype> tag is a required tag, that defines the document type to SGML
processor.
•All list types are coded in the same manner (which makes it easy to change from/to
another)
•Ordered list display with numbers for each list item
•Unordered list display with bullets for each list item, and ...
•Simple lists display without bullets or numbers for the list items
•Lists can be nested, with DTL handling the indentation of the nested lists
•A command line could be added to the help panel by specifying a <cmdarea> tag
before the </help> tag and converting the panel again using ISPDTLC. We will see
an example of this shortly.
Application Panel Coding

Start out with an application panel
Action bar with two choices (File and Help)
Panel Title
Use a Keylist that is shipped with ISPF
Top Instruction to the user
Single-choice selection field
When displayed in GUI mode, show as a radio button group
Multi-choice selection field
When displayed in GUI mode, show as check boxes
Command Line
•Now we will look at coding an application panel using DTL. This is a relatively
simple example but it will demonstrate many of the basic DTL tags.
•The panel will require the following elements:
•an Action Bar with 2 choices - FILE and HELP
•Panel Title
•Use an ISPF supplied keylist
•Instructions for the user at the top of the panel
•A single choice selection field which will display as a radio button group in
GUI mode, and ...
•A multi-choice selection field which will display as check boxes in GUI
mode
•AND a command line
Application Panel Coding ...
This slide shows the display required from the panel generated from our DTL code.
The display includes:
•an Action Bar with 2 choices - FILE and HELP
•panel title
•instructions for the user at the top of the panel
•a single choice selection field
•a multi-choice selection field, and ...
•a command line
The File action bar choice has 4 pull-down choices:

1 - Add Entry
2 - Delete Entry
3 - Update Entry
4 - Exit
The Help action bar choice has 3 pull-down choices:

1 - General help
2 - Keys Help
3 - About

<!doctype dm system()>



<panel name=panel1 keylist=isrnsab applid=isr depth=16>

Dream on Vacation Guide







<ab>

<abc>File
The following slides show the DTL source code used to generate the panel
displayed on the previous slides.
•The required <!doctype> tag is first tag specified
•The <panel> tag defines the panel name, the keylist, applid, depth, and the panel
title
•The name attribute on the <panel> tag is used to give the panel the name
"panel1"
•The keylist attribute spcifies ISPF supplied keylist ISRNSAB will be used
for this panel (NSAB is an acronym for “No scrollable area with Action
Bar”)
•ISPF ships a number of keylists; e.g. -
•ISRNAB - No scrollable area with No Action Bar
•ISRSAB - Scrollable area with Action Bar
•The <ab> tag start the definition of the action bar
•The <abc> tag shown defines the File action bar choice


<pdc>Add Entry
<action run=add>
</pdc>
<pdc>Delete Entry
<action run=delete>
</pdc>
<pdc>Update Entry <action run=update>
<pdc>Exit <action run=exit>

</abc>

<abc>Help
<pdc>General Help
<action run=isptutor parm=h1>
<pdc>Keys Help <action run=keyshelp>
<pdc>About <action run=isptutor parm=h2>
</abc>
•The <pdc> tags shown at the top of the slide define the 4 pull-down choices for
the File action bar choice
•The <action> tag defines the action to be performed when the associated
pull-down choice is selected
•RUN= ADD, DELETE, and UPDATE are actions that the application
program must handle. ADD, DELETE, and UPDATE are either
application or system commands.
•RUN=EXIT will be handled by ISPF because EXIT is an ISPF command.
ISPF will generate a return code of 8 from the panel display.
•The </abc> tag specifies the end of the definition of the File action bar choice
•Another <abc> tag starts the definition of the Help action bar choice
•The <action> tags specify running the ISPF supplied program
ISPTUTOR and the ISPF command KEYSHELP.
•KEYSHELP displays the help panel for the current keylist (if
defined)
•ISPTUTOR runs the ISPF tutorial application. The parameters H1
and H2 are passed to ISPTUTOR and identify the name of the first
help panel to be displayed in the tutorial. These help panels must be
provided as part of the application.


</ab>

<topinst>Choose one of the locations and your preferred modes of travel.

</topinst>



<area>




<region dir=horiz>
•The </ab> tag marks the end of the action bar definition
•The <topinst> tag defines the instructions to be placed at the top of the panel
•The COMPACT keyword could be used to prevent a blank line being
displayed after the top instructions
•The <area> tag defines the portion of the panel which is will contain information
such as fields and their descriptions
•Adding the depth attribute to the <area> tag will cause the area to be
scrollable. (Remember to change the keylist to one that supprts scrolling,
such as ISRSAB - Scrollable with Action Bar)
•Some tags are required to be within an area
•The <region> tag is used to define the characteristics of a panel section
including the direction in which fields on an application panel are arranged. This
example uses the dir=horiz attribute to define a horizontal region.
•By default DTL write objects vertically down the screen.







<selfld type=single name=loc selwidth=25 pmtwidth=25 entwidth=1

listtype=radio>Exotic Location




<choice>Germany
<choice>Hawaii
<choice>Norway
<choice>Sweden
<choice>Finland

</selfld>
•The first object with the region is a single choice selection field. The <SELFLD>
tag is used to create the selection field.
•The type=single attribute and an entry width (entwidth) of 1 is
specified because only one location is required to be selected.
•The name attribute specifies the ISPF variable to contain the user’s
selection. It will contain the number of the selection.
•The selwidth attribute sets the width of the text for the subsequent
selection choices
•The pmtwidth attribute sets the width of the prompt text ("Exotic
Location"), and ...
•The listtype=radio setting causes a radio button to be displayed in
GUI mode
•The <choice> tags define the text for the 5 location choices
•The </selfld> tag marks to end of the selection list definition







<selfld type=multi selwidth=25 pmtwidth=25 chkbox=yes>Travel Mode




<choice name=ship>Ship
<choice name=plane>Plane
<choice name=ferry>Ferry Boat
<choice name=car>Drive Yourself

</selfld>
•The second object is a multi-choice selection field, which allows the user to select
more than one choice. The <SELFLD> tag with type=multi specified is used to
define the multi-choice selection field.
•The chkbox=yes setting causes check boxes to be displayed in GUI mode
•The <choice> tags define the text for each of the 4 Travel Mode choices. The
name attribute specifies the ISPF variable that will contain a forward slash (/)
character is the associated choice is selected.
•The </selfld> tag marks to end of the selection list definition



</region>
</area>


<cmdarea>Enter any Command Here

</panel>

•The </region> tag marks the end the region

•The </area> tag marks the end of the area
•The <cmdarea> tag is used to define the command area. The text after the '>'
delimiter defines the command prompt text - 'Enter any command here'
•The </panel> tag marks the end of the panel.
Basic Text
The following tags can be used in information regions and help panels to control the
text layout:
<p> paragraph
<h1>, <h2>, <h3>, and <h4> headings
<lines> and </lines> to stop reflowing
<xmp> and </xmp> are like <lines>, but indents two spaces
<fig> and </fig> are like <lines>, but by default adds the frame=rule
attribute to the tag.
You can also specify a <figcap> tag within a <fig> pair.
<sl> and </sl> - simple lists,
<ol> and </ol> - ordered lists, and
<ul> and </ul> - unordered lists, with
<li> list items and <lp> list paragraphs
<dl> and </dl> - definition lists, with
<dthd> data term header, and <ddhd> data definition header
<dt> data terms, and <dd> data definitions
<parml> and </parml> - parameter lists, with
<pt> parameter terms and <pd> parameter definitions
•There are many tags that can be used to define different types of text on panels
•Each have there own attributes, for instance:
•The <p> start a new paragraph and by default leaves a blank line
•There are tags to define:
•Headings. For example the <H1> tag identifies a main topic and the
heading text is centered (for other heading tags the text is left-
justified).
•Lines. The text between the <lines> and </lines> is
unformatted (i.e. is displayed on the panel as specified in the DTL
source).
•Examples. Similar to lines but text between the <xmp> and
</xmp> tags is indented 2 spaces from current left margin.
•Figures. Similar to lines but the default frame=rule setting
causes dashed lines to appear above and below the text between the
<fig> and </fig> tags.
•DTL also supports an assortment of tags for specifying different types of lists
More about Basic Text

Alerts
<note> tag to generate notes. The 'Note:' prefix is added to the paragraph of text.
<note> is used when only one paragraph is needed.
<nt> and </nt> tags are used when the <p> tag is needed to specify multiple
paragraphs in the note. The 'Note:' prefix is added here too.
<warning> and </warning> tags adds 'Warning:' to the front of the paragraph.
The <warning> tag must be preceded by either a <p> or a <lp> tag.
<caution> and </caution> tags adds 'CAUTION:' to the line preceding the
paragraph.
The <caution> tag must be preceded by either a <p> or a <lp> tag.
Emphasized text
<hp> and </hp> highlight phrase tags bracket text to be emphasized
Reference phrases (hypertext links)
<rp help=panel-name> and </rp> tags bracket text defined as a reference
phrase (or hypertext link)
•DTL provides tags to highlight or emphasize text or information for the user
The <rp> (reference phrase) tag is used to specify a word or phrase within panel text
that has additional help information associated with it. The word or phrase is
emphasized within the text of the panel to inform the user that additional
information is available. The user positions the cursor on the reference phrase and
presses F1=Help to obtain help on the phrase.
Data Fields
Data fields are used to display variable data and to allow the user to enter data
Defined with the <dtafld> tag
Each data field must have an associated variable specified on the datavar= attribute
The usage= attribute can be:
IN to define an entry (input-only) field
OUT to define an output-only field
BOTH to define an input-output field (this is the default)
Data field width is specified on the entwidth= attribute OR from the value specified
for the type= attribute of the varclass associated with the variable named on the
datavar= attribute
Field prompts are specified after the end tag on the <dtafld> tag
The size of the prompt is specified on the pmtwidth= attribute
Data field descriptions follow the input field and are specified with the <dtafldd> tag
The width of the description is specified on the deswidth= attribute of the <dtafld>
tag
•A panel is of little use if it does not provide a way to input and output data ☺
•Input and output fields are defined using the <dtafld> tag.
Data Field Example

<panel name=example3 depth=13 width=70 wintitle=Example>
Library Inventory
<topinst>To add a book to the inventory, complete the fields below,
then press Enter.
<area>
<dtacol pmtwidth=15 vardcl=no>
<dtafld datavar=title usage=in entwidth=50>Title
<dtafld datavar=author usage=in entwidth=20 deswidth=30>Author
<dtafldd>Last name, First name, M.I.
<dtafld datavar=publish entwidth=20>Publisher
<dtafld datavar=pages usage=in entwidth=5 deswidth=15>
Total number of pages
<dtafldd>(1 - 99999)
</dtacol>
</area>
</panel>
• It is easiest to look at example to understand how to define data fields using

DTL.
• This slide shows the DTL for a panel with 4 input fields:
1. The name attribute on the <panel> tag identifies the generated panel
as EXAMPLE3. The depth and width attributes specify the panel to be
displayed as a window 70 characters wide by 13 rows. The title of the
window is "Example“.
2. The <topinst> tag specifies instructions to be displayed at the top of
the panel. The text is format to fit across 2 lines.
3. The <dtacol> tag defines the formatting for data fields displayed in a
column. The prompt width for the fields is 15 characters and the entry
width defaults to the rest of the region - in this case the width of the
panel.
4. The <dtafld> tags define each of the data fields in the column:
datavar= specifies the ISPF variable for the field
usage=in defines an input field
entwidth= defines the width of an input field
Following the > character is the prompt text for the field
5. The <dtafldd> tag defines the data field description. This is text display
on the right-hand side of the data field.
Other Data Field Attributes

required= indicates this is a required input field. DTL will automatically generate
a VER when this is specified.
msg= specifies the error message to be issued when a required field is not
filled in.
autotab= specifies that the cursor will skip to the next field.
Noendattr specifies that no ending attribute will be placed after the data field.
pmtfmt= controls the generation of prompt leader characters.
init= generates code in the )INIT section to initialize the field.
caps= specifies that the field is displayed in uppercase or not.
•The <dtafld> tag in z/OS 1.9 has about 46 different attributes.

•The only required attribute is the DATAVAR attribute (described earlier)
•Other data field attributes not previously discussed include:
•required – indicates a mandatory input field. Generates a VER
NONBLANK statement for the field in the panel logic.
•msg – specifies the message displayed when data is not entered into a field
defined with required=yes.
•autotab – used to force the cursor to automatically skip to the next input
field when the user enters the last character in this field.
•noendattr - specifies that no ending attribute to be placed at the end of
the input field. This allows for input fields to be split over more than 1 line
(eg: Option 6 - TSO command field), but is only valid when window=no is
specified on the <panel> tag or dir=horiz is specified on the
<region> tag.
•pmtfmt - control the generation of the prompt leader characters. The
deafult value is "CUA" which generate the leader dots (as in our example).
•init - the conversion utility adds a statement to the panel )INIT section
to initialize the field to the specified value.
•caps – if ON is specified, the data in the field is displayed in uppercase.
Selection Fields
Use the <selfld> tag to define selection fields
The <choice> tag enumerates the choices to be presented
There are five types of selection fields specified by the type= attribute:
Single - select one from several choices
Multi - select many from several choices
Menu - a variation of single selection used for ISPF selection panels
Model - similar to Menu, but used for edit model panels
Tutor - similar to Menu, but used for tutorial selection menus
Menu, Model, and Tutor are only permitted when the MENU keyword is
specified on the <panel> tag
Single selection Multi selection

Exotic Location Travel Mode
_ 1. Germany _ Ship
2. Hawaii _ Plane
3. Norway _ Ferry Boat
4. Sweden _ Drive Yourself
5. Finland
The type values of menu, model, and tutor can only be specified when the
menu keyword is specified on the <panel> tag.
Single Choice Fields

Specify the variable name on the name= attribute of the <selfld> tag
Specify the name of the program variable with the checkvar= attribute on the
<choice> tag
Specify the correlation between the panel variable and the program variable with the
match= attribute on the <choice> tag
•The checkvar attribute defines a variable whose value indicates whether or not
the choice is preselected when the selection field is displayed. If the value of the
variable is equivalent to the string you specify with the match attribute, the item is
marked as selected when the panel displays.
ISPF updates the variable to the value specified by the match attribute when the
user selects the choice being defined.
•The match attribute defines the value for the check variable that causes the item
to be preselected. The value can be any character string. MATCH=1 is the default.
Single Selection Field Example

<panel name=example4 depth=13 width=50>Single Selection
<topinst>Choose the most convenient day for your appointment, then press
Enter.
<area>
<selfld name=choice selwidth=30 pmtwidth=9>Weekdays: This DTL produces
<choice checkvar=day match=MON>Monday
this panel logic
<choice checkvar=day match=TUE>Tuesday
<choice checkvar=day match=WED>Wednesday to produce this display
<choice checkvar=day match=THU>Thursday
<choice checkvar=day match=FRI>Friday
</selfld>
</area>
</panel>
)INIT
.ZVARS = '(CHOICE)'
&CHOICE = ' '
IF (&DAY='MON') &CHOICE='1'
IF (&DAY='TUE') &CHOICE='2'
IF (&DAY='WED') &CHOICE='3'
IF (&DAY='THU') &CHOICE='4'
IF (&DAY='FRI') &CHOICE='5'
)PROC
&CHOICE = TRANS(&CHOICE 01,1 02,2 03,3
04,4 05,5 *,*)
VER(&CHOICE RANGE,1,5)
IF (&CHOICE='1') &DAY='MON'
IF (&CHOICE='2') &DAY='TUE'
IF (&CHOICE='3') &DAY='WED'
IF (&CHOICE='4') &DAY='THU'
IF (&CHOICE='5') &DAY='FRI'
)END
•This slide shows an example of using DTL to define a single selection field.
•The example makes use of the checkvar and match attributes on the
<choice> tags to allow the program identify the selection made by the user.
•NOTE: the default for the <selfld> tag is TYPE=SINGLE
Multi-selection Fields
Specify type=multi on the <selfld> tag
Specify the name of the variable on the panel with the name= attribute on the
<choice> tag
Specify the name of the program variable with the checkvar= attribute on the
<choice> tag
Multi-selection fields are defined in a very similar way to single choice fields.
)INIT
.ZVARS = '(D1 D2 D3 D4 D5)'
Multi-selection
Field Example &D1 = ' '
&D2 = ' '
<panel name=example5 depth=11 width=40> &D3 = ' '
Multi Selection &D4 = ' '
<area> &D5 = ' '
IF (&MON = '1') &D1 = '/'
<dtacol pmtwidth=** selwidth=20>
IF (&TUE = '1') &D2 = '/'
<selfld type=multi>Choose the days you IF (&WED = '1') &D3 = '/'
are available and then press Enter. IF (&THU = '1') &D4 = '/'
<choice name=d1 checkvar=mon>Monday IF (&FRI = '1') &D5 = '/'
<choice name=d2 checkvar=tue>Tuesday )REINIT
<choice name=d3 checkvar=wed>Wednesday REFRESH(D1 D2 D3 D4 D5)
<choice name=d4 checkvar=thu>Thursday )PROC
<choice name=d5 checkvar=fri>Friday IF (&D1 ¬= ' ')
</selfld> &D1 = '/'
This DTL produces &MON = '1'
</dtacol>
ELSE &MON = '0'
</area>
</panel>
this panel logic IF (&D2 ¬= ' ')
&D2 = '/'
to produce this display &TUE = '1'
ELSE &TUE = '0'
IF (&D3 ¬= ' ')
&D3 = '/'
&WED = '1'
ELSE &WED = '0'
IF (&D4 ¬= ' ')
&D4 = '/'
&THU = '1'
ELSE &THU = '0'
IF (&D5 ¬= ' ')
&D5 = '/'
&FRI = '1'
ELSE &FRI = '0'
)END
•This slide shows an example of using DTL to define a multi-selection field.

•The example makes use of the checkvar and match attributes on the
<choice> tags to allow the program identify the selections made by the user.
•pmtwidth=** causes the conversion utility to use the maximum available space
as the prompt width.
•The selwidth attribute specifies the number of bytes reserved for choices in
selection fields coded within the data column.
Menu Choice Fields

Specify type=menu on the <selfld> tag to define the selection field as a SELECT
panel
Specify the <choice> tag as you would for a single selection field
Specify an <action> tag to indicate the select invocation
run= specifies the name of the object to invoke
type= specifies the kind of object (panel, cmd, pgm, or exit)
parm= specifies parameters to the invocation
newappl= specifies the application id
scrname= specifies the screen name
lang= specifies the language
passlib specifies Passlib keyword be added to the menu choice
newpool specifies Newpool keyword be added to the menu choice
suspend specifies Suspend keyword be added to the menu choice
nocheck to bypass command checking for lower level functions
<action run=isrseprm type=pgm scrname=superce nocheck>
•Specify an <action> tag for each <choice> tag to indicate the command,
program, or panel to be invoked for that choice
•There are a number of attributes that can specified for the <action> tag for a
menu choice. Some of the more important attributes are:
•RUN - is a required attribute for the <action> tag on a menu choice and
specifies the name of the command, program, or panel invoked for the
choice.
•TYPE - defines the type of the object on the RUN attribute (i.e. command,
program, or panel). A value of EXIT can be specified for a choice to cause
an exit from the menu.
•PARM - defines any parameters to be passed to the object specified with the
RUN attribute
•NEWAPPL - defines the new application id for the command invoked for
the menu selection choice
•SCRNAME - defines the screen name that is displayed on the top left of
panels for the application invoked for the menu choice.
•LANG – specifies the language for the invoked command and can be either
APL or CREX for Compile REXX (otherwise it is not required)
•PASSLIB – specifies that application level ISPF libraries are to be passed
to the application invoked for the choice
•NEWPOOL - requests a new function pool for dialog variables be created
for the application.
•SUSPEND - will revert the next display for the selected application to full
screen , rather than using the existing window
•NOCHECK - will bypass normal command checking for lower level
functions. It only valid when invoking programs or commands and it is the
Other Selection Field Attributes

selwidth= on the <selfld> tag defines the amount of space taken up by the
choice-description-text of each choice tag
required= indicates this is a required selection. DTL will automatically generate
a VER when this is specified
msg= specifies the error message to be issued when a required field is not
filled in
autotab= specifies that the cursor will skip to the next field
fchoice= controls the first choice number for single-choice and menu-choice
selections. It can be set to 0 or 1.
choicecols= and choicedepth= specifies the number of columns and number of
choices formatted into a column respectively
The <selfld> and <dtafld> tags share many of the same attributes.
Data Columns
Use the <dtacol> and </dtacol> tags to "factor" out common attributes for multiple
<dtafld> and <selfld> tags enclosed between the start and end tag
The following attributes can be specified on a <dtacol>
pmtwidth
entwidth
deswidth
selwidth
fldspace
pad
padc <dtacol pmtwidth=45 selwidth=76>
<selfld type=multi>Choose the days you are
outline
available and then press Enter.
pmtfmt
<choice name=d1 checkvar=mon>Monday
autotab
<choice name=d2 checkvar=tue>Tuesday
attrchange
<choice name=d3 checkvar=wed>Wednesday
pmtloc <choice name=d4 checkvar=thu>Thursday
dbalign <choice name=d5 checkvar=fri>Friday
varclass </selfld>
required </dtacol>
caps
vardcl
Specifying these attributes on a contained <dtafld> or <selfld> tag will

override any corresponding attribute on the <dtacol> tag.
List Fields (Tables)

The following tags are used to define list fields (which generate panels with )MODEL
sections)
<lstfld> and </lstfld> - to define the list field
<lstgrp> and </lstgrp> - to define a column group heading
<lstcol> - to define a column within a list field. You must code a <lstcol> tag
for each column of data in the list field
usage= IN, OUT, or BOTH
colwidth= to determine the data width to be used by the column
<area>
line= to provide multi-line model area
<lstfld vardcl=no>
<lstgrp headline=yes>User Name
This DTL produces
<lstcol datavar=fname usage=out colwidth=18>First Name
<lstcol datavar=lname usage=out colwidth=18>Surname this panel code
</lstgrp>
<lstcol datavar=phnum usage=in required=yes colwidth=12>Phone
</lstfld>
</area> ------------- User Name --------------
First Name Surname Phone
)MODEL
%Z +%Z +_Z +
•The list field tags are used to generate panels used with the TBDISPL (Table
Display) service
•The <lstfld> tag defines an ISPF table display area.
•The <lstgrp> tag defines a heading for a single column or multiple columns
within a list field.
•The <lstcol> tag defines a column of data displayed in the ISPF table display
area.
Help
Adding "HELP" in your application
Use the help=help-panel-name attribute with your "object“ tags
<abc> and <pdc> tags for action bar choice and pull-down choice help
<selfld> tag for single choice selection fields
<choice> tag for multi-choice selection fields
<cmdarea> tag for command-line help
<panel> tag for overall panel help
<dtafld> tag for data fields
<lstcol> tag for table display columns
eg: <choice name=field1 help=help1 ...>
Most tags that create 'user-interaction' objects have help available
Create the help panel as we did in the first example.

ENTITY Declarations
Entities are symbolic names used to insert text into a file.
can be either a simple string of characters, or
text from another file (imbed or parameter entity)
parameter entity is an imbed file containing other ENTITY declarations
Entities are defined in the declaration section of the <doctype> tag

<doctype dm system( <:ENTITY entity-name ...> )>
ENTITY keyword must be in UPPER case

Entity names:
Up to 8 characters for imbed and parameter entities, and
Up to 17 characters for other entity names
Must be preceded with an ampersand (‘&’) to use the entity in text
Must be preceded with a percent ('%') when referring to a parameter entity
end with semicolon (';'), a blank, or end of line
CaSe sEnSiTiVe
Entity text can be up to 253 characters
•You can define, or declare frequently used words, phrases, and longer character
strings in your source file as entities or parameter entities that represent text in the
source file. After you have declared them, you refer to the names of the entities in
place of the word or phrase in the text.
•Entities define symbolic names that can be either:
• a simple string or character, or
• the name of another file.
•Use of the entity will imbed the file.
•A parameter entity contains other ENTITY statements. This allows
you to place multiple entity declarations within an external file and
refer to them within a source file.
•An imbed entity contains other DTL tags
•Entities must be defined in the declaration section of the doctype tag. The
declaration section is coded immediately after the system parameter on the
<doctype> tag.
•The ENTITY keyword must be in UPPER case
•Parameter entity names must be a valid member name, up to 8 characters in length.
String or character entity names can be up to 17 characters.
•To use an entity:
•the name must be preceded with '&‘ but …
•for a parameter entity, the name must be preceded with ‘%’
•The name must end with a semicolon (‘;’), blank, or end of line
•The entity text can be up to 253 characters in length
ENTITY Example
<!doctype dm system(
<:ENTITY panel_title "Multiple Selection">
<:ENTITY panel_depth "depth=11">
<:ENTITY panel_width "40">
<:ENTITY msel_desc1 space "Choose the days you are available

and then press Enter">
<:ENTITY shripnl system "shripnl"> <:-- Defines imbed entity -->
<:ENTITY % shrient system > <:-- Defines parameter entity -->

%shrient; <:-- includes the entity -->
)> <:-- DO NOT DELETE THIS LINE -->
&shripnl; <:-- includes the entity -->
•This slide shows our previous example panel modified to use a number of ENTITY
definitions.
•The ENTITY's panel_title, panel_depth, panel_width, and
msel_desc1 are defined as character strings.
•They are not imbed or parameter entities, so the entity names can be longer
than 8 characters
•ENTITY shripnl is defined as an imbed entity - it will imbed an external file
(member SHRIPNL) within the body.
•ENTITY shrient is a parameter entity as it defines additional entities (as we
will see on the next page)
•The % sign indicates it as a parameter entity
•The line with %shrient cause the external file to be imbedded at this point
•Note: the ')>' terminates the <!doctype> tag and the comment just warns to
look carefully at the code before changing it.
•Anyone looking at any of the DTL supplied source for the ISPF panels will
often see a comment like this as it terminates a <!doctype> tag that can
be several hundred lines further up in the code and not always on the same
screen or page.
ENTITY Example…
<doctype> tag not required
<:-- SHRIENT imbed file -->
<:ENTITY mon "Monday"> in imbed files
<:ENTITY tue "Tuesday">
<:ENTITY wed "Wednesay">
<:ENTITY thu "Thursday">
<:ENTITY fri "Friday">
<:ENTITY sat "Saturday">
<:ENTITY sun "Sunday">
<:-- SHRIPNL imbed file -->

<panel name=example6 &panel_depth;
width=&panel_width;>
&panel_title;
<area>
<dtacol pmtwidth=** selwidth=(&panel_width;/2)>
<selfld type=multi>&msel_desc1;
<choice name=d1 help=help1 checkvar=mon>&mon;
<choice name=d2 checkvar=tue>&tue;
<choice name=d3 checkvar=wed>&wed;
<choice name=d4 checkvar=thu>&thu;
<choice name=d5 checkvar=fri>&fri;
</selfld>
</dtacol>
</area>
</panel>
•SHRIENT is a parameter entity containing entities that define the text for the
selection fields.
•Entities can be used for sections of code that is common across many panels (e.g.
action bar definitions)
•They can also use to cater for national language support. ISPF uses entities for this
purpose.
Regions
Understanding regions is the key to mastering panel layout with DTL
Two types of regions exist –
the type determines which way things stack within the region
Horizontal - things stack left to right in this region type
Vertical - things stack top to bottom in this region type
Try to visualize a panel in terms of regions as you write the DTL
Nesting regions is frequently necessary

<:ENTITY a "Options">
<:ENTITY b "Print Graphics">
<:ENTITY c "General">
Regions <:ENTITY d "Terminal ...">
<region dir=horiz>
<region dir=vert>&a
...
</region>
<region dir=vert>
<region dir=horiz>&b
...
</region>
<region dir=horiz>&c
...
</region>
</region>
</region>
<region dir=horiz>&d
...
</region>
Horizontal Regions
(dashed lines)
•The ISPF Setting panel (ISPISMMN) accessed from option 0 is an excellent

example of a panel using different regions.
•This panel has two main horizontal regions defined with dir=horiz on the
<region> tag :
•One at the top which contains a number of other regions, and ...
•one region at the bottom .
<:ENTITY a "Options">
<:ENTITY b "Print Graphics">
<:ENTITY c "General">
Regions <:ENTITY d "Terminal ...">
<region dir=horiz>
<region dir=vert>&a
...
</region>
<region dir=vert>
<region dir=horiz>&b
...
</region>
<region dir=horiz>&c
...
</region>
</region>
</region>
<region dir=horiz>&d
...
</region>
Horizontal Regions
(dashed lines)
Vertical Regions
(solid lines)
•The upper region is divided into 2 vertical regions

•The Options region
•And the region on the right
•which in turn is divided into 2 more horizontal regions
•the print graphic region at the top, and ...
•the General region at the bottom
Region Spacing
The indent=x attribute on the <region> tag moves the entire region x spaces to the
right
eg: <region dir=horiz indent=8>
The <divider> tag creates space between regions, both horizontal and vertical
Adding the gutter= attribute adds more than one space
When a gutter attribute is specified between vertical regions, ISPF will
always add an odd number of spaces
The type= attribute adds a visual divider
eg: <divider type=solid gutter=3>

ISPDTLC – DTL Conversion Utility

Converts DTL to:
Panels
Messages
Command tables
Keylist tables
Options
select on panel
(scroll down)
<compopt> tag
in source
•The DTL conversion utility is invoked using the command ISPDTLC

•Member name is member containing the DTL source to convert
•DTL Source data set is used to specify up to 16 data set for the source
member and imbed files
•Panel data set is the output data set into which the panel is generated
•Message data set is the output data set when converting messages
•Log data set is for messages from the conversion utility
•List data set for the listing written by the conversion utility
•Script data set is used when you want the utility to generate a panel
image using bookmaster tags so the panel may be include in documentation files
•Tables data set is the output data set when generating command and
keylist tables
•Keylist Application Id is the APPLID to be used for the keylist, either
on the panel definition or when creating a keylist
•There are an additional 3 screens of options for the DTL conversion utility.
•Conversion utility options can be entered on the panels or included in the source
using the <compopt> tag.
ISPDTLC in Batch
Sample JCL to run DTL Conversion Utility in Batch.
//VANDYKEC JOB ...
//*
//ISPDTLC EXEC PGM=IKJEFT01
//SYSEXEC DD DSN=ISP.SISPEXEC,DISP=SHR
//ISPPROF DD RECFM=FB,LRECL=80,SPACE=(TRK,(1,1,2))
//ISPMLIB DD DSN=ISP.SISPMENU,DISP=SHR
//ISPPLIB DD DSN=ISP.SISPPENU,DISP=SHR
//ISPSLIB DD DSN=ISP.SISPSENU,DISP=SHR
//ISPTLIB DD DSN=ISP.SISPTENU,DISP=SHR
//DTLGML DD DSN=VANDYKE.GML,DISP=SHR
// DD DSN=VANDYKE.GMLINC,DISP=SHR
//DTLMSG DD DSN=VANDYKE.MSGS,DISP=SHR
//DTLPAN DD DSN=VANDYKE.PANELS,DISP=SHR
//DTLTAB DD DSN=VANDYKE.TABLES,DISP=SHR
//ISPLOG DD SYSOUT=*,RECFM=FB,LRECL=133
//SYSTSPRT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSTSIN DD *
ISPSTART CMD(%ISPDTLC EXAMPLE6 +
(REPLACE DISK KEYLAPPL=ISR +
NOPREP STATS PROFDDN=* +
)
//*
•This slide shows a sample batch job to run the DTL conversion utility in batch
•The ISPxLIB DDs refer to standard ISPF shipped datasets
•DTLGML DD is for the input data sets
•a concatenation of up to 16 data sets can be specified
•DTLMSG, DTLPAN and DTLTAB DDs are the output data sets for
generated messages, panels, and tables (keylists or command tables)
•SYSTSIN DD contains the TSO command to invoke ISPDTLC under ISPF
•ISPSTART is used to establish the ISPF environment and then
invoke REXX exec ISPDTLC
•The first parameter is the source member name (that is found in the
DTLGML concatenation)
•other parameters follow the '('
References
ISPF Publications (z/OS v1.9)
SC34-4824 DTL Guide
SC34-4821 Dialog Developer's Guide and Reference
SC34-4816 Reference Summary
Chapter 8. Dialog Tag Language Tags
ISPF DTL source

ISPF ships the DTL source for all of its panels
ISPF Edit Models

MODEL CLASS DTL within edit to set model class
MODEL tagname to generate skeleton syntax for the tag with descriptions of each
of the parameters

DTL

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

DTL

Uploaded by

Copyright:

Available Formats

Interactive System Productivity Facility (ISPF)

ISPF Panels – Dialog Tag

Peter Van Dyke

Attendance counts towards ISPF certification

8:00 9:30 11:00 13:30 15:00 16:30 18:00

Sunday 2612 2613

Tuesday 8301 8302 8303 2625 2626

Wednesday 2602 2603 2604 2627 2628

Thursday 2605 2606 2632 2633

2 ISPF Panels - Advanced | Session 2627 © 2009 IBM Corporation

3 ISPF Panels - Advanced | Session 2627 © 2009 IBM Corporation

DTL stands for Dialog Tag Language

A markup language based on ISO SGML

You use DTL to define:

A Conversion Utility, ISPDTLC, is shipped with ISPF

4 ISPF Panels - Advanced | Session 2627 © 2009 IBM Corporation

DTL is the acronym for Dialog Tag Language.

Why Use DTL?

Allows for simplified creation of CUA compliant dialogs

Allows for common imbed files at compile-time

Once you get started, it's easy to use

5 ISPF Panels - Advanced | Session 2627 © 2009 IBM Corporation

What Can DTL Do?

Automatic space filling (no more counting spaces!)

Include processing (imbed files at conversion time)

Quick changes from one construct to another

6 ISPF Panels - Advanced | Session 2627 © 2009 IBM Corporation

•DTL simplifies coding by its automatic generation of some constructs, for

Do I Have to Use it Everywhere?

7 ISPF Panels - Advanced | Session 2627 © 2009 IBM Corporation

•Do you have to use DTL everywhere?

Basic DTL Tag Syntax Notes

DTL is a freeform language

DTL is not case sensitive

A tag consists of the tag name inside delimiters (< >):

Many tags are sets of a "start-tag“

8 ISPF Panels - Advanced | Session 2627 © 2009 IBM Corporation

Basic DTL Tag Syntax …

DTL will automatically word-wrap text with some exceptions

9 ISPF Panels - Advanced | Session 2627 © 2009 IBM Corporation

Basic DTL Tag Syntax …

Some end-tags are optional

Many attributes have defaults that will be used if not coded

10 ISPF Panels - Advanced | Session 2627 © 2009 IBM Corporation

•Some DTL tags have attributes

Example - Simple Help Panel

11 ISPF Panels - Advanced | Session 2627 © 2009 IBM Corporation

•Let’s look at an example of a simple help panel.

Help Panel Display

12 ISPF Panels - Advanced | Session 2627 © 2009 IBM Corporation

Simple Help Panel Example

All types of lists are coded in the same manner

To add a command line to this help panel

13 ISPF Panels - Advanced | Session 2627 © 2009 IBM Corporation

Application Panel Coding

14 ISPF Panels - Advanced | Session 2627 © 2009 IBM Corporation

Application Panel Coding ...

15 ISPF Panels - Advanced | Session 2627 © 2009 IBM Corporation

Application Panel Coding ...

16 ISPF Panels - Advanced | Session 2627 © 2009 IBM Corporation

The File action bar choice has 4 pull-down choices:

Application Panel Coding ...

17 ISPF Panels - Advanced | Session 2627 © 2009 IBM Corporation