Interactive System Productivity Facility

(ISPF) IBM

Dialog Tag Language Guide

and Reference
OS/390 Version 2 Release 10.0

SC28-1219-04
Interactive System Productivity Facility (ISPF) IBM

Dialog Tag Language Guide

and Reference
OS/390 Version 2 Release 10.0

SC28-1219-04
 Note
Before using this document, read the general information under “Notices” on page 505.

Fifth Edition (September 2000)

This edition applies to ISPF for Version 2 Release 10 of the licensed program OS/390 (program number 5647-A01)
and to all subsequent releases and modifications until otherwise indicated in new editions.
Order publications by phone or fax. IBM Software Manufacturing Solutions takes publication orders between 8:30
a.m. and 7:00 p.m. eastern standard time (EST). The phone number is (800) 879-2755. The fax number is (800)
284-4721.
You can also order publications through your IBM representative or the IBM branch office serving your locality.
Publications are not stocked at the address below.
A form for comments appears at the back of this publication. If the form has been removed, and you have
ISPF-specific comments, address your comments to:
International Business Machines Corporation
Software Reengineering
Department G7IA / Building 503
Research Triangle Park, NC 27709-9990

FAX (United States & Canada): 1+800+227-5088

IBMLink (United States customers only): CIBMORCF@RALVM17
IBM Mail Exchange: [email protected]
Internet: [email protected]

If you would like a reply, be sure to include your name, address, telephone number, or FAX number.
Make sure to include the following in your comment or note:
Title and order number of this book
Page number or topic related to your comment
The ISPF development team maintains a site on the World-Wide Web. The URL for the site is:
http://www.software.ibm.com/ad/ispf

© Copyright International Business Machines Corporation 1989, 2000. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
 Contents
Figures . . . . . . . . . . . . . . . ix Chapter 2. How to Use the Dialog Tag
Language (DTL) . . . . . . . . . . . 11
Preface . . . . . . . . . . . . . . . xi Syntax Conventions. . . . . . . . . . . . 11
About This Book . . . . . . . . . . . . . xi Attributes and Values . . . . . . . . . . 11
Who Should Use This Book . . . . . . . . . xi Tag Text . . . . . . . . . . . . . . 12
Text Formatting . . . . . . . . . . . . 13
| Summary of Changes . . . . . . . . xiii Nesting tags . . . . . . . . . . . . . 15
| ISPF Product Changes . . . . . . .
. xiii . . Markup Declarations . . . . . . . . . . . 16
| ISPF DM Component Changes. . . . .
. xiv . . Declaring the Document Type . . . . . . . 16
| ISPF PDF Component Changes . . . .
. xvi . . Including Comments in Your Markup . . . . 16
| ISPF SCLM Component Changes. . . . . . . xvii Defining Entities and Parameter Entities . . . . 18
| ISPF Client/Server Component Changes . . . . xviii Imbedding Source Files . . . . . . . . . 23
| ISPF User Interface Considerations . . . . . . xviii Run-Time Substitution Variables . . . . . . 24
| ISPF Migration Considerations . . . . . . . xviii Predefined Entities . . . . . . . . . . . 25
| ISPF Profiles . . . . . . . . . . . . . xix
| Year 2000 Support for ISPF . . . . . . . . xix Chapter 3. Getting Started: Designing
Application Panels . . . . . . . . . 27
What’s in the OS/390 V2R10.0 ISPF Defining Application Panels: The PANEL Tag . . . 27
library? . . . . . . . . . . . . . . xxi The Panel Title . . . . . . . . . . . . 28
OS/390 V2R10.0 ISPF . . . . . . . . . . . xxi Panel Size (Width and Depth) . . . . . . . 29
Key Mapping Lists . . . . . . . . . . . 29
Associated Help Panels . . . . . . . . . 29
The ISPF User Interface. . . . . . . xxiii Panel Defaults . . . . . . . . . . . . 30
Some Terms You Should Know . . . . . . . xxiii Cursor Placement . . . . . . . . . . . 30
How to Navigate in ISPF without Using Action Other Panel Attributes. . . . . . . . . . 32
Bars . . . . . . . . . . . . . . . . xxiv Defining Action Bars and Pull-Downs . . . . . 34
How to Navigate in ISPF Using the Action Bar Coding an Action Bar Definition . . . . . . 35
Interface . . . . . . . . . . . . . . . xxiv Pull-Down Choice Actions . . . . . . . . 36
Action Bars . . . . . . . . . . . . . xxiv Action Bar Help . . . . . . . . . . . . 36
Action Bar Choices . . . . . . . . . . xxvii Preselected Pull-Down Choices . . . . . . . 37
Point-and-Shoot Text Fields . . . . . . . xxviii Mnemonic Choice Selection . . . . . . . . 38
Function Keys . . . . . . . . . . . xxviii Pull-Down Choice Accelerator Support . . . . 39
Selection Fields . . . . . . . . . . . xxix Defining the Panel Body . . . . . . . . . . 39
Command Nesting . . . . . . . . . . . xxx Panel Instructions . . . . . . . . . . . 39
The AREA Tag . . . . . . . . . . . . 40
Elements and Features in OS/390 xxxi Scrollable Areas . . . . . . . . . . . . 41
Multiple AREA Tags . . . . . . . . . . 44
Part 1. Guide to the Dialog Tag The DYNAMIC AREA Tag . . . . . . . . 45
The GRAPHIC AREA Tag . . . . . . . . 46
Language (DTL) . . . . . . . . . . 1 The DIVIDER Tag . . . . . . . . . . . 46
The REGION Tag . . . . . . . . . . . 47
Chapter 1. Introduction to the Dialog Tag Defining a Command Area . . . . . . . . . 51
Language (DTL) . . . . . . . . . . . 3 Defining Panel Defaults . . . . . . . . . . 53
Why the Dialog Tag Language (DTL)? . . . . . . 3
What Is the Dialog Tag Language? . . . . . . . 4 Chapter 4. Variables and Variable
Dialog Elements . . . . . . . . . . . . . 5 Classes . . . . . . . . . . . . . . 57
Application Panels . . . . . . . . . . . 5 Declaring Variables . . . . . . . . . . . . 57
Help Panels. . . . . . . . . . . . . . 7 Defining Variable Classes . . . . . . . . . . 58
Messages . . . . . . . . . . . . . . 8 Variable Class Types . . . . . . . . . . . 59
Application Command Table . . . . . . . . 8 Character Variables . . . . . . . . . . . 59
Key Mapping Lists . . . . . . . . . . . 9 Numeric Variables . . . . . . . . . . . 60
Variables and Variable Classes . . . . . . . . 9 Variable Validation . . . . . . . . . . . . 61
What Is the ISPF Conversion Utility? . . . . . . 9 Translate Lists . . . . . . . . . . . . 61
Validity Checks . . . . . . . . . . . . 66

© Copyright IBM Corp. 1989, 2000 iii

 Overriding Variable Classes . . . . . . . . 76 Variable Substitution . . . . . . . . . . 156

Chapter 5. Application Panel Fields . . 77 Chapter 8. The Application Command

Field Prompts . . . . . . . . . . . . . 77 Table . . . . . . . . . . . . . . . 157
Defining Data Fields . . . . . . . . . . . 80 Defining the Application Command Table . . . . 157
Data Field Width . . . . . . . . . . . 82 Specifying Command Actions . . . . . . . 159
Data Field Descriptions . . . . . . . . . 82 Truncating Commands . . . . . . . . . 160
Data Field Help . . . . . . . . . . . . 83
Other Data Field Attributes . . . . . . . . 84 Chapter 9. Defining Key Mapping Lists 163
Defining Selection Fields . . . . . . . . . . 87
Assigning Keys and Actions . . . . . . . . 163
Single-Choice Fields . . . . . . . . . . 88
ISPF Default Key List. . . . . . . . . . 164
Multiple-Choice Fields. . . . . . . . . . 89
Displaying Keys . . . . . . . . . . . 164
Menu-Choice Fields . . . . . . . . . . 91
Defining Help for Key List . . . . . . . . 165
Model-Choice Fields . . . . . . . . . . 92
| Tutor-Choice Fields . . . . . . . . . . . 93
Selection Field Help . . . . . . . . . . 93 Chapter 10. Using the Conversion
Selection Width . . . . . . . . . . . . 93 Utility . . . . . . . . . . . . . . . 167
Other Selection Field Attributes. . . . . . . 95 Using the ISPF-Supplied Invocation Panels . . . 167
Data Columns . . . . . . . . . . . . . 98 Invocation Panel . . . . . . . . . . . 167
Defining List Fields. . . . . . . . . . . . 99 Panel Input Fields . . . . . . . . . . . 170
List Group Headings . . . . . . . . . . 101 Panel Options . . . . . . . . . . . . 171
List Column Width . . . . . . . . . . 103 Converting Multiple DTL Source Files . . . . 174
Other List Column Attributes . . . . . . . 103 Calling Help . . . . . . . . . . . . 174
Defining Group Headings . . . . . . . . 106 Using CUA Panel Attributes . . . . . . . 174
Defining Point-and-Shoot Fields . . . . . . . 106 Conversion Utility Syntax . . . . . . . . . 175
Conversion Utility General Information . . . . 181
Chapter 6. Information Regions and ISPF Conversion Utility Messages . . . . . . 184
Return Codes . . . . . . . . . . . . 185
Help Panels . . . . . . . . . . . . 109
Conversion Results . . . . . . . . . . 185
Defining an Information Region . . . . . . . 109
Conversion Utility File Names. . . . . . . . 186
Defining Basic Text . . . . . . . . . . . 110
Paragraphs . . . . . . . . . . . . . 110
Headings . . . . . . . . . . . . . . 112 Part 2. Dialog Tag Language (DTL)
Lines . . . . . . . . . . . . . . . 113 Reference . . . . . . . . . . . . 189
Examples . . . . . . . . . . . . . . 114
Figures . . . . . . . . . . . . . . 115
Chapter 11. How to Read the Syntax
Defining Lists . . . . . . . . . . . . . 117
Note Lists . . . . . . . . . . . . . 118 Diagrams . . . . . . . . . . . . . 191
Simple Lists . . . . . . . . . . . . . 118
Unordered Lists . . . . . . . . . . . 120 Chapter 12. Markup Declarations and
Ordered Lists . . . . . . . . . . . . 122 DTL Macro Reference . . . . . . . . 193
Definition Lists . . . . . . . . . . . . 124 Document-Type Declaration . . . . . . . . 193
Parameter Lists . . . . . . . . . . . . 128 Description . . . . . . . . . . . . . 193
Nesting Tags within Lists . . . . . . . . 129 Example . . . . . . . . . . . . . . 194
Nesting Lists within Lists . . . . . . . . 131 Entity Declarations . . . . . . . . . . . 194
Alerting Users: Notes, Warnings, Cautions, and Description . . . . . . . . . . . . . 195
Attention . . . . . . . . . . . . . . . 132 Conditions . . . . . . . . . . . . . 195
Notes . . . . . . . . . . . . . . . 132 Example . . . . . . . . . . . . . . 196
Attention and Warning . . . . . . . . . 135 Sample Entity Definitions . . . . . . . . 197
Caution . . . . . . . . . . . . . . 136 DTL Macros . . . . . . . . . . . . . 199
Emphasizing Panel Text . . . . . . . . . 137
Using Information Regions with Other Panel Chapter 13. Tag Reference . . . . . . 201
Elements . . . . . . . . . . . . . . 141
Rules for Variable Names . . . . . . . . . 201
Help Panels . . . . . . . . . . . . . 142
Rules for “%variable” Names . . . . . . . . 201
AB (Action Bar) . . . . . . . . . . . . 201
Chapter 7. Messages . . . . . . . . 151 Description . . . . . . . . . . . . . 202
Defining Messages . . . . . . . . . . . 151 Conditions . . . . . . . . . . . . . 202
Specifying Message Severity . . . . . . . 152 Nested Tags . . . . . . . . . . . . . 203
Short Messages . . . . . . . . . . . . 153 Example . . . . . . . . . . . . . . 203
Assigning Messages . . . . . . . . . . 153 ABC (Action Bar Choice) . . . . . . . . . 204
Displaying Messages . . . . . . . . . . 155 Description . . . . . . . . . . . . . 205

iv OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 Conditions . . . . . . . . . . . . . 205 Nested Tags . . . . . . . . . . . . . 250
Nested Tags . . . . . . . . . . . . . 205 Example . . . . . . . . . . . . . . 250
Example . . . . . . . . . . . . . . 205 CHOICE (Selection Choice). . . . . . . . . 252
ACTION (Action) . . . . . . . . . . . . 207 Description . . . . . . . . . . . . . 256
Description . . . . . . . . . . . . . 211 Conditions . . . . . . . . . . . . . 257
Conditions . . . . . . . . . . . . . 212 Nested Tags . . . . . . . . . . . . . 257
Nested Tags . . . . . . . . . . . . . 212 Example . . . . . . . . . . . . . . 257
Example . . . . . . . . . . . . . . 212 CMD (Command Definition) . . . . . . . . 259
AREA (Area) . . . . . . . . . . . . . 213 Description . . . . . . . . . . . . . 260
Description . . . . . . . . . . . . . 215 Conditions . . . . . . . . . . . . . 260
Conditions . . . . . . . . . . . . . 216 Nested Tags . . . . . . . . . . . . . 260
Nested Tags . . . . . . . . . . . . . 216 Example . . . . . . . . . . . . . . 260
Example . . . . . . . . . . . . . . 217 CMDACT (Command Action) . . . . . . . . 261
ASSIGNI (Assignment List Item) . . . . . . . 219 Description . . . . . . . . . . . . . 263
Description . . . . . . . . . . . . . 220 Conditions . . . . . . . . . . . . . 263
Conditions . . . . . . . . . . . . . 220 Nested Tags . . . . . . . . . . . . . 263
Nested Tags . . . . . . . . . . . . . 220 Example . . . . . . . . . . . . . . 263
Example . . . . . . . . . . . . . . 220 CMDAREA (Command Area) . . . . . . . . 264
ASSIGNL (Assignment List) . . . . . . . . 221 Description . . . . . . . . . . . . . 269
Description . . . . . . . . . . . . . 221 Conditions . . . . . . . . . . . . . 269
Conditions . . . . . . . . . . . . . 221 Nested Tags . . . . . . . . . . . . . 269
Nested Tags . . . . . . . . . . . . . 221 Example . . . . . . . . . . . . . . 269
Example . . . . . . . . . . . . . . 221 CMDTBL (Command Table) . . . . . . . . 270
ATTENTION (Attention) . . . . . . . . . 222 Description . . . . . . . . . . . . . 271
Description . . . . . . . . . . . . . 222 Conditions . . . . . . . . . . . . . 271
Conditions . . . . . . . . . . . . . 223 Nested Tags . . . . . . . . . . . . . 271
Nested Tags . . . . . . . . . . . . . 223 Example . . . . . . . . . . . . . . 271
Example . . . . . . . . . . . . . . 223 COMMENT (Comment) . . . . . . . . . . 272
ATTR (Attribute) . . . . . . . . . . . . 224 Description . . . . . . . . . . . . . 272
Description . . . . . . . . . . . . . 227 Conditions: . . . . . . . . . . . . . 273
Conditions . . . . . . . . . . . . . 227 Nested Tags . . . . . . . . . . . . . 273
Nested Tags . . . . . . . . . . . . . 228 Example . . . . . . . . . . . . . . 273
Example . . . . . . . . . . . . . . 228 COMPOPT (Compiler Options) . . . . . . . 274
BOTINST (Bottom Instruction). . . . . . . . 228 Description . . . . . . . . . . . . . 275
Description . . . . . . . . . . . . . 228 Conditions: . . . . . . . . . . . . . 275
Conditions . . . . . . . . . . . . . 229 Nested Tags . . . . . . . . . . . . . 275
Nested Tags . . . . . . . . . . . . . 229 Example . . . . . . . . . . . . . . 275
Example . . . . . . . . . . . . . . 229 COPYR (Copyright) . . . . . . . . . . . 276
CAUTION (Caution) . . . . . . . . . . . 230 Description . . . . . . . . . . . . . 276
Description . . . . . . . . . . . . . 230 Conditions . . . . . . . . . . . . . 276
Conditions . . . . . . . . . . . . . 230 Nested Tags . . . . . . . . . . . . . 276
Nested Tags . . . . . . . . . . . . . 231 Example . . . . . . . . . . . . . . 276
Example . . . . . . . . . . . . . . 231 DA (Dynamic Area) . . . . . . . . . . . 277
CHDIV (Choice Divider) . . . . . . . . . 232 Description . . . . . . . . . . . . . 281
Description . . . . . . . . . . . . . 233 Conditions . . . . . . . . . . . . . 281
Conditions . . . . . . . . . . . . . 233 Nested Tags . . . . . . . . . . . . . 282
Nested Tags . . . . . . . . . . . . . 233 Example . . . . . . . . . . . . . . 282
Example . . . . . . . . . . . . . . 233 DD (Definition Description) . . . . . . . . 282
CHECKI (Validity Check Item) . . . . . . . 234 Description . . . . . . . . . . . . . 282
Description . . . . . . . . . . . . . 242 Conditions . . . . . . . . . . . . . 282
Conditions . . . . . . . . . . . . . 242 Nested Tags . . . . . . . . . . . . . 283
Nested Tags . . . . . . . . . . . . . 242 Example . . . . . . . . . . . . . . 283
Example . . . . . . . . . . . . . . 242 DDHD (Definition Description Header) . . . . 284
CHECKL (Validity Check List). . . . . . . . 243 Description . . . . . . . . . . . . . 284
Description . . . . . . . . . . . . . 243 Conditions . . . . . . . . . . . . . 284
Conditions . . . . . . . . . . . . . 243 Nested Tags . . . . . . . . . . . . . 284
Nested Tags . . . . . . . . . . . . . 243 Example . . . . . . . . . . . . . . 285
Example . . . . . . . . . . . . . . 243 DIVIDER (Area Divider) . . . . . . . . . 285
CHOFLD (Choice Data Field) . . . . . . . . 244 Description . . . . . . . . . . . . . 287
Description . . . . . . . . . . . . . 249 Conditions . . . . . . . . . . . . . 287
Conditions . . . . . . . . . . . . . 249 Nested Tags . . . . . . . . . . . . . 287

Contents v
 Example . . . . . . . . . . . . . . 287 HELPDEF (Help default) . . . . . . . . . 332
DL (Definition List) . . . . . . . . . . . 288 Description . . . . . . . . . . . . . 334
Description . . . . . . . . . . . . . 289 Conditions . . . . . . . . . . . . . 334
Conditions . . . . . . . . . . . . . 289 Nested Tags . . . . . . . . . . . . . 334
Nested Tags . . . . . . . . . . . . . 289 Example . . . . . . . . . . . . . . 334
Example . . . . . . . . . . . . . . 290 Hn (Heading) . . . . . . . . . . . . . 335
DT (Definition Term) . . . . . . . . . . . 291 Description . . . . . . . . . . . . . 335
Description . . . . . . . . . . . . . 292 Conditions . . . . . . . . . . . . . 335
Conditions . . . . . . . . . . . . . 292 Nested Tags . . . . . . . . . . . . . 335
Nested Tags . . . . . . . . . . . . . 292 Example . . . . . . . . . . . . . . 335
Example . . . . . . . . . . . . . . 292 HP (Highlighted Phrase) . . . . . . . . . 336
DTACOL (Data Column) . . . . . . . . . 293 Description . . . . . . . . . . . . . 337
Description . . . . . . . . . . . . . 296 Conditions . . . . . . . . . . . . . 337
Conditions . . . . . . . . . . . . . 297 Nested Tags . . . . . . . . . . . . . 337
Nested Tags . . . . . . . . . . . . . 297 Example . . . . . . . . . . . . . . 337
Example . . . . . . . . . . . . . . 298 INFO (Information Region) . . . . . . . . . 339
DTAFLD (Data Field). . . . . . . . . . . 299 Description . . . . . . . . . . . . . 339
Description . . . . . . . . . . . . . 308 Conditions . . . . . . . . . . . . . 339
Conditions . . . . . . . . . . . . . 308 Nested Tags . . . . . . . . . . . . . 339
Nested Tags . . . . . . . . . . . . . 308 Example . . . . . . . . . . . . . . 340
Example . . . . . . . . . . . . . . 308 KEYI (Key Item) . . . . . . . . . . . . 340
DTAFLDD (Data Field Description) . . . . . . 309 Description . . . . . . . . . . . . . 342
Description . . . . . . . . . . . . . 310 Conditions . . . . . . . . . . . . . 342
Conditions . . . . . . . . . . . . . 310 Nested Tags . . . . . . . . . . . . . 343
Nested Tags . . . . . . . . . . . . . 310 Example . . . . . . . . . . . . . . 343
Example . . . . . . . . . . . . . . 310 KEYL (Key List) . . . . . . . . . . . . 344
DTHD (Definition Term Header) . . . . . . . 311 Description . . . . . . . . . . . . . 345
Description . . . . . . . . . . . . . 311 Conditions . . . . . . . . . . . . . 345
Conditions . . . . . . . . . . . . . 311 Nested Tags . . . . . . . . . . . . . 345
Nested Tags . . . . . . . . . . . . . 311 Example . . . . . . . . . . . . . . 345
Example . . . . . . . . . . . . . . 312 LI (List Item) . . . . . . . . . . . . . 346
FIG (Figure) . . . . . . . . . . . . . . 312 Description . . . . . . . . . . . . . 347
Description . . . . . . . . . . . . . 313 Conditions . . . . . . . . . . . . . 347
Conditions . . . . . . . . . . . . . 313 Nested Tags . . . . . . . . . . . . . 348
Nested Tags . . . . . . . . . . . . . 313 Example . . . . . . . . . . . . . . 348
Example . . . . . . . . . . . . . . 314 LINES (Lines) . . . . . . . . . . . . . 349
FIGCAP (Figure Caption) . . . . . . . . . 315 Description . . . . . . . . . . . . . 349
Description . . . . . . . . . . . . . 315 Conditions . . . . . . . . . . . . . 349
Conditions . . . . . . . . . . . . . 315 Nested Tags . . . . . . . . . . . . . 350
Nested Tags . . . . . . . . . . . . . 315 Example . . . . . . . . . . . . . . 350
Example . . . . . . . . . . . . . . 315 LIT (Literal) . . . . . . . . . . . . . . 351
GA (Graphic Area) . . . . . . . . . . . 316 Description . . . . . . . . . . . . . 351
Description . . . . . . . . . . . . . 317 Conditions . . . . . . . . . . . . . 351
Conditions . . . . . . . . . . . . . 318 Nested Tags . . . . . . . . . . . . . 351
Nested Tags . . . . . . . . . . . . . 318 Example . . . . . . . . . . . . . . 352
Example . . . . . . . . . . . . . . 318 LP (List Part) . . . . . . . . . . . . . 352
| GENERATE (Generate) . . . . . . . . . . 318 Description . . . . . . . . . . . . . 353
| Description . . . . . . . . . . . . . 319 Conditions . . . . . . . . . . . . . 353
| Conditions . . . . . . . . . . . . . 319 Nested Tags . . . . . . . . . . . . . 353
| Nested Tags . . . . . . . . . . . . . 319 Example . . . . . . . . . . . . . . 354
| Example . . . . . . . . . . . . . . 319 LSTCOL (List Column) . . . . . . . . . . 354
GRPHDR (Group Header) . . . . . . . . . 320 Description . . . . . . . . . . . . . 361
Description . . . . . . . . . . . . . 322 Conditions . . . . . . . . . . . . . 361
Conditions . . . . . . . . . . . . . 322 Nested Tags . . . . . . . . . . . . . 361
Nested Tags . . . . . . . . . . . . . 322 Examples . . . . . . . . . . . . . . 362
Example . . . . . . . . . . . . . . 322 LSTFLD (List Field) . . . . . . . . . . . 364
HELP (Help Panel) . . . . . . . . . . . 323 Description . . . . . . . . . . . . . 366
Description . . . . . . . . . . . . . 328 Conditions . . . . . . . . . . . . . 367
Conditions . . . . . . . . . . . . . 329 Nested Tags . . . . . . . . . . . . . 367
Nested Tags . . . . . . . . . . . . . 329 Example . . . . . . . . . . . . . . 367
Example . . . . . . . . . . . . . . 330 LSTGRP (List Group) . . . . . . . . . . . 368

vi OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 Description . . . . . . . . . . . . . 369 Conditions . . . . . . . . . . . . . 408
Conditions . . . . . . . . . . . . . 370 Nested Tags . . . . . . . . . . . . . 409
Nested Tags . . . . . . . . . . . . . 370 Example . . . . . . . . . . . . . . 409
Example . . . . . . . . . . . . . . 370 PD (Parameter Description) . . . . . . . . 410
LSTVAR (List Variable) . . . . . . . . . . 371 Description . . . . . . . . . . . . . 410
Description . . . . . . . . . . . . . 372 Conditions . . . . . . . . . . . . . 410
Conditions . . . . . . . . . . . . . 372 Nested Tags . . . . . . . . . . . . . 410
Nested Tags . . . . . . . . . . . . . 372 Example . . . . . . . . . . . . . . 411
Example . . . . . . . . . . . . . . 372 PDC (Pull-Down Choice) . . . . . . . . . 412
M (Mnemonic) . . . . . . . . . . . . . 374 Description . . . . . . . . . . . . . 414
Description . . . . . . . . . . . . . 375 Conditions . . . . . . . . . . . . . 414
Conditions . . . . . . . . . . . . . 375 Nested Tags . . . . . . . . . . . . . 414
Nested Tags . . . . . . . . . . . . . 375 Example . . . . . . . . . . . . . . 414
Example . . . . . . . . . . . . . . 375 PDSEP (Pull-Down Separator) . . . . . . . . 416
MSG (Message). . . . . . . . . . . . . 376 Description . . . . . . . . . . . . . 416
Description . . . . . . . . . . . . . 379 Conditions . . . . . . . . . . . . . 416
Conditions . . . . . . . . . . . . . 379 Nested Tags . . . . . . . . . . . . . 416
Nested Tags . . . . . . . . . . . . . 379 Example . . . . . . . . . . . . . . 416
Example . . . . . . . . . . . . . . 379 PNLINST (Panel Instruction) . . . . . . . . 418
MSGMBR (Message Member) . . . . . . . . 380 Description . . . . . . . . . . . . . 418
Description . . . . . . . . . . . . . 381 Conditions . . . . . . . . . . . . . 418
Conditions . . . . . . . . . . . . . 381 Nested Tags . . . . . . . . . . . . . 418
Nested Tags . . . . . . . . . . . . . 381 Example . . . . . . . . . . . . . . 418
Example . . . . . . . . . . . . . . 381 PS (Point-and-Shoot) . . . . . . . . . . . 419
NOTE (Note) . . . . . . . . . . . . . 382 Description . . . . . . . . . . . . . 421
Description . . . . . . . . . . . . . 382 Conditions . . . . . . . . . . . . . 421
Conditions . . . . . . . . . . . . . 383 Nested tags . . . . . . . . . . . . . 421
Nested Tags . . . . . . . . . . . . . 383 Example . . . . . . . . . . . . . . 421
Example . . . . . . . . . . . . . . 383 PT (Parameter Term) . . . . . . . . . . . 422
NOTEL (Note List) . . . . . . . . . . . 384 Description . . . . . . . . . . . . . 422
Description . . . . . . . . . . . . . 384 Conditions . . . . . . . . . . . . . 422
Conditions . . . . . . . . . . . . . 384 Nested Tags . . . . . . . . . . . . . 423
Nested Tags . . . . . . . . . . . . . 385 Example . . . . . . . . . . . . . . 423
Example . . . . . . . . . . . . . . 385 REGION (Region) . . . . . . . . . . . . 424
NT (Note) . . . . . . . . . . . . . . 386 Description . . . . . . . . . . . . . 426
Description . . . . . . . . . . . . . 386 Conditions . . . . . . . . . . . . . 426
Conditions . . . . . . . . . . . . . 386 Nested Tags . . . . . . . . . . . . . 426
Nested Tags . . . . . . . . . . . . . 386 Help Panel . . . . . . . . . . . . . 427
Example . . . . . . . . . . . . . . 387 Example . . . . . . . . . . . . . . 427
OL (Ordered List) . . . . . . . . . . . . 387 RP (Reference Phrase) . . . . . . . . . . 430
Description . . . . . . . . . . . . . 388 Description . . . . . . . . . . . . . 431
Conditions . . . . . . . . . . . . . 388 Conditions . . . . . . . . . . . . . 431
Nested Tags . . . . . . . . . . . . . 389 Nested Tags . . . . . . . . . . . . . 431
Example . . . . . . . . . . . . . . 389 Example . . . . . . . . . . . . . . 432
P (Paragraph) . . . . . . . . . . . . . 390 SELFLD (Selection Field) . . . . . . . . . 433
Description . . . . . . . . . . . . . 390 Description . . . . . . . . . . . . . 443
Conditions . . . . . . . . . . . . . 391 Conditions . . . . . . . . . . . . . 444
Nested Tags . . . . . . . . . . . . . 391 Nested Tags . . . . . . . . . . . . . 444
Example . . . . . . . . . . . . . . 391 Example . . . . . . . . . . . . . . 445
PANDEF (Panel Default) . . . . . . . . . 392 SL (Simple List) . . . . . . . . . . . . 447
Description . . . . . . . . . . . . . 395 Description . . . . . . . . . . . . . 448
Conditions . . . . . . . . . . . . . 396 Conditions . . . . . . . . . . . . . 448
Nested Tags . . . . . . . . . . . . . 396 Nested Tags . . . . . . . . . . . . . 448
Example . . . . . . . . . . . . . . 396 Example . . . . . . . . . . . . . . 448
PANEL (Panel) . . . . . . . . . . . . . 397 SOURCE (Source) . . . . . . . . . . . . 449
Description . . . . . . . . . . . . . 405 Description . . . . . . . . . . . . . 450
Conditions . . . . . . . . . . . . . 405 Conditions . . . . . . . . . . . . . 450
Nested Tags . . . . . . . . . . . . . 406 Nested Tags . . . . . . . . . . . . . 450
Example . . . . . . . . . . . . . . 406 Example . . . . . . . . . . . . . . 451
PARML (Parameter List). . . . . . . . . . 408 T (Truncation) . . . . . . . . . . . . . 451
Description . . . . . . . . . . . . . 408 Description . . . . . . . . . . . . . 451

Contents vii
 Conditions . . . . . . . . . . . . . 452 Description . . . . . . . . . . . . . 466
Nested Tags . . . . . . . . . . . . . 452 Conditions . . . . . . . . . . . . . 466
Example . . . . . . . . . . . . . . 452 Nested Tags . . . . . . . . . . . . . 466
| TEXTLINE (Text Line) . . . . . . . . . . 452 Example . . . . . . . . . . . . . . 467
| Description . . . . . . . . . . . . . 453 WARNING (Warning) . . . . . . . . . . 468
| Conditions . . . . . . . . . . . . . 453 Description . . . . . . . . . . . . . 468
| Nested Tags . . . . . . . . . . . . . 453 Conditions . . . . . . . . . . . . . 468
| Example . . . . . . . . . . . . . . 453 Nested Tags . . . . . . . . . . . . . 468
| TEXTSEG (Text Segment) . . . . . . . . . 453 Example . . . . . . . . . . . . . . 469
| Description . . . . . . . . . . . . . 453 XLATI (Translate Item) . . . . . . . . . . 470
| Conditions . . . . . . . . . . . . . 454 Description . . . . . . . . . . . . . 470
| Nested Tags . . . . . . . . . . . . . 454 Conditions . . . . . . . . . . . . . 471
| Example . . . . . . . . . . . . . . 454 Nested Tags . . . . . . . . . . . . . 471
TOPINST (Top Instruction) . . . . . . . . . 455 Example . . . . . . . . . . . . . . 471
Description . . . . . . . . . . . . . 455 XLATL (Translate List) . . . . . . . . . . 472
Conditions . . . . . . . . . . . . . 455 Description . . . . . . . . . . . . . 472
Nested Tags . . . . . . . . . . . . . 456 Conditions . . . . . . . . . . . . . 473
Example . . . . . . . . . . . . . . 456 Nested Tags . . . . . . . . . . . . . 473
UL (Unordered List) . . . . . . . . . . . 457 Example . . . . . . . . . . . . . . 473
Description . . . . . . . . . . . . . 458 XMP (Example). . . . . . . . . . . . . 474
Conditions . . . . . . . . . . . . . 458 Description . . . . . . . . . . . . . 474
Nested Tags . . . . . . . . . . . . . 458 Conditions . . . . . . . . . . . . . 474
Example . . . . . . . . . . . . . . 458 Nested Tags . . . . . . . . . . . . . 474
VARCLASS (Variable Class) . . . . . . . . 459 Example . . . . . . . . . . . . . . 475
Description . . . . . . . . . . . . . 461
Conditions . . . . . . . . . . . . . 462
Nested Tags . . . . . . . . . . . . . 462
Part 3. Appendixes . . . . . . . . 477
Example . . . . . . . . . . . . . . 462
VARDCL (Variable Declaration) . . . . . . . 463 Appendix. Dialog Tag Language (DTL)
Description . . . . . . . . . . . . . 463 Tags . . . . . . . . . . . . . . . 479
Conditions . . . . . . . . . . . . . 463 Tag Summary . . . . . . . . . . . . . 479
Nested Tags . . . . . . . . . . . . . 463
Example . . . . . . . . . . . . . . 463 Notices . . . . . . . . . . . . . . 505
VARLIST (Variable List) . . . . . . . . . . 464 Programming Interface Information . . . . . . 506
Description . . . . . . . . . . . . . 464 Trademarks . . . . . . . . . . . . . . 506
Conditions . . . . . . . . . . . . . 464
Nested Tags . . . . . . . . . . . . . 465
Index . . . . . . . . . . . . . . . 509
Example . . . . . . . . . . . . . . 465
VARSUB (Variable Substitution) . . . . . . . 466

viii OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Figures
1. Panel with an Action Bar Pull-Down Menu xxv 54. Nested Ordered Lists . . . . . . . . . 124
2. Pop-Up Selected from an Action Bar 55. Definition List . . . . . . . . . . . 125
Pull-Down . . . . . . . . . . . . xxvi 56. Definition List (BREAK=ALL) . . . . . . 127
3. Panel with an Action Bar and 57. Definition List (BREAK=FIT) . . . . . . 128
Point-and-Shoot Fields . . . . . . . . xxvi 58. Parameter List . . . . . . . . . . . 129
4. An Unavailable Choice on a Pull-Down xxvii 59. Nested Paragraph within a List . . . . . 130
5. Application Panel . . . . . . . . . . . 6 60. List Part . . . . . . . . . . . . . 131
6. Help Panel . . . . . . . . . . . . . 7 61. Nested Unordered List in a Definition List 131
7. Message Displayed in Message Area . . . . 8 62. Note (NOTE tag) . . . . . . . . . . 133
8. Entity Reference for Text Substitution . . . . 19 63. Notel (NOTEL tag). . . . . . . . . . 134
9. Entity Reference for Text Substitution . . . . 20 64. Note (NT tag) . . . . . . . . . . . 135
10. Entity Reference for Text Substitution and File 65. Warning . . . . . . . . . . . . . 136
Embedding . . . . . . . . . . . . 21 66. Caution . . . . . . . . . . . . . 137
11. Parameter Entities . . . . . . . . . . 23 67. Highlighted Phrase Example . . . . . . 139
12. Cursor Placement . . . . . . . . . . 31 68. Reference Phrase Example . . . . . . . 140
13. Action Bar and Pull-Down . . . . . . . 35 69. Reference Phrase Example of Help Attribute 141
14. Preselected Pull-Down Choice . . . . . . 39 70. Information Region . . . . . . . . . 142
15. Top and Bottom Instructions . . . . . . . 40 71. Help Panel . . . . . . . . . . . . 144
16. AREA MARGINW=10 . . . . . . . . . 41 72. Help Panel (Example 1 of 4) . . . . . . 146
17. Scrollable Panel Area . . . . . . . . . 43 73. Help Panel (Example 2 of 4) . . . . . . 146
18. Application Panel Area. . . . . . . . . 43 74. Help Panel (Example 3 of 4) . . . . . . 146
19. Scrollable Panel Area . . . . . . . . . 44 75. Help Panel (Example 4 of 4) . . . . . . 147
20. Multiple Horizontal Areas . . . . . . . 45 76. Help Panel (Example 1 of 3) . . . . . . 148
21. Area Dividers . . . . . . . . . . . . 47 77. Help Panel (Example 2 of 3) . . . . . . 148
22. Vertical Region . . . . . . . . . . . 48 78. Help Panel (Example 3 of 3) . . . . . . 149
23. Horizontal Region . . . . . . . . . . 49 79. Data Field and Message . . . . . . . . 155
24. Horizontal Region . . . . . . . . . . 50 80. Displayed Function Key Area . . . . . . 165
25. Command Area . . . . . . . . . . . 52 81. Conversion Utility Invocation Panel
26. Command Area . . . . . . . . . . . 53 (ISPCP01) . . . . . . . . . . . . . 167
27. Variable Translation Results . . . . . . . 62 82. Conversion Utility Invocation Panel (Middle) 168
28. Variable Translation . . . . . . . . . . 63 83. Conversion Utility Invocation Panel . . . . 168
29. Variable Translation . . . . . . . . . . 65 84. Conversion Utility Invocation Panel . . . . 169
30. Variable Translation . . . . . . . . . . 65 85. Conversion Utility Invocation Panel (End) 169
31. Prompt Locations . . . . . . . . . . 78 86. Panel ISPCP04 . . . . . . . . . . . 174
32. Prompt Widths . . . . . . . . . . . 79 87. ISPF Dialog Tag Language Conversion Utility
33. Data Fields. . . . . . . . . . . . . 81 - Confirm Cancel . . . . . . . . . . 183
34. Data Field Description . . . . . . . . . 83 88. ISPF Dialog Tag Language Conversion Utility
35. Single-Choice Selection Field . . . . . . . 89 - Recursive invoke . . . . . . . . . . 184
36. Multiple-Choice Selection Field . . . . . . 91 89. Entities and Parameter Entities. . . . . . 197
37. Sample Option Menu . . . . . . . . . 92 90. Action Bar . . . . . . . . . . . . 204
38. Selection Field SELWIDTH Attribute . . . . 95 91. Action Bar Choices. . . . . . . . . . 206
39. Data Column . . . . . . . . . . . . 99 92. Application Panel Area . . . . . . . . 218
40. List Field . . . . . . . . . . . . . 101 93. Application Panel Area . . . . . . . . 218
41. List Group . . . . . . . . . . . . 102 94. Application Panel Area . . . . . . . . 219
42. Paragraph . . . . . . . . . . . . . 111 95. Attention Statement . . . . . . . . . 224
43. Multiple Paragraphs . . . . . . . . . 112 96. Bottom Instructions . . . . . . . . . 230
44. Headings (H1-H2) . . . . . . . . . . 113 97. Caution Statement . . . . . . . . . . 232
45. LINES . . . . . . . . . . . . . . 114 98. Choice Divider . . . . . . . . . . . 234
46. XMP . . . . . . . . . . . . . . 115 99. Choice Data Fields . . . . . . . . . . 251
47. Figure with Rules . . . . . . . . . . 116 100. Selection Field Choices . . . . . . . . 259
48. Figure Caption . . . . . . . . . . . 117 101. Command Area . . . . . . . . . . . 270
49. Simple List . . . . . . . . . . . . 118 102. Comment text added to a panel . . . . . 274
50. Compact Simple List . . . . . . . . . 119 103. Copyright statement added to a panel 277
51. Unordered List . . . . . . . . . . . 120 104. Definition Descriptions . . . . . . . . 284
52. Nested Unordered Lists . . . . . . . . 122 105. Definition Description Header . . . . . . 285
53. Ordered List . . . . . . . . . . . . 122 106. Area Dividers . . . . . . . . . . . 288

© Copyright IBM Corp. 1989, 2000 ix

 107. Definition List (BREAK=NONE) . . . . . 290 135. Messages . . . . . . . . . . . . . 380
108. Definition List (BREAK=FIT) . . . . . . 291 136. Message Member . . . . . . . . . . 382
109. Definition List (BREAK=ALL) . . . . . . 291 137. Note . . . . . . . . . . . . . . 383
110. Definition Terms . . . . . . . . . . 293 138. NOTEL . . . . . . . . . . . . . 385
111. Data Column . . . . . . . . . . . 299 139. NT . . . . . . . . . . . . . . . 387
112. Data Fields . . . . . . . . . . . . 309 140. Ordered Lists . . . . . . . . . . . 390
113. Data Field Descriptions . . . . . . . . 311 141. Paragraphs . . . . . . . . . . . . 392
114. Definition Term Header . . . . . . . . 312 142. Application Panel . . . . . . . . . . 407
115. Figure . . . . . . . . . . . . . . 314 143. Parameter List . . . . . . . . . . . 410
116. Figure Caption . . . . . . . . . . . 316 144. Parameter Descriptions . . . . . . . . 412
| 117. Generated Panel . . . . . . . . . . 320 145. Pull-Down Choices . . . . . . . . . 416
118. Group Heading . . . . . . . . . . . 323 146. Pull-Down Separator . . . . . . . . . 417
119. Help Panel (Example 1 of 3) . . . . . . 331 147. Panel Instructions . . . . . . . . . . 419
120. Help Panel (Example 2 of 3) . . . . . . 331 148. Point-and-Shoot Fields . . . . . . . . 422
121. Help Panel (Example 3 of 3) . . . . . . 331 149. Parameter Terms . . . . . . . . . . 423
122. Headings . . . . . . . . . . . . . 336 150. Regions . . . . . . . . . . . . . 429
123. HP (Highlighted Phrase) . . . . . . . . 338 151. Using WIDTH and DEPTH Attributes 430
124. Information Region . . . . . . . . . 340 152. Reference Phrase Example . . . . . . . 432
125. Key Items. . . . . . . . . . . . . 344 153. Reference Phrase Example . . . . . . . 432
126. Function Keys . . . . . . . . . . . 346 154. Selection Fields . . . . . . . . . . . 446
127. List Items . . . . . . . . . . . . . 349 155. Selection Menu . . . . . . . . . . . 447
128. LINES . . . . . . . . . . . . . . 351 156. Simple List . . . . . . . . . . . . 449
129. List Part . . . . . . . . . . . . . 354 157. Top Instructions. . . . . . . . . . . 457
130. List Columns . . . . . . . . . . . 363 158. Unordered List . . . . . . . . . . . 459
131. List Columns . . . . . . . . . . . 364 159. Variable Substitution . . . . . . . . . 467
132. List Field . . . . . . . . . . . . . 368 160. Warning Statement. . . . . . . . . . 469
133. List Group . . . . . . . . . . . . 371 161. Example . . . . . . . . . . . . . 475
134. List Variable . . . . . . . . . . . . 374

x OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 Preface
This book describes how to use the Dialog Tag Language (DTL), the tag-based
markup language you use to create the following ISPF dialog elements:
v Application panels
v Help panels
v Application command tables
v Messages
v Key lists.

It also explains how to use the ISPF conversion utility to convert the source files
that contain DTL markup into ISPF panel language source or execution time
format.

About This Book

This book is organized into two sections:
v Part 1 guides you through the steps involved in using the Dialog Tag Language
for designing, defining, and converting dialog elements for ISPF applications.
v Part 2 provides an alphabetical reference of the Dialog Tag Language tags and
markup declarations.

Who Should Use This Book

This book is for ISPF application developers who want to use the Dialog Tag
| Language (DTL) to create dialog elements for ISPF applications.

© Copyright IBM Corp. 1989, 2000 xi

xii OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
|

| Summary of Changes
| OS/390 V2R10.0 ISPF contains the following changes and enhancements:
| v ISPF Product and Library Changes
| v ISPF Dialog Manager Component Changes
| v ISPF PDF Component Changes
| v ISPF SCLM Component Changes
| v ISPF Client/Server Component Changes
|
| ISPF Product Changes
| Changes to the ZENVIR variable. Characters 1 through 8 contain the product name
| and sequence number in the format ISPF x.y, where x.y indicates:
| v <= 4.2 means the version.release of ISPF
| v = 4.3 means ISPF for OS/390 release 2
| v = 4.4 means ISPF 4.2.1 and ISPF for OS/390 release 3
| v = 4.5 means ISPF for OS/390 Version 2 Release 5.0
| v = 4.8 means ISPF for OS/390 Version 2 Release 8.0
| v = 5.0 means ISPF for OS/390 Version 2 Release 10.0
| The ZENVIR variable is used by IBM personnel for internal purposes. The x.y
| numbers DO NOT directly correlate to an ISPF release number in all cases. For
| example, as shown above, a ZENVIR value of 4.3 DOES NOT mean ISPF Version 4
| Release 3. NO stand-alone version of ISPF exists above ISPF Version 4 Release 2
| Modification 1.

| The ZOS390RL variable contains the OS/390 release on your system.

| The ZISPFOS system variable contains the level of ISPF code that is running as
| part of the OS/390 release on your system. This might or might not match
| ZOS390RL. For this release, the variable contains ISPF for OS/390 Version 2
| Release 10.0.

| New system variables:

| ZBDMAX
| BDISPMAX value
| ZBDMXCNT
| Count of current displays in batch mode session
| ZPANELID
| Name of currently displayed panel
| ZSCREENI
| Logical screen data
| ZSCREENC
| Cursor position within the logical screen data

| The ISRDDN utility is now documented in the ISPF User’s Guide.

© Copyright IBM Corp. 1989, 2000 xiii

|
| ISPF DM Component Changes
| The DM component of ISPF includes the following new functions and
| enhancements:
| v Additional support for panel process:
| – Support added for ″verify data set name with filter, (DSNAMEF)″.
| – Support added for ″verify data set name with filter with member,
| (DSNAMEFM)″.
| – Support added for ″verify data set name with quotes and parentheses,
| (DSNAMEPQ)″.
| – Support added for ″verify name with filter, (NAMEF)″.
| – Support added for ″verify specific constants within a variable, (PICTCN,
| string)″.
| – Support added for ″verify international format date, (IDATE)″.
| – Support added for ″verify standard date, (STDDATE)″.
| – Support added for ″verify Julian date, (JDATE)″.
| – Support added for ″verify Julian standard date, (JSTD)″.
| – Support added for ″verify international time, (ITIME)″.
| – Support added for ″verify standard time, (STDTIME)″.
| – Support added for NOJUMP attribute keyword.
| – Support added to allow INTENS(NON) on LI, LID, VOI and LEF attribute
| types.
| – Update )HELP section processing to support variables for keyword values
| and two new keywords MSG(message-name) and PASSTHRU.
| v Support added for STKADD keyword on LIBDEF service.
| v New QBASELIB service to query base libraries.
| v Add Panel Id to CUAATTR utility.
| v Add support for starting a new screen or application from the ISPF Task List
| panel.
| v Add support for command CMDE which provides ability to expand command
| line if more room is required for the command.
| v Add support to allow ISPF panel exits to be written in REXX.
| v Add support for ZSCREENI and ZSCREENC variables to retrieve data from the
| logical screen at the cursor position.
| v Add a field to the ISPF configuration table for the default language.
| v Add fields to the ISPF configuration table to allow customization of the ISPF
| temporary data sets.
| v Add a field to the ISPF configuration table for the default ISPF panel used
| when invoking ISPF.
| v Pass the screen name to the SELECT Service Start and End and DISPLAY
| Installation exits.
| v Update various ISPF messages with additional information. For example, a
| better message will be displayed when the user’s profile is out of space, and the
| data set name and abend code will be added to the error message displayed as a
| result of an abend when opening a data set.

| ISPDTLC enhancements:

| ISPDTLC changes include new invocation options, new tags, and new tag.
| attributes as ISPF extensions to the Dialog Tag Language.

| General improvements:

xiv OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
| v A new option has been added to the interactive invocation panel, the
| DISPLAY(W) option check interval. This option controls the display frequency of
| a control panel for the DISPLAY and DISPLAYW options. The control panel
| choices are to continue, cancel the DISPLAY(W) option, or change the interval
| for the display of the control panel.
| v New tags:
| – GENERATE
| – TEXTLINE
| – TEXTSEG
| v Remove obsolete OS/2 DM compatibility and ISPF DTL extension messages for
| OS/390 V3.
| v Add support for Tutorial selection panel ZSEL generation via ACTION tags.
| v Revise member list processing to behave more like SUPERC by leaving the ″S″
| code in the member selection field. Members can be deselected by removing the
| ″S″ before using PF3 to run the requested members.
| v REQ70311 - Provide a user cancel/reset for the DISPLAY and DISPLAYW
| invoke options. A new panel - ISPCP08 - will display every nn (1 default) panels
| to allow the user to cancel or continue the display processing.
| v Expand the interactive panel to 16 DTL source files.
| v Expand the HELP attribute on tags for field level help to support the ISPF
| enhancement for MSG(message-ID) and PASSTHRU. HELP values can be: NO,
| YES, help-panel-name, *message-id, %varname, or *%varname. The ″*″ prefix
| defines a message-id.
| New or changed tag attributes:
|| Tag name Attribute update

| ATTR Add ATTN

| CHECKI Add support for ″VER(&variable, DSNAMEF)″

| Add support for ″VER(&variable, DSNAMEFM)″
| Add support for ″VER(&variable, DSNAMEPQ)″
| Add support for ″VER(&variable, NAMEF)″
| Add support for ″VER(&variable, PICTCN, ...)″
| Add support for ″VER(&variable, IDATE)″
| Add support for ″VER(&variable, STDDATE)″
| Add support for ″VER(&variable, JDATE)″
| Add support for ″VER(&variable, JSTD)″
| Add support for ″VER(&variable, ITIME)″
| Add support for ″VER(&variable, STDTIME)″

| CHOFLD Add ATTRCHAR and CAPS

| Support HELP for: YES, *message-id, *%varname

| CHOICE Add AUTOSEL

| Support HELP for: YES, *message-id, *%varname

| CMDAREA Add CAPS, NOJUMP, and SCRCAPS

| Support HELP for: YES, *message-id, *%varname
| Support SCRVHELP for: YES, *message-id, *%varname

| DA Add HELP and SCRCAPS

| Support SCRVHELP for: YES, *message-id, *%varname

| DTACOL Add VARCLASS, REQUIRED, and CAPS

Summary of Changes xv
| Tag name Attribute update

| DTAFLD Add ATTRCHAR, CAPS, and NOJUMP

| Support HELP for: YES, *message-id, *%varname
| Support DISPLAY=NO on CUA output fields

| FIG Add NOSKIP

| GRPHDR Add INDENT

| LI Add NOSKIP

| LINES Add NOSKIP

| LP Add NOSKIP

| LSTCOL Add CAPS and DISPLAY

| Support HELP for: YES, *message-id, *%varname

| LSTFLD Add SCRCAPS

| Support HELP for: YES, *message-id, *%varname

| MSG Add FORMAT

| Support HELP =*

| MSGMBR Add WIDTH

| PANEL Add ERRORCHECK

| SELFLD Support TYPE=TUTOR

| Support HELP for: YES, *message-id, *%varname

| XMP Add NOSKIP

|
|
| ISPF PDF Component Changes
| The ISPF PDF component contains the following new functions and enhancements:
| v An Edit settings dialog is now available via the EDSET and EDITSET primary
| commands as well as from the Edit_Setting pulldown choice when editing data.
| This enables the user to change:
| – the line that Edit positions the target of a FIND, CHANGE or EXCLUDE
| command.
| – whether or not the Editor always scrolls the target of a FIND, CHANGE, or
| EXCLUDE command to the target line specified.
| – the user session initial macro, a macro to be run whenever an edit session is
| started.
| – the maximum storage allowed for Edit.
| – Confirm Cancel/Move/Replace.
| – Preserve VB record length.
| v The Edit COMPARE command will now compare your current Edit session
| against another data set without requiring a SAVE.
| v The Edit COMPARE parameter SESSION or * will compare your current Edit
| data against the data saved on disk.
| v The Edit COMPARE command can be issued while editing an uncataloged data
| set to compare members within the same data set.
| v The new MEMLIST service provides an interface into ISPF option 3.1, providing
| all the built-in commands available from option 3.1.

xvi OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
| v A new option in the ISPF Configuration Table dialog provides the automatic
| creation of a ++USERMOD for the configuration data.
| v The new DSINFO service will return information about a specified data set in
| dialog variables.
| v The Editor will no longer append a 1 character blank to variable length records
| that are 8 bytes in length.
| v An ISPF Configuration option was added to disallow wildcards in the high level
| qualifier of option 3.4.
| v The SuperC utility now supports an ALLMEMS option to enable compares of all
| members including alias entries without member selection.
| v The primary and secondary quantity for the SuperC LIST and UPDATE data sets
| can be configured.
| v Allow use of the SYSOUT field when doing a local print from option 3.6.
| v Add an OPTION(DELETE) to the LMMDISP service to delete a member of the
| displayed list.
| v Update the edit macro command DATASET to also return the data set from
| which the member being edited was found.
| v Add a new dialog service called VIIF (View Interface service) which provides
| View function for the EDIF environment.
| v Add an edit macro command LINE_STATUS which indicates whether a line of
| data has been changed during the edit session, and if so, how.
| v Add additional keywords that can be specified in the expiration date field when
| creating a data set to indicate permanent retention: 9999, NEVER, NOLIMIT and
| PERM.
| v Add a new option in the ISPF Configuration Table dialog to allow disabling all
| ENQ displays. This option indicates whether or not users should be able to see
| who has existing data set ENQs when they press the help key or when they use
| the ISRDDN utility.
| v The LMINIT service specified with the DDNAME parameter will now handle
| DDNAMEs with up to 16 concatenated data sets. The DATAID generated by the
| LMINIT can then be passed to services such as EDIT and BROWSE to process
| members in any of the 16 data sets.
|
| ISPF SCLM Component Changes
| The ISPF SCLM component contains the following new functions and
| enhancements:
| v Additional/modified SCLM Services:
| – An AUTHCODE service to update authorization codes has been added.
| – A NEXTGRP service to return the promote target for a given group.
| – The MIGRATE service will now allow the DATE/TIME of the member to be
| set by the caller.
| – The MIGRATE service will now be supported via the FLMLNK interface.
| – The MIGRATE service has a new report output and associated specification
| on the service call (default is to go to the terminal).
| – The FLMCMPLB macro has been deleted. Any projects using FLMCMPLB
| currently must be recoded to use: FLMSYSLB dsn,INCLS=COMPOOL.
| v Additional exit points have been added:
| – At edit start and when the SPROF command is invoked.
| – When data is saved (Edit SAVE, Migrate, etc.).

Summary of Changes xvii

| – After the NOTIFY step of a DELETE.
| – After the VERIFY step of a DELETE.
| – After the VERIFY step of a BUILD.
| v The Versioning Utility will now allow a SuperC COMPARE of versions to be
| done.
| v The Versioning Utility will capture output members, in addition to editable
| types.
| v Workstation commands can now be used from translators running during a
| PROMOTE in batch mode.
| v SCLM will now display dates in 4-character year format.
| v The NRETRIEV command is now supported for SCLM.
| v Added the ability to specify separate VERCOUNT values for each group/type
| combination.
| v Additional samples:
| – A sample interface into ServiceDesk for OS/390 to show how a change
| management system can be integrated into SCLM.
| – An Edit autoflagger to automatically flag changed lines.
| – A versioning delete sample.
|
| ISPF Client/Server Component Changes
| The ISPF Client/Server Component enables a panel to be displayed unchanged
| (except for panels with graphic areas) at a workstation using the native display
| function of the operating system of the workstation. ISPF manuals call this
| ″running in GUI mode.″

| There are no changes to the ISPF Client/Server for this release.

|
| ISPF User Interface Considerations
| Many changes have been made to the ISPF Version 4 user interface to conform to
| CUA guidelines. If you prefer to change the interface to look and act more like the
| Version 3 interface, you can do the following:
| v Use the CUAATR command to change the screen colors
| v Use the ISPF Settings panel to specify that the TAB or HOME keys position the
| cursor to the command line rather than to the first action bar item
| v Set the command line to the top of the screen by deselecting Command line at
| bottom on the ISPF Settings panel
| v Set the primary keys to F13–24 by selecting 2 for Primary range on the Tailor
| Function Key Definition Display panel
| v Use the KEYLIST OFF command to turn keylists off
| v Use the PSCOLOR command to change point-and-shoot fields to blue.
| v Change the DFLTCOLR field in the PDF configuration table ISRCONFG to
| disable action bars and or edit highlighting
|
| ISPF Migration Considerations
| When migrating to OS/390 V2R8.0 or higher for the first time, you must convert
| your ISPF customization to the new format. Refer to the section entitled The ISPF
| Configuration Table in the ISPF Planning and Customizing manual.

xviii OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
| When migrating from one version of ISPF to another, you must be sure to
| reassemble and re-link the SCLM project definition.

| ISPF Profiles
| Major changes were made to the ISPF profiles for ISPF Version 4.2 and OS/390
| Version 1 Release 1.0 ISPF. The profiles for ISPF Version 3 and the profiles for
| OS/390 ISPF are not compatible. If you are moving back and forth between an
| ISPF Version 3 system and OS/390 V1R1.0 or higher system, you must run with
| separate profiles. Profiles for OS/390 V1R1.0 and higher are compatible with each
| other.

| Year 2000 Support for ISPF

| ISPF is fully capable of using dates for the year 2000 and beyond. All of your
| existing applications should continue to run (some may need minor changes, as
| explained below) when the year 2000 comes. The base support for the year 2000
| was added to OS/390 Version 1 Release 2.0, but the same level of support is
| available for ISPF Version 3.5, ISPF Version 4, and OS/390 Version 1 Release 1.0 as
| well. To get support for the earlier versions, be sure that your system has the
| correct APARs installed. All ISPF APARs that add or correct function relating to the
| year 2000 contain the YR2000 identifier in the APAR text. You should search for
| these APARs to ensure you have all the function available.

| What function is included?

| v ISPF Dialog variable ZSTDYEAR now correctly shows the year for dates past
| 1999. Earlier versions always showed the first 2 characters of the year as 19.
| v A new ISPF dialog variable (ZJ4DATE) is available for Julian dates with a 4–digit
| year.
| v An ISPF Configuration Table field enables PDF to interpret 2 character year
| dates as either a 19xx or 20xx date. The default value is 65. Any 2-character year
| date whose year is less than or equal to this value is considered a 20xx date,
| anything greater than this value is considered 19xx. To see what value has been
| set by the ISPF Configuration Table, use the new ZSWIND variable.
| v New parameters in the LMMSTATS service (CREATED4 and MODDATE4) for
| specifying 4-character year dates. All existing parameters still exist and you can
| continue to use them. If both the 2-character year date parameters (CREATED
| and MODDATE) and the 4-character year date parameters (CREATED4 and
| MODDATE4) are specified, the 2-character versions are used.
| v Dialog variables ZLC4DATE and ZLM4DATE have been added.
| – You can set them before making an LMMREP or LMMADD call. Do this to
| specify a 4-character created or last modified date to set in the ISPF statistics.
| – They are set by LMMFIND, LMMLIST and LMMDISP to the current value of
| the created and last modified dates in the ISPF statistics.

| What might need to change? Some minor changes to your existing ISPF dialogs
| might be necessary, especially in ISPF dialogs that use the Library Access Services
| to manipulate ISPF member statistics.
| v For those services that accept both 4-character year dates and 2-character year
| dates, you can specify one or the other. If you specify both, the 2-character year
| date is used to avoid affecting existing dialogs. When the 2-character year date is
| used, the configuration table field mentioned above is used to determine
| whether the date should be interpreted as 19xx or 20xx.

Summary of Changes xix

| v ISPF will not necessarily show 4-character dates in all circumstances but it will
| process them correctly. For example, a member list might only display
| 2-character year dates but will sort those dates in the proper order.
| v SCLM stores dates past the year 1999 in a new internal format. If an accounting
| file contains dates in this new format, it cannot be processed by a system
| without year 2000 support. Accounting files without dates past 1999 can be
| processed with or without the year 2000 support.
| v No conversion of the LMF control file is necessary.

xx OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

|

What’s in the OS/390 V2R10.0 ISPF library?

You can order the ISPF books using the numbers provided below.

OS/390 V2R10.0 ISPF

Title Order Number
OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference SC28-1219-04
OS/390 V2R10.0 ISPF Planning and Customizing SC28-1298-04
OS/390 V2R10.0 ISPF User’s Guide Volume I SC34-4791-00
OS/390 V2R10.0 ISPF User’s Guide Volume II SC34-4792-00
OS/390 V2R10.0 ISPF Services Guide SC28-1272-04
OS/390 V2R10.0 ISPF Dialog Developer’s Guide and Reference SC28-1273-04
OS/390 V2R10.0 ISPF Reference Summary SC28-1308-04
OS/390 V2R10.0 ISPF Edit and Edit Macros SC28-1312-04
OS/390 V2R10.0 ISPF Library Management Facility SC28-1317-04
OS/390 V2R10.0 ISPF Messages and Codes GC28-1326-04
OS/390 V2R10.0 ISPF Software Configuration and Library Manager SC34-4750-02
Project Manager’s and Developer’s Guide
OS/390 V2R10.0 ISPF Software Configuration and Library Manager SC28-1320-04
Reference
Entire library Bill of Forms SBOF-8564-00

The licensed books that were declassified in OS/390 Version 2 Release 4 appear on
the OS/390 Online Library Collection, SK2T-6700.

The remaining licensed books for OS/390 Version 2 appear on the OS/390
Licensed Product Library, LK2T-2499, in unencrypted form.

© Copyright IBM Corp. 1989, 2000 xxi

xxii OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
The ISPF User Interface
ISPF provides an action bar-driven interface that exploits many of the usability
features of Common User Access (CUA) interfaces. Refer to Object-Oriented Interface
Design: IBM Common User Access Guidelines for additional information.

The panels look different than in Version 3: all screens are in mixed case, and most
have action bars at the top. These action bars give you a new way to move around
in the product as well as access to command nesting. Command nesting allows
you to suspend an activity while you perform a new one rather than having to end
a function to perform another function.

This chapter primarily explains the action bar-driven interface and the use of
ISPF’s graphical user interface (GUI).

Some Terms You Should Know

The following terms are used in this book:

action bar. The area at the top of an ISPF panel that contains choices that give you access to actions available on
that panel. When you select an action bar choice, ISPF displays a pull-down menu.

pull-down menu. A list of numbered choices extending from the selection you made on the action bar. The action
bar selection is highlighted; for example, Utilities in Figure 1 on page xxv appears highlighted on your screen. You
can select an action either by typing in its number and pressing Enter or by selecting the action with your cursor.
ISPF displays the requested panel. If your choice contains an ellipsis (...), ISPF displays a pop-up window. When you
exit this panel or pop-up, ISPF closes the pull-down and returns you to the panel from which you made the initial
action bar selection.

ellipsis. Three dots that follow a pull-down choice. When you select a choice that contains an ellipsis, ISPF displays
a pop-up window.

pop-up window. A bordered temporary window that displays over another panel.

modal pop-up window. A type of window that requires you to interact with the panel in the pop-up before
continuing. This includes cancelling the window or supplying information requested.

modeless pop-up window. A type of window that allows you to interact with the dialog that produced the pop-up
before interacting with the pop-up itself.

point-and-shoot text. Text on a screen that is cursor-sensitive. See “Point-and-Shoot Text Fields” on page xxviii for
more information.

push button. A rectangle with text inside. Push buttons are used in windows for actions that occur immediately
when the push button is selected (available only when you are running in GUI mode).

function key. In previous releases of ISPF, a programmed function (PF) key. This is a change in terminology only.

select. In conjunction with point-and-shoot text fields and action bar choices, this means moving the cursor to a
field and simulating Enter.

mnemonics. Action bar choices can be defined with a underscored letter in the action bar choice text. In host mode
you can access the action bar choice with the ACTIONS command and parameter ’x’, where ’x’ is the underscored
letter in the action bar choice text. In GUI mode you can use a hot key to access a choice on the action bar; that is,
you can press the ALT key in combination with the letter that is underscored in the action bar choice text.

© Copyright IBM Corp. 1989, 2000 xxiii

The ISPF User Interface

How to Navigate in ISPF without Using Action Bars

If you use a non-programmable terminal to access OS/390 V2R10.0 ISPF and you
do not want to take advantage of the command nesting function, you can make
selections the same way you always have: by typing in a selection number and
pressing Enter.

How to Navigate in ISPF Using the Action Bar Interface

Most ISPF panels have action bars at the top; the choices appear on the screen in
white by default. Many panels also have point-and-shoot text fields, which appear
in turquoise by default. The panel shown in Figure 3 on page xxvi has both.

Action Bars
Action bars give you another way to move through ISPF. If the cursor is located
somewhere on the panel, there are several ways to move it to the action bar:
v Use the cursor movement keys to manually place the cursor on an action bar
choice.
v Type ACTIONS on the command line and press Enter to move the cursor to the
first action bar choice.
v Press F10 (Actions) or the Home key to move the cursor to the first action bar
choice.
If mnemonics are defined for action bar choices, you can:
– In 3270 mode, on the command line, type ACTIONS and the mnemonic letter
that corresponds to an underscored letter in the action bar choice text. This
results in the display of the pull-down menu for that action bar choice.
– In 3270 mode, on the command line enter the mnemonic letter that
corresponds to an underscored letter in the action bar choice text, and press
the function key assigned to the ACTIONS command. This results in the
display of the pull-down menu for that action bar choice.
– In GUI mode, you can use a hot key to access a choice on an action bar or on
a pull-down menu; that is, you can press the ALT key in combination with
the mnemonic letter that is underscored in the choice text to activate the text.
Use the tab key to move the cursor among the action bar choices. If you are
running in GUI mode, use the right and left cursor keys.
Notes:
1. ISPF does not provide a mouse emulator program. This book uses select in
conjunction with point-and-shoot text fields and action bar choices to mean
moving the cursor to a field and simulating Enter.

Note: Some users program their mouse emulators as follows:

v Mouse button 1 – to position the cursor to the pointer and simulate
Enter
v Mouse button 2 – to simulate F12 (Cancel).
2. If you want the Home key to position the cursor at the first input field on an
ISPF panel, type SETTINGS on any command line and press Enter to display the
ISPF Settings panel. Deselect the Tab to action bar choices option.
3. If you are running in GUI mode, the Home key takes you to the beginning of
the current field.

xxiv OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 The ISPF User Interface
When you select one of the choices on the action bar, ISPF displays a pull-down
menu. Figure 1 shows the pull-down menu displayed when you select Utilities on
the ISPF Primary Option Menu action bar.

«1¬ The selected action bar choice is highlighted.

Figure 1. Panel with an Action Bar Pull-Down Menu

To select a choice from the Utilities pull-down menu, type its number in the entry
field (underlined) and press Enter or select the choice. To cancel a pull-down menu
without making a selection, press F12 (Cancel). For example, if you select choice
9, ISPF displays the Command Table Utility pop-up, as shown in Figure 2 on
page xxvi.

Note: If you entered a command on the command line prior to selecting an action
bar choice, the command is processed, and the pull-down menu is never
displayed. The CANCEL, END, and RETURN commands are exceptions.
These three commands are not processed and the cursor is repositioned to
the first input field in the panel body. If there is no input field, the cursor is
repositioned under the action bar area. If you are running in GUI mode and
select an action bar choice, any existing command on the command line is
ignored.

The ISPF User Interface xxv

The ISPF User Interface

Figure 2. Pop-Up Selected from an Action Bar Pull-Down

«1¬ Action bar. You can select any of the action bar choices and display a pull-down.
«2¬ Options. The fields in this column are point-and-shoot text fields.
«3¬ Dynamic status area. You can specify what you want to be displayed in this area.

Figure 3. Panel with an Action Bar and Point-and-Shoot Fields

xxvi OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 The ISPF User Interface
Action Bar Choices
The action bar choices available vary from panel to panel, as do the choices
available from their pull-downs. However, Menu and Utilities are basic action bar
choices, and the choices on their pull-down menus are always the same.

Menu Action Bar Choice

The following choices are available from the Menu pull-down:
Settings Displays the ISPF Settings panel
View Displays the View Entry panel
Edit Displays the Edit Entry panel
ISPF Command Shell Displays the ISPF Command Shell panel
Dialog Test... Displays the Dialog Test Primary Option panel
Other IBM Products... Displays the Additional IBM Program
Development Products panel
SCLM Displays the SCLM Main Menu
ISPF Workplace Displays the Workplace entry panel
Status Area... Displays the ISPF Status panel
Exit Exits ISPF.

Note: If a choice displays in blue (the default) with an asterisk as the first digit of
the selection number (if you are running in GUI mode, the choice will be
grayed), the choice is unavailable for one of the following reasons:
v Recursive entry is not permitted here
v The choice is the current state; for example, RefMode is currently set to
Retrieve in Figure 4.

Figure 4. An Unavailable Choice on a Pull-Down

The ISPF User Interface xxvii

The ISPF User Interface
Utilities Action Bar Choice
The following choices are available from the Utilities pull-down:
Library Displays the Library Utility panel
Data Set Displays the Data Set Utility panel
Move/Copy Displays the Move/Copy Utility panel
Data Set List Displays the Data Set List Options panel
Reset Statistics Displays the Reset ISPF Statistics panel
Hardcopy Displays the Hardcopy Utility panel
Download... Displays the panel that enables you to download
workstation clients and other files from the host.
Outlist Displays the Outlist Utility panel
Commands... Displays the Command Table Utility panel
Reserved Reserved for future use by ISPF; an unavailable
choice
Format Displays the Format Specification panel
SuperC Displays the SuperC Utility panel
SuperCE Displays the SuperCE Utility panel
Search-for Displays the Search-For Utility panel.
Search-forE Displays the Search-ForE Utility panel.

Point-and-Shoot Text Fields

Point-and-shoot text fields are cursor-sensitive; if you select a field, the action
described in that field is performed. For example, if you select Option 0, Settings,
in Figure 3 on page xxvi, ISPF displays the ISPF Settings panel.

Note: If you have entered a command on the command line, this command is
processed before any point-and-shoot command unless you are running in
GUI mode.

The cursor-sensitive portion of a field often extends past the field name. Until you
are familiar with this new feature of ISPF, you might want to display these fields
in reverse video (use the PSCOLOR command to set Highlight to REVERSE).

Note: You can use the Tab key to position the cursor to point-and-shoot fields by
selecting the Tab to point-and-shoot fields option on the ISPF Settings panel
(Option 0).

Function Keys
ISPF uses CUA-compliant definitions for function keys F1–F12 (except inside the
Edit function). F13–F24 are the same as in ISPF Version 3. By default you see the
CUA definitions because your Primary range field is set to 1 (Lower - 1 to 12).

To use non-CUA-compliant keys, select the Tailor function key display choice
from the Function keys pull-down on the ISPF Settings (option 0) panel action bar.
On the Tailor Function Key Definition Display panel, specify 2 (Upper - 13 to 24)
in the Primary range field.

The following function keys help you navigate in ISPF:

F1 Help. Displays Help information. If you press F1 (and it is set to Help)
after ISPF displays a short message, a long message displays in a pop-up
window.
F2 Split. Divides the screen into two logical screens separated by a horizontal
line or changes the location of the horizontal line.

xxviii OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 The ISPF User Interface
Note: If you are running in GUI mode, each logical screen displays in a
separate window.
F3 Exit (from a pull-down). Exits the panel underneath a pull-down.
F3 End. Ends the current function.
F7 Backward. Moves the screen up the scroll amount.
F8 Forward. Moves the screen down the scroll amount.
F9 Swap. Moves the cursor to where it was previously positioned on the
other logical screen of a split-screen pair.
F10 Actions. Moves the cursor to the action bar. If you press F10 a second time,
the cursor moves to the command line.
F12 Cancel. Issues the Cancel command. Use this command to remove a
pull-down menu if you do not want to make a selection. F12 also moves
the cursor from the action bar to the Option ==> field on the ISPF Primary
Option Menu. See ISPF Dialog Developer’s Guide and Reference for
cursor-positioning rules.
F16 Return. Returns you to the ISPF Primary Option Menu or to the display
from which you entered a nested dialog. RETURN is an ISPF system
command.

Selection Fields
OS/390 V2R10.0 ISPF uses the following CUA-compliant conventions for selection
fields:
A single period (.)
Member lists that use a single period in the selection field recognize only a
single selection. For example, within the Edit function you see this on your
screen:
│EDIT USER1.PRIVATE.TEST ROW 00001 of 00002 │
│ Name VV MM Created Changed Size Init Mod ID │
│ . MEM1 01.00 94/05/12 94/07/22 40 0 0 USER1 │
│ . MEM2 01.00 94/05/12 94/07/22 30 0 0 KEENE │

You can select only one member to edit.

A single underscore (_)
Selection fields marked by a single underscore prompt you to use a slash
(/) to select the choice. You may use any non-blank character. For example,
the Panel display CUA mode field on the ISPF Settings panel has a single
underscore for the selection field:
Options
Enter "/" to select option
_ Command line at bottom
_ Panel display CUA mode
_ Long message in pop-up

Note: If you are running in GUI mode, this type of selection field displays
as a check box; that is, a square box with associated text that
represents a choice. When you select a choice, a check mark (in
OS/2) or an X (in Windows) appears in the check box to indicate
that the choice is in effect. You can clear the check box by selecting
the choice again.
An underscored field (____)
Member lists or text fields that use underscores in the selection field

The ISPF User Interface xxix

The ISPF User Interface
recognize multiple selections. For example, from the Display Data Set List
Option panel, you may select multiple members for print, rename, delete,
edit, browse, or view processing.

Command Nesting
Command nesting allows you to suspend an activity while you perform a new one
rather than having to end a function to perform another function. For example, in
previous versions of ISPF, if you are editing a data set and want to allocate another
data set, you type =3.2 on the command line and press Enter. ISPF ends your edit
session before taking you to the Data Set Utility panel. When you have allocated
the data set and want to return to your edit session, you type =2 and press Enter;
ISPF returns you to the Edit Entry Panel. With OS/390 V2R10.0 ISPF, from your
edit session, select the Data set choice from the Utilities pull-down on the Edit
panel action bar. ISPF suspends your edit session and displays the Data Set Utility
panel. When you have allocated the new data set and end the function, OS/390
V2R10.0 ISPF returns you directly to your edit session rather than to the Edit Entry
Panel.

xxx OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Elements and Features in OS/390
You can use the following table to see the relationship of a product you are
familiar with and how it is referred to in OS/390 Version 2 Release 10.0. OS/390
V2R10.0 is made up of elements and features that contain function at or beyond
the release level of the products listed in the following table. The table gives the
name and level of each product on which an OS/390 element or feature is based,
identifies the OS/390 name of the element or feature, and indicates whether it is
part of the base or optional. For more compatibility information about OS/390
elements see OS/390 Planning for Installation, GC28-1726

Product Name and Level Name in OS/390 Base or Optional

BookManager BUILD/MVS V1R3 BookManager BUILD optional
BookManager READ/MVS V1R3 BookManager READ base
MVS/Bulk Data Transfer V2 Bulk Data Transfer (BDT) base
MVS/Bulk Data Transfer File-to-File V2 Bulk Data Transfer (BDT) File-to-File optional
MVS/Bulk Data Transfer SNA NJE V2 Bulk Data Transfer (BDT) SNA NJE optional
IBM OS/390 C/C++ V1R2 C/C++ optional
DFSMSdfp V1R3 DFSMSdfp base
DFSMSdss DFSMSdss optional
DFSMShsm DFSMShsm optional
DFSMSrmm DFSMSrmm optional
DFSMS/MVS Network File System V1R3 DFSMS/MVS Network File System base
DFSORT R13 DFSORT optional
EREP MVS V3R5 EREP base
FFST/MVS V1R2 FFST/MVS base
GDDM/MVS V3R2 GDDM base
v GDDM-OS/2 LINK
v GDDM-PCLK
GDDM-PGF V2R1.3 GDDM-PGF optional
GDDM-REXX/MVS V3R2 GDDM-REXX optional
IBM High Level Assembler for MVS & VM High Level Assembler base
& VSE V1R2
IBM High Level Assembler Toolkit High Level Assembler Toolkit optional
ICKDSF R16 ICKDSF base
ISPF V4R2M1 ISPF base
Language Environment for MVS & VM V1R5 Language Environment base
Language Environment V1R5 Data Language Environment Data Decryption optional
Decryption

© Copyright IBM Corp. 1989, 2000 xxxi

Product Name and Level Name in OS/390 Base or Optional
MVS/ESA SP V5R2.2
BCP BCP or MVS base
ESCON Director Support ESCON Director Support base
Hardware Configuration Definition Hardware Configuration Definition base
(HCD) (HCD) base
JES2 V5R2.0 JES2 optional
JES3 V5R2.1 JES3 base
LANRES/MVS V1R3.1 LANRES base
IBM LAN Server for MVS V1R1 LAN Server base
MICR/OCR Support MICR/OCR Support base
OS/390 UNIX System Services OS/390 UNIX System Services base
OS/390 UNIX Application Services OS/390 UNIX Application Services base
OS/390 UNIX DCE Base Services (OSF OS/390 UNIX DCE Base Services
DCE level 1.1)
base
OS/390 UNIX DCE Distributed File OS/390 UNIX DCE Distributed File
Services (DFS) (OSF DCE level 1.1) Services (DFS)
optional
OS/390 UNIX DCE User Data Privacy OS/390 UNIX DCE User Data Privacy
optional
SOMobjects Application Development SOMobjects Application Development
Environment (ADE) V1R1 Environment (ADE)
SOMobjects Runtime Library (RTL) base
SOMobjects Runtime Library (RTL)
SOMobjects service classes base
SOMobjects service classes
Open Systems Adapter Support Facility Open Systems Adapter Support Facility base
(OSA/SF) R1 (OSA/SF)
MVS/ESA RMF V5R2 RMF optional
OS/390 Security Server Resource Access Control Facility (RACF) optional
v DCE Security Server
v OS/390 Firewall Technologies
v Lightweight Directory Access Protocol
(LDAP) Client and Server
v Open Cryptographic Enhanced Plug-ins
(OCEP)
SDSF V1R6 SDSF optional
SMP/E SMP/E base
Softcopy Print base
SystemView for MVS Base SystemView for MVS Base base
IBM TCP/IP V3R1 TCP/IP base
v TCP/IP CICS Sockets v TCP/IP CICS Sockets v optional
v TCP/IP IMS Sockets v TCP/IP IMS Sockets v optional
v TCP/IP Kerberos v TCP/IP Kerberos v optional
v TCP/IP Network Print Facility (NPF) v TCP/IP Network Print Facility (NPF) v optional
v TCP/IP OS/390 Communications Service v TCP/IP OS/390 Communications Service v optional
IP Applications IP Applications v optional
v TCP/IP OS/2 Offload v TCP/IP OS/2 Offload
TIOC R1 TIOC base
Time Sharing Option Extensions (TSO/E) TSO/E base
V2R5

xxxii OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Product Name and Level Name in OS/390 Base or Optional
VisualLift for MVS V1R1.1 v VisualLift Run-Time Environment (RTE) v base
v VisualLift Application Development v optional
Environment (ADE)
VTAM V4R3 with the AnyNet feature VTAM base
3270 PC File Transfer Program V1R1.1 3270 PC File Transfer Program base

Elements and Features in OS/390 xxxiii

xxxiv OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Part 1. Guide to the Dialog Tag Language (DTL)
This section contains the following chapters:

Chapter 1. Introduction to the Dialog Tag Language (DTL) contains an

introduction to the Dialog Tag Language (DTL) and descriptions of the dialog
elements you define with the Dialog Tag Language. A brief description of the ISPF
Conversion Utility is also included.

Chapter 2. How to Use the Dialog Tag Language (DTL) explains the syntax
conventions of the Dialog Tag Language.

Chapter 3. Getting Started: Designing Application Panels tells you how to design
application panels.

Chapter 4. Variables and Variable Classes tells you how to declare variables,
define variable classes, and validate variables.

Chapter 5. Application Panel Fields tells you how to define interactive fields for
application panels.

Chapter 6. Information Regions and Help Panels tells you how to define
information regions and help panels.

Chapter 7. Messages tells you how to define messages.

Chapter 8. The Application Command Table tells you how to define application
commands and the application command table.

Chapter 9. Defining Key Mapping Lists tells you how to define key mapping lists.

Chapter 10. Using the Conversion Utility describes the steps involved in
converting your DTL source files into ISPF panel language source format or
executable pre-processed ISPF format.

© Copyright IBM Corp. 1989, 2000 1

2 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Chapter 1. Introduction to the Dialog Tag Language (DTL)
This book introduces you to the Dialog Tag Language (DTL), a tag-based language
used to define many of the elements that make up the type of application known
as a dialog, the communication between a person and a computer. We tell you how
to define these elements using DTL and how to prepare them for use in your ISPF
applications.

The elements you produce with DTL are used by ISPF as the user interface for
your ISPF applications. The programs you write using ISPF services and a
programming language use the dialog elements you create for an application.

This chapter provides an overview of DTL, and the dialog elements you create
with DTL. We introduce you to DTL by discussing the following main topics:
v Why the Dialog Tag Language?
This section talks about why you would want to use DTL to create elements for
ISPF applications.
v What is the Dialog Tag Language?
This section explains what the Dialog Tag Language is and how it works.
v Dialog elements
This section provides descriptions and examples of the dialog elements. These
elements are:
– Application panels
– Help panels
– Messages
– An application command table
– Key mapping lists.
v Variables and variable classes
This section discusses the definition of variables you include in dialog element
definitions.
v What is the ISPF Conversion Utility?
This section provides a description of the conversion utility, the compiler you
use to convert your DTL source files for use by ISPF.

Why the Dialog Tag Language (DTL)?

If you are already familiar with a tag-based markup language, such as IBM
BookMaster*, you will find that DTL is very similar. We created DTL for many of
the same reasons that we created BookMaster:
v Markup tags are easy to use. Because tag names are short and relate directly to
the structure of the dialog elements, they are also easy to remember.
v DTL lends flexibility to application development. Panels can be quickly changed
without your having to tediously line up text and fields. This gives you greater
control over application development and updates.
v 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.

© Copyright IBM Corp. 1989, 2000 3

 v DTL techniques improve the way in which interactive programs, like ISPF
applications, are developed. The language concentrates on the role of the various
elements and their interrelationships, and ISPF takes care of their form and
appearance at run time.
v DTL also enforces some formatting rules defined by the Systems Application
Architecture* Common User Access (CUA), so you do not have to be familiar
with all of the CUA formatting rules. Therefore, the CUA skills required by
programmers who are developing CUA-conforming applications are significantly
reduced.
v DTL enables National Language Support (NLS) and the conversion utility
provides NLS translations for certain key words.

In other words, if you are looking for an application development and

maintenance system that is sophisticated, flexible, and easy to use, that’s DTL.

Examples of DTL usage by ISPF have been shipped in data set 'ISP.SISPGxxx',
where xxx is a standard ISPF language identifier. Consult your ISPF system
administrator for the actual location of these examples.

What Is the Dialog Tag Language?

In Why the Dialog Tag Language (DTL)? we referred to DTL as a tag-based
markup language that is similar to IBM BookMaster. The two have much in
common. For example, markup is a term that is usually associated with
documentation. It is an old typesetter’s term that formerly meant the instructions
with which a document was “marked up” to show how the document should be
set in type.

Today, this definition has been expanded to include information that is added to a
document to enable a person or system to process it. Just as markup information
can describe a document’s characteristics or the processing to be performed, it can
also describe the characteristics or processing related to dialog elements. This is
where the tags come in.

We call DTL a tag-based markup language simply because the markup consists of
tags that determine not only what each element is, but also how it is processed. To
convert the dialog elements into a format that is usable by ISPF, you must convert
them to ISPF elements with ISPDTLC, the ISPF conversion utility. (See “What Is
the ISPF Conversion Utility?” on page 9 for more information.)

Another thing that DTL and BookMaster have in common, of course, is the tags
themselves, which have the following similarities:
v They are very short and easy to remember.
v They are often accompanied by text.
v Many DTL tags are almost identical to corresponding BookMaster tags.

These are all reasons that familiarity with BookMaster will make it easy to learn
DTL. For example, we created the preceding bulleted, or unordered list by editing a
file using an editor and typing the following:
:ul compact.
:li.They are very short and easy to remember.
:li.They are often accompanied by text.
:li.Many DTL tags are almost identical to corresponding BookMaster tags.
:eul.

4 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 You could create a similar list for an information panel by using the following DTL
tags with the same text:
<ul compact>
<li>They are very short and easy to remember.
<li>They are often accompanied by text.
<li>Many DTL tags are almost identical to corresponding BookMaster tags.
</ul>

Here, the <ul> and </ul> tags, respectively, begin and end the unordered list. This
type of list is called an unordered list because the list items are not numbered. The
individual list items are defined by the <li> tags and consist of the accompanying
text.

As you can see from the preceding example, DTL tags act as control words that
specify how the text of source files is interpreted by the conversion utility. This
concept is based on the Standard Generalized Markup Language (SGML), which is
a standard of the International Standards Organization (ISO). The conventions of
the Dialog Tag Language are based on the SGML standard.

After you are finished marking up a source file, you use the conversion utility to
convert the file into a format usable by your ISPF application. In addition to
processing the file, the conversion utility also checks and verifies the syntax of
your markup, and notifies you of any errors. After conversion, the elements you
defined in your source file are stored within ISPF libraries.

You can use ISPF dialog test facilities to display application panels and messages
after they have been converted. Displaying your panels is a good idea to make
sure they format properly.

You should now have a basic understanding of DTL and how it works. The next
section builds on this understanding by describing the types of elements that you
can define with DTL.

Dialog Elements
This section provides a descriptive overview of the dialog elements you can create
for an ISPF application. These elements include:
v Application panels
v Help panels
v Messages
v An application command table
v Key mapping lists.

Application Panels
Application panels are the primary element of the user interface for an application.
They allow users to interact with your application through the use of data fields,
selection fields, and other interactive fields. Application panels appear in primary
and pop-up windows.

Figure 5 on page 6 shows a full-screen application panel. Following that is a list of

the elements that make up an application panel.

Chapter 1. Introduction to the Dialog Tag Language (DTL) 5

 File Search Help
--------------------------------------------------------------------------
Library Card Registration

Type in patron's name and card number if applicable.

Then, select an action bar choice.

Date . . . : 12/29/90
Card No. . . _______ (A 7-digit number)
Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following Check valid branches

__ 1. New _ North Branch
2. Renewal _ South Branch
3. Replacement _ East Branch
_ West Branch

Enter a command ===> ______________________________________________________

F1=Help F2=Split F3=Exit F6=KEYSHELP F9=Swap
F12=Cancel

Figure 5. Application Panel

Application Panel Elements

Action bar
The action bar appears in the top portion of the panel. It contains keyword
choices that provide users access to available actions for the current panel.
When the user selects an action bar choice, a pull-down containing choices
appears directly below the action bar choice.
Panel title
The panel title appears below the action bar.
Panel body
The panel body serves as the main work area of the panel. The panel body
contains the input and output fields, selection fields, and other text.
Additionally, the panel body can contain optional top and bottom
instructions, which provide instructional text to the user. Top instructions
appear below the panel title and above the interactive fields on the panel.
Top instructions tell the user how to interact with the panel. Bottom
instructions appear below the interactive fields on the panel. Bottom
instructions tell the user how to interact with the panel, or how to continue
with the application.
Message area
The message area appears below the panel body.1 ISPF uses the message
area (or message pop-ups) to display messages to users while they are
working in the panel.
Command area
The optional command area (or command line), which appears at the
bottom of the panel, consists of two components: the command field

1. The message area and the command area for panels defined with DTL appear at the bottom of the panel if the user has selected
the Command line at bottom option on the ISPF Settings panel, or the application has set ZPLACE to BOTTOM. For additional
information on placement options, refer to the discussion of the ISPF Settings panel in the ISPF User’s Guide.

6 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 prompt and the command entry field. 1 Application users can use the
command entry field to enter commands or requests to the ISPF
application.
Function key area
The optional function key area, which appears at the bottom of the panel
immediately below the command area (if one is defined), contains the key
assignments for dialog actions valid for the application panel. The user can
request that function keys not be displayed.

“Chapter 3. Getting Started: Designing Application Panels” on page 27 tells you

how to define application panels and panel elements.

Help Panels
Help panels appear in pop-up windows in response to user requests for assistance
during ISPF application sessions. ISPF processes these help requests and displays
the help panels.

Using DTL, you can create help panels that provide help for:
v An entire application panel (extended help or panel help)
v A specific field on an application panel (contextual help or field help)
v Messages (message help)
v The function key area (keys help).

Figure 6 illustrates a help panel. Following that is a list that defines each of the
elements that make up a help panel.

┌────────────────────────────────────────────────────┐
│ Help for Ordering Parts │
│ │
│ Use one of the following codes when ordering a │
│ part number from inventory: │
│ │
│ ST │
│ Indicates that the part order is for stock │
│ replenishment. │
│ │
│ CU │
│ Indicates that the part order is for │
│ immediate customer shipment. │
│ │
│ EL │
│ Indicates that the part order is for │
│ shipment to an external location. │
│ │
│ │
│ │
│ F1=Help F3=Exit F12=Cancel │
└────────────────────────────────────────────────────┘

Figure 6. Help Panel

Help Panel Elements

Help panel title
The help panel title appears at the topmost portion of the panel, followed
by a blank line separating the panel title from the panel body. If the help
panel text exceeds the defined depth of the help panel, a scrolling indicator
appears in the right margin of the blank line following the panel title.

Chapter 1. Introduction to the Dialog Tag Language (DTL) 7

 Help panel body
The help panel body contains the text of the help panel.
Text within the help panel is protected, which means that the user cannot
interact with the text. You define this static text within an information region
in the panel definition.
Function key area
If you are creating a help panel that does not end with a scrollable area,
note that ISPF reserves 4 lines at the bottom of the panel for function keys.
The display of keys in the function key area is controlled by the user
through the ISPF FKA command.

“Chapter 6. Information Regions and Help Panels” on page 109 tells you how to
define help panels and information regions.

Messages
You can use DTL to define messages that display in response to a user request or
action, or that provide additional information. Messages can confirm a
user-requested action, report an error in user input, or notify the user of an error
or exception condition. Figure 7 illustrates a message displayed in the message area
of an application panel (highlighting added).
The messages you define for an application are stored within message members. You
File Search Help
--------------------------------------------------------------------------
Library Card Registration

Type in patron's name and card number if applicable.

Then, select an action bar choice.

Date . . . : 12/29/90
Card No. . . _______ (A 7-digit number)
Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following Check valid branches

__ 1. New _ North Branch
2. Renewal _ South Branch
3. Replacement _ East Branch
_ West Branch
You must type your name in the Name field.
Enter a command ===> ______________________________________________________
F1=Help F2=Split F3=Exit F6=KEYSHELP F9=Swap
F12=Cancel

Figure 7. Message Displayed in Message Area

use DTL to define the messages and message members.

“Chapter 7. Messages” on page 151 provides a complete description of defining

messages and message members.

Application Command Table

You can use DTL to define commands that perform actions requested by the user.
The valid commands for an application are defined and stored within an internal
application command table. You can define only one command table for an
application.

8 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 Valid commands include those assigned to pull-down choices, function keys, and
commands entered in command entry fields.

“Chapter 8. The Application Command Table” on page 157 tells you how to define
commands and application command tables.

Key Mapping Lists

The key assignments that are active for an application are defined and stored
within key mapping lists. These key assignments allow the user to request
commands and other actions through the use of function keys. Key assignments
for your application are displayed in the function key area of application panels.

“Chapter 9. Defining Key Mapping Lists” on page 163 tells you how to define key
assignments and key mapping lists.

Variables and Variable Classes

| Variables are used to communicate information between an application and the
| user. Each variable you define for a DTL-defined dialog element can be declared, or
| identified, within a variable list. In addition, each variable can be associated with a
| variable class that defines its type and length characteristics. The variable class can
| also be used to define translations and validity checks that are used when a value
| is displayed on a panel or entered by a user.

“Chapter 4. Variables and Variable Classes” on page 57 tells you how to declare
variables and define variable classes.

What Is the ISPF Conversion Utility?

ISPDTLC is the ISPF conversion tool that converts Dialog Tag Language (DTL)
source files to ISPF panel language source format or executable preprocessed ISPF
format. ISPF provides you with an invocation panel that allows you to specify a
number of options for the conversion, or you can use conversion utility command
syntax from the command line of your terminal. “Chapter 10. Using the
Conversion Utility” on page 167 provides a complete description of both methods.

Chapter 1. Introduction to the Dialog Tag Language (DTL) 9

10 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Chapter 2. How to Use the Dialog Tag Language (DTL)
This chapter describes the tag syntax conventions and mark-up declarations of the
Dialog Tag Language (DTL). It also explains how to use the DTL to create dialog
element source files for your ISPF applications.

The markup style of DTL is based on the International Standards Organization

(ISO) Standard Generalized Markup Language (SGML). Markup languages allow
you to specify, through the use of tags, how the text of a file is to be formatted for
use by an application. Because DTL is a markup language, you must follow special
rules and conventions when using it to define dialog elements.

Syntax Conventions
The DTL tags act as control words that determine how the text in the source files is
used. Each tag is enclosed within a set of delimiter symbols that distinguish the
tag as a control word (as opposed to general text).Start tags, which initiate text
interpretation,are preceded by the start tag open delimiter (<) and followed by the
close delimiter (>). End tags, which explicitly end text interpretation,are preceded
by the end tag open delimiter (</) and followed by the close delimiter (>).

For example, the DTL tags used for defining the beginning and end of an
application panel are the PANEL tag and its matching end tag, which look like
this:2
<panel>
</panel>

DTL tags are free-form. Indentation of nested tags can be helpful for DTL source
file readability.

All of the text that you define between a start and end tag is the tag definition. The
DTL tag data extends to the right boundary of the source file. Therefore, DTL
source files cannot contain line sequence numbers. The characteristics of the tag
determine how the text or other tags coded within the tag definition will be
formatted.

Attributes and Values

Many DTL start tags contain attributes and values that define various physical and
operating characteristics of the dialog elements. While most attributes and values
are optional, or contain default settings, some are required.

For example, the PANEL tag has a required NAME attribute that must be specified
to identify the panel. The value you assign to the NAME attribute must be unique
for each panel in a source file. This PANEL tag has the NAME value “panel1”:
<panel name=panel1>
</panel>

2. End tags are not required for all of the DTL tags. In many cases, the tag is implicitly ended by other start tags. For this reason, we
don’t use optional end tags in the markup examples in this book. “Chapter 13. Tag Reference” on page 201 contains a detailed
description of each of the DTL tags, including which tags require an end tag.

© Copyright IBM Corp. 1989, 2000 11

 The PANEL tag also has two optional attributes, DEPTH and WIDTH, whose
values specify the dimensions of the panel. For these types of attributes, you
specify a numeric value.
<panel name=panel1 depth=20 width=40>
</panel>

Values for some of the tag attributes are predetermined; that is, you can choose
from one of a number of keyword values for the tag. For example, the FIG (figure)
tag has a FRAME attribute that specifies the top and bottom borders of the figure.
The value you assign to the FRAME attribute can be either RULE, which produces
a visible border above and below the figure, or NONE, which results in a figure
without a border. No other value is acceptable for the FRAME attribute.

RULE is the default value, which means that the figure formats with visible
borders if you do not specify the FRAME attribute.

The markup for a figure without ruled borders looks like this:
<fig frame=none>
</fig>

When coding values for attributes, you must use single or double quotes to enclose
values that contain characters other than A–Z, a–z, 0–9, a hyphen (–), or a period
(.).

For example, the value assigned to the TYPE attribute of this VARCLASS tag
contains a blank, so the value must be enclosed in quotes:
<varclass name=boolean type='char 1'>

Some attributes can be assigned either a specific value, such as a number or a

character string, or a variable name. To distinguish a variable name from a specific
value, precede the variable name with a percent (%) sign. This convention is called
% notation.The percent sign distinguishes the variable name from a specific value.
To specify a string that begins with a %, you must code an additional % before the
string to distinguish it from a variable name. (For example, to specify the string
%“abc”, code “%%abc”).

The ACTION attribute in the following example uses % notation to specify a

variable named “varname”:
<cmdact action='%varname'>

The length of any attribute value is limited to 253 characters, unless stated
otherwise. This includes the lengths of any entity references that are a part of the
value.

Generally, you can code tags, attributes, and values in uppercase, lowercase, or
mixed case; the results are always the same regardless of case. The conventions
you must follow for case-sensitive processing for each tag are described in
“Chapter 13. Tag Reference” on page 201.

Tag Text
The content or text of a tag is coded immediately following the start tag. This is
the actual text that is subject to formatting and translation. The text is processed
according to the type of tag it follows.

12 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 For example, the text following this P (paragraph) tag is the actual text that
appears in the panel after formatting:
<p>The copy command allows you to copy single or multiple forms.

Because the tag text is processed according to the tag characteristics, not the way it
is written in the source file, the paragraph could also be marked up using more
than one line, like this:
<p>
The copy command allows you to
copy single or multiple forms.

The formatted result is the same in either case.

In most cases, there is no limit to the amount of text you can code. However, keep
in mind that the text of some tags, such as the title of a PANEL tag, should be
limited because of size constraints of the panel they are coded within. “Chapter 13.
Tag Reference” on page 201 describes text length restrictions (if they exist) for each
of the tags.

In most cases, multiple lines of text are concatenated. Concatenation, leading

blanks, and trailing blanks are processed as follows:
v Leading and trailing blanks between lines of text are not preserved. Instead, they
are compressed to a single blank when the lines are concatenated.
v The first line of tag text may start on the same line as the start tag, or on the
next line. The formatted result is the same.

The text of some tags, such as the FIG, LINES, and XMP tag, allow you to control
where lines break. That is, within the range of the tag, each output line is ended at
the same point that you ended the input line. With these tags, multiple lines are
not concatenated, and all blanks are preserved.

Text Formatting
ISPF determines if the text is to be formatted according to English rules or Asian
rules, based on the language specified on the conversion utility invocation. If the
language is JAPANESE, CHINESET, CHINESES, or KOREAN, ISPF will use the
Japanese, Traditional Chinese, Simplified Chinese, or Korean text formatting rules,
respectively. If JAPANESE language is specified and the KANA option is also
specified, ISPF uses the Japanese Katakana formatting rules. Otherwise, the English
formatting rules are used.

English Rules for Text Formatting

Text exceeding the width of the available panel space is wrapped to the next line.
The text is split at blanks. However, if any word exceeds the panel space, then the
word splits and continues on the next line.

Asian Rules for Text Formatting

Some characters should not be placed at the beginning of a line, and some should
not be placed at the end of a line. These beginning-and-ending inhibited characters
are different among the languages but the required process is the same. Thus, ISPF
uses the same text formatting process for these Asian languages, but uses a
different beginning-and-ending inhibitor character table for each of the languages.

The text is first split into words. An SBCS word is delimited by blanks, or SO/SI
characters. Then any beginning inhibitors are stripped from the beginning of the

Chapter 2. How to Use the Dialog Tag Language (DTL) 13

 word and treated as separate words, and any ending inhibitors are stripped from
the end of the word and treated as separate words.

Adjoining DBCS alphanumeric characters (that is, Ward 42 characters) are treated
as one DBCS word. Then any beginning inhibitors are stripped from the beginning
of the word and treated as separate words, and any ending inhibitors are stripped
from the end of the word and treated as separate words. All other non-Ward 42
double-byte characters are treated as separate DBCS words.

If a word exceeds the available panel space, then the word splits and continues on
the next line. If the text consists of mixed data and does not fit in one line within
the specified width, the first position will always be reserved for a SO character (if
first word is double-byte) or for a blank (if the first word is single-byte). This
allows the text to be aligned properly.

Words that exceed the width of the available panel space are wrapped to the next
line according to following rules:

┌───────────────────────┐
│ ... CE─1 CE │
│CB CB+1 ... │
└───────────────────────┘
┌───────┬─────┬─────┬─────┬─────────────┐
│ CE─1 │ CE │ CB │ CB+1│ Process │
├───────┼─────┼─────┼─────┼─────────────┤
│ any │ B,X │ B │ X,E │ Backward │
│ E │ E │ X,B │ X,E │ Backward │
│ X,B │ E │ any │ any │ Forward │
│ X,B │ X │ B │ B │ Forward │
│ ───── any other ──── │ No process │
└─────────────────────────┴─────────────┘

Where:
CE-1 and CE Last two words that fit on line
CB and CB+1 First two words on next line
E Ending inhibitor
B Beginning inhibitor
X Neither
Forward Move CE to next line
Backward Move CB to previous line
No process Split as is

Note: If words CE or CB are single-byte words and are more than 1 character, or if
CE or CB are double-byte words and are more than 1 double-byte character,
then no special processing is used; the line is split as is.

When your panel contains several successive lines of mixed data from different
tags, the alignment of a short text string can appear to be shifted 1 byte further left
than the surrounding text. This occurs because a text string that fits on one line
does not have the leading position reserved for the SO character to use as many
positions on the screen as possible.

You can control the alignment of successive lines of mixed data by adding a string
of DBCS blanks to the end of a short text string. This forces the SO character
position to be reserved during formatting.

SBCS and DBCS blanks that end or begin a line will be deleted.

14 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 Nesting tags
It is often necessary to code certain tags (and their text) within the definition of
other tags (between the start and end tags). This is called nesting.

A good example of nesting is the relationship between the DL (definition list) tag,
the DT (definition term) tag, and the DD (definition description) tag. The DL tag
specifies a definition list and the DT and DD tags specify the terms and
descriptions of the items within the definition list. Consequently, the DT and DD
tags must be nested within a DL tag and its matching end tag if the list is to
format properly.

Here’s an example:3
<dl>
<dt>This is a definition term.
<dd>This is a definition description.
<dt>Another term.
<dd>Another description.
</dl>

There are several tags that must be nested within the actual text of another start
tag. These tags serve to identify a condition for the text. In this example, the nested
CMD tag follows the CMDTBL start tag and precedes the CMDTBL end tag. The T
(truncation) tag nested within the text of the CMD tag provides truncation of the
command text.
<CMDTBL APPLID=conv>
<CMD NAME=delete>Del<T>ete
<CMDACT ACTION=setverb>
</CMDTBL>

Nesting tags can take on many different forms and can be complex. For example,
some tags allow multiple tags or multiple occurrences of the same tag to be nested,
while other tags do not allow nesting of any tags. You can also nest levels of
certain tags, that is, nested tags within other nested tags. Additionally, in many
instances, you must nest certain tags within other tags. The tag descriptions in
“Chapter 13. Tag Reference” on page 201 describe the allowed and required
conditions for nesting each of the DTL tags.

Including Comments in the Generated Panel or Message Member

You can use the COMMENT tag to add comments to the generated panel or
message member file. The TYPE attribute specifies the panel section for the
comment. TYPE = END is automatically used for message member processing. You
provide the comment text in a manner similar to the paragraph tag. ISPDTLC
flows the text to a width of 66 bytes and adds “/* ” before and “ */” after each
resulting comment line.

Including Copyright Statements in the Generated Panel or

Message Member
You can use the COPYR tag to add a copyright statement to the generated panel or
message member. The copyright statement is placed in the panel immediately
following the )END panel section line, or immediately following the last message
in the message member. The text of the COPYR tag is limited to 66 bytes. ISPDTLC
adds “/* ” before and “ */” after the copyright text. Each COPYR tag adds one
line to the generated panel.

3. Although it isn’t required, we indented the nested tags in this example to illustrate nesting levels. You can also do this in your
own source files.

Chapter 2. How to Use the Dialog Tag Language (DTL) 15

Markup Declarations
In addition to tag markup, you can also include markup declarations in your source
files to define other, related information. Markup declarations are control
statements that specify how other markup (such as tags) within a source file is to
be interpreted.

For example, in order for the compiler to recognize your source files as being
intended for DTL conversion to ISPF elements, you must include a document type
declaration at the beginning of each source file.

Like tags, markup declarations must be enclosed within a set of delimiter symbols
so the compiler can distinguish the declaration as a control statement. All markup
declarations are preceded by the <! symbol and followed by the > symbol. (For
NLS users of DTL the <! symbol can be replaced with the <: symbol.)

DTL supports three types of markup declarations:

v Document type declarations
v Comments
v Entity declarations.

Declaring the Document Type

Before you can convert a source file that contains the tag markup for dialog
elements, you must declare the document type. Do this by coding the DOCTYPE
declaration at the beginning of the source file. The DOCTYPE declaration looks
like this:
<!doctype dm system>

Where:
<! Begins the markup declaration
DOCTYPE Identifies the declaration as a document type declaration
DM Specifies that the source file contains tags used to define dialog
elements for a Dialog Manager application
SYSTEM Indicates that the syntax rules for defining elements are contained
in an external file
> Closes the markup declaration.

External files that are embedded (through the use of entity declarations) within the
source file intended for conversion cannot contain a DOCTYPE declaration. They
are converted using the DOCTYPE declaration of the source file they are
embedded within. For more information on entity declarations and embedding
external files within source files, see “Defining Entities and Parameter Entities” on
page 18.

Including Comments in Your Markup

If you want to include notes, reminders, or other text that you don’t want
processed in your source files, you can insert them as comments, and the
conversion utility ignores them.

Note: You cannot place comments within any of the DTL tags. A comment placed
within a start or end tag causes the tag to end, and the text following the
comment is treated as part of the tag content.

16 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

Like document type declarations, comments must be enclosed within markup
declaration delimiters (<! >). However, you must also delimit comments within
markup declarations by preceding and following a comment with two dashes (--),
like this:
<!-- This is the text of the comment -->

Because the dashes act as comment delimiters,you can use them in any markup
declaration. For example, you can include a comment within a DOCTYPE
declaration:
<!doctype dm system -- DECLARE DOCUMENT TYPE -->

The following comment will generate a warning message because the second set of
dashes is interpreted as the end of a comment and the text “Provides help for
ordering” is treated as an additional markup declaration:
<!-- Panel DMH022 -- Provides help for ordering -->

If you delete one of the dashes in the second set of dashes, or use another symbol,
no error will occur.
<!-- Panel DMH022 - Provides help for ordering -->

This block comment will produce a warning message because of the odd number
of dashes in the first and last lines of the block:
<!----------------------------------------->
<!--This source file contains all of the -->
<!-- help panels for the application -->
<!----------------------------------------->

We could avoid this problem by using a different symbol between the comment
dashes, like this:
<!--*************************************-->
<!--This source file contains all of the -->
<!-- help panels for the application -->
<!--*************************************-->

ISPDTLC accepts comments which start with the 4 characters “<!--” and end with
the 3 characters “-->”. The minimum valid comment is 7 characters (“<!---->”).

You cannot nest comments within other comments. You can, however, code
multiple comments within a markup declaration, like this:
<!-- Here a comment --
-- THERE A COMMENT --
-- Everywhere a comment, COMMENT-->

As you can see, each of the comments begin and end correctly with the comment
delimiters.

You can use comment delimiters to temporarily ignore multiple lines (or a block)
of DTL source text. The block of text might include one or more DTL tags. To
comment out a block of text, place an open comment delimiter before the first line of
the text, and a close comment delimiter after the last line of text. For example:
<!--
<p> This is a multiple line of text block
<p> It is commented out for compile purposes
-->

Chapter 2. How to Use the Dialog Tag Language (DTL) 17

 When commenting out multiple lines of DTL source, use the MCOMMENT
compiler option when coding the ISPDTLC invocation syntax, or select the Process
multiple line comment blocks option on the ISPDTLC invocation panel.

Defining Entities and Parameter Entities

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. You declare them within the DOCTYPE statement of your source file.
After you declare them, you refer to the names of the entities in place of the word
or phrase in the text. This saves you time when marking up your text, and allows
you to globally change the defined words or phrases in one place in the source file.

You can use entities and parameter entities for the following purposes:
v To replace single characters in text that are considered special characters. This
can include characters not available on a particular keyboard, or characters that
have special meaning to the compiler, such as the tag start delimiter (<), that
you want to treat as normal text.
DTL provides you with a set of predefined single-character entities. See
“Predefined Entities” on page 25 for a list of these entities.
v To replace strings of text, such as words, phrases, and longer text strings used
frequently in the source file text.
v To embed entire files in a source file. This is useful for breaking up a source file
into smaller, more manageable files, and for declaring entities that are shared by
different source files.

When you refer to an entity in the text of a source file, you must precede the entity
reference with an ampersand (&) and follow it with a semicolon (;) or a blank
space. The text defined by the entity replaces the entity reference in the formatted
text.

Entities
Entities are symbolic statements that represent text strings in a source file. Like
other markup declarations, entity declarations must be enclosed within markup
declaration delimiters (<! >). In addition, you must place entity declarations within
the declaration subset of the DOCTYPE statement.

The declaration subset is delimited by left and right brackets ([ ]) or parentheses ()

and is coded within the DOCTYPE statement. If left and right brackets are coded,
they must have the hex values of ‘AD’ and ‘BD’ respectively.

Within the markup declaration delimiters, you declare the entity with the term
“entity”, the name you are assigning to the entity, and the text string the name
represents. The text string of the entity must be enclosed in single or double
quotes.
<!doctype dm system (
<!entity name “text string”>
)>

Entity names must have the following characteristics:

v 1–17 characters
v The first character must be alphabetic (A–Z, a–z, @, #, or $)
v Remaining characters, if any, can be A–Z, a–z, @, #, $, 0–9, or _
v Entity names are case-sensitive.
v Entity names of more than 8 bytes must contain at least 1 underscore character.

18 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

This example declares an entity named “guar” for the phrase “full, unconditional,
money-back guarantee”:
<!doctype dm system [
<!entity guar “full, unconditional, money-back guarantee”>
]>

Now that we’ve declared the entity, we can use the entity name in our source file
text instead of the entire text string. To specify an entity name in text, you must
precede the name with an ampersand (&) and follow it with a semicolon (;) or a
blank, as we did in this panel text:

<!doctype dm system [
<!entity guar “full, unconditional, money-back guarantee”>
]>
<panel name=widget21 width=40>Widgets
<area>
<info width=38>
<p>You'll love the wide selection of merchandise
in our Widgets department.
<p>And, like all of our merchandise, Widgets come
with our &guar;.
</info>
</area>
</panel>

As long as we declared the entity properly, the compiler recognizes the entity
reference in the source file and replaces it with the text of the entity declaration.
Figure 8 shows the result.

Widgets

You'll love the wide selection of

merchandise in our Widgets department.

And, like all of our merchandise,

Widgets come with our full,
unconditional, money-back guarantee.

Figure 8. Entity Reference for Text Substitution

We can refer to the same entity in the text of the source file as many times as we
like. And, if we should ever want to change the text of the entity, we only have to
do it in one place–where we declared it in the declaration subset.

We’ll change the entity we declared earlier to show you what we mean.

<!doctype dm system [
<!entity guar “partial, conditional, non-refundable guarantee”>

Chapter 2. How to Use the Dialog Tag Language (DTL) 19

 ]>
<panel name=widget22 width=40>Widgets
<area>
<info width=38>
<p>You'll love the wide selection of merchandise
in our Widgets department.
<p>And, like all of our merchandise, Widgets come
with our &guar;.
</info>
</area>
</panel>

The only change we made was to the text of the entity declaration, not the entity
name. Following reformatting, the text of the entity reference now looks like this:

Widgets

You'll love the wide selection of

merchandise in our Widgets department.

And, like all of our merchandise,

Widgets come with our partial,
conditional, non-refundable guarantee.

Figure 9. Entity Reference for Text Substitution

If, for any reason you need to change the name of an entity, be sure to update all
of the references to the entity name in your text.

You can also define the text of an entity in an external file and refer to that file in
an entity declaration. If you do this, you must include the SYSTEM parameter in
the entity declaration, to indicate to the conversion utility that the file is external.

Note: You must include the external file in the concatenation of DTL source files
defined to the conversion utility.

For example, we’ll define a text string we want to use as an entity in our source
file in a file called WIDGETS. Here are the contents of the WIDGETS file:
doohickeys, whatnots, and gizmos

To declare this file in the entity declaration in our source file, we code it like this,
with the SYSTEM parameter:
<!doctype dm system [
<!entity guar “full, unconditional, money-back guarantee”>
<!entity widgets system>
]>

20 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

And, if we want to use the text string in our source file, we refer to the entity
“widgets” (in this case, the file name also serves as the entity name).

<!doctype dm system [
<!entity guar “full, unconditional, money-back guarantee”>
<!entity widgets system>
]>
<panel name=widget23 width=42>More Widgets
<area>
<info width=40>
<p>The fine selection of items in our Widgets department
includes &widgets;.
<p>And, like all of our merchandise, Widgets come with
our &guar;.
</info>
</area>
</panel>

Figure 10 shows the formatted result.

More Widgets

The fine selection of items in our

Widgets department includes doohickeys,
whatnots, and gizmos.

And, like all of our merchandise,

Widgets come with our full,
unconditional, money-back guarantee.

Figure 10. Entity Reference for Text Substitution and File Embedding

Anytime we want to update or change the text of the entity, we only need to
change the text in the WIDGETS file.

In the previous example, the name “widgets” serves as the external file name and
as the entity name.

The SYSTEM parameter may optionally be followed by the filename for the
included file. When the SYSTEM parameter is used but no filename is provided,
the entity name is used as the filename.

For instance, if you want to declare a different entity name for the WIDGETS file,
“things” for example, code it like this in the entity declaration:
<!doctype dm system [
<!entity guar “full, unconditional, money-back guarantee”
><!entity things system “widgets”>
]>

Chapter 2. How to Use the Dialog Tag Language (DTL) 21

 And refer to the entity name, things, like this:
<!doctype dm system [
<!entity guar &“full, unconditional, money-back guarantee&”>
<!entity things system “widgets”>
]>
<panel name=widget24 width=42>More Widgets
<area>
<info width=40>
<p>The fine selection of items in our Widgets department
includes &things;.
<p>And, like all of our merchandise, Widgets come with
our &guar;.
</info>
</area>
</panel>

The formatted result of this markup is the same as that shown in Figure 10 on
page 21, assuming no changes were made to the text of the WIDGETS file.

Parameter Entities
Parameter entities allow you to place multiple entity declarations within an external
file and refer to them within a source file. To embed the entities into the source
file, you must declare the external file as a parameter entity. A parameter entity is
identified by a percent symbol (%) following the term “entity” and followed by a
space and the entity name. See “Entity Declarations” on page 194 for the syntax
description. You refer to a parameter entity within the DOCTYPE statement by
preceding the entity name with a percent symbol (%) and following it with a
semicolon (;). This embeds the parameter entity file and allows its entities to be
referred to in the source file.

For example, we’ve declared all of our entities within an external file called
SYMBOLS. Here are the contents of the SYMBOLS file:
<!ENTITY sb “ShelfBrowse”>
<!ENTITY cotime “ten days”>
<!ENTITY xcotime “five days”>
<!ENTITY nttime “three days”>
<!ENTITY nitem “red checkout card”>
<!ENTITY lfine “ten cents”>
<!ENTITY cophone “555-1234”>

The conversion utility locates the parameter entity using the rules defined above
for entity external files.

We can embed the above file into the declaration subset of the source file with a
parameter entity declaration within the DOCTYPE statement. As long as we
declare the parameter entity and refer to it properly, we can use any of the
declared entities in the external file in the text of the source file.
<!doctype dm system
[<!entity % SYMBOLS system> %SYMBOLS;]>
<panel name=chkout width=40 depth=22>Library Checkout Periods
<area>
<info width=38>
<p>&sb; allows you to check out an inventory
item for a maximum of &cotime;.
However, you can renew the item for an additional
&xcotime; by calling in your card number to our
checkout phone line (&cophone;) any time of day.
<p>If an inventory item is a new shelf item
(indicated by the &nitem;), you may only reserve it for
a maximum of &nttime;.
You may not renew a new shelf item.

22 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 <p>There is a fine of &lfine; per day for all
items returned late.
</info>
</area>
</panel>

Figure 11 shows the formatted result.

Parameter entity names must have the following characteristics:
Library Checkout Periods

ShelfBrowse allows you to check out an

inventory item for a maximum of ten
days. However, you can renew the item
for an additional five days by calling
in your card number to our checkout
phone line (555-1234) any time of day.

If an inventory item is a new shelf

item (indicated by the red checkout
card), you may only reserve it for a
maximum of three days. You may not
renew a new shelf item.

There is a fine of ten cents per day

for all items returned late.

Figure 11. Parameter Entities

v 1–8 characters
v The first character must be alphabetic (A–Z, a–z, @, #, or $)
v Remaining characters, if any, must be A–Z, a–z, @, #, $, or 0–9
v Parameter entity names are case-sensitive.

Imbedding Source Files

You can also use entities to imbed entire files within your source file. For example,
you could define common variables for several panels in your source file in a
separate file. These separate files are stored as members of any input library
specified to ISPDTLC. The following markup shows the contents of a file called
VARDEFS.
<varclass name=titlcls type='char 50'>
<varclass name=bookcls type='char 20'>
<varclass name=pagecls type='char 5'>
<varclass name=datecls type='char 8'>

<varlist>
<vardcl name=title varclass=titlcls>
<vardcl name=author varclass=bookcls>
<vardcl name=publish varclass=bookcls>
<vardcl name=pages varclass=pagecls>
<vardcl name=curdate varclass=datecls>
</varlist>

Another common markup file could be defined for an action bar. The following
markup shows a portion of the contents of a file called ACTNBAR.
<ab>
<abc>File
<pdc>Add Entry

Chapter 2. How to Use the Dialog Tag Language (DTL) 23

 <action run=add>
<pdc>Delete Entry
<action run=delete>
<pdc>Update Entry
<action run=update>
<pdc>Exit
<action run=exit>
. <abc>View
.
.
. <abc>Options
.
.
. <abc>Help
.
.
</ab>

We can imbed these files in a source file by coding entity references to the files in
the source file DOCTYPE statement.
<!doctype dm system [
<!entity actnbar system>
<!entity vardefs system>]>

&vardefs;

<panel name=dfdxmp21>Library Inventory

&actnbar;

<topinst>To add a book to the inventory, complete the fields below,

and then press Enter.
<area>
<dtafld datavar=title usage=in pmtwidth=14>Title
<dtafld datavar=author usage=in pmtwidth=14>Author
<dtafld datavar=publish pmtwidth=14>Publisher
<dtafld datavar=pages usage=in pmtwidth=14>Number of pages
<divider type=solid gutter=3>
<dtafld datavar=curdate usage=out pmtwidth=20>Today's date is
</area>
</panel>

The variable definitions in VARDEFS are referred to by the data fields in the panel
because the file was imbedded into the source file through the entity declaration.
In the previous example, the entry width information for each field is obtained
from the variable definitions.

File imbed entity names must have the following characteristics:

v 1–8 characters
v The first character must be alphabetic (A–Z, a–z, @, #, or $)
v Remaining characters, if any, must be A–Z, a–z, @, #, $, or 0–9
v Entity names are case-sensitive.

Run-Time Substitution Variables

If you need to include a dialog variable within your panel source that will be
substituted at run time, the output panel must be created to contain an
“&variable” string. An example would be a reference to an ISPF variable such as
&ZDATE.

The conversion utility always tries to substitute each “&variable” found at

conversion time with the available entity definitions. If the conversion utility can’t
find an entity definition, it issues a warning message, and then passes the original
“&variable” into the output panel.

24 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 To avoid the warning message, you can use the predefined entity “&amp”. You can
code the variable in the tag source as “&amp;variable” to make “&variable” appear
in the panel. Alternatively, you could provide an entity definition for the variable,
such as <!ENTITY variable “&variable”>.

You should use caution when designing panels that contain run-time substitution
variables. The regular panel formatting process might not leave sufficient space in
the panel text line for the variable value to be inserted. For example, a variable
name of “&date” that requires 10 positions (YYYY/MM/DD) should be coded as
“&date(10);”.

Predefined Entities
The Dialog Tag Language provides you with a set of predefined entities that you
can use in your source files. You can use them when the symbol you want is not
present on your keyboard, or conflicts with a conversion utility delimiter symbol.

You do not need to declare a predefined entity to use it. If you use the entity in
your source file as you would an entity that you declare within your document
subset, the conversion utility performs the substitution for you. You should always
use the pre-defined entities for all symbols that are used as part of the tag
language syntax.

The Dialog Tag Language predefined entities include:

&gtsym; greater than (>)
&ltsym; less than (<)
&colon; colon (:)
&amp; ampersand (&)
&semi; semicolon (;)
&period; period (.)
&quote; single quote (')
&dquote; double quote (")
&ndash; short dash (–)
&not; not symbol (¬)
&us; underscore (_)
&or; logical or (|)
&sll; back slash (\)
&lbrk; left bracket ([)
&rbrk; right bracket (])
&lbrc; left brace ({)
&rbrc; right brace (})
&minus; minus sign (−)
&plus; plus sign (+)
&rbl; required blank ( )
&tpl; text placeholder ( )
&eqsym; equal sign (=)
&rdb; required SBCS blank in DBCS mode ( )
&percent; percent sign (%)
&dot; dot (.)
Points to Remember:
1. Some of the symbols defined in the preceding list will not display on some
non-programmable terminals.
2. The &rbl; predefined entity creates one blank in the resulting panel text. To
place three required blanks in a text string, for example, you should code
&rbl;&rbl;&rbl; in your tag source file.

Chapter 2. How to Use the Dialog Tag Language (DTL) 25

 3. The &tpl; predefined entity uses a hex FF code to reserve a space in DTL
formatted text. After formatting is completed, the hex FF character is replaced
by a blank. As with any predefined entity, you can change this default to
another value. The current value of &tpl; is used for post-formatting text
replacement. Thus, if you prefer to use an @ as the reserved space character,
define the entity as follows:
<! ENTITY TPL '@'>

If multiple reserved spaces are required, you could use the following entity
definitions to reserve 10 characters. To use your own entity name, first define
TPL to override the system default character for text replacement. Second, add
your entity definition, using the specified override character.
<! ENTITY TPL '@'>
<! ENTITY MYTPL '@@@@@@@@@@'>

When the &tpl; is changed, be careful to select a character that will not
otherwise be used in your panel.
4. The &rdb; predefined entity generates an SBCS blank when ISPDTLC is
processing in DBCS mode, or a null character when processing in SBCS mode.
5. The &dot; predefined entity generates a dot (or period) character in the text.
The number of spaces following the &dot; in the DTL source is maintained in
the formatted panel.

26 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

Chapter 3. Getting Started: Designing Application Panels
Each application panel you create will serve a specific purpose, with unique fields,
messages, and help information defined for each one. In this chapter, we tell you
how to define elements that are common among application panels.This includes
defining the application panels, and the interactive elements of panels, including
action bars, instruction text, and command areas. We also tell you how to arrange
the contents of your application panels using panel regions and dividers.

At the end of this chapter, we tell you about the PANDEF tag, which allows you to
define common attributes and values for the panels in your application in a single
place.

Defining Application Panels: The PANEL Tag

You use the PANEL tag, its associated attributes, and the required PANEL end tag
to define an application panel and the specific characteristics of the panel.

The PANEL start and end tags define the beginning and ending of an application
panel. The PANEL start tag defines:
v Panel name
v Name of the help panel for the application panel
v Name of the panel default
v Dimensions of the panel
v Associated key mapping list
v KEYLTYPE value
v APPLID value
v Cursor placement
v CCSID number
v MENU keyword
v PRIME keyword
v TUTOR keyword
v WINDOW value
v WINTITLE value
v APPTITLE value
v PAD value
v PADC value
v OUTLINE value
v EXPAND value.
v MSGLINE value
v TITLINE value
v CMDLINE value
v ATTRUSE value
v ENDATTR value
v TYPE value
v SMSG value
v LMSG value
v ASIS keyword
v ACTBAR keyword
v MERGESAREA value
v PANELSTMT value
v ENTKEYTEXT value
v IMAPNAME value

© Copyright IBM Corp. 1989, 2000 27

 v IMAPROW value
v IMAPCOL value
v TMARGIN value
v BMARGIN value
| v ERRORCHECK value
v Panel title text

With the exception of the required NAME attribute used to identify the name of
the application panel, all of the attributes for the PANEL tag are optional. Many
attributes have default values that the conversion utility assumes if you do not
specify the attribute. This section describes these attributes, and how to use them.

The PANEL start and end tags look like this, respectively:
<panel
. name=mainpan>
.
.
</panel>

| In the preceding example, we included the required NAME attribute and its value
| mainpan on the PANEL start tag. ISPF requires that each panel definition contain
| this attribute and an associated value to identify the panel. The panel name is also
| used as the panel ID when the panel ID is displayed. The “NAME=*” notation will
| set the panel name to be the same as the member name of the input DTL source
| file. If multiple panel definitions have been combined within a single source file,
| then this notation should be used for only one panel definition within the file.

The panel name must follow the standard naming convention described in “Rules
for Variable Names” on page 201.

Note: During conversion when the PREP option is active, the conversion utility
uses a temporary PDS to store ISPF source format panels. The file name for
interactive use is:
'tsoprefix.TEMPDTLW.DTLPANnn', where nn is the screen number.

Or, if the TSO NOPREFIX profile option is in effect, the file name is:
'tsouserid.TEMPDTLW.DTLPANnn', where nn is the screen number.

For batch, the file name is:

'tsoprefix.TEMPDTLW.DTLBATCH'

Or, if the TSO NOPREFIX profile option is in effect, the file name is:
'tsouserid.TEMPDTLW.DTLBATCH'

The ISPPREP utility is called to convert all of the generated panels from
ISPF source format to pre-processed format at one time to improve
performance.

The Panel Title

The text that appears as the title of the panel is called the title text. You define the
title text by coding it as tag text for the PANEL start tag.

This example uses the text “Catalog Ordering System” as title text:
<panel
. name=mainpan>Catalog Ordering System
.
.
</panel>

28 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 Panel Size (Width and Depth)
| Use the DEPTH and WIDTH attributes of the PANEL tag to define the size of an
| application panel. The PANEL tag has a default WIDTH value of 76 characters and
| a default DEPTH value of 22 lines. If you specify WINDOW=NO, the default
| WIDTH is 80 and the default DEPTH is 24. These are the values the conversion
| utility assumes if you do not specify dimensions for WIDTH and DEPTH.

The following example defines the panel size as 60 characters wide and 15 lines
deep:
<panel
. name=mainpan width=60 depth=15>Catalog Ordering System
.
.
</panel>

If we want the width of the panel to be 76 characters wide (the default width), we
only need to specify a value for DEPTH, as in this markup:
<panel name=mainpan depth=15>Catalog Ordering System
.
.
.
</panel>

This results in a panel with a default width of 76 characters and a specified depth
of 15 lines.

Because you can display application panels in pop-ups, you should allow for
pop-up borders (added by ISPF at run time) when you define the WIDTH and
DEPTH values for application panels. When the panel is displayed in a pop-up,
ISPF adds two lines to the depth specified and 4 characters to the width specified
for pop-up borders. Remember that ISPF cannot display a panel whose size
exceeds the device size and will issue an error message at run time if this situation
is encountered.

Key Mapping Lists

To specify the function keys that are active for an application panel, use the
KEYLIST attribute of the PANEL tag. This attribute specifies the name of the key
mapping list you define for use with the panel. A key mapping list contains the
keys that are active while the panel is displayed. The key mapping list also
specifies what command is run when each key is pressed.

This PANEL definition refers to a key mapping list named key01:

<panel name=mainpan keylist=key01>Catalog Ordering System
.
.
.
</panel>

For more information on defining key mapping lists, see “Chapter 9. Defining Key
Mapping Lists” on page 163.

Associated Help Panels

To provide help for an application panel (also called extended help), specify the
name of the associated help panel with the HELP attribute of the PANEL tag. The
help panel you specify appears when the user requests extended help while in the
application panel or when contextual help is requested for an item on the panel,
but no contextual help is available for the item. The help panel you specify is also
displayed when the user requests extended help while in a contextual help panel
associated with an item on the panel.

Chapter 3. Getting Started: Designing Application Panels 29

 This panel definition refers to a help panel named ordhelp:
<panel
. name=mainpan help=ordhelp>Catalog Ordering System
.
.
</panel>

“Help Panels” on page 142 tells you how to create help panels for your application.

Panel Defaults
The PANEL tag attribute PANDEF provides the name of a panel default definition.
Attribute values defined on the named PANDEF tag are used for the current panel
unless the attribute has also been specified on the PANEL tag.

Cursor Placement
The PANEL tag attributes, CURSOR, CSRINDEX, and CSRPOS, allow you to
specify where the cursor is placed when the panel is initially displayed. If you do
not specify a specific cursor position, ISPF places the cursor in the first field in the
PANEL definition that can contain the cursor.

Use the CURSOR attribute to specify the field that is to contain the cursor. Use the
CSRINDEX and CSRPOS attributes to identify positions within the field you
specify with the CURSOR attribute. CSRINDEX and CSRPOS can only be used
when the CURSOR attribute is used.

The CURSOR Attribute

Use the CURSOR attribute to specify the value of the NAME attribute of a
CHOICE or SELFLD tag, or the value of the DATAVAR attribute of a CHOFLD,
DTAFLD or LSTCOL tag. The characteristics of cursor placement are described in
the following list:
CHOFLD The cursor appears in the first character position of the choice
field. Cursor positioning is valid only when the USAGE attribute
of the CHOFLD tag specifies INPUT or BOTH.
CHOICE The cursor appears in the entry field of the specified choice in a
multiple-choice selection field.
DTAFLD The cursor appears in the first character position of the data field.
Cursor positioning is valid only when the USAGE attribute of the
DTAFLD tag specifies INPUT or BOTH.
LSTCOL The cursor appears in the first row in the list column. Cursor
positioning is valid only when the USAGE attribute of the LSTCOL
tag specifies INPUT or BOTH.
SELFLD The cursor appears in the entry field of the specified single-choice
selection field.

“Chapter 5. Application Panel Fields” on page 77 provides a complete description

of the types of interactive fields you can define for your application panels.

You can also place the cursor in the command area of the panel by specifying
cmdarea as the CURSOR value.

“Defining a Command Area” on page 51 provides a complete description of the

CMDAREA tag.

30 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 In the following example4, the CURSOR attribute specifies the data field DATAVAR
value place. When the panel is initially displayed, the cursor appears in the first
character position of that field. Figure 12 shows the formatted result.
<!doctype dm system>
<panel name=mainpan1 cursor=place>Travel Agency
<selfld name=dest selwidth=50 pmtwidth=15>Destinations:
<choice>London
<choice>Madrid
<choice>Paris
<choice>Zurich
</selfld>
<divider>
<dtafld datavar=place entwidth=9 pmtwidth=5>Other
<cmdarea>
</panel>

Travel Agency

Destinations:
__ 1. London
2. Madrid
3. Paris
4. Zurich

Other _________

Command ===> ____________________________________________________________

Figure 12. Cursor Placement

If no cursor placement was specified in the PANEL tag for the preceding example,
the cursor would appear in the entry field of the Destinations single-choice
selection field when the panel is initially displayed.

The CSRINDEX Attribute

To place the cursor in a table row within a list field, use the CURSOR attribute to
specify the data variable name for a list column within the list field, and the
CSRINDEX attribute to specify the table row number where the cursor should be
placed. The value you assign to CSRINDEX must be numeric.

The CSRPOS Attribute

If you use the CURSOR attribute to place the cursor within an input-only, or
input/output data field or list column, or the command area, you can also define a
specific character position for the cursor using the CSRPOS attribute.

4. In this example, and in other examples in this chapter, we show tag markup for elements such as fields and variables that have
not yet been discussed so that we can illustrate the formatting characteristics of some tags. The syntax of these elements are not
important for the purposes of these examples. We discuss the syntax conventions of these elements in later chapters of this book.

Chapter 3. Getting Started: Designing Application Panels 31

 The value you assign to the CSRPOS attribute must be numeric. This numeric
value indicates the number of character positions from the left margin of the field
where the cursor is placed, where a 1 specifies that the cursor should be in the first
character position.

Other Panel Attributes

See “PANEL (Panel)” on page 397 for more information.
KEYLTYPE
This attribute is used to add the SHARED keyword to the KEYLIST parameter
of the )PANEL statement.
APPLID
This attribute is used to add the application ID to the KEYLIST parameter of
the )PANEL statement.
CCSID
This attribute specifies the coded-character-set identifier as defined by the
Character Data Representation Architecture.
MENU
This attribute specifies that the panel will be an ISPF menu selection panel.
PRIME
This attribute is used with the MENU attribute to specify an ISPF primary
option menu.
TUTOR
This attribute specifies that the panel is to be an ISPF tutorial panel.
WINDOW
This attribute is used to control the generation of the WINDOW keyword on
the panel )BODY statement.
WINTITLE
This attribute is used to add a title on a pop-up window border.
APPTITLE
This attribute is used to add a title on the GUI window border.
PAD
This attribute specifies the pad character for initializing the field. You can
define this attribute as a variable name preceded by a “%”.
PADC
This attribute specifies the conditional padding character to be used for
initializing the field. You can define this attribute as a variable name preceded
by a “%”.
OUTLINE
This attribute provides for displaying lines around the field on a DBCS
terminal. You can define this attribute as a variable name preceded by a “%”.
EXPAND
This attribute causes the ISPF EXPAND keyword to be added to the panel
)BODY statement.
MSGLINE
This attribute controls the provision for a long message line in the generated
panel. When MSGLINE=NO, the blank line for the long message is not added
to the panel )BODY section.

32 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

TITLINE
This attribute controls the provision for a panel title line in the generated
panel. When TITLINE=NO, the title line is not added to the panel )BODY
section. This attribute allows a panel formatted as a dynamic area to provide
the panel title as part of the dynamic area data.
CMDLINE
This attribute controls the automatic addition of the command area to a menu
selection or table display panel. When CMDLINE=NO, the command area is
not automatically generated when the CMDAREA tag is not present in the
DTL source file.
ATTRUSE
This attribute controls the use of panel attribute characters in the range of x‘01’
through x‘2F’. When ATTRUSE=YES, dynamic area attributes (specified with
the ATTR tag) can be assigned low-order hex values normally reserved for use
by the conversion utility.
ENDATTR
This attribute specifies that when the last attribute on any panel body line is
‘normal text’ (CUA), it will be replaced by the default ‘text’ (ISPF) attribute.
TYPE
This attribute specifies that the panel will be used for host display, GUI mode
display, or both.
SMSG
This attribute provides the name of the field where the short message is to be
placed.
LMSG
This attribute provides the name of the field where the long message is to be
placed.
ASIS
This attribute specifies that the command and long message fields are to
appear on the display as specified in the generated panel definition. When
ASIS is specified, any user request specified on the Settings panel, or by setting
the system variable ZPLACE is ignored.
ACTBAR
This attribute causes the action bar information for the panel to be generated,
overriding the NOACTBAR invocation option.
MERGESAREA
This attribute specifies that a panel with a single scrollable area be reformatted
to combine the scrollable area into the panel body.
PANELSTMT
This attribute controls the creation of the )PANEL statement.
ENTKEYTEXT
This attribute provides the text for the Enter key push button provided on
panels displayed in GUI mode.
IMAPNAME
This attribute provides the name of the image placed on panels displayed in
GUI mode.
IMAPROW
This attribute provides the row number for positioning the image.

Chapter 3. Getting Started: Designing Application Panels 33

 IMAPCOL
This attribute provides the column number for positioning the image.
TMARGIN
This attribute provides the number of blank lines to format at the top of the
panel as a top margin.
BMARGIN
This attribute provides the number of blank lines to format at the bottom of
the panel as a bottom margin.
| ERRORCHECK
| This attribute specifies that error checking code is added to the )PROC panel
| section.

Defining Action Bars and Pull-Downs

To create a consistent user interface, you should design your applications according
to the object-action process sequence defined by the SAA Common User Access.
The action bar is a major user interface component that helps you achieve
consistency in your applications.

The action bar is the panel element located at the top of an application panel that
contains action bar choices for the panel. Each action bar choice represents a group
of related choices that appear in the pull-down associated with the action bar
choice. When the user selects an action bar choice, the associated pull-down
appears directly below the action bar choice. Pull-downs contain choices that,
when selected by the user, perform actions that apply to the contents of the panel.

Panel Design Note

ISPF and DTL provide the tools to help you create the object-action process
sequence in your application, but it is your responsibility as an application
designer to ensure that the contents of your action bar are actions that can be
applied to the objects contained within your panel.

Typically, application panels intended for display within primary windows

contain action bars that present the user with all of the available actions that
apply to that panel. Application panels that are displayed as pop-ups should
not include the action bar. Instead, actions for a pop-up panel are presented
in the function key area.

Figure 13 on page 35 shows an action bar with the File pull-down menu displayed.

34 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 File View Options Help
┌────────────────────┐-------------------------------------------------------
│ _ 1. Add Entry │ Sample Application
│ 2. Delete Entry │
│ 3. Update Entry │
│ 4. Exit │
└────────────────────┘

Figure 13. Action Bar and Pull-Down

The tags you use to create the action bar and its pull-down menus are:
AB To start an action bar definition. The required AB end tag ends an
action bar definition.
ABC To define each of the action bar choices.
PDC To define the choices on the pull-down associated with an action
bar choice.
ACTION To specify an action to be taken when the pull-down choice is
selected. The ACTION tag is coded within the PDC tag.
M To specify a mnemonic character for action bar choice or
pull-down choice selection.

Coding an Action Bar Definition

The following list describes how to code an action bar definition:
v Code the AB start tag immediately after the PANEL start tag and before any
other tags in the panel.
v Following the AB start tag, code an ABC tag for each action bar choice in the
action bar. The text you specify on the ABC tag is the text that appears in the
action bar as the action bar choice.
v Code the associated PDC tags within the ABC tags. The text you specify on the
PDC tag is the text that appears as the pull-down choice.
v Following each PDC tag, code one or more ACTION tags to specify what type of
action occurs when that pull-down choice is selected by the user.
The ACTION tag RUN attribute (and its internal-command-name) define a
command action for the pull-down choice.If you define multiple ACTION tags
for a pull-down choice, one of which contains a RUN value, code the RUN
action last, because any actions specified after a RUN action are ignored.
v End the action bar definition with the required AB end tag.

The following example shows the markup for the action bar shown in Figure 13.
The detailed markup for the File pull-down is included.

Chapter 3. Getting Started: Designing Application Panels 35

 <panel name=mainpan2 depth=15>Sample Application
<ab>
<abc>File
<pdc>Add Entry
<action run=add>
<pdc>Delete Entry
<action run=delete>
<pdc>Update Entry
<action run=update>
<pdc>Exit
<action run=Exit>
. <abc>View
.
.
. <abc>Options
.
.
. <abc>Help
.
.
. </ab>
.
.
</panel>

Pull-Down Choice Actions

A pull-down choice provides an immediate action to the user. To ensure that a
pull-down choice performs an immediate action, you should code an ACTION tag
that specifies the RUN attribute for each pull-down choice. The value you assign to
RUN tells ISPF which command to run when the user selects the choice.

In the preceding markup example, each ACTION definition uses the RUN attribute
to specify a command. Each of these commands must be defined within the
command table for the application. “Chapter 8. The Application Command Table”
on page 157 tells you how to define commands for an application.

In addition to the RUN action, you can specify other types of actions to occur
when a pull-down choice is selected. The SETVAR and TOGVAR attributes on the
ACTION tag can be used to set and toggle variables which the application can use
to determine the processing to perform.

Remember, any SETVAR or TOGVAR actions for a pull-down choice must be

coded before any ACTION definition specifying the RUN action, because actions
coded after RUN are ignored.

A pull-down choice may be marked as unavailable. The UNAVAIL attribute is used

to provide a variable name that is used by ISPF to determine the availability of the
pull-down choice. When the variable value is 1, the pull-down choice is
unavailable.

Action Bar Help

| You can provide help for each action bar choice and pull-down choice with the
| HELP attribute on the ABC and PDC tags, respectively. By specifying the name of
| a help panel or message for the action bar choice or pull-down choice, ISPF knows
| which help information to display when the user requests help on that choice. If
| you do not specify help for a pull-down choice, the help for the action bar choice
| is displayed, when the user requests help. If there is no help defined for the action
| bar choice, the extended help panel is displayed.

In the following example, we’ve added the HELP attribute to each of the action bar
choices and pull-down choices in the action bar defined on page 36. The values
specified with each HELP attribute are the NAME values of defined help panels.

36 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 <!doctype dm system>
<panel name=mainpan3 width=50 depth=15>Sample Application
<ab>
<abc help=hfile>File
<pdc help=hnew>Add Entry
<action run=add>
<pdc help=hopen>Delete Entry
<action run=delete>
<pdc help=hsave>Update Entry
<action run=update>
<pdc help=hexit>Exit
<action run=Exit>
. <abc help=hview>View
.
.
. <abc help=hoption>Options
.
.
. <abc help=hhelp>Help
.
.
. </ab>
.
.
</panel>

In the preceding example, we defined a help panel named hhelp for the Help
action bar choice.

Common User Access requires that you put the Help action bar choice as the last
action bar choice in an action bar definition. You should code the Help action bar
pull-down as follows:
<abc help=hhelp>Help
<pdc>Extended help
<action run=exhelp>
<pdc>Keys help
<action run=keyshelp>
</abc>

“Help Panels” on page 142 tells you how to define help panels.

Preselected Pull-Down Choices

You can define a pull-down choice as being preselected with the CHECKVAR and
MATCH attributes of the PDC tag.The CHECKVAR attribute specifies the name of
a variable that you set at run time to indicate if the pull-down choice should be
preselected. The MATCH attribute defines a value that causes the choice to be
preselected. ISPF compares the value of the variable named for the CHECKVAR
attribute to the MATCH value, and if they are equal, the choice appears
preselected when the pull-down is displayed.

Continuing with the library application, assume that the user can view the files in
the library sorted by name, owner, date, or size. Preselecting a pull-down choice
provides a visual cue to the user of the current sort order.

To preselect any of the pull-down choices, the same CHECKVAR value is specified
for each choice, and a unique MATCH value is specified for each choice. The
application variable specified with CHECKVAR is set to the MATCH value to
indicate the sorting option being used. The variable specified with CHECKVAR is
changed each time the sorting option is changed. This provides a visual reminder
to the user of how the files are sorted.

Chapter 3. Getting Started: Designing Application Panels 37

 Mnemonic Choice Selection
ISPF supports mnemonic selection of action bar choices for both host system and
GUI mode display and pull-down choices when running in GUI mode.

Mnemonic selection of action bar choices and pull-down choices is automatically

determined by ISPDTLC when a non-DBCS conversion is in process. When DBCS
is specified, mnemonics are not automatically generated. The default mnemonic
character generation can be overridden by adding the MNEMGEN=NO attribute to
the AB tag for non-DBCS conversions. The mnemonic character that will be
selected is the first alphabetic or numeric character from the current action bar
choice or pull-down choice description text that is not previously used as a
mnemonic character within the action bar or current pull-down. If a unique
mnemonic character cannot be selected, the conversion utility will issue a message.
DBCS characters cannot be specified as mnemonics. See “M (Mnemonic)” on
page 374 for a description of how to provide a mnemonic character that is not part
of the normal choice description.

Mnemonic selection of action bar choices and pull-down choices may be specified
by placing the M tag immediately in front of the character to be used as a
mnemonic within the ABC or PDC text.

The automatic mnemonic generation does not replace any valid mnemonic
specified by the M tag. (If the mnemonic character specified by the M tag is a
duplicate of a mnemonic character previously selected by the generation process, a
message is issued and ISPDTLC will attempt to replace the duplicate value that
was specified.) This processing allows the combination of specific character
selection with the automatic generation feature, as long as the characters
automatically generated and the characters specified (by the M tag) are unique.
<:doctype dm system (
<:ENTITY actnfile system>
<:ENTITY actnoptn system>
<:ENTITY actnhelp system>
)>

<panel name=pdcxmp1>Sample Application

<ab>
&actnfile;

<abc>View
<pdc checkvar=sorttype match=N><M>Name
<action run=name>
<pdc checkvar=sorttype match=O><M>Owner
<action run=owner>
<pdc checkvar=sorttype match=D><M>Date
<action run=date>
<pdc checkvar=sorttype match=S><M>Size
<action run=size>

&actnoptn;
&actnhelp;
</ab>

<topinst>
<area>
</area>
<cmdarea>
</panel>

If the application sets the variable sorttype to “D” before the panel is displayed,
then the Date choice will be preselected.

38 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 Figure 14 shows how the View pull-down would appear in this scenario.

Pull-Down Choice Accelerator Support

ISPF supports accelerators on pull-down choices when you are operating in GUI
mode. Accelerators may include up to three keys. They are supported in DTL by
specifying the ACC1, ACC2, and ACC3 attributes on the PDC tag.

See “PDC (Pull-Down Choice)” on page 412 for a description of accelerator

attributes.

File View Options Help

------┌─────────────┐-----------------------------------------------------
│ 3 1. Name │ Sample Application
│ 2. Owner │
│ 3. Date │
│ 4. Size │
└─────────────┘

Figure 14. Preselected Pull-Down Choice

Defining the Panel Body

In this section, we tell you how to use DTL to define elements of the panel body
such as instruction text, areas, regions, and dividers.

Panel Instructions
DTL provides you with the TOPINST, PNLINST, and BOTINST tags to define
instructions for your application panels. None of the tags have required end tags
associated with them.

Use the instruction tags to provide text that tells the user how to interact with the
panel or how to continue with an application.

If the COMPACT attribute is not specified, a blank line is added to the panel after
each TOPINST tag and before each PNLINST or BOTINST tag.

You must code the top and bottom instruction tags outside of the portion of the
panel defined with the AREA tag and its matching end tag. (The section called
“The AREA Tag” on page 40 explains how to use the AREA tag). Code the
TOPINST tag immediately after the action bar definition (or the PANEL start tag if
the panel does not contain an action bar). Code the BOTINST following the main
body of the panel, before the PANEL end tag. You may code PNLINST tags within
the AREA tag.

Chapter 3. Getting Started: Designing Application Panels 39

 This application panel markup contains both types of instructions. Figure 15 shows
the results.
<!doctype dm system>
<panel name=mainpan5>Item Selection
<topinst>Select one of the following items and press Enter.
<selfld name=itemtyp selwidth=76>
<choice>Automotive
<choice>Hardware
<choice>Health and beauty
<choice>Lawn and garden
<choice>Sporting goods
</selfld>
<botinst>To exit the application, press F3.
</panel>

Item Selection

Select one of the following items and press Enter.

__ 1. Automotive
2. Hardware
3. Health and beauty
4. Lawn and garden
5. Sporting goods

To exit the application, press F3.

Figure 15. Top and Bottom Instructions

The AREA Tag

The AREA tag (and its matching end tag) defines the main portions of the panel
body. You code all of the interactive fields for the panel within AREA definitions.

Add an AREA definition to the previous application panel markup.

<!doctype dm system>
<panel name=mainpan6 depth=18>Item Selection
<topinst>Select one of the following items and press Enter.
<area>
<selfld name=itemtyp selwidth=76>
<choice>Automotive
<choice>Hardware
<choice>Health and beauty
<choice>Lawn and garden
<choice>Sporting goods
</selfld>
</area>
<botinst>To exit the application, press F3.
</panel>

40 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

| As stated on page 39, you must code the top and bottom instruction tags outside
| of the AREA definition. In this example, we coded only a selection field within the
| AREA definition.

The AREA tag has an optional MARGINW attribute that you can use to specify the
width of the panel body margins. This is useful for arranging fields on a panel.

The MARGINW attribute has a default value of 1. You can specify a different value
to increase the size of the panel body margins. For example, we could specify a
margin width for the AREA in the preceding markup example.
<!doctype dm system>
<panel name=mainpan7>Item Selection
<topinst>Select one of the following items and press Enter.
<area marginw=10>
<selfld name=itemtyp selwidth=58>
<choice>Automotive
<choice>Hardware
<choice>Health and beauty
<choice>Lawn and garden
<choice>Sporting goods
</selfld>
</area>
<botinst>To exit the application, press F3.
</panel>

We specified a margin width of 10. Here’s how the panel looks now:

Item Selection

Select one of the following items and press Enter.

__ 1. Automotive
2. Hardware
3. Health and beauty
4. Lawn and garden
5. Sporting goods

To exit the application, press F3.

Figure 16. AREA MARGINW=10

Scrollable Areas
| You specify a scrollable area with the Dialog Tag Language by coding the AREA
| tag and specifying the DEPTH, EXTEND, and DIV attributes for the area. When
| the DEPTH attribute is present, the conversion utility generates the )AREA section
| in the panel definition, along with the corresponding )ATTR and )BODY entries for
| the scrollable area.

Help panels generated by the Conversion Utility that contain all of the help panel
text within an AREA tag (with DEPTH specified) are not split into separate panels.

Chapter 3. Getting Started: Designing Application Panels 41

 The conversion utility places the text in an )AREA section, which allows you to
define panels up to the display size limit of ISPF.

If you specified DEPTH to signal the creation of a panel with a scrollable area, you
can also specify the EXTEND and DIV attributes.

You can specify EXTEND=ON to allow the panel to expand to the logical window
size. If you intend to have the panel in a pop-up window, you should not code the
EXTEND attribute. Panels that specify EXTEND=ON cannot be preprocessed.

You use the DIV attribute to control the creation of a divider line before and after
the scrollable area.

If you specify DIV=BLANK, a blank divider line is added before and after the area.
If you specify DIV=SOLID, a visible divider is created. The visible divider formats
with an attribute byte on each end of the line of dashes, which causes the line to
appear with a 1 character “space” on both ends. Omitting the DIV attribute or
specifying DIV=NONE causes the area to be created without divider lines.

| The conversion utility uses the DEPTH attribute value to reserve a fixed amount of
| space in the panel body. This space, together with the divider lines, if specified, is
| considered as part of the body within the depth limit specified (or defaulted) on
| the PANEL tag. When EXTEND=OFF, the minimum depth for a scrollable area is
| two lines, one for the scrolling indicator line and at least one line of displayable
| text.

The following markup illustrates how you would code a scrollable panel. Figure 17
on page 43, Figure 18 on page 43, and Figure 19 on page 44 show the formatted
result.
<!DOCTYPE DM SYSTEM(
<!entity sampvar2 system>
<!entity sampabc system>)>
&sampvar2;

<PANEL NAME=scrarea3 KEYLIST=keylxmp>File-A-Case

<AB>
&sampabc;
</AB>
<TOPINST COMPACT>
Type in client's name and case number (if applicable).
<TOPINST>Then select an action bar choice.
<AREA>
<DTAFLD DATAVAR=caseno PMTWIDTH=12 ENTWIDTH=7 DESWIDTH=25>Case No
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address PMTWIDTH=12 ENTWIDTH=25>Address
<DIVIDER>
<SELFLD NAME=casesel PMTWIDTH=30 PMTLOC=before SELWIDTH=38>Choose
one of the following
<CHOICE CHECKVAR=case MATCH=civ>Civil
<CHOICE CHECKVAR=case MATCH=estate>Real Estate
<CHOICE CHECKVAR=case MATCH=environ>Environmental
</SELFLD>
</AREA>
<AREA DEPTH=6>
<SELFLD TYPE=multi PMTWIDTH=35 SELWIDTH=50>Check type of offense committed
<CHOICE NAME=patin HELP=patin CHECKVAR=val>Patent Infringement
<CHOICE NAME=defa HELP=defame CHECKVAR=def>Defamation
<CHOICE NAME=cont HELP=cont CHECKVAR=con>Breach of Valid Contract
<CHOICE NAME=priv HELP=priv CHECKVAR=pri>Invasion of Privacy

42 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 <CHOICE NAME=incr HELP=incr CHECKVAR=icr>Interference with Contractual
Relations
<CHOICE NAME=disp HELP=disp CHECKVAR=dis>Improper Disposal of Medical
By-Products
<CHOICE NAME=fraud HELP=fraud CHECKVAR=fra>Fraud
</SELFLD>
</AREA>
<CMDAREA>Enter a command
</PANEL>

File Search Help

------------------------------------------------------------------------
File-A-Case

Type in client's name and case number (if applicable).

Then select an action bar choice.

Case No . . _______ (A 7-digit number)

Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following __ 1. Civil

2. Real Estate
3. Environmental
More: +
Check type of offense committed
_ Patent Infringement
_ Defamation
_ Breach of Valid Contract
Enter a command ===> ___________________________________________________
F1=Help F3=Exit F5=Display F6=Keyshelp F10=Actions
F12=Cancel

Figure 17. Scrollable Panel Area

After scrolling, the panel appears as follows:

File Search Help

------------------------------------------------------------------------
File-A-Case

Type in client's name and case number (if applicable).

Then select an action bar choice.

Case No . . _______ (A 7-digit number)

Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following __ 1. Civil

2. Real Estate
3. Environmental
More: - +
_ Breach of Valid Contract
_ Invasion of Privacy
_ Interference with Contractual Relations
_ Improper Disposal of Medical By-products
Enter a command ===> ___________________________________________________
F1=Help F3=Exit F5=Display F6=Keyshelp F10=Actions
F12=Cancel

Figure 18. Application Panel Area

After scrolling, the last choice in the list is visible.

Chapter 3. Getting Started: Designing Application Panels 43

 File Search Help
------------------------------------------------------------------------
File-A-Case

Type in client's name and case number (if applicable).

Then select an action bar choice.

Case No . . _______ (A 7-digit number)

Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following __ 1. Civil

2. Real Estate
3. Environmental
More: -
_ Invasion of Privacy
_ Interference with Contractual Relations
_ Improper Disposal of Medical By-products
_ Fraud
Enter a command ===> ___________________________________________________
F1=Help F3=Exit F5=Display F6=Keyshelp F10=Actions
F12=Cancel

Figure 19. Scrollable Panel Area

Multiple AREA Tags

The default AREA tag formatting arranges areas vertically within the panel body.

The WIDTH and DIR attributes of the AREA tag allow areas to be formatted
horizontally.

The following markup illustrates the use of horizontal areas. Figure 20 on page 45
shows the formatted result.
<!DOCTYPE DM SYSTEM(
<!entity sampvar2 system>
<!entity sampabc system>)>
&sampvar2;

<PANEL NAME=scrarea4 KEYLIST=keylxmp>File-A-Case

<AB>
&sampabc;
</AB>
<CMDAREA>Enter a command
<TOPINST COMPACT>
Type in client's name and case number (if applicable).
<TOPINST>Then select an action bar choice.
<AREA width=50 dir=horiz>
<DTAFLD DATAVAR=caseno PMTWIDTH=12 ENTWIDTH=7 DESWIDTH=21>Case No
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=8>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address PMTWIDTH=12 ENTWIDTH=25>Address
<DIVIDER>
<SELFLD NAME=casesel PMTWIDTH=11 PMTLOC=before SELWIDTH=38>Choose
one of the following
<CHOICE CHECKVAR=case MATCH=civ>Civil
<CHOICE CHECKVAR=case MATCH=estate>Real Estate
<CHOICE CHECKVAR=case MATCH=environ>Environmental
</SELFLD>
</AREA>
<AREA width=26 dir=horiz>
<SELFLD TYPE=multi PMTWIDTH=24 SELWIDTH=26 depth=10>

44 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 Check type of offense
<CHOICE NAME=patin HELP=patin CHECKVAR=val>Patent Infringement
<CHOICE NAME=defa HELP=defame CHECKVAR=def>Defamation
<CHOICE NAME=cont HELP=cont CHECKVAR=con>Breach of Valid Contract
<CHOICE NAME=priv HELP=priv CHECKVAR=pri>Invasion of Privacy
<CHOICE NAME=incr HELP=incr CHECKVAR=icr>Interference with Contractual
Relations
<CHOICE NAME=disp HELP=disp CHECKVAR=dis>Improper Disposal of Medical
By-Products
<CHOICE NAME=fraud HELP=fraud CHECKVAR=fra>Fraud
</SELFLD>
</AREA>
</PANEL>

File Search Help

-------------------------------------------------------------------------
File–A–Case

Type in client's name and case number (if applicable).

Then select an action bar choice.
Check type of offense
#SAREA37 #
Case No . . _______ (A 7–digit number) # #
Name . . . . _________________________ (Last, # #
First, # #
M.I.) # #
Address . . _________________________ # #
# #
Choose one # #
of the # #
following __ 1. Civil # #
2. Real Estate
3. Environmental
Enter a command ===> ____________________________________________________
F1=Help F3=Exit F5=Display F6=Keyshelp F10=Actions
F12=Cancel

The contents of the scrollable area are as follows:

)AREA SAREA37

_ Patent Infringement
_ Defamation
_ Breach of Valid
Contract
_ Invasion of Privacy
_ Interference with
Contractual Relations
_ Improper Disposal of
Medical By–Products
_ Fraud

)AREA SAREA37

Figure 20. Multiple Horizontal Areas

The DYNAMIC AREA Tag

You specify a dynamic area in the )BODY section by coding the DA and ATTR
tags. The DA tag is used to define the dynamic area in the panel )BODY section.
The ATTR tag is used to specify the )ATTR section entries for DATAIN, DATAOUT,
and CHAR attribute types used within the dynamic area. A dynamic area allows

Chapter 3. Getting Started: Designing Application Panels 45

 you to specify an area of the panel to format with your application. Refer to the
ISPF Dialog Developer’s Guide and Reference for more information.

The GRAPHIC AREA Tag

You specify a graphic area in the panel )BODY section by coding the GA tag. A
Graphic area allows you to define a specific portion of the screen for a GDDM
display. Refer to the ISPF Dialog Developer’s Guide and Reference for more
information.

The DIVIDER Tag

You can separate the elements on a panel or the regions you define for a panel
with the DIVIDER tag. A DIVIDER definition produces either a blank or visible
divider line, depending on the value you assign to the TYPE attribute of the
DIVIDER tag. The visible divider line can be a dashed line or a solid line, or it can
contain text.

The default value, NONE, produces a blank divider line. The values DASH,
SOLID, and TEXT produce a visible divider line.

For horizontally formatted dividers,

v When the GRAPHIC invocation option is specified, SOLID produces a solid line
for host display and DASH produces a dashed line.
v When NOGRAPHIC is specified or the panel is displayed in GUI mode, both
SOLID and DASH produce a dashed line.
Both SOLID and DASH use the “|” character (obtained from the ISPF literals
table) for vertically formatted dividers. The value TEXT (used in combination with
the FORMAT attribute) is valid only for dividers within vertical regions and
specifies that blank padding is used for the supplied text.

The GAP attribute specifies whether the divider line completely crosses the panel
area or region that contains the divider, or if a 1-character gap is to remain at
either end of a horizontally formatted divider. The valid values for the GAP
attribute are YES (the default), and NO.

The value you assign to GUTTER specifies the size (in characters) of the total
width of the divider. For vertical formatting the default is 1, because ISPF allots 1
line of screen space for the divider. For horizontal formatting the default GUTTER
size is 3, because an attribute byte is placed both before and after the divider
character. Any value above the default is split to either side of the divider. If the
GUTTER value is an even number, the conversion utility increases the number by 1
so that the divider is centered within the defined width. The GUTTER attribute is
useful for creating blank space on a panel.

The NOENDATTR attribute is valid only when formatting dividers within

horizontal regions. When NOENDATTR is specified, the ending attribute is not
added to the divider. With NOENDATTR and a GUTTER size of 1, a divider of
one blank character can be created. With a GUTTER size of 2, TYPE=SOLID can be
used to produce a visible divider.

The FORMAT attribute is valid only when formatting dividers within vertical
regions. The FORMAT attribute must be specified to have ISPDTLC process the
text provided with the DIVIDER tag. FORMAT specifies the text placement within
the divider line as START, CENTER, or END.

46 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 There are two DIVIDER tags defined in the following example. The first DIVIDER
does not specify a TYPE attribute, and produces a blank horizontal line. The
second DIVIDER specifies TYPE=SOLID, and produces a visible divider.
<!doctype dm system>
<panel name=fields1>Selections
<area>
<dtacol selwidth=24 pmtwidth=15>
<selfld name=item>Pick an item:
<choice>Widget
<choice>Doohickey
<choice>Gizmo
</selfld>
<divider>
<selfld name=color>Pick a color:
<choice>Red
<choice>Green
</selfld>
<divider type=solid gap=no>
<selfld name=size>Pick a size:
<choice>Miniscule
<choice>Behemoth
</selfld>
</dtacol>
</area>
<botinst>To exit the application, press F3.
</panel>

Figure 21 shows the result:

Selections

Pick an item:
__ 1. Widget
2. Doohickey
3. Gizmo

Pick a color:
__ 1. Red
2. Green
-------------------------------------------------------------------------
Pick a size:

__ 1. Miniscule
2. Behemoth

To exit the application, press F3.

Figure 21. Area Dividers

The dashed line in the second divider in the preceding example extends across the
entire AREA definition to both margins because we specified GAP=NO in the
DIVIDER definition.

The REGION Tag

You can further define the areas of your panel, and how you want the information
in the areas arranged, with the REGION tag. Using one or more regions within a
PANEL definition provides an easy way of arranging the elements on a panel. Like
the PANEL and AREA tags, the REGION end tag is required.

Chapter 3. Getting Started: Designing Application Panels 47

 The DIR (direction) attribute of the REGION tag specifies how the elements within
a region are arranged, either horizontally or vertically. The default value is VERT,
which arranges the elements within the region vertically. This means that if you do
not specify a horizontal region (DIR=HORIZ), or if you do not define a region at
all, the panel elements are arranged vertically by default.

For example, the selection fields in the following example are arranged vertically,
because no DIR value is defined for the REGION tag.
<!doctype dm system>
<panel name=fields2>Selections
<area>
<region>
<dtacol selwidth=24 pmtwidth=15>
<selfld name=item>Pick an item:
<choice>Widget
<choice>Doohickey
<choice>Gizmo
</selfld>
<divider>
<selfld name=color>Pick a color:
<choice>Red
<choice>Green
</selfld>
<divider type=solid gap=no>
<selfld name=size>Pick a size:
<choice>Miniscule
<choice>Behemoth
</selfld>
</dtacol>
</region>
</area>
<botinst>To exit the application, press F3.
</panel>

Selections

Pick an item:
__ 1. Widget
2. Doohickey
3. Gizmo

Pick a color:
__ 1. Red
2. Green
-------------------------------------------------------------------------

Pick a size:
__ 1. Miniscule
2. Behemoth

To exit the application, press F3.

Figure 22. Vertical Region

We’ll specify the HORIZ value for the region to change the layout of the selection
fields to horizontal. Figure 23 on page 49 shows the result.

48 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

<!doctype dm system>
<panel name=fields3>Selections
<area>
<region dir=horiz>
<dtacol selwidth=20 pmtwidth=15>
<selfld name=item>Pick an item:
<choice>Widget
<choice>Doohickey
<choice>Gizmo
</selfld>
<divider type=solid gutter=5>
<selfld name=color>Pick a color:
<choice>Red
<choice>Green
</selfld>
<divider type=solid gutter=5>
<selfld name=size>Pick a size:
<choice>Miniscule
<choice>Behemoth
</selfld>
</dtacol>
</region>
</area>
<botinst>To exit the application, press F3.
</panel>

Selections

Pick an item: | Pick a color: | Pick a size:

__ 1. Widget | __ 1. Red | __ 1. Miniscule
2. Doohickey | 2. Green | 2. Behemoth
3. Gizmo | |

To exit the application, press F3.

Figure 23. Horizontal Region

In the markup for this example, we also changed the format of the DIVIDER tags
to provide additional space and a visible line between the selection fields. We did
this by specifying TYPE=SOLID and GUTTER=5 on each of the DIVIDER tags. You
will notice another characteristic in the preceding example: the divider lines are
now vertical. That’s because of the manner DTL handles dividers within regions.
DTL adheres to the following formatting rules for DIVIDER tags within regions:
v A DIVIDER tag coded within a vertical region formats horizontally.
v A DIVIDER tag coded within a horizontal region formats vertically.

The following markup illustrates how REGION and DIVIDER tags format under
different circumstances. This example shows both horizontal and vertical regions,
as well as solid and blank dividers.

Chapter 3. Getting Started: Designing Application Panels 49

 <!doctype dm system>
<panel name=mainpan8>Application
<topinst>Complete the information below and press Enter.
<area>
<dtafld datavar=name entwidth=25 pmtwidth=9>Name
<dtafld datavar=addr entwidth=25 pmtwidth=9>Address
<region dir=horiz>
<dtafld datavar=city pmtwidth=9 entwidth=25>City
<dtafld datavar=stat pmtwidth=5 entwidth=2>State
<dtafld datavar=zip pmtwidth=8 entwidth=5>Zip code
</region>
<divider type=solid gutter=3>
<region dir=horiz>
<selfld name=grade pmtwidth=32 selwidth=33>Highest education level
<choice>Some high school
<choice>High school graduate
<choice>Some college
<choice>College graduate
<choice>Some post-graduate work
<choice>Post graduate degree
</selfld>
<divider gutter=5>
<region>
<info width=30>
<p compact>Complete if applicable:
</info>
<dtafld datavar=grad pmtwidth=10 entwidth=11>Date of graduation
<dtafld datavar=field pmtwidth=10 entwidth=11>Field of study
</region>
</region>
</area>
</panel>

Figure 24 shows how the preceding markup formats.

Application

Complete the information below and press Enter.

Name . . _________________________
Address _________________________
City . . _________________________ State __ Zip code _____

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

Complete if applicable:
Highest education level Date of
__ 1. Some high school graduation ___________
2. High school graduate Field of
3. Some college study . . ___________
4. College graduate
5. Some post-graduate work
6. Post graduate degree

Figure 24. Horizontal Region

This is an example of nesting regions. The data fields for entering the graduation
date and field of study are arranged in a vertical region that is nested within a
horizontal region.

| The ALIGN, DEPTH, EXTEND, INDENT, LOCATION, WIDTH, GRPBOX, and

| GRPWIDTH attributes allow additional formatting control. The DEPTH and

50 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

| EXTEND attributes are used with scrollable regions. ALIGN, INDENT,
| LOCATION, and WIDTH affect the placement of fields within the region and the
| placement of the region within the panel. GRPBOX and GRPWIDTH specify that
| the region should be displayed as a group box in GUI mode. The optional group
| box title is supplied as text following the REGION tag ending delimiter. When
| displayed on a host terminal, a panel defined with a group box will contain the
| group box title, but will not have a group box border.

Defining a Command Area

Many applications are dependent on a command area in their panels. You define a
command area and specify the prompt text of the command area with the
CMDAREA tag. The conversion utility supplies the prompt symbol (===>) and
provides the entry field in the command area for user input.

The conversion utility always formats the command area at the top of the panel.
An ISPF run-time option determines the actual display location of the command
line.

The command area contains an entry field and command prompt text, and is
normally displayed at the bottom of an application panel. Users can enter
commands in the command entry field. All commands entered into the command
entry field are validated against the commands you define within the application
command table and the ISPF-provided commands. For more information on
defining the application command table, see “Chapter 8. The Application
Command Table” on page 157.
<!doctype dm system (<!entity actnbar system>)>
<panel name=cmdxmp1>Application Name
&actnbar;
<topinst>Sample command area panel
<area>
</area>
<CMDAREA>
</panel>

Here’s how the command area displays on the panel:

Chapter 3. Getting Started: Designing Application Panels 51

 File View Options Help
-------------------------------------------------------------------------
Application Name

Sample command area panel

Command ===> ____________________________________________________________

Figure 25. Command Area

In Figure 25 we did not specify the text of the command prompt, so the conversion
utility automatically added the text “Command” (or its translated equivalent),
which is the default text. If we wanted to specify something other than this text,
we could have coded it as tag text, as in this example:
<!doctype dm system (<!entity actnbar system>)>
<panel name=cmdxmp2>Application Name
&actnbar;
<topinst>Sample command area panel
<area>
</area>
<cmdarea>Enter a command
</panel>

You can code up to 59 bytes of prompt text on a standard 76 byte width panel
when overriding the default text. Here’s how the command prompt looks now:

52 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 File View Options Help
-------------------------------------------------------------------------
Application Name

Sample command area panel

Enter a command ===> ____________________________________________________

Figure 26. Command Area

| Data entered on the command line can be forced to uppercase either by specifying
| CAPS = ON or by including a VARCLASS tag to define the command area and an
| XLATL tag to specify translation to uppercase. (The type attribute defines the space
| available on a standard 76 character width panel using the default command
| prompt.)
| <varclass name=vccmd type='char 59'>
| <xlatl format=upper>
| </xlatl>
| </varclass>
|
| <varlist>
| <varclass name=zcmd varclass=vccmd>
| </varclass>

| The AUTOTAB, CAPS, CMDLEN, CMDLOC, ENTWIDTH, IMAPNAME,

| IMAPNAMEP, NAME, NOINIT, NOJUMP, OUTLINE, PAD, PADC, PLACE,
| PMTTEXT, PSBUTTON, PSVAL, PSVAR, SCRCAPS, SCROLLTAB, SCROLLVAR,
| and SCRVHELP are attributes that control formatting, initialization, and
| presentation of the command area.

Defining Panel Defaults

DTL provides you with a tag that makes it easier for you to define attributes and
values that are common for multiple application panels: the PANDEF (panel
default) tag. This tag must be coded in the source file before any panels it is
providing defaults for.

The default PANEL values you can define with the PANDEF tag are:
v The panel dimensions (DEPTH and WIDTH)
v The help panel
v The key mapping list
v The KEYLTYPE value
v The CCSID number
v The WINDOW value
v The WINTITLE value
v The APPTITLE value

Chapter 3. Getting Started: Designing Application Panels 53

 v The PAD value
v The PADC value
v The OUTLINE value
v The EXPAND value.
v The MERGESAREA value
v APPLID value
v ENTKEYTEXT value
v IMAPNAME value
v IMAPROW value
v IMAPCOL value
v TMARGIN value
v BMARGIN value

You can use a PANDEF tag to define all of these values, or some of them. You can
also override a specific panel default value for a referencing panel by specifying
the attribute on the PANEL tag.

For instance, if you create a series of panels that all have the same dimensions and
that all refer to the same help panel and key mapping list, you can define these
values in a PANDEF definition, and refer to that definition in each of the
application panels that use those values. The DTL compiler does the rest of the
work for you, as long as the default definition is available as part of the same
source file as the panels that refer to it.

For example, if you are creating a series of panels that all share the same values,
you could create a PANDEF definition like this:

<!doctype dm system>

<pandef id=printdef help=prnthlp depth=20 width=70 keylist=printkey>

And refer to the panel default like this on all of the panels in that series:

<panel name=panel01 pandef=printdef>A Panel

.
.
.
</panel>

<panel name=panel02 pandef=printdef>Another Panel

.
.
.
</panel>

When you compile this source file, the PANDEF definition provides those values
for the panels that refer to the panel default.

You can also use the PANDEF tag to define common values for individual PANEL
attributes. For instance, if the only commonality between application panels is the
dimensions, you can use a panel default to define the dimensions and refer only to
those values in the application panel definitions:

<!doctype dm system>

<pandef id=size depth=20 width=70>

<panel name=panel01 help=help01

keylist=keylsta
. pandef=size>A Panel
.
.
</panel>

54 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

<panel name=panel02 help=help02
keylist=keylstb
. pandef=size>Another Panel
.
.
</panel>

Anytime you want to change the dimensions of the application panels that refer to
a panel default, you only have to make the change in one place: in the PANDEF
definition.

To override a PANDEF value, you must specify that value in the PANEL definition.
The following example contains a panel default that defines both dimensions and a
help panel. While all three PANEL definitions refer to the panel default, the panel
with the NAME value panel03 specifies a different help panel, and thus overrides
the PANDEF HELP value.

<!doctype dm system>

<pandef id=pandef01 depth=20 width=70 help=help01>

<panel name=panel01 pandef=pandef01>

.
.
.
</panel>

<panel name=panel02 pandef=pandef01>

.
.
.
</panel>

<panel name=panel03 pandef=pandef01 help=help02>

.
.
.
</panel>

You can also define multiple panel defaults within a single source file, like this:

<!doctype dm system>
<pandef id=pandef01 depth=20 width=70 help=help01>

<pandef id=pandef02 depth=10 width=50 help=help02 keylist=klist01>

<panel name=panel01 pandef=pandef01>

.
.
.
</panel>

<panel name=panel02 pandef=pandef02>

.
.
.
</panel>

<panel name=panel03 pandef=pandef01 help=help02>

.
.
.
</panel>

Chapter 3. Getting Started: Designing Application Panels 55

56 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Chapter 4. Variables and Variable Classes
Much of the information displayed within dialog elements is derived directly from
the tags used to define it. Other information is obtained dynamically when the
application is running, such as:
v Data that the user supplies
v Data that the application supplies
v Data that ISPF supplies.

In all of these cases, the data is derived from values specified in variables.

DTL provides you with tags to declare variables and to define the characteristics of
these variables using variable classes. Variables and variable classes are considered
global because they can be referred to by more than one element within the same
source file. All variables referred to by dialog elements should be declared.
Variable names and variable classes should be used consistently throughout dialog
elements that are used in the same application.

Variables declared using DTL are accessible to your application through the dialog
variable pools and variable services provided by ISPF. Within ISPF display
processing, all variable values are in character format. ISPF transforms display
variables between their dialog program format and internal display processing
character format when retrieving and storing variable values.

Compatibility Considerations

| Although the conversion utility processes all of the variable information

| provided in your DTL source file and issues suppressible warning messages
| for missing VARDCL tags during the processing of several other tags, such as
| DTAFLD and LSTCOL, ISPF does not require any of the tags described in the
| chapter to generate a valid ISPF panel.

| The conversion utility supports the SOURCE tag as an alternative means of

| placing variable processing and validation statements directly into the ISPF
| panel.

Declaring Variables
You declare variables for dialog elements by coding variable declarations within a
variable list. You also specify the variable class associated with each declared
variable.

The variable list (VARLIST) tag and its required end tag define the variable list.
You code the variable list after any variable classes and before any other tags.

To declare variables, use VARDCL (variable declaration) tags within the VARLIST
definition. The VARDCL tag has two required attributes, NAME and VARCLASS.
NAME The NAME attribute specifies the name of the variable used within
the DTL source file.

© Copyright IBM Corp. 1989, 2000 57

 For example, a data field definition includes a variable name in the
DATAVAR attribute to specify the variable that receives data when
the user enters data in the field.
VARCLASS The VARCLASS attribute specifies the variable class associated
with the variable declaration. Variable classes define the format
and length of variable data plus translations and checks to perform
on the data.

In this example, the variable list contains two variable declarations referred to by
the data fields in the application panel.

<!doctype dm system>

<varclass name=authorc type='char 40'>

<varclass name=catnumc type='char 10'>

<varlist>
<vardcl name=author varclass=authorc>
<vardcl name=catnum varclass=catnumc>
</varlist>

<panel name=books1>Book Title Search

<area>
<dtacol pmtwidth=20>
<dtafld entwidth=40 datavar=author>Author
<dtafld entwidth=10 datavar=catnum>Catalog number
</dtacol>
</area>
</panel>

Note:

| The ISPF Dialog Tag Language conversion utility does not require that you
| code the VARCLASS, VARDCL, or VARLIST tags for a successful generation
| of a panel, command table, or message member that includes variables. If
| the conversion utility finds a variable that does not have an associated
| VARDCL definition, it issues a suppressible warning message.

The use of the VARCLASS, VARDCL, and VARLIST tags is required if you
want to use the facilities provided by the CHECKL and XLATL tags.

Defining Variable Classes

To complete the preceding example, we must code the variable classes that are
referred to with the VARDCL VARCLASS attributes. The variable class information
must be defined if the conversion utility is to generate )INIT and )PROC section
statements for variable translations and validations. ( “Variable Validation” on
page 61 tells you how to define translations and validity checks.)

The VARCLASS (variable class) tag defines a variable class. You include variable
classes in the same source file as the dialog elements and variable list that refer to
them. Additionally, you must code variable classes in the source file before the
variable list and dialog element definitions. You do this by coding variable classes
following the DOCTYPE statement or by coding this information in an external file
and embedding the file following the DOCTYPE statement.

There are two required attributes associated with the VARCLASS tag: NAME and
TYPE.

58 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 NAME
The NAME attribute is used to identify and refer to the variable class.
TYPE The TYPE attribute is used to define the format and entry-field width for
variable data.

In addition to the required attributes described above, the VARCLASS tag has an
optional MSG attribute. This attribute specifies the message to be displayed if the
variable fails any defined validity checks and no message is defined for the XLATL
or CHECKL tags. “Chapter 7. Messages” on page 151 tells you how to define
messages.

Variable Class Types

DTL supports character variables and numeric variables. In addition, the
conversion utility uses the length specified in the TYPE attribute value of the
VARCLASS tag to determine the entry width of fields associated with the
VARCLASS tag if this width is not defined with the tag used to create the field.
For more information on defining field entry widths, see “Chapter 5. Application
Panel Fields” on page 77.

Character Variables
You can specify whether single-byte characters, double-byte characters, or mixed
double- and single-byte characters are permitted, as well as the maximum number
of bytes the variable can accept. Each type is described below:
Type Description
'CHAR maximum-length' Specifies a single-byte character string.
'DBCS maximum-length' Specifies a double-byte character string. The
maximum length must be an even number.
'MIXED maximum-length' Specifies a character string containing single-byte
characters, double-byte characters, or both.

Note: This type is treated as CHAR if the system

does not support double-byte characters.
'ANY maximum-length' Specifies a character string containing single-byte
characters, double-byte characters, or both. It is
processed by the conversion utility as MIXED.
'EBCDIC maximum-length' Specifies a single-byte character string.
'%varname maximum-length' Specifies that a variable name will be used for
TYPE in the Panel definition. The application must
ensure a valid type is set before the panel is
displayed.
'VMASK maximum-length' A VEDIT statement is added to the generated
panel. The ‘maximum-length’ is the default length
for associated variables. The application must use
the VMASK service with a user-specified mask
value.
'ITIME' A VEDIT statement is added to the generated
panel for associated variables. The default length
for the variables is 5. The application must use the
VMASK service with a mask of ITIME.

Chapter 4. Variables and Variable Classes 59

 'STDTIME' A VEDIT statement is added to the generated
panel for associated variables. The default length
for the variables is 8. The application must use the
VMASK service with a mask of STDTIME.
'IDATE' A VEDIT statement is added to the generated
panel for associated variables. The default length
for the variables is 8. The application must use the
VMASK service with a mask of IDATE.
'STDDATE' A VEDIT statement is added to the generated
panel for associated variables. The default length
for the variables is 10. The application must use the
VMASK service with a mask of STDDATE.
'JDATE' A VEDIT statement is added to the generated
panel for associated variables. The default length
for the variables is 6. The application must use the
VMASK service with a mask of JDATE.
'JSTD' A VEDIT statement is added to the generated
panel for associated variables. The default length
for the variables is 8. The application must use the
VMASK service with a mask of JSTD.

We’ll add the variable classes for authorc and catnumc to the markup example on
page 58. We will assume that an author’s last name has a maximum of 40
characters and that a catalog number is 10 characters.
<!doctype dm system>

<varclass name=authorc type='char 40'>

<varclass name=catnumc type='char 10'>

<varlist>
<vardcl name=author varclass=authorc>
<vardcl name=catnum varclass=catnumc>
</varlist>

<panel name=books2>Book Title Search

<area>
<dtacol pmtwidth=20>
<dtafld entwidth=40 datavar=author>Author
<dtafld entwidth=10 datavar=catnum>Catalog number
</dtacol>
</area>
</panel>

Numeric Variables
You can use the NUMERIC type to ensure that a valid number is entered in the
associated field. You can specify the total number of digits (up to 16) allowed in
the number and the number of fractional digits allowed. The conversion utility will
generate a VER(variable ENUM) statement for input validation.

For example, the following variable class specifies that the data entered in the
associated field has a maximum number of five digits, two of which are fractional.
<varclass name=pricevar type='numeric 5 2'>

If you do not specify an entry width with the tag that defines the associated field,
the conversion utility will calculate an entry width for the field based on the
NUMERIC value and allow for a sign, thousands separators, and a decimal point.

60 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

Variable Validation
DTL allows you to define translate lists and validity checks as part of the variable
class definition by using tags nested within the VARCLASS tag. These built-in
translations and checks are especially useful because ISPF automatically performs
them on variable values, so the dialog application doesn’t need to.

Note: Translations and checks are performed only on variable values that are
intended for display. For instance, before displaying the data from a variable
specified on the DATAVAR attribute of a DTAFLD tag, ISPF performs any
specified translations on the variable retrieved from the application to
construct the correct display value. However, ISPF does not perform
translations on a variable specified as the CHECKVAR attribute of a
CHOICE tag.

Translate Lists
Translate lists provide a means of translating a displayed variable value into a
different dialog variable pool value, and vice versa. Translation can occur on input
(when the user enters a value), on output (the value stored in the variable pool is
translated before the user sees it), or both. This is based on the USAGE value of
the tag that refers to a variable using a variable class with translate lists.

To associate a translate list with a variable class, code the XLATL (translate list) tag
and its required end tag within the VARCLASS definition.

The type of translation is determined by the value assigned to the FORMAT

attribute of the XLATL tag. The two types of translations supported are:
v Uppercase translation
v Item translation

There is an optional MSG attribute on the XLATL tag that allows you to specify
your own message to display when input translation specified by the XLATL does
not result in a match. For information about defining your own messages, see
“Chapter 7. Messages” on page 151.

Upper
Allows you to translate a value to uppercase. To specify this translation, code
FORMAT=UPPER on the XLATL tag. This translation is always successful.

We’ll add a translate list to the authorc variable class in the example on page 60.
The translate list converts the author’s name to uppercase.

<varclass name=authorc type='CHAR 40' msg=liba001>

<xlatl format=upper>
</xlatl>

The following figure shows the results on input and output translations for the
previous example.

Chapter 4. Variables and Variable Classes 61

 Input:
User-entered value Value stored in pool
┌───────────┐ ┌──────┐
│ AuThor │ ─────────────────Ê │AUTHOR│
└───────────┘ Translates to └──────┘

Output:
Value in Pool Displayed to User
┌───────────┐ ┌──────┐
│ AuThor │ ─────────────────Ê │AUTHOR│
└───────────┘ Translates to └──────┘

Figure 27. Variable Translation Results

Item Translation
Allows you to translate an internal variable value to a displayed value (or
vice-versa) on an item-for-item basis. To specify this translation, either code
FORMAT=NONE on the XLATL tag or omit the FORMAT attribute because this is
the default. You define the list of possible internal values and the corresponding
display values they should be translated to, or from, using the XLATI (translate
item) tags nested within the XLATL tag.

To specify an internal value (the value in the variable pool) for a translate item, use
the VALUE attribute on the XLATI tag. The XLATI tag text specifies what the user
sees (for output) and enters (for input).

The display value is the XLATI tag text. If a display value of all blanks or a
display value in which leading, trailing, or embedded blanks are preserved is
desired, use the literal (LIT) tag and its required end tag to indicate that blanks are
significant.

An explicit match is achieved during translation processing as follows:

v On input, an explicit match occurs when the value the user enters matches one
of the specified display values in the translate list. An explicit match also occurs
when a display value is omitted (indicating any value is acceptable) and the
corresponding internal value is specified.
v On output, an explicit match occurs when the value from the variable pool
matches one of the specified internal values in the translate list. An explicit
match also occurs when an internal value is omitted (indicating any value is
acceptable) and the corresponding display value is specified.

Omitting both the internal value and the display value does not produce an
explicit match. This case is discussed later in this section.

Translate list processing is case-sensitive. To ensure that a match results when the
user enters the correct display value but in a different or mixed case, code an
uppercase conversion translate list before the value translate list.

In the following example, we define the variable class dayc to use an internal value
for days of the week that is different from the display value. We also ensure that
comparisons will be on uppercase values by defining a translate list with
FORMAT=UPPER before the item translation list.

62 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

<!doctype dm system>

<varclass name=dayc type='CHAR 9'>

<xlatl format=upper>
</xlatl>
<xlatl msg=liba004>
<xlati value=1>SUNDAY
<xlati value=2>MONDAY
<xlati value=3>TUESDAY
<xlati value=4>WEDNESDAY
<xlati value=5>THURSDAY
<xlati value=6>FRIDAY
<xlati value=7>SATURDAY
</xlatl>

The following figure shows how variable values of variable class dayc are
translated on input and output.

Input:
User-entered value Internal value
┌─────────┐ ┌─┐
│Wednesday│ ─────────────────Ê │4│
└─────────┘ Translates to └─┘

Output:
Internal value Displayed value
┌─┐ ┌─────────┐
│7│ ─────────────────Ê │SATURDAY │
└─┘ Translates to └─────────┘

Figure 28. Variable Translation

The previous example shows one translate list with a finite number of translation
items. This example assumes that the only possible internal values are 1–7 and the
only possible display values are the days of the week. For input fields, a match
must be found in this list, or the translation fails and message liba004 is displayed
to the user.

To allow a nonmatching value to be passed on for further processing (either to

another translate list or to the validity checks that follow), you code an XLATI tag
without an internal-value or a display-value to indicate that any value is acceptable,
as in the following example.

<!doctype dm system>

<varclass name=dayc type='CHAR 9'>

<xlatl format=upper>
</xlatl>
<xlatl>
<xlati value=1>SUNDAY
<xlati value=2>MONDAY
<xlati value=3>TUESDAY
<xlati value=4>WEDNESDAY
<xlati value=5>THURSDAY
<xlati value=6>FRIDAY
<xlati value=7>SATURDAY
<xlati>
</xlatl>

Chapter 4. Variables and Variable Classes 63

 Because multiple translate lists are permitted, we can expand this example to
accept either the days of the week spelled out or their accepted abbreviations.
Because the last XLATI tag in the first translate list has no internal or displayed
value, the input value will be passed on for further translate list or validity
checking.
<!doctype dm system>

<varclass name=dayc type='CHAR 9'>

<xlatl format=upper>
</xlatl>
<xlatl>
<xlati value=1>SUNDAY
<xlati value=2>MONDAY
<xlati value=3>TUESDAY
<xlati value=4>WEDNESDAY
<xlati value=5>THURSDAY
<xlati value=6>FRIDAY
<xlati value=7>SATURDAY
<xlati>
</xlatl>
<xlatl>
<xlati value=1>SUN
<xlati value=2>MON
<xlati value=3>TUES
<xlati value=4>WED
<xlati value=5>THUR
<xlati value=6>FRI
<xlati value=7>SAT
</xlatl>

It is possible to omit only the internal value to indicate that any internal value is
acceptable. This affects input and output translate processing differently. When
translating on input, the value is not translated before being stored in the variable
pool. When translating on output, any value not already matched is translated to
the displayed value.

In the following example, the branchc variable class illustrates translate processing
when only the internal value is omitted.
<!doctype dm system>

<varclass name=branchc type='CHAR 3'>

<xlatl format=upper>
</xlatl>
<xlatl>
<xlati value=1>RAL
<xlati>CRY
</xlatl>

64 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

Input:
User-entered value Internal Value
┌───┐ ┌───┐
│CRY│ ─────────────────Ê │CRY│
└───┘ Translates to └───┘

Output:
Internal Value Displayed Value
┌─┐ ┌───┐
│7│ ─────────────────Ê │CRY│
└─┘ Translates to └───┘

Figure 29. Variable Translation

It is also possible to omit only the display value to indicate that any display value
is acceptable. This affects input and output translate processing differently. When
translating on input, any value not already matched is translated to the internal
value. When translating on output, the internal value is not translated before it is
displayed.

We’ll change the branchc variable class to illustrate translate processing when only
the display value is omitted.
<!doctype dm system>

<varclass name=branchc type='CHAR 3'>

<xlatl format=upper>
</xlatl>
<xlatl>
<xlati value=1>RAL
<xlati value=2>
</xlatl>

Input:
User-entered value Internal Value
┌───┐ ┌─┐
│CRY│ ─────────────────Ê │2│
└───┘ Translates to └─┘

Output:
Internal Value Displayed Value
┌─┐ ┌─┐
│2│ ─────────────────Ê │2│
└─┘ Translates to └─┘

Figure 30. Variable Translation

It is possible to specify that less than the full input value be entered by the use of
the TRUNC attribute. Output translation is not affected.

We’ll change the branchc variable class again to illustrate.

<!doctype dm system>

<varclass name=branchc type='CHAR 3'>

<xlatl format=upper>
</xlatl>

Chapter 4. Variables and Variable Classes 65

 <xlatl format=none trunc=1>
<xlati value=1>RAL
<XLATI VALUE=2>
</xlatl>

Input:
User-entered Value Internal Value
┌─┐ ┌─┐
│R│ ─────────────────Ê │1│
└─┘ Translates to └─┘

Output:
Internal Value Displayed Value
┌─┐ ┌───┐
│1│ ─────────────────Ê │RAL│
└─┘ Translates to └───┘

Validity Checks
You use validity checks to automatically verify data input by the user. Validity
checks are coded after any translate lists.

To associate a validity check with a variable class, code the CHECKL (check list)
tag and its required end tag either following the last translate list, or if no translate
list exists, following the VARCLASS start tag. The individual check item that
defines the test to perform is coded using the CHECKI (check item) tag nested
within the check list. You can code one CHECKI tag in a CHECKL definition.
However, you can code multiple CHECKL tags within a variable class definition.

There is an optional MSG attribute on the CHECKL tag that allows you to specify
your own message to display when the entered value fails the test. If you do not
specify a message, ISPF Dialog Manager supplies a default message for you. For
more information about defining your own messages, see “Chapter 7. Messages”
on page 151.

A value entered by the user must pass the check item test for the check list to be
considered successful. Furthermore, because there can be multiple check lists
defined, all check lists must be successful for the validation to be successful.

The TYPE attribute of the CHECKI tag allows you to specify the various validity
tests of the input. You can define the following types of validity checks:
v RANGE
v ALPHA
v VALUES
v VALUESX
v CHARS (limited to characters for HEX, BIT, and NUM tests)
v FILEID
v DSNAME
| v DSNAMEF
| v DSNAMEFM
| v DSNAMEPQ
v DSNAMEQ
v NAME
| v NAMEF
v DBCS
v EBCDIC
v MIX

66 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 v ALPHAB
v PICT
| v PICTCN
v LISTV
v LISTVX
v LEN
v ENUM
v BIT
v NUM
v HEX
v INCLUDE
| v IDATE
| v STDDATE
| v JDATE
| v JSTD
| v ITIME
| v STDTIME

RANGE
To perform a range test, specify the check item TYPE attribute as RANGE. A range
check allows you to check a value within a numeric range including the end
points. The PARM1 attribute specifies the lower bound; PARM2 specifies the upper
bound. The range delimiters can include 16 digits, and may contain a preceding
sign (− or +).

The following example of a NUMERIC variable class contains a range check that
ensures that catalog numbers are in the range 50 to 90000000.

<!doctype dm system>

<varclass name=catnumc type='NUMERIC 8'>

<checkl msg=liba005>
<checki type=range parm1=50 parm2=90000000>
</checkl>

The conversion utility generates an ISPF range verification statement in the )PROC
section.

ALPHA
To perform an alphabetic test, specify the check item TYPE attribute as ALPHA.
An alpha check limits the characters allowed to A–Z, a–z, #, $, and @.

The following example of an alpha check in the authorc variable class ensures that
authors’ names are alphabetic.

<!doctype dm system>

<varclass name=authorc type='CHAR 40'>

<checkl msg=liba006>
<checki type=alpha>
</checkl>

The conversion utility generates an ISPF alpha verification statement in the )PROC
section.

VALUES
To perform a values test, specify the check item TYPE attribute as VALUES. A
values test allows you to specify a list of values. The value the user enters must

Chapter 4. Variables and Variable Classes 67

 match one of the values in the list. The PARM1 attribute must have the value EQ.
The PARM2 attribute specifies the list of values. Because case is respected in a
VALUES check, if you want case to be ignored, you must code an UPPER
translation and code the values all in uppercase.

The following example of a check in a variable class named subject ensures that the
value entered is MATH, SCIENCE, ENGLISH, or HISTORY.
<!doctype dm system>

<varclass name=subject type='char 10'>

<xlatl format=upper>
</xlatl>
<checkl msg=liba008>
<checki type=values parm1=eq
parm2='MATH SCIENCE ENGLISH HISTORY'>
</checkl>

The conversion utility generates a LIST verification statement in the )PROC section.

VALUESX
The check item type VALUESX is the opposite of VALUES. This test allows you to
specify a list of values that are not valid. The PARM1 attribute must have the
value NE. The PARM2 attribute specifies the list of values that are not valid. The
value the user enters cannot match any of the values specified in the list. Because
case is respected in a VALUESX check, if you want case to be ignored, you must
code an UPPER translation and code the values all in uppercase.

The following example of a check in a variable class named subject ensures that the
value entered is not MATH, SCIENCE, ENGLISH, or HISTORY.
<!doctype dm system>

<varclass name=subject type='char 10'>

<xlatl format=upper>
</xlatl>
<checkl msg=liba008>
<checki type=valuesx parm1=ne
parm2='MATH SCIENCE ENGLISH HISTORY'>
</checkl>

The conversion utility generates a LISTX verification statement in the )PROC

section.

CHARS
The conversion utility supports BIT, HEX and NUM validation with
TYPE=CHARS. The PARM1 attribute must have the value EQ. The PARM2
attribute value can be either “01” for BIT validation, “0123456789ABCDEFabcdef”
for HEX validation, or “0123456789” for NUM validation.

The following example of a check list in the hexc variable class validates
hexadecimal values.
<!doctype dm system>

<varclass name=hexc type='char 2'>

<checkl msg=liba008>
<checki type=chars parm1=eq parm2='0123456789ABCDEFabcdef'>
</checkl>

The conversion utility generates an ISPF hex verification statement in the )PROC
section.

68 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 FILEID
To perform a FILEID test, specify the check item TYPE attribute as FILEID.

The following example of a FILEID check in the infile variable class ensures that
specified variables contain a valid file ID in CMS syntax.

<!doctype dm system>

<varclass name=infile type='CHAR 20'>

<checkl msg=liba010>
<checki type=fileid>
</checkl>

The conversion utility generates an ISPF FILEID verification statement in the

)PROC section.

DSNAME
To perform a DSNAME test, specify the check item TYPE attribute as DSNAME.

The following example of a DSNAME check in the namefile variable class ensures
that the specified variables contain a valid TSO file name.

<!doctype dm system>

<varclass name=namefile type='CHAR 44'>

<checkl msg=liba011>
<checki type=dsname>
</checkl>

The conversion utility generates a DSNAME verification statement in the )PROC

section.

| DSNAMEF
| To perform a DSNAMEF test, specify the check item TYPE attribute as DSNAMEF.

| The following example of a DSNAMEF check in the namefile variable class ensures
| that the specified variables contain a valid TSO file name.
|
| <!doctype dm system>
|
| <varclass name=namefile type='CHAR 44'>
| <checkl msg=liba011>
| <checki type=dsnamef>
| </checkl>

| The conversion utility generates a DSNAMEF verification statement in the )PROC

| section.

| DSNAMEFM
| To perform a DSNAMEFM test, specify the check item TYPE attribute as
| DSNAMEFM.

| The following example of a DSNAMEFM check in the namefile variable class

| ensures that the specified variables contain a valid TSO file name.
|
| <!doctype dm system>
|

Chapter 4. Variables and Variable Classes 69

| <varclass name=namefile type='CHAR 44'>
| <checkl msg=liba011>
| <checki type=dsnamefm>
| </checkl>

| The conversion utility generates a DSNAMEFM verification statement in the

| )PROC section.

| DSNAMEPQ
| To perform a DSNAMEPQ test, specify the check item TYPE attribute as
| DSNAMEPQ.

| The following example of a DSNAMEPQ check in the namefile variable class

| ensures that the specified variables contain a valid TSO file name.
|
| <!doctype dm system>
|
| <varclass name=namefile type='CHAR 44'>
| <checkl msg=liba011>
| <checki type=dsnamepq>
| </checkl>

| The conversion utility generates a DSNAMEPQ verification statement in the

| )PROC section.

DSNAMEQ
To perform a DSNAMEQ test, specify the check item TYPE attribute as
DSNAMEQ.

The following example of a DSNAMEQ check in the namefile variable class ensures
that the specified variables contain a valid TSO file name.

<!doctype dm system>

<varclass name=namefile type='CHAR 44'>

<checkl msg=liba011>
<checki type=dsnameq>
</checkl>

The conversion utility generates a DSNAMEQ verification statement in the )PROC

section.

NAME
To perform a NAME test, specify the check item TYPE attribute as NAME.

The following example of a NAME check in the chapters variable class ensures that
the variable contains a valid name, following the rules of member names.

<!doctype dm system>

<varclass name=chapters type='CHAR 8'>

<checkl msg=liba012>
<checki type=name>
</checkl>

The conversion utility generates a NAME verification statement in the )PROC

section.

| NAMEF
| To perform a NAMEF test, specify the check item TYPE attribute as NAMEF.

70 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

| The following example of a NAMEF check in the chapters variable class ensures
| that the variable contains a valid name, following the rules of member names.
|
| <!doctype dm system>
|
| <varclass name=chapters type='CHAR 8'>
| <checkl msg=liba012>
| <checki type=namef>
| </checkl>

| The conversion utility generates a NAMEF verification statement in the )PROC

| section.

DBCS
To perform a DBCS test, specify the check item TYPE attribute as DBCS.

The following example of a DBCS check in the dbdesc variable class ensures that
specified variables contain valid DBCS characters.

<!doctype dm system>

<varclass name=dbdesc type='DBCS 12'>

<checkl msg=liba013>
<checki type=dbcs>
</checkl>

The conversion utility generates a DBCS verification statement in the )PROC

section.

EBCDIC
To perform an EBCDIC test, specify the check item TYPE attribute as EBCDIC.

The following example of an EBCDIC check in the title variable class ensures that
specified variables contain valid EBCDIC characters.

<!doctype dm system>

<varclass name=title1 type='CHAR 40'>

<checkl msg=liba014>
<checki type=ebcdic>
</checkl>

The conversion utility generates an EBCDIC verification statement in the )PROC

section.

MIX
To perform a MIX test, specify the check item TYPE attribute as MIX.

The following example of a MIX check in the title2 variable class ensures that
specified variables contain valid DBCS and EBCDIC characters.

<!doctype dm system>

<varclass name=title2 type='CHAR 40'>

<checkl msg=liba015>
<checki type=mix>
</checkl>

The conversion utility generates a MIX verification statement in the )PROC section.

Chapter 4. Variables and Variable Classes 71

 ALPHAB
To perform an ALPHAB test, specify the check item TYPE attribute as ALPHAB.
An ALPHAB check limits the characters allowed to A–Z or a–z. Blanks are not
allowed.

The following example of an ALPHAB check in the chapters variable class ensures
that chapters’ names are alphabetic.

<!doctype dm system>

<varclass name=chapters type='CHAR 8'>

<checkl msg=liba016>
<checki type=alphab>
</checkl>

The conversion utility generates an ALPHAB verification statement in the )PROC

section.

PICT
To perform a PICT check, specify the check item TYPE attribute as PICT. A PICT
check allows you to specify a pattern used to validate the variable. The PARM1
attribute must have the value EQ. The PARM2 attribute contains the validation
character string.

The following example of a PICT check in the socsec variable class validates the
format of a social security number.

<!doctype dm system>

<varclass name=socsec type='CHAR 11'>

<checkl msg=liba017>
<checki type=pict parm1=eq parm2='nnn-nn-nnnn'>
</checkl>

The conversion utility generates a PICT verification statement in the )PROC

section.

| PICTCN
| To perform a PICTCN check, specify the check item TYPE attribute as PICTCN. A
| PICTCN check allows you to specify a pattern containing required characters to
| validate the variable. The PARM1 attribute contains a mask character. The PARM2
| attribute contains the field-mask. The PARM3 attribute contains the validation
| string.

| The following example of a PICTCN check in the socsec variable class validates the
| format of a social security number, including the hyphen (-) character in positions
| 4 and 7.
|
| <!doctype dm system>
|
| <varclass name=socsec type='CHAR 11'>
| <checkl msg=liba017>
| <checki type=pictcn parm1='*' parm2='***-**-****'
| parm3='nnn-nn-nnnn'>
| </checkl>

| The conversion utility generates a PICTCN verification statement in the )PROC

| section.

72 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

LISTV
To perform a LISTV check, specify the check item TYPE attribute as LISTV. A
LISTV test allows you to provide a variable name that has been defined by your
application to contain a list of valid variable values. The PARM1 attribute must
have the value EQ. The PARM2 attribute must be a variable name entered with
“%” as the first character.

The following example of a LISTV check in the majors variable class validates
major subjects, providing the application has previously defined the listitem
variable to contain the value “MATH SCIENCE ENGLISH HISTORY”.

<!doctype dm system>

<varclass name=majors type='CHAR 8'>

<checkl msg=liba018>
<checki type=listv parm1=eq parm2=%listitem>
</checkl>

The conversion utility generates a LISTV verification statement in the )PROC

section.

LISTVX
The check item type LISTVX is the opposite of LISTV. A LISTVX test allows you to
provide a variable name that has been defined by your application to contain a list
of variable values that are not valid. PARM1 attribute must have the value NE. The
PARM2 attribute must be a variable name entered with “%” as the first character.

The following example of a LISTVX check in the majors variable class validates
major subjects, providing the application has previously defined the listitem
variable to contain the value “MATH SCIENCE ENGLISH HISTORY”.

<!doctype dm system>

<varclass name=majors type='CHAR 8'>

<checkl msg=liba018>
<checki type=listvx parm1=ne parm2=%listitem>
</checkl>

The conversion utility generates a LISTVX verification statement in the )PROC

section.

LEN
To perform a LEN check, specify the check item TYPE attribute as LEN. A LEN
test allows you to validate the length of the variable. The PARM1 attribute can be a
relational operator or a variable name that contains a relational operator. Valid
relational operators are EQ, LT, GT, LE, GE, NE, NG, or NL. If a variable name is
used, it must be preceded by a “%”. The PARM2 value can be either a number or a
variable name that contains the number. If you enter a number, it must be in the
range of 1–99999. If you use a variable name, it must be preceded by a “%”.

The following example of a LEN check in the chapters variable class validates the
length of chapter names.

<!doctype dm system>

<varclass name=chapters type='CHAR 8'>

<checkl msg=liba019>
<checki type=len parm1=le parm2=8>
</checkl>

Chapter 4. Variables and Variable Classes 73

 The conversion utility generates a LEN verification statement in the )PROC section.

ENUM
To perform an ENUM check, specify the check item TYPE attribute as ENUM. An
ENUM check allows you to verify a variable as extended numeric. ISPF verifies
variable values for correct decimal and comma notation plus correct sign
placement.

The following example of an ENUM check in the quantity variable class ensures
that specified variables are in correct extended numeric format.

<!doctype dm system>

<varclass name=quantity type='CHAR 10'>

<checkl msg=liba020>
<checki type=enum>
</checkl>

The conversion utility generates an ENUM verification statement in the )PROC

section.

BIT
To perform a BIT check, specify the check item TYPE as BIT. A BIT check allows
you to verify that a variable contains only 0’s and 1’s.

The following example of a BIT check in the choices variable class ensures that
specified variables are in BIT format.

<!doctype dm system>

<varclass name=choices type='CHAR 1'>

<checkl msg=liba021>
<checki type=bit>
</checkl>

NUM
To perform a NUM check, specify the check item TYPE attribute as NUM. A NUM
check allows you to verify a variable as a numeric character 0–9.

The following example of a NUM check in the numbers variable class ensures that
specified variables are numeric.

<!doctype dm system>

<varclass name=numbers type='CHAR 5'>

<checkl msg=liba022>
<checki type=num>
</checkl>

HEX
To perform a HEX check, specify the check item TYPE attribute as HEX. A HEX
check allows you to specify a variable that contains only hexadecimal characters
(0–9, A–F).

The following example of a HEX check in the hexc variable class validates
hexadecimal values.

<!doctype dm system>

74 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 <varclass name=hexc type='CHAR 2'>
<checkl msg=liba008>
<checki type=hex>
</checkl>

INCLUDE
To perform an INCLUDE check, specify the TYPE attribute as INCLUDE, and, at a
minimum, the PARM2 attribute as ALPHA, ALPHAB, or NUM. The PARM1 and
PARM3 attributes are optional.

The following example of an INCLUDE check in the incl variable class will allow
an imbedded blank and validate the values for both the ALPHA and NUM
characters as defined earlier.

<!doctype dm system>

<varclass name=incl type='CHAR 10'>

<checkl msg=liba023>
<checki type=include parm1=IMBLK parm2=ALPHA parm3=NUM>
</checkl>

Note: Refer to the ISPF Dialog Developer’s Guide and Reference for additional
information concerning panel variable verification.

| IDATE
| To perform an IDATE check, specify the TYPE attribute as IDATE. An IDATE check
| allows you to validate an 8 character international date, including the national
| language date delimiter. The format for the United States is YY/MM/DD.

| The following example validates an IDATE.

|
| <!doctype dm system>
|
| <varclass name=idate type='CHAR 8'>
| <checkl msg=liba024>
| <checki type=idate>
| </checkl>

| STDDATE
| To perform an STDDATE check, specify the TYPE attribute as STDDATE. An
| STDDATE check allows you to validate a 10 character standard date, including the
| national language date delimiter. The format for the United States is
| YYYY/MM/DD.

| The following example validates an STDDATE.

|
| <!doctype dm system>
|
| <varclass name=stddate type='CHAR 10'>
| <checkl msg=liba025>
| <checki type=stddate>
| </checkl>

| JDATE
| To perform a JDATE check, specify the TYPE attribute as JDATE. A JDATE check
| allows you to validate a 6 character Julian date. The format is YY.DDD.

| The following example validates a JDATE.

Chapter 4. Variables and Variable Classes 75

|
| <!doctype dm system>
|
| <varclass name=jdate type='CHAR 6'>
| <checkl msg=liba026>
| <checki type=jdate>
| </checkl>

| JSTD
| To perform a JSTD check, specify the TYPE attribute as JSTD. A JSTD check allows
| you to validate an 8 character Julian date. The format is YYYY.DDD.

| The following example validates a JSTD.

|
| <!doctype dm system>
|
| <varclass name=jstd type='CHAR 8'>
| <checkl msg=liba026>
| <checki type=jstd>
| </checkl>

| ITIME
| To perform an ITIME check, specify the TYPE attribute as ITIME. An ITIME check
| allows you to validate a 5 character international time, including the national
| language time delimiter. The format for the United States is HH:MM.

| The following example validates an ITIME.

|
| <!doctype dm system>
|
| <varclass name=itime type='CHAR 5'>
| <checkl msg=liba027>
| <checki type=itime>
| </checkl>

| STDTIME
| To perform a STDTIME check, specify the TYPE attribute as STDTIME. A
| STDTIME check allows you to validate an 8 character standard time, including the
| national language time delimiter. The format for the United States is HH:MM:SS.

| The following example validates a STDTIME.

|
| <!doctype dm system>
|
| <varclass name=stdtime type='CHAR 8'>
| <checkl msg=liba028>
| <checki type=stdtime>
| </checkl>

| Overriding Variable Classes

Some tags, such as DTAFLD, allow you to specify a different variable class for a
variable other than the default one that was specified when the variable was
declared using the VARDCL tag. This is called an overriding variable class and is
used to perform different translates and validity checks from those provided by the
default variable class.

76 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

Chapter 5. Application Panel Fields
Most of the direct interaction that takes place between the user and the application
is through the use of interactive fields. They provide a means for the user to
communicate data to the application, as well as receive data from the application.

The type of interaction the user has with the application depends on the task. The
task, in turn, determines the fields’ characteristics. The appearance of the fields, the
application’s response to user input, and assistance such as messages and help
information must all be considered when defining an interactive field.

In this chapter, we tell you how to use the Dialog Tag Language to define the
following types of fields and their operating characteristics:
v Data fields
v Selection fields
v List fields.

This chapter begins with a description of field prompts for data fields and
selection fields.

Field Prompts
A field prompt is static, descriptive text that explains the field it is associated with.
Data fields and selection fields support the use of field prompts. To define a field
prompt for a data field or selection field, specify the prompt text as the tag text on
the DTAFLD and SELFLD tags.

The PMTLOC attribute defines the location of the prompt using one of the
following values:
PMTLOC = ABOVE
The prompt appears above and left-aligned with the field. This is the
default for selection fields.
PMTLOC = BEFORE
The prompt appears directly in front of and on the same line as the field.
This is the default for data fields.

You should define the amount of space the prompt uses by specifying the
PMTWIDTH attribute on the DTAFLD and SELFLD tags. If the prompt text is
longer than the width you specify on PMTWIDTH, the prompt is word-wrapped
on multiple lines. Using the PMTWIDTH attribute can ensure that multiple fields
with prompts are aligned evenly. If you do not specify PMTWIDTH, the field
prompt length is determined by the length of the prompt text.

When PMTLOC=BEFORE, the conversion utility inserts leader dots at the end of
the prompt text to fill the specified prompt width. For output-only data fields, a
colon is used in place of the last leader dot. For fields with this prompt location, it
is a good idea to specify a PMTWIDTH with a value that allows for leader dots
after the prompt text. This lends consistency to the panel appearance. The
conversion utility issues a warning message when there is insufficient space for
leader dots.

© Copyright IBM Corp. 1989, 2000 77

 Figure 31 shows how prompts appear.

Application Name

Name . . . . ____________________
Address . . ____________________
City . . . . ____________________
State . . . __

Method of payment
Age . . . . __ 1. 0 - 12 __ 1. Cash
2. 13 - 19 2. Check
3. 20 - 29 3. Credit card
4. 30 - 49
5. 50 - 64
6. over 65

Payment
___________

Figure 31. Prompt Locations

The Name, Address, City, and State data fields show the prompts in front of the
fields (PMTLOC=BEFORE), as does the Age field, which shows a prompt for a
selection field. The same prompt width is used on the first five fields so that they
align evenly. The Method of payment and Payment fields demonstrate the prompt
above the field (PMTLOC=ABOVE).

Here’s the markup used to demonstrate the field prompts in Figure 31:

<!doctype dm system>

<varclass name=sampcls type ='char 20'>

<varclass name=statcls type='char 2'>
<varclass name=numcls type='numeric 8 2'>
<varclass name=char1 type='char 1'>

<varlist>
<vardcl name=name varclass=sampcls>
<vardcl name=addr varclass=sampcls>
<vardcl name=city varclass=sampcls>
<vardcl name=stat varclass=statcls>
<vardcl name=pay varclass=numcls>
<vardcl name=age varclass=char1>
<vardcl name=paymeth varclass=char1>
</varlist>

<panel name=pmt01>Application Name

<area>
<dtafld datavar=name entwidth=20 pmtwidth=12>Name
<dtafld datavar=addr entwidth=20 pmtwidth=12>Address
<dtafld datavar=city entwidth=20 pmtwidth=12>City
<dtafld datavar=stat entwidth=2 pmtwidth=12>State
<divider>
<region dir=horiz>
<selfld name=age selwidth=20 pmtloc=before pmtwidth=12>Age
<choice>0 - 12
<choice>13 - 19
<choice>20 - 29

78 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 <choice>30 - 49
<choice>50 - 64
<choice>over 65
</selfld>
<divider gutter=5>
<selfld name=paymeth selwidth=24 pmtwidth=20>Method of payment
<choice>Cash
<choice>Check
<choice>Credit card
</selfld>
</region>
<divider>
<dtafld datavar=pay entwidth=11 pmtloc=above pmtwidth=7>Payment
</area>
</panel>

Figure 32 shows how the prompt width can affect the appearance of the prompt
text.
The prompts in the two data fields are formatted differently. The prompt text of
Application Name

This is a very, very long prompt __________

This is a
very, very
long prompt __________

Here is another long prompt used to show word-wrapping of prompts

__ 1. Choice 1
2. Choice 2

Here is
another long
prompt used to
show
word-wrapping
of prompts
__ 1. Choice 1
2. Choice 2

Figure 32. Prompt Widths

the first data field is not wrapped. It formats on one line, using as much space as
necessary (up to the maximum available formatting width). The second data field
has the same prompt text, with a prompt width that is less than the amount of
space needed, so the prompt text is wrapped to as many lines as are needed.
Similarly, the two selection fields also demonstrate how the prompt text appears
based on the prompt width. The prompt text of data fields and selection fields can
be displayed differently by omitting or specifying different values for the
PMTWIDTH attribute.

The following is the markup used to demonstrate the field prompts in Figure 32:
<!doctype dm system>

<varclass name=sampcls type='char 10'>

<varclass name=char1 type='char 1'>

<varlist>
<vardcl name=samplea varclass=sampcls>
<vardcl name=sampleb varclass=sampcls>
<vardcl name=samplec varclass=char1>

Chapter 5. Application Panel Fields 79

 <vardcl name=sampled varclass=char1>
</varlist>

<panel name=pmt02>Application Name

<area>
<dtacol entwidth=10 selwidth=76>
<dtafld datavar=samplea>This is a very, very long prompt
<divider>
<dtafld datavar=sampleb pmtwidth=12>This is a very, very long prompt
<divider>
<selfld name=samplec>Here is another long prompt used to show
word-wrapping of prompts
<choice>Choice 1
<choice>Choice 2
</selfld>
<divider>
<selfld name=sampled pmtwidth=14>Here is another long prompt used to show
word-wrapping of prompts
<choice>Choice 1
<choice>Choice 2
</selfld>
</dtacol>
</area>
</panel>

Defining Data Fields

Data fields are used to display variable data and to allow the user to enter data. To
define a data field, use the DTAFLD tag. Every data field must have an associated
variable, which is specified on the required DATAVAR attribute. Like all variables
used on the panel, the variable named on the DATAVAR attribute can be declared
using the VARDCL tag.

The purpose of the data field is defined using one of these values on the USAGE
attribute of the DTAFLD tag:
IN Defines an entry (input-only) data field. An entry data field allows the user
to enter data. When an entry field is initially displayed, it is padded with
underscore characters, unless the data is right-justified.
OUT Defines an output-only data field. An output-only data field is used to
display the current value of the variable associated with the data field. The
user cannot tab to or interact with an output-only field.
BOTH Defines an input/output data field. When an input/output field is initially
displayed, the current value of the associated variable is displayed, and the
user can enter data into the field as well. If you do not specify the USAGE
attribute, BOTH is the default.

Data fields support field prompts, which can be placed in front of or above the
data field.

This panel contains examples of all three types of data fields:

80 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 Library Inventory

To add a book to the inventory, complete the fields below, and then press
Enter.

Title . . . . __________________________________________________
Author . . . . ____________________
Publisher . . SPOTH AND CRICK
Number of
pages . . . . _____

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

Today's date is . : 08-10-89

Figure 33. Data Fields

Here’s the markup for Figure 33:

<!doctype dm system>

<varclass name=titlcls type='char 50'>

<varclass name=bookcls type='char 20'>
<varclass name=pagecls type='numeric 5'>
<varclass name=datecls type='char 8'>

<varlist>
<vardcl name=title varclass=titlcls>
<vardcl name=author varclass=bookcls>
<vardcl name=publish varclass=bookcls>
<vardcl name=pages varclass=pagecls>
<vardcl name=curdate varclass=datecls>
</varlist>

<panel name=dfdxmp1a>Library Inventory

<topinst>To add a book to the inventory, complete the fields below,
and then press Enter.
<area>
<dtafld datavar=title usage=in pmtwidth=14>Title
<dtafld datavar=author usage=in entwidth=20 pmtwidth=14>Author
<dtafld datavar=publish entwidth=20 pmtwidth=14>Publisher
<dtafld datavar=pages usage=in entwidth=5 pmtwidth=14>Number of pages
<divider type=solid gutter=3 gap=no>
<dtafld datavar=curdate usage=out entwidth=8 pmtwidth=20>Today's date is
</area>
</panel>

In the previous example, there are three input-only data fields, an input/output
data field, and an output-only data field. The value of the associated variable is not
displayed in an input-only data field, so when the panel is initially displayed, the
Title, Author, and Number of pages fields are blank. The Publisher data field
assumes the default, BOTH, so the current value of the associated variable, publish,
is displayed in the data field when the panel is initially displayed. The output-only
data field is used to display the current date. The user cannot interact with this
data field, since it is used only to display variable data. The user can enter data
into any of the data fields except the output-only field.

Chapter 5. Application Panel Fields 81

 Data Field Width
The width of a data field is determined by the value you specify for the
ENTWIDTH attribute of the DTAFLD tag. You should specify ENTWIDTH for all
data fields. In the previous example, ENTWIDTH is specified for each DTAFLD tag
except for the Title field, whose length is determined as discussed next.

If you do not specify a value for ENTWIDTH, the width of the data field is
determined by the value specified for the TYPE attribute of the VARCLASS tag
associated with the variable named in the DTAFLD DATAVAR attribute. For
example, the Title field in Figure 33 on page 81 has an entry width of 50 as
determined by the variable class titlcls, which has the TYPE value “char 50”. This
variable class is associated with the data field through the variable declaration title,
which is specified as the data field’s DATAVAR attribute value. For more
information on variables and variable classes, see “Chapter 4. Variables and
Variable Classes” on page 57.

The formatted width of the field is 2 positions more than the ENTWIDTH value to
provide for an attribute byte both before and after the field. The maximum width
for an entry field is the remaining available formatting width in the panel.

Note: The conversion utility tracks the remaining width available for use. For data
fields, the width of the entry field has first priority, followed by the prompt
width, and then the description width.

Data Field Descriptions

In addition to a field prompt, you can provide additional descriptive text for a
data field using the DTAFLDD (data field description) tag. You code the DTAFLDD
tag following the definition of the data field being described. The DTAFLDD tag
has no attributes or required end tag. Multiple data field descriptions can be coded
if necessary, and each description begins a new line.

The data field description appears to the right of the entry field, taking up as
much room as is available, unless you have used the DESWIDTH attribute of the
DTAFLD tag to specify a width for the description. If the DESWIDTH attribute is
defined, the data field description is displayed within the description width
specified (or defaulted), and word-wrapped on multiple lines, if necessary.

This panel contains data field descriptions.

82 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 Library Inventory

To add a book to the inventory, complete the fields below, then press
Enter.

Title . . . . . __________________________________________________
Author . . . . ____________________ Last name, First name, M.I.
Publisher . . . SPOTH AND CRICK
Total number of
pages . . . . . ______ (1 - 99999)

Figure 34. Data Field Description

Here’s the markup used to generate the panel in Figure 34:

<!doctype dm system>

<varclass name=titlcls type='char 50'>

<varclass name=bookcls type='char 20'>
<varclass name=pagecls type='numeric 5'>

<varlist>
<vardcl name=title varclass=titlcls>
<vardcl name=author varclass=bookcls>
<vardcl name=publish varclass=bookcls>
<vardcl name=pages varclass=pagecls>
</varlist>

<panel name=dfdxmp4>Library Inventory

<topinst>To add a book to the inventory, complete the fields below,
then press Enter.
<area>
<dtacol pmtwidth=15>
<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>

Data Field Help

| ISPF allows you to provide help on a data field using the HELP attribute on the
| DTAFLD tag. If you specify the name of a help panel or message for a data field,
| ISPF knows which help information to display when the user selects help on the
| data field. If you do not specify help for a data field, the extended help panel
| (specified with the HELP attribute of the enclosing PANEL tag) is displayed.

Chapter 5. Application Panel Fields 83

 The following example shows how to provide help for data fields.

<!doctype dm system>

<varclass name=titlcls type='char 50'>

<varclass name=bookcls type='char 20'>
<varclass name=pagecls type='numeric 5'>

<varlist>
<vardcl name=title varclass=titlcls>
<vardcl name=author varclass=bookcls>
<vardcl name=publish varclass=bookcls>
<vardcl name=pages varclass=pagecls>
</varlist>

<panel name=dfdxmp5>Library Inventory

<topinst>To add a book to the inventory, complete the fields below,
then press Enter.
<area>
<dtacol pmtwidth=15>
<dtafld datavar=title help=hlptitl entwidth=50>Title
<dtafld datavar=author help=hlpauth entwidth=20 deswidth=30>Author
<dtafldd>Last name, First name, M.I.
<dtafld datavar=publish help=hlppubl entwidth=20>Publisher
<dtafld datavar=pages help=hlppage entwidth=5 deswidth=15>
Total number of pages
<dtafldd>(1 - 99999)
</dtacol>
</area>
</panel>

Other Data Field Attributes

There are several other attributes you can specify to tailor a data field to meet the
requirements of your application. See “DTAFLD (Data Field)” on page 299 for more
information. The following list describes each of the remaining DTAFLD attributes
and what you can do with them:
REQUIRED
This attribute allows you to indicate if the data field requires input. When you
assign a value of YES to this attribute, the user must enter data into the field
before ISPF accepts the panel as valid. The default REQUIRED value is NO.
This attribute is only valid for data fields defined as input-only or as
input/output.
MSG
This attribute identifies the message that should be displayed when the user
does not enter any data into an input-required data field. If you do not specify
this attribute, ISPF displays a default message. This attribute is valid only if
REQUIRED=YES.

“Chapter 7. Messages” on page 151 tells you how to define application

messages.
ALIGN
This attribute allows you to align the variable data within the data field. The
default value for ALIGN is start, which aligns the data from the left side of the
data field. You can also center the data within the field with the center value,
or justify the data from the right side of the field with the end value.
AUTOTAB
This attribute provides automatic cursor movement between data fields. If you
specify AUTOTAB=YES for a data field, the cursor automatically moves to the

84 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 next field that is capable of input. If no other field capable of input exists on
the panel, the cursor returns to the beginning of the data field.
DISPLAY
| The value you assign to this attribute, either yes (the default) or no, determines
| if the data appears on the screen when the user enters it. One way to use
| DISPLAY=NO is for defining a password.
VARCLASS
This attribute allows you to override the variable class that is specified on the
variable declaration (VARDCL) for the data field’s data variable (DATAVAR).
See “Chapter 4. Variables and Variable Classes” on page 57 for a description of
variables and variable classes.
FLDSPACE
This attribute specifies the space reserved for the data-entry field. When the
FLDSPACE value is larger than the entry width plus any attributes, blanks are
added following the data-entry field. This provides spacing before DTAFLDD
tag descriptions.
NOENDATTR
This attribute specifies that no ending attribute character will be placed after
the data field. NOENDATTR is valid only when WINDOW=NO is specified or
when data fields are being formatted within a horizontal region.
PAD
This attribute specifies the pad character for initializing the field. You can
define this attribute as a variable name preceded by a “%”.
PADC
This attribute specifies the conditional padding character to be used for
initializing the field. You can define this attribute as a variable name preceded
by a “%”.
OUTLINE
This attribute provides for displaying lines around the field on a DBCS
terminal. You can define this attribute as a variable name preceded by a “%”.
PMTFMT
This attribute controls the generation of prompt leader characters. The default
is to create CUA leader dots.
PSVAR
This attribute provides the name of a variable that is to be set when a DTAFLD
is clicked on for point-and-shoot selection.
PSVAL
This attribute provides the value to be placed in the field specified by the
PSVAR attribute.
PAS
This attribute can be used to provide a variable name that will contain the
value ON to enable point-and-shoot for this data field, or OFF to disable
point-and-shoot. When PSVAR and PSVAL have been specified without the
PAS attribute, the point-and-shoot field will be automatically enabled.
CSRGRP
The CSRGRP attribute, in combination with the PAS attribute, is used to
specify a cursor group for GUI mode operation.
EXPAND
The EXPAND attribute, used in combination with EXPAND=xy on the PANEL

Chapter 5. Application Panel Fields 85

 definition, causes the expand characters to be added to the DTAFLD definition,
effectively allowing ENTWIDTH to expand.
FLDWIDTH
The FLDWIDTH attribute, used in combination with WINDOW=NO on the
PANEL definition, provides the width of a data field that spans multiple lines.
ATTRCHANGE
The ATTRCHANGE attribute specifies that, if required, an additional )ATTR
section entry (which can apply to multiple fields) be created instead of a
unique “.ATTR” override entry for the current field.
INIT
The INIT attribute provides an initial value for the data field.
DBALIGN
The DBALIGN attribute is used only for DBCS language conversion when
PMTLOC=ABOVE to align the prompt text with the data field.
DEPTH
This attribute defines the depth reserved for the field. When the panel is
displayed in GUI mode, a field specified as point-and-shoot results in a push
button displayed with the specified DEPTH.
IMAPNAME
This attribute specifies the name of an image to be placed on the
point-and-shoot push button when it is displayed in GUI mode.
IMAPNAMEP
This attribute specifies the name of an image to be placed on the
point-and-shoot push button after it has been pushed when it is displayed in
GUI mode.
PLACE
This attribute specifies the position of the image relative to the text within the
point-and-shoot push button.
PMTSKIP
This attribute, used during horizontal field formatting of input fields, specifies
that the cursor should move past the prompt text to the input field.
DESSKIP
This attribute, used during horizontal field formatting of input fields, specifies
that the cursor should move past the description text to the next input field.
FLDTYPE
This attribute specifies whether CUA or traditional ISPF attribute definitions
are used.
COLOR
When FLDTYPE=ISPF, this attribute specifies the color of the field.
INTENS
When FLDTYPE=ISPF, this attribute specifies the intensity of the field.
HILITE
When FLDTYPE=ISPF, this attribute specifies the highlighting for the field.
| ATTRCHAR
| This attribute provides a user selected panel attribute for the data field.
| CAPS
| This attribute specifies whether the field is displayed in uppercase characters.

86 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

| NOJUMP
| This attribute specifies that the JUMP function is disabled for the data field.

Defining Selection Fields

Selection fields allow the user to select from a group of choices on an application
panel. You can specify if only one choice can be selected from a selection field, or if
multiple choices are allowed.

In either case, you use the same DTL tags to define a selection field. The SELFLD
(selection field) tag and its required end tag define a selection field. The CHOICE
(selection choice) tag defines a choice within a selection field. You code the
CHOICE tags between the SELFLD start and end tags, like this:
<selfld>
<choice>
<choice>
<choice>
</selfld>

Each CHOICE tag defines a choice within the selection field.

Like data fields, selection fields support field prompts, which can be placed in
front of or above the selection field. Field prompts are described in “Field
Prompts” on page 77.

To define the selection field type use the TYPE attribute of the SELFLD tag. The
values you can assign to TYPE are:
SINGLE Specifies the selection field as being a single-choice field. Choices
in a single-choice selection field appear in a list with an entry field
preceding the first choice in the list. The conversion utility prefixes
the text of each choice with a number, so the selection field choices
are numbered sequentially. Users indicate choice selection by
typing the number of the choice they want in the entry field.
MULTI Specifies the selection field as being a multiple-choice field.
Choices in a multiple-choice selection field appear in a list with a
single-character entry field preceding each choice. Users indicate
choice selection by typing any nonblank character in the entry
fields.
MENU Specifies the selection field as being a menu-choice field. Choices in
a menu-choice selection field are similar to those in a single-choice
selection field. TYPE=MENU is valid only when the MENU
keyword has been specified on the PANEL tag.
MODEL Specifies the selection field as being a model-choice field. Choices
in a model-choice selection field are similar to those in a
menu-choice selection field. TYPE=MODEL is valid only when the
MENU keyword has been specified on the PANEL tag.
| TUTOR Specifies the selection field as being a tutor-choice field. Choices in
| a tutor-choice selection field are similar to those in a menu-choice
| selection field. TYPE=TUTOR is valid only when the MENU
| keyword has been specified on the PANEL tag.

The CHOICE tag has two attributes associated with it that are important when
defining a selection field: CHECKVAR and MATCH. The CHECKVAR and

Chapter 5. Application Panel Fields 87

 MATCH attributes are used to preselect choices in the selection field. The
CHECKVAR attribute can also communicate to the application which selections
were made by the user.

The value specified on the CHECKVAR attribute is the name of a dialog variable
that is defined by the application. Both the application and ISPF can set the check
variable. The following sections describe how the CHECKVAR and MATCH
attributes are used for each type of selection field.

Single-Choice Fields
Use a single-choice selection field when you have a fixed set of choices that are
mutually exclusive. That is, the user can select only one of the choices by typing
the choice number in the entry field. You can specify the preselected choice in a
single-choice selection field so that one item is already selected when the panel is
displayed. The user can either leave the preselected choice or enter a different
choice number.

To preselect choices in a single-choice selection field, and to find out which choice
was selected by the user, you should specify the CHECKVAR and MATCH
attributes for each CHOICE tag. For a single-choice field, all of the enclosed
choices should refer to the same check variable, but they should have unique
MATCH values. The following markup shows how this is coded.
<!doctype dm system>

<varclass name=daycls type ='char 1'>

<varlist>
<vardcl name=day varclass=daycls>
<vardcl name=choice varclass=daycls>
</varlist>

<panel name=singsel>Schedule Appointments

<topinst>Choose the most convenient day for your appointment,
then press Enter.
<area>
<selfld name=choice selwidth=30 pmtwidth=9>Weekdays:
<choice checkvar=day match=M>Monday
<choice checkvar=day match=T>Tuesday
<choice checkvar=day match=W>Wednesday
<choice checkvar=day match=H>Thursday
<choice checkvar=day match=F>Friday
</selfld>
</area>
</panel>

To preselect a certain choice, set the check variable, day, to the match value for that
choice. Assume that the check variable, day, is set to M before the panel is
displayed. When the panel is displayed, the choice, Monday, is selected as shown
in Figure 35 on page 89.

88 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 Schedule Appointments

Choose the most convenient day for your appointment, then press Enter.

Weekdays:
1 1. Monday
2. Tuesday
3. Wednesday
4. Thursday
5. Friday

Figure 35. Single-Choice Selection Field

If the user decides that another day is more convenient, another choice might be
selected. This causes the check variable to be updated with the match value of the
newly selected choice. For example, if the user selects Friday (by typing “5” in the
entry field), the check variable, day, will contain “F” when control is returned to
the application.

Note: The TYPE attribute does not have to be specified on a single-choice selection
field because TYPE=SINGLE is the default. However, you must specify the
NAME attribute for single-choice selection fields.

Multiple-Choice Fields
Use a multiple-choice selection field when you have several choices for the user,
but they are not mutually exclusive. Each choice acts independently as a toggle,
and selecting one of the choices does not affect any of the other choices in the
selection field.

To preselect choices in a multiple-choice selection field, and to find out which

choices were selected by the user, specify the CHECKVAR, MATCH, and
NOMATCH attributes for each CHOICE tag.

On a multiple-choice selection field, define a unique check variable for each

enclosed CHOICE. You can let the MATCH value default to 1, or specify the
MATCH attribute with a value of your choice. Also, you can let the NOMATCH
value default to 0, or specify the NOMATCH attribute with a value of your choice.
Here’s how a multiple-choice selection field is coded:

<!doctype dm system>

<varclass name=sampcls type ='char 1'>

<varlist>
<vardcl name=dry varclass=sampcls>
<vardcl name=cut varclass=sampcls>
<vardcl name=per varclass=sampcls>
<vardcl name=fac varclass=sampcls>
<vardcl name=man varclass=sampcls>

Chapter 5. Application Panel Fields 89

 <vardcl name=ped varclass=sampcls>
<vardcl name=ch1 varclass=sampcls>
<vardcl name=ch2 varclass=sampcls>
<vardcl name=ch3 varclass=sampcls>
<vardcl name=ch4 varclass=sampcls>
<vardcl name=ch5 varclass=sampcls>
<vardcl name=ch6 varclass=sampcls>
</varlist>

<panel name=multsel>Schedule Appointments

<area>
<dtacol pmtwidth=45 selwidth=76>
<selfld type=multi>Choose the services needed, then press Enter.
<choice name=ch1 checkvar=dry>Dry haircut
<choice name=ch2 checkvar=cut>Shampoo, haircut, and style
<choice name=ch3 checkvar=per>Permanent or body wave
<choice name=ch4 checkvar=fac>Facial
<choice name=ch5 checkvar=man>Manicure
<choice name=ch6 checkvar=ped>Pedicure
</selfld>
</dtacol>
</area>
</panel>

You specify preselected choices for a multiple-choice selection field just as you
would for a single-choice selection field. Set the check variable for the preselected
choices to the match values (or the default value of 1) for those choices. When a
choice is preselected, a slash (/) is displayed in the entry field preceding the
choice.

When the user types a value in an entry field in a multiple-choice selection field,
ISPF toggles the choice as follows:
v If the choice is already selected and the user enters a blank in the entry field,
ISPF deselects the choice and sets the check variable to the NOMATCH value for
the choice, or to 0 if the NOMATCH attribute is not specified.
v If the choice is not selected and the user types a nonblank character in the entry
field, ISPF selects the choice and sets the check variable to the MATCH value for
the choice, or to 1 if the MATCH attribute is not specified. If the choice is not
selected, ISPF sets the check variable to the NOMATCH value for the choice, or
to 0 if the NOMATCH attribute is not specified.

In the preceding markup, the MATCH attribute was not specified, so the check
variables toggle between 0 and 1 (the default MATCH and NOMATCH values) as
the user selects and deselects items.

Because ISPF is setting the check variable, you should not use the SETVAR or the
TOGVAR attributes of the ACTION tag to refer to the check variable.

Figure 36 on page 91 shows how the multiple-choice selection field in the preceding
markup appears with the choices Facial and Pedicure preselected.

90 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 Schedule Appointments

Choose the services needed, then press Enter.

_ Dry haircut
_ Shampoo, haircut, and style
_ Permanent or body wave
/ Facial
_ Manicure
/ Pedicure

Figure 36. Multiple-Choice Selection Field

Menu-Choice Fields
Use a menu-choice selection field to create an ISPF option menu. Menu-choice
fields are similar to single-choice fields. That is, the user can select only one of the
choices presented. The entry field for this type of selection field is the command
line, which is formatted with the word Option instead of Command. As with
single-choice selections, you can specify a preselected choice so that one item is
already selected when the panel is displayed.

The CHOICE tag is followed by an ACTION tag which specifies the type of
selection (PANEL, PGM, CMD, or EXIT), and other attributes required by the ISPF
SELECT service.

When creating an option menu, the MENU keyword is required on the PANEL tag.
The optional PRIME keyword causes the creation of a primary option menu. The
SELFLD tag must specify TYPE=MENU. Depending on the panel being created,
the SELFLD tag attributes ENTWIDTH, FCHOICE, and TRAIL, and the CHOICE
tag attribute SELCHAR might be required. See “Chapter 13. Tag Reference” on
page 201 for more information on the PANEL, SELFLD, CHOICE, and ACTION
tags.

The following markup creates a sample option menu:

<!doctype dm system ()>
<!-- MENU selection panel example -->
<panel name=menusel1 menu>Sample Option Menu
<topinst>Enter a selection choice

<region indent=4>
<selfld type=menu entwidth=1 selwidth=40>
<choice checkvar=xtest1 match=a>Select Command
<action run=tstch1 type=cmd parm='1234'
newappl=aaaa passlib newpool suspend
lang=crex nocheck mode=fscr>
<choice checkvar=xtest1 match=b>Select Panel
<action run=tstch2 type=panel

Chapter 5. Application Panel Fields 91

 addpop newappl=aaaa passlib newpool suspend>
<choice checkvar=xtest1 match=c>Select Program
<action run=tstch3 type=pgm parm=abcd
newappl=aaaa passlib newpool suspend
nocheck mode=fscr>
<choice checkvar=xtest1 match=x>Exit
<action run=exit type=exit>
</selfld>
</region>

<cmdarea>
</panel>

The resulting panel is:

Sample Option Menu

Enter a selection choice

1 Select Command
2 Select Panel
3 Select Program
4 Exit

Option ===> _____________________________________________________________

Figure 37. Sample Option Menu

Model-Choice Fields
Use a model-choice selection field to create an ISPF edit model selection menu.
Model-choice fields are similar to single-choice or menu-choice fields. That is, the
user can select only one of the choices presented. The entry field for this type of
selection field is the command line, which is formatted with the word Option
instead of Command. As with single-choice or menu-choice selections, you can
specify a preselected choice so that one item is already selected when the panel is
displayed.

The CHOICE tag is followed by an ACTION tag which specifies the type of
selection (PANEL, PGM, CMD, or EXIT), and other attributes required by the ISPF
SELECT service.

When creating an edit model menu, the MENU keyword is required on the PANEL
tag. The SELFLD tag must specify TYPE=MODEL. Depending on the panel being
created, the SELFLD tag attributes ENTWIDTH, FCHOICE, and TRAIL, and the
CHOICE tag attributes SELCHAR, HIDEX, and TRUNC might be required. See
“Chapter 13. Tag Reference” on page 201 for more information on the PANEL,
SELFLD, CHOICE, and ACTION tags.

92 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

| Tutor-Choice Fields
| Use a tutor-choice selection field to create an ISPF tutorial selection menu.
| Tutor-choice fields are similar to menu-choice fields. That is, the user can select
| only one of the choices presented. The entry field for this type of selection field is
| the command line, which is formatted with the word Option instead of Command.
| As with menu-choice selections, you can specify a preselected choice so that one
| item is already selected when the panel is displayed.

| The CHOICE tag is followed by an ACTION tag that must specify the type of
| selection as PANEL, and other attributes required by the ISPF SELECT service.

| When creating a tutorial menu, the MENU keyword is required on the PANEL tag.
| The SELFLD tag must specify TYPE=TUTOR. Depending on the panel being
| created, the SELFLD tag attributes ENTWIDTH and FCHOICE, and the CHOICE
| tag attribute SELCHAR might be required. See “Chapter 13. Tag Reference” on
| page 201 for more information on the PANEL, SELFLD, CHOICE, and ACTION
| tags.

Selection Field Help

| ISPF enables you to provide help on selection fields. For single-choice selection
| fields, you specify the name of a help panel or message for the selection field with
| the HELP attribute of the SELFLD tag. For multiple-choice selection fields, you
| specify the name of a help panel or message for each of the choices in the selection
| field with the HELP attribute of the CHOICE tags. For menu-choice, model-choice,
| or tutor-choice fields, the selection field is the command line. The name of the help
| panel or message must be provided on the CMDAREA tag. If you specify help for
| a single-choice selection field, a menu-choice selection field, or for choices in a
| multiple-choice selection field, ISPF displays that help information when the user
| requests help and the cursor is on that panel element. If there is no help defined,
| the extended help panel is displayed.

The following example shows how to code a help panel for a single-choice
selection field.
<selfld name=choice help=dayhelp>Weekdays:
<choice checkvar=day match=M>Monday
<choice checkvar=day match=T>Tuesday
<choice checkvar=day match=W>Wednesday
<choice checkvar=day match=H>Thursday
<choice checkvar=day match=F>Friday
</selfld>

This example shows how to code help panels for choices in a multiple-choice
selection field.
<selfld type=multi>Choose the services needed:
<choice name=ch1 help=dryhlp>Dry haircut
<choice name=ch2 help=cuthlp>Shampoo, haircut, and style
<choice name=ch3 help=permhlp>Permanent or body wave
<choice name=ch4 help=facehlp>Facial
<choice name=ch5 help=manihlp>Manicure
<choice name=ch6 help=pedihlp>Pedicure
</selfld>

Selection Width
The SELWIDTH attribute of the SELFLD tag should be used to define the amount
of space taken up by the choice-description-text of each CHOICE tag. This attribute

Chapter 5. Application Panel Fields 93

 is used to control the formatting of panels defined with horizontal regions. If you
do not specify a SELWIDTH value, the conversion utility reserves the remaining
available formatting width for the text.

| When specifying an explicit SELWIDTH value, you must take into consideration
| the components of the selection field, as well as the choice-description-text. The
| conversion utility reserves a number of positions on the lines that selection field
| choices appear on for the entry fields, 3270 attributes, and, in the case of
| single-choice, menu-choice, model-choice, and tutor-choice selection fields, the
| choice prefixes. See page 436 for a discussion of the amount of space reserved for
| each choice type.

These reserved positions must be added to the length of the choice-description-text

in the SELWIDTH value you specify. For example, the following markup contains
two selection fields, one single-choice and one multiple-choice, within a horizontal
region. To format the selection fields properly, ensure that the SELWIDTH values
you specify are adequate for the reserved positions and the choice-description-text.
The largest choice-description-text in the first selection field is 9 characters, which,
when combined with the 10 reserved positions in the field, means you must
specify a SELWIDTH value of at least 19. The largest choice-description-text in the
second selection field is 27 characters, which, when combined with the 5 reserved
positions in the field, means you must specify a SELWIDTH value of at least 32.

| See page 437 for more information aboout SELWIDTH.

<!doctype dm system>
<varclass name=char1 type='char 1'>
<varclass name=char2 type='char 2'>

<varlist>
<vardcl name=person varclass=char2>
<vardcl name=ch1 varclass=char1>
<vardcl name=ch2 varclass=char1>
<vardcl name=ch3 varclass=char1>
<vardcl name=ch4 varclass=char1>
<vardcl name=ch5 varclass=char1>
<vardcl name=ch6 varclass=char1>
</varlist>

<panel name=servsel>Service Selections

<topinst>Select the stylist and services you want, then press Enter.
<area>
<region dir=horiz>
<selfld name=person selwidth=19 pmtwidth=15>Stylist
<choice checkvar=stylst match=1>Cecilia
<choice checkvar=stylst match=2>Dana
<choice checkvar=stylst match=3>Laurel
<choice checkvar=stylst match=4>Pierce
<choice checkvar=stylst match=5>Stephenie
</selfld>
<divider>
<selfld type=multi selwidth=32 pmtwidth=15>Services
<choice name=ch1 checkvar=dry>Dry haircut
<choice name=ch2 checkvar=cut>Shampoo, haircut, and style
<choice name=ch3 checkvar=per>Permanent or body wave
<choice name=ch4 checkvar=fac>Facial
<choice name=ch5 checkvar=man>Manicure
<choice name=ch6 checkvar=ped>Pedicure
</selfld>
</region>
</area>
</panel>

94 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 Here’s the formatted result:

Service Selections

Select the stylist and services you want, then press Enter.

Stylist Services
__ 1. Cecilia _ Dry haircut
2. Dana _ Shampoo, haircut, and style
3. Laurel _ Permanent or body wave
4. Pierce _ Facial
5. Stephenie _ Manicure
_ Pedicure

Figure 38. Selection Field SELWIDTH Attribute

Other Selection Field Attributes

There are several other attributes you can specify to tailor a selection field to meet
the requirements of your application. See “SELFLD (Selection Field)” on page 433
for more information. The following list describes each of the remaining SELFLD
attributes and what you can do with them:
ENTWIDTH
| This attribute controls the entry width for single-choice, menu-choice,
| model-choice, and tutor-choice selections.
REQUIRED
| This attribute allows you to indicate if the single-choice selection field requires
| input. When you assign a value of YES to this attribute, the user must enter
| data into the field before ISPF accepts the panel as valid. The default
| REQUIRED value is NO.
MSG
This attribute identifies the message that should be displayed when the user
does not enter any data into the selection field. If you do not specify this
attribute, ISPF displays a default message. This attribute is valid only if
REQUIRED=YES.

“Chapter 7. Messages” on page 151 tells you how to define application

messages.
FCHOICE
| This attribute controls the first choice number for single-choice, menu-choice,
| model-choice, and tutor-choice selections. The value can be either 0 or 1.
AUTOTAB
This attribute provides automatic cursor movement between fields. If you
specify AUTOTAB=YES for a selection field, the cursor automatically moves to
the next field that is capable of input. If no other field capable of input exists
on the panel, the cursor returns to the selection field.

Chapter 5. Application Panel Fields 95

 DEPTH
This attribute specifies that the selection list is to be formatted as a scrollable
area. A list formatted into multiple columns (see CHOICECOLS below) is
formatted as multiple scrollable areas.
EXTEND
This attribute is valid only when DEPTH has been specified and specifies that
the scrollable area is to be expanded at run-time to the size of the logical
screen.
TRAIL
This attribute is used with menu-choice selections to specify the name of one
or more variables that applications use to obtain TRAIL information created by
option menu selection processing.
CHOICECOLS
This attribute is used to specify the number of columns to create for the
selection list. When multiple columns are requested, the number of choices
placed in each column is obtained from the CHOICEDEPTH attribute.
CHOICEDEPTH
This attribute specifies the number of choices to be formatted into each column
of choices. If more choice entries are specified than can be formatted in the
available number of columns specified by the CHOICECOLS attribute, the
remaining choice entries are placed in the rightmost (or only) available column
for the current SELFLD tag.
CWIDTHS
This attribute specifies the number of bytes to be allocated for each column of
CHOICE entries. The ‘w1 w2...wn’ notation provides the number of bytes for
each column. You may use an asterisk or a number combined with an asterisk
to specify a proportional allocation of column space.
PAD
This attribute specifies the pad character for initializing the field. You can
define this attribute as a variable name preceded by a “%”.
PADC
This attribute specifies the conditional padding character to be used for
initializing the field. You can define this attribute as a variable name preceded
by a “%”.
OUTLINE
This attribute provides for displaying lines around the field on a DBCS
terminal. You can define this attribute as a variable name preceded by a “%”.
SELMSG
This attribute specifies the message that is displayed when an invalid
single-choice entry is selected.
SELMSGU
This attribute specifies the message that is displayed when an unavailable
single-choice entry is selected.
INIT
This attribute controls the single-choice and multiple-choice selection field
variables initialization in the panel )INIT section.
VERIFY
| This attribute controls the single-choice verification and menu-choice,
| model-choice, or tutor-choice selection logic generation in the panel )PROC
| section.

96 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

REFRESH
This attribute controls the creation of the REFRESH statement in the )REINIT
section for multi-choice selection variables.
SELFMT
This attribute controls the placement of the choice selection character(s) within
the width specified by ENTWIDTH.
CHKBOX
This attribute controls the display of multiple-choice fields as check boxes
when operating in GUI mode.
ZGUI
This attribute controls the creation of the VGET (ZGUI) statement created as
part of the )INIT section for multiple-choice selection definitions using the
“&multipmt” built-in ENTITY.
CSRGRP
This attribute, in combination with CHKBOX=YES, provides a cursor group
identification for multi-choice selections.
TSIZE
This attribute provides the number of bytes to indent multiple lines of
CHOICE text.
LISTTYPE
This attribute controls the display of single-choice selection lists when
operating in GUI mode.
LISTREF
This attribute provides the name of the )LIST section for list boxes, drop-down
lists, and combination boxes.
LISTDEPTH
This attribute specifies the display depth for list boxes, drop-down lists, and
combination boxes.
DBALIGN
This attribute, used for DBCS fields when PMTLOC=ABOVE, specifies
alignment of the prompt text with the selection input field.
NOSEL
This attribute provides a value to be placed in the CHECKVAR variable
(specified by the CHOICE tag), when no selection is made from a single-choice
selection list.
SELDEFAULT
This attribute specifies a default choice selection for a single-choice selection
list.
PMTSKIP
This attribute, used during horizontal field formatting, specifies that the cursor
should move past the prompt text to the input field.
FLDTYPE
This attribute specifies whether CUA or traditional ISPF attribute definitions
are used.
COLOR
When FLDTYPE=ISPF, this attribute specifies the color of the the field.
INTENS
When FLDTYPE=ISPF, this attribute specifies the intensity of the the field.

Chapter 5. Application Panel Fields 97

 HILITE
When FLDTYPE=ISPF, this attribute specifies the highlighting of the the field.

Data Columns
The DTACOL (data column) tag can be used to define values for data fields and
selection fields that are coded within the data column. If you have a group of data
fields and selection fields on the same application panel, the DTACOL tag is a
convenient short-cut for ensuring alignment of the fields.

The DTACOL tag has the following attributes:

PMTWIDTH Applies to data fields and selection fields
ENTWIDTH Applies to data fields only
DESWIDTH Applies to data fields only
SELWIDTH Applies to selection fields only
FLDSPACE Applies to data fields only
PAD Applies to data fields only
PADC Applies to data fields only
OUTLINE Applies to data fields only
PMTFMT Applies to data fields only
AUTOTAB Applies to data fields only
ATTRCHANGE
Applies to data fields only
PMTLOC Applies to data fields only
DBALIGN Applies to data fields only
| VARCLASS Applies to data fields only
| REQUIRED Applies to data fields only
| CAPS Applies to data fields only

| These attributes serve the same purposes in DTACOL definitions as they do in

| CHOFLD, DTAFLD, and SELFLD definitions. The only difference is that when you
| use them with a DTACOL tag, they define those values for all of the data fields
| and selection fields coded between the DTACOL start and end tags.

The following markup uses a data column to define a prompt width, entry width,
and description width for the data fields and the selection field coded within the
data column. Because we want to limit the entry width of the State and Zip code
fields, we defined ENTWIDTH values in the DTAFLD definitions for these fields
that override the DTACOL ENTWIDTH value.

<!doctype dm system>

<varclass name=sampcls type ='char 30'>

<varclass name=statcls type ='char 2'>
<varclass name=zipcls type ='char 5'>
<varclass name=char1cls type ='char 1'>

<varlist>
<vardcl name=name varclass=sampcls>

98 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference

 <vardcl name=addr varclass=sampcls>
<vardcl name=city varclass=sampcls>
<vardcl name=stat varclass=statcls>
<vardcl name=day varclass=char1cls>
<vardcl name=zipc varclass=zipcls>
</varlist>

<panel name=dcolxmp>Schedule Appointments

<topinst>Enter your name and address and
choose the most convenient day for your appointment.
<area>
<dtacol pmtwidth=12 entwidth=30 deswidth=29 selwidth=30>
<dtafld datavar=name>Name
<dtafldd>Last, First, M.I.
<dtafld datavar=addr>Address
<dtafldd>If it applies, include apartment number
<dtafld datavar=city>City
<dtafld datavar=stat entwidth=2>State
<dtafldd>Use 2-character abbreviation
<dtafld datavar=zipc entwidth=5>Zip code
<divider type=solid gutter=3>
<selfld name=day pmtloc=before>Weekdays
<choice>Monday
<choice>Tuesday
<choice>Wednesday
<choice>Thursday
<choice>Friday
</selfld>
</dtacol>
</area>
</panel>

Here’s how the panel formats:

Schedule Appointments

Enter your name and address and choose the most convenient day for your
appointment.

Name . . . . ______________________________ Last, First, M.I.

Address . . ______________________________ If it applies, include
apartment number
City . . . . ______________________________
State . . . __ Use 2-character abbreviation
Zip code . . _____

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

Weekdays . . __ 1. Monday
2. Tuesday
3. Wednesday
4. Thursday
5. Friday

Figure 39. Data Column

Defining List Fields

A list field is used to display ISPF table data in column format, and to allow the
user to enter data in the column rows. The list field supports vertical scrolling if all
of the data in the list field is not visible.

Chapter 5. Application Panel Fields 99

 If you define a list field in a panel, the ISPF application program must use the
TBDISPL service to display the panel.

The tags you use to define a list field are:

LSTFLD To define the list field. A matching end tag is required.
LSTGRP To define column group headings. A matching end tag is required.
LSTCOL To define a column within a list field. You code a LSTCOL tag for
each column of data in the list field.
LSTVAR To define a variable model line.

A list field can contain one or more columns of data, where each column can be
input-only, output-only, or input/output, as defined by the USAGE attribute on the
LSTCOL tag. These are the values you can specify on the USAGE attribute:
IN Defines an input-only list column. An input-only column is
underscore-filled when it is initially displayed, unless the data is
right-justified, and the user can enter data into any of the rows in the input
column.
OUT Defines an output-only list column. When the panel is initially displayed,
output-only columns display the value of the ISPF table variable associated
with the list column. The user cannot interact with an output-only list
column.
BOTH Defines an input/output list column. Input/output list columns display
the value of the ISPF table variable associated with the list column when
the panel is initially displayed, as well as allowing the user to enter data
into any of the rows in the column. BOTH is the default value for the
USAGE attribute.

The data that is associated with each list column is specified on the DATAVAR
attribute of the LSTCOL tag. Like all variables used on the panel, the data variable
should be declared using the VARDCL tag.

The conversion utility builds a model section into the converted application panel.
The model section begins with a )MODEL header statement, which includes the
variables named by the DATAVAR attributes of each of the LSTCOL tags defined
within the LSTFLD.

Application panels defined using the LSTFLD tag must be displayed using the
ISPF TBDISPL service. You can specify the optional ROWS=SCAN attribute on the
LSTFLD tag to indicate that only those rows meeting the criteria established by a
previous TBSARG service are to be displayed.

You can define a column heading for any of the list columns in the list field by
specifying the column heading text as the tag text on the LSTCOL tag. You can
specify the optional DIV attribute on the LSTFLD tag to create a divider line
between the display of table rows. The column headings do not scroll when the list
field is scrolled.

| A scroll amount field can be placed at the right end of the command line by
| specifying the SCROLLVAR attribute on the LSTFLD tag. Field level help for the
| SCROLLVAR field is specified using the SCRVHELP attribute. The scroll amount
| field is displayed in uppercase characters when the SCRCAPS=ON attribute is
| specified.

100 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 This panel shows a list field with six columns. The first column is output-only, and
the remaining columns are input/output.

Scheduling Account Visits ROW 1 to 9 of 9

Enter the account name in the appropriate time slot.

Monday Tuesday Wednesday Thursday Friday

08:00 - 08:59 _________ _________ _________ _________ _________
09:00 - 09:59 _________ _________ _________ _________ _________
10:00 - 10:59 _________ Simmons _________ _________ _________
11:00 - 11:59 _________ _________ _________ _________ _________
12:00 - 12:59 _________ _________ Douglass Campbell _________
01:00 - 01:59 _________ _________ _________ _________ _________
02:00 - 02:59 _________ _________ _________ _________ _________
03:00 - 03:59 _________ _________ _________ _________ _________
04:00 - 04:59 _________ _________ _________ _________ _________
***************************** Bottom of data *****************************

Command ===> ___________________________________________ Scroll ===> ____

F1=Help F2=Split F3=Exit F9=Swap F12=Cancel

Figure 40. List Field

Here’s the markup we used to create the panel:

<!doctype dm system>

<varclass name=timecls type='char 13'>

<varclass name=vc1 type ='char 9'>

<varlist>
<vardcl name=timecol varclass=timecls>
<vardcl name=moncol varclass=vc1>
<vardcl name=tuecol varclass=vc1>
<vardcl name=wedcol varclass=vc1>
<vardcl name=thrcol varclass=vc1>
<vardcl name=fricol varclass=vc1>
</varlist>

<panel name=lstfld2>Scheduling Account Visits

<topinst>Enter the account name in the appropriate time slot.
<area>
<lstfld scrollvar=scrlamt scrvhelp=scrhelp>
<lstcol datavar=timecol usage=out colwidth=13>
<lstcol datavar=moncol colwidth=9>Monday
<lstcol datavar=tuecol colwidth=9>Tuesday
<lstcol datavar=wedcol colwidth=9>Wednesday
<lstcol datavar=thrcol colwidth=9>Thursday
<lstcol datavar=fricol colwidth=9>Friday
</LSTFLD>
</area>
<cmdarea>
</panel>

List Group Headings

You can define additional headings for the columns in a list field using the
LSTGRP (list group) tag and its matching end tag. You can define a list group for a
single list column or for multiple list columns. You nest the list columns you want
to provide additional heading text for within the LSTGRP definition.

Chapter 5. Application Panel Fields 101

 At least one field from the first line of the model set must be included within a
LSTGRP definition.

The HEADLINE attribute of the LSTGRP tag allows you to place dashes in the list
group heading. This is handy for list groups that span across several list columns.
Specify HEADLINE=YES to produce a dashed list group heading.

The ALIGN attribute of the LSTGRP tag allows you to control the format position
of the list group heading. The default value is CENTER. The heading can be left-
or right-justified by specifying the values START or END, respectively.

For example, we added a LSTGRP definition to the list field shown earlier.

Scheduling Account Visits ROW 1 to 9 of 9

Enter the account name in the appropriate time slot.

--------------------- Appointments ---------------------

Monday Tuesday Wednesday Thursday Friday
08:00 - 08:59 _________ _________ _________ _________ _________
09:00 - 09:59 _________ _________ _________ _________ _________
10:00 - 10:59 _________ Simmons _________ _________ _________
11:00 - 11:59 _________ _________ _________ _________ _________
12:00 - 12:59 _________ _________ Douglass Campbell _________
01:00 - 01:59 _________ _________ _________ _________ _________
02:00 - 02:59 _________ _________ _________ _________ _________
03:00 - 03:59 _________ _________ _________ _________ _________
04:00 - 04:59 _________ _________ _________ _________ _________
***************************** Bottom of data *****************************

Command ===> ___________________________________________ Scroll ===> ____

F1=Help F2=Split F3=Exit F9=Swap F12=Cancel

Figure 41. List Group

The text of the list group, Appointments is centered within the dashes. Here’s how
we coded the list group:

<!doctype dm system>

<varclass name=timecls type='char 13'>

<varclass name=vc1 type ='char 9'>

<varlist>
<vardcl name=timecol varclass=timecls>
<vardcl name=moncol varclass=vc1>
<vardcl name=tuecol varclass=vc1>
<vardcl name=wedcol varclass=vc1>
<vardcl name=thrcol varclass=vc1>
<vardcl name=fricol varclass=vc1>
</varlist>

<panel name=lstgrp2>Scheduling Account Visits

<topinst>Enter the account name in the appropriate time slot.
<area>
<lstfld scrollvar=scrlamt scrvhelp=scrhelp>
<lstcol datavar=timecol usage=out colwidth=13>
<lstgrp headline=yes>Appointments
<lstcol datavar=moncol colwidth=9>Monday
<lstcol datavar=tuecol colwidth=9>Tuesday

102 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 <lstcol datavar=wedcol colwidth=9>Wednesday
<lstcol datavar=thrcol colwidth=9>Thursday
<lstcol datavar=fricol colwidth=9>Friday
</lstgrp>
</lstfld>
</area>
<cmdarea>
</panel>

List Column Width

You can use the COLWIDTH attribute of the LSTCOL tag to determine the data
width to be used by the column. If you do not specify this attribute, the data
width and column formatting width are determined by the actual length of the
column-heading If the width of the column-heading text is greater than the
COLWIDTH, it is used as the column formatting width.

The minimum width value is 1 and the maximum is the remaining available panel
(or region) width. If the column-heading and the COLWIDTH attribute are omitted,
the data width and column formatting width are determined by the TYPE value of
the associated VARCLASS. If a VARCLASS TYPE value is not available, the size of
the column variable name (specified by the DATAVAR attribute) determines the
width.

You should code the COLWIDTH attribute with a value equal to the length of the
table data variable.

Other List Column Attributes

There are several other attributes that can be used in the LSTCOL tag. Many of
these attributes are the same as attributes on the DTAFLD tag. The following list
describes these LSTCOL attributes and how they are used:
ALIGN
This attribute aligns the variable data within the list column. The default value
for ALIGN is start, which aligns the data from the left side of the column. You
can also center the data within the column with the center value, or justify the
data to the right side of the column with the end value. The attribute value end
is useful for right-justifying numbers within an output-only column, because
numbers are typically right-aligned.
ATTRCHANGE
This attribute specifies that, if required, an additional )ATTR section entry
(which can apply to multiple fields) be created instead of a unique “.ATTR”
override entry for the current field.
AUTOTAB
This attribute specifies automatic tabbing. If you assign a value of YES to this
attribute, the cursor automatically moves to the next field that is capable of
user input when the user enters the last character in the current list column.
The default value for AUTOTAB is NO. This attribute is only valid for list
columns defined as input-only or as input/output.
CLEAR
This attribute specifies that the column is a table extension variable, which
should be cleared before the row is displayed. Column names with the CLEAR
attribute are identified by the CLEAR keyword on the )MODEL statement.
COLOR
When COLTYPE=ISPF, this attribute specifies the color for the column.

Chapter 5. Application Panel Fields 103

 COLSPACE
| The COLSPACE attribute specifies the total number of bytes for the column
| width, including the leading and trailing attributes, and the trailing blank for
| input fields. The use of the COLSPACE attribute causes column heading text
| longer than the COLSPACE value to be flowed into multiple lines.
COLTYPE
The COLTYPE attribute specifies the attribute type to be used for the column.
CSRGRP
This attribute, in combination with the PAS attribute, specifies a cursor group
for GUI mode operation.
FORMAT
This attribute specifies how the data column and its column heading are
formatted. If you do not specify this attribute, or if you specify the attribute
value START, then the column formats as in ISPF Version 3.1 and ISPF Version
3.2.
HELP
This attribute specifies the help panel name to display when the user requests
help on the list column.
HILITE
When COLTYPE=ISPF, this attribute specifies the highlighting for the column.
INTENS
When COLTYPE=ISPF, this attribute specifies the intensity for the column.
LINE
This attribute specifies the model line that contains the variable. You can
specify lines 1–8.
MSG
This attribute identifies the message that should be displayed when the user
does not enter any data into an input-required list column. If you do not
specify this attribute, ISPF displays a default message. This attribute is valid
only if REQUIRED=YES. “Chapter 7. Messages” on page 151 tells you how to
define application messages.
NOENDATTR
This attribute specifies that no ending attribute character will be placed after
the data column. NOENDATTR is ignored for the last data column on each
model line. See “LSTCOL (List Column)” on page 354 for more information
about the NOENDATTR attribute.
OUTLINE
This attribute provides for displaying lines around the field on a DBCS
terminal. You can define this attribute as a variable name preceded by a “%”.
See “LSTCOL (List Column)” on page 354 for more information about the
OUTLINE attribute.
PAD
This attribute specifies the pad character for initializing the field. You can
define this attribute as a variable name preceded by a “%”. See “LSTCOL (List
Column)” on page 354 for more information about the PAD attribute.
PADC
This attribute specifies the conditional padding character to be used for
initializing the field. You can define this attribute as a variable name preceded
by a “%”. See “LSTCOL (List Column)” on page 354 for more information
about the PADC attribute.

104 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PAS
This attribute is used to control the generation of the point-and-shoot indicator
for table display panels. You can define this attribute as a variable name
preceded by a “%”.
POSITION
This attribute allows you to specify the starting position of the data column.
The POSITION value must be greater than the end of the last formatted data
column for that model line and less than the right panel margin. Column
formatting for adding the data column and text takes place after the starting
position has been established. See “LSTCOL (List Column)” on page 354 for
more information.
REQUIRED
This attribute indicates if this column is required to have input for any
modified row. For input-required columns (REQUIRED=YES), ISPF will not
validate the panel unless the user has entered data into that column. If you do
not specify this attribute, input is not required on the list column. This
attribute is only valid for list columns defined as input-only or as
input/output.
TEXT
This attribute specifies a short description of the data column. Text can be
placed before or after the data column. See “LSTCOL (List Column)” on
page 354 for more information.
TEXTLOC
This attribute specifies the location of the TEXT relative to the data column.
Text can be placed on either side of the data column. See “LSTCOL (List
Column)” on page 354 for more information.
TEXTFMT
This attribute specifies the format of the text within the length of the text area.
The text can be left-justified, centered, or right-justified. See “LSTCOL (List
Column)” on page 354 for more information.
TEXTLEN
This attribute specifies the amount of space to reserve for formatting the
descriptive text. This helps you line up text on different model lines, and if the
space reserved is longer than the descriptive text, TEXTLEN permits
formatting within the reserved space with the TEXTFMT attribute. See
“LSTCOL (List Column)” on page 354 for more information.
TEXTSKIP
This attribute specifies the cursor should move past the text to the next input
field.
VARCLASS
This attribute allows you to override the variable class that is specified on the
variable declaration (VARDCL) for the list column’s data variable (DATAVAR).
See “Chapter 4. Variables and Variable Classes” on page 57 for a description of
variables and variable classes.
| CAPS
| This attribute specifies whether the data column is displayed in uppercase
| characters.
| DISPLAY
| This attribute specifies whether the data column is visible when the panel is
| displayed.

Chapter 5. Application Panel Fields 105

 Defining Group Headings
The Group Header (GRPHDR) tag defines a group heading in the panel )BODY
section.

The FORMAT attribute is used to control the type of text formatting. You can
choose formatting similar to the LINES tag or the P tag. For example, if
FORMAT=NONE, the text formats as if you used a LINES tag. However, if
FORMAT=START, CENTER, or END, the text flows to multiple lines and is
formatted at the right, center or left part of the space reserved for the group
heading.

The following list provides a short description of the other available attributes:
WIDTH
This attribute specifies the number of columns reserved for the group heading.
The default value is the remaining panel width.
FMTWIDTH
This attribute specifies the number of columns (of the WIDTH value) to use for
formatting the group heading. The default is the WIDTH value. By specifying
a FMTWIDTH that is less than the WIDTH value, the group heading text can
be formatted on multiple lines.
| INDENT
| This attribute specifies the number of bytes that the group heading is to be
| indented.
HEADLINE
This attribute specifies whether dashes are added to span the width of the
group heading not occupied by text.
DIV
This attribute specifies the type of divider line to be placed before and after the
group heading text.
DIVLOC
This attribute specifies whether the divider is to be added before the group
heading, after the group heading, or both before and after the group heading.
COMPACT
This attribute causes the group heading to format without a blank line before
the group heading.
STRIP
This attribute causes leading and trailing blanks to be removed from the group
heading text.

Defining Point-and-Shoot Fields

The Point-and-Shoot (PS) tag is used to identify a portion of panel )BODY section
text to be used for point-and-shoot selection. When a point-and-shoot selection is
made, a variable is set to a specified value before normal )PROC section
processing. The PS tag attributes identify the variable name and the value
associated with each point-and-shoot selection.

The PS tag requires a matching end tag to indicate the end of the point-and-shoot
text.

106 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Refer to the ISPF Dialog Developer’s Guide and Reference for more information about
point-and-shoot selection.

Chapter 5. Application Panel Fields 107

108 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Chapter 6. Information Regions and Help Panels
Some of the information displayed on panels is static, or fixed text that the user
does not interact with directly. This includes text such as top instructions and
bottom instructions, prompt text, and data-field description text. DTL provides you
with another method of defining static text for application panels using information
regions.

Defining an information region on a panel allows you more flexibility for defining
static text on a panel. The tags you use to define the text of information regions are
much more versatile than the tags you use to define other types of static text,
which means you can be more creative in the text you define.

In addition to using information regions on application panels, you must use them
to define the text on help panels you define for your application. In this chapter,
we tell you how to define information regions on application panels, and how to
define help panels for your applications.

Defining an Information Region

Use the INFO tag and its required end tag to define an information region on a
panel. You can code an information region within an AREA, HELP, PANEL, or
REGION definition.

Here’s an example of an INFO definition:

<panel name=infopan width=42 depth=16>Information

<area>
<info>
</info>
</area>
</panel>

The INFO tag has an optional WIDTH attribute that defines the width of the
information region. If the value you assign the INFO WIDTH attribute is greater
than the WIDTH available in the panel, the conversion utility will reset the value
to the available width.

Note: You should code the WIDTH attribute if the information region is part of an
application panel definition that uses horizontal region capability.

The INFO tag only defines an information region. It does not define the text of the
information region. DTL provides you with a set of tags that define the text in
information regions. These tags are:
v ATTENTION
v CAUTION
v DL (definition list)
v FIG (figure)
v Hn (heading)
v HP (highlighted phrase)
v LINES
v NOTE
v NOTEL (note list)
v NT (note)

© Copyright IBM Corp. 1989, 2000 109

 v OL (ordered list)
v P (paragraph)
v PARML (parameter list)
v RP (reference phrase)
v PS (point-and-shoot)
v SL (simple list)
v UL (unordered list)
v WARNING
v XMP (example).

With the exception of HP, PS, and RP, these tags can be coded only within an INFO
definition. The next section explains how to use each of these tags and some other
tags that complement these tags within information regions.

Defining Basic Text

Paragraphs
The tag you use most often in information regions is the P (paragraph) tag. Use the
P tag to arrange text as you would arrange a paragraph in your usual writing (to
join one or more sentences related by their subject matter into a single block of
text).

When the paragraph text formats for display, the text starts at the current margin
and the words automatically wrap to fit within the margin. In addition, the
conversion utility normally inserts a blank line before each paragraph.

The P tag has an optional attribute, COMPACT, which causes the blank line before
the paragraph to be omitted. The P tag does not require a matching end tag.

We’ll illustrate the use of the P tag with this example :

<!doctype dm system>
<panel name=infopan1 width=42>Information
<area>
<info width=40>
<p>This is a paragraph.
This sentence is also part of the paragraph.
</info>
</area>
</panel>

Notice that we coded the second sentence of the paragraph on a different line. It
doesn’t matter, because the conversion utility treats it as part of the same
paragraph and formats it accordingly. That is, two blanks are automatically
inserted between the sentences. Here’s how the paragraph looks:

110 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Information

This is a paragraph. This sentence is

also part of the paragraph.

Figure 42. Paragraph

As you can see, the text of the paragraph is left-justified on the panel and the
words automatically wrap to fit within the defined dimensions of the information
region.

We’ll add another paragraph to the panel to illustrate how two paragraphs format:
<!doctype dm system>
<panel name=infopan2 width=42>Information
<area>
<info width=40>
<p>This is a paragraph.
This sentence is also part of the paragraph.
<p>Here is another paragraph.
Paragraphs are useful for providing
information on panels.
</info>
</area>
</panel>

Figure 43 on page 112 shows the result:

Chapter 6. Information Regions and Help Panels 111

 Information

This is a paragraph. This sentence is

also part of the paragraph.

Here is another paragraph. Paragraphs

are useful for providing information on
panels.

Figure 43. Multiple Paragraphs

In addition to the placement and wrapping of the text, the compiler separated the
paragraphs with a blank line.

Headings
The Hn (heading) tag allows you to place headings in an information region. You
use these headings to define topics and subtopics of information. You can define
four levels of headings:
H1 Centers text in the information region. Use this heading level to identify a
main topic of information.
H2, H3, H4
Formats text against the left margin of the information region. Use one of
these heading levels to identify subtopics of information.

You must code headings sequentially. The conversion utility adds a blank line to
the information region before and after the formatted heading text. The heading
tags have no attributes associated with them, and they don’t require an end tag.

The following markup contains an information region using two heading levels
and paragraphs following each one.
<!doctype dm system>
<panel name=infopan3 width=42>Information
<area>
<info width=40>
<h1>A Main Topic
<p>Notice how the heading is in the
center of the information region?
<h2>A Subtopic
<p>This heading is left-justified.
<h2>Another Subtopic
<p>Here's another level-two heading.
</info>
</area>
</panel>

112 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Here’s the formatted result:

Information

A Main Topic

Notice how the heading is in the center

of the information region?

A Subtopic

This heading is left-justified.

Another Subtopic

Here's another level-two heading.

Figure 44. Headings (H1-H2)

Lines
Occasionally, you’ll want to present text that you don’t want formatted by the
compiler, or that you want to show “as is”. You can use the LINES (lines) tag and
its required end tag to do this. All text coded within a LINES definition is treated
as unformatted text, and you can position the text however you like on each line.
If the text line is too long to fit in the available width, the conversion utility
truncates the text and issues a warning message.

| The LINES tag requires an end tag.

There are many ways to use a LINES definition. Here we use it for a quotation:
<!doctype dm system>
<panel name=specact width=48>Special Activities
<area>
<info width=46>
<lines>
Between the dark and daylight,
When the night is beginning to lower,
Comes a pause in the days' occupations,
That's known as the children's hour.
-Longfellow
</lines>
<p>Every Tuesday evening at seven
o'clock, we present the Children's Hour,
a one-hour recital of selected children's
stories in our children's section.
</info>
</area>
</panel>

And our quotation appears just the way we marked it up:

Chapter 6. Information Regions and Help Panels 113

 Special Activities

Between the dark and daylight,

When the night is beginning to lower,
Comes a pause in the days' occupations,
That's known as the children's hour.
-Longfellow

Every Tuesday evening at seven o'clock, we

present the Children's Hour, a one-hour
recital of selected children's stories in our
children's section.

Figure 45. LINES

Examples
The XMP (example) tag is similar to the LINES tag, in that it allows you to code
unformatted text. However, the text of an XMP definition is indented two spaces
from the current margin, as opposed to the text of a LINES definition, which is not
indented from the current margin.

Like a LINES definition, you should avoid coding lines of text in an XMP
definition that exceed the available formatting width of the information region. If
the text exceeds the defined width, it is truncated.

The XMP tag requires a matching end tag.

Here’s the formatted result of an example using the XMP tag:

114 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Order a Toy

Type the catalog number of the toy you want to order

and press Enter. The number must be a 6-digit number.

For example:

Catalog Number. . . 581678

Figure 46. XMP

The markup for the previous panel looks like this:

<!doctype dm system>
<panel name=toy1 width=57>Order a Toy
<area>
<info width=55>
<p>Type the catalog number of the toy you want to order
and press Enter.
The number must be a 6-digit number.
<p>For example:
<xmp>
Catalog Number. . . 581678
</xmp>
</info>
</area>
</panel>

Figures
The FIG (figure) tag is yet another way you can code text that isn’t formatted. It
works just like the LINES tag, except you can add a ruled border above and below
the figure to separate it from the rest of the panel. You can also provide a caption
for the figure using the FIGCAP tag.

Like the LINES and XMP tags, the FIG tag requires an end tag.

To define the ruled borders for the figure, use the FRAME attribute of the FIG start
tag. The FRAME attribute has two values, RULE, which is the default, and NONE.
Because RULE is the default value, you don’t need to specify this attribute if you
want ruled lines above and below the figure. To create a figure without rules,
specify NONE as the FRAME value.

The figure in this panel formats with a ruled border:

<!doctype dm system>
<panel name=toy2 width=57>Order a Toy
<area>
<info width=55>
<p>Type the catalog number of
the toy you want to order and

Chapter 6. Information Regions and Help Panels 115

 press Enter.
The number must be a 6-digit number.
<p>For example:
<xmp>
Catalog Number. . . 581678
</xmp>
<p>A description of the toy will appear.
<fig>
ZOOM-A-GO DAREDEVIL SET

Your kids will have hours of excitement

playing with this full set of action toys.
Requires 80 “AA” batteries. Not included.
</fig>
</info>
</area>
</panel>

Here’s the formatted panel:

Order a Toy

Type the catalog number of the toy you want to order

and press Enter. The number must be a 6-digit number.

For example:

Catalog Number. . . 581678

A description of the toy will appear.

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

ZOOM-A-GO DAREDEVIL SET

Your kids will have hours of excitement

playing with this full set of action toys.
Requires 80 “AA” batteries. Not included.

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

Figure 47. Figure with Rules

If we wanted the figure to appear without a ruled border, we would have specified
FRAME=NONE for the FIG tag.

The FIG tag also has an optional WIDTH attribute that allows you to specify how
the figure is aligned in the information region. The valid values for WIDTH are
PAGE and COL. PAGE, which is the default value, aligns the figure along the left
margin of the information region. COL indicates that the figure is aligned along the
current left margin; that is, the current margin defined by the tag the figure is
nested in. This is useful, for example, for aligning figures within list items.

Figure Captions (FIGCAP) Tag

To add a caption to the figure in Figure 47, use a FIGCAP tag and caption text
within the figure definition, like this:
<!doctype dm system>
<panel name=toy3 width=57>Order a Toy
<area>
<info width=55>
<p>Type the catalog number of

116 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 the toy you want to order and
press Enter.
The number must be a 6-digit number.
<p>For example:
<xmp>
Catalog Number. . . 581678
</xmp>
<p>A description of the toy will appear.
<fig>
ZOOM-A-GO DAREDEVIL SET

Your kids will have hours of excitement

playing with this full set of action toys.
Requires 80 “AA” batteries. Not included.
<figcap>Zoom-A-Go Daredevil Set
</fig>
</info>
</area>
</panel>

The figure caption appears just below the bottom figure rule:

Order a Toy

Type the catalog number of the toy you want to order

and press Enter. The number must be a 6-digit number.

For example:

Catalog Number. . . 581678

A description of the toy will appear.

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

ZOOM-A-GO DAREDEVIL SET

Your kids will have hours of excitement

playing with this full set of action toys.
Requires 80 “AA” batteries. Not included.

------------------------------------------------
Zoom-A-Go Daredevil Set

Figure 48. Figure Caption

Defining Lists
Sometimes you want to present information to the user that is not appropriate in
paragraph form, such as list items, a sequence of items or actions, or definitions.
For these situations (and many others), you can use the DTL list tags to format
your text appropriately.

You can create these types of lists:

Note lists Format as numbered lists of notes under a header
called Notes.
Simple lists Format as indented lists of items without any
preceding identifiers.
Unordered lists Format as indented lists of items with each item

Chapter 6. Information Regions and Help Panels 117

 preceded by a bullet (o), a hyphen (-), or dashes
(--), depending on the level of nesting.
Ordered lists Format as indented lists of items with each item
preceded by a number or letter indicating its
sequence in the list.
Definition lists Format in two columns, with terms in one column
and their matching descriptions in the other. You
can also specify headings for each column in the
list. (This list is a definition list.)
Parameter lists Format in two columns. This list is specifically
designed to identify and define parameter terms.

The list items in note lists, simple lists, unordered lists, and ordered lists are
created with the list item (LI) tag. The LI tag does not require an end tag. It is
implicitly ended by another LI tag, an LP tag, or the end tag of the list it is coded
within.

Note Lists
See “Alerting Users: Notes, Warnings, Cautions, and Attention” on page 132 for an
example showing the use of note lists.

Simple Lists
A simple list is the least complex type of list. Use a simple list when the
information you are presenting does not follow a sequential pattern or when
bullets are not required to discriminate one list item from another.

Figure 49 illustrates a simple list.

Virtues

Around the child bend all the three sweet

graces:

Faith

Hope

Charity

Figure 49. Simple List

This is the markup for the panel:

<!doctype dm system>
<panel name=slistx1 width=44>Virtues
<area>

118 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 <info width=42>
<p>Around the child bend all the
three sweet graces:
<sl>
<li>Faith
<li>Hope
<li>Charity
</sl>
</info>
</area>
</panel>

We used the SL tag and its matching end tag to define the simple list. We defined
each of the list items by nesting the LI tags within the simple list definition.

As you can see, our simple list formatted with a blank line between each of the list
items. For cases where you need to conserve space, you can use the COMPACT
attribute to format the list without blank lines between the list items.

Code the COMPACT attribute within the SL start tag (before the tag close
delimiter), like this:
<!doctype dm system>
<panel name=slistx2 width=44>Virtues
<area>
<info width=42>
<p>Around the child bend all the
three sweet graces:
<sl compact>
<li>Faith
<li>Hope
<li>Charity
</sl>
</info>
</area>
</panel>

Now the simple list is compacted:

Virtues

Around the child bend all the three sweet

graces:

Faith
Hope
Charity

Figure 50. Compact Simple List

Chapter 6. Information Regions and Help Panels 119

 You can also nest simple lists within other lists. The list items format at different
indentation levels, based on the level of nesting.

The indentation for the list item is based on the SPACE attribute of the LI tag and
the enclosing list tag. When SPACE=NO (or the SPACE attribute is not present) the
list item indentation is 4 spaces. When SPACE=YES, the indentation is 3 spaces.
See “Chapter 13. Tag Reference” on page 201 for additional information about the
LI, SL, OL, and UL tags.

Unordered Lists
Unordered lists are similar to simple lists, except each list item is preceded by
symbol that is dependent on the nesting level of the list. You don’t have to supply
the symbols–the conversion utility does that for you.

Use an unordered list if the list items are long and you don’t want to imply any
particular sequence in the list.

Here’s an unordered list:

Window Shopper

With Window Shopper, you can order many

wonderful things, such as:

o Raindrops on roses

o Whiskers on kittens

o Bright copper kettles

o Warm woolen mittens

o Brown paper packages tied up with string

And many more of your favorite things!

Figure 51. Unordered List

And here’s the markup for this unordered list:

<!doctype dm system>
<panel name=winshop width=48>Window Shopper
<area>
<info width=46>
<p>With Window Shopper, you can order many wonderful things,
such as:
<ul>
<li>Raindrops on roses
<li>Whiskers on kittens
<li>Bright copper kettles
<li>Warm woolen mittens
<li>Brown paper packages tied up with string
</ul>
<p>And many more of your favorite things!
</info>
</area>
</panel>

120 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
For our unordered list, we used the UL tag and its matching end tag. As you can
see, even though we didn’t code the bullet symbols (o) in the markup, they appear
before each of the list items in the unordered list.

We could make this list compact like our simple list example because the
COMPACT attribute is also valid for the UL tag. Likewise, we could use the
SPACE attribute to control indentation of the list items for the UL tag.

You can also define levels of unordered lists; that is, you can nest unordered lists
within other unordered lists. When you do this, the symbols preceding the list
items in each level of the list vary, depending on the level of nesting. Specifically,
the list items in the first (or only) level of unordered list are preceded by bullets
(o), as shown in Figure 51 on page 120. If you nest another unordered list within an
unordered list,the list items in that list are preceded by hyphen symbols (-). A
third-level unordered list has dashes (--) preceding the list items. The nested tag
text is aligned according to the level of nesting.

To show how this works, we’ll create a panel with three levels of unordered lists.
<!doctype dm system>
<panel name=ulists width=42>Nested Unordered Lists
<area>
<info width=40>
<ul>
<li>First level, first item
<li>First level, second item
<ul>
<li>Second level, first item
<li>Second level, second item
<ul>
<li>Third level, only item
</ul>
</ul>
<li>Back to the first level
</ul>
</info>
</area>
</panel>

Here’s how this panel looks:

Chapter 6. Information Regions and Help Panels 121

 Nested Unordered Lists

o First level, first item

o First level, second item

- Second level, first item

- Second level, second item

-- Third level, only item

o Back to the first level

Figure 52. Nested Unordered Lists

If you nest more than three levels of unordered lists, the sequence of bullets,
hyphens, and dashes repeats. For example, a fourth level would be preceded by
bullets, a fifth level by hyphens, and so on.

Remember, all lists must be explicitly ended with the appropriate list end tag.

Ordered Lists
Ordered lists imply an outline sequence to the list items by preceding each of the
list items with a number or character depending on the level of nesting.

Here’s an ordered list:

Window Shopper

After you have placed your order with Window

Shopper, you should...

1. Press the Enter key to leave the Order Panel.

2. Go to the receiving desk located at the front

of the store.

3. Give the cashier the pink copy of your

receipt.

4. Take your purchases home, and enjoy!

Figure 53. Ordered List

122 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 You don’t supply the numbers for the list items in your markup; they are
generated automatically. This saves you time when you revise ordered lists,
because you can insert, delete, or rearrange list items without renumbering them
yourself.

Here’s the markup we used for this list:

<!doctype dm system>
<panel name=winshop2 width=52>Window Shopper
<area>
<info width=50>
<p>After you have placed your order with Window Shopper, you should...
<ol>
<li>Press the Enter key to leave the Order Panel.
<li>Go to the receiving desk located at the front of the store.
<li>Give the cashier the pink copy of your receipt.
<li>Take your purchases home, and enjoy!
</ol>
</info>
</area>
</panel>

Like other types of lists, you can nest ordered lists within other lists. And, like
unordered lists, the levels of the lists you nest determine the characters that
precede the list items.

Specifically, the conversion utility uses the following sequence when processing list
items in nested ordered lists:
v First-level list items are preceded by sequential numbers followed by a period
and 2 spaces 5.
v Second-level list items are preceded by sequential lowercase alphabetic
characters followed by a period and 2 spaces 5.
v Third-level list items are preceded by sequential numbers followed by a close
parentheses symbol and 2 spaces 5.
v Fourth-level list items are preceded by sequential lowercase alphabetic characters
followed by a close parentheses symbol and 2 spaces 5.

Note: Each level beyond the first level indents 45 spaces.

The sequence of nesting is repeated for levels of nesting beyond the fourth level.
For example, the list items in a fifth level of nesting are preceded by sequential
numbers followed by a period.

To show you what this looks like, we’ll nest three levels of ordered lists in this
markup. We’ll use the COMPACT attribute in the third level to conserve space.
<!doctype dm system>
<panel name=olists width=42>Nested Ordered Lists
<area>
<info width=40>
<ol>
<li>Step one (first level)
<li>Step two (first level)
<ol>
<li>Step one (second level)
<li>Step two (second level)
<ol compact>

5. The default indentation for a list item is 4 spaces. When the SPACE=YES attribute is coded, the indentation is 3 spaces. See the LI
and OL tag descriptions in “Chapter 13. Tag Reference” on page 201 for more information.

Chapter 6. Information Regions and Help Panels 123

 <li>Step one (third level)
<li>Step two (third level)
</ol>
<li>Step three (second level)
</ol>
<li>Step three (first level)
</ol>
</info>
</area>
</panel>

Here’s how the DTL compiler formats this panel:

Nested Ordered Lists

1. Step one (first level)

2. Step two (first level)

a. Step one (second level)

b. Step two (second level)

1) Step one (third level)

2) Step two (third level)

c. Step three (second level)

3. Step three (first level)

Figure 54. Nested Ordered Lists

Definition Lists
Definition lists allow you to identify a list of words or phrases and their
corresponding definitions. A definition list formats as a two-column list: the terms
you define appear in the left column, and the definitions for the terms appear in
the right column. Definition lists are slightly more complex than the previous lists
we’ve discussed, because of the additional tags required to construct them.

The tags used to create a definition list are:

DL Begins a definition list. The required end tag ends the list.
DT Identifies the term being defined. The definition term is formatted in the
left column of the list. It does not require an end tag.
DD Identifies the term description. Each definition description is formatted in
the right column of the list, immediately opposite or below its associated
term. It does not require an end tag.

You can also create headings for definition list columns. There are two additional
tags that you can use to do this. They are:
DTHD Defines a header for the definition term column.
DDHD Defines a header for the definition description column.

124 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Both of these tags are optional for creating definition lists. We’ll show you how
you can use them to enhance definition lists later on in this section.

Here’s an example of a definition list:

Department Codes

Use the following codes for each of the

matching departments:

AP Appliances

AU Automotive

GA Garden shop

HB Health and beauty

HO Home decor

SP Sporting goods

Figure 55. Definition List

Here’s the markup:

<!doctype dm system>
<panel name=deptcode width=42>Department Codes
<area>
<info width=40>
<p>Use the following codes for each of the
matching departments:
<dl>
<dt>AP
<dd>Appliances
<dt>AU
<dd>Automotive
<dt>GA
<dd>Garden shop
<dt>HB
<dd>Health and beauty
<dt>HO
<dd>Home decor
<dt>SP
<dd>Sporting goods
</dl>
</info>
</area>
</panel>

The DL tag has optional attributes:

TSIZE specifies the space allocated for the term column
BREAK indicates if the definition formats on the same line as its associated
term
COMPACT determines if there is a space between each set of terms and
descriptions

Chapter 6. Information Regions and Help Panels 125

 NOSKIP suppresses the blank line normally placed before the list
INDENT controls the indentation from the current left margin

Use the TSIZE attribute to specify how much space you want for the definition
term column. The default value is 10 bytes. If you want to specify more (or less)
space than the default, use the TSIZE attribute to assign the value you want.

Use the BREAK attribute to specify where the definition descriptions are supposed
to start (on the same line as the definition terms or on the next line). The BREAK
attribute can be specified as NONE, ALL, or FIT.
NONE The definition descriptions start on the same lines as the definition
terms.
ALL All of the definition descriptions start on the line after the
definition terms.
FIT The definition descriptions are to start on the next line only when
the definition term does not fit in the allocated space and spills
over into the description area.

The definition list in Figure 55 on page 125 used the default BREAK=NONE. We’ll
define another list that uses BREAK=ALL.
<!doctype dm system>
<panel name=reverb1 width=52>Reverberations
<area>
<info width=50>
<p>Reverberations is one of the most popular brands of electronic
components available today.
We stock the following Reverberations components:
<dl break=all>
<dt>CD Player Unit
<dd>With auto-search, auto-off, power door, and
a two-year warranty.
<dt>Receiver
<dd>Digital, 6-speaker hookup, and built-in
equalizer.
<dt>Tape deck
<dd>Supports metal and chrome cassettes, and comes with
a two-year warranty.
</dl>
</info>
</area>
</panel>

Figure 56 on page 127 shows how this definition list formats.

126 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Reverberations

Reverberations is one of the most popular brands

of electronic components available today. We
stock the following Reverberations components:

CD Player Unit
With auto-search, auto-off, power door,
and a two-year warranty.

Receiver
Digital, 6-speaker hookup, and built-in
equalizer.

Tape deck
Supports metal and chrome cassettes, and
comes with a two-year warranty.

Figure 56. Definition List (BREAK=ALL)

Because the TSIZE and BREAK attributes lend versatility to definition lists, we can
rearrange this list practically any way we want. We’ll change the BREAK value to
FIT, and increase the TSIZE to 13 to show you what we mean. We’ll also add
headings to the list to show you how they format.
<!doctype dm system>
<panel name=reverb2 width=52>Reverberations
<area>
<info width=50>
<p>Reverberations is one of the most popular brands of electronic
components available today.
We stock the following Reverberations components:
<dl tsize=13 break=fit>
<dthd>Component
<ddhd>Features
<dt>CD Player Unit
<dd>With auto-search, auto-off, power door, and
a two-year warranty.
<dt>Receiver
<dd>Digital, 6-speaker hookup, and built-in equalizer.
<dt>Tape deck
<dd>Supports metal and chrome cassettes, and comes with
a two-year warranty.
</dl>
</info>
</area>
</panel>

Here’s how the panel looks now:

Chapter 6. Information Regions and Help Panels 127

 Reverberations

Reverberations is one of the most popular brands

of electronic components available today. We
stock the following Reverberations components:

Component Feature

CD Player Unit
With auto-search, auto-off, power
door, and a two-year warranty.

Receiver Digital, 6-speaker hookup, and

built-in equalizer.

Tape deck Supports metal and chrome cassettes,

and comes with a two-year warranty.

Figure 57. Definition List (BREAK=FIT)

Parameter Lists
Parameter lists are another way of defining terms in a list form. You use a
parameter list when the terms you are defining are related to the application in
some way (for example, showing codes or parameters).

The tags you use to create parameter lists are the PARML tag and its required end
tag, the PT (parameter term) tag, and the PD (parameter description) tag. The
parameter list tags work a lot like the definition list tags in defining terms and
descriptions, except there are no tags for defining list headings.

The PARML tag also contains the TSIZE and BREAK attributes. The TSIZE default
value is 10 bytes, as it is for definition lists. However, the BREAK default value for
parameter lists is ALL, instead of NONE, as in definition lists. Thus, the parameter
descriptions format on the lines following the parameter terms unless you specify
otherwise.

Here’s the markup for a typical parameter list:

<!doctype dm system>
<panel name=ordnum width=52>Order Numbers
<area>
<info width=50>
<p>The order number assigned to each inventory item
represents specific information about the item.
<p>Specifically,
<parml>
<pt>123
<pd>The first 3 digits represent the
department the item is stocked in.
<pt>456
<pd>The fourth, fifth, and sixth digits
represent the item.
<pt>78
<pd>The seventh and eighth digits represent
the lot number of the item.

128 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 </parml>
</info>
</area>
</panel>

And here’s the formatted parameter list:

Order Numbers

The order number assigned to each inventory item

represents specific information about the item.

Specifically,

123
The first 3 digits represent the
department the item is stocked in.

456
The fourth, fifth, and sixth digits
represent the item.

78
The seventh and eighth digits represent
the lot number of the item.

Figure 58. Parameter List

Nesting Tags within Lists

The format of your lists isn’t confined to only list items. You can also nest other
tags within the list items. For example, if a list item requires an additional
paragraph, you can nest a P tag following the list item.

This markup contains an ordered list with a paragraph nested within the second
list item.
<!doctype dm system>
<panel name=winshop3 width=52>Window Shopper
<area>
<info width=50>
<p>After you have placed your order with Window Shopper, you should...
<ol>
<li>Press the Enter key to leave the Order Panel.
<li>Go to the receiving desk located at the front of the store.
<p>Don't forget to bring your receipt!
<li>Give the cashier the pink copy of your receipt.
<li>Take your purchases home, and enjoy!
</ol>
</info>
</area>
</panel>

The paragraph text follows the indentation of the preceding list item, like this:

Chapter 6. Information Regions and Help Panels 129

 Window Shopper

After you have placed your order with Window

Shopper, you should...

1. Press the Enter key to leave the Order Panel.

2. Go to the receiving desk located at the front

of the store.

Don't forget to bring your receipt!

3. Give the cashier the pink copy of your

receipt.

4. Take your purchases home, and enjoy!

Figure 59. Nested Paragraph within a List

The List Part (LP) Tag

If you want to insert unindented text in a list, use the list part (LP) tag. The LP tag
is useful for providing information about the list items that follow it.

We added a list part to the panel shown in Figure 59:

<!doctype dm system>

<panel name=winshop4 width=52>Window Shopper

<area>
<info width=50>
<p>After you have placed your order with Window Shopper, you should...
<ol>
<li>Press the Enter key to leave the Order Panel.
<li>Go to the receiving desk located at the front of the store.
<p>Don't forget to bring your receipt!
<li>Give the cashier the pink copy of your receipt.
<lp>Occasionally, the item you ordered won't be in stock.
If this occurs, the cashier will be happy to delete
the item from your order.
<li>Take your purchases home, and enjoy!
</ol>
</info>
</area>
</panel>

Here’s the formatted result:

130 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Window Shopper

After you have placed your order with Window

Shopper, you should...

1. Press the Enter key to leave the Order Panel.

2. Go to the receiving desk located at the front

of the store.

Don't forget to bring your receipt!

3. Give the cashier the pink copy of your

receipt.

Occasionally, the item you ordered won't be in

stock. If this occurs, the cashier will be happy
to delete the item from your order.

4. Take your purchases home, and enjoy!

Figure 60. List Part

Nesting Lists within Lists

On pages 121 and 123 we showed you how to define levels of nested unordered
and ordered lists. You can also nest different types of lists within other lists.

Here’s an example of an unordered list nested within a definition list:

Payment Procedures

Methods of Payment

Cash
Of course, we always accept cash!

Charge
Your charge card is welcome here! We
accept the following charge cards:

o BigCharge
o MoneyCard
o Plastic Express

Personal Check
We gladly welcome your personal check,
with the proper identification.

Figure 61. Nested Unordered List in a Definition List

Here’s the markup we used to create the nested lists in Figure 61:
<!doctype dm system>

<panel name=payment width=52>Payment Procedures

<area>

Chapter 6. Information Regions and Help Panels 131

 <info width=50>
<h1>Methods of Payment
<dl tsize=9 break=all>
<dt>Cash
<dd>Of course, we always accept cash!
<dt>Charge
<dd>Your charge card is welcome here!
We accept the following charge cards:
<ul compact>
<li>BigCharge
<li>MoneyCard
<li>Plastic Express
</ul>
<dt>Personal check
<dd>We gladly welcome your personal check,
with the proper identification.
</dl>
</info>
</area>
</panel>

You can nest any type of list within another list. Remember, whenever you nest
lists, be sure that you end each level with its proper end tag.

Alerting Users: Notes, Warnings, Cautions, and Attention

DTL provides you with tags that you can use to alert the user to certain text that
warrants special attention. Whether you are noting a minor aspect of the
application or alerting the user to the risk of possible damage to programs or data,
you can alert the user appropriately.

In this section, we discuss the following tags:

v ATTENTION
v CAUTION
v NOTE
v NOTEL
v NT
v WARNING.

Notes
The NOTE, NOTEL, and NT tags format as noted text. Use notes to emphasize
minor points.

When you use either the NOTE or NT tag, you get the text “Note:” followed by a
space before the text you specify. However, the text is formatted differently
depending on which tag you use.

The NOTEL tag is formatted with the first line containing the text ″Notes:″
followed by a numbered list of note information provided by the <LI> tag.
The NOTE tag
If the text is a single paragraph, you use the NOTE tag. The text is
formatted as an unindented block, like a paragraph. The NOTE tag does
not require a matching end tag.
You use the NOTE tag like this:
<!doctype dm system>
<panel name=widget61 width=50>Widgets
<area>
<info width=48>

132 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 <p>Choose the type of Widget you want to order by placing
the cursor on the field and pressing Enter.
<note>If the Widget you wish to order is not in stock, please
refer to the “Back Order” panel to place an order.
</info>
</area>
</panel>

Figure 62 shows how it formats.

Widgets

Choose the type of Widget you want to order by

placing the cursor on the field and pressing
Enter.

Note: If the Widget you wish to order is not in

stock, please refer to the “Back Order” panel to
place an order.

Figure 62. Note (NOTE tag)

The NOTEL tag

If more than one note is used for special attention information, you use the
NOTEL tag. Each note is provided by a separate LI tag. The notes are
numbered similar to the format described in “Ordered Lists” on page 122.
You use either the P or LP tag to add any additional paragraphs in the
NOTEL definition. Use the required end tag to end the NOTEL definition.
In this example, 2 notes are used, 1 with more than one paragraph. We use
the NOTEL tag and its required end tag along with LI tags to define the
notes, and a P tag for the additional paragraph.
<!doctype dm system>
<panel name=widget63 width=50>Widgets
<area>
<info width=48>
<p>Choose the type of Widget you want to order by placing
the cursor on the field and pressing Enter.
<notel>
<li>If the Widget you wish to order is not in stock, please
refer to the "Back Order" panel to place an order.
<li>Back-ordered Widgets usually arrive within three days.
<p>Please check again in three days.
</notel>
<p>If you want to order more than one Widget, specify the quantity
and press Enter.
</info>
</area>
</panel>

Chapter 6. Information Regions and Help Panels 133

 Notice that the P tag in the note is coded before the NOTEL end tag,
indicating that the second paragraph belongs in the note.

Here’s how the panel looks now:

Widgets

Choose the type of Widget you want to order by

placing the cursor on the field and pressing
Enter.

Notes:

1. If the Widget you wish to order is not in

stock, please refer to the “Back Order”
panel to place an order.

2. Back-ordered Widgets usually arrive within

three days.

Please check again in three days.

If you want to order more than one Widget,

specify the quantity and press Enter.

Figure 63. Notel (NOTEL tag)

As you can see, the the text of the NOTEL tag is formated as a list under
the ″Notes:″ heading. The text of the P tag is indented to match the list
items.
The NT tag
If the note requires more than one paragraph, you use the NT tag. You use
the P tag to add any additional paragraphs in the NT definition. Use the
required end tag to end the NT definition.
Another difference between the NOTE and NT tag is that the NT tag
indents the note text from the left panel margin.
In this example, the note is longer than one paragraph. We use the NT tag
and its required end tag to define the note, and a P tag for each additional
paragraph.
<!doctype dm system>
<panel name=widget62 width=50>Widgets
<area>
<info width=48>
<p>Choose the type of Widget you want to order by placing
the cursor on the field and pressing Enter.
<nt>If the Widget you wish to order is not in stock, please
refer to the “Back Order” panel to place an order.
<p>Back-ordered Widgets usually arrive within three days.
</nt>
<p>If you want to order more than one Widget, specify the quantity
and press Enter.
</info>
</area>
</panel>

Notice that the P tag in the note is coded before the NT end tag, indicating
that the second paragraph belongs in the note.

134 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Here’s how the panel looks now:

Widgets

Choose the type of Widget you want to order by

placing the cursor on the field and pressing
Enter.

Note: If the Widget you wish to order is not in

stock, please refer to the “Back Order”
panel to place an order.

Back-ordered Widgets usually arrive

within three days.

If you want to order more than one Widget,

specify the quantity and press Enter.

Figure 64. Note (NT tag)

As you can see, the text of the NT tag is indented, as is the text of the P
tag coded within the NT tag.

Attention and Warning

Attention statements and warning statements alert the user of a possible risk
involved with a user action, or of existing error conditions.

You must immediately precede the ATTENTION or WARNING tag with a P

(paragraph) tag, LI (list item) tag, or LP (list part) tag. The warning statement
formats with the term “Warning:” before the text. The attention statement formats
with the term “Attention:” before the text.

The ATTENTION and WARNING tags have no associated attributes and require a
matching end tag.

Here’s the markup for a warning statement that formats as a paragraph.

<!doctype dm system>
<panel name=addfile width=50>Changing a File
<area>
<info width=48>
<p>After you have made the desired changes
to the file, press Enter to save the changes.
<p><warning>Pressing Enter saves
ALL changes made to the file.
You can cancel this operation by pressing
the F12=Cancel key.
</warning>
</info>
</area>
</panel>

Here’s the formatted result:

Chapter 6. Information Regions and Help Panels 135

 Changing a File

After you have made the desired changes to the

file, press Enter to save the changes.

Warning: Pressing Enter saves ALL changes made

to the file. You can cancel this operation by
pressing the F12=Cancel key.

Figure 65. Warning

Caution
Caution statements indicate the greatest degree of severity. Like the WARNING
tag, the CAUTION tag has a required end tag, and must be preceded by a P
(paragraph) tag, LI (list item) tag, or LP (list part) tag. The caution statement
formats with the term “CAUTION:” followed by the caution text on the next line.
<!doctype dm system>
<panel name=delfile width=50>Deleting a File
<area>
<info width=48>
<p>To delete a file, type the filename in the
“Delete this file” field and press Enter.
<p>A message appears asking for verification.
To continue the delete operation, press Enter.
<p><caution>Verifying the delete operation
permanently deletes the file from your records.
There is no chance of recovery.
</caution>
</info>
</area>
</panel>

Here’s the formatted result:

136 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Deleting a File

To delete a file, type the filename in the

“Delete this file” field and press Enter.

A message appears asking for verification. To

continue the delete operation, press Enter.

CAUTION:
Verifying the delete operation permanently
deletes the file from your records. There is no
chance of recovery.

Figure 66. Caution

Emphasizing Panel Text

You can emphasize text on application panels or on help panels with highlighting
by using the HP (highlighted phrase) tag. You can also highlight words or phrases
to indicate that additional information is available by using the RP (reference
phrase) tags. On a color terminal, the emphasized text displays in a CUA defined
color, or whatever color you set with the Color Change Utility.

Highlighting requires the use of 3270 attribute bytes to control the display of
highlighted text. The attribute positions before and after the highlighted text
display as blank spaces. These attributes might limit the formatting of your
highlighted phrase or reference phrase.

For example, if you typed your text as follows:

<HP>To cancel this option</HP>, press the F12 key.

Here’s the result:

To cancel this option, press the F12 key.

You can prevent this situation by writing statements that do not require
punctuation following an HP or an RP end tag.

Highlighted Phrases
The HP (highlighted phrase) tag provides emphasis through highlighting. You can
focus the user’s attention to particular sections of the panel text by highlighting
words, phrases, or entire paragraphs.

The HP tag requires a matching end tag to indicate the end of a highlighted
phrase.

The following markup example shows you how to use the HP tag.

Chapter 6. Information Regions and Help Panels 137

 <!DOCTYPE DM SYSTEM>

<VARCLASS NAME=date TYPE='char 8'>

<VARCLASS NAME=numcls TYPE='numeric 7'>
<VARCLASS NAME=namecls TYPE='char 25'>
<VARCLASS NAME=char1cls TYPE='char 1'>
<VARCLASS NAME=char7cls TYPE='char 7'>

<VARLIST>
<VARDCL NAME=whchsrch VARCLASS=char1cls>
<VARDCL NAME=curdate VARCLASS=date>
<VARDCL NAME=cardno VARCLASS=numcls>
<VARDCL NAME=name VARCLASS=namecls>
<VARDCL NAME=address VARCLASS=namecls>
<VARDCL NAME=cardsel VARCLASS=char1cls>
<VARDCL NAME=card VARCLASS=char7cls>
<VARDCL NAME=north VARCLASS=char1cls>
<VARDCL NAME=south VARCLASS=char1cls>
<VARDCL NAME=east VARCLASS=char1cls>
<VARDCL NAME=west VARCLASS=char1cls>
</VARLIST>

<PANEL NAME=hlitep>Library Card Registration

<AB>
<ABC>File
<PDC>Add Entry
<ACTION RUN=add>
<PDC>Delete Entry
<ACTION RUN=delete>
<PDC>Update Entry
<ACTION RUN=update>
<PDC>Exit
<ACTION RUN=exit>
<ABC>Search
<PDC CHECKVAR=whchsrch MATCH=1>Search on name
<ACTION SETVAR=whchsrch VALUE=1>
<ACTION RUN=search>
<PDC CHECKVAR=whchsrch MATCH=2>Search on card number
<ACTION SETVAR=whchsrch VALUE=2>
<ACTION RUN=search>
<ABC>Help
<PDC>Extended Help...
<ACTION RUN=exhelp>
<PDC>Keys Help...
<ACTION RUN=keyshelp>
</AB>
<TOPINST>Type in <HP>patron's name</HP> and <HP>card number</HP>
(if applicable).
<TOPINST>Then select an action bar choice.
<AREA>
<DTACOL PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25 SELWIDTH=25>
<DTAFLD DATAVAR=curdate USAGE=out ENTWIDTH=8>Date
<DTAFLD DATAVAR=cardno ENTWIDTH=7>Card No.
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address>Address
</DTACOL>
<DIVIDER>
<REGION DIR=horiz>
<SELFLD NAME=cardsel PMTWIDTH=30 SELWIDTH=38>Choose
one of the following
<CHOICE CHECKVAR=card MATCH=new>New
<CHOICE CHECKVAR=card MATCH=renew>Renewal
<CHOICE CHECKVAR=card MATCH=replace>Replacement
</SELFLD>
<SELFLD TYPE=multi PMTWIDTH=30 SELWIDTH=25>Check valid branches

138 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 <CHOICE NAME=north HELP=nthhlp CHECKVAR=nth>North Branch
<CHOICE NAME=south HELP=sthhlp CHECKVAR=sth>South Branch
<CHOICE NAME=east HELP=esthlp CHECKVAR=est>East Branch
<CHOICE NAME=west HELP=wsthlp CHECKVAR=wst>West Branch
</SELFLD>
</REGION>
</AREA>
<CMDAREA>Enter a command
</PANEL>

Here’s the formatted result:

File Search Help

--------------------------------------------------------------------------
Library Card Registration

Type in patron's name and card number (if applicable).

Then select an action bar choice.

Date . . . : 08/29/90
Card No. . . _______ (A 7-digit number)
Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following Check valid branches

__ 1. New _ North Branch
2. Renewal _ South Branch
3. Replacement _ East Branch
_ West Branch

Enter a command ===> ______________________________________________________

F1=Help F2=Split F3=Exit F6=KEYSHELP F9=Swap
F12=Cancel

Figure 67. Highlighted Phrase Example

Reference Phrases
The RP (reference phrase) tag allows you to highlight words or phrases on panels
to indicate that additional help information is available. When a help panel with
reference phrases is displayed, the cursor is positioned in the first reference phrase.
When an application panel containing reference phrases is displayed, the cursor
will be positioned to the first reference phrase or panel input field, unless the
cursor setting has been specified by the application. The reference phrase is an
input-capable field so that the user can tab to successive reference phrases on the
panel. The reference phrase text is refreshed whenever the panel is displayed.

| When the user places the cursor on a reference phrase and requests help, the
| reference phrase panel or message is displayed. Reference phrase help panels
| themselves can also contain reference phrases. When a user cancels a reference
| phrase help, the panel from which the user requested the reference phrase help is
| displayed again. All other help facilities, such as KEYSHELP and EXHELP, are
| available from a reference phrase help panel.

The RP tag requires a matching end tag to indicate the end of the reference phrase
text.

The following markup example shows you how to use the RP tag.
<!DOCTYPE DM SYSTEM>

<HELP NAME=frenchl depth=12>Help for Masters Degree in French Literature

Chapter 6. Information Regions and Help Panels 139

 <area>
<info>
<p>
The Masters in French Literature (MFL) Program is also available
to students interested in
<rp help=liteve>evening studies.</rp>
<p>
Please consult your program advisers for details before registering for
a class.
</info>
</area>
</help>

<help name=liteve depth=13>Help for Evening Studies

<area>
<info>
<p>
Evening Studies offered by the French Literature
graduate program are available to students
interested in part-time and full-time studies.
All core courses and many electives are offered
in the evening on a rotating basis. Please
consult your program advisers for details before
registering for a class.
</info>
</area>
</help>

Here’s the formatted result:

Help for Masters Degree in French Literature

The Masters in French Literature (MFL) Program

is also available to students interested in
evening studies.

Please consult your program advisers for details

before registering for a class.

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 68. Reference Phrase Example

Accordingly, when the user selects the reference phrase evening studies, the help
panel specified by the HELP attribute (help=liteve) is displayed.

140 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Help for Evening Studies

Evening Studies offered by the French Literature

graduate program are available to students
interested in part-time and full-time studies.
All core courses and many electives are offered
in the evening on a rotating basis. Please
consult your program advisers for details before
registering for a class.

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 69. Reference Phrase Example of Help Attribute

The help-panel-name attribute specifies the name of the help panel to be displayed if
the reference phrase is selected.

Using Information Regions with Other Panel Elements

You can use information regions to complement the other elements of an
application panel in many different ways. For example, you can use an information
region to provide additional information for fields on an application panel.

The information region in the following markup example uses a paragraph and a
compact ordered list to tell the user how to interact with the panel fields. Figure 70
on page 142 shows the formatted result.
<!doctype dm system>

<VARCLASS NAME=selcls TYPE='char 1'>

<VARLIST>
<VARDCL NAME=day VARCLASS=selcls>
<VARDCL NAME=time VARCLASS=selcls>
</VARLIST>

<panel name=appmnt>Make an Appointment

<area>
<info width=74>
<p>To schedule an appointment, you must choose one
selection from each field.
<ol compact>
<li>Choose a day from the first field.
<li>Choose a time slot from the second field.
<li>After you have completed both fields, press
Enter to log your appointment and leave the panel.
</ol>
</info>
<divider type=solid gutter=3>
<region dir=horiz>
<region>
<selfld name=day selwidth=20 pmtwidth=9>Weekdays:
<choice>Monday
<choice>Tuesday
<choice>Wednesday
<choice>Thursday
<choice>Friday
</selfld>
</region>
<divider gutter=8>
<region>
<selfld name=time selwidth=20 pmtwidth=5>Time:
<choice>9:00

Chapter 6. Information Regions and Help Panels 141

 <choice>10:00
<choice>11:00
<choice>12:00
<choice>1:00
<choice>2:00
<choice>3:00
<choice>4:00
</selfld>
</region>
</region>
</area>
</panel>

Make an Appointment

To schedule an appointment, you must choose one selection from each field.

1. Choose a day from the first field.

2. Choose a time slot from the second field.
3. After you have completed both fields, press Enter to log your
appointment and leave the panel.

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

Weekdays: Time:
__ 1. Monday __ 1. 9:00
2. Tuesday 2. 10:00
3. Wednesday 3. 11:00
4. Thursday 4. 12:00
5. Friday 5. 1:00
6. 2:00
7. 3:00
8. 4:00

Figure 70. Information Region

Help Panels
In this section, we show you how to use the DTL to define help panels that
provide help to users while they are using an ISPF application. We also show you
how to link help panels with application panels.

Defining Help Panels

The HELP tag and its required end tag define a help panel. The HELP start tag
indicates the beginning of a help panel definition, and the HELP end tag closes the
definition. All of the other tags that compose a help panel are coded between these
two tags. You also use the HELP tag to define the help panel title in the same way
you code panel title text with the PANEL tag, as tag content.

The HELP tag and its matching end tag look like this:
<help name=help01>Help Panel Title
</help>

In the above example, we added the required NAME attribute and value to the
HELP start tag. The NAME value you assign must follow the standard naming
convention described in “Rules for Variable Names” on page 201.

The value you assign to NAME is the value that elements such as application
panels, fields, and messages use to provide help to the user.

142 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
For example, if we define the help we want to provide for an application panel in
a help panel with the NAME value help01, we would specify that help panel like
this in the PANEL definition:
<panel name=panel01 width=60 depth=18 help=help01>Application

The help panel help01 would appear when the user requests help for that
application panel.

Like the PANEL tag, the HELP tag has WIDTH and DEPTH attributes that define
the dimensions of the panel. However, help panels differ from application panels.
If the DEPTH attribute is specified on the AREA tag, a single panel is created with
a scrollable section to allow the display of longer sections of help text. Otherwise,
the conversion utility generates as many help panels as needed (up to 37) for the
help text content you define. This means that you can define text for a help panel
that exceeds the defined depth, and, even though the text may not appear in the
initial display of the panel, the user can view the text through page scrolling.
Examples of both types of help panel scrolling are shown on page 145 and
Figure 77 on page 148.

Because ISPF displays all DTL-defined help panels in pop-ups, the WIDTH and
DEPTH values you specify must allow for the addition of two lines (depth) and 4
characters (width) for pop-up borders. Therefore, WIDTH=76 and DEPTH=22 are
the maximum values that can be used with 80-by-24 display devices. The HELP
panel default values are WIDTH=50 and DEPTH=10.

Typically, you would define help panel values of WIDTH=60 and DEPTH=22 or
less. The specified depth must include allowance for the panel title line and its
separator. A help panel that does not end with a scrollable area also reserves four
lines for the function key area.

Defining Help Panel Text

The text you define for help panels cannot be modified by the user; it is for
information purposes only. To define this text, use an information region and the
tags associated with information regions. The INFO tag and its matching end tag
are required in help panel definitions.

You can also use AREA definitions within help panels. Remember to code the
entire INFO definition (start and end tag) within the AREA definition, just as you
would on an application panel. Here’s an example:

<help name=help01>Help Panel Title

<area>
. <info>
.
.
</info>
</area>
</help>

You can use any of the information region tags discussed earlier in this chapter in
a help panel. For example, you use the P (paragraph) tag to define a paragraph of
text on a help panel the same way you use it to define a paragraph on an
application panel.

In the following help panel markup, we use two paragraphs, an unordered list, a
figure and figure caption to define the help text. The specification of DEPTH=28 is
valid only if the display terminal has 30 or more display lines. Figure 71 on
page 144 shows the formatted result.

Chapter 6. Information Regions and Help Panels 143

 <!doctype dm system>

<help name=olcthlp depth=28 width=50>Help for Online Catalog

<area>
<info>
<p>The Online Catalog provides
you with:
<ul compact>
<li>The book title
<li>Catalog number
<li>Page count
<li>The author
<li>A brief description
</ul>
<p>Here is an example:
<fig>
The Yellow Subroutine
365 Pages 1234.56
John-Paul Georgenringo

A young band of British programmers embarks on

a voyage across a perilous “sea” language in
search of FORTRAN and fame.
<figcap>Online Catalog Example
</fig>
</info>
</area>
</help>

Help for Online Catalog

The Online Catalog provides you with:

o The book title

o Catalog number
o Page count
o The author
o A brief description

Here is an example:

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

The Yellow Subroutine

365 Pages 1234.56
John-Paul Georgenringo

A young band of British programmers embarks on

a voyage across a perilous “sea” language
in search of FORTRAN and fame.

------------------------------------------------
Online Catalog Example

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 71. Help Panel

In Figure 71, all of the text was displayed because the depth we defined for the
help panel was large enough to accommodate the text. However, the amount of
help you want to provide for your users can vary, and it’s not always possible to
display all of the help text you define in the initial panel display, especially when
you don’t, or can’t, specify a large DEPTH value for the help panel.

144 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Depending on the use of the AREA tag, the conversion utility generates multiple
panels or a single scrollable help panel.

The following help panel markup includes an information region that contains a
paragraph, a definition list, and two unordered lists nested within the definition
list.

The addition of the DEPTH attribute on the AREA tag illustrates a scrollable panel.
<!DOCTYPE DM SYSTEM>

<help name=helpscr width=46 depth=16>ShelfBrowse for Kids

<area depth=10>
<info>
<p>ShelfBrowse can help you
find any kind of book you are looking for.
The two main categories for books are:
<dl tsize=12>
<dthd>Book
<ddhd>Description
<dt>Fiction
<dd>Fiction books are stories
that never really happened.
The writer made them up.
For example:
<ul>
<li>Fairy Tales
<li>Mysteries
<li>Science fiction stories
</ul>
<dt>Nonfiction
<dd>Nonfiction books are about
things that really exist.
For example:
<ul>
<li>History books
<li>Reference books
<li>How-to books
</ul>
</dl>
</info>
</area>
</help>

When initially displayed, the first part of the scrollable text is visible. For this
example, to scroll down, place the cursor on the first or last displayed line of text,
and press Enter or the RIGHT (F11) key. Use the LEFT (F10) key to scroll up.

Chapter 6. Information Regions and Help Panels 145

 HELPSCR ShelfBrowse for Kids

More: +

ShelfBrowse can help you find any kind of

book you are looking for. The two main
categories for books are:

Book Description

Fiction Fiction books are stories that

never really happened. The

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 72. Help Panel (Example 1 of 4)

After scrolling down, the following panel appears:

HELPSCR ShelfBrowse for Kids

More: - +
never really happened. The
writer made them up. For
example:

o Fairy tales

o Mysteries

o Science fiction stories

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 73. Help Panel (Example 2 of 4)

After scrolling down, the following panel appears:

HELPSCR ShelfBrowse for Kids

More: - +
o Science Fiction stories

Nonfiction Nonfiction books are about

things that really exist. For
example:

o History books

o Reference books

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 74. Help Panel (Example 3 of 4)

After scrolling down, the following panel appears:

146 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Note that because there is only one additional line to display, the scroll has moved
the scrollable text up only one line.

HELPSCR ShelfBrowse for Kids

More: -
Nonfiction Nonfiction books are about
things that really exist. For
example:

o History books

o Reference books

o How-to books

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 75. Help Panel (Example 4 of 4)

If no AREA tag is present or the AREA tag does not contain the DEPTH attribute,
multiple help panels are generated. ISPF simulates scrolling by displaying the set
of multiple help panels in sequence.

If the help panel contains additional text, the conversion utility provides an
indicator at the top of the panel to notify the user. If additional text exists, the text
More: is displayed followed by a + sign. Following scrolling, if additional text stills
exists, the indicator displays as “More: − +”, indicating scrolling is possible in
either direction. If, following scrolling, no more text is available through scrolling
forward, but text is available by scrolling backward, the indicator displays as
“More: −”. Scrolling function keys are defined by tutorial processing.

The following markup uses the previous example without a DEPTH attribute on
the AREA tag to generate multiple help panels. Because all of the data does not fit
in one help panel, the conversion utility created three panels: HELPSB, HELPSBX0,
and HELPSBX1. The panels are displayed individually by tutorial processing.
Figures 76, 77, and 78 show the formatted results with the function key area
displayed in its short form.
<!DOCTYPE DM SYSTEM>

<help name=helpsb width=46 depth=16>ShelfBrowse for Kids

<area>
<info>
<p>ShelfBrowse can help you
find any kind of book you are looking for.
The two main categories for books are:
<dl tsize=12>
<dthd>Book
<ddhd>Description
<dt>Fiction
<dd>Fiction books are stories
that never really happened.
The writer made them up.
For example:
<ul>
<li>Fairy Tales
<li>Mysteries
<li>Science fiction stories
</ul>

Chapter 6. Information Regions and Help Panels 147

 <dt>Nonfiction
<dd>Nonfiction books are about
things that really exist.
For example:
<ul>
<li>History books
<li>Reference books
<li>How-to books
</ul>
</dl>
</info>
</area>
</help>

HELPSB ShelfBrowse for Kids

More: +
ShelfBrowse can help you find any kind of
book you are looking for. The two main
categories for books are:

Book Description

Fiction Fiction books are stories that

never really happened. The
writer made them up. For
example:

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 76. Help Panel (Example 1 of 3)

HELPSBX0 ShelfBrowse for Kids

More: - +
o Fairy Tales

o Mysteries

o Science fiction stories

Nonfiction Nonfiction books are about

things that really exist. For
example:

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 77. Help Panel (Example 2 of 3)

148 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 HELPSBX1 ShelfBrowse for Kids
More: -
o History books

o Reference books

o How-to books

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 78. Help Panel (Example 3 of 3)

As we stated earlier, you can use any of the tags provided for information regions
to define the text of the information regions in your help panels.

Chapter 6. Information Regions and Help Panels 149

150 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Chapter 7. Messages
You use messages to communicate information to users; that is, information that
you, the application developer, believe they need to know. Typically, this would be
information regarding user actions, status, or problems that need correction.
Additionally, ISPF issues messages when needed to inform users of situations that
ISPF handles.

The Dialog Tag Language provides you with the means of defining
application-provided messages. You use ISPF services to handle the display of
messages. When the application calls for a message to be displayed, ISPF places it
either in the message area of the application panel or within a pop-up window,
known as a message pop-up.

Messages are defined according to their purpose and severity. The four types of
messages you can define are:
Information To provide information about a user-requested
action.
Warning To provide information about conditions the user
may need to be aware of.
Action To alert the user to an exception condition that
requires a response from the user to correct the
situation.
Critical To alert the user to an exception condition that
requires a response from the user to correct the
situation. Critical messages are similar to action
messages.

This chapter tells you how to define messages for your applications. For a
complete description of ISPF message processing, refer to ISPF Dialog Developer’s
Guide and Reference.

Defining Messages
The messages you define using DTL are stored within message members. Each
regular message member can contain up to 10 messages. The conversion utility
stores the message members in an ISPF message file for the application. The DTL
tags you use to define messages and message members are:
MSGMBR
Defines a message member. The MSGMBR tag requires an end tag.
MSG Defines a message within a message member. The text of the MSG tag is
the text that appears as the message. Each message can be up to 512 bytes
in length after variable substitution. “Variable Substitution” on page 156
describes variable substitution in messages.

You assign an identifier to each message within a message member. The message
identifier is composed of two required attribute values: the NAME attribute value
of the MSGMBR tag and the SUFFIX attribute value for the MSG tag.

© Copyright IBM Corp. 1989, 2000 151

 The NAME attribute you specify for the MSGMBR tag can consist of 1–5 uppercase
or lowercase alphabetic characters and 2 numeric characters.

The SUFFIX attribute values for each of the MSG tags you code within a MSGMBR
definition must consist of either 1 numeric character (0–9) or a numeric character
(0–9) and an optional suffix character as defined for ISPF messages. Each of the
values must be unique (a message suffix cannot be defined twice in a message
member).
<!doctype DM system>

<msgmbr name=maia00>
<msg suffix=0>You cannot type a number in the Name field.
<msg suffix=1>Please include your first name in the Name field.
<msg suffix=2>Unrecognized character in Name field. Please correct.
<msg suffix=3>Unrecognized character in Address field. Please correct.
<msg suffix=4>You cannot type a number in the City field.
<msg suffix=5>Unrecognized character in City field. Please correct.
<msg suffix=6>You cannot type a number in the State field.
<msg suffix=7>You must type two letters in the State field.
<msg suffix=8>The Zip code exceeds the maximum length.
<msg suffix=9>You cannot type an alphabetic character in the Zip field.
</msgmbr>

The value of the MSG SUFFIX attribute, when added to the MSGMBR NAME
value, forms the message identifier for that message. For example, the message
identifier for the message: “You must type two letters in the State field”. is
maia007. If you specify maia007 as the MSG value on a CHECKL tag, this message
is displayed when ISPF detects the error as a result of input validation.

In addition to SUFFIX, the MSG tag has an optional HELP attribute that allows
you to identify a help panel for the message. For information on defining help
panels, see “Chapter 6. Information Regions and Help Panels” on page 109.

Specifying Message Severity

The severity you assign a message determines if the alarm is sounded when the
message is displayed. You can specify the severity of a message with the
MSGTYPE attribute of the MSG tag. ISPF accepts one of four values for the
MSGTYPE attribute: INFO (the default value), WARNING, ACTION, or
CRITICAL. The value can be supplied as a variable name.
Information Messages
Use the default value INFO when you want to provide the user with
feedback about the state of the application.

<msgmbr name=orda00>
<msg suffix=0>Your order is being processed. Please wait...
</msgmbr>
Warning Messages
Warning messages tell users that a potentially undesirable situation could
occur. Users only need to respond to the message to continue, although
corrective action may be required later. ISPF displays warning messages
with an alarm.

<msgmbr name=orda00>
<msg suffix=0>Your order is being processed. Please wait...

152 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 <msg suffix=1 msgtype=warning>Your request for the engraving
option is not valid.
Please check your request, and correct it if necessary.
</msgmbr>
Action and Critical Messages
Action and critical messages both represent the highest degree of severity.
They tell users about exception conditions that require a response. The user
must respond with a specific action to continue with the application. ISPF
displays these messages with an alarm.
Action messages may appear in a pop-up or in the panel message area.
Critical messages always appear in a pop-up.
<!doctype dm system>

<msgmbr name=orda00>
<msg suffix=0>Your order is being received. Please wait...
<msg suffix=1 msgtype=warning>Your request for
the engraving option is not valid.
Please check your request, and correct it if necessary.
<msg suffix=2 msgtype=action>The data you have
entered is incorrect.
Please reenter the data.
</msgmbr>

Short Messages
| The SMSG attribute enables you to specify a short message. The short message
| does not conform to CUA architecture, but it is supported for ISPF compatibility.

Assigning Messages
Some of the DTL tags have an optional MSG attribute that you use to specify a
message-identifier. The message text associated with the message-identifier
specified is displayed when conditions you define for the tag are not met by the
user.

The following list contains the DTL tags that have MSG attributes associated with
them, and describes the conditions for each.
CHECKL
Use the MSG attribute of the CHECKL tag to specify a message ISPF
displays when the user’s input fails the validation check defined for the
check list.
CHOFLD
Use the MSG attribute of the CHOFLD tag to specify a message ISPF
displays when the user does not provide input for a required field. You
can only assign a message to a data field when the REQUIRED attribute
has a value of YES.
DTAFLD
Use the MSG attribute of the DTAFLD tag to specify a message ISPF
displays when the user does not provide input for a required field. You
can only assign a message to a data field when the REQUIRED attribute
has a value of YES.
LSTCOL
Use the MSG attribute of the LSTCOL tag to specify a message ISPF
displays when the user does not provide input for a required entry. You
can only assign a message to a list column when the REQUIRED attribute
has a value of YES.

Chapter 7. Messages 153

 SELFLD
Use the MSG attribute of the SELFLD tag to specify a message ISPF
displays when the user does not provide input for a required single-choice
selection field. You can only assign a message to a selection field when the
REQUIRED attribute has a value of YES.
Use the SELMSG attribute of the SELFLD tag to specify a message ISPF
displays when the user selects an invalid choice.
Use the SELMSGU attribute of the SELFLD tag to specify a message ISPF
displays when the user selects an unavailable choice.
VARCLASS
Use the MSG attribute of the VARCLASS tag to specify a message ISPF
displays when the user’s input fails the validity check defined by the
VARCLASS TYPE attribute.

Note: The message specified by the MSG attribute of a VARCLASS tag is

also used if enclosed checks (CHECKL tag) or translations (XLATL
tag) do not include the MSG attribute.
XLATL
Use the MSG attribute of the XLATL tag to specify a message that ISPF
displays when the user’s input fails a specified translation.

ISPF displays a default message for most of the situations listed above if you do
not specify the MSG attribute.

To show you how messages are associated with DTL tags, the following example
defines a data field that requires input from the user. It also defines a message
member that contains the warning message ISPF displays if the user does not
provide input for the field. Figure 79 on page 155 shows the displayed panel and
message.

<!doctype dm system>

<varclass name=namecls type='char 30'>

<varlist>
<vardcl name=name varclass=namecls>
</varlist>

<msgmbr name=ordb00>
<msg suffix=0 msgtype=warning>You must type your name in the Name field.
</msgmbr>

<panel name=msgxmp1>Application Panel

<dtafld datavar=name pmtwidth=12 required=yes msg=ordb000>Name
<cmdarea>
</panel>

154 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Application Panel

Name . . . . ______________________________

You must type your name in the Name field.

Command ===> ____________________________________________________________

Figure 79. Data Field and Message

Displaying Messages
You can specify how a message will be displayed, either in the panel message area
or a pop-up, using the LOCATION attribute of the MSG tag.

There are five valid values you can assign to LOCATION: AREA (the default),
MODAL, MODAL(L), MODELESS, and MODELESS(L). AREA specifies that the
message is to appear in the panel message area, unless the text of the message
exceeds the length of the message area. If the text of the message exceeds the
message area length, ISPF displays the message in a pop-up.

If you want a message that requires a response from the user to appear in a
pop-up, specify the MODAL or MODAL(L) value for the LOCATION attribute.
This is useful for presenting warning and action messages that have a good deal of
text.

If you want a message that does not require a response from the user to appear in
a pop-up, specify the MODELESS or MODELESS(L) value for the LOCATION
attribute.

For further discussion of these LOCATION values, see “MSG (Message)” on

page 376.

The following message member markup contains three messages, each of them
with a different LOCATION value. The second and third messages display in
pop-up windows.
<!doctype dm system>
<msgmbr name=orda01>
<msg suffix=0>Your order is being received. Please wait...
<msg suffix=1 msgtype=warning location=modeless>Your request for
the engraving option is not valid.
Please check your request, and correct it if necessary.

Chapter 7. Messages 155

 <msg suffix=2 msgtype=action location=modal>The data you have
entered is incorrect.
Please reenter the data.
</msgmbr>

Variable Substitution
You can specify a variable in the text of a message by using the VARSUB (variable
substitution) tag. When the message is displayed, ISPF inserts the current value of
the variable into the text of the displayed message.

You code the VARSUB tag within the text of the message where you want the
substitution to be made. You use the required VAR attribute of the VARSUB tag to
specify the name of a declared variable whose value is substituted in the message
text.

In the following example, we used two variable substitutions in the text of the
message “msga001”. The first VARSUB specifies the variable invvar, which
provides an invoice number in the message. The second VARSUB specifies the
variable datevar, which provides a date in the message.

<!doctype dm system>

<varclass name=invoices type='char 10'>

<varclass name=updates type='char 8'>

<varlist>
<vardcl name=invvar varclass=invoices>
<vardcl name=datevar varclass=updates>
</varlist>

<msgmbr name=msga00>
<msg suffix=0>Your request is being processed.
<msg suffix=1>The invoice number you have requested,
<varsub var=invvar>, was last updated on
<varsub var=datevar>.
</msgmbr>

156 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Chapter 8. The Application Command Table
In addition to the commands in the ISPF system command table, DTL provides
you with a way to define and store commands that are specific to your application.
You can also define commands that override the ISPF system commands. You
define and store these commands within a command table for your application.
These application-specific commands define the responses to commands entered by
the user in the command entry field and commands linked to pull-down choices
and key mapping lists.

You can define only one command table for an application. ISPF locates the
command table using the defined application-identifier for the command table.

For a complete description of ISPF command processing and a list of the ISPF
system commands, refer to the ISPF User’s Guide

Defining the Application Command Table

The tags you use to define an application command table are:
CMDTBL Begins the definition of an application command table. The
required end tag ends the definition.
CMD Defines a command within an application command table. You
code the CMD tags within a CMDTBL definition (between the start
and end tags).
CMDACT Defines the action taken by ISPF when a user enters a command.
You code the CMDACT tag following the command (CMD) with
which it is associated.

The CMDTBL tag has a required APPLID attribute that you use to define the
application identifier for the command table. ISPF uses the value you assign with the
APPLID attribute to identify the command table. The value you assign to APPLID
must be the same as the run-time application identifier specified when the
application starts.

The value you assign as an application identifier can have a maximum of 4

characters, and the first character must be A-Z, a-z, @, #, or $.

Any remaining characters can be either A-Z, a-z, @, #, $ or 0-9. Lowercase

characters are translated to their uppercase equivalents. Additionally, ISPF reserves
the application identifier ISPx, where x is any character including the space
character. Do not use any of these for an APPLID value.

The conversion utility uses the application identifier as a prefix to the string CMDS
to form the name of the command table library. For example, the APPLID value,
demo, results in the application command table name DEMOCMDS.

Command tables are updated using ISPF table services. Input is obtained from the
ISPTLIB DDname allocation and output is written to the ISPTABL DDname
allocation. Refer to the description of how to allocate libraries before starting ISPF
in the ISPF User’s Guide for more information about the use of ISPTLIB and
ISPTABL.

© Copyright IBM Corp. 1989, 2000 157

 When a user enters a command in a command-entry field or through a pull-down
choice or function key, ISPF searches the command tables defined for the user. Any
or all of the following tables will be searched (in the order shown below) if the
table is present and defined. (A user and site command table can be defined in the
ISPF Configuration table and the search order of the site and system command
table can be reversed if specified as such in the ISPF Configuration table.)
1. Application command table
2. User command table
3. Site command table
4. System command table

If the command is found in a command table, ISPF performs the action defined in
that command table for that command. If the command is not found in any of the
command tables, ISPF passes the command to the application program for
processing. If any of the command tables are not present, ISPF skips to the next
command table in the hierarchy.

Use the CMD tag to define each of the commands within the application command
table. The CMD tag has a required NAME attribute that you use to identify the
internal-command-name for the command. The value you assign as an
internal-command-name must not exceed 8 characters, and the first character must be
alphabetic. Any remaining characters can be either alphabetic or numeric.

The following markup example shows a source file that contains an application
command table, a key mapping list, and a panel with an action bar. The command
table contains commands that are mapped to the RUN attributes of the ACTION
tags associated with the pull-down choices and to the CMD attributes of the KEYI
tags.

<!doctype dm system>

<cmdtbl applid=brws>
<cmd name=quit>quit
<cmdact action=...>
<cmd name=send>send
<cmdact action=...>
</cmdtbl>

<keyl name=panlkeys>
<keyi key=f4 cmd=quit>
<keyi key=f6 cmd=send>
</keyl>

<panel...>
<ab>
<abc>Actions
<pdc>Quit
<action run=quit>
<pdc>Send
<action run=send>
<pdc>Exit
<action run=exit>
. </ab>
.
.
</panel>

Because ISPF provides the EXIT command, it is not defined within the application
command table. When the EXIT command is entered, ISPF finds it in the system
command table.

158 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Specifying Command Actions
You must specify a CMDACT tag for each of the CMD tags you define within an
application command table so that ISPF can process these commands. You use the
CMDACT tag to define the action taken for the command. Code the CMDACT tag
immediately after the CMD tag it is associated with.

The ACTION Attribute

The CMDACT tag has a required attribute, ACTION, which you use to specify the
ISPF command action. You can assign one of the ISPF command actions in the
following list and some of the ISPF-provided system commands as listed in
“CMDACT (Command Action)” on page 261. You can also specify command
actions dynamically at run time as discussed in “Specifying Command Actions
Dynamically” on page 160.
ALIAS To allow a command to have an alternate name, such as using
QUIT as an alias for EXIT.
PASSTHRU To pass the command to the application. The internal-command-
name and any command parameters are passed to the dialog in the
ISPF ZCMD system variable.
SETVERB To pass the command to the application. The internal-command-
name is passed to the dialog in the ZVERB system variable, and the
parameters (if any) are passed to the dialog in the ZCMD system
variable.

The ALIAS command action provides you with a way to define synonyms for
commands. The internal-command-name you define for the ALIAS attribute value
defines the command to be processed. You must enclose the keyword ALIAS, the
internal-command-name, and any optional parameters within quotes.

When you define an ALIAS command action, you must code that command’s
CMD and CMDACT tags before the command the ALIAS represents. ISPF searches
the application-defined commands first, and then searches the ISPF system
commands. It must locate the ALIAS definition before the aliased command.

In the following example, we’ve added the commands PREV and NEXT to the
application command table. We want “PREV” and “NEXT” to be aliases for the
ISPF system commands BACKWARD and FORWARD. Because the BACKWARD
and FORWARD commands are provided by ISPF, we do not need to define them
in the application command table. ISPF locates the aliases before the ISPF system
commands they refer to.

Additionally, this example shows the CMDACT for the SEND command set to
PASSTHRU, because we want the application program to process the SEND
command.

<cmdtbl applid=brws>
<cmd name=quit>quit
<cmdact action='alias exit'>
<cmd name=send>send
<cmdact action=passthru>
<cmd name=prev>
<cmdact action='alias backward'>
<cmd name=next>
<cmdact action='alias forward'>
</cmdtbl>

Chapter 8. The Application Command Table 159

 Specifying Command Actions Dynamically
You can also specify a variable as the value for the ACTION attribute of the
CMDACT tag. ISPF substitutes the value of the variable at run time when the
command is processed. The run-time value of the variable must be one of the
ISPF-supported command actions. You specify the variable using the % notation in
the ACTION value.

In the following example, we specified the variable scroll as a command action for
the SCROLL command. When the user issues the SCROLL command, ISPF obtains
the value of the variable scroll from the variable pool to determine the action to be
taken. The application can then control the direction of scrolling by setting the
variable scroll to FORWARD or BACKWARD, or to NOP if no scrolling is possible.

<!doctype dm system>

<cmdtbl applid=abcd>
<cmd name=scroll>scroll
. <cmdact action='%scroll'>
.
.
</cmdtbl>

Truncating Commands
Using the command facilities as we have discussed them so far in this chapter, the
user must enter a full command name when typing a command in the command
area. You can provide a shortcut for the user by defining command truncations for
commands. The user can issue a truncated command in the command area by
entering the minimum number of characters you specify for the command.

To specify truncation for a command, you code the T (truncation) tag within the
external-command-name of the command.

For example, to specify “qu” as the minimum command for the QUIT command,
you add the T tag to the external-command-name, like this:

<cmdtbl applid=brws>
<cmd name=quit>qu<t>it
. <cmdact action='alias exit'>
.
.
</cmdtbl>

The T tag follows the characters you specify as the minimum command.

With this truncation, the user can issue the QUIT command by typing the
command in one of the following ways:
qu
qui
quit

However, you should be careful to avoid adding truncations that duplicate other
truncations in the command table. For example, these two truncations define
minimum commands (“co”) that are identical:

<cmdtbl applid=brws>
<cmd name=comp>co<t>mpare
<cmdact action=passthru>
<cmd name=copy>co<t>py
<cmdact action=passthru>
</cmdtbl>

160 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
The preceding definition would cause the conversion utility to issue a warning
message.

To avoid this type of duplication, place the T tag appropriately in the CMD tag
content. The above duplication can be avoided by coding the truncations as
follows:

<cmdtbl applid=brws>
<cmd name=comp>com<t>pare
<cmdact action=passthru>
<cmd name=copy>cop<t>y
<cmdact action=passthru>
</cmdtbl>

Chapter 8. The Application Command Table 161

162 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Chapter 9. Defining Key Mapping Lists
Every application panel has keys that map to valid actions for the panel. You
define these key assignments within key mapping lists. The key assignments map
a key to a command defined within the application command table or to an
ISPF-provided command. You use the KEYLIST attribute of the HELP, HELPDEF,
PANEL or PANDEF tags to name the key mapping list to use for a panel. If a
keylist is not specified, ISPF provides the default key mapping list used for help
panels. ISPF also provides a default key mapping list used when application
panels do not refer to an application-defined KEYLIST.

The tags you use to define key mapping lists are:

KEYL To define a key mapping list. The required end tag ends the key mapping
list definition.
KEYI To define a key assignment and specify the command ISPF processes when
the user presses the key, and specify the label for the key if it is displayed
in the function key area.
You can code multiple KEYI (key item) tags within a KEYL (key list)
definition. You code a KEYI tag for each key that is defined for the key
mapping list.

Keylists are updated using ISPF table services. Input is obtained from the ISPTLIB
DDname allocation and output is written to the ISPTABL DDname allocation. Refer
to the description of how to allocate libraries before starting ISPF in the ISPF User’s
Guide for more information about the use of ISPTLIB and ISPTABL.

Assigning Keys and Actions

The KEYL tag starts a key mapping list definition and provides the name of the
key mapping list. You specify the key mapping list to be used with the KEYLIST
attribute of the HELP, HELPDEF, PANEL, or PANDEF tag.

Each KEYI definition within a key mapping list maps a key assignment with a
command. The command can be defined in the application command table, the
user command table, the site command table, the system command table, or it can
be one of the ISPF-provided commands. The required KEY and CMD attributes of
the KEYI tag match the key with the command.

The KEYI definition in this example maps the F2 key on the user’s keyboard with
the SEARCH command in the application command table.

<!doctype dm system>

<cmdtbl applid=abcd>
<cmd name=search>Search
<cmdact action=passthru>
</cmdtbl>

<keyl name=panlkeys>
<keyi key=f2 cmd=search>Search
</keyl>

<panel name=panl01 keylist=panlkeys>

© Copyright IBM Corp. 1989, 2000 163

 .
.
.
</panel>

When the user presses the F2 key during the display of an application panel that
refers to this key mapping list, ISPF processes the SEARCH command.

ISPF Default Key List

ISPF provides a default key mapping list named ISPKYLST for application panels.
If you do not specify a key mapping list to be associated with a panel (using the
KEYLIST attribute of the PANEL or PANDEF tag), ISPF uses the keys defined for
ISPKYLST to display in the function key area of the panel when it is displayed. See
“PANEL (Panel)” on page 397 for information about coding the PANEL tag.

The key mappings for ISPKYLST are:

Key Command
F1 HELP
F2 SPLIT
F3 EXIT
F9 SWAP
F12 CANCEL
F13 HELP
F14 SPLIT
F15 EXIT
F21 SWAP
F24 CANCEL

ISPF provides a default key mapping list named ISPHELP for help panels. If you
do not specify a key mapping list to be associated with a panel (using the
KEYLIST attribute of the HELP or HELPDEF tag), ISPF uses the keys defined for
ISPHELP to display in the function key area of the panel when it is displayed. See
“HELP (Help Panel)” on page 323 for information about coding the HELP tag and
Table 4 on page 328 for key mappings of the ISPHELP keylist.

You can override the ISPF default key mapping list by specifying a KEYLIST
attribute in the panel definition. All keys that you want to be active, including
those for ISPF-provided commands, must be specified in the key mapping list
referred to by the KEYLIST attribute.

Displaying Keys
While all of the key assignments you define in a key mapping list are valid for the
application panels that refer to the list, they only appear in the function key area
(FKA) of the panel under the following conditions:
v You specify that the key is to be displayed by including FKA=YES in the KEYI
tag, and
v The user has not turned off display of the function key area.

You use the FKA attribute of the KEYI tag to specify whether the key is to appear
in the panel’s function key area. The default FKA value, NO, means that the key
will not appear. You must specify FKA=YES for the key to be displayed in the
function key area.

When function keys are displayed in the function key area, the key you assign is
displayed followed by an equal sign and the FKA text defined for the KEYI tag.

164 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Defining Help for Key List
The conversion utility supports a keys help panel name on the KEYL tag. This
allows a keys help panel to be associated with the key list. You can use the
KEYLIST utility to add, change, or delete a keylist help panel name.

Alternatively, the application can provide the help panel name in the ZKEYHELP
variable. However, the panel name specified as the keylist help panel either on the
KEYL tag or by the KEYLIST utility overrides the panel name supplied by the
ZKEYHELP variable.

In the following example, we want only the F2, F3, and F6 keys to appear in the
panel function key area, with F2 mapped to the SEARCH command defined in the
application command table, F3 mapped to the EXIT command, and F6 mapped to
the KEYSHELP command. We also want F1 to be active to support the ISPF HELP
command. No other function keys are to be active for this key mapping list. To
obtain this result, we define the function key mapping list as follows:

<!doctype dm system>

<cmdtbl applid=abcd>
<cmd name=search>Search
<cmdact action=passthru>
</cmdtbl>
<keyl name=panlkeys help=pnlkeyh>
<keyi key=f1 cmd=help>
<keyi key=f2 cmd=search fka=yes>Search
<keyi key=f3 cmd=exit fka=yes>Exit
<keyi key=f6 cmd=keyshelp fka=yes>Keyshelp
</keyl>

<panel
. name=panl01 keylist=panlkeys>
.
.
</panel>

Here’s how the function key area appears when panel “panl01” is displayed:

F2=Search F3=Exit F6=Keyshelp

Figure 80. Displayed Function Key Area

Chapter 9. Defining Key Mapping Lists 165

166 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Chapter 10. Using the Conversion Utility
The ISPF conversion utility is a tool that converts Dialog Tag Language (DTL)
source files into ISPF panel language source format or executable preprocessed
ISPF format. There are two methods of invoking the conversion utility–using the
ISPF-supplied invocation panels, or using the conversion utility syntax. In either
case, the conversion utility must be run under ISPF control. In this chapter, we
explain both methods of calling the conversion utility.

Using the ISPF-Supplied Invocation Panels

Type the following command on the command line to invoke the conversion utility
and display the ISPF invocation panel:
ISPDTLC

Invocation Panel
The following panel appears:

Figure 81. Conversion Utility Invocation Panel (ISPCP01)

When you scroll forward once, the following panel view appears.

© Copyright IBM Corp. 1989, 2000 167

 Figure 82. Conversion Utility Invocation Panel (Middle)

When you scroll forward a second time, the following panel view appears.

Figure 83. Conversion Utility Invocation Panel

When you scroll forward again, the following panel view appears.

168 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Figure 84. Conversion Utility Invocation Panel

Finally, when you scroll forward again, the following panel view appears.

Figure 85. Conversion Utility Invocation Panel (End)

You must specify:

v At least one file containing DTL source
v The panel output file
v The message output file

The language selection defaults to the current ISPF session language. The current
selected language is displayed as an information field on the panel.

Chapter 10. Using the Conversion Utility 169

 Select the national language you want by using the “Language” action bar
pull-down to enter a number corresponding to the supported ISPF language. The
language is used to provide formatting rules for tag text. See “Text Formatting” on
page 13 for more information.

Panel Input Fields

Additional information about the panel input fields follows:
Member Name
If the member name is left blank or entered as a member pattern, a member
list is displayed. You can select one or more members to be converted from the
member list.
DTL Source data set - n
You can specify up to three additional DTL source libraries on the invocation
panel. See “Additional DTL Source Files” on page 173 for more information.
Panel data set
If no panel output is required, you can specify NULLFILE or DUMMY in place
of the panel output file name.
Message data set
if no message output is required, you can specify NULLFILE or DUMMY in
place of the message output file name.
Log data set
The log file name is optional. If it is not specified and the messages are to be
written to disk, log output is written to the ISPF log file. If the log file is a
PDS, a member name must be provided. You may specify an asterisk to tell the
conversion utility to use the input GML source file member name as the
output log file member name. However, if the input GML member is in the
special DTLLST file list format (discussed in “Conversion Utility General
Information” on page 181) then a separate log file member is created for each
source member converted.
List data set
The list file name is optional. If it is not specified, list output is written to the
ISPF list file. If the list file is a PDS, a member name must be provided. You
may specify an asterisk to tell the conversion utility to use the input DTL
source file member name as the output list file member name. However, if the
input GML member is in the special DTLLST file list format (discussed in
“Conversion Utility General Information” on page 181) then a separate list file
member is created for each source member converted.
SCRIPT data set
The SCRIPT file name is optional. If a SCRIPT output file is requested, it must
be a PDS file. Member names for the SCRIPT file are the same as the panel file.
Tables data set
The Tables file name is optional. If a tables file name is provided, it must be an
80 byte fixed length PDS file. When a tables file is provided, keylist and
command table output is placed in this file.
| Keylist Application ID
| The optional Keylist Application ID is used when the APPLID attribute is
| omitted on the HELP, PANEL, KEYL, or CMDTBL tags. This is the equivalent
| of the ID provided by the KEYAPPL option described in “Conversion Utility
| Syntax” on page 175.

170 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Conversion status message interval
When the conversion utility is running in interactive mode and the “Place
ISPDTLC Messages in log file” option is selected and the “List Source Convert
Messages” option is deselected, a status message containing the name of the
current DTL source file member being converted is displayed in the long
message area. This message provides a conversion status when you are
converting multiple members using the DTLLST format member option. See
page 184 for more information about the DTLLST syntax. The default message
interval value is 1 which displays the message for each member processed.
This value can be set to 0 to suppress the message (which is useful when
running in GUI mode) or to a value that refreshes the message after a specified
number of members have been converted.
| DISPLAY(W) option check interval

| When the conversion utility is running in test mode and either the DISPLAY or
| DISPLAYW option is selected, the converted panel is displayed for visual
| verification. A panel is displayed periodically after the converted panel has
| been displayed to enable the user to control the DISPLAY or DISPLAYW
| function.

| The DISPLAY(W) option check interval option on the invocation panel controls
| the frequency of the DISPLAY or DISPLAYW control function panel
| appearance. The default value is 1, so that the control function panel is
| displayed after each converted panel display. The control panel enables you to
| continue using the same display interval, cancel the DISPLAY or DISPLAYW
| option, or change the control panel display interval.

All files specified must be pre-allocated.

When the log or list file is a PDS file and the member name is not an asterisk, all
of the conversion results are placed in the specified member. If the file name or
member name is changed, the pending log or list information is written to the
previously specified member and a new log or list is generated beginning with the
next conversion. When the conversion utility ends, pending log and list files are
written.

The log and list files can be either fixed or variable length, with or without printer
control. When the file is allocated with print control specified, the conversion
utility output begins in column 2; column 1 is blank. When print control is not
specified, the conversion utility output begins in column 1.

Panel Options
The conversion utility options are displayed either as a multi-choice selection list
by scrolling the invocation panel, or in a series of multi-choice selection list panels
with related options, through the Options pull-down on the action bar.

You select the options by entering a “/” in front of the option description. If you
want to deselect an option, you must leave the selection choice field blank. These
options are initially set to the default values described in “Conversion Utility
Syntax” on page 175. The options and their valid values are equivalent to
conversion utility syntax in the following manner. Note that b represents a blank.

Options Valid Values

Replace Panel/Message/SCRIPT/Keylist/ / is equivalent to REPLACE, the default.
Command Members b is equivalent to NOREPLACE.

Chapter 10. Using the Conversion Utility 171

 Options Valid Values
Preprocess Panel Output / is equivalent to PREP, the default.
b is equivalent to NOPREP.
Place ISPDTLC Messages in log file b is equivalent to SCREEN, the default.
/ is equivalent to DISK.
Suppress Messages (ISPF extensions) b is the equivalent to NOMSGSUPP, the
default.
/ is equivalent to MSGSUPP.
Suppress Messages (CUA exceptions) b is equivalent to NOCUASUPP, the
default,
/ is equivalent to CUASUPP.
Use CUA Panel Attributes / is equivalent to CUAATTR, the default.
b is equivalent to NOCUAATTR.
Generate Statistics on Panel/Message/ / is equivalent to STATS, the default.
Script Members b is equivalent to NOSTATS.
Generate List file b is equivalent to NOLISTING, the default.
/ is equivalent to LISTING.
Generate List file with substitution b is equivalent to NOFORMAT, the default.
/ is equivalent to FORMAT.
Generate SCRIPT file b is equivalent to NOSCRIPT, the default.
/ is equivalent to SCRIPT.
Replace Log File Members / is equivalent to LOGREPL, the default.
b is equivalent to NOLOGREPL.
Replace List File Members / is equivalent to LISTREPL, the default.
b is equivalent to NOLISTREPL.
List Source Convert Msgs b is equivalent to NOLSTVIEW, the
default.
/ is equivalent to LSTVIEW.
Use Expanded Message Format b is equivalent to NOMSGEXPAND, the
default.
/ is equivalent to MSGEXPAND.
Allow DBCS b is equivalent to NODBCS, the default.
/ is equivalent to DBCS.
Specify KANA / is equivalent to KANA.
Specify NOKANA / is equivalent to NOKANA.
Create panels with Action bars / is equivalent to ACTBAR, the default.
b is equivalent to NOACTBAR
Create panels with GUI mode display / is equivalent to GUI, the default.
controls b is equivalent to NOGUI
Add ISPDTLC version / timestamp to panel/ is equivalent to VERSION, the default.
b is equivalent to NOVERSION
Combine scrollable areas into panel body b is equivalent to NOMERGESAREA, the
default.
/ is equivalent to MERGESAREA.
Display converted panels (*) b is equivalent to NODISPLAY, the
default.
/ is equivalent to DISPLAY.
Display converted panels in a window (*) b is equivalent to NODISPLAYW, the
default.
/ is equivalent to DISPLAYW.

172 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Options Valid Values
Bypass data set name validation b is equivalent to DSNCHK, the default.
(after first cycle). / is equivalent to NODSNCHK.
Enable graphic character display / is equivalent to GRAPHIC, the default.
b is equivalent to NOGRAPHIC.
Use full names in place of Z variables b is equivalent to ZVARS, the default.
/ is equivalent to NOZVARS.
Align DBCS prompt text with entry field b is equivalent to NODBALIGN, the default.
/ is equivalent to DBALIGN.
| Preserve leading blanks when space is b is equivalent to NOPLEB, the default.
| not specified / is equivalent to PLEB.
| Process multiple line comment blocks b is equivalent to NOMCOMMENT,
| the default.
| / is equivalent to MCOMMENT.
| Display additional DTL source data set list b —second input panel is not displayed.
| / —second input panel is displayed.
| (*): If you specify DISPLAY or DISPLAYW, ISPDTLC must be run in test mode (Option 7)
| to force display processing to use the current generated panel. An error message is issued
| if ISPDTLC is not being run in test mode and either option is specified.

All of the entries from the panel (or panels) are saved in the user’s profile.

Additional DTL Source Files

A second input panel is displayed for entry of up to twelve additional DTL source
file data set names when any of the following occurs:
| v you place the cursor on the point-and-shoot panel phrase DTL input files 5-16
| and press Enter.
v the Display additional DTL source data set list option is selected from either
the scrollable area of the main panel or the Miscellaneous section of the Options
action bar pull-down
v XDTL is entered on the command line
v Option 7 is selected from the Commands action bar pull-down

Chapter 10. Using the Conversion Utility 173

 Figure 86. Panel ISPCP04

| The entries for DTL source data sets 2-16 can be reset from the first invocation
| panel by placing the cursor on the point-and-shoot field Click here to reset DTL
| input files 2-16 and pressing Enter. The panel redisplays with all entries except
| DTL Source data set-1 reset to blanks.

| Similarly, DTL source data sets 5-16 can be reset from the additional source files
| panel by placing the cursor on the point-and-shoot field Click here to reset DTL
| input files 5-16 and pressing Enter. The invocation panel redisplays with all entries
| on the additional source files panel reset to blanks.

Converting Multiple DTL Source Files

When ISPF finishes processing the DTL source you specify, the conversion utility
displays the invocation panel again to convert another DTL source file. This cycle
continues until you exit or cancel the conversion utility.

Calling Help
You can get help for any field on the conversion utility invocation panel by
moving the cursor to the field and pressing the F1 key.

Using CUA Panel Attributes

CUA defines the default colors and emphasis techniques for individual panel
elements. The conversion utility generates panel element attributes that ISPF
defines. The NOCUAATTR option can be used to create panels with attributes
compatible with ISPF Version 3.1 and Version 3.2.

Refer to the ISPF User’s Guide for more information about panel attributes.

174 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Conversion Utility Syntax
You can also invoke the conversion utility using the syntax discussed in this
section. This feature provides compatibility with previous ISPDTLC releases and
allows you to issue multiple calls from a user-specified EXEC file. To read the
conversion utility syntax, see “Chapter 11. How to Read the Syntax Diagrams” on
page 191 for more information.

You can view the allowable syntax and a description of the options by entering the
following command on the ISPF command line:
ISPDTLC ?

This command causes the general help panel to be displayed. The first line of
information contains the ISPDTLC version, APAR, and PTF numbers.

This diagram shows the conversion utility syntax:

REPLACE SCREEN NODBCS

ÊÊ ISPDTLC source-filespec( Ê
NOREPLACE DISK DBCS

NOPANEL NOMSGSUPP NOCUASUPP

Ê Ê
NOKANA KEYLAPPL=xxxx PANEL MSGSUPP CUASUPP
KANA

PREP CUAATTR NOLSTVIEW STATS NOSCRIPT

Ê Ê
NOPREP NOCUAATTR LSTVIEW NOSTATS SCRIPT

NOLISTING NOMSGEXPAND LOGREPL LISTREPL

Ê Ê
NOFORMAT MSGEXPAND NOLOGREPL NOLISTREPL
LISTING
FORMAT

ACTBAR GUI VERSION NOMERGESAREA NODISPLAY

Ê Ê
NOACTBAR NOGUI NOVERSION MERGESAREA DISPLAY

NODISPLAYW DSNCHK GRAPHIC ZVARS NODBALIGN

Ê Ê
DISPLAYW NODSNCHK NOGRAPHIC NOZVARS DBALIGN

NOPLEB NOMCOMMENT
Ê Ê
PLEB MCOMMENT PROFILE=data-set-name
PROFDDN=ddname|*

Chapter 10. Using the Conversion Utility 175

 Ê ÊÍ
national-language

As denoted in the preceding diagram, when you specify options, a left parenthesis
“(” is required before the first option. If you specify mutually exclusive options
such as SCREEN and DISK, the conversion utility issues an error message and
stops processing.

The syntax description follows:

source-filespec
Specify the source-filespec as a member of a partitioned data set (PDS) that
contains the DTL source to be converted to ISPF dialog elements. The first-level
qualifier is the “user ID” and the second-level qualifier is “GML” for the input
data set name unless the PROFILE option is specified to override the default.

Note: The conversion utility output is stored as commands, keylists, messages

and panels. A single source file might result in any or all of these
objects. The source file might contain multiple command tables, keylists,
message members or panels. The names for the output objects are
provided by the CMDTBL, KEYL, MSGMBR, PANEL, and HELP tags.
See the descriptions of these tags for additional information.
REPLACE | NOREPLACE
Indicates whether members generated by the conversion utility will replace
existing members of the same name. If you specify NOREPLACE, the
conversion utility issues a warning message for each existing member with the
same name, but does not overwrite the existing member. If you specify
REPLACE, the conversion utility overwrites any existing member with the
same name. REPLACE and NOREPLACE affect keylists, commands, messages,
panels, and SCRIPT files.
SCREEN | DISK
Indicates where to send information, warning, and error messages that occur
while running the conversion utility. If you specify SCREEN (the default),
conversion messages are sent to the display screen. If you specify DISK,
conversion messages are sent to the designated log file.

Note: If your messages are not being written to the ISPF log, the specified
conversion utility log file must be pre-allocated. If your messages are
being written to the ISPF log, the ISPF Settings option must specify that
an ISPF log is to be created.

| Running the conversion utility with the DISK option causes additional
| messages to be appended to the existing sequential ISPDTLC log file or the
| ISPF log. When using the conversion utility log file, a separator record
| indicating the date and time of the execution is written to the log file before
| any messages.

Messages are written to the screen automatically when:

v The conversion utility detects errors during initialization.
v System I/O errors occur.
DBCS | NODBCS
Indicates whether or not DBCS validation is performed on tag text following
the tag suffix “>”. Errors found during DBCS validation cause the conversion

176 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 utility to issue error or warning messages. DBCS shift-out and shift-in
characters are considered part of the text, thereby contributing to the length of
the text.

Attention: DBCS strings cannot span records. That is, DBCS shift-out and
shift-in characters (shift-in characters end the DBCS string) must be on the
same record. The conversion utility ends with a severe error for incorrectly
formed DBCS strings. If DBCS is specified and no language is specified, the
default language is Japanese.
KANA | NOKANA
Indicates whether the KANA keyword will be added to the )BODY statement
on panels and the message ID line of messages. There is no default. If KANA
is specified and no language is specified, the default language is Japanese.
Refer to the ISPF User’s Guide for more information.
KEYLAPPL=xxxx
| The KEYLAPPL=xxxx option, where “xxxx” is equal to the 1–4 character
| application ID, must be specified when the user includes a key list or lists in
| the DTL source and the APPLID attribute is omitted on the KEYL tag. The
| application ID is used by the conversion utility to write to the correct key list
| file.

| Note: You cannot use “ISP” as an application ID, because the conversion
| utility is running as an ISP application.
| Refer to ISPF User’s Guide for restrictions on updating key lists.
PANEL | NOPANEL
The PANEL keyword forces the conversion utility to display the invocation
panel even if a source-filespec has been entered. The PANEL keyword is
disregarded when the conversion utility is running in a batch job.
| MSGSUPP | NOMSGSUPP
| The MSGSUPP keyword causes the conversion utility to suppress warning
| messages concerning panel formatting.
CUASUPP | NOCUASUPP
The CUASUPP keyword causes the conversion utility to suppress warning
messages concerning CUA Architecture non-compliance.
PREP | NOPREP
The NOPREP keyword causes the preprocessing of the output panel to be
bypassed. Panel output is stored in ISPF panel format.
CUAATTR | NOCUAATTR
The NOCUAATTR keyword forces the conversion utility to create panels with
attribute definitions compatible with ISPF Version 3.1 and Version 3.2.
CUAATTR causes panels to be created using CUA attribute types as defined in
the ISPF Dialog Developer’s Guide and Reference

Note: If you specify NOCUAATTR, the conversion utility will issue a message
and change the default GRAPHIC option to NOGRAPHIC because
GRAPHIC support is implemented only for CUA attributes.
LSTVIEW | NOLSTVIEW
The LSTVIEW keyword causes the conversion utility to display the “converting
source file” message in line mode when the user has routed the log file
messages to DISK. NOLSTVIEW causes the “converting source file” message to
be displayed as a long message in full screen mode. The NOLSTVIEW

Chapter 10. Using the Conversion Utility 177

 keyword is disregarded when the conversion utility is running in a batch job;
the “converting source file” message is written to file SYSTSPRT.
STATS | NOSTATS
The NOSTATS keyword causes the conversion utility to bypass the creation of
member statistics on created panels and messages. STATS and NOSTATS affect
messages, panels, and SCRIPT files.
SCRIPT | NOSCRIPT
The SCRIPT keyword causes the conversion utility to create a panel image
template as a member of a file allocated to DTLSCR. The panel image template
has BookMaster tags included so that it may be incorporated into
documentation files. Input and output fields in the panel image are shown as
underscores. Run-time substitution variables are shown as “&varname”.
Editing will be required to supply appropriate information for input and
output fields and “&varname” values.

Note: The specified conversion utility SCRIPT output file must be preallocated.
LISTING | NOLISTING
The LISTING keyword causes the conversion utility to create a list file of the
processed source GML records. This file is allocated to DTLLIST or if no file
name is provided to the conversion utility, the list is added to the standard
ISPF list data set. The file you provide can be in either sequential or
partitioned format.

Note: If your messages are not being written to the ISPF list file, the specified
conversion utility list file must be preallocated.

Indentation of nested tags (to a limit of 30 columns) is provided for readability.

The listing is limited to an 80-column format. Tag contents that would extend
beyond the right column are flowed to multiple lines.

The formatted listing is unchanged from the original DTL source file except for
indentation processing.
FORMAT | NOFORMAT
The FORMAT keyword causes the conversion utility to create a list file of the
source GML records after entity substitution is performed. (The FORMAT
keyword implies the LISTING keyword.) The number at the left side of the list
indicates the file nest level. If the LISTING keyword is specified in
combination with the NOFORMAT keyword, all substitution is bypassed and
the listing can be used as a formatted input GML file.
MSGEXPAND | NOMSGEXPAND
The MSGEXPAND keyword causes the conversion utility to expand the
warning and error messages to include an indicator of the major type of tag in
process (PANEL, HELP, KEYL, MSGMBR, CMDTBL) along with the object
name.
LOGREPL | NOLOGREPL
Indicates whether members generated by the conversion utility will replace
existing log file PDS members of the same name. If you specify NOLOGREPL,
the conversion utility issues a warning message for each existing member with
the same name but will not overwrite the existing member.
LISTREPL | NOLISTREPL
Indicates whether members generated by the conversion utility will replace
existing list file PDS members of the same name. If you specify NOLISTREPL,

178 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 the conversion utility issues a warning message for each existing member with
the same name but will not overwrite the existing member.
ACTBAR | NOACTBAR
Indicates whether the ISPF panel statements for action bars will be added to
the generated panel. If you specify NOACTBAR, the panel sections for )ABC,
)ABCINIT, and )ABCPROC and the action bar lines from the panel body are
not added to the output panel. (The DTL source for action bar creation is
syntax-checked in all cases.)

If a PANEL tag includes the keyword ACTBAR, this option is ignored for that
panel.
GUI | NOGUI
The NOGUI keyword causes the GUI display mode panel keywords for
mnemonics and check boxes to be removed from the generated panel.

If you specify MNEMGEN=YES on the AB tag or CHKBOX=YES on the

SELFLD tag, this option is ignored for the specified tag. This option can be
overridden by specifying the TYPE attribute on the PANEL tag.
VERSION | NOVERSION
| Indicates whether the ISPDTLC version number, maintenance level, and
| member creation date and time are added as comments following the )END
| panel statement and the last message of a message member. In addition,
| VERSION causes the conversion language (ENGLISH, GERMAN, JAPANESE,
| and so on), Panel ID, and ISPF version to be added to the )ATTR panel
| statement line as a comment. If you specify NOVERSION, the comments are
| not added to the generated panel or message.

| Note: If the PREP conversion option has been specified, the comments will not
| be part of the final panel because they will not be processed by the
| ISPPREP utility.
| NOMERGESAREA | MERGESAREA
Indicates whether scrollable areas will be merged into panel body sections.
Merge occurs only when the entire scrollable area can be contained within the
panel body, allowing for the function key area. This option can be overridden
by specifying the MERGESAREA attribute on the HELP or PANEL tag.
NODISPLAY | DISPLAY

| Indicates whether the converted panel will be displayed by the conversion

| utility immediately after the panel is created. The display will be in full screen
| format. The DISPLAY keyword is disregarded when the conversion utility is
| running in a batch job.

| Note: If you specify DISPLAY, ISPDTLC must be run in test mode (Option 7)
| to force display processing to use the current generated panel. An error
| message is issued if ISPDTLC is not being run in test mode and this
| option is specified.

| DISPLAY causes each converted panel to be displayed until the user enters
| DISPLAY OFF on the command line of a displayed panel or selects option 2
| from the display control panel. The control panel is displayed periodically,
| according to the interval specified in the DISPLAY(W) option check interval
| field on the invocation panel, or from the Miscellaneous choice on the Options
| action bar choice.

Chapter 10. Using the Conversion Utility 179

 NODISPLAYW | DISPLAYW

| Indicates whether the converted panel will be displayed by the conversion

| utility immediately after the panel is created. The display will be within a
| window. The DISPLAYW keyword is disregarded when the conversion utility
| is running in a batch job.

| Note: If you specify DISPLAYW, ISPDTLC must be run in test mode (Option
| 7) to force display processing to use the current generated panel. An
| error message is issued if ISPDTLC is not being run in test mode and
| this option is specified.

| DISPLAYW causes each converted panel to be displayed until the user enters
| DISPLAY OFF on the command line of a displayed panel or selects option 2
| from the display control panel. The control panel is displayed periodically,
| according to the interval specified in the DISPLAY(W) option check interval
| field on the invocation panel, or from the Miscellaneous choice on the Options
| action bar choice.
DSNCHK | NODSNCHK
Indicates whether file validation will be performed on the files specified on the
interactive panel after the first conversion cycle has been completed. If you
specify NODSNCHK and any specified file is unavailable, the conversion will
fail when the conversion utility attempts to use the file. The NODSNCHK
keyword is disregarded when the conversion utility is running in a batch job.
GRAPHIC | NOGRAPHIC
Indicates, for host display only, whether the action bar separator line and
visible horizontal divider lines will display as dashed lines or as solid lines.
The GRAPHIC option can be overridden by the tag definition that generates
the line. See tag attribute descriptions for
v “AB (Action Bar)” on page 201,
v “AREA (Area)” on page 213,
v “CHDIV (Choice Divider)” on page 232,
v “DA (Dynamic Area)” on page 277,
v “DIVIDER (Area Divider)” on page 285,
v “GA (Graphic Area)” on page 316,
v “GRPHDR (Group Header)” on page 320,
v “LSTFLD (List Field)” on page 364, and
v “LSTGRP (List Group)” on page 368
for information about the creation of action bar separator and various types of
visible divider lines. (In GUI mode, the action bar separator always displays as
a solid line, and divider lines always display as dashed lines.) If you specify
NOGRAPHIC, the action bar separator line and visible divider lines will be
created as dashed lines.

Note: If you specify NOCUAATTR, the conversion utility will issue a message
and change the default GRAPHIC option to NOGRAPHIC because
GRAPHIC support is implemented only for CUA attributes.
ZVARS | NOZVARS
Indicates whether variable names will be formatted as Z variables. If you
specify NOZVARS, the variable name will be used in panel )BODY or )AREA
formatting unless the variable name is longer than the defined field width.
DBALIGN | NODBALIGN
For DBCS language conversions only. Indicates whether fields with

180 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PMTLOC=ABOVE will be aligned so that the first position of the prompt text
is formatted above the first position of the field.
PLEB | NOPLEB
Indicates whether leading blanks in ENTITY text strings are processed. This
option is effective only for ENTITY definitions that do not specify the space
keyword.
MCOMMENT | NOMCOMMENT
Indicates whether multiple line comment blocks, starting with <! −− or <: −−
and ending with the first −−> found are valid. Comment blocks can include
DTL tags.
PROFILE=data-set-name | PROFDDN=ddname | PROFDDN=*
The PROFILE or PROFDDN option provides access to the data set name that
contains the conversion utility defined DD names and associated
PDS/sequential file names to be used by the conversion utility during I/O. A
sample profile member ISPDTLP is shipped in the ISPSLIB skeleton library.

The data-set-name value must be a fully qualified data set name that specifies
either a sequential or a partitioned data set. If the profile entry is part of a
partitioned dataset, then the member name must be included in the
data-set-name specification.

The ddname value specifies a ddname allocated to a profile data set.

The ″*″ value specifies that the ddnames used in the conversion will be found
as pre-allocated files. See page 187 for the ddnames used by ISPDTLC.

The profile data set and all data sets defined within the profile must be
preallocated.
national-language
Specifies the language rules to be used for formatting the tag text. Supported
language keywords are:
CHINESES ENGLISH ITALIAN PORTUGUE UPPERENG
CHINESET FRENCH JAPANESE SGERMAN
DANISH GERMAN KOREAN SPANISH

Note: ISPF must have been installed to support the language requested by the
conversion utility.

Conversion Utility General Information

The output panel library can be defined as either fixed length or variable length. A
fixed length record library must have a record length of 80, 132, or 160 bytes.
Record lengths for variable length record libraries must be increased by 4. Variable
length libraries defined with a record length other than 84, 136, or 164 are treated
as the next smaller standard size. Thus, a variable length file of 255 bytes is treated
as 164, and a variable length file of 100 bytes is treated as 84.

The NOPREP option directs the conversion utility to write the panels being
processed directly to the specified panel output file in the ISPF source format. The
overall width for the created panels is limited by the record length of the
designated file. Thus, if you have specified a panel library with a fixed length of 80
bytes (or a variable length of 84 bytes), the maximum panel width allowed on the
PANEL tag will be 80.

Chapter 10. Using the Conversion Utility 181

 The PREP (default) option causes the creation of a temporary panel library to
receive the ISPF source panel format file. The temporary library is created with a
record length of 160 bytes. Multiple panels created in PREP mode are stored in the
temporary library and converted through one call to ISPPREP. When all of the
panels are converted, the temporary library is deleted. ISPPREP is called by the
conversion utility when you do the following:
v Change the name of the output panel library on the ISPDTLC invocation panel
and then convert another panel.
v Deselect the Preprocess Panel Output option on the ISPDTLC invocation panel
and then convert another panel.
v Change the Generate Statistics on Panel/Message/Script Members option on the
ISPDTLC invocation panel and then convert another panel.
v Enter “PREP” on the command line of the ISPDTLC invocation panel or select
“PREP” from the ‘Commands’ action bar pull-down.
v Exit from the conversion utility.

ISPPREP is also called when:

v The number of extents of the temporary library exceeds 5.
v The number of members written to the temporary library exceeds 50.

ISPPREP output for panels longer than 80 bytes can be stored in a panel library
with a fixed record length of 80 (or a variable record length of 84). Thus, you can
create larger than standard panels in PREP mode while directing the final panel
output to a library defined with a standard length. It is the developer’s
responsibility to ensure that the WIDTH specified on the PANEL tag is appropriate
for the device intended to display the panel.

When the log or list files are specified as members of a partitioned data set, and
the log or list file member name is specified as an asterisk (*) the member is
written before the invocation panel is redisplayed. Otherwise, the log and/or list
file is stored in memory (and added to for additional DTL source conversions)
until one of the following occurs:
v The output log or list data set name is changed and another conversion is
performed.
v The member name of the log or list file is changed on the invocation panel and
another conversion is performed.
v The input DTL source member name is changed when the log or list member
name is specified as an asterisk.
v You enter on the command line or select from the Commands action bar
pull-down:
SAVELOG
to save the log file
SAVELIST
to save the list file
SAVEALL
to save both log and list files.
v You exit the conversion utility.

When the log file is specified as a partitioned data set, messages issued when the
conversion utility ends are directed to the screen.

When the CANCEL command is entered, ISPDTLC displays a cancellation

confirmation panel. This panel provides options for disposition of pending log and

182 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
list file members and for any panels to be processed by ISPPREP. An option is also
provided to ignore the CANCEL command and resume ISPDTLC processing.

ISPF Dialog Tag Language Conversion Utility

You have entered the CANCEL command.

Specify termination processing choice.

_ 1. Do not save log or list files. Do not

preprocess pending panels.
2. Save log and list files only.
3. Preprocess pending panels only.
4. Save pending log and list files.
Preprocess pending panels.
5. Ignore CANCEL command and resume
processing.
F1=Help F3=End F4=Return F5=Rfind
F6=Rchange F10=Left F11=Right F12=Cretriev

Figure 87. ISPF Dialog Tag Language Conversion Utility - Confirm Cancel

The panel appears with option 1 preselected. You may choose another option to
save log and list files only, preprocess pending panels only, save log and list files
and preprocess pending panels, or resume processing.

When you enter the SUBMIT command, ISPDTLC creates and submits a batch job,
using the file names and options specified on the interactive panel. After the job is
submitted, the interactive panel is redisplayed. The batch JCL file is built using the
ISPF skeleton ISPDTLB.

You can also run ISPDTLC from ISPF options 4 and 5 and from the workplace
member list.

Note: From the workplace member list, enter “T” (TSO) in front of the member
name to be processed. On the TSO pop-up panel enter
“ISPDTLC / (PANEL RETURN” to run a foreground conversion or
“ISPDTLC / (PANEL SUBMIT” to submit a batch job.

After you complete the required ISPDTLC invocation panel fields and press Enter,
the conversion runs or the job is submitted, and control is returned to the previous
option.

Extremely large DTL input source files (source files that contain multiple panel,
message, key list, and application command table definitions) might cause memory
capacity to be exceeded. Should this occur, split the DTL input source file into
multiple files with fewer panels, message members, key lists, or command table
definitions or reduce the record length of the input source file.

When ISPDTLC is invoked recursively, that is, more than 1 time from the same
ISPF screen, the following panel is displayed.

Chapter 10. Using the Conversion Utility 183

 ISPF Dialog Tag Language Conversion Utility

CAUTION:
ISPDTLC has been invoked recursively.
Results are not predictable.

Enter processing option.

_ 1. CANCEL this invocation of ISPDTLC.
2. Proceed with recursive execution.

F1=Help F3=End F4=Return F5=Rfind

F6=Rchange F10=Left F11=Right F12=Cancel

Figure 88. ISPF Dialog Tag Language Conversion Utility - Recursive invoke

The panel appears with option 1 preselected. If you select option 2, the new
invocation will be processed. Because of possible region size limitations, results are
not predicable.

The recursive invocation check is based on the setting of a profile variable that is
unique for each active screen. If the recursive check panel appears following an
abend, the profile variable was not properly reset when the abend occurred. In this
case, select option 2 to allow ISPDTLC to continue.

If the conversion utility is called without a source-filespec or if the PANEL option

has been specified, the invocation panel is displayed. If other options have been
specified, they are merged with the options from the profile before the display. The
PROFILE option is disregarded when the invocation panel is displayed.

The source-filespec can be a special file which is a list of other files to be converted.
When you use this option, you can convert multiple panels with a single call to the
conversion utility. The format of the file list is :
DTLLST source-filespec 1
DTLLST
. source-filespec 2
.
.

The format of source-filespec is the same as any other call to the conversion utility.
Duplicate source-filespec names within DTLLST are ignored.

The national-language selection UPPERENG causes the conversion utility to use the
uppercase version of the ENGLISH program literals. In addition, the tag text for all
tags except <SOURCE> is translated to uppercase during the conversion process.

The national-language selection SGERMAN causes the conversion utility to use a

special German-to-Swiss German conversion routine to create Swiss German panels
from either German or Swiss German DTL source files.

ISPF Conversion Utility Messages

During processing, the conversion utility can issue information, warning, and error
messages. For unsupported DTL tags and attributes that generate warning
messages, the conversion utility either ignores the tag or attribute, or sets attribute
values to the conversion utility defaults. If the conversion causes error messages,

184 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 the conversion utility will not generate the ISPF file (key list, panel, application
command table, or message member) that would have been created had the error
not occurred.

In the message listing, the line numbers displayed in the messages might not
always match the line numbers of the source file that caused the message. This
occurs because the conversion utility must sometimes continue to read the source
file until it encounters an end tag or a new tag before issuing a message. You
should be able to determine which source line created the message by examining
the DTL source file.

There are two options required to suppress all noncritical messages.

| v The MSGSUPP option is used to suppress messages related to ISPDTLC
| formatting.
v The CUASUPP option is used to suppress messages related to CUA architecture
deviations allowed by ISPDTLC. Examples include nonstandard use of F1/F13,
F3/F15, and F12/F24 keylist commands, and the use of the SMSG attribute on
the MSG tag to create a short message.

When each DTL source file conversion is completed, the conversion utility issues a
message listing the number of warning and error messages generated. If the
MSGSUPP or CUASUPP option(s) have been specified, an additional message is
issued with the total number of messages suppressed.

When the conversion utility is finished, it issues a message listing the total number
of warning and error messages generated. If the MSGSUPP or CUASUPP option(s)
have been specified, a message is issued with the total number of messages
suppressed. The end of job messages listing the total number of messages are
placed in the ISPF log file, if the log file is available; otherwise the overall totals
are written to the terminal.

Return Codes
The following list of return codes explains the results of the conversion invocation.
0 No warnings, errors, or severe errors
1 All messages were suppressed.
4 CANCEL command ended ISPDTLC
8 Only warnings were found
16 At least one DTL conversion had at least one error
20 At least one DTL conversion ended with a severe error.

For multiple conversions, the highest return code is used.

Conversion Results
The results of the conversion are placed in the shared pool.
v The variable ZDTLRC contains the return code.
v The variable ZDTLNWRN contains the number of warning messages.
v The variable ZDTLNERR contains the number of error messages.
v The variable ZDTLNSUP contains the number of suppressed messages.

Chapter 10. Using the Conversion Utility 185

Conversion Utility File Names
The conversion utility is shipped as a REXX exec on the ISPF product tape.

The ISPDTLC exec can reside in a CLIST data set allocated to SYSPROC or in an
EXEC data set allocated to SYSEXEC. For more information on the use of REXX
execs on MVS, refer to the TSO/E Version 2 REXX User’s Guide.

Additional Requirements:
v All data sets must be allocated prior to running the conversion utility. In
addition, the conversion utility uses ISPF services to produce command table
and key list output, which means that a partitioned data set must be allocated to
ISPTABL. Refer to the section on allocating ISPF libraries in the ISPF User’s
Guide for more information.
v To allow the user to specify the source and destination data sets when using the
conversion utility syntax, seven DD names have been reserved in an allocation
profile with associated data set names to be provided by the user.

Note: ISPDTLC profiles from previous releases can be used without change.
However, a warning message is issued if the DTLMIN or DTLNLS DD
name records are encountered.
v A sample profile member ISPDTLP is shipped in the ISPSLIB skeleton library.
You can modify the data set names for installation or user use. DTL format
comments (<!−−comment text−−> or (<:−−comment text−−>) can be used in the
profile data set or member. Do not modify the DDNAMEs in the following table
(column one). A sample user updated profile member follows:

DDNAME Data Set

DTLGML any.GML.input
DTLPAN your.panel.output
DTLMSG your.msg.output
6
DTLLOG your.log.output
6
DTLLIST your.list.output
DTLSCR your.script.output
DTLTAB your.table.output

DTLGML is the input file to the conversion utility. The last 6 files are for output
and are usually the user’s own data sets.
v For compatibility with previous ISPDTLC releases, the user can provide the
allocation profile name on invocation:
ISPDTLC source-filespec (disk PROFILE=User.profile

The data set name following the PROFILE keyword must be a fully-qualified
data set name. When specifying the data set name, do not include quotes.

The profile data-set-name can specify either a sequential or a partitioned data

set. If the profile entry is part of a partitioned dataset, then the member name

6. The sequential data set name associated with the DTLLOG and DTLLIST ddnames should have the same characteristics and
attributes as the LOG and LIST data sets for ISPF.

186 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 must be included in the data-set-name specification. The profile data set and all
data sets defined within the profile must be pre-allocated.

An example of the default data set names used for the conversion utility is
shown in the following table. USERID is the user’s TSO prefix.

DDNAME Data Set Type Description

DTLGML userid.GML PDS The DTL source PDS where GML
members reside.
DTLPAN userid.PANELS or PDS PDS for panel member output. May
NULLFILE or DUMMY be specified as NULLFILE or
DUMMY for cases where no panel
output is required.
DTLMSG userid.MSGS or PDS PDS for message member output.
NULLFILE or DUMMY May be specified as NULLFILE or
DUMMY for cases where no
message output is required.
DTLLOG userid.ISPDTLC.LOG SEQ or PDS Optional. User’s log data set for
userid.LOGLIB(logmem) conversion utility messages. If not
specified, log messages are written to
the standard ISPF log data set. If file
is a PDS, member name must be
included in the data set name
specification.
DTLLIST userid.ISPDTLC.LIST SEQ or PDS Optional. User’s list data set for
userid.LISTLIB(listmem) conversion utility messages. If not
specified, list messages are written to
the standard ISPF list data set. If file
is a PDS, member name must be
included in the data set name
specification.
DTLSCR userid.SCRIPT PDS Optional. PDS for panel member
documentation output. The DTLSCR
data set is required only if the
SCRIPT option is specified.
DTLTAB userid.TABLES PDS Optional. PDS for keylist and
command table output. If specified, a
LIBDEF is performed for ISPTLIB
and ISPTABL and the keylist and
command table output is written to
the data set.

The profile can contain multiple entries for each DD name. For output files, the
first valid data set name in the profile is used. For the input GML file, each data
set is checked in the order they are found in the profile for the member name
specified. The first match by member name is used as the file to be converted.

When the data set associated with either the DTLLOG or DTLLIST ddname in the
profile is a PDS, the member name may be a single asterisk. When the asterisk
notation is present, the conversion utility uses the same name for the log or list file
as the source GML member name.

Chapter 10. Using the Conversion Utility 187

188 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Part 2. Dialog Tag Language (DTL) Reference
This section contains the following chapters:
Chapter 11. How to Read the Syntax Diagrams
This chapter describes the elements that make up a syntax diagram.
Chapter 12. Markup Declarations and DTL Macro Reference
This chapter contains a reference listing for each DTL markup declaration.
Chapter 13. Tag Reference
This chapter contains a reference listing for each DTL tag.

Each reference listing in this section contains a syntax diagram and attribute
definition list, as well as a description and examples of usage.

© Copyright IBM Corp. 1989, 2000 189

190 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Chapter 11. How to Read the Syntax Diagrams
Throughout this book, syntax is described using the structure defined below.
v Read the syntax diagrams from left to right, from top to bottom, following the
path of the line.
Symbol
Description
ÊÊ─── indicates the beginning of a statement.
───Ê indicates that the statement syntax is continued on the next line.
Ê─── indicates that a statement is continued from the previous line.
───ÊÍ indicates the end of a statement.

Diagrams of syntactical units other than complete statements start with the Ê───
symbol and end with the ───Ê symbol.
v Required items appear on the horizontal line (the main path).

ÊÊ STATEMENT required-item ÊÍ

v Optional items appear below the main path.

ÊÊ STATEMENT ÊÍ
optional-item

v Items positioned above the syntax diagram line are default parameters.

default-item1
ÊÊ STATEMENT ÊÍ

v If you can choose from two or more items, these items appear vertically, in a
stack.
If you must choose an item in the stack, one of the required items appears on the
main path.

ÊÊ STATEMENT required-choice1 ÊÍ
required-choice2

If a default is also available, it appears above the main line.

default-choice
ÊÊ STATEMENT required-choice1 ÊÍ
required-choice2

If choosing one of the items is optional, the entire stack appears below the main
path.

© Copyright IBM Corp. 1989, 2000 191

 ÊÊ STATEMENT ÊÍ
optional-choice1
optional-choice2

v An arrow returning to the left above the item indicates an item that you can
repeat. Required items appear on the main line and optional items appear below
the main line.

ÊÊ STATEMENT » repeatable-item ÊÍ

A repeat arrow indicates that you can make more than one choice from the
grouped items, or repeat a single item.
v Keywords appear in uppercase (for example, PARM1). However, they can be
uppercase or lowercase when they are entered. They must be spelled exactly as
shown. Variables and acceptable values appear in all lowercase letters (for
example, parmx). They represent names or values that you supply. Keywords and
keywords followed by parameters (for example, MSG=message-id) can be coded
in any order.
v If punctuation marks, parentheses, arithmetic operators, or other symbols are
shown, you must enter them as part of the syntax.

192 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Chapter 12. Markup Declarations and DTL Macro Reference
This chapter provides you with a detailed look at the following topics:
v Document-type declaration
v Entity declarations.
v Sample Entity definitions.
v DTL Macros.

Document-Type Declaration
The document-type declaration (DOCTYPE) identifies the source file document
type and the rules the source file must follow.

ÊÊ <!DOCTYPE DM SYSTEM > ÊÍ

[ ]
entity-declarations
( )
entity-declarations

DOCTYPE
Indicates that this is a document-type declaration.
DM
Indicates that this is a DTL source file defining dialog elements.
SYSTEM
Indicates that the rules for the DOCTYPE are contained in an external file.
[|(
Indicates the beginning of the declaration subset. Either the left bracket or the
open parenthesis can be used to begin the declaration subset. The declaration
subset can contain entity declarations and parameter entity references. If the
left bracket is coded, it must be the hex value ‘AD’.
entity-declarations
The entity declarations you define for the source file must be coded within the
declaration subset. “Entity Declarations” on page 194 contains a complete
description of entity declarations.
]|)
Indicates the end of the declaration subset. Either the right bracket or the close
parenthesis can be used to end the declaration subset. If the right bracket is
coded, it must be the hex value ‘BD’.

Description
A document-type declaration identifies the source file document type and rules the
source file must follow.

The DOCTYPE declaration must appear in a DTL source file before any tag
markup, although it can be preceded by comments. Files that are embedded in a
source file intended for compilation cannot contain a DOCTYPE declaration.

© Copyright IBM Corp. 1989, 2000 193

Doctype
Example
The DOCTYPE statement declares the source file as a DM type file.

<!doctype dm system>

<varclass name=varc type='char 10'>

<varlist>
<vardcl name=vard varclass=varc>
</varlist>

<panel
. name=panel>
.
.

Entity Declarations
Entities are symbolic names that are used to insert text into a file.

ÊÊ
» <!ENTITY entity-name ″entity-text″ > ÊÍ
% ″entity-text″
CDATA SPACE REPLACE
SYSTEM
″filespec″

ENTITY
Indicates this is an entity declaration.
% Indicates a parameter entity declaration, which must be followed by at least
one space.
entity-name
The name of the entity. It must follow these rules:
v Length
– 1–8 for file imbed entity names
– 1–8 for parameter entity names
– 1–17 for other entity names
v The first character must be A–Z, a–z, @, #, or $.
v Remaining characters, if any, can be A–Z, a–z, @, #, $, or 0–9.
When an entity name is more than 8 bytes in length, one or more of the
remaining characters must be an underscore.
v Entity names are case-sensitive.
v The entity name for a parameter entity can be specified as a variable name
(that is, %&varname;). The resolved name must follow the parameter entity
naming rules.
CDATA
Indicates that any delimiter characters in entity-text will not be interpreted as
delimiters. This allows you to define entities with tags in entity-text that will
not be interpreted as tags.

For example the entity-text “<panel>” is not interpreted as the PANEL tag if
the CDATA keyword is used.

The effect of CDATA is to delay substitution of the variable until all other text
manipulation is completed. For example, you should use CDATA to specify an
entity-text string of blanks as normal text processing removes leading and
trailing blanks from text strings.

194 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Entities
Note: CDATA cannot be used with parameter entities.
SPACE
Indicates that entity-text which spans multiple DTL source file records will be
formatted like the <p> tag. (Leading and trailing blanks on entity-text lines will
be compressed to a single blank character.) In addition, multiple blanks
between words of entity-text will be compressed to a single blank character.
REPLACE
Indicates that the current entity-text is to replace any previous definition of the
same entity name.
“entity-text”
The text associated with the entity reference. The text must be enclosed in
single or double quotes. The length of the entity-text must be less than or equal
to 253 bytes.
SYSTEM
Indicates this entity refers to an external file.
“filespec”
The name of the file the entity refers to. The name must be enclosed in single
or double quotes. If this is not specified, it defaults to the name of the entity.

The SYSTEM parameter can optionally be followed by the filename for the
included file. The file name for MVS is a member name for a file provided on
the invocation panel or specified as “DTLGML” entries in the ISPDTLC profile.

Description
Entities are symbolic names that are used to insert text into a file. The text that an
entity refers to can be a simple string of characters or it can be the text from an
entire file.

An entity reference is used to insert the text associated with the entity. Entities
must be declared in the declaration subset of the DOCTYPE declaration before they
can be referred to. To refer to the entity in the source file, the entity name is
preceded by an ampersand (&) to indicate it is an entity or percent (%) to indicate
it is a parameter entity. Both types of entities are ended with a semicolon (;). A
blank or the end of the line can be used to end the entity reference instead of the
semicolon.

Because entity declarations can only be made within the declaration subset, the
parameter entity is the only way to embed a file of entity declarations. Parameter
entities are used when an entity reference is needed in the declaration subset.
References to parameter entities can only be made in the declaration subset.

References to entities can be made anywhere in the source file after the end of the
DOCTYPE declaration.

Note: To refer to an entity within a <SOURCE> tag in the source file, the entity
name is preceded by a percent (%) instead of an ampersand (&).

Because entity names are case-sensitive, ensure that references to entities are
specified correctly.

Conditions
Entities that are declared do not have to be referred to.

Chapter 12. Markup Declarations and DTL Macro Reference 195

Entities
Example
This example uses both entities and parameter entities. It embeds the file GLBENT
with global entity declarations, and a file with tags and text. It also uses entities
and parameter entities that refer to text strings.

The first entity declaration declares the “glbent” parameter entity as an external
file.

The file name is defaulted to GLBENT. A parameter entity is used because this file
contains entity declarations. Because entity declarations can only be made in the
declaration subset, the GLBENT file is embedded with an entity reference within
the declaration subset. The entity declarations in GLBENT are for text that is used
at the top and bottom of the panel. The “header” entity declaration refers to an
external file, and the “footer” is a text string. Both of these entities are referred to
in the source file.

The second entity declaration, for “list”, is also a parameter entity. This declaration
refers to a string, not an external file. The text is the SL tag name, which is referred
to in the next two entity declarations. These two declarations, “slist” and “elist”,
are used as the SL start and end tags. They are defined as entities so the type of
list can be changed in one place. To change the list type from a simple list (SL) to
an unordered list (UL), change the parameter entity “list” from SL to UL.

This is the content of the source file:

<!DOCTYPE DM SYSTEM [
<!ENTITY % glbent SYSTEM -- declaration of global entity file -->
%glbent;<!-- Embeds the global entity file -->
<!ENTITY % list “sl” -- type of list -->
<!ENTITY slist “<%list;>” -- type of list start tag. -- >
<!ENTITY elist “</%list;>” -- type of list end tag. -- >
]>

<panel name=showlist depth=22 width=45>Show Departments

<area>
<info width=40>
&header;
<p>The floors and departments are shown below:
&slist;
<li>First floor
&slist;
<li>Toys
<li>Electronics
&elist;
<li>Second floor
&slist;
<li>Boys clothes
<li>Girls clothes
&elist;
&elist;
&footer;
</info>
</area>
</panel>

This is the content of the embedded file GLBENT:

<!ENTITY header SYSTEM “coname”>

<!ENTITY footer “<p> We're always glad to help!”>

196 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Entities
This is the content of the embedded file CONAME:

<lines>
Jeff's Children's World
Barnett, NC
</lines>

Figure 89 shows the formatted result:

Show Departments

Jeff's Children's World

Barnett, NC

The floors and departments are shown below:

First floor

Toys

Electronics

Second floor

Boys clothes

Girls clothes

We're always glad to help!

Figure 89. Entities and Parameter Entities

Sample Entity Definitions

The tag examples in “Chapter 13. Tag Reference” on page 201 use entity definitions
to create the sample panels. The entities used are called SAMPABC (to define the
action bar); SAMPVAR1, SAMPVAR2, and SAMPVAR3 (to provide VARCLASS and
VARLIST definitions); and and SAMPBODY (to provide a panel body section).

The DTL definitions follow:

SAMPABC:
<ABC>File
<PDC>Add Entry
<ACTION RUN=add>
<PDC>Delete Entry
<ACTION RUN=delete>
<PDC>Update Entry
<ACTION RUN=update>
<PDC>Exit
<ACTION RUN=exit>
<ABC>Search
<PDC CHECKVAR=whchsrch MATCH=1>Search on name
<ACTION SETVAR=whchsrch VALUE=1>
<ACTION RUN=search>
<PDC CHECKVAR=whchsrch MATCH=2>Search on card number
<ACTION SETVAR=whchsrch VALUE=2>
<ACTION RUN=search>
<ABC>Help

Chapter 12. Markup Declarations and DTL Macro Reference 197

Entities
<PDC>Extended Help...
<ACTION RUN=exhelp>
<PDC>Keys Help...
<ACTION RUN=keyshelp>
SAMPVAR1:
<VARCLASS NAME=date TYPE='char 8'>
<VARCLASS NAME=numcls TYPE='numeric 7'>
<VARCLASS NAME=namecls TYPE='char 25'>
<VARCLASS NAME=char1cls TYPE='char 1'>
<VARCLASS NAME=char7cls TYPE='char 7'>

<VARLIST>
<VARDCL NAME=whchsrch VARCLASS=char1cls>
<VARDCL NAME=curdate VARCLASS=date>
<VARDCL NAME=cardno VARCLASS=numcls>
<VARDCL NAME=name VARCLASS=namecls>
<VARDCL NAME=address VARCLASS=namecls>
<VARDCL NAME=cardsel VARCLASS=char1cls>
<VARDCL NAME=card VARCLASS=char7cls>
<VARDCL NAME=north VARCLASS=char1cls>
<VARDCL NAME=south VARCLASS=char1cls>
<VARDCL NAME=east VARCLASS=char1cls>
<VARDCL NAME=west VARCLASS=char1cls>
<VARDCL NAME=nth VARCLASS=char1cls>
<VARDCL NAME=sth VARCLASS=char1cls>
<VARDCL NAME=est VARCLASS=char1cls>
<VARDCL NAME=wst VARCLASS=char1cls>
</VARLIST>
SAMPVAR2:
<VARCLASS NAME=casecls TYPE='char 7'>
<VARCLASS NAME=namecls TYPE='char 25'>
<VARCLASS NAME=addrcls TYPE='char 25'>
<VARCLASS NAME=char1cls TYPE='char 1'>
<VARCLASS NAME=char2cls TYPE='char 2'>

<VARLIST>
<VARDCL NAME=caseno VARCLASS=casecls>
<VARDCL NAME=name VARCLASS=namecls>
<VARDCL NAME=address VARCLASS=addrcls>
<VARDCL NAME=casesel VARCLASS=char2cls>
<VARDCL NAME=patin VARCLASS=char1cls>
<VARDCL NAME=defa VARCLASS=char1cls>
<VARDCL NAME=cont VARCLASS=char1cls>
<VARDCL NAME=priv VARCLASS=char1cls>
<VARDCL NAME=incr VARCLASS=char1cls>
<VARDCL NAME=disp VARCLASS=char1cls>
<VARDCL NAME=fraud VARCLASS=char1cls>
</VARLIST>
SAMPVAR3:
<VARCLASS NAME=namecls TYPE='char 7'>
<VARCLASS NAME=char1cls TYPE='char 1'>
<VARCLASS NAME=char2cls TYPE='char 2'>

<VARLIST>
<VARDCL NAME=file VARCLASS=namecls>
<VARDCL NAME=type VARCLASS=char2cls>
<VARDCL NAME=marg VARCLASS=char2cls>
<VARDCL NAME=copy VARCLASS=char2cls>
<VARDCL NAME=duplx VARCLASS=char1cls>
</VARLIST>
SAMPBODY:

198 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Entities
<TOPINST>Type in patron's name and card number (if applicable).
<TOPINST>Then select an action bar choice.
<AREA>
<DTAFLD DATAVAR=curdate PMTWIDTH=12 ENTWIDTH=8 USAGE=out>Date
<DTAFLD DATAVAR=cardno PMTWIDTH=12 ENTWIDTH=7 DESWIDTH=25>Card No
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address PMTWIDTH=12 ENTWIDTH=25>Address
<DIVIDER>
<REGION DIR=horiz>
<SELFLD NAME=cardsel PMTWIDTH=30 SELWIDTH=38>Choose
one of the following
<CHOICE CHECKVAR=CARD MATCH=NEW>New
<CHOICE CHECKVAR=CARD MATCH=RENEW>Renewal
<CHOICE CHECKVAR=CARD MATCH=REPLACE>Replacement
</SELFLD>
<SELFLD TYPE=multi PMTWIDTH=30 SELWIDTH=25>Check valid branches
<CHOICE NAME=NORTH HELP=NTHHLP CHECKVAR=NTH>North Branch
<CHOICE NAME=SOUTH HELP=STHHLP CHECKVAR=STH>South Branch
<CHOICE NAME=EAST HELP=ESTHLP CHECKVAR=EST>East Branch
<CHOICE NAME=WEST HELP=WSTHLP CHECKVAR=WST>West Branch
</SELFLD>
</REGION>
</AREA>
<CMDAREA>Enter a command

DTL Macros
A DTL macro is a DTL source member found in the concatenated DTL source
libraries allocated as input to ISPDTLC. The macro member can be empty or it can
contain any DTL tag coding, including DTL comments.

The macro member is imbedded into the current DTL source file when the macro
name is encountered during conversion. The file imbed process is similar to Entity
file imbed.

DTL macro tag syntax is similar to regular DTL tag syntax. You invoke a macro by
specifying the macro member name using a special DTL tag open delimiter, like
this:
<?macmemb>

The macro member name must conform to the DTL standard member name rules.

When ISPDTLC finds the <? open delimiter, a file imbed is performed on the
specified member name. The reserved member name dummy can be specified to
create a no operation (NOP) situation during the imbed cycle. If the specified
member has no records, conversion continues with the next DTL source record.

The content of the macro member can be any valid DTL source input. The member
can contain multiple tags and comment records just like any other DTL source file.
DTL source file variables, sometimes referred to as entities, are substituted using
standard entity processing.

An advantage to using the macro syntax instead of an entity file imbed is that you
need not code the entity declaration for the file to be imbedded. ISPDTLC resolves
the required information for you.

Another advantage is that you can specify entity values as part of the macro
coding syntax, and bypass the coding of other entity delcarations. For example, if
the entity variables subst_var_1, subst_var_2, and subst_var_3 were coded within

Chapter 12. Markup Declarations and DTL Macro Reference 199

Entities
the macro using standard DTL syntax (that is, &subst_var_1;,&subst_var_2;, and
&subst_var_3;), you could invoke the macro and specify the substitution values
like this:
<?macmemb subst_var_1=subvalue1 subst_var_2=subvalue2
subst_var_3=subvalue3>

ISPDTLC automatically defines the entities with the specified values. The values
are stored using entity REPLACE processing, so that if a previous definition exists,
it is overwrittten. The new definition remains in effect until replaced, and can be
referenced by any other part of the DTL source file.

Macro tags placed within the document declaration function use the same rules as
macro tags found after the document declaration. For example, you can use the
macro syntax in place of parameter entities. The parameter entity (really a file of
other entity definitions) member pentmem can be imbedded easily by coding
<?pentmem>

within the document declaration. This syntax replaces the more complicated
parameter entity coding of
<:ENTITY % pentmem; system>
%pentmem;

In another example, the macro syntax can be used in place of entity tags.
<?dummy panel_title='ISPF macro example'
panel_width=60
panel_depth=18>

This syntax replaces multiple entity definitions:

<:ENTITY panel_title 'ISPF macro example'>
<:ENTITY panel_width '60'>
<:ENTITY panel_depth '18'>

In the previous example the macro name dummy is used to bypass the file imbed
and enable the attribute resolution process to establish the entity values.

200 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Chapter 13. Tag Reference
This chapter contains an alphabetical reference of the Dialog Tag Language (DTL)
tags.

Each reference listing contains:

v A diagram of the valid syntax for the tag
v A list describing the tag attributes
v A description of the tag
v Conditions of usage
v A table of the tags that can be nested within the tag
v An example of how the tag is used within DTL source markup.

Rules for Variable Names

Variable names supplied as attribute values on DTL tags must have the following
characteristics:
v 1–8 characters in length
v The first character must be A–Z, a–z, @, #, or $.
v Remaining characters, if any, can be A–Z, a–z, @, #, $, or 0–9.

Lowercase characters are translated to their uppercase equivalents

Names composed of valid characters that are longer than 8 bytes are truncated to 8
bytes. Names that are not valid are set to blank.

Rules for “%variable” Names

When a “%varname” notation is found as an attribute value, the “%varname”
entry must have the following characteristics:
v 2–9 characters in length
v The first character is a “%”.
v The second character must be A–Z, a–z, @, #, or $.
v Remaining characters, if any, can be A–Z, a–z, @, #, $, or 0–9.

Lowercase characters are translated to their uppercase equivalents

The first position of a valid name is replaced by an “&”.

Names composed of valid characters that are longer than 9 bytes are truncated to 9
bytes. Names that are not valid are set to blank.

It is the responsibility of the application to provide a valid value in the variable

before the panel is displayed.

AB (Action Bar)
The AB tag defines an action bar on an application panel.

ÊÊ <AB Ê
YES ABSEPSTR=ab-separator-string
MNEMGEN= NO

© Copyright IBM Corp. 1989, 2000 201

AB
Ê > </AB> ÊÍ
ABSEPCHAR=ab-separator-character

MNEMGEN=YES | NO

Note: When the conversion utility is operating in DBCS mode, the default
value for MNEMGEN is NO.
This attribute controls the automatic generation of mnemonic characters for the
entire action bar. When MNEMGEN=NO, mnemonic characters are determined
only by the use of the M tag within action bar or pull-down choice description
text. See “Mnemonic Choice Selection” on page 38 and “M (Mnemonic)” on
page 374 for additional information.

When MNEMGEN=YES, the NOGUI invocation option is ignored and

mnemonics will be generated automatically.
ABSEPSTR=ab-separator-string
This attribute provides a string of data to be overlayed at the right end of the
action bar separator line.

Note: This attribute is NOT recommended for general use because the action
bar separator line is not displayed when operating in GUI mode.
ABSEPCHAR=ab-separator-character
This attribute provides a replacement character for the action bar separator
line. When the GRAPHIC invocation option has been specified, the action bar
separator will default to a solid line for host display. You can use the
ABSEPCHAR attribute to provide a different character such as a dash.

Description
The AB tag defines an action bar on an application panel. The action bar appears
on the panel above the panel title line. The action bar provides a way for users to
view all actions that apply to the panel it is coded within.

The conversion utility inserts a line between the action bar and the panel title line.
The GRAPHIC invocation option creates a solid line. NOGRAPHIC creates a
dashed line. If required by the length or number of action bar choices, the
conversion utility will format multiple lines for the action bar.

ABC tags, which you code within an AB definition, define application panel
choices for the action bar. PDC tags, which you code within ABC tag definitions,
define the action bar pull-down choices.

To define an action bar and its associated pull-downs, you code the AB tag (and
other tags that define the action bar choices and pull-downs) within a PANEL
definition.

Conditions
v The AB tag requires an end tag.
v You must code the AB tag within a PANEL definition. Each application panel
can include only one action bar. See “PANEL (Panel)” on page 397 for a complete
description of this tag.
v You must code at least one ABC tag within an action bar definition.
v To conform to CUA rules, you must include a help action bar choice.

202 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 AB
Nested Tags
You can code the following tag within an AB definition:

Tag Name Usage Page Required

ABC Action bar choice Multiple 204 Yes

Example
The following markup contains the action bar markup for the application panel
illustrated in Figure 90 on page 204.
<!DOCTYPE DM SYSTEM(
<!entity sampvar1 system>
<!entity sampbody system>)>
&sampvar1;

<PANEL NAME=ab KEYLIST=keylxmp>Library Card Registration

<AB>
<ABC>File
<PDC>Add Entry
<ACTION RUN=add>
<PDC>Delete Entry
<ACTION RUN=delete>
<PDC>Update Entry
<ACTION RUN=update>
<PDC>Exit
<ACTION RUN=exit>
<ABC>Search
<PDC CHECKVAR=whchsrch MATCH=1>Search on name
<ACTION SETVAR=whchsrch VALUE=1>
<ACTION RUN=search>
<PDC CHECKVAR=whchsrch MATCH=2>Search on card number
<ACTION SETVAR=whchsrch VALUE=2>
<ACTION RUN=search>
<ABC>Help
<PDC>Extended Help...
<ACTION RUN=exhelp>
<PDC>Keys Help...
<ACTION RUN=keyshelp>
</AB>
&sampbody;
</PANEL>

Chapter 13. Tag Reference 203

 ABC

File Search Help

--------------------------------------------------------------------------
Library Card Registration

Type in patron's name and card number if applicable.

Then select an action bar choice.

Date . . . :
Card No. . . _______ (A 7-digit number)
Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following Check valid branches

__ 1. New _ North Branch
2. Renewal _ South Branch
3. Replacement _ East Branch
_ West Branch

Enter a command ===> ______________________________________________________

F1=Help F2=Split F3=Exit F6=KEYSHELP F9=Swap
F12=Cancel

Figure 90. Action Bar

ABC (Action Bar Choice)

The ABC tag defines a choice in an action bar and serves as a base for associated
pull-down choice tags.

ÊÊ <ABC Ê
NO PDCVAR=pdc-variable-name
HELP= YES
help-panel-name
*help-message-id
%varname
*%varname

Ê > choice-description-text ÊÍ
</ABC>

| HELP=NO | YES | help-panel-name | *help-message-id | %varname |

| *%varname
| This attribute specifies the help action taken when the user requests help on
| the action bar choice.

| When HELP=YES, control is returned to the application. You can specify either
| a help panel or a message identifier. If a message identifier is used, it must be
| prefixed with an asterisk (*).

| The help attribute value can be specified as a variable name. When %varname
| is coded, a panel variable name is created. When *%varname is coded, a
| message variable name is created.

| If the user requests help on an action bar choice and no help is defined, the
| extended help panel is displayed. If an extended help panel is not defined for
| the panel, the application or ISPF tutorial is invoked.

204 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 ABC
| The help-panel-name must follow the standard naming convention described in
| “Rules for Variable Names” on page 201.

| See “HELP (Help Panel)” on page 323 for information on creating help panels.
| For information about creating messages, see “MSG (Message)” on page 376.
PDCVAR=pdc-variable-name
This attribute provides the name of a variable to contain the value of the
pull-down choice. When a variable name is provided, it replaces the default
ZPDC variable name. The pdc-variable-name is not initialized to blank.

The pdc-variable-name must follow the standard naming convention described in

“Rules for Variable Names” on page 201.
choice-description-text
This is the text that appears in the action bar. The text is limited to 64 bytes.

If the choice-description-text exceeds the panel width, the conversion utility

issues a warning message and truncates the text. If the choice-description-text for
multiple ABC tags exceeds the panel width, the conversion utility formats a
multiple-line action bar.

Description
The ABC tag defines a choice in an action bar and serves as a base for associated
pull-down choice tags. The pull-down choices appear in a pull-down when the
action bar choice is selected.

If the text of an action bar choice contains multiple words, multiple blanks
between the words are not compressed.

Conditions
v You must code the ABC tag within an AB definition. See “AB (Action Bar)” on
page 201 for a complete description of this tag.
v You must code at least one PDC tag within each ABC definition. See “PDC
(Pull-Down Choice)” on page 412 for a complete description of this tag.
v The maximum number of action bar choices that will be generated is 40.

Nested Tags
You can code the following tag within an ABC definition:

Tag Name Usage Page Required

COMMENT Comment Multiple 272 No
PDC Pull-down choice Multiple 412 Yes
M Mnemonic Single 374 No
SOURCE Source Multiple 449 No

Example
The following markup illustrates the use of the PDCVAR attribute to specify an
application variable for the first action bar choice. It produces the action bar on the
application panel shown in Figure 91 on page 206.
<!DOCTYPE DM SYSTEM(
<!entity sampvar1 system>
<!entity sampbody system)>

Chapter 13. Tag Reference 205

ABC
&sampvar1;

<PANEL NAME=abc1 KEYLIST=keylxmp>Library Card Registration

<AB>
<ABC PDCVAR=foptns>File
<PDC>Add Entry
<ACTION RUN=add>
<PDC>Delete Entry
<ACTION RUN=delete>
<PDC>Update Entry
<ACTION RUN=update>
<PDC>Exit
<ACTION RUN=exit>
<ABC>Search
<PDC CHECKVAR=whchsrch MATCH=1>Search on name
<ACTION SETVAR=whchsrch VALUE=1>
<ACTION RUN=search>
<PDC CHECKVAR=whchsrch MATCH=2>Search on card number
<ACTION SETVAR=whchsrch VALUE=2>
<ACTION RUN=search>
<ABC>Help
<PDC>Extended Help...
<ACTION RUN=exhelp>
<PDC>Keys Help...
<ACTION RUN=keyshelp>
</AB>
&sampbody;
</PANEL>

File Search Help

--------------------------------------------------------------------------
Library Card Registration

Type in patron's name and card number if applicable.

Then select an action bar choice.

Date . . . :
Card No. . . _______ (A 7-digit number)
Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following Check valid branches

__ 1. New _ North Branch
2. Renewal _ South Branch
3. Replacement _ East Branch
_ West Branch

Enter a command ===> ______________________________________________________

F1=Help F2=Split F3=Exit F6=KEYSHELP F9=Swap
F12=Cancel

Figure 91. Action Bar Choices

206 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 ACTION

ACTION (Action)
The ACTION tag defines the action that occurs when a pull-down choice or a
selection field choice is selected.

ÊÊ <ACTION Keyword 1 > ÊÍ

Keyword 2 </ACTION>
Keyword 3

Keyword 1:

RUN= internal-command-name PARM= parameters Ê

%varname %varname NO
APPLCMD= YES

Ê
ISPF options

Keyword 2:

SETVAR=variable-name
1
VALUE= string
%varname

Keyword 3:

TOGVAR=variable-name
0 1
VALUE1= string VALUE2= string
%varname %varname

ISPF options:

CMD
TYPE= PGM Ê
PANEL NEWAPPL
WSCMD NEWAPPL=application-id NEWWINDOW
WSCMDV
EXIT

Ê Ê
PASSLIB NEWPOOL SUSPEND SCRNAME=screen-name NOCHECK

Chapter 13. Tag Reference 207

 ACTION
Ê Ê
ADDPOP OPT= option MODE= LINE LANG= APL
%varname FSCR CREX

Ê Ê
BARRIER NEST WSDIR=ws-directory MODELESS
WSINVOKE= MODAL

Ê
MAX VIS
WSSIZE= MIN WSVIEW= INVIS

RUN=internal-command-name | %varname
When the ACTION tag is associated with a PDC tag, this attribute specifies the
internal name of a command to be executed. The command is found in the
application or system command table unless APPLCMD=YES is specified. The
search for the command follows the normal command processing rules. For
information on defining commands, see “CMD (Command Definition)” on
page 259.

The RUN action is an ending action. Thus, if multiple ACTION tags are coded
for a given pull-down, those following a RUN action are ignored.

When the ACTION tag is associated with a CHOICE tag (under a SELFLD tag
that specifies TYPE=MENU or TYPE=MODEL), the TYPE attribute and related
RUN attribute values are:
TYPE RUN attribute value
CMD Command name
PGM Program name
PANEL Panel name
WSCMD Workstation command name and parameters
WSCMDV The name of a variable that contains the workstation command
and parameters.

| When the ACTION tag is associated with a CHOICE tag under a SELFLD tag
| that specifies TYPE=TUTOR, the TYPE attribute is forced to PANEL. The RUN
| attribute must provide a panel name. None of the other ISPF selection menu
| attributes are valid for tutorial panels.

If TYPE=CMD is specified and the internal-command-name should start with a

%, you must code an additional % before the internal-command-name to
distinguish it from a variable name. (For example, to specify the
internal-command-name “%abc”, code “%%abc”. If TYPE=EXIT is specified, the
RUN attribute is required for conversion utility processing, but is not used in
the generated panel.

Note: This attribute is not supported if the ACTION tag is associated with a
CHOICE tag under a SELFLD tag that specifies TYPE=SINGLE or
TYPE=MULTI.

208 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 ACTION
PARM=parameters | %varname
These are the command parameters. These parameters are passed to
command processing with the command specified on the RUN attribute.
Command processing handles the specified parameters the same way
parameters entered in the command area are handled. You can specify the
name of a dialog variable (using % notation) whose value at run time will
be passed as the parameter data. When the ACTION tag is associated with
a PDC tag, the conversion utility limits the length of the command
parameters to 72 single-byte characters.

When a ACTION tag is used to build a menu selection choice for

TYPE=CMD or TYPE=PGM, and the NEWWINDOW attribute has been
specified, the conversion utility limits the length of the command
parameters to 249 single-byte characters; otherwise, the parameter is added
to the selection as coded. The PARM attribute is not used when
TYPE=WSCMD.
APPLCMD=NO | YES
This attribute specifies whether the command provided by the RUN
attribute is to be passed directly to the application, bypassing the
command table search. When APPLCMD=YES, the length of the command
name is limited to 7 bytes to allow the passthru character “>” to be
prefixed to the command name.

This attribute is valid only on an ACTION tag that is associated with a

PDC tag.

| The following attributes are valid only when generating an ISPF selection
| menu or edit model selection menu. (When the SELFLD tag specifies
| TYPE=TUTOR, the TYPE attribute is forced to ″PANEL″ and none of the
| other ISPF selection menu attributes are valid.)
TYPE=CMD | PGM | PANEL | WSCMD | WSCMDV | EXIT
This attribute specifies the type of selection to be generated for the
selection menu. The attributes NEWAPPL, NEWWINDOW, PASSLIB,
NEWPOOL, SUSPEND, SCRNAME, NOCHECK, ADDPOP, OPT, MODE,
LANG, BARRIER, NEST, WSDIR, WSINVOKE, WSSIZE, and WSVIEW are
not valid when TYPE=EXIT is specified.
NEWAPPL=application–id
The NEWAPPL keyword may be specified with or without an application
identifier. This attribute specifies that the NEWAPPL keyword (and the
application identifier, if present) will be added to the selection menu
choice.
NEWWINDOW
This attribute specifies that the selection menu choice will be created
specifying the ISPSTRT programming interface. The NEWWINDOW
attribute is valid only when TYPE=PANEL, TYPE=PGM, or TYPE=CMD.
PASSLIB
This attribute specifies that the PASSLIB keyword will be added to the
selection menu choice.
NEWPOOL
This attribute specifies that the NEWPOOL keyword will be added to the
selection menu choice.

Chapter 13. Tag Reference 209

ACTION
SUSPEND
This attribute specifies that the SUSPEND keyword will be added to the
selection menu choice.
SCRNAME=screen-name
This attribute specifies that the SCRNAME keyword will be added to the
selection menu choice. ISPF reserved values for screen-name are LIST,
NEXT, PREV, ON, and OFF.
NOCHECK
This attribute specifies that the NOCHECK keyword will be added to the
selection menu choice. The NOCHECK attribute is valid only when
TYPE=CMD or TYPE=PGM.
ADDPOP
This attribute specifies that the ADDPOP keyword will be added to the
selection menu choice. The ADDPOP attribute is valid only when
TYPE=PANEL.
OPT=option | %varname
This attribute specifies that the OPT keyword will be added to the
selection menu choice to specify an initial option for the panel. The OPT
attribute is valid only when TYPE=PANEL.
MODE=LINE | FSCR
This attribute specifies that the MODE keyword will be added to the
selection menu choice. The MODE attribute is valid only when
TYPE=CMD or TYPE=PGM.
LANG=APL | CREX
This attribute specifies that the LANG keyword will be added to the
selection menu choice. The LANG attribute is valid only when
TYPE=CMD.
BARRIER
This attribute specifies that the BARRIER keyword will be added to the
selection menu choice. The BARRIER attribute is valid only when
TYPE=CMD.
NEST
This attribute specifies that the NEST keyword will be added to the
selection menu choice. The NEST attribute is valid only when TYPE=CMD.
WSDIR=ws-directory
This attribute specifies that the WSDIR(ws-directory) keyword will be added
to the selection menu choice. WSDIR provides the name of a dialog
variable that contains the directory name from which the workstation
command should be invoked. The WSDIR attribute is valid only when
TYPE=WSCMD or TYPE=WSCMDV.
WSINVOKE=MODELESS | MODAL
This attribute specifies either the MODELESS or MODAL keyword will be
added to the selection menu choice. The WSINVOKE attribute is valid only
when TYPE=WSCMD or TYPE=WSCMDV.
WSSIZE=MAX | MIN
This attribute specifies either the MAX or MIN keyword will be added to
the selection menu choice. The WSSIZE attribute is valid only when
TYPE=WSCMD or TYPE=WSCMDV.

210 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 ACTION
WSVIEW=VIS | INVIS
This attribute specifies either the VIS or INVIS keyword will be added to
the selection menu choice. The WSVIEW attribute is valid only when
TYPE=WSCMD or TYPE=WSCMDV.
SETVAR=variable-name
This attribute sets a value into a dialog variable. The SETVAR attribute names
the variable to set. The variable-name must be coded without the leading %
sign.
VALUE=1 | string | %varname
This is the value to set into the variable named on the SETVAR attribute. If
you code the SETVAR attribute but omit the VALUE attribute, ISPF assigns
the variable a value of 1. You can specify the name of a variable (using %
notation) whose value at run time will be used to set the variable.

When defining the ACTION tag for selection fields, you should be aware that
the variable name defined in the SELFLD tag for single-choice selection fields
or in the CHOICE tag for multiple-choice selection fields will contain the value
entered by the user when the selection is made. In addition, if the CHECKVAR
attribute is specified in the CHOICE tag, the value of the MATCH attribute
associated with the choice is set into the variable named by the CHECKVAR
attribute. Therefore, it is not necessary to use the ACTION tag SETVAR
attribute for the application to know which selection field choice or choices
were made by the user.
TOGVAR=variable-name
This attribute allows you to alternate the value of a single variable between
two values. The TOGVAR attribute names the variable to set. The variable-name
must be coded without the leading % sign.

The function of the TOGVAR action can be depicted as follows:

if (TOGVAR-variable-name = VALUE1-string)
TOGVAR-variable-name = VALUE2-string
else
TOGVAR-variable-name = VALUE1-string
VALUE1=0 | string | %varname
This is the value to set into the variable named on the TOGVAR attribute if
it is not currently equal to this value. If you code the TOGVAR attribute,
but omit the VALUE1 attribute, the variable is assigned a value of 0. You
can specify the name of a variable (using % notation) whose value at run
time will be used to set the variable.
VALUE2=1 | string | %varname
This is the value to set into the variable named on the TOGVAR attribute if
it is currently equal to the value specified with the VALUE1 attribute. If
you code the TOGVAR attribute, but omit the VALUE2 attribute, the
variable is assigned a value of 1. You can specify the name of a variable
(using % notation) whose value at run time will be used to set the variable.

Description
The ACTION tag defines the action that occurs when a pull-down choice or a
selection field choice is selected. Code the ACTION tag within the PDC or
CHOICE definition it is associated with. You can specify multiple ACTION tags for
a given choice. The conversion utility builds the logic to carry out the actions in
the order in which you code the ACTION tags.

Chapter 13. Tag Reference 211

 ACTION
When defining action bar pull-downs, you should code the SETVAR attribute in
the ACTION tags associated with each PDC tag if the application needs to know
which pull-down choice the user selected. Unlike selection fields, there is no
variable name associated with a pull-down definition and the PDC CHECKVAR
variable is not set to indicate the user’s choice. Therefore, dialogs must refer to the
SETVAR variable-name to determine the pull-down choice the user has selected.

| The TYPE, NEWAPPL, NEWWINDOW, PASSLIB, NEWPOOL, SUSPEND,

| SCRNAME, NOCHECK, ADDPOP, OPT, MODE, LANG, BARRIER, NEST, WSDIR,
| WSINVOKE, WSSIZE, and WSVIEW attributes are used by the conversion utility
| to build an ISPF selection menu. They are valid only when they appear on an
| ACTION tag associated with a CHOICE tag which is nested within a SELFLD tag
| that specifies TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR (when the SELFLD
| tag specifies TYPE=TUTOR, the only valid selection menu attribute is
| TYPE=PANEL). They will not be processed in other situations. Refer to the ISPF
| User’s Guide for a description of the function of these keywords in ISPF option
| menus.

Conditions
v You must code the ACTION tag within the PDC or CHOICE definition it is
associated with. See “PDC (Pull-Down Choice)” on page 412 and “CHOICE
(Selection Choice)” on page 252 for descriptions of these tags.
v You must code one (and only one) of these attributes on each ACTION tag:
RUN, SETVAR, or TOGVAR.
v You can code the RUN attribute when:
– The ACTION tag is associated with a PDC tag.
| – The ACTION tag is associated with a CHOICE tag under a SELFLD tag that
| specifies TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR.
v When a “%varname” notation is found on any of the attributes that allow a
variable name, the “%varname” entry must follow the standard naming
convention described in “Rules for “%variable” Names” on page 201.

Nested Tags
None.

Example
In the following markup, each of the PDC tags have associated ACTION tags that
specify the command that is executed when the pull-down choice is selected. Many
of the PDC tags have additional ACTION tags associated with them that specify
the SETVAR attribute to let the application know which pull-down choice was
selected.

The use of ACTION tags associated with CHOICE tags is illustrated in the
example for “PS (Point-and-Shoot)” on page 419.
<!DOCTYPE DM SYSTEM>

<PANEL NAME=action1>Library Card Listing

<AB>
<ABC>File
<PDC>Add Entry
<ACTION SETVAR=fchoice VALUE=add>
<ACTION RUN=add>
<PDC>Delete Entry
<ACTION SETVAR=fchoice VALUE=delete>
<ACTION RUN=delete>

212 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 ACTION
<PDC>Update Entry
<ACTION SETVAR=fchoice VALUE=update>
<ACTION RUN=update>
<PDC>Exit
<ACTION RUN=exit>
<ABC>Sort sequence
<PDC CHECKVAR=whchsort MATCH=1>Sort on name
<ACTION SETVAR=whchsort VALUE=1>
<ACTION RUN=sort>
<PDC CHECKVAR=whchsort MATCH=2>Sort on card number
<ACTION SETVAR=whchsort VALUE=2>
<ACTION RUN=sort>
<ABC>Help
<PDC>Extended Help...
<ACTION RUN=exhelp>
<PDC>Keys Help...
<ACTION RUN=keyshelp>
</AB>
<TOPINST>Choose the size of the list needed.
<TOPINST>Then select action bar choice “Sort sequence” to
indicate the desired sort sequence.
<AREA>
<SELFLD NAME=aa PMTWIDTH=30 PMTLOC=before SELWIDTH=38>Choose
one of the following
<CHOICE>New this month
<CHOICE>New this year
<CHOICE>All (this will take time to process)
</SELFLD>
</AREA>
<CMDAREA>Enter a command
</PANEL>

AREA (Area)
The AREA tag defines portions of a panel body, one or more of which can be
scrollable.

ÊÊ <AREA Ê
1 0 INDENT=n
MARGINW= n MARGIND=

Ê Ê
DEPTH= n DEPTH Options WIDTH=n VERT
* DIR= HORIZ

Ê > </AREA> ÊÍ

DEPTH Options:

OFF NONE
EXTEND= ON DIV= BLANK DIV Options
FORCE SOLID
DASH
TEXT

Chapter 13. Tag Reference 213

 AREA
DIV Options:

MAX FORMAT= START TEXT=divider-text

DIVWIDTH= MIN CENTER
END

MARGINW=1 | n
This attribute defines a margin along the left and right sides of the panel area.
This attribute allows you to specify the width of the margin in characters. The
minimum value you can specify is 1 and the maximum value is 32. If you do
not specify a value, the margin is set to 1.

The MARGINW cannot be larger than one half the panel width minus 2.
Specification of the MARGINW should always allow enough room in the panel
body section of the ISPF panel being generated to contain all non-wrapped
data without truncation. Specification of one half the panel width minus 2
results in no panel area in which panel body text can be written.
MARGIND=0
This attribute defines a margin along the top and bottom of the panel area.

The conversion utility will only support a margin depth of zero in an effort to
use all of the available space on the panel body. Any definition of margin
depth that is not equal to zero will be changed to zero.
INDENT=n
This attribute defines the number of columns to indent the current AREA from
the current MARGINW value.
DEPTH=n | *
This attribute defines the minimum size of a scrollable panel area. If DEPTH is
not specified for HELP panels, the conversion utility will generate multiple
HELP panels for compatibility with previous releases. When EXTEND=OFF,
the minimum DEPTH is 2 lines. When EXTEND=ON, the minimum DEPTH is
1 line. When DEPTH=*, the conversion utility will reserve the remaining
available panel depth for the scrollable area.
EXTEND=OFF | ON | FORCE
This attribute defines the run-time display size for the scrollable area. If
EXTEND=ON is specified, the panel definition is expanded from the
minimum DEPTH to the size of the logical screen. Only one EXTEND=ON
attribute value is allowed on a panel. The first tag (AREA, DA, GA,
REGION, SELFLD) with EXTEND=ON is accepted; the EXTEND attribute
on any subsequent AREA tag is ignored.

If you intend to display the panels in a pop-up window, it is recommended

that you code EXTEND=OFF.

If the EXTEND attribute is specified without a DEPTH attribute, a warning

message is issued and the EXTEND attribute is ignored.

| If EXTEND=FORCE is specified within a horizontal area, the

| EXTEND(ON) keyword is added to the scrollable area attribute statement
| in the )ATTR panel section. The conversion utility issues a message to
| advise of a potential error if other panel fields are formatted on or after the
| last defined line of the scrollable area.

214 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 AREA
DIV=NONE | BLANK | SOLID | DASH | TEXT
This attribute specifies the type of divider line to be placed before and
after the scrollable area. If this attribute is not specified, or has the value
NONE, no divider line is generated. The value BLANK produces a blank
line. You must specify SOLID, DASH, or TEXT to produce a visible divider
line. When the GRAPHIC invocation option is specified, SOLID produces a
solid line for host display and DASH produces a dashed line. When
NOGRAPHIC is specified or the panel is displayed in GUI mode, both
SOLID and DASH produce a dashed line. A visible divider formats with a
non-displayable attribute byte on each end of the line.

If the DIV attribute is found without the DEPTH attribute, a warning

message is issued and the DIV attribute is ignored.
DIVWIDTH=MAX | MIN
This attribute specifies the width of the divider line. If
DIVWIDTH=MAX, the divider line extends across the entire width of
the panel defined by the AREA tag. If DIVWIDTH=MIN, the divider
line is formatted to allow for the MARGINW and INDENT attribute
values.
FORMAT=START | CENTER | END
This attribute specifies the position of the divider-text within the divider
line. You must specify both the FORMAT attribute and the TEXT
attribute to create a divider line containing text.
TEXT=divider-text
This attribute specifies the text to be placed on the divider line. You
must specify both the FORMAT attribute and the TEXT attribute to
create a divider line containing text.
WIDTH=n
This attribute defines the width of a panel area. If WIDTH is not specified the
area formats to the remaining available panel width.
DIR=VERT | HORIZ
This attribute allows areas to be placed side by side on the panel. You use the
WIDTH attribute in combination with the DIR attribute to tell the conversion
utility to position areas horizontally. When the current horizontal AREA right
boundary reaches or exceeds the right panel boundary, the next AREA will be
formatted below the current AREA(s), at the left edge of the panel.

Description
The AREA tag defines portions of a panel body. The conversion utility uses the
DEPTH attribute value to reserve lines in the formatted panel body for a scrollable
area. The DEPTH value cannot be more than the number of panel body lines still
available for formatting when the AREA tag is processed.

The maximum DEPTH that you can specify is 2 lines less than the DEPTH value
| specified on the HELP or PANEL tag.
| Notes:
| 1. If you specify the CMDAREA tag within your DTL source file, it must appear
| before the AREA tag when DEPTH=* is specified. The AREA tag DEPTH may
| have to be adjusted to allow for additional lines which result from tags present
| within the panel definition following the end AREA tag.

Chapter 13. Tag Reference 215

 AREA
| 2. For HELP panels, the presence of additional tags following a scrollable area
| causes the conversion utility to reserve 4 lines at the bottom of the screen to
| provide for the function key area.

| The first line of the scrollable area is always reserved for the scrolling indicator
line, which is provided by ISPF at run time. If all of the scrollable portion of the
panel is displayed within the available DEPTH, the scroll indicator line is blank;
otherwise, the value “More: +”, “More: − +”, or “More: −” will appear. On
application panels, this portion includes the interactive fields and text of the panel.
On help panels, this portion is the area of the panel that contains help text.

The DIR attribute is used to place entire areas side by side on the panel.
Formatting within the AREA tag is always in a vertical direction. Panel areas are
formatted horizontally when multiple AREA tags (specifying DIR=HORIZ) are
placed sequentially in the DTL source file. Any other tag which occurs between an
end AREA tag and a start AREA tag causes the overall panel formatting direction
to be set to vertical.

Conditions
v The AREA tag requires an end tag.
v You must code AREA tags within a HELP or PANEL definition. See “HELP
(Help Panel)” on page 323 and “PANEL (Panel)” on page 397 for descriptions of
these tags.
v Only one area can be defined with EXTEND=ON. This includes other AREA
tags as well as any dynamic area defined by the DA tag, graphic area defined by
the GA tag, scrollable section lists defined by the SELFLD tag, or scrollable
regions defined by the REGION tag.

Nested Tags
Application Panel
You can code the following tags within an AREA definition on an application
panel:

Tag Name Usage Page Required

COMMENT Comment Multiple 272 No
DA Dynamic area Multiple 277 No
DIVIDER Area divider Multiple 285 No
DTACOL Data column Multiple 293 No
DTAFLD Data field Multiple 299 No
GA * Graphic area Single 316 No
GRPHDR Group header Multiple 320 No
INFO Information region Multiple 339 No
LSTFLD * List field Single 364 No
PNLINST Panel Instruction Multiple 418 No
REGION Region Multiple 424 No
SELFLD Selection field Multiple 433 No
SOURCE Source Multiple 449 No

216 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 AREA
Tag Name Usage Page Required
Note:
* This tag is not valid within a scrollable area.

Help Panel
You can code the following tag within an AREA definition on a help panel:

Tag Name Usage Page Required

COMMENT Comment Multiple 272 No
DIVIDER Area divider Multiple 285 No
INFO Information region Multiple 339 No
REGION Region Multiple 424 No

Example
The application panel in the following example contains four data fields and two
selection fields coded within the AREA definition. The top instructions and
command area are coded outside of the AREA definition. In addition, the panels
illustrate a scrollable panel. Figure 92 on page 218, Figure 93 on page 218 and
Figure 94 on page 219, show the formatted results.
<!DOCTYPE DM SYSTEM(
<!entity sampvar2 system>
<!entity sampabc system>)>
&sampvar2;

<PANEL NAME=area1 KEYLIST=keylxmp>File-A-Case

<AB>
&sampabc;
</AB>
<TOPINST COMPACT>
Type in client's name and case number (if applicable).
<TOPINST>Then select an action bar choice.
<AREA>
<DTAFLD DATAVAR=caseno PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25>Case no
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address PMTWIDTH=12 ENTWIDTH=25>Address
<DIVIDER>
<SELFLD NAME=casesel PMTWIDTH=30 PMTLOC=before SELWIDTH=38>Choose
one of the following
<CHOICE CHECKVAR=case MATCH=civ>Civil
<CHOICE CHECKVAR=case MATCH=estate>Real estate
<CHOICE CHECKVAR=case MATCH=environ>Environmental
</SELFLD>
</AREA>
<AREA DEPTH=6>
<SELFLD TYPE=multi PMTWIDTH=35 SELWIDTH=50>Check type of offense committed
<CHOICE NAME=patin HELP=patin CHECKVAR=val>Patent infringement
<CHOICE NAME=defa HELP=defame CHECKVAR=def>Defamation
<CHOICE NAME=cont HELP=cont CHECKVAR=qua>Breach of valid contract
<CHOICE NAME=priv HELP=priv CHECKVAR=pri>Invasion of privacy
<CHOICE NAME=incr HELP=incr CHECKVAR=icr>Interference with
contractual relations
<CHOICE NAME=disp HELP=disp CHECKVAR=dis>Improper disposal of
medical by-products
<CHOICE NAME=fraud HELP=fraud CHECKVAR=fra>Fraud

Chapter 13. Tag Reference 217

AREA
</SELFLD>
</AREA>
<CMDAREA>Enter a command
</PANEL>

File Search Help

-------------------------------------------------------------------------
File–A–Case

Type in client's name and case number (if applicable).

Then select an action bar choice.

Case no . . _______ (A 7-digit number)

Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following __ 1. Civil

2. Real estate
3. Environmental
More: +
Check type of offense committed
_ Patent infringement
_ Defamation
_ Breach of valid contract
Enter a command ===> ____________________________________________________
F1=Help F3=Exit F5=Display F6=Keyshelp F10=Actions
F12=Cancel

Figure 92. Application Panel Area

After scrolling, the panel appears as follows:

File Search Help

-------------------------------------------------------------------------
File–A–Case

Type in client's name and case number (if applicable).

Then select an action bar choice.

Case no . . _______ (A 7-digit number)

Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following __ 1. Civil

2. Real estate
3. Environmental
More: - +
_ Breach of valid contract
_ Invasion of privacy
_ Interference with contractual relations
_ Improper disposal of medical by-products
Enter a command ===> ____________________________________________________
F1=Help F3=Exit F5=Display F6=Keyshelp F10=Actions
F12=Cancel

Figure 93. Application Panel Area

After scrolling, the last choice in the list is visible.

218 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 AREA

File Search Help

-------------------------------------------------------------------------
File–A–Case

Type in client's name and case number (if applicable).

Then select an action bar choice.

Case no . . _______ (A 7-digit number)

Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following __ 1. Civil

2. Real estate
3. Environmental
More: -
_ Invasion of privacy
_ Interference with contractual relations
_ Improper disposal of medical by-products
_ Fraud
Enter a command ===> ____________________________________________________
F1=Help F3=Exit F5=Display F6=Keyshelp F10=Actions
F12=Cancel

Figure 94. Application Panel Area

An example of horizontal AREA formatting is shown in “Multiple AREA Tags” on

page 44 .

ASSIGNI (Assignment List Item)

The ASSIGNI tag defines an assignment in an assignment list.

ÊÊ <ASSIGNI > Ê
VALUE=test-value RESULT=assigned-value

Ê ÊÍ
</ASSIGNI>

VALUE=test-value
This attribute specifies the value to be matched when performing the
assignment.

The value of the data field variable is compared to the value of each VALUE
attribute in succession until a match is found. The test-value must be the same
case as the value to be matched. You can specify XLATL FORMAT=UPPER
within the variable class associated with the data field to convert user input to
uppercase before the assignment test is processed.

When ISPF finds a match, it assigns the value in the RESULT attribute to the
variable named on the ASSIGNL tag. If ISPF does not find a match, no
assignment is made.

If you omit this attribute, any value satisfies the test and ISPF assigns
assigned-value to the dialog variable.

If a test-value appears more than once in the list, the first occurrence is used.

Chapter 13. Tag Reference 219

ASSIGNI
RESULT=assigned-value
This attribute specifies the resulting value of the assignment if a match occurs
on the test-value specified by VALUE.

Assigned-value specifies the character string value for the conversion utility to
assign to the variable named on the ASSIGNL tag. If you omit this attribute,
the test-value is assigned to the variable.

Description
The ASSIGNI tag defines an assignment in an assignment list. Each ASSIGNI tag
provides information necessary to assign a value (the RESULT attribute) to a
variable (specified with the ASSIGNL tag) based on the test-value (the VALUE
attribute) of the variable named on the DTAFLD tag. As many ASSIGNI tags as are
necessary (up to a limit of 126) can be included within the assignment list. The
ISPF TRANS() function is used for ASSIGNI processing.

If both the VALUE and RESULT attributes are omitted, the DESTVAR attribute of
the ASSIGNL tag is assigned the value of the data field’s data variable
(DATAVAR).

Conditions
v You must code an ASSIGNI tag within an ASSIGNL definition. See “ASSIGNL
(Assignment List)” on page 221 for a complete description of this tag.

Nested Tags
None.

Example
The following source file markup contains an application panel containing a data
field. Within the data field is an assignment list that sets the dialog variable rmtype
to 1 when “SINGLE” is entered in the data field, or to 2 when “DOUBLE” is
entered in the data field. The associated variable declarations and variable classes
are also shown.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=roomvar TYPE='char 6'>

<XLATL FORMAT=upper>
</XLATL>

<VARCLASS NAME=rmtypvar TYPE='char 1'>

<VARLIST>
<VARDCL NAME=room VARCLASS=roomvar>
<VARDCL NAME=rmtype VARCLASS=rmtypvar>
</VARLIST>

<PANEL NAME=assigni DEPTH=12 WIDTH=50>Hotel Register

<AREA>
<DTAFLD DATAVAR=room ENTWIDTH=6 DESWIDTH=20 PMTWIDTH=15>Room type
<ASSIGNL DESTVAR=rmtype>
<ASSIGNI VALUE=SINGLE RESULT=1>
<ASSIGNI VALUE=DOUBLE RESULT=2>
</ASSIGNL>
<DTAFLDD>(Single or Double)
</AREA>
<BOTINST>Press Enter to continue.
</PANEL>

220 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 ASSIGNL

ASSIGNL (Assignment List)

The ASSIGNL tag defines an assignment list.

ÊÊ <ASSIGNL DESTVAR=destination-variable-name > </ASSIGNL> ÊÍ

DESTVAR=destination-variable-name
DESTVAR specifies the variable that receives the assignment value. You can
code multiple assignment lists if you need to assign values to additional
variables.

Note: If the destination-variable-name is a variable name used for another field

on the panel, the value of the other field will be overlaid by the
assignment value. The destination-variable-name should only be used for
an output field variable.

Description
The ASSIGNL tag defines an assignment list. ASSIGNI tags, which define the
elements of the assignment list, are coded within the ASSIGNL tag.

Assignment lists are optional and provide a means of assigning a value to one
variable based on the content of another. ISPF compares the value of the variable
specified with the DATAVAR attribute of the DTAFLD tag against the values in the
ASSIGNI tags.

Processing of assignment lists occurs at panel end (after translates and checks).

Conditions
v The ASSIGNL tag requires an end tag.
v You must code an ASSIGNL tag within the DTAFLD definition it is associated
with. See “DTAFLD (Data Field)” on page 299 for a complete description of this
tag.

Nested Tags
You can code the following tag within an ASSIGNL definition:

Tag Name Usage Page Required

ASSIGNI Assignment list item Multiple 219 No

Example
The assignment list in the following markup assigns a value to the variable decimal
dependent on the value the user enters in the data field variable hexvar. The
associated variable declarations and variable classes are also shown.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=varcls1 TYPE='char 1'>

<VARCLASS NAME=varcls2 TYPE='char 2'>

<VARLIST>
<VARDCL NAME=hexvar VARCLASS=varcls1>
<VARDCL NAME=decimal VARCLASS=varcls2>

Chapter 13. Tag Reference 221

ASSIGNL
</VARLIST>

<PANEL NAME=assignl>Hex to Decimal

<TOPINST>Enter a hexadecimal digit.
<AREA>
<DTAFLD DATAVAR=hexvar PMTWIDTH=23 ENTWIDTH=1>Hexadecimal Value
<ASSIGNL DESTVAR=decimal>
<ASSIGNI VALUE=0>
<ASSIGNI VALUE=1>
<ASSIGNI VALUE=2>
<ASSIGNI VALUE=3>
<ASSIGNI VALUE=4>
<ASSIGNI VALUE=5>
<ASSIGNI VALUE=6>
<ASSIGNI VALUE=7>
<ASSIGNI VALUE=8>
<ASSIGNI VALUE=9>
<ASSIGNI VALUE=a RESULT=10>
<ASSIGNI VALUE=b RESULT=11>
<ASSIGNI VALUE=c RESULT=12>
<ASSIGNI VALUE=d RESULT=13>
<ASSIGNI VALUE=e RESULT=14>
<ASSIGNI VALUE=f RESULT=15>
<ASSIGNI RESULT="??">
</ASSIGNL>
<DTAFLD DATAVAR=decimal USAGE=out PMTWIDTH=23 ENTWIDTH=2>Decimal Value
</AREA>
</PANEL>

ATTENTION (Attention)
The ATTENTION tag defines text that alerts the user to a risk of possible error
conditions in the system.

ÊÊ <ATTENTION> </ATTENTION> ÊÍ
text

text
This is the text of the attention message.

Description
The ATTENTION tag defines text that alerts the user to a risk of possible error
conditions in the system.

The ATTENTION tag is one of the tags that alert the user of a possible risk;
CAUTION and WARNING are the others.

Code an attention statement before the text to which it pertains so that the user
can read about the possible risks before reading the text.

When an attention statement is displayed, the string “Attention:” (or its translated
equivalent) appears on the screen before the text of the statement.

You can code additional paragraphs of text by coding the P (paragraph) tag within
an ATTENTION definition. You can also code other tags allowed in an information
area within an ATTENTION definition.

222 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 ATTENTION
Conditions
v The ATTENTION tag requires an end tag.
v You must code the ATTENTION tag within an INFO definition. See “INFO
(Information Region)” on page 339 for a complete description of this tag.
v The ATTENTION tag must be immediately preceded by a P, LI, or LP tag. If the
ATTENTION tag is coded on the same line as one of these tags, there can be no
intervening blanks. See “P (Paragraph)” on page 390, “LI (List Item)” on
page 346, and “LP (List Part)” on page 352 for descriptions of these tags.
v You cannot nest ATTENTION, WARNING or CAUTION tags within each other.

Nested Tags
You can code the following tags within an ATTENTION definition:

Tag Name Usage Page Required

DL Definition list Multiple 288 No
FIG Figure Multiple 312 No
HP Highlighted phrase Multiple 336 No
LINES Lines Multiple 349 No
NOTE Note Multiple 382 No
NOTEL Note List Multiple 384 No
NT Note Multiple 386 No
OL Ordered list Multiple 387 No
P Paragraph Multiple 390 No
PARML Parameter list Multiple 408 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
SL Simple list Multiple 447 No
UL Unordered list Multiple 457 No
XMP Example Multiple 474 No

Example
The following help panel markup contains a warning statement. The warning
statement starts at the left margin because it is imbedded in the LP tag.
<!DOCTYPE DM SYSTEM>

<HELP NAME=attentn DEPTH=20>Help For Changing a File

<AREA>
<INFO>
<OL>
<LI>Type over the existing data
in the entry fields with the new data.
<LP><ATTENTION>Performing the next step will save
all changes and delete the existing data.
<P>To quit this function without
deleting the existing data, press F12.
</ATTENTION>
<LI>Press Enter to save the
updated data.

Chapter 13. Tag Reference 223

 ATTENTION
</OL>
</INFO>
</AREA>
</HELP>

Help For Changing a File

1. Type over the existing data in the entry

fields with the new data.

Attention: Performing the next step will save all

changes and delete the existing data.

To quit this function without deleting the

existing data, press F12.

2. Press Enter to save the updated data.

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 95. Attention Statement

ATTR (Attribute)
| The ATTR tag defines a panel attribute used within a dynamic area or a
| preformatted displayable panel section. Refer to the ISPF User’s Guide for a
| complete discussion of panel )ATTR section keywords.

ÊÊ <ATTR ATTRCHAR=code TYPE= DATAIN Ê

DATAOUT HIGH
CHAR INTENS= LOW
NON
%varname

Ê Ê
CAPS= OFF JUST= ASIS PAD= NULLS
ON LEFT USER
IN RIGHT char
OUT %varname %varname
%varname

Ê Ê
PADC= NULLS OFF OFF
USER SKIP= ON GE= ON
char %varname %varname
%varname

224 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 ATTR
Ê Ê
COLOR= WHITE HILITE= USCORE
RED BLINK
BLUE REVERSE
GREEN %varname
PINK
YELLOW
TURQ
%varname

Ê Ê
OFF FORMAT= EBCDIC
NUMERIC= ON DBCS
%varname MIX
%varname

Ê Ê
NONE OFF OFF
OUTLINE= L PAS= ON CKBOX= ON
R %varname %varname
O
U
BOX
%varname

Ê Ê
CUADYN= CEF NO
EE CSRGRP= YES
LEF n
NEF
VOI
LID
LI
CH
CT
DT
ET
FP
NT
PIN
PT
SAC
SI
SUC
WASL
WT
%varname

Ê > ÊÍ
OFF </ATTR>
ATTN= ON
%varname

ATTRCHAR=code
This attribute can be a single character or a two-position entry of valid hex

Chapter 13. Tag Reference 225

 ATTR
digits. If you enter an incorrect value, a warning message is issued and the
value is set to null. Hex entries are converted to character. Hex values ‘00’–‘2F’
are reserved for use by the conversion utility.
TYPE=DATAIN | DATAOUT | CHAR
This attribute specifies the characteristic of the field within the dynamic area.
Use DATAIN and DATAOUT attribute values for specifying unprotected or
protected fields, respectively, within the dynamic area. The CHAR attribute
value defines a character attribute that is recognized only when found within a
shadow variable.

| When the ATTR tag is coded within the GENERATE tag, TYPE can also be
| specified as any CUA attribute type, or as %varname.
INTENS=HIGH | LOW | NON | %varname
This attribute defines the intensity of a field. You can define this attribute as a
variable name preceded by a “%”.
CAPS=OFF | ON | IN | OUT | %varname
This attribute specifies the uppercase or lowercase attribute of a field. You can
define this attribute as a variable name preceded by a “%”.
JUST=ASIS | LEFT | RIGHT | %varname
This attribute specifies how the contents of the field are to be justified when
displayed. You can define this attribute as a variable name preceded by a “%”.
PAD=NULLS | USER | char | %varname
This attribute specifies the pad character for initializing the field. You can
define this attribute as a variable name preceded by a “%”.
PADC=NULLS | USER | char | %varname
This attribute specifies the conditional padding character to be used for
initializing the field. You can define this attribute as a variable name preceded
by a “%”.
SKIP=OFF | ON | %varname
This attribute specifies the autoskip attribute of the field. You can define this
attribute as a variable name preceded by a “%”.
GE=OFF | ON | %varname
This attribute specifies that ISPF will place a graphic escape order before the
character defined as a character level attribute by TYPE=CHAR. You can define
this attribute as a variable name preceded by a “%”.
COLOR=WHITE | RED | BLUE | GREEN | PINK | YELLOW | TURQ |
%varname
This attribute specifies the color of the field. You can define this attribute as a
variable name preceded by a “%”.
HILITE=USCORE | BLINK | REVERSE | %varname
This attribute specifies the extended highlighting attribute of the field. You can
define this attribute as a variable name preceded by a “%”.
NUMERIC=OFF | ON | %varname
This attribute specifies whether Numeric Lock is to be activated for data typed
in the field. You can define this attribute as a variable name preceded by a
“%”.
FORMAT=EBCDIC | DBCS | MIX | %varname
This attribute specifies the character format for the field. You can define this
attribute as a variable name preceded by a “%”.

226 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 ATTR
OUTLINE=NONE | L | R | O | U | BOX | %varname
This attribute provides for displaying lines around the field on a DBCS
terminal. You can define this attribute as a variable name preceded by a “%”.
PAS=OFF | ON | %varname
This attribute controls the availability of the point-and-shoot function for
dynamic areas. You can define this attribute as a variable name preceded by a
“%”.
CKBOX=OFF | ON | %varname
This attribute controls the generation of check boxes for dynamic areas when
the panel is displayed while running in GUI mode. You can define this
attribute as a variable name preceded by “%”.
CUADYN=CEF | EE | LEF | NEF | VOI | LID | LI | CH | CT | DT | ET |
FP | NT | PIN | PT | SAC | SI | SUC | WASL | WT | %varname
This attribute specifies a standard CUA attribute for the DATAIN and
DATAOUT panel attribute definitions.

Values CEF, EE, LEF, and NEF are valid when TYPE=DATAIN. The remaining
values are valid when TYPE=DATAOUT. You can define this attribute as a
variable name preceded by a “%”.

The conversion utility will issue a warning message if the CUADYN attribute
is specified and the invocation option is NOCUAATTR.
CSRGRP=NO | YES | n
The CSRGRP attribute is valid only when TYPE=DATAOUT. When
CSRGRP=YES, the conversion utility generates a cursor group number to be
used for this DATAOUT attribute. When CSRGRP=n, the number provided is
used for this attribute. The PAS attribute must be specified as ON or
%varname.
| ATTN=NO | YES | %varname
| This attribute specifies the attention-select attribute of the field. You can define
| this attribute as a variable name preceded by a ″%″.

Description
| The ATTR tag is used to create an entry in the )ATTR panel section for fields to be
| displayed within a dynamic area, or preformatted panel section.

Conditions
| v You must code an ATTR tag within a Dynamic Area or GENERATE tag
| definition. See “DA (Dynamic Area)” on page 277 and “GENERATE (Generate)”
| on page 318 for a complete description of these tags.
v If ATTRCHAR is not specified, an error is logged and the output panel is not
saved.
v If ATTRCHAR is a duplicate of a previously specified attribute, or conflicts with
an attribute reserved by the conversion utility, an error is logged and the output
panel is not saved.
v If TYPE is not specified, an error is logged and the output panel is not saved. If
TYPE is specified, but the value is invalid, the value is set to DATAIN.
v If both PAD and PADC have been specified, PAD is ignored and PADC is used.
v When a “%varname” notation is found on any of the attributes that allow a
variable name, the “%varname” entry must follow the standard naming
convention described in “Rules for “%variable” Names” on page 201.

Chapter 13. Tag Reference 227

ATTR
Nested Tags
None.

Example
<!DOCTYPE DM SYSTEM(
<!entity sampvar1 system>
<!entity sampabc system>)>
&sampvar1;

<PANEL NAME=attr KEYLIST=keylxmp>Library Card Registration

<AB>
&sampabc;
</AB>
<TOPINST> Type in patron's name and card number (if applicable)
<AREA>
<DTACOL PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25 SELWIDTH=25>
<DTAFLD DATAVAR=curdate USAGE=out ENTWIDTH=8>Date
<DTAFLD DATAVAR=cardno ENTWIDTH=7>Card No.
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address>Address
</DTACOL>
<DIVIDER>
<DA NAME=darea DIV=solid DEPTH=6 SHADOW=shadwvar>
<ATTR ATTRCHAR=# TYPE=datain PADC='_' COLOR=BLUE>
<ATTR ATTRCHAR=| TYPE=dataout COLOR=green>
<ATTR ATTRCHAR=$ TYPE=char COLOR=red>
</DA>
</AREA>
<CMDAREA>Enter a command
</PANEL>

BOTINST (Bottom Instruction)

The BOTINST tag defines bottom instructions for an application panel.

ÊÊ <BOTINST > ÊÍ
COMPACT instruction-text </BOTINST>

COMPACT
This attribute causes the bottom instruction to format without a blank line
before the text.
instruction-text
This is the text of the bottom instruction. The instruction-text must fit in the
remaining panel depth.

Description
The BOTINST tag defines bottom instructions for an application panel. The
instruction-text formats as a paragraph based on the width of the application panel.
You can code multiple paragraphs of instruction text by using a new bottom
instruction tag for each new paragraph.

If the COMPACT attribute is not specified, the conversion utility inserts a blank
line before the bottom instruction text.

228 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 BOTINST
Conditions
v You must code the BOTINST within a PANEL definition. See “PANEL (Panel)”
on page 397 for a complete description of this tag.
v You cannot code a BOTINST tag within an AREA definition. If you define an
area for the panel, code the BOTINST tag after the AREA end tag.

Nested Tags
You can code the following tags within a BOTINST definition:

Tag Name Usage Page Required

HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No

Example
The following application panel markup contains two bottom instructions.
Figure 96 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=choiccls TYPE='char 2'>

<VARLIST>
<VARDCL NAME=choices VARCLASS=choiccls>
</VARLIST>

<PANEL NAME=botinst1 WIDTH=35 DEPTH=22>Four Choices

<AREA>
<SELFLD NAME=choices PMTWIDTH=20 SELWIDTH=33>Choose one:
<CHOICE>Raindrops on roses
<CHOICE>Whiskers on kittens
<CHOICE>Bright copper kettles
<CHOICE>Warm woolen mittens
</SELFLD>
</AREA>
<BOTINST>Press Enter to continue.
<BOTINST>Press F12 to cancel.
</PANEL>

Chapter 13. Tag Reference 229

 CAUTION

Four Choices

Choose one:
__ 1. Raindrops on roses
2. Whiskers on kittens
3. Bright copper kettles
4. Warm woolen mittens

Press Enter to continue.

Press F12 to cancel.

F1=Help F3=Exit F12=Cancel

Figure 96. Bottom Instructions

CAUTION (Caution)
The CAUTION tag defines a statement that alerts the user of a possible risk.

ÊÊ <CAUTION> </CAUTION> ÊÍ
text

text
This is the text of the caution statement.

Description
The CAUTION tag defines a statement that alerts the user of a possible risk. Use
the CAUTION tag to alert the user to a condition that might have serious
consequences, such as the deletion of a file.

| The CAUTION tag is one of the tags that alert the user to a possible risk; the
| others are ATTENTION and WARNING.

Code a caution statement before the text to which it pertains so that the user can
read about the possible risks before reading the text. When a caution statement is
displayed, the string “CAUTION:” or its translated equivalent appears on the
screen and the caution text displays on the following line.

You can code additional paragraphs of caution text by coding the P (paragraph)
tag within a CAUTION definition. You can also code other tags allowed in an
information area within a CAUTION definition.

CAUTION text is formatted with an attribute byte that causes it to be emphasized.

Conditions
v The CAUTION tag requires an end tag.

230 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CAUTION
v A CAUTION tag must be immediately preceded by an LI, LP, or P tag. See “LI
(List Item)” on page 346, “LP (List Part)” on page 352, and “P (Paragraph)” on
page 390 for descriptions of these tags.
v You must code the CAUTION tag only within an INFO definition. See “INFO
(Information Region)” on page 339 for a complete description of this tag.
v You cannot nest ATTENTION, CAUTION, or WARNING tags within each other.

Nested Tags
You can code the following tags within a CAUTION definition:

Tag Name Usage Page Required

DL Definition list Multiple 288 No
FIG Figure Multiple 312 No
HP Highlighted phrase Multiple 336 No
LINES Lines Multiple 349 No
NOTE Note Multiple 382 No
NOTEL Note list Multiple 384 No
NT Note Multiple 386 No
OL Ordered list Multiple 387 No
P Paragraph Multiple 390 No
PARML Parameter list Multiple 408 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
SL Simple list Multiple 447 No
UL Unordered list Multiple 457 No
XMP Example Multiple 474 No

Example
The following help panel markup contains a caution statement. Figure 97 on
page 232 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=caution DEPTH=20>Help for DELETE Command

<AREA>
<INFO>
<P>The DELETE command erases the specified file from storage.
<P><CAUTION>
Issuing the DELETE command permanently
removes the file from storage.
There is no possibility of recovery.
</CAUTION>
<P>You can exit from the DELETE operation
by pressing F12.
</INFO>
</AREA>
</HELP>

Chapter 13. Tag Reference 231

CHDIV

Help for DELETE Command

The DELETE command erases the specified file

from storage.

CAUTION:
Issuing the DELETE command permanently removes
the file from storage. There is no possibility
of recovery.

You can exit from the DELETE operation by

pressing F12.

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 97. Caution Statement

CHDIV (Choice Divider)

The CHDIV tag creates a blank or visible divider between CHOICE tags.

ÊÊ <CHDIV Ê
NONE 1 START
TYPE= SOLID GUTTER= n FORMAT= CENTER
DASH END
TEXT

Ê > ÊÍ
divider-text </CHDIV>

TYPE=NONE | SOLID | DASH | TEXT

This attribute specifies the type of divider line. The line width is one character.

The default value is none, which produces a blank line. You must specify solid,
dash, or text to produce a visible divider line. When the GRAPHIC invocation
option is specified, SOLID produces a solid line for host display and DASH
produces a dashed line. When NOGRAPHIC is specified or the panel is
displayed in GUI mode, both SOLID and DASH produce a dashed line.
GUTTER=1 | n
This attribute specifies the total width of the divider. If the GUTTER value is
an even number, the conversion utility increases the number by 1 so that the
divider is centered within the defined width.

The minimum and default GUTTER value is 1.

FORMAT=START | CENTER | END
This attribute specifies the position of the divider text within the width of the
divider line. The divider width is the same as the CHOICE tag text formatting
width.
divider-text
This is the text of the choice divider.

232 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CHDIV
Description
The CHDIV tag creates a blank or solid divider between CHOICE tags.

Conditions
v You must code the CHDIV tag within an SELFLD definition. See “SELFLD
(Selection Field)” on page 433 for a description of this tag.

Nested Tags
You can code the following tags within a CHDIV definition:

Tag Name Usage Page Required

HP Highlighted phrase Multiple 336 No

Example
The following example illustrates the creation of an ISPF selection menu. The
CHDIV tag is included to separate the Exit option from the other selection choices.
The FCHOICE attribute specifies that the first selection number is 0. The choice
selection for Exit is specified on the CHOICE tag. The ACTION tag for the Exit
choice selection specifies both the RUN and TYPE attributes because RUN is
required on the ACTION tag and TYPE is necessary to specify the ISPF selection
for the generated ZSEL panel statement.
<!doctype dm system ()>
<!-- Sample selection menu -->
<varclass name=vc1 type='char 80'>
<xlatl format=upper>
</xlatl>

<varlist>
<vardcl name=zcmd varclass=vc1>
</varlist>

<panel name=chdiv1 menu keylist=keylxmp>

Sample Selection Panel with CHDIV tag
<topinst>This is a selection panel.
<selfld type=menu pmtloc=before fchoice=0 trail=nextsel
selwidth=40 pmtwidth=10>Select an option
<choice checkvar=xtest1 match=a>
Selection #0 (Command Selch0)
<action run=Selch0>
<choice checkvar=xtest1 match=b>
Selection #1 (Command Selch1)
<action run=Selch1 parm='1 2 3 4'
passlib newpool suspend>
<choice checkvar=xtest1 match=c>
Selection #2 (Command Selch2)
<action run=Selch2 parm=1234>
<choice checkvar=xtest1 match=d>
Selection #3 (Command Selch3)
<action run=Selch3 parm=abcd>
<choice checkvar=xtest1 match=e>
Selection #4 (Command Selch4)
<action run=Selch4 parm='a b c d'>
<chdiv>
<choice selchar=X>
Exit
<action run=exit type=exit>
</selfld>
<cmdarea>
</panel>

Chapter 13. Tag Reference 233

CHDIV
Figure 98 shows the formatted result.

Sample Selection Panel with CHDIV tag

Option ===> _____________________________________________________________

This is a selection panel.

Select an
option . . 0 Selection #0 (Command Selch0)
1 Selection #1 (Command Selch1)
2 Selection #2 (Command Selch2)
3 Selection #3 (Command Selch3)
4 Selection #4 (Command Selch4)

X Exit

Option ===> _____________________________________________________________

F1=Help F3=Exit F5=Display F6=Keyshelp F10=Actions
F12=Cancel

Figure 98. Choice Divider

CHECKI (Validity Check Item)

The CHECKI tag defines a test of an input value.

ÊÊ <CHECKI TYPE= Ê

234 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CHECKI
Ê RANGE PARM1= low-bound PARM2= high-bound Ê
%varname %varname
ALPHA
CHARS PARM1=EQ PARM2=character-set
VALUES PARM1=EQ PARM2=value-list
VALUESX PARM1=NE PARM2=value-list
BIT
NAME
NAMEF
PICT PARM1=EQ PARM2=pictstring
PICTCN PARM1=mask-character PARM2=field-mask PARM3=string
NUM
DBCS
LISTV PARM1=EQ PARM2=%varlist
LISTVX PARM1=NE PARM2=%varlist
ALPHAB
LEN PARM1= operator PARM2= length
%varname %varname
EBCDIC
ENUM
DSNAME
DSNAMEF
DSNAMEFM
DSNAMEPQ
DSNAMEQ
MIX
HEX
FILEID
INCLUDE PARM2= ALPHA
PARM1=IMBLK ALPHAB PARM3= ALPHA
NUM ALPHAB
NUM
IDATE
STDDATE
JDATE
JSTD
ITIME
STDTIME

Ê > ÊÍ
</CHECKI>

TYPE=
This attribute specifies the type of check to be performed. The valid types are:
RANGE

This allows you to check for an integer value within a range. The specified
range includes the end points. The range delimiters can include 16 digits.
The range delimiters can also contain a sign (− or +). If no sign is coded,
the value is assumed to be positive.

Chapter 13. Tag Reference 235

CHECKI
Attention:

In ISPF, the VER(variable RANGE,lower,upper) statement limits the length

of the specified variable to 16 digits. If the application developer specifies
the CHECKI TYPE=RANGE on a variable that is longer than 16 positions
in length, the variable may not be correctly validated.

For example, assume an application developer defines a data field with a

length of 20 and defines the following validity check for the field:
<CHECKI TYPE=RANGE PARM1=1 PARM2=9999999999999999>

If the number 12345678901234567890 were entered into the field, only the
first 16 digits of the field would be verified and the number would be
within the defined range, even though the entire number entered is outside
of the defined range.
PARM1=low-bound | %varname
This attribute supplies the low value, if any or the name of a variable
that contains the low value. If you do not supply a value, the default is
“−” followed by sixteen 9s (that is, −9999...99). Negative values must
be coded with the minus sign on the left.

ISPF restrictions on the VER(variable RANGE,lower,upper) apply. The

lower value specified in PARM1 can be positive or negative. The
length of the lower limit is limited to 16 digits, in addition to the plus
or minus sign if used.
PARM2=high-bound | %varname
This attribute supplies the high value, if any or the name of a variable
that contains the high value. If you do not supply a value, the default
is sixteen 9s (that is, 9999...99). Negative values must be coded with the
minus sign on the left.

ISPF restrictions on the VER(variable RANGE,lower,upper) apply. The

upper value specified in PARM2 can be positive or negative. The
length of the upper limit is limited to 16 digits, in addition to the plus
or minus sign if used.
ALPHA
This limits the character set to A–Z, a–z, and #, $, @. The conversion utility
builds the VER(variable ALPHA) statement.
CHARS
Specifies the CHARS check of characters allowed within an input string.

The conversion utility uses the TYPE=CHARS check to support ISPF

VER(variable BIT), VER(variable HEX) and VER(variable NUM). BIT, HEX,
and NUM are the only types of support provided by ISPF for the
TYPE=CHARS check.
PARM1=EQ
This attribute contains EQ to specify that PARM2 contains a value that
must be matched. If PARM1 contains any other value, the check is
ignored and the conversion utility issues a warning message.
PARM2=character-set
This attribute specifies a set of characters to be matched.
v If TYPE=CHARS, PARM1=‘EQ’, and PARM2=‘01’, the conversion
utility generates VER(variable BIT).

236 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CHECKI
v If TYPE=CHARS, PARM1=‘EQ’, and
PARM2=‘0123456789ABCDEFabcdef’, the conversion utility generates
VER(variable HEX).
v If TYPE=CHARS, PARM1=‘EQ’, and PARM2=‘0123456789’, the
conversion utility generates VER(variable NUM).

Note: If these options are used, the PARM2 value must be specified
exactly as shown above.
v If PARM2 contains any other values, the check is ignored and the
conversion utility issues a warning message.
VALUES
Specifies that the value entered must be the same as one of the values
specified in PARM2.

The VER LIST statement built by the conversion utility is case-sensitive to

the values entered in PARM2 (no folding of PARM2 to uppercase). This
means that ISPF looks for an exact match in the verification process. You
can specify XLATL FORMAT=UPPER within the variable class definition
before the CHECKL tag to convert user input to uppercase before the
VALUES check is processed.
PARM1=EQ
This attribute contains EQ to specify that PARM2 contains values that
must be matched. If PARM1 contains any other value, the check is
ignored and the conversion utility issues a warning message.
PARM2=value-list
This attribute specifies the list of values. If the list contains more than
one value, it must be enclosed in quotes. If a value in the list contains
blanks, then it must be enclosed in single quotes and the entire list
enclosed in double quotes. Each value in the list must be separated by
blanks or enclosed quotes. For example:
dog
‘dog cat bird lion’
“parsley onion ‘black pepper’ garlic”

The maximum number of values allowed is 100.

Note: You should surround the entire value for PARM2 with double
quotes and then surround any value in the list that contains
blanks with single quotes. Double quotes surrounding a list are
supported by the conversion utility.

The conversion utility generates VER(variable LIST,value-list) from PARM2.

VALUESX
Specifies that the value entered cannot be any of the values specified in
PARM2. This is the opposite of VALUES.

The VER LISTX statement built by the conversion utility is case-sensitive to

the values entered in PARM2 (no folding of PARM2 to uppercase). This
means that ISPF looks for an exact match in the verification process. You
can specify XLATL FORMAT=UPPER within the variable class definition
before the CHECKL tag to convert user input to uppercase before the
VALUES check is processed.

Chapter 13. Tag Reference 237

 CHECKI
PARM1=NE
This attribute contains NE to specify that PARM2 contains values that
cannot be entered. If PARM1 contains any other value, the check is
ignored and the conversion utility issues a warning message.
PARM2=VALUE-LIST
This attribute specifies the list of values. If the list contains more than
one value, it must be enclosed in quotes. If a value in the list contains
blanks, then it must be enclosed in single quotes and the entire list
enclosed in double quotes. Each value in the list must be separated by
blanks or enclosed quotes. For example:
dog
‘dog cat bird lion’
“parsley onion ‘black pepper’ garlic”

The maximum number of values allowed is 100.

Note: You should surround the entire value for PARM2 with double
quotes and then surround any value in the list that contains
blanks with single quotes. Double quotes surrounding a list are
supported by the conversion utility.

The conversion utility generates VER(variable LISTX,value-list) from

PARM2.
BIT
Specifies that the variable must be all 0’s and 1’s. The conversion utility
builds the VER(variable BIT) statement.
NAME
Specifies that the variable must contain a valid name, following the rules
of member names. The conversion utility builds the VER(variable NAME)
statement.
| NAMEF
| Specifies that the variable must contain a valid name filter. The conversion
| utility builds the VER(variable NAMEF) statement.
PICT
Specifies that the variable must contain characters that match the
corresponding type of character in pictstring.
PARM1=EQ
This attribute contains EQ to specify that PARM2 contains values that
must be matched. If PARM1 contains any other value, the check is
ignored and the conversion utility issues a warning message.
PARM2=pictstring
This ‘pictstring’ parameter must be the actual value to be used in the
generated VER statement. ISPF does not support a variable name for
this value.

If PARM2 contains invalid characters as defined by ISPF, the check is

ignored and the conversion utility issues a warning message.

The conversion utility builds the VER(variable PICT,pictstring) statement.

| PICTCN
| Specifies that the variable must contain specific constants along with other
| standard ISPF picture verification characters.

238 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CHECKI
| PARM1=mask-character
| The mask-character is any special character that represents itself. It
| cannot be one of the ISPF picture string characters (C,A,N,X,9,c,a,n,x)
| PARM2=field-mask
| The field-mask provides the required characters for the field. All other
| field positions must be represented by the mask-character. For
| example, if the field is to contain a string VnnRnnMnn (for Version,
| Release, and Modification) and the mask-character is an asterisk (*), the
| field mask is V**R**M**.
| PARM3=string
| The string must be the same length as the field-mask. It contains all of
| the required characters in the same positions as the field-mask. The
| positions defined with the mask-character in the field-mask contain
| one of the standard ISPF picture characters (C,A,N,X,9,c,a,n,x). To
| complete the example used above, the string is VnnRnnMnn. The
| resulting verification statement is:
| VER(variable,PICTCN,*,V**R**M**,VnnRnnMnn)
|

| The variable is verified for V in position 1, R in position 4, M in

| position 7, and numeric characters in positions 2,3,5,6,8, and 9.

| The conversion utility builds the VER(variable,PICTCN,mask-

| character,field-mask,string) statement.
NUM
Specifies that the variable must contain all numeric characters (0–9). The
conversion utility builds the VER(variable NUM) statement.
DBCS
Specifies that the variable must contain all valid DBCS characters. The
conversion utility builds the VER(variable DBCS) statement.
LISTV
Specifies that the variable must be one of the values provided by varlist.
PARM1=EQ
This attribute contains EQ to specify that PARM2 contains values that
must be matched. If PARM1 contains any other value, the check is
ignored and the conversion utility issues a warning message.
PARM2=%varlist
This attribute must be a variable name entered with “%” as the first
character. The variable contents are provided by the application and
must be a list of valid values.

The conversion utility builds the VER(variable LISTV,&varlist) statement.

LISTVX
Specifies that the variable cannot be any of the values provided by varlist.
This is the opposite of LISTV.
PARM1=NE
This attribute contains NE to specify that PARM2 contains values that
cannot be entered. If PARM1 contains any other value, the check is
ignored and the conversion utility issues a warning message.
PARM2=%VARLIST
This attribute must be a variable name entered with “%” as the first

Chapter 13. Tag Reference 239

 CHECKI
character. The variable contents are provided by the application and
must be a valid list of excluded values.

The conversion utility builds the VER(variable LISTVX,&varlist) statement.

ALPHAB
Specifies that the variable must be all alphabetic characters (A–Z or a–z).
The conversion utility builds the VER(variable ALPHAB) statement.
LEN
Specifies that the variable must satisfy the condition expressed by the
relational operator and the expected length.
PARM1=operator | %varname
This attribute can be a relational operator (EQ, LT, GT, LE, GE, NE,
NG, or NL) or a variable name that contains a relational operator. If a
variable name is entered, it must be preceded by a “%”.
PARM2=length | %varname
The parameter must be either a number or a variable name. If a
number is entered, it must be in the range of 1–99999. If a variable
name is entered, it must be preceded by a “%”.

The conversion utility builds the VER(variable operator,length) statement.

EBCDIC
Specifies that the variable must contain all valid EBCDIC characters. The
conversion utility builds the VER(variable EBDIC) statement.
ENUM
Specifies that the variable can contain extended numeric notation. The
conversion utility builds the VER(variable ENUM) statement.
DSNAME
Specifies that the variable must contain a valid TSO data set name. The
conversion utility builds the VER(variable DSNAME) statement.
| DSNAMEF
| Specifies that the variable must contain a valid TSO data set name filter.
| The optional member name cannot be specified as a member pattern. A
| missing close parentheses and ending quotation mark are automatically
| added by ISPF. The conversion utility builds the VER(variable DSNAMEF)
| statement.
| DSNAMEFM
| Specifies that the variable must contain a valid data set name. The optional
| member name can be specified as a member pattern. A missing close
| parentheses and ending quotation mark are automatically added by ISPF.
| The conversion utility builds the VER(variable DSNAMEFM) statement.
| DSNAMEPQ
| Specifies that the variable must contain a valid TSO data set name. A
| missing close parentheses and ending quotation mark are automatically
| added by ISPF. The conversion utility builds the VER(variable
| DSNAMEPQ) statement.
| DSNAMEQ
| Specifies that the variable must contain a valid TSO data set name. A
| missing ending quotation mark is automatically added by ISPF. The
| conversion utility builds the VER(variable DSNAMEQ) statement.

240 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CHECKI
MIX
Specifies that the variable must contain all valid DBCS and EBCDIC
characters. The conversion utility builds the VER(variable MIX) statement.
HEX
Specifies that the variable must contain all hexadecimal characters (0–9, a–f
or A–F). The conversion utility builds the VER(variable HEX) statement.
FILEID
Specifies that the variable must contain a valid file ID in CMS syntax. The
conversion utility builds the VER(variable FILEID) statement.

Refer to the ISPF User’s Guide for additional information concerning panel
variable validation.
INCLUDE
Specifies that the variable must contain valid characters from at least one
of the ISPF defined VER groups ALPHA, ALPHAB or NUM.
PARM1=IMBLK
This attribute contains IMBLK to specify that the IMBLK keyword be
added to the generated VER statement. If PARM1 contains any other
value, it will be reset to the value IMBLK.
PARM2=ALPHA | ALPHAB | NUM
This attribute must contain either the value ALPHA, ALPHAB, or
NUM. If PARM2 is not specified or contains any other value, the
INCLUDE check is ignored and the conversion utility issues a warning
message.
PARM3=ALPHA | ALPHAB | NUM
This attribute must contain either the value ALPHA, ALPHAB, or
NUM. The value specified for PARM3 should be different than the
value specified for PARM2. If the values for PARM2 and PARM3 are
the same, the PARM3 value is ignored and the conversion utility issues
a warning message.

The conversion utilty builds the VER(variable INCLUDE [,IMBLK], parm2

[,parm3]) statement.
| IDATE
| Specifies that the variable must contain a valid 8 character international
| date. The conversion utility builds the VER(variable,IDATE) statement.
| STDDATE
| Specifies that the variable must contain a valid 10 character standard date.
| The conversion utility builds the VER(variable,STDDATE) statement.
| JDATE
| Specifies that the variable must contain a valid 6 character Julian date. The
| conversion utility builds the VER(variable,JDATE) statement.
| JSTD
| Specifies that the variable must contain a valid 8 character standard Julian
| date. The conversion utility builds the VER(variable,JSTD) statement.
| ITIME
| Specifies that the variable must contain a valid 5 character international
| time. The conversion utility builds the VER(variable,ITIME) statement.

Chapter 13. Tag Reference 241

 CHECKI
| STDTIME
| Specifies that the variable must contain a valid 8 character standard time.
| The conversion utility builds the VER(variable,STDTIME) statement.

Compatibility Considerations

In ISPF Version 3.1, the conversion utility also supported the CHECKI
attribute and value TYPE=NUMERIC. If used, the conversion utility will
generate a VER(variable ENUM) and a warning message. This support
provides backward compatibility with ISPF Version 3.1.

You should now use the TYPE=NUMERIC attribute of the VARCLASS tag to
specify that checking for a numeric value should be performed. See
“VARCLASS (Variable Class)” on page 459 for more information.

Description
The CHECKI tag defines a test of an input value. Validity checking occurs only on
input.

Conditions
v You must code the CHECKI tag within a CHECKL definition. The conversion
utility supports only one CHECKI within each CHECKL definition. If multiple
CHECKI definitions are coded within a single CHECKL definition, the
additional CHECKI tags are ignored and are not syntax checked. See “CHECKL
(Validity Check List)” on page 243 for a complete description of this tag.
v The conversion utility builds a VER statement in the ISPF )PROC section of the
panel definition for a CHECKI tag.
v When a “%varname” notation is found on any of the attributes that allow a
variable name, the “%varname” entry must follow the standard naming
convention described in “Rules for “%variable” Names” on page 201.

Nested Tags
None.

Example
In this example, variables associated with the variable class aa must have a value
that contains only alphabetic characters. Values associated with the variable class
bb can only be SINGLE or DOUBLE.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=aa TYPE=‘char 18’>

<CHECKL MSG=msgf881>
<CHECKI TYPE=ALPHA>
</CHECKL>

<VARCLASS NAME=bb TYPE=‘char 6’>

<XLATL FORMAT=upper>
</XLATL>
<CHECKL MSG=msgf883>
<CHECKI TYPE=VALUES PARM1=EQ PARM2=“SINGLE DOUBLE”>
</CHECKL>

<VARLIST>
<VARDCL NAME=checka VARCLASS=aa>

242 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CHECKI
<VARDCL NAME=checkb VARCLASS=bb>
</VARLIST>

<PANEL NAME=checki>CHECKI audits

<DTAFLD DATAVAR=checka ENTWIDTH=18 PMTWIDTH=20>Enter Last Name
<DTAFLD DATAVAR=checkb ENTWIDTH=6 PMTWIDTH=20>Enter Room Type
<CMDAREA>
</PANEL>

CHECKL (Validity Check List)

The CHECKL tag defines a validity check for input variables.

ÊÊ <CHECKL > </CHECKL> ÊÍ

MSG=message-identifier

MSG=message-identifier
This attribute identifies the message to be issued if the value fails the
embedded test. The conversion utility adds this message-identifier to the VER
statement generated by the enclosed CHECKI tag. If you do not specify your
own message, ISPF issues a message specified on the enclosing VARCLASS tag
or the default message associated with the type of VER statement generated.
See “MSG (Message)” on page 376 for information on creating messages.

Description
The CHECKL tag defines a validity check for input variables. The CHECKI tag
coded within the check list performs the validation test.

Field validity checking follows standard ISPF conventions based on the verification
statements generated. For details, see “CHECKI (Validity Check Item)” on
page 234.

Conditions
v The CHECKL tag requires an end tag.
v You must code the CHECKL tag within a VARCLASS definition. See
“VARCLASS (Variable Class)” on page 459 for a complete description of this tag.
v The CHECKL tag must be coded after any and all XLATL tags in the same
variable class.

Nested Tags
You can code the following tag within a CHECKL definition:

Tag Name Usage Page Required

CHECKI Validity check item Single 234 No

Example
The following source file markup contains two variable classes that each contain a
validity check list. The second variable class also contains a translate list that
translates variable values to uppercase. Notice that the translate list is coded in the
variable class before the validity check list.

Chapter 13. Tag Reference 243

CHECKL
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=aa TYPE='char 18'>

<CHECKL MSG=msgf881>
<CHECKI TYPE=ALPHA>
</CHECKL>

<VARCLASS NAME=bb TYPE='char 6'>

<XLATL FORMAT=upper>
</XLATL>
<CHECKL MSG=msgf883>
<CHECKI TYPE=VALUES PARM1=EQ PARM2="SINGLE DOUBLE">
</CHECKL>

<VARLIST>
<VARDCL NAME=checka VARCLASS=aa>
<VARDCL NAME=checkb VARCLASS=bb>
</VARLIST>

<PANEL NAME=checkl>CHECKL audits

<DTAFLD DATAVAR=checka ENTWIDTH=18 PMTWIDTH=20>Enter Last Name
<DTAFLD DATAVAR=checkb ENTWIDTH=6 PMTWIDTH=20>Enter Room Type
<CMDAREA>
</PANEL>

CHOFLD (Choice Data Field)

The CHOFLD tag defines an input field, an output field, or an input/output field
within the text of a CHOICE tag.

ÊÊ <CHOFLD DATAVAR=field-data Ê
VARCLASS=variable-class-name

Ê Ê
NO BOTH
HELP= YES USAGE= IN
help-panel-name OUT
*help-message-id
%varname
*%varname

Ê Ê
NO NO
REQUIRED= YES AUTOTAB= YES
YES MSG=message-identifier

Ê Ê
ENTWIDTH=n FLDSPACE=n START
ALIGN= CENTER
END

244 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CHOFLD
Ê Ê
YES NOENDATTR PAD= NULLS
DISPLAY= NO USER
char
%varname

Ê Ê
PADC= NULLS NONE
USER OUTLINE= L
char R
%varname O
U
BOX
%varname

Ê Ê
PSVAR= point-and-shoot-variable
%varname

Ê Ê
PSVAL= point-and-shoot-value PAS=%varname EXPAND
%varname

Ê > Ê
NO INIT=initial-value IMAP Options
ATTRCHANGE= YES
NEW

Ê Ê
ATTRCHAR=code OFF choice-description-text
CAPS= ON

Ê ÊÍ
</CHOFLD>

IMAP Options:

IMAPNAME= image-name Ê
%varname IMAPNAMEP= image-namep
%varname

Ê
ABOVE
PLACE= BELOW
LEFT
RIGHT
%varname

Chapter 13. Tag Reference 245

 CHOFLD
DATAVAR=field-data
This attribute specifies the variable name for the data in the field. The value
coded must be a variable-name without the leading % notation.
VARCLASS=variable-class-name
This attribute specifies the name of the variable class, defined using a
VARCLASS tag, that overrides the default variable class referred to by the
VARDCL that declared the data variable for this field.
| HELP=NO | YES | help-panel-name | *help-message-id | %varname |
| *%varname
| This attribute specifies the help action taken when the user requests help for
| this choice data field. This is field-level help.

| When HELP=YES, control is returned to the application. You can specify either
| a help panel or a message identifier. If a message identifier is used, it must be
| prefixed with an asterisk (*).

| The help attribute value can be specified as a variable name. When %varname
| is coded, a panel variable name is created. When *%varname is coded, a
| message variable name is created.

| If the user requests help for the choice data field and no help is defined, the
| extended help panel is displayed. If an extended help panel is not defined for
| the panel, the application or ISPF tutorial is invoked.

| The help-panel-name must follow the standard naming convention described in

| “Rules for Variable Names” on page 201.

| See “HELP (Help Panel)” on page 323 for information on creating help panels.
| For information about creating messages, see “MSG (Message)” on page 376.
USAGE=BOTH | IN | OUT
This attribute indicates whether the field is for input only, output only, or both.
REQUIRED=NO | YES
This attribute indicates if the field requires input. This attribute is valid only
when USAGE=IN or BOTH.

If REQUIRED=YES is coded, a VER(variable,NONBLANK) statement will be

built by the conversion utility and placed in the )PROC section of the ISPF
panel generated.
MSG=message-identifier
This attribute specifies the message that is displayed when the user does
not complete a required entry (defined with the REQUIRED attribute). If
you do not specify a message-identifier, ISPF displays a default message.

If you specify the MSG attribute and REQUIRED=YES, a

VER(variable,NONBLANK,MSG=message-identifier) statement is built by
the conversion utility and placed in the )PROC section of the ISPF panel
generated. If you specify the MSG attribute and REQUIRED=NO (the
default), the conversion utility issues a warning message.

See “MSG (Message)” on page 376 for information on creating messages.

246 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CHOFLD
Note: You can specify messages pertaining to other validations using
XLATL and CHECKL tags within a VARCLASS definition. See the
descriptions of these tags for additional information.
AUTOTAB=NO | YES
When AUTOTAB=YES, the cursor moves to the next field capable of input
when the user enters the last character in this field. If no other field capable of
user input exists on the panel, the cursor returns to the beginning of this field.
The ISPF SKIP keyword is not supported when running in GUI mode.

AUTOTAB=YES is valid only when the value for USAGE is either BOTH or
IN. If specified, this attribute overrides the AUTOTAB value of the DTACOL
tag.
ENTWIDTH=n
This attribute specifies the number of bytes used for the choice data field. The
minimum width is 1 and the maximum is the remaining available panel width,
less the required amount of space for field attributes. If ENTWIDTH is not
provided on either the CHOFLD tag or the enclosing DTACOL tag, the
conversion utility will use the width determined by the TYPE value of the
associated VARCLASS.

If specified, this attribute overrides the ENTWIDTH value of the DTACOL tag.
FLDSPACE=n
This attribute specifies the number of bytes reserved for the choice data field.
The minimum width is 2 and the maximum is the remaining available panel
(or region) width. The FLDSPACE value should include the actual entry width
plus the number of entry field attributes. If the value specified by ENTWIDTH
is less than the specified FLDSPACE value, the entry field is padded with
blanks to the FLDSPACE value. This will create blank space between the entry
field and following choice-description-text and allows you to align description
text from successive CHOFLD definitions.

If specified, this attribute overrides the FLDSPACE value of the DTACOL tag.
ALIGN=START | CENTER | END
This attribute specifies the alignment of data within the display field after all
translations have been performed. Use this attribute to align the data with the
start, the end, or the center of the display field.

This is accomplished in the conversion utility by using an attribute character

for the field that specifies JUST(LEFT) if ALIGN=START or JUST(RIGHT) if
ALIGN=END. ALIGN=CENTER will use an attribute character for the field
that specifies JUST(ASIS).

Alignment occurs if the transformed value of the dialog variable is shorter

than the display width of the field. When ALIGN=END, there is no underscore
padding performed. Instead, blanks are used.
DISPLAY=YES | NO
This attribute specifies whether data will display on the screen when the user
types it in. If you specify NO, the data will not display. This attribute is useful
when creating fields for passwords or other information which you do not
want to appear on the screen.
NOENDATTR
This attribute, which is valid only when WINDOW=NO is specified on the
PANEL tag or DIR=HORIZ is specified on the REGION tag, specifies that no

Chapter 13. Tag Reference 247

CHOFLD
ending attribute will be placed after the choice data field. NOENDATTR is
ignored for the last field on each panel line unless WINDOW=NO has been
specified on the PANEL tag. NOENDATTR is valid only when the CHOFLD
tag is followed by a CHOFLD, CHOICE, or CHDIV tag.
PAD=NULLS | USER | char | %varname
This attribute specifies the pad character for initializing the field. You can
define this attribute as a variable name preceded by a “%”.

If specified, this attribute overrides the PAD value of the DTACOL tag.
PADC=NULLS | USER | char | %varname
This attribute specifies the conditional padding character to be used for
initializing the field. You can define this attribute as a variable name preceded
by a “%”.

If specified, this attribute overrides the PADC value of the DTACOL tag.
OUTLINE=NONE | L | R | O | U | BOX | %varname
This attribute provides for displaying lines around the field on a DBCS
terminal. You can define this attribute as a variable name preceded by a “%”.

If specified, this attribute overrides the OUTLINE value of the DTACOL tag.
PSVAR=point-and-shoot-variable | %varname
This attribute provides the name of a variable that is to be set when a
CHOFLD is clicked on for point-and-shoot selection. You can define this
attribute as a variable name preceded by a “%”.

The point-and-shoot-variable must follow the standard naming convention

described in “Rules for Variable Names” on page 201.
PSVAL=point-and-shoot-value | %varname
This attribute provides the value to be placed in the field specified by the
PSVAR attribute. You can define this attribute as a variable name preceded by
a “%”. To specify a blank value, the ″’ ’″ (quotation mark, apostrophe, blank,
apostrophe, quotation mark) coding notation should be used.
PAS=%varname
This attribute can be used to provide a variable name to specify ON or OFF for
point-and-shoot. When PSVAR and PSVAL have been specified without the
PAS attribute, the point-and-shoot field will be automatically enabled.
EXPAND
The EXPAND attribute, used in combination with EXPAND=xy on the PANEL
definition, causes the expand characters to be added to the CHOFLD
definition, effectively allowing ENTWIDTH to expand. The ENTWIDTH value
must be specified as 4 or greater for the EXPAND function to operate.

Note: If the PANEL tag attribute EXPAND is defined with no value specified,
the CHOFLD tag EXPAND attribute is not used.
ATTRCHANGE=NO | YES | NEW
When ATTRCHANGE=YES or ATTRCHANGE=NEW, the conversion utility
formats an additional entry in the panel )ATTR section (that can apply to
multiple data fields) instead of creating a unique .ATTR(field-name) entry in
the )INIT section for this field. With this option, multiple CHOFLD tags with
the same characteristics require fewer panel logic statements.
ATTRCHANGE=NEW creates a new entry. ATTRCHANGE=YES uses an
existing entry, if possible.

248 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CHOFLD
INIT=initial-value
When the INIT attribute is specified, the conversion utility adds a statement to
the panel )INIT section to initialize the field to the initial-value.
IMAPNAME= image-name | %varname
This attribute specifies the name of an image to be placed on the
point-and-shoot push button when it is displayed in GUI mode. The
image-name is not used when the panel is displayed in host mode.

The image-name must follow the standard naming convention described in

“Rules for Variable Names” on page 201.
IMAPNAMEP=image-namep | %varname
This attribute specifies the name of an image to be placed on the
point-and-shoot push button after it has been pushed when it is displayed
in GUI mode. The image-namep is not used when the panel is displayed in
host mode.

The image-namep must follow the standard naming convention described in

“Rules for Variable Names” on page 201.
PLACE=ABOVE | BELOW | LEFT | RIGHT
This attribute specifies the position of the image relative to the text within
the point-and-shoot push button.
| ATTRCHAR=code
| This attribute can be a single character or a two-position entry of valid hex
| digits. If you enter an incorrect value, a warning message is issued and the
| value is set to null. Hex entries are converted to character. Hex values ’00’-’2F’
| are reserved for use by the conversion utility.
| CAPS=OFF | ON
| When CAPS=ON, the data in the field is displayed in uppercase characters.
choice-description-text
This is the text for the choice data field. The choice-description-text appears
following the field.

Description
The CHOFLD tag is similar to the DTAFLD tag. When the enclosing SELFLD tag is
defined within a DTACOL tag, the CHOFLD tag will use default values defined by
the DTACOL tag in the same way as the DTAFLD tag.

The CHOFLD tag defines an input field, an output field, or an input/output field
within CHOICE tag description text on an application panel.

The formatted width of the field is 2 positions more than the ENTWIDTH value to
provide for an attribute byte both before and after the field.

Conditions
v You must code the CHOFLD tag within a CHOICE tag definition. The CHOFLD
tag can be placed anywhere within the choice-description-text. See “CHOICE
(Selection Choice)” on page 252 for a description of this tag.
v The variable name specified in the DATAVAR attribute should have an
associated VARDCL definition. See “VARDCL (Variable Declaration)” on
page 463 for a complete description of this tag.
v If both PAD and PADC have been specified, PAD is ignored and PADC is used.

Chapter 13. Tag Reference 249

CHOFLD
v When a ″%varname″ notation is found on any of the attributes that allow a
variable name, the %varname entry must follow the standard naming
convention described in “Rules for “%variable” Names” on page 201.

Nested Tags
You can code the following tags within a CHOFLD definition:

Tag Name Usage Page Required

ACTION Action Multiple 207 No
CHDIV Choice Divider Multiple 232 No
COMMENT Comment Multiple 272 No
HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
SOURCE Source Multiple 449 No

Example
The following source file markup contains an application panel that is similar to
the example for the CHOICE tag. In this example, the first selection field is
modified to illustrate the CHOFLD tag. The first choice includes a panel
input/output field named cardtype which must be completed when the new choice
is selected.

Notice that the reference CHOICE source file has been modified to:
v Add a VARCLASS for the cardtype field before the include file which has both
VARCLASS and VARDCL tags.
v Add a VARDCL for the cardtype field after the include file which has both
VARCLASS and VARDCL tags.
v Add the CHOFLD tag to define the choice data field.
v Add a DTACOL tag definition to allow for a SOURCE tag that provides an audit
of cardtype only when new is selected.

Figure 99 on page 251 shows the formatted result.

<!DOCTYPE DM SYSTEM(
<!entity sampvar1 system>
<!entity sampabc system>)>

<VARCLASS NAME=char9cls TYPE='char 9'>

<XLATL FORMAT=upper>
</XLATL>

&sampvar1;

<VARLIST>
<VARDCL NAME=cardtype VARCLASS=char9cls>
</VARLIST

<PANEL NAME=chofld KEYLIST=keylxmp>Library Card Registration

<AB>
&sampabc;
</AB>
<TOPINST>Type in patron's name and card number (if applicable).
<TOPINST>Then select an action bar choice.
<AREA>

250 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CHOFLD
<DTAFLD DATAVAR=curdate PMTWIDTH=12 ENTWIDTH=8 USAGE=out>Date
<DTAFLD DATAVAR=cardno PMTWIDTH=12 ENTWIDTH=7 DESWIDTH=25>Card No
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address PMTWIDTH=12 ENTWIDTH=25>Address
<DIVIDER>
<REGION DIR=horiz>
<SELFLD NAME=cardsel PMTWIDTH=30 SELWIDTH=38>Choose
one of the following
<CHOICE CHECKVAR=card MATCH=new>
New Type:
<CHOFLD datavar=cardtype autotab=yes entwidth=9>
(Permanent or Temporary)
<CHOICE CHECKVAR=card MATCH=renew>Renewal
<CHOICE CHECKVAR=card MATCH=replace>Replacement
</SELFLD>
<DTACOL>
<SOURCE>
IF (&CARDSEL = 1)
VER(&CARDTYPE,NB,LIST,TEMPORARY,PERMANENT)
</SOURCE>
</DTACOL>
<SELFLD TYPE=multi PMTWIDTH=30 SELWIDTH=25>Check valid branches
<CHOICE NAME=north HELP=nthhlp CHECKVAR=nth>North Branch
<CHOICE NAME=south HELP=sthhlp CHECKVAR=sth>South Branch
<CHOICE NAME=east HELP=esthlp CHECKVAR=est>East Branch
<CHOICE NAME=west HELP=wsthlp CHECKVAR=wst>West Branch
</SELFLD>
</REGION>
</AREA>
<CMDAREA>Enter a command
</PANEL>

File Search Help

--------------------------------------------------------------------------
Library Card Registration

Type in patron's name and card number (if applicable).

Then select an action bar choice.

Date . . . :
Card No. . . _______ (A 7-digit number)
Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following Check valid branches

__ 1. New Type: Z _ North Branch
(Permanent or Temporary) _ South Branch
2. Renewal _ East Branch
3. Replacement _ West Branch

Enter a command ===> ______________________________________________________

F1=Help F2=Split F3=Exit F6=KEYSHELP F9=Swap
F12=Cancel

Figure 99. Choice Data Fields

Chapter 13. Tag Reference 251

CHOICE

CHOICE (Selection Choice)

The CHOICE tag defines information about a choice in a selection field.

ÊÊ <CHOICE Ê
NAME=choice-name NO
HELP= YES
help-panel-name
*help-message-id
%varname
*%varname

Ê Ê
CHECKVAR=variable-name
1 0
MATCH= string NOMATCH= string

Ê Ê
YES SELCHAR=’char(s),n’ PAD= NULLS
AUTOTAB= NO USER
char
%varname

Ê Ê
PADC= NULLS NONE HIDE HIDEX
USER OUTLINE= L
char R
%varname O
U
BOX
%varname

Ê Ê
UNAVAIL=variable-name TRUNC=n
1
UNAVAILMAT= string

Ê > choice-description-text ÊÍ
YES </CHOICE>
AUTOSEL= NO

NAME=choice-name
Specifies the name of the choice. The choice-name must follow the standard
naming convention described in “Rules for Variable Names” on page 201.

Note: This attribute is required for choices defined for a multiple-choice

selection field because the choice-name is used as the input field for
multiple choice selections.

For multiple-choice selection fields, the choice-name can also be used to position
the cursor on the choice or to position a pop-up.

252 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CHOICE
Note: This attribute is not supported by the conversion utility for single-choice
selection fields. In this case, the NAME value of the SELFLD tag is used
as the field name.
| HELP=NO | YES | help-panel-name | *help-message-id | %varname |
| *%varname
| This attribute specifies the help action taken when the user requests for a
| multiple-choice selection field. This is field-level help.

| When HELP=YES, control is returned to the application. You can specify either
| a help panel or a message identifier. If a message identifier is used, it must be
| prefixed with an asterisk (*).

| The help attribute value can be specified as a variable name. When %varname
| is coded, a panel variable name is created. When *%varname is coded, a
| message variable name is created.

| If the user requests help on a choice and no help is defined, the extended help
| panel is displayed. If an extended help panel is not defined for the panel, the
| application or ISPF tutorial is invoked.

| The help-panel-name must follow the standard naming convention described in

| “Rules for Variable Names” on page 201.

| See “HELP (Help Panel)” on page 323 for information on creating help panels.
| For information about creating messages, see “MSG (Message)” on page 376.

| Note: This attribute is valid only when the SELFLD tag has been specified
| with TYPE=MULTI.
| CHECKVAR=variable-name
This 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.

The preselection indicator depends on the value of the TYPE attribute from the
SELFLD tag and whether the display mode is host or GUI.

GUI Display
TYPE LISTTYPE Host Display Indicator Indicator
MULTI n/a slash check
SINGLE (not used) Choice number Choice number
RADIO Choice number Radio button selected
LISTBOX Choice number Choice highlighted
in list
DDLIST Choice number Choice displayed
in field
COMBO Choice number Choice placed in field
MENU n/a Choice number Choice number
MODEL n/a Choice number Choice number

| When the SELFLD tag has been specified with TYPE=MENU, TYPE=MODEL,
| or TYPE=TUTOR, the CHOICE number (or SELCHAR value) is placed in the
| command line.

Chapter 13. Tag Reference 253

 CHOICE
The variable-name is updated to the value specified by the MATCH attribute
when the user selects the choice being defined. For multiple-choice selection
fields (SELFLD TYPE=MULTI), if you do not select a choice, or you deselect a
choice, the associated variable-name is set to the value of the NOMATCH
attribute or to 0 if the NOMATCH attribute is not specified.

Use a different variable for variable-name than what has been specified for
choice-name.

Do not use the same variable for the variable-name as you use for the
variable-name specified for the SETVAR or TOGVAR attributes of the ACTION
tag.

| For single-choice selection fields (SELFLD TYPE=SINGLE), ISPF selection

| menus (SELFLD TYPE=MENU), edit model selection menus (SELFLD
| TYPE=MODEL), or tutorial selection menus (SELFLD TYPE=TUTOR), the
| variable-name should be the same for all of the choices. For multiple-choice
| selection fields (SELFLD TYPE=MULTI), the variable-name should be different
| for each choice.

The CHECKVAR attribute value must be specified without a leading % sign.

The variable-name must follow the standard naming convention described in
“Rules for Variable Names” on page 201.
MATCH=1 | string
Defines the value for the check variable that causes the item to be
preselected. The string can be any character string. MATCH=1 is the
default.
NOMATCH=0 | string
Defines the value for setting the check variable when the item is not
selected. NOMATCH=0 is the default.

Note: This attribute is valid only when the SELFLD tag has been specified
with TYPE=MULTI.
AUTOTAB=YES | NO
When AUTOTAB=YES, the cursor moves to the next field capable of input
when the user enters the last character in this field. If no other field capable of
user input exists on the panel, the cursor remains on this field.

The ISPF SKIP keyword is not supported when running in GUI mode.

Note: This attribute is valid only when the SELFLD tag has been specified
with TYPE=MULTI.
SELCHAR=’char(s),n’
| This attribute specifies an alphanumeric character(s) to be used as the selection
| menu, edit model selection menu, or tutorial selection menu choice in place of
| the normal numeric value automatically supplied by the conversion utility. The
| number of characters accepted is controlled by the ENTWIDTH attribute of the
| SELFLD tag. The char(s) value is used as coded, that is, it is not uppercased.

| When the HIDE attribute is also specified, the number of characters to be used
| for the hidden choice selection may be specified as part of the SELCHAR
| attribute. If specified, the n value overrides the number of characters normally
| obtained from the ENTWIDTH attribute of the SELFLD tag. The n value can be
| a numeric value from 1 to the number of bytes provided as the char(s) value,

254 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CHOICE
| or you can specify an “*” to tell the conversion utility to use all of the char(s)
| provided for the choice selection. The n value is ignored when the HIDE
| attribute is not specified.

| Note: This attribute is valid only when the SELFLD tag has been specified
| with TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR.
| PAD=NULLS | USER | char | %varname
This attribute specifies the pad character for initializing the field. You can
define this attribute as a variable name preceded by a “%”.

Note: This attribute is valid only when the SELFLD tag has been specified
with TYPE=MULTI.
PADC=NULLS | USER | char | %varname
This attribute specifies the conditional padding character to be used for
initializing the field. You can define this attribute as a variable name preceded
by a “%”.

Note: This attribute is valid only when the SELFLD tag has been specified
with TYPE=MULTI.
OUTLINE=NONE | L | R | O | U | BOX | %varname
This attribute provides for displaying lines around the field on a DBCS
terminal. You can define this attribute as a variable name preceded by a “%”.

Note: This attribute is valid only when the SELFLD tag has been specified
with TYPE=MULTI.
HIDE
This attribute causes a choice entry for a single-choice, menu-choice,
model-choice, or tutor-choice selection to be removed from the selection list
display.

This allows the creation of a numbered selection list when the choice numbers
are not continuous by adding a ‘dummy’ CHOICE tag at the appropriate place
in the DTL source. The number assigned to the hidden CHOICE does not
appear in the selection list. Normal )INIT and )PROC section entries are not
affected.

Note: This attribute is valid only when the SELFLD tag has been specified
with TYPE=SINGLE, TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR.
HIDEX
This attribute causes a choice entry for a model-choice selection to be removed
both from the selection list display and from the selection processing.

This attribute is used in combination with the TRUNC attribute and the
SELCHAR attribute to supply an alternate CHOICE tag definition with an
alternate hidden model selection keyword.

For example, if an edit model panel has a selectable description of “VER”, but
you also want to allow the full word “VERIFY” to select the same model, two
CHOICE tags are required. The first one defines the choice with the text
“VER”. The alternate CHOICE uses the same SELCHAR information, adds the
attribute HIDEX and TRUNC=3, and specifies the tag text as “VERIFY”. The
conversion utiltiy uses the first definition to build the panel text and the

Chapter 13. Tag Reference 255

 CHOICE
selection processing statement and uses the alternate CHOICE to accept the
entry “VERIFY” by truncating it to “VER”.

Note: This attribute is valid only when the SELFLD tag has been specified
with TYPE=MODEL.
UNAVAIL=variable-name
This attribute defines a variable whose value indicates whether or not the
choice is available when the selection field is displayed. If the value of the
variable is equivalent to the string you specify with the UNAVAILMAT
attribute (or to the default value “1”), the item is displayed as an unavailable
choice.
UNAVAILMAT=1 | string
Defines the value for the UNAVAIL variable that causes the choice to be
unavailable. The string can be any character string. UNAVAILMAT=1 is the
default.
TRUNC=n
This attribute is used for model-choice selection to specify the minimum
number of characters required to identify the model choice. If the TRUNC
attribute is not specified, the entire model choice name must be used to
identify the model selection.

Note: This attribute is valid only when the SELFLD tag has been specified
with TYPE=MODEL.
| AUTOSEL=YES | NO
| This attribute is used for tutor-choice selection to control the automatic
| selection of this choice by tutorial processing. When AUTOSEL=NO, the choice
| is not automatically selected.
choice-description-text
The text of the selection choice.

Description
The CHOICE tag defines a choice within a selection field. The behavior and
appearance of the choice depends on whether it is coded within a single-choice,
multiple-choice, or menu-choice selection field. The single-choice entries are further
affected in GUI mode by the value of the LISTTYPE attribute on the SELFLD tag.

For menu-choice selection fields, the text is preceded by a number (not followed by
a period), the input field is the command line, and the choice selection is displayed
with the CUA type Normal Text (NT).

For a single-choice selection list:

v When the LISTTYPE attribute of the SELFLD tag is not specified, the text is
preceded by a number (followed by a period), the conversion utility provides an
input field before the first choice for entry of the number of the selected choice,
and the choice selection is displayed with the CUA type Select Available Choices
(SAC).
v When LISTTYPE=RADIO is specified on the SELFLD tag, the choice selection is
displayed as a radio button in GUI mode.
v When LISTTYPE=LISTBOX is specified on the SELFLD tag, the choice selection
is displayed as a list box in GUI mode.
v When LISTTYPE=DDLIST is specified on the SELFLD tag, the choice selection is
displayed as a drop-down list in GUI mode.

256 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CHOICE
v When LISTTYPE=COMBO is specified on the SELFLD tag, the choice selection is
displayed in a combination box in GUI mode.
The field name for single-choice selection fields is the value specified for the
NAME attribute of the SELFLD tag. The default field name for an ISPF selection
menu choice is the field name used to identify the command line, normally ZCMD.

The text of each choice in a multiple-choice selection field is preceded by an input

field. The field name for multiple-choice selection fields is the value specified for
the NAME attribute of the CHOICE tag.

You can define an action for each choice using the SETVAR or TOGVAR attribute
in an ACTION tag associated with the choice. Typically, an application knows what
choice was selected by the application user by the value in the selection field
name. The CHOICE field name for a multi-choice selection is set to a “/” when
control is returned to the application. The SELFLD field name contains the number
of the choice for single choice selection when control is returned to the application.
The command line variable name contains the number of a menu selection choice
when control is returned to the application. Alternatively, the application can use
the value of the check variable or use SETVAR or TOGVAR to set another named
variable.

Conditions
v You must code the CHOICE tag within a SELFLD definition. See “SELFLD
(Selection Field)” on page 433 for a complete description of this tag.
v If coded within a multiple-choice selection field (SELFLD TYPE=MULTI), the
choice-name can have an associated VARDCL definition.
v If both PAD and PADC have been specified, PAD is ignored and PADC is used.
v When a “%varname” notation is found on any of the attributes that allow a
variable name, the “%varname” entry must follow the standard naming
convention described in “Rules for “%variable” Names” on page 201.
v If the choice-description-text contains HP (Emphasized Text) or RP (Reference
Phrase) tags, the UNAVAIL attribute is ignored.

Nested Tags
You can code the following tags within a CHOICE definition:

Tag Name Usage Page Required

ACTION Action Multiple 207 No
CHDIV Choice Divider Multiple 232 No
CHOFLD Choice data field Multiple 244 No
COMMENT Comment Multiple 272 No
HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
SOURCE Source Multiple 449 No

Example
The application panel in the following markup contains two selection fields. The
first is a single-choice selection field that can be preselected depending on the
value assigned to the variable card. When card is equal to new, renew, or replace, the

Chapter 13. Tag Reference 257

CHOICE
selection field’s input data field is assigned a value of 1, 2, or 3, respectively;
otherwise, it is not preselected and the input data field remains blank.

The second selection field is a multiple-choice selection field. This field can be
preselected by assigning values to the variables nth, sth, est and wst. If the given
variable equals 1, the corresponding selection field is marked with a /. More than
one of the choices may be selected. Any non-blank character in the choice
entry-field will select that choice. Preselected choices can be deselected by typing a
blank character over the field.

Figure 100 on page 259 shows the formatted result.

<!DOCTYPE DM SYSTEM(
<!entity sampvar1 system>
<!entity sampabc system>)>
&sampvar1;

<PANEL NAME=choice1 KEYLIST=keylxmp>Library Card Registration

<AB>
&sampabc;
</AB>
<TOPINST>Type in patron's name and card number (if applicable).
<TOPINST>Then select an action bar choice.
<AREA>
<DTAFLD DATAVAR=curdate PMTWIDTH=12 ENTWIDTH=8 USAGE=out>Date
<DTAFLD DATAVAR=cardno PMTWIDTH=12 ENTWIDTH=7 DESWIDTH=25>Card No
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address PMTWIDTH=12 ENTWIDTH=25>Address
<DIVIDER>
<REGION DIR=horiz>
<SELFLD NAME=cardsel PMTWIDTH=30 SELWIDTH=38>Choose
one of the following
<CHOICE CHECKVAR=card MATCH=new>New
<CHOICE CHECKVAR=card MATCH=renew>Renewal
<CHOICE CHECKVAR=card MATCH=replace>Replacement
</SELFLD>
<SELFLD TYPE=multi PMTWIDTH=30 SELWIDTH=25>Check valid branches
<CHOICE NAME=north HELP=nthhlp CHECKVAR=nth>North Branch
<CHOICE NAME=south HELP=sthhlp CHECKVAR=sth>South Branch
<CHOICE NAME=east HELP=esthlp CHECKVAR=est>East Branch
<CHOICE NAME=west HELP=wsthlp CHECKVAR=wst>West Branch
</SELFLD>
</REGION>
</AREA>
<CMDAREA>Enter a command
</PANEL>

258 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CMD

File Search Help

--------------------------------------------------------------------------
Library Card Registration

Type in patron's name and card number (if applicable).

Then select an action bar choice.

Date . . . :
Card No. . . _______ (A 7-digit number)
Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following Check valid branches

__ 1. New _ North Branch
2. Renewal _ South Branch
3. Replacement _ East Branch
_ West Branch

Enter a command ===> ______________________________________________________

F1=Help F2=Split F3=Exit F6=KEYSHELP F9=Swap
F12=Cancel

Figure 100. Selection Field Choices

CMD (Command Definition)

The CMD tag defines a command within an application command table.

ÊÊ <CMD NAME=internal-command-name > Ê

ALTDESCR=command-description

Ê ÊÍ
external-command-name </CMD>

NAME=internal-command-name
This attribute specifies an internal name for the command. The
internal-command-name must have the following characteristics:
v 2–8 single-byte characters in length
v The first (or only) character must be A–Z, a–z, @, #, or $.
v Remaining characters, if any, can be A–Z, a–z, @, #, $, —, or 0–9.

Lowercase characters are translated to their uppercase equivalents.

The internal-command-name is used in two ways:

v As the command table search criteria when:
– A key defined in the current key list is pressed
– A pull-down choice with an associated RUN action is selected
– A command is entered in the command area of a panel.
v As the value passed to dialogs when the command action is PASSTHRU or
SETVERB. See “CMDACT (Command Action)” on page 261 for more
information on the PASSTHRU and SETVERB command actions.
ALTDESCR=command-description
This attribute provides a description of the command. It is placed in the ISPF
variable ZCTDESC. The command-description text length is limited to 80 bytes.

Chapter 13. Tag Reference 259

CMD
external-command-name
Specifies the external name for this command.

Note: The external-command-name must be equal to the internal-command-name.

You must use the external-command-name to support the ability provided
by ISPF for truncated command entry and the T (truncation) tag. For
more information, see “T (Truncation)” on page 451.

Description
The CMD tag defines a command within an application command table. The
defined command can be issued by an application user by entering the
internal-command-name in the panel command area, or pressing a function key, or
selecting a pull-down choice that references the command’s internal-command-name.
See “KEYI (Key Item)” on page 340 and “ACTION (Action)” on page 207 for
additional information.

The action to be taken when a command is issued is defined with the CMDACT
tag. See “CMDACT (Command Action)” on page 261 for information on defining
command actions.

Conditions
v The CMD tag must be coded within a CMDTBL definition. See “CMDTBL
(Command Table)” on page 270 for a complete description of this tag.

Nested Tags
You can code the following tags within a CMD definition:

Tag Name Usage Page Required

CMDACT Command action Single 261 Yes
T Truncation Single 451 No

Example
The following source file markup contains a command table that defines the
commands UPDATE, ADD, DELETE, and SEARCH. The DELETE and UPDATE
commands have defined truncations.
<!DOCTYPE DM SYSTEM>

<CMDTBL APPLID=conv>
<CMD NAME=update>Upd<T>ate
<CMDACT ACTION='alias add'>
<CMD NAME=add>Add
<CMDACT ACTION=setverb>
<CMD NAME=delete>Del<T>ete
<CMDACT ACTION=passthru>
<CMD NAME=search>Search
<CMDACT ACTION=passthru>
</CMDTBL>

The following table shows the resultant ISPF application command table.
Table 1. ISPF Application Command Table
ZCTVERB ZCTTRUNC ZCTACT

UPDATE 3 ALIAS ADD

ADD 0 SETVERB

260 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CMD
Table 1. ISPF Application Command Table (continued)
ZCTVERB ZCTTRUNC ZCTACT

DELETE 3 PASSTHRU
SEARCH 0 PASSTHRU

CMDACT (Command Action)

The CMDACT tag defines the action that occurs when the associated command is
issued.

ÊÊ <CMDACT ACTION= ’SELECT select-parameters’ Ê

’ALIAS internal-command-name ’
parameters
PASSTHRU
SETVERB
BACKWARD
CANCEL
EXIT
EXHELP
FKA
FORWARD
HELP
PANELID
RETRIEVE
’%varname’
application-command
ASIS

Ê > ÊÍ
</CMDACT>

ACTION=
This attribute indicates the action that should be performed when the
associated command is issued. The ACTION attribute value is limited to 240
characters. The value must be one of the following:
SELECT select-parameters
Causes the ISPF SELECT service to be issued.
ALIAS internal-command-name
Provides an alternate way to express a command. For example, you can
assign QUIT as an alias for the command EXIT.

The ALIAS internal-command-name has a maximum length of 8 characters.

In the command table, an alias must precede the command for which it is
an alias.

You can create a chain of command aliases in a command table, as long as

the result is a valid executable action. The last command and parameter
values that ISPF encounters in the alias chain are the ones executed. The
command and the parameter values do not necessarily come from the
same command definition entry. For example:
Command Name Command Action

Chapter 13. Tag Reference 261

CMDACT
EASYKEY ALIAS CMD PARM1 PARM2
CMD ALIAS CMD1 PARM3
CMD1 ALIAS CMD2

In this example, if the EASYKEY command is issued, the command that

would ultimately be executed would be CMD2 PARM3.
parameters
If any ALIAS parameters are specified, they take precedence over any
parameters included with the command when issued from a command
line or the ACTION tag RUN attribute when a pull-down choice is
selected.

If the ALIAS internal-command-name does not include parameters, ISPF

accepts parameters from the command line or ACTION tag.
PASSTHRU
The PASSTHRU action causes the command and any parameters to be
passed to the dialog program in the ZCMD dialog variable.
SETVERB
This is an alternate way to pass a command to the dialog. The SETVERB
action causes the internal-command-name to be passed to the dialog in the
ZVERB dialog variable. Any command parameters are passed in the
ZCMD dialog variable.
BACKWARD
Specifies the ISPF system command BACKWARD as the command action.
CANCEL
Specifies the ISPF system command CANCEL as the command action.
EXIT
Specifies the ISPF system command EXIT as the command action.
EXHELP
Specifies the ISPF system command EXHELP as the command action.
FKA
Specifies the ISPF system command FKA as the command action.
FORWARD
Specifies the ISPF system command FORWARD as the command action.
HELP
Specifies the ISPF system command HELP as the command action.
PANELID
Specifies the ISPF system command PANELID as the command action.
RETRIEVE
Specifies the ISPF system command RETRIEVE as the command action.
%varname
You can specify a command action dynamically at run time by specifying
the name of a variable (using % notation) for the ACTION attribute. If you
specify a variable name, ISPF retrieves the action value when the
command is issued. The variable value must be one of the actions
previously listed.

262 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CMDACT
The “%varname” entry must follow the naming conventions described in
“Rules for “%variable” Names” on page 201.
| application-command
| Specifies an application-unique command as the command action. The
| command action is created as an ALIAS unless the ASIS keyword is
| specified.
| ASIS Specifies that the application-unique command is to be created
| without the ALIAS designation.

| Description
The CMDACT tag defines the action that occurs when the associated command is
issued.

Conditions
v The CMDACT tag must be coded within the CMD definition it is associated
with. See “CMD (Command Definition)” on page 259 for a complete description
of this tag.
v You must specify the ACTION attribute on the CMDACT tag.

Nested Tags
None.

Example
The following source file markup contains a command table that defines the
commands UPDATE, ADD, DELETE and SEARCH. The ADD command sets the
ZVERB variable equal to add. The DELETE command sets the ZCMD variable to
delete. The UPDATE command is an alias for ADD.
<!DOCTYPE DM SYSTEM>

<CMDTBL APPLID=conv>
<CMD NAME=update>Upd<T>ate
<CMDACT ACTION='alias add'>
<CMD NAME=add>Add
<CMDACT ACTION=setverb>
<CMD NAME=delete>Del<T>ete
<CMDACT ACTION=passthru>
<CMD NAME=search>Search
<CMDACT ACTION=passthru>
</CMDTBL>

The following table shows the resultant ISPF application command table.
Table 2. ISPF Application Command Table
ZCTVERB ZCTTRUNC ZCTACT

UPDATE 3 ALIAS ADD

ADD 0 SETVERB
DELETE 3 PASSTHRU
SEARCH 0 PASSTHRU

Chapter 13. Tag Reference 263

CMDAREA

CMDAREA (Command Area)

The CMDAREA tag defines a command entry area on an application panel.

ÊÊ <CMDAREA Ê
NO BEFORE
HELP= YES PMTLOC=
help-panel-name
*help-message-id
%varname
*%varname

Ê Ê
NOINIT PAD= NULLS PADC= NULLS
USER USER
char char
%varname %varname

Ê Ê
NONE NAME=cmdarea-variable-name ENTWIDTH=n
OUTLINE= L
R
O
U
BOX
%varname

Ê Ê
YES DEFAULT DEFAULT
PMTTEXT= NO CMDLOC= ASIS CMDLEN= MAX

Ê Ê
NO SCROLLVAR=scroll-variable
AUTOTAB= YES

Ê Ê
NO NO
SCRVHELP= YES SCROLLTAB= YES
scroll-help-panel-name
*scroll-help-message-id
%varname
*%varname

Ê Ê
OFF PSBUTTON=cmd-pb-text-| PB group |
SCRCAPS= ON

Ê > Ê
OFF OFF command-prompt-text
CAPS= ON NOJUMP= ON

264 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CMDAREA
Ê ÊÍ
</CMDAREA>

PB Group:

ÊÊ Ê
PSVAR= point-and-shoot-variable
%varname

Ê | IMAP Options | ÊÍ
PSVAL= point-and-shoot-value
%varname

IMAP Options

ÊÊ IMAPNAME= image-name Ê
%varname IMAPNAMEP= image-namep
%varname

Ê ÊÍ
ABOVE
PLACE= BELOW
LEFT
RIGHT
%varname

| HELP=NO | YES | help-panel-name | *help-message-id | %varname |

| *%varname
| This attribute specifies the help action taken when the user requests help for
| the command area.

| When HELP=YES, control is returned to the application. You can specify either
| a help panel or a message identifier. If a message identifier is used, it must be
| prefixed with an asterisk (*).

| The help attribute value can be specified as a variable name. When %varname
| is coded, a panel variable name is created. When *%varname is coded, a
| message variable name is created.

| If the user requests help on a choice and no help is defined, the extended help
| panel is displayed. If an extended help panel is not defined for the panel, the
| application or ISPF tutorial is invoked.

| The help-panel-name must follow the standard naming convention described in

| “Rules for Variable Names” on page 201.

| See “HELP (Help Panel)” on page 323 for information on creating help panels.
| For information about creating messages, see “MSG (Message)” on page 376.

Chapter 13. Tag Reference 265

CMDAREA
PMTLOC=BEFORE
This attribute defines the location of the prompt text. The text defined by
command-prompt-text appears on the same line as the command area entry field.
NOINIT
This attribute controls the initial display of the command line. When this
attribute is specified, the ZCMD field is not initialized to blanks before the
panel is displayed.
PAD=NULLS | USER | char | %varname
This attribute specifies the pad character for initializing the field. You can
define this attribute as a variable name preceded by a “%”.
PADC= NULLS | USER | char | %varname
This attribute specifies the conditional padding character to be used for
initializing the field. You can define this attribute as a variable name preceded
by a “%”.
OUTLINE=NONE | L | R | O | U | BOX | %varname
This attribute provides for displaying lines around the field on a DBCS
terminal. You can define this attribute as a variable name preceded by a “%”.
NAME=cmdarea-variable-name
This attribute specifies a command area name to replace the default name
ZCMD.

The cmdarea-variable-name must follow the standard naming convention

described in “Rules for Variable Names” on page 201.
ENTWIDTH=n
This attribute is used to specify the length of the command field. It is used in
combination with WINDOW=NO on the PANEL tag to create a command line
which is longer than a single panel line.
PMTTEXT=YES | NO
This attribute is used to control the formatting of the command-prompt-text.
When PMTTEXT=NO, the command-prompt-text is not used, leaving only the
“===>” indicator for the command field.
CMDLOC=DEFAULT | ASIS
This attribute is used to control the placement of the command line in the
generated panel. When CMDLOC=DEFAULT (or when CMDLOC is not
specified) the command area is placed at line 2 in the panel, and the display
position is controlled by the option specified on the Settings panel. When
CMDLOC=ASIS is specified, the command area is placed in the generated
panel in the same relative position as the CMDAREA tag is found in the DTL
source, and the Settings option is ignored when the panel is displayed.
CMDLEN=DEFAULT | MAX
This attribute is used to control the length of the command line in the
generated panel. When CMDLEN=DEFAULT (or when CMDLEN is not
specified) the command line length is taken from the specified (or defaulted)
WIDTH attribute of the PANEL tag. When CMDLEN=MAX is specified, the
command line length is taken from the record length of the output panel file.

This attribute is valid only when WINDOW=NO is specified on the PANEL

tag.
AUTOTAB=NO | YES
When AUTOTAB=YES, the cursor moves to the next input field when you
enter the last character in the command field. If there is no other input field on

266 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CMDAREA
the panel, the cursor returns to the beginning of the command line. The ISPF
SKIP keyword is not supported in GUI mode.
SCROLLVAR=scoll-variable
This attribute specifies the name of a variable that the application uses to
obtain scrolling information. The scroll-variable must follow the standard
naming convention described in “Rules for Variable Names” on page 201.

If the attribute is specified, the conversion utility creates a scroll entry on the
command line, providing that the resulting command area allows at least 8
bytes for a command entry.
| SCRVHELP=NO | YES | scroll-help-panel-name | *scroll-help-message-id |
| %varname | *%varname
| This attribute specifies the help action taken when the user requests help for
| the field specified with the SCROLLVAR attribute.

| When SCRVHELP=YES, control is returned to the application. You can specify

| either a help panel or a message identifier. If a message identifier is used, it
| must be prefixed with an asterisk (*).

| The help attribute value can be specified as a variable name. When %varname
| is coded, a panel variable name is created. When *%varname is coded, a
| message variable name is created.

| If the user requests help on a choice and no help is defined, the extended help
| panel is displayed. If an extended help panel is not defined for the panel, the
| application or ISPF tutorial is invoked.

| The scroll-help-panel-name must follow the standard naming convention

| described in “Rules for Variable Names” on page 201.

| See “HELP (Help Panel)” on page 323 for information on creating help panels.
| For information about creating messages, see “MSG (Message)” on page 376.
SCROLLTAB=NO | YES
When SCROLLTAB=YES, the cursor moves to the next input field when you
enter the last character in the scroll amount field. If there is no other input
field on the panel, the cursor returns to the beginning of the command line.
The ISPF SKIP keyword is not supported in GUI mode.
| SCRCAPS=OFF | ON
| When SCRCAPS=ON, the data in the scroll field is displayed in uppercase
| characters.
PSBUTTON=cmd-pb-text
This attribute requires that the PSVAR and PSVAL attributes also be specified.

This attribute specifies that a command push button is to be placed at the end
of the command line, provided that the resulting command area allows at least
8 bytes for a command entry. The push button text area is created as a
point-and-shoot field.
PSVAR=point-and-shoot-variable | %varname
This attribute provides the name of a variable that is to be set when the
cmd-pb-text is clicked on for point-and-shoot selection. You can define this
attribute as a variable name preceded by a percent (%) sign.

Chapter 13. Tag Reference 267

 CMDAREA
The point-and-shoot-variable must follow the standard naming convention
described in “Rules for Variable Names” on page 201.
PSVAL=point-and-shoot-value | %varname
This attribute provides the value to be placed in the field specified by the
PSVAR attribute. You can define this attribute as a variable name preceded
by a percent (%) sign. To specify a blank value, use the coding notation
“’ ’” (quotation mark, apostrophe, blank space, apostrophe, quotation
mark).
IMAPNAME=image-name | %varname
This attribute specifies the name of an image to be placed on the
point-and-shoot push button when it is displayed in GUI mode. The
image-name is not used when the panel is displayed in host mode. The
image-name must follow the standard naming convention described in
“Rules for Variable Names” on page 201.
IMAPNAMEP=image-namep | %varname
This attribute specifies the name of an image to be placed on the
point-and-shoot push button after it has been pushed when it is displayed
in GUI mode. The image-namep is not used when the panel is displayed in
host mode. The image-namep must follow the standard naming convention
described in “Rules for Variable Names” on page 201.
PLACE=ABOVE | BELOW | LEFT | RIGHT | %varname
This attribute specifies the position of the image relative to the text within
the point-and-shoot push button.
| CAPS=OFF | ON
| When CAPS=ON, the data in the field is displayed in uppercase characters.
| NOJUMP=OFF | ON
| When NOJUMP=ON, the JUMP function is disabled for the field.
command-prompt-text
The command-prompt-text specifies the prompt text for the command entry area.
The maximum prompt text (not including the command area prefix ===>) is 59
bytes for a standard 76 byte-width panel. The conversion utility reserves 8
bytes for a minimum command entry field and 3 additional bytes are required
for panel attributes. One blank is placed between the command-prompt-text and
the command area prefix. One blank is placed between the end of the
command line and the right panel boundary (unless the WINDOW=NO
attribute has been specified) to prevent the cursor from skipping into the right
panel window border. These formatting considerations mean that the
maximum length of the command-prompt-text for a panel 76 bytes in width is
59. If the length of the command-prompt-text exceeds the available space, a
message is issued and the command-prompt-text is truncated. If your panel
requires that the Scroll field be added to the Command line, or the
SCROLLVAR attribute is specified in the CMDAREA definition, the
command-prompt-text must be further reduced to allow for the Scroll field. If
your panel specifies the PSBUTTON attribute, the command-prompt-text must be
further reduced to allow for the Command push button.

If you do not provide command-prompt-text, the word “Command” (or its

translated equivalent) is the default, unless you are creating an ISPF selection
panel, in which case the word “Option” (or its translated equivalent) is the
default. The Common User Access command area prefix (===>) is always
added automatically in front of the entry field.

268 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CMDAREA
Description
The CMDAREA tag defines a command entry area on an application panel. The
command entry area extends to the right side of the panel, unless limited by the
ENTWIDTH attribute or the presence of a Scroll field. Application users use the
command entry area to enter commands.

Note: If you specify the CMDAREA tag within your DTL source file:
| v It must appear before the AREA, DA, GA, REGION, or SELFLD tag when
| DEPTH=* is specified.
v It must appear before the SELFLD tag when TYPE=MENU and
CHECKVAR or UNAVAIL attributes are specified on nested CHOICE
tags.

Conditions
v You must code the CMDAREA tag within a PANEL definition. You can code
only one command area definition for each panel. See “PANEL (Panel)” on
page 397 for a complete description of this tag.
| v The data entered on the command line is processed “as is”. To translate the data
| to uppercase, you must either provide a VARDCL definition for the field ZCMD
| with a reference to a VARCLASS containing an XLATL tag which specifies
| FORMAT=UPPER, or specify CAPS=ON.
v You cannot code the CMDAREA tag within an AREA definition. The Command
area is generated at the top of the panel source to allow for floating of the
command line. Refer to the ISPF User’s Guide for more information.
v If both PAD and PADC have been specified, PAD is ignored and PADC is used.
v When a “%varname” notation is found on any of the attributes that allow a
variable name, the “%varname” entry must follow the standard naming
convention described in “Rules for “%variable” Names” on page 201.

Nested Tags
Tag Name Usage Page Required
HP Highlighted phrase Multiple 336 No

Example
The following application panel markup contains a command area. The
command-prompt-text “Use this area to enter a command” is specified in the markup
to override the default text “Command”. Figure 101 shows the formatted result.
<!DOCTYPE DM SYSTEM>
<VARCLASS NAME=choiccls TYPE='char 2'
<VARCLASS NAME=vccmd TYPE='char 62'>
<XLATL FORMAT=upper>
</XLATL>
</VARCLASS>

<VARLIST>
<VARDCL NAME=sample VARCLASS=choiccls>
<VARDCL NAME=zcmd VARCLASS=vccmd>
</VARLIST>

<PANEL NAME=cmdarea1>Choose a Virtue

<TOPINST>Select a choice.
<AREA>
<SELFLD NAME=sample PMTWIDTH=10 SELWIDTH=20>Virtues:
<CHOICE>Faith

Chapter 13. Tag Reference 269

CMDAREA
<CHOICE>Hope
<CHOICE>Charity
</SELFLD>
</AREA>
<BOTINST>Now press Enter.
<CMDAREA>Use this area to enter a command
</PANEL>

Choose a Virtue

Select a choice.

Virtues:
__ 1. Faith
2. Hope
3. Charity

Now press Enter.

Use this area to enter a command ===> ____________________________________

F1=Help F3=Exit F12=Cancel

Figure 101. Command Area

CMDTBL (Command Table)

The CMDTBL tag provides support to define the ISPF application command table.

ÊÊ <CMDTBL APPLID=application-identifier > </CMDTBL> ÊÍ

NO
SORT= YES

APPLID=application-identifier
This attribute specifies an application identifier. This identifier is used as a
prefix to the string “CMDS” to form the name of the command table. The
application-identifier must have the following characteristics:
v 1–4 characters in length
v The first (or only) character must be A–Z or a–z @, #, or $.
v Remaining characters, if any, must be A–Z, a–z, @, #, $, or 0–9.

Lowercase characters are translated to their uppercase equivalents.

The name of the command table is member name xxxxCMDS, where xxxx
represents the application-identifier.

Command tables are updated using ISPF table services. Input is obtained from
the ISPTLIB DDname allocation and output is written to the ISPTABL DDname

270 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 CMDTBL
allocation. Refer to the description of how to allocate libraries before starting
ISPF in the ISPF User’s Guide for more information about the use of ISPTLIB
and ISPTABL.
SORT=NO | YES
When SORT=YES is specified, the command table is sorted in command-name
sequence. Any commands defined as an ALIAS to other commands are placed
in the command table first, in command-name sequence. The regular
commands follow the ALIAS entries in command-name sequence.

If SORT=NO or the SORT attribute is not specified, commands are placed in

the command table in the sequence the CMD tags are encountered in the DTL
source file.

Description
The command table tag provides support to define the ISPF application command
table. ACTION tags and definitions of key lists reference the command definitions
within an application command table.

Note: To access commands through the use of the key list function keys, specify
the KEYLAPPL ID invocation parameter for the conversion utility with the
same APPLID value used for the CMDTBL tag.

Conditions
v The CMDTBL tag requires an end tag.
v You cannot code the CMDTBL tag within any other tag definition.
v You can code only one command table for any application.

Nested Tags
You can code the following tag within a CMDTBL definition:

Tag Name Usage Page Required

CMD Command definition Multiple 259 Yes

Example
The following source file markup contains a command table that defines the
commands UPDATE, ADD, DELETE and SEARCH.
<!DOCTYPE DM SYSTEM>

<CMDTBL APPLID=conv>
<CMD NAME=update>Upd<T>ate
<CMDACT ACTION='alias add'>
<CMD NAME=add>Add
<CMDACT ACTION=setverb>
<CMD NAME=delete>Del<T>ete
<CMDACT ACTION=passthru>
<CMD NAME=search>Search
<CMDACT ACTION=passthru>
</CMDTBL>

Chapter 13. Tag Reference 271

CMDTBL
The following table shows the resultant ISPF application command table.
Table 3. ISPF Application Command Table
ZCTVERB ZCTTRUNC ZCTACT

UPDATE 3 ALIAS ADD

ADD 0 SETVERB
DELETE 3 PASSTHRU
SEARCH 0 PASSTHRU

COMMENT (Comment)
The COMMENT tag adds comment text to the generated panel or message
member.

ÊÊ <COMMENT > ÊÍ
END comment-text </COMMENT>
TYPE= CCSID
PANEL
ATTR
ABCINIT
ABCPROC
INIT
REINIT
PROC
HELP
PNTS
LIST

TYPE=END | CCSID | PANEL | ATTR | ABCINIT | ABCPROC | INIT |

REINIT | PROC | HELP | PNTS | LIST
This attribute specifies the section of the panel that is to contain the comment
text. The default is END. TYPE=END is assumed if the COMMENT tag is used
within the MSGMBR tag.

COMMENT tags that specify the TYPE as ABCINIT or ABCPROC must follow
an ABC or PDC tag.

When a COMMENT tag is coded within a HELP panel, the TYPE value is
limited to CCSID, PANEL, ATTR, INIT, PROC, or END.
comment-text
The comment-text is flowed to a width of 66 bytes. The conversion utility adds
“/* ” before and “ */” after the the resulting text.

When no comment-text is present, a blank comment line is added to the

specified (or defaulted) panel section.

Description
The COMMENT tag adds comments to the generated ISPF format panel. If the
PREP conversion option has been specified, the comments will not be part of the
final panel because they will not be processed by the ISPPREP utility.

Lines of text from a COMMENT tag are added to the specified panel section when
encountered in the DTL source file.

272 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 COMMENT
Note: If the panel section specified will not be generated by other conversion
processing, comments will be formatted as follows:
TYPE Comments will be placed:
CCSID
Following the )PANEL statement.
LIST Before the )END statement.

Comments added to the )END panel section are placed following any entries from
the COPYR tag and comments containing the ISPDTLC version number and panel
creation date. Lines placed in the )END section of a HELP panel are added to each
continuation HELP panel.

Conditions:
v You must code the COMMENT tag within an ABC, AREA, CHOICE, DA,
DTACOL DTAFLD, HELP, LSTCOL, LSTFLD, LSTGRP, PANEL, PDC, REGION
or SELFLD tag definition.

Nested Tags
None.

Example
The following source file markup contains a comment of several lines that will be
placed after the )END panel statement. Figure 102 on page 274 shows portion of
the ISPF format panel containing the formatted result.
<!doctype dm system>
<!-- COMMENT tag example - PANEL tag -->
<!-- )END section - after CMDAREA tag -->

<varclass name=vc1 type='char 10'>

<varclass name=vc2 type='char 6'>
<varlist>
<vardcl name=lst1 varclass=vc1>
<vardcl name=lst2 varclass=vc2>
</varlist>

<panel name=comment1 depth=19 width=50>

This is panel Comment1

<LSTFLD >
<LSTGRP headline=yes>
<LSTCOL colwidth=10 datavar=lst1 usage=in varclass=vc1 line=1
required=yes autotab=yes align=end help=h1 msg=abcd101>COL1
<LSTCOL colwidth=6 datavar=lst2 usage=in varclass=vc2 line=2
required=yes autotab=yes align=end help=h1 msg=abcd101>COL2
</LSTGRP>
</LSTFLD>
<cmdarea>
<comment type=end>
comment line 1
comment line 2
comment line 3
comment line 4
comment line 5
comment line 6
comment line 7
comment line 8
comment line 9
</panel>

Chapter 13. Tag Reference 273

COMMENT

.
.
.
)END
/* comment line 1 comment line 2 comment line 3 comment line 4 */
/* comment line 5 comment line 6 comment line 7 comment line 8 */
/* comment line 9 */

Figure 102. Comment text added to a panel

COMPOPT (Compiler Options)

The COMPOPT tag sets compiler options for the current source file.

REPLACE SCREEN NODBCS

ÊÊ <COMPOPT Ê
NOREPLACE DISK DBCS NOKANA
KANA

NOPANEL NOMSGSUPP NOCUASUPP PREP

Ê Ê
KEYLAPPL=xxxx PANEL MSGSUPP CUASUPP NOPREP

CUAATTR NOLSTVIEW STATS NOSCRIPT

Ê Ê
NOCUAATTR LSTVIEW NOSTATS SCRIPT

NOLISTING NOMSGEXPAND LOGREPL LISTREPL

Ê Ê
NOFORMAT MSGEXPAND NOLOGREPL NOLISTREPL
LISTING
FORMAT

ACTBAR GUI VERSION NOMERGESAREA NODISPLAY

Ê Ê
NOACTBAR NOGUI NOVERSION MERGESAREA DISPLAY

NODISPLAYW DSNCHK GRAPHIC ZVARS NODBALIGN

Ê Ê
DISPLAYW NODSNCHK NOGRAPHIC NOZVARS DBALIGN

NOMCOMMENT
Ê > ÊÍ
MCOMMENT RESET national-language </COMPOPT>

With the exception of RESET, all of the option keywords used for the COMPOPT
tag are the same as those used for “Conversion Utility Syntax” on page 175. Please
refer to that chapter for information about these keywords.

The COMPOPT tag keyword RESET restores the conversion utility options to their
original invocation settings.

274 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 COMPOPT
Description
The COMPOPT tag should be placed after the document type declaration and
before the first PANEL, HELP, MSGMBR, KEYL, or CMDTBL tag that requires a
compiler option change. Conversion option changes do not apply to ENTITY
declaration processing.

When the COMPOPT tag is processed, all conversion utility options except
PANEL, DISK, SCREEN, DISPLAY, DISPLAYW, DBCS, and KANA are first reset to
the defined default values. The options specified on the COMPOPT tag are then
applied.

The options set by this tag remain in effect for the current source file until another
COMPOPT tag is processed. If you are converting a list of members, either from
member list selections or from a DTLLST list of members, the conversion utility
options are reset to their original invocation settings when the current source file is
completed.

The PROFILE and PROFDDN options defined as part of the conversion utility
invocation syntax are not supported by the COMPOPT tag.

Conditions:
None.

Nested Tags
None.

Example
The following source file markup contains a compiler options line that specifies the
compiler options to be used converting this source file.
<!doctype dm system>
<varclass name=vc1 type='char 10'>
<varclass name=vc2 type='char 6'>
<varlist>
<vardcl name=lst1 varclass=vc1>
<vardcl name=lst2 varclass=vc2>
</varlist>

<compopt noprep noreplace>

<panel name=compopt depth=19 width=50>

This is panel Compopt

<LSTFLD >
<LSTGRP headline=yes>
<LSTCOL colwidth=10 datavar=lst1 usage=in varclass=vc1 line=1
required=yes autotab=yes align=end help=h1 msg=abcd101>COL1
<LSTCOL colwidth=6 datavar=lst2 usage=in varclass=vc2 line=2
required=yes autotab=yes align=end help=h1 msg=abcd101>COL2
</LSTGRP>
</LSTFLD>
<cmdarea>
</panel>

Chapter 13. Tag Reference 275

COPYR

COPYR (Copyright)
The COPYR tag adds copyright text to the generated panel or message member.

ÊÊ <COPYR> ÊÍ
copyright-text </COPYR>

copyright-text
The copyright-text is limited to 66 bytes. It is automatically formatted as a panel
comment with a “/* ” in front and a “ */” following the supplied text.

Description
The COPYR tag adds copyright information to the panel.

The COPYR tag must be placed before the first PANEL, HELP, or MSGMBR
definition within the DTL source file that is to contain the copyright information.

You can use multiple COPYR tags. Each tag creates one comment line, which is
placed after the )END panel statement, or the last message in the message member,
in the order found in the DTL source.

The copyright-text is added to each subsequent panel or message member generated

from the same DTL source file member. If the PREP conversion option has been
specified, the copyright will not be part of the final panel because comments are
not processed by the ISPPREP utility.

Conditions
None.

Nested Tags
None.

Example
The following source file markup contains two copyright lines that will be placed
after the )END panel statement. Figure 103 on page 277 shows a portion of the ISPF
format panel containing the formatted result.
<!doctype dm system>
<!-- COPYR tag example - PANEL tag -->

<varclass name=vc1 type='char 10'>

<varclass name=vc2 type='char 6'>
<varlist>
<vardcl name=lst1 varclass=vc1>
<vardcl name=lst2 varclass=vc2>
</varlist>

<copyr>Copyright statement 1
<copyr>Copyright statement 2

<panel name=copyrt1 depth=19 width=50>

This is panel Copyrt1

<LSTFLD >
<LSTGRP headline=yes>
<LSTCOL colwidth=10 datavar=lst1 usage=in varclass=vc1 line=1

276 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 COPYR
required=yes autotab=yes align=end help=h1 msg=abcd101>COL1
<LSTCOL colwidth=6 datavar=lst2 usage=in varclass=vc2 line=2
required=yes autotab=yes align=end help=h1 msg=abcd101>COL2
</LSTGRP>
</LSTFLD>
<cmdarea>
</panel>

.
.
.
)END
/* Copyright statement 1 */
/* Copyright statement 2 */

Figure 103. Copyright statement added to a panel

DA (Dynamic Area)
The DA tag defines a dynamic area in the panel )BODY section.

ÊÊ <DA NAME=varname Ê
OFF LVLINE=variable-name
EXTEND= ON
FORCE

Ê Ê
OFF USERMOD= usermod-code
SCROLL= ON %varname
CMDLINE

Ê Ê
DATAMOD= datamod-code DEPTH= n WIDTH=n
%varname *

Ê Ê
SHADOW=shadow-name NONE
DIV= BLANK DIV Options
SOLID
DASH
TEXT

Ê Ê
SCROLLVAR=scroll-variable NO
SCRVHELP= YES
scroll-help-panel-name
*scroll-help-message-id
%varname
*%varname

Chapter 13. Tag Reference 277

DA
Ê Ê
NO OFF NT
SCROLLTAB= YES SCRCAPS= ON INITATTR= CT
ET
WT
WASL

Ê > </DA> ÊÍ
NO
HELP= YES
help-panel-name
*help-message-id
%varname
*%varname

DIV Options:

FORMAT= START TEXT=divider-text

CENTER
END

NAME=varname
This attribute defines the name of a dynamic area. This name is the dialog
variable specified by the application that contains the data for the dynamic
area. The varname must follow the standard naming convention described in
“Rules for Variable Names” on page 201.
EXTEND=OFF | ON | FORCE
This attribute defines the run-time display size of the dynamic area. If
EXTEND=ON is specified, the dynamic area definition is expanded to the size
of the logical screen. If you intend to display the panels in a pop-up window,
use EXTEND=OFF (which is the default.)

If EXTEND=FORCE is specified within a horizontal area or region, the

EXTEND(ON) keyword is added to the dynamic area attribute statement in the
)ATTR panel section. The conversion utility issues a message to advise of a
potential display error if other panel fields are formatted on or after the last
defined line of the dynamic area.
LVLINE=variable-name
This attribute allows you to specify the name of a variable that contains the
result of the ISPF function LVLINE. The variable-name must follow the standard
naming convention described in “Rules for Variable Names” on page 201.
SCROLL=OFF | ON | CMDLINE
If you specify SCROLL=ON or SCROLL=CMDLINE, ISPDTLC adds the scroll
amount field provided by the SCROLLVAR attribute to the command line.

If you specify SCROLL=ON, ISPDTLC also automatically enables scrolling

commands by adding SCROLL(ON) to the dynamic area attribute definition.

Note: When SCROLL(ON) is not part of the dynamic area attribute definition,
data in the scroll amount field is available to the application exactly as
entered.

278 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 DA
The first dynamic area on a panel that specifies SCROLL=ON or
SCROLL=CMDLINE (with a valid SCROLLVAR attribute) controls the creation
of the scroll amount field. The specification of the SCROLL attribute on
subsequent DA tags is ignored.
USERMOD=usermod-code | %varname
This attribute specifies a single-character or a 2-position hexadecimal value to
be substituted for attribute characters in a dynamic area variable following
user interaction. You can define this attribute as a variable name preceded by a
“%”.
DATAMOD=datamod-code | %varname
This attribute specifies a single-character or a 2-position hexadecimal value to
be substituted for attribute characters in a dynamic area following user
interaction. You can define this attribute as a variable name preceded by a “%”.
DEPTH=n | *
This attribute specifies the number of lines reserved for the dynamic area
definition.

If the DA tag is to be formatted in the panel )BODY section, that is, the tag is
not within a scrollable area:
v The maximum DEPTH value is the DEPTH value specified on the PANEL
tag, reduced by the number of divider lines (if the DIV attribute is specified)
and any other lines previously used by text or interactive fields.
v If the DEPTH value is specified as an asterisk (*), the conversion utility will
reserve the remaining available panel depth for the dynamic area.

If the DA tag is defined within a scrollable area (see “AREA (Area)” on

page 213), * cannot be specified as the depth value. The maximum DEPTH
value is limited by the ISPF run-time environment.
WIDTH=n
This attribute specifies the number of columns reserved in the panel )BODY
section for the dynamic area definition. If the dynamic area width is less than
the PANEL width, the conversion utility adds an attribute byte immediately
following the right dynamic area boundary. The minimum width for a
dynamic area is the length of varname plus two (2) positions. The maximum
value is the remaining panel width.
SHADOW=shadow-name
This attribute provides a name for a shadow variable name which is used to
define character level attributes within the dynamic area string. The
shadow-name must follow the standard naming convention described in “Rules
for Variable Names” on page 201.
DIV=NONE | BLANK | SOLID | DASH | TEXT
This attribute specifies the type of divider line to be placed before and after the
dynamic area. If this attribute is not specified or has the value NONE, no
divider line is generated. The value BLANK produces a blank line. You must
specify SOLID, DASH, or TEXT to produce a visible divider line. When the
GRAPHIC invocation option is specified, SOLID produces a solid line for host
display and DASH produces a dashed line. When NOGRAPHIC is specified or
the panel is displayed in GUI mode, both SOLID and DASH produce a dashed
line. A visible divider line formats with a non-displayable attribute byte on
each end of the line.
FORMAT=START | CENTER | END
This attribute specifies the position of the divider-text within the divider

Chapter 13. Tag Reference 279

 DA
line. You must specify both the FORMAT attribute and the TEXT attribute
to create a divider line containing text.
TEXT=divider-text
This attribute specifies the text to be placed on the divider line. You must
specify both the FORMAT attribute and the TEXT attribute to create a
divider line containing text.
SCROLLVAR=scoll-variable
This attribute specifies the name of a variable that the application uses to
obtain scrolling information. The scroll-variable must follow the standard
naming convention described in “Rules for Variable Names” on page 201.
| SCRVHELP=NO | YES | scroll-help-panel-name | *scroll-help-message-id |
| %varname | *%varname
| This attribute specifies the help action taken when the user requests help for
| the field specified with the SCROLLVAR attribute.

| When SCRVHELP=YES, control is returned to the application. You can specify

| either a help panel or a message identifier. If a message identifier is used, it
| must be prefixed with an asterisk (*).

| The help attribute value can be specified as a variable name. When %varname
| is coded, a panel variable name is created. When *%varname is coded, a
| message variable name is created.

| If the user requests help on a choice and no help is defined, the extended help
| panel is displayed. If an extended help panel is not defined for the panel, the
| application or ISPF tutorial is invoked.

| The scroll-help-panel-name must follow the standard naming convention

| described in “Rules for Variable Names” on page 201.

| See “HELP (Help Panel)” on page 323 for information on creating help panels.
| For information about creating messages, see “MSG (Message)” on page 376.
SCROLLTAB=NO | YES
If you specify SCROLLTAB=YES, the cursor moves to the next input field
when the user enters the last character in the scroll amount field. If there is no
other input field on the panel, the cursor moves to the beginning of the
command line. The ISPF SKIP keyword is not supported in GUI mode.
| SCRCAPS=OFF | ON
| When SCRCAPS=ON, the data in the scroll field is displayed in uppercase
| characters.
INITATTR=NT | CT | ET | WT | WASL
This attribute specifies the last attribute found before the start of the dynamic
area. This allows the developer control of the initial color for the area. The
conversion utility will replace the last attribute found before the dynamic area
with the attribute specified.
| HELP=NO | YES | help-panel-name | *help-message-id | %varname |
| *%varname
| This attribute specifies whether or not help is available for the dynamic area.

| When HELP=YES, requesting help when the cursor is within the dynamic area
| causes control to return to the application. It is the application’s responsibility

280 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 DA
| to process the help request. You can specify either a help panel or a message
| identifier. If a message identifier is used, it must be prefixed with an asterisk
| (*).

| The help attribute value can be specified as a variable name. When %varname
| is coded, a panel variable name is created. When *%varname is coded, a
| message variable name is created.

| If the user requests help in a dynamic area and no help is defined, the
| extended help panel is displayed. If an extended help panel is not defined for
| the panel, the application or ISPF tutorial is invoked.

| The help-panel-name must follow the standard naming convention described in

| “Rules for Variable Names” on page 201.

| See “HELP (Help Panel)” on page 323 for information on creating help panels.
| For information about creating messages, see “MSG (Message)” on page 376.

Description
The DA tag defines a dynamic area in the panel )BODY or )AREA sections.

| If you specify the CMDAREA tag within your DTL source file, it must appear
| before the DA tag when DEPTH=* is specified. The DA tag DEPTH may have to
| be adjusted to allow for additional lines which result from tags present within the
| panel definition following the end DA tag.

Refer to the ISPF User’s Guide for a discussion of the Dynamic area in ISPF panels.

Conditions
v You must code the DA tag within a PANEL, AREA, or REGION tag. If found
anywhere else, an error is logged and the output panel is not saved.
v If NAME is not valid or not specified, an error is logged and the output panel is
not saved.
v You can use the EXTEND=ON attribute only once within a panel, and
EXTEND=ON cannot be specified on a DA tag coded within a scrollable area. If
EXTEND is already active, either from a DA tag, or from an AREA, GA, SELFLD
or REGION tag, a warning message is logged and the EXTEND attribute is
ignored.
v You can use the SCROLLVAR attribute only once within a panel.
v If you specify the SCROLLVAR attribute, you must also specify the attribute
SCROLL=ON or SCROLL=CMDLINE.
v The resulting scroll entry on the command line must leave at least eight
positions for the command entry field.
v If you specify the SCRVHELP attribute, you must also specify the SCROLLVAR
attribute.
v When a “%varname” notation is found on any of the attributes that allow a
variable name, the “%varname” entry must follow the standard naming
convention described in “Rules for “%variable” Names” on page 201.

Chapter 13. Tag Reference 281

DA
Nested Tags
You can code the following tags within a DA definition:

Tag Name Usage Page Required

ATTR Attribute Multiple 224 No
COMMENT Comment Multiple 272 No
SOURCE Source Multiple 449 No

Example
<!DOCTYPE DM SYSTEM(
<!entity sampvar1 system>
<!entity sampabc system>)>
&sampvar1;

<PANEL NAME=da KEYLIST=keylxmp>Library Card Registration

<AB>
&sampabc;
</AB>
<TOPINST> Type in patron's name and card number (if applicable)
<AREA>
<DTACOL PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25 SELWIDTH=25>
<DTAFLD DATAVAR=curdate USAGE=out ENTWIDTH=8>Date
<DTAFLD DATAVAR=cardno ENTWIDTH=7>Card No.
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address>Address
</DTACOL>
<DIVIDER>
<DA NAME=darea DIV=solid DEPTH=6 SHADOW=shadwvar>
<ATTR ATTRCHAR=# TYPE=datain PADC='_' COLOR=BLUE>
<ATTR ATTRCHAR=| TYPE=dataout COLOR=green>
<ATTR ATTRCHAR=$ TYPE=char COLOR=red>
</DA>
</AREA>
<CMDAREA>Enter a command
</PANEL>

DD (Definition Description)
The DD tag defines the description of a term in a definition list.

ÊÊ <DD> ÊÍ
definition-description </DD>

definition-description
This is the text for the description of a definition list term.

Description
The DD tag defines the description of a term in a definition list.

Conditions
v You must code the DD tag within a DL definition. See “DL (Definition List)” on
page 288 for a complete description of this tag.

282 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 DD
v Each DD tag must follow an associated DT tag within the definition list. You can
code only one DD tag for each DT tag.

Nested Tags
You can code the following tags within a DD definition:

Tag Name Usage Page Required

DL Definition list Multiple 288 No
FIG Figure Multiple 312 No
HP Highlighted phrase Multiple 336 No
LINES Lines Multiple 349 No
NOTE Note Multiple 382 No
NOTEL Note List Multiple 384 No
NT Note Multiple 386 No
OL Ordered list Multiple 387 No
P Paragraph Multiple 390 No
PARML Parameter list Multiple 408 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
SL Simple list Multiple 447 No
UL Unordered list Multiple 457 No
XMP Example Multiple 474 No

Example
The following help panel markup contains a definition list with three definition
descriptions. Figure 104 on page 284 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=dd DEPTH=22 WIDTH=64>Help for Markup

<AREA>
<INFO>
<P>Here are some definitions:
<DL TSIZE=2 BREAK=all>
<DT>markup
<DD>Text that is added to document data in order to
convey information about it.
There are three types of markup the DTL uses: tags, references,
and markup declarations.
<DT>markup declaration
<DD>Markup that controls how other markup of a document
is to be interpreted, for example document type and entity declarations.
<DT>markup language
<DD>A set of characters, conventions, and rules to control
the interpretation of document data.
The Dialog Tag Language is a markup language.
</DL>
</INFO>
</AREA>
</HELP>

Chapter 13. Tag Reference 283

DDHD

Help for Markup

Here are some definitions:

markup
Text that is added to document data in order to convey
information about it. There are three types of markup the
DTL uses: tags, references, and markup declarations.

markup declaration
Markup that controls how other markup of a document is to be
interpreted, for example document type and entity
declarations.

markup language
A set of characters, conventions, and rules to control the
interpretation of document data. The Dialog Tag Language is
a markup language.

F1=Help F3=Exit F5=Exhelp F6=Keyshelp

F7=PrvTopic F8=NxtTopic F10=PrvPage F11=NxtPage
F12=Cancel

Figure 104. Definition Descriptions

DDHD (Definition Description Header)

The DDHD tag defines the heading for the description column of a definition list.

ÊÊ <DDHD> ÊÍ
definition-description-header </DDHD>

definition-description-header
This is the text of the definition description header.

Description
The DDHD tag defines the heading for the description column of a definition list.
You can code multiple DDHD tags within a definition list.

The conversion utility inserts a blank line between the header and the list items
unless the COMPACT attribute is specified on the DL tag.

Conditions
v You must code the DDHD tag within a DL definition. See “DL (Definition List)”
on page 288 for a complete description of this tag.
v Each DDHD tag must be paired with and follow a DTHD tag. See “DTHD
(Definition Term Header)” on page 311 for a complete description of this tag.

Nested Tags
You can code the following tags within a DD definition:

Tag Name Usage Page Required

HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No

284 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 DDHD
Example
The following help panel markup contains a definition description header with the
text “Meaning”. Figure 105 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=ddhd DEPTH=18>Prefix Help

<AREA>
<INFO>
<P>The following list defines each of the valid prefixes.
<DL TSIZE=12>
<DTHD>Prefix
<DDHD>Meaning
<DT>AU
<DD>Automotive
<DT>HB
<DD>Health and beauty
<DT>LG
<DD>Lawn and garden
<DT>SG
<DD>Sporting goods
</DL>
</INFO>
</AREA>
</HELP>

Prefix Help

The following list defines each of the valid

prefixes.

Prefix Meaning

AU Automotive

HB Health and beauty

LG Lawn and garden

SG Sporting goods

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 105. Definition Description Header

DIVIDER (Area Divider)

The DIVIDER tag creates a blank or visible divider within the text portion of an
application panel.

ÊÊ <DIVIDER Ê
NONE YES 1
TYPE= SOLID GAP= NO GUTTER= n
DASH
TEXT

Chapter 13. Tag Reference 285

DIVIDER
Ê Ê
NOENDATTR FORMAT= START
CENTER
END

Ê > ÊÍ
divider-text </DIVIDER>

TYPE=NONE | SOLID | DASH | TEXT

This attribute specifies the type of divider line. The line width is one character.

The default value is NONE, which produces a blank line. You must specify
SOLID, DASH, or TEXT to produce a visible divider line. When the GRAPHIC
invocation option is specified, SOLID produces a solid line for host display
and DASH produces a dashed line. When NOGRAPHIC is specified or the
panel is displayed in GUI mode, both SOLID and DASH produce a dashed
line.
GAP=YES | NO
When GAP=NO, the divider line completely crosses from one side of the text
area to the other. When GAP=YES, a one-character gap remains at each end of
the divider line. However, GAP=YES is ignored and set to NO for dividers
coded within horizontal regions.
GUTTER=1 | n
This attribute specifies the total width of the divider. If the GUTTER value is
an even number, the conversion utility increases the number by 1 so that the
divider is centered within the defined width.

The minimum GUTTER value is 1. If GUTTER=1 on a DIVIDER within a

horizontal region, then the TYPE value must be NONE.

The default GUTTER value for a DIVIDER within a vertical region is 1. The
default GUTTER value for dividers within horizontal regions is 3 to allow for
an attribute byte on each side of the divider character.
NOENDATTR
This attribute is valid only when the DIVIDER tag is coded within a horizontal
region. It specifies that no ending attribute character will be placed after the
divider character.

Note: The minimum divider space that can be specified for a horizontal region
is 1.

When the GUTTER value is 1, the divider character is set to blank.

When the GUTTER value is 2, a solid divider may be specified. The divider
character is placed in the second position of the 2 character GUTTER space.
FORMAT=START | CENTER | END
This attribute specifies the position of the divider text within the width of the
divider line.
divider-text
This is the text of the area divider line.

286 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 DIVIDER
Description
The DIVIDER tag creates a blank or solid divider within the text portion of an
application panel. A horizontally formatted visible divider is created when you
specify the TYPE attribute value as SOLID or DASH. When the GRAPHIC
invocation option is specified, SOLID produces a solid line for host display and
DASH produces a dashed line. When NOGRAPHIC is specified or the panel is
displayed in GUI mode, both SOLID and DASH produce a dashed line. A
vertically formatted SOLID or DASH divider is the “|” character which is obtained
from the ISPF literals table. The direction of the divider is determined by the tag
definition it is coded within. Formatting for dividers are as follows:
v Dividers coded within an AREA, HELP, or PANEL tag definition format
horizontally.
v Dividers coded within a vertical region format horizontally.
v Dividers coded within a horizontal region format vertically.

The divider line can be formatted with descriptive text. When this feature is used,
the FORMAT attribute must be specified. If FORMAT is not specified, the tag text
is ignored. You control the text padding with the TYPE attribute. If TYPE=TEXT,
the divider-text is padded with blanks. When TYPE=SOLID or TYPE=DASH, the
divider-text is padded with the specifed character.

Conditions
v You must code the DIVIDER tag within an AREA, DTACOL, HELP, PANEL, or
REGION definition. See “AREA (Area)” on page 213, “DTACOL (Data Column)”
on page 293, “HELP (Help Panel)” on page 323, “PANEL (Panel)” on page 397,
and “REGION (Region)” on page 424 for descriptions of these tags.

Nested Tags
You can code the following tags within a DIVIDER definition:

Tag Name Usage Page Required

HP Highlighted phrase Multiple 336 No

Example
The following application panel markup contains four DIVIDER definitions. The
first divider is blank. The second divider is solid with a gutter size of 2 and a
GAP=NO value. The third and fourth dividers are solid. Figure 106 on page 288
shows the formatted result.
<!DOCTYPE DM SYSTEM(
<!entity sampvar3 system>)>
&sampvar3;

<PANEL NAME=divider DEPTH=22 WIDTH=70>Print a Document

<AREA>
<DTACOL PMTWIDTH=20 ENTWIDTH=8 SELWIDTH=40 DESWIDTH=35>
<DTAFLD DATAVAR=file>File name
<DTAFLDD>Name of the document to be printed
<DIVIDER TYPE=none>
<SELFLD NAME=type PMTLOC=before>Type style for printing
<CHOICE>Prestige Elite (12 pitch)
<CHOICE>Courier (10 pitch)
<CHOICE>Essay Standard (proportional)
<CHOICE>Essay Bold (proportional)
</SELFLD>
</DTACOL>
<DIVIDER TYPE=solid GUTTER=2 GAP=no>

Chapter 13. Tag Reference 287

DIVIDER
<DTACOL PMTWIDTH=20 ENTWIDTH=2 DESWIDTH=35>
<DTAFLD DATAVAR=marg>Left margin
<DTAFLDD>Number of spaces in the left margin
<DIVIDER TYPE=solid>
<DTAFLD DATAVAR=copy>Copies
<DTAFLDD>Number of copies
<DIVIDER TYPE=solid>
<DTAFLD DATAVAR=duplx ENTWIDTH=1>Duplex
<DTAFLDD>1 = Yes (Print both sides of paper)
<DTAFLDD>2 = No (Print one side only)
</DTACOL>
</AREA>
</PANEL>

Print a Document

File name . . . . . ________ Name of the document to be printed

Type style for

printing . . . . . . __ 1. Prestige Elite (12 pitch)
2. Courier (10 pitch)
3. Essay Standard (proportional)
4. Essay Bold (proportional)

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

Left margin . . . . __ Number of spaces in the left margin

------------------------------------------------------------------
Copies . . . . . . . __ Number of copies
------------------------------------------------------------------
Duplex . . . . . . . _ 1 = Yes (Print both sides of paper)
2 = No (Print one side only)

F1=Help F3=Exit F12=Cancel

Figure 106. Area Dividers

DL (Definition List)
The DL tag defines a list of terms and their corresponding definitions within an
information region.

ÊÊ <DL Ê
10 NONE COMPACT NOSKIP
TSIZE= n BREAK= FIT
ALL

Ê > </DL> ÊÍ
INDENT= n

TSIZE=10 | n
This attribute specifies the space to be allocated for the definition term. The
default value is 10 characters. The minimum TSIZE value is 0 and the
maximum is 40.
BREAK=NONE | FIT | ALL
This attribute controls the formatting of the definition terms and descriptions.

288 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 DL
If BREAK=NONE, the term is on the same line as the description, spilling into
the description area if the length exceeds TSIZE. If BREAK=FIT, the description
is on the line below the term if the term exceeds the TSIZE value. If
BREAK=ALL, every definition is on the line below the term.
COMPACT
This attribute causes the list to format without a blank line between the items
in the list. If you code DDHD and DTHD tags in a compact definition list, the
list formats without a blank line between the headers and list items.
NOSKIP
This attribute causes the list to format without creating a blank line before the
first line of the list.
INDENT = n
This attribute specifies that the definition list is to be indented from the current
left margin.

Description
The DL tag defines a list of terms and their corresponding definitions within an
information region. You use the DT and DD tags to identify the terms that you are
defining and their descriptions, respectively. You use the DTHD and the DDHD
tags to define headings for the term and description columns in definition lists.

The conversion utility inserts a blank line before the definition list unless NOSKIP
is specified.

If you do not specify a TSIZE value, the space allocated for the term size is 10
characters. If any term is longer than 10 characters and BREAK=NONE (the
default) is specified, the term will extend into the description line. If the term is
still too long to fit, it will wrap to the next line.

The definition description is an implied paragraph, and can contain any text items.
For example, you can insert additional paragraphs in a definition description by
using the paragraph (P) tag following the description paragraph. Other tags that
you want to nest within the definition list (such as OL, SL, or UL) must follow the
DD tag within the list.

Conditions
v The DL tag requires an end tag.
v You must code the DL tag within an INFO definition. See “INFO (Information
Region)” on page 339 for a complete description of this tag.
v If you code DDHD and DTHD tags within the definition list, they must precede
the first DT tag.

Nested Tags
You can code the following tags within a DL definition:

Tag Name Usage Page Required

DD Definition description Multiple 282 No
DDHD Definition description Multiple 284 No
header
DT Definition term Multiple 291 No
DTHD Definition term header Multiple 311 No

Chapter 13. Tag Reference 289

DL

Example
The following help panel markup contains a definition list that uses the default
BREAK value of NONE, which formats the definition descriptions on the same line
as the associated terms. Definition term and description headers are also included.
Figure 107 shows the formatted result of the markup. Figure 108 on page 291 shows
how the same definition list would format with a BREAK value of FIT. Figure 109
on page 291 shows how the same definition list would format with a BREAK
value of ALL.
<!DOCTYPE DM SYSTEM>

<HELP NAME=dl DEPTH=22 WIDTH=60>Employee Code Help

<AREA>
<INFO>
<P>The following list defines the valid employee codes.
<DL TSIZE=11>
<DTHD>Code
<DDHD>Meaning
<DT>Full-time
<DD>Indicates that the employee works a
regular schedule of 40 hours or more weekly.
<DT>Part-time
<DD>Indicates that the employee works a regular
schedule of 20 to 40 hours weekly.
<DT>Supplemental
<DD>Indicates that the employee works less than
20 hours weekly.
No regular schedule is in place.
</DL>
</INFO>
</AREA>
</HELP>

Employee Code Help

The following list defines the valid employee codes.

Code Meaning

Full-time Indicates that the employee works a regular

schedule of 40 hours or more weekly.

Part-time Indicates that the employee works a regular

schedule of 20 to 40 hours weekly.

Supplemental Indicates that the employee works less than

20 hours weekly. No regular schedule is in
place.

F1=Help F3=Exit F5=Exhelp F6=Keyshelp

F7=PrvTopic F8=NxtTopic F10=PrvPage F11=NxtPage
F12=Cancel

Figure 107. Definition List (BREAK=NONE)

290 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 DL

Employee Code Help

The following list defines the valid employee codes.

Code Meaning

Full-time Indicates that the employee works a regular

schedule of 40 hours or more weekly.

Part-time Indicates that the employee works a regular

schedule of 20 to 40 hours weekly.

Supplemental
Indicates that the employee works less than 20
hours weekly. No regular schedule is in place.

F1=Help F3=Exit F5=Exhelp F6=Keyshelp

F7=PrvTopic F8=NxtTopic F10=PrvPage F11=NxtPage
F12=Cancel

Figure 108. Definition List (BREAK=FIT)

Employee Code Help

The following list defines the valid employee codes.

Code Meaning

Full-time
Indicates that the employee works a regular
schedule of 40 hours or more weekly.

Part-time
Indicates that the employee works a regular
schedule of 20 to 40 hours weekly.

Supplemental
Indicates that the employee works less than 20
hours weekly. No regular schedule is in place.

F1=Help F3=Exit F5=Exhelp F6=Keyshelp

F7=PrvTopic F8=NxtTopic F10=PrvPage F11=NxtPage
F12=Cancel

Figure 109. Definition List (BREAK=ALL)

DT (Definition Term)
The DT tag defines a term in a definition list.

ÊÊ <DT> ÊÍ
definition-term </DT>

definition-term
This is the text of the definition term.

Chapter 13. Tag Reference 291

DT
Description
The DT tag defines a term in a definition list.

Conditions
v You must code the DT tag within a DL definition. See “DL (Definition List)” on
page 288 for a complete description of this tag.
v Each DT tag must be paired with and precede a DD tag.

Nested Tags
You can code the following tags within a DD definition:

Tag Name Usage Page Required

HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No

Example
The following help panel markup contains a definition list with three definition
terms. Each definition term is paired with an associated definition description.
Figure 110 on page 293 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=dt DEPTH=22 WIDTH=64>Help for Markup

<AREA>
<INFO>
<P>Here are some definitions:
<DL TSIZE=2 BREAK=all>
<DT>markup
<DD>Text that is added to document data in order to
convey information about it.
There are three types of markup the DTL uses: tags, references,
and markup declarations.
<DT>markup declaration
<DD>Markup that controls how other markup of a document
is to be interpreted, for example document type and entity declarations.
<DT>markup language
<DD>A set of characters, conventions, and rules to control
the interpretation of document data.
The Dialog Tag Language is a markup language.
</DL>
</INFO>
</AREA>
</HELP>

292 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 DTACOL

Help for Markup

Here are some definitions:

markup
Text that is added to document data in order to convey
information about it. There are three types of markup the
DTL uses: tags, references, and markup declarations.

markup declaration
Markup that controls how other markup of a document is to be
interpreted, for example document type and entity
declarations.

markup language
A set of characters, conventions, and rules to control the
interpretation of document data. The Dialog Tag Language is
a markup language.

F1=Help F3=Exit F5=Exhelp F6=Keyshelp

F7=PrvTopic F8=NxtTopic F10=PrvPage F11=NxtPage
F12=Cancel

Figure 110. Definition Terms

DTACOL (Data Column)

The DTACOL tag defines default values for data fields (DTAFLD) and selection
fields (SELFLD) that are coded within a DTACOL definition.

ÊÊ <DTACOL Ê
PMTWIDTH= n ENTWIDTH=n DESWIDTH= n
* *
**

Ê Ê
SELWIDTH= n FLDSPACE=n PAD= NULLS
* USER
char
%varname

Ê Ê
PADC= NULLS NONE CUA
USER OUTLINE= L PMTFMT= ISPF
char R NONE
%varname O END
U
BOX
%varname

Ê Ê
NO NO BEFORE
AUTOTAB= YES ATTRCHANGE= YES PMTLOC= ABOVE
NEW

Chapter 13. Tag Reference 293

DTACOL
Ê Ê
YES VARCLASS=variable-class-name
DBALIGN= NO
PROMPT
FIELD
FORCE

Ê > </DTACOL> ÊÍ
NO OFF
REQUIRED= YES CAPS= ON

PMTWIDTH=n | * | **
This attribute specifies the number of bytes reserved for prompts for data
fields and selection fields coded within the data column. The minimum width
is 0 and the maximum is the remaining available panel width. When you
specify PMTWIDTH=*, the conversion utility uses the length of the prompt
text as the prompt width. When you specify PMTWIDTH=**, the conversion
utility uses the maximum available space as the prompt width. If
PMTFMT=CUA is specified (or defaulted) and the prompt text has fewer
characters than the field allows, leader dots fill the remaining spaces. For
output-only data fields, a colon is also added as the last character in the
prompt width space. If any prompt contains more characters than the width
you specify, the prompt is word-wrapped to fit on multiple lines.

Note: Any field within the data column defining a prompt width overrides the
DTACOL PMTWIDTH value.
ENTWIDTH=n
This attribute specifies the number of bytes reserved for data fields coded
within the data column. The minimum width is 1 and the maximum is the
remaining available panel (or region) width.

Note: Any data field within the data column defining an entry width
overrides the DTACOL ENTWIDTH value.
DESWIDTH=n | *
This attribute specifies the number of bytes reserved for the description text of
the enclosed DTAFLDD tags. The minimum width is 0. When you specify
DESWIDTH=*, the conversion utility uses the length of the description text as
the description width. If the text is longer than the width you specify, the text
is word-wrapped to fit on multiple lines.

Note: Any data field within the data column defining a description width
overrides the DTACOL DESWIDTH value.
SELWIDTH=n | *
This attribute specifies the number of bytes reserved for choices in selection
fields coded within the data column. The minimum width value is 1 and the
maximum is the remaining available panel width. If the width required by the
choice-text and its entry field exceeds the specified SELWIDTH value, the text is
wrapped to multiple conversion utility will use the remaining available panel
(or region) width.

Note: Any selection field within the data column defining a selection width
overrides the DTACOL SELWIDTH value.

294 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 DTACOL
FLDSPACE=n
This attribute specifies the number of bytes reserved for the data field. The
minimum width is 2 and the maximum is the remaining available panel (or
region) width. The FLDSPACE value should include the actual entry width
plus the number of entry field attributes. If the value specified by ENTWIDTH
(plus attributes) is less than the specified FLDSPACE value, the entry field is
padded with blanks to the FLDSPACE value. This will create blank space
between the entry field and description text provided by the DTAFLDD tag
and allows you to align description text from successive DTAFLD definitions.

Note: Any data field within the data column defining field space overrides the
DTACOL FLDSPACE value.
PAD=NULLS | USER | char | %varname
This attribute specifies the pad character for initializing the field. You can
define this attribute as a variable name preceded by a “%”.

Note: Any data field within the data column defining PAD overrides the
DTACOL PAD value.
PADC=NULLS | USER | char | %varname
This attribute specifies the conditional padding character to be used for
initializing the field. You can define this attribute as a variable name preceded
by a “%”.

Note: Any data field within the data column defining PADC overrides the
DTACOL PADC value.
OUTLINE=NONE | L | R | O | U | BOX | %varname
This attribute provides for displaying lines around the field on a DBCS
terminal. You can define this attribute as a variable name preceded by a “%”.

Note: Any data field within the data column defining OUTLINE overrides the
DTACOL OUTLINE value.
PMTFMT=CUA | ISPF | NONE | END
This attribute controls the generation of prompt leader characters. The default
is to create CUA leader dots. When ISPF is specified, and at least 4 bytes of
prompt text space remain following the prompt text, the “===>” character
string is placed in the rightmost 4 positions of the prompt text space. When
NONE is specified, no leader characters are added to the prompt text. When
END is specified, the prompt text is right justified within the prompt text
space.

Note: Any data field within the data column defining PMTFMT overrides the
DTACOL PMTFMT value.
AUTOTAB=NO | YES
When AUTOTAB=YES, the cursor moves to the next field capable of input
when the user enters the last character in this field. If no other field capable of
user input exists on the panel, the cursor returns to the beginning of this field.
The ISPF SKIP keyword is not supported when running in GUI mode.

Note: Any data field within the data column defining AUTOTAB overrides the
DTACOL AUTOTAB value.
ATTRCHANGE=NO | YES | NEW
When ATTRCHANGE=YES or ATTRCHANGE=NEW, the conversion utility
formats an additional entry in the panel )ATTR section (that can apply to

Chapter 13. Tag Reference 295

 DTACOL
multiple data fields) instead of creating a unique “.ATTR(field-name)” entry in
the )INIT section for each field. With this option, multiple DTAFLD tags with
the same characteristics require fewer panel logic statements.
ATTRCHANGE=NEW creates a new entry. ATTRCHANGE=YES uses an
existing attribute, if possible.

Note: Any data field within the data column defining ATTRCHANGE
overrides the DTACOL ATTRCHANGE value.
PMTLOC=BEFORE | ABOVE
This attribute defines the prompt location for the enclosed DTAFLD and
SELFLD tags.

Note: Any data field or selection field within the data column defining
PMTLOC overrides the DTACOL PMTLOC value.
DBALIGN=YES | NO | PROMPT | FIELD | FORCE
This attribute defines the DBALIGN value for the enclosed DTAFLD tags.

Note: Any data field within the data column defining DBALIGN overrides the
DTACOL DBALIGN value.
VARCLASS=variable-class-name
This attribute defines the name of the variable class for enclosed CHOFLD and
DTAFLD tags.

Note: Any data field within the data column defininig VARCLASS overrides
the DTACOL VARCLASS value.
| REQUIRED=NO | YES
| This attribute defines whether the fields for enclosed CHOFLD and DTAFLD
| tags require input.

| Note: Any data field within the data column defining REQUIRED overrides
| the DTACOL REQUIRED value.
| CAPS=OFF | ON
| This attribute defines whether the fields for enclosed CHOFLD and DTAFLD
| tages are displayed in uppercase characters.

| Note: Any data field within the data column defining CAPS overrides the
| DATCOL CAPS value.

| Description
The DTACOL tag defines default attribute values for data fields (DTAFLD), choice
data fields (CHOFLD), and selection fields (SELFLD) that are coded within a
DTACOL definition. This allows you to define common values for fields coded
within the data column within a single tag definition.

The xxxWIDTH attributes are convenient for aligning fields on an application

panel. Fields are laid out within the data column along boundaries established by
the values specified on the DTACOL tag. The following example shows those
boundaries:
│ │ │ │
│Í─────PMTWIDTH────Ê│ │Í─────FLDSPACE────Ê│ │Í──────DESWIDTH────────Ê│
│ │ │ │ │ │
│ │ │Í───ENTWIDTH───Ê│ │ │ │
│ │ │ │ │ │ │
│ │ │ │ │ │ │

296 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 DTACOL
│ Data field prompt │ │ │ │ │ Data field description │
│ text │ │ │ │ │ text │
│ │ │ │ │ │ │
│ │ │ │
│ │ │Í────────────SELWIDTH────────────────────────Ê│
│ │ │ │
│ │ │ │
│ Selection field │ │ __ 1. Selection field choice text │
│ prompt text │ │ │
│ │ │ │

The prompt width (PMTWIDTH) is valid for data fields and selection fields coded
within the data column description. The entry width (ENTWIDTH), field space
(FLDSPACE), and description width (DESWIDTH) are only used by enclosed
DTAFLD tags. The selection width (SELWIDTH) is used only by enclosed SELFLD
tags. All of the previous cases stated are true only when the enclosed DTAFLD or
| SELFLD tags do not specify values that override the DTACOL values.

| Note: The SELFLD tag does not use the ENTWIDTH, DESWIDTH, FLDSPACE,
| PAD, PADC, OUTLINE, AUTOTAB, ATTRCHANGE, DBALIGN,
| VARCLASS, REQUIRED, or CAPS attributes of the DTACOL tag.

| If the combined PMTWIDTH, ENTWIDTH, and DESWIDTH values exceed the

remaining available panel (or region) width, the conversion utility issues a warning
message and attempts to fit the data in the available width by wrapping the text.

For data fields, first priority is given to the entry field. Second and third priorities
are given to the prompt and description fields, respectively. These fields use the
available width remaining after the width of the entry field is determined.

Note: Word wrapping can result in word truncation if insufficient width is

available for the text.

Conditions
v The DTACOL tag requires an end tag.
v You must code the DTACOL tag within an AREA, PANEL, or REGION
definition. You can code a DTACOL definition anywhere within these tags, but
the start and end tags must enclose any DTAFLD or SELFLD tags to which it
applies. See “AREA (Area)” on page 213, “PANEL (Panel)” on page 397, and
“REGION (Region)” on page 424 for descriptions of these tags.
v If both PAD and PADC have been specified, PAD is ignored and PADC is used.
v When a “%varname” notation is found on any of the attributes that allow a
variable name, the “%varname” entry must follow the standard naming
convention described in “Rules for “%variable” Names” on page 201.

Nested Tags
You can code the following tags within a DTACOL definition:

Tag Name Usage Page Required

COMMENT Comment Multiple 272 No
DIVIDER Area divider Multiple 285 No
DTAFLD Data field Multiple 299 No
GRPHDR Group header Multiple 320 No
SELFLD Selection field Multiple 433 No

Chapter 13. Tag Reference 297

DTACOL
Tag Name Usage Page Required
SOURCE Source Multiple 449 No

Example
The following application panel markup contains a data column that provides
default width values for the enclosed data fields and data field descriptions. The
ENTWIDTH value specified on the first and second data fields override the
ENTWIDTH value specified on the DTACOL tag. Figure 111 on page 299 shows the
formatted result.
<!DOCTYPE DM SYSTEM(
<!entity sampvar1 system>
<!entity sampabc system>)>
&sampvar1;

<PANEL NAME=dtacol2 KEYLIST=keylxmp>Library Card Registration

<AB>
&sampabc;
</AB>
<TOPINST> Type in patron's name and card number (if applicable)
<TOPINST> Then select an action bar choice.
<AREA>
<DTACOL PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25 SELWIDTH=25
<DTAFLD DATAVAR=curdate USAGE=out ENTWIDTH=8>Date
<DTAFLD DATAVAR=cardno ENTWIDTH=7>Card No.
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address>Address
</DTACOL>
<DIVIDER>
<REGION DIR=horiz>
<SELFLD NAME=cardsel PMTWIDTH=30 SELWIDTH=38>Choose
one of the following
<CHOICE CHECKVAR=card MATCH=new>New
<CHOICE CHECKVAR=card MATCH=renew>Renewal
<CHOICE CHECKVAR=card MATCH=replace>Replacement
</SELFLD>
<SELFLD TYPE=multi PMTWIDTH=30 SELWIDTH=25>Check valid branches
<CHOICE NAME=north HELP=nthhlp CHECKVAR=nth>North Branch
<CHOICE NAME=south HELP=sthhlp CHECKVAR=sth>South Branch
<CHOICE NAME=east HELP=esthlp CHECKVAR=est>East Branch
<CHOICE NAME=west HELP=wsthlp CHECKVAR=wst>West Branch
</SELFLD>
</REGION>
</AREA>
<CMDAREA>Enter a command
</PANEL>

298 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 DTAFLD

File Search Help

--------------------------------------------------------------------------
Library Card Registration

Type in patron's name and card number if applicable.

Then select an action bar choice.

Date . . . : 08/29/90
Card No. . . _______ (A 7-digit number)
Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following Check valid branches

__ 1. New _ North Branch
2. Renewal _ South Branch
3. Replacement _ East Branch
_ West Branch

Enter a command ===> ______________________________________________________

F1=Help F2=Split F3=Exit F6=KEYSHELP F9=Swap
F12=Cancel

Figure 111. Data Column

DTAFLD (Data Field)

The DTAFLD tag defines an input field, an output field, or an input/output field
on an application panel.

ÊÊ <DTAFLD DATAVAR=field-data Ê
NAME=field-name

Ê Ê
VARCLASS=variable-class-name NO
HELP= YES
help-panel-name
*help-message-id
%varname
*%varname

Ê Ê
BOTH NO
USAGE= IN REQUIRED= YES
OUT YES MSG=message-identifier

Ê Ê
NO ENTWIDTH=n PMTWIDTH= n
AUTOTAB= YES *
**

Ê Ê
DESWIDTH= n FLDSPACE=n START
* ALIGN= CENTER
END

Chapter 13. Tag Reference 299

DTAFLD
Ê Ê
BEFORE YES NOENDATTR
PMTLOC= ABOVE DISPLAY= NO

Ê Ê
PAD= NULLS PADC= NULLS
USER USER
char char
%varname %varname

Ê Ê
NONE CUA
OUTLINE= L PMTFMT= ISPF
R NONE
O END
U
BOX
%varname

Ê Ê
PSVAR= point-and-shoot-variable
%varname

Ê Ê
PSVAL= point-and-shoot-value PAS=%varname
%varname

Ê Ê
NO EXPAND FLDWIDTH=n NO
CSRGRP= YES ATTRCHANGE= YES
n NEW

Ê Ê
INIT=initial-value DEPTH= n
%varname

Ê Ê
IMAPNAME= imnage-name IMAP Group YES
%varname DBALIGN= NO
PROMPT
FIELD
FORCE

Ê Ê
NO NO CUA
PMTSKIP= YES DESSKIP= YES FLDTYPE= ISPF

300 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 DTAFLD
Ê Ê
COLOR= WHITE HIGH
RED INTENS= LOW
BLUE NON
GREEN %varname
PINK
YELLOW
TURQ
%varname

Ê Ê
HILITE= USCORE ATTRCHAR=code OFF
BLINK CAPS= ON
REVERSE
%varname

Ê > ÊÍ
OFF prompt-text </DTAFLD>
NOJUMP= ON

IMAP Group:

IMAPNAMEP= image-namep ABOVE

%varname PLACE= BELOW
LEFT
RIGHT
%varname

NAME=field-name
This attribute specifies the name of the field. The field-name must follow the
standard naming convention described in “Rules for Variable Names” on
page 201.

The field-name can be used by:

v The PANEL tag to position the cursor
v The ISPF DISPLAY or TBDISPL services to position the cursor
v The ISPF ADDPOP service to position a pop-up.
DATAVAR=field-data
This attribute specifies the variable name for the data in the field. The value
coded must be a variable-name without the leading % notation. The conversion
utility considers NAME and DATAVAR to be synonymous. However, the value
you assign DATAVAR has precedence. For example, if you specify different
values for the DATAVAR and NAME attributes, the conversion utility uses the
DATAVAR value as the name of the field on the panel.

Chapter 13. Tag Reference 301

 DTAFLD

Compatibility Considerations

DATAVAR is a required attribute for the DTAFLD tag. For backward

compatibility between releases, you can code either the NAME or the
DATAVAR attributes, or both.

VARCLASS=variable-class-name
This attribute specifies the name of the variable class, defined using a
VARCLASS tag, that overrides the default variable class referred to by the
VARDCL that declared the data variable for this field.
| HELP=NO | YES | help-panel-name | *help-message-id | %varname |
| *%varname
| This attribute specifies the help action taken when the user requests help for
| this data field. This is field-level help.

| When HELP=YES, control is returned to the application. You can specify either
| a help panel or a message identifier. If a message identifier is used, it must be
| prefixed with an asterisk (*).

| The help attribute value can be specified as a variable name. When %varname
| is coded, a panel variable name is created. When *%varname is coded, a
| message variable name is created.

| If the user requests help for the data field and no help is defined, the extended
| help panel is displayed. If an extended help panel is not defined for the panel,
| the application or ISPF tutorial is invoked.

| The help-panel-name must follow the standard naming convention described in

| “Rules for Variable Names” on page 201.

| See “HELP (Help Panel)” on page 323 for information on creating help panels.
| For information about creating messages, see “MSG (Message)” on page 376.
USAGE=BOTH | IN | OUT
This attribute indicates whether the field is for input only, output only, or both.

For USAGE=OUT, the conversion utility inserts a colon as the last character of
the data field prompt to indicate to the user that it is an output-only field.
REQUIRED=NO | YES
This attribute indicates if the field requires input. This attribute is valid only
when USAGE=IN or BOTH.

If REQUIRED=YES is coded, a VER(variable,NONBLANK) statement will be

built by the conversion utility and placed in the )PROC section of the ISPF
panel generated.
MSG=message-identifier
This attribute specifies the message that is displayed when the user does
not complete a required entry (defined with the REQUIRED attribute). If
you do not specify a message-identifier, ISPF displays a default message.

If you specify the MSG attribute and REQUIRED=YES, a

VER(variable,NONBLANK,MSG=message-identifier) statement is built by

302 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 DTAFLD
the conversion utility and placed in the )PROC section of the ISPF panel
generated. If you specify the MSG attribute and REQUIRED=NO (the
default), the conversion utility issues a warning message.

See “MSG (Message)” on page 376 for information on creating messages.

Note: You can specify messages pertaining to other validations using

XLATL and CHECKL tags within a VARCLASS definition. See the
descriptions of these tags for additional information.
AUTOTAB=NO | YES
When AUTOTAB=YES, the cursor moves to the next field capable of input
when the user enters the last character in this field. If no other field capable of
user input exists on the panel, the cursor returns to the beginning of this field.
The ISPF SKIP keyword is not supported when running in GUI mode.

AUTOTAB=YES is valid only when the value for USAGE is either BOTH or
IN. If specified, this attribute overrides the AUTOTAB value of the DTACOL
tag.
ENTWIDTH=n
This attribute specifies the number of bytes used for the data field. The
minimum width is 1 and the maximum is the remaining available panel width
less the required amount of space for field attributes. If ENTWIDTH is not
provided on either the DTAFLD tag or the enclosing DTACOL tag, the
conversion utility will use the width determined by the TYPE value ot the
associated VARCLASS.

If specified, this attribute overrides the ENTWIDTH value of the DTACOL tag.
PMTWIDTH=n | * | **
This attribute specifies the number of bytes used for the data field prompt-text.
The minimum width is 0 and the maximum is the remaining available panel
(or region) width less the required amount of space for field attributes. When
you specify PMTWIDTH=*, the conversion utility uses the length of the
prompt text as the prompt width. When you specify PMTWIDTH=**, the
conversion utility uses the maximum available space as the prompt width. If
PMTFMT=CUA is specified (or defaulted) and the prompt-text has fewer
characters than the field allows, leader dots fill the remaining spaces. If any
prompt contains more characters than the width you specify, the prompt is
word-wrapped to fit on multiple lines. If PMTWIDTH is not specified and
prompt-text is present, the PMTWIDTH value will be defaulted to the length of
the prompt-text.

If specified, this attribute overrides the PMTWIDTH value of the DTACOL tag.
DESWIDTH=n | *
This attribute specifies the number of bytes used for the description text of
enclosed DTAFLDD tags. The minimum width is 0. When you specify
DESWIDTH=*, the conversion utility uses the length of the description text as
the description width. If the text is longer than the width you specify, the text
is word-wrapped to fit on multiple lines.

If specified, this attribute overrides the DESWIDTH value of the DTACOL tag.
FLDSPACE=n
This attribute specifies the number of bytes reserved for the data fields coded
within the data column. The minimum width is 2 and the maximum is the

Chapter 13. Tag Reference 303

DTAFLD
remaining available panel (or region) width. The FLDSPACE value should
include the actual entry width plus the number of entry field attributes. If the
value specified by ENTWIDTH is less than the specified FLDSPACE value, the
entry field is padded with blanks to the FLDSPACE value. This will create
blank space between the entry field and description text provided by the
DTAFLDD tag and allows you to align description text from successive
DTAFLD definitions.

If specified, this attribute overrides the FLDSPACE value of the DTACOL tag.
ALIGN=START | CENTER | END
This attribute specifies the alignment of data within the display field after all
translations have been performed. Use this attribute to align the data with the
start, the end, or the center of the display field.

This is accomplished in the conversion utility by using an attribute character

for the field that specifies JUST(LEFT) if ALIGN=START or JUST(RIGHT) if
ALIGN=END. ALIGN=CENTER will use an attribute character for the field
that specifies JUST(ASIS).

Alignment occurs if the transformed value of the dialog variable is shorter

than the display width of the field. When ALIGN=END, there is no underscore
padding performed–blanks are used.
PMTLOC=BEFORE | ABOVE
This attribute specifies whether the prompt-text of the data field appears above
or in front of the data field.
DISPLAY=YES | NO
This attribute specifies whether data will display on the screen when the user
types it in. If you specify NO, the data will not display. This attribute is useful
when creating fields for passwords or other information which you do not
want to appear on the screen.
NOENDATTR
This attribute, which is valid only when WINDOW=NO is specified on the
PANEL tag or DIR=HORIZ is specified on the REGION tag, specifies that no
ending attribute will be placed after the data field. NOENDATTR is ignored
for the last field on each panel line unless WINDOW=NO has been specified
on the PANEL tag. NOENDATTR is valid only when the DTAFLD tag is
followed by a DTAFLD, DTAFLDD, DIVIDER, or SELFLD tag.
PAD=NULLS | USER | char | %varname
This attribute specifies the pad character for initializing the field. You can
define this attribute as a variable name preceded by a “%”.

If specified, this attribute overrides the PAD value of the DTACOL tag.
PADC= NULLS | USER | char | %varname
This attribute specifies the conditional padding character to be used for
initializing the field. You can define this attribute as a variable name preceded
by a “%”.

If specified, this attribute overrides the PADC value of the DTACOL tag.
OUTLINE=NONE | L | R | O | U | BOX | %varname
This attribute provides for displaying lines around the field on a DBCS
terminal. You can define this attribute as a variable name preceded by a “%”.

304 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 DTAFLD
If specified, this attribute overrides the OUTLINE value of the DTACOL tag.
PMTFMT=CUA | ISPF | NONE | END
This attribute controls the generation of prompt leader characters. The default
is to create CUA leader dots. When ISPF is specified, and at least 4 bytes of
prompt text space remain following the prompt text, the “===>” character
string is placed in the rightmost 4 positions of the prompt text space. When
NONE is specified, no leader characters are added to the prompt text. When
END is specified, the prompt text is right justified within the prompt text
space.

If specified, this attribute overrides the PMTFMT value of the DTACOL tag.
PSVAR=point-and-shoot-variable | %varname
This attribute provides the name of a variable that is to be set when a DTAFLD
is clicked on for point-and-shoot selection. You can define this attribute as a
variable name preceded by a “%”.

The point-and-shoot-variable must follow the standard naming convention

described in “Rules for Variable Names” on page 201.
PSVAL=point-and-shoot-value | %varname
This attribute provides the value to be placed in the field specified by the
PSVAR attribute. You can define this attribute as a variable name preceded by
a “%”. To specify a blank value, the "' '" (quotation mark, apostrophe, blank,
apostrophe, quotation mark) coding notation should be used.
PAS=%varname
This attribute can be used to provide a variable name to specify ON or OFF for
point-and-shoot. When PSVAR and PSVAL have been specified without the
PAS attribute, the point-and-shoot field will be automatically enabled.
CSRGRP=NO | YES | N
When CSRGRP=YES, the conversion utility generates a cursor group number
to be used for this data field. When CSRGRP=n, the number provided is used
for this field. The PAS attribute must be specified as %varname.

The CSRGRP attribute is accepted for all data fields. It is used at run-time for
output fields only.
EXPAND
The EXPAND attribute, used in combination with EXPAND=xy on the PANEL
definition, causes the expand characters to be added to the DTAFLD definition,
effectively allowing ENTWIDTH to expand. The ENTWIDTH value must be
specified as 4 or greater for the EXPAND function to operate.

Note: If the PANEL tag attribute EXPAND is defined with no value specified,
the DTAFLD tag EXPAND attribute is not used.
FLDWIDTH=n
The FLDWIDTH attribute, used in combination with WINDOW=NO on the
PANEL definition, provides the width of a DTAFLD which spans multiple
lines.

FLDWIDTH cannot be used within any horizontal region.

ATTRCHANGE=NO | YES | NEW
When ATTRCHANGE=YES or ATTRCHANGE=NEW, the conversion utility
formats an additional entry in the panel )ATTR section (that can apply to
multiple data fields) instead of creating a unique “.ATTR(field-name)” entry in

Chapter 13. Tag Reference 305

DTAFLD
the )INIT section for this field. With this option, multiple DTAFLD tags with
the same characteristics require fewer panel logic statements.
ATTRCHANGE=NEW creates a new entry. ATTRCHANGE=YES uses an
existing entry, if possible.
INIT=initial-value
When the INIT attribute is specified, the conversion utility adds a statement to
the panel )INIT section to initialize the field to the initial-value.
DEPTH=n | %varname
This attribute defines the depth reserved for the field. When the panel is
displayed in GUI mode, a field specified as point-and-shoot results in a push
button displayed with the specified DEPTH. You use this attribute in
combination with the IMAPNAME attribute to provide space for the image.
The minimum value is 1 and the maximum value is the remaining panel
depth.
IMAPNAME=image-name | %varname
This attribute specifies the name of an image to be placed on the
point-and-shoot push button when it is displayed in GUI mode. The
image-name is not used when the panel is displayed in host mode.

The image-name must follow the standard naming convention described in

“Rules for Variable Names” on page 201.
IMAPNAMEP=image-namep | %varname
This attribute specifies the name of an image to be placed on the
point-and-shoot push button after it has been pushed when it is displayed
in GUI mode. The image-namep is not used when the panel is displayed in
host mode.

The image-namep must follow the standard naming convention described in

“Rules for Variable Names” on page 201.
PLACE=ABOVE | BELOW | LEFT | RIGHT
This attribute specifies the position of the image relative to the text within
the point-and-shoot push button.
DBALIGN=YES | NO | PROMPT | FIELD | FORCE
This attribute defines the DBALIGN value. DBALIGN is used only for DBCS
language conversions when PMTLOC=ABOVE and the DBALIGN invocation
option is specified.

When DBALIGN=PROMPT, the start position of the prompt-text is shifted 1

position to the right.

When DBALIGN=FIELD, the start position of the data field is shifted 1

position to the right.

When DBALIGN=YES, and the prompt-text starts with a DBCS character, the
data field is shifted. If DBALIGN=YES and the prompt text starts with an SBCS
character or the prompt text is not provided, no shifting is done.

When DBALIGN=FORCE, both the prompt-text and the data field are shifted.
DBALIGN=YES and DBALIGN=FORCE are useful to align a DTAFLD with
another DTAFLD or SELFLD tag.

When DBALIGN=NO, no alignment adjustment is made.

306 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 DTAFLD
PMTSKIP=NO | YES
This attribute is used for horizontal formatting of input fields. When
PMTSKIP=YES, and the previous DTAFLD definition includes the
NOENDATTR attribute, the cursor moves past the prompt text to the input
field when the user enters the last character in the previous field. If there is no
other input field on the panel, the cursor returns to the first input field on the
panel. The ISPF SKIP keyword is not supported in GUI mode.
DESSKIP=NO | YES
This attribute is used for horizontal formatting of input fields. When
DESSKIP=YES, and the current DTAFLD definition includes the NOENDATTR
attribute, the cursor skips over the description text provided by the DTAFLDD
tag to the next input field when the user enters the last character in the current
field. If there is no other input field on the panel, the cursor returns to the first
input field on the panel. The ISPF SKIP keyword is not supported in GUI
mode.
| FLDTYPE=CUA | ISPF
| This attribute defines the attribute type to be applied to the table field.
| TYPE=CUA, the default, causes the field to display using the standard CUA
| attrubute. When FLDTYPE=ISPF, a non-CUA attribute entry is generated for
| the )ATTR section, and you can specify the color, intensity, and highlighting of
| the attribute. See the COLOR, INTENS, and HILITE attributes that follow for
| more information. These attributes are not valid when FLDTYPE=CUA.

| Note: IF DISPLAY=NO is specified, an .ATTR(...) is created to override this

| field.
| COLOR=WHITE | RED | BLUE | GREEN | PINK | YELLOW | TURQ |
%varname
This attribute specifies the color of the field. You can define this attribute as a
variable name preceded by a percent (%) sign.
INTENS=HIGH | LOW | NON | %varname
This attribute defines the intensity of the field. You can define this attribute as
a variable name preceded by a percent (%) sign.
HILITE=USCORE | BLINK | REVERSE | %varname
This attribute specifies the extended highlighting attribute of the field. You can
define this attribute as a variable name preceded by a percent (%) sign.
| ATTRCHAR=code
| This attribute can be a single character or a two-position entry of valid hex
| digits. If you enter an incorrect value, a warning message is issued and the
| value is set to null. Hex entries are converted to character. Hex values ‘00’–‘2F’
| are reserved for use by the conversion utility.
| CAPS=OFF | ON
| When CAPS=ON, the data in the field is displayed in uppercase characters.
| NOJUMP=OFF | ON
| When NOJUMP=ON, the JUMP function is disabled for the field.
prompt-text
This is the prompt text for the data field. The prompt-text appears in front of or
above the field, depending on the setting of the PMTLOC attribute. If you do
not specify prompt text, no text appears for the field.

If the prompt-text exceeds the width defined for a prompt, it is word-wrapped

to multiple lines.

Chapter 13. Tag Reference 307

DTAFLD
Description
The DTAFLD tag defines an input field, an output field, or an input/output field
on an application panel.

The formatted width of the field is 2 positions more than the ENTWIDTH value to
provide for an attribute byte both before and after the field.

If PMTLOC=ABOVE, an attribute is placed both before and after the prompt text
reserved space. If PMTLOC=BEFORE (or PMTLOC is not specified), and the
DTAFLD is being formatted in a horizontal region, then an additional byte is used
for the field prompt attribute when the field prompt is not at the left edge of the
panel.

The DTAFLDD tag can be used to provide the description text for the data field.

Conditions
v You must code the DTAFLD tag within an AREA, DTACOL, PANEL, or
REGION definition. See “AREA (Area)” on page 213, “DTACOL (Data Column)”
on page 293, “PANEL (Panel)” on page 397, and “REGION (Region)” on
page 424 for descriptions of these tags.
v The variable name specified in the DATAVAR attribute should have an
associated VARDCL definition. See “VARDCL (Variable Declaration)” on
page 463 for a complete description of this tag.
v If both PAD and PADC have been specified, PAD is ignored and PADC is used.
v When a “%varname” notation is found on any of the attributes that allow a
variable name, the “%varname” entry must follow the standard naming
convention described in “Rules for “%variable” Names” on page 201.

Nested Tags
You can code the following tags within a DTAFLD definition:

Tag Name Usage Page Required

ASSIGNL Assignment list Multiple 221 No
COMMENT Comment Multiple 272 No
DTAFLDD Data field description Multiple 309 No
HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
SOURCE Source Multiple 449 No

Example
The following source file markup contains an application panel with three data
fields and the variable declarations and classes associated with the data fields. The
Date field is an output-only field that displays the current date. The Name and
Password fields are input/output fields. The Password field is defined as a
required field, and specifies DISPLAY=NO, so the user input for this field will not
be displayed. A data column specifying a default prompt width for the data fields
is also defined. Figure 112 on page 309 shows the formatted result.

308 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 DTAFLD
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=date TYPE='char 8'>

<VARCLASS NAME=name TYPE='char 25'>
<VARCLASS NAME=password TYPE='char 8'>

<VARLIST>
<VARDCL NAME=curdate VARCLASS=date>
<VARDCL NAME=namevar VARCLASS=name>
<VARDCL NAME=passvar VARCLASS=password>
</VARLIST>

<PANEL NAME=dtafld1 HELP=loghelp>System Logon

<TOPINST>Complete the following fields, then press Enter.
<AREA>
<DTACOL PMTWIDTH=12>
<DIVIDER>
<DTAFLD DATAVAR=curdate USAGE=out ENTWIDTH=8 FLDSPACE=27>Date
<DTAFLDD>(Current Date)
<DIVIDER>
<DTAFLD DATAVAR=namevar ENTWIDTH=25 DESWIDTH=25>Name
<DTAFLDD>(Last, First)
<DIVIDER>
<DTAFLD DATAVAR=passvar REQUIRED=yes ENTWIDTH=8 DISPLAY=no>Password
</DTACOL>
</AREA>
</PANEL>

System Logon

Complete the following fields, then press Enter.

Date . . . : 08/29/90 (Current Date)

Name . . . . _________________________ (Last, First)

Password . .

F1=Help F3=Exit F12=Cancel

Figure 112. Data Fields

DTAFLDD (Data Field Description)

The DTAFLDD tag defines descriptive text associated with a data field.

ÊÊ <DTAFLDD> ÊÍ
description </DTAFLDD>

description
This is the descriptive text associated with the data field.

Chapter 13. Tag Reference 309

DTAFLDD
Description
The DTAFLDD tag defines descriptive text associated with a data field. For
example, it could explain what the application user can type into the field.

The text appears in the area defined by the DESWIDTH attribute of the DTAFLD
or DTACOL tag.

You can specify more than one DTAFLDD tag for a given field. Each data field
description starts a new line.

Conditions
v You must code the DTAFLDD tag within the DTAFLD definition it is associated
with. See “DTAFLD (Data Field)” on page 299 for a complete description of this
tag.

Nested Tags
You can code the following tags within a DTAFLD definition:

Tag Name Usage Page Required

HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No

Example
The following application panel markup contains two data fields that each have
associated data field descriptions. Figure 113 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=filecls TYPE='char 8'>

<VARCLASS NAME=copycls TYPE='char 2'>

<VARLIST>
<VARDCL NAME=file VARCLASS=filecls>
<VARDCL NAME=copynum VARCLASS=copycls>
</VARLIST>

<PANEL NAME=dtafldd>Print a File

<TOPINST>Type in the name of the file you want to print
and the number of copies, then press Enter.
<AREA>
<DTAFLD DATAVAR=file PMTWIDTH=12 ENTWIDTH=8 DESWIDTH=30>Filename
<DTAFLDD>(Maximum of 8 characters)
<DTAFLD DATAVAR=copynum PMTWIDTH=12 ENTWIDTH=2 DESWIDTH=8>Copies
<DTAFLDD>(1 - 99)
</AREA>
<CMDAREA>Enter a command
</PANEL>

310 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 DTHD

Print a File

Type in the name of the file you want to print and the number of copies,
then press Enter.

Filename . . ________ (Maximum of 8 characters)

Copies . . . __ (1 - 99)

Enter a command ===> ______________________________________________________

F1=Help F3=Exit F12=Cancel

Figure 113. Data Field Descriptions

DTHD (Definition Term Header)

The DTHD tag defines the heading for the term column of a definition list.

ÊÊ <DTHD> definition-term-header ÊÍ
</DTHD>

| definition-term-header
| This is the text of the definition term header. The length of the text for the
| definition term header should be less than the specified TSIZE value in the DL
| tag. A warning message is issured if the length of the text exceeds the limit.

Description
The DTHD tag defines the heading for the term column of a definition list. You
can code multiple DTHD tags within a definition list.

The conversion utility inserts a blank line between the header and the list items
unless the COMPACT attribute is specified on the DL tag.

Conditions
v You must code the DTHD tag within a DL definition. See “DL (Definition List)”
on page 288 for a complete description of this tag.
v Each DTHD tag must be paired with and precede a definition description header
(DDHD) tag.

Nested Tags
You can code the following tags within a DTAFLD definition:

Tag Name Usage Page Required

HP Highlighted phrase Multiple 336 No

Chapter 13. Tag Reference 311

DTHD
Tag Name Usage Page Required
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No

Example
The following help panel markup contains a definition term header with the text
“Prefix”. Figure 114 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=dthd DEPTH=18>Prefix Help

<AREA>
<INFO>
<P>The following list defines each of the valid prefixes.
<DL TSIZE=12>
<DTHD>Prefix
<DDHD>Meaning
<DT>AU
<DD>Automotive
<DT>HB
<DD>Health and beauty
<DT>LG
<DD>Lawn and garden
<DT>SG
<DD>Sporting goods
</DL>
</INFO>
</AREA>
</HELP>

Prefix Help

The following list defines each of the valid

prefixes.

Prefix Meaning

AU Automotive

HB Health and beauty

LG Lawn and garden

SG Sporting goods

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 114. Definition Term Header

FIG (Figure)
The FIG tag defines the format of text so that it is set off from other text on the
panel and retains the format of the enclosed text.

ÊÊ <FIG > Ê
RULE PAGE NOSKIP
FRAME= NONE WIDTH= COL

312 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 FIG
Ê </FIG> ÊÍ
figure-content

FRAME=RULE | NONE
This attribute specifies the type of frame to put around the figure.
RULE Specifies dashed lines appears above and below the figure.
NONE
Specifies no frame; a blank line is left above and below the figure.
WIDTH=PAGE | COL
This attribute specifies where the figure should be aligned. The value PAGE
(the default) formats the figure on the original left margin. The value COL
formats the figure on the current left margin. The current left margin may be
different than the original left margin of the panel if the FIG tag is nested
within another tag that causes indenting; the UL tag, for example.
| NOSKIP
| This attribute causes the blank line normally placed before the figure to be
| skipped.
figure-content
This is the text of the figure definition.

Description
The FIG tag defines the format of text so that it is set off from other text on the
panel and retains the format of the enclosed text. Tags that normally cause word
wrapping within an information region (such as P, NOTE, or PARML) do not cause
word-wrapping when nested within a FIG definition. In addition, blank spaces and
blank lines in the source are preserved in the figure.

If any DTL source text line is too long to fit in the remaining available formatting
width, the data is truncated. A warning message is issued when the first line
within the figure is truncated.

A figure can also contain a figure caption, defined with the FIGCAP tag (see
“FIGCAP (Figure Caption)” on page 315).

Conditions
v The FIG tag requires an end tag.
v You must code the FIG tag within an INFO definition. See “INFO (Information
Region)” on page 339 for a complete description of this tag.

Nested Tags
You can code the following tags within a FIG definition:

Tag Name Usage Page Required

DL Definition list Multiple 288 No
FIGCAP Figure caption Single 315 No
HP Highlighted phrase Multiple 336 No
NOTE Note Multiple 382 No
NOTEL Note List Multiple 384 No
NT Note Multiple 386 No

Chapter 13. Tag Reference 313

FIG
Tag Name Usage Page Required
OL Ordered list Multiple 387 No
P Paragraph Multiple 390 No
PARML Parameter list Multiple 408 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
SL Simple list Multiple 447 No
UL Unordered list Multiple 457 No
XMP Example Multiple 474 No

Example
The following help panel markup contains a figure definition with a ruled frame.
The output of the text within the figure definition is identical to the figure-content.
Figure 115 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=fig DEPTH=20>ShelfBrowse Help

<AREA>
<INFO>
<FIG>

We're your local library...

CHECK US OUT!

</FIG>
</INFO>
</AREA>
</HELP>

ShelfBrowse Help

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

We're your local library...

CHECK US OUT!

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

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 115. Figure

314 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 FIGCAP

FIGCAP (Figure Caption)

The FIGCAP tag defines a caption for a figure defined with the FIG tag.

ÊÊ <FIGCAP> ÊÍ
figure-caption-text </FIGCAP>

figure-caption-text
This is the text of the figure caption.

Description
The FIGCAP tag defines a caption for a figure defined with the FIG tag. The figure
caption is formatted below the frame of the figure when FRAME=RULE is
specified on the FIG tag.

The conversion utility does not add any blank lines before or after the figure
caption.

Conditions
v You must code the FIGCAP tag within a FIG definition. See “FIG (Figure)” on
page 312 for a complete description of this tag.
v You can code only one FIGCAP within a FIG definition. Code the FIGCAP tag
following the content of the figure, before the FIG end tag.

Nested Tags
You can code the following tags within a FIG definition:

Tag Name Usage Page Required

HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No

Example
The following help panel markup contains a figure definition with an enclosed
figure caption. Figure 116 on page 316 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=figcap DEPTH=20>ShelfBrowse Help

<AREA>
<INFO>
<FIG>

We're your local library...

CHECK US OUT!

<FIGCAP>Our Motto
</FIG>
</INFO>
</AREA>
</HELP>

Chapter 13. Tag Reference 315

FIGCAP

ShelfBrowse Help

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

We're your local library...

CHECK US OUT!

------------------------------------------------
Our Motto

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 116. Figure Caption

GA (Graphic Area)
The GA tag allows the creation of graphic areas on ISPF panels.

ÊÊ <GA NAME=graphic-area-name Ê
OFF DEPTH= n
EXTEND= ON *
FORCE

Ê Ê
WIDTH=n NONE LVLINE=variable-name
DIV= BLANK DIV Options
SOLID
DASH
TEXT

Ê > ÊÍ
</GA>

DIV Options:

FORMAT= START TEXT=divider-text

CENTER
END

NAME=graphic-area-name
This attribute defines the name of the graphic area. This name is the dialog
variable specified by the application that provides the data for the graphic
area.

316 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 GA
The NAME attribute must follow the standard naming convention described in
“Rules for Variable Names” on page 201.
EXTEND=OFF | ON | FORCE
This attribute defines the run-time display size of the graphic area. If
EXTEND=ON is specified, the graphic area definition is expanded to the size
of the logical screen. If you intend to display the panel in a pop-up window,
use EXTEND=OFF (which is the default.)

If EXTEND=FORCE is specified within a horizontal area or region, the

EXTEND(ON) keyword is added to the graphic area attribute statement in the
)ATTR panel section. The conversion utility issues a message to advise of a
potential display error if other panel fields are formatted on or after the last
defined line of the graphic area.
DEPTH=n | *
This attribute specifies the number of lines reserved for the graphic area
definition. The DEPTH attribute value reserves space within the panel )BODY
section. The minimum depth is one line. will reserve the remaining available
panel depth for the graphic area.
WIDTH=n
This attribute specifies the number of columns reserved for the graphic area
definition. The minimum width is the number of positions in the graphic area
name plus 4 and the maximum is 2 positions less than the panel width. The
conversion utility places attribute bytes on both sides of the graphic area.
DIV=NONE | BLANK | SOLID | DASH | TEXT
This attribute specifies the type of divider line to be placed before and/or after
the graphic area. If this attribute is not specified or has the value NONE, no
divider line is generated. The value BLANK produces a blank line. You must
specify SOLID, DASH, or TEXT to produce a visible divider line. When the
GRAPHIC invocation option is specified, SOLID produces a solid line for host
display and DASH produces a dashed line. When NOGRAPHIC is specified or
the panel is displayed in GUI mode, both SOLID and DASH produce a dashed
line. A visible divider line formats with a non-displayable attribute byte on
each end of the line.
FORMAT=START | CENTER | END
This attribute specifies the position of the divider-text within the divider
line. You must specify both the FORMAT attribute and the TEXT attribute
to create a divider line containing text.
TEXT=divider-text
This attribute specifies the text to be placed on the divider line. You must
specify both the FORMAT attribute and the TEXT attribute to create a
divider line containing text.
LVLINE=variable-name
This attribute allows you to specify the name of a variable which contains the
result of the ISPF function LVLINE.

The LVLINE attribute must follow the standard naming convention described
in “Rules for Variable Names” on page 201.

Description
| The GA tag defines a graphic area in the panel )BODY section.

Chapter 13. Tag Reference 317

 GA
If you specify the CMDAREA tag within your DTL source file, it must appear
before the GA tag when DEPTH=* is specified. The GA tag DEPTH may have to be
adjusted to allow for additional lines which result from tags present within the
panel definition following the end GA tag.

Refer to the ISPF User’s Guide for a discussion of the graphic area in ISPF panels.

Conditions
v You must code the GA tag within a PANEL, AREA, or REGION tag. If found
anywhere else, an error is logged and the output panel is not saved.
v If NAME is not valid or not specified, an error is logged and the output panel is
not saved.
v You can use the EXTEND=ON attribute only once within a panel. If EXTEND is
already active, from another GA tag, or from an AREA, DA, SELFLD, or
REGION tag, a warning message is logged and the EXTEND attribute is
ignored.
v You can code only one GA tag within a PANEL definition.
v You cannot code the GA tag within a scrollable area.

Nested Tags
None.

Example
<!DOCTYPE DM SYSTEM(
<!entity sampvar1 system>
<!entity sampabc system>)>
&sampvar1;

<PANEL NAME=ga KEYLIST=keylxmp>Library Card Registration

<AB>
&sampabc;
</AB>
<TOPINST> Type in patron's name and card number (if applicable)
<AREA>
<DTACOL PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25 SELWIDTH=25>
<DTAFLD DATAVAR=curdate USAGE=out ENTWIDTH=8>Date
<DTAFLD DATAVAR=cardno ENTWIDTH=7>Card No.
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address>Address
</DTACOL>
<DIVIDER>
<GA NAME=garea DIV=solid DEPTH=6 WIDTH=40>
</GA>
</AREA>
<CMDAREA>Enter a command
</PANEL>

| GENERATE (Generate)
| The GENERATE tag provides direct formatting for )BODY and )AREA panel
| sections.

| ÊÊ <GENERATE> </GENERATE> ÊÍ

318 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 GENERATE
| Description
| The GENERATE tag is used to add pre-formatted displayable panel contents into
| the )BODY or )AREA panel sections. These contents can contain any valid
| displayable information. It is the panel developer’s responsibility to provide valid
| displayable data.

| The pre-formatted information is coded within a nested SOURCE tag. The

| SOURCE tag TYPE attribute is automatically determined based on the position of
| the GENERATE tag within the DTL source file. When panel attributes are required,
| the ATTR tag can be used to define the necessary )ATTR section entries.

| Conditions
| v The GENERATE tag requires an end tag.
| v You must code the GENERATE tag within an AREA, HELP or PANEL tag
| definition.

| Nested Tags
| You can code the following tags within a FIG definition:
|| Tag Name Usage Page Required
| ATTR Attribute Multiple 224 No
| COMMENT Comment Multiple 272 No
| SOURCE Source Multiple 449 No
|

| Example
| The following markup shows contains a GENERATE tag with nested ATTR and
| SOURCE tags. Figure 117 on page 320 shows the generated panel file.
| <:DOCTYPE DM SYSTEM>
| <PANEL NAME=* KEYLIST=keylxmp applid=isr window=no>
| Generate Tag Example
|
| <CMDAREA>
| <pnlinst compact>
| Sample panel source to illustrate the GENERATE tag.
|
| <divider type=solid gap=no>
|
| <genereate>
| <attr attrchar=! type=FP>
| <attr attrchar=_ type=NEF>
| <attr attrchar=+ type=NT>
|
| <source>
| ! Project ===>_PROJECT !
| ! Group ===>_GROUP1 !===>_GROUP2 !===>_GROUP3 !===>_GROUP4 +
| ! Type ===>_TYPE !
| ! Member ===>_MEMBER !
|
| ! DS Name ===>_OTHERDSN +
| ! Volume ===>_VOLUME+
| </source>
| </genereate>
|
| </panel>
|

Chapter 13. Tag Reference 319

 GENERATE
|
)PANEL KEYLIST(KEYLXMP,ISR)
)ATTR DEFAULT(""") FORMAT(MIX)
05 TYPE(PT)
06 TYPE(PIN)
09 TYPE(FP)
0A TYPE(NT)
13 TYPE(NEF)
22 TYPE(WASL) SKIP(ON) GE(ON)
! TYPE(FP)
_ TYPE(NEF)
+ TYPE(NT)
)BODY CMD(ZCMD)
Generate Tag Example

Command ===> Z

Sample panel source to illustrate the GENERATE tag.

------------------------------------------------------------------------------
! Project ===>_PROJECT !
! Group ===>_GROUP1 !===>_GROUP2 !===>_GROUP3 !===>_GROUP4 +
! Type ===>_TYPE !
! Member ===>_MEMBER !
! DS Name ===>_OTHERDSN +
! Volume ===>_VOLUME+
)INIT
.ZVARS = '(ZCMD)'
&ZCMD = ' '
)PROC
)END

Figure 117. Generated Panel

|
GRPHDR (Group Header)
The GRPHDR tag allows the creation of group headers on ISPF panels.

ÊÊ <GRPHDR Ê
START WIDTH=n FMTWIDTH=n
FORMAT= CENTER
END
NONE

Ê Ê
INDENT=n NO NONE
HEADLINE= YES DIV= BLANK
SOLID
DASH

Ê > Ê
AFTER COMPACT STRIP group-heading-text
DIVLOC= BEFORE
BOTH

Ê ÊÍ
</GRPHDR>

320 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 GRPHDR
FORMAT=START | CENTER | END | NONE
This attribute specifies the type of group header formatting.

When FORMAT=NONE, the lines of group-heading-text are placed in the panel

)BODY section without alteration. The processing is similar to the LINES tag.

When the values START, CENTER, or END are specified, the data is processed
in a manner similar to the P tag. The group-heading-text is read and flowed to
fit within the width limit specified by FMTWIDTH. Multiple lines may be
added to the panel, depending on the length of the group-heading-text.
WIDTH=n
This attribute specifies the number of columns reserved for the group heading.
The minimum width for a group heading is 4. The maximum value is the
remaining panel width. If WIDTH is not specified, the default value is set to
the remaining panel width. The conversion utility uses 2 positions from the
specified or default WIDTH for attributes.
FMTWIDTH=n
This attribute specifies the number of columns to use for formatting the
group-heading-text. The minimum formatting width is 2. The maximum value is
the value specified or defaulted for WIDTH. If FMTWIDTH is not specified,
the default value is set to the value of WIDTH.
| INDENT=n
| This attribute specifies that the group heading is to be indented from the
| current position.
HEADLINE=NO | YES
This attribute specifies whether dashes are added to span the width of the
group heading not occupied by text. This allows a visual indication of the
width of the group heading.
DIV=NONE | BLANK | SOLID | DASH
This attribute specifies the type of divider line to be placed before and after the
group heading. If this attribute is not specified or has the value NONE, no
divider line is generated. The value BLANK produces a blank line. You must
specify SOLID or DASH to produce a visible divider line. When the GRAPHIC
invocation option is specified, SOLID produces a solid line for host display
and DASH produces a dashed line. When NOGRAPHIC is specified or the
panel is displayed in GUI mode, both SOLID and DASH produce a dashed
line.
DIVLOC=AFTER | BEFORE | BOTH
This attribute specifies whether divider line is to be added after the group
heading, before the group heading or both before and after the group heading.
COMPACT
This attribute causes the group heading to format without a blank before the
heading.
STRIP
This attribute causes leading and trailing blanks to be removed from the
heading.
group-heading-text
This is the text of the group header. If no group-heading-text is provided, a
blank line is added to the panel unless the COMPACT attribute is also
specified.

Chapter 13. Tag Reference 321

GRPHDR
Description
The GRPHDR tag defines a group heading in the panel )BODY section.

The FMTWIDTH and HEADLINE attributes are not valid in combination with
FORMAT=NONE. The DIVLOC attribute is not valid in combination with
DIV=NONE.

You use the FMTWIDTH attribute to control the width of flowed text within the
number of columns specified by WIDTH. The FORMAT attribute controls the
placement of the resulting lines within the heading WIDTH. The FMTWIDTH
attribute has no effect if the length of the group-heading-text is less than the value
specified.

Because the group heading is formatted as text, a blank line is placed at the
beginning of each group heading unless the COMPACT attribute has been
specified. However, when the group heading is the first item in a scrollable region
the blank line is not generated.

Conditions
v You must code the GRPHDR tag within a PANEL, AREA, DTACOL, or REGION
tag. If found anywhere else, an error is logged and the output panel is not
saved.

Nested Tags
You can code the following tag within a GRPHDR tag:

Tag Name Usage Page Required

HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No

Example
<!DOCTYPE DM SYSTEM>
<!entity sampvar1 system>
<!entity sampabc system>)>
&sampvar1;

<PANEL NAME=grphdr KEYLIST=keylxmp>Library Card Registration

<AB>
&sampabc;
</AB>
<TOPINST> Type in patron's name and card number (if applicable)
<AREA>
<GRPHDR FORMAT=center WIDTH=50 FMTWIDTH=30 DIV=solid COMPACT>
Data Field Group Heading
</GRPHDR>
<DTACOL PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25 SELWIDTH=25>
<DTAFLD DATAVAR=curdate USAGE=out ENTWIDTH=8>Date
<DTAFLD DATAVAR=cardno ENTWIDTH=7>Card No.
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address>Address

322 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 GRPHDR
</DTACOL>
</AREA>
<CMDAREA>Enter a command
</PANEL>

File Search Help

-------------------------------------------------------------------------
Library Card Registration

Type in patron's name and card number (if applicable)

Data Field Group Heading

-----------------------------------------------
Date . . . : ________
Card No. . . _______ (A 7–digit number)
Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Enter a command ===> ____________________________________________________

F1=Help F3=Exit F5=Display F6=Keyshelp F10=Actions
F12=Cancel

Figure 118. Group Heading

HELP (Help Panel)

The HELP tag defines a help panel.

ÊÊ <HELP NAME=help-panel-name Ê
HELP= hhelp-panel-name
%varname

Ê Ê
HELPDEF=helpdef-id 50 10
WIDTH= n DEPTH= n
FIT FIT

Ê Ê
CCSID=n TUTOR KEYLIST=key-list-name KEYLIST Options

Ê Ê
EXPAND=xy WINTITLE=window-title APPTITLE=application-title

Ê Ê
NO YES
MERGESAREA= YES MSGLINE= NO

Chapter 13. Tag Reference 323

HELP
Ê > help-panel-title </HELP> ÊÍ
IMAPNAME= image-name IMAP Group
%varname

KEYLIST Options:

PRIVATE APPLID=application-id
KEYLTYPE= SHARED

IMAP Group:

IMAPROW= n IMAPCOL = n
%varname %varname

NAME=help-panel-name
This attribute specifies the name of the help panel. The help-panel-name must
follow the standard naming convention described in “Rules for Variable
Names” on page 201.

In addition, the help-panel-name is limited to 7 characters when the DTL source

you are converting causes the conversion utility to build multiple panels. If
you have specified an 8-position help name and multiple panels are required,
the help name will be truncated to 7 positions. If you are not creating a
scrollable help panel, this allows additional panels to be built if the help text
exceeds the limits of the original help panel. Up to 36 additional help panels
will be built to contain additional help text.

If the number of generated panels required exceeds 37, a warning message is

issued and all help text after the 37th panel is discarded. The additional panel
names are generated from the original help-panel-name by the following rules:
v The character ‘X’ will be used to pad the help-panel-name to 8 characters in
length if the original help-panel-name is less than 8 characters.
v The eighth character of the generated panel name will be incremented from
0–9 and A–Z depending on the number of panels required to be generated.
For example, if the original help-panel-name is ‘HELP1’ and the help text
extends beyond the original panel, the second generated panel name would
be ‘HELP1XX0’, and the third would be ‘HELP1XX1’.

If you specify NAME=*, the help-panel-name is set to the input DTL source
member name. If multiple dialog element definitions have been combined
within a single source file, then this notation should be used for only one
dialog element definition within the file. See “Dialog Elements” on page 5 for a
description of dialog element types created by the conversion utility.

The help-panel-name is used to build the help panel output file name in which
the conversion utility stores the converted help panel. The default name is
“userid.PANELS(help-panel-name)”.

324 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 HELP
The output panel filename can be specified on the invocation panel for the
conversion utility. You can specify the panel library of your choice. If the
SCRIPT option was specified, the help-panel-name is also used to build the file
name in which the conversion utility stores the image of the help panel. The
default name is “userid.SCRIPT(help-panel-name)”.

See “Chapter 10. Using the Conversion Utility” on page 167 for complete
information on invocation syntax.

The ISPF tutorial facility displays help panels. The user can scroll forward by
pressing Enter or the RIGHT (F11) key, or scroll backward by pressing the
LEFT (F10) key. The scrolling indicators “More: +”, “More: −”, and
“More: − +” are added to the displayed panel to indicate more help is
available.
HELP=hhelp-panel-name | %varname
This attribute specifies the name of a defined help for help panel. It identifies
the help text that is associated with help processing.

The hhelp-panel-name must follow the standard naming convention described in

“Rules for Variable Names” on page 201.

Specification of the HELP attribute will cause ISPDTLC to generate

“.HHELP=hhelp-panel-name” (or “.HHELP=&varname”) in the )INIT section
during help panel generation.

If no value is provided for the HELP attribute, the conversion utility will add
the default “.HHELP = ISP00006” to the generated panel.

ISPF displays this panel when the application user requests help and the
cursor is not on a panel field that is defined as a reference phrase.
HELPDEF=helpdef-id
This attribute specifies a defined help default. The helpdef-id value is the
identifier specified on the HELPDEF tag. You can override any of the defaults
from this HELPDEF tag by specifying that attribute on the HELP tag. See the
description of the HELPDEF tag for information on defining help defaults.
WIDTH=50 | n | FIT
This attribute specifies the width of the help panel. The default width is 50.
When you specify this attribute, it should be greater than or equal to the
minimum width of 16 characters. The maximum is 156. Because there are set
margins of 1 character on each side of the panel text to allow for 3270 attribute
bytes, the effective width for text for a help panel defined as WIDTH=50 is 48
characters.

If you have specified WIDTH=FIT, The conversion utility will format the panel
using the maximum available width. When formatting is completed the
WIDTH value will be reset to the minimum width used or to 16 if the
formatted panel is less than 16 characters wide.

If the specified WIDTH exceeds the maximum minus 4 allowed by the display
device, ISPF issues an error message at run time.
DEPTH=10 | n | FIT
This attribute specifies the depth of the HELP panel. The maximum depth is 60
and the minimum depth is 6. When the panel body does not end with a
scrollable area, four lines at the bottom of each help panel are reserved for the

Chapter 13. Tag Reference 325

HELP
function key area. Two lines are reserved at the top of the help panel for the
help-panel-title and a separator line. You must include provisions for these 6
lines in the depth you specify.

The default help panel depth of 10 is used when the DEPTH attribute
provided cannot be used or the DEPTH attribute is not specified.

If you have specified DEPTH=FIT, The conversion utility will format the panel
using a depth of 22. When formatting is completed the DEPTH value will be
reset to the minimum depth used or to 6 if the formatted panel contains less
than 6 lines.

If the specified DEPTH exceeds the maximum, minus 2, allowed by the display
device, ISPF issues an error message at run time.
CCSID=n
CCSID specifies the coded-character-set identifier as defined by the Character
Data Representation Architecture. CCSID should be entered as a five-position
numeric value. For more information on using the CCSID attribute, refer to the
ISPF Dialog Developer’s Guide and Reference
TUTOR
This attribute specifies that the panel title be formatted with the word Tutorial
(or its translated equivalent) on each end of the title line, similar to ISPF
tutorial panels.
KEYLIST=key-list-name
KEYLIST is an ISPF extension to the Dialog Tag Language. This attribute
specifies the name of the key mapping list associated with the help panel. If
you do not specify a key-list-name in a HELP definition, the ISPF-provided key
list (ISPHELP) will be used. For information on defining key mapping list, see
“KEYL (Key List)” on page 344. For information on the ISPF-provided key list,
refer to the ISPF User’s Guide
KEYLTYPE= PRIVATE | SHARED
This attribute is used to add the SHARED keyword to the KEYLIST
parameter of the )PANEL statement. For information about the )PANEL
statement, refer to the ISPF Dialog Developer’s Guide and Reference The
KEYLTYPE attribute is ignored if you have not provided the KEYLIST
attribute as part of the HELP tag definition or as part of an associated
HELPDEF tag definition.
APPLID=application-id
This attribute is used to add the application ID to the )PANEL statement.
The application-id overrides the KEYLAPPL invocation option value. The
APPLID attribute is ignored if you have not provided the KEYLIST
attribute as part of the HELP tag definition or as part of an associated
HELPDEF tag definition.
EXPAND=xy
This attribute adds the EXPAND(xy) attribute to the )BODY section of the
panel. If only one character is present, the second character will be set to the
same value. If the EXPAND attribute is present with no value specified, the
conversion utility will use a character from the range of low-order hex values
available for panel attributes. This removes an available character from
possible use as a panel attribute and may cause panel formatting errors.
WINTITLE=window-title
This attribute is used to add a title on the pop-up window border. The

326 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 HELP
attribute value is placed in the ISPF ZWINTTL variable. The maximum length
of the window-title text is the panel width minus 1.
APPTITLE=application-title
This attribute is used to add a title on the GUI window border. The attribute
value is placed in the ISPF ZAPPTTL variable. The maximum length of the
application-title text is the panel width minus 1.
MERGESAREA= NO | YES
This attribute controls an additional formatting step for panels with a single
scrollable area. If the entire contents of the scrollable area will fit within a
standard 24-line panel (allowing 4 lines for the function keys display), the
scrollable area content is moved into the panel body.
MSGLINE=YES | NO
This attribute controls the provision for a long message line in the generated
panel. When MSGLINE=NO, the blank line for the long message is not added
to the panel )BODY section. It is the panel designer’s responsibility to ensure
that critical panel areas are positioned so that the long message will not inhibit
use of the resulting panel.
IMAPNAME=image-name | %varname
This attribute specifies the name of an image to be placed on the panel when it
is displayed in GUI mode. The image-name is not used when the panel is
displayed in host mode.

The image-name must follow the standard naming convention described in

“Rules for Variable Names” on page 201.
IMAPROW=n | %varname
This attribute specifies the row number for positioning the image. Image
position uses an orgin based on 0. Therefore, the minimum row value is 0
and the maximum is 59, relating to the above description for the DEPTH
attribute. If a varible name is used, the application must set the variable to
a valid value before the panel is displayed. The value specified should be
within the actual panel depth for the image to be visible when the panel is
displayed.
IMAPCOL=n | %varname
This attribute specifies the column number for positioning the image.
Image position uses an orgin based on 0. Therefore, the minimum column
value is 0 and the maximum is 155, relating to the above description for
the WIDTH attribute. If a varible name is used, the application must set
the variable to a valid value before the panel is displayed. The value
specified should be within the actual panel width for the image to be
visible when the panel is displayed.
help-panel-title
This specifies the title that appears on the help panel.

The help-panel-title is centered within the specified help panel width in

accordance to CUA rules. If the title text is wider than the WIDTH specified,
the title will be truncated with an ellipses (...) appended. Two lines are
reserved for the title and a separator which can include the scrolling indicator
if there are more panels.

Chapter 13. Tag Reference 327

HELP
Description
The HELP tag defines a help panel. A help panel can contain multiple information
areas, which you use the INFO tag to define (see “INFO (Information Region)” on
page 339).

ISPF always displays help panels defined with DTL in a pop-up window with a
border. Therefore, the maximum value you can specify for the WIDTH attribute is
4 less than the maximum allowed by the display device. This allows for the left
and right borders and their 3270 attribute characters. The maximum value for the
DEPTH attribute is 2 less than the maximum allowed by the display device to
allow for the top and bottom borders. Borders are added to the formatted help
panel at run time.

If you are not creating a scrollable help panel and the text to be included in the
)BODY section of the ISPF panel exceeds the specified DEPTH value, up to 36
additional panels are generated to contain the additional text. If the help text
extends beyond the original help panel and 36 additional help panels, an error
message will be issued and the excess text will be truncated. If the error occurs,
and the DEPTH and WIDTH attributes are not set to their maximum values, the
values should be increased or the amount of text to be included in the help panel
should be reduced.

For nonscrollable HELP panels or for scrollable HELP panels which end with a
nonscrollable section, a function key area of four lines is reserved at the bottom of
the panel. The four lines are taken from the value specified for the DEPTH
attribute.

If you do not specify the KEYLIST attribute, ISPF automatically associates the
ISPF-provided key list “ISPHELP” with all DTL help panels.

The following table shows the “ISPHELP” key list and assignments:
Table 4. ISPHELP keylist and assignments
Key Command Key Label Format
F1 HELP Help Short
F2 SPLIT Split Long
F3 EXIT Exit Short
F4 RESIZE Resize Long
F5 EXHELP Exhelp Short
F6 KEYSHELP Keyshelp Short
F7 UP PrvTopic Short
F8 DOWN NxtTopic Short
F9 SWAP Swap Long
F10 LEFT PrvPage Short
F11 RIGHT NxtPage Short
F12 CANCEL Cancel Short

All ISPHELP function keys are active when the cursor is in the help panel. Display
of keys in the function key area is controlled by the user through the ISPF FKA
command.

328 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 HELP
Because help panels are displayed by the ISPF tutorial processor, the commands
assigned to the keys are those supported by the ISPF tutorial. For more
information on the ISPF tutorial, refer to the ISPF User’s Guide

Since ISPDTLC generated panels are not normally used in a full Tutorial, the
default ISPHELP keylist may result in confusion in the use of the F7 and F8 keys
for scrolling. An alternate approach is the ISPHLP2 keylist as defined below. To use
this keylist, add the KEYLIST=ISPHLP2 attribute to your help panel definition.
Table 5. ISPHLP2 keylist and assignments
Key Command Key Label Format
F1 HELP Help Short
F2 SPLIT Split Long
F3 EXIT Exit Short
F4 RESIZE Resize Long
F5 EXHELP Exhelp Short
F6 KEYSHELP Keyshelp Short
F7 LEFT PrvPage Short
F8 RIGHT NxtPage Short
F9 SWAP Swap Long
F10 LEFT PrvPage Long
F11 RIGHT NxtPage Long
F12 CANCEL Cancel Short

Conditions
v The HELP tag requires an end tag.
v You cannot code the HELP tag within any other tag definition.
v If the help panel does not have a panel body, the conversion utility issues an
error message. The help panel must contain at least one INFO (information
region) definition to qualify as a panel body. See “INFO (Information Region)”
on page 339 for a complete description of this tag.
v When a “%varname” notation is found on any of the attributes that allow a
variable name, the “%varname” entry must follow the standard naming
convention described in “Rules for “%variable” Names” on page 201.

Nested Tags
You can code the following tags within a HELP definition:

Tag Name Usage Page Required

AREA Area Multiple 213 No
COMMENT Comment Multiple 272 No
DIVIDER Divider Multiple 285 No
HP Highlighted phrase Multiple 336 Yes
INFO Information region Multiple 339 Yes
REGION Region Multiple 424 No
SOURCE Source Multiple 449 No

Chapter 13. Tag Reference 329

 HELP
Tag Name Usage Page Required
| TEXTLINE Text Line Single 452 No

Example
The following help panel markup contains an information region that contains a
paragraph, a definition list, and two unordered lists nested within the definition
list. Because all of the data does not fit in one help panel, the conversion utility
created three panels HELP, HELPXXX0, and HELPXXX1. The panels are scrollable.
Figures 119, 120, and 121 show the formatted results with the function key area
displayed in its short form.
<!DOCTYPE DM SYSTEM>

<HELP NAME=help WIDTH=46 DEPTH=16>ShelfBrowse for Kids

<AREA>
<INFO>
<P>ShelfBrowse can help you
find any kind of book you are looking for.
The two main categories for books are:
<DL TSIZE=12>
<DTHD>Book
<DDHD>Description
<DT>Fiction
<DD>Fiction books are stories
that never really happened.
The writer made them up.
For example:
<UL>
<LI>Fairy Tales
<LI>Mysteries
<LI>Science fiction stories
</UL>
<DT>Nonfiction
<DD>Nonfiction books are about
things that really exist.
For example:
<UL>
<LI>History books
<LI>Reference books
<LI>How to books
</UL>
</DL>
</INFO>
</AREA>
</HELP>

330 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 HELP

ShelfBrowse for Kids

More: +
ShelfBrowse can help you find any kind of
book you are looking for. The two main
categories for books are:

Book Description

Fiction Fiction books are stories that

never really happened. The
writer made them up. For
example:

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 119. Help Panel (Example 1 of 3)

ShelfBrowse for Kids

More: - +
o Fairy Tales

o Mysteries

o Science fiction stories

Nonfiction Nonfiction books are about

things that really exist. For
example:

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 120. Help Panel (Example 2 of 3)

ShelfBrowse for Kids

More: -
o History books

o Reference books

o How to books

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 121. Help Panel (Example 3 of 3)

Chapter 13. Tag Reference 331

HELPDEF

HELPDEF (Help default)

The HELPDEF tag defines default values for help panels.

ÊÊ <HELPDEF ID=helpdef-id Ê
HELP= hhelp-panel-name
%varname

Ê Ê
WIDTH= n DEPTH= n CCSID=n
FIT FIT

Ê Ê
KEYLIST=key-list-name KEYLIST Options EXPAND=xy

Ê Ê
WINTITLE=window-title APPTITLE=application-title

Ê Ê
NO IMAPNAME= image-name
MERGESAREA= YES %varname

Ê > ÊÍ
IMAPROW= n IMAPCOL= n </HELPDEF>
%varname %varname

KEYLIST Options:

PRIVATE APPLID=application-id
KEYLTYPE= SHARED

ID=helpdef-id
This is the ID of the help panel default definition. The ID is used as the
identifier of this set of default definitions on the HELP tag.

The helpdef-id must follow the standard naming convention described in “Rules
for Variable Names” on page 201.
HELP=hhelp-panel-name | %varname
This attribute specifies the default name of a defined help for help panel. It
identifies the help text that is associated with help processing.

The hhelp-panel-name must follow the standard naming convention described in

“Rules for Variable Names” on page 201.
WIDTH=n | FIT
This attribute specifies a default width value for a help panel that refers to this
help default.

332 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 HELPDEF
DEPTH=n | FIT
This attribute specifies a default depth value for a help panel that refers to this
help default.
CCSID=n
CCSID specifies the coded-character-set identifier as defined by the Character
Data Representation Architecture. CCSID should be entered as a five-position
numeric value. For more information on using the CCSID attribute, refer to the
ISPF Dialog Developer’s Guide and Reference
KEYLIST=key-list-name
This attribute specifies the name of the key mapping list associated with the
help panel. If you do not specify a key-list-name in a HELP definition, the
ISPF-provided key list (ISPHELP) will be used. For information on defining
key mapping list, see “KEYL (Key List)” on page 344. For information on the
ISPF-provided key list, refer to the ISPF User’s Guide
KEYLTYPE=PRIVATE | SHARED
This attribute is used to add the SHARED keyword to the KEYLIST
parameter of the )PANEL statement. For information about the )PANEL
statement, refer to the ISPF Dialog Developer’s Guide and Reference
APPLID=application-id
This attribute is used to add the application ID to the )PANEL statement.
The application-id overrides the KEYLAPPL invocation option value.
EXPAND=xy
This attribute adds the EXPAND(xy) attribute to the )BODY section of the
panel. If only one character is provided, the second character is set to the same
value. If the EXPAND attribute is present with no value specified, the
conversion utility will use a character from the range of low-order hex values
available for panel attributes. This removes an available character from
possible use as a panel attribute and may cause panel formatting errors.
WINTITLE=window-title
This attribute is used to add a title on the pop-up window border. The
attribute value is placed in the ISPF ZWINTTL variable. The maximum length
of the window-title is the panel width minus 1.
APPTITLE=application-title
This attribute is used to add a title on the GUI window border. The attribute
value is placed in the ISPF ZAPPTTL variable. The maximum length of the
application-title text is the panel width minus 1.
MERGESAREA= NO | YES
This attribute controls an additional formatting step for panels with a single
scrollable area. If the entire contents of the scrollable area will fit within a
standard 24-line panel (allowing 4 lines for the function keys display), the
scrollable area content is moved into the panel body.
IMAPNAME=image-name | %varname
This attribute specifies the name of an image to be placed on the panel when it
is displayed in GUI mode. The image-name is not used when the panel is
displayed in host mode.

The image-name must follow the standard naming convention described in

“Rules for Variable Names” on page 201.
IMAPROW=n | %varname
This attribute specifies the row number for positioning the image. Image
position uses an orgin based on 0. Therefore, the minimum row value is 0 and

Chapter 13. Tag Reference 333

HELPDEF
the maximum is 59, relating to the description for the DEPTH attribute on the
HELP tag. If a varible name is used, the application must set the variable to a
valid value before the panel is displayed. The value specified should be within
the actual panel depth for the image to be visible when the panel is displayed.
IMAPCOL=n | %varname
This attribute specifies the column number for positioning the image. Image
position uses an orgin based on 0. Therefore, the minimum column value is 0
and the maximum is 155, relating to the description for the WIDTH attribute
on the HELP tag. If a varible name is used, the application must set the
variable to a valid value before the panel is displayed. The value specified
should be within the actual panel width for the image to be visible when the
panel is displayed.

Description
The HELPDEF tag defines default values for help panels. When a HELP panel tag
refers to a help panel default, the values specified by the associated HELPDEF tag
are used for the help panel unless overriden by values specified in the HELP tag
definition.

The HELP tag can override any of the HELPDEF values by specifying that value
within its own definition. Therefore, it is possible for a HELP tag to select certain
default values from the help panel default and override others.

See “HELP (Help Panel)” on page 323 for more information.

You can code multiple HELPDEF definitions in a single application. Each help
default must have a unique helpdef-id.

Portability Considerations

In ISPF Version 3 Release 1, the Conversion Utility supported the HELPDEF

tag. In this release, the HELPDEF tag is supported to ease portability between
releases.

Conditions
v You cannot code the HELPDEF tag within any other tag definition.
v You must code the HELPDEF tag before you code any HELP tag that refers to it.

Nested Tags
None.

Example
In the following source file example, the HELPDEF definition defines default
DEPTH and WIDTH values. The help panels “help15” and “help16” both reference
the help default–“help15” uses both default values and “help16” uses only the
default WIDTH value, and overrides the default DEPTH value by specifying its
own DEPTH value. The help panel “help17” does not reference the help default,
and defines its own DEPTH and WIDTH values.
<!DOCTYPE DM SYSTEM>

<HELPDEF ID=helpdef1 DEPTH=10 WIDTH=40>

334 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 HELPDEF
<HELP
. NAME=help15 HELPDEF=helpdef1>Help for This
.
.
</HELP>

<HELP
. NAME=help16 HELPDEF=helpdef1 DEPTH=15>Help for That
.
.
</HELP>

<HELP
. NAME=help17 DEPTH=15 WIDTH=25>Help for the Other
.
.
</HELP>

Hn (Heading)
The heading tags define main topics and subtopics of information within an
information region.

ÊÊ <Hn> ÊÍ
heading-text </Hn>

heading-text
This is the text of the heading.

Description
The heading tags define main topics and subtopics of information within an
information region. You can define up to four heading levels. The n in Hn
indicates the heading level. The heading levels are formatted as follows:
H1 Identifies a main topic of information. The text is centered on the panel.
H2, H3, H4
The text is formatted against the left margin of the panel body.

Headings are formatted with one blank line before them.

Conditions
v The Hn tag must be coded within an INFO definition. See “INFO (Information
Region)” on page 339 for a complete description of this tag.

Nested Tags
You can code the following tags within an H2, H3, and H4 tag only:

Tag Name Usage Page Required

HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No

Example
The following help panel markup contains two levels of headings. Figure 122 on
page 336 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=hn DEPTH=22>Department Descriptions Help

Chapter 13. Tag Reference 335

Hn
<AREA>
<INFO>
<H1>Departments
<H2>Entertainment
<P>Our entertainment department carries the
finest in home entertainment components.
<H2>Exotic Pets
<P>You can order from a wide variety of exotic
pets and pet supplies in this department.
<H2>Toys
<P>Your kids will love our wide selection of
toys, games, and play equipment.
</INFO>
</AREA>
</HELP>

Department Descriptions Help

Departments

Entertainment

Our entertainment department carries the finest

in home entertainment components.

Exotic Pets

You can order from a wide variety of exotic pets

and pet supplies in this department.

Toys

Your kids will love our wide selection of toys,

games, and play equipment.

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 122. Headings

HP (Highlighted Phrase)
The HP tag identifies text to be displayed with highlighted emphasis.

ÊÊ <HP Ê
ET COLOR= WHITE
TYPE= CH RED
CT BLUE
FP GREEN
LEF PINK
LI YELLOW
NT TURQ
PT %varname
SAC
TEXT
WASL
WT

336 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 HP
Ê Ê
HIGH HILITE= USCORE
INTENS= LOW BLINK
NON REVERSE
%varname %varname

Ê ÊÍ
phrase-to-be-highlighted </HP>

TYPE= ET | CH | CT | FP | LEF | LI | NT | PT | SAC | TEXT | WASL | WT

This attribute defines the attribute type to be applied to the
phrase-to-be-highlighted. Using a CUA attribute causes the text to appear in the
associated color.

When TYPE=TEXT, a non-CUA attribute is generated and you can specify the
color, intensity, and highlighting with the COLOR, INTENS, and HILITE
attributes. These attributes are not valid for CUA types.
COLOR= WHITE | RED | BLUE | GREEN | PINK | YELLOW | TURQ |
%varname
This attribute specifies the color of the field. You can define this attribute as a
variable name preceded by a percent (%) sign.
INTENS= HIGH | LOW | NON | %varname
This attribute defines the intensity of a field. You can define this attribute as a
variable name peceded by a percent (%) sign.
HILITE= USCORE | BLINK | REVERSE | %varname
This attribute specifies the extended highlighting attribute of a field. You can
define this attribute as a variable name peceded by a percent (%) sign.
phrase-to-be-highlighted
This text displays with highlighted emphasis.

Description
The HP identifies text to be displayed with highlighted emphasis by ISPF. The HP
end tag restores normal text.

Conditions
v You can code the HP tag wherever the RP tag is valid.
v You can code the HP tag within the text following the CHDIV, CMDAREA,
HELP, and PANEL tags.
v The HP tag requires an end tag.

Nested Tags
None.

Example
The following markup shows the formatted result in Figure 123 on page 338.
<!DOCTYPE DM SYSTEM(
<!entity sampvar1 system>
<!entity sampabc system>)>
&sampvar1;

Chapter 13. Tag Reference 337

HP

<PANEL NAME=hp KEYLIST=keylxmp>Library Card Registration

<AB>
&sampabc;
</AB>
<TOPINST> Type in <HP>patron's name</HP> and <HP>card number</HP>
(if applicable)
<TOPINST> Then select an action bar choice.
<AREA>
<DTACOL PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25 SELWIDTH=25>
<DTAFLD DATAVAR=curdate USAGE=out ENTWIDTH=8>Date
<DTAFLD DATAVAR=cardno ENTWIDTH=7>Card No.
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address>Address
</DTACOL>
<DIVIDER>
<REGION DIR=horiz>
<SELFLD NAME=cardsel PMTWIDTH=30 SELWIDTH=38>Choose
one of the following
<CHOICE CHECKVAR=card MATCH=new>New
<CHOICE CHECKVAR=card MATCH=renew>Renewal
<CHOICE CHECKVAR=card MATCH=replace>Replacement
</SELFLD>
<SELFLD TYPE=multi PMTWIDTH=30 SELWIDTH=25>Check valid branches
<CHOICE NAME=north HELP=nthhlp CHECKVAR=nth>North Branch
<CHOICE NAME=south HELP=sthhlp CHECKVAR=sth>South Branch
<CHOICE NAME=east HELP=esthlp CHECKVAR=est>East Branch
<CHOICE NAME=west HELP=wsthlp CHECKVAR=wst>West Branch
</SELFLD>
</REGION>
</AREA>
<CMDAREA>Enter a command
</PANEL>

File Search Help

--------------------------------------------------------------------------
Library Card Registration

Type in patron's name and card number (if applicable).

Then select an action bar choice.

Date . . . :
Card No. . . _______ (A 7-digit number)
Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following Check valid branches

__ 1. New _ North Branch
2. Renewal _ South Branch
3. Replacement _ East Branch
_ West Branch

Enter a command ===> ______________________________________________________

F1=Help F2=Split F3=Exit F6=KEYSHELP F9=Swap
F12=Cancel

Figure 123. HP (Highlighted Phrase)

338 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 INFO

INFO (Information Region)

The INFO tag defines an information region for a panel.

ÊÊ <INFO > </INFO> ÊÍ

WIDTH= format-width INDENT=n
*

WIDTH=format-width | *
This attribute determines the width the conversion utility uses to format the
text in the ISPF )BODY section of the panel. If WIDTH is not the value is set to
the remaining available panel (or region) width. If specified, the WIDTH value
cannot be larger than the defined width of the panel (or region) minus 2
characters. For example, a WIDTH value of 58 is acceptable for an information
region within a panel with a defined width of 60.

Note: You should code the WIDTH attribute if the information region is part
of an application panel definition that uses horizontal region capability.
The actual width used in a horizontal region is 2 characters longer than
the WIDTH attribute value to provide for attribute bytes that delimit the
region.
INDENT=n
This attribute defines the number of columns to indent the current information
region from the current left boundary.

Description
The INFO tag defines an information region for a panel. The information region is
used to display text such as paragraphs, lists, notes, examples, and figures. A
typical use of the INFO tag is for the definition of text within help panels.

Conditions
v The INFO tag requires an end tag.
v You must code the INFO tag within an AREA, HELP, or PANEL definition. See
“AREA (Area)” on page 213, “HELP (Help Panel)” on page 323, and “PANEL
(Panel)” on page 397 for descriptions of these tags.

Nested Tags
You can code the following tags within an INFO definition:

Tag Name Usage Page Required

DL Definition list Multiple 288 No
FIG Figure Multiple 312 No
Hn Heading Multiple 335 No
LINES Lines Multiple 349 No
NOTE Note Multiple 382 No
NOTEL Note List Multiple 384 No
NT Note Multiple 386 No
OL Ordered list Multiple 387 No
P Paragraph Multiple 390 No

Chapter 13. Tag Reference 339

INFO
Tag Name Usage Page Required
PARML Parameter list Multiple 408 No
SL Simple list Multiple 447 No
UL Unordered list Multiple 457 No
XMP Example Multiple 474 No

Example
The following help panel markup contains an information region. The text of the
information region is defined using two P (paragraph) tags and an unordered list
(UL) tag with three LI (list item) tags. Figure 124 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=info WIDTH=60 DEPTH=22>ShelfBrowse Help

<AREA>
<INFO WIDTH=42>
<P>When ShelfBrowse finds your book, it displays this
information:
<UL>
<LI>Reference information about the book.
<LI>The location of the book.
<LI>If the book is in stock.
<P>If the book is not in stock, see the librarian.
</UL>
</INFO>
</AREA>
</HELP>

ShelfBrowse Help

When ShelfBrowse finds your book, it

displays this information:

o Reference information about the book.

o The location of the book.

o If the book is in stock.

If the book is not in stock, see the

librarian.

F1=Help F3=Exit F5=Exhelp F6=Keyshelp

F7=PrvTopic F8=NxtTopic F10=PrvPage F11=NxtPage
F12=Cancel

Figure 124. Information Region

KEYI (Key Item)

The KEYI tag defines a key assignment within a key mapping list.

340 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 KEYI
ÊÊ <KEYI KEY=virtual-key CMD=internal-command-name Ê
UPPER
CASE= MIXED

Ê > ÊÍ
NO PARM=parm-string FKA-text </KEYI>
FKA= YES
LONG
SHORT

KEY=virtual-key
This attribute specifies the name of the key to assign to the command. The
conversion utility supports F1–F24 only.
CMD=internal-command-name
This attribute specifies the command that ISPF runs when the user presses the
key.

The internal-command-name must follow the standard naming convention

described in “Rules for Variable Names” on page 201.

As an extension to the Dialog Tag Language, the conversion utility supports

special ISPF command syntax for internal-command-name. In this case, the
internal-command-name must have the following characteristics:
v 2–9 single-byte characters in length
v The first character must be a ‘>’, ‘:’, or ‘%’.
To code the > character you must use the &gtsym predefined entity. See
“Predefined Entities” on page 25 for more information.
v The second character must be A–Z, a–z, @, #, or $.
v Remaining characters, if any, must be A–Z, a–z, @, #, $, or 0–9.

Lowercase characters are translated to their uppercase equivalents by default.

CASE=UPPER | MIXED
This attribute specifies that the internal-command-name will be converted to
uppercase characters or stored as entered in the tag definition.
FKA=NO | YES | LONG | SHORT
This attribute specifies whether the key assignment is to appear in the function
key area of an application panel. The default value NO indicates that the key is
not to appear. You must specify FKA=YES, FKA=LONG, or FKA=SHORT if
you want the key to be displayed in the function key area.

When FKA=NO is specified, the key is active even if it is not displayed.

Chapter 13. Tag Reference 341

KEYI

Compatibility Considerations

In ISPF Version 3.1, the conversion utility supported the values NO,
SHORT, and LONG for the FKA attribute. The FKA attribute values have
been changed to YES and NO. FKA=YES is converted to FKA=SHORT. If
you want keys to appear only when the user chooses LONG form, you
must code FKA=LONG.

For compatiblility between releases, the conversion utility allows SHORT

or LONG.

PARM=parm-string
This attribute allows a parameter to be added to the command specified by the
CMD attribute. The combined length of the command and the parameter is
limited to 40 bytes. When the combined length exceeds 40 bytes, truncation of
the PARM occurs at the end of the last complete word in the parm-string, for a
parm-string containing multiple words. A parm-string which is a single word is
truncated at position 40.
FKA-text
This is the text for the key which is to appear in the function key area of the
panels that refer to the key list. This text is appended to the string “Fn=” (with
no intervening space) to create the displayed format. You should use initial
caps for the FKA-text value.

If not specified, the FKA-text defaults to the internal-command-name specified for

the key.

The function key area is formatted at run time based on the panel size. The
maximum number of bytes allowed for FKA-text is 64. If the text exceeds 64
bytes, it is truncated and a warning message is issued. The conversion utility
removes excess blanks from FKA-text. The first 8 bytes of the resulting text are
used by ISPF.

Description
The KEYI tag defines a key assignment within a key mapping list. Key
assignments provide a means of associating commands with keys.

KEYI tags with the same assignment cause the conversion utility to issue a
warning message and retain only the first occurrence.

Conditions
v You must code the KEYI tag within a KEYL definition. See “KEYL (Key List)” on
page 344 for a complete description of this tag.
v Each KEYI definition can only have one command assigned to it. Additionally,
CUA requires the following conventions when assigning commands to certain
keys:
– If KEY=F1 or F13, then CMD must be HELP.
– If KEY=F3 or F15, then CMD must be EXIT.
– If KEY=F12 or F24, then CMD must be CANCEL.

ISPF will allow you to provide the name of your own command on these keys.

342 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 KEYI
If you code the command HELP, EXIT, or CANCEL as part of your KEYI
definition, then HELP must be assigned to key F1 or F13, EXIT must be assigned
to F3 or F15, and CANCEL must be assigned to F12 or F24.

Nested Tags
None.

Example
The following source file markup contains a key mapping list and an application
panel that refers to the key mapping list. The F7 and F8 keys do not appear on the
panel because they both have an FKA value of NO. Figure 125 on page 344 shows
the formatted application panel with the displayed keys.
<!DOCTYPE DM SYSTEM(
<!entity sampvar1 system>
<!entity sampabc system>
<!entity sampbody system>)>
&sampvar1;

<KEYL NAME=keylxmp>
<KEYI KEY=f1 CMD=help FKA=yes>Help
<KEYI KEY=f2 CMD=split FKA=yes>Split
<KEYI KEY=f3 CMD=exit FKA=yes>Exit
<KEYI KEY=f5 CMD=search FKA=no>Display
<KEYI KEY=f6 CMD=keyhlp FKA=yes>Keyshelp
<KEYI KEY=f7 CMD=backward FKA=no>Backward
<KEYI KEY=f8 CMD=forward FKA=no>Forward
<KEYI KEY=f9 CMD=swap FKA=yes>Swap
<KEYI KEY=f10 CMD=actions FKA=no>Actions
<KEYI KEY=f12 CMD=cancel FKA=yes>Cancel
</KEYL>

<PANEL NAME=keyi KEYLIST=keylxmp>Library Card Registration

<AB>
&sampabc;
</AB>
&sampbody;
</PANEL>

Chapter 13. Tag Reference 343

KEYL

File Search Help

--------------------------------------------------------------------------
Library Card Registration

Type in patron's name and card number if applicable.

Then select an action bar choice.

Date . . . :
Card No. . . _______ (A 7-digit number)
Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following Check valid branches

__ 1. New _ North Branch
2. Renewal _ South Branch
3. Replacement _ East Branch
_ West Branch

Enter a command ===> ______________________________________________________

F1=Help F2=Split F3=Exit F6=KEYSHELP F9=Swap
F12=Cancel

Figure 125. Key Items

KEYL (Key List)

The KEYL tag defines a key mapping list where keys can be mapped to
commands.

ÊÊ <KEYL NAME=key-list-name Ê
HELP=help-panel-name

Ê > </KEYL> ÊÍ
UPDATE APPLID=application-id
ACTION= DELETE

NAME=key-list-name
This attribute specifies a name for a key list. The HELP, HELPDEF, PANEL,
and PANDEF tag refer to the key-list-name.

The key-list-name must follow the standard naming convention described in

“Rules for Variable Names” on page 201.

The name of the keylist table is xxxxKEYS where xxxx represents the
application identifier provided to ISPDTLC with the KEYLAPPL keyword
when invoked, in the “Keylist Application ID” field on the invocation panel, or
with the APPLID attribute of this tag.

The key-list-name is used to identify the entry in the keylist table. For example,
if NAME=CONVLIST and KEYLAPPL=XYZ, then CONVLIST will be written
as a table entry to member XYZKEYS in the table library partitioned data set.

Keylists are updated using ISPF table services. Input is obtained from the
ISPTLIB DDname allocation and output is written to the ISPTABL DDname
allocation. Refer to the description of how to allocate libraries before starting
ISPF in the ISPF User’s Guide for more information about the use of ISPTLIB
and ISPTABL.

344 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 KEYL
See “Chapter 10. Using the Conversion Utility” on page 167 for more
information on invocation parameters for the conversion utility.
HELP=help-panel-name
This attribute names a help panel that displays when the user requests help on
a keylist display.

If a user requests help for a keylist and no help has been defined by the KEYL
tag, the ZKEYHELP variable is checked for a help panel name. If the
application has not set ZKEYHELP, a message that keyshelp is not available is
displayed.

The help-panel-name must follow the standard naming convention described in

“Rules for Variable Names” on page 201.

See “HELP (Help Panel)” on page 323 for information on creating help panels.
ACTION=UPDATE | DELETE
This attribute specifies the type of action requested for the keylist specified by
key-list-name.

When ACTION=DELETE is specified, it is not necessary to nest any KEYI tags

within the KEYL tag definition.
APPLID=application-id
This attribute provides the application ID used to build the keylist name. The
application-id overrides the KEYLAPPL invocation option value.

Description
The KEYL tag defines a key mapping list where keys can be mapped to
commands.

To display these keys on a panel requires that the PANEL or PANDEF tag refer to
the key-list-name. ISPF uses the specified key mapping list when building the
display dependent on the user’s setting by the FKA command. For more
information on displaying and formatting of the function key area, refer to the
appropriate section in the ISPF User’s Guide

Conditions
v The KEYL tag requires an end tag.
v The KEYL tag cannot be nested within any other tag definition.
v When ACTION=UPDATE is specified (or defaulted), at least one KEYI tag must
be included in the keylist definition.

Nested Tags
You can code the following tag within a KEYL definition:

Tag Name Usage Page Required

KEYI Key item Multiple 340 No

Example
The following source file markup contains a key mapping list and an application
panel that refers to the key mapping list. Figure 126 on page 346 shows the
formatted application panel with the displayed keys.

Chapter 13. Tag Reference 345

KEYL
<!DOCTYPE DM SYSTEM(
<!entity sampvar1 system>
<!entity sampabc system>
<!entity sampbody system>)>
&sampvar1;

<KEYL NAME=keyltbl>
<KEYI KEY=f1 CMD=help FKA=yes>Help
<KEYI KEY=f2 CMD=split FKA=yes>Split
<KEYI KEY=f3 CMD=exit FKA=yes>Exit
<KEYI KEY=f5 CMD=search FKA=no>Display
<KEYI KEY=f6 CMD=keyhlp FKA=no>Keyshelp
<KEYI KEY=f7 CMD=backward FKA=yes>Backward
<KEYI KEY=f8 CMD=forward FKA=yes>Forward
<KEYI KEY=f9 CMD=swap FKA=yes>Swap
<KEYI KEY=f10 CMD=actions FKA=no>Actions
<KEYI KEY=f12 CMD=cancel FKA=yes>Cancel
</KEYL>

<PANEL NAME=keyl KEYLIST=keylxmp>Library Card Registration

<AB>
&sampabc;
</AB>
&sampbody;
</PANEL>

File Search Help

--------------------------------------------------------------------------
Library Card Registration

Type in patron's name and card number if applicable.

Then select an action bar choice.

Date . . . :
Card No. . . _______ (A 7-digit number)
Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following Check valid branches

__ 1. New _ North Branch
2. Renewal _ South Branch
3. Replacement _ East Branch
_ West Branch

Enter a command ===> ______________________________________________________

F1=Help F2=Split F3=Exit F6=KEYSHELP F9=Swap
F12=Cancel

Figure 126. Function Keys

LI (List Item)
The LI tag defines a list item within a note list, ordered list, unordered list, or
simple list.

ÊÊ <LI > ÊÍ
NO NOSKIP item-text </LI>
SPACE= YES

346 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 LI
SPACE=NO | YES
The SPACE attribute controls the indentation space for the list item. When the
SPACE attribute is not specified on the LI tag, the SPACE attribute from the
enclosing list tag is used to set the indentation space for the item-text.

When SPACE=YES, the indentation is set to 3 spaces. When SPACE=NO (or

SPACE is not specified), the indentation is set to 4 spaces.

The SPACE attribute can be used to control the alignment of list items when
the first word of some list items is a DBCS word preceded by a shift-out
character and the first word of other list items is a SBCS word.
| NOSKIP
| This attribute causes the list item to format without creating a blank line before
| the item.
item-text
This is the text of the list item.

Description
The LI tag defines a list item within a note list, ordered list, unordered list, or
simple list.

The formatting of the LI tag is dependent on the type of list you use it within and
the level of nesting.
List Formatting
Note Formats with a 3-space or 4-space indentation (depending on the
SPACE attribute) and is preceded by sequential numbers.
Ordered Formats with a 3-space or 4-space indentation (depending on the
SPACE attribute) within the level of the list in which it is defined
and is preceded by sequential numbers or letters.
Simple Formats with a 3-space or 4-space indentation (depending on the
SPACE attribute) within the level of the list it is defined within.
Unordered Formats with a 3-space or 4-space indentation (depending on the
SPACE attribute) within the level of the list in which it is defined
and is preceded by bullets or dashes.

The next list item implicitly ends the previous list item as do the NOTEL, OL, SL,
and UL end tags.

If you do not specify text for a list item, a blank line is displayed for that item.

Conditions
v You must code the LI tag within a NOTEL, OL, SL, or UL definition. See
“NOTEL (Note List)” on page 384, “OL (Ordered List)” on page 387, “SL (Simple
List)” on page 447, and “UL (Unordered List)” on page 457 for descriptions of
these tags.

Chapter 13. Tag Reference 347

LI
Nested Tags
You can code the following tags within an LI definition:

Tag Name Usage Page Required

ATTENTION Attention Single 222 No
CAUTION Caution Single 230 No
DL Definition list Multiple 288 No
FIG Figure Multiple 312 No
HP Highlighted phrase Multiple 336 No
LINES Lines Multiple 349 No
NOTE Note Multiple 382 No
NOTEL Note List Multiple 384 No
NT Note Multiple 386 No
OL Ordered list Multiple 387 No
P Paragraph Multiple 390 No
PARML Parameter list Multiple 408 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
SL Simple list Multiple 447 No
UL Unordered list Multiple 457 No
WARNING Warning Single 468 No
XMP Example Multiple 474 No

Example
The following help panel markup contains an unordered list with three list items.
The last list item contains an additional paragraph of text. Figure 127 on page 349
shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=li DEPTH=20>ShelfBrowse Help

<AREA>
<INFO>
<P>When ShelfBrowse finds your book,
it displays this information:
<UL>
<LI>Reference information about the book.
<LI>The location of the book.
<LI>If the book is in stock.
<P>If the book is not in stock, see the librarian.
</UL>
<P>Thank you for using ShelfBrowse.
</INFO>
</AREA>
</HELP>

348 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 LINES

ShelfBrowse Help

When ShelfBrowse finds your book, it displays

this information:

o Reference information about the book.

o The location of the book.

o If the book is in stock.

If the book is not in stock, see the

librarian.

Thank you for using ShelfBrowse.

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 127. List Items

LINES (Lines)
The LINES tag defines unformatted text within an information region.

ÊÊ < LINES > </LINES> ÊÍ

NOSKIP text

| NOSKIP
| This attribute causes the blank line normally placed before the lines to be
| skipped.
text
This is the unformatted text.

Description
The LINES tag defines unformatted text within an information region. Tags that
normally cause word-wrapping (such as the P, LI, or CAUTION) do not cause
wrapping when nested within a LINES definition.

If the source text on any line is too long to fit in the remaining available formatting
width, the conversion utility truncates that line. The conversion utility issues a
warning message the first time that truncation occurs.

The formatting of the LINES tag is similar to that of the FIG tag, except that there
is no border or caption capability.

Conditions
v The LINES tag requires an end tag.
v You must code the LINES tag within an INFO definition. See “INFO
(Information Region)” on page 339 for a complete description of this tag.

Chapter 13. Tag Reference 349

LINES
Nested Tags
You can code the following tags within a LINES definition:

Tag Name Usage Page Required

DL Definition list Multiple 288 No
HP Highlighted phrase Multiple 336 No
NOTE Note Multiple 382 No
NOTEL Note List Multiple 384 No
NT Note Multiple 386 No
OL Ordered list Multiple 387 No
P Paragraph Multiple 390 No
PARML Parameter list Multiple 408 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
SL Simple list Multiple 447 No
UL Unordered list Multiple 457 No
XMP Example Multiple 474 No

Example
The following application panel markup contains a LINES definition. The
formatted output of the LINES definition is identical to the input markup.
Figure 128 on page 351 shows the formatted results.
<!DOCTYPE DM SYSTEM>

<PANEL NAME=lines DEPTH=22 WIDTH=40>Lines Tag Example

<AREA>
<INFO WIDTH=38>
<P>The following area shows how the LINES tag formats.
<LINES>
First line, just at it was entered.
Second line, ditto.

Notice we skipped a line here?

You
can
even
do
this.
</LINES>
<P>The LINES tag formatting ends immediately above.
</INFO>
</AREA>
</PANEL>

350 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 LIT

Lines Tag Example

The following area shows how the LINES

tag formats.

First line, just at it was entered.

Second line, ditto.

Notice we skipped a line here?

You
can
even
do
this.

The LINES tag formatting ends

immediately above.

F1=Help F3=Exit F12=Cancel

Figure 128. LINES

LIT (Literal)
The LIT tag defines a string where all blanks are significant and included in the
value.

ÊÊ <LIT> literal-display-value </LIT> ÊÍ

literal-display-value
This attribute specifies a string with all blanks preserved.

Description
The LIT tag defines a string where all blanks are significant and included in the
value. No stripping of leading, trailing, or embedded blanks is performed.

This is the only way to specify trailing blanks or a value of all blanks in the XLATI
displayed-value.

The LIT start and end tags must be on the same line as the literal-display-value to
preserve the original spacing of the value.

Conditions
v The LIT tag requires an end tag.
v You must code the LIT tag only within an XLATI definition. See “XLATI
(Translate Item)” on page 470 for a complete description of this tag.
v Multiple LIT tags may be coded within a single XLATI definition, as long as
they are not nested within each other. However, a better approach is to include
the whole XLATI displayed-value within the LIT tag.

Nested Tags
None.

Chapter 13. Tag Reference 351

LIT
Example
The following markup contains a variable class definition with two translate lists.
The last four translate items in the second list contain LIT definitions that preserve
trailing blanks in the displayed value of their respective translate items.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=aa TYPE='char 2'>

<VARCLASS NAME=bb TYPE='char 9'>
<VARCLASS NAME=cc TYPE='char 9'>
<XLATL FORMAT=upper>
</XLATL>
<XLATL>
<XLATI VALUE=1>BIGCHARGE
<XLATI VALUE=2><LIT>V I S T A</LIT>
<XLATI VALUE=3><LIT>EZCARD </LIT>
<XLATI VALUE=4><LIT>CHECK </LIT>
<XLATI VALUE=5><LIT> CASH</LIT>
</XLATL>

<VARLIST>
<VARDCL NAME=dispva VARCLASS=cc>
<VARDCL NAME=inptva VARCLASS=bb>
<VARDCL NAME=chckva VARCLASS=aa>
</VARLIST>

<PANEL NAME=lit>LIT translation

<TOPINST>You can display this panel with ISPF option 7.2
<TOPINST>For this example, enter the word 'BIGCHARGE', 'V I S T A',
'EZCARD', 'CHECK', or ' CASH' in the "literal value"
field (no quotes).
<TOPINST>The literal will be translated to the corresponding number
defined in the XLATL tag, and will be displayed in the
"translated value" field.
<TOPINST>The literal you enter will be displayed (left justified) in
the "original value" field.
<DTACOL>
<:-- assign "literal value" to "original value" -->
<SOURCE>
&inptva = &dispva
</SOURCE>
<DTAFLD DATAVAR=dispva ENTWIDTH=9 PMTWIDTH=20 ALIGN=center>Literal value
<DTAFLD DATAVAR=chckva ENTWIDTH=2 PMTWIDTH=20 USAGE=out>Translated value
<DTAFLD DATAVAR=inptva ENTWIDTH=9 PMTWIDTH=20 USAGE=out>Original value
<:-- assign translated "literal value" to "translated value" -->
<SOURCE>
&chckva = &dispva
</SOURCE>
</DTACOL>
<CMDAREA>
</PANEL>

LP (List Part)
The LP tag defines a comment or explanation within a note list, ordered list,
unordered list, or simple list.

ÊÊ < LP > ÊÍ
NOSKIP implied-paragraph </LP>

352 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 LP
| NOSKIP
| This attribute causes the list part to format without creating a line before the
| list part.
implied-paragraph
This is the text of the list part.

Description
The LP tag defines a comment or explanation within an ordered list, unordered
list, or simple list. You can code the LP tag anywhere within a list.

The text of the list part starts at the left margin of the current level of the list. It is
not numbered or lettered. When you use it within a NOTEL or OL definition, LP
does not interrupt or increment the sequence.

The next list item or the end of the list implicitly ends the list part.

Conditions
v You must code the LP tag within a NOTEL, OL, SL, or UL definition. See
“NOTEL (Note List)” on page 384, “OL (Ordered List)” on page 387, “SL (Simple
List)” on page 447, and “UL (Unordered List)” on page 457 for descriptions of
these tags.

Nested Tags
You can code the following tags within an LP definition:

Tag Name Usage Page Required

ATTENTION Attention Single 222 No
CAUTION Caution Single 230 No
DL Definition list Multiple 288 No
FIG Figure Multiple 312 No
HP Highlighted phrase Multiple 336 No
LINES Lines Multiple 349 No
NOTE Note Multiple 382 No
NOTEL Note List Multiple 384 No
NT Note Multiple 386 No
OL Ordered list Multiple 387 No
P Paragraph Multiple 390 No
PARML Parameter list Multiple 408 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
SL Simple list Multiple 447 No
UL Unordered list Multiple 457 No
WARNING Warning Single 468 No
XMP Example Multiple 474 No

Chapter 13. Tag Reference 353

LP
Example
The following help panel markup contains an ordered list with a nested list part
tag. WARNING and P tags are nested within the list part definition. Figure 129
shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=lp WIDTH=50 DEPTH=20>Help For Changing a File

<AREA>
<INFO>
<OL>
<LI>Type over the existing data
in the entry fields with the new data.
<LP>
<WARNING>
Performing the next step will save all changes
and delete the existing data.
<P>To quit this function without
deleting the existing data, press F12=Cancel.
</WARNING>
<LI>Press Enter to save the
updated data.
</OL>
</INFO>
</AREA>
</HELP>

Help For Changing a File

1. Type over the existing data in the entry

fields with the new data.

Warning: Performing the next step will save all

changes and delete the existing data.

To quit this function without deleting the

existing data, press F12=Cancel.

2. Press Enter to save the updated data.

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 129. List Part

LSTCOL (List Column)

The LSTCOL tag defines a column of data from an ISPF table displayed in the ISPF
table display area of a panel.

ÊÊ <LSTCOL DATAVAR=column-data Ê
VARCLASS=variable-class-name

354 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 LSTCOL
Ê Ê
NO BOTH
HELP= YES USAGE= IN
help-panel-name OUT
*help-message-id
%varname
*%varname

Ê Ê
NO COLWIDTH=data-width
REQUIRED= YES
YES MSG=message-id

Ê Ê
START NO LINE=n CLEAR
ALIGN= CENTER AUTOTAB= YES
END

Ê Ê
POSITION=n START TEXT=descriptive-text
FORMAT= CENTER
END

Ê Ê
BEFORE START TEXTLEN=n
TEXTLOC= AFTER TEXTFMT= CENTER
END

Ê Ê
NO NOENDATTR
TEXTSKIP= YES

Ê Ê
PAD= NULLS PADC= NULLS NONE
USER USER OUTLINE= L
char char R
%varname %varname O
U
BOX
%varname

Ê Ê
OFF NO NO
PAS= ON CSRGRP= YES ATTRCHANGE= YES
%varname n NEW

Chapter 13. Tag Reference 355

 LSTCOL
Ê Ê
COLSPACE=n CUA COLOR= WHITE
COLTYPE= ISPF RED
EE BLUE
VOI GREEN
LID PINK
YELLOW
TURQ
%varname

Ê Ê
HIGH HILITE= USCORE OFF
INTENS= LOW BLINK CAPS= ON
NON REVERSE
%varname %varname

Ê > ÊÍ
YES column-heading </LSTCOL>
DISPLAY= NO

DATAVAR=column-data
This is the data which will occupy the column. The column-data value must be
an ISPF table variable name (without a leading % sign).
VARCLASS=variable-class-name
This is the name of a variable class, defined with a VARCLASS tag, that
overrides the default variable class referred to by the VARDCL tag that
declares the data variable for the list column.
| HELP=NO | YES | help-panel-name | *help-message-id | %varname |
| *%varname
| This attribute specifies the help action taken when the user requests help for
| this list column. This is field-level help.

| When HELP=YES, control is returned to the application. You can specify either
| a help panel or a message identifier. If a message identifier is used, it must be
| prefixed with an asterisk (*).

| The help attribute value can be specified as a variable name. When %varname
| is coded, a panel variable name is created. When *%varname is coded, a
| message variable name is created.

| If the user requests help for a list column and no help is defined, the extended
| help panel is displayed. If an extended help panel is not defined for the panel,
| the application or ISPF tutorial is invoked.

| The help-panel-name must follow the standard naming convention described in

| “Rules for Variable Names” on page 201.

| See “HELP (Help Panel)” on page 323 for information on creating help panels.
| For information about creating messages, see “MSG (Message)” on page 376.
USAGE=BOTH | IN | OUT
This attribute indicates if this column is for input, output, or both.

356 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 LSTCOL
REQUIRED=NO | YES
This attribute indicates if this column is required to have input for each
modified row. The default is NO. This attribute is valid only when USAGE=IN
or BOTH.

If you specify REQUIRED=YES, a conditional VER(variable,NONBLANK)

statement will be built by the conversion utility and placed in the )PROC
section of the ISPF panel generated. This results in the column variable being
verified only when the row is selected or modified.
MSG=message-id
This attribute specifies the message that is displayed when the user does
not complete a required entry (defined with the REQUIRED attribute). If
you do not specify a message-identifier, ISPF displays a default message.

If you specify the MSG attribute and REQUIRED=YES, a

VER(variable,NONBLANK,MSG=message-identifier) statement is built by
the conversion utility and placed in the )PROC section of the ISPF panel
generated. If you specify the MSG attribute and REQUIRED=NO (the
default), the conversion utility issues a warning message.

See “MSG (Message)” on page 376 for information on creating messages.

Note: You can specify messages pertaining to other validations using

XLATL and CHECKL tags within a VARCLASS definition. See the
descriptions of these tags for additional information.
COLWIDTH=data-width
This attribute determines the data width to be used by the column. If you do
not specify this attribute, the data width and column formatting width are
determined by the actual length of the column-heading If the width of the
column-heading text is greater than the COLWIDTH, it will be used as the
column formatting width. The minimum width is 1 and the maximum is the
remaining available panel (or region) width. If the column-heading and the
COLWIDTH attribute are omitted, the data width and column formatting
width are determined by the TYPE value of the associated VARCLASS. If a
VARCLASS TYPE value is not available, the size of the column variable name
(specified by the DATAVAR attribute) determines the width.

You should code the COLWIDTH attribute with a value equal to the length of
the table data variable.
ALIGN=START | CENTER | END
This attribute specifies how the data value is to be displayed in the data field.

An attribute character is used for the field that specifies JUST(LEFT) if

ALIGN=START, JUST(ASIS) if ALIGN=CENTER or JUST(RIGHT) if
ALIGN=END. When ALIGN=END, there is no underscore padding performed;
blanks are used.
AUTOTAB=NO | YES
When AUTOTAB=YES, the cursor moves to the next field capable of input
when the user enters the last character in the list column field.

AUTOTAB=YES is valid only when the value for USAGE is either BOTH or
IN.

The ISPF SKIP keyword is not supported when running in GUI mode.

Chapter 13. Tag Reference 357

LSTCOL
LINE=n
This attribute is an provides the application the ability to place LSTCOL fields
on different model lines. ISPF defines the range of lines as 1 to 8. The default
is 1. Column headings are generated on multiple lines to match the LSTCOL
field placement.
CLEAR
This attribute adds a CLEAR (variable, ...) statement to the )MODEL line.
CLEAR should be specified for table extension variables.

For more information about the )MODEL line, refer to the ISPF User’s Guide
POSITION=n
This attribute specifies the starting position of the data column and related text
or the column heading, if the heading is longer than the data column. If this
attribute is not specified or is not valid, the conversion utility formats the
column immediately to the right of the previous column on the specified or
default model line. This attribute allows you to position fields on different
model lines with vertical alignment. Column position is location of the
attribute byte preceding the data column.
FORMAT=START | CENTER | END
This attribute specifies how the data column and its column heading are
formatted. If you do not specify this attribute, or if you specify the attribute
value START, then the column formats as in ISPF Version 3.1 and ISPF Version
3.2.

Formatting of the data in the column takes place within the column width,
which is determined as described in the COLWIDTH attribute section.

When you specify the attribute value CENTER, the conversion utility centers a
column heading that is shorter than the column width. If the column heading
is longer than the column width, then the data column is centered under the
column heading. When either the heading or the data column is centered,
blank characters are added before and after the column heading or data
column. The total amount of space to be added is divided by 2 and the
resulting whole number is the number of blanks added in front of the column
heading or data column. The difference between the total amount of space and
the amount placed in front of the column heading or data column is used at
the end.

When you specify the attribute value END, a column heading that is shorter
than the column width is right-justified so it aligns with the end of the
displayed data. If the column heading is longer than the column width, the
data column is right-justified so that the displayed data and the column
heading end at the same position.

If there is insufficient space available to format the column heading as

requested, the conversion utility issues a message that the FORMAT attribute is
ignored.

The FORMAT attribute does not affect the display of the field contents within
the data column, which is determined by the ALIGN attribute.
TEXT=descriptive-text
This attribute specifies a short description of the data column. It can be placed
before or after the data column. Text containing special characters or imbedded
blanks must be enclosed in quotes.

358 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 LSTCOL
TEXTLOC=BEFORE | AFTER
This attribute specifies the location of the TEXT relative to the data column.
Text can be placed on either side of the data column.
TEXTFMT=START | CENTER | END
This attribute specifies the format of the text within the length of the text area.
The text can be left-justified, centered, right-justified.
TEXTLEN=n
This attribute specifies the amount of space to reserve for formatting the
descriptive text. This attribute helps you line up text on different model lines,
and if the space reserved is longer than the descriptive text, it permits
formatting within the reserved space with the TEXTFMT attribute. If the
descriptive text is longer than the space reserved by the TEXTLEN attribute,
the descriptive text is not formatted and a warning message is issued.
TEXTSKIP=NO | YES
This attribute provides for skipping past the descriptive text when either the
TEXTLOC=BEFORE and the previous LSTCOL tag includes the NOENDATTR
attribute, or TEXTLOC=AFTER and the current LSTCOL tag includes the
NOENDATTR attribute. If there is no other input field on the panel, the cursor
moves to the first input field. The ISPF SKIP keyword is not supported in GUI
mode.
NOENDATTR
This attribute specifies that no ending attribute character will be placed after
the data column. NOENDATTR is ignored for the last data column on each
model line.
PAD=NULLS | USER | char | %varname
This attribute specifies the pad character for initializing the field. You can
define this attribute as a variable name preceded by a “%”.
PADC=NULLS | USER | char | %varname
This attribute specifies the conditional padding character to be used for
initializing the field. You can define this attribute as a variable name preceded
by a “%”.
OUTLINE=NONE | L | R | O | U | BOX | %varname
This attribute provides for displaying lines around the field on a DBCS
terminal. You can define this attribute as a variable name preceded by a “%”.
PAS=OFF | ON | %varname
This attribute controls the availability of the point-and-shoot function for this
table field. You can define this attribute as a variable name preceded by “%”
CSRGRP=NO | YES | n
When CSRGRP=YES, the conversion utility generates a cursor group number
to be used for this table column. When CSRGRP=n, the number provided is
used for this field. The PAS attribute must be specified as ON or %varname.

The conversion utility accepts the CSRGRP attribute for any table field
definition. The CRSGRP attribute is used at run-time for output fields only.
ATTRCHANGE=NO | YES | NEW
When ATTRCHANGE=YES or ATTRCHANGE=NEW, the conversion utility
formats an additional entry in the panel )ATTR section (that can apply to
multiple list columns) instead of creating a unique “.ATTR(field-name)” entry
in the )INIT section for this field. With this option, multiple LSTCOL tags with

Chapter 13. Tag Reference 359

 LSTCOL
the same characteristics require fewer panel logic statements.
ATTRCHANGE=NEW creates a new entry. ATTRCHANGE=YES uses an
existing entry, if possible.
| COLSPACE=n
| The COLSPACE attribute specifies the total number of bytes for the column
| width, including the leading and trailing attributes, and any trailing blank
| following an input field. The use of the COLSPACE attribute causes column
| heading text longer than the COLSPACE value (minus the attribute bytes) to
| be flowed into multiple lines.
COLTYPE=CUA | ISPF | EE | VOI | LID
This attribute defines the attribute type to be applied to the table field.
TYPE=CUA, the default, causes the field to display using the standard CUA
attribute.

VOI and LID are valid only when USAGE=OUT.

EE is valid when USAGE=IN or USAGE=BOTH.

Using a CUA attribute causes the field to appear in the associated. color.

When COLTYPE=ISPF, a non-CUA attribute is generated and you can specify

the color, intensity, and highlighting of the field using the COLOR, INTENS,
and HILITE attributes. These attributes are not valid for CUA types.
COLOR=WHITE | RED | BLUE | GREEN | PINK | YELLOW | TURQ |
%varname
This attribute specifies the color of the field. You can define this attribute as a
variable name preceded by a percent (%) sign.
INTENS=HIGH | LOW | NON | %varname
This attribute defines the intensity of the field. You can define this attribute as
a variable name preceded by a percent (%) sign.
HILITE=USCORE | BLINK | REVERSE | %varname
This attribute specifies the extended highlighting attribute of the field. You can
define this attribute as a variable name preceded by a percent (%) sign.
| CAPS=OFF | ON
| When CAPS=ON, the data in the field is displayed in uppercase characters.
| DISPLAY=YES | NO
| This attribute specifies whether the data for the field will be visible when the
| panel is displayed. This attribute is used to allow fields to contain information
| you do not want to appear on the screen.
column-heading
This is the text of the list column heading. If the length of the column-heading
and the COLWIDTH values are not equal, the greater of the two is used to
determine column formatting width. If the column-heading and the
COLWIDTH attributes are omitted, the column formatting width is determined
by the TYPE value of the associated VARCLASS. If a VARCLASS TYPE value
is not available, the size of the column variable name (specified by the
DATAVAR attribute) determines the width.

The column-heading text placement over the column is determined by the

FORMAT attribute value.

360 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 LSTCOL
Description
In conjunction with the LSTFLD tag, LSTCOL tags provide a means of defining a
vertically scrollable list display area that is made up of columns of data coming
from ISPF table data. One or more ISPF )MODEL section statements will be built to
display the fields defined by the LSTCOL tags. The use of LSTCOL tags requires
the use of the TBDISPL service in the application program.

If the ISPF panel width is smaller than the total width of the group of columns,
columns that exceed the panel width will be clipped from the right. A warning
message is issued if this condition occurs.

You can use the LINE attribute to format your table to display on multiple lines.

If NOENDATTR is not specified, the conversion utility generates a beginning and

ending attribute for each column of the table display )MODEL line. An additional
blank is also inserted for fields with USAGE=IN or BOTH if AUTOTAB=NO. This
characteristic results in the following conditions:
v When USAGE=OUT, 2 extra spaces are added to the defined column formatting
width.
v When AUTOTAB=YES and USAGE=IN or BOTH, 2 extra spaces are added to
the defined column formatting width.
v When AUTOTAB=NO (the default) and USAGE=IN or BOTH, 3 extra spaces are
added to the defined column formatting width.

It is important that you allow for this extra space when designing your panel. The
extra space is added to the width value for the field as defined in the description
of the COLWIDTH attribute.

Conditions
v You must code the LSTCOL tag within a LSTFLD or LSTGRP tag. See “LSTFLD
(List Field)” on page 364 for a complete description of this tag.
v Each LSTCOL definition should have a VARDCL definition associated with the
variable value specified with the DATAVAR attribute. See “VARDCL (Variable
Declaration)” on page 463 for a complete description of this tag.
v Only MODEL lines that actually are formatted with fields are written in the
panel body. Thus, if some LSTCOL entries specify LINE=1 and others specify
LINE=3, but there are no LSTCOL entries for LINE 2, only two MODEL lines are
created.
v If both PAD and PADC have been specified, PAD is ignored and PADC is used.
v When a “%varname” notation is found on any of the attributes that allow a
variable name, the “%varname” entry must follow the standard naming
convention described in “Rules for “%variable” Names” on page 201.

Nested Tags
You can code the following tags within a LSTCOL definition:

Tag Name Usage Page Required

COMMENT Comment Multiple 272 No
HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No

Chapter 13. Tag Reference 361

LSTCOL
Tag Name Usage Page Required
SOURCE Source Multiple 449 No

Examples
In the following source file markup, the application panel contains a list field with
five list columns. The first three columns are defined as output-only, and are coded
within the Subscriber Name list group. The Number column is an input/output
column, and it is coded within the Phone list group. The last column is input-only,
and it is coded within the Approved list group. This column requires input, so if it
is not filled in, the error message “MSGG886” will be displayed. The variable
declarations and classes associated with the list columns are also shown. Figure 130
on page 363 shows the formatted result of the application panel.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=namecls TYPE='char 15'>

<VARCLASS NAME=midcls TYPE='char 1'>
<VARCLASS NAME=phoncls TYPE='char 12'>
<VARCLASS NAME=appcls TYPE='char 1'>
<XLATL FORMAT=upper>
</XLATL>
<CHECKL>
<CHECKI TYPE=values PARM1=EQ PARM2='Y N'>
</CHECKL>

<VARLIST>
<VARDCL NAME=xfname VARCLASS=namecls>
<VARDCL NAME=xlname VARCLASS=namecls>
<VARDCL NAME=xmid VARCLASS=midcls>
<VARDCL NAME=xphone VARCLASS=phoncls>
<VARDCL NAME=xapp VARCLASS=appcls>
</VARLIST>

<PANEL NAME=lstcola KEYLIST=keyltbl>Subscriber List

<TOPINST>Enter phone number, if missing,
(format - nnn-nnn-nnnn) and approved
indicator (y or n) for each person.
<AREA>
<LSTFLD>
<LSTGRP HEADLINE=yes>Subscriber Name
<LSTCOL DATAVAR=xfname USAGE=out COLWIDTH=15>First Name
<LSTCOL DATAVAR=xlname USAGE=out COLWIDTH=15>Last Name
<LSTCOL DATAVAR=xmid USAGE=out COLWIDTH=1>MI
</LSTGRP>
<LSTGRP>Phone
<LSTCOL DATAVAR=xphone COLWIDTH=12>Number
</LSTGRP>
<LSTGRP>Approved
<LSTCOL DATAVAR=xapp USAGE=in REQUIRED=yes
COLWIDTH=1 MSG=msgg886>(Y or N)
</LSTGRP>
</LSTFLD>
</AREA>
<CMDAREA>
</PANEL>

362 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 LSTCOL

Subscriber List ROW 1 TO 3 OF 3

Enter phone number, if missing, (format - nnn-nnn-nnnn) and approved

indicator (y or n) for each person.

--------- Subscriber Name ---------- Phone Approved

First Name Last Name MI Number (Y or N)

Pete Moss P 919-888-4444 _
Sally Forth N ____________ _
Melba Toast T 919-444-8888 _
****************************** BOTTOM OF DATA *****************************

Command ===> ______________________________________________________________

F1=Help F2=Split F3=Exit F7=Backward F8=Forward
F9=Swap F12=Cancel

Figure 130. List Columns

To display the same table in a different format, we can change the LSTCOL tags
for name to include the LINE attribute. The DTL changes are reflected in the
following example.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=namecls TYPE='char 15'>

<VARCLASS NAME=midcls TYPE='char 1'>
<VARCLASS NAME=phoncls TYPE='char 12'>
<VARCLASS NAME=appcls TYPE='char 1'>
<XLATL FORMAT=upper>
</XLATL>
<CHECKL>
<CHECKI TYPE=values PARM1=EQ PARM2='Y N'>
</CHECKL>

<VARLIST>
<VARDCL NAME=xfname VARCLASS=namecls>
<VARDCL NAME=xlname VARCLASS=namecls>
<VARDCL NAME=xmid VARCLASS=midcls>
<VARDCL NAME=xphone VARCLASS=phoncls>
<VARDCL NAME=xapp VARCLASS=appcls>
</VARLIST>

<PANEL NAME=lstcolb KEYLIST=keyltbl>Subscriber List

<TOPINST>Enter phone number, if missing,
(format - nnn-nnn-nnnn) and approved
indicator (y or n) for each person.
<AREA>
<LSTFLD DIV=solid>
<LSTGRP HEADLINE=yes>Subscriber Name
<LSTCOL DATAVAR=xfname USAGE=out LINE=1 COLWIDTH=15>First Name
<LSTCOL DATAVAR=xlname USAGE=out LINE=2 COLWIDTH=15>Last Name
<LSTCOL DATAVAR=xmid USAGE=out LINE=3 COLWIDTH=1>MI
</LSTGRP>
<LSTGRP>Phone
<LSTCOL DATAVAR=xphone COLWIDTH=12>Number
</LSTGRP>
<LSTGRP>Approved
<LSTCOL DATAVAR=xapp USAGE=in REQUIRED=yes
COLWIDTH=1 MSG=msgg886>(Y or N)

Chapter 13. Tag Reference 363

LSTCOL
</LSTGRP>
</LSTFLD>
</AREA>
<CMDAREA>
</PANEL>

Figure 131 shows the formatted result of the application panel.

Subscriber List ROW 1 TO 3 OF 3

Enter phone number, if missing, (format - nnn-nnn-nnnn) and approved

indicator (y or n) for each person.

Subscriber Name Phone Approved

First Name Number (Y or N)
Last Name
MI
Pete 919-888-4444 _
Moss
P
--------------------------------------------------------------------------
Sally ____________ _
Forth
N
--------------------------------------------------------------------------
Melba 919-444-8888 _
Toast
Command ===> ______________________________________________________________
F1=Help F2=Split F3=Exit F7=Backward F8=Forward
F9=Swap F12=Cancel

Figure 131. List Columns

LSTFLD (List Field)

The LSTFLD tag defines an ISPF table display area that is made up of columns of
data coming from ISPF tables.

ÊÊ <LSTFLD Ê
NONE NOSCAN
RULES= HORIZ ROWS= SCAN
VERT %varname
BOTH

Ê Ê
NONE SCROLLVAR=scroll-variable
DIV= BLANK
SOLID
DASH
char

364 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 LSTFLD
Ê Ê
NO NO
SCRVHELP= YES SCROLLTAB= YES
scroll-help-panel-name
*scroll-help-message-id
%varname
*%varname

Ê > </LSTFLD> ÊÍ
OFF NO
SCRCAPS= ON ATTRCHANGE= YES
NEW

RULES=NONE | HORIZ | VERT | BOTH

This attribute specifies the type of interior rules that will be drawn in the table
display being defined within the LSTFLD tag. This applies to all the list
columns within the context of this tag.

This attribute is supported by using the ISPF outline (L|R|O|U|Box|None)

statement on panel definition statements. However, the lines around fields will
only be visible on double-byte character support terminals.

Note: Any list column field within the list field defining OUTLINE overrides
the LSTFLD RULES value.
ROWS=NOSCAN | SCAN | %varname
This attribute provides support by TBDISPL of rows previously selected by the
TBSARG service. If you specify ROWS=SCAN, the conversion utility adds
ROWS(SCAN) to the )MODEL line statement in the generated ISPF panel.

If you specify ROWS=%varname, ROWS(&varname) is added to the )MODEL

line. The application must set the variable name to ALL or SCAN before the
panel is displayed.
DIV=NONE | BLANK | SOLID | DASH | char
This attribute specifies the type of divider line to be added as the last line of a
model set. If this attribute is omitted or specified as NONE, the divider line is
not generated. If this attribute is specified as BLANK, a blank divider line is
generated. You may specify either SOLID or DASH to produce a visible
divider line. When the GRAPHIC invocation option is specified, SOLID
produces a solid line for host display and DASH produces a dashed line.
When NOGRAPHIC is specified or the panel is displayed in GUI mode, both
SOLID and DASH produce a dashed line. Alternately, you can specify a
character or a character string of your choice. The character or characters
provided are replicated to the available width of the panel (or region) to create
the divider line.

If you have defined LSTCOL tags for all 8 of the available model lines, then
the conversion utility issues a message and does not generate any divider line.
SCROLLVAR=scoll-variable
This attribute specifies the name of a variable that the application uses to
obtain scrolling information. The scroll-variable must follow the standard
naming convention described in “Rules for Variable Names” on page 201.

Chapter 13. Tag Reference 365

 LSTFLD
If the attribute is specified, the conversion utility creates a scroll entry on the
command line, providing that the resulting command area allows at least 8
bytes for a command entry.
| SCRVHELP=NO | YES | scroll-help-panel-name | *scroll-help-message-id |
| %varname | *%varname
| This attribute specifies the help action taken when the user requests help for
| the field specified with the SCROLLVAR attribute.

| When SCRVHELP=YES, control is returned to the application. You can specify

| either a help panel or a message identifier. If a message identifier is used, it
| must be prefixed with an asterisk (*).

| The help attribute value can be specified as a variable name. When %varname
| is coded, a panel variable name is created. When *%varname is coded, a
| message variable name is created.

| If the user requests help on a choice and no help is defined, the extended help
| panel is displayed. If an extended help panel is not defined for the panel, the
| application or ISPF tutorial is invoked.

| The scroll-help-panel-name must follow the standard naming convention

| described in “Rules for Variable Names” on page 201.

| See “HELP (Help Panel)” on page 323 for information on creating help panels.
| For information about creating messages, see “MSG (Message)” on page 376.
SCROLLTAB=NO | YES
When SCROLLTAB=YES, the cursor moves to the next input field when the
user enters the last character in the scroll amount field. If there is no other
input field on the panel, the cursor moves to the beginning of the command
line. The ISPF SKIP keyword is not supported in GUI mode.
| SCRCAPS=OFF | ON
| When SCRCAPS=ON, the data in the scroll field is displayed in uppercase
| characters.
ATTRCHANGE=NO | YES | NEW
When ATTRCHANGE=YES or ATTRCHANGE=NEW, the conversion utility
formats an additional entry in the panel )ATTR section (that can apply to
multiple list columns) instead of creating a unique “.ATTR(field-name)” entry
in the )INIT section for each field. With this option, multiple LSTCOL tags with
the same characteristics require fewer panel logic statements.
ATTRCHANGE=NEW creates a new entry. ATTRCHANGE=YES uses an
existing entry, if possible.

Note: Any list column field within the list field defining ATTRCHANGE
overrides the LSTFLD ATTRCHANGE value.

Description
The LSTFLD tag defines a scrollable list display area that is made up of columns of
data coming from ISPF table data. The conversion utility creates a )MODEL line at
the bottom of the )BODY section of the panel the list field is coded within.

366 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 LSTFLD
The use of the LSTFLD tag causes all other tags that generate panel data and that
are coded after the LSTFLD end tag to be moved before the )MODEL statement.
This is because ISPF does not allow any panel body definition after the )MODEL
statement.

Conditions
v The LSTFLD tag requires an end tag.
v You must code the LSTFLD tag within an AREA, REGION, or PANEL definition.
See “AREA (Area)” on page 213, “REGION (Region)” on page 424, and “PANEL
(Panel)” on page 397 for descriptions of these tags.
v You can code only one list field on an application panel.
v You should code a CMDAREA on any panel that contains a LSTFLD definition.
If you do not include the CMDAREA tag, the conversion utility inserts one and
issues a message, unless the PANEL tag specifies CMDLINE=NO.
v You can use the SCROLLVAR attribute only once within a panel.
v The resulting scroll entry on the command line must leave at least 8 positions
for the command entry field.
v If you specify the SCRVHELP attribute, you must also specify the SCROLLVAR
attribute.

Nested Tags
You can code the following tags within a LSTFLD definition:

Tag Name Usage Page Required

COMMENT Comment Multiple 272 No
LSTCOL List column Multiple 354 No
LSTGRP List group Multiple 368 No
LSTVAR List variable Multiple 371 No
SOURCE Source Multiple 449 No

Example
The application panel in the following source file markup contains a list field with
five list columns of data. In addition, three list groups are defined within the list
field. The first three list columns are output-only columns. The fourth list column
uses the default value both, which allows it to handle both input and output data.
The last list column is an input-only column, and input by the user is required.
Figure 132 on page 368 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=namecls TYPE='char 15'>

<VARCLASS NAME=midcls TYPE='char 1'>
<VARCLASS NAME=phoncls TYPE='char 12'>
<VARCLASS NAME=appcls TYPE='char 1'>
<XLATL FORMAT=upper>
</XLATL>
<CHECKL>
<CHECKI TYPE=values PARM1=EQ PARM2='Y N'>
</CHECKL>

<VARLIST>
<VARDCL NAME=xfname VARCLASS=namecls>
<VARDCL NAME=xlname VARCLASS=namecls>
<VARDCL NAME=xmid VARCLASS=midcls>

Chapter 13. Tag Reference 367

LSTFLD
<VARDCL NAME=xphone VARCLASS=phoncls>
<VARDCL NAME=xapp VARCLASS=appcls>
</VARLIST>

<PANEL NAME=lstfld3 KEYLIST=keyltbl>Subscriber List

<TOPINST>Enter phone number, if missing,
(format - nnn-nnn-nnnn) and approved
indicator (y or n) for each person.
<AREA>
<LSTFLD SCROLLVAR=scrlamt SCRVHELP=scrhelp>
<LSTGRP HEADLINE=yes>Subscriber Name
<LSTCOL DATAVAR=xfname USAGE=out COLWIDTH=15>First Name
<LSTCOL DATAVAR=xlname USAGE=out COLWIDTH=15>Last Name
<LSTCOL DATAVAR=xmid USAGE=out COLWIDTH=1>MI
</LSTGRP>
<LSTGRP>Phone
<LSTCOL DATAVAR=xphone COLWIDTH=12>Number
</LSTGRP>
<LSTGRP>Approved
<LSTCOL DATAVAR=xapp USAGE=in REQUIRED=yes
COLWIDTH=1 MSG=msgg886>(Y or N)
</LSTGRP>
</LSTFLD>
</AREA>
<CMDAREA>
</PANEL>

Subscriber List

Enter phone number, if missing, (format – nnn–nnn–nnnn) and approved

indicator (y or n) for each person.

--------- Subscriber Name ---------- Phone Approved

First Name Last Name MI Number (Y or N)
Pete Moss P 919-888-4444 _
Sally Forth N ____________ _
Melba Toast T 919-444-8888 _
****************************** BOTTOM OF DATA ****************************

Command ===> ___________________________________________ Scroll ===> ____

F1=Help F2=Split F3=Exit F7=Backward F8=Forward
F9=Swap F12=Cancel

Figure 132. List Field

LSTGRP (List Group)

The LSTGRP tag defines a heading for a single column or multiple columns within
a list field.

ÊÊ <LSTGRP Ê
NO CENTER
HEADLINE= YES ALIGN= START
DASH END

368 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 LSTGRP
Ê > </LSTGRP> ÊÍ
column-group-heading

HEADLINE=NO | YES | DASH

This attribute specifies whether the heading text is padded to span the width
of the group heading not occupied by the text. This provides a visual
indication of the columns that belong to a group heading. You must specify
YES or DASH to produce the visible indicator. When the GRAPHIC invocation
option is specified, YES produces a solid line for host display and DASH
produces a dashed line. When NOGRAPHIC is specified or the panel is
displayed in GUI mode, both YES and DASH produce a dashed line.
ALIGN=CENTER | START | END

This attribute specifies how the list group heading is formatted. If you do not
specify this attribute, or if you specify ALIGN=CENTER, then the heading will
be centered over multiple columns or a variable model line, or left-justified
over a single column.

When ALIGN=START, the list group heading is left-justified. When

ALIGN=END, the list group heading is right-justified.
column-group-heading
The heading is placed above the column group in the nonscrollable part of the
list field. The heading must fit on one line above the column or columns in the
group. If column-group-heading text is longer than the formatted width of the
column or columns in the group, it is truncated. The column-group-heading
appears on the line immediately above the group of columns.

If you do not specify column-group-headings for any of the columns within the
group, the conversion utility will reserve the area where the heading would be
displayed and fill it with blanks. If the column-group-heading is not specified but
HEADLINE=YES is specified, the heading will contain only a dashed line.

Description
The LSTGRP tag defines a heading for a single column or multiple columns within
a list field. You can use the LSTGRP tag to group columns in a list field together
under a single heading that applies to all of the columns. You create the columns
using the LSTCOL or LSTVAR tag.

The list field can contain other columns that do not belong to the list column
group. Only the LSTCOL or LSTVAR definitions nested within the LSTGRP tag
belong to the group.

There must be at least one LSTCOL tag, nested LSTGRP tag, or LSTVAR tag
defined within a column group. The column formatting widths, and the gutters
between them, define how much space is allocated for the group heading. If this
space is less than the space needed for the group heading, the conversion utility
will truncate the heading. If the LSTGRP definition contains only one LSTCOL tag,
and the ALIGN attribute is not specified, the group heading is left-justified over
the column.

You can use the LSTGRP tag to specify multiple lines of single column headings or
multiple lines of multiple column headings.

Chapter 13. Tag Reference 369

LSTGRP
Conditions
v The LSTGRP tag requires an end tag.
v You must code the LSTGRP tag within a LSTFLD definition or another LSTGRP
definition. See “LSTFLD (List Field)” on page 364 for a complete description of
the LSTFLD tag.
v You can code multiple LSTGRP tags within a LSTFLD definition.
v A LSTGRP definition must contain a nested LSTCOL, LSTVAR, or LSTGRP tag,
otherwise the conversion utility will issue an error.
v The nested tags LSTCOL definitions must include at least one data column from
the first displayable model line.

Nested Tags
You can code the following tags within the LSTGRP tag:

Tag Name Usage Page Required

COMMENT Comment Multiple 272 No
HP Highlighted phrase Multiple 336 No
LSTCOL List column Multiple 354 Yes
LSTGRP List group Multiple 368 No
LSTVAR List variable Multiple 371 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
SOURCE Source Multiple 449 No

Example
In the following source file markup, the application panel contains a list field with
six list columns. The first three columns are placed under a common group, as are
the last two columns. Also, for each of the first three columns, a second-level
group heading is used in place of list column headings. This technique provides a
blank space between the group headings and the data columns. Figure 133 on
page 371 shows the formatted result of the application panel.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=namecls TYPE='char 12'>

<VARCLASS NAME=midcls TYPE='char 1'>
<VARCLASS NAME=yearcls TYPE='char 9'>
<VARCLASS NAME=semcls TYPE='char 2'>

<VARLIST>
<VARDCL NAME=xfname VARCLASS=namecls>
<VARDCL NAME=xlname VARCLASS=namecls>
<VARDCL NAME=xmid VARCLASS=midcls>
<VARDCL NAME=xyear VARCLASS=yearcls>
<VARDCL NAME=sem1 VARCLASS=semcls>
<VARDCL NAME=sem2 VARCLASS=semcls>
</VARLIST>

<PANEL NAME=lstgrp WIDTH=66 KEYLIST=keyltbl>Class Roster

<AREA>
<LSTFLD>
<LSTGRP HEADLINE=yes>Student Name
<LSTGRP>Last
<LSTCOL DATAVAR=xlname USAGE=out COLWIDTH=12>
</LSTGRP>

370 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 LSTGRP
<LSTGRP>First
<LSTCOL DATAVAR=xfname USAGE=out COLWIDTH=12>
</LSTGRP>
<LSTGRP>M
<LSTCOL DATAVAR=xmid USAGE=out COLWIDTH=1>
</LSTGRP>
</LSTGRP>
<LSTGRP>Class
<LSTGRP>Year
<LSTCOL DATAVAR=xyear USAGE=out COLWIDTH=9>
</LSTGRP>
</LSTGRP>
<LSTGRP HEADLINE=yes>Grade
<LSTCOL DATAVAR=sem1 COLWIDTH=2>Sem 1
<LSTCOL DATAVAR=sem2 COLWIDTH=2>Sem 2
</LSTGRP>
</LSTFLD>
</AREA>
<CMDAREA>
</PANEL>

Class Roster ROW 1 TO 6 OF 6

------- Student Name -------- Class -- Grade ---

Last First M Year

Sem 1 Sem 2
Duff Dean T Junior A B+
Gillihan Dana L Freshman B+ B
Rivas Sergio J Post-Grad D D
Romero Maria C Post-Grad A A
Spencer Donald M Freshman A B
Szabo Imre B Senior C+ B
************************ BOTTOM OF DATA ************************

Command ===> ___________________________________________________

F1=Help F2=Split F3=Exit F7=Backward F8=Forward
F9=Swap F12=Cancel

Figure 133. List Group

LSTVAR (List Variable)

The LSTVAR tag defines a )MODEL section variable model line displayed in the
ISPF table display area of a panel.

ÊÊ <LSTVAR DATAVAR=variable-model-name > Ê

LINE=n column-heading

Ê ÊÍ
</LSTVAR>

Chapter 13. Tag Reference 371

LSTVAR
DATAVAR=variable-model-name
This is the data which will occupy the column. The variable-model-name value
must be a variable model line name (without a leading % sign).
LINE=n
This attribute provides the application the ability to place a LSTVAR model
variable on different model lines. ISPF defines the range of lines as 1 to 8. The
default is 1. Headings are generated on multiple lines to match the LSTVAR
field placement.
column-heading
This is the text of the model variable heading.

Description
In conjunction with the LSTFLD and LSTCOL tags, LSTVAR tags provide a means
of defining a vertically scrollable list display area that is made up of data coming
from ISPF tables. One or more ISPF )MODEL section statements will be built to
display the fields defined by the LSTVAR tags. The use of LSTVAR tags requires
the use of the TBDISPL service in the application program.

The application must place valid data in the variable model line before the panel is
displayed.

You can use the LINE attribute to format your table to display on multiple lines.

Conditions
v You must code the LSTVAR tag within a LSTFLD tag. See “LSTFLD (List Field)”
on page 364 for a complete description of this tag.
v Only MODEL lines that are not blank fields are written in the panel body. Thus,
if one LSTVAR entries specifies LINE=1 and another specifies LINE=3, but there
are no entries for LINE 2, only two MODEL lines are created.

Nested Tags
You can code the following tags within the LSTVAR tag:

Tag Name Usage Page Required

COMMENT Comment Multiple 272 No
HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
SOURCE Source Multiple 449 No

Example
In the following source file markup, the application panel contains a list field with
five list columns and 2 variable model lines. The first three columns are defined as
output-only, and are coded within the Subscriber Name list group. The Number
column is an input/output column, and it is coded within the Phone list group.
The last column is input-only, and it is coded within the Approved list group. This
column requires input, so if it is not filled in, the error message MSGG886 will be
displayed. The variable declarations and classes associated with the list columns
are also shown.

372 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 LSTVAR
Note: The variable model lines are shown in the formatted output to illustrate the
formatting process. The application must provide valid values for these
variables before the panel is displayed.
Figure 134 on page 374 shows the formatted result of the application panel.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=namecls TYPE='char 15'>

<VARCLASS NAME=midcls TYPE='char 1'>
<VARCLASS NAME=phoncls TYPE='char 12'>
<VARCLASS NAME=appcls TYPE='char 1'>
<XLATL FORMAT=upper>
</XLATL>
<CHECKL>
<CHECKI TYPE=values PARM1=EQ PARM2='Y N'>
</CHECKL>

<VARLIST>
<VARDCL NAME=xfname VARCLASS=namecls>
<VARDCL NAME=xlname VARCLASS=namecls>
<VARDCL NAME=xmid VARCLASS=midcls>
<VARDCL NAME=xphone VARCLASS=phoncls>
<VARDCL NAME=xapp VARCLASS=appcls>
</VARLIST>

<PANEL NAME=lstvar KEYLIST=keyltbl>Subscriber List

<TOPINST>Enter phone number, if missing,
(format - nnn-nnn-nnnn) and approved
indicator (y or n) for each person.
<AREA>
<LSTFLD>
<LSTVAR datavar=xmodelv1>Variable model line at top
<LSTGRP HEADLINE=yes>Subscriber Name
<LSTCOL DATAVAR=xfname USAGE=out line=2 COLWIDTH=15>First Name
<LSTCOL DATAVAR=xlname USAGE=out line=2 COLWIDTH=15>Last Name
<LSTCOL DATAVAR=xmid USAGE=out line=2 COLWIDTH=1>MI </LSTGRP>
<LSTGRP>Phone
<LSTCOL DATAVAR=xphone line=2 COLWIDTH=12>Number
</LSTGRP>
<LSTGRP>Approved
<LSTCOL DATAVAR=xapp USAGE=in line=2 REQUIRED=yes
COLWIDTH=1 MSG=msgf886>(Y or N)
</LSTGRP>
<LSTVAR datavar=xmodelv2 line=3>Variable model line at bottom
</LSTFLD>
</AREA>
<CMDAREA>
</PANEL>

Chapter 13. Tag Reference 373

M

Subscriber List

Enter phone number, if missing, (format - nnn-nnn-nnnn)&cont.

and approved
indicator (y or n) for each person.

--------- Subscriber Name ---------- Phone

Approved
Variable model line at top
First Name Last Name MI Number (Y or N)
Variable model line at bottom
&XMODELV1
_______________ _______________ _ ____________ _
&XMODELV2

Command ===> ______________________________________________________________

F1=Help F2=Split F3=Exit F7=Backward F8=Forward
F9=Swap F12=Cancel

Figure 134. List Variable

M (Mnemonic)
The M tag defines a single character to be used as a mnemonic selection for action
bar or pull-down choices.

ÊÊ <M> mnemonic-character ÊÍ
</M>

mnemonic-character
The single-byte character following the mnemonic start tag specifies the
mnemonic for the action bar choice or pull-down choice. The
mnemonic-character must be a single-byte alphabetic or numeric character;
double-byte characters are not allowed.

If you want the mnemonic to be a character that is not part of the normal
choice text, follow the choice text with the mnemonic character specified
within parenthesis. This convention is particularly useful when you have a
large number of choices, which makes it difficult to choose a unique mnemonic
for each choice. For example, if you had the pull-down choice Add, and the
characters A and d were already used on other choices in the same pull-down,
you could choose another character for your mnemonic:
<pdc>Add(<m>B)

In this case B becomes the mnemonic for Add. When an alternate mnemonic is
specified on a PDC tag, the resulting 3 bytes of text (the “(B)” in this example),
are replaced in the description by a variable. The variable is set to blanks or to
the 3-byte value depending on the ZGUI variable, thus displaying the
mnemonic only in GUI mode.

374 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 M
Description
Mnemonic characters are supported by ISPF for pull-down choices only when you
are running in GUI mode. They are ignored for host display.

Unless you have specified MNEMGEN=NO on the AB tag, the conversion utility
will automatically select a mnemonic character for each action bar and pull-down
choice for SBCS conversions. The character selected as the mnemonic is the first
alphabetic or numeric character in the choice description not previously used as a
mnemonic for that set of choices.

Conditions
When the conversion utility automatically generates mnemonics, the M tag
selection is processed first, and if the specified mnemonic is valid, the automatic
mnemonic generation is not used for that choice. If the specified mnemonic
character is invalid, or a duplicate of a previously used mnemonic character (either
specified or automatically selected), a message is issued and an attempt will be
made to select a different mnemonic character.

When processing DBCS conversions or when MNEMGEN=NO is coded on the AB

tag, automatic mnemonic character selection is disabled and mnemonic characters
are only specified by the M tag. The use of mnemonics should be consistent for all
choices in an action bar or pull-down as follows:
v Code the M tag within the text following the ABC and PDC tags.
v Each mnemonic chosen must be unique. The conversion utility will issue a
message and discard duplicate mnemonics.
v If mnemonics are used for any action bar or pull-down choice, they should be
used for all of the choices. The conversion utility will issue a message if any
choice in a group does not have a mnemonic.

Nested Tags
None.

Example
In the following example, all of the action bar choices and pull-down choices have
been coded to show the use of the M tag. Some of the pull-down choices illustrate
the use of the optional end tag.
<!DOCTYPE DM SYSTEM(
<!entity sampvar1 sysem>
<!entity sampbody system>)>
&sampvar1;

<PANEL NAME=m1 KEYLIST=keylxmp>Library Card Registration

<AB>
<ABC><M>File
<PDC><M>A</M>dd Entry
<ACTION RUN=add>
<PDC><M>D</M>elete Entry
<ACTION RUN=delete>
<PDC><M>U</M>pdate Entry
<ACTION RUN=update>
<PDC><M>E</M>xit
<ACTION RUN=exit>
<ABC><M>Search
<PDC CHECKVAR=whchsrch MATCH=1>Search on <M>n</M>ame
<ACTION SETVAR=whchsrch VALUE=1>
<ACTION RUN=search>

Chapter 13. Tag Reference 375

 M
<PDC CHECKVAR=whchsrch MATCH=2>Search on <M>c</M>ard number
<ACTION SETVAR=whchsrch VALUE=2>
<ACTION RUN=search>
<ABC><M>Help
<PDC><M>Extended Help...
<ACTION RUN=exhelp>
<PDC><M>Keys Help...
<ACTION RUN=keyshelp>
</AB>
&sampbody;
</PANEL>

MSG (Message)
The MSG tag defines a message within a message member.

ÊÊ <MSG SUFFIX=message-suffix-number Ê
HELP= help-panel-name
%varname
*

Ê Ê
INFO AREA
MSGTYPE= WARNING LOCATION= MODAL
ACTION MODAL(L)
CRITICAL MODELESS
%varname MODELESS(L)
%varname

Ê Ê
DISP= KANA NO NONE
NOKANA ALARM= YES ABBREV= KEYWORD
%varname VALUE
BOTH

Ê > Ê
FLOW SMSG=short-message-text message-text
FORMAT= ASIS

Ê ÊÍ
</MSG>

SUFFIX=message-suffix-number
This attribute specifies the suffix of the message. The suffix consists of either 1
numeric character (0–9) or a numeric character (0–9) and an optional alpha
suffix character as defined for ISPF messages, which is added to the MSGMBR
message-member-name to form the ISPF message ID.

Each message-suffix-number within a message member must be unique.

Attempts to define duplicate suffixes will result in a warning message and the
duplicate MSG will be ignored.
| HELP=help-panel-name | %varname | *
| Specifies the name of the help panel that is associated with this message and
| that will be displayed if the user requests help for the message.

376 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 MSG
| If you specify a help panel, ISPDTLC generates “.HELP=help-panel-name” (or
| “.HELP=&varname” or “.HELP=*”) in the ISPF message ID definition. If you
| don’t specify a help panel, no help is available for the message.

| The help-panel-name must follow the standard naming convention described in

| “Rules for Variable Names” on page 201.
MSGTYPE=INFO | WARNING | ACTION | CRITICAL | %varname
This attribute specifies the severity of the message. ISPF displays INFO
messages without an alarm. ISPF displays WARNING, ACTION, and
CRITICAL messages with an alarm.

ACTION and CRITICAL message types are used to identify the most severe
errors. This level of error usually requires a user response. ISPF will always
display CRITICAL messages in a pop-up. ACTION messages are displayed
based on the value of the LOCATION attribute.

The %varname value specifies that the value INFO, WARNING, ACTION, or
CRITICAL will be provided in the named variable by the application prior to
issuing the message.

The conversion utility changes INFO to .TYPE=NOTIFY when formatting the

message member.

ISPF recognizes message types (.TYPE=) of NOTIFY, WARNING, ACTION, and

CRITICAL. ISPF uses the TYPE value specified in conjunction with the value
of .WINDOW to determine the display characteristics of the message. The
.WINDOW value is generated from the value specified for the LOCATION
attribute. For more information on ISPF messages, refer to ISPF Dialog
Developer’s Guide and Reference
LOCATION=AREA | MODAL | MODAL(L) | MODELESS | MODELESS(L) |
%varname
This attribute specifies how the message is displayed.

LOCATION=AREA (the default) specifies that the message is to appear in the

panel message area. However, if the text of the message exceeds the length of
the panel message area, ISPF will display the message in a pop-up.

LOCATION=MODAL specifies that the message is to appear in a pop-up

which requires a user response. The conversion utility generates
.WINDOW=RESP in the ISPF message definition.

LOCATION=MODAL(L) specifies that the long message is to appear in a

pop-up which requires a user response. The conversion utility generates
.WINDOW=LRESP in the ISPF message definition.

LOCATION=MODELESS specifies that the message is to appear in a pop-up

which does not require a user response. The conversion utility generates
.WINDOW=NORESP in the ISPF message definition.

LOCATION=MODELESS(L) specifies that the long message is to appear in a

pop-up which does not require a user response. The conversion utility
generates .WINDOW=LNORESP in the ISPF message definition.

Chapter 13. Tag Reference 377

 MSG
LOCATION=%varname specifies that the value AREA, MODAL, or
MODELESS will be provided in the named variable by the application prior to
issuing the message. The conversion utility generates .WINDOW=&VARNAME
in the ISPF message definition.
DISP=KANA | NOKANA
This attribute specifies the addition of either the KANA or NOKANA keyword
to the message control information.
ALARM=NO | YES | %varname
This attribute controls the use of the alarm when the message is displayed.

ALARM=%varname specifies that the value YES or NO will be provided in the

named variable by the application prior to issuing the message.
ABBREV=NONE | KEYWORD | VALUE | BOTH
This attribute specifies the format of the message control information. You may
abbreviate the message control keyword, the message control keyword value,
or both.
| FORMAT=FLOW | ASIS
| This attribute specifies the formatting of the message-text.

| The default of FLOW means to flow the message text continuously within the
| WIDTH of the MSGMBR

| When FORMAT=ASIS, the genrated message preserves imbedded blanks, but

| drops leading or trailing blanks.
SMSG=short-message-text
You can provide a short message of up to 24 bytes which ISPF will display in
the short message area of the panel.

The VARSUB tag is not supported within the short-message-text. If a substitution

variable is required, you may code ″&amp;variable″ to place the variable name
in the message. A short-message-text consisting of more than one word must be
enclosed within quotation marks (" "). If the short-message-text contains a single
apostrophe ('), the conversion utility generates double apostrophes as it does
for message-text, as described below.

The short message is not recommended by the CUA Architecture definition.

A short message cannot be created unless the message-text is also provided.

message-text
This is the text of the message. The message-text is placed in the long-message
area of a message file. The message-text is limited to 512 characters. The
conversion utility truncates all message-text after 512 characters and issues a
warning message. If no message-text is coded, then no message is generated.

Several characters within the long message area have a special meaning to
ISPF. If you use the apostrophe within message-text, the conversion utility
generates double apostrophes so the single apostrophe will be displayed when
ISPF issues the message. If you use the ampersand (&) within the long
message, it must be coded as “&amp” followed by a blank or semicolon to be
interpreted as a literal ampersand character (through ENTITY substitution).

378 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 MSG
For ISPF substitution variables, you should code the VARSUB tag. ISPF does
not perform output translation (specified in the associated VARCLASS tag) on
ISPF run-time substitution variables.

Refer to the ISPF Dialog Developer’s Guide and Reference for a description of the
syntax rules you should use for defining consistent messages.

Description
The MSG tag defines a message within a message member. Each MSG definition
within a message member must have a unique message-suffix-number.

Conditions
v You must code the MSG tag within a MSGMBR definition. See “MSGMBR
(Message Member)” on page 380 for a complete description of this tag.
v When a “%varname” notation is found on any of the attributes that allow a
variable name, the “%varname” entry must follow the standard naming
convention described in “Rules for “%variable” Names” on page 201.

Nested Tags
You can code the following tag within a MSG definition:

Tag Name Usage Page Required

VARSUB Variable substitution Multiple 466 No

Example
The following markup contains the message member MSGG88, which contains
nine MSG definitions. The text of messages MSGG883 and MSGG888 contain
variable substitutions. Figure 135 on page 380 shows the generated ISPF message
member.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=msgcls TYPE='char 20'>

<VARLIST>
<VARDCL NAME=phoneno VARCLASS=msgcls>
<VARDCL NAME=cnum VARCLASS=msgcls>
</VARLIST>

<MSGMBR NAME=msgg88>
<MSG SUFFIX=1 disp=kana abbrev=keyword>Name must be alphabetic.
<MSG SUFFIX=2 disp=nokana abbrev=value>Enter only number of days.
<MSG SUFFIX=3 MSGTYPE=critical>The only rooms we have available
are either SINGLE or DOUBLE. Please call the manager of the hotel
who will arrange equivalent lodging at another
hotel in the area. This is our mistake, and we will, of course,
pick up the bill. Please call collect <VARSUB VAR=phoneno>.
<MSG SUFFIX=4 MSGTYPE=action LOCATION=modal abbrev=both>
Please enter either BIGCHARGE, V I S T A, EZCARD, CHECK, or CASH.
<MSG SUFFIX=5 MSGTYPE=warning LOCATION=modeless>Please enter your name.
<MSG SUFFIX=6>Please enter Y or N.
<MSG SUFFIX=7>Card number is a seven-digit number.
<MSG SUFFIX=8 MSGTYPE=warning>The card number you entered,
<VARSUB VAR=cnum> is not valid.
<MSG SUFFIX=9>Message '9' contains imbedded quotes.
</MSGMBR>

Chapter 13. Tag Reference 379

MSGMBR

MSGG881 .T=NOTIFY KANA

'Name must be alphabetic.'
MSGG882 .TYPE=N NOKANA
'Enter only number of days.'
MSGG883 .TYPE=CRITICAL
'The only rooms we have available are either SINGLE or DOUBLE. Please call th' +
'e manager of the hotel who will arrange equivalent lodging at another hotel ' +
'in the area. This is our mistake, and we will, of course, pick up the bill. ' +
'Please call collect &PHONENO.'
MSGG884 .T=A .W=R
'Please enter either BIGCHARGE, V I S T A, EZCARD, CHECK, or CASH.'
MSGG885 .TYPE=WARNING .WINDOW=NORESP
'Please enter your name.'
MSGG886 .TYPE=NOTIFY
'Please enter Y or N.'
MSGG887 .TYPE=NOTIFY
'Card number is a seven-digit number.'
MSGG888 .TYPE=WARNING .ALARM=YES
'The card number you entered, &CNUM is not valid.'
MSGG889 .TYPE=NOTIFY
'Message '9'' contains imbedded quotes.'

Figure 135. Messages

MSGMBR (Message Member)

The MSGMBR tag defines a message member.

ÊÊ <MSGMBR NAME=message-member-name Ê
CCSID=n 76
WIDTH= 68

Ê > </MSGMBR> ÊÍ

NAME=message-member-name
This specifies the name of the message member, which also serves as the prefix
for all identifiers of messages within the member.

The message-member-name can be specified as a 3–7 character name, conforming

to ISPF message member standard naming convention. The last two positions
must be numeric. The preceding characters can be A–Z, a–z, or #, $, @.

Lowercase characters are translated to their uppercase equivalents.

If you specify NAME=*, the message-member-name is set to the input DTL

source member name. If multiple dialog element definitions have been
combined within a single source file, then this notation should be used for
only one dialog element definition within the file. See “Dialog Elements” on
page 5 for a description of dialog element types created by the conversion
utility.

The message-member-name is also used to build the name used for storing
messages. For example, if NAME=MSGA12, the default name used to store the
message members is userid.MSGS(MSGA12). This can be changed by

380 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 MSGMBR
specifying a message file on the conversion utility invocation panel. See
“Chapter 10. Using the Conversion Utility” on page 167 for more information
on ISPDTLC syntax.

For information on allocating a message library at run time, refer to the ISPF
User’s Guide
CCSID=n
CCSID specifies the coded-character-set identifier as defined by the Character
Data Representation Architecture. CCSID should be entered as a five-position
numeric value. For more information on using the CCSID attribute, refer to the
ISPF Dialog Developer’s Guide and Reference
| WIDTH=76 | 68
| This attribute specifies the width of the formatted messages. When WIDTH=68,
| the resulting messages are formatted entirely within a normal Edit or View
| screen.

Description
The MSGMBR tag defines a message member. You can code multiple message
members for a single application.

The message-member-name is an explicit part of the identifier for messages coded in

the message member. Each message member contains multiple messages. You use
the MSG tag to define messages within a message member.

Conditions
v The MSGMBR tag requires an end tag.
v You cannot code the MSGMBR tag within any other tag definition.

Nested Tags
You can code the following tag within a MSGMBR definition:

Tag Name Usage Page Required

COMMENT Comment Multiple 272 No
MSG Message Multiple 376 Yes

Example
The following markup defines the message member MSGM88, which contains nine
MSG definitions. Figure 136 on page 382 shows the generated ISPF message
member.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=msgcls TYPE='char 20'>

<VARLIST>
<VARDCL NAME=phoneno VARCLASS=msgcls>
<VARDCL NAME=cnum VARCLASS=msgcls>
</VARLIST>

<MSGMBR NAME=msgm88>
<MSG SUFFIX=1>Name must be alphabetic.
<MSG SUFFIX=2>Enter only number of days.
<MSG SUFFIX=3 MSGTYPE=critical>The only rooms we have available
are either SINGLE or DOUBLE. Please call the manager of the hotel
who will arrange equivalent lodging at another

Chapter 13. Tag Reference 381

MSGMBR
hotel in the area. This is our mistake, and we will, of course,
pick up the bill. Please call collect <VARSUB VAR=phoneno>.
<MSG SUFFIX=4 MSGTYPE=action LOCATION=modal>Please enter either
BIGCHARGE, V I S T A, EZCARD, CHECK, or CASH.
<MSG SUFFIX=5 MSGTYPE=warning LOCATION=modeless>Please enter your name.
<MSG SUFFIX=6>Please enter Y or N.
<MSG SUFFIX=7>Card number is a seven-digit number.
<MSG SUFFIX=8 MSGTYPE=warning>The card number you
entered, <VARSUB VAR=cnum> is not valid.
<MSG SUFFIX=9>Message '9' contains imbedded quotes.
</MSGMBR>

MSGM881 .TYPE=NOTIFY
'Name must be alphabetic.'
MSGM882 .TYPE=NOTIFY
'Enter only number of days.'
MSGM883 .TYPE=CRITICAL
'The only rooms we have available are either SINGLE or DOUBLE. Please call th' +
'e manager of the hotel who will arrange equivalent lodging at another hotel ' +
'in the area. This is our mistake, and we will, of course, pick up the bill. ' +
'Please call collect &PHONENO.'
MSGM884 .TYPE=ACTION .WINDOW=RESP
'Please enter either BIGCHARGE, V I S T A, EZCARD, CHECK, or CASH.'
MSGM885 .TYPE=WARNING .WINDOW=NORESP
'Please enter your name.'
MSGM886 .TYPE=NOTIFY
'Please enter Y or N.'
MSGM887 .TYPE=NOTIFY
'Card number is a seven-digit number.'
MSGM888 .TYPE=WARNING
'The card number you entered, &CNUM is not valid.'
MSGM889 .TYPE=NOTIFY
'Message '9'' contains imbedded quotes.'

Figure 136. Message Member

NOTE (Note)
The NOTE tag defines a single-paragraph note within an information region.

ÊÊ <NOTE > ÊÍ
TEXT=alternate-note-heading note-text </NOTE>

TEXT=alternate-note-heading
This attribute provides a text string to replace the standard ″Note:″ heading.
note-text
This is the text of the note.

Description
The NOTE tag defines a single-paragraph note within an information region. You
can code the NOTE tag anywhere within an INFO tag.

The text of the note formats as an implied paragraph, at the current left margin.
The text “Note:” (or its translated equivalent), or the alternate note heading, begins
the paragraph and is aligned with the text of a list item when you use it within a
list.

382 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 NOTE
Conditions
v You must code the NOTE tag within an INFO definition. See “INFO
(Information Region)” on page 339 for a complete description of this tag.
v You cannot nest a NOTE tag within another NOTE definition.

Nested Tags
You can code the following tags within a NOTE tag:

Tag Name Usage Page Required

HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No

Example
The following help panel markup contains a note. Figure 137 shows the formatted
result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=note DEPTH=20>Book / Periodical Search Help

<AREA>
<INFO>
<P>This entry screen allows you to locate a desired
book or periodical by entering the title in the entry field.
<NOTE>If the item you are trying to locate is not
in stock and you would like to reserve it, please see the
librarian at the front desk.
</INFO>
</AREA>
</HELP>

Book / Periodical Search Help

This entry screen allows you to locate a desired

book or periodical by entering the title in the
entry field.

Note: If the item you are trying to locate is

not in stock and you would like to reserve it,
please see the librarian at the front desk.

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 137. Note

Chapter 13. Tag Reference 383

NOTEL

NOTEL (Note List)

The NOTEL tag defines a list of notes within an information region.

ÊÊ <NOTEL Ê
COMPACT NOSKIP NO INDENT=n
SPACE= YES

Ê > </NOTEL> ÊÍ
TEXT=alternate-note-heading

COMPACT
This attribute causes the list to be formatted without a blank line between the
list items.
NOSKIP
This attribute causes the list to format without creating a blank line before the
first line of the list.
SPACE=NO | YES
The SPACE attribute controls the indentation space for the list item. When the
SPACE attribute is not specified on the LI tag, the SPACE attribute from the
NOTEL tag is used to set the indentation space for the nested LI tag item-text.

When SPACE=YES, the indentation is set to 3 spaces.

When SPACE=NO (or SPACE is not specified), the indentation is set to 4

spaces.

The SPACE attribute can be used to control the alignment of list items when
the first word of some list items is a DBCS word preceded by a shift-out
character and the first word of other list items is an SBCS word.
INDENT=n
This attribute specifies that the note list be indented from the current left
margin.
TEXT=alternate-note-heading
This attribute provides a text string to replace the standard ″Notes:″ heading.

Description
The NOTEL tag defines a numbered list of notes. You can code the NOTEL tag
anywhere within an INFO tag.

The first line of the note list formats with the word ″Notes:″ (or its translated
equivalent) or the alternate-note-heading.

Use the LI tag to denote each list item. See “LI (List Item)” on page 346 for more
information on the LI tag.

Conditions
v You must code the NOTEL tag within an INFO definition. See “INFO
(Information Region)” on page 339 for a complete description of this tag.
v You cannot nest a NOTEL tag within a NOTEL definition.

384 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 NOTEL
Nested Tags
You can code the following tags within a NOTEL definition:

Tag Name Usage Page Required

LI List Item Multiple 346 No
LP List Part Multiple 352 No

Example
The following help panel markup contains a multiple notes. Notice the numbered
format for the content of the notes, which is different from the format generated
with the NOTE or NT tag. A P tag is nested within the NOTEL definition to
provide an additional paragraph of note text. Figure 138 shows the formatted
result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=notel DEPTH=20>Book / Periodical Search Help

<AREA>
<INFO>
<P>This entry screen allows you to locate a desired
book or periodical by entering the title in the entry field.
<NOTEL>
<LI>If the item you are trying to locate is not
in stock and you would like to reserve it, please see the
librarian at the front desk.
<LI>If the librarian is not there, please do not yell for help.
<P>This is a library!
</NOTEL>
</INFO>
</AREA>
</HELP>

Book / Periodical Search Help

This entry screen allows you to locate a desired

book or periodical by entering the title in the
entry field.

Notes:

1. If the item you are trying to locate is

not in stock and you would like to
reserve it, please see the librarian at
the front desk.

2. If the librarian is not there, please do

not yell for help.

This is a library!

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 138. NOTEL

Chapter 13. Tag Reference 385

NT

NT (Note)
The NT tag defines a single- or multiple-paragraph note within an information
region.

ÊÊ <NT > </NT> ÊÍ

TEXT=alternate-note-heading note-text

TEXT=alternate-note-heading
This attribute provides a text string to replace the standard ″Note:″ heading.
note-text
This is the text of the note. You can use the P tag to code additional
paragraphs of text.

Description
The NT tag defines a single- or multiple-paragraph note within an information
region. You can code the NT tag anywhere within an INFO definition.

The text of the note formats as an indented block. The block of text is indented
seven spaces from the current left margin. The text “Note:” (or its translated
equivalent), or the alternate note heading, begins the paragraph. The note aligns
with the text of a list item when you code it within a list.

Conditions
v The NT tag requires an end tag.
v You must code the NT tag within an INFO definition. See “INFO (Information
Region)” on page 339 for a complete description of this tag.
v You can nest text tags such as paragraphs and lists within a note, but you
cannot nest NT and NOTE tags.

Nested Tags
You can code the following tags within a NT definition:

Tag Name Usage Page Required

DL Definition list Multiple 288 No
FIG Figure Multiple 312 No
HP Highlighted phrase Multiple 336 No
LINES Lines Multiple 349 No
OL Ordered list Multiple 387 No
P Paragraph Multiple 390 No
PARML Parameter list Multiple 408 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
SL Simple list Multiple 447 No
UL Unordered list Multiple 457 No
XMP Example Multiple 474 No

386 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 NT
Example
The following help panel markup contains a multiple-paragraph note. Notice the
indented format for the content of the note, which is different from the format
generated with the NOTE tag. A P tag is nested within the NT definition to
provide an additional paragraph of note text. Figure 139 shows the formatted
result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=nt DEPTH=20>Book / Periodical Search Help

<AREA>
<INFO>
<P>This entry screen allows you to locate a desired
book or periodical by entering the title in the entry field.
<NT>If the item you are trying to locate is not
in stock and you would like to reserve it, please see the
librarian at the front desk.
<P>If the librarian is not there, please do not yell for help.
This is a library!
</NT>
</INFO>
</AREA>
</HELP>

Book / Periodical Search Help

This entry screen allows you to locate a desired

book or periodical by entering the title in the
entry field.

Note: If the item you are trying to locate is

not in stock and you would like to
reserve it, please see the librarian at
the front desk.

If the librarian is not there, please do

not yell for help. This is a library!

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 139. NT

OL (Ordered List)
The OL tag defines an ordered list of items within an information region.

ÊÊ <OL Ê
COMPACT NOSKIP NO INDENT=n
SPACE= YES

Ê > </OL> ÊÍ
TEXT=OL-heading-text

Chapter 13. Tag Reference 387

OL
COMPACT
This attribute causes the list to be formatted without a blank line between the
list items.
NOSKIP
This attribute causes the list to format without creating a blank line before the
first line of the list.
SPACE=NO | YES
The SPACE attribute controls the indentation space for the list item. When the
SPACE attribute is not specified on the LI tag, the SPACE attribute from the
OL tag is used to set the indentation space for the nested LI tag item-text.

When SPACE=YES, the indentation is set to 3 spaces. When SPACE=NO (or

SPACE is not specified), the indentation is set to 4 spaces.

The SPACE attribute can be used to control the alignment of list items when
the first word of some list items is a DBCS word preceded by a shift-out
INDENT=n
This attribute specifies that the list be indented from the current left margin.
TEXT=OL-heading-text
This attribute causes the list to format with a heading line containing the
OL-heading-text.

Description
The OL tag defines an ordered list of items within an information region. You use
ordered lists to indicate a set of sequential items or steps. You can code the OL tag
anywhere within an information region.

Ordered lists are formatted as indented lists, with sequential numbers or letters at
the left margin of the list items. Nested lists (lists embedded within other lists)
indent four spaces to the right of the left margin of the list that contains them.

Note: The SPACE attribute does not affect the indentation of nested lists.

The conversion utility adds a blank line before the first item in the list.

Sequential numbers or letters, depending on the nesting level of the ordered list
precede the list items. The levels are as follows:
1. Level 1: 1., 2., 3., . . .
2. Level 2: a., b., c., . . .
3. Level 3: 1), 2), 3), . . .
4. Level 4: a), b), c), . . .

Any additional levels repeat the sequence from level 1.

Panels formatted with the DBCS option use uppercase alphabetic characters for the
even-numbered nesting levels.

Use the LI tag to denote each list item. See “LI (List Item)” on page 346 for more
information on the LI tag.

Conditions
v The OL tag requires an end tag.

388 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 OL
v You must code the OL tag within an INFO definition. See “INFO (Information
Region)” on page 339 for a complete description of this tag.

Nested Tags
You can code the following tags within an OL definition:

Tag Name Usage Page Required

LI List item Multiple 346 No
LP List part Multiple 352 No

Example
The following help panel markup contains two ordered lists and a paragraph. The
second ordered list and the paragraph are nested within the first list. Figure 140 on
page 390 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=ol DEPTH=22 WIDTH=60>Widget Assembly Help

<AREA>
<INFO>
<P>To assemble your new Widget, you should:
<OL>
<LI>Attach the gizmo flexure component to the
main steering mechanism of the doohickey.
<OL COMPACT>
<LI>If slot A fits snugly on retaining
pin B, proceed to step 2.
<LI>If slot A does not fit snugly on
retaining pin B, throw the Widget away
and buy a new one.
</OL>
<LI>Use a screwdriver to turn the power drive unit on.
<LI>Stand back and watch the fun!
<P>Wake up the kids and call the neighbors, they won't
want to miss it!
</OL>
</INFO>
</AREA>
</HELP>

Chapter 13. Tag Reference 389

P

Widget Assembly Help

To assemble your new Widget, you should:

1. Attach the gizmo flexure component to the main

steering mechanism of the doohickey.

a. If slot A fits snugly on retaining pin B, proceed

to step 2.
b. If slot A does not fit snugly on retaining pin B,
throw the Widget away and buy a new one.

2. Use a screwdriver to turn the power drive unit on.

3. Stand back and watch the fun!

Wake up the kids and call the neighbors, they won't

want to miss it!

F1=Help F3=Exit F5=Exhelp F6=Keyshelp

F7=PrvTopic F8=NxtTopic F10=PrvPage F11=NxtPage
F12=Cancel

Figure 140. Ordered Lists

P (Paragraph)
The P tag defines a paragraph of text within an information region.

ÊÊ <P > Ê
COMPACT INTENSE=varname INDENT=n paragraph-text

Ê ÊÍ
</P>

COMPACT
This attribute causes the paragraph to format without a blank line before the
paragraph.
INTENSE=varname
This attribute supplies a variable name that must contain a valid value for the
INTENS keyword. The entire paragraph is controlled by this value. For
example, if the variable contains the value NON, the paragraph will not be
visible.
INDENT=n
This attribute specifies that the paragraph be indented from the current left
margin.
paragraph-text
This is the text of the paragraph.

Description
The P tag defines a paragraph of text within an information region. You can code
the P tag anywhere within an INFO definition.

Each paragraph formats as an unindented block of text. A blank line is added

before the paragraph unless the COMPACT attribute is specified.

390 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 P
Paragraphs within a list align with the text of the list item.

Conditions
v You must code the P tag within an INFO definition. See “INFO (Information
Region)” on page 339 for a complete description of this tag.

Nested Tags
You can code the following tags within a P definition:

Tag Name Usage Page Required

ATTENTION Attention Single 222 No
CAUTION Caution Single 230 No
HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
WARNING Warning Single 468 No

Example
The following help panel markup contains four paragraphs. The first three
paragraphs are coded within an information region with a defined width of 40, so
the text of the paragraphs will be formatted according to this width. The last
paragraph is coded within an information region with no defined width, so the
paragraph text will be formatted according to the width defined on the HELP tag.
Figure 141 on page 392 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=p DEPTH=22 WIDTH=60>P Tag Help

<AREA>
<INFO WIDTH=40>
<P>Here's a paragraph.
Lines are formatted to fill the width of the
information region.
<P>Here's another paragraph.
Notice the line skip between the paragraphs.
<P>Paragraphs are very versatile.
You can use them within many other tags.
</INFO>
<INFO WIDTH=58>
<P>The paragraphs above were formatted within an
information region defined with a width of 40.
This paragraph is formatted within the width specified
for the panel.
</INFO>
</AREA>
</HELP>

Chapter 13. Tag Reference 391

PANDEF

P Tag Help

Here's a paragraph. Lines are formatted

to fill the width of the information
region.

Here's another paragraph. Notice the

line skip between the paragraphs.

Paragraphs are very versatile. You can

use them within many other tags.

The paragraphs above were formatted within an information

region defined with a width of 40. This paragraph is
formatted within the width specified for the panel.

F1=Help F3=Exit F5=Exhelp F6=Keyshelp

F7=PrvTopic F8=NxtTopic F10=PrvPage F11=NxtPage
F12=Cancel

Figure 141. Paragraphs

PANDEF (Panel Default)

The PANDEF tag defines default values for application panels.

ÊÊ <PANDEF ID=pandef-id Ê
HELP= help-panel-name DEPTH= n
%varname FIT

Ê Ê
WIDTH= n
FIT
%varname

Ê Ê
KEYLIST=key-list-name
PRIVATE APPLID=application-id
KEYLTYPE= SHARED

Ê Ê
CCSID=n YES WINTITLE=window-title
WINDOW= NO

Ê Ê
APPTITLE=application-title PAD= NULLS PADC= NULLS
USER USER
char char
%varname %varname

392 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PANDEF
Ê Ê
NONE EXPAND=xy NO
OUTLINE= L MERGESAREA= YES
R
O
U
BOX
%varname

Ê Ê
ENTKEYTEXT=enter-key-text IMAPNAME= image-name
%varname

Ê Ê
IMAPROW= n
%varname

Ê > ÊÍ
IMAPCOL= n TMARGIN=n BMARGIN=n </PANDEF>
%varname

ID=pandef-id
This attribute defines the identifier for the panel default definition. The
pandef-id is the value you specify with the PANDEF attribute of PANEL tags
that refer to the panel default.

The pandef-id must follow the standard naming convention described in “Rules
for Variable Names” on page 201.
HELP=help-panel-name | %varname
This attribute specifies the extended (panel help) help panel that displays when
the user selects help on an application panel that specifies the panel default.

The help-panel-name must follow the standard naming convention described in

“Rules for Variable Names” on page 201.

Specification of the HELP attribute will cause ISPDTLC to generate

“.HELP=help-panel-name” (or “.HELP=&varname”) in the )INIT section during
panel generation.

ISPF displays this panel when the application user requests help and the
cursor is not on a panel field that has its own field-level help specified. This
help panel is also displayed when the user requests extended help.
DEPTH=n | FIT
This attribute specifies a default depth value for an application panel that
refers to this panel default. See “PANEL (Panel)” on page 397, for more
information.
WIDTH=n | FIT | %varname
This attribute specifies a default width value for an application panel that
refers to this panel default. See “PANEL (Panel)” on page 397, for more
information.

Chapter 13. Tag Reference 393

PANDEF
KEYLIST=key-list-name
This attribute specifies the name of a key mapping list associated with panels
that refer to this panel default. See “KEYL (Key List)” on page 344 for more
information.
KEYLTYPE= PRIVATE | SHARED
This attribute is used to add the SHARED keyword to the KEYLIST
parameter of the )PANEL statement. For more information about the
)PANEL statement, refer to the ISPF Dialog Developer’s Guide and Reference
APPLID=application-id
This attribute is used to add the application ID to the )PANEL statement.
The application-id overrides the KEYLAPPL invocation option value.
CCSID=n
This attribute specifies the default CCSID value for an application panel that
refers to this panel default. See “PANEL (Panel)” on page 397 for more
information.
WINDOW=YES | NO
The WINDOW attribute is used to control the generation of the WINDOW
keyword on the panel )BODY section. The default is to create the WINDOW
keyword. WINDOW=NO should be used when WIDTH=%varname is also
used to create a panel.
WINTITLE=window-title
This attribute is used to add a title on the pop-up window border. The
attribute value is placed in the ISPF ZWINTTL variable. The maximum length
of the window-title text is the panel width minus 1.
APPTITLE=application-title
This attribute is used to add a title on the GUI window border. The attribute
value is placed in the ISPF ZAPPTTL variable. The maximum length of the
application-title text is the panel width minus 1.
PAD=NULLS | USER | char | %varname
This attribute specifies the pad character for initializing the field. You can
define this attribute as a variable name preceded by a “%”.
PADC= NULLS | USER | char | %varname
This attribute specifies the conditional padding character to be used for
initializing the field. You can define this attribute as a variable name preceded
by a “%”.
OUTLINE=NONE | L | R | O | U | BOX | %varname
This attribute provides for displaying lines around the field on a DBCS
terminal. You can define this attribute as a variable name preceded by a “%”.
EXPAND=xy
This attribute adds the EXPAND(xy) attribute to the )BODY section of the
panel. If only one character is present, the second character will be set to the
same value. If the EXPAND attribute is present with no value specified, the
conversion utility will use a character from the range of low-order hex values
available for panel attributes. This removes an available character from
possible use as a panel attribute and may cause panel formatting errors.
MERGESAREA= NO | YES
This attribute controls an additional formatting step for panels with a single
scrollable area. If the entire contents of the scrollable area will fit within a
standard 24-line panel (allowing 2 lines for the function keys display), and no

394 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PANDEF
input or output fields are found in the panel body following the location of the
scrollable area, the scrollable area content is moved into the panel body.
ENTKEYTEXT=enter-key-text
This attribute is provide the text for the Enter key push button provided on
panels displayed in GUI mode. The ENTKEYTEXT attribute causes a statement
to be added to the panel )INIT section to set the value of the ZENTKTXT
variable to the enter-key-text value.
IMAPNAME=image-name | %varname
This attribute specifies the name of a image to be placed on the panel when it
is displayed in GUI mode. The image-name is not used when the panel is
displayed in host mode.

The image-name must follow the standard naming convention described in

“Rules for Variable Names” on page 201.
IMAPROW=n | %varname
This attribute specifies the row number for positioning the image. Image
position uses an orgin based on 0. Therefore, the minimum row value is 0 and
the maximum is 61, relating to the description for the DEPTH attribute on the
PANEL tag. If a varible name is used, the application must set the variable to a
valid value before the panel is displayed. The value specified should be within
the actual panel depth for the image to be visible when the panel is displayed.
IMAPCOL=n | %varname
This attribute specifies the column number for positioning the image. Image
position uses an orgin based on 0. Therefore, the minimum column value is 0
and the maximum is 159, relating to the description for the WIDTH attribute
on the PANEL tag. If a varible name is used, the application must set the
variable to a valid value before the panel is displayed. The value specified
should be within the actual panel width for the image to be visible when the
panel is displayed.
TMARGIN=n
This attribute provides the number of blank lines to format at the top of the
panel as a top margin.
BMARGIN=n
This attribute provides the number of blank lines to format at the bottom of
the panel as a bottom margin.

Description
The PANDEF tag defines default values for application panels.

PANEL tags refer to the panel default by specifying the pandef-id definition as the
PANDEF attribute value. When a PANEL tag refers to a panel default, the values
specified by the associated PANDEF tag are used for the panel unless overridden
by values specified in the PANEL tag definition.

The PANEL tag can override any of the PANDEF values by specifying that value
within its own definition. Thus, it is possible for a PANEL tag to select certain
default values from the panel default and override others.

See “PANEL (Panel)” on page 397 for more information.

You can code multiple panel defaults for an application. Each panel default should
have a unique pandef-id.

Chapter 13. Tag Reference 395

PANDEF
Conditions
v You cannot code the PANDEF tag within any other tag definition.
v You must code the PANDEF tag before you code any PANEL tag that refers to it.
v If both PAD and PADC have been specified, PAD is ignored and PADC is used.
v When a “%varname” notation is found on any of the attributes that allow a
variable name, the “%varname” entry must follow the standard naming
convention described in “Rules for “%variable” Names” on page 201.
v EXPAND can operate only when there are no trailing attributes on the line to be
expanded. Panel lines formatted as part of a horizontal region require the use of
attributes for field alignment. Therefore, the EXPAND feature is functional only
for panel sections built within a vertical (or default) region that is not part of
any horizontal region.

Nested Tags
None.

Example
The following source file markup contains two panel default definitions. The
application panels panel1 and panel2 both refer to the panel default pandef1. The
panel panel1 uses all of the defined default values and panel2 uses only the default
DEPTH and WIDTH values, and overrides the default HELP and KEYLIST values
by specifying those values in the PANEL definition. The third application panel,
panel3 refers to all of the default values specified in the panel default pandef2.
<!DOCTYPE DM SYSTEM(
<!entity sampvar1 sysem>
<!entity sampbody system>)>
&sampvar1;

<PANDEF ID=panldef1 DEPTH=20 WIDTH=76 HELP=helpaaa KEYLIST=keylxmp>

<PANDEF ID=panldef2 DEPTH=22 WIDTH=70 HELP=morehlp>

<PANEL NAME=pandef1 PANDEF=panldef1>First Panel

&sampbody;
</PANEL>

<PANEL NAME=pandef2 PANDEF=panldef1

HELP=morehlp KEYLIST=keyltbl>Second Panel
&sampbody;
</PANEL>

<PANEL NAME=pandef3 PANDEF=panldef2>Third Panel

&sampbody;
</PANEL>

<HELP NAME=helpaaa>Help panel "helpaaa"

<AREA>
<INFO WIDTH=48>
<P>This is PANDEF help panel "helpaaa"
</INFO>
</AREA>
</HELP>

<HELP NAME=morehlp>Help panel "morehlp"

<AREA>
<INFO WIDTH=48>

396 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PANDEF
<P>This is PANDEF help panel "morehlp"
</INFO>
</AREA>
</HELP>

PANEL (Panel)
The PANEL tag defines an application panel.

ÊÊ <PANEL NAME=panel-name Ê
HELP= help-panel-name
%varname

Ê Ê
PANDEF=pandef-id 22 76
DEPTH= n WIDTH= n
FIT FIT
%varname

Ê Ê
KEYLIST=key-list-name KEYLIST Options

Ê Ê
CURSOR=cursor-field
CSRINDEX=index-value CSRPOS=position-value

Ê Ê
CCSID=n MENU PRIME TUTOR YES
WINDOW= NO

Ê Ê
WINTITLE=window-title APPTITLE=application-title

Ê Ê
PAD= NULLS PADC= NULLS NONE
USER USER OUTLINE= L
char char R
%varname %varname O
U
BOX
%varname

Ê Ê
EXPAND=xy

Ê Ê
YES YES YES
MSGLINE= NO TITLINE= NO CMDLINE= NO

Chapter 13. Tag Reference 397

PANEL
Ê Ê
NO DEFAULT BOTH
ATTRUSE= YES ENDATTR= TEXT TYPE= GUI
ALL NOGUI

Ê Ê
SMSG=short-msg-fieldname LMSG=long-msg-fieldname ASIS

Ê Ê
ACTBAR NO YES
MERGESAREA= YES PANELSTMT= NO

Ê Ê
ENTKEYTEXT=enter-key-text

Ê Ê
IMAPNAME= image-name IMAP Options TMARGIN=n BMARGIN=n
%varname

Ê > Ê
NO
ERRORCHECK= YES

Ê </PANEL> ÊÍ
panel-title-text

KEYLIST Options:

PRIVATE APPLID=application-id
KEYLTYPE= SHARED

IMAP Options:

IMAPROW= n IMAPCOL= n
%varname %varname

NAME=panel-name
This attribute specifies the name of the panel. The panel-name is used in the
ISPF DISPLAY or TBDISPL service call. The panel-name is also used as the
panel ID, which the user can display. The panel-name must follow the standard
naming convention described in “Rules for Variable Names” on page 201.

If you specify NAME=*, the panel-name is set to the input DTL source member
name. If multiple dialog element definitions have been combined within a
single source file, then this notation should be used for only one dialog

398 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PANEL
element definition within the file. See “Dialog Elements” on page 5 for a
description of dialog element types created by the conversion utility.

The panel-name is used to build the panel output file name in which the
conversion utility stores the converted panel. The default is
“userid.PANELS(panel-name)”.

You can specify the output panel library filename of your choice on the
invocation panel for the conversion utility, or in the conversion utility profile
as DDname DTLPAN for batch (or command syntax invocation) processing.

If the SCRIPT option has been specified, the panel-name is also used to build
the file name in which the conversion utility stores the image of the panel. The
default name is “userid.SCRIPT(panel-name)”.

You can specify the output SCRIPT library filename of your choice on the
invocation panel for the conversion utility, or in the conversion utility profile
as DDname DTLSCR for batch (or command syntax invocation) processing.

See “Chapter 10. Using the Conversion Utility” on page 167 for complete
information on invocation syntax.
HELP=help-panel-name | %varname
This attribute specifies the name of a defined extended (panel help) help panel.
It identifies the help text that is associated with the panel definition.

The help-panel-name must follow the standard naming convention described in

“Rules for Variable Names” on page 201.

Specification of the HELP attribute will cause ISPDTLC to generate

“.HELP=help-panel-name” (or “.HELP=&varname”) in the )INIT section during
panel generation.

ISPF displays this panel when the application user requests help and the
cursor is not on a panel field that has its own field-level help specified. This
help panel is also displayed when the user requests extended help.
PANDEF=pandef-id
This attribute specifies a defined panel default. The pandef-id value is the
identifier specified on the PANDEF tag. You can override any of the defaults
from this PANDEF tag by specifying that attribute on the PANEL tag. See
“PANDEF (Panel Default)” on page 392 for information on defining panel
defaults.
DEPTH=22 | n | FIT
This attribute defines the depth of the panel. The default depth is 22 when
WINDOW=YES or 24 when WINDOW=NO. When the panel is displayed in a
pop-up, ISPF adds two lines to the DEPTH value you specify to accommodate
the borders at the top and bottom of the pop-up.

The value specified for the depth is the depth of the entire panel including the
panel title, the action bar, the function key area, the message area, any
scrollable areas, and the command area.

Chapter 13. Tag Reference 399

PANEL
The maximum depth is 62 and the minimum depth is 5. If the DEPTH value is
less than the minimum value allowed or exceeds the maximum value allowed,
the conversion utility issues a warning message and sets the depth to the
default.

The depth defined should be large enough to include all formatted text and
input/output fields as well as the function key area, message area, any
scrollable areas, and the command area. If the depth specified is not large
enough to include these panel elements, ISPF will overlay with the function
keys if the function key display is on or with the message area if the message
is not displayed in a pop-up.

If DEPTH=FIT, The conversion utility will format the panel using a depth of
22. When formatting is completed the DEPTH value will be reset to the
minimum depth used or to 5 if the formatted panel contains less than 5 lines.

If the DEPTH value exceeds the maximum allowed to display the panel on the
device, ISPF issues an error message at run time.
WIDTH=76 | n | FIT | %varname
This attribute defines the width (in characters) of the panel. The default width
is 76 when WINDOW=YES or 80 when WINDOW=NO. When the panel is
displayed in a pop-up, ISPF adds 4 to the WIDTH value you specify to
accommodate the left and right borders of the pop-up.

The value specified for the width is the width of the entire panel (or region),
including the margins.

The maximum width is 160 and the minimum width is 16.

Because there is a minimum margin width of 1 character on each side of the

panel text, the effective width for text for a panel defined with WIDTH=76 is a
maximum of 74 characters.

If the WIDTH value is less than the minimum value allowed or exceeds the
maximum value allowed, ISPDTLC issues a warning message and sets the
width to the default.

If WIDTH=FIT or WIDTH=%varname, the conversion utility will format the

panel using the maximum available width as determined from the LRECL
value of the output panel file.

If WIDTH=FIT, when formatting is completed the WIDTH value will be reset

to the minimum width used or to 16 if the formatted panel is less than 16
characters wide.

If WIDTH=%varname, when formatting is completed the WIDTH keyword on

the )BODY panel statement is set to the variable name. WINDOW=NO must
also be coded on the PANEL tag in order to use %varname.

Note: Panels that have the width specified as a variable cannot be

preprocessed.

If WIDTH value exceeds the maximum allowed to display the panel on the
device, ISPF issues an error message at run time.

400 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PANEL
KEYLIST=key-list-name
This attribute specifies the name of the key mapping list associated with the
panel.

If you do not specify a key-list-name in a PANEL definition or an associated

PANDEF definition, the ISPF-provided key list (ISPKYLST) will be used. For
information on defining key mapping lists, see “KEYL (Key List)” on page 344.
For information on the ISPF-provided key list, refer to the ISPF User’s Guide
KEYLTYPE=PRIVATE | SHARED
This attribute is used to add the SHARED keyword to the KEYLIST
parameter of the )PANEL statement. For information about the )PANEL
statement, refer to the ISPF Dialog Developer’s Guide and Reference The
KEYLTYPE attribute is ignored if you have not provided the KEYLIST
attribute as part of the PANEL tag definition or as part of an associated
PANDEF tag definition.
APPLID=application-id
This attribute is used to add the application ID to the )PANEL statement.
The application-id overrides the KEYLAPPL invocation option value. The
APPLID attribute is ignored if you have not provided the KEYLIST
attribute as part of the PANEL tag definition or as part of an associated
PANDEF tag definition.
CURSOR=cursor-field
This attribute, together with CSRINDEX and CSRPOS, controls the initial
placement of the cursor when the ISPF displays the panel. You can specify
cursor-field as the value of:
v The NAME attribute of a CHOICE tag (for multiple-choice selection fields)
| v The DATAVAR attribute of the CHOFLD tag.
v The DATAVAR attribute of a DTAFLD tag
v The DATAVAR attribute of a LSTCOL tag
v The NAME attribute of a SELFLD tag (for single-choice selection fields).

The cursor can also be placed on the command area, when it is defined for a
panel with the CMDAREA tag. Use the ISPF-reserved name cmdarea as the
value for cursor-field to place the cursor on the command area.
CSRINDEX=index-value
This attribute, together with CURSOR and CSRPOS, controls the placement
of the cursor when ISPF displays a table display panel. This attribute may
be specified only when the CURSOR attribute refers to a list column.

CSRINDEX specifies the row in the )MODEL section where ISPF places the
cursor when it displays the panel.
CSRPOS=position-value
This attribute, together with CURSOR and CSRINDEX, controls the
placement of the cursor when ISPF displays the panel. This attribute may
be specified only when the CURSOR attribute refers to a data field, list
column, or the command area.

CSRPOS specifies the number of byte positions into the entry field that
ISPF places the cursor when it displays the panel.

The first position of a field is denoted by 1. The maximum position that

you can specify is the length of the underlying data.

Chapter 13. Tag Reference 401

PANEL
If the value specified for this attribute is not valid, the default (1) is used.
CCSID=n
This attribute specifies the coded-character-set identifier as defined by the
Character Data Representation Architecture. CCSID should be entered as a
five-position numeric value. For more information on using the CCSID
attribute, refer to the ISPF Dialog Developer’s Guide and Reference
MENU
This attribute specifies that the panel will be an ISPF menu selection or edit
model selection panel. This type of panel does not allow a table display.
PRIME
This attribute is used together with MENU to specify a primary option menu.
TUTOR
This attribute specifies that the panel title be formatted with the word Tutorial
(or its translated equivalent) on each end of the title line, similar to ISPF
tutorial panels.
WINDOW=YES | NO
The WINDOW attribute is used to control the generation of the WINDOW
keyword on the panel )BODY section. The default is to create the WINDOW
keyword. WINDOW=NO should be used when WIDTH=%varname is also
used to create a panel.
WINTITLE=window-title
This attribute is used to add a title on the pop-up window border. The
attribute value is placed in the ISPF ZWINTTL variable. The maximum length
of the window-title text is the panel width minus 1.
APPTITLE=application-title
This attribute is used to add a title on the GUI window border. The attribute
value is placed in the ISPF ZAPPTTL variable. The maximum length of the
application-title text is the panel width minus 1.
PAD=NULLS | USER | char | %varname
This attribute specifies the pad character for initializing the field. You can
define this attribute as a variable name preceded by a “%”.
PADC= NULLS | USER | char | %varname
This attribute specifies the conditional padding character to be used for
initializing the field. You can define this attribute as a variable name preceded
by a “%”.
OUTLINE=NONE | L | R | O | U | BOX | %varname
This attribute provides for displaying lines around the field on a DBCS
terminal. You can define this attribute as a variable name preceded by a “%”.
EXPAND=xy
This attribute adds the EXPAND(xy) attribute to the )BODY section of the
panel. If only one character is present, the second character will be set to the
same value. If the EXPAND attribute is present with no value specified, the
conversion utility will use a character from the range of low-order hex values
available for panel attributes. This removes an available character from
possible use as a panel attribute and may cause panel formatting errors.
MSGLINE=YES | NO
This attribute controls the provision for a long message line in the generated
panel. When MSGLINE=NO, the blank line for the long message is not added

402 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PANEL
to the panel )BODY section. It is the panel designer’s responsibility to ensure
that critical panel areas are positioned so that the long message will not inhibit
use of the resulting panel.
TITLINE=YES | NO
This attribute controls the generation of the panel title line. When
TITLINE=NO, the panel title is not added to the generated panel. This option
is provided for applications that format a panel title as part of a dynamic area.
It is the panel designer’s responsibility to ensure that the resulting panel meets
CUA requirements.
CMDLINE=YES | NO
This attribute controls the automatic generation of the command area on
option menu panels and table display panels. When CMDLINE=NO, the
command area is not automatically added to panels that do not include a
CMDAREA tag within the panel definition.
ATTRUSE=NO | YES | ALL
This attribute controls the assignment of panel attributes within the range of
x‘01’ through x‘3F’. When ATTRUSE=YES or ATTRUSE=ALL, attributes for use
in dynamic areas supplied by the ATTR tag can be assigned low-order hex
values normally used by the conversion utility.

When ATTRUSE=YES, all of the attributes specified by the ATTR tag plus the
required attributes used by the conversion utility must fit in the defined range
of x‘01’ through x‘2F’.

When ATTRUSE=ALL, all of the attributes specified by the ATTR tag plus the
required attributes used by the conversion utility must fit in the defined range
of x‘01’ through x‘3F’.
ENDATTR=DEFAULT | TEXT
This attribute specifies that when the last attribute on any panel body line is
“normal text” (CUA), it will be replaced by the default “text” (ISPF) attribute.
The effect is to force any text on subsequent lines not preceded by another
attribute from the normal text color to blue.
TYPE=BOTH | GUI | NOGUI
This attribute specifies that the panel will be used for either host display, GUI
display, or both. When NOGUI is specified, for example, the panel language
control statements that enable check boxes, radio buttons, list boxes,
drop-down lists, and combination boxes are not added to the generated panel.
When GUI is specified, SELFLD tag formatting for list boxes, drop-down lists,
and combination boxes results in only 1 line in the panel )BODY section; the
choice list is displayed as a GUI function.
SMSG=short-msg-fieldname
This attribute provides the name of the field where the short message is to be
placed. The short-msg-fieldname must follow the standard naming convention
described in “Rules for Variable Names” on page 201.
LMSG=long-msg-fieldname
This attribute provides the name of the field where the long message is to be
placed. The long-msg-fieldname must follow the standard naming convention
described in “Rules for Variable Names” on page 201.
ASIS
This attribute specifies that the command and long message fields are to
appear on the display as specified in the generated panel definition. When

Chapter 13. Tag Reference 403

PANEL
ASIS is specified, any user request specified on the Settings panel, or by setting
the system variable ZPLACE is ignored.
ACTBAR
This attribute causes the action bar information for the panel to be generated,
overriding the NOACTBAR invocation option.
MERGESAREA=NO | YES
This attribute controls an additional formatting step for panels with a single
scrollable area. If the entire contents of the scrollable area will fit within a
standard 24-line panel (allowing 2 lines for the function keys display), and no
input or output fields are found in the panel body following the location of the
scrollable area, the scrollable area content is moved into the panel body.
PANELSTMT=YES | NO
This attribute controls the creation of the )PANEL statement. You can use this
attribute to create a panel without keylist interaction.
ENTKEYTEXT=enter-key-text
This attribute is provide the text for the Enter key push button provided on
panels displayed in GUI mode. The ENTKEYTEXT attribute causes a statement
to be added to the panel )INIT section to set the value of the ZENTKTXT
variable to the enter-key-text value.
IMAPNAME=image-name | %varname
This attribute specifies the name of a image to be placed on the panel when it
is displayed in GUI mode. The image-name is not used when the panel is
displayed in host mode.

The image-name must follow the standard naming convention described in

“Rules for Variable Names” on page 201.
IMAPROW=n | %varname
This attribute specifies the row number for positioning the image. Image
position uses an orgin based on 0. Therefore, the minimum row value is 0
and the maximum is 61, based on the above description for the DEPTH
attribute. If a varible name is used, the application must set the variable to
a valid value before the panel is displayed. The value specified should be
within the actual panel depth for the image to be visible when the panel is
displayed.
IMAPCOL=n | %varname
This attribute specifies the column number for positioning the image.
Image position uses an orgin based on 0. Therefore, the minimum row
value is 0 and the maximum is 159, based on the above description for the
WIDTH attribute. If a varible name is used, the application must set the
variable to a valid value before the panel is displayed. The value specified
should be within the actual panel width for the image to be visible when
the panel is displayed.
TMARGIN=n
This attribute provides the number of blank lines to format at the top of the
panel as a top margin.
BMARGIN=n
This attribute provides the number of blank lines to format at the bottom of
the panel as a bottom margin.

404 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PANEL
| ERRORCHECK=NO | YES
| This attribute specifies whether error checking logic is added to the end of the
| )PROC section. The extra logic prevents exit from the panel if any errors are
| present.
| IF (.MSG ¬= ' ')
| &ZVERB = ' '
| .RESP = ENTER
| panel-title-text
This is the text of the panel title.

Panel titles should be used when more than one panel can be displayed within
an application. The panel-title-text is centered within the width defined for the
panel in accordance with CUA rules. If the panel-title-text is wider than the
WIDTH specified, the title is truncated, from the right, with an ellipsis (...)
appended. Two lines are reserved for the panel title and for a blank line
between the panel title and the rest of the panel body.

Description
The PANEL tag defines an application panel.

Tags coded within a PANEL definition (between the PANEL start tag and end tag)
define the content of the panel.

Conditions
v When the MENU attribute is specified, the LSTFLD tag cannot be nested under
the PANEL tag.
v The PANEL tag requires an end tag.
v You cannot code a PANEL tag within any other tag definition.
v The PANEL definition must contain at least one of the following tags:
– BOTINST (See “BOTINST (Bottom Instruction)” on page 228)
– DA (See “DA (Dynamic Area)” on page 277)
– DTAFLD (See “DTAFLD (Data Field)” on page 299)
– GA (See “GA (Graphic Area)” on page 316)
– INFO (See “INFO (Information Region)” on page 339)
– LSTFLD (See “LSTFLD (List Field)” on page 364)
– PNLINST (See “PNLINST (Panel Instruction)” on page 418)
– SELFLD (See “SELFLD (Selection Field)” on page 433)
– TOPINST (See “TOPINST (Top Instruction)” on page 455)
v If both PAD and PADC have been specified, PAD is ignored and PADC is used.
v When a “%varname” notation is found on any of the attributes that allow a
variable name, the “%varname” entry must follow the standard naming
convention described in “Rules for “%variable” Names” on page 201.
v EXPAND can operate only when there are no trailing attributes on the line to be
expanded. Panel lines formatted as part of a horizontal region require the use of
attributes for field alignment. Therefore, the EXPAND feature is functional only
for panel sections built with a vertical (or default) region that is not part of any
horizontal region.

Chapter 13. Tag Reference 405

PANEL
Nested Tags
You can code the following tags within a PANEL definition:

Tag Name Usage Page Required

AB Action bar Single 201 No
AREA Area Multiple 213 No
BOTINST Bottom instruction Multiple 228 No
CMDAREA Command area Single 264 No
COMMENT Comment Multiple 272 No
DA Dynamic area Multiple 277 No
DIVIDER Area divider Multiple 285 No
DTACOL Data column Multiple 293 No
DTAFLD Data field Multiple 299 No
GA Graphic area Single 316 No
GRPHDR Group header Multiple 320 No
HP Highlighted phrase Multiple 336 No
INFO Information region Multiple 339 No
LSTFLD * List field Single 364 No
PNLINST Panel Instruction Multiple 418 No
REGION Region Multiple 424 No
SELFLD Selection field Multiple 433 No
TEXTLINE Text Line Single 452 No
TOPINST Top instruction Multiple 455 No
Note:
* This tag is not valid within an ISPF selection menu panel.

Example
The following application panel markup contains an action bar, a top instruction,
two selection fields, and a command area. The PANEL KEYLIST attribute specifies
a key mapping list, which is displayed below the command area. Figure 142 on
page 407 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=selcls TYPE='CHAR 2'>

<VARLIST>
<VARDCL NAME=loc VARCLASS=selcls>
<VARDCL NAME=mode VARCLASS=selcls>
</VARLIST>

<PANEL NAME=panel HELP=trvlhlp KEYLIST=keylxmp

DEPTH=22 WIDTH=60>Dream Vacation Guide
<AB>
<ABC>File
<PDC>Add Entry
<ACTION RUN=add>
<PDC>Delete Entry
<ACTION RUN=delete>
<PDC>Update Entry
<ACTION RUN=update>
<PDC>Exit

406 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PANEL
<ACTION RUN=exit>
<ABC>Help
<PDC>Extended Help...
<ACTION RUN=exhelp>
<PDC>Keys Help...
<ACTION RUN=keyshelp>
</AB>
<TOPINST>Choose one of the following exotic locations and
your preferred mode of travel, then press Enter.
<AREA>
<REGION DIR=horiz>
<SELFLD NAME=loc PMTWIDTH=23 SELWIDTH=25>Exotic Location:
<CHOICE>Athens, GA
<CHOICE>Berlin, CT
<CHOICE>Cairo, IL
<CHOICE>Lizard Lick, NC
<CHOICE>Paris, TX
<CHOICE>Rome, NY
<CHOICE>Venice, FL
</SELFLD>
<DIVIDER>
<SELFLD NAME=mode PMTWIDTH=25 SELWIDTH=25>Travel Mode:
<CHOICE>Boxcar
<CHOICE>Hitchhike
<CHOICE>Mule
</SELFLD>
</REGION>
</AREA>
<CMDAREA>
</PANEL>

<HELP NAME=trvlhlp>Sample help panel "trvlhelp"

<AREA>
<INFO WIDTH=48>
<P>This is help panel "trvlhlp"
</INFO>
</AREA>
</HELP>

File Help
---------------------------------------------------------
Dream Vacation Guide

Choose one of the following exotic locations and your

preferred mode of travel, then press Enter.

Exotic Location: Travel Mode:

__ 1. Athens, GA __ 1. Boxcar
2. Berlin, CT 2. Hitchhike
3. Cairo, IL 3. Mule
4. Lizard Lick, NC
5. Paris, TX
6. Rome, NY
7. Venice, FL

Command ===> ______________________________________________

F1=Help F2=Split F3=Exit F6=Keyshelp
F9=Swap F12=Cancel

Figure 142. Application Panel

Chapter 13. Tag Reference 407

PARML

PARML (Parameter List)

The PARML tag defines a parameter list within an information region.

ÊÊ <PARML Ê
10 ALL COMPACT
TSIZE= n BREAK= FIT
NONE

Ê > </PARML> ÊÍ
INDENT=n

TSIZE=10 | n
This attribute defines the space allocated for the parameter term. The default is
10 characters. The minimum TSIZE value is 0 and the maximum is 40.
BREAK=ALL | FIT | NONE
This attribute controls the formatting of the parameter terms and descriptions.
If BREAK=ALL (the default), every description is on the line below the term. If
BREAK=FIT, the description is on the line below the term if the term is longer
than the TSIZE value. If BREAK=NONE, the term is on the same line as the
description, spilling into the description area if the length exceeds the TSIZE
value.
COMPACT
This attribute causes the conversion utility to format the list without a blank
line between the items.
INDENT=n
This attribute specifies that the parameter list be indented from the current left
margin.

Description
The PARML tag defines a parameter list within an information region.

Parameter lists are similar to definition lists. They involve three tags: PARML
(parameter list) and a matching end tag, PT (parameter term), and PD (parameter
description). As in definition lists, the term tag defines a term, and the definition
tag defines the description associated with the term. The PD tag must immediately
follow the PT tag that it is associated with.

Parameter lists can occur anywhere in an information region; you can nest them
within other lists, and you can nest other lists within parameter lists.

Conditions
v The PARML tag requires an end tag.
v You must code the PARML tag within an INFO definition. See “INFO
(Information Region)” on page 339 for a complete description of this tag.

408 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PARML
Nested Tags
You can code the following tags within a PARML definition:

Tag Name Usage Page Required

PT Parameter term Multiple 422 No
PD Parameter description Multiple 410 No

Example
The following help panel markup contains two parameter lists. The second
parameter list is nested within the second parameter description of the first list.
Figure 143 on page 410 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=parml DEPTH=22>Part Number Code Help

<AREA>
<INFO>
<P>Valid part numbers consist of a three-digit
number followed by a 2-character suffix.
<PARML TSIZE=6>
<PT>123
<PD>The first three digits represent
the lot number of the part.
<PT>AA
<PD>The 2-character suffix represents the
department the part originated from.
The valid suffixes are:
<PARML BREAK=none COMPACT>
<PT>TO
<PD>Tools
<PT>EL
<PD>Electrical
<PT>ME
<PD>Mechanical
</PARML>
</PARML>
</INFO>
</AREA>
</HELP>

Chapter 13. Tag Reference 409

PD

Part Number Code Help

Valid part numbers consist of a three-digit

number followed by a 2-character suffix.

123
The first three digits represent the lot
number of the part.

AA
The 2-character suffix represents the
department the part originated from. The
valid suffixes are:

TO Tools
EL Electrical
ME Mechanical

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 143. Parameter List

PD (Parameter Description)
The PD tag defines a parameter description in a parameter list.

ÊÊ <PD> ÊÍ
parameter-description </PD>

parameter-description
This is the text of the parameter description.

Description
The PD tag defines a parameter description in a parameter list.

Conditions
v You must code the PD tag within a PARML definition. See “PARML (Parameter
List)” on page 408 for a complete description of this tag.
v Each PD tag must be paired with a PT tag. You can specify only one PD tag for
each PT tag within a parameter list. The PD tag must immediately follow the PT
tag it is associated with.

Nested Tags
You can code the following tags within a PD definition:

Tag Name Usage Page Required

DL Definition list Multiple 288 No
FIG Figure Multiple 312 No
HP Highlighted phrase Multiple 336 No
LINES Lines Multiple 349 No
NOTE Note Multiple 382 No

410 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PD
Tag Name Usage Page Required
NOTEL Note List Multiple 384 No
NT Note Multiple 386 No
OL Ordered list Multiple 387 No
P Paragraph Multiple 390 No
PARML Parameter list Multiple 408 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
SL Simple list Multiple 447 No
UL Unordered list Multiple 457 No
XMP Example Multiple 474 No

Example
The following help panel markup contains a parameter list with three PD
definitions. Figure 144 on page 412 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=pd DEPTH=20>Help for Ordering Parts

<AREA>
<INFO>
<P>Use one of the following codes when ordering
a part number from inventory:
<PARML TSIZE=5>
<PT>ST
<PD>Indicates that the part
order is for stock replenishment.
<PT>CU
<PD>Indicates that the part
order is for immediate customer shipment.
<PT>EL
<PD>Indicates that the part
order is for shipment to an external location.
</PARML>
</INFO>
</AREA>
</HELP>

Chapter 13. Tag Reference 411

 PDC

Help for Ordering Parts

Use one of the following codes when ordering a

part number from inventory:

ST
Indicates that the part order is for stock
replenishment.

CU
Indicates that the part order is for
immediate customer shipment.

EL
Indicates that the part order is for
shipment to an external location.

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 144. Parameter Descriptions

PDC (Pull-Down Choice)

The PDC tag defines a pull-down choice for an action bar pull-down.

ÊÊ <PDC Ê
NO UNAVAIL=unavail-variable-name
HELP= YES
help-panel-name
*help-message-id
%varname
*%varname

Ê Ê
CHECKVAR=check-variable-name
1
MATCH= match-string

Ê > pull-down-description-text Ê
ACC1=key1 ACC2=key2 ACC3=key3

Ê ÊÍ
</PDC>

| HELP=NO | YES | help-panel-name | *help-message-id | %varname |

| *%varname
| This attribute specifies the help action taken when the user requests help for a
| pull-down choice selection.

| When HELP=YES, control is returned to the application. You can specify either
| a help panel or a message identifier. If a message identifier is used, it must be
| prefixed with an asterisk (*).

412 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PDC
| The help attribute value can be specified as a variable name. When %varname
| is coded, a panel variable name is created. When *%varname is coded, a
| message variable name is created.

| If the user requests help on a choice and no help is defined, the extended help
| panel is displayed. If an extended help panel is not defined for the panel, the
| application or ISPF tutorial is invoked.

| The help-panel-name must follow the standard naming convention described in

| “Rules for Variable Names” on page 201.

| See “HELP (Help Panel)” on page 323 for information on creating help panels.
| For information about creating messages, see “MSG (Message)” on page 376.

| Note: This attribute is valid only when the SELFLD tag has been specified
| with TYPE=MULTI.
| UNAVAIL=unavail-variable-name
This attribute specifies the name of a variable that is used by ISPF to
determine the availability of the pull-down choice. When the variable value is
1, the pull-down choice is unavailable.

The unavail-variable-name must follow the standard naming convention

described in “Rules for Variable Names” on page 201.
CHECKVAR=check-variable-name
This attribute specifies a variable whose value indicates whether or not the
pull-down choice is preselected when the pull-down is displayed. If the value
of the variable is equivalent to the match-string you specify with the MATCH
attribute, the pull-down choice appears preselected. Otherwise, it does not. The
check-variable-name must follow the standard naming convention described in
“Rules for Variable Names” on page 201.

Note: Unlike selection fields, ISPF does not reset the check-variable-name to
indicate the pull-down choice the user selects. Therefore, you should
code the SETVAR attribute in an ACTION tag associated with the
pull-down choices when the application needs to know which
pull-down choice was selected.
MATCH=1 | match-string
This attribute defines the value that causes the pull-down choice to be
preselected. The value of variable specified by the CHECKVAR attribute is
compared to the match-string value, and if they are equal, the pull-down
choice appears preselected.
ACC1=key1
This attribute specifies an accelerator key to be used when operating in GUI
mode. The key1 value can be Ctrl, Shift, Alt, Insert, Delete, Backspace, F1–F12,
A–Z, a–z, or 0–9.
ACC2=key2
This attribute specifies an accelerator key to be used when operating in GUI
mode. The key2 value can be be Ctrl, Shift, Alt, Insert, Delete, Backspace,
F1–F12, A–Z, a–z, or 0–9.
ACC3=key3
This attribute specifies an accelerator key to be used when operating in GUI
mode. The key3 value can be Ctrl, Shift, Alt, Insert, Delete, Backspace, F1–F12,
A–Z, a–z, or 0–9.

Chapter 13. Tag Reference 413

PDC
pull-down-description-text
This is the text for the pull-down choice. The maximum length of the text is 64
bytes.

Each pull-down-description-text is prefixed with a sequential number beginning

with 1 to allow selection by number.

Description
The PDC tag defines a pull-down choice for an action bar pull-down. If you do not
code any PDC tags within an ABC tag, that action bar choice will not appear on
the action bar.

To provide for a pull-down selection, an input field is generated prior to the first
pull-down-description-text that allows entry of the number of the selected pull-down
choice. Since field names are being generated, the application developer should not
use field names beginning with Z.

Up to three accelerator keys may be specified. ISPDTLC checks for valid

combinations of ACCn attributes. Invalid combinations are reset to blank and a
warning message is issued.
v Insert, Delete, Backspace, and Fn are valid single keys.
v Only one ACCn can be a function key.
v SHIFT plus A–Z, a–z, or 0–9 is not valid.
v When three keys are specified, two must be CTRL, ALT, or SHIFT.
v When two keys are specified, one must be CTRL, ALT, or SHIFT.
v No two keys can have the same value.
v The combined length of the key values including any connecting “+” characters
must be 30 bytes or less.
v An accelerator key combination can be used only one time on a panel.

Conditions
v You must code the PDC tag within an ABC definition. See “ABC (Action Bar
Choice)” on page 204 for a complete description of this tag.
v The maximum number of pull-down choices that will be generated is 60.
However, the depth specified on the enclosing PANEL tag can further reduce
this maximum number.

Nested Tags
You can code the following tag within a PDC definition:

Tag Name Usage Page Required

ACTION Action Multiple 207 No
COMMENT Comment Multiple 272 No
M Mnemonic Single 374 No
SOURCE Source Multiple 449 No

Example
The following application panel markup produces the action bar and pull-down
shown in Figure 145 on page 416.

In this example, when the action bar choice Search is chosen, the variable whchsrch
is tested to see if one of the pull-down choices should be preselected. If whchsrch=1

414 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PDC
then the pull-down choice Search on name is preselected with a 1 in the
pull-down selection entry field. If whchsrch=2 then the pull-down choice Search on
card number is preselected with a 2 in the pull-down selection entry field. If
whchsrch is not equal to 1 or 2, then neither pull-down choice is preselected. The
example shows the Search on name choice preselected. If srch2=1, then the
UNAVAIL attribute on the pull-down choice Search on card number would cause
that choice to be unavailable. The example shows the result.
<!DOCTYPE DM SYSTEM(
<!entity sampvar1 system>
<!entity sampbody system>)>
&sampvar1;

<PANEL NAME=pdc2 KEYLIST=keylxmp>Library Card Registration

<AB>
<ABC>File
<PDC>Add Entry
<ACTION RUN=add>
<PDC>Delete Entry
<ACTION RUN=delete>
<PDC>Update Entry
<ACTION RUN=update>
<PDC>Exit
<ACTION RUN=exit>
<ABC>Search
<PDC CHECKVAR=whchsrch MATCH=1 UNAVAIL=srch1>
ACC1=ctrl ACC2=alt ACC3=n>Search on name
<ACTION SETVAR=whchsrch VALUE=1>
<ACTION RUN=search>
<PDC CHECKVAR=whchsrch MATCH=2 UNAVAIL=srch2
ACC1=ctrl ACC2=alt ACC3=c>Search on card number
<ACTION SETVAR=whchsrch VALUE=2>
<ACTION RUN=search>
<ABC>Help
<PDC>Extended Help...
<ACTION RUN=exhelp>
<PDC>Keys Help...
<ACTION RUN=keyshelp>
</AB>
&sampbody;
</PANEL>

Chapter 13. Tag Reference 415

PDSEP

File Search Help

------┌──────────────────────────────┐-----------------------------------
│ 1 1. Search on name │gistration
│ *. Search on card number │
└──────────────────────────────┘
Type in client's name and case number (if applicable).

Then, select an action bar choice.

Date . . . : 11/09/89
Card No . . _______ (A 7-digit number)
Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Choose one of the following Check valid branches

__ 1. New _ North Branch
2. Renewal _ South Branch
3. Replacement _ East Branch
_ West Branch
Enter a command ===> ______________________________________________________
F1=Help F2=Split F3=Exit F6=KEYSHELP F9=Swap
F12=Cancel

Figure 145. Pull-Down Choices

PDSEP (Pull-Down Separator)

The PDSEP tag defines a horizontal divider line on an action bar pull-down menu.

ÊÊ <PDSEP> ÊÍ
</PDSEP>

Description
The PDSEP tag defines a horizontal divider line on an action bar pull-down menu.
You use the horizontal divider to separate groups of related pull-down choices.

Conditions
v The PDSEP tag can only be coded between PDC tags. All PDSEP tags found
before the first PDC tag or after the last PDC tag are discarded.
v Only one PDSEP tag should be coded between PDC tags. If multiple PDSEP tags
are found between PDC tags, the first one is accepted and the others are
discarded.
v The PDSEP tag automatically closes an open PDC tag and all nested tags
following the PDC tag.

Nested Tags
None.

Example
The following example shows how the PDSEP tag is used to draw a separator line
in a pull-down menu. Figure 146 on page 417 shows the formatted result.
<!DOCTYPE DM SYSTEM(
<!entity sampvar1 sysem>
<!entity sampbody system>)>
&sampvar1;

416 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PDSEP
<PANEL NAME=pdsep KEYLIST=keylxmp>Library Card Registration
<AB>
<ABC>File
<PDC>Add Entry
<ACTION RUN=add>
<PDC>Delete Entry
<ACTION RUN=delete>
<PDC>Update Entry
<ACTION RUN=update>
<PDSEP>
<PDC>Exit
<ACTION RUN=exit>
BC>Search
<PDC CHECKVAR=whchsrch MATCH=1 UNAVAIL=srch1
acc1=ctrl acc2=alt acc3=n >Search on name
<ACTION SETVAR=whchsrch VALUE=1>
<ACTION RUN=search>
<PDC CHECKVAR=whchsrch MATCH=2 UNAVAIL=srch2
acc1=ctrl acc2=alt acc3=c>Search on card number
<ACTION SETVAR=whchsrch VALUE=2>
<ACTION RUN=search>
<ABC>Help
<PDC>Extended Help...
<ACTION RUN=exhelp>
<PDC>Keys Help...
<ACTION RUN=keyshelp>
</AB>
&sampbody;
</PANEL>

Figure 146. Pull-Down Separator

Chapter 13. Tag Reference 417

PNLINST

PNLINST (Panel Instruction)

The PNLINST tag defines panel instructions for an application panel.

ÊÊ <PNLINST > ÊÍ
COMPACT instruction-text </PNLINST>

COMPACT
This attribute causes the panel instruction to format without a blank line before
the text.
instruction-text
This is the text of the panel instruction. The instruction-text must fit in the
remaining panel depth.

Description
The PNLINST tag defines panel instructions for an application panel. The
instruction-text formats as a paragraph based on the width of the application panel,
area, or region. You can code multiple paragraphs of instruction text by using a
new panel instruction tag for each new paragraph.

If the COMPACT attribute is not specified, the conversion utility inserts a blank
line before the panel instruction text.

Conditions
v You must code the PNLINST within a PANEL, AREA, or REGION definition.

Nested Tags
You can code the following tags within a PNLINST definition:

Tag Name Usage Page Required

HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No

Example
The following application panel markup contains one panel instruction. Figure 147
shows the formatted result.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=selcls TYPE='char 2'>

<VARLIST>
<VARDCL NAME=loc VARCLASS=selcls>
<VARDCL NAME=mode VARCLASS=selcls>
</VARLIST>

<PANEL NAME=pnlinst HELP=trvlhlp WIDTH=60 DEPTH=22 KEYLIST=keylxmp>

Dream Vacation Guide
<AB>
<ABC>File
<PDC>Add Entry
<ACTION RUN=add>
<PDC>Delete Entry
<ACTION RUN=delete>

418 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PNLINST
<PDC>Update Entry
<ACTION RUN=update>
<PDC>Exit
<ACTION RUN=exit>
<ABC>Help
<PDC>Extended Help...
<ACTION RUN=exhelp>
<PDC>Keys Help...
<ACTION RUN=keyshelp>
</AB>
<AREA>
<PNLINST>Choose one of the following exotic locations and
your preferred mode of travel, then press Enter.
<DIVIDER>
<REGION DIR=horiz>
<SELFLD NAME=loc PMTWIDTH=23 SELWIDTH=25>Exotic Location:
<CHOICE>Athens, GA
<CHOICE>Berlin, CT
<CHOICE>Cairo, IL
<CHOICE>Lizard Lick, NC
<CHOICE>Paris, TX
<CHOICE>Rome, NY
<CHOICE>Venice, FL
</SELFLD>
<DIVIDER>
<SELFLD NAME=mode PMTWIDTH=25 SELWIDTH=25>Travel Mode:
<CHOICE>Boxcar
<CHOICE>Hitchhike
<CHOICE>Mule
</SELFLD>
</REGION>
</AREA>
<CMDAREA>
</PANEL>

Dream Vacation Guide

Command ===> ____________________________________________

Choose one of the following exotic locations and your

preferred mode of travel, then press Enter.

Exotic Location: Travel Mode:

__ 1. Athens, GA __ 1. Boxcar
2. Berlin, CT 2. Hitchhike
3. Cairo, IL 3. Mule
4. Lizard Lick, NC
5. Paris, TX
6. Rome, NY
7. Venice, FL

Figure 147. Panel Instructions

PS (Point-and-Shoot)
The PS tag defines a text string that is to be enabled for point-and-shoot.

Chapter 13. Tag Reference 419

PS
ÊÊ <PS VAR= point-and-shoot-variable-name Ê
%varname

Ê VALUE= point-and-shoot-value Ê
%varname NO
* CSRGRP= YES
n

Ê Ê
DEPTH= n IMAPNAME= image-name IMAP group
%varname %varname

Ê > point-and-shoot-text </PS> ÊÍ

IMAP group

IMAPNAMEP= image-namep ABOVE

%varname PLACE= BELOW
LEFT
RIGHT
%varname

VAR=point-and-shoot-variable-name | %varname
This attribute provides the name of a variable which is to be set when a
point-and-shoot phrase is clicked on for selection. You can define this attribute
as a variable name preceded by a “%”.

The point-and-shoot-variable-name must follow the standard naming convention

described in “Rules for Variable Names” on page 201.
VALUE=point-and-shoot-value | %varname | *

This attribute provides the value to be placed in the field specified by the VAR
attribute. You can define this attribute as a variable name preceded by a “%”.
To specify a blank value, the "' '" (quotation mark, apostrophe, blank,
apostrophe, quotation mark) coding notation should be used.

When the PS tag is used with the CHOICE tag, VALUE=* can be used to
automatically use the current choice number (or SELCHAR value) as the
point-and-shoot selection value.
CSRGRP=NO | YES | n
When CSRGRP=YES, the conversion utility generates a cursor group number
to be used for this point-and-shoot text field. When CSRGRP=n, the number
provided is used for this field.
DEPTH=n | %varname
This attribute defines the depth reserved for the point-and-shoot field. When
the panel is displayed in GUI mode, the resulting push button is displayed
with the specified DEPTH. You use this attribute in combination with the
IMAPNAME attribute to provide space for the image. The minimum value is 1
and the maximum value is the remaining panel depth.

420 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PS
IMAPNAME=image-name | %varname
This attribute specifies the name of a image to be placed on the
point-and-shoot push button when it is displayed in GUI mode. The
image-name is not used when the panel is displayed in host mode.

The image-name must follow the standard naming convention described in

“Rules for Variable Names” on page 201.
IMAPNAMEP=image-namep | %varname
This attribute specifies the name of a image to be placed on the
point-and-shoot push button after it has been pushed when it is displayed
in GUI mode. The image-namep is not used when the panel is displayed in
host mode.

The image-namep must follow the standard naming convention described in

“Rules for Variable Names” on page 201.
PLACE=ABOVE | BELOW | LEFT | RIGHT | %varname
This attribute specifies the position of the image relative to the text within
the point-and-shoot push button.
point-and-shoot-text
This is the text of a point-and-shoot entry.

Description
The PS tag is valid as part of the text following:
INFO TAGS
ATTENTION, CAUTION, DD, DDHD, DT, DTHD, FIG, FIGCAP, H2, H3,
H4, LI, LINES, LP, NOTE, NT, P, PD, PT, WARNING, and XMP.
PANEL TAGS
BOTINST, CHOFLD, CHOICE, DTAFLD, DTAFLDD, GRPHDR, LSTCOL,
LSTGRP, PNLINST, SELFLD, and TOPINST.

The point-and-shoot-text is color emphasized within the text of the panel. When
running in GUI mode, the point-and-shoot-text displays as a push button. For host
displays, the user places the cursor on the point-and-shoot-text and presses ENTER
to select the option.

Conditions
v The PS tag requires an end tag.
v When a “%varname” notation is found on any of the attributes that allow a
variable name, the “%varname” entry must follow the standard naming
convention described in “Rules for “%variable” Names” on page 201.

Nested tags
None.

Example
The following example is provided to show the use of point-and-shoot selection for
a sample option menu. Figure 148 on page 422 shows the formatted result.
<!doctype dm system ()>
<!-- Sample selection menu with point-and-shoot -->
<panel name=ps1 menu keylist=keylxmp>Sample Point-and-Shoot
<topinst>This is a selection panel.
<selfld type=menu pmtloc=before

Chapter 13. Tag Reference 421

PS
selwidth=40 pmtwidth=10>Select an option
<choice checkvar=xtest1 match=a>
<PS VAR=zcmd VALUE=1>Selection #1 (Command Tstch1)</PS>
<action run=tstch1 parm='1 2 3 4'
passlib newpool suspend>
<choice checkvar=xtest1 match=b>
<PS VAR=zcmd VALUE=2>Selection #2 (Command Tstch2)</PS>
<action run=tstch2 parm=1234>
<choice checkvar=xtest1 match=c>
<PS VAR=zcmd VALUE=3>Selection #3 (Command Tstch3)</PS>
<action run=tstch3 parm=abcd>
<choice checkvar=xtest1 match=d>
<PS VAR=zcmd VALUE=4>Selection #4 (Command Tstch4)</PS>
<action run=tstch4 parm='a b c d'>
</selfld>
<cmdarea>
</panel>

Sample Point–and–Shoot

This is a selection panel.

Select an
option . . 1 Selection #1 (Command Tstch1)
2 Selection #2 (Command Tstch2)
3 Selection #3 (Command Tstch3)
4 Selection #4 (Command Tstch4)

Option ===> _____________________________________________________________

F1=Help F3=Exit F5=Display F6=Keyshelp F10=Actions
F12=Cancel

Figure 148. Point-and-Shoot Fields

PT (Parameter Term)
The PT tag defines a term in a parameter list.

ÊÊ <PT> ÊÍ
parameter-term </PT>

parameter-term
This is the text of the parameter term.

Description
The PT tag defines a parameter term in a parameter list.

Conditions
v You must code the PT tag within a PARML definition. See “PARML (Parameter
List)” on page 408 for a complete description of this tag.

422 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 PT
v Each PT tag must be paired with an associated PD tag. You can specify only one
PT tag for each PD tag within a parameter list. The PT tag must immediately
precede the PD tag it is associated with.

Nested Tags
You can code the following tag within a PT definition:

Tag Name Usage Page Required

HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No

Example
The following help panel markup contains a parameter list with two parameter
terms. Figure 149 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=pt WIDTH=40 DEPTH=18>Help for the Duplex Function

<AREA>
<INFO>
<P>The two options associated with
the DUPLEX function are:
<PARML TSIZE=5>
<PT>DCopies
<PD>Which prints one-sided copies that
are prepared for future duplex copying.
<PT>DPrint
<PD>Which prints two-sided copies.
</PARML>
</INFO>
</AREA>
</HELP>

Help for the Duplex Function

The two options associated with the

DUPLEX function are:

DCopies
Which prints one_sided copies
that are prepared for future
duplex copying.

DPrint
Which prints two_sided copies.

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 149. Parameter Terms

Chapter 13. Tag Reference 423

REGION

REGION (Region)
The REGION tag defines the characteristics of a panel section including the
direction in which fields on an application panel are arranged.

ÊÊ <REGION Ê
VERT INDENT=n WIDTH= n
DIR= HORIZ *

Ê Ê
DEPTH= n YES
* OFF ALIGN= NO
EXTEND= ON
FORCE

Ê > Ê
GRPBOX Group DEFAULT group-box-title
LOCATION= TITLE

Ê </REGION> ÊÍ

GRPBOX Group:

NO
GRPBOX= YES
GRPWIDTH=n GRPBXVAR=variable-name 1
GRPBXMAT= string

DIR=VERT | HORIZ
This attribute specifies in which direction the contents of a region is arranged.
The default value is VERT, which formats the contents of the region in a
vertical direction; that is, top to bottom. If you specify the HORIZ value for
DIR, the contents of the region are formatted horizontally; that is, left to right
within the region.
INDENT=n
This attribute defines the number of columns to indent the current region from
the current left region boundary.
WIDTH=n | *
This attribute defines the width of a panel region. If WIDTH is not specified or
WIDTH=*, the default value is the remaining available panel width.
DEPTH=n | *
This attribute defines the size of a scrollable region. When EXTEND=OFF, the
minimum value is 2 and the maximum value is the remaining panel depth.
When EXTEND=ON, the minimum value is 1. If the DEPTH value is specified
as “*”, the conversion utility will reserve the remaining available panel depth
for the scrollable region.

If DEPTH is not specified the region will not be scrollable.

EXTEND=OFF | ON | FORCE
This attribute defines the run-time display size for the scrollable region. If

424 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 REGION
EXTEND=ON is specified, the panel definition is expanded from the
minimum DEPTH to the size of the logical screen. Only one EXTEND=ON
attribute value is allowed on a panel. The first tag (AREA, DA, GA,
REGION, SELFLD) with EXTEND=ON is accepted; the EXTEND attribute
on any subsequent tag is ignored.

If you intend to display the panels in a pop-up window, it is recommended

that you code EXTEND=OFF.

If the EXTEND attribute is specified without the DEPTH attribute, a

warning message is issued and the EXTEND attribute is ignored.

If EXTEND=FORCE is specified within a horizontal area or region, the

EXTEND(ON) keyword is added to the scrollable area attribute statement
in the )ATTR panel section. The conversion utility issues a message to
advise of a potential display error if other panel fields are formatted on or
after the last defined line of the scrollable area.
ALIGN=YES | NO
This attribute controls the horizontal alignment of the first fields in horizontal
regions. The default is to align the fields to facilitate cursor movement by
tabbing. This attribute is valid only when DIR=HORIZ.
GRPBOX=NO | YES
This attribute is used to specify a group box. The default value is NO. The
group box outline is visible only when running ISPF in GUI mode.

When GRPBOX=YES is specified on the same REGION tag that defines a

scrollable region, the group box title is formatted as the first line within the
)AREA panel section.
GRPWIDTH=n
This attribute is used to specify the width of the group box. The default
and maximum group box width is the region width.

GRPWIDTH can be used to specify a group box width smaller than the
default value. As an example, when the region consists only of a SELFLD
tag that is formatted into multiple columns for host display, but is
specified as a list box or drop-down list, the GUI mode display appears as
a single column. The right border of the group box would normally extend
beyond the space required for the GUI display. The GRPWIDTH attribute
can be used to limit the group box to the width of the list box or
drop-down list.
GRPBXVAR=variable-name
This attribute defines a variable whose value indicates whether or not the
group box outline is added when the panel is displayed in GUI mode. If
the variable is equal to the value specified by the GRPBXMAT attribute,
the group box outline is added.

The GRPBXVAR attribute value must be specified without a leading %

sign. The variable-name must follow the standard naming convention
described in “Rules for Variable Names” on page 201.
GRPBXMAT=1 | string
This attribute defines the value for the GRPBXVAR variable that indicates
the group box outline is to be added to the panel in GUI mode. The string
can be any character string. GRPBXMAT=1 is the default.

Chapter 13. Tag Reference 425

REGION
LOCATION=DEFAULT | TITLE
This attribute is used to build a panel ‘title’ which requires data fields in
specific column positions. A single line may be formatted to be placed in the
panel title position by enclosing the appropriate tags within a horizontal region
specifying LOCATION=TITLE. The resulting line displays with the colors
associated with the tags used to format the line. This attribute is valid only
when DIR=HORIZ.
group-box-title
This is the title for the group box. The group-box-title should be supplied only
when GRPBOX=YES. In other cases a warning message will be issued.

Description
The REGION tag defines the characteristics of a panel section. You can code
multiple regions within an application panel.

Nonscrollable horizontal regions are normally aligned left-to-right using the first
input field from each region. If a panel consists of both scrollable and nonscrollable
regions formatted horizontally, scrollable regions will normally be aligned with the
first input fields of nonscrollable regions.

Regions containing data formatted from INFO tags or from the GRPHDR tag will
normally start with a blank line when formatted in the )BODY panel section. The
blank line is omitted when these tags are formatted at the beginning of a scrollable
area.

If you specify the CMDAREA tag within your DTL source file, it must appear
before the REGION tag when DEPTH=* is specified. The REGION tag DEPTH may
have to be adjusted to allow for additional lines which result from tags present
within the panel definition following the end REGION tag.

Conditions
v The REGION tag requires an end tag.
v You must code the REGION tag within an AREA or PANEL definition. See
“AREA (Area)” on page 213 and “PANEL (Panel)” on page 397 for descriptions
of these tags.
v You can also nest regions within other regions.
v You can code only one LSTFLD tag within a REGION definition.

Compatibility Considerations

In Version 3, the conversion utility did not format nested horizontal

regions. In this release, nested horizontal formatting is supported.

Nested Tags
You can code the following tags within a REGION definition:

Tag Name Usage Page Required

COMMENT Comment Multiple 272 No
DA Dynamic area Multiple 277 No
DIVIDER Area divider Multiple 285 No

426 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 REGION
Tag Name Usage Page Required
DTACOL Data column Multiple 293 No
DTAFLD Data field Multiple 299 No
GA Graphic area Single 316 No
GRPHDR Group header Multiple 320 No
INFO Information region Multiple 339 No
LSTFLD List field Single 364 No
PNLINST Panel Instruction Multiple 418 No
REGION Region Multiple 364 No
SELFLD Selection field Multiple 433 No

Help Panel
You can code the following tags within a REGION definition on a help panel:

Tag Name Usage Page Required

DIVIDER Area divider Multiple 285 No
INFO Information region Multiple 339 No
REGION Region Multiple 424 No

Example
The following application panel markup contains both horizontal and vertical
regions. The first two horizontal regions arrange the fields coded within them in a
horizontal format. The third horizontal region arranges the selection field and the
contents of the vertical region nested within it in a horizontal format. In this
example, the INDENT attribute has been used to indent all fields formatted within
a region 2 positions under the previous text. The ALIGN attribute has adjusted the
default placement of fields in the last vertical region. Figure 150 on page 429 shows
the formatted result.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=chr25 TYPE='char 25'>

<VARCLASS NAME=chr12 TYPE='char 12'>
<VARCLASS NAME=chr10 TYPE='char 10'>
<VARCLASS NAME=chr9 TYPE='char 9'>
<VARCLASS NAME=chr8 TYPE='char 8'>
<VARCLASS NAME=chr2 TYPE='char 2'>

<VARLIST>
<VARDCL NAME=name VARCLASS=chr25>
<VARDCL NAME=date VARCLASS=chr8>
<VARDCL NAME=addr VARCLASS=chr25>
<VARDCL NAME=city VARCLASS=chr10>
<VARDCL NAME=state VARCLASS=chr9>
<VARDCL NAME=zip VARCLASS=chr12>
<VARDCL NAME=level VARCLASS=chr2>
<VARDCL NAME=graddate VARCLASS=chr2>
<VARDCL NAME=major VARCLASS=chr10>
</VARLIST>

<PANEL NAME=region1 keylist=keylxmp>Application Form

<TOPINST>Complete all of the fields below, then press Enter.
<AREA>
<REGION INDENT=2>

Chapter 13. Tag Reference 427

REGION
<REGION DIR=horiz>
<DTACOL PMTWIDTH=10>
<DTAFLD DATAVAR=name ENTWIDTH=25>Name
<DTAFLD DATAVAR=date ENTWIDTH=8 DESWIDTH=10>Date
<DTAFLDD>(mm/dd/yy)
</DTACOL>
</REGION>
<DTAFLD DATAVAR=addr ENTWIDTH=25 PMTWIDTH=10>Address
<REGION DIR=horiz>
<DTAFLD DATAVAR=city PMTWIDTH=10 ENTWIDTH=25>City
<DTAFLD DATAVAR=state PMTWIDTH=9 ENTWIDTH=2>State
<DTAFLD DATAVAR=zip PMTWIDTH=12 ENTWIDTH=5>Zip code
</REGION>
</REGION>
<DIVIDER TYPE=solid GUTTER=3>
<REGION DIR=horiz INDENT=2 ALIGN=no>
<SELFLD NAME=level SELWIDTH=35 PMTWIDTH=25>Highest education level:
<CHOICE>Some high school
<CHOICE>High school graduate
<CHOICE>Some college
<CHOICE>College graduate
<CHOICE>Some post-graduate work
<CHOICE>Post-graduate degree
</SELFLD>
<DIVIDER TYPE=solid>
<REGION>
<GRPHDR FORMAT=none COMPACT STRIP>
For applicants who are
high school or college
graduates:
<REGION INDENT=2>
<DTACOL PMTWIDTH=20>
<DTAFLD DATAVAR=graddate ENTWIDTH=2>Year of graduation
<DTAFLD DATAVAR=major ENTWIDTH=10>Field of study
</DTACOL>
</REGION>
</REGION>
</REGION>
</AREA>
<CMDAREA>Enter a command
</PANEL>

428 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 REGION

Application Form

Complete all of the fields below, then press Enter.

Name . . . _________________________ Date . . . ________ (mm/dd/yy)

Address _________________________
City . . . _________________________ State . . __ Zip code . . _____

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

Highest education level: | For applicants who are

__ 1. Some high school | high school or college
2. High school graduate | graduates:
3. Some college | Year of graduation __
4. College graduate | Field of study . . . __________
5. Some post–graduate work |
6. Post–graduate degree |

Enter a command ===> ____________________________________________________

F1=Help F3=Exit F5=Display F6=Keyshelp F10=Actions
F12=Cancel

Figure 150. Regions

The following example illustrates the use of the WIDTH and DEPTH attributes.
The first vertical region width reserves the space required for the second vertical
region, which is also scrollable. Figure 151 on page 430 shows the formatted result.
<!DOCTYPE DM SYSTEM(
<!entity sampvar2 sysem>
<!entity sampabc system>)>
&sampvar2;

<PANEL NAME=region3 KEYLIST=keylxmp>File-A-Case

<AB>
&sampabc;
</AB>
<CMDAREA>Enter a command
<TOPINST COMPACT>
Type in client's name and case number (if applicable).
<TOPINST>Then select an action bar choice.
<REGION DIR=horiz>
<REGION WIDTH=50>
<DTAFLD DATAVAR=caseno PMTWIDTH=12 ENTWIDTH=7 DESWIDTH=21>Case No
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=8>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address PMTWIDTH=12 ENTWIDTH=25>Address
<DIVIDER>
<SELFLD NAME=casesel PMTWIDTH=11 PMTLOC=before SELWIDTH=38>Choose
one of the following
<CHOICE CHECKVAR=case MATCH=civ>Civil
<CHOICE CHECKVAR=case MATCH=estate>Real Estate
<CHOICE CHECKVAR=case MATCH=environ>Environmental
</SELFLD>
</REGION>
<REGION DEPTH=10>
<SELFLD TYPE=multi PMTWIDTH=24 SELWIDTH=26>
Check type of offense
<CHOICE NAME=patin HELP=patin CHECKVAR=val>Patent Infringement
<CHOICE NAME=defa HELP=defame CHECKVAR=def>Defamation
<CHOICE NAME=cont HELP=cont CHECKVAR=con>Breach of Valid Contract
<CHOICE NAME=priv HELP=priv CHECKVAR=pri>Invasion of Privacy
<CHOICE NAME=incr HELP=incr CHECKVAR=icr>Interference with
Contractual Relations
<CHOICE NAME=disp HELP=disp CHECKVAR=dis>Improper Disposal of

Chapter 13. Tag Reference 429

REGION
Medical By-Products
<CHOICE NAME=fraud HELP=fraud CHECKVAR=fra>Fraud
</SELFLD>
</REGION>
</REGION>
</PANEL>

File Search Help

-------------------------------------------------------------------------
File–A–Case

Type in client's name and case number (if applicable).

Then select an action bar choice.
#SAREA37 #
Case No . . _______ (A 7–digit number) # #
Name . . . . _________________________ (Last, # #
First, # #
M.I.) # #
Address . . _________________________ # #
# #
Choose one # #
of the # #
following __ 1. Civil # #
2. Real Estate
3. Environmental

Enter a command ===> ____________________________________________________

F1=Help F3=Exit F5=Display F6=Keyshelp F10=Actions
F12=Cancel

The contents of the scrollable area are as follows:

)AREA SAREA37

Check type of offense

_ Patent Infringement
_ Defamation
_ Breach of Valid
Contract
_ Invasion of Privacy
_ Interference with
Contractual Relations
_ Improper Disposal of
Medical By–Products
_ Fraud

)AREA SAREA37

Figure 151. Using WIDTH and DEPTH Attributes

RP (Reference Phrase)
The RP tag specifies a word or phrase within panel text that has additional help
information associated with it.

ÊÊ <RP HELP= help-panel-name > reference-phrase </RP> ÊÍ

*help-message-id
%varname
*%varname

430 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 RP
| HELP= help-panel-name | *help-message-id | %varname | *%varname
| This attribute specifies the name of a panel that displays when the user
| requests help for the reference-phrase.

| You can specify either a help panel or a message identifier. If a message

| identifier is used, it must be prefixed with an asterisk (*).

| The help attribute value can be specified as a variable name. When %varname
| is coded, a panel variable name is created. When *%varname is coded, a
| message variable name is created.

| If the user requests help on a choice and no help is defined, the extended help
| panel is displayed. If an extended help panel is not defined for the panel, the
| application or ISPF tutorial is invoked.

| The help-panel-name must follow the standard naming convention described in

| “Rules for Variable Names” on page 201.

| See “HELP (Help Panel)” on page 323 for information on creating help panels.
| For information about creating messages, see “MSG (Message)” on page 376.
reference-phrase
This is the text of the phrase.

Description
The RP tag specifies a word or phrase within panel text that has additional
information associated with it.

The RP tag is valid as part of the text following:

INFO tags
ATTENTION, CAUTION, DD, DDHD, DT, DTHD, FIG, FIGCAP, H2, H3,
H4, LI, LINES, LP, NOTE, NT, P, PD, PT, WARNING, and XMP.
PANEL tags
BOTINST, CHOFLD, CHOICE, DTAFLD, DTAFLDD, GRPHDR, LSTCOL,
LSTGRP, PNLINST, SELFLD, and TOPINST.

The reference-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.

Each reference phrase is related to additional help panels in a manner similar to

field-level help. The panel that appears when you request help from a reference
phrase can also contain reference phrases.

Each reference-phrase results in one or more entries in the )HELP panel section.
Multiple entries are required for phrases that span lines; a separate entry is created
for each panel line used by the reference-phrase.

Conditions
v The RP tag requires an end tag.

Nested Tags
None.

Chapter 13. Tag Reference 431

RP
Example
The following help panel markup contains a reference phrase definition for the
phrase, “lifetime warranty”. Figure 152 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=rp>HELP for Appliances

<AREA>
<INFO>
<p>In addition to our free delivery and installation program, we also
offer an exclusive <rp help=warrtyh>lifetime warranty</rp> on all
of our appliances.
</INFO>
</AREA>
</HELP>

<help name=warrtyh>Help for Lifetime Warranty

<AREA>
<INFO>
<p>Lifetime warranty covers the replacement of any part that breaks
or becomes non-functional while this product is used by the original
owner.
</INFO>
</AREA>
</HELP>

Help for Appliances

In addition to our free delivery and

installation program, we also offer an exclusive
lifetime warranty on all of our appliances.

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 152. Reference Phrase Example

Accordingly, when the user selects the reference phrase lifetime warranty, the help
panel specified by the HELP attribute (help=warrtyh) is displayed. Figure 153
shows the formatted result.

Help for Lifetime Warranty

Lifetime warranty covers the replacement of any

part that breaks or becomes non-functional while
this product is used by the original owner.

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 153. Reference Phrase Example

432 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 SELFLD

SELFLD (Selection Field)

The SELFLD tag defines a field that includes a list of choices.

ÊÊ <SELFLD Ê
NAME=field-name NO
HELP= YES
help-panel-name
*help-message-id
%varname
*%varname

Ê Ê
SINGLE ABOVE PMTWIDTH= n
TYPE= MULTI PMTLOC= BEFORE *
MENU **
MODEL
TUTOR

Ê Ê
SELWIDTH= n 2
* ENTWIDTH= n
’e1 e2...en’

Ê Ê
NO 1
REQUIRED= YES FCHOICE= 0
YES MSG=message-identifier

Ê Ê
YES DEPTH= n
AUTOTAB= NO * OFF
EXTEND= ON
FORCE

Ê Ê
TRAIL=’trail-var-1 trail-var-2 ... trail-var-n’ 1
CHOICECOLS= n

Ê Ê
CHOICEDEPTH= n CWIDTHS=’w1 w2...wn’ PAD= NULLS
* USER
char
%varname

Ê Ê
PADC= NULLS
USER
char
%varname

Chapter 13. Tag Reference 433

SELFLD
Ê Ê
NONE SELMSG=selfld-msg-identifier
OUTLINE= L
R
O
U
BOX
%varname

Ê Ê
SELMSGU=selfld-msg-unavailable YES
INIT= NO

Ê Ê
YES YES START
VERIFY= NO REFRESH= NO SELFMT= END

Ê Ê
YES YES NO
CHKBOX= NO ZGUI= NO CSRGRP= YES
n

Ê Ê
TSIZE=’s1 s2...sn’

Ê Ê
LISTTYPE= RADIO
LISTBOX LISTREF=list-name LISTDEPTH=n
DDLIST
COMBO

Ê Ê
YES NOSEL=no-selection-value SELDEFAULT=x
DBALIGN= NO
FIELD
FORCE

Ê Ê
NO CUA COLOR= WHITE
PMTSKIP= YES FLDTYPE= ISPF RED
BLUE
GREEN
PINK
YELLOW
TURQ
%varname

434 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 SELFLD
Ê > Ê
HIGH HILITE= USCORE
INTENS= LOW BLINK
NON REVERSE
%varname %varname

Ê </SELFLD> ÊÍ
field-prompt-text

NAME=field-name
This attribute specifies the name for the selection field. The field-name must
follow the standard naming convention described in “Rules for Variable
Names” on page 201.

The NAME field is required if TYPE=SINGLE because the selection field name
is used as the input field for single-choice selection fields. The NAME field is
ignored if TYPE=MULTI.

| The NAME field is optional for TYPE=MENU, TYPE=MODEL, or

| TYPE=TUTOR. If present, it is used in place of the command field name in the
| construction of the option selection statement. However, because the input
| field is the command line, you must provide panel logic using the SOURCE
| tag to ensure that the selection choice is placed in the NAME field.

For single-choice selection fields, the field-name can be used to position the
cursor on the field using the CURSOR attribute of the enclosing PANEL tag or
the CURSOR parameter of the DISPLAY service call. In addition, you can use
the field-name to position a pop-up using the POPLOC parameter of the
ADDPOP service call.
| HELP=NO | YES | help-panel-name | *help-message-id | %varname |
| *%varname
| This attribute specifies the help action taken when the user requests help for a
| selection field. This is field-level help.

| When HELP=YES, control is returned to the application. You can specify either
| a help panel or a message identifier. If a message identifier is used, it must be
| prefixed with an asterisk (*).

| The help attribute value can be specified as a variable name. When %varname
| is coded, a panel variable name is created. When *%varname is coded, a
| message variable name is created.

| If the user requests help on a field and no help is defined, the extended help
| panel is displayed. If an extended help panel is not defined for the panel, the
| application or ISPF tutorial is invoked.

| The help-panel-name must follow the standard naming convention described in

| “Rules for Variable Names” on page 201.

| See “HELP (Help Panel)” on page 323 for information on creating help panels.
| For information about creating messages, see “MSG (Message)” on page 376.

| Note: This attribute is valid only when TYPE=SINGLE.

Chapter 13. Tag Reference 435

 SELFLD
| TYPE=SINGLE | MULTI | MENU | MODEL | TUTOR
| This attribute specifies whether the selection field is single-choice,
| multiple-choice, an ISPF selection menu, an edit model selection menu, or a
| tutorial selection menu.

| Single-choice selection fields allow the user to select only one choice from the
| selection list. Choices in a single-choice selection field appear with sequential
| numbers before each choice. An input field precedes the first choice in the
| selection field.

| Multiple-choice selection fields allow the user to select one or more choices
| from the selection list. Choices in a multiple-choice selection field appear with
| a single character input field before each choice.

| The use of TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR is allowed only

| when the MENU keyword has been specified on the PANEL tag. ISPF selection
| menu, edit model, or tutorial selection menu fields are formatted in a manner
| similar to single-choice selection fields. Choices appear with sequential
| numbers before each choice and the user may select only one choice from the
| selection list. With these options, the command line is used as the entry choice
| field. Because the HELP attribute on the SELFLD tag is not valid when
| TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR, help for selection menu or
| edit model menu choices must be entered on the CMDAREA tag.

| Note: Because the selection menu, edit model menu, or tutorial menu panel
| uses the command line for choice selection, a command area is required.
| The conversion utility will automatically generate a command area if no
| CMDAREA tag is provided.
| PMTLOC=ABOVE | BEFORE
This attribute specifies whether the field-prompt-text appears above or in front
of the selection field.
PMTWIDTH=n | * | **
This attribute specifies the number of bytes to be used by the prompt for the
selection field. When you specify PMTWIDTH=*, the conversion utility uses
the length of the prompt text as the prompt width. When you specify
PMTWIDTH=**, the conversion utility uses the maximum available space as
the prompt width. If any prompt is longer than this value, the prompt is
word-wrapped to fit on multiple lines. The minimum value is 0 and the
maximum is the remaining available panel (or region) value. This value
overrides the PMTWIDTH value on an enclosing DTACOL tag.
SELWIDTH=n | *
This attribute specifies the number of bytes used for the choices in the
selection field. It is useful for defining a consistent appearance for the selection
choices. If you do not specify the SELWIDTH parameter on the SELFLD tag,
the SELWIDTH parameter on any enclosing DTACOL tag is used. If you do
not specify a SELWIDTH value and SELWIDTH is not specified on an
enclosing DTACOL tag, then the remaining available width of the panel (or
current region) determines the width used to format the choice text. If the
SELWIDTH value is specified as “*”, the conversion utility will use the
remaining available width.

If the width required by the choice-description-text and its entry-field exceeds the
value specified for SELWIDTH, the text is word-wrapped to multiple lines.

436 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 SELFLD
Note: Because all of the remaining space is used if no SELWIDTH attribute is
provided or if SELWIDTH=“*” is coded, you should specify a
SELWIDTH value for fields defined:
v With PMTLOC=BEFORE, because PMTWIDTH is not part of the
space reserved by SELWIDTH.
v Within a horizontal region if additional fields are to be formatted to
the right of the SELFLD section.
SELWIDTH for selection fields defined within a horizontal region if
additional fields are to be formatted to the right of the SELFLD section.

The width specified for a single-choice selection field should include all or a
portion of the choice-description-text plus 8-13 positions, determined as follows:
v The choice selection entry-field (1-3 characters)
v The entry-field 3270 attributes (2 characters)
v The choice-number inserted by the conversion utility (3-5 characters)
v The 3270 attributes that enclose the choice-description-text (2 characters).

The width of a multiple-choice selection field should include all or a portion of

the choice-description-text plus 5 positions, determined as follows:
v The choice selection entry-fields (1 character)
v The entry-field 3270 attributes (2 characters)
v The 3270 attributes that enclose the choice-description-text (2 characters).

| The width specified for a menu-choice, model-choice, or tutorial-choice

| selection field should include all or a portion of the choice-description-text plus
| 4-19 positions, determined as follows:
| v The choice selection entry-field (1-16 characters)
| v The entry-field 3270 attribute (1 character)
| v The 3270 attributes that enclose the choice-description-text (2 characters).
| ENTWIDTH=2 | n | ’e1 e2...en’
| This attribute is valid only when TYPE=SINGLE, TYPE=MENU,
| TYPE=MODEL, or TYPE=TUTOR.

| Multiple ENTWIDTH values can be used when TYPE=MENU, TYPE=MODEL,

| or TYPE=TUTOR. For these types of selection lists, the ENTWIDTH is used
| only to format the amount of space used by the selection character(s). The
| multiple width format is used when CHOICECOLS is greater than 1 to
| customize the width required for each column of choices. If the number of
| ENTWIDTH values is less than the number of columns, the last (or only)
| ENTWIDTH value is used for the remaining columns. If more ENTWIDTH
| values are supplied than there are columns of choices, the excess ENTWIDTH
| values are ignored.

| When TYPE=SINGLE and the value of LISTTYPE is not COMBO, ENTWIDTH

| specifies the number of bytes used for both the entry field and the space
| between the selection identifier and the selection text. The default width value
| is 2. The minimum width value is 1, which can be specified for any
| single-choice selection list. The maximum width value (when LISTTYPE is not
| COMBO) is 3, which can be specified for selection lists within a scrollable
| panel area. The width of 3 is provided for use when the number of CHOICE
| tags will exceed 99.

| When LISTTYPE=COMBO, the maximum ENTWIDTH value is 2 bytes less

| than the SELWIDTH value.

Chapter 13. Tag Reference 437

 SELFLD
| Note: A width of 1 should only be used when the total number of CHOICE
| tags is less than 10. The conversion utility discards choices which cannot
| be selected with the specified entry width.

| When TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR, the command area is

| used as the input field and the ENTWIDTH value is used only to determine
| the spacing between the selection identifier and the selection text. The
| maximum ENTWIDTH value for these types is 16.
REQUIRED=NO | YES
This attribute indicates if the field requires input.

If REQUIRED=YES is coded, a VER(variable,NONBLANK) statement will be

built by ISPDTLC and placed in the )PROC section of the generated ISPF
panel.

Note: This attribute is valid only when TYPE=SINGLE.

MSG=message-identifier
This attribute specifies the message that is displayed when the user does
not choose a selection (defined with the REQUIRED attribute). If you do
not specify a message-identifier, ISPF displays a default message.

If you specify the MSG attribute and REQUIRED=YES, a

VER(variable,NONBLANK,MSG=message-identifier) statement is built by
ISPDTLC and placed in the )PROC section of the generated ISPF panel. If
you specify the MSG attribute and REQUIRED=NO (the default), the
conversion utility issues a warning message.
FCHOICE=1 | 0
| The FCHOICE attribute controls the starting choice number for TYPE=SINGLE,
| TYPE=MENU, TYPE=MODEL or TYPE=TUTOR. When FCHOICE=0, the first
| choice is the number 0.

| Note: This attribute is valid only when TYPE=SINGLE, TYPE=MENU,

| TYPE=MODEL, or TYPE=TUTOR.
| AUTOTAB=YES | NO
When AUTOTAB=YES, the cursor moves to the next field capable of input
when the user enters the last character in this field. If no other field capable of
user input exists on the panel, the cursor returns to the beginning of this field.

The ISPF SKIP keyword is not supported when running in GUI mode.

Note: This attribute is valid only when TYPE=SINGLE.

DEPTH=n | *
This attribute defines the minimum size of a scrollable selection list. If DEPTH
is not specified, the selection list will not be scrollable. If the DEPTH value is
specified as “*”, the conversion utility will reserve the remaining available
panel depth. When EXTEND=OFF, the minimum depth is 2. When
EXTEND=ON, the minimum depth is 1. The DEPTH attribute is ignored when
LISTTYPE=COMBO.
EXTEND=OFF | ON | FORCE
This attribute defines the run-time display size for the scrollable list area. If
EXTEND=ON is specified, the panel definition is expanded from the
minimum DEPTH to the size of the logical screen. Only one EXTEND=ON

438 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 SELFLD
attribute value is allowed on a panel. The first tag (AREA, DA, GA,
REGION, SELFLD) with EXTEND=ON is accepted; the EXTEND attribute
on any subsequent tag is ignored.

If the EXTEND attribute is specified without the DEPTH attribute, a

warning message is issued and the EXTEND attribute is ignored. The
EXTEND attribute is ignored when LISTTYPE=COMBO.

If you intend to display the panels in a pop-up window, it is recommended

that you code EXTEND=OFF.

If EXTEND=FORCE is specified within a horizontal area or region, the

EXTEND(ON) keyword is added to the scrollable area attribute statement
in the )ATTR panel section. The conversion utility issues a message to
advise of a potential display error if other panel fields are formatted on or
after the last defined line of the scrollable area.
TRAIL=’trail-var-1 trail-var-2 ... trail-var-n’
This attribute specifies variable name(s) that the application uses to obtain the
TRAIL information created by menu or model selection processing.

Each trail variable specified must follow the standard naming convention
| described in “Rules for Variable Names” on page 201.

| Note: This attribute is valid only when TYPE=MENU, TYPE=MODEL, or

| TYPE=TUTOR.
| CHOICECOLS=1 | n
This attribute specifies the number of columns to format with the CHOICE
items. The default is 1. The CHOICECOLS attribute is ignored when
LISTTYPE=COMBO.
CHOICEDEPTH=n | *
This attribute specifies the number of CHOICE entries to be placed in each
column. The minimum CHOICEDEPTH value is 1. The normal maximum and
default is the remaining panel depth. If the DEPTH attribute has been specified
on the SELFLD tag, or an enclosing REGION or AREA tag, (and the
corresponding tag attribute value for EXTEND is OFF) the most recently
specified depth value is used as the maximum and default value. You may
specify CHOICEDEPTH=“*” which tells the conversion utility to calculate the
column depth based on the total number of CHOICE tags and the number of
columns specified by the CHOICECOLS attribute.

If more CHOICE entries are specified than can be formatted in the available
number of columns specified by the CHOICECOLS attribute, the remaining
CHOICE entries are placed in the rightmost (or only) available column for the
current SELFLD tag. The CHOICEDEPTH attribute is ignored when
LISTTYPE=COMBO.
CWIDTHS=‘w1 w2...wn’
This attribute specifies the number of bytes to be allocated for each column of
CHOICE entries. The ‘w1 w2...wn’ notation provides the number of bytes for
each column. You may use an asterisk or a number combined with an asterisk
to specify a proportional allocation of column space. For example, the
specification of ‘2* * 3*’ for 3 columns would result in a space calculation based
on 6 units, with 2 units allocated to column 1, 1 unit allocated to column 2,
and 3 units allocated to column 3. If more columns have been specified by
CHOICECOLS than are accounted for by CWIDTHS, the remaining space is

Chapter 13. Tag Reference 439

 SELFLD
divided evenly between the remaining columns. If CWIDTHS is not specified,
the available formatting space is divided evenly based on the CHOICECOLS
value. The CWIDTHS attribute is ignored when LISTTYPE=COMBO.
PAD=NULLS | USER | char | %varname
This attribute specifies the pad character for initializing the field. You can
define this attribute as a variable name preceded by a “%”.

Note: This attribute is valid only when TYPE=SINGLE.

PADC=NULLS | USER | char | %varname
This attribute specifies the conditional padding character to be used for
initializing the field. You can define this attribute as a variable name preceded
by a “%”.

Note: This attribute is valid only when TYPE=SINGLE.

OUTLINE=NONE | L | R | O | U | BOX | %varname
This attribute provides for displaying lines around the field on a DBCS
terminal. You can define this attribute as a variable name preceded by a “%”.

Note: This attribute is valid only when TYPE=SINGLE.

SELMSG=selfld-msg-identifier
This attribute specifies the message that is displayed when an invalid
single-choice entry is selected.
SELMSGU=selfld-msg-unavailable
This attribute specifies the message that is displayed when an unavailable
single-choice entry is selected.
INIT=YES | NO
This attribute controls the single-choice and multi-choice selection field
variables initialization in the panel )INIT section.
VERIFY=YES | NO
| This attribute controls the single-choice verification and menu-choice,
| model-choice, or tutor-choice selection logic generation in the panel )PROC
| section. When TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR, VERIFY=NO
| bypasses the creation of the ZSEL statement. You can provide a replacement
| ZSEL statement with the <SOURCE> tag.
REFRESH=YES | NO
This attribute controls the creation of the REFRESH statement in the panel
)REINIT section for multi-choice selection lists.
SELFMT=START | END
| This attribute controls the placement of the choice selection character(s) within
| the width specified by ENTWIDTH. The default is to left justify the choice
| selection character(s).

| Note: This attribute is valid only when TYPE=SINGLE, TYPE=MENU,

| TYPE=MODEL, or TYPE=TUTOR.
| CHKBOX=YES | NO
This attribute controls the creation of panel keywords that enable check boxes
when running ISPF in GUI mode. The default value is YES.

The CHKBOX attribute is not valid and is ignored for single-choice,

menu-choice, and model-choice selection lists.

440 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 SELFLD
If the conversion utility has been invoked with the NOGUI option, specifying
CHKBOX=YES on the SELFLD tag will override the invocation option so that
check-box controls will be generated.
ZGUI=YES | NO
This attribute controls the creation of the ″VGET (ZGUI)″ statement in the
panel )INIT section for multi-choice selection lists that specify the ″&multipmt″
ENTITY as field-prompt-text.
CSRGRP=NO | YES | n
The CSRGRP attribute is valid only when TYPE=MULTI and CHKBOX=YES
(either specified or defaulted). When CSRGRP=YES, the conversion utility
generates a cursor group number to be used for this selection list. When
CSRGRP=n, the number provided is used for the CHOICE fields within this
SELFLD tag.
TSIZE=’s1 s2...sn’
The TSIZE attribute provides the number of bytes to indent multiple lines of
CHOICE text. Multiple TSIZE values can be used to provide unique
indentation amounts for multiple column lists (when CHOICECOLS is greater
than 1). If the number of TSIZE values is less than the number of columns, the
last (or only) TSIZE value is used for the remaining columns. If more TSIZE
values are supplied than there are columns of choices, the extra TSIZE values
are ignored.
LISTTYPE=RADIO | LISTBOX | DDLIST | COMBO
This attribute controls the creation of panel keywords that cause single-choice
selection lists to be displayed with radio buttons, or as a list box, drop-down
list, or combination box when running ISPF in GUI mode.

For multi-choice, menu-choice, and model-choice selection lists, the LISTTYPE

attribute is not valid and is ignored.

When LISTTYPE=COMBO or LISTTYPE=DDLIST and the PANEL tag has

specified TYPE=GUI, a single input field is placed in the panel )BODY section,
and the DEPTH, EXTEND, CHOICECOLS, CHOICEDEPTH, and CWIDTHS
attributes are ignored. The length of the input field is determined by the
ENTWIDTH attribute. For combination boxes, you should consider placing a
list of the valid possible choices in a help panel accessable through field-level
help.
LISTREF=list-name
This attribute is not used for LISTTYPE=RADIO. The list-name specifies the
name for the )LIST section in the generated panel. The list-name must
follow the standard naming convention described in “Rules for Variable
Names” on page 201. If you don’t specify list-name, the default list-name is
the field-name provided by the NAME attribute.

If a panel contains more than one SELFLD tag that has the same set of
CHOICEs, the CHOICE tags can be provided within the first SELFLD tag
definition, and then referenced in subsequent SELFLD tags by specifying
the first SELFLD tag list-name as the LISTREF value of the subsequent
SELFLD tag(s).
LISTDEPTH=n
The LISTDEPTH attribute is not used for LISTTYPE=RADIO. LISTDEPTH
provides the number of panel lines to be used for the list box, drop-down
list, or combination box.

Chapter 13. Tag Reference 441

 SELFLD
When LISTTYPE=LISTBOX and you don’t specify LISTDEPTH, the list box
depth will be defaulted to use the number of panel lines formatted for a
numbered selection list, allowing for the horizontal scroll bar. If
LISTDEPTH is specified, the value should be less than the number of lines
formatted for a numbered selection list to allow for the horizontal scroll
bar.

When LISTTYPE=DDLIST and you don’t specify LISTDEPTH, the

drop-down list depth is determined by ISPF when the panel is displayed.
If LISTDEPTH is specified, the minimum LISTDEPTH value is 1. The
normal maximum value is the remaining panel depth. If the DEPTH
attribute has been specified on the SELFLD tag or on an enclosing
REGION or AREA tag (and the corresponding tag attribute value for
EXTEND is OFF), the most recently specified depth value is the maximum
value.
DBALIGN=YES | NO | FIELD | FORCE
This attribute defines the DBALIGN value. DBALIGN is used only for DBCS
language conversions when PMTLOC=ABOVE and the DBALIGN invocation
option is specified.

When DBALIGN=YES, and the field-prompt-text starts with a DBCS character

or a single-choice or multi-choice selection list definition does not include
field-prompt-text, the entry field for the choice is shifted 1 position to the right.

When DBALIGN=NO, no alignment adjustment is made.

When DBALIGN=FIELD, the entry field is shifted but no adjustment is done

for the prompt. The FORCE and FIELD values are useful when alignment is
required with other SELFLD or DTAFLD tags.

When DBALIGN=FORCE, the entry field is shifted and the field-prompt-text is

also adjusted to match even if the field-prompt-text starts with a single byte
character.
NOSEL=no-selection-value
This attribute provides a value to be placed the CHECKVAR variable (specified
by the CHOICE tag) when no selection is chosen from the available list.

The NOSEL attribute is not valid and is ignored for multi-choice, menu-choice,
and model-choice selection lists.

If REQUIRED=YES is specified, a message is issued and NOSEL is ignored.

If no CHOICE tag specifies a CHECKVAR attribute, the NOSEL attribute is

ignored.
SELDEFAULT=x
| This attribute is used to provide a default choice selection when
| TYPE=SINGLE, MENU, MODEL, or TUTOR. The value x must be a valid
| choice selection. If no selection is made by the user, the default value is
| returned to the application.
PMTSKIP=NO | YES
This attribute is used for horizontal formatting of input fields. When
PMTSKIP=YES, and the previous DTAFLD definition includes the
NOENDATTR attribute, the cursor will move past the prompt text to the input
field when the user enters the last character in the previous field. If there is no

442 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 SELFLD
other input field on the panel, the cursor returns to the first input field on the
panel. The ISPF SKIP keyword is not supported in GUI mode.
FLDTYPE=CUA | ISPF
This attribute defines the attribute type to be applied to the selection entry
field when LISTTYPE is LISTBOX, DDLIST, or COMBO. TYPE=CUA, the
default, causes the field to display using the standard CUA attribute. When
FLDTYPE=ISPF, a non-CUA attribute is generated and you may specify the
color, intensity and highlighting with the COLOR, INTENS and HILITE
attributes. These attributes are not valid when FLDTYPE=CUA.
COLOR=WHITE | RED | BLUE | GREEN | PINK | YELLOW | TURQ |
%varname
This attribute specifies the color of the field. You can define this attribute as a
variable name preceded by a ″%″.
INTENS=HIGH | LOW | NON | %varname
This attribute defines the intensity of a field. You can define this attribute as a
variable name preceded by a ″%″.
HILITE=USCORE | BLINK | REVERSE | %varname
This attribute specifies the extended highlighting attribute of the field. You can
define this attribute as a variable name preceded by ″%″.
field-prompt-text
This is the prompt text for the selection field. The prompt text can appear in
front of or above the field, based on the value assigned to the PMTLOC
attribute.

Multi-choice selections are displayed as check boxes when running in GUI

mode. To support both host and workstation forms of multi-choice prompt
text, a special pre-defined ENTITY name of “&multipmt” may be specified as
the field-prompt-text. When the panel is displayed, the field-prompt-text will be
Enter “/” to select option

(or its translated equivalent) for host display or

Check box to select option

(or its translated equivalent) for workstation display. The panel definition
should specify a PMTWIDTH value large enough to format the prompt as a
single line. If there is insufficient space to present the entire field-prompt-text, it
will be truncated to fit the available space.

Description
The SELFLD tag defines a selection field that includes a list of choices. CHOICE
tags coded within the SELFLD definition define the choices for the selection field.

| The TYPE attribute of the SELFLD tag determines how the choices appear. If
| TYPE=SINGLE, the SELFLD NAME attribute is used as the selection input field. If
| TYPE=MULTI, the CHOICE NAME attribute is used as the selection input field for
| each choice. If TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR, the command line
| is used as the selection input field.

When a selection list is formatted as a scrollable list:

v The multi-choice list entry field scrolls with the choice descriptions.
v The single-choice entry field is formatted beside the choice list and remains
visible when the choice descriptions scroll.

Chapter 13. Tag Reference 443

 SELFLD
v Choice descriptions that are formatted in multiple columns (CHOICECOLS and
CHOICEDEPTH attributes specified) result in a separate scrollable area for each
column.

The )LIST section is added to the panel if you specify:

v The LISTREF attribute
v A scrollable selection list (DEPTH is provided)
v The SELFLD tag within a scrollable AREA or REGION
v A multiple column selection list (CHOICECOLS > 1)
v LISTTYPE=COMBO
v TYPE=GUI on the PANEL tag.

| Note: If you specify the CMDAREA tag within your DTL source file, it must
| appear before the SELFLD tag when TYPE=MENU, TYPE=MODEL, or
| TYPE=TUTOR and CHECKVAR or UNAVAIL attributes are specified on
| nested CHOICE tags.

| If you specify the CMDAREA tag within your DTL source file, it must
| appear before the SELFLD tag when DEPTH=* is specified. The SELFLD tag
| DEPTH may have to be adjusted to allow for additional lines which result
| from tags present within the panel definition following the end SELFLD tag.

| Conditions
v The SELFLD tag requires an end tag.
v You must code the SELFLD tag within an AREA, DTACOL, REGION, or PANEL
definition. See “AREA (Area)” on page 213, “DTACOL (Data Column)” on
page 293, “REGION (Region)” on page 424, and “PANEL (Panel)” on page 397
for descriptions of these tags.
v Single-choice selection fields (the default TYPE value) should have an associated
VARDCL definition for the field-name specified with the NAME attribute. See
“VARDCL (Variable Declaration)” on page 463 for a complete description of this
tag.
v If both PAD and PADC have been specified, PAD is ignored and PADC is used.
v When a “%varname” notation is found on any of the attributes that allow a
variable name, the “%varname” entry must follow the standard naming
convention described in “Rules for “%variable” Names” on page 201.
| v You should code a CMDAREA on any panel that contains a SELFLD definition
| that specifies TYPE=MENU, TYPE=MODEL, or TYPE=TUTOR. If you do not
| include the CMDAREA tag, the conversion utility inserts one and issues a
| message, unless the PANEL tag specifies CMDLINE=NO.
v Only one menu-choice or model-choice list is formatted for any panel. If
multiple menu-choice or model-choice lists are specified, the first one will be
formatted as a menu; subsequent menu-choice or model-choice lists will be
formatted as single-choice lists.

Nested Tags
You can code the following tags within a SELFLD definition:

Tag Name Usage Page Required

CHDIV Choice Divider Multiple 232 No
CHOICE Selection choice Multiple 252 No
COMMENT Comment Multiple 272 No

444 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 SELFLD
Tag Name Usage Page Required
HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
SOURCE Source Multiple 449 No

Example
The following application panel markup contains two selection fields. The first
selection field is a single-choice selection field with the prompt text located before
the selection field. The single-choice selection field can be preselected depending
on the value assigned to the variable card.

The second selection field is a multiple-choice selection field with the prompt text
located above the selection field. Choices within this field may be preselected
depending on the value assigned to the CHECKVAR attribute variable specified on
the respective CHOICE tags.
<!DOCTYPE DM SYSTEM(
<!entity sampvar1 sysem>
<!entity sampabc system>)>
&sampvar1;

<PANEL NAME=selfld3 KEYLIST=keylxmp>Library Card Registration

<AB>
&sampabc;
</AB>
<TOPINST>Type in patron's name and card number (if applicable).
<TOPINST>Then select an action bar choice.
<AREA>
<DTAFLD DATAVAR=curdate PMTWIDTH=12 ENTWIDTH=8 USAGE=out>Date
<DTAFLD DATAVAR=cardno PMTWIDTH=12 ENTWIDTH=7 DESWIDTH=25>Card No
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address PMTWIDTH=12 ENTWIDTH=25>Address
<DIVIDER>
<REGION DIR=horiz>
<SELFLD NAME=cardsel PMTWIDTH=30 SELWIDTH=40
entwidth=1 required=yes autotab=yes>
Choose one of the following
<CHOICE CHECKVAR=card MATCH=new>New
<CHOICE CHECKVAR=card MATCH=renew>Renewal
<CHOICE CHECKVAR=card MATCH=replace>Replacement
</SELFLD>
<SELFLD TYPE=multi PMTWIDTH=30 SELWIDTH=36
depth=5 init=no>
Check valid branches
<CHOICE NAME=north HELP=nthhlp CHECKVAR=nth>North Branch
<CHOICE NAME=south HELP=sthhlp CHECKVAR=sth>South Branch
<CHOICE NAME=east HELP=esthlp CHECKVAR=est>East Branch
<CHOICE NAME=west HELP=wsthlp CHECKVAR=wst>West Branch
<CHOICE NAME=city HELP=ctyhlp CHECKVAR=cty>City Branch
<CHOICE NAME=cnty HELP=cnthlp CHECKVAR=cnt>County Branch
</SELFLD>
</REGION>
</AREA>
<CMDAREA>Enter a command
</PANEL>

Chapter 13. Tag Reference 445

SELFLD
Figure 154 shows the formatted result.

File Search Help

-------------------------------------------------------------------------
Library Card Registration

Type in patron's name and card number (if applicable).

Then select an action bar choice.

Date . . . : ________
Card No . . _______ (A 7–digit number)
Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________

Check valid branches

Choose one of the following #SAREA37 #
_ 1. New # #
2. Renewal # #
3. Replacement # #
# #
Enter a command ===> ____________________________________________________
F1=Help F3=Exit F5=Display F6=Keyshelp F10=Actions
F12=Cancel

The contents of the scrollable area are as follows:

)AREA SAREA37

_ North Branch
_ South Branch
_ East Branch
_ West Branch
_ City Branch
_ County Branch

)AREA SAREA37

Figure 154. Selection Fields

The following example illustrates the creation of an ISPF selection menu. The
FCHOICE attribute specifies that the first selection number is 0. The choice
selection for Exit is specified on the CHOICE tag. The ACTION tag for the Exit
choice selection specifies both the RUN and TYPE attributes because RUN is
required on the ACTION tag and TYPE is necessary to specify the ISPF selection
for the generated ZSEL panel statement.
<!doctype dm system ()>
<!-- Sample selection menu -->
<varclass name=vc1 type='char 80'>
<xlatl format=upper>
</xlatl>

<varlist>
<vardcl name=zcmd varclass=vc1>
</varlist>

<panel name=selfld2 menu keylist=keylxmp>Sample Selection Panel

<topinst>This is a selection panel.
<selfld type=menu pmtloc=before fchoice=0 trail=nextsel
selwidth=40 pmtwidth=10>Select an option
<choice checkvar=xtest1 match=a>
Selection #0 (Command Selch0)
<action run=Selch0>

446 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 SELFLD
<choice checkvar=xtest1 match=b>
Selection #1 (Command Selch1)
<action run=Selch1 parm='1 2 3 4'
passlib newpool suspend>
<choice checkvar=xtest1 match=c>
Selection #2 (Command Selch2)
<action run=Selch2 parm=1234>
<choice checkvar=xtest1 match=d>
Selection #3 (Command Selch3)
<action run=Selch3 parm=abcd>
<choice checkvar=xtest1 match=e>
Selection #4 (Command Selch4)
<action run=Selch4 parm='a b c d'>
<choice selchar=X>
Exit
<action run=exit type=exit>
</selfld>
<cmdarea>
</panel>

Figure 155 shows the formatted result.

Sample Selection Panel

This is a selection panel.

Select an
option . . 0 Selection #0 (Command Selch0)
1 Selection #1 (Command Selch1)
2 Selection #2 (Command Selch2)
3 Selection #3 (Command Selch3)
4 Selection #4 (Command Selch4)
X Exit

Option ===> _____________________________________________________________

F1=Help F3=Exit F5=Display F6=Keyshelp F10=Actions
F12=Cancel

Figure 155. Selection Menu

SL (Simple List)
The SL tag defines a simple list of items within an information region.

ÊÊ <SL Ê
COMPACT NOSKIP NO INDENT=n
SPACE= YES

Ê > </SL> ÊÍ
TEXT=SL-heading-text

COMPACT
This attribute causes the list to be formatted without a blank line between the
list items.

Chapter 13. Tag Reference 447

SL
NOSKIP
This attribute causes the list to format without creating a blank line before the
first line of the list.
SPACE=NO | YES
The SPACE attribute controls the indentation space for the list item. When the
SPACE attribute is not specified on the LI tag, the SPACE attribute from the SL
tag is used to set the indentation space for the nested LI tag item-text.

When SPACE=YES, the indentation is set to 3 spaces. When SPACE=NO (or

SPACE is not specified), the indentation is set to 4 spaces.

The SPACE attribute can be used to control the alignment of list items when
the first word of some list items is a DBCS word preceded by a shift-out
character and the first word of other list items is a SBCS word.
INDENT=n
This attribute specifies that the list be indented from the current left margin.
TEXT=SL-heading-text
This attribute causes the list to format with a heading line containing the
SL-heading-text.

Description
The SL tag defines a simple list of items within an information region.

Simple lists are indented lists, with no bullets, dashes, or hyphens preceding the
list items. Nested lists indent four spaces to the right of the left margin of the list
that contains them.

Note: The SPACE attribute does not affect the indentation of nested lists.

The conversion utility adds a blank line before the first item in the list.

Use the LI tag to denote each list item. See “LI (List Item)” on page 346 for more
information on the LI tag.

Conditions
v The SL tag requires an end tag.
v You must code the SL tag within an INFO definition. See “INFO (Information
Region)” on page 339 for a complete description of this tag.

Nested Tags
You can code the following tags within the SL tag:

Tag Name Usage Page Required

LI List item Multiple 346 No
LP List part Multiple 352 No

Example
The following help panel markup contains two simple lists. The second simple list
is compact, and is nested within the first list. Figure 156 on page 449 shows the
formatted result.

448 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 SL
<!DOCTYPE DM SYSTEM>

<HELP NAME=sl WIDTH=40 DEPTH=22>Help for ShelfBrowse

<AREA>
<INFO>
<P>Using ShelfBrowse, you can locate the following items:
<SL>
<LI>Audiotapes
<LI>Books
<LI>Periodicals
<SL COMPACT>
<LI>Newspapers
<LI>Magazines
</SL>
<LI>Reference material
<LI>Videotapes
</SL>
</INFO>
</AREA>
</HELP>

Help for ShelfBrowse

Using ShelfBrowse, you can locate the

following items:

Audiotapes

Books

Periodicals

Newspapers
Magazines

Reference material

Videotapes

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 156. Simple List

SOURCE (Source)
The SOURCE tag defines ISPF panel logic statements within an application panel.

ÊÊ <SOURCE > text </SOURCE> ÊÍ

PROC
TYPE= REINIT
INIT
ABCINIT
ABCPROC

TYPE=PROC | REINIT | INIT | ABCINIT | ABCPROC

This attribute specifies the panel section that will be updated with the
SOURCE tag text.

Chapter 13. Tag Reference 449

 SOURCE
text
This is the unformatted ISPF panel statement.

Description
The SOURCE tag defines ISPF panel statements within an application panel.

Lines of text from a SOURCE tag that follows an AREA, CHOICE, DA, DTACOL,
DTAFLD, HELP, LSTCOL, LSTFLD, LSTGRP, PANEL, REGION, or SELFLD tag are
added to the )INIT, )REINIT, or )PROC panel section when encountered in the DTL
source file.

For example, if a SOURCE tag follows the DTAFLD tag, any logic or other entries
normally generated by DTAFLD would be completed before the lines within
SOURCE are added.

The use of a SOURCE tag within a SELFLD tag results in the placement of the
SOURCE tag lines after any logic created by the previous CHOICE tag. Additional
)INIT, )REINIT, or )PROC section entries may be added when the end SELFLD tag
is processed. You can control the placement of the SOURCE tag entries by nesting
the SELFLD tag definition within a DTACOL tag, and placing the SOURCE tag
definition either before or after the SELFLD tag definition.

Lines of text from a SOURCE tag within an action bar definition are added to:
v )ABCINIT following all other generated statements for that PDC tag.
v )ABCPROC before any other generated statements for that PDC tag.

SOURCE tags within an action bar definition must specify the TYPE as ABCINIT
or ABCPROC. SOURCE tags that follow the other listed tags cannot specify TYPE
as ABCINIT or ABCPROC.

| When the SOURCE tag is coded within a GENERATE tag, the TYPE attribute is
| ignored. TYPE is automatically determined from the placement of the GENERATE
| tag within the DTL source file.

If the length of any line exceeds the record length of the output panel file, the
conversion utility truncates the line and issues a warning message.

Text found between the SOURCE and SOURCE end tags is placed in the specified
panel section as coded; that is, no formatting except entity substitution is
performed. To refer to an entity within <SOURCE> tag text, the entity name is
preceded by a percent (%) instead of an ampersand (&). Using the percent (%) sign
avoids conflict with variable names. A valid percent sign can be specified as
“%amp;” to avoid an “entity not found” message. For example, you would refer to
the TSO command “%xyz” as “%amp;xyz”.

Conditions
v The SOURCE tag requires an end tag.
| v You must code the SOURCE tag within an ABC, AREA, CHOICE, DA, DTACOL,
| DTAFLD, GENERATE, HELP, LSTCOL, LSTFLD, LSTGRP, PANEL, PDC,
| REGION, or SELFLD tag definition.

Nested Tags
None.

450 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 SOURCE
Example
<!DOCTYPE DM SYSTEM(
<!entity sampvar1 sysem>
<!entity sampabc system>)>
&sampvar1;

<PANEL NAME=source1 KEYLIST=keylxmp>Library Card Registration

<AB>
&sampabc;
</AB>
<TOPINST>Type in patron's name and card number (if applicable)
<TOPINST>Then select an action bar choice.
<AREA>
<DTACOL PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25 SELWIDTH=25>
<DTAFLD DATAVAR=curdate USAGE=out ENTWIDTH=8>Date
<DTAFLD DATAVAR=cardno ENTWIDTH=7>Card No.
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address>Address
</DTACOL>
<DIVIDER>
<REGION DIR=horiz>
<SELFLD NAME=cardsel PMTWIDTH=30 SELWIDTH=38>Choose
one of the following
<CHOICE CHECKVAR=card MATCH=new>New
<CHOICE CHECKVAR=card MATCH=renew>Renewal
<CHOICE CHECKVAR=card MATCH=replace>Replacement
<SOURCE TYPE=proc>
if (&cardsel = 1)
VER (&name,nb)
VER (&address,nb)
</SOURCE>
</SELFLD>
<SELFLD TYPE=multi PMTWIDTH=30 SELWIDTH=25>Check valid branches
<CHOICE NAME=north HELP=nthhlp CHECKVAR=nth>North Branch
<CHOICE NAME=south HELP=sthhlp CHECKVAR=sth>South Branch
<CHOICE NAME=east HELP=esthlp CHECKVAR=est>East Branch
<CHOICE NAME=west HELP=wsthlp CHECKVAR=wst>West Branch
</SELFLD>
</REGION>
</AREA>
<CMDAREA>Enter a command
</PANEL>

T (Truncation)
The T tag designates the minimum command name that the user must enter to
issue a command.

ÊÊ <T> ÊÍ
</T>

Description
You must code the T tag within the external-command-name of the CMD tag. For
example, if the following command is coded in an application command table, the
user could enter com, comp, compa, compar, or compare to run the command.
<cmd name=compare>com<t>pare

The command name must be at least 2 bytes.

Chapter 13. Tag Reference 451

 T
At run time, ISPF runs the first valid command in the command table that matches
the character string entered in the command area.

You should be careful to avoid specifying values that conflict with other
commands. For example:
<cmd name=compare>co<t>mpare
<cmd name=copy>co<t>py

In this situation, if the user enters co as a command, ISPF will run the COMPARE
command.

Conditions
v You must code the T tag within the external-command-name of a CMD definition.
See “CMD (Command Definition)” on page 259 for a complete description of this
tag.

Nested Tags
None.

Example
The following source file markup contains a command table. The commands
DELETE and UPDATE have truncation definitions that allow the user to enter
“del” and “upd”, respectively, as the minimum command name.
<!DOCTYPE DM SYSTEM>

<CMDTBL APPLID=conv>
<CMD NAME=update>Upd<T>ate
<CMDACT ACTION='alias add'>
<CMD NAME=add>Add
<CMDACT ACTION=setverb>
<CMD NAME=delete>Del<T>ete
<CMDACT ACTION=passthru>
<CMD NAME=search>Search
<CMDACT ACTION=passthru>
</CMDTBL>

The following table shows the resultant ISPF application command table.
Table 6. ISPF Application Command Table
ZCTVERB ZCTTRUNC ZCTACT
UPDATE 3 ALIAS ADD
ADD 0 SETVERB
DELETE 3 PASSTHRU
SEARCH 0 PASSTHRU

| TEXTLINE (Text Line)

| The TEXTLINE tag generates a single line of text to replace the regular tag text for
| the HELP and PANEL tags.

| ÊÊ <TEXTLINE> </TEXTLINE> ÊÍ

452 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 TEXTLINE
| Description
| The TEXTLINE tag encloses one or more TEXTSEG tags, used to define the parts
| or segments of the replacement text. Text defined by the TEXTSEG tag(s) is
| accumulated in a left to right order. The resulting text is used to to create or
| replace the text portion of the HELP or PANEL tag definition.

| Conditions
| v The TEXTLINE tag requires an end tag.
| v You must code the TEXTLINE tag within a HELP or PANEL tag definition.

| Nested Tags
| You can code the following tags within a FIG definition:
|| Tag Name Usage Page Required
| TEXTSEG Text Segment Multiple 453 Yes
|

| Example
| See the example for “TEXTSEG (Text Segment)”.

| TEXTSEG (Text Segment)

| The TEXTSEG tag creates a text segment to be accumulated for the replacement
| text line by the TEXTLINE tag.

| ÊÊ <TEXTSEG Ê
| EXPAND= AFTER WIDTH= n
BEFORE
BOTH

| Ê > text ÊÍ
| </TEXTSEG>

|
| EXPAND=ABOVE | BEFORE | BOTH
| This attribute specifies whether expand control is added to the provided text.
| Expand characters are obtained from the HELP or PANEL tag definition, if
| available. If no expand character(s) have been specified on those tags, the
| conversion utility generates the necessary character. You may place the expand
| control before, after, or both before and after the text.
| WIDTH=n
| This attribute specifies the number of bytes to reserve for the text. The default
| is to not allow space beyond the actual text length.
| Text
| This is the text of the segment.

| Description
| The TEXTSEG tag defines a part or segment of a replacement text line. When
| multiple TEXTSEG tags are present within the TEXTLINE definition, the
| replacement text line is created from left to right in the order the TEXTSEG tags
| are coded.

Chapter 13. Tag Reference 453

 TEXTSEG
| Conditions
| v You must code the TEXTSEG tag within a TEXTLINE tag definition.
| v If the EXPAND attribute is not specified and the resulting replacment text is less
| than the panel width, the text will be centered as the panel title.

| Nested Tags
| You can code the following tags within a FIG definition:
|| Tag Name Usage Page Required
| HP Highlighted Phrase Multiple 336 No
|

| Example
| The follwing example uses the TEXTLINE and TEXTSEG tags to create a special
| panel title that includes the system time and date. Because the EXPAND attribute
| is specified in the second TEXTSEG tag, the resulting title replacement text has the
| time and date fields placed at the left and right panel border.
| <!doctype dm system ()>
| <!-- Sample selection menu -->
|
| <varclass name=vc1 type='char 80'>
| <xlatl format=upper>
| </xlatl>
|
| <varlist>
| <vardcl name=zcmd varclass=vc1>
| </varlist>
|
| <panel name=textseg1 menu keylist=keylxmp>
|
| <textline>
| <textseg>&ztime
| <textseg expand=both>
| Sample Selection Panel with TEXTLINE tag
| <textseg>&zdate(8)
| </textline>
|
| <topinst>This is a selection panel.
| <selfld type=menu pmtloc=before fchoice=0 trail=nextsel
| selwidth=40 pmtwidth=10>Select an option
| <choice checkvar=xtest1 match=a>
| Selection #0 (Command Selch0)
| <action run=Selch0>
| <choice checkvar=xtext1 match=b>
| Selection #1 (Command Selch1)
| <action run=Selch1 parm='1 2 3 4'>
| passlib newpool suspend
| <choice checkvar=xtest1 match=c>
| Selection #2 (Command Selch2)
| <action run=Selch2 parm=1234>
| <choice checkvar=xtest1 match=d>
| Selection #3 (Command Selch3)
| <action run=Selch3 parm=abcd>
| <choice checkvar=xtest1 match=e>
| Selection #4 (Command Selch4)
| <action run=Selch4 parm='a b c d'>
| <chdiv>
| <choice selchar=x>
| Exit
| <action run=exit type=exit>
| </selfld>

454 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 TEXTSEG
| <cmdarea>
| </panel>
| /doctype
|
| 07:30 Sample Selection Panel with TEXTLINE tag 99/12/15
| Option ===> _
|
| This is a selection panel.
|
| Select an
| option . . 0 Selection #0 (Command Selch0)
| 1 Selection #1 (Command Selch1)
| 2 Selection #2 (Command Selch2)
| 3 Selection #3 (Command Selch3)
| 4 Selection #4 (Command Selch4)
|
| X Exit
|
|
|
|
|
|
|
|
|
|
|
TOPINST (Top Instruction)
The TOPINST tag defines top instructions for an application panel.

ÊÊ <TOPINST > ÊÍ
COMPACT instruction-text </TOPINST>

COMPACT
This attribute causes the top instruction to format without a blank line after the
text.
instruction-text
This is the text of the top instruction. The instruction-text must fit in the
remaining panel depth.

Description
The TOPINST tag defines top instructions for an application panel. The
instruction-text formats as a paragraph based on the width of the application panel.
You can code multiple paragraphs of instruction text by using a new top
instruction tag for each new paragraph.

If the COMPACT attribute is not specified, the conversion utility inserts a blank
line after the top instruction text.

Conditions
v You must code the TOPINST within a PANEL definition. See “PANEL (Panel)”
on page 397 for a complete description of this tag.
v You cannot code a TOPINST tag within an AREA definition. If you define an
area for the panel, code the TOPINST tag before the AREA start tag.

Chapter 13. Tag Reference 455

TOPINST
Nested Tags
You can code the following tag within a TOPINST definition:

Tag Name Usage Page Required

HP Highlighted phrase Multiple 336 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No

Example
The following application panel markup contains top instructions. Figure 157 on
page 457 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=selcls TYPE='CHAR 2'>

<VARLIST>
<VARDCL NAME=loc VARCLASS=selcls>
<VARDCL NAME=mode VARCLASS=selcls>
</VARLIST>

<PANEL NAME=topinst HELP=trvlhlp WIDTH=60 DEPTH=22 KEYLIST=keylxmp>

Dream Vacation Guide
<AB>
<ABC>File
<PDC>Add Entry
<ACTION RUN=add>
<PDC>Delete Entry
<ACTION RUN=delete>
<PDC>Update Entry
<ACTION RUN=update>
<PDC>Exit
<ACTION RUN=exit>
<ABC>Help
<PDC>Extended Help...
<ACTION RUN=exhelp>
<PDC>Keys Help...
<ACTION RUN=keyshelp>
</AB>
<TOPINST>Choose one of the following exotic locations and
your preferred mode of travel, then press Enter.
<AREA>
<REGION DIR=horiz>
<SELFLD NAME=loc PMTWIDTH=23 SELWIDTH=25>Exotic Location:
<CHOICE>Athens, GA
<CHOICE>Berlin, CT
<CHOICE>Cairo, IL
<CHOICE>Lizard Lick, NC
<CHOICE>Paris, TX
<CHOICE>Rome, NY
<CHOICE>Venice, FL
</SELFLD>
<DIVIDER>
<SELFLD NAME=mode PMTWIDTH=25 SELWIDTH=25>Travel Mode:
<CHOICE>Boxcar
<CHOICE>Hitchhike
<CHOICE>Mule
</SELFLD>
</REGION>
</AREA>
<CMDAREA>
</PANEL>

456 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 TOPINST

File Help
---------------------------------------------------------
Dream Vacation Guide

Choose one of the following exotic locations and your

preferred mode of travel, then press Enter.

Exotic Location: Travel Mode:

__ 1. Athens, GA __ 1. Boxcar
2. Berlin, CT 2. Hitchhike
3. Cairo, IL 3. Mule
4. Lizard Lick, NC
5. Paris, TX
6. Rome, NY
7. Venice, FL

Command ===>_______________________________________________
F1=Help F2=Split F3=Exit F6=Keyshelp
F9=Swap F12=Cancel

Figure 157. Top Instructions

UL (Unordered List)
The UL tag defines an unordered list of items within an information region.

ÊÊ <UL Ê
COMPACT NOSKIP NO INDENT=n
SPACE= YES

Ê > </UL> ÊÍ
TEXT=UL-heading-text

COMPACT
This attribute causes the list to be formatted without a blank line between the
list items.
NOSKIP
This attribute causes the list to format without creating a blank line before the
first line of the list.
SPACE=NO | YES
The SPACE attribute controls the indentation space for the list item. When the
SPACE attribute is not specified on the LI tag, the SPACE attribute from the
UL tag is used to set the indentation space for the nested LI tag item-text.

When SPACE=YES, the indentation is set to 3 spaces. When SPACE=NO (or

SPACE is not specified), the indentation is set to 4 spaces.

The SPACE attribute can be used to control the alignment of list items when
the first word of some list items is a DBCS word preceded by a shift-out
character and the first word of other list items is a SBCS word.
INDENT=n
This attribute specifies that the list be indented from the current left margin.

Chapter 13. Tag Reference 457

UL
TEXT=UL-heading-text
This attribute causes the list to format with a heading line containing the
UL-heading-text.

Description
The UL tag defines an unordered list of items within an information region.
Unordered lists format as indented lists, with the list item identifier at the left
margin. Nested lists indent four spaces to the right of the left margin of the list
that contains them.

Note: The SPACE attribute does not affect the indentation of nested lists.

The conversion utility adds a blank line before the first item in the list. There are
three levels of item identifiers: bullets (o), hyphens (-), and dashes (--). Each level is
used successively when you nest unordered lists.

Panels formatted with the DBCS option use an uppercase ‘O’ as the bullet
character.

Use the LI tag to denote each list item. See “LI (List Item)” on page 346 for more
information on the LI tag.

Conditions
v The UL tag requires an end tag.
v You must code the UL tag within an INFO definition. See “INFO (Information
Region)” on page 339 for a complete description of this tag.

Nested Tags
You can code the following tags within a UL definition:

Tag Name Usage Page Required

LI List item Multiple 346 No
LP List part Multiple 352 No

Example
The following help panel markup contains two unordered lists. The second
unordered list is nested within the second list item of the first unordered list.
Figure 158 on page 459 shows the formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=ul DEPTH=22>Help for Reference Section

<AREA>
<INFO>
<P>Learn everything about anything,
and more, in our Reference section.
Our Reference section includes:
<UL>
<LI>Atlases
<LI>Dictionaries
<UL COMPACT>
<LI>English
<LI>Other languages
</UL>
<LI>Encyclopedias
<LI>How-to books

458 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 UL
<LI>Magazines and periodicals
</UL>
</INFO>
</AREA>
</HELP>

Help for Reference Section

Learn everything about anything, and more, in

our Reference section. Our Reference section
includes:

o Atlases

o Dictionaries

- English
- Other languages

o Encyclopedias

o How-to books

o Magazines and periodicals

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 158. Unordered List

VARCLASS (Variable Class)

The VARCLASS tag defines information related to a class of variables.

ÊÊ <VARCLASS NAME=variable-class-name Ê

Ê TYPE= ’CHAR maximum-length’ Ê

’DBCS maximum length’
’MIXED maximum-length’
’ANY maximum-length’
’EBCDIC maximum-length’
’%varname maximum-length’
ITIME
STDTIME
IDATE
STDDATE
JDATE
JSTD
’VMASK maximum-length’
0
’NUMERIC total-digits fractional-digits ’

Ê > ÊÍ
MSG=message-identifier </VARCLASS>

NAME=variable-class-name
This attribute specifies the name of this variable class.

Chapter 13. Tag Reference 459

 VARCLASS
The variable-class-name must follow the standard naming convention described
in “Rules for Variable Names” on page 201.
TYPE=type of data
This attribute specifies the data type and display length characteristics for
variables that refer to the variable class.

| For data fields and list columns, the conversion utility uses the lengths
| specified in this attribute when CHOFLD or DTAFLD ENTWIDTH or LSTCOL
| COLWIDTH attributes cannot otherwise be determined. The lengths specified
| control the width of the data field in the panel.

The allowable TYPE values are:

'CHAR maximum-length'
This specifies a character string for which the maximum length, in bytes, is
given by maximum-length.
'DBCS maximum-length'
This is a double-byte character string for which the maximum length, in
bytes, is given by maximum-length. The maximum length must an even
number.
'MIXED maximum-length'
This specifies a character string containing single-byte characters,
double-byte characters, or both for which the maximum length, in bytes, is
given by maximum-length. Strings of DBCS characters are delimited by
shift-out (SO) and shift-in (SI) codes.
'ANY maximum-length'
This attribute is processed by the conversion utility as TYPE=MIXED.
'EBCDIC maximum-length'
This specifies a character string containing only single-byte characters for
which the maximum length, in bytes, is given by maximum-length.
'%varname maximum-length'
This specifies a variable name will be used to define the type of character
string. The maximum length, in bytes, is given by maximum-length. It is the
responsibility of the application developer to ensure that %varname
contains a valid TYPE value prior to attempting to display the panel.
ITIME
The conversion utility will add a ″VEDIT (variable)″ statement to the
)PROC section of the panel for variables which are related to this
VARCLASS. The default length value of ITIME is set by the conversion
utility to 5.
STDTIME
The conversion utility will add a ″VEDIT (variable)″ statement to the
)PROC section of the panel for variables which are related to this
VARCLASS. The default length value of STDTIME is set by the conversion
utility to 8.
IDATE
The conversion utility will add a ″VEDIT (variable)″ statement to the
)PROC section of the panel for variables which are related to this
VARCLASS. The default length value of IDATE is set by the conversion
utility to 8.

460 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 VARCLASS
STDDATE
The conversion utility will add a ″VEDIT (variable)″ statement to the
)PROC section of the panel for variables which are related to this
VARCLASS. The default length value of STDDATE is set by the conversion
utility to 10.
JDATE
This attribute is supported as an ISPF extension to the Dialog Tag
Language. The conversion utility will add a ″VEDIT (variable)″ statement to
the )PROC section of the panel for variables which are related to this
VARCLASS. The default length value of JDATE is set by the conversion
utility to 6.
JSTD
This attribute is supported as an ISPF extension to the Dialog Tag
Language. The conversion utility will add a ″VEDIT (variable)″ statement to
the )PROC section of the panel for variables which are related to this
VARCLASS. The default length value of JSTD is set by the conversion
utility to 8.
'VMASK maximum-length'
This attribute is supported as an ISPF extension to the Dialog Tag
Language. the VMASK attribute is provided to support the user mask
option the the ISPF VMASK service. The maximum-length value is limited
to the ISPF maximum of 20. The conversion utility will add a ″VEDIT
(variable)″ statement to the )PROC section of the panel for variables which
are related to this VARCLASS.
'NUMERIC total-digits 0 | fractional-digits'
This attribute allows you to check to see if the user has entered a valid
number. A valid number can include thousands separators, a decimal
separator, and a sign. The conversion utility builds the VER(variable
ENUM) statement to perform numeric validation. The value specified for
total-digits must not be greater than 16.

The total-digits and fractional-digits are used to determine a maximum-length

value which is used for field entry width, if necessary, in DTAFLD and
LSTCOL processing. For example, ‘NUMERIC 8 2’ defines a width of 11,
composed of 8 possible digits, a decimal point, a thousands separator, and
a leading sign.

Note: ISPF does not check to verify proper positioning of the decimal
point. Refer to the discussion on VER(variable ENUM) in the ISPF
User’s Guide for more information.
MSG=message-identifier
This attribute indicates the default message to be displayed if the variable fails
any of the enclosed checks. See “MSG (Message)” on page 376 for information
on creating messages.

Description
The VARCLASS tag defines information related to a class of variables. You can
group validation and translation checks you want ISPF to perform within one
VARCLASS definition. You point to the VARCLASS definition from one or more
VARDCL tags you code within the VARLIST definition.

Note: The ISPF Dialog Tag Language conversion utility does not require that you
code the VARCLASS, VARDCL, or VARLIST tags for a successful generation

Chapter 13. Tag Reference 461

VARCLASS
of a panel, command table, or message member that includes variables. If
the conversion utility finds a variable that does not have an associated
VARDCL definition, it issues a warning message.

The use of the VARCLASS, VARDCL, and VARLIST tags is required if you
want to use the facilities provided by the CHECKL and XLATL tags.

Conditions
v You cannot code the VARCLASS tag within any other tag definition.
v You must code the VARCLASS tag before any other tag within the source file
that refers to it.
v Within the variable class definition, you must code any and all XLATL tags
before any CHECKL tags.

Nested Tags
You can code the following tags within a VARCLASS definition:

Tag Name Usage Page Required

CHECKL Check list Multiple 243 No
XLATL Translate list Multiple 472 No

Example
The following example contains two variable classes. The first variable class
provides an alphabetic validity check. The second variable class provides input
translation to upper case and validates that the input is one of the listed values.
Also shown in the markup are two input data fields (within a PANEL definition)
that refer to the variable declarations associated with the variable classes.

<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=namec TYPE='char 25'>

<CHECKL>
<CHECKI TYPE=alpha>
</CHECKL>

<VARCLASS NAME=officec TYPE='char 4'>

<XLATL FORMAT=upper>
</XLATL>
<CHECKL>
<CHECKI TYPE=values PARM1=EQ PARM2='A101 A108 B210 B214'>
</CHECKL>

<VARLIST>
<VARDCL NAME=reserver VARCLASS=namec>
<VARDCL NAME=office VARCLASS=officec>
</VARLIST>

<PANEL NAME=varclass>Conference Room

<TOPINST>Enter the required information to reserve a conference room.
<AREA>
<DTACOL PMTWIDTH=20>
<DTAFLD DATAVAR=reserver USAGE=in ENTWIDTH=25>Name
<DTAFLD DATAVAR=office USAGE=in ENTWIDTH=4>Office number
</DTACOL>
</AREA>
</PANEL>

462 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 VARDCL

VARDCL (Variable Declaration)

The VARDCL tag declares variables referred to in dialog element definitions.

ÊÊ <VARDCL NAME=name VARCLASS=variable-class-name > ÊÍ

</VARDCL>

NAME=name
This attribute specifies the name of a variable used elsewhere in the DTL
source file. The name must follow the standard naming convention described in
“Rules for Variable Names” on page 201.
VARCLASS=variable-class-name
This attribute specifies the default variable class associated with the variable. If
you want to perform a different set of checks or translations on any data field
or list column, you can specify an overriding variable class in the DTAFLD or
LSTCOL tags.

Description
The VARDCL tag declares variables referred to in dialog element definitions.

Note: The ISPF Dialog Tag Language conversion utility does not require that you
code the VARCLASS, VARDCL, or VARLIST tags for successful generation
of a panel, command table, or message member that includes variables. If
the conversion utility finds a variable that does not have an associated
VARDCL definition, it issues a warning message.

The use of the VARCLASS, VARDCL, and VARLIST tags is required if you
want to use the facilities provided by the CHECKL and XLATL tags.

Conditions
v You must code the VARDCL tag within a VARLIST tag. See “VARLIST (Variable
List)” on page 464 for a complete description of this tag.

Nested Tags
None.

Example
The following source file markup contains variable declarations for all of the
variables defined in the panel definition. The declared variables include:
v The variable whchsrch specified in the CHECKVAR attributes associated with the
pull-down choices of the Search action bar choice.
v The data field variables curdate, cardno, name, and address.
v The variable cardsel, which is the entry-field of the single-choice selection field.
v The variables north, south, east, and west, which are the entry-fields associated
with the multiple-choice selection field.
v The variables defined as the check variables (CHECKVAR attribute) for the
selection fields.
<!DOCTYPE DM SYSTEM(
<!entity sampabc sysem>
<!entity sampbody system>)>

Chapter 13. Tag Reference 463

VARDCL
<VARCLASS NAME=date TYPE='char 8'>
<VARCLASS NAME=numcls TYPE='numeric 7'>
<VARCLASS NAME=namecls TYPE='char 25'>
<VARCLASS NAME=char1cls TYPE='char 1'>
<VARCLASS NAME=char7cls TYPE='char 7'>

<VARLIST>
<VARDCL NAME=whchsrch VARCLASS=char1cls>
<VARDCL NAME=curdate VARCLASS=date>
<VARDCL NAME=cardno VARCLASS=numcls>
<VARDCL NAME=name VARCLASS=namecls>
<VARDCL NAME=address VARCLASS=namecls>
<VARDCL NAME=cardsel VARCLASS=char1cls>
<VARDCL NAME=card VARCLASS=char7cls>
<VARDCL NAME=north VARCLASS=char1cls>
<VARDCL NAME=south VARCLASS=char1cls>
<VARDCL NAME=east VARCLASS=char1cls>
<VARDCL NAME=west VARCLASS=char1cls>
<VARDCL NAME=nth VARCLASS=char1cls>
<VARDCL NAME=sth VARCLASS=char1cls>
<VARDCL NAME=est VARCLASS=char1cls>
<VARDCL NAME=wst VARCLASS=char1cls>
</VARLIST>

<PANEL NAME=vardcl>Library Card Registration

<AB>
&sampabc;
</AB>
&sampbody;
</PANEL>

VARLIST (Variable List)

The VARLIST tag provides the means to code VARDCL tags in a single list.

ÊÊ <VARLIST> </VARLIST> ÊÍ

Description
The VARLIST tag provides the means to code VARDCL tags in a single list. The
VARDCL tags coded within a VARLIST definition declare variables that are
referred to in the dialog element definitions within a DTL source file.

Note: The ISPF Dialog Tag Language conversion utility does not require that you
code the VARCLASS, VARDCL, or VARLIST tags for a successful generation
of a panel, command table, or message member that includes variables. If
the conversion utility finds a variable that does not have an associated
VARDCL definition, it issues a warning message.

The use of the VARCLASS, VARDCL, and VARLIST tags is required if you
want to use the facilities provided by the CHECKL and XLATL tags.

Conditions
v The VARLIST tag requires an end tag.
v You cannot code the VARLIST tag within any other tag definition.
v You can code the VARLIST tag immediately after any and all VARCLASS tags
within the DTL source file and before any tag definitions that refer to the
variables declared in the variable list.

464 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 VARLIST
Nested Tags
You code the following tag within a VARLIST definition:

Tag Name Usage Page Required

VARDCL Variable declaration Multiple 464 No

Example
The following source file markup contains a variable list. The variable declarations
within the list define variables for the fields within the PANEL definitions that
refer to them.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=char8 TYPE='char 8'>

<VARCLASS NAME=name TYPE='char 25'>
<VARCLASS NAME=phoncls TYPE='char 12'>
<VARCLASS NAME=appcls TYPE='char 1'>
<XLATL FORMAT=upper>
</XLATL>
<CHECKL>
<CHECKI TYPE=values PARM1=EQ PARM2='Y N'>
</CHECKL>

<VARLIST>
<VARDCL NAME=curdate VARCLASS=char8>
<VARDCL NAME=namevar VARCLASS=name>
<VARDCL NAME=passvar VARCLASS=char8>
<VARDCL NAME=xlname VARCLASS=name>
<VARDCL NAME=xphone VARCLASS=phoncls>
<VARDCL NAME=xapp VARCLASS=appcls>
</VARLIST>

<PANEL NAME=varlist1 KEYLIST=keylxmp>System Log On

<TOPINST>Complete the following fields, then press Enter.
<AREA>
<DTACOL PMTWIDTH=12>
<DTAFLD DATAVAR=curdate ENTWIDTH=8 USAGE=out>Date
<DTAFLD DATAVAR=namevar ENTWIDTH=25 DESWIDTH=15>Name
<DTAFLD DATAVAR=passvar ENTWIDTH=8 DISPLAY=no>Password
</DTACOL>
</AREA>
</PANEL>

<PANEL NAME=varlist2 DEPTH=14 KEYLIST=keyltbl>Subscriber List

<TOPINST>Enter phone number, if missing,
(format - nnn-nnn-nnnn) and approved
indicator (y or n) for each person.
<AREA>
<LSTFLD>
<LSTCOL DATAVAR=xlname USAGE=out COLWIDTH=25>Last Name
<LSTCOL DATAVAR=xphone COLWIDTH=12>Phone Number
<LSTGRP>Approved
<LSTCOL DATAVAR=xapp USAGE=in REQUIRED=yes
COLWIDTH=1 MSG=msgv886>(Y or N)
</LSTGRP>
</LSTFLD>
</AREA>
<CMDAREA>Enter a command
</PANEL>

Chapter 13. Tag Reference 465

VARSUB

VARSUB (Variable Substitution)

The VARSUB tag specifies a variable to substitute in message text.

ÊÊ <VARSUB VAR=variable-name > ÊÍ

</VARSUB>

VAR=variable-name
This attribute specifies the variable whose value is substituted within the
message.

The variable-name should be declared with a VARDCL tag.

The variable-name must follow the standard naming convention described in

“Rules for Variable Names” on page 201.

Description
The VARSUB tag specifies a variable to substitute in message text. You use the
required VAR attribute to specify the variable whose value is resolved and inserted
into the message text when the message is displayed. The value coded must be a
variable name without leading % notation.

You can code the VARSUB tag in the message-text of a MSG tag. The variable value
is inserted by ISPF at run time at the position in the message text where the
VARSUB tag is coded.

For example, assume the following VARSUB tag was coded within the text of this
message:
<msgmbr name=abca00>
<msg suffix=1 msgtype=warning>Invalid name,
“<VARSUB VAR=LASTN>”, specified.
The name may contain only alphabetic characters.
</msgmbr>

When a dialog refers to a message abca001 (with a GETMSG, SETMSG, DISPLAY,

or TBDISPL service call) or the message is displayed by ISPF during panel
validation, the value of lastn is retrieved and inserted into the message text. The
message after substitution would appear as follows:
Invalid name, “Jones1”, specified.
The name may contain only alphabetic characters.

Conditions
v You must code the VARSUB tag within the text of a MSG definition. See “MSG
(Message)” on page 376 for a complete description of this tag.
v The value specified by the VAR attribute should be declared with a VARDCL
tag. See “VARDCL (Variable Declaration)” on page 463 for a complete
description of this tag.

Nested Tags
None.

466 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 VARSUB
Example
The following markup contains a message member which contains nine MSG
definitions. The text of messages MSGV883 and MSGV888 contain variable
substitutions. Figure 159 shows the generated message member.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=msgcls TYPE='char 20'>

<VARLIST>
<VARDCL NAME=phoneno VARCLASS=msgcls>
<VARDCL NAME=cnum VARCLASS=msgcls>
</VARLIST>

<MSGMBR NAME=msgv88>
<MSG SUFFIX=1>Name must be alphabetic.
<MSG SUFFIX=2>Enter only number of days.
<MSG SUFFIX=3 MSGTYPE=critical>The only rooms we have available
are either SINGLE or DOUBLE. Please call the manager of the hotel
who will arrange equivalent lodging at another
hotel in the area. This is our mistake, and we will, of course,
pick up the bill. Please call collect <VARSUB VAR=phoneno>.
<MSG SUFFIX=4 MSGTYPE=action LOCATION=modal>Please enter either
BIGCHARGE, V I S T A, EZCARD, CHECK, or CASH.
<MSG SUFFIX=5 MSGTYPE=warning LOCATION=modeless>Please enter your name.
<MSG SUFFIX=6>Please enter Y or N.
<MSG SUFFIX=7>Card number is a seven-digit number.
<MSG SUFFIX=8 MSGTYPE=warning>The card number you
entered, <VARSUB VAR=cnum> is not valid.
<MSG SUFFIX=9>Message '9' contains imbedded quotes.
</MSGMBR>

MSGV881 .TYPE=NOTIFY
'Name must be alphabetic.'
MSGV882 .TYPE=NOTIFY
'Enter only number of days.'
MSGV883 .TYPE=CRITICAL
'The only rooms we have available are either SINGLE or DOUBLE. Please call th' +
'e manager of the hotel who will arrange equivalent lodging at another hotel ' +
'in the area. This is our mistake, and we will, of course, pick up the bill. ' +
'Please call collect &PHONENO.'
MSGV884 .TYPE=ACTION .WINDOW=RESP
'Please enter either BIGCHARGE, V I S T A, EZCARD, CHECK, or CASH.'
MSGV885 .TYPE=WARNING .WINDOW=NORESP
'Please enter your name.'
MSGV886 .TYPE=NOTIFY
'Please enter Y or N.'
MSGV887 .TYPE=NOTIFY
'Card number is a seven-digit number.'
MSGV888 .TYPE=WARNING
'The card number you entered, &CNUM is not valid.'
MSGV889 .TYPE=NOTIFY
'Message '9'' contains imbedded quotes.'

Figure 159. Variable Substitution

Chapter 13. Tag Reference 467

WARNING

WARNING (Warning)
The WARNING tag defines text that alerts the user to a risk of possible error
conditions in the system.

ÊÊ <WARNING> </WARNING> ÊÍ
text

text
This is the text of the warning.

Description
The WARNING tag defines text that alerts the user to a risk of possible error
conditions in the system.

The WARNING tag is one of the tags that alert the user of a possible risk; the
others are the CAUTION tag and the ATTENTION tag.

Code a warning statement before the text to which it pertains so that the user can
read about the possible risks before reading the text.

When a warning statement is displayed, the string “Warning:” (or its translated
equivalent) appears on the screen before the text of the warning statement.

You can code additional paragraphs of warning text by coding the P (paragraph)
tag within a WARNING definition. You can also code other tags allowed in an
information area within a WARNING definition.

Conditions
v The WARNING tag requires an end tag.
v You must code the WARNING tag within an INFO definition. See “INFO
(Information Region)” on page 339 for a complete description of this tag.
v The WARNING tag must be immediately preceded by a P, LI, or LP tag. If the
WARNING tag is coded on the same line as one of these tags, there can be no
intervening blanks. See “P (Paragraph)” on page 390, “LI (List Item)” on
page 346, and “LP (List Part)” on page 352 for descriptions of these tags.
v You cannot nest WARNING, ATTENTION, or CAUTION tags within each other.

Nested Tags
You can code the following tags within a WARNING definition:

Tag Name Usage Page Required

DL Definition list Multiple 288 No
FIG Figure Multiple 312 No
HP Highlighted phrase Multiple 336 No
LINES Lines Multiple 349 No
NOTE Note Multiple 382 No
NOTEL Note List Multiple 384 No
NT Note Multiple 386 No

468 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 WARNING
Tag Name Usage Page Required
OL Ordered list Multiple 387 No
P Paragraph Multiple 390 No
PARML Parameter list Multiple 408 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
SL Simple list Multiple 447 No
UL Unordered list Multiple 457 No
XMP Example Multiple 474 No

Example
The following help panel markup contains a warning statement. The warning
statement starts at the left margin because it is imbedded in the LP tag.
<!DOCTYPE DM SYSTEM>

<HELP NAME=warning DEPTH=20>Help For Changing a File

<AREA>
<INFO>
<OL>
<LI>Type over the existing data
in the entry fields with the new data.
<LP><WARNING>Performing the next step will save
all changes and delete the existing data.
<P>To quit this function without
deleting the existing data, press F12.
</WARNING>
<LI>Press Enter to save the
updated data.
</OL>
</INFO>
</AREA>
</HELP>

Help For Changing a File

1. Type over the existing data in the entry

fields with the new data.

Warning: Performing the next step will save all

changes and delete the existing data.

To quit this function without deleting the

existing data, press F12.

2. Press Enter to save the updated data.

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 160. Warning Statement

Chapter 13. Tag Reference 469

XLATI

XLATI (Translate Item)

The XLATI tag defines an individual list element in a translate list.

ÊÊ <XLATI > ÊÍ
VALUE=internal-value displayed-value </XLATI>

VALUE=internal-value
ISPF saves this value in the variable pool when translating on input and
retrieves it from the variable pool when translating on output. If the
internal-value contains characters other than A–Z, a–z, and 0–9, you must
enclose the value in quotes.

Omitting this attribute indicates that any value is acceptable. When translating
on input, ISPF does not translate the displayed-value before storing it in the
pool. When translating on output, ISPF translates to the displayed-value any
value that is not already matched.
displayed-value
This attribute specifies the displayed value that must be matched when doing
a translation on input and the result when doing a translation on output. The
test for a translation match is case-sensitive. Any characters, including
embedded blanks, are allowed in the displayed-value. If the value has blanks
that you want preserved, or the value consists of only blanks, the value should
be coded within the LIT (Literal) tag. If the LIT tag is not used, all blanks will
be stripped and any value with only blanks will indicate that no value was
specified.

Omitting this value indicates that any value is acceptable. When translating on
output, this means that the internal-value is not to be translated before being
displayed. When translating on input, it means that any value not already
matched is to translate to the internal-value.

Description
The XLATI tag defines an individual list element in a translate list. As many
XLATI tags as are necessary (up to a limit of 126) to accomplish the desired
translation can be included within the translation list.

Each XLATI tag provides information necessary to translate a displayed-value to an

internal-value and vice versa. Translation is done in the order given by the tags.
Translation stops when a match is found. An XLATI tag that omits both
internal-value and displayed-value has the following effect: when translating on
output the variable value is displayed, and when translating on input the entered
value is stored in the variable.

The ISPF TRANS() function will be used for all translations. When translating on
output, ISPF )INIT panel logic translates the internal-value to the displayed-value.
When translating on input, ISPF )PROC panel logic translates the displayed-value to
the internal-value. The test for a translation match is case-sensitive. You can code an
XLATL FORMAT=UPPER definition before an XLATL definition that contains
XLATI tags to convert user input to uppercase before the translate list is processed.

470 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 XLATI
Conditions
You must code the XLATI tag within an XLATL definition. See “XLATI (Translate
Item)” on page 470 for a complete description of this tag.

Nested Tags
You can code the following tag within an XLATI definition:

Tag Name Usage Page Required

LIT Literal Multiple 351 No

Example
The following source file markup contains a variable class with a translate list that
performs input and output translation on values assigned to the winter months.
The associated variable declarations and fields are also shown.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=monthcls type='char 3'>

<XLATL FORMAT=upper>
</XLATL>
<XLATL MSG=abcd003>
<XLATI VALUE=11>NOV
<XLATI VALUE=12>DEC
<XLATI VALUE=01>JAN
<XLATI VALUE=02>FEB
<XLATI VALUE=03>MAR
</XLATL>

<VARCLASS NAME=costcls TYPE='numeric 6' MSG=abcd001>

<VARCLASS NAME=typecls TYPE='char 4'>

<XLATL FORMAT=upper>
</XLATL>
<CHECKL MSG=abcd002>
<CHECKI TYPE=values Parm1=EQ Parm2= 'GAS OIL ELEC'>
</CHECKL>

<VARLIST>
<VARDCL NAME=month VARCLASS=monthcls>
<VARDCL NAME=cost VARCLASS=costcls>
<VARDCL NAME=heat VARCLASS=typecls>
</VARLIST>

<PANEL NAME=xlati KEYLIST=keylxmp>Heating Cost Survey

<TOPINST>Complete the information below and then press Enter.
<AREA>
<DTACOL PMTWIDTH=20 DESWIDTH=30>
<DTAFLD DATAVAR=month ENTWIDTH=3>Winter month
<DTAFLDD>Enter Nov, Dec, Jan, Feb, or Mar
<DTAFLD DATAVAR=cost ENTWIDTH=6>Heating cost
<DTAFLD DATAVAR=heat ENTWIDTH=4>Type of heating
<DTAFLDD>Enter Oil, Gas, or Elec
</DTACOL>
</AREA>
<BOTINST>Thank you for your participation.
</PANEL>

<MSGMBR NAME=abcd00>
<MSG SUFFIX=1>Heating cost must be numeric
<MSG SUFFIX=2>Type of heating must be "Gas", "Oil", or "Elec"
<MSG SUFFIX=3>Winter month must be "Nov","Dec", "Jan", "Feb", or "Mar"
</MSGMBR>

Chapter 13. Tag Reference 471

XLATL

XLATL (Translate List)

The XLATL tag defines a translate list for a variable class.

ÊÊ <XLATL Ê
NONE
FORMAT= UPPER
NONE TRUNC = n
char

Ê > </XLATL> ÊÍ
MSG=message-identifier

FORMAT=NONE | UPPER
This attribute defines the type of translation. NONE specifies that enclosed
XLATI tags are to be used to translate the value on an item for item basis.
UPPER specifies that the variable value is translated to uppercase.
TRUNC=n | char
This attribute defines the type of truncation to be performed on input values. It
is valid only when FORMAT=NONE. If a number is provided, truncation
occurs at the length indicated. If a non-numeric character is provided,
truncation occurs at the first occurrence of that character.
MSG=message-identifier
This attribute specifies the ID of a message to be issued for the error condition
that results when an input translation fails because the user entered a value
not specified in the list. Specifying an XLATI tag with no internal-value and no
displayed-value ensures that any value not in the list is accepted without error. If
no message ID is specified and an error occurs, the message-identifier specified
on the VARCLASS tag is used. If no message-identifier is specified on the XLATL
tag or the VARCLASS tag, no message is displayed.

Note: This message is not used if translation on output fails. The variable
value is displayed as is, subject to whatever size restrictions apply to the
field.

Description
The XLATL tag defines a translate list for a variable class. XLATI tags, which
define the elements of the translation list, are coded within the XLATL tag. A
translation list is defined within a VARCLASS tag.

If FORMAT=NONE is specified, it is expected that there are XLATI tags within the
XLATL definition. If FORMAT=UPPER is specified, no XLATI tags are accepted in
the XLATL definition.

Translation lists are optional and provide a means of translating between a

displayed value and the internal value of the variable. Translation can occur on
input (the translation result is stored in the variable pool), on output (the value
from the pool is translated before the user sees it), or both, depending on the
USAGE attribute of the DTAFLD tag that is associated with the variable.
Translation for table display is not supported by ISPF. Refer to the ISPF Dialog
Developer’s Guide and Reference for additional information about the TRANS
function.

472 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 XLATL
Conditions
v The XLATL tag requires an end tag.
v You must code the XLATL tag within a VARCLASS definition. See “VARCLASS
(Variable Class)” on page 459 for a complete description of this tag.
v You must code any and all XLATL tags before any CHECKL tags in the same
variable class.

Nested Tags
You can code the following tag within the XLATL tag:

Tag Name Usage Page Required

XLATI Translate item Multiple 470 Yes

Example
The following source file markup includes translation of user input for monthcls to
uppercase followed by a translation list of the abbreviated month to an internal
value. If no match is found, message abcd003 is issued. The example also shows the
use of uppercase translation before a check for a list of values for Type of heating.
<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=monthcls type='char 3'>

<XLATL FORMAT=upper>
</XLATL>
<XLATL MSG=abcd003>
<XLATI VALUE=11>NOV
<XLATI VALUE=12>DEC
<XLATI VALUE=01>JAN
<XLATI VALUE=01>FEB
<XLATI VALUE=03>MAR
</XLATL>

<VARCLASS NAME=costcls TYPE='numeric 6' MSG=abcd001>

<VARCLASS NAME=typecls TYPE='char 4'>

<XLATL FORMAT=upper>
</XLATL>
<CHECKL MSG=abcd002>
<CHECKI TYPE=values Parm1=EQ Parm2= 'GAS OIL ELEC'>
</CHECKL>

<VARLIST>
<VARDCL NAME=month VARCLASS=monthcls>
<VARDCL NAME=cost VARCLASS=costcls>
<VARDCL NAME=heat VARCLASS=typecls>
</VARLIST>

<PANEL NAME=xlatl KEYLIST=keylxmp>Heating Cost Survey

<TOPINST>Complete the information below and then press Enter.
<AREA>
<DTACOL PMTWIDTH=20 DESWIDTH=30>
<DTAFLD DATAVAR=month ENTWIDTH=3>Winter month
<DTAFLDD>Enter Nov, Dec, Jan, Feb, or Mar
<DTAFLD DATAVAR=cost ENTWIDTH=6>Heating cost
<DTAFLD DATAVAR=heat ENTWIDTH=4>Type of heating
<DTAFLDD>Enter Oil, Gas, or Elec
</DTACOL>
</AREA>
<BOTINST>Thank you for your participation.
</PANEL>

Chapter 13. Tag Reference 473

 XLATL
<MSGMBR NAME=abcd00>
<MSG SUFFIX=1>Heating cost must be numeric
<MSG SUFFIX=2>Type of heating must be "Gas", "Oil", or "Elec"
<MSG SUFFIX=3>Winter month must be "Nov","Dec", "Jan", "Feb", or "Mar"
</MSGMBR>

XMP (Example)
The XMP tag defines unformatted text within an information region.

ÊÊ <XMP > </XMP> ÊÍ

NOSKIP text

| NOSKIP
| This attribute causes the blank line normally placed before the example to be
| skipped.
text
This is the text of the example.

Description
The XMP tag defines unformatted text within an information region.

Text coded between the XMP start and end tags is indented two spaces and
formats from the current left margin. Tags which normally cause word-wrapping
(for example, P and LI) will not cause word-wrapping when nested within an XMP
tag.

When defining text for an example in your source file, you should be careful not to
exceed the width of the information region it is coded within. If the source text on
any line exceeds the formatting width, the conversion utility truncates the line. A
warning message is issued the first time truncation occurs.

Conditions
v The XMP tag requires an end tag.
v You must code the XMP tag within an INFO definition. See “INFO (Information
Region)” on page 339 for a complete description of this tag.
v You can code multiple XMP tags within an INFO definition, as long as they are
not nested within each other.

Nested Tags
You can code the following tags within an XMP definition:

Tag Name Usage Page Required

DL Definition list Multiple 288 No
HP Highlighted phrase Multiple 336 No
NOTE Note Multiple 382 No
NOTEL Note List Multiple 384 No
NT Note Multiple 386 No
OL Ordered list Multiple 387 No
P Paragraph Multiple 390 No

474 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 XMP
Tag Name Usage Page Required
PARML Parameter list Multiple 408 No
PS Point-and-Shoot Multiple 419 No
RP Reference phrase Multiple 430 No
SL Simple list Multiple 447 No
UL Unordered list Multiple 457 No

Example
The following help panel markup contains an example. Figure 161 shows the
formatted result.
<!DOCTYPE DM SYSTEM>

<HELP NAME=xmp WIDTH=40 DEPTH=20>Help for the Search Function

<AREA>
<INFO>
<P>To locate a book, type the book
title in the “Title” field and press Enter.
<P>Example:
<XMP>
Title: THE JOY OF CODING
</XMP>
<P>You don't have to worry about using
upper or lowercase letters; all text is automatically
converted to uppercase for the search.
</INFO>
</AREA>
</HELP>

Help for the Search Function

To locate a book, type the book title

in the "Title" field and press Enter.

Example:

Title: THE JOY OF CODING

You don't have to worry about using

upper or lowercase letters; all text
is automatically converted to
uppercase for the search.

F1=Help F3=Exit F5=Exhelp

F6=Keyshelp F7=PrvTopic F8=NxtTopic
F10=PrvPage F11=NxtPage F12=Cancel

Figure 161. Example

Chapter 13. Tag Reference 475

XMP

476 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Part 3. Appendixes

© Copyright IBM Corp. 1989, 2000 477

478 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Appendix. Dialog Tag Language (DTL) Tags
Tag Summary
The following table is an alphabetic summary of the supported Dialog Tag
Language (DTL) tags for OS/390 V2R10.0 ISPF. The table shows the tag, tells
whether an end tag is required (Yes) or optional (No), and lists the tag’s attributes
(if any) and the tag content (if any) in italics. The table also lists which tags you
can nest within the tag, as well as which tags you can code the tag within.
Table 7. Tag summary
End Nested Used
Tag tag Attributes tags within
AB Yes MNEMGEN=YES | NO ABC PANEL
ABSEPSTR=ab-separator-string
ABSEPCHAR=ab-separator-character
| ABC No HELP=NO | YES | help-panel-name | COMMENT AB
| *help-message-id | %varname | *%varname PDC
| PDCVAR=pdc-variable-name M
| choice-description-text SOURCE
ACTION No RUN=internal-command-name | %varname CHOICE
PARM=parameters | %varname PDC
APPLCMD=NO | YES
TYPE=CMD | PGM | PANEL | WSCMD
| WSCMDV | EXIT
NEWAPPL | NEWAPPL=application-id
NEWWINDOW
PASSLIB
NEWPOOL
SUSPEND
SCRNAME=screen-name
NOCHECK
ADDPOP
OPT=option | %varname
MODE=LINE | FSCR
LANG=APL | CREX
BARRIER
NEST
WSDIR=ws-directory
WSINVOKE=MODELESS | MODAL
WSSIZE=MAX | MIN
WSVIEW=VIS | INVIS
SETVAR=variable-name
VALUE=1 | string | %varname
TOGVAR=variable-name
VALUE1=0 | string | %varname
VALUE2=1 | string | %varname

© Copyright IBM Corp. 1989, 2000 479

Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
AREA Yes MARGINW=1 | n COMMENT HELP
MARGIND=0 DA PANEL
INDENT=n DIVIDER
DEPTH=n | * DTACOL
EXTEND=OFF | ON | FORCE DTAFLD
DIV=NONE | BLANK | SOLID | DASH GA
| TEXT GRPHDR
DIVWIDTH=MAX | MIN INFO
FORMAT=START | CENTER | END LSTFLD
TEXT=divider-text PNLINST
REGION
WIDTH=n SELFLD
DIR=VERT | HORIZ SOURCE
ASSIGNI No VALUE=test-value ASSIGNL
RESULT=assigned-value
ASSIGNL Yes DESTVAR=destination-variable-name ASSIGNI DTAFLD
ATTENTION Yes text DL LI
FIG LP
HP P
LINES
NOTE
NOTEL
NT
OL
P
PARML
PS
RP
SL
UL
XMP

480 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
| ATTR No ATTRCHAR=code DA
| TYPE=DATAIN | DATAOUT | CHAR
| INTENS=HIGH | LOW | NON | %varname
| CAPS=OFF | ON | IN | OUT | %varname
| JUST=ASIS | LEFT | RIGHT | %varname
| PAD=NULLS | USER | char | %varname
| PADC=NULLS | USER | char | %varname
| SKIP=OFF | ON | %varname
| GE=OFF | ON | %varname
| COLOR=WHITE | RED | BLUE | GREEN |
| PINK | YELLOW | TURQ | %varname
| HILITE=USCORE | BLINK | REVERSE |
| %varname
| NUMERIC=OFF | ON | %varname
| FORMAT=EBCDIC | DBCS | MIX | %varname
| OUTLINE=NONE | L | R | O | U | BOX |
| %varname
| PAS=OFF | ON | %varname
| CKBOX=OFF | ON | %varname
| CUADYN=CEF | EE | LEF | NEF | VOI
| | LID | LI | CH | CT | DT | ET | FP
| | NT | PIN | PT | SAC | SI | SUC
| | WASL | WT | %varname
| CSRGRP=NO | YES | n
| ATTN=OFF | ON | %varname
BOTINST No COMPACT HP PANEL
instruction-text PS
RP
CAUTION Yes text DL LI
FIG LP
HP P
LINES
NOTE
NOTEL
NT
OL
P
PARML
PS
RP
SL
UL
XMP
CHDIV No TYPE=NONE | SOLID | DASH | TEXT HP SELFLD
GUTTER=1 | n CHOICE
FORMAT=START | CENTER | END
divider-text

Appendix. Dialog Tag Language (DTL) Tags 481

 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
| CHECKI No TYPE= CHECKL
| RANGE
| PARM1=low-bound | %varname
| PARM2=high-bound | %varname
| ALPHA
| CHARS
| PARM1=EQ
| PARM2=character-set
| VALUES
| PARM1=EQ
| PARM2=value-list
| VALUESX
| PARM1=NE
| PARM2=value-list
| BIT
| NAME
| NAMEF
| PICT
| PARM1=EQ
| PARM2=pictstring
| PICTCN
| PARM1=mask-character
| PARM2=field-mask
| PARM3=string
| NUM
| DBCS
| LISTV
| PARM1=EQ
| PARM2=%varlist
| LISTVX
| PARM1=NE
| PARM2=%varlist
| ALPHAB
| LEN
| PARM1=operator | %varname
| PARM2=length | %varname
| EBCDIC
| ENUM
| DSNAME
| DSNAMEF
| DSNAMEFM
| DSNAMEPQ
| DSNAMEQ
| MIX
| HEX
| FILEID
| INCLUDE
| PARM1=IMBLK
| PARM2=ALPHA | ALPHAB | NUM
| PARM3=ALPHA | ALPHAB | NUM
| IDATE
| STDDATE
| JDATE
| JSTD
| ITIME
| STDTIME

482 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
CHECKL Yes MSG=message-identifier CHECKI VARCLASS
| CHOFLD No DATAVAR=field-data ACTION CHOICE
| VARCLASS=variable-class-name CHDIV
| HELP=NO | YES | help-panel-name | COMMENT
| *help-message-id | %varname | *%varname HP
| USAGE=BOTH | IN | OUT PS
| REQUIRED=NO | YES RP
| MSG=message-identifier SOURCE
| AUTOTAB=NO | YES
| ENTWIDTH=n
| FLDSPACE=n
| ALIGN=START | CENTER | END
| DISPLAY=YES | NO
| NOENDATTR
| PAD=NULLS | USER | char | %varname
| PADC=NULLS | USER | char | %varname
| OUTLINE=NONE | L | R | O | U | BOX |
| %varname
| PSVAR=point-and-shoot-variable | %varname
| PSVAL=point-and-shoot-value | %varname
| PAS=%varname
| EXPAND
| ATTRCHANGE=NO | YES | NEW
| INIT=initial-value
| IMAPNAME=image-name | %varname
| IMAPNAMEP=image-namep | %varname
| PLACE=ABOVE | BELOW | LEFT
| | RIGHT | %varname
| ATTRCHAR=code
| CAPS=OFF | ON
| choice-description-text
| CHOICE No NAME=choice-name ACTION SELFLD
| HELP=NO | YES | help-panel-name | CHDIV
| *help-message-id | %varname | *%varname CHOFLD
| CHECKVAR=variable-name COMMENT
| MATCH=1 | string HP
| NOMATCH=0 | string PS
| AUTOTAB=YES | NO RP
| SELCHAR=’char(s),n’ SOURCE
| PAD=NULLS | USER | char | %varname
| PADC=NULLS | USER | char | %varname
| OUTLINE=NONE | L | R | O | U | BOX |
| %varname
| HIDE
| HIDEX
| UNAVAIL=variable-name
| UNAVAILMAT=1 | string
| TRUNC=n
| AUTOSEL=YES | NO
| choice-description-text
CMD No NAME=internal-command-name CMDACT CMDTBL
ALTDESCR=command-description T
external-command-name

Appendix. Dialog Tag Language (DTL) Tags 483

 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
CMDACT No ACTION= CMD
’SELECT=select-parameters’
’ALIAS=internal-command-name parameters’
PASSTHRU
SETVERB
BACKWARD
CANCEL
EXIT
EXHELP
FKA
FORWARD
HELP
PANELID
RETRIEVE
%varname
Application-command
ASIS
| CMDAREA No HELP=NO | YES | help-panel-name | HP PANEL
| *help-message-id | %varname | *%varname
| PMTLOC=BEFORE
| NOINIT
| PAD=NULLS | USER | char | %varname
| PADC=NULLS | USER | char | %varname
| OUTLINE=NONE | L | R | O | U | BOX |
| %varname
| NAME=cmdarea-variable-name
| ENTWIDTH=n
| PMTTEXT=YES | NO
| CMDLOC=DEFAULT | ASIS
| CMDLEN=DEFAULT | MAX
| AUTOTAB=NO | YES
| SCROLLVAR=scroll-variable
| SCRVHELP=NO | YES | scroll-help-panel-name
| |*scroll-help-message-id | %varname
| | *%varname
| SCROLLTAB=NO | YES
| PSBUTTON=cmd-pb-text
| PSVAR=point-and-shoot-variable | %varname
| PSVAL=point-and-shoot-value | %varname
| IMAPNAME=image-name | %varname
| IMAPNAMEP=image-namep | %varname
| PLACE=ABOVE | BELOW | LEFT
| | RIGHT | %varname
| CAPS=OFF | ON
| SCRCAPS=OFF | ON
| NOJUMP=OFF | ON
| command-prompt-text
CMDTBL Yes APPLID=application-identifier CMD
SORT=NO | YES

484 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
COMMENT No TYPE=END | CCSID | PANEL | ATTR | ABC
ABCINIT | ABCPROC | INIT | REINIT | AREA
PROC | HELP | PNTS | LIST CHOICE
comment-text DA
DTACOL
DTAFLD
HELP
LSTCOL
LSTFLD
LSTGRP
MSGMBR
PANEL
PDC
REGION
SELFLD
COMPOPT No REPLACE | NOREPLACE None
SCREEN | DISK
NODBCS | DBCS
NOKANA | KANA
KEYLAPPL=xxxx
NOPANEL | PANEL
NOMSGSUPP | MSGSUPP
NOCUASUPP | CUASUPP
PREP | NOPREP
CUAATTR | NOCUAATTR
NOLSTVIEW | LSTVIEW
STATS | NOSTATS
NOSCRIPT | SCRIPT
NOLISTING | LISTING
NOFORMAT | FORMAT
NOMSGEXPAND | MSGEXPAND
LOGREPL | NOLOGREPL
LISTREPL | NOLISTREPL
ACTBAR | NOACTBAR
GUI | NOGUI
VERSION | NOVERSION
NOMERGESAREA | MERGESAREA
NODISPLAY | DISPLAY
NODISPLAYW | DISPLAYW
DSNCHK | NODSNCHK
GRAPHIC | NOGRAPHIC
ZVARS | NOZVARS
NODBALIGN | DBALIGN
NOMCOMMENT | MCOMMENT
RESET
national-language
COPYR No copyright-text

Appendix. Dialog Tag Language (DTL) Tags 485

 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
| DA Yes NAME=varname ATTR AREA
| EXTEND=OFF | ON | FORCE COMMENT PANEL
| LVLINE=variable-name SOURCE REGION
| SCROLL=OFF | ON | CMDLINE
| USERMOD=usermod-code | %varname
| DATAMOD=datamod-code | %varname
| DEPTH=n | *
| WIDTH=n
| SHADOW=shadow-name
| DIV=NONE | BLANK | SOLID | DASH
| | TEXT | FORMAT=START | CENTER | END
| TEXT=divider-text
| SCROLLVAR=scroll-variable
| SCRVHELP=NO | YES | scroll-help-panel-name
| |*scroll-help-message-id | %varname
| | *%varname
| SCROLLTAB=NO | YES
| SCRCAPS=OFF | ON
| INITATTR=NT | CT | ET | WT | WASL
| HELP=NO | YES | help-panel-name |
| *help-message-id | %varname | *%varname
|
DD No definition-description DL DL
FIG
HP
LINES
NOTE
NOTEL
NT
OL
P
PARML
PS
RP
SL
UL
XMP
DDHD No definition-description-header HP DL
PS
RP
DIVIDER No TYPE=NONE | SOLID | DASH | TEXT HP AREA
GAP=YES | NO DTACOL
GUTTER=1 | n PANEL
NOENDATTR REGION
FORMAT=START | CENTER | END
divider-text

486 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
DL Yes TSIZE=10 | n DD ATTENTION
BREAK=NONE | FIT | ALL DDHD CAUTION
COMPACT DT DD
NOSKIP DTHD FIG
INDENT=n INFO
LI
LINES
LP
NT
PD
WARNING
XMP
DT No definition-term HP DL
PS
RP
| DTACOL Yes PMTWIDTH=n | * | ** COMMENT AREA
| ENTWIDTH=n DIVIDER PANEL
| DESWIDTH=n | * DTAFLD REGION
| SELWIDTH=n | * GRPHDR
| FLDSPACE=n SELFLD
| PAD=NULLS | USER | char | %varname SOURCE
| PADC=NULLS | USER | char | %varname
| OUTLINE=NONE | L | R | O | U | BOX |
| %varname
| PMTFMT=CUA | ISPF | NONE | END
| AUTOTAB=NO | YES
| ATTRCHANGE=NO | YES | NEW
| PMTLOC=BEFORE | ABOVE
| DBALIGN=YES | NO | PROMPT | FIELD |
| FORCE
| VARCLASS=variable-class-name
| REQUIRED=NO | YES
| CAPS=OFF | ON

Appendix. Dialog Tag Language (DTL) Tags 487

 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
| DTAFLD No NAME=field-name ASSIGNL AREA
| DATAVAR=field-data COMMENT DTACOL
| VARCLASS=variable-class-name DTAFLDD PANEL
| HELP=NO | YES | help-panel-name | HP REGION
| *help-message-id | %varname | *%varname PS
| USAGE=BOTH | IN | OUT RP
| REQUIRED=NO | YES SOURCE
| MSG=message-identifier
| AUTOTAB=NO | YES
| ENTWIDTH=n
| PMTWIDTH=n | * | **
| DESWIDTH=n | *
| FLDSPACE=n
| ALIGN=START | CENTER | END
| PMTLOC=BEFORE | ABOVE
| DISPLAY=YES | NO
| NOENDATTR
| PAD=NULLS | USER | char | %varname
| PADC=NULLS | USER | char | %varname
| OUTLINE=NONE | L | R | O | U | BOX |
| %varname
| PMTFMT=CUA | ISPF | NONE | END
| PSVAR=point-and-shoot-variable | %varname
| PSVAL=point-and-shoot-value | %varname
| PAS=%varname
| CSRGRP=NO | YES | n
| EXPAND
| FLDWIDTH=n
| ATTRCHANGE=NO | YES | NEW
| INIT=initial-value
| DEPTH=n | %varname
| IMAPNAME=image-name | %varname
| IMAPNAMEP=image-namep | %varname
| PLACE=ABOVE | BELOW | LEFT |
| RIGHT | %varname
| DBALIGN=YES | NO | PROMPT | FIELD |
| FORCE
| PMTSKIP=NO | YES
| DESSKIP=NO | YES
| FLDTYPE=CUA | ISPF
| COLOR=WHITE | RED | BLUE | GREEN |
| PINK | YELLOW | TURQ | %varname
| INTENS=HIGH | LOW | NON | %varname
| HILITE=USCORE | BLINK | REVERSE |
| %varname
| ATTRCHAR=code
| CAPS=OFF | ON
| NOJUMP=OFF | ON
| prompt-text
DTAFLDD No description HP DTAFLD
PS
RP
DTHD No definition-term-header HP DL
PS
RP

488 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
| FIG Yes FRAME=RULE | NONE DL ATTENTION
| WIDTH=PAGE | COL FIGCAP CAUTION
| NOSKIP HP DD
| figure-content NOTE INFO
| NOTEL LI
| NT LP
| OL NT
| P PD
| PARML WARNING
| PS
| RP
| SL
| UL
| XMP
FIGCAP No figure-caption-text HP FIG
PS
RP
GA No NAME=graphic-area-name AREA
EXTEND=OFF | ON | FORCE PANEL
DEPTH=n | * REGION
WIDTH=n
DIV=NONE | BLANK | SOLID | DASH
| TEXT
FORMAT=START | CENTER | END
TEXT=divider-text
LVLINE=variable-name
| GENERATE Yes ATTR AREA
| COMMENT HELP
| SOURCE PANEL
| REGION
GRPHDR No FORMAT=START | CENTER | END | NONE HP AREA
WIDTH=n PS DTACOL
FMTWIDTH=n RP PANEL
HEADLINE=NO | YES REGION
DIV=NONE | BLANK | SOLID | DASH
DIVLOC=AFTER | BEFORE | BOTH
COMPACT
STRIP
group-heading-text

Appendix. Dialog Tag Language (DTL) Tags 489

Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
HELP Yes NAME=help-panel-name AREA
HELP=hhelp-panel-name | %varname COMMENT
HELPDEF=helpdef-id DIVIDER
WIDTH=50 | n | FIT HP
DEPTH=10 | n | FIT INFO
CCSID=n REGION
TUTOR SOURCE
KEYLIST=key-list-name
KEYLTYPE=PRIVATE | SHARED
APPLID=application-id
EXPAND=xy
WINTITLE=window-title
APPTITLE=application-title
MERGESAREA=NO | YES
MSGLINE=YES | NO
IMAPNAME=image-name | %varname
IMAPROW=n | %varname
IMAPCOL=n | %varname
help-panel-title
HELPDEF No ID=helpdef-id
HELP=hhelp-panel-name | %varname
WIDTH=n | FIT
DEPTH=n | FIT
CCSID=n
KEYLIST=key-list-name
KEYLTYPE=PRIVATE | SHARED
APPLID=application-id
EXPAND=xy
WINTITLE=window-title
APPTITLE=application-title
MERGESAREA=NO | YES
IMAPNAME=image-name | %varname
IMAPROW=n | %varname
IMAPCOL=n | %varname
H1 No heading-text INFO
H2/H3/H4 No heading-text HP INFO
PS
RP

490 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
HP Yes TYPE=ET | CH | CT | FP | LEF | LI ATTENTION
| NT | PT | SAC | TEXT | WASL | WT BOTINST
COLOR=WHITE | RED | BLUE | GREEN | CAUTION
PINK | YELLOW | TURQ | %varname CHDIV
INTENS=HIGH | LOW | NON | %varname CHOICE
HILITE=USCORE | BLINK | REVERSE | CMDAREA
%varname DD
phrase-to-be-highlighted DDHD
DIVIDER
DT
DTAFLD
DTAFLDD
DTHD
FIG
FIGCAP
GRPHDR
H2
H3
H4
HELP
LI
LINES
LP
LSTCOL
LSTGRP
NOTE
NT
P
PANEL
PD
PNLINST
PT
SELFLD
TOPINST
WARNING
XMP
INFO Yes WIDTH=format-width | * DL AREA
INDENT=n FIG HELP
Hn PANEL
LINES REGION
NOTE
NOTEL
NT
OL
P
PARML
SL
UL
XMP
KEYI No KEY=virtual-key KEYL
CMD=internal-command-name
CASE=UPPER | MIXED
FKA=NO | YES | LONG | SHORT
PARM=parm-string
FKA-text

Appendix. Dialog Tag Language (DTL) Tags 491

 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
KEYL Yes NAME=key-list-name KEYI
HELP=help-panel-name
ACTION=UPDATE | DELETE
APPLID=application-id
LI No SPACE=NO | YES ATTENTION NOTEL
NOSKIP CAUTION OL
item-text DL SL
FIG UL
HP
LINES
NOTE
NOTEL
NT
OL
P
PARML
PS
RP
SL
UL
WARNING
XMP
| LINES Yes NOSKIP DL ATTENTION
| text HP CAUTION
| NOTE DD
| NOTEL INFO
| NT LI
| OL LP
| P NT
| PARML PD
| PS WARNING
| RP
| SL
| UL
| XMP
LIT Yes literal-display-value XLATI
LP No NOSKIP ATTENTION NOTEL
implied-paragraph CAUTION OL
DL SL
FIG UL
HP
LINES
NOTE
NOTEL
NT
OL
P
PARML
PS
RP
SL
UL
WARNING
XMP

492 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
| LSTCOL No DATAVAR=column-data COMMENT LSTFLD
| VARCLASS=variable-class-name HP LSTGRP
| HELP=NO | YES | help-panel-name | PS
| * help-message-id | %varname | *%varname RP
| USAGE=BOTH | IN | OUT SOURCE
| REQUIRED=NO | YES
| MSG=message-id
| COLWIDTH=data-width
| ALIGN=START | CENTER | END
| AUTOTAB=NO | YES
| LINE=n
| CLEAR
| POSITION=n
| FORMAT=START | CENTER | END
| TEXT=descriptive-text
| TEXTLOC=BEFORE | AFTER
| TEXTFMT=START | CENTER | END
| TEXTLEN=n
| TEXTSKIP=NO | YES
| NOENDATTR
| PAD=NULLS | USER | char | %varname
| PADC=NULLS | USER | char | %varname
| OUTLINE=NONE | L | R | O | U | BOX |
| %varname
| PAS=OFF | ON | %varname
| CSRGRP=NO | YES | n
| ATTRCHANGE=NO | YES | NEW
| COLSPACE=n
| COLTYPE=CUA | ISPF | EE | VOI | LID
| COLOR=WHITE | RED | BLUE | GREEN |
| PINK | YELLOW | TURQ | %varname
| INTENS=HIGH | LOW | NON | %varname
| HILITE=USCORE | BLINK | REVERSE |
| %varname
| CAPS=OFF | ON
| DISPLAY=YES | NO
| column-heading
| LSTFLD Yes RULES=NONE | HORIZ | VERT | BOTH COMMENT AREA
| ROWS=NOSCAN | SCAN | %varname LSTCOL PANEL
| DIV=NONE | BLANK | SOLID | DASH | char LSTGRP REGION
| SCROLLVAR=scoll-variable LSTVAR
| SCRVHELP=NO | YES | scroll-help-panel-name SOURCE
| |*scroll-help-message-id | %varname
| | *%varname
| SCROLLTAB=NO | YES
| SCRCAPS=OFF | ON
| ATTRCHANGE=NO | YES | NEW
LSTGRP Yes HEADLINE=NO | YES | DASH COMMENT LSTFLD
ALIGN=CENTER | START | END HP LSTGRP
column-group-heading LSTCOL
LSTGRP
LSTVAR
PS
RP
SOURCE

Appendix. Dialog Tag Language (DTL) Tags 493

 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
LSTVAR No DATAVAR=variable-model-name COMMENT LSTFLD
LINE=n HP LSTGRP
column-heading PS
RP
SOURCE
M No mnemonic-character ABC
PDC
| MSG No SUFFIX=message-suffix-number VARSUB MSGMBR
| HELP=help-panel-name | %varname | *
| MSGTYPE=INFO | WARNING | ACTION
| | CRITICAL | %varname
| LOCATION=AREA | MODAL | MODAL(L) |
| MODELESS | MODELESS (L) | %varname
| DISP=KANA | NOKANA
| ALARM=NO | YES | %varname
| ABBREV=NONE | KEYWORD | VALUE
| | BOTH
| FORMAT=FLOW | ASIS
| SMSG=short-message-text
| message-text
| MSGMBR Yes NAME=message-member-name COMMENT
| CCSID=n MSG
| WIDTH=76 | 68
NOTE No TEXT=alternate-note-heading HP ATTENTION
note-text PS CAUTION
RP DD
FIG
INFO
LI
LINES
LP
PD
WARNING
XMP
NOTEL Yes COMPACT LI ATTENTION
NOSKIP LP CAUTION
SPACE=NO | YES DD
INDENT=n FIG
TEXT=alternate-note-heading INFO
LI
LINES
LP
PD
WARNING
XMP

494 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
NT Yes TEXT=alternate-note-heading DL ATTENTION
note-text FIG CAUTION
HP DD
LINES FIG
OL INFO
P LI
PARML LINES
PS LP
RP PD
SL WARNING
UL XMP
XMP
OL Yes COMPACT LI ATTENTION
NOSKIP LP CAUTION
SPACE=NO | YES DD
INDENT=n FIG
TEXT=OL-heading-text INFO
LI
LINES
LP
NT
PD
WARNING
XMP
P No COMPACT ATTENTION ATTENTION
INTENSE=varname CAUTION CAUTION
INDENT=n HP DD
paragraph-text PS FIG
RP INFO
WARNING LI
LINES
LP
NT
PD
WARNING
XMP

Appendix. Dialog Tag Language (DTL) Tags 495

Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
PANDEF No ID=pandef-id
HELP=help-panel-name | %varname
DEPTH=n | FIT
WIDTH=n | FIT | %varname
KEYLIST=key-list-name
KEYLTYPE=PRIVATE | SHARED
APPLID=application-id
CCSID=n
WINDOW=YES | NO
WINTITLE=window-title
APPTITLE=application-title
PAD=NULLS | USER | char | %varname
PADC=NULLS | USER | char | %varname
OUTLINE=NONE | L | R | O | U | BOX |
%varname
EXPAND=xy
MERGESAREA=NO | YES
ENTKEYTEXT=enter-key-text
IMAPNAME=image-name | %varname
IMAPROW=n | %varname
IMAPCOL=n | %varname
TMARGIN=n
BMARGIN=n

496 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
| PANEL Yes NAME=panel-name AB
| HELP=help-panel-name | %varname AREA
| PANDEF=pandef-id BOTINST
| DEPTH=22 | n | FIT CMDAREA
| WIDTH=76 | n | FIT | %varname COMMENT
| KEYLIST=key-list-name DA
| KEYLTYPE=PRIVATE | SHARED DIVIDER
| APPLID=application-id DTACOL
| CURSOR=cursor-field DTAFLD
| CSRINDEX=index-value GA
| CSRPOS=position-value GRPHDR
| CCSID=n HP
| MENU INFO
| PRIME LSTFLD
| TUTOR PNLINST
| WINDOW=YES | NO REGION
| WINTITLE=window-title SELFLD
| APPTITLE=application-title TOPINST
| PAD=NULLS | USER | char | %varname
| PADC=NULLS | USER | char | %varname
| OUTLINE=NONE | L | R | O | U | BOX |
| %varname
| EXPAND=xy
| MSGLINE=YES | NO
| TITLINE=YES | NO
| CMDLINE=YES | NO
| ATTRUSE=NO | YES | ALL
| ENDATTR=DEFAULT | TEXT
| TYPE=BOTH | GUI | NOGUI
| SMSG=short-msg-fieldname
| LMSG=long-msg-fieldname
| ASIS
| ACTBAR
| MERGESAREA=NO | YES
| PANELSTMT=YES | NO
| ENTKEYTEXT=enter-key-text
| IMAPNAME=image-name | %varname
| IMAPROW=n | %varname
| IMAPCOL=n | %varname
| TMARGIN=n
| BMARGIN=n
| ERRORCHECK=NO | YES
| panel-title-text
PARML Yes TSIZE=10 | n PT ATTENTION
BREAK=ALL | FIT | NONE PD CAUTION
COMPACT DD
INDENT=n FIG
INFO
LI
LINES
LP
NT
PD
WARNING
XMP

Appendix. Dialog Tag Language (DTL) Tags 497

 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
PD No parameter-description DL PARML
FIG
HP
LINES
NOTE
NOTEL
NT
OL
P
PARML
PS
RP
SL
UL
XMP
| PDC No HELP=NO | YES | help-panel-name | ACTION ABC
| *help-message-id | %varname | *%varname COMMENT
| UNAVAIL=unavail-variable-name M
| CHECKVAR=check-variable-name SOURCE
| MATCH=1 | match-string
| ACC1=key1
| ACC2=key2
| ACC3=key3
| pull-down-description-text
PDSEP No PDC
PNLINST No COMPACT HP AREA
instruction-text PS REGION
RP PANEL

498 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
PS Yes VAR=point-and-shoot-variable-name | %varname ATTENTION
VALUE=point-and-shoot-value | %varname | * BOTINST
CSRGRP=NO | YES | n CAUTION
DEPTH=n | %varname CHOFLD
IMAPNAME=image-name | %varname CHOICE
IMAPNAMEP=image-namep | %varname DD
PLACE=ABOVE | BELOW | LEFT | DDHD
RIGHT | %varname DT
point-and-shoot-text DTAFLD
DTAFLDD
DTHD
FIG
FIGCAP
GRPHDR
H2
H3
H4
LI
LINES
LP
LSTCOL
LSTGRP
NOTE
NT
P
PD
PNLINST
PT
SELFLD
TOPINST
WARNING
XMP
PT No parameter-term HP PARML
PS
RP
REGION Yes DIR=VERT | HORIZ COMMENT AREA
INDENT=n DA HELP
WIDTH=n | * DIVIDER PANEL
DEPTH=n | * DTACOL REGION
EXTEND=OFF | ON | FORCE DTAFLD
ALIGN=YES | NO GA
GRPBOX=NO | YES GRPHDR
GRPWIDTH=n INFO
GRPBXVAR=variable-name LSTFLD
GRPBXMAT=1 | string PNLINST
LOCATION=DEFAULT | TITLE REGION
group-box-title SELFLD

Appendix. Dialog Tag Language (DTL) Tags 499

 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
| RP Yes HELP= help-panel-name | help-message-id ATTENTION
| | %varname | *%varname BOTINST
| reference-phrase CAUTION
| CHOFLD
| CHOICE
| DD
| DDHD
| DT
| DTAFLD
| DTAFLDD
| DTHD
| FIG
| FIGCAP
| GRPHDR
| H2
| H3
| H4
| LI
| LINES
| LP
| LSTCOL
| LSTGRP
| NOTE
| NT
| P
| PD
| PNLINST
| PT
| SELFLD
| TOPINST
| WARNING
| XMP

500 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
| SELFLD Yes NAME=field-name CHDIV AREA
| HELP=NO | YES | help-panel-name | CHOICE DTACOL
| *help-message-id | %varname | *%varname COMMENT PANEL
| TYPE=SINGLE | MULTI | MENU | MODEL | HP REGION
| TUTOR PS
| PMTLOC=ABOVE | BEFORE RP
| PMTWIDTH=n | * | ** SOURCE
| SELWIDTH=n | *
| ENTWIDTH=2 | n | ’e1 e2...en’
| REQUIRED=NO | YES
| MSG=message-identifier
| FCHOICE=1 | 0
| AUTOTAB=YES | NO
| DEPTH=n | *
| EXTEND=OFF | ON | FORCE
| TRAIL=’trail-var-1 trail-var-2 ... trail-var-n’
| CHOICECOLS=1 | n
| CHOICEDEPTH=n | *
| CWIDTHS=’w1 w2...wn’
| PAD=NULLS | USER | char | %varname
| PADC=NULLS | USER | char | %varname
| OUTLINE=NONE | L | R | O | U | BOX |
| %varname
| SELMSG=selfld-msg-identifier
| SELMSGU=selfld-msg-unavailable
| INIT=YES | NO
| VERIFY=YES | NO
| REFRESH=YES | NO
| SELFMT=START | END
| CHKBOX=YES | NO
| ZGUI=YES | NO
| CSRGRP=NO | YES | n
| TSIZE=’s1 s2...sn’
| LISTTYPE=RADIO | LISTBOX | DDLIST |
| COMBO
| LISTREF=list-name
| LISTDEPTH=n
| DBALIGN=YES | NO | FIELD | FORCE
| NOSEL=no-selection-value
| SELDEFAULT=x
| PMTSKIP=NO | YES
| FLDTYPE=CUA | ISPF
| COLOR=WHITE | RED | BLUE | GREEN |
| PINK | YELLOW | TURQ | %varname
| INTENS=HIGH | LOW | NON | %varname
| HILITE=USCORE | BLINK | REVERSE |
| %varname
| field-prompt-text

Appendix. Dialog Tag Language (DTL) Tags 501

 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
SL Yes COMPACT LI ATTENTION
NOSKIP LP CAUTION
SPACE=NO | YES DD
INDENT=n FIG
TEXT=’SL-heading-text’ INFO
LI
LINES
LP
NT
PD
WARNING
XMP
SOURCE Yes TYPE=PROC | REINIT | INIT | ABCINIT | ABC
ABCPROC AREA
text CHOICE
DA
DTACOL
DTAFLD
HELP
LSTCOL
LSTFLD
LSTGRP
PANEL
PDC
REGION
SELFLD
T No CMD
| TEXTLINE Yes TEXTSEG HELP
| PANEL
| TEXTSEG No EXPAND=AFTER | BEFORE | BOTH HP TEXTLINE
| WIDTH=n
| text
TOPINST No COMPACT HP PANEL
instruction-text PS
RP
UL Yes COMPACT LI ATTENTION
NOSKIP LP CAUTION
SPACE=NO | YES DD
INDENT=n FIG
TEXT=UL-heading-text INFO
LI
LINES
LP
NT
PD
WARNING
XMP

502 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
 Summary of DTL Tags
Table 7. Tag summary (continued)
End Nested Used
Tag tag Attributes tags within
VARCLASS No NAME=variable-class-name CHECKL
TYPE=’CHAR maximum length’ XLATL
’DBCS maximum length’
’MIXED maximum length’
’ANY maximum length’
’EBCDIC maximum length’
’%varname maximum length’
ITIME
STDTIME
IDATE
STDDATE
JDATE
JSTD
’VMASK maximum-length’
’NUMERIC total-digits 0 | fractional-digits’
MSG=message-identifier
VARDCL No NAME=name VARLIST
VARCLASS=variable-class-name
VARLIST Yes VARDCL
VARSUB No VAR=variable-name MSG
WARNING Yes text DL LI
FIG LP
HP P
LINES
NOTE
NOTEL
NT
OL
P
PARML
PS
RP
SL
UL
XMP
XLATI No VALUE=internal-value LIT XLATL
displayed-value
| XLATL Yes FORMAT=NONE | UPPER XLATI VARCLASS
| TRUNC=n | char
| MSG=message-identifier
|
XMP Yes NOSKIP DL ATTENTION
text HP CAUTION
NOTE DD
NOTEL FIG
NT INFO
OL LI
P LINES
PARML LP
PS NT
RP PD
SL WARNING
UL

Appendix. Dialog Tag Language (DTL) Tags 503

Summary of DTL Tags

504 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Notices
This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user’s responsibility to evaluate and verify the
operation of any non_IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you
any license to these patents. You can send license inquiries, in writing, to the IBM
Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY
10504–1785, USA.

For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries in writing to

IBM World Trade Asia Corporation

Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS

PUBLICATION ″AS IS″ WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OR NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply
to you.

This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.

© Copyright IBM Corp. 1989, 2000 505

 Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact the IBM Corporation,
Department TL3B, 3039 Cornwallis Road, Research Triangle Park, North Carolina,
27709–2195, USA. Such information may be available, subject to appropriate terms
and conditions, including in some cases, payment of a fee.

The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.

Information concerning non-IBM products was obtained from the suppliers of

those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non_IBM products should be addressed to the
suppliers of those products.

If you are viewing this information softcopy, the photographs and color
illustrations may not appear.

Programming Interface Information

This book primarily documents information that is NOT intended to be used as
Programming Interfaces of ISPF.

This book also documents intended Programming Interfaces that allow the
customer to write programs to obtain the services of ISPF. This information is
identified where it occurs, either by an introductory statement to a chapter or
section or by the following marking:
-----------Programming Interface information----------------

Trademarks
The following terms are trademarks of International Business Machines
Corporation in the United States, other countries, or both:

BookManager Language Environment

C++ MVS
DFSMSdfp MVS/ESA
DFSMSdss OS/2
DFSMShsm OS/390
DFSMSrmm OS/390 Security Server
DFSMS/MVS RACF
DFSORT Resource Access Control Facility
ESCON SOMobjects
FFST System View
GDDM VisualLift
IBM VTAM

Microsoft and Windows are registered trademarks of Microsoft Corporation in the

United States, other countries, or both.

506 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
UNIX is a registered trademark of The Open Group in the United States and other
countries.

Other company, product, and service names may be trademarks or service marks
of others.

Notices 507
508 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
Index
Special Characters ACTION attribute (continued)
value FKA on CMDACT tag 262
ALTDESCR attribute on CMD tag 259
APPLCMD attribute on ACTION
% keyword value FORWARD on CMDACT tag 209
on ENTITY statement 194 tag 262 application command table 157
% notation 12 value HELP on CMDACT tag 262 defining commands 157
value PANELID on CMDACT defining with CMDTBL tag 157
tag 262
A value PASSTHRU on CMDACT
overview 8
application-id
AB (action bar) tag 36 tag 262
conditions of usage 202 value RETRIEVE on CMDACT ISPx 157
defining an action bar 34 tag 262 option 177
description 202 value SELECT on CMDACT tag 261 using with CMDTBL tag 157
examples value SETVERB on CMDACT application panel
adding HELP attribute 36 tag 262 action bar 6
application panel markup 203 action bar 36 bottom instruction 6
defining help panel 37 defining 34 command area 7
markup 35 description 6 defining a command area 51
using mnemonic selection 38 providing help for 36 defining a panel ID 28
how to code 35 action bar (AB) tag defining a region 47
syntax 201 conditions of usage 202 defining action bar and
ABBREV attribute description 202 pull-downs 34
on MSG tag 378 examples 203 defining an area divider 46
ABC (action bar choice) tag syntax 201 defining common attributes and
conditions of usage 205 action bar choice 36 values 53
description 205 action bar choice (ABC) tag defining common elements 27
examples conditions of usage 205 defining cursor placement 30
defining help panel 37 description 205 defining panel width and depth 29
markup 35 examples 205 defining the panel title 28
PDCVAR attribute 205 syntax 204 defining top and bottom
using mnemonic selection 38 action message instructions 39
syntax 204 defining 153 defining with the PANEL tag 27
ABSEPCHAR attribute on AB tag 202 description 153 description of PANEL tag 405
ABSEPSTR attribute on AB tag 202 ADDPOP attribute on ACTION tag 210 examples of PANEL tag 406
ACC1 attribute on PDC tag 413 ALARM attribute function key area 7
ACC2 attribute on PDC tag 413 on MSG tag 378 layout 5
ACC3 attribute on PDC tag 413 overview 5
alerting users
accelerator attributes on PDC tag 413 panel body 6
using the ATTENTION tag 132
ACTBAR attribute on PANEL tag 404 panel title 6
using the CAUTION tag 132
ACTBAR option 179 providing help for 29
using the NT tag 132
ACTION (action) tag specifying a key mapping list 29
using the WARNING tag 132
conditions of usage 212 syntax for PANEL tag 397
ALIAS command action
description 211 top instruction 6
examples defining 159
description 159 APPLID attribute
defining help panel 37 description 157
markup 35 ALIGN attribute
on CHOFLD tag 247 on CMDTBL tag 270
PDC tags and SETVAR on HELP TAG 326
attribute 212 on DTAFLD tag 304
on LSTCOL tag 357 on HELPDEF TAG 333
using mnemonic selection 38 on KEYL TAG 345
for pull-down choice 35 on LSTGRP tag 369
on REGION tag 425 on PANDEF TAG 394
syntax 207 on PANEL TAG 401
ACTION attribute using 84
ALPHA test APPTITLE attribute
on CMDACT tag 261
on KEYL tag 345 description 67 on HELP TAG 327
value ALIAS on CMDACT tag 261 example 67 on HELPDEF TAG 333
value application-command on specifying on CHECKI tag 236 on PANDEF tag 394
CMDACT tag 263 ALPHAB test on PANEL tag 402
value BACKWARD on CMDACT description 72 AREA (area) tag
tag 262 example 72 conditions of usage 216
value CANCEL on CMDACT specifying on CHECKI tag 240 defining panel text portion 40
tag 262 alphabetic test description 215
value EXHELP on CMDACT tag 262 description 67 examples 40, 217
value EXIT on CMDACT tag 262 example 67 syntax 213

© Copyright IBM Corp. 1989, 2000 509

area divider (DIVIDER) tag ATTRUSE attribute on PANEL tag 403 CCSID attribute
conditions of usage 287 AUTOSEL attribute on HELP tag 326, 381
description 287 on CHOICE tag 256 on HELPDEF tag 333
examples 287 AUTOTAB 95 on PANDEF tag 394
syntax 285 AUTOTAB attribute on PANEL tag 402
ASIS attribute on PANEL tag 403 description 98, 103 CDATA keyword
ASSIGNI (assignment list item) tag on CHOFLD tag 247 on ENTITY statement 194
conditions of usage 220 on CHOICE tag 254 character variables 59
description 220 on CMDAREA tag 266 CHARS test
examples 220 on DTACOL tag 295 specifying on CHECKI tag 236
syntax 219 on DTAFLD tag 303 CHDIV (choice divider) tag
ASSIGNL (assignment list) tag on LSTCOL tag 357 conditions of usage 233
conditions of usage 221 on SELFLD tag 438 description 233
description 221 using 103 examples
examples 221 solid and blank 233
syntax 221 syntax 232
assignment list (ASSIGNL) tag
conditions of usage 221
B check list
example 154
BARRIER attribute on ACTION tag 210
description 221 specifying message for 154
BIT test
examples 221 CHECKI (validity check item) tag
description 74
syntax 221 conditions of usage 242
example 74
assignment list item (ASSIGNI) tag description 242
specifying on CHECKI tag 238
conditions of usage 220 examples 242
BMARGIN attribute
description 220 syntax 234
on PANDEF TAG 395
examples 220 checking values within a numeric range,
on PANEL TAG 404
syntax 219 range test 67
BOTINST (bottom instruction) tag
ATTENTION (attention) tag CHECKL (validity check list) tag
conditions of usage 229
conditions of usage 223 conditions of usage 243
defining instruction text 39
description 222 description 243
description 228
syntax 222 examples 243
examples 40, 229
attention message syntax 243
syntax 228
description using MSG attribute 153
bottom instruction
format 135 CHECKVAR attribute
defining 39
ATTENTION tag description 37
description 6
description 135 example 38
bottom instruction (BOTINST) tag
ATTN attribute on CHOICE tag 253
conditions of usage 229
on ATTR tag 227 on PDC tag 413
description 228
ATTR (attribute) tag CHKBOX attribute
examples 229
conditions of usage 227 description 97
syntax 228
description 227 on SELFLD tag 440
BREAK=ALL attribute in definition
examples 228 using 97
list 126
syntax 224 CHOFLD (choice data field) tag
BREAK attribute
ATTRCHANGE attribute on DL tag 288 conditions of usage 249
description 98 on PARML tag 408 description 249
data field 86 BREAK=FIT attribute in definition examples 250
list field 103 list 127 syntax 244
on CHOFLD tag 248 CHOFLD (choice field) tag
on DTACOL tag 295 using MSG attribute 153
on DTAFLD tag 305
on LSTCOL tag 359
C choice 87, 93
CHOICE (selection choice) tag
CAPS attribute
on LSTFLD tag 366 conditions of usage 257
description 98
using 86, 103 defining a selection field 87
data field 86
ATTRCHAR attribute input-only 105 description 256
description input/output 105 examples 257
data field 86 on ATTR tag 226 syntax 252
on ATTR tag 225 on CMDAREA tag 268 choice data field (CHOFLD) tag
on DTAFLD tag 307 on DTACOL tag 296 conditions of usage 249
using 86 on DTAFLD tag 307 description 249
attribute on LSTCOL tag 360 examples 250
description 11 using 86 syntax 244
tag 11 CASE attribute on KEYI tag 341 choice divider (CHDIV) tag
attribute (ATTR) tag CAUTION (caution) tag conditions of usage 233
conditions of usage 227 conditions of usage 230 description 233
description 227 description 136, 230 examples 233
examples 228 example 136 syntax 232
syntax 224 examples 231 CHOICECOLS attribute
attributes and values, coding 11 syntax 230 description 96

510 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
CHOICECOLS attribute (continued) command 157 COMPACT attribute (continued)
on SELFLD tag 439 command action (CMDACT) tag on UL tag 457
using 96 conditions of usage 263 using in a note list 384
CHOICEDEPTH attribute description 263 using in a simple list 119
description 96 examples 263 using in an ordered list 123
on SELFLD tag 439 syntax 261 using in an unordered list 121
using 96 using to define a command compact for simple list 119
CKBOX attribute on ATTR tag 227 action 159 compact lists
CLEAR attribute command area note 118
description 103 defining 51 ordered 123
on LSTCOL tag 358 defining cursor placement 30 simple 119
CMD (command definition) tag description 7 unordered 121
assigning function key 163 command area (CMDAREA) tag compiler options (COMPOPT) tag
conditions of usage 260 conditions of usage 269 syntax 274
description 260 description 269 COMPOPT (compiler options) tag
examples 260 examples 269 examples 275
syntax 259 syntax 264 syntax 274
using to define a command 157 command definition (CMD) tag compopt (COMPOPT) tag
CMD attribute on KEYI tag 341 conditions of usage 260
examples 275
CMDACT (command action) tag description 260
considerations, compatibility for AREA
conditions of usage 263 examples 260
tag 216
description 263 syntax 259
conversion utility
examples 263 command-prompt-text attribute on
syntax 261 CMDAREA tag 268 ACTBAR option 179
CMDAREA (command area) tag command table 157 converting multiple source files 174
conditions of usage 269 command table (CMDTBL) tag CUAATTR option 177
defining a command area 51 CUASUPP option 177
conditions of usage 271
description 269 description 271 DBALIGN option 180
examples examples 271 DBCS option 176
defining 51 DISK option 176
syntax 270
in an application panel DISPLAY option 179
commands
markup 269 DISPLAYW option 180
application command table 157
specifying the command prompt DSNCHK option 180
declaring variables for 57
text 52 FORMAT option 178
defining a command area 51
syntax 264 GRAPHIC option 180
defining application command
CMDLEN attribute on CMDAREA GUI option 179
table 157
tag 266 help 174
defining with CMDTBL tag 157
CMDLINE attribute on PANEL tag 403 installing 186
description of application command
invocation panel input fields 170
CMDLOC attribute on CMDAREA table 8
tag 266 invocation panel options 171
specifying command action 159
invocation panels 167
CMDTBL (command table) tag specifying with the RUN attribute 36
KANA option 177
assigning function key 163 truncating 160
KEYAPPL option 177
conditions of usage 271 comment (COMMENT) tag
LISTING option 178
description 271 examples 273 LISTREPL option 178
examples 271 syntax 272 LOGREPL option 178
syntax 270 COMMENT (comment) tag LSTVIEW option 177
using to define a command table 157 examples 273 MCOMMENT option 181
coding an action bar definition 35 syntax 272 MERGESAREA option 179
COLOR attribute comment delimiter messages 184
description 97, 103 description 17 MSGEXPAND option 178
data field 86 example 17 MSGSUPP option 177
on ATTR tag 226 using 17 NOACTBAR option 179
on DTAFLD tag 307 comments NOCUAATTR option 177
on HP tag 337 examples 17 NOCUASUPP option 177
on LSTCOL tag 360 including in generated panel 15 NODBALIGN option 180
on SELFLD tag 443 including in source files 16 NODBCS option 176
using 86, 97 COMPACT attribute NODISPLAY option 179
COLSPACE attribute on BOTINST tag 228 NODISPLAYW option 180
description 104 on DL tag 289 NODSNCHK option 180
on LSTCOL tag 360 on GRPHDR tag 321 NOFORMAT option 178
COLTYPE attribute on NOTEL tag 384 NOGRAPHIC option 180
description 104 on OL tag 388 NOGUI option 179
on LSTCOL tag 360 on P tag 390 NOKANA option 177
column, defining widths 98, 103 on PARML tag 408 NOLISTING option 178
column data 98 on PNLINST tag 418 NOLISTREPL option 178
COLWIDTH attribute on LSTCOL on SL tag 447 NOLOGREPL option 178
tag 357 on TOPINST tag 455 NOLSTVIEW option 177

Index 511
conversion utility (continued) cursor placement (continued) DBCS
NOMCOMMENT option 181 in list field 30 option 176
NOMERGESAREA option 179 in selection field 30 restrictions for leading and trailing
NOMSGEXPAND option 178 LSTCOL 30 blanks 13
NOMSGSUPP option 177 SELFLD 30 DBCS test
NOPANEL option 177 CWIDTHS attribute specifying on CHECKI tag 239
NOPLEB option 181 CWIDTHS attribute on SELFLD test
NOPREP option 177 tag 439 description 71
NOREPLACE option 176 description 96 example 71
NOSCRIPT option 178 using 96 DD (definition description) tag
NOSTATS option 178 conditions of usage 282
NOVERSION option 179 description 124, 282
NOZVARS option 180
overview 9
D examples
DA (dynamic area) tag basic 125
PANEL option 177 BREAK=ALL attribute 126
PLEB option 181 conditions of usage 281
BREAK=FIT attribute 127
PREP option 177 description 281
help panel markup 283
PROFDDN option 181 examples 282
syntax 282
PROFILE option 181 syntax 277
using 45 DDHD (definition description header) tag
REPLACE option 176 conditions of usage 284
SCREEN option 176 data column
description 124, 284
SCRIPT option 178 defining 98
examples 127, 285
STATS option 178 example 98
syntax 284
supporting keys help 165 data column (DTACOL) tag
declaring variables 57
syntax 175 conditions of usage 297
default keylist, key mappings 164
using 167 description 98, 296
examples 298 defining help for key list 165
VERSION option 179
ZVARS option 180 syntax 293 definition description (DD) tag
converting DTL source files 167 data field conditions of usage 282
COPYR (copyright) tag attributes 84 description 282
examples 276 defining a field prompt 77 examples
syntax 276 defining alignment of data 84 basic 125
copyright defining an associated message 84, BREAK=ALL attribute 126
including in generated panel 15 95 BREAK=FIT attribute 127
copyright (COPYR) tag defining cursor placement 30 help panel markup 283
examples 276 defining data columns 98 syntax 282
copyright (COPYRIGHT) tag defining help for 83 definition description header (DDHD) tag
syntax 276 defining input/output 80 conditions of usage 284
CSRGRP attribute defining width 82 description 284
description 97, 104 examples 80 examples 285
data field 85 providing descriptive text 82 syntax 284
on ATTR tag 227 tailoring 84, 95 definition list (DL) tag
on DTAFLD tag 305 data field (DTAFLD) tag conditions of usage 289
on LSTCOL tag 359 conditions of usage 308 description 289
on PS tag 420 description 308 examples
on SELFLD tag 441 examples 308 basic 125
using 85, 97 syntax 299 BREAK=ALL attribute 126
CSRINDEX attribute data field description (DTAFLDD) tag BREAK=FIT attribute 127
example 31 conditions of usage 310 default BREAK value of
on PANEL tag 401 description 82, 310 NONE 290
CSRPOS attribute example 82 syntax 288
example 31 examples 310 using to define a definition list 124
on PANEL tag 401 syntax 309 definition term (DT) tag
CUAATTR option 177 DATAMOD attribute on DA tag 279 conditions of usage 292
CUADYN attribute on ATTR tag 227 DATAVAR attribute description 292
CUASUPP option 177 description 58 examples
CURSOR attribute on CHOFLD tag 246 basic 125
example 31 on DTAFLD tag 301 BREAK=ALL attribute 126
on PANEL tag 401 on LSTCOL tag 356 BREAK=FIT attribute 127
cursor field on PANEL tag 401 on LSTVAR tag 372 help panel markup 292
cursor placement DBALIGN attribute syntax 291
ABC 30 description 97, 98 definition term header (DTHD) tag
characteristics 30 data field 86 conditions of usage 311
CHOICE 30 on DTAFLD tag 306 description 311
DTAFLD 30 on SELFLD tag 442 examples 312
in command area 30 using 86, 97 syntax 311
in data field 30 DBALIGN option 180 delimiter symbol 11

512 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
depth and width, defining with PANDEF DISP attribute DSNAMEFM test (continued)
tag 53 on MSG tag 378 specifying on CHECKI tag 240
DEPTH attribute DISPLAY attribute DSNAMEPQ test
defining application panel depth 29 description 85 description 70
description 96 input-only 105 example 70
data field 86 input/output 105 specifying on CHECKI tag 240
on AREA tag 214 on CHOFLD tag 247 DSNAMEQ test
on DA tag 279 on DTAFLD tag 304 description 70
on DTAFLD tag 306 on LSTCOL tag 360 example 70
on GA tag 317 using 85 specifying on CHECKI tag 240
on HELP tag 325 DISPLAY option 179 DSNCHK option 180
on HELPDEF tag 333 DISPLAYW option 180 DT (definition term) tag
on PANDEF tag 393 DIV attribute conditions of usage 292
on PANEL tag 399 on AREA tag 215 description 124, 292
on PS tag 420 on DA tag 279 examples
on REGION tag 424 on GA tag 317 basic 125
on SELFLD tag 438 on GRPHDR tag 321 BREAK=ALL attribute 126
using 86, 96 on LSTFLD tag 365 BREAK=FIT attribute 127
DESSKIP attribute DIVIDER (area divider) tag help panel markup 292
description conditions of usage 287 syntax 291
data field 86 defining a divider 46 DTACOL (data column) tag
on DTAFLD tag 307 description 287 conditions of usage 297
using 86 examples description 296
DESTVAR attribute, on ASSIGNL solid and blank 49, 287 examples 298
tag 221 TYPE attribute 47 syntax 293
DESWIDTH attribute within a horizontal REGION DTAFLD (data field) tag 82
description 98 tag 49 conditions of usage 308
on DTACOL tag 294 within vertical REGION tag 48 description 308
on DTAFLD tag 303 syntax 285 examples 308
dialog element within a REGION tag 49 syntax 299
creating 11 DIVLOC attribute on GRPHDR tag 321 using 80
help panel 7 DIVWIDTH attribute using MSG attribute 153
dialog elements on AREA tag 215 DTAFLDD (data field description)
application command table 8 DL (definition list) tag tag 82
description 5 conditions of usage 289 conditions of usage 310
description of application panel 5 description 124, 289 description 310
description of help panel 7 examples examples 310
key mapping list 9 basic 125 syntax 309
messages 8 BREAK=ALL attribute 126 DTHD (definition term header) tag
types 5 BREAK=FIT attribute 127 conditions of usage 311
variable classes 9 default BREAK value of description 124, 311
variables 9 NONE 290 examples 127, 312
Dialog Tag Language (DTL) syntax 288 syntax 311
using to define a definition list 124 DTL
advantages 3
DM application, providing help for 142 macros 199
coding attributes and values 11
DOCTYPE statement results of converting 185
coding tag text 12
declaring document type 16 return codes 185
comments 15, 16
description 193 source files, converting 167
copyright statements 15
document type declaration 16 dynamic area (DA) tag
delimiters 11
parameters 193 conditions of usage 281
document type declaration 16
syntax 193 description 281
entities 18
document type declaration examples 282
introduction 3
description 193 syntax 277
nesting tags 15
types supported by DTL 16 using 45
parameter entities 22
predefined symbols 25 double-byte characters, permitting usage
relationship to CUA 4 through variables 59
results of converting 185 DSNAME test E
return codes 185 description 69 EBCDIC test
similarity to BookMaster 4 example 69 description 71
source file 11 specifying on CHECKI tag 240 example 71
syntax conventions 11 DSNAMEF test specifying on CHECKI tag 240
using 11 description 69 emphasizing panel text
dialog variable 57 example 69 description 137
DIR attribute specifying on CHECKI tag 240 HP (Highlighted phrase) 137
on AREA tag 215 DSNAMEFM test restriction 137
on REGION tag 424 description 69 RP (reference phrase) 137
DISK option 176 example 69 end tag delimiters 11

Index 513
ENDATTR attribute on PANEL tag 403 EXTEND attribute FLDSPACE attribute
entity description 96 description 85, 98
defining 18 on AREA tag 214 on CHOFLD tag 247
description 18 on DA tag 278 on DTACOL tag 295
examples on GA tag 317 on DTAFLD tag 303
changing text 19 on REGION tag 424 using 85
declaring a different name 22 on SELFLD tag 438 FLDTYPE attribute
declaring a file 20 using 96 description 97
declaring name and text string 18 data field 86
naming conventions 19 on DTAFLD tag 307
specifying a name in text 19
using a text string in source
F on SELFLD tag 443
using 86, 97
FCHOICE attribute
file 21 FLDWIDTH attribute
description 95 description
using to imbed external files 23
on SELFLD tag 438 data field 86
naming conventions 18
using 95 on DTAFLD tag 305
parameter 22
field using 86
predefined 25
using to imbed external files 23 defining 77 FMTWIDTH attribute on GRPHDR
defining a data field message 84, 95 tag 321
entity declarations
defining a list field message 104 FORMAT attribute
conditions of usage 195
defining data field 80 description 104
description 194, 195
defining data field columns 98 on AREA tag 215
example 196
defining list field 99 on ATTR tag 226
entity definitions
defining multiple-choice selection on CHDIV tag 232
example 197
fields 89 on DIVIDER tag 286
ENTITY keyword defining selection fields 87
on ENTITY statement 194 on GRPHDR tag 321
defining single-choice fields 88 on LSTCOL tag 358
entity-name interactive 77 on MSG tag 378
on ENTITY statement 194 providing additional information 141 on XLATL tag 472
ENTITY statement types 77 FORMAT option 178
parameters 194 field-level help formatting panel text
syntax 194 on LSTCOL tag 356 Asian rules 13
entity-text on SELFLD tag 435 English rules 13
on ENTITY statement 195 field prompt FRAME attribute on FIG tag 313
ENTKEYTEXT attribute attributes 77 function key area
on PANDEF TAG 395 defining 77 defining 163
on PANEL TAG 404 example 77 description 7
ENTWIDTH attribute specifying width 79
description 95, 98 FIG (figure) tag
on CHOFLD tag 247
on CMDAREA tag 266
conditions of usage 313
description 313
G
on DTACOL tag 294 GA (graphic area) tag
examples 115, 314
on DTAFLD tag 303 conditions of usage 318
syntax 312
on SELFLD tag 437 description 317
using to define a figure 115
using 95 examples 318
FIGCAP (figure caption) tag
syntax 316
ENUM 74 conditions of usage 315
using 46
ENUM test description 315
GAP attribute on DIVIDER tag 286
specifying on CHECKI tag 240 examples 116, 315
GE attribute on ATTR tag 226
error messages 184 syntax 315
generate (GENERATE) tag
ERRORCHECK attribute figure (FIG) tag conditions of usage 319
on PANEL tag 405 conditions of usage 313 description 319
example (XMP) tag description 313 examples 319
conditions of usage 474 examples 115, 314 syntax 318
description 474 syntax 312 GENERATE (generate) tag
examples 114, 475 using to define a figure 115 conditions of usage 319
syntax 474 figure caption (FIGCAP) tag description 319
using to define an example 114 conditions of usage 315 syntax 318
EXPAND attribute description 315 GENERATE (generate)tag
description examples 116, 315 examples 319
data field 85 syntax 315 generated panel comments
on CHOFLD tag 248 FileID test 69 comments 15
on DTAFLD tag 305 FILEID test generated panel statements
on HELP TAG 326 specifying on CHECKI tag 241 copyright 15
on HELPDEF TAG 333 files for installing the product 186 graphic area (GA) tag
on PANDEF TAG 394 filespec conditions of usage 318
on PANEL tag 402 on ENTITY statement 195 description 317
using 85 FKA attribute on KEYI tag 341 examples 318

514 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
graphic area (GA) tag (continued) HELP attribute (continued) Hn (heading) tag (continued)
syntax 316 on LSTCOL tag 356 syntax 335
using 46 on MSG tag 376 using to define a heading 112
GRAPHIC option 180 on PANDEF tag 393 horizontal region 48
group header (GRPHDR) tag on PANEL tag 399 HP (Highlighted phrase) tag
conditions of usage 322 on PDC tag 412 conditions of usage 337
description 322 on RP tag 431 description 137, 337
examples 322 on SELFLD tag 435 examples 137, 337
syntax 320 help default (HELPDEF) tag restriction 137
GRPBOX attribute on REGION tag 425 conditions of usage 334 syntax 336
GRPBXMAT attribute on REGION description 334
tag 425 examples 334
GRPBXVAR attribute on REGION
tag 425
syntax 332
help panel
I
ID attribute
GRPHDR (group header) tag defining for a data field 83
on HELPDEF tag 332
additional attributes for 106 defining help panel text 143
on PANDEF tag 393
conditions of usage 322 function key area 8
ID panel 28
description 322 layout 7
IDATE test
description of attributes 106 overview 7
description 75
examples 322 panel body 8
example 75
syntax 320 panel title 7
IMAPCOL attribute
GRPWIDTH attribute on REGION title 7
on HELP tag 327
tag 425 types of help 7
on HELPDEF tag 334
GUI option 179 using HELP attribute of PANEL
on PANDEF tag 395
GUTTER attribute tag 29
on PANEL tag 404
on CHDIV tag 232 help panel (HELP) tag
IMAPNAME attribute
on DIVIDER tag 286 conditions of usage 329
description
description 328
data field 86
examples 330
on CHOFLD tag 249
H syntax 323
help panel tag, using 142
on DTAFLD tag 306
heading on HELP tag 327
help panels
in the information region 112 on HELPDEF tag 333
defining 142
levels 112 on PANDEF tag 395
defining areas and regions 143
heading (Hn) tag on PANEL tag 404
using the INFO tag with 143
conditions of usage 335 on PS tag 421
help pull-down, defining 37
description 335 using 86
HELP tag 142
examples 112, 335 IMAPNAME attribute on CMDAREA
HELPDEF (help default) tag
syntax 335 tag 268
using to define a heading 112 conditions of usage 334 IMAPNAMEP attribute
description 334
HEADLINE attribute description
examples 334
on GRPHDR tag 321 data field 86
on LSTGRP tag 369 syntax 332 on DTAFLD tag 306
help HELPDEF attribute on HELP tag 325 on PS tag 421
defining a help pull-down 37 HEX test using 86
defining for a data field 83 description 74 IMAPNAMEP attribute on CMDAREA
defining help panels 142 example 74 tag 268
field-level 435 specifying on CHECKI tag 241 IMAPROW attribute
for action bar 36 HIDE attribute on CHOICE tag 255 on HELP tag 327
for application panels 29 HIDEX attribute on CHOICE tag 255 on HELPDEF tag 333
for selection choice 93 highlighted phrase (HP) tag 432 on PANDEF tag 395
for selection field 93 conditions of usage 337 on PANEL tag 404
for the conversion utility 174 description 337 imbedding source files 23
HELP (help panel) tag examples 337 immediate-action, for pull-down
conditions of usage 329 syntax 336 choice 35
description 328 HILITE attribute INCLUDE test
examples 330 description 98, 104 description 75
syntax 323 data field 86 example 75
HELP attribute on ATTR tag 226 specifying on CHECKI tag 241
on ABC tag 204 on DTAFLD tag 307 INDENT attribute
on CHOFLD tag 246 on HP tag 337 on OL tag 388
on CHOICE tag 253 on LSTCOL tag 360 on P tag 390
on CMDAREA tag 265 on SELFLD tag 443 on PARML tag 408
on DA tag 280 using 86, 98 on SL tag 448
on DTAFLD tag 302 Hn (heading) tag on UL tag 457
on HELP tag 325 conditions of usage 335 INDENT attribute on AREA tag 214
on HELPDEF tag 332 description 335 INDENT attribute on GRPHDR tag 321
on KEYL tag 345 examples 112, 335 INDENT attribute on REGION tag 424

Index 515
index value on PANEL tag 401 ISPKYLST (continued) keys 163 (continued)
INFO (information region) tag using 164 assigning actions 163
conditions of usage 339 ISPx application identifier 157 default keylist 164
description 339 item translate list defining 164
examples 109, 340 description 61 defining key mapping lists 163
syntax 339 example 62 displaying 164
using to define an information ITIME test
region 109 description 76
information message
defining 152
example 76 L
LANG attribute on ACTION tag 210
description 152
LEN test
providing for fields 141
information region
J description 73
JDATE test example 73
defining 109
description 75 specifying on CHECKI tag 240
defining text 110
example 75 LI (list item) tag
definition lists 124
JSTD test conditions of usage 347
examples (XMP tag) 114
description 76 description 347
figure captions 116
example 76 examples
figures 115
JUST attribute on ATTR tag 226 basic unordered list 120
headings 112
help panel with unordered
list part 130
list 348
ordered lists 122
paragraphs 110
K list part (LP) tag 130
KANA option 177 nested unordered 121
parameter lists 128
KEY attribute on KEYI tag 341 nesting ordered list 122
providing information for fields 141
key item (KEYI) tag note list 118
simple lists 118
conditions of usage 342 paragraph nested in a list 129
tags for text 109
description 342 simple list 118
unformatted text 113
examples 343 syntax 346
unordered lists 120
syntax 340 LINE attribute
information region (INFO) tag
using to define a key item 163 description 104
conditions of usage 339
key list, defining help 165 on LSTCOL tag 358
description 339
key mapping list on LSTVAR tag 372
examples 109, 340
defining 163 LINES (lines) tag
syntax 339
defining with PANDEF tag 53 conditions of usage 349
using to define an information
overview 9 description 349
region 109
using KEYLIST attribute of PANEL examples 113, 350
INIT attribute
tag 29 syntax 349
description 96
key mapping list (KEYL) tag using to define unformatted text 113
data field 86
conditions of usage 345 list column 31
on CHOFLD tag 249
description 345 defining width 103
on DTAFLD tag 306
examples 345 truncating 103
on SELFLD tag 440
syntax 344 list column (LSTCOL) tag
using 86, 96
KEYAPPL option 177 conditions of usage 361
initialization syntax, source-filespec 176
KEYI (key item) tag description 361
input/output data field 80
conditions of usage 342 examples 362
installing the conversion utility 186
description 163, 342 syntax 354
instruction text 40 list field
examples 343
instructions, top and bottom 39 additional attributes for 103
syntax 340
INTENS attribute auto-tab attribute 103
using to define a key item 163
description 97, 104 defining 99
KEYL (key mapping list) tag
data field 86 defining alignment of data 103
conditions of usage 345
on ATTR tag 226 defining an associated message 104
description 163, 345
on DTAFLD tag 307 defining cursor placement 30
examples 345
on HP tag 337 defining required input for 105
syntax 344
on LSTCOL tag 360 description 99
using 163
on SELFLD tag 443 example 101
KEYLIST attribute
using 86, 97 specifying help for 104
examples 29
INTENSE attribute on HELP TAG 326 tailoring 103
on P tag 390 on HELPDEF TAG 333 list field (LSTFLD) tag
ISP application identifier 157 on PANDEF tag 394 conditions of usage 367
ISPDTLC on PANEL tag 401 description 366
overview 9 KEYLTYPE attribute examples 367
using ? 175 on HELP TAG 326 syntax 364
using command 167 on HELPDEF tag 333 list group (LSTGRP) tag
ISPKYLST on PANDEF tag 394 conditions of usage 370
description 164 on PANEL tag 401 description 369
key mappings list 164 keys 163 example 370

516 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
list group (LSTGRP) tag (continued) LOCATION attribute MATCH attribute (continued)
syntax 368 on MSG tag 377 on PDC tag 413
list item (LI) tag on REGION tag 426 MCOMMENT option 181
conditions of usage 347 LOGREPL option 178 MENU attribute on PANEL tag 402
description 347 LP (list part) tag MERGESAREA attribute
examples conditions of usage 353 on HELP TAG 327
basic 118 description 353 on HELPDEF TAG 333
COMPACT attribute on simple examples 130, 354 on PANDEF TAG 394
list 119 syntax 352 on PANEL tag 404
compact ordered list 123 using to define a list part 130 MERGESAREA option 179
help panel with unordered LSTCOL (list column) tag message
list 348 additional attributes for 103 declaring variables for 57
syntax 346 conditions of usage 361 defining 151
list part (LP) tag description 100, 361 defining for a data field 84, 95
conditions of usage 353 description of attributes 103 defining for a list field 104
description 353 examples 362 example 8
examples 130, 354 syntax 354 for check list 154
syntax 352 using MSG attribute 153 member 151
using to define a list part 130 LSTFLD (list field) tag specifying a variable in text 156
list variable (LSTVAR) tag conditions of usage 367 specifying type 152
conditions of usage 372 description 100, 366 types 151
description 372 examples 367 message (MSG) tag
example 372 syntax 364 conditions of usage 379
syntax 371 LSTGRP (list group) tag description 379
LISTDEPTH attribute conditions of usage 370 examples 152, 379
description 97 description 100, 369 MSG SUFFIX attribute 152
on SELFLD tag 441 example 370 syntax 376
using 97 syntax 368 using to define a message 151
LISTING option 178 LSTVAR (list variable) tag message identifier 152
LISTREF attribute conditions of usage 372 message member 151
description 97 description 100, 372 message member (MSGMBR) tag
on SELFLD tag 441 example 372 conditions of usage 381
using 97 syntax 371 description 381
LISTREPL option 178 LSTVIEW option 177 examples
lists LVLINE attribute basic 151
definition 124 on DA tag 278 defining a message member 381
list part 130 on GA tag 317 specifying type 152
nesting lists within lists 131 syntax 380
note 118 using to define a message
ordered 122
parameter 128
M member 151
M (mnemonic) tag messages
simple 118 assigning for check list 153
conditions of usage 375
types 117 assigning for data field 153
description 375
unordered 120 assigning for failing specified
example 375
LISTTYPE attribute parameters 374 translation 153
description 97 syntax 374 assigning for failing validity
on SELFLD tag 441 macros check 153
using 97 DTL 199 assigning for list column 153
LISTV test MARGIND attribute on AREA tag 214 conversion utility 184
description 73 MARGINW attribute defining 151
example 73 example 41 description 151
specifying on CHECKI tag 239 on AREA tag 214 error 184
LISTVX test markup, coding 11 overview 8
description 73 markup declarations warning 184
example 73 comments 16 MIX test
specifying on CHECKI tag 239 defining entities and parameter description 71
LIT (literal) tag entities 18 example 71
conditions of usage 351 document type declaration 16 specifying on CHECKI tag 241
description 351 entity declarations 18 MNEMGEN attribute on AB tag 202
examples 352 types supported by DTL 16 mnemonic (M) tag
syntax 351 markup language conditions of usage 375
literal (LIT) tag advantages 4 description 375
conditions of usage 351 description 3 example 375
description 351 MATCH attribute parameters 374
examples 352 description 37 syntax 374
syntax 351 example 38 mnemonic choice selection
LMSG attribute on PANEL tag 403 on CHOICE tag 254 from pull-downs and action bars 38

Index 517
mnemonic choice selection (continued) nesting 135 NOSKIP attribute (continued)
support of 38 lists within lists 131 on XMP tag 474
MODE attribute on ACTION tag 210 ordered lists 122, 123 NOSTATS option 178
MSG (message) tag simple list 119 NOTE (note) tag
conditions of usage 379 tags within lists 129 conditions of usage 383
description 379 unordered lists 121 description 382
examples 152, 379 NEWAPPL attribute on ACTION examples 383
MSG SUFFIX attribute 152 tag 209 syntax 382
syntax 376 NEWPOOL attribute on ACTION note (NT) tag
using to define a message 151 tag 209 conditions of usage 386
MSG attribute NEWWINDOW attribute on ACTION description 386
on CHECKL tag 243 tag 209 examples 387
on DTAFLD tag 302 NOACTBAR option 179 syntax 386
on LSTCOL tag 357 NOCHECK attribute on ACTION note list (NOTEL) tag
on SELFLD tag 438 tag 210 conditions of usage 384
on VARCLASS tag 461 NOCUAATTR option 177 description 384
on XLATL tag 472 NOCUASUPP option 177 examples 385
using 84, 95 NODBALIGN option 180 syntax 384
MSGEXPAND option 178 NODBCS option 176 NOTE tag
MSGLINE attribute on HELP tag 327 NODISPLAY option 179 description 132
MSGLINE attribute on PANEL tag 402 NODISPLAYW option 180 example 132
MSGMBR (message member) tag NODSNCHK option 180 NOTEL (note list) tag
conditions of usage 381 NOENDATTR attribute conditions of usage 384
description 381 description 85, 104 description 132, 384
examples on CHOFLD tag 247 examples 133, 385
basic 151 on DIVIDER tag 286 syntax 384
defining a message member 381 on DTAFLD tag 304 NOVERSION option 179
specifying type 152 on LSTCOL tag 359 NOZVARS option 180
syntax 380 using 85 NT (note) tag
using to define a message NOFORMAT option 178 conditions of usage 386
member 151 NOGRAPHIC option 180 description 132, 386
MSGSUPP option 177 NOGUI option 179 example 134
MSGTYPE attribute on MSG tag 377 NOINIT attribute on CMDAREA examples 387
multiple-choice selection field tag 266 syntax 386
defining 89 NOJUMP attribute NUM test
discussion 89 description description 74
example 89 data field 87 example 74
MVS naming conventions 186 on CMDAREA tag 268 specifying on CHECKI tag 239
on DTAFLD tag 307 NUMERIC attribute on ATTR tag 226
N using 87
NOKANA option 177
numeric variables
converting 60
NAME attribute NOLISTING option 178 description 60
identifying variables 57 NOLISTREPL option 178 uses 60
on CHOICE tag 252 NOLOGREPL option 178
on CMD tag 259 NOLSTVIEW option 177
on CMDAREA tag 266
on DA tag 278
NOMATCH attribute on CHOICE
tag 254
O
on DTAFLD tag 301 OL (ordered list) tag
NOMCOMMENT option 181
on GA tag 316 conditions of usage 388
NOMERGESAREA option 179
on HELP tag 324 description 388
NOMSGEXPAND option 178 examples
on KEYL tag 344
NOMSGSUPP option 177 COMPACT attribute 123
on MSGMBR tag 380
NOPANEL option 177 list part (LP) tag 130
on PANEL tag 398
on SELFLD tag 435 NOPLEB option 181 nested with paragraph 389
on VARCLASS tag 459 NOPREP option 177 nesting 122
on VARDCL tag 463 NOREPLACE option 176 paragraph nested in a list 129
rules for variable names 201 NOSCRIPT option 178 syntax 387
using with the PANEL tag 28 NOSEL attribute using to define an ordered list 122
NAME test description 97 OPT attribute on ACTION tag 210
description 70 on SELFLD tag 442 ordered list (OL) tag
example 70 using 97 conditions of usage 388
specifying on CHECKI tag 238 NOSKIP attribute description 388
NAMEF test on FIG tag 313 examples
description 70 on LINES tag 349 COMPACT attribute 123
example 70 on NOTEL tag 384 list part (LP) tag 130
specifying on CHECKI tag 238 on OL tag 388 nested with paragraph 389
naming conventions for MVS 186 on SL tag 448 nesting 122
NEST attribute on ACTION tag 210 on UL tag 457 paragraph nested in a list 129

518 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
ordered list (OL) tag (continued) PADC attribute (continued) paragraph (P) tag (continued)
syntax 387 on SELFLD tag 440 examples (continued)
using to define an ordered list 122 using 85, 96 nested in an ordered list 129
OUTLINE attribute PANDEF (panel default) tag syntax 390
description conditions of usage 396 using to define a paragraph 110
data field 85 defining panel defaults 53 parameter description (PD) tag
DTACOL tag 98 description 395 conditions of usage 410
LSTCOL tag 104 examples description 410
seletion field 96 overriding a value 55 examples 128, 411
on ATTR tag 227 referring to default syntax 410
on CHOFLD tag 248 definitions 396 parameter entity
on CHOICE tag 255 shared panel dimensions only 54 description 22
on CMDAREA tag 266 shared panel values 54 examples 22
on DTACOL tag 295 syntax 392 naming conventions 23
on DTAFLD tag 304 PANDEF attribute on PANEL tag 399 syntax 194
on LSTCOL tag 359 panel 7 parameter list (PARML) tag
on PANDEF tag 394 declaring variables for 57 conditions of usage 408
on PANEL tag 402 defining fields 77 description 408
on SELFLD tag 440 defining with the PANEL tag 27 examples 409
using 85, 96 PANEL (panel) tag syntax 408
output data field 80 conditions of usage 405 using to define a parameter list 128
overriding variable classes 76 defining a panel ID 28 parameter term (PT) tag
defining an application panel 27 conditions of usage 422
P defining cursor placement 30
defining panel NAME value 28
description 422
examples 128, 423
P (paragraph) tag defining the panel title 28 syntax 422
conditions of usage 391 defining the panel width and PARM attribute
description 390 depth 29 on ACTION tag 209
examples description 405 on KEYI tag 342
basic 110 examples PARML (parameter list) tag
defining information region CURSOR attribute 31 conditions of usage 408
width 391 HELP attribute 30 description 408
formatting of 111 KEYLIST attribute 29, 406 examples 128, 409
nested in an ordered list 129 start and end tags 28 syntax 408
syntax 390 WIDTH and DEPTH attributes 29 using to define a parameter list 128
using to define a paragraph 110 specifying a key mapping list 29 PAS attribute
PAD attribute specifying a KEYLIST attribute 29 description 105
description specifying associated help panel 29 data field 85
data field 85 syntax 397 on ATTR tag 227
DTACOL tag 98 panel body 6 on CHOFLD tag 248
LSTCOL tag 104 panel default (PANDEF) tag on DTAFLD tag 305
selection field 96
conditions of usage 396 on LSTCOL tag 359
on ATTR tag 226
description 395 using 85
on CHOFLD tag 248
examples 396 PASSLIB attribute on ACTION tag 209
on CHOICE tag 255
syntax 392 PASSTHRU 159
on CMDAREA tag 266
panel defaults 53 PD (parameter description) tag
on DTACOL tag 295
panel instruction (PNLINST) tag conditions of usage 410
on DTAFLD tag 304
conditions of usage 418 description 410
on LSTCOL tag 359
description 418 examples 128, 411
on PANDEF tag 394
examples 418 syntax 410
on PANEL tag 402
syntax 418 PDC (pull-down choice) tag
on SELFLD tag 440
using 85, 96 PANEL option 177 conditions of usage 414
PADC attribute panel region, defining 47 description 414
description panel title examples
data field 85 defining 28 basic 414
DTACOL tag 98 description 6 defining help panel 37
LSTCOL tag 104 for help panels 7 markup 35
selection field 96 PANELSTMT attribute using mnemonic selection 38
on ATTR tag 226 on PANEL tag 404 syntax 412
on CHOFLD tag 248 paragraph (P) tag PDCVAR attribute on ABC tag 205
on CHOICE tag 255 conditions of usage 391 PDSEP (pull-down separator) tag
on CMDAREA tag 266 description 390 conditions of usage 416
on DTACOL tag 295 examples description 416
on DTAFLD tag 304 basic 110 example 416
on LSTCOL tag 359 defining information region syntax 416
on PANDEF tag 394 width 391 phrase-to-be-highlighted attribute
on PANEL tag 402 formatting of 111 on HP tag 337

Index 519
PICT test prompt-width, specifying for data REGION (region) tag (continued)
description 72 field 79 examples
example 72 PS (point-and-shoot) tag DIR attribute 47
specifying on CHECKI tag 238 conditions of usage 421 horizontal and vertical 49, 427
PICTCN test description 421 syntax 424
description 72 example 421 REPLACE keyword
example 72 syntax 419 on ENTITY statement 195
specifying on CHECKI tag 238 PSBUTTON attribute on CMDAREA REPLACE option 176
PLACE attribute tag 267 REQUIRED attribute
description PSVAL attribute description 98
data field 86 description data field 84
on DTAFLD tag 306 data field 85 LSTCOL tag 105
on PS tag 421 on CHOFLD tag 248 selection field 95
using 86 on DTAFLD tag 305 on CHOFLD tag 246
PLACE attribute on CMDAREA tag 268 using 85 on DTACOL tag 296
PLEB option 181 PSVAL attribute on CMDAREA tag 268 on DTAFLD tag 302
PMTFMT attribute PSVAR attribute on LSTCOL tag 357
description on SELFLD tag 438
description 98
data field 85 using 84, 95
data field 85
on CHOFLD tag 248 RESULT attribute on ASSIGNI tag 220
on DTACOL tag 295
on DTAFLD tag 305 return codes, results of converting with
on DTAFLD tag 305
using 85 DTL 185
using 85
PSVAR attribute on CMDAREA tag 267 risk (attention statement) 135
PMTLOC attribute
PT (parameter term) tag risk (warning statement) 135
description 98
conditions of usage 422 ROWS attribute on LSTFLD tag 365
on CMDAREA tag 266
description 422 RP (Reference phrase) tag
on DTAFLD tag 304
examples 128, 423 conditions of usage 431
on SELFLD tag 436
syntax 422 description 139, 431
using 77
pull-down, defining 34 example 139
PMTSKIP attribute
pull-down choice examples 432
description 97 (PDC) tag restriction 139
data field 86 conditions of usage 414 syntax 430
on DTAFLD tag 307 description 414 rules
on SELFLD tag 442 examples 414 for variable names 201
using 86, 97 syntax 412 formatting Asian panel text 13
PMTTEXT attribute on CMDAREA actions 36 formatting English panel text 13
tag 266 defining 34 RULES attribute on LSTFLD tag 365
PMTWIDTH attribute example 36 RUN attribute
description 98 preselected 37 example 158
on DTACOL tag 294 providing help for 36 on ACTION tag 208
on DTAFLD tag 303 pull-down separator (PDSEP) tag specifying a command 36, 158
on SELFLD tag 436 (PDSEP) tag
using 77 conditions of usage 416
PNLINST (panel instruction) tag
conditions of usage 418
description 416
example 416
S
description 418 SCRCAPS attribute
syntax 416
examples 418 on CMDAREA tag 267
syntax 418 on DA tag 280
on LSTFLD tag 366
point-and-shoot (PS) tag
conditions of usage 421
R SCREEN option 176
RANGE test SCRIPT option 178
description 421
checking values within a numeric SCRNAME attribute on ACTION
example 421
range 67 tag 210
syntax 419
description 67 SCROLL attribute on DA tag 278
pop-up window, displaying messages
specifying on CHECKI tag 235 SCROLLTAB attribute
on 151
reference phrase (RP) tag on LSTFLD tag 366
POSITION attribute
conditions of usage 431 SCROLLTAB attribute on CMDAREA
description 105 description 431 tag 267
on LSTCOL tag 358 examples 432 SCROLLTAB attribute on DA tag 280
position value on PANEL tag 401 syntax 430 SCROLLVAR attribute
predefined entities 25 REFRESH attribute on DA tag 280
predetermined tag attributes 12 description 97 on LSTFLD tag 365
PREP option 177 on SELFLD tag 440 SCROLLVAR attribute on CMDAREA
preselected pull-down choice 37 using 97 tag 267
PRIME attribute on PANEL tag 402 REGION (region) tag SCRVHELP attribute
PROFDDN option 181 conditions of usage 426 on CMDAREA tag 267
PROFILE option 181 defining a region 47 on DA tag 280
prompt 77 description 426 on LSTFLD tag 366

520 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
SELCHAR attribute on CHOICE tag 254 SKIP attribute on ATTR tag 226 T (truncation) tag (continued)
SELDEFAULT attribute SL (simple list) tag syntax 451
description 97 conditions of usage 448 using to define command
on SELFLD tag 442 description 448 truncation 160
using 97 examples tag
selection choice (CHOICE) tag basic 118 attributes 11
conditions of usage 257 compact and nested 448 coding text 12
description 256 COMPACT attribute 119 delimiters 11
examples 257 syntax 447 description 11
syntax 252 using to define a simple list 118 nesting 15
selection choice, defining space for 93 SMSG attribute rules for coding values 12
selection field on MSG tag 378 text 12
attributes 95 on PANEL tag 403 values 11
defining 87 SORT attribute on CMDTBL tag 271
tags
defining a field prompt 77 source (SOURCE) tag
defining cursor placement 30 example 451 AB 201
defining space for choice 93 SOURCE (source) tag ABC 204
help for 93 example 451 ACTION 207
using the CHOICE tag 87 SOURCE (Source) tag ASSIGNI 219
selection field (SELFLD) tag conditions of usage 450 ASSIGNL 221
conditions of usage 444 description 450 ATTENTION 132, 222
description 443 syntax 449 ATTR 224
examples 445 source file BOTINST 228
syntax 433 defining dialog elements 11 CAUTION 132
selection list, defining cursor defining entities and parameter CHDIV 232
placement 31 entities 18 CHECKI 234
selection width, defining 95 DOCTYPE declaration 193 CHECKL 243
SELFLD (selection field) tag frequently used words (entities) 18 CHOFLD 244
conditions of usage 444 imbedding 23 CHOICE 252
description 443 including comments 15, 16 CMD 259
examples 445 including copright statements 15 CMDACT 261
syntax 433 source-filespec, for system 176 CMDAREA 264
using MSG attribute 154 SPACE attribute CMDTBL 270
SELFMT attribute on LI tag 347 COMMENT 272
description 97 on OL tag 388 COMPOPT 274
on SELFLD tag 440 on SL tag 448 COPYRIGHT 276
using 97 on UL tag 457 DA 277
SELMSG attribute SPACE keyword DD 282
on ENTITY statement 195 DDHD 284
description 96
specifying DIVIDER 285
on SELFLD tag 440
a list of values to match value of user DL 288
using 96
input 67 DT 291
SELMSGU attribute
a list of valuesx to match value of DTACOL 293
description 96
user input 68 DTAFLD 299
on SELFLD tag 440
calling the conversion utility 176 DTAFLDD 309
using 96
source-filespec 176 DTHD 311
SELWIDTH attribute
start tag delimiters 11 FIG 312
defining space for 93 FIGCAP 315
description 93, 98 STATS option 178
STDDATE test for information region 109
on DTACOL tag 294 GA 316
on SELFLD tag 436 description 75
example 75 GENERATE 318
using 93 GRPHDR 320
SETVAR attribute on ACTION tag 211 STDTIME test
description 76 HELP 323
SETVERB 159 HELPDEF 332
example 76
SHADOW attribute on DA tag 279 Hn 335
STRIP attribute on GRPHDR tag 321
simple list (SL) tag HP 336
SUFFIX attribute on MSG tag 376
conditions of usage 448 INFO 339
SUSPEND attribute on ACTION tag 210
description 448 KEYI 340
syntax diagrams, reading 191
examples KEYL 344
SYSTEM keyword
basic 118 LI 346
on ENTITY statement 195
compact and nested 448 LINES 349
COMPACT attribute 119 LIT 351
syntax 447 LP 352
using to define a simple list 118 T LSTCOL 354
single-choice selection field T (truncation) tag LSTFLD 364
defining 88 conditions of usage 452 LSTGRP 368
discussion 88 description 451 LSTVAR 371
example 88 examples 160, 452 M 374

Index 521
tags (continued) text line (TEXTLINE) tag (continued) translate lists (continued)
mnemonic 374 syntax 452 types 61
MSG 376 text segment (TEXTSEG) tag translation
MSGMBR 380 conditions of usage 454 defining items for 61
nesting 131 description 453 example 62, 63
NOTE 382 examples 454 TRUNC attribute
NOTEL 384 syntax 453 on CHOICE tag 256
NT 132, 386 TEXTFMT attribute on XLATL tag 472
OL 387 description 105 truncation (T) tag
P 390 on LSTCOL tag 359 conditions of usage 452
PANDEF 392 TEXTLEN attribute description 451
PANEL 397 description 105 examples 160, 452
PARML 408 on LSTCOL tag 359 syntax 451
PD 410 TEXTLINE (text line) tag using to define command
PDC 412 conditions of usage 453 truncation 160
PDSEP 416 description 453 TSIZE attribute
PNLINST 418 syntax 452 description 97
PS 419 TEXTLINE (text line)tag on DL tag 288
PT 422 examples 453 on PARML tag 408
REGION 424 TEXTLOC attribute on SELFLD tag 441
RP 430 description 105 using 97
SELFLD 433 on LSTCOL tag 359
TUTOR attribute
SL 447 TEXTSEG (text segment) tag
on HELP tag 326
SOURCE 449 conditions of usage 454
on PANEL tag 402
T 451 description 453
tutor-choice fields 93
TEXTLINE 452 syntax 453
TYPE attribute
TEXTSEG 453 TEXTSEG(text segment)tag
TOPINST 455 examples 454 description 87
UL 457 TEXTSKIP attribute on ACTION tag 209
VARCLASS 459 description 105 on ATTR tag 226
VARDCL 463 on LSTCOL tag 359 on CHDIV tag 232
VARLIST 464 title, panel 28 on CHECKI tag 235
VARSUB 466 TITLINE attribute on PANEL tag 403 on COMMENT tag 272
WARNING 132, 468 TMARGIN attribute on DIVIDER tag 286
XLATI 470 on PANDEF TAG 395 on HP tag 337
XLATL 472 on PANEL TAG 404 on PANEL tag 403
XMP 474 TOGVAR attribute on ACTION tag 211 on SELFLD tag 436
top instruction on SOURCE tag 449
text
on VARCLASS tag 460
adding to a list 130 defining 39
description 6 using 87
defining for information region 110
value %varname on VARCLASS
help 143 top instruction (TOPINST) tag
tag 460
providing attention to user 135 conditions of usage 455
value ALPHA on CHECKI tag 236
providing caution 136 description 455
value ALPHAB on CHECKI tag 240
providing notes to user 132 examples 456
value ANY on VARCLASS tag 460
providing warning to user 135 syntax 455
value BIT on CHECKI tag 238
static 109 TOPINST (top instruction) tag
value CHAR on VARCLASS tag 460
tag 12 conditions of usage 455 value CHARS on CHECKI tag 236
tags used to define 109 defining instruction text 39
value DBCS on CHECKI tag 239
using the example tag 114 description 455 value DBCS on VARCLASS tag 460
using the figure tag 115 examples 40, 456 value DSNAME on CHECKI tag 240
using the heading tags 112 syntax 455 value DSNAMEF on CHECKI
using the LINES tag 113 TRAIL attribute tag 240
using the paragraph tag 110 description 96 value DSNAMEFM on CHECKI
TEXT attribute on SELFLD tag 439 tag 240
description 105 using 96 value DSNAMEPQ on CHECKI
on AREA tag 215 translate item (XLATI) tag tag 240
on LSTCOL tag 358 conditions of usage 471 value DSNAMEQ on CHECKI
on NOTE tag 382 description 470 tag 240
on NOTEL tag 384 examples 471 value EBCDIC on CHECKI tag 240
on NT tag 386 syntax 470 value EBCDIC on VARCLASS
on OL tag 388 translate list (XLATL) tag tag 460
on SL tag 448 conditions of usage 473 value ENUM on CHECKI tag 240
on UL tag 458 description 472 value FILEID on CHECKI tag 241
text line (TEXTLINE) tag examples 473 value HEX on CHECKI tag 241
conditions of usage 453 syntax 472 value IDATE on VARCLASS tag 460
description 453 translate lists value INCLUDE on CHECKI tag 241
examples 453 defining 61 value ITIME on VARCLASS tag 460

522 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
TYPE attribute (continued) validity check item (CHECKI) tag variable class (VARCLASS) tag
value JDATE on VARCLASS tag 461 (continued) conditions of usage 462
value JSTD on VARCLASS tag 461 description 242 description 461
value LEN on CHECKI tag 240 examples 242 examples 462
value LISTV on CHECKI tag 239 syntax 234 syntax 459
value LISTVX on CHECKI tag 239 validity check list (CHECKL) tag variable data
value MIX on CHECKI tag 241 conditions of usage 243 aligning 84, 103
value MIXED on VARCLASS tag 460 description 243 description 103
value NAME on CHECKI tag 238 examples 154, 243 variable declaration (VARDCL) tag
value NAMEF on CHECKI tag 238 syntax 243 conditions of usage 463
value NUM on CHECKI tag 239 validity checks description 463
value NUMERIC on VARCLASS description 66 examples 463
tag 461 types 66 syntax 463
value PICT on CHECKI tag 238 using 66 variable list
value PICTCN on CHECKI tag 238 using CHECKL and CHECKI tags 66 defining 57
value RANGE on CHECKI tag 235 value variable list (VARLIST) tag
value STDDATE on VARCLASS description 11 conditions of usage 464
tag 461 tag 11 description 464
value STDTIME on VARCLASS VALUE attribute examples 465
tag 460 syntax 464
on ACTION tag 211
value VALUES on CHECKI tag 237 variable names
on ASSIGNI tag 219
value VALUESX on CHECKI tag 237 as a tag value, assigning 12
on PS tag 420
value VMASK on VARCLASS rules 201
on XLATI tag 470
tag 461 rules for %varname as a tag
VALUE1 attribute on ACTION tag 211
value 201
VALUE2 attribute on ACTION tag 211
variable substitution (VARSUB) tag
VALUES test
U description 67
conditions of usage 466
description 466
UL (unordered list) tag example 67
examples 156, 467
conditions of usage 458 specifying on CHECKI tag 237 syntax 466
description 458 VALUESX test using to substitute a variable 156
examples description 68 variable translate list
basic 120 example 68
basic and nested 458 defining 61
specifying on CHECKI tag 237 relation to VARCLASS definition 61
nested 121 VAR attribute
syntax 457 types 61
on PS tag 420 variable validation 61
using to define an unordered list 120 on VARSUB tag 466
UNAVAIL attribute variables
VARCLASS (variable class) tag character 59
on CHOICE tag 256
conditions of usage 462 declaring 57
on PDC tag 413
description 461 defining a variable class 58
UNAVAILMAT attribute on CHOICE
examples 462 in data fields 80
tag 256
syntax 459 item translating 62
unformatted text
using MSG attribute 154 numeric 60
using the example tag 114
using to define a variable class 59 overview 9
using the figure tag 115
using the LINES tag 113 VARCLASS attribute rules for naming 201
unordered list (UL) tag description 85, 98 specifying in message text 156
conditions of usage 458 input-only 105 translate list 61
description 458 input/output 105 translating 61, 62
examples on CHOFLD tag 246 validating 61
basic 120 on DTAFLD tag 302 validity checks 66
basic and nested 458 on LSTCOL tag 356 VARLIST (variable list) tag
nested 121 on VARDCL tag 463 conditions of usage 464
syntax 457 using 85 description 464
using to define an unordered list 120 VARDCL (variable declaration) tag examples 58, 465
upper translate list conditions of usage 463 syntax 464
example 61 description 463 using 57
translating a value to uppercase 61 examples 58, 463 VARSUB (variable substitution) tag
USAGE attribute syntax 463 conditions of usage 466
description 99 variable class description 466
on CHOFLD tag 246 associating translate list 61 examples 467
on DTAFLD tag 302 defining 58 syntax 466
on LSTCOL tag 356 defining character variables 59 VERIFY attribute
USERMOD attribute on DA tag 279 defining translate list 472 description 96
description 57 on SELFLD tag 440
V overriding 76 using 96
validity check item (CHECKI) tag overriding the data variable 105 VERSION option 179
conditions of usage 242 overview 9 vertical region 48

Index 523
W XMP (example) tag (continued)
description 474
WARNING (warning) tag examples 114, 475
conditions of usage 468 syntax 474
description 468 using to define an example 114
examples 223, 469
syntax 468
warning message
defining 152 Z
description ZCMD system variable
format 135
for PASSTHRU 159
information messages 152
for SETVERB 159
ISPF conversion utility
messages 184 ZGUI attribute
example 135 description 97
WARNING tag on SELFLD tag 441
description 135 using 97
example 135 ZKEYHELP, using 165
width and depth, defining with PANDEF
tag 53 ZVARS option 180
WIDTH attribute ZVERB system variable for
defining application panel width 29 SETVERB 159
on AREA tag 215
on DA tag 279
on FIG tag 313
on GA tag 317
on GRPHDR tag 321
on HELP tag 325
on HELPDEF tag 332
on INFO TAG 339
on MSGMBR tag 381
on PANDEF tag 393
on PANEL tag 400
on REGION tag 424
window
layout 5
WINDOW attribute
on PANDEF tag 394
on PANEL tag 402
WINTITLE attribute
on HELP TAG 326
on HELPDEF TAG 333
on PANDEF tag 394
on PANEL tag 402
word-wrapping
data field width 82
on DESWIDTH attribute 82
WSDIR attribute on ACTION tag 210
WSINVOKE attribute on ACTION
tag 210
WSSIZE attribute on ACTION tag 210
WSVIEW attribute on ACTION tag 211

X
XLATI (translate item) tag
conditions of usage 471
description 470
examples 471
syntax 470
XLATL (translate list) tag
conditions of usage 473
description 472
examples 473
syntax 472
using MSG attribute 154
XMP (example) tag
conditions of usage 474

524 OS/390 V2R10.0 ISPF Dialog Tag Language Guide and Reference
IBMR

File Number: S370/4300-39

Program Number: 5647-A01

Printed in the United States of America

on recycled paper containing 10%
recovered post-consumer fiber.

SC28-1219-04