Display Rpgle

AS/400 Advanced Series IBM
Application Display Programming

Version 4
SC41-5715-00
AS/400 Advanced Series IBM
Version 4
SC41-5715-00
Take Note!
Before using this information and the product it supports, be sure to read the general information under “Notices” on page xxix.
First Edition (August 1997)
This edition applies to the licensed program IBM Operating System/400 (Program 5769-SS1), Version 4 Release 1 Modification 0,
and to all subsequent releases and modifications until otherwise indicated in new editions.
Make sure that you are using the proper edition for the level of the product.
Order publications through your IBM representative or the IBM branch serving your locality. If you live in the United States, Puerto
Rico, or Guam, you can order publications through the IBM Software Manufacturing Solutions at 800+879-2755. Publications are not
stocked at the address given below.
IBM welcomes your comments. A form for readers’ comments may be provided at the back of this publication. You can also mail
your comments to the following address:
IBM Corporation
Attention Department 542
IDCLERK
3605 Highway 52 N
Rochester, MN 55901-7829 USA
or you can fax your comments to:
United States and Canada: 800+937-3430

Other countries: (+1)+507+253-5192
If you have access to Internet, you can send your comments electronically to IDCLERK@RCHVMW2.VNET.IBM.COM; IBMMAIL, to
IBMMAIL(USIB56RZ).
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes
appropriate without incurring any obligation to you.
 Copyright International Business Machines Corporation 1997. All rights reserved.

Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to
restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxix
Programming Interface Information . . . . . . . . . . . . . . . . . . . . . . . . . xxx
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx
About Application Display Programming (SC41-5715) . . . . . . . . . . . xxxi

Who Should Use This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxi
Prerequisite and Related Information . . . . . . . . . . . . . . . . . . . . . . . xxxi
Information Available on the World Wide Web . . . . . . . . . . . . . . . . . . xxxi
Summary of Changes to Application Display Programming . . . . . . . . xxxiii
Part 1. Building a Sample Display with Online Help Information
Chapter 1. Building a Sample Display with Online Help Information . . . 1-1
Part 2. Programming Application Displays Using Display Files
Chapter 2. Defining Your Display in a Display File . . . . . . . . . . . . . . 2-1

Establishing a Display File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Determining File Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Deciding Whether to Describe Data Inside or Outside Your Program . . . . 2-3
Creating a Display File and Description . . . . . . . . . . . . . . . . . . . . . 2-4
Changing the File Description . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Detecting File Description Changes . . . . . . . . . . . . . . . . . . . . . . . . 2-6
Defining Display Fields and Functions in a Record Format . . . . . . . . . . . . 2-7
Understanding the Field Attribute Characters . . . . . . . . . . . . . . . . . . 2-8
Understanding How Record Format Fields Can Be Used . . . . . . . . . . . 2-9
Defining Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Defining Command Attention (CAnn) and Command Function (CFnn) Keys 2-12
Specifying Alternative Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13
Passing Information via Indicators . . . . . . . . . . . . . . . . . . . . . . . 2-14
Inserting Constant Field Text from a Message Description . . . . . . . . . 2-16
Allowing for Right-to-Left Cursor Movement . . . . . . . . . . . . . . . . . . 2-16
Defining Cursor Movement to Input-Capable Positions Only . . . . . . . . 2-16
Defining Cursor Progression for Entry Fields . . . . . . . . . . . . . . . . . 2-17
Defining Attributes for Entry Fields . . . . . . . . . . . . . . . . . . . . . . . 2-18
Protecting Entry Fields Using Edit Masks . . . . . . . . . . . . . . . . . . . 2-19
Specifying Right-to-Left Display Processing . . . . . . . . . . . . . . . . . . 2-19
Specifying Word Wrap for Fields . . . . . . . . . . . . . . . . . . . . . . . . 2-20
Emphasizing Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21
Adding Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22
Editing Output Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23
Defining Your Own Edit Codes . . . . . . . . . . . . . . . . . . . . . . . . . 2-23
Specifying Valid Screen Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . 2-24
Enabling Your Display to Be Printed . . . . . . . . . . . . . . . . . . . . . . 2-25
Defining Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27
Using Program-Described Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27
Defining Input-Only Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28
Defining Output-Only Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28
 Copyright IBM Corp. 1997 iii

Defining Input and Output Files . . . . . . . . . . . . . . . . . . . . . . . . . 2-28
Chapter 3. Working with Display Files in an Application . . . . . . . . . . 3-1

Understanding How the System Allocates Resources . . . . . . . . . . . . . . . 3-1
Opening Display Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Acquiring a Display Station for I/O Operations . . . . . . . . . . . . . . . . . . . 3-2
Obtaining Information about Display Files and Display Stations . . . . . . . . . 3-3
Obtaining Information about Open and I/O Operations . . . . . . . . . . . . . 3-3
Obtaining Attribute Information about Display Stations . . . . . . . . . . . . . 3-4
Sending and Receiving Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Determining Which Record Formats Are Active on a Display . . . . . . . . . 3-5
Writing Output to the Display . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Inviting Input to the Display . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30
Reading Invited Input from the Display . . . . . . . . . . . . . . . . . . . . . 3-31
Reading Input from the Display . . . . . . . . . . . . . . . . . . . . . . . . . 3-33
Writing Output and Reading Input at the Same Time . . . . . . . . . . . . 3-40
Canceling Input That Was Not Waited For . . . . . . . . . . . . . . . . . . . 3-41
Locking the Keyboard and Positioning the Cursor During I/O Operations . 3-41
Saving Previously Displayed Information . . . . . . . . . . . . . . . . . . . . 3-43
Understanding the Effects of I/O Operations on Command Keys . . . . . . 3-45
Avoiding Record Format Problems on the 5250 Display Station . . . . . . 3-45
Releasing an Acquired Display Station from I/O Operations . . . . . . . . . . 3-49
Closing Display Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-49
Mapping Display Operations to High-Level Language Operations . . . . . . . 3-49
Sharing Display Files in the Same Job . . . . . . . . . . . . . . . . . . . . . . 3-50
Understanding the Open Operation for Files Shared in a Job . . . . . . . . 3-51
Understanding the Input/Output Operation for Files Shared in a Job . . . 3-51
Understanding the Close Operation for Files Shared in a Job . . . . . . . 3-52
Chapter 4. Displaying Groups of Records Using Subfiles . . . . . . . . . . 4-1

Recognizing Subfile Uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Describing Subfiles in Your DDS Source . . . . . . . . . . . . . . . . . . . . . . 4-3
Using a Subfile in a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
Requesting I/O Operations for a Subfile . . . . . . . . . . . . . . . . . . . . . . 4-12
Requesting I/O Operations for a Subfile Record Format . . . . . . . . . . . 4-12
Requesting I/O Operations for a Subfile Control Record Format . . . . . . 4-15
Recognizing Subfile I/O Requests in High-Level Languages . . . . . . . . 4-15
Controlling the Appearance of Subfiles . . . . . . . . . . . . . . . . . . . . . . 4-16
Displaying Horizontal Subfiles with Display Modes . . . . . . . . . . . . . . . 4-17
Specifying Subfile Size Equal to Page Size . . . . . . . . . . . . . . . . . . . . 4-19
Specifying Subfile Size Not Equal to Page Size . . . . . . . . . . . . . . . . . 4-21
Checking Validity on Subfile Data . . . . . . . . . . . . . . . . . . . . . . . . . 4-22
Displaying Error Messages from Subfiles . . . . . . . . . . . . . . . . . . . . . 4-23
Positioning the Cursor on the Displayed Subfile . . . . . . . . . . . . . . . . . 4-24
Positioning the Cursor Initially . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24
Positioning the Cursor When a Roll Key Is Used . . . . . . . . . . . . . . . 4-24
Positioning the Cursor When a Fold or Truncate Key Is Used . . . . . . . 4-27
Positioning the Cursor and Rolling When Two or More Records Are
Displayed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-27
Understanding Subfile DDS and Program Logic–Example . . . . . . . . . . . 4-31
Chapter 5. Defining Windows with Display Files . . . . . . . . . . . . . . . 5-1

Window Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
DDS Window Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
iv Application Display Programming V4R1

Window Representation and Hardware Configuration . . . . . . . . . . . . . . . 5-3
Creating Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Window Definition Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Window Reference Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Window Size and Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Cursor Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Subfiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
DDS Help Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Defining Window Borders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Border Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Multiple Border Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
UIM Help Window Borders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
Defining a Window Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
Reading Data from Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
Changing Window Borders and Contents . . . . . . . . . . . . . . . . . . . . . 5-10
Moving and Duplicating Windows . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
Making Two Windows Seem Active at Once . . . . . . . . . . . . . . . . . . . 5-11
Making One Window in a Series Stand Out . . . . . . . . . . . . . . . . . . . 5-12
Removing Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
Removing All Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
Removing More Recent Windows . . . . . . . . . . . . . . . . . . . . . . . . 5-13
Improving Application Performance . . . . . . . . . . . . . . . . . . . . . . . . 5-13
System Save and Restore Operations . . . . . . . . . . . . . . . . . . . . . 5-13
Bypassing System Save and Restore Operations . . . . . . . . . . . . . . 5-14
Programming Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-15
Using Basic Window Functions . . . . . . . . . . . . . . . . . . . . . . . . . 5-16
Defining Windows in a Separate Display File . . . . . . . . . . . . . . . . . 5-20
RPG Program Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21
RPG Program Source for WINPGM . . . . . . . . . . . . . . . . . . . . . . 5-22
Chapter 6. Creating a Graphical Look for Displays . . . . . . . . . . . . . . 6-1

Factors Affecting the Graphical Look . . . . . . . . . . . . . . . . . . . . . . . . 6-1
Hardware Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
Enhanced Display Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4
DDS Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
Creating Menu Bars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Defining the Menu-Bar Choices . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Suppressing the Menu-Bar Separator . . . . . . . . . . . . . . . . . . . . . . 6-8
Defining the Menu-Bar Separator . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
Selection Fields—Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
DDS for Selection Fields—Example . . . . . . . . . . . . . . . . . . . . . . 6-12
Creating a Vertical Single-Choice Selection Field . . . . . . . . . . . . . . . 6-13
Creating a Vertical Multiple-Choice Selection Field . . . . . . . . . . . . . . 6-14
Creating a Horizontal Selection Field . . . . . . . . . . . . . . . . . . . . . . 6-14
Cursor Movement in a Vertical Selection Field . . . . . . . . . . . . . . . . 6-15
Cursor Movement in a Horizontal Selection Field . . . . . . . . . . . . . . . 6-16
Controlling the Selection Indicators in a Selection Field . . . . . . . . . . . 6-17
Creating Pull-Down Menus Using Single-Choice Selection Fields . . . . . . . 6-18
Controlling the Selection Indicators in a Pull-Down Menu . . . . . . . . . . 6-20
Defining Accelerator Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-21
Defining a Menu-Bar Switch Key . . . . . . . . . . . . . . . . . . . . . . . . 6-22
Defining a Cancel Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-23
Limiting Function When Cursor is Outside a Pull-Down Menu . . . . . . . 6-24
Contents v
Selection Lists—Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24
DDS for Selection Lists—Example . . . . . . . . . . . . . . . . . . . . . . . 6-26
Creating Selection Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26
Controlling the Selection Indicators in a Selection List . . . . . . . . . . . . 6-28
Scroll Bars—Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30
Creating a Scroll Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-31
DDS for Scroll Bars—Example . . . . . . . . . . . . . . . . . . . . . . . . . 6-33
Scroll Bar Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-33
Push Buttons—Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34
DDS for Push Buttons—Example . . . . . . . . . . . . . . . . . . . . . . . . 6-35
Creating Push Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-35
Controlling the Availability of Choices . . . . . . . . . . . . . . . . . . . . . . . 6-36
Auto-Selection in Single-Choice Selection Fields . . . . . . . . . . . . . . . . 6-37
Auto-Enter in Single-Choice Selection Fields . . . . . . . . . . . . . . . . . . . 6-38
Defining Mnemonics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-38
Defining Choice Colors and Attributes . . . . . . . . . . . . . . . . . . . . . . . 6-39
Continued-Entry Fields—Overview . . . . . . . . . . . . . . . . . . . . . . . . . 6-42
Specifying Word Wrap on Continued-Entry Fields . . . . . . . . . . . . . . 6-43
DBCS Considerations with Continued-Entry Fields . . . . . . . . . . . . . . 6-43
How DBCS Data is Returned for Continued-Entry Fields . . . . . . . . . . 6-44
Keyboard Functions with Continued-Entry Fields . . . . . . . . . . . . . . . 6-44
Forward Field-Exit Processing . . . . . . . . . . . . . . . . . . . . . . . . . . 6-49
Backward Field-Exit Processing . . . . . . . . . . . . . . . . . . . . . . . . . 6-49
How the Menu Bar Interacts with the Application . . . . . . . . . . . . . . . . 6-50
Defining the MNUBARDSP Keyword on the Application Record . . . . . . 6-50
Defining the MNUBARDSP Keyword on the Menu-Bar Record . . . . . . . 6-51
Receiving Input from the Pull-Down Menus . . . . . . . . . . . . . . . . . . 6-53
Removing a Pull-Down Menu after Receiving Input . . . . . . . . . . . . . 6-55
Updating a Pull-Down Menu before Displaying . . . . . . . . . . . . . . . . 6-55
Defining Application Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-56
Defining Choice-Level Help . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-56
Defining Help for a Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-59
Key Interaction for Menu Bars and Pull-Down Menus . . . . . . . . . . . . . . 6-60
Cursor Movement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-61
Pressing the Tab Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-61
Pressing the Cursor Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-62
Using the MNUBARDSP Keyword on the Application Record . . . . . . . . 6-62
Using the MNUBARDSP Keyword on the Menu-Bar Record . . . . . . . . 6-65
How the Displays Look . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-67
Simple Hotspots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-68
Command Key Emulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-68
Page Up and Page Down Key Emulation . . . . . . . . . . . . . . . . . . . 6-69
Programmable Mouse Buttons—Overview . . . . . . . . . . . . . . . . . . . . 6-69
Pointer Device Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-69
AID Codes to be Returned . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-70
Programmable Mouse Buttons—Benefits . . . . . . . . . . . . . . . . . . . 6-70
Programmable Mouse Buttons Operation . . . . . . . . . . . . . . . . . . . 6-71
Programmable Mouse Buttons—NWS Considerations . . . . . . . . . . . . 6-72
Programmable Mouse Buttons—Event Processing States . . . . . . . . . . 6-72
Programmable Mouse Buttons—Event Processing Priority . . . . . . . . . 6-73
Grid Line Structures—Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 6-79
DDS for Grid Line Structures—Example . . . . . . . . . . . . . . . . . . . . 6-80
Grid Line Structures and Windows . . . . . . . . . . . . . . . . . . . . . . . 6-81
vi Application Display Programming V4R1

Hardware Requirements for Grid Line Structures . . . . . . . . . . . . . . . 6-82
Inserting HTML Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-82
Resolving HTML Field Overlap . . . . . . . . . . . . . . . . . . . . . . . . . 6-83
Chapter 7. Overriding Display Files and Display File Attributes . . . . . . 7-1

Determining Whether or Not to Use Overrides . . . . . . . . . . . . . . . . . . . 7-1
Overriding File Attributes in HLL Programs . . . . . . . . . . . . . . . . . . . . . 7-1
Overriding File Names in HLL Programs . . . . . . . . . . . . . . . . . . . . . . 7-3
Overriding Both File Names and Attributes in HLL Programs . . . . . . . . . . 7-3
Applying Overrides When Compiling a Program . . . . . . . . . . . . . . . . . . 7-4
Deleting Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
Displaying Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6
Using File Redirection to Override File Names and Libraries or File Types . . 7-6
Overriding Files with the Same File Types . . . . . . . . . . . . . . . . . . . . 7-6
Overriding Files with Different File Types . . . . . . . . . . . . . . . . . . . . 7-6
Recognizing Commands That Ignore or Restrict Overrides . . . . . . . . . . . . 7-9
Chapter 8. Handling Messages and Errors for Display Files . . . . . . . . 8-1

Creating and Displaying Your Own Messages . . . . . . . . . . . . . . . . . . . 8-1
Displaying a Message on the Message Line . . . . . . . . . . . . . . . . . . 8-2
Displaying a Message on the Message Line When a Subfile Control Record
is Written . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Displaying a Message on the Message Line Using a Message Field . . . . 8-3
Priorities for Displaying Messages on a Message Line . . . . . . . . . . . . 8-3
Displaying Messages in a Field on the Display . . . . . . . . . . . . . . . . . 8-3
Displaying Messages on a Program Message Queue . . . . . . . . . . . . . 8-4
Displaying Error Messages through a Subfile . . . . . . . . . . . . . . . . . . 8-4
Sounding an Alarm for Messages . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
Automatically Handling Permanent I/O Errors on Display Stations . . . . . . 8-7
Analyzing Error Messages Sent from the System . . . . . . . . . . . . . . . . . 8-8
Understanding Messages and Message Monitors . . . . . . . . . . . . . . . 8-9
Understanding Major/Minor Return Codes . . . . . . . . . . . . . . . . . . . 8-10
Recovering from Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11
Chapter 9. Creating and Accessing Menus Using Display Files . . . . . . 9-1

Running System and User-Defined Menus . . . . . . . . . . . . . . . . . . . . . 9-1
Returning to a Menu after Running the GO command . . . . . . . . . . . . . 9-1
Determining the Previous Menu . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1
Using the Cancel and Exit Keys on Menus . . . . . . . . . . . . . . . . . . . 9-2
Choosing the Menu That Is Shown at Sign-On Time . . . . . . . . . . . . . . 9-3
Defining Your Own Display File Menus . . . . . . . . . . . . . . . . . . . . . . . 9-4
Understanding DDS and Display File Considerations for Menus . . . . . . . 9-4
Describing Menu Actions in a Message File . . . . . . . . . . . . . . . . . . . 9-5
Naming Help Formats for Menus . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
Building a Display File Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7
Defining Your Own Program Menus . . . . . . . . . . . . . . . . . . . . . . . . 9-10
Passing Parameters for Program Menus . . . . . . . . . . . . . . . . . . . . 9-10
Building a Program Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11
Exiting from a Program Menu without Returning to the Previous Menu . . 9-13
Avoiding Menu Name Conflict . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-15
Naming Your Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-15
Placing Your Menu in a Higher Library in the Library List . . . . . . . . . . 9-16
Specifying the Library That Contains the Menu . . . . . . . . . . . . . . . . 9-16
Contents vii
Using the Generic Menu Specification . . . . . . . . . . . . . . . . . . . . . 9-16
Changing the Command Default after Duplicating a Command . . . . . . . 9-16
Displaying Menu Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16
Changing Menu Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16
Deleting Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17
Chapter 10. Using User-Defined Data Streams . . . . . . . . . . . . . . . . 10-1

Understanding Display Station Differences . . . . . . . . . . . . . . . . . . . . 10-1
Understanding User-Defined Data Stream Limitations . . . . . . . . . . . . . . 10-2
Chapter 11. Passing Data between Programs . . . . . . . . . . . . . . . . 11-1

Passing Data in the Same Routing Step in a Job . . . . . . . . . . . . . . . . 11-1
Passing Data between Routing Steps in a Job . . . . . . . . . . . . . . . . . . 11-3
Chapter 12. Waiting for Input from a Display File, an ICF File, and a
Data Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1
Chapter 13. Using Alternative Character Sets and Code Pages . . . . . 13-1
Specifying Character Translation for Fields . . . . . . . . . . . . . . . . . . . . 13-2
Determining the Character Identifier (CHRID) Value for Your Display . . . . . 13-4
Chapter 14. Improving System Performance with Displays . . . . . . . . 14-1

Deferring the Write Operation for a Display File . . . . . . . . . . . . . . . . . 14-1
Designating the Primary Screen Size for a Display File . . . . . . . . . . . . . 14-1
Writing Only One Page of Subfile Records at a Time . . . . . . . . . . . . . . 14-1
Sharing an Open Data Path (ODP) for the Same Job . . . . . . . . . . . . . . 14-2
Sending Records with Input Fields to the Display in Order . . . . . . . . . . . 14-2
Overlapping and Not Deleting Repeatedly Sent Records . . . . . . . . . . . . 14-2
Restoring the Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Defining Command Attention Keys Rather Than Command Function Keys . 14-3
Using the Invite Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Using Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4
Part 3. Programming Application Displays Using Panel Groups
Chapter 15. Improving Productivity with User Interface Manager . . . . 15-1

Increasing User Productivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1
Increasing Application Programmer Productivity . . . . . . . . . . . . . . . . . 15-1
What to Consider before Using UIM Instead of Data Description
Specifications (DDS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1
Chapter 16. Introduction to the User Interface Manager . . . . . . . . . . 16-1

Overview of UIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1
What the UIM Supports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2
What Is a Panel Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2
What Is a Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2
Creating Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-3
Elements Within a Panel Group . . . . . . . . . . . . . . . . . . . . . . . . . . 16-3
Using the UIM Language Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-4
Using Dialog Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-4
Using Control Language (CL) Commands . . . . . . . . . . . . . . . . . . . . 16-5
Using an Application Programming Interface (API) . . . . . . . . . . . . . . . 16-5
Defining a Menu Object Using UIM . . . . . . . . . . . . . . . . . . . . . . . . 16-6
viii Application Display Programming V4R1

Creating a Menu Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-6
Required Tags for a Menu Panel . . . . . . . . . . . . . . . . . . . . . . . . 16-8
Source for Example Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-9
Defining a Panel Group Object Using UIM . . . . . . . . . . . . . . . . . . . 16-13
Creating a List Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-13
Required Tags for a List Panel . . . . . . . . . . . . . . . . . . . . . . . . 16-16
Source for Example List Panel . . . . . . . . . . . . . . . . . . . . . . . . 16-17
Application Programming for a List Panel . . . . . . . . . . . . . . . . . . 16-25
Creating a Confirmation List Panel . . . . . . . . . . . . . . . . . . . . . . . . 16-27
Required Tags for a Confirmation List Panel . . . . . . . . . . . . . . . . 16-28
Source for Example Confirmation Panel . . . . . . . . . . . . . . . . . . . 16-28
Automatic Confirmation Processing . . . . . . . . . . . . . . . . . . . . . . 16-31
Application Programming for Confirmation Processing . . . . . . . . . . . 16-31
Creating a Data Presentation Panel . . . . . . . . . . . . . . . . . . . . . . . 16-32
Required Tags for a Data Presentation Panel . . . . . . . . . . . . . . . . 16-34
Source for Example Data Presentation Panel . . . . . . . . . . . . . . . . 16-35
Application Programming for a Data Presentation Panel . . . . . . . . . . 16-46
Data Entry Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-49
Creating a Panel with a Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . 16-50
Required Tags for a Panel with a Menu Bar . . . . . . . . . . . . . . . . . 16-52
Source for Example Panel with a Menu Bar . . . . . . . . . . . . . . . . . 16-53
Application Programming for a Menu Bar Panel . . . . . . . . . . . . . . 16-63
Chapter 17. Details of Using User Interface Manager . . . . . . . . . . . . 17-1

Opening a UIM Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1
Defining Dialog Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1
Restrictions on Using Dialog Variables . . . . . . . . . . . . . . . . . . . . . 17-3
Dialog Variable Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . 17-3
Providing Field Values for a Display Panel Using Dialog Variables . . . . 17-4
Using Variable Pool Services . . . . . . . . . . . . . . . . . . . . . . . . . . 17-4
Character Set and Code Page Considerations . . . . . . . . . . . . . . . . 17-5
Managing a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-7
Defining a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-8
Initializing a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-8
Displaying a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-8
Updating a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-9
Incomplete List Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-9
Removing and Inserting an Entry from a List . . . . . . . . . . . . . . . . 17-10
Controlling List Entries on a List Display . . . . . . . . . . . . . . . . . . . 17-10
Improving Interactive Response Time for a List Display . . . . . . . . . . 17-11
Using Action Lists and Selection Lists . . . . . . . . . . . . . . . . . . . . 17-11
Using Selection Characters . . . . . . . . . . . . . . . . . . . . . . . . . . 17-13
Managing Panel Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-13
Enabling Conversion to a GUI . . . . . . . . . . . . . . . . . . . . . . . . . . 17-14
Scrolling Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-14
Defining Scrollable Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-14
Defining Function Key Scrolling . . . . . . . . . . . . . . . . . . . . . . . . 17-15
Scrolling and Error Conditions . . . . . . . . . . . . . . . . . . . . . . . . . 17-15
Scrolling a List Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-15
Scrolling a Menu Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-16
Scrolling an Information Area . . . . . . . . . . . . . . . . . . . . . . . . . 17-16
Scrolling Data Item Groups . . . . . . . . . . . . . . . . . . . . . . . . . . 17-16
Scrolling a Text Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-16
Defining Contextual Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-16
Contents ix
Command Line Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-19
Command Line Interpretation . . . . . . . . . . . . . . . . . . . . . . . . . 17-19
Entering Commands That Are Too Long . . . . . . . . . . . . . . . . . . . 17-20
Formatting Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-20
Handling Function Keys and VARUPD Value . . . . . . . . . . . . . . . . 17-21
Panel Formatting Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-22
When Panel Formatting Is Performed . . . . . . . . . . . . . . . . . . . . 17-22
Application Control of Panel Formatting . . . . . . . . . . . . . . . . . . . 17-23
Limits of the Panel Formatter . . . . . . . . . . . . . . . . . . . . . . . . . 17-24
Folding Up Multiple Panels When EXIT Is Requested . . . . . . . . . . . . . 17-24
Folding Up a List Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-26
Adding a Pop-Up Window over Another Panel . . . . . . . . . . . . . . . 17-27
Using Menu Bars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-27
Differences Between Pull-Down Menus and Pop-Up Windows . . . . . . 17-28
Using Pop-Up Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-30
Defining Application Windows . . . . . . . . . . . . . . . . . . . . . . . . . 17-30
Adding and Removing Windows . . . . . . . . . . . . . . . . . . . . . . . 17-31
Using the Command Line in a Window . . . . . . . . . . . . . . . . . . . . 17-32
UIM as a Request Processor Program When Displaying a Panel . . . . . . 17-33
Printing Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-33
Printing a Print Head Panel . . . . . . . . . . . . . . . . . . . . . . . . . . 17-35
Printing a Print Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-35
Using Blank Lines for Separating . . . . . . . . . . . . . . . . . . . . . . . 17-36
Fonts and Highlighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-36
Printing the Trailer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-36
Defining Prolog Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-36
Defining Header Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-36
Using the Page-Eject Function During Printing . . . . . . . . . . . . . . . 17-37
Sharing and Overriding Printer Files . . . . . . . . . . . . . . . . . . . . . 17-37
Printing Double-Byte Character Set (DBCS) Considerations . . . . . . . 17-37
Commonly Asked UIM Questions . . . . . . . . . . . . . . . . . . . . . . . 17-37
Part 4. Programming Help Displays
Chapter 18. Making Online Help Information Accessible for Your

Display File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1
Enabling the Help Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2
Choosing between Panel Groups, Documents, and Records for Help . . . . 18-2
Defining Which Areas of Your Display Need Online Help Information . . . . . 18-3
Specifying Panel Groups for Help in Your Display File . . . . . . . . . . . . . 18-6
Copying QUSRTOOL Examples That Specify Help Using Panel Groups . 18-9
Specifying Documents in Your Display File . . . . . . . . . . . . . . . . . . . . 18-9
Specifying Records in Your Display File . . . . . . . . . . . . . . . . . . . . . 18-12
Entering the Records That Contain the Help Information . . . . . . . . . 18-14
Using Records and Documents for Help in the Same Display File . . . . 18-15
Understanding the Restrictions on Records . . . . . . . . . . . . . . . . . 18-15
Paging between Help Displays That Use Records . . . . . . . . . . . . . 18-16
Returning Control to Your Program after Pressing the Help Key . . . . . . 18-20
Returning Control to Your Program after Showing the Help Display . . . 18-20
Returning Control to Your Program without Showing the Help Display . 18-22
Chapter 19. Making Online Help Accessible for Your Panel Group . . . 19-1
x Application Display Programming V4R1

Definitions and Explanations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-1
Help in a List Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-5
Coding Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-6
Help in a Menu Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-7
Coding Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-7
Help in a Data Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-9
Coding Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-10
Help in a Menu Bar Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-13
Coding Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-14
Help in a Function Key Area . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-15
Coding Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-16
Chapter 20. Defining Online Help Information . . . . . . . . . . . . . . . . 20-1

Defining Online Help Information in a Panel Group . . . . . . . . . . . . . . . 20-1
Entering the UIM Source for a Panel Group for Help . . . . . . . . . . . . . 20-1
Creating and Deleting Panel Groups . . . . . . . . . . . . . . . . . . . . . 20-15
Assigning Panel Groups as Help for Commands . . . . . . . . . . . . . . 20-16
Using Panel Groups in a Search Index . . . . . . . . . . . . . . . . . . . . 20-16
Copying QUSRTOOL Examples That Define Help in a Panel Group . . 20-18
Defining Online Information in a Document . . . . . . . . . . . . . . . . . . . 20-18
Creating a Document for Help . . . . . . . . . . . . . . . . . . . . . . . . . 20-18
Viewing the Document without Pressing the Help Key . . . . . . . . . . . 20-19
Defining Online Help Information in a DDS Record . . . . . . . . . . . . . . 20-19
Part 5. Guidelines for IBM AS/400-Style Displays
Chapter 21. Designing IBM AS/400-Style Displays . . . . . . . . . . . . . 21-1

Using the Displays Example in the QUSRTOOL Library . . . . . . . . . . . . 21-1
Recognizing the Example Objects . . . . . . . . . . . . . . . . . . . . . . . 21-1
Installing the Example Objects . . . . . . . . . . . . . . . . . . . . . . . . . 21-4
Viewing the Sample Displays, Command, and Online Help Information . . 21-4
Copying the Source for the Example Objects for Your Own Use . . . . . . 21-7
Defining Special Functions and Attributes for All Displays . . . . . . . . . . . 21-8
Designing the Single-Choice Menu Display . . . . . . . . . . . . . . . . . . . . 21-8
Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-9
Instruction Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-9
Menu Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-9
Menu Selection Entry Field . . . . . . . . . . . . . . . . . . . . . . . . . . 21-10
Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-10
Online Help Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-10
General Menu Display Operation . . . . . . . . . . . . . . . . . . . . . . . 21-10
Designing the Entry Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-11
Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-11
Instruction Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-12
Prompt Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-12
Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-17
General Entry Display Operation . . . . . . . . . . . . . . . . . . . . . . . 21-17
Designing the Information Display . . . . . . . . . . . . . . . . . . . . . . . . 21-17
Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-19
Location Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-19
Prompt Area 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-19
Prompt Area 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-20
Contents xi
Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-20
General Information Display Operation . . . . . . . . . . . . . . . . . . . . 21-21
Designing the List Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-21
Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-22
Prompt Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-22
Options Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-23
Column Headings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-24
Extended Action Entry Area . . . . . . . . . . . . . . . . . . . . . . . . . . 21-24
List Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-24
Paging Location Information . . . . . . . . . . . . . . . . . . . . . . . . . . 21-25
Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-25
General List Display Operation . . . . . . . . . . . . . . . . . . . . . . . . 21-26
Defining the Function Key Area for All Displays . . . . . . . . . . . . . . . . 21-33
Optional Command Line and Identifier Field . . . . . . . . . . . . . . . . . 21-34
Common Key Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . 21-38
Defining Help Information for All Displays . . . . . . . . . . . . . . . . . . . . 21-44
Help for the Menu Display . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-44
Help for the Entry Display . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-46
Help for the Information Display . . . . . . . . . . . . . . . . . . . . . . . . 21-47
Help for the List Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-48
Defining and Presenting Messages . . . . . . . . . . . . . . . . . . . . . . . 21-49
Designing Common User Access (CUA) Entry Level Models . . . . . . . . 21-50
Entry Dialog Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-51
Single-Choice Selection (Menu) . . . . . . . . . . . . . . . . . . . . . . . . 21-52
Entry Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-53
Information Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-55
List Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-55
Help Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-57
Part 6. Appendixes
Appendix A. UIM Panel Group Definition Language . . . . . . . . . . . . A-1

Panel Group Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4
Name Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4
Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
Imbeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
DBCS Graphic Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
Hexadecimal Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
APPFMT (Application Formatted Area) . . . . . . . . . . . . . . . . . . . . . . A-8
Required Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8
Optional Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-8
Application Formatted Data . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9
Example: Application Formatted Area . . . . . . . . . . . . . . . . . . . . . A-9
BOTINST (Bottom Instruction) . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10
CHECK (Validity Checking) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-11
Required Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-11
xii Application Display Programming V4R1

Optional Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-11
Example: Validity Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . A-12
CIT (Title Citation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13
Example: Title Citations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13
CLASS (Class Definition) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-14
Example: Class Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . A-24
Display Forms of Numeric Values . . . . . . . . . . . . . . . . . . . . . . . . A-24
Display Forms of Character, Date, and Time Values . . . . . . . . . . . . . A-25
CMDLINE (Command Line) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-26
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-26
COND (Condition Definition) . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-27
Example: Conditioning an Option . . . . . . . . . . . . . . . . . . . . . . . . A-29
COPYR (Copyright) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-30
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-30
DATA (Data Presentation Area) . . . . . . . . . . . . . . . . . . . . . . . . . . A-31
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-33
Print Formatting Considerations . . . . . . . . . . . . . . . . . . . . . . . . . A-33
Example 1: Data Entry Panel . . . . . . . . . . . . . . . . . . . . . . . . . . A-34
Example 2: Two-Column Format in a Data Entry Panel . . . . . . . . . . . A-34
Example 3: Two Presentation Areas for Data Items . . . . . . . . . . . . . A-35
Example 4: Data Presentation Area with a Menu Area . . . . . . . . . . . A-36
Example 5: Data Entry Panel with a Nested Data Group . . . . . . . . . . A-36
DATAC (Data Item Choices) . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-38
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-38
DATACOL (Data Column) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-39
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-39
DATAGRP (Data Group) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-40
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-41
DATAI (Data Item) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-42
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-45
DATAIX (Data Item Extender) . . . . . . . . . . . . . . . . . . . . . . . . . . . A-47
DATASLT (Data Selection Field) . . . . . . . . . . . . . . . . . . . . . . . . . . A-51
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-52
Example 2: Multiple-Selection Field . . . . . . . . . . . . . . . . . . . . . . A-53
DATASLTC (Data Selection Field Choice) . . . . . . . . . . . . . . . . . . . . A-55
Contents xiii
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-56
DL (Definition List) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-57
Required Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-57
Optional Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-58
Example 1: Definition List . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-58
Example 2: Compact Definition List . . . . . . . . . . . . . . . . . . . . . . A-58
FIG (Figure) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-59
Optional Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-59
Example: Sample Figure . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-59
HELP (Help Module) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-60
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-61
Example: Help Panel Definition . . . . . . . . . . . . . . . . . . . . . . . . . A-62
HP0 through HP9 (Highlighted Phrase) . . . . . . . . . . . . . . . . . . . . . . A-63
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-63
H1 through H4 (Heading) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-65
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-65
Example: Heading Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-65
IMHELP (Imbed Help) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-66
Example: Imbedded Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-66
IMPORT (Import) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-67
INFO (Information Area) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-68
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-68
ISCH (Index Search) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-70
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-70
Example: Index Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-70
ISCHSUBT (Index Search Subtopic) . . . . . . . . . . . . . . . . . . . . . . . . A-71
Example: Index Search Hierarchy . . . . . . . . . . . . . . . . . . . . . . . A-71
ISCHSYN (Index Search Synonym) . . . . . . . . . . . . . . . . . . . . . . . . A-72
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-72
Example: Index Search Synonyms . . . . . . . . . . . . . . . . . . . . . . . A-72
KEYI (Key List Item) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-74
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-75
Example: Key Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-75
KEYL (Key List) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-76
Example: Key List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-76
LINES (Unformatted Lines) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-77
xiv Application Display Programming V4R1

Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-77
Example: Unformatted Lines . . . . . . . . . . . . . . . . . . . . . . . . . . A-77
LINK (Hypertext Link Definition) . . . . . . . . . . . . . . . . . . . . . . . . . . A-78
Conditional Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-79
Bidirectional Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . A-80
Example: Hypertext Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-80
LIST (List Area) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-82
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-85
Example 1: List Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-86
Example 2: List Area with Three Layout Columns . . . . . . . . . . . . . . A-87
Example 3: List Area with List Column Groups . . . . . . . . . . . . . . . . A-87
Example 4: Dynamic List Column Heading Formatting . . . . . . . . . . . A-88
LISTACT (List Action) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-90
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-94
Confirmation Panel Requirements . . . . . . . . . . . . . . . . . . . . . . . A-94
Confirmation Panel Conventions . . . . . . . . . . . . . . . . . . . . . . . . A-94
Example: List Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-95
LISTCOL (List Column) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-96
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-99
Formatting Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-99
LISTDEF (List Definition) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-100
Required Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-100
Optional Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-100
LISTGRP (List Column Group) . . . . . . . . . . . . . . . . . . . . . . . . . . A-103
Optional Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-103
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-104
Example: List Column Group . . . . . . . . . . . . . . . . . . . . . . . . . A-104
LISTVIEW (List View) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-105
Required Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-105
LP (List Part) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-107
Example: List Part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-107
MBAR (Menu Bar) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-108
Example: Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-108
MBARC (Menu Bar Choice) . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-110
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-110
MENU (Menu Area) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-111
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-112
Example 1: Simple Menu Area . . . . . . . . . . . . . . . . . . . . . . . . A-112
Contents xv
Example 2: Menu Area with Groups . . . . . . . . . . . . . . . . . . . . . A-112
MENUGRP (Menu Group) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-114
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-114
MENUI or MI (Menu Item) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-115
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-116
NT or NOTE (Note) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-117
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-117
Example: Using a Note . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-117
OL (Ordered List) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-118
Required Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-119
Example: Ordered List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-119
OPTLINE (Option Line) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-120
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-120
P (Paragraph) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-121
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-121
Example: Paragraph Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . A-121
PANEL (Display Panel) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-122
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-127
Example: Panel Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . A-127
PARML (Parameter List) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-129
Required Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-129
Example: Parameter List . . . . . . . . . . . . . . . . . . . . . . . . . . . A-130
PC (Paragraph Continuation) . . . . . . . . . . . . . . . . . . . . . . . . . . . A-131
Example: Paragraph Continuation . . . . . . . . . . . . . . . . . . . . . . A-131
PDACCEL (Pull-Down Accelerator) . . . . . . . . . . . . . . . . . . . . . . . A-132
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-132
PDFLD (Pull-Down Field) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-133
PDFLDC (Pull-Down Field Choice) . . . . . . . . . . . . . . . . . . . . . . . . A-134
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-136
Confirmation Panel Requirements . . . . . . . . . . . . . . . . . . . . . . A-136
Confirmation Panel Conventions . . . . . . . . . . . . . . . . . . . . . . . A-136
PK (Programming Keyword) . . . . . . . . . . . . . . . . . . . . . . . . . . . A-138
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-138
PNLGRP (Panel Group) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-139
PRTHEAD (Print Head Panel) . . . . . . . . . . . . . . . . . . . . . . . . . . A-142
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-143
Layout of the Title Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-143
Example: Print Title Line . . . . . . . . . . . . . . . . . . . . . . . . . . . A-145
PRTPNL (Print Panel) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-146
xvi Application Display Programming V4R1

Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-146
PRTTRAIL (Print Trailer Message) . . . . . . . . . . . . . . . . . . . . . . . . A-148
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-148
Example: Trailer Message . . . . . . . . . . . . . . . . . . . . . . . . . . . A-148
PV (Programming Variable) . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-149
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-149
RT (Reverse Text) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-150
Example 1: Left-to-Right Formatting on a Right-to-Left Panel . . . . . . A-150
Example 2: Left-to-Right Formatting on a Left-to-Right Panel . . . . . . A-151
SL (Simple List) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-152
Required Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-152
Example: Simple Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-153
TEXT (Text Area) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-154
Cursor positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-155
Text Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-155
Example: Text area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-157
TI (Translation List Item) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-158
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-158
TL (Translation List) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-159
Examples: Translation List . . . . . . . . . . . . . . . . . . . . . . . . . . A-159
TOPINST (Top Instruction) . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-161
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-161
TT (Truth Table) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-162
Example: Truth Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-162
TTROW (Truth Table Row) . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-163
UL (Unordered List) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-164
Required Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-165
Example: Unordered Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . A-165
VAR (Variable Definition) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-166
Dialog Variables Defined by UIM . . . . . . . . . . . . . . . . . . . . . . . A-166
VARRCD (Variable Record Definition) . . . . . . . . . . . . . . . . . . . . . . A-169
XH1 through XH4 (Extended Help Headings) . . . . . . . . . . . . . . . . . A-170
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-170
Formatting Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-170
Example: Sample Headings . . . . . . . . . . . . . . . . . . . . . . . . . . A-170
XMP (Example) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-171
Example: Formatting an Example . . . . . . . . . . . . . . . . . . . . . . A-171
Appendix B. UIM Dialog Commands . . . . . . . . . . . . . . . . . . . . . . B-1

The VARUPD Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4
Contents xvii
ACTIONS (Menu Bar Cursor Action) . . . . . . . . . . . . . . . . . . . . . . B-4
CALL (Call Program) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4
CANCEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-6
CHGVIEW (Change View) . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-6
CMD (System Command) . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-7
CMDLINE (Command Line) . . . . . . . . . . . . . . . . . . . . . . . . . . . B-7
DSPHELP (Display Help) . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-7
ENTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-8
EXIT (Exit Display) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-8
EXTHELP (Extended Help) . . . . . . . . . . . . . . . . . . . . . . . . . . . B-9
HELP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-9
HELPHELP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-9
HELPIDX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-9
HOME (Display Home Menu) . . . . . . . . . . . . . . . . . . . . . . . . . . B-9
KEYSHELP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-10
MENU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-10
MOREKEYS (Display More Function Keys) . . . . . . . . . . . . . . . . . . B-10
MOVETOP (Move to Top) . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-11
MSG (Display Message) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-11
PAGEDOWN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-11
PAGEUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-12
PRINT (Print Display) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-12
PROMPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-13
PULLDOWN (Display Pull-Down Menu) . . . . . . . . . . . . . . . . . . . . B-14
RETRIEVE (Retrieve Command String) . . . . . . . . . . . . . . . . . . . . B-14
RETURN (Return Control to Application) . . . . . . . . . . . . . . . . . . . B-14
Appendix C. Feedback Area Layouts for Display Files . . . . . . . . . . . C-1

Open Feedback Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1
Device Definition List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-4
I/O Feedback Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-6
Common I/O Feedback Area . . . . . . . . . . . . . . . . . . . . . . . . . . C-6
I/O Feedback Area for Display Files . . . . . . . . . . . . . . . . . . . . . . C-9
Get Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-12
Appendix D. Double-Byte Character Set Support for Displays . . . . . . D-1

Double-Byte Character Set Fundamentals . . . . . . . . . . . . . . . . . . . . D-1
DBCS Code Scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-1
Shift-Control Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-3
Using Double-Byte Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-3
Double-Byte Character Size . . . . . . . . . . . . . . . . . . . . . . . . . . . D-4
Processing Double-Byte Characters . . . . . . . . . . . . . . . . . . . . . . . . D-4
Basic Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-4
Extended Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-4
What Happens When Extended Characters Are Not Processed . . . . . . D-4
Device File Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-5
What a DBCS File Is . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-5
When to Indicate a DBCS File . . . . . . . . . . . . . . . . . . . . . . . . . . D-5
How to Indicate a DBCS File . . . . . . . . . . . . . . . . . . . . . . . . . . D-5
Improperly Indicated DBCS Files . . . . . . . . . . . . . . . . . . . . . . . . D-6
Display Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-6
Inserting Shift-Control Characters . . . . . . . . . . . . . . . . . . . . . . . . D-6
Number of Displayed Extended Characters . . . . . . . . . . . . . . . . . . D-6
Number of Input Fields on a Display . . . . . . . . . . . . . . . . . . . . . . D-6
xviii Application Display Programming V4R1

Effects of Displaying Double-Byte Data at Alphanumeric Work Stations . . D-7
Effects of Displaying DBCS-Graphic Fields on Double-Byte Displays . . . D-7
Application Program Considerations . . . . . . . . . . . . . . . . . . . . . . . . D-7
Designing Application Programs That Process Double-Byte Data . . . . . D-7
Changing Alphanumeric Application Programs to DBCS Application
Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-8
DBCS Font Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-8
Finding Out if a DBCS Font Table Exists . . . . . . . . . . . . . . . . . . . D-8
Copying a DBCS Font Table onto Tape or Diskette . . . . . . . . . . . . . D-9
Copying a DBCS Font Table from Tape or Diskette . . . . . . . . . . . . . D-9
Deleting a DBCS Font Table . . . . . . . . . . . . . . . . . . . . . . . . . . D-10
Starting the Character Generator Utility . . . . . . . . . . . . . . . . . . . . D-10
Copying User-Defined Double-Byte Characters . . . . . . . . . . . . . . . . D-10
DBCS Font Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-10
DBCS Sort Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-11
Using DBCS Sort Tables on the System . . . . . . . . . . . . . . . . . . . . D-12
Finding Out if a DBCS Sort Table Exists . . . . . . . . . . . . . . . . . . . . D-12
Saving a DBCS Sort Table onto Tape or Diskette . . . . . . . . . . . . . . D-12
Restoring a DBCS Sort Table from Tape or Diskette . . . . . . . . . . . . . D-12
Copying a Japanese DBCS Master Sort Table to a Data File . . . . . . . . D-12
Copying a Japanese DBCS Master Sort Table from a Data File . . . . . . D-13
Deleting a DBCS Sort Table . . . . . . . . . . . . . . . . . . . . . . . . . . . D-14
DBCS Conversion Dictionaries . . . . . . . . . . . . . . . . . . . . . . . . . . . D-14
System-Supplied Dictionary (for Japanese Use Only) . . . . . . . . . . . . D-14
User-Created Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-15
Commands for DBCS Conversion Dictionaries . . . . . . . . . . . . . . . . D-15
Displaying and Printing the DBCS Conversion Dictionary . . . . . . . . . . D-19
Deleting a DBCS Conversion Dictionary . . . . . . . . . . . . . . . . . . . . D-19
DBCS Conversion (for Japanese Use Only) . . . . . . . . . . . . . . . . . . . D-19
Where You Can Use DBCS Conversion . . . . . . . . . . . . . . . . . . . . D-20
How DBCS Conversion Works . . . . . . . . . . . . . . . . . . . . . . . . . D-20
Using DBCS Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-20
Performing DBCS Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . D-21
Appendix E. Display File Return Codes . . . . . . . . . . . . . . . . . . . . E-1

Major Code 00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1
Major Code 02 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1
Major Code 03 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2
Major Code 04 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2
Major Codes 08–11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3
Major Code 34 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3
Major Code 80 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3
Major Code 81 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-5
Major Code 82 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-6
Major Code 83 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-10
Appendix F. Edit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-1

OS/400 Edit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-1
Examples of Editing Using OS/400 Edit Codes . . . . . . . . . . . . . . . . . F-3
User-Defined Edit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-4
Using User-Defined Edit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . F-5
Example of a User-Defined Edit Code . . . . . . . . . . . . . . . . . . . . . . F-5
Appendix G. System/36-Compatible Display Data Management . . . . . G-1
Contents xix
Clearing Lines on the Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-1
Input Data for Display File Records . . . . . . . . . . . . . . . . . . . . . . . . G-2
Input Data from the Work Station Controller . . . . . . . . . . . . . . . . . . . G-2
Self-Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-2
Return Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-3
Erase Input Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-3
Display Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-3
Positioning the Cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-4
Displaying Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-4
Put Override . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-6
Handling Signed Numeric Data . . . . . . . . . . . . . . . . . . . . . . . . . . . G-7
Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-7
Help Key Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-7
Using Command Keys to Exit Application Help . . . . . . . . . . . . . . . . . G-8
Cancel-Invite Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-8
Retain Command and Function Keys . . . . . . . . . . . . . . . . . . . . . . . G-9
System/36 Functions Not Supported . . . . . . . . . . . . . . . . . . . . . . . . G-10
Restricted DDS Keywords/Functions . . . . . . . . . . . . . . . . . . . . . . . . G-10
Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . H-1
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . X-1
xx Application Display Programming V4R1

Figures
2-1. Sample DDS Source for a Display File . . . . . . . . . . . . . . . . . . 2-7
2-2. Record Formats in the Program and on the Display . . . . . . . . . . 2-8
2-3. DDS for Field-Level Cursor Progression . . . . . . . . . . . . . . . . 2-18
2-4. DDS for Subfile-Level Cursor Progression . . . . . . . . . . . . . . . 2-18
2-5. Sample DDS for Right-to-Left Display Processing . . . . . . . . . . . 2-19
2-6. Sample DDS for Program-to-System Fields . . . . . . . . . . . . . . 2-22
2-7. Sample DDS for Two Display Sizes . . . . . . . . . . . . . . . . . . . 2-25
2-8. Sample DDS for Subfiles for Two Display Sizes . . . . . . . . . . . . 2-25
3-1. Valid Placement of Records on a Screen When the CLRL Keyword Is
Not Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
3-2. Wrong Placement of Records on Screen When CLRL Keyword Not
Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
3-3. Replacing Record Formats . . . . . . . . . . . . . . . . . . . . . . . . . 3-9
3-4. Sample DDS Source Showing Use of the SLNO(*VAR) Keyword . . 3-12
3-5. Sample DDS Source Showing Difference between CLRL and
OVERLAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
3-6. Sample DDS Source Showing Use of the PUTOVR Keyword . . . . 3-19
3-7. Sample DDS Source Showing Efficient Use of PUTOVR Keyword . 3-20
3-8. Sample DDS Source Showing Another Use of PUTOVR Keyword . 3-22
3-9. Sample DDS Source Showing Use of the PUTRETAIN Keyword . . 3-24
3-10. Sample DDS Source Showing Use of the PUTRETAIN Keyword . . 3-25
3-11. Sample DDS Source Showing Use of the DSPMOD Keyword . . . 3-27
3-12. Sample DDS to Show Record Format Problems . . . . . . . . . . . 3-47
4-1. DDS Keyword Processing Order for Subfile Control . . . . . . . . . 4-10
4-2. Vertically Displayed Subfile . . . . . . . . . . . . . . . . . . . . . . . . 4-16
4-3. Horizontally Displayed Subfile . . . . . . . . . . . . . . . . . . . . . . 4-16
4-4. Horizontally and Vertically Displayed Subfiles Displayed at the Same
Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17
4-5. Sample DDS Using DSPMOD with Subfiles . . . . . . . . . . . . . . 4-18
4-6. Sample DDS Using SFLSIZ, SFLPAG, and ROLLUP Keywords . . 4-19
4-7. Sample DDS for a Variable-Length Record . . . . . . . . . . . . . . 4-20
4-8. Sample DDS Using the SFLNXTCHG Keyword . . . . . . . . . . . . 4-22
4-9. Sample DDS for a Message Subfile . . . . . . . . . . . . . . . . . . . 4-23
4-10. Sample DDS Using the DSPATR(PC) Keyword . . . . . . . . . . . . 4-25
4-11. Sample DDS Showing Customer Name Search Subfile . . . . . . . 4-32
5-1. Window Title—Display Example . . . . . . . . . . . . . . . . . . . . . . 5-9
5-2. DDS for a Window Title . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
6-1. Radio Buttons and Check Boxes . . . . . . . . . . . . . . . . . . . . . 6-1
6-2. Example of a Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
6-3. DDS for a Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
6-4. Menu Bar on a Graphical Display Station with Enhanced Interface . 6-10
6-5. Menu Bar on a Nongraphical Display Station with Underline
Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
6-6. Menu Bar on a Nongraphical Display Station without Underline
Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
6-7. Menu Bar on a Display Station without Enhanced Interface . . . . . 6-10
6-8. Selection Fields on a Graphical Display Station with Enhanced
Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11
6-9. Selection Fields on a Nongraphical Display Station . . . . . . . . . . 6-12
6-10. DDS for Single-Choice and Multiple-Choice Selection Fields . . . . 6-13
 Copyright IBM Corp. 1997 xxi

6-11. Example of DDS for Horizontal Selection Field . . . . . . . . . . . . 6-14
6-12. DDS for Suppressing Selection Indicators in a Selection Field . . . 6-17
6-13. Suppressed Selection Indicators in Selection Field . . . . . . . . . . 6-18
6-14. Example of a Pull-Down Menu . . . . . . . . . . . . . . . . . . . . . . 6-18
6-15. DDS for a Pull-Down Menu . . . . . . . . . . . . . . . . . . . . . . . . 6-19
6-16. Pull-Down Menu on a Graphical Display Station with Enhanced
Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19
6-17. Pull-Down Menu on a Nongraphical Display Station with Underline
Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19
6-18. Pull-Down Menu on a Nongraphical Display Station without
Underline Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20
6-19. Pull-Down Menu on a Display without Enhanced Interface . . . . . 6-20
6-20. DDS for Suppressing Selection Indicators in a Pull-Down Menu . . 6-20
6-21. Suppressed Selection Indicators on Graphical Display Station . . . 6-21
6-22. Suppressed Selection Indicators on Nongraphical Display Station . 6-21
6-23. DDS for Accelerator Keys . . . . . . . . . . . . . . . . . . . . . . . . 6-22
6-24. Accelerators in a Pull-Down Menu . . . . . . . . . . . . . . . . . . . . 6-22
6-25. DDS for Menu-Bar Switch Key and Cancel Key . . . . . . . . . . . . 6-23
6-26. Selection Lists on a Graphical Display Station with Enhanced
Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-25
6-27. Selection Lists on a Nongraphical Display Station with Underline
Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-25
6-28. DDS for Selection Lists—Example . . . . . . . . . . . . . . . . . . . 6-26
6-29. DDS for Enabling Selection Indicators in a Selection List . . . . . . 6-29
6-30. Selection Indicators on Graphical Display Station . . . . . . . . . . . 6-29
6-31. Scroll Bar on a Graphical Display Station with Enhanced Interface . 6-30
6-32. Scroll Bar on a Nongraphical Display Station with Underline
Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-31
6-33. DDS for Scroll Bars—Example . . . . . . . . . . . . . . . . . . . . . . 6-33
6-34. Push Buttons on a Graphical Display Station with Enhanced
Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34
6-35. Push Buttons on a Nongraphical Display Station with Underline
Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34
6-36. Push Buttons on a Nongraphical Display Station without Underline
Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34
6-37. Push Buttons on a Display Station without Enhanced Interface . . . 6-34
6-38. DDS for Push Buttons—Example . . . . . . . . . . . . . . . . . . . . 6-35
6-39. Control Values for the CHCCTL Keyword . . . . . . . . . . . . . . . 6-36
6-40. DDS to Control the Availability of Choices . . . . . . . . . . . . . . . 6-37
6-41. Single-Choice Selection Field with an Unavailable Choice . . . . . . 6-37
6-42. Examples of Valid DDS for Mnemonics . . . . . . . . . . . . . . . . . 6-38
6-43. Examples of DDS Not Valid for Mnemonics . . . . . . . . . . . . . . 6-38
6-44. DDS Using CHCAVAIL and CHCSLT for Menu-Bar Choices . . . . 6-40
6-45. DDS Using CHCAVAIL and CHCUNAVAIL for Selection Fields . . . 6-41
6-46. DDS Using CHCAVAIL, CHCUNAVAIL, and CHCSLT for Selection
Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-41
6-47. DDS Using CHCAVAIL, CHCUNAVAIL, and CHCSLT for Single
Choice Selection List Choices . . . . . . . . . . . . . . . . . . . . . . 6-42
6-48. DDS Using CHCAVAIL, CHCUNAVAIL, and CHCSLT for Multiple
Choice Selection List Choices . . . . . . . . . . . . . . . . . . . . . . 6-42
6-49. Continued-Entry Fields in Rectangular Arrangement . . . . . . . . . 6-43
6-50. DDS Using MNUBARDSP on the Application Record . . . . . . . . 6-50
6-51. DDS Using MNUBARDSP on the Menu-Bar Record . . . . . . . . . 6-52
6-52. DDS for Pull-Down Input (PULLINPUT) Parameter . . . . . . . . . . 6-54
xxii Application Display Programming V4R1

6-53. DDS for Return-Field Parameter . . . . . . . . . . . . . . . . . . . . . 6-56
6-54. DDS for Menu-Bar Choice Help . . . . . . . . . . . . . . . . . . . . . 6-57
6-55. DDS for Single-Selection Field Choice Help . . . . . . . . . . . . . . 6-57
6-56. A Help List for a Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . 6-59
6-57. Help for a Named Field . . . . . . . . . . . . . . . . . . . . . . . . . . 6-59
6-58. Help for a Constant Field . . . . . . . . . . . . . . . . . . . . . . . . . 6-59
6-59. Cursor Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-60
6-60. Grid Line Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-80
6-61. DDS for Grid Line Structures—Example . . . . . . . . . . . . . . . . 6-80
6-62. DDS Coding Before Adding HTML Keyword . . . . . . . . . . . . . . 6-85
6-63. DDS Coding After Adding HTML Keyword . . . . . . . . . . . . . . . 6-86
6-64. Graphic Image on an AS/400 5250 Gateway Display . . . . . . . . . 6-86
8-1. Sample DDS Source for ERRSFL Keyword . . . . . . . . . . . . . . . 8-5
8-2. Sample DDS Source for SFLMSGID Keyword . . . . . . . . . . . . . . 8-6
9-1. DDS Source for Sample Menu Called PERSMENU . . . . . . . . . . . 9-8
9-2. DDS Source for Program Menu Example . . . . . . . . . . . . . . . 9-11
16-1. An Example Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-7
16-2. Required UIM Tags for a Menu Panel . . . . . . . . . . . . . . . . . 16-8
16-3. Example List Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-14
16-4. Example of Alternate View of List . . . . . . . . . . . . . . . . . . . 16-14
16-5. Required UIM Tags for a List Panel . . . . . . . . . . . . . . . . . . 16-17
16-6. Example Confirmation List Panel . . . . . . . . . . . . . . . . . . . 16-27
16-7. Example Data Presentation Panel . . . . . . . . . . . . . . . . . . . 16-32
16-8. Example Data Presentation Panel after Scrolling . . . . . . . . . . 16-33
16-9. Required UIM Tags for a Data Presentation Panel . . . . . . . . . 16-35
16-10. Example Panel with a Menu Bar . . . . . . . . . . . . . . . . . . . . 16-50
16-11. Required UIM Tags for a Panel with a Menu Bar . . . . . . . . . . 16-52
17-1. Example of Job Exit Flag . . . . . . . . . . . . . . . . . . . . . . . . 17-25
17-2. Example of Printout . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-35
18-1. Sample H Specification in DDS Source . . . . . . . . . . . . . . . . . 18-4
18-2. Sample DDS Source Showing HLPPNLGRP . . . . . . . . . . . . . 18-8
18-3. Sample DDS Source Showing HLPPNLGRP and Option Indicators 18-9
18-4. Sample DDS Source Showing HLPDOC . . . . . . . . . . . . . . . 18-11
18-5. Sample DDS Source Showing HLPDOC and Option Indicators . . 18-12
18-6. Sample DDS Source Showing HLPRCD . . . . . . . . . . . . . . . 18-13
18-7. Sample DDS Source Showing HLPRCD and Option Indicators . . 18-14
18-8. Sample DDS Source with HLPRCD . . . . . . . . . . . . . . . . . . 18-14
18-9. Sample DDS Source to Show Secondary Help . . . . . . . . . . . 18-18
18-10. Sample DDS Source to Show HLPCMDKEY . . . . . . . . . . . . 18-21
18-11. Sample DDS Source to Show HLPCMDKEY and Response
Indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-22
19-1. InfoSeeker Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-3
19-2. Index Search Display . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-4
21-1. Sample Menu in QUSRTOOL . . . . . . . . . . . . . . . . . . . . . . 21-4
21-2. Sample Entry Display in QUSRTOOL . . . . . . . . . . . . . . . . . . 21-5
21-3. Sample Information Display (Two Pages) in QUSRTOOL . . . . . . 21-6
21-4. Sample List Display in QUSRTOOL . . . . . . . . . . . . . . . . . . . 21-7
21-5. Sample Application Menu . . . . . . . . . . . . . . . . . . . . . . . . . 21-9
21-6. Sample Entry Display . . . . . . . . . . . . . . . . . . . . . . . . . . 21-11
21-7. Sample Information Display (Two Pages) . . . . . . . . . . . . . . 21-18
21-8. Sample List Display . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-21
21-9. Layout of Display with Location Information . . . . . . . . . . . . . 21-25
21-10. Example of Processing Priority with List Display . . . . . . . . . . 21-28
21-11. Create User Profile Entry Display . . . . . . . . . . . . . . . . . . . 21-35
Figures xxiii
21-12. Create Command Display with Additional Parameters Selected . . 21-36
21-13. Second Display of Additional Parameters . . . . . . . . . . . . . . 21-36
21-14. Work with Members Using PDM Entry Display . . . . . . . . . . . 21-37
21-15. Help Areas for Entry Displays . . . . . . . . . . . . . . . . . . . . . 21-46
21-16. Help Areas for Information Displays . . . . . . . . . . . . . . . . . . 21-47
21-17. Help Areas for List Displays . . . . . . . . . . . . . . . . . . . . . . 21-48
21-18. Example of an Application Menu . . . . . . . . . . . . . . . . . . . 21-52
21-19. Entry Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-54
21-20. Example of an Information Display . . . . . . . . . . . . . . . . . . 21-55
21-21. Example of a List Display . . . . . . . . . . . . . . . . . . . . . . . . 21-56
A-1. Highlighting Classes Allowed in TEXT Area . . . . . . . . . . . . . A-156
D-1. IBM Host-System Code Scheme . . . . . . . . . . . . . . . . . . . . D-2
G-1. Circumventing the Save Command . . . . . . . . . . . . . . . . . . . G-9
xxiv Application Display Programming V4R1

Tables
1-1. Names Used in Steps for Creating Sample Displays . . . . . . . . . . 1-1
1-2. More Ways to Create Application Displays . . . . . . . . . . . . . . . . 1-6
1-3. More Ways to Create Online Help Information . . . . . . . . . . . . . . 1-6
2-1. Column positions for sample DDS . . . . . . . . . . . . . . . . . . . . . 2-8
2-2. DDS for Emphasizing Fields . . . . . . . . . . . . . . . . . . . . . . . 2-21
2-3. PRINT Keyword Results Using Print Key . . . . . . . . . . . . . . . . 2-26
3-1. Display Stations Implicitly Acquired When Display Files Are Opened 3-2
3-2. Information Available from the Get-Attributes Operation . . . . . . . . 3-4
3-3. Results of SLNO(*VAR) Values . . . . . . . . . . . . . . . . . . . . . 3-11
3-4. Results from CLRL Example . . . . . . . . . . . . . . . . . . . . . . . 3-16
3-5. Keywords Ignored If Display Modes Are Changed . . . . . . . . . . 3-28
3-6. Display File Operations Supported by the Operating System and the
Equivalent High-Level Language Commands . . . . . . . . . . . . . 3-49
4-1. Optional Functions for Subfiles . . . . . . . . . . . . . . . . . . . . . . . 4-4
4-2. Subfile Operations Supported by the System and Equivalent HLL
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15
6-1. Functions Supported by Hardware Configurations A, B, and C . . . . 6-2
6-2. Functions Supported by Hardware Configurations D, E, and F . . . . 6-3
6-3. How a Scroll Bar is Sized . . . . . . . . . . . . . . . . . . . . . . . . . 6-32
6-4. Scroll Bar Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-33
6-5. Keywords Used to Define Colors and Display Attributes . . . . . . . 6-39
6-6. Values Returned in MNUCHOICE and PULLINPUT . . . . . . . . . 6-55
6-7. Actions Performed at Different Cursor Locations . . . . . . . . . . . 6-61
7-1. File Redirections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7
7-2. File Redirection Combinations . . . . . . . . . . . . . . . . . . . . . . . 7-7
8-1. System Message Number Ranges . . . . . . . . . . . . . . . . . . . 8-10
8-2. Major Return Code Definitions . . . . . . . . . . . . . . . . . . . . . . 8-11
9-1. Restrictions for Display File Menus . . . . . . . . . . . . . . . . . . . . 9-4
9-2. Suggestions for Display File Menus . . . . . . . . . . . . . . . . . . . . 9-5
12-1. Display File and ICF File Entry Field Attributes . . . . . . . . . . . . 12-1
13-1. CHRID Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5
17-1. Initial Values of Dialog Variable . . . . . . . . . . . . . . . . . . . . . 17-2
17-2. UIM CCSID/CHRID Conversions for Display . . . . . . . . . . . . . . 17-5
17-3. UIM CCSID/CHRID Conversions for Print . . . . . . . . . . . . . . . 17-7
17-4. Cursor-Sensitive Function Keys Assigned to Dialog Commands . 17-29
18-1. Different Ways to Define Online Help Information . . . . . . . . . . . 18-2
18-2. Characteristics of Different Methods of Online Help Information . . 18-2
18-3. Help for Sample Display . . . . . . . . . . . . . . . . . . . . . . . . . 18-5
18-4. Other DDS Keywords for UIM Help . . . . . . . . . . . . . . . . . . . 18-6
18-5. Help for Sample Display Using Panel Groups . . . . . . . . . . . . . 18-7
18-6. Help for Sample Display Using HLPDOC . . . . . . . . . . . . . . . 18-10
18-7. Help for Sample Display Using HLPRCD . . . . . . . . . . . . . . . 18-13
21-1. Source Members for Displays Example in QUSRTOOL (Install,
Create, and Delete) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-2
21-2. Source Members for Displays Example in QUSRTOOL (Sample
Displays, Command, and Online Help Information) . . . . . . . . . . 21-3
21-3. Objects Created When Creating Example Objects . . . . . . . . . . 21-4
21-4. Required Functions and Attributes of All AS/400-Style Displays . . 21-8
21-5. Optional Functions and Attributes of All AS/400-Style Displays . . . 21-8
21-6. Function Key Assignments . . . . . . . . . . . . . . . . . . . . . . . 21-38
 Copyright IBM Corp. 1997 xxv

21-7. Type of Help for Each Help Area–Menu Display . . . . . . . . . . 21-45
21-8. DDS Considerations–Help on Menu Displays . . . . . . . . . . . . 21-45
21-9. Type of Help for Each Help Area–Entry Display . . . . . . . . . . . 21-46
21-10. DDS Considerations–Help on Entry Displays . . . . . . . . . . . . 21-46
21-11. Type of Help for Each Help Area–Information Display . . . . . . . 21-47
21-12. DDS Considerations–Help on Information Displays . . . . . . . . . 21-47
21-13. Type of Help for Each Help Area–List Display . . . . . . . . . . . . 21-48
21-14. DDS Considerations–Help on List Displays . . . . . . . . . . . . . 21-49
21-15. CUA Entry Dialog Actions . . . . . . . . . . . . . . . . . . . . . . . 21-51
A-1. Tag Attributes That Can Be Continued . . . . . . . . . . . . . . . . . A-1
A-2. Restrictions Associated With Mixed Panels . . . . . . . . . . . . . . A-2
A-3. Tags Allowed Between the CLASS and ECLASS Tag . . . . . . . . A-14
A-4. Attribute Summary for Each BASETYPE . . . . . . . . . . . . . . . . A-18
A-5. Tags Allowed Between the DATA and EDATA Tags . . . . . . . . . A-32
A-6. Tag Allowed Between the DATASLT and EDATASLT Tags . . . . . A-51
A-7. Tags Allowed Between the DL and EDL Tags . . . . . . . . . . . . . A-57
A-8. Tag Allowed Between the KEYL and EKEYL Tags . . . . . . . . . . A-76
A-9. Tags Allowed Between the LIST and ELIST Tags . . . . . . . . . . A-83
A-10. NOCMD and NOEXT Attribute Interaction . . . . . . . . . . . . . . . A-93
A-11. Emphasis Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-101
A-12. Layout Values for Width=80 . . . . . . . . . . . . . . . . . . . . . . A-106
A-13. Layout Values for WIDTH=132 . . . . . . . . . . . . . . . . . . . . . A-106
A-14. Layout Values for WIDTH=132 . . . . . . . . . . . . . . . . . . . . . A-106
A-15. Tag Allowed Between the MBAR and EMBAR Tags . . . . . . . . A-108
A-16. Tags Allowed Between the MBARC and EMBARC Tags . . . . . . A-110
A-17. Tags Allowed Between the MENU and EMENU Tags . . . . . . . A-111
A-18. Tag Allowed Between the MENUGRP and EMENUGRP Tags . . A-114
A-19. Tags Allowed Between the NOTE and ENOTE Tags . . . . . . . . A-117
A-20. Tags Allowed Between the OL and EOL Tags . . . . . . . . . . . . A-118
A-21. Tags Allowed Between the PANEL and EPANEL Tag . . . . . . . A-122
A-22. Layout of UIM finger print . . . . . . . . . . . . . . . . . . . . . . . . A-124
A-23. Tags Allowed Between the PARML and EPARML Tags . . . . . . A-129
A-24. Tags Allowed Between the PDFLD and EPDFLD Tags . . . . . . A-133
A-25. Valid Action Text for ACTION Values . . . . . . . . . . . . . . . . . A-134
A-26. Tags Allowed Between the PNLGRP and EPNLGRP Tags . . . . A-139
A-27. Tags Allowed Between the PRTHEAD and EPRTHEAD Tags . . A-142
A-28. First Line of Heading with Print Width 132 . . . . . . . . . . . . . . A-144
A-29. First Line of Heading with Print Width 80 . . . . . . . . . . . . . . . A-144
A-30. Second Line of Heading with Print Width 132 . . . . . . . . . . . . A-144
A-31. Second Line of Heading with Print Width 80 . . . . . . . . . . . . . A-145
A-32. Tags Allowed Between the PRTPNL and EPRTPNL Tags . . . . . A-146
A-33. Tags Allowed Between the SL and ESL Tags . . . . . . . . . . . . A-152
A-34. Tag Allowed Between the TL and ETL Tags . . . . . . . . . . . . . A-159
A-35. Tag Allowed Between the TT and ETT Tags . . . . . . . . . . . . . A-162
A-36. Tags Allowed Between the UL and EUL Tags . . . . . . . . . . . . A-164
A-37. Attributes of UIM-Defined Variables (Z-Variables) . . . . . . . . . . A-168
B-1. Summary of the Valid Uses of Dialog Commands . . . . . . . . . . B-2
B-2. Summary of the Effects of Dialog Commands . . . . . . . . . . . . . B-3
C-1. Open Feedback Area . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1
C-2. Device Definition List . . . . . . . . . . . . . . . . . . . . . . . . . . . C-4
C-3. Common I/O Feedback Area . . . . . . . . . . . . . . . . . . . . . . . C-6
C-4. I/O Feedback Area for Display Files . . . . . . . . . . . . . . . . . . . C-9
C-5. Get Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-12
D-1. IBM Japanese Character Set . . . . . . . . . . . . . . . . . . . . . . . D-2
xxvi Application Display Programming V4R1

D-2. IBM Korean Character Set . . . . . . . . . . . . . . . . . . . . . . . . D-2
D-3. IBM Simplified Chinese Character Set . . . . . . . . . . . . . . . . . D-2
D-4. IBM Traditional Chinese Character Set . . . . . . . . . . . . . . . . . D-3
F-1. Summary Chart for OS/400 Edit Codes . . . . . . . . . . . . . . . . . . F-1
F-2. Valid Edit Codes, Source Data, and Edited Output . . . . . . . . . . . F-3
F-3. IBM-Supplied Edit Descriptions . . . . . . . . . . . . . . . . . . . . . . F-4
G-1. Message Files for MSGID . . . . . . . . . . . . . . . . . . . . . . . . G-5
G-2. Message Files for MSGID . . . . . . . . . . . . . . . . . . . . . . . . G-5
Tables xxvii
xxviii Application Display Programming V4R1
Notices
References in this publication to IBM products, programs, or services do not imply that IBM intends to
make these available in all countries in which IBM operates. 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.
Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent
product, program, or service may be used instead of the IBM product, program, or service. The evaluation
and verification of operation in conjunction with other products, except those expressly designated by IBM,
are the responsibility of the user.
IBM may have patents or pending patent applications covering subject matter in this document. The fur-
nishing 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, 500 Columbus Avenue, Thornwood, NY
10594, U.S.A.
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 software interop-
erability coordinator. Such information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.
Address your questions to:
IBM Corporation
Software Interoperability Coordinator
3605 Highway 52 N
Rochester, MN 55901-7829 USA
This publication could contain technical inaccuracies or typographical errors.
This publication may refer to products that are announced but not currently available in your country. This
publication may also refer to products that have not been announced in your country. IBM makes no
commitment to make available any unannounced products referred to herein. The final decision to
announce any product is based on IBM's business and technical judgment.
This publication contains examples of data and reports used in daily business operations. To illustrate
them as completely as possible, the examples include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to the names and addresses used by an
actual business enterprise is entirely coincidental.
This publication contains small programs that are furnished by IBM as simple examples to provide an
illustration. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot
guarantee or imply reliability, serviceability, or function of these programs. All programs contained herein
are provided to you "AS IS". THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE EXPRESSLY DISCLAIMED.
 Copyright IBM Corp. 1997 xxix

Programming Interface Information
This publication is intended to help the application programmer create and maintain displays for an appli-
cation. This publication documents Product-Sensitive Programming Interface and Associated Guidance
Information provided by the OS/400 licensed program.
Product-Sensitive programming interfaces allow the customer installation to perform tasks such as diag-
nosing, modifying, monitoring, repairing, tailoring, or tuning of this IBM software product. Use of such inter-
faces creates dependencies on the detailed design or implementation of the IBM software product.
Product-Sensitive programming interfaces should be used only for these specialized purposes. Because
of their dependencies on detailed design and implementation, it is to be expected that programs written to
such interfaces may need to be changed in order to run with new product releases or versions, or as a
result of service.
Trademarks
The following terms are trademarks of the IBM Corporation in the United States or other countries or both:
AFP Operating System/400

AIX OS/2
Application System/Entry OS/400
APPN PS/1
AS/400 PS/2
Common User Access RPG
CUA SAA
IBM System/36
Information Assistant System/38
InfoWindow System/370
Integrated Language Environment Systems Application Architecture
OfficeVision 400
Microsoft, Windows, and the Windows 95 logo are trademarks or registered trademarks of Microsoft Cor-
poration.
PC Direct is a trademark of Ziff Communications Company and is used by IBM Corporation under license.
UNIX is a registered trademark in the United States and other countries licensed exclusively through
X/Open Company Limited.
C-bus is a trademark of Corollary, Inc.
Java and HotJava are trademarks of Sun Microsystems, Inc.
Other company, product, and service names, which may be denoted by a double asterisk (**), may be
trademarks or service marks of others.
xxx Application Display Programming V4R1

About Application Display Programming (SC41-5715)
This book contains information on:
Using DDS to create and maintain displays for an application
Creating and working with display files on the system
Creating online help information
Using UIM to define panels and dialogs for an application
Use this book to program for application and help displays.
This book does not describe all the DDS keywords or the configuration of display
stations. You may need to refer to other IBM books for more specific information
about a particular topic.
For a list of related publications, see the “Bibliography.”
Who Should Use This Book

This book should be used by application programmers who create or work with
application and help displays. You should also have knowledge of the source entry
utility (SEU) and data description specifications (DDS).
This book assumes that a device description already exists to describe your display
station to the system.
Prerequisite and Related Information

For information about other AS/400 publications (except Advanced 36), see either
of the following:
The Publications Reference book, SC41-5003, in the AS/400 Softcopy Library.
The AS/400 Information Directory, a unique, multimedia interface to a
searchable database that contains descriptions of titles available from IBM or
from selected other publishers. The AS/400 Information Directory is shipped
with the OS/400 operating system at no charge.
Information Available on the World Wide Web

More AS/400 information is available on the World Wide Web. You can access this
information from the AS/400 home page, which is at the following uniform resource
locator (URL) address:
http://www.as4ðð.ibm.com
Select the Information Desk, and you will be able to access a variety of AS/400
information topics from that page.
 Copyright IBM Corp. 1997 xxxi

xxxii Application Display Programming V4R1
Summary of Changes to Application Display Programming
HTML Keyword
You can use HTML tags to update applications for use on the Internet through the
World Wide Web. For more information, see“DDS Keywords” on page 6-5 and
“Inserting HTML Tags” on page 6-82.
Changes or additions to the text are indicated by a vertical line (|) to the left of the
change or addition.
The following programming languages are no longer offered as licensed programs

in V3R7:
AS/400 BASIC, FORTRAN/400, AS/400 PL/I, AS/400 Pascal, and RM/COBOL-85

for the AS/400
Therefore, references to these products have been removed or adjusted in this

edition.
 Copyright IBM Corp. 1997 xxxiii

xxxiv Application Display Programming V4R1
Part 1. Building a Sample Display with Online Help
Information
Chapter 1. Building a Sample Display with Online Help Information . . . 1-1
 Copyright IBM Corp. 1997

Application Display Programming V4R1
Chapter 1. Building a Sample Display with Online Help
Information
This chapter outlines the steps you need to do to create a sample display with
online help information on the AS/400. If you are not sure how to do one or more
of the steps, see the additional information referred to in each step.
The Application Display: The sample display is created using a display file (also
known as a display device file). A display file is an object, or named storage
space, created by the user that contains the file description. The file description
identifies the display station used and, optionally, the record formats used by the
display station. Record formats describe the characteristics and arrangement of
the fields on a display. Record formats are defined using data description spec-
ifications (DDS), which describe data attributes outside the application program
that processes the data.
The Online Help Information: The online help information for the sample display
is defined using help panel groups. A panel group is an object, or named storage
space, that contains text to be used as online help information by the user interface
manager. The user interface manager (UIM) is a function of the operating system
that provides online help information for displays, including help for part or all of a
display, help for commands, the InfoSeeker function, the index search function
(selectable help topics), and hypertext (the capability to link different units of online
help information).
The following table lists the sample names used in the steps:
Table 1-1. Names Used in Steps for Creating Sample Displays

Name What It Is
SRCSAM Sample source file
ADMSAM Sample source member for application display
DSPSAM Sample display file
HDMSAM Sample source member for help display
PNLSAM Sample panel group
LIBSAM Sample library that contains source file SRCSAM, display file
DSPSAM, and panel group PNLSAM
The steps show only one way to create a sample display with online help informa-
tion. Other methods are discussed at the end of this chapter.
1. Create the source file SRCSAM using the Create Source Physical File
(CRTSRCPF) command; create the library LIBSAM using the Create Library
(CRTLIB) command.
2. Enter the Start Programming Development Manager (STRPDM) command to
begin using the programming development manager (PDM). When the display
appears, select option 3 (Work with members).
 Copyright IBM Corp. 1997 1-1

à AS/4ðð Programming Development Manager (PDM)
ð
Select one of the following:
1. Work with libraries
2. Work with objects
3. Work with members
9. Work with user-defined options
Selection or command
===> 3
F3=Exit F4=Prompt F9=Retrieve F1ð=Command entry

F12=Cancel F18=Change defaults
(C) COPYRIGHT IBM CORP. 1981, 1993.
á ñ
Additional Information
The programming development manager (PDM) is the part of the
AS/400* Application Development Tools licensed program that allows users
to perform several operations (such as copy, delete, and rename) from lists
of libraries, objects, and members.
Since the display file (which will be created in step 9) does not actually
contain any data, the DDS source for a display file is entered in a source
file. A source file is an object that is made up of one or more source
members, which are the different sets of data that make up your DDS
source.
More information about the programming development manager is available
in the ADTS/400: Programming Development Manager book.
3. When the Specify Members to Work With display appears, complete the file
and library information and press the Enter key.
à Specify Members to Work With

ð
Type choices, press Enter.
File . . . . . . . . . . SRCSAM Name
Library . . . . . . . . LIBSAM \LIBL, \CURLIB, name
Member:
Name . . . . . . . . . \ALL \ALL, name, \generic\
Type . . . . . . . . . \ALL \ALL, \BLANK, type, \generic\
F3=Exit F5=Refresh F12=Cancel
á ñ
1-2 Application Display Programming V4R1

4. The Work with Members Using PDM display appears.
à Work with Members Using PDM

ð
File . . . . . . SRCSAM
Library . . . . LIBSAM Position to . . . . .
Type options, press Enter.

2=Edit 3=Copy 4=Delete 5=Display 6=Print
7=Rename 8=Display description 9=Save 13=Change text
Opt Member Type Text
(No members match the subsetting criteria)
Parameters or command
===>
F3=Exit F4=Prompt F5=Refresh F6=Create
F9=Retrieve F1ð=Command entry F23=More options F24=More keys
á ñ
Press F6 on this display to create a new member.
5. The Start Source Entry Utility display appears. Complete the information on
this display and press the Enter key.
à Start Source Entry Utility (STRSEU)

ð
Source file . . . . . . . . . . > SRCSAM Name, \PRV

Library . . . . . . . . . . . > LIBSAM Name, \LIBL, \CURLIB, \PRV
Source member . . . . . . . . . ADMSAM Name, \PRV, \SELECT
Source type . . . . . . . . . . DSPF Name, \SAME, BAS, BASP, C...
Text 'description' . . . . . . . DDS for sample display
Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
á ñ
The source entry utility (SEU) is a function of the Application Development
ToolSet licensed program that is used to create and change source
members. More information about the source entry utility is available in the
ADTS/400: Source Entry Utility book.
6. Because you are creating a new member, the SEU Edit display appears with a
screen of blank lines. The text on the last line of the display, Member
Chapter 1. Building a Sample Display with Online Help Information 1-3

ADMSAM added to file SRCSAM indicates that SEU added the new member to
the file you specified.
à Columns . . . .: 1 71 Edit LIBSAM/SRCSAM

ð
SEU==> ADMSAM
FMT DP .....AANð1Nð2Nð3T.Name++++++RLen++TDpBLinPosFunctions++++++++++++++++++
\\\\\\\\\\\\\\\ Beginning of data \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
'''''''
'''''''
'''''''
'''''''
'''''''
'''''''
'''''''
'''''''
'''''''
'''''''
'''''''
'''''''
'''''''
'''''''
\\\\\\\\\\\\\\\\\\ End of data \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F3=Exit F4=Prompt F5=Refresh

F1ð=Top F11=Bottom F24=More keys
Member ADMSAM added to file LIBSAM/SRCSAM.
+
á ñ
7. On the SEU edit display, enter the DDS source statements for the new
member. Since the instructions in this chapter allow you to provide online help
information for the sample display, make sure your DDS source includes the
necessary DDS keywords to enable and access help.
SEU has many functions available to help you enter your DDS. More infor-
mation about the functions of SEU is available in the the ADTS/400: Source
Entry Utility book.
For information about describing your display using DDS, see “Defining
Display Fields and Functions in a Record Format” on page 2-7 in this
guide. For more information about the DDS keywords needed for online
help information, see Chapter 18, “Making Online Help Information Acces-
sible for Your Display File.”
8. When you are finished entering your DDS source, press F3 and complete the
information on the Exit display. Press the Enter key.
9. To create the new display file, enter the Create Display File (CRTDSPF)
command on any command line. Make sure you specify the source file and
member that contains your DDS source:
CRTDSPF FILE(LIBSAM/DSPSAM) SRCFILE(LIBSAM/SRCSAM) SRCMBR(ADMSAM)
Press the Enter key.
For more information about creating display files, see “Creating a Display
File and Description” on page 2-4.
10. To add online help information to the sample display, create a second source
file member for the UIM source. You are not required to create the second
source member in the same source file that you created your DDS source in;

however, do not use the same source member for both the DDS and UIM
source.
To create the second source file member, repeat steps 2 through 4. When the
Start Source Entry Utility display appears again, continue with step 11.
11. Complete the information on the Start Source Entry Utility display by specifying
the following:
For this prompt... Enter this...
Source member HDMSAM
Source type PNLGRP
Text description UIM help for sample display
12. On the SEU edit display, enter the UIM source statements for the new member.
For information about defining your online help information using UIM, see
“Defining Online Help Information in a Panel Group” on page 20-1.
13. When you are finished entering your UIM source, press F3 and complete the
information on the Exit display. Press the Enter key.
14. Enter the Create Panel Group (CRTPNLGRP) command on any command line:
CRTPNLGRP PNLGRP(LIBSAM/PNLSAM) SRCFILE(LIBSAM/SRCSAM) SRCMBR(HDMSAM)
Press the Enter key.
For more information about panel groups, see “Creating and Deleting Panel
Groups” on page 20-15.
Although one library was used in the previous steps, you are not required to create
the different objects for your displays in the same library.
Other ways of creating your own application displays on the AS/400 system follow:
Chapter 1. Building a Sample Display with Online Help Information 1-5

Table 1-2. More Ways to Create Application Displays
Method Description Where to Find More
Information
Screen design aid A function of the Application Development ToolSet licensed ADTS/400: Screen
(SDA) program that helps you design, create, and maintain displays Design Aid book.
and menus. SDA allows you to design your displays as you
want them to look and then the system creates the DDS
source and a display file for you.
QUSRTOOL A library, which is optionally installable on your system, that “Using the Displays
provides you access to examples of various tools and pro- Example in the
gramming techniques that may help you with application QUSRTOOL Library” on
development and management of your system. The display page 21-1
example in QUSRTOOL provides four sample displays with
online help information. You can copy the source for these
displays into a library of your choosing and then tailor them
for your own use.
UIM panel groups A part of the system that allows you to define panels and Chapter 16, “Introduction
dialogs for your application. The UIM controls the panel's to the User Interface
appearance and assures consistency with panels developed Manager” on page 16-1
by IBM *.
Other ways of creating online help information for your displays follow:
Table 1-3. More Ways to Create Online Help Information

Method Description Where to Find More Information
Help documents Objects for online help information that are “Defining Online Information in a Document”
created using AS/400 OfficeVision, which on page 20-18 and “Specifying Documents
is the IBM licensed program that provides in Your Display File” on page 18-9
many office functions, such as word pro-
cessing. This can be accessed from
display files and not the UIM application
panels.
Help records DDS keywords that allow you to create “Defining Online Help Information in a DDS
your online help information in the same or Record” on page 20-19 and “Specifying
a different member as the DDS source for Records in Your Display File” on page 18-12
your application display. This can be
accessed from display files and not the
UIM application panels.
To compare and contrast the different ways to create online help information, see
“Choosing between Panel Groups, Documents, and Records for Help” on
page 18-2.

Part 2. Programming Application Displays Using Display
Files
Chapter 2. Defining Your Display in a Display File . . . . . . . . . . . . . . 2-1
Establishing a Display File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Determining File Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Field-Level Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Record-Level Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
File-Level Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Deciding Whether to Describe Data Inside or Outside Your Program . . . . 2-3
Externally Described Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Program-Described Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Creating a Display File and Description . . . . . . . . . . . . . . . . . . . . . 2-4
Changing the File Description . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Detecting File Description Changes . . . . . . . . . . . . . . . . . . . . . . . . 2-6
Defining Display Fields and Functions in a Record Format . . . . . . . . . . . . 2-7
Understanding the Field Attribute Characters . . . . . . . . . . . . . . . . . . 2-8
Understanding How Record Format Fields Can Be Used . . . . . . . . . . . 2-9
Defining Command Attention (CAnn) and Command Function (CFnn) Keys 2-12
Specifying Alternative Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13
Passing Information via Indicators . . . . . . . . . . . . . . . . . . . . . . . 2-14
Removing Option and Response Indicators from the Record Area . . . 2-15
Enabling Different Response Indicators Simultaneously . . . . . . . . . 2-15
Setting an Indicator Off . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15
Inserting Constant Field Text from a Message Description . . . . . . . . . 2-16
Allowing for Right-to-Left Cursor Movement . . . . . . . . . . . . . . . . . . 2-16
Defining Cursor Movement to Input-Capable Positions Only . . . . . . . . 2-16
Defining Cursor Progression for Entry Fields . . . . . . . . . . . . . . . . . 2-17
Defining Attributes for Entry Fields . . . . . . . . . . . . . . . . . . . . . . . 2-18
Protecting Entry Fields Using Edit Masks . . . . . . . . . . . . . . . . . . . 2-19
Specifying Right-to-Left Display Processing . . . . . . . . . . . . . . . . . . 2-19
Specifying Word Wrap for Fields . . . . . . . . . . . . . . . . . . . . . . . . 2-20
Specifying Word Wrap for Fields—Tips . . . . . . . . . . . . . . . . . . . 2-21
Emphasizing Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21
Adding Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22
Editing Output Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23
Defining Your Own Edit Codes . . . . . . . . . . . . . . . . . . . . . . . . . 2-23
Specifying Valid Screen Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . 2-24
Enabling Your Display to Be Printed . . . . . . . . . . . . . . . . . . . . . . 2-25
Defining Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27
Using Program-Described Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27
Defining Input-Only Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28
Defining Output-Only Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28
Defining Input and Output Files . . . . . . . . . . . . . . . . . . . . . . . . . 2-28
Chapter 3. Working with Display Files in an Application . . . . . . . . . . 3-1

Understanding How the System Allocates Resources . . . . . . . . . . . . . . . 3-1
Opening Display Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Acquiring a Display Station for I/O Operations . . . . . . . . . . . . . . . . . . . 3-2
Obtaining Information about Display Files and Display Stations . . . . . . . . . 3-3
Obtaining Information about Open and I/O Operations . . . . . . . . . . . . . 3-3

Obtaining Attribute Information about Display Stations . . . . . . . . . . . . . 3-4
Sending and Receiving Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Determining Which Record Formats Are Active on a Display . . . . . . . . . 3-5
Writing Output to the Display . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Placing Records on the Display . . . . . . . . . . . . . . . . . . . . . . . . 3-5
Understanding Which Records Do Not Occupy Space on the Display . . 3-8
Changing Record Formats on a Display . . . . . . . . . . . . . . . . . . . 3-8
Deciding the Order of Record Formats Written to the Display . . . . . . . 3-9
Overlaying and Erasing Record Formats on a Display . . . . . . . . . . 3-10
Starting Your Record Format on a Specific Line . . . . . . . . . . . . . . 3-11
Clearing a Specified Number of Lines . . . . . . . . . . . . . . . . . . . . 3-13
Rolling Data between Two Lines on a Display . . . . . . . . . . . . . . . 3-16
Overriding the Attributes or the Content of a Field . . . . . . . . . . . . 3-18
Erasing All Unprotected Input and Output/Input Fields on the Display . 3-23
Resetting Modified Data Tags Associated with Records on the Display 3-23
Keeping a Record or Field on a Display . . . . . . . . . . . . . . . . . . 3-23
Deferring the Write Operation Until a Read Request is Made . . . . . . 3-26
Specifying Default Values for Fields . . . . . . . . . . . . . . . . . . . . . 3-26
Indicating Which Mode to Display Records . . . . . . . . . . . . . . . . . 3-27
Positioning the Cursor after an Output Operation . . . . . . . . . . . . . 3-28
Returning the Cursor Position to an Application . . . . . . . . . . . . . . 3-29
Returning the Cursor Position Within a Subfile to an Application . . . . 3-29
Returning the Mode of a Subfile to an Application . . . . . . . . . . . . . 3-29
Initializing Output/Input Fields . . . . . . . . . . . . . . . . . . . . . . . . 3-29
Inviting Input to the Display . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30
Reading Invited Input from the Display . . . . . . . . . . . . . . . . . . . . . 3-31
Understanding the Read-From-Invited-Devices . . . . . . . . . . . . . . 3-32
Reading Input from the Display . . . . . . . . . . . . . . . . . . . . . . . . . 3-33
Unlocking the Keyboard while the Program Is Processing Data . . . . . 3-35
Keeping Input Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-36
Setting an Indicator When Data Is Changed . . . . . . . . . . . . . . . . 3-36
Initializing Records and Unlocking the Keyboard–Diagram . . . . . . . . 3-36
Specifying Validity-Checking Functions . . . . . . . . . . . . . . . . . . . 3-37
Understanding the Limitations on the Number of Input-Capable Fields . 3-39
Handling Negative Numeric Input Data . . . . . . . . . . . . . . . . . . . 3-40
Understanding How the System Reads Input from the Display . . . . . 3-40
Writing Output and Reading Input at the Same Time . . . . . . . . . . . . 3-40
Canceling Input That Was Not Waited For . . . . . . . . . . . . . . . . . . . 3-41
Locking the Keyboard and Positioning the Cursor During I/O Operations . 3-41
Saving Previously Displayed Information . . . . . . . . . . . . . . . . . . . . 3-43
Understanding the Effects of I/O Operations on Command Keys . . . . . . 3-45
Avoiding Record Format Problems on the 5250 Display Station . . . . . . 3-45
Releasing an Acquired Display Station from I/O Operations . . . . . . . . . . 3-49
Closing Display Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-49
Mapping Display Operations to High-Level Language Operations . . . . . . . 3-49
Sharing Display Files in the Same Job . . . . . . . . . . . . . . . . . . . . . . 3-50
Understanding the Open Operation for Files Shared in a Job . . . . . . . . 3-51
Understanding the Input/Output Operation for Files Shared in a Job . . . 3-51
Understanding the Close Operation for Files Shared in a Job . . . . . . . 3-52
Chapter 4. Displaying Groups of Records Using Subfiles . . . . . . . . . . 4-1

Recognizing Subfile Uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Describing Subfiles in Your DDS Source . . . . . . . . . . . . . . . . . . . . . . 4-3
Using a Subfile in a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10

Requesting I/O Operations for a Subfile . . . . . . . . . . . . . . . . . . . . . . 4-12
Requesting I/O Operations for a Subfile Record Format . . . . . . . . . . . 4-12
Adding a Record at a Specified Location in a Subfile . . . . . . . . . . . 4-12
Updating an Active Record in the Subfile . . . . . . . . . . . . . . . . . . 4-13
Reading an Active Record at a Specified Location in the Subfile . . . . 4-13
Reading the Next Changed Record in a Subfile . . . . . . . . . . . . . . 4-14
Requesting I/O Operations for a Subfile Control Record Format . . . . . . 4-15
Displaying Subfile Records . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15
Placing Subfile Records on the Display for Processing . . . . . . . . . . 4-15
Displaying and Processing Subfile Records at the Same Time . . . . . 4-15
Recognizing Subfile I/O Requests in High-Level Languages . . . . . . . . 4-15
Controlling the Appearance of Subfiles . . . . . . . . . . . . . . . . . . . . . . 4-16
Displaying Horizontal Subfiles with Display Modes . . . . . . . . . . . . . . . 4-17
Specifying Subfile Size Equal to Page Size . . . . . . . . . . . . . . . . . . . . 4-19
Specifying Subfile Size Not Equal to Page Size . . . . . . . . . . . . . . . . . 4-21
Checking Validity on Subfile Data . . . . . . . . . . . . . . . . . . . . . . . . . 4-22
Displaying Error Messages from Subfiles . . . . . . . . . . . . . . . . . . . . . 4-23
Positioning the Cursor on the Displayed Subfile . . . . . . . . . . . . . . . . . 4-24
Positioning the Cursor Initially . . . . . . . . . . . . . . . . . . . . . . . . . . 4-24
Positioning the Cursor When a Roll Key Is Used . . . . . . . . . . . . . . . 4-24
Positioning the Cursor When a Fold or Truncate Key Is Used . . . . . . . 4-27
Displayed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-27
Understanding Subfile DDS and Program Logic–Example . . . . . . . . . . . 4-31
Chapter 5. Defining Windows with Display Files . . . . . . . . . . . . . . . 5-1

Window Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
DDS Window Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Window Representation and Hardware Configuration . . . . . . . . . . . . . . . 5-3
Creating Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Window Definition Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Window Reference Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Window Size and Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Cursor Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Subfiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
DDS Help Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Defining Window Borders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Border Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Multiple Border Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
UIM Help Window Borders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
Defining a Window Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-9
DDS for a Window Title—Example . . . . . . . . . . . . . . . . . . . . . 5-10
Reading Data from Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
Changing Window Borders and Contents . . . . . . . . . . . . . . . . . . . . . 5-10
Moving and Duplicating Windows . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
Making Two Windows Seem Active at Once . . . . . . . . . . . . . . . . . . . 5-11
Making One Window in a Series Stand Out . . . . . . . . . . . . . . . . . . . 5-12
Removing Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
Removing All Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13
Removing More Recent Windows . . . . . . . . . . . . . . . . . . . . . . . . 5-13
Improving Application Performance . . . . . . . . . . . . . . . . . . . . . . . . 5-13
System Save and Restore Operations . . . . . . . . . . . . . . . . . . . . . 5-13
Response Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13

Bypassing System Save and Restore Operations . . . . . . . . . . . . . . 5-14
USRRSTDSP Keyword Processing and Interactions . . . . . . . . . . . 5-15
Using Basic Window Functions . . . . . . . . . . . . . . . . . . . . . . . . . 5-16
DDS Full-Screen Display and Window Definitions . . . . . . . . . . . . . 5-16
RPG Display Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-17
Step 1: Display Initial Display . . . . . . . . . . . . . . . . . . . . . . . . 5-18
Step 2: Display Window 1 . . . . . . . . . . . . . . . . . . . . . . . . . . 5-18
Step 3: Display Window 2 . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19
Step 4: Restore Window 1 . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19
Defining Windows in a Separate Display File . . . . . . . . . . . . . . . . . 5-20
DDS Full-Screen Display and Window Definitions . . . . . . . . . . . . . 5-21
RPG Program Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21
RPG Program Source for WINPGM . . . . . . . . . . . . . . . . . . . . . . 5-22
Step 2: Display a Window . . . . . . . . . . . . . . . . . . . . . . . . . . 5-22
Step 3: Return to the Initial Display . . . . . . . . . . . . . . . . . . . . . 5-23
Chapter 6. Creating a Graphical Look for Displays . . . . . . . . . . . . . . 6-1

Factors Affecting the Graphical Look . . . . . . . . . . . . . . . . . . . . . . . . 6-1
Hardware Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
Enhanced Display Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4
DDS Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
Creating Menu Bars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Defining the Menu-Bar Choices . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Suppressing the Menu-Bar Separator . . . . . . . . . . . . . . . . . . . . . . 6-8
Defining the Menu-Bar Separator . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
Selection Fields—Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
DDS for Selection Fields—Example . . . . . . . . . . . . . . . . . . . . . . 6-12
Creating a Vertical Single-Choice Selection Field . . . . . . . . . . . . . . . 6-13
Creating a Vertical Multiple-Choice Selection Field . . . . . . . . . . . . . . 6-14
Creating a Horizontal Selection Field . . . . . . . . . . . . . . . . . . . . . . 6-14
Cursor Movement in a Vertical Selection Field . . . . . . . . . . . . . . . . 6-15
Cursor Movement in a Horizontal Selection Field . . . . . . . . . . . . . . . 6-16
Controlling the Selection Indicators in a Selection Field . . . . . . . . . . . 6-17
Creating Pull-Down Menus Using Single-Choice Selection Fields . . . . . . . 6-18
Controlling the Selection Indicators in a Pull-Down Menu . . . . . . . . . . 6-20
Defining Accelerator Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-21
Defining a Menu-Bar Switch Key . . . . . . . . . . . . . . . . . . . . . . . . 6-22
Defining a Cancel Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-23
Limiting Function When Cursor is Outside a Pull-Down Menu . . . . . . . 6-24
Selection Lists—Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24
DDS for Selection Lists—Example . . . . . . . . . . . . . . . . . . . . . . . 6-26
Creating Selection Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26
Controlling the Selection Indicators in a Selection List . . . . . . . . . . . . 6-28
Scroll Bars—Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30
Creating a Scroll Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-31
DDS for Scroll Bars—Example . . . . . . . . . . . . . . . . . . . . . . . . . 6-33
Scroll Bar Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-33
Push Buttons—Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34
DDS for Push Buttons—Example . . . . . . . . . . . . . . . . . . . . . . . . 6-35
Creating Push Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-35
Controlling the Availability of Choices . . . . . . . . . . . . . . . . . . . . . . . 6-36

Auto-Selection in Single-Choice Selection Fields . . . . . . . . . . . . . . . . 6-37
Auto-Enter in Single-Choice Selection Fields . . . . . . . . . . . . . . . . . . . 6-38
Defining Mnemonics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-38
Defining Choice Colors and Attributes . . . . . . . . . . . . . . . . . . . . . . . 6-39
Continued-Entry Fields—Overview . . . . . . . . . . . . . . . . . . . . . . . . . 6-42
Specifying Word Wrap on Continued-Entry Fields . . . . . . . . . . . . . . 6-43
DBCS Considerations with Continued-Entry Fields . . . . . . . . . . . . . . 6-43
How DBCS Data is Returned for Continued-Entry Fields . . . . . . . . . . 6-44
Keyboard Functions with Continued-Entry Fields . . . . . . . . . . . . . . . 6-44
Character data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-44
Field Mark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-45
Automatic Shape Determination (ASD) Processing . . . . . . . . . . . . 6-46
Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-46
Erase EOF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-46
Erase Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-46
Reverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-46
Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-47
Field Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-47
Field Plus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-47
Field Minus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-47
Dup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-47
Kanji . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-47
Character Backspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-48
Character Advance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-48
New Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-48
Field Advance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-49
Field Backspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-49
Forward Field-Exit Processing . . . . . . . . . . . . . . . . . . . . . . . . . . 6-49
Backward Field-Exit Processing . . . . . . . . . . . . . . . . . . . . . . . . . 6-49
How the Menu Bar Interacts with the Application . . . . . . . . . . . . . . . . 6-50
Defining the MNUBARDSP Keyword on the Application Record . . . . . . 6-50
Defining the MNUBARDSP Keyword on the Menu-Bar Record . . . . . . . 6-51
Receiving Input from the Pull-Down Menus . . . . . . . . . . . . . . . . . . 6-53
Receiving Input from Pull-Down Menus Using the Pull-Down Input
Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-53
Removing a Pull-Down Menu after Receiving Input . . . . . . . . . . . . . 6-55
Updating a Pull-Down Menu before Displaying . . . . . . . . . . . . . . . . 6-55
Defining Application Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-56
Defining Choice-Level Help . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-56
Defining Help for a Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-59
Key Interaction for Menu Bars and Pull-Down Menus . . . . . . . . . . . . . . 6-60
Cursor Movement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-61
Pressing the Tab Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-61
Pressing the Cursor Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-62
Using the MNUBARDSP Keyword on the Application Record . . . . . . . . 6-62
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-64
Using the MNUBARDSP Keyword on the Menu-Bar Record . . . . . . . . 6-65
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-66
How the Displays Look . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-67
Simple Hotspots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-68
Command Key Emulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-68
Page Up and Page Down Key Emulation . . . . . . . . . . . . . . . . . . . 6-69
Programmable Mouse Buttons—Overview . . . . . . . . . . . . . . . . . . . . 6-69

Pointer Device Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-69
AID Codes to be Returned . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-70
Programmable Mouse Buttons—Benefits . . . . . . . . . . . . . . . . . . . 6-70
Programmable Mouse Buttons Operation . . . . . . . . . . . . . . . . . . . 6-71
Programmable Mouse Buttons—NWS Considerations . . . . . . . . . . . . 6-72
Programmable Mouse Buttons—Event Processing States . . . . . . . . . . 6-72
Programmable Mouse Buttons—Event Processing Priority . . . . . . . . . 6-73
Unshifted Left Button Pressed Event Processing . . . . . . . . . . . . . 6-73
Unshifted Left Button Released Event Processing . . . . . . . . . . . . . 6-75
Unshifted Left Button Double Click Event Processing . . . . . . . . . . . 6-75
Shifted Left Button Pressed Event Processing . . . . . . . . . . . . . . . 6-76
Shifted Left Button Released Event Processing . . . . . . . . . . . . . . 6-76
Shifted Right Button Pressed Event Processing . . . . . . . . . . . . . . 6-78
Any Other Pointer Device Event Processing . . . . . . . . . . . . . . . . 6-79
Grid Line Structures—Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 6-79
DDS for Grid Line Structures—Example . . . . . . . . . . . . . . . . . . . . 6-80
Grid Line Structures and Windows . . . . . . . . . . . . . . . . . . . . . . . 6-81
Hardware Requirements for Grid Line Structures . . . . . . . . . . . . . . . 6-82
Inserting HTML Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-82
Resolving HTML Field Overlap . . . . . . . . . . . . . . . . . . . . . . . . . 6-83
Chapter 7. Overriding Display Files and Display File Attributes . . . . . . 7-1

Determining Whether or Not to Use Overrides . . . . . . . . . . . . . . . . . . . 7-1
Overriding File Attributes in HLL Programs . . . . . . . . . . . . . . . . . . . . . 7-1
Overriding File Names in HLL Programs . . . . . . . . . . . . . . . . . . . . . . 7-3
Overriding Both File Names and Attributes in HLL Programs . . . . . . . . . . 7-3
Applying Overrides When Compiling a Program . . . . . . . . . . . . . . . . . . 7-4
Deleting Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
Displaying Overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6
Using File Redirection to Override File Names and Libraries or File Types . . 7-6
Overriding Files with the Same File Types . . . . . . . . . . . . . . . . . . . . 7-6
Overriding Files with Different File Types . . . . . . . . . . . . . . . . . . . . 7-6
Recognizing Commands That Ignore or Restrict Overrides . . . . . . . . . . . . 7-9
Chapter 8. Handling Messages and Errors for Display Files . . . . . . . . 8-1

Creating and Displaying Your Own Messages . . . . . . . . . . . . . . . . . . . 8-1
Displaying a Message on the Message Line . . . . . . . . . . . . . . . . . . 8-2
Displaying a Message on the Message Line When a Subfile Control Record
is Written . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Displaying a Message on the Message Line Using a Message Field . . . . 8-3
Priorities for Displaying Messages on a Message Line . . . . . . . . . . . . 8-3
Displaying Messages in a Field on the Display . . . . . . . . . . . . . . . . . 8-3
Displaying Messages on a Program Message Queue . . . . . . . . . . . . . 8-4
Displaying Error Messages through a Subfile . . . . . . . . . . . . . . . . . . 8-4
Sounding an Alarm for Messages . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
Automatically Handling Permanent I/O Errors on Display Stations . . . . . . 8-7
Analyzing Error Messages Sent from the System . . . . . . . . . . . . . . . . . 8-8
Understanding Messages and Message Monitors . . . . . . . . . . . . . . . 8-9
Understanding Major/Minor Return Codes . . . . . . . . . . . . . . . . . . . 8-10
Recovering from Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11
Normal Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11
Completion with Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . 8-12
Permanent System or File Error . . . . . . . . . . . . . . . . . . . . . . . 8-13

Permanent Device or Session Error on I/O Operation . . . . . . . . . . 8-13
Device or Session Error on Open or Acquire Operation . . . . . . . . . 8-14
Recoverable Device or Session Errors on I/O Operation . . . . . . . . . 8-14
Chapter 9. Creating and Accessing Menus Using Display Files . . . . . . 9-1

Running System and User-Defined Menus . . . . . . . . . . . . . . . . . . . . . 9-1
Returning to a Menu after Running the GO command . . . . . . . . . . . . . 9-1
Determining the Previous Menu . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1
Using the Cancel and Exit Keys on Menus . . . . . . . . . . . . . . . . . . . 9-2
Choosing the Menu That Is Shown at Sign-On Time . . . . . . . . . . . . . . 9-3
Defining Your Own Display File Menus . . . . . . . . . . . . . . . . . . . . . . . 9-4
Understanding DDS and Display File Considerations for Menus . . . . . . . 9-4
Describing Menu Actions in a Message File . . . . . . . . . . . . . . . . . . . 9-5
Naming Help Formats for Menus . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
Building a Display File Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7
Describing the Menu and Menu Help Information . . . . . . . . . . . . . . 9-7
Creating the Display File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9
Creating the Message File . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9
Adding Messages to the Message File . . . . . . . . . . . . . . . . . . . . 9-9
Creating the Menu Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9
Running the Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10
Defining Your Own Program Menus . . . . . . . . . . . . . . . . . . . . . . . . 9-10
Passing Parameters for Program Menus . . . . . . . . . . . . . . . . . . . . 9-10
Building a Program Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11
Describing the Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11
Creating the Display File . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12
Entering the Source and Creating a CL Program . . . . . . . . . . . . . 9-12
Creating the Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13
Running the Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13
Exiting from a Program Menu without Returning to the Previous Menu . . 9-13
Program 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-14
Program 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-15
Avoiding Menu Name Conflict . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-15
Naming Your Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-15
Placing Your Menu in a Higher Library in the Library List . . . . . . . . . . 9-16
Specifying the Library That Contains the Menu . . . . . . . . . . . . . . . . 9-16
Using the Generic Menu Specification . . . . . . . . . . . . . . . . . . . . . 9-16
Changing the Command Default after Duplicating a Command . . . . . . . 9-16
Displaying Menu Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16
Changing Menu Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16
Deleting Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17
Chapter 10. Using User-Defined Data Streams . . . . . . . . . . . . . . . . 10-1

Understanding Display Station Differences . . . . . . . . . . . . . . . . . . . . 10-1
Understanding User-Defined Data Stream Limitations . . . . . . . . . . . . . . 10-2
Chapter 11. Passing Data between Programs . . . . . . . . . . . . . . . . 11-1

Passing Data in the Same Routing Step in a Job . . . . . . . . . . . . . . . . 11-1
Passing Data between Routing Steps in a Job . . . . . . . . . . . . . . . . . . 11-3
Chapter 12. Waiting for Input from a Display File, an ICF File, and a
Data Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1
Chapter 13. Using Alternative Character Sets and Code Pages . . . . . 13-1

Specifying Character Translation for Fields . . . . . . . . . . . . . . . . . . . . 13-2
Determining the Character Identifier (CHRID) Value for Your Display . . . . . 13-4
Chapter 14. Improving System Performance with Displays . . . . . . . . 14-1

Deferring the Write Operation for a Display File . . . . . . . . . . . . . . . . . 14-1
Designating the Primary Screen Size for a Display File . . . . . . . . . . . . . 14-1
Writing Only One Page of Subfile Records at a Time . . . . . . . . . . . . . . 14-1
Sharing an Open Data Path (ODP) for the Same Job . . . . . . . . . . . . . . 14-2
Sending Records with Input Fields to the Display in Order . . . . . . . . . . . 14-2
Overlapping and Not Deleting Repeatedly Sent Records . . . . . . . . . . . . 14-2
Restoring the Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Defining Command Attention Keys Rather Than Command Function Keys . 14-3
Using the Invite Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Using Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4

Chapter 2. Defining Your Display in a Display File
A display file defines the format of the information to be presented on a display
station, and how that information is processed by the system on its way to and from
the display station. Data description specifications (DDS) describe the data
referred to by a display file.
This chapter tells you about display files, including how to create them and how to
provide DDS source for them to describe your display.
Establishing a Display File

A display file is an object on the system. An object is a named storage space that
consists of a set of characteristics that describe itself and, in the case of a display
file, the data. Like other objects on the system, display files have the following char-
acteristics:
A display file is named and placed in a library when it is created. The file name
and library name allow you to refer to the display file in your applications.
Once a display file is created, it can be changed, secured, saved, restored, or
deleted.
Before an application program can work with a display station, a display file must
be opened to allow data to flow between the program and the display station.
Application Display
Program File Display Station Data
Device
Description
RV2W045-1
A device description, which is a system object that describes the display station to
the system, must also exist for the display station. A device description contains
information such as device address, device type, model number, and features.
Device descriptions are usually created by system personnel or, for locally attached
devices, can be created during the automatic configuration of the system.
A program may work with more than one display station at a time by doing one of
the following:
Opening more than one display file
Opening a display file that allows more than one display station to be attached
to an open file

Since a display file does not have a set of data uniquely associated with it, the
relationship between the data and the display file is established when the display
file is opened and ends when the display file is closed.
Determining File Descriptions

The file description, which is created at the same time the display file is created,
describes the characteristics of the display file and determines how the display file
does the following:
Controls the display station
Formats output data from the program for presentation at the display station
Formats input data from the display station for presentation to the program
A file description determines how a program is able to use the file. If a program
attempts to perform an operation that is inconsistent with the display file
description, the system does not allow the operation.
The file description is created and deleted at the same time as the display file it
describes. Some parts of a file description may be changed, either permanently
with the Change Display File (CHGDSPF) command or temporarily with the Over-
ride with Display File (OVRDSPF) command.
A file description describes data at three different levels:

Field level
Record level
File level
The following sections describe these levels.
Field-Level Descriptions
A field is the smallest unit of data that is recognized and handled by the data man-
agement support of the system. A field-level description allows you to give the
system detailed characteristics of a field, such as:
Where on the screen the field is to appear
What type of data is valid for the field
Whether the field should be highlighted in some way
How it will be presented from the program to the system on output and from
the system to the program on input.
Where each field is relative to the start of a record
What the characteristics of each field will be while in the system
Where the data for each field should be acquired from for output
Where and how input from the display station should be placed so the program
can use it
Whether the field is an input-capable field or output-capable field only
Only field-level descriptions can determine that valid data is specified for individual
fields on a display.

Record-Level Descriptions
A record is an ordered set of one or more fields. A record-level description
allows you to tell the system what a particular record looks like, or its record
format.
A record-level description is given in one of two ways:

If field-level descriptions are also used, you identify what fields make up the
record format and the order of these fields within the record format. The
system can then perform separate operations on each field described with a
field-level description in the record-level description. For example, one field can
be highlighted while another is not.
If field-level descriptions are not used, the record format is given by specifying
the length of the record. The system handles the entire record as a unit and
cannot perform operations on one part of the record one way and another part
a different way.
Since records are used to transfer data between the system and the application
program, a record-level description is required for display files.
File-Level Descriptions
A file is an organized set of zero or more records (a file with zero records is
empty). A file-level description is a description that applies to the file as a whole.
For a display file, you can specify the following in the file-level description:
What record formats are valid for the display file
What display station should be usable with the display file
What graphic character set is to be assumed for the data that will be entered
through the display file
Deciding Whether to Describe Data Inside or Outside Your Program

When the detailed description of the display file and the data it refers to is con-
tained in a display file rather than imbedded in a program, the data is called
externally described data. When the data is described within the source program,
the data is called program described data.
Externally Described Data

Externally described data exists independently of any program that uses the file.
Using externally described data, you can produce a detailed and standard
description of both the display file and any data that can be processed through the
display file.
To use externally described data, you need to declare that the display file is to be
used as an externally described file. The language compiler or interpreter extracts
the file description from the display and then incorporates it into the program.
There are several advantages to using externally described data:

Increased programmer productivity. The language automatically describes the
record layouts for you without additional coding. You need to describe records
and fields only once (when the file is created). You can then refer to these
fields within the program.
Chapter 2. Defining Your Display in a Display File 2-3

Ease of file and program maintenance. When fields are added, deleted, or
changed, it can be done in one place instead of maintaining the record layout
in each program that uses the file.
Increased data integrity. Since the fields and records are described in one
central location, there is less chance of programming errors when describing
the data in the file to the program. All application programs using the file will
have the same view of the data. Moreover, the system view of the data
becomes the same as the application program view.
Level checking provided. Level checking is an automatic method used when
the program is run that determines if the file description has changed since the
program was last compiled. Depending on the type of change, the program
may only need to be recompiled without modification. This allows better control
over program maintenance. There is more information on the level-checking
function in “Detecting File Description Changes” on page 2-6.
Program-Described Data
You are not required to use external descriptions to describe your displays in your
program. If you do not use externally described data, you must declare variables in
your source program that define to the compiler or interpreter what the data looks
like.
When program-described data is used, the program and the system may not have
the same view of the data:
If the file does not have any field-level descriptions, the system must operate at
the record level. The only concern in this case is that the record length the
program is using is the same as what the system is using. It need not be, but
the system always operates with the record length it has. If the record length
that the system is using differs from the record length the program is using, the
system truncates or pads as necessary.
If the file has field-level descriptions but the program does not use them, the
system uses the field-level descriptions even though the program does not.
The system expects the program to present data according to the file
description and, conversely, provides data to the program according to the
description.
More information about program-described data is found in “Using Program-

Described Data” on page 2-27.
Creating a Display File and Description

Display files are created using the Create Display File (CRTDSPF) command.
You can define the DDS for your display file in one of two ways:
Using the screen design aid (SDA) utility
Entering your own DDS source
You can specify certain attributes about your display file. Information about these
attributes is found in the following:
“Deferring the Write Operation Until a Read Request is Made” on page 3-26
“Saving Previously Displayed Information” on page 3-43
CL Reference
Security – Reference

The following illustration compares the two ways to create display files:
Two Ways to Define Display Files
Enter your own DDS and then use the Design your display as it will look
Create Display File (CRTDSPF) Command ... using the screen design aid (SDA) utility ...
Go To Another List
1. Work with documents in folder

2. Work with documents to be printed
3. Work with folders
4. Work with nontext document data
5. Work with text profiles
Selection
-
F3=Exit F12=Cancel
CRTDSPF command compiles DDS and creates

display file object. SDA generates DDS and runs the CRTDSPF command.
Go To Another List

Selection
-
F3=Exit F12=Cancel
RV2W000-5
You may also combine the two methods, creating an initial display using SDA and
then tailoring the generated DDS.
Changing the File Description

After a display file has been created, the file description can be changed:
To change the file description that was originally specified on the CRTDSPF
command, use the Change Display File (CHGDSPF) command.
To change the file-level, record-level, or field-level information contained in the
DDS source, you must first update the DDS source and then create the display
file again using the CRTDSPF command. A new display file can be created
without deleting the existing display file by specifying REPLACE(YES) on the
CRTDSPF command.
To change both the CL command file-level descriptions and the DDS source,
specify the new values when you create the display file again.

Changes to display file descriptions are applied according to the following:
If the file-level description was changed with a CL command, any program that
uses the file will automatically use those new descriptions.
If the DDS descriptions were changed and the program uses the file as a
program-described file, the system uses the new file-level description.
However, if the DDS descriptions were changed and the program uses the file
as an externally described file, then the record-level and field-level descriptions
used when the program was compiled may not match the changed file. If the
system detects a mismatch when the program opens the file, an error occurs.
See “Detecting File Description Changes.”
You may also temporarily change a file-level description when a display file is
opened. More information about these temporary changes is found in Chapter 7,
“Overriding Display Files and Display File Attributes” on page 7-1.
Detecting File Description Changes

When a program that uses externally described files is compiled, the high-level lan-
guage compiler extracts the record-level and field-level descriptions for the files
referred to in the program and makes those descriptions part of the compiled
program. When you run the program, you can verify that the descriptions with
which the program was compiled are the current descriptions.
The system assigns a unique level identifier for each record format when the file it
is associated with is created. The system uses the following information to deter-
mine the level identifier:
Record format name
Field name
Total length of the record format
Number of fields in the record format
Field attributes (for example, length and decimal positions)
Order of the fields in the record format
Display files may also use the number of and order of special fields called indica-
tors to determine the level identifier.
If you change the DDS for a record format and change any of the items in the
preceding list, the level identifier changes.
To check for changes in the level identifiers when you run your program, specify
*YES for the LVLCHK parameter on the CRTDSPF or CHGDSPF command. When
the display file is opened, the level identifiers of the display file and the file
description that is part of the compiled program are compared format-by-format. If
the identifiers differ or if any of the formats specified in the program do not exist in
the file, a message is sent to the program to identify the condition.
If the identifiers differ, either the formats have been changed or your program does
not use the changed formats. If the changed format does affect your program, you
may decide to do the following:
Compile the program again so that the changes are included
Determine if the changes affect your program before deciding what action to
take.

To check the changes to the record format, run one of the following commands:
Display File Field Description (DSPFFD) command to display the record-level
and field-level descriptions
Start Source Entry Utility (STRSEU) command to display the source file con-
taining the DDS for the file
Display File Description (DSPFD) or the DSPFFD command to display the
format level identifier defined in the file
Display Program References (DSPPGMREF) command to display the format
level identifier that was used when the program was created
Defining Display Fields and Functions in a Record Format

A record format in a display file describes both the format of the record as it is used
in the application program and the format of the record when it is displayed (see
Figure 2-2 on page 2-8).
A record format contains field descriptions, which are defined using data description
specifications (DDS). For each field in a record format, you describe the following:
Location of the field on the display
Length of the field
Type of data contained in the field (character, zoned decimal, or floating point)
Field type (output, input, or output/input).
Information about DDS keywords
This section describes how DDS keywords are used to describe the information
on your display. For more information about specific DDS keywords, see the
DDS Reference.
DDS for Display File: The following source shows the DDS for a sample display
file:
|...+....1....+....2....+....3....+....:833.+....5....+....6....+....7...
A R RECORD
A 3 2'Customer Number:'
A CUST 5 ð 3 2ð
A 3 27'Customer Name:'
A NAME 2ð 3 44
A 4 27'Address:'
A ADDR 2ð 4 44
A CITY 2ð 5 44
A STATE 2 5 66
A ZIP 5 ð 5 7ð
Figure 2-1. Sample DDS Source for a Display File
Table 2-1 on page 2-8 shows the column positions and descriptions for the DDS
specifications.

Table 2-1. Column positions for sample DDS
Column Definition Starting Position
17 Type of name 17
19 - 28 Field name 19
30 - 34 Length 34
36 - 37 Decimal positions 37
39 - 41 Line location 41
42 - 44 Position location 44
45 - 80 Function 45
Record Format Used by the Program: The program passes the fields in the
record in the same order that you described them in the DDS source.
CUST NAME ADDR CITY STATE ZIP
1 5 6 25 26 45 46 65 66 67 68 72
RV2W028-1
Record Format on the Display: The fields are displayed according to the display
positions you assigned them in the DDS source.
CUST NAME
Customer Number: 41394 Customer Name: Sorenson and Walton

Address: 500 5th Avenue
New York NY 55555
ADDR CITY STATE ZIP

RSLH714-0
Figure 2-2. Record Formats in the Program and on the Display
Understanding the Field Attribute Characters

Each field displayed has a beginning attribute character and an ending attribute
character associated with it that define the displayed field. The beginning char-
acter precedes the first character of a field and is displayed as a blank. The ending
attribute character follows the last character of a field and is also displayed as a
blank. For example, if you specify a field for positions 2 through 8, the beginning
attribute character is in position 1 and the ending attribute character is in position 9.
These characters are not included in the field length you specify in DDS. A begin-
ning attribute character can overlap an ending attribute character; that is, they can
occupy the same position on the display. However, nothing else can overlap the
beginning attribute character. Therefore, when you design a display, you must
allow one space for the beginning attribute character of each field. You can use
the blank attribute character to space between fields when they are displayed.

If field-level descriptions are not used, the entire record is treated as a field with a
beginning attribute character and an ending attribute character.
When a record is displayed so that the last field in the record ends in the last posi-
tion on the line, the ending attribute character for that field is in the first position of
the next line. The beginning attribute character of the first field in the next record
can be superimposed on the ending attribute character. For example, if the ending
attribute character for the last field in record 1 is in position 1 of line 5, the begin-
ning attribute character for record 2 can also be in position 1 of line 5. In this case,
the first record is not considered to be overlapped. However, if the first field in a
record begins in position 1, which means that the beginning attribute character is in
the last position of the preceding line, the previous record is overlapped and is
cleared from the display.
To see the locations of fields in the input records and output records used by the
program, see the printed DDS output produced when you created your display file
using the CRTDSPF command.
Understanding How Record Format Fields Can Be Used

The fields you describe in the record format can be used in the following ways:
Note: To see the location of positions on a DDS form, see Table 2-1 on
page 2-8.
Input fields are fields that are passed from the display station to the program
when the program reads a record. Input fields can be initialized with a default
value (specified in the record format for the display file). If the user does not
change the field and the field is selected for input, the default value is passed
to the program. Input fields that are not initialized are displayed as blanks into
which the user can enter data. By default, input fields are underlined on the
display.
Note: Trailing blanks on input fields are replaced by null and not blank charac-
ters; therefore, the Insert key can be used to insert characters in all
input fields that end in blanks.
Output fields are fields that are passed from the program to the display station
when the program writes a record to a display. Output fields contain data pro-
vided by the program, not by the user. To specify an initial value for a named
output field, see “Specifying Default Values for Fields” on page 3-26.
In the case of subfiles, which are special records used to display lists of infor-
mation, output fields are returned to the program as if they were output/input
fields.
Output/input fields are fields that are passed from the program when the
program writes a record to a display and are passed to the program when the
program reads a record from the display and the field is selected for input. By
default, these fields are underlined on the display. Output/input fields are
usually used when the program displays data that can be changed by a user.
To specify an initial value for a named output field, see “Specifying Default
Values for Fields” on page 3-26.
Hidden fields are fields that are passed from and to the program but are not
sent to the display. Hidden fields are useful in applications involving subfiles.
For example, a subfile record can contain record key information in a hidden
field. The hidden field cannot be seen by the user, but is returned to the

program with the subfile record so that the program can return the record to the
database.
Constant fields are fields that are passed to the display but are unknown to
the program. These fields are unnamed and have their constant values defined
in the DDS for the file. DATE, TIME, and MSGCON are examples of keywords
that are allowed only on constant fields and whose constant values are deter-
mined during program run time (DATE and TIME) or DDS compile time
(MSGCON).
Message lines are output fields that are treated as messages.
Program-to-system fields are output-only fields that are named, numeric or
alphanumeric. They are used to communicate between an application program
and the system. Program-to-system fields do not appear on the display. That
is, your program can place data in these fields and the system will use that
data to control its processing on an output operation, but the user cannot see
the contents of these fields.
A field is input-capable if it is an input field or an output/input field. Each input-

capable field has a special attribute called a modified data tag (MDT). The MDT
is set on by the display station when any data is typed into the field. It can also be
set on and cleared by the application program.
The maximum number of fields that you can specify for each record format is
32 763. (See “Understanding the Limitations on the Number of Input-Capable
Fields” on page 3-39 for information on the number of input-capable fields that can
be specified.) The maximum combined length for all fields and indicators in a
record format is 32 763.
The following display shows output fields and input fields displayed in response to a
request (in the form of entering a customer number in an input field) from a user.
à ð
Customer number: 41394
Order number: 41882
Order date: 11/ð1/81
Order amount: $58ð.ðð
A/R balance: $58ð.ðð
Enter next customer number: ______
á ñ
The prompts, Customer number:, Order number:, Order date:, Order amount:, A/R
balance:, and Enter next customer number: are constants. The data associated
with these fields (41394, 41882, 11/01/81, $580.00, and $580.00) is displayed in

output fields. The data is passed from the application program to the system, and
the system displays it. The field following the constant Enter next customer
number: is an input field. The user must enter data into this field (the cursor is
positioned at the beginning of the input field). Input fields are underlined by default.
Editing of the field is normally defined within DDS.
You must specify the location for each field except when the field is a hidden field,
a message line, or a program-to-system field, or when the field is in a subfile
message record format. You cannot specify line 1, position 1 for location, except
when you define a record that can start in any line.
The maximum length of a character field or numeric (zoned decimal) field is the
number of positions remaining (relative to the start location of the field) on the
display minus 1. Another restriction of the numeric (zoned decimal) field is that it
can be no longer than 31, even if more than 31 positions are remaining on the
display.
Specifications for the fields you describe can be retrieved from a previously
described field. The previously described field can be either in a database file or
already defined in the DDS source for the display file. When you use field-level
descriptions from a database file, binary and packed decimal fields are changed to
zoned decimal fields. These fields that you use to define other fields are called
reference fields.
You can define two fields to occupy the same positions on the display, and use
option indicators to select which of the overlapping fields is to be displayed. If
more than one overlapping field is selected on the same output operation, only the
first field selected is displayed.
Defining Function Keys

To write an application using a display station, you have to control both the func-
tions of the keys at the keyboard, and the contents of the display.
Display
Contents
Keyboard
Functions
RV2W001-2
The Enter key can always be used by the user. So that the user can use the other
function keys, you must specify the following DDS keywords to enable the corre-
sponding function key:
CAnn, where nn is 1-24
CFnn, where nn is 1-24
CLEAR

HELP (not required if you only need the Help key to retrieve the message help
on the display)
HOME
PRINT
ROLLDOWN or PAGEUP (not required to be able to roll a subfile when the
subfile page is not equal to the subfile size)
ROLLUP or PAGEDOWN (not required to be able to roll a subfile when the
subfile page is not equal to the subfile size)
MOUBTN (Programmable Mouse Button) allows attention identifiers to be asso-
ciated with various pointer device events.
PSHBTNFLD (Push Button Field) allows an attention ID to be associated with a
push button.
To tell which function key is pressed when you perform the read operation, you
need to define your function keys using one of the following:
Define a response indicator for the function key. A response indicator is an
indicator that returns information back to an application. There are 99
response indicators available to you.
Note: Response indicators are used for more than function keys. For
example, you can use them to tell when the data in a field on the
display has changed.
Examine the input/output feedback area. The input/output feedback area is
status information provided by the system about the operations performed on
an opened file. To find out how to get information from the input/output feed-
back area, see the manual for the programming language you are using. See
Appendix C, “Feedback Area Layouts for Display Files” on page C-1 for a
description of the information available from the feedback areas.
Defining Command Attention (CAnn) and Command Function (CFnn)

Keys
The command function (CFnn) keys and command attention (CAnn) keys are num-
bered 1 through 24 and are the same physical set of keys on the keyboard. These
keyboard keys are usually labeled Cmdnn or PFnn or Fnn, where nn is the associ-
ated key number. They can be used to set a response indicator or to perform a
certain function.
The different command keys do the following:

Command function A record containing changed fields is returned to the
program.
Command attention A record is returned to the program but the record does
not contain the data entered by the user and no field vali-
dation is performed.
If a key is specified as a CFnn key in a file, it cannot also be specified as a CAnn

key in the file. Likewise, if it is specified as a CAnn key, it cannot also be a CFnn
key. For example, if function key 01 is specified as a CAnn key (CA01), you
cannot specify CF01 anywhere in the same file.
If a response indicator is specified for a CFnn key and the key is pressed, the
response indicator is set on and passed to the program with the input data. If a
response indicator is not specified for a CFnn key, only the input data is passed.

Note: The input/output feedback area contains the 1-character attention identifier
(AID), which also identifies the key pressed. See Appendix C, “Feedback
Area Layouts for Display Files” on page C-1 for a description of the
input/output feedback area.
If a response indicator is specified for a CAnn key and the key is pressed, the
response indicator is set on and passed to the program. Fields sent to the display
and hidden fields are returned to the program. If a CFnn key or the Enter key was
previously pressed, the input-only field is returned as previously typed data. If data
was never entered into an input-only field, the field is returned as blanks (character
field) or zeros (numeric field). Fields changed by the user since the last time a
CFnn key or Enter key was pressed are not returned.
The use of CAnn keys can cause the input buffer of the program to contain user-
entered data that does not meet the validation specified in the display file. For
example, the user enters data and presses a CFnn key or the Enter key, and the
data is validated as defined in your DDS. Input data is processed one field at a
time with data manipulation taking place before the validity checking. If a validity-
checking error occurs, a message is selected and all the other input data is pro-
cessed. After all input data is processed and one or more errors have occurred, a
message is sent to the user. Then, if the user presses a valid CAnn key, no
changed data is sent from the display. The data is moved from the input buffer
save area to the input buffer. The input buffer now contains the data that is in
error. If your program is not going to process this data when the CAnn key is
pressed, you do not have a problem. If this is a problem, avoid using CAnn keys;
only use CFnn keys so that data that is not valid can be detected.
If you want to use CAnn keys, you should not specify the following validity-checking
DDS keywords:
CHECK(M10)
CHECK(M11)
CHECK(VN)
CHECK(VNE)
CHKMSGID
COMP/CMP
RANGE
VALUES
The Print, Help, Clear, and Home keys operate in the same manner as the CAnn
keys. The Roll Up, Roll Down, Page Up, and Page Down keys operate in the
same manner as CFnn keys.
Specifying Alternative Keys

You can also define command attention or command function keys to perform the
functions of the Help, Page Up (or Roll Down) and Page Down (or Roll Up) keys.
The function key specified on the keyword identifies the alternative key to be used.
The DDS keywords are:

ALTHELP: Indicates that the help function will be started when either the Help
key or the key specified on the ALTHELP keyword is pressed. If the ALTHELP
keyword is specified but an alternative key is not specified, the default is CA01.

Note that the Help key is an attention key, not a function key, because it does
not return input.
ALTPAGEUP and ALTPAGEDWN: Indicate that the paging functions will be
started when the page keys or the keys specified on the keywords are pressed.
If alternative keys are not specified on the ALTPAGEUP or ALTPAGEDWN
keywords, the defaults are CF07 and CF08, respectively. Note that the page
keys are function keys, because they return input.
The alternative keys specified on the ALTHELP, ALTPAGEUP, and ALTPAGEDWN

keywords provide the same function as the actual keys. For example, if pressing
the Help key starts the help function, then pressing the alternative key defined by
the ALTHELP keyword will also start the help function. Likewise, if pressing the
Page Up or Page Down key returns control to the application program, then
pressing the alternative key will also return control to the application program. Both
of these examples appear to the program as if the actual key was pressed.
The user profile option for paging (USROPT(*ROLLKEY)) applies to the PAGEUP,
PAGEDOWN, ALTPAGEUP, ALTPAGEDWN, ROLLUP, and ROLLDOWN
keywords.
The alternative help key function does not work when the keyboard is locked. For
example, if you type information into a field that is not input-capable, a controller-
detected error occurs and flashing numbers appear. The Help key can be used to
get more information about the error. The function key specified as the alternative
help key will not be valid until the Reset key is pressed, and then the help informa-
tion will no longer be available.
Passing Information via Indicators

Indicators are one-character fields that exist either in the input records and output
records used by the program or in a special indicator area. An indicator is on if it
has the value 1 and off if it has the value 0. You can use indicators to pass infor-
mation from a program to the system or from the system to a program. You
specify how indicators are to be used through the DDS for the display file.
There are two types of indicators for display files:

Option indicators: Pass information from an application program to the
system. These typically are used to control the pro-
cessing of a particular record format by the system.
Response indicators: Pass information from the system to an application
program when an input request completes. Response
indicators can inform the program which function keys
were pressed by the user or whether data was changed
by the user.
Both option and response indicators can be specified at the file level, record format
level, and field level. Indicators specified at the file level apply to all record formats
within the file.

Removing Option and Response Indicators from the Record
Area
You can use the Indicator Area (INDARA) keyword to separate the option and
response indicators from the input and output records used by the program. If you
use the INDARA keyword, the indicators are placed in a separate 99-character
area; see your appropriate high-level language manual for information on how this
99-character area is defined.
If you use the same indicator number as both a response indicator and as an
option indicator, you can use the status of the response indicator to set the option
indicator for a subsequent output operation. For example, indicator 15 is used as
both a response indicator and an option indicator. If the response indicator is on
when an input operation is performed on the record format, option indicator 15 is
set on and will be on when an output operation is performed for that record format.
The maximum number of record formats that you can define for a display file is
1024. If you do not use the INDARA keyword, the maximum number of fields that
you can specify depends on the number of indicators (1 character each) you use
and the length of each field you describe. The total combined length of all fields
and indicators in a record format cannot exceed 32 763 characters. If you use the
INDARA keyword to specify a separate indicator area, the maximum number of
fields that you can specify depends only on the length of each field. The total
number of all fields cannot exceed 32 763.
Enabling Different Response Indicators Simultaneously

It is possible to have different response indicators for the ROLLUP/ROLLDOWN
keywords on record formats displayed at the same time. For example, record A
has specified a roll-up indicator of 52 and record B has specified a roll-up indicator
of 25 and both records are displayed. When a read operation is requested to
record A in your program, the operator presses the Roll Up key which returns
control to your program. Record A is passed to your program with response indi-
cator 52 set on; response indicator 25 is not set. Your program can then do a read
operation to record B. When record B is passed to your program, response indi-
cator 25 is set on; response indicator 52 is not set. Only the response indicator
specified on the record format for which the read operation is done is set. The
record format in which the cursor was located when the Roll Up key was pressed
does not affect the setting of the response indicator associated with the ROLL
keyword.
Setting an Indicator Off

An indicator specified on the SETOF or SETOFF keyword becomes a response
indicator that is set off and returned to the program. The indicator is not set off
until an input operation is performed. If the same indicator is specified elsewhere in
the record format as a response indicator, the indicator is returned to the program
based on the status of the associated keyword condition. For example, if response
indicator 01 is specified both for the SETOF/SETOFF keyword and the CF5 key,
indicator 01 is returned in the on condition when the CF5 key is pressed. If the
indicator is specified elsewhere as a response indicator, there is no need to use the
SETOF/SETOFF keyword.

Inserting Constant Field Text from a Message Description
You can specify that the text for constant fields is contained in a message
description using the Message Constant (MSGCON) keyword.
If the message description used for the constant text is shorter than the field on the
display, the remaining portion of the field is padded with blanks. If the message
description is longer than the field, the message description is truncated.
If the messages description does not exist when the DDS is compiled, the file is not
created. If you change the message description, you will have to create the file
again if you want the display file to contain the updated messages.
Allowing for Right-to-Left Cursor Movement

The cursor can be made to move from right to left on the display between fields
and in input fields. Two parameters for the DDS CHECK keyword can be used to
do this:
CHECK (RL): Moves the cursor from right to left in specified nonnumeric input
fields or all nonnumeric input fields on the display.
CHECK (RLTB): Moves the cursor from right to left between fields.
When using these parameters, remember the following:

Modulus check digit verification is supported, but the check digit is still the byte
to the extreme right of the field.
A field for which right-to-left cursor movement is specified can occupy more
than one line on the display. However, the cursor still moves from the top of
the display to the bottom.
You cannot use right-to-left cursor movement with user-defined data streams.
Note: If no cursor positioning is specified in the display file or by the program, the
cursor is placed in the input-capable field to the extreme left of the top line.
Defining Cursor Movement to Input-Capable Positions Only

Use the cursor input only (CSRINPONLY) keyword to restrict cursor movement to
input-capable positions only. This keyword affects only the cursor arrow keys. This
function moves the cursor to the first input-capable position on a display in the
direction of the arrow key. The user needs to press the cursor key only once in the
appropriate direction to have the cursor move to the input-capable position.
Specify this keyword at the file or record level.
The input-capable positions to which the cursor can move include the following:
Input field (except protected fields)
Selection-field choice (except those on which you cannot place the cursor
because of its choice control (CHCCTL) value)
Selection-list choice (except those on which you cannot place the cursor
because of its choice control (CHCCTL) value)
Message line (if a message is displayed and the keyboard is not locked).
Message subfile defined with the subfile message record (SFLMSGRCD)
keyword.

Several DDS keywords (such as DSPATR(PC) and CSRLOC) can be used to posi-
tion the cursor at any display position. This is true even if the CSRINPONLY
keyword is specified. The first subsequent cursor movement keystroke will move
the cursor to a cursorable location. If no cursorable position exists on the display,
the cursor will be positioned to row 1, column 1. Once the cursor has been moved
from this position, pressing the home key repositions the cursor back to its initial
position.
If a window is displayed with no input fields, the cursor is positioned at row 1,

column 1 of the window. If a cursor movement key is pressed, the cursor moves to
row 1, column 1 of the full display (outside the window). If the window is defined
with *RSTCSR, command keys are not valid outside the window. Pressing the
home key returns the cursor to the window. Pressing any command key or the
Enter key sounds an alarm and returns the cursor to the window. To avoid this
problem, consider specifying an input inhibited input field in the upper corner of the
window or specifying *NORSTCSR on the window keyword.
Notes:
1. If a message subfile is defined with a SFLPAG keyword greater than 1 and the
CSRINPONLY keyword is in effect, any fields that have been turned to reverse
image because of an error, will be turned to unreverse image if the message
subfile is rolled to a partial page of messages.
2. Fields that have been turned to reverse image because of an error are turned
to unreverse image when the following conditions are true:
A message subfile is defined with a SFLPAG keyword greater than 1
The CSRINPONLY keyword is in effect
The message subfile is rolled to a partial page of messages
3. When a record is written with the PUTOVR, ERRMSG, or ERRMSGID
keywords in effect, the state of the CSRINPONLY keyword is not changed. If
the CSRINPONLY keyword is in effect prior to the write operation with the
PUTOVR, ERRMSG, or ERRMSGID keywords, the CSRINPONLY remains in
effect. This is true regardless of the optioning of the CSRINPONLY keyword
on the record assigned the PUTOVR, ERRMSG, or ERRMSGID keywords.
This is also true regardless of the optioning of the PUTOVR, ERRMSG, or
ERRMSGID keywords on the record assigned the CSRINPONLY keyword.
4. Writing a record with the PROTECT keyword does not affect the input fields
associated with messages when the CSRINPONLY keyword is in effect. Any
messages displayed are not protected. Therefore, the cursor may still be
moved the messages.
5. The CSRINPONLY keyword is valid only for display stations attached to a con-
troller that supports an enhanced interface for nonprogrammable work stations.
It is ignored on display stations attached to other controllers.
Defining Cursor Progression for Entry Fields

The FLDCSRPRG keyword lets the user specify the next field the cursor should
move to when the cursor leaves a field.
The DDS for the field looks like this:

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A F1 1ðA B 3 4FLDCSRPRG(F3)
Figure 2-3. DDS for Field-Level Cursor Progression
The parameter for the FLDCSRPRG keyword is the name of the field the cursor will
go to when forward field-exit processing is performed. When the cursor leaves F1
because of a field exit key, it goes to F3. If the field named with this keyword is
optioned off, cursor progression for this field is ignored.
Note: When the cursor leaves a field using backward field-exit processing, the
cursor moves to the first field on the display that has the exited-field name
specified on the FLDCSRPRG keyword. For the DDS in Figure 2-3, if
backward field-exit processing is used to leave field 2, the cursor moves to
field 3.
SFLCSRPRG is the keyword used for subfile cursor progression. The DDS for
subfiles looks like this:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R SFLð1 SFL
A S1 1ðA B 5 5SFLCSRPRG
A S2 1ðA B 5 25
A R CTLð1 SFLCTL(SFLð1)
A SFLPAG(5) SFLSIZ(2ð) SFLDSP
Figure 2-4. DDS for Subfile-Level Cursor Progression
The SFLCSRPRG keyword causes the cursor to move from a field in a subfile
record to the same field in the next displayed subfile record. Without
SFLCSRPRG, the cursor moves from a field in a record to the next field in the
same record. When the cursor leaves field S1 of the first record of the subfile, it
goes to S1 of the second record of the subfile. Without the SFLCSRPRG keyword,
the cursor goes to field S2 of the first record. When the cursor leaves S2, it goes
to S1 of the next record because S2 does not have the SFLCSRPRG keyword.
This keyword is not allowed with subfiles that use field selection. It cannot be used
with horizontal subfiles. When the cursor is on S1 of the last SFL record displayed,
the cursor moves to the next input field below the last SFL record. If there are no
remaining SFL fields, the cursor moves to the top of the display.
Note: The FLDCSRPRG keyword and the SFLCSRPRG keyword are ignored on
displays that are attached to a controller that does not support an enhanced
interface for nonprogrammable work stations.
Defining Attributes for Entry Fields

An entry field’s leading field attribute is changed to a specified attribute when the
cursor enters the field.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A F1 1ðA B 3 4ENTFLDATR(\CURSOR (\DSPATR CS))
A F2 1ðA B 13 4ENTFLDATR(\NOCURSOR (\COLOR RED))

ENTFLDATR tells the system to change the attribute of the field when the cursor
enters the field. *CURSOR and *NOCURSOR are used to specify whether the
cursor is visible when it enters the field. If the *NOCURSOR option is specified, the
cursor row and column values in the input-output feedback area indicate the first
position in the field. You can also specify a color or an attribute.
Note: The ENTFLDATR keyword is ignored on displays that are attached to a
controller that does not support an enhanced interface for nonprogrammable
work stations.
Protecting Entry Fields Using Edit Masks

The EDTMSK keyword is a new DDS keyword for fields with EDTCDE or EDTWRD
keywords. When the field is displayed, certain areas of the field will be protected.
You define which areas to protect.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A F1 6 ðB 3 4EDTWRD(' / / ')
A EDTMSK(' & & ')
A F2 6 ðB 4 4EDTCDE(Y)
A EDTMSK(' & & ')
The ampersand (&) represents a protected part of the field. A blank represents an
unprotected part of the field. The length of the edit mask must equal the display
length of the field. The number of unprotected positions must at least equal the
program length of the field. You must only protect nonnumeric data because pro-
tected data is not returned if the field is changed. Wherever there is an &, that part
is protected no matter what data is in the field.
The first field has the slash (/) characters protected in a date. For the second field,
the / in the date is always protected.
Keyboard functions on displays attached to a controller that supports an enhanced

interface for nonprogrammable work stations are the same for edit-mask fields as
they are for continued-entry fields.
Note: The EDTMSK keyword is ignored on display stations attached to a con-
troller that does not support an enhanced interface for nonprogrammable
work stations.
Specifying Right-to-Left Display Processing

You can specify that records in a display file be written in the right-to-left direction
by using the Display Right-to-Left (DSPRL) keyword. This keyword is allowed only
at the file level.
Figure 2-5 shows an example of the DDS coding.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A DSPRL
A R RECORD
A FLD1 2ðA 5 5')Customer Name(:'
Figure 2-5. Sample DDS for Right-to-Left Display Processing

The DDS in Figure 2-5 produces this output on the display:
à ð
:(emaN remotsuC)
Notice that the left and right parentheses in the DDS are reversed; this is so they
appear correctly on the display. All symmetrical characters have to be specified in
this way.
If your application program uses one display file with the DSPRL keyword and
another display file with the WINDOW keyword, make sure that the display file with
the WINDOW keyword also specifies the DSPRL keyword. Otherwise, the display
assumes the orientation of the display file that has the WINDOW keyword.
If you specify the DSPRL keyword, the cursor moves from right to left when you
enter data. Therefore, it is not necessary to use the CHECK(RL) keyword. If you
specify CHECK(RL) and DSPRL, the CHECK(RL) keyword is ignored.
The DSPRL keyword causes all records in a display file to be written in the right-to-
left direction. You cannot specify that individual records be written in the left-to-
right direction.
If you specify the ERRMSG or the ERRMSGID keywords with the DSPRL keyword,
the messages associated with these keywords display in the left-to-right direction.
Specifying Word Wrap for Fields

Word wrap is the function that automatically moves the last word in a field down to
the next line in the field if the word runs beyond the right margin of the field. To
specify the word wrap function for a named field, use the word wrap (WRDWRAP)
keyword. This keyword can be used at the file, record, or field level. It can only be
used with input-only (I) or output/input (B) fields.
Notes:
1. This function is available only for display stations attached to a controller that
supports an enhanced interface for nonprogrammable work stations.
2. The Reverse key and the Close key cannot be used in a word wrap field.
3. When word wrap is used and the keyboard is in insert mode, null characters
are not shifted to the right; they are replaced.
Word wrap is not allowed for these fields:

DBCS-only fields
Pure fields
Either fields (with double byte)
Open fields with SBCS data
Word wrap is not allowed with the following field types or features:
Signed numeric
Numeric only
Digits only

Magnetic Stripe Reader (DSPATR(OID))
Light Pen (DSPATR(SP))
Right-justify
Mandatory fill
Self-check (M10F/M11F)
Dup allowed
Right-to-left cursor movement (CHECK(RL))
Right-to-left, top-to-bottom cursor movement (CHECK(RLTB))
If all the data cannot fit within a word wrap field without splitting words, the word
wrap function for that field is ignored. The data is written as if word wrap had not
been specified. The subsequent operation of the field is also as if word wrap were
not specified.
Word wrap may be specified on fields that are contained on a single line. In this
case, when the keyboard is in insert mode, null characters are not shifted to the
right; they are replaced.
Specifying Word Wrap for Fields—Tips

Some things to consider when using the word wrap function:
The total length of the input field should allow for character positions at the
ends of lines or segments to be used for padding when a wrap occurs. If a
field is too short, errors will occur or word wrap will be turned off.
The length of each line or segment should be as large, or larger than the
longest word that may be entered in the field. If a line or segment is too short,
errors will occur or the data may be shifted down to the last line or segment.
Extra blanks that are inserted to make a wrap occur are removed when data is
returned to your program.
Emphasizing Fields
You can emphasize a field of a record on the display by specifying the following in
the DDS for the file:
Note: Any function not supported for your display station is ignored.
Table 2-2. DDS for Emphasizing Fields

Type of Emphasizing DDS keyword
Underlining a field (the default for input fields) DSPATR(UL)
Placing vertical separators between the characters in a field DSPATR(CS)
Highlighting a field by displaying it with greater intensity than is DSPATR(HI)
normally used on the display
Reversing the image of a field from light on dark to dark on light or DSPATR(RI)
from dark on light to light on dark
Making the data in the field invisible to the display station user DSPATR(ND)
Placing the cursor at a specific field DSPATR(PC)
Blinking a field when it is displayed DSPATR(BL)
Another way of specifying attributes for a field is by using a program-to-system field

parameter on the DSPATR keyword. Your application program uses the program-

to-system field to set the display attributes or protection attribute for the field to
which the DSPATR keyword applies.
Figure 2-6 shows an example of the DDS coding for program-to-system fields:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R RECORD
A FLD1 5A 2 2DSPATR(&PFLD1)
A FLD2 5A 2 9DSPATR(&PFLD2)
A PFLD1 1A P
A PFLD2 1A P
Figure 2-6. Sample DDS for Program-to-System Fields
One program-to-system field may be used for multiple fields within a record. Only
one program-to-system field can be used per field. You cannot specify the fol-
lowing attributes using the program-to-system field:
MDT Set changed data tag when displayed
OID Operator identification
PC Position cursor
SP Select by light pen
For the valid hexadecimal values that your program can pass to the program-to-
system field, see the DDS Reference.
Adding Color
You can design your displays for use on display stations that show color. The DDS
keyword COLOR allows you to specify the following colors for fields: green, white,
red, turquoise, yellow, pink, and blue. This keyword is ignored if it is selected for a
field displayed on a display station that does not support color.
If the COLOR keyword is not specified in the DDS for the display file but the
display station is specified in the display station description as a color display
station, displays that you have designed for display stations that do not support
color can also be used for the color display station. The keywords DSPATR(UL)
and DSPATR(RI), if specified on separate fields, function the same as they do for
the 5250 display station. However, the keywords DSPATR(CS), DSPATR(HI), and
DSPATR(BL) produce the following colors on a color display station (the specified
display attributes CS, HI, and BL are suppressed):
Color Produced on the Display Display Display

Color Display Station Attribute Attribute Attribute
when No COLOR Keyword Selected: Selected: Selected:
is Specified DSPATR(CS) DSPATR(HI) DSPATR(BL)
Green (normal)
Turquoise X
White X
Red, no blinking X
Red, blinking X X

Color Produced on the Display Display Display
Color Display Station Attribute Attribute Attribute
when No COLOR Keyword Selected: Selected: Selected:
is Specified DSPATR(CS) DSPATR(HI) DSPATR(BL)
Yellow X X
Pink X X
Blue X X X
Editing Output Fields

The system provides editing support that makes fields more readable when they
are displayed. With the system editing support, you can do the following:
Suppress leading zeros
Punctuate a field with commas and periods to show decimal column and to
group digits by threes
Show negative values with a minus sign to the left or right
Show negative values with the letters CR (credit) to the right
Show zero values as zeros or blanks
Show asterisks to the left of significant digits to provide asterisk protection
Show a currency symbol corresponding to the system value QCURSYM
The system provides this editing support with edit codes and edit words. Edit
codes are a defined set of editing patterns. In addition to those provided by the
system, you may also define your own edit codes. You identify edit codes by
name, and the system edits a field according to the pattern defined by the named
edit code. Edit words are edit patterns that you define to produce the desired
results. Edit codes cover most commonly used editing requirements. You need to
use the edit word support only for those editing needs not covered by edit codes.
Edit codes are used as follows:

If your application is using program-described data, your high-level language
may allow you to identify edit codes or create your own edit words.
If your application is using externally described data, the edit code (EDTCDE)
DDS keyword allows you to identify an edit code, and the edit word (EDTWRD)
DDS keyword allows you to define your own editing pattern.
The system provides several edit codes. The editing patterns defined by these
codes are contained in Appendix F, “Edit Codes.”
Defining Your Own Edit Codes

You can define five edit codes to provide more editing function than is available
with the OS/400* edit codes, and to handle common editing functions that would
otherwise require the use of an edit word. These are called user-defined edit
codes. For example, you may need to edit numbers that include hyphens (like
some telephone numbers), or more than one decimal point. You can use user-
defined edit codes for these functions. These edit codes are named QEDIT5,
QEDIT6, QEDIT7, QEDIT8, and QEDIT9 and can be referred to in DDS or a high-
level language program by number (5, 6, 7, 8, or 9).
These edit codes are created by using the Create Edit Description (CRTEDTD)
command. Edit descriptions are always placed in library QSYS. They cannot be

moved or renamed; only one occurrence of each is allowed. Edit descriptions have
an object type of *EDTD.
Even though they are user-defined edit codes, your system comes with a version of
each one of them. You can use these edit descriptions as they are, or you can
delete them and create your own. The editing performed by the IBM-supplied ver-
sions of these edit descriptions as well as a definition of the contents of and the
rules for using any user-defined edit code are described in Appendix F, “Edit
Codes.”
Before using any of the user-defined edit codes, you should check its contents on
your system, since it may have been changed from the IBM-supplied version. The
Display Edit Description (DSPEDTD) command will display the contents of a user-
defined edit code.
Changing a user-defined edit code description does not affect any application or
display file that has already been created using that edit description. If you want
your application to use the changed edit description, you must either create the
high-level language program again (if the edit code is referred to in the program) or
create the file again (if the application is using an externally described file that con-
tains EDTCDE keywords).
Specifying Valid Screen Sizes

In some cases, you can use the following screen size condition names to select
keywords and display locations based on screen size:
*DS3, 24 by 80 (5251 Models 11 and 12, 5291, 5292, 3179 Model 2, 3180-2,
3196, and 3197)
*DS4, 27 by 132 (3180-2; 3197 Models D1, D2, W1, W2; 3477 Models FA, FC,
FD, FE, FG, FW; 3487 Models HA, HG, HW, HC)
Note: The capability to display in 27 by 132 mode is allowed on 3180-2, 3197,
3477 Models FA, FC, FD, FE, FG, FW, and 3487 Models HE, HD, HW,
HC display stations attached to a 6040 or 6041 or 2638 local display
station controller, or remotely attached to a 5294 or 5394 controller.
The display size for 27 by 132 mode is ignored for the DSPSIZ keyword
unless these controllers are specified.
These condition names can be used to place fields in different locations on different
sizes of screens. However, the fields must still be specified in the same order on
each size of screen. For example, the following DDS formats a display for both a
24 by 80 screen and a 27 by 132 screen:

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A DSPSIZ(\DS3 \DS4)
A .
A .
A .
A R RECORD
A NAME 2ð 5 2
A \DS4 3112
A ADDR 3ð 6 2
A \DS4 41ð2
Figure 2-7. Sample DDS for Two Display Sizes
Normally, the display files are set up for a 24 by 80 screen (default size). The
DSPSIZ keyword specifies which display sizes are valid for a file and indicates
which sizes are the primary and secondary screen sizes. (The primary screen size
is the first or only DSPSIZ value.) On the DSPSIZ keyword, the screen size can be
specified as *DS3, *DS4, 24 80, or 27 132. For example, DSPSIZ (24 80) specifies
a screen size of 24 by 80. When primary and secondary display sizes are speci-
fied, the display file is validated for both sizes.
The screen size designated as the primary screen size should be the one with
which the display file will most often be used. A performance benefit will be real-
ized by coding the DSPSIZ keyword in this manner. Additional processing is per-
formed when the actual screen size is the secondary screen size.
The screen size condition names let you improve the use of a single display file for
any size screen. For example, when you are using subfiles, you can specify 22
records per page for a 24 by 80 screen or 25 records per page for a 27 by 132
screen:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A DSPSIZ(\DS4 \DS3)
A .
A .
A .
A SFLPAG(25)
A \DS3 SFLPAG(22)
A .
A .
A .
Figure 2-8. Sample DDS for Subfiles for Two Display Sizes
You can also define your own screen size condition names.
Enabling Your Display to Be Printed

If the Print key is enabled for your display, the user can print the current display by
pressing the Print key. The parameter (or lack of parameter) you specify for the
DDS PRINT keyword controls how your display is printed:

Table 2-3. PRINT Keyword Results Using Print Key
Parameter Action
No parameter The output goes to the display station printer associated with
this display (the PRINTER parameter on the Create Device
Description for Display (CRTDEVDSP) or Change Device
Description for Display (CHGDEVDSP)). If the operation to the
display station printer fails or if there is no display station
printer specified, the output goes to the printer file specified on
the PRTFILE parameter on the display station description.
The default for the PRTFILE parameter is QSYSPRT.
File name and, optionally, The print operation is directed to the specified printer file. If
library name the operation fails, it is directed to the default printer file, which
is specified on the PRTFILE parameter on the CRTDEVDSP or
CHGDEVDSP command.
Response indicator Control returns to the program with the response indicator set
on.
*PGM Control returns to the program which must check the attention
identifier in the input/output feedback area to determine which
key was pressed.
The PRINT keyword can be used at the file level and also at the record level.
When PRINT is specified at the record level, several records with different forms of
the PRINT keyword (or with no PRINT keyword) may be displayed on the screen at
the same time. The last record format written to the screen controls the use of the
Print key for the entire screen.
If you specify the PRINT keyword in any form, the user can print a display con-
taining the message help.
The PRTKEYFMT parameter allows you to control what information is included

when you print your display:
Output only
Output with header information (rows and columns)
Output with border information (title lines, which include the system name, date
and time, and formatted user and display device name)
Output with both border and header information
The PRTKEYFMT parameter on the Change Job (CHGJOB) and Retrieve Job Attri-
butes (RTVJOBA) commands allows you to select how you want your Print key
output to look.
When you change the device description of a display station printer (by using the
CHGDEVPRT command or the DLTDEVD and CRTDEVPRT commands), you
should also change the device description of the associated display station, using
the PRINTER parameter on the CHGDEVDSP command. You should do this even
if the name of the printer, whose device description you changed, remains the
same.

Defining Windows
There are applications that could make use of a window on the display to assist the
user in entering data.
A window is information that overlays part of the current display and allows the
user to read the information inside the window. The remainder of the display is not
overlaid by the window and can still be read by the user.
You can create windows by using standard DDS or by using user-defined data
streams. To use standard DDS, see Chapter 5, “Defining Windows with Display
Files” on page 5-1. Examples are also available in the QUSRTOOL library.
Using Program-Described Data

You can create a display file without using data description specifications. Such a
display file then uses program-described data, and has no record or field level
descriptions of its own.
When you are using program-described data with a display file to communicate with
one or more display stations, only simple display formatting can be performed, and
that formatting must be specified in the high-level language program that is using
the file. All field descriptions are defined and all processing is performed in the
program that uses the file. More than one display file can be opened to the same
display station at the same time within the same program, but only two can be used
on the same display station at the same time: one for input and one for output.
When a display file that uses program-described data is opened, the system treats
the area on the display as a single field. That is, the field length is the same as the
record length. The record length is defined by the program that is using the file,
and stays the same from the time the file is opened until it is closed. Indicators
cannot be passed when records are passed from the program to a display station,
or from the display station to a program. Also, command keys cannot be used for
program-described display files.
The space on the display is assigned to program-described display files as shown

in the following example.
Records for the first file used by the program appear on the first (top) part of the
display. Records for the second file appear on the display immediately following
the area used by records in the first file.
Record from file A First File Used By Program
Record from file B Second File Used By Program
Unused Area
RSLH705-0

The record from file B starts at the beginning of the first full line after the last line of
the record from file A. If the record from file A does not completely fill its last line,
the space is used by neither record and must be accounted for when calculating
the maximum record lengths. In program-described display files, the maximum
record lengths are:
For an input file, the screen size minus 2
For an output file, the screen size minus 2
For an output/input file, the screen size minus 2
For two files (one output and one input), the screen size minus 3
When a program-described display file is opened, it can be defined as:

Input only
Output only
Input and output
Defining Input-Only Files

When an input-only file is opened, the record is initialized to a single blank field on
the screen. The cursor is positioned at the first position of the field and the user
can type in any type of data.
When the program reads the record, the input is passed to the program. The
record is not erased from the screen. The cursor is again positioned at the first
position of the record (field) and the keyboard is unlocked when the program reads
the next record. The user can then type in the next record over the previous
record.
Defining Output-Only Files

When an output-only file is opened, the record is initialized to a single blank field on
the screen. When the program writes a record to the file, the record is displayed
and the keyboard is locked. The user must press the Enter key before another
record can be written to the file. Subsequent records written to the file erase the
currently displayed record because only one record can be displayed for the output
file.
Defining Input and Output Files

When an input and output file is opened, the record is initialized to a single blank
field on the screen. The cursor is positioned at the first position of the file and the
user can type in any kind of data.
The program that is using the file can read records or write records in any
sequence. Whenever a record is written to the file, the modified data tag is set off
(to indicate that data was not entered into the field) and the keyboard is unlocked.
If the user then enters data into the field, the modified data tag is set on. If the
next operation is a write operation instead of a read operation, the data typed in by
the user is written over and the modified data tag is set off again.

Chapter 3. Working with Display Files in an Application
After you define your display file, you can use it in an application. This chapter
discusses the operations performed when a display file is used in an application.
Understanding How the System Allocates Resources

When a high-level language program uses a display file, several operations require
that the system allocate the resources needed to perform that operation. Allocating
file resources causes the system to obtain a lock on a display file when it is
opened. Multiple users then cannot use the same display file in conflicting ways.
For example, the system will not allow you to delete a file while any application
program is using it.
File resources are allocated in two ways:

The system performs the allocation whenever an operation is requested that
requires it. The following operations for display files require allocation:
– Open: The file resources include the file description and the display
station. More information about the open operation is found in “Opening
Display Files” on page 3-2.
– Acquire: The display station is allocated as a resource. More information
about the acquire operation is found in “Acquiring a Display Station for I/O
Operations” on page 3-2.
– Starting a program on a remote system: The file resources include session
resources needed for APPC/APPN*.
If you prefer to ensure that all the resources that are needed by a program are
available before the program is run, you may use the Allocate Object (ALCOBJ)
CL command in the job prior to running the program.
When allocating resources, the system waits for a predefined time if the resources
are not immediately available. If the resources do not become available within the
time limit, the following happens:
If you are using the ALCOBJ command, the command fails.
If your program is performing a file operation, that operation fails and an error
message is sent to the program message queue.
You may attempt to use the error handling functions of your high-level language to
try the operation again. For example, if an open operation fails because another
job is using the display station associated with the file, you could retry the open
operation later when the display station is no longer being used.
The length of time that the system waits when allocating resources is specified on
the ALCOBJ command and on the WAITFILE parameter of the CRTDSPF
command. If the ALCOBJ command is used prior to running a program, then the
value of the WAITFILE parameter is ignored because resources are available. If
your application has error handling procedures for display station errors occurring
on display files, you should specify a value other than *IMMED to allow the system
to recover from the display station error. The system recovery procedures for the
display station must be completed before your program can recover from errors due
to the allocation of resources.

Opening Display Files
The open operation connects a display file to a program for processing.
When a display file is opened, usually one or more display stations are implicitly
acquired, or automatically prepared for I/O operations, for the display file:
Table 3-1. Display Stations Implicitly Acquired When Display Files Are Opened
How the Display File is Other Specifications Display Station Implicitly Acquired
Defined When Opened
Defined with a single *REQUESTER specified Display station at which the user requested the program
display station
*REQUESTER not speci- Display station specified on the DEV parameter of the
fied CRTDSPF, CHGDSPF, or OVRDSPF command
Defined with multiple Opened by a CL All display stations specified on the DEV parameter of
display stations program the CRTDSPF, CHGDSPF, or OVRDSPF command
Opened by any high- The first display station specified on the DEV parameter
level language other than of the CRTDSPF, CHGDSPF, or OVRDSPF command
CL
Defined with no display – None
stations
The value specified on the WAITFILE parameter for the CRTDSPF, CHGDSPF, or
OVRDSPF command is used to determine how long the open operation should wait
for file resources to become available so they can be allocated. If a file resource,
such as a display station, does not become available and the wait time specified
ends, the open operation fails.
Implicitly acquiring a display station when the file is opened results in the following:
The screen is cleared completely and the cursor is placed in the upper-left
corner of the display.
The keyboard is unlocked.
Any display station to be implicitly acquired at the open operation must be varied
on. Switched-line display stations can also be acquired if they are in a vary-on-
pending state. Also, a display station other than the *REQUESTER display station
cannot be acquired if it is signed on.
Acquiring a Display Station for I/O Operations

The system implicitly acquires, or automatically assigns, a display station to a
display file when the display file is opened. However, you may also acquire addi-
tional display stations for your program using the acquire operation. The acquire
operation is used in multiple display file applications or if you are performing error
recovery in your application.
A successful acquire operation results in the following:

The screen is cleared completely and the cursor is placed in the upper-left
corner of the display.
The keyboard is unlocked.

The value specified for the WAITFILE parameter on the CRTDSPF, CHGDSPF, or
OVRDSPF command is used to determine how long the acquire operation should
wait for a display station to become available so it can be allocated. If a display
station does not become available and the wait time ends, no display is acquired.
A display station cannot be allocated unless it is varied on. Switched-line display

stations can be allocated if they are in a vary-on-pending state. Also, a display
station other than the *REQUESTER display station cannot be allocated if it is
signed on.
The system allows only one *REQUESTER display station to be acquired to any
display file, including a multiple-device display file.
If an acquire operation is not successful, the release operation is the only valid
operation to the display station.
Obtaining Information about Display Files and Display Stations

You can obtain information about the open and I/O operations performed on an
open display file, and attribute information about a display station you are using.
Obtaining Information about Open and I/O Operations

After a display file is successfully opened, the system keeps track of the status of
the file in feedback areas.
The open feedback area contains information about the display file after it has
been successfully opened, including:
Name and library of the display file
Number of rows and columns on the display
Name and library of the file after overrides have been applied
Information about the display station defined for the file
The device definition list part of the open feedback area contains information
about each device attached to the display file.
The I/O feedback area contains information about the I/O operations performed on
the display file after it has been successfully opened. The I/O feedback area has
two sections:
The common feedback area contains information about I/O operations that
were performed on the file. This includes the number of operations and the
last operation.
The file-dependent feedback area contains file-specific information for display
files, such as the major/minor return code and the amount of data received
from a display station.
As operations are performed on the display file, the feedback area is updated to
reflect the latest status.
There is one feedback area for each open file. An exception is for shared files,
which share feedback areas as well as the data path between the program and the
file. For more information on shared files, see “Sharing Display Files in the Same
Job” on page 3-50.
Chapter 3. Working with Display Files in an Application 3-3

Feedback areas can be used to provide information when errors occur. For
example, when an error occurs with a display file, the program could determine
predefined error handling operations based on the major/minor return code in the
file-dependent feedback area. More information on major/minor return codes is
available in Chapter 8, “Handling Messages and Errors for Display Files.”
Some high-level languages on the system allow you to access the status and other
information about the file against which operations are being performed.
See Appendix C, “Feedback Area Layouts for Display Files,” for a description of all
the information available from the feedback areas.
Obtaining Attribute Information about Display Stations

The get-attributes operation allows you to obtain the following information about a
specific display station:
Table 3-2. Information Available from the Get-Attributes Operation

Information Details
The specific model of the Valid only when the display station is acquired to the file
display station
The screen size of the Valid only when the display station is acquired to the file
display station
Device acquired indicator Indicates whether or not the display station is currently
acquired to the file
Device invite status Indicates whether or not the display station is invited, and if
so whether or not the display station has data available;
valid only when the display station is acquired to the file
*REQUESTER display Indicates whether or not the display station is the
station indicator *REQUESTER display station
Since the information supplied is also available in the open and input/output feed-
back areas for the display station that is implicitly acquired when the file is opened,
the get-attributes operation is most useful for multiple display file applications. For
more information on how to perform the get-attributes operation, see the appro-
priate high-level language manual.
See Appendix C, “Feedback Area Layouts for Display Files,” for a description of all
the information available from the get-attributes operation.
Sending and Receiving Data

All data written to and read from the display by the application program is done with
records. Records consist of fields, which are individual items of data. The high-
level languages in which application programs are written have I/O statements that
give data to the system to be written to the display and receive data from the
system that it read from the display in the form of records.
The I/O statements of the high-level languages also refer to record formats, which
are defined using DDS. On output, a record format describes how the data given
by the program is to be presented on the display as well as how the data is to be
processed before presenting it. On input, the record format is used to control some

display functions, to extract the program data from all the data which is on the
display, and to present that data back to the application program.
This section uses DDS keywords that control sending and receiving information
to the display. For more information about specific DDS keywords, see the
DDS Reference.
Determining Which Record Formats Are Active on a Display

The system maintains the active record format table, a table of all record formats
that are currently on the display. Read operations may take place against only
those record formats that are in the active record format table. Certain DDS
keywords cause records in the table to be altered.
A record format is added to the table when a write operation that contains the
record format is performed. A record format is removed from the table when a read
operation can no longer be correctly performed for this record.
The active record format table is cleared whenever the display is cleared.
Writing Output to the Display

A write operation passes a record from the program to the system. The record
format in the display file contains the information necessary for the system to
handle the record. The write operation results in the following:
Write Operation
HELLO HELLO
Clears screen Writes record Unlocks

to screen keyboard
RV2W010-1
Placing Records on the Display

One record format can occupy an entire screen or the screen can be divided to
display more than one record format.
If a record is displayed on more than one line, the following rules apply:

The lines must be consecutive lines on the display. For example, if one record
occupies two lines and the record begins on line 2, the record must continue on
line 3.
Only a beginning attribute character can occupy line 1, position 1.
If only the ending attribute character for the last field in a record is in position 1
of the next line, another record format can begin on that same line.
Only one record can occupy a line on the display at a time. If you want to
display a record format that overlaps one or more lines of a record format
already on the display, specify *NO for the clear lines (CLRL) keyword.
CLRL(*NO) clears the common lines before displaying the new record format.
The following three figures show how screens can be divided when the CLRL
keyword is not specified:
Record Format A
RSLH199-0
Figure 3-1 (Part 1 of 3). Valid Placement of Records on a Screen When the CLRL
Keyword Is Not Used

Record Format A
Record Format B
RSLH197-0
Keyword Is Not Used
Record Format A
Record Format D
Record Format B
RSLH198-0
Keyword Is Not Used
The following figure shows how screens cannot be divided when the CLRL
keywords is not specified:

Record Record
Format A Format B
(Fields from different record formats cannot be displayed on the same line.)
Record Format A
Record Format B
Record Format A
Record Format A
Record Format B
(Fields from different record formats cannot be displayed on the same line.)
RV2W048-0
Figure 3-2. Wrong Placement of Records on Screen When CLRL Keyword Not Used
Understanding Which Records Do Not Occupy Space on the

Display
The following types of records do not occupy space on a display but are assumed
to be at line 0:
Records with no fields defined
Records with only hidden, program-to-system, or message fields
Records with the CLRL keyword specified and with no input-capable fields
The system keeps track of only one of these records at a time. If an output opera-
tion for a record assumed to be at line 0 replaces another record assumed to be at
line 0, you can no longer issue an input operation for the replaced record.
Changing Record Formats on a Display

The formats displayed can change while a file is being processed because informa-
tion on a display can be deleted when new formats are displayed.
When your program displays a new record format for output or to allow input, the
existing display is usually erased before the new record format is displayed. For
example, if three record formats are on the display at the same time and you write
another record to the display, the three record formats on the display are erased.
Several DDS keywords, such as the OVERLAY keyword, let you control the dis-
playing of records and input fields on input and output operations. For more infor-
mation about these DDS keywords, see “Overlaying and Erasing Record Formats
on a Display” on page 3-10 and “Clearing a Specified Number of Lines” on
page 3-13.
In the following example, the fields are defined for a record format as follows:

Fields from record format A occupy lines 1 through 4.
Fields from record format B occupy lines 5 through 7.
Fields from record format C occupy lines 8 through 10.
Fields from record format D, which has the CLRL keyword specified for it,
occupy lines 5 through 9.
In the following illustration, record formats A, B, and C are displayed first. When
record format D is displayed, it replaces record formats B and C.
Lines
1
2
3 Record Format A
4
5
6 Record Format B
7
8
Record Format C
9
10
11
12
Record format D is displayed

Lines
1
2
3 Record Format A
4
5
6
7
8 Record Format D
9
10
11
12
RSLH700-0
Figure 3-3. Replacing Record Formats
If record format D did not have the OVERLAY keyword specified for it, the following
would have happened in the previous example:
Record format A would also have been deleted.
Lines 5 through 7 of record format B would have remained on the display. The
data in any fields of record format B overlaid by record format D would have
been changed. (see “Clearing a Specified Number of Lines” on page 3-13 for
more information).
Deciding the Order of Record Formats Written to the Display

To improve performance, records containing input fields should be sent to the
display station in the order in which they appear on the display.
In Figure 3-3, if record formats A and B both contain input fields and appear on the
same display, record format A should be sent to the display first.

Overlaying and Erasing Record Formats on a Display
To avoid erasing the existing display when your program displays a new record
format for output or to allow input, you can specify the OVERLAY keyword. The
OVERLAY keyword causes only those records that are completely or partially over-
lapping to be erased; all other records remain on the display.
Note: The OVERLAY keyword does not prevent the screen from being erased if it
is in effect for the first write operation after a file is opened unless the DDS
keyword ASSUME is specified for any record format in the display file.
You can use the OVERLAY keyword to display information from your application
that needs to be presented together but naturally falls into two or more pieces. For
example, you could use one record format in your application to present information
for a state at the top of a display and another record format to provide the informa-
tion for a particular region within that state.
To place two or more records on the display at the same time, separate the write
operations for your display from the read operations. Then, when you perform
each write operation, the system takes the data from the record that you have pro-
vided it, combines it with the information specified in the record format, and places
it on the display. You can lock the keyboard until the display is ready to perform
the read operations by doing one of the following:
Specify the LOCK keyword on all the record formats
Specify *YES for the Defer Write (DFRWRT) parameter for the display file
You can use multiple record formats when you want to present lists of information
in a subfile to the user. A subfile is a group of records that have the same record
format and are read from and written to a display station in one operation. For
more information about subfiles, see Chapter 4, “Displaying Groups of Records
Using Subfiles” on page 4-1.
To erase certain records from the display when you overlay records, use the
ERASE keyword with the OVERLAY keyword. The following diagram shows the
effect of the OVERLAY and ERASE keywords on an output operation:
Before After
A A
Put D
with OVERLAY D
B
Not Used
C C
Put D A
with OVERLAY
and ERASE C D
Not Used
RV2W032-1

.1/ Record format B is erased because record format D overlaps it, and record
format D is displayed. Record format D did not use all of the space record
format B previously used so it does not overlap record format C.
.2/ Record format B is erased because record format D overlaps it and record
format C is erased because ERASE C is specified. Record format D is dis-
played, and part of the display is no longer in use.
Starting Your Record Format on a Specific Line

To start your record format on a specific line, use the starting line number (SLNO)
keyword. On the SLNO keyword, you can specify one of the following:
The actual starting line number for the record format (a value from 1 to 27).
When you specify an actual line number, the system adjusts the line numbers
for all fields in a record by the specified value minus 1.
A variable starting line number (*VAR), which allows you to specify a starting
line number value in your high-level language program at run time. Depending
on the value specified in your program, the following occurs:
Table 3-3. Results of SLNO(*VAR) Values

Value Specified Results
0 or no value specified A starting line number of 1 is assumed.
Value exceeds the number The system sends a message to the program and the I/O
of lines on the screen or is a request is not performed.
negative value
The starting location for the A warning message (severity 10) is issued at file creation
field for at least one display time. At run time, an error message is issued if the screen
size is row 1, column 1 size being displayed contains a field starting in row 1,
column 1, and the variable starting line number is set to 1
by the program.
Each programming language provides a different way to set and add to the starting
line number. See the appropriate manual for the language you are using.
The system adjusts the line numbers for each field in the record format by the
specified value minus 1. If the resulting line number exceeds the screen size, the
field is not displayed. In addition, if any part of a field goes beyond the last line on
the screen, the field is not displayed.
The SLNO keyword cannot be used in a record format that contains the record-
level keywords ASSUME, KEEP, USRDFN, SFL, or SFLCTL, or in a display file
that contains the file level keyword PASSRCD.
However, the SLNO keyword may be used with several other DDS keywords:
If the CLRL keyword is used with the SLNO keyword and the CLRL keyword
specifies a number of lines to clear, clearing starts with the starting line number
on the SLNO keyword.
If you use the SLNO(*VAR) keyword with the OVERLAY keyword but without
the CLRL keyword and then write the record several times, each time with a
different starting line number, the previous record is deleted before the new
record is displayed.

If the SLNO keyword is used with the PUTOVR, PUTRETAIN, ERRMSG, or
ERRMSGID keyword in effect, the system checks the starting line number to
determine if the previous output operation to the record had the same starting
line number:
– If the starting line number is the same, the action specified by the
PUTOVR, PUTRETAIN, ERRMSG, or ERRMSGID keyword is performed.
– If the starting line numbers are not the same, the PUTOVR, PUTRETAIN,
ERRMSG, or ERRMSGID keyword is ignored, and the record format is dis-
played with the lines adjusted by the new value.
The following DDS shows an example of using the SLNO(*VAR) keyword:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R ORDENT
A 1 36'ORDER ENTRY'
A 3 2'Enter customer number:'
A CUST 5 B +2
A 5 2'Enter order number:'
A ORDNBR 6 B +2
A 7 2'ITEM NUMBER'
A 7 18'DESCRIPTION'
A 7 44'QUANTITY'
A R LINITM OVERLAY
A SLNO(\VAR)
A CLRL(\NO)
A ITEM 6 ðO 9 2
A DESCRP 2ð O 9 18
A QTYORD 3 ðO 9 44
A R INPFMT OVERLAY
A 23 2'Enter item number:'
A ITMNBR 6 ðI +2
A +5'Enter Qty:'
A QTY 3 ðI +2
Figure 3-4. Sample DDS Source Showing Use of the SLNO(*VAR) Keyword
In this example, the record format ORDENT contains the prompt for an Order Entry
display. When the user enters a customer number and an order number, the fol-
lowing occurs:
1. The program writes the record format INPFMT to the display, which allows the
user to enter an item number and quantity ordered.
2. After the user enters the item number and the quantity, the program retrieves
the description of the item from a file and writes the record format LINITM to
the display.
3. The program writes the INPFMT record format to the display to allow the user
to enter another item number.
The design of this display allows the user to enter the item number and quantity on
the same line. As a line item is entered, the program uses the LINITM record
format to build the order on the display. The SLNO(*VAR) keyword is used so the
program can add a line to the display each time the LINITM record format is
written. The CLRL(*NO) keyword has to be specified on the LINITM record format
so that the previous record is not deleted when a new record is written.

When the LINITM record format is first written to the display, the value of *VAR is 1
so the fields are displayed on line 9. On each successive output operation to this
record format, the program adds 1 to the starting line number so that a new line
item is added to the display.
After the user enters two item numbers and quantities, the display looks like this:
à ORDER ENTRY
ð
Enter customer number: 34785
Enter order number: 1J234ð
ITEM NUMBER DESCRIPTION QUANTITY
96321 Pliers 115

86768 Saws 125
Enter item number: ___ Enter Qty: ___
á ñ
The SLNO keyword is most efficient when you want the user to always enter data
on the same line and yet build a display of previously entered records, as shown in
the preceding example. However, for a typical inquiry function where you want to
display more than one record at a time, the use of a subfile is more efficient.
Clearing a Specified Number of Lines

To clear a certain number of lines on the screen before you write a record format to
the screen, use the clear lines (CLRL) keyword. You can specify the CLRL
keyword even when the record contains no fields that are displayed. Clearing
begins with the starting line number, and the value specified on the CLRL keyword
determines the number of lines to be cleared (any value from 1 to 27). The starting
line number is determined as follows:
If the SLNO keyword is not specified, the field locations determine the starting
line number.
If the SLNO(nn) keyword is specified, nn is the starting line number.
If the SLNO(*VAR) keyword is specified, the starting line number defaults to 1
at the time the display file is created and can be changed by the application
program at the time it is run.
You can also specify the following values to clear specific lines:
Value Lines Cleared
*END All lines from the starting line to the end of the display
*NO Only the lines of the display that are used by the overlapping record
format

*ALL All lines of the display. Since the default action is to clear all the lines of
the screen, you do not normally have to specify CLRL(*ALL) unless you
also specify a DDS keyword, such as USRDSPMGT, that changes this
default.
Note: When you use the CLRL keyword, you should specify *YES for the
RSTDSP parameter on the CRTDSPF or CHGDSPF command; otherwise,
data on the display may be lost if the file is suspended.
You can use the CLRL(*NO) keyword to prevent an overlapped record from being
deleted when the overlapping record is written to the display. If you use this
keyword, any records being displayed that are to be overlapped are not deleted
from the screen; the new record overlays them entirely or partially. There is a per-
formance advantage to using CLRL(*NO) if you have a display that contains con-
stants and data that is repeatedly sent to the screen. By sending the constants as
a separate format and by using CLRL(*NO) for the format containing only the data,
you can reduce the time required to send the record format to the display. For
example:
Lines
1
2
3
Record Format A (lines 1 through 4)
4
5
Record Format B (lines 5 through 8)
6
7 Record Format C (lines 7 through 12)
8
9
10
11
12
RSLH701-0
If CLRL(*NO) is specified on record format C, all fields of record format B not over-
lapped by C remain on the screen when record format C is written to the screen. If
the OVERLAY or PUTOVR keyword were used for this same situation, record
format B would be deleted when record format C is written to the screen because
record format C overlaps record format B.
The following considerations apply to the CLRL keyword when used with other DDS
keywords:
If the CLRL keyword is specified in a record format with input-capable fields,
any input-capable fields in the overlapped records are no longer input-capable.
Fields in all other record formats that are not overlapped remain input-capable.
If you do not want these fields to remain input-capable, you should use the
PROTECT keyword on the record format along with the CLRL(nn) keyword.
Records with the CLRL keyword and with no input-capable fields are assumed
to be at line 0. Thus, if the CLRL(nn) keyword is specified in a record format
that has no input-capable fields, all records already on the display remain on
the display and their input-capable fields remain input-capable. Because
records that start at line 0 are not known to the system, the ROLLUP and
ROLLDOWN keywords do not work for these records. Also, these records may
not be cleared completely when they are overlapped by other records that have
the OVERLAY keyword specified. The lines needed for the overlapping record

are cleared whereas the lines not needed for the overlapping record remain on
the screen.
The CLRL(nn) keyword is not allowed in a record format with the record-level
keywords ASSUME, KEEP, USRDFN, SFL, or SFLCTL, or in a display file with
the file level keyword PASSRCD.
The CLRL(nn) keyword is ignored if either the ERRMSG or ERRMSGID
keyword is in effect.
If the CLRL(nn) keyword is used and the PUTOVR or PUTRETAIN keyword is
in effect, the clearing of lines may conflict with the PUTOVR or PUTRETAIN
function. The PUTOVR or PUTRETAIN keyword requires that the fields being
overridden be on the display whereas the CLRL(nn) keyword may clear those
fields first. If a record becomes unavailable for input because of the CLRL(nn)
keyword, the input-capable fields remain input-capable if the PUTOVR keyword
is in effect. However, the system issues a message if the program attempts to
read such a record. Although the CLRL(nn), CLRL(*NO), and CLRL(*END)
keywords imply the OVERLAY keyword, the following example illustrates the
differences between the CLRL and OVERLAY keywords:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R RECORD1
A FLD1 1ð I 4 5
A FLD2 1ð I 5 5
A 5 21'Enter employee number'
A R RECORD2A OVERLAY
A FLD3 1 B 5 2
A 6 2'Required field'
A 7 2'Enter 1, 2, or N'
A FLD4 19 O 8 2
A R RECORD2B CLRL(4)
A FLD5 1 B 5 2
A 6 2'Required field'
A 7 2'Enter 1, 2, or N'
A FLD6 19 O 8 2
A R RECORD3 OVERLAY
A FLD7 1ð O 8 15
A . .
A . .
A . .
A FLD8 1ð B 12 4
A R RECORD4 CLRL(\NO)
A FLD9 42 I 11 2
Figure 3-5. Sample DDS Source Showing Difference between CLRL and OVERLAY
The following results occur if the program performs the output operations on the
record format in the following order:

Table 3-4. Results from CLRL Example
Order of Record
Formats Results
RECORD1 Lines 4 through 12 are deleted when RECORD2A is written to the
RECORD3 display because RECORD2A overlaps RECORD1 and RECORD3,
RECORD2A and only the OVERLAY keyword is specified for RECORD2A.
RECORD1 Lines 5 through 8 are cleared before RECORD2B is written to the
RECORD3 display because the CLRL(4) keyword is specified. FLD1 in
RECORD2B RECORD1 and any input-capable fields in RECORD3 (lines 9
through 12) remain on the screen but are no longer input-capable
because part of RECORD1 and RECORD3 is overlapped by
RECORD2B.
RECORD1 RECORD1 remains on the screen when RECORD3 is written to the
RECORD3 screen because the OVERLAY keyword is specified in RECORD3.
RECORD4 When RECORD4 is written to the screen, it uses part of line 11,
RECORD2A which is also used by RECORD3, and because CLRL(*NO) is
specified in RECORD4, RECORD3 remains on the screen.
However, the system is no longer aware that RECORD3 is on the
screen so when RECORD2A is written, only lines 4 through 8 are
cleared; the part of RECORD3 below line 8 remains on the screen.
Rolling Data between Two Lines on a Display

If you are using a high-level language program, you can roll the data between two
lines on the display up or down by specifying the allow roll (ALWROL) keyword.
The lines vacated by the rolled data are set to nulls and another record format can
be written to those lines.
In your program, you must specify the following:

The starting line number and the ending line number of the lines to be rolled.
The start and end line numbers define a window on the screen.
The number of lines to be rolled. If the number of lines to be rolled is positive,
the data is rolled up. If the number of lines to be rolled is negative, the data is
rolled down.
Whether the roll is to be up or down.
In the window, the lines of data are rolled up (or down) by the number of lines you
specified in your program. The data rolled off the window is gone. The input-
capable fields of any record format partially or completely within the window are no
longer input-capable. After the roll, your program cannot issue an input operation
to any record format within the window.
The following example shows a display before a program-controlled roll occurs, and
the same display after a program-controlled roll occurs. The following is specified
in the program:
The starting line number is 8
The ending line number is 18
The number of lines to be rolled down is 6.

Display before the Roll Operation
UPDATE CUSTOMER ORDER RECORD Line 1
To end this program, press CF1 Line 3
Record
format
1
Enter your operator number: Line 8
Enter customer number: Line 10
Press CF3 to display option menu Line 12
RSLH165-0
Display after the Roll Down Operation
UPDATE CUSTOMER ORDER RECORD Line 1

Unchanged
To end this program, press CF1 Line 3
Item number ordered: Line 9 Record

format
Quantity ordered: Line 11 2
Enter your operator number: 25

Line 14
Enter customer number: 12345
Line 16
Press CF3 to display option menu
Line 18
Previous
lines 8
through 12
after being
rolled down
RSLH171-0
The ALWROL keyword cannot be used with the file level keyword PASSRCD or
with the following record-level keywords: KEEP, ASSUME, USRDFN, SFL, or
SFLCTL.
If the ERRMSG, ERRMSGID, PUTOVR, or PUTRETAIN keyword is in effect for the

same output operation in which the ALWROL keyword is in effect, the system
issues message CPF5014. If an ERRMSG, ERRMSGID, PUTOVR, or record level

PUTRETAIN keyword is not in effect, the message is not issued. However, if the
PUTRETAIN keyword is specified at the field level with option indicators, the
message (CPF5014) is issued if the option indicators for the PUTRETAIN keyword
are on or off.
Overriding the Attributes or the Content of a Field

To send only some of the data and attributes of a record to the display, use the
following keywords:
Put with explicit override (PUTOVR)
Override data (OVRDTA)
Override attribute (OVRATR)
By sending less data or attributes, you can shorten the response time at the
display, especially for remotely attached displays.
When the PUTOVR keyword is specified, the following occurs:

The display attributes are overridden for those fields with the OVRATR keyword
in effect.
The data content is overridden for those fields with the OVRDTA keyword in
effect.
The output operation functions as if the OVERLAY keyword were also in effect,
even if the OVERLAY keyword is not specified.
The PUTOVR keyword cannot be specified in a record format that contains the
PUTRETAIN keyword nor can it be used for subfile records.
The display attributes that can be overridden by the OVRATR keyword are:
CHECK(ER) End of Record
CHECK(ME) Mandatory enter
DSPATR(MDT) Set on modified data tag
DSPATR(PR) Protect
DSPATR(BL) Blink
DSPATR(CS) Column separator
DSPATR(HI) High intensity
DSPATR(ND) Nondisplay
DSPATR(PC) Position cursor
DSPATR(RI) Reverse image
DSPATR(UL) Underline
DUP Dup key capable
The following is an example of the PUTOVR keyword.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R ITMRVW
A PUTOVR
A 1 35'ITEM REVIEW'
A 3 2'Item number:'
A ITMNBR 5 B +2
A 5 2'Item description:'
A ITMDSC 2ð +2
A 1ð OVRDTA
A 7 2'Item price:'
A ITMPRC 8 2 +2
A 15 OVRDTA
A 9 2'Warehouse location:'
A WHSLOC 3 +2
A 2ð OVRDTA
A 11 2'Quantity on hand:'
A QTYOH 5 ð +2
A 25 OVRDTA
A OVRATR
A N25 3ð DSPATR(HI)
Figure 3-6. Sample DDS Source Showing Use of the PUTOVR Keyword
The DDS describes a display that allows the user to enter an item number, and to
review the item description, the item price, the warehouse location, and the quantity
on hand:
1. On the first output operation, all fields are sent to the display, and all option
indicators are off. The PUTOVR keyword is ignored because the record is not
already on the screen. On the first output operation, the current field values in
the program are displayed for the output fields. If your program has not set
any of these fields, the values will be whatever the high-level language used to
initialize the output buffer.
If an output-capable field must always have a specific value on the first output
operation, you can use the DFT or DFTVAL keywords to initialize the field to
that value. When used on an output-capable field with the PUTOVR and
OVRDTA keywords the DFT keyword causes the system to place the default
value rather than the program value on the display when the record is first
placed on the display.
2. The user enters an item number. The program sets on indicators 10, 15, 20,
and 25 and issues a write-read operation to display the output fields. On the
write operation, the PUTOVR keyword is in effect because the record is already
on the screen. Because the OVRDTA keyword is specified on the ITMDSC,
ITMPRC, WHSLOC, and QTYOH fields and because their option indicators are
on, these fields are the only data sent to the display.
If the user enters another item number and the data for a field already dis-
played does not change, the program sets off the option indicator and does not
display that field again. For example, assume that for the second item number,
the WHSLOC is the same as for the first item number. On the output operation
to display the information for the second item number, the program sets off
indicator 20. Therefore, the only fields sent to the display are ITMDSC,
ITMPRC, and QTYOH because indicators 10, 15, and 25 are on.

For the QTYOH field, the program can change the attributes for the field without
changing the data by setting off indicator 25 and setting on indicator 30 before the
output operation.
You can use the option indicators on the OVRDTA keyword to control which fields
are sent to the display. If no option indicators are used, all fields with the OVRDTA
keyword specified are sent to the display on each output operation because the
OVRDTA keyword is in effect when the PUTOVR keyword is in effect. In the pre-
ceding example, if no option indicators were used, all four fields would be sent to
the display on each output operation. You can also use the same indicator to
control more than one field.
An alternative design for this same application is to use two record formats and
send the constants to the display in one record format and the variables in the
other record format. You would have to use the CLRL(*NO) keyword to prevent the
record format containing the constants from being erased. However, if the record
format is already on the display, the use of the PUTOVR keyword provides the
most efficient approach.
The following examples illustrate how to use the PUTOVR keyword for efficient
coding:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R PROMPT
A CFð3(91 'Return')
A PUTOVR
A ERASEINP
A OVERLAY
A 1 28'Efficient Coding Example'
A 3 2'FLD1'
A FLD1 5 I 3 7
A 5 2'FLD2'
A FLD2 5 5 7
A OVRDTA
A 7 2'FLD3'
A FLD3 5 7 7
A 15 OVRDTA
A 9 2'FLD4'
A FLD4 5 9 7
A OVRDTA
A 16 DSPATR(HI)
A 11 2'FLD5'
A FLD5 5 11 7DFT('ABCDE')
A OVRDTA
A 17 DSPATR(HI)
A 13 2'Constant 1'
A OVRATR
A 18 DSPATR(BL)
A 15 2'Constant 2'
A OVRATR
A N19 DSPATR(ND)
A 17 2'Constant 3'
A 2ð OVRATR DSPATR(RI)
Figure 3-7. Sample DDS Source Showing Efficient Use of PUTOVR Keyword

In the preceding example, the following happens:
1. If the record format is not currently on the display, the PUTOVR, OVRATR, and
OVRDTA keywords are ignored when the record format is displayed. On sub-
sequent output operations when the record format is already on the display and
the PUTOVR keyword is in effect, only the fields or constants defined with the
OVRATR or OVRDTA keyword are sent to the display. The ERASEINP
keyword is used because it is the most efficient way to clear all input fields, and
the OVERLAY keyword is used because it is required with the ERASEINP
keyword.
2. FLD1 is an input field that is cleared each time the record format is displayed.
3. FLD2 is sent to the display each time the record format is displayed because
its associated OVRDTA keyword is unconditionally specified.
4. FLD3 is sent to the display on the first output operation. On subsequent output
operations, FLD3 is not sent to the display unless indicator 15, which is used to
condition the OVRDTA keyword, is on.
5. FLD4 is sent to the display on each output operation because its associated
OVRDTA keyword is unconditionally specified. When the OVRDTA keyword is
in effect, the attributes for the field are always sent to the display. Indicator 16
is used to control the DSPATR(HI) keyword for FLD4.
6. On the first output operation, the default value of ABCDE appears in FLD5. On
subsequent output operations, a value from the program is displayed in FLD5
because its associated OVRDTA keyword is unconditionally specified.
Indicator 17 is used to control the DSPATR(HI) keyword for FLD5.
7. Constant 1 is always displayed, but it is only sent to the display on the first
output operation. However, the attributes for the field are sent to the display
each time the record format is written, and option indicator 18 is used to control
whether the field blinks.
8. Constant 2 is sent to the display only on the first output operation. However,
the attributes for the field are sent to the display each time the record format is
written, and if option indicator 19 is off, Constant 2 will not be displayed.
9. Constant 3 is sent to the display only on the first output operation. However,
the attributes for this field are not sent to the display on subsequent output
operations unless indicator 20 is on. If option indicator 20 is on when an output
operation is done, Constant 3 is displayed in reverse image, and it will continue
to appear in reverse image regardless of the status of indicator 20 on subse-
quent output operations.
The following example shows how the PUTOVR keyword can be used for an appli-
cation in which the user enters some information common to a group of records
and then repeatedly enters detailed information relating to specific records in the
group.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R HEADING TEXT('Header Display')
A SETOF(88 'ERASEINP CTL')
A CFð3(91 'Return')
A 1 2'HEADING INFORMATION'
A DSPATR(HI)
A 1 6ð'CF3-End of Program'
A 2 6ð'CF2-New heading'
A HDING 5 I +2
A R DETAIL TEXT('Detail display')
A OVERLAY
A PUTOVR
A PROTECT
A 88 ERASEINP
A CFð2(92 'New header')
A 8 2'DETAIL DISPLAY'
A DSPATR(HI)
A 1ð 2'Input'
A FLDA 5 I +2
A 12 2'Output'
A FLDB 5 +2DFT(' ')
A OVRDTA
Figure 3-8. Sample DDS Source Showing Another Use of PUTOVR Keyword
In the preceding example, the following happens:

1. The program displays the HEADING record format, and then performs an input
operation to the record format to receive the HDING field as input. The SETOF
keyword in the HEADING record format sets off indicator 88, which is used to
condition the ERASEINP keyword in the DETAIL record format.
2. The program then displays the DETAIL record format. Because the OVERLAY
keyword is in effect, the HEADING record format remains on the display. The
PROTECT keyword is also in effect so the input field (HDING) in the HEADING
record format is protected. Therefore, the user cannot change this field when
the DETAIL record format is displayed.
3. The ERASEINP keyword is conditioned by option indicator 88. Because indi-
cator 88 is off the first time the DETAIL record format is displayed, the
ERASEINP keyword is not in effect. On subsequent output operations, indi-
cator 88 is set on and the ERASEINP keyword is in effect. Therefore, FLDA is
cleared on subsequent output operations. The option indicator is used on the
ERASEINP keyword so that it is not in effect the first time the DETAIL record
format is displayed. Because the ERASEINP keyword is processed before the
PROTECT keyword, it would clear the HDING field in the HEADING record
format if it were in effect the first time the DETAIL record format is written.
4. FLDB is an output field that is sent to the display on each output operation
because the OVRDTA keyword is specified unconditionally. The DFT keyword
with a value of blanks is used so the field will not contain any data the first time
the DETAIL record is displayed for a group.

Erasing All Unprotected Input and Output/Input Fields on the
Display
To erase all unprotected input-capable fields, use the erase input (ERASEINP)
keyword. The ERASEINP keyword can only be used with the OVERLAY keyword.
To erase all unprotected input-capable fields that have their modified data tags on,
specify *MDTON for the ERASEINP keyword. To erase all unprotected input-
capable fields whether their modified data tags are on or not, specify *ALL for the
ERASEINP keyword.
The ERASEINP keyword can improve response time because it clears fields rather
than sends blanks to the display. If the fields erased at the display do not have
their modified data tags set on for the next read operation, data is returned for
those fields from the input save area. This is data saved by the system from the
previous return of the field from the display station.
You can use the INZINP keyword at the record level with ERASEINP(*ALL) and
PUTOVR to initialize the input save area without sending data for the cleared fields
to the display.
Resetting Modified Data Tags Associated with Records on the

Display
To reset the modified data tags, use the modified data tag off (MDTOFF) keyword.
The MDTOFF keyword, which can only be used with the OVERLAY keyword, is
processed before the next record is displayed.
To reset only the modified data tags of the unprotected fields, specify *UNPR for
the MDTOFF keyword. To reset the modified data tags of all input-capable fields,
specify *ALL for the MDTOFF keyword.
Keeping a Record or Field on a Display

The PUTRETAIN keyword is used to reduce the number of characters sent to the
display. This keyword can only be used with the OVERLAY keyword and can be
used to change only the display attributes of a field. Except for not sending data,
all other functions are supported when the PUTRETAIN keyword is specified.
Using the PUTRETAIN keyword at either the record format level or the field level
can cause fields from this record which were previously written to the display to
remain on the display even if they are not selected for this write operation. To
avoid this, you can use the PUTRETAIN keyword at the field level and define the
field twice: once with option indicators as you want it to appear in the display, and
once with no option indicators and as a constant with a value of blanks. If the first
field is not selected, the second field is. The second field is displayed so the
blanks erase the contents of the field that is not selected.
Note: The ERRMSG and ERRMSGID keywords function as if the PUTRETAIN
keyword were specified at the record format level. That is, no fields are
sent to the display, no field attributes for other fields are changed, and no
command keys are changed when the ERRMSG and ERRMSGID keywords
are in effect.
The following is an example of the PUTRETAIN keyword used at the record format
level. The following DDS describes a student search menu having three options.

The option selected is highlighted. For example, if option 1 is selected, the char-
acter string 1. By number is highlighted.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R SELECT OVERLAY
A PUTRETAIN ERASEINP
A N44 1 2'STUDENT SEARCH MENU'
A N44 3 1ð'1. By number'
A 1ð DSPATR(HI)
A N44 4 1ð'2. By name'
A 11 DSPATR(HI)
A N44 5 1ð'3. By address'
A 12 DSPATR(HI)
A N44 1ð 2'Select the number of the item to +
A search by:'
A INPUT 1 I 1ð 47
A 44 DSPATR(RI)
Figure 3-9. Sample DDS Source Showing Use of the PUTRETAIN Keyword
The following happens:

1. On the first output operation, all fields are sent to the display, and all option
indicators are off. The PUTRETAIN keyword is ignored because the record is
not already on the display.
2. The user selects item 1, 2, or 3. When the program receives the input, it sets
on indicator 10, 11, or 12, depending on which item is chosen. If anything
other than item 1, 2, or 3 is chosen, the program sets on indicator 44.
On the next output operation, field 1, 2, or 3 is highlighted, or the input field is
in reverse image, depending on which indicator is on.
The data for all fields is not resent to the display but the field attributes are
resent. No data is sent for constants. To resend attributes for each output
field or constant, 4 bytes are needed. To resend attributes for each input-
capable field, 9 bytes are needed. By using the PUTRETAIN keyword, you
reduce the number of characters sent to the display by 96, from 138 to 42.
(These numbers do not include protocol control characters needed to frame
data.)
The ERASEINP keyword causes the user’s selection to be erased.
The following is an example of the PUTRETAIN keyword used at the field level.
Here, the PUTRETAIN keyword is used to keep input that is not valid and to reduce
the number of characters sent to the display. The following DDS describes a
display containing an item’s name, color, shape, and size, and asks for quantity.
The user can change the values for color, shape, and size.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R CHANGE OVERLAY
A 1 2'CHANGE MENU'
A N43 3 2'Change the underlined fields to +
A change the description.'
A 4 2'Item:'
A ITEM 2ð O 4 12
A 44 PUTRETAIN
A 5 2'Quantity:'
A QTY 4Y ðI 5 12
A 44 PUTRETAIN
A ð9 DSPATR(BL PC)
A 6 2'Color:'
A COLOR 1ð B 6 12
A 44 PUTRETAIN
A 1ð DSPATR(BL PC)
A 7 2'Shape:'
A SHAPE 1ð B 7 12
A 44 PUTRETAIN
A 11 DSPATR(BL PC)
A 8 2'Size:'
A SIZE 1ð B 8 12
A 44 PUTRETAIN
A 12 DSPATR(BL PC)
A 44 9 2'Choice:'
A 44 CHOICE 2ð O 9 12
A 15 9 12' '
Figure 3-10. Sample DDS Source Showing Use of the PUTRETAIN Keyword
The following happens:

1. On the first output operation, all indicators are off, so all the constants and the
fields except CHOICE and the constant field following CHOICE are sent to the
display.
2. The user enters a quantity. The program sets on indicator 43. When the next
output operation occurs, indicator 43 prevents the second constant field from
being resent.
3. When the user is to enter the quantity for another item, the program issues
another output operation. The attributes for the fields QTY, ITEM, COLOR,
SHAPE, and SIZE are sent to the display. Field selection prevents the
CHOICE field from being sent to the display.
At least one field, in this case QTY, must be kept to prevent the entire record
area from being erased.
4. If the user enters a quantity, color, shape, or size that is not valid, indicator 44
is set on so that the input fields (QTY, COLOR, SHAPE, and SIZE) are not
erased and so that the output field CHOICE is sent to the display. In addition,
the appropriate indicator, 9, 10, 11, or 12, is set on so that the input field in
error blinks and the cursor position is below the field. (The CHOICE field would
show the user valid choices for the field in error.)
5. The CHOICE field and a constant field of blanks are defined for the same
location. After the user enters valid data, indicator 15 is set on, indicator 44 is
set off, and the constant field initializes the CHOICE field to all blanks.

Deferring the Write Operation Until a Read Request is Made
The DFRWRT parameter on the Create Display File (CRTDSPF) or Change
Display File (CHGDSPF) command allows you to specify how the system is to
handle write operations. If you specify DFRWRT(*NO), the program does not
regain control until the write operation has displayed the data and updated the
input/output feedback area.
If you specify the default of DFRWRT(*YES) for the file, the program regains
control after the output record is processed. The program can then use the record
area where the output was stored to start processing the next write or write-read
operation. The data is actually sent to the display only when a read or write-read
operation is issued or when the FRCDTA DDS keyword is in effect for a write-only
operation.
Using DFRWRT(*YES) on a display file improves systems performance; however,

DFRWRT(*YES) should not be used in the following circumstances:
If you want to find out immediately if the write operation was successful. An
error associated with a write operation for a file with DFRWRT(*YES) specified
is issued only when the data is actually sent to the display.
If the time between the write operation and the read or write-read is long. For
example, if the program does several database operations after the write oper-
ation (before it issues a read or write-read operation), the user will not see the
data while the database operations are performed.
If the file is closed after the write-only operation and the KEEP keyword is not
specified. If the display file has the DDS keyword KEEP specified in any of its
records, the data accumulated from the write-only operation is displayed when
the file is closed. However, if the KEEP keyword is not specified, the data may
never be displayed.
The DFRWRT parameter has no effect on the following:

Write operations using user-defined data streams
Write operations to display files that use program-described data
Record formats for which the FRCDTA DDS keyword is in effect
Specifying Default Values for Fields

Both DFT and DFTVAL keywords are used to specify the default values to be dis-
played for fields. However, there are differences between the way the two are
used.
The DFT keyword can be used with constant, input, output, and output/input fields
and cannot be optioned. When it is used with output or output/input fields the
OVRDTA and PUTOVR keywords must also be specified. If the record is not on
the display, this combination of keywords will cause the default value to be placed
on the screen. If the record is already on the display, the PUTOVR keyword is in
effect and the data from the program appears on the display rather than the default
value.
The DFTVAL keyword can be used only on output and output/input fields and can
be optioned. If it is in effect on an output operation, the value from the keyword is
placed in the field, rather than the value from the program. If the record is on the
display and the PUTOVR and OVRDTA keywords are in effect, the program value
is used rather than the default value.

The DFT and DFTVAL keywords may not be specified on the same field.
Indicating Which Mode to Display Records

Some display stations, for example the 3180-2 display station, support an alternate
screen size. You can specify this alternate size using the DSPMOD keyword. The
DSPMOD keyword indicates, for a particular record, which mode is used to display
the record. Any record that does not have the DSPMOD keyword specified for it is
displayed in the default display mode. The default display mode is the first of the
*DS3 or *DS4 display sizes on the DSPSIZ keyword.
The DSPMOD keyword is only valid when both *DS3 and *DS4 are specified on the
DSPSIZ keyword. This keyword is valid only at the record level. Option indicators
are allowed. The DSPMOD keyword may not be duplicated in a record.
Note: The capability to display in 27 by 132 mode is allowed on 3180-2, 3197,
3477 Models FA, FC, FD, FE, FG, FW, and 3487 Models HE, HD, HW, HC
display stations attached to a local display station controller, or remotely
attached to a 5294 or 5394 controller. The DSPMOD keyword is ignored
unless these controllers are used.
For example, the following DDS would display RECORD1 in 27 by 132 mode, and
RECORD2 in 24 by 80 mode (the default mode set up by the DSPSIZ keyword).
RECORD3 will be displayed in 27 by 132 mode if option indicator 03 is on, or in 24
by 80 mode if option indicator 03 is not on.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A DSPSIZ(\DS3 \DS4)
A R RECORD1 DSPMOD(\DS4)
A R RECORD2
A R RECORD3
A ð3 DSPMOD(\DS4)
Figure 3-11. Sample DDS Source Showing Use of the DSPMOD Keyword
The use of the DSPMOD keyword can cause the display mode to be changed dra-
matically. Caution should be used when specifying the DSPMOD keyword. When
a record with DSPMOD active causes the mode to be changed, all records cur-
rently on the display are cleared and deleted from the active record table. The
record with DSPMOD active is then sent to the display. The mode for this record is
maintained on the display as long as the DSPMOD keyword is active. Setting
DSPMOD off or a write operation to another record without DSPMOD causes the
display mode to be placed back in the primary display screen size for the display
station.
Using the previous sample DDS source, the DSPMOD keyword gives the following
results if records are written to the screen in the following order:
RECORD1 is displayed in *DS4 mode.
The display screen is cleared and RECORD2 is displayed in *DS3 mode.
If indicator 03 is off, RECORD3 is displayed in *DS3 mode. RECORD2
remains on the display if the OVERLAY keyword is specified.
If indicator 03 is on, RECORD2 is cleared and RECORD3 is displayed in *DS4
mode.

Note: When changing display modes, the displayed subfile data is removed from
the display. However, the subfile data is not cleared from the subfile table.
The following keywords are ignored if the display modes have changed:
Table 3-5. Keywords Ignored If Display Modes Are Changed

Keywords Additional Information
ALWROL When a record is not on the screen, it cannot be rolled.
ASSUME The records with the ASSUME keyword remain on the screen
when the file is opened. When the display modes change, the
records on the screen are cleared. This is similar to specifying
the ASSUME keyword without the OVERLAY keyword. The
display size of the file with the KEEP keyword must equal the
display size of the file with the ASSUME keyword.
CLRL All lines will be cleared by a change in display mode.
ERASEINP/INZINP When the display modes change, the record is displayed with
ERRMSG PUTOVR not in effect, even if the record was on the screen
ERRMSGID before the display modes changed.
KEEP
OVERLAY
PROTECT
PUTOVR
PUTRETAIN –
SFLMSG
SFLMSGID
Positioning the Cursor after an Output Operation

You can specify where you want the cursor positioned after an output operation by
using the CSRLOC or DSPATR(PC) keyword.
On the record-level keyword CSRLOC, you can specify the names of two 3-byte
zoned decimal hidden fields that contain the exact line and position for the cursor
location. With the CSRLOC keyword, you can position the cursor outside the
record you are displaying.
The field-level keyword DSPATR(PC) positions the cursor at the first position of the
field after the record is written. However, if the OVERLAY keyword is specified at
the record level, the cursor position may be lost after subsequent write operations.
Note: The cursor is not positioned if the keyboard is unlocked before the output
operation.
If both the CSRLOC and DSPATR(PC) keywords are specified, the cursor is posi-
tioned by the CSRLOC keyword. If several fields have DSPATR(PC) keyword
specified, the cursor is positioned at the first field for which the DSPATR(PC)
keyword is specified.
If the CSRLOC and DSPATR(PC) keywords are not specified, the cursor is posi-
tioned at the first input-capable field on the display. If there is no input-capable
field, the cursor is positioned in the upper-left corner of the display. However, if the
CSRLOC and DSPATR(PC) keywords are not specified for records containing
input-capable fields, the cursor position may be lost if the record is suspended and
then restored. For example, the cursor position may be lost if the F1 (Help) key is
pressed after the record is displayed.

Other DDS functions can affect the write operation. For a write operation to a user-
defined data stream (USRDFN keyword), the functions performed are determined
by the user-supplied controls.
Returning the Cursor Position to an Application

You can determine where the cursor was positioned on input by using the
RTNCSRLOC (return cursor location) keyword.
This keyword may be specified in either of two formats:

Return the name of the record and field in which the cursor is currently posi-
tioned. Optionally, a third parameter may be specified that will contain the rela-
tive cursor position within the field.
Return the row and column position of the cursor relative to the display.
Optionally, two additional parameters return either of the following:
– The row and column position of the cursor relative to the active window (if
one exists)
– The location of the cursor at the beginning of a two event mouse button
call.
The parameters of these formats are described in the DDS Reference.
Returning the Cursor Position Within a Subfile to an Application

On input, you can determine where the cursor is located in a subfile by using the
SFLCSRRRN (subfile cursor relative record number) keyword. The relative record
number on which the cursor is positioned is returned in the hidden field specified as
the parameter on the keyword. The field must be defined in the record format as a
signed numeric (S in position 35) with a length of 5 with zero decimal places. Also,
it must be a hidden field (H in position 38).
Returning the Mode of a Subfile to an Application

You can use the SFLMODE (subfile mode) keyword to determine whether the
subfile was in folded or truncated mode on input. The mode parameter is required.
The SFLMODE keyword is only valid for subfile control records and the SFLCTL
keyword must be specified.
The field specified for the mode parameter is defined in the record format as a 1
character (A in position 35) hidden field (H in position 38). The field is returned
with a value of 0 if the subfile is folded and with a value of 1 if the subfile is trun-
cated. If SFLDROP (subfile drop) or SFLFOLD (subfile fold) is not specified on the
SFLCTL (subfile control) record, the value is always returned as 0.
Initializing Output/Input Fields

Device support saves all data read from input-capable fields for records currently
on the display in a save area. The output/input fields within this save area are
updated on output operations.
For output operations, the following happens:

Input-only fields are initialized to zeros (numeric fields), blanks (character
fields), or a default value (DFT keyword) from the display file.
Output/input fields, hidden fields, and program-to-system fields are initialized to
the contents of the output buffer. If this output operation is caused by the ini-
tialize record function (INZRCD keyword), no output buffer is available.

Output/input fields and hidden fields are initialized similar to input-only fields.
Output/input fields are input and output capable.
Output-only fields are not part of the input buffer unless they are part of a
subfile record, in which case they are saved as if they were output/input fields.
All response indicators for this record are set off.
Note: For input-capable fields, if the PUTRETAIN or ERASEINP keyword is in
effect, the save area for the field remains unchanged.
Neither the input nor the output buffer is changed during write operations.
Inviting Input to the Display

The invite operation is used to send a request for input to a display station and
return to the program without waiting for the input to arrive. This allows a program
to request input from one or more display stations but continue processing without
waiting for any of the display stations to respond. When the program is ready to
process the input, the data can be received from any of the invited display stations
by performing a read-from-invited-devices operation.
The invite operation is done by performing a write operation using a record format
with the INVITE DDS keyword in effect. Refer to the appropriate high-level lan-
guage manual to determine how to perform a write operation and how to use indi-
cators to control the INVITE DDS keyword.
Once a display station is invited, the valid operations to receive data from the
display station are the read-from-invited-devices operation and the read(wait) oper-
ation directed to a specific display station. Cancel invite is also a valid operation to
an invited display station.
Before a display station can be used for I/O operations in a multiple-device display
file, it must be acquired to the file. A program can direct the invite operation to any
display station currently acquired for the file.
If the multiple-device display file was created with DFRWRT(*YES) specified, an

output operation with the INVITE DDS keyword optioned on will cause the output
that has been postponed to be displayed on the screen before the display station is
invited.
If you want to invite a display station but have no data to send to it, perform the
output operation with a record format which contains the INVITE DDS keyword
optioned on but has no output-capable fields.
Multiple-display station display files are supported in ILE RPG*, ILE COBOL*, ILE
C*, and CL.
Inviting Input from CL Programs: The invite operation is available directly to CL

programs through CL commands:
WAIT(*NO) on RCVF and SNDRCVF Commands:
WAIT(*NO) allows overlapping of I/O operations and the running program,
requests for input from more than one display, and receiving input as it is avail-
able. This provides support equivalent to the invite operation.
On a read operation with the no-wait option, the system sends the request to
the display and returns to the program. However, the requested record is not

available when control returns. The purpose of this operation is to make the
display station eligible to send input data while the program performs other
work.
To retrieve the record, issue a WAIT command. The WAIT command issues a
read-from-invited-devices operation. The program waits until data is available
from the display station or the WAITRCD time elapses. Then, the display
station name and any input data are passed to the user program. If more than
one read-with-no-wait operation has been issued (each to a different display)
and more than one completes, the WAIT command processes only the first
read-with-no-wait operation that is completed.
A WAIT command can be issued to process each of the other read-with-no-wait
operations. They are processed in the order of completion.
When a record containing the INVITE keyword is sent to the display, the opera-
tion is handled as a write-read operation with a no-wait option. The INVITE
DDS keyword is ignored on the write-read operation.
A write-read operation with a no-wait option is the same as a write followed by
a read-with-no-wait.
ENDRCV Command:
The ENDRCV command is used to end a request for input made with the
WAIT(*NO) option. The ENDRCV command ends the input request even if
data is available from the display station. If data is being sent by the display
station when the ENDRCV operation is performed, the data is lost. If the
display station is not invited, the application program is signaled with an error.
Reading Invited Input from the Display

The read-from-invited-devices operation provides a means of waiting for and
receiving data from any one of the invited display stations. This method of inviting
a display station and then reading from the invited display station is useful when
the application must control the amount of time spent waiting for the user to
respond. When the read-from-invited-devices operation is performed, the program
waits for the time interval specified on the WAITRCD keyword of the CRTDSPF,
CHGDSPF, or the OVRDSPF command. The wait can be ended in the following
ways:
Data becomes available from an invited display station. The display station
name, the results of the operation, and any input data are passed to the
program. When data has been received, the display station is no longer invited
and must be invited again by an invite operation if more data is to be received
from the display station by a read-from-invited-devices operation.
No-display station-invited signal. Indicates that none of the display stations
associated with the file are in the invited condition. Refer to the appropriate
high-level language manual for information on how this will be communicated to
the program.
Job-ended-controlled signal. Indicates that the job that the program is running
in is being ended with the controlled option through the End Job (ENDJOB),
End System (ENDSYS), Power Down System (PWRDWNSYS), or End Sub-
system (ENDSBS) command. Refer to the appropriate high-level language
manual for information on how this will be communicated to the program. This
occurs only once in a process no matter how many multiple-device display files
are in use. All invited display stations remain invited.

No-invited-devices-have-data-available signal. This occurs when no display
stations associated with the file have data available, the WAITRCD time is
*IMMED, and none of the previous conditions apply. The invited display
stations remain invited. Refer to the appropriate high-level language manual
for information on how this will be communicated to the program.
Time-out-on-wait-for-data-from-invited-devices signal. This occurs when the
WAITRCD value is a finite number of seconds, no data became available
during that interval, and none of the previous conditions apply. Refer to the
appropriate high-level language manual for information on how this will be com-
municated to the program. The invited display stations remain invited.
Also, ILE COBOL provides a means of performing the read-from-invited-devices

operation as if WAITRCD(*IMMED) had been specified. See the ILE COBOL
books for information on the NODATA phrase and its effect on the read-from-
invited-devices operation.
Understanding the Read-From-Invited-Devices

When the program is ready to process input from one of the invited display
stations, it can issue a read-from-invited-devices operation. This operation waits for
a specified time for input to arrive from one of the invited display stations. The time
limit can be specified when the display file is created and can subsequently be
changed or overridden. If no invited display stations respond within the time limit,
the program receives an indication that the time limit expired and can continue pro-
cessing. If an invited display station responds within the time limit, the program can
determine which display station responded and the record format used to process
the data. The other invited display stations remain invited and can be sending
data. The responding display station can also be invited again by another invite
operation.
A read operation can also be directed to a specific display station. This operation
will not complete until the specified display station responds with data. The display
station need not be invited for the read operation, but, if it is, the program will wait
for input and the display station is no longer invited.
The read-from-invited-devices operation only accepts data from display stations
which are currently invited.
If more than one display station acquired to the display file has an invite out-
standing, a read-from-invited-devices operation will return the next available
record from one of the invited display stations. If records are received from
more than one display station before the read-from-invited-devices operation,
the other records will be kept for a subsequent read-from-invited-devices opera-
tion or for a subsequent read(wait) operation directed to a specific display
station.
When a display station has responded and the input is received by the read-
from-invited-devices operation, that display station is no longer invited. It can
be invited again by another invite operation but this should not be done until all
the record formats on the display with input-capable fields have been read.
A record format cannot be specified on the read-from-invited-devices operation.
The record format returned from a display is the same as the last record format
written to the display station.
The timing function associated with the WAITRCD parameter may not force an
end to the wait if the system is processing the Help key. In the following

cases, the read-from-invited-devices function will not end until the user exits
from the help information:
– The system is displaying help that is defined by H specifications in the DDS
for the display file.
– The system is displaying help for a message when the display station is the
requester display station for the job and the display file specifies
MAXDEV(1).
You can force message help to end when the WAITRCD time ends by speci-
fying a value greater than 1 for the MAXDEV parameter on the CRTDSPF or
CHGDSPF command.
Reading-From-Invited-Devices from CL Programs: The read-from-invited-

devices operation is available directly to CL programs through CL commands. To
retrieve the record, issue a WAIT command. The WAIT command issues a read-
from-invited-devices operation. The program waits until data is available from the
display station or the WAITRCD time elapses. Then, the display station name and
any input data are passed to the user program. If more than one read-with-no-wait
operation has been issued (each to a different display) and more than one com-
pletes, the WAIT command processes only the first read-with-no-wait operation that
is completed.
A WAIT command can be issued to process each of the other read-with-no-wait

operations. They are processed in the order of completion.
When a record containing the INVITE keyword is sent to the display, the operation
is handled as a write-read operation with a no-wait option. The INVITE DDS
keyword is ignored on the write-read operation.
A write-read operation with a no-wait option is the same as a write followed by a

read-with-no-wait.
Reading Input from the Display

A read operation passes a record from the system to the program. The display
file record format contains the information necessary for the system to handle the
record. The user must perform a required action such as pressing the Enter key or
a function key to pass the data to the system. The read operation results in the
following:

Read Operation
Program
HELLO
.
.
.
.
.
Returns data
to program
Unlocks
keyboard Locks keyboard
(If locked) after user action RV2W011-2
For input operations, the following happens in the order given:

1. For an input-only operation, all response indicators for this record are set off
and the read operation is issued.
2. Character fields received from the display are right- or left-justified and padded
with blanks or truncated as necessary. The default is left-justify, which can be
overridden using the AUTO or CHECK keyword.
3. Numeric fields received from the display have the following done to them:
a. If the field is negative, the zone portion of the units position is set to a D
(see “Handling Negative Numeric Input Data” on page 3-40).
b. All nonnumeric characters are removed and the numeric characters are
compressed.
c. Signed numeric fields are right-justified and numeric-only fields are decimal
aligned.
d. The field is padded with zeros or truncated as necessary.
e. Field validation is performed.
All fields received from the display whether they are part of the selected record or
not are handled in this way.
If any field validation errors are detected, a message is sent to the user so that the
error can be corrected. This process is repeated until there are no longer any
errors. The save area for the requested record is then copied into the input buffer.
Note: To process input data for a read operation with no record format name,
display station support uses the last record written to the display that con-
tains at least one of the following:
Input-only fields
Output/input fields
Hidden fields
If no such format is on the display, display station support uses the last
format written to the display that did not contain these kinds of fields, for
example, an output-only record that specifies valid command keys. If no
such record exists on the display, an error message is returned to the
program.

A record does not have to be written to the display before it can be read by the
program with the INZRCD keyword. The system does this the same way an appli-
cation program performs an output operation with the exception of the following:
For an output-only field, no user data is available so the field is initialized to
blanks. If the field is edited, the editing is ignored. If the BLKFOLD keyword is
specified, it is ignored.
For an output/input field, no user data is available so the field is initialized to
blanks. If the field is edited, the editing is ignored. The field actually contains
null characters (hexadecimal zeros), which appear as blanks.
For a constant or input-only field, the data does not normally come from the
output buffer so the field appears the same as when the program displays it
using a write operation.
For a hidden field, the field is returned on a read operation as blanks (hex 40) if
the field is a character field or zeros (hex F0) if the field is a numeric field.
For a message, there is no message data so the field is ignored.
The LOGOUT keyword is ignored.
The ERRMSG and ERRMSGID keywords are ignored because the record is
not already on the display.
The SFLMSG and SFLMSGID keywords are ignored.
All other fields or keywords are processed as if they were selected on an output
operation.
Unlocking the Keyboard while the Program Is Processing Data

The keyboard can be unlocked so that data can be entered into input fields while
the program is processing previously entered input data with the UNLOCK keyword.
Normally, input fields are not erased until after the keyboard is unlocked. On a
read operation, input fields are erased after the keyboard is unlocked only if the
UNLOCK keyword is specified and the GETRETAIN keyword is not specified.
For the 5250 display station, the read operation with the UNLOCK keyword in effect
results in the following:
1. The 5250 display station does a hardware validity check on the fields. If no
errors are found, the following is done:
a. If the UNLOCK keyword is specified without the GETRETAIN keyword or if
the UNLOCK(*ERASE) keyword is specified, all input-capable fields that
are changed are cleared.
b. If the UNLOCK keyword is specified with the GETRETAIN keyword or if the
UNLOCK(*MDTOFF) keyword is specified, all modified data tags (MDTs)
are reset.
c. If the UNLOCK(*ERASE *MDTOFF) keyword is specified, all input-capable
fields that are changed are cleared and their MDTs are reset.
d. The cursor is repositioned to the field where the user can enter the next
record.
e. The keyboard is unlocked.
2. The system validity checks all the fields for all records on the display. If errors
are detected, normal error retry is performed. A user could be typing into the
next record when an error message is displayed.
Note: The error message could refer to data that is no longer on the display
because the data was erased.

3. Control returns to the program.
Notes:
1. If an application program detects input errors and sends error messages to the
display, the messages may refer to input that has been typed over.
2. If the CHANGE keyword is specified and either the UNLOCK keyword is speci-
fied without the GETRETAIN keyword or with the UNLOCK(*ERASE) keyword
is specified, the associated response indicator is set on for the next input
record.
3. When a read operation with the UNLOCK keyword (and without the
GETRETAIN keyword) or the UNLOCK(*ERASE) keyword is used for a record
while a subfile is on the screen, subfile records may be returned to the program
on a subsequent get-next-changed operation to the subfile even though the
user did not enter data into the subfile record. It is recommended that you use
the UNLOCK(*ERASE *MDTOFF) keyword instead of the UNLOCK keyword
(without the GETRETAIN keyword) or the UNLOCK(*ERASE) keyword. If you
must use either of the latter, you should make sure that your high-level lan-
guage program compares for blanks to handle the possibility that an unmodified
field containing all blanks is returned to the program.
Keeping Input Data

Input data on a display can be kept after the user presses the Enter key with the
GETRETAIN keyword. The GETRETAIN keyword can only be used with the
UNLOCK keyword.
Setting an Indicator When Data Is Changed

A response indicator can be set on when data is entered into an input field or when
data is changed in an output/input field with the CHANGE keyword.
Initializing Records and Unlocking the Keyboard–Diagram

The following diagram shows the effect of INZRCD and UNLOCK keywords on an
input operation:
Before After
B Not Used
Get A
with INZRCD
D A
C Not Used
Get E
with INZRCD Not Used
and UNLOCK
E
Not Used
RV2W033-1
Note: Record formats A, D, and E occupy the same lines.

.1/ Record formats B, D, and C are erased if the OVERLAY keyword is not speci-
fied for record format A. Record format A is displayed with constants and ini-
tialized input fields. The keyboard is unlocked. The keyboard is locked after
the user satisfies the get operation.
.2/ Record formats B, D, and C are erased if the OVERLAY keyword is not speci-
fied for record format E. Record format E is displayed with constants and ini-
tialized input fields. The keyboard is unlocked. After the user satisfies the
read operation, the contents of the input fields are erased and the keyboard is
unlocked again.
Note: Even though the UNLOCK keyword is specified, field validity checking, if
specified, and command key verification are performed. Therefore, a user
could be typing into the next record when an error message is sent to the
display.
Specifying Validity-Checking Functions

Two methods can be used to check the validity of data entered by the user:
Have the system check the data before it is passed to the application program.
Have all the input data passed to the application program, which checks the
validity of the data.
In either case, if errors are detected, a message is displayed informing the user of
the error so that it can be corrected. If you choose the second method for
detecting errors, see “Creating and Displaying Your Own Messages” on page 8-1
for information on how your program can display error messages. The rest of this
section gives more information on the first method, when the system detects the
errors before passing the data to your program.
The validity-checking functions you can specify in DDS are:

Detecting fields in which at least one character must be entered (CHECK(ME)
keyword). Blanks are valid characters. This is referred to as mandatory enter.
Detecting fields in which every position must contain a character (CHECK(MF)
keyword). Blanks are valid characters. This is referred to as mandatory fill.
Detecting incorrect data types where character, numeric, or signed numeric
data is required.
Detecting data that is not in the range specified for the field (RANGE keyword).
Performing comparison checking between data entered and specified constant
value (COMP keyword).
Comparing the data entered to a specific list of valid entries (VALUES
keyword).
Detecting if a valid field or record name was entered in a character field
(CHECK(VN) keyword).
Detecting if a valid object name was entered in a character field (CHECK(VNE)
keyword).
Performing modulus 10 or 11 check digit verification (CHECK(M10) or
CHECK(M11) keyword). (Only one can be specified.)
Allowing blank-key entries to be processed as if no entry had been made
(CHECK(AB) keyword). CHECK(AB)–Allow Blanks–is ignored if the subfile
keyword SFLROLVAL or SFLRCDNBR is also specified for the field.
Detecting if a space, a plus sign, or a minus sign is embedded between
numeric digits in a numeric field. Also, detecting if a plus sign or minus sign
precede a numeric digit in a numeric field. To detect such cases, use the Vali-
date Numeric (VALNUM) keyword.

The ERRSFL keyword can be used in addition to the validity checking keywords
CHECK(M10 M11 VN VNE), COMP, RANGE, and VALUES to allow more than one
of the error messages associated with the keywords to be displayed at one time.
When you specify the RANGE, COMP/CMP, VALUES, CHECK(VN), CHECK(VNE),

CHECK(M10), or CHECK(M11) keyword for validity checking and an error is
detected by one of these validity checking functions, the following happens:
1. The keyboard is locked.
2. All fields in error are displayed in reverse image. If a field in error has both the
underline (UL) display attribute and the highlight attribute (HI), its image is not
reversed, as this combination of attributes has the same effect as
DSPATR(ND).
3. The cursor is positioned at the beginning of the first field in error.
4. A system-supplied error message for the first field in error is displayed on the
error line,
or,
If you have chosen to provide your own error message for a field using the
CHKMSGID keyword and this is the first field in error, then your error message
is displayed on the error line.
If your controller is installed with the self-check feature (see the 5250 Functions
Reference), the controller performs validity checking for the CHECK(M10F) and
CHECK(M11F) keywords. Errors are detected when you attempt to move the
cursor from the input field rather than when you press the Enter key or a Command
Attention key. The Operator Error Code ðð115, rather than a system-supplied or
user-specified message, is displayed in the lower left corner of the display. If the
USRDSPMGT keyword is also specified, CHECK(M10) and CHECK(M11) function
as CHECK(M10F) and CHECK(M11F).
If the RANGE, COMP, VALUES, CHECK(VN), or CHECK(VNE) keyword is speci-

fied for a field, and data is entered into that field, the field indicates that it has been
changed regardless of attempts by the user to restore the field after an error. If
blanks (for character fields) or zeros (for numeric fields) will fail the validity checking
function, use the CHECK(AB) keyword. This will satisfy the validity checking func-
tion.
When you specify validity checking for records that are part of a subfile, each field
in the record is validity checked before it is placed in the subfile from the display.
You cannot roll the records until all fields in error are corrected.
The system only performs validity checking on a field if the field is changed by the
user or if its modified data tag (MDT) is set on using DSPATR(MDT).
Notes:
1. If the user presses the Dup key, any validity checking for a field is ignored.
The DUP keyword lets the user use the Dup key.
2. The value for a numeric field for which the COMP, VALUES, or RANGE
keyword is specified is aligned based on the decimal positions specified for the
field and filled with zeros where necessary. If decimal positions were not
entered for the field, the decimal point is assumed to be to the right of the digit
to the extreme right in the value. For example, for a numeric field with length

of 5 and decimal positions of 2, the value 1.2 is interpreted as 001.20 and the
value 100 is interpreted as 100.00.
3. When you use the RANGE keyword for validity checking an input field and
blanks are entered in the input field, the value for the input field may not meet
the range requirements. Blanks are converted to zeros for numeric fields and
are passed as blanks for character fields. Use the field level keyword BLANKS
to determine when a field is displayed as all blanks. The response indicator on
the BLANKS keyword is set on if the user enters blanks.
Understanding the Limitations on the Number of Input-Capable

Fields
For a remote 5250 display station (a display station attached through a remote con-
troller), you can specify as many as 126 or 256 input fields on one display,
depending on the controller model. (The 5294 controller supports 126 input fields;
the 5394 controller supports 256 input fields.) Additionally, if either DSPATR(OID)
or DSPATR(SP) is specified, this maximum is reduced by 1 for each three
instances of these keywords. If fewer than three instances occur, it is still reduced
by one.
For a local 5250 display station (a display station attached through the local display
station controller), you can specify as many as 256 input fields. Also, if either
DSPATR(OID) or DSPATR(SP) is specified, this maximum is reduced by 1 for each
three instances of these keywords. In addition, any use of the magnetic stripe
reader on a local 5250 display station also reduces the maximum number of fields.
The maximum number of fields is calculated as follows:
256 - 3+B A rounded up to the next whole number

+
6 3
RSLH131-2
A is the number of DSPATR(OID) and DSPATR(SP) fields on the display and B is

the length of the longest expected magnetic stripe input where 125 data characters
is the maximum allowed. Magnetic stripe data not specified as DSPATR(OID) can
be entered into any input field.
If the maximum number of input fields is exceeded in any of the preceding cases,
message CPF5192 is issued to the using program.
No maximum-number-of-fields diagnostic is provided during display file creation

because the number of fields and record formats is not known until the program is
run.
When a subfile record is displayed, the actual number of input-capable fields sent
to the display is the number defined in the record multiplied by the number of
subfile records that are displayed.
For remotely attached 3270 displays, the limitation is 126 input fields.
For ASCII displays attached through a protocol converter, the limitations are the
same as the controller to which they are attached.

Handling Negative Numeric Input Data
The negative sign in numeric input data can appear in three forms:
Hex 60 if the sign is entered using the - (minus) key
Hex D if the sign is entered using the Field Minus key
Hex Dn if the sign is entered as an alphanumeric character with a D zone
The hex 60 is treated as a true minus sign if it is to the right of the least significant
digit.
The hex D zone is treated as a minus sign if it is the least significant digit. In
addition, it is treated as a significant digit with a value equal to the numeric portion.
Imbedded blanks (between significant digits) are changed to zeros before decimal
alignment.
Understanding How the System Reads Input from the Display

When a read operation is issued, the system reads all the records on a display.
However, only one record is passed to the program for each read operation. The
system saves all the other records in anticipation of more read operations.
If each read operation refers to a different record on the display, no action is

required of the user. However, if each read refers not to a different record on the
display but to the same record and if the RTNDTA keyword is not specified, the
user must perform an action such as pressing the Enter key or a CFnn key to start
the next read operation because each record entered is passed to the program only
once. If the RTNDTA keyword is specified, the user does not have to perform any
action because the same input buffer that was returned to the program on the pre-
vious read operation for the record is returned again.
The system saves the contents of input-capable fields for records that are active on
the display. This saved data is passed to the user program and can be altered by:
Initializing the data with a constant on a write operation. A field can be initial-
ized with the value specified in a DFT keyword.
Entering data through directly typing the data in or using a light pen to select
data. (The MDT for a field can be set on to simulate user input.)
Entering data from a program on a write operation. This applies to output/input
fields (and output-only fields for subfiles).
Initializing the data with blanks (character fields) or zeros (numeric fields) on an
output operation for the same record unless the PUTRETAIN keyword is speci-
fied. This applies to input-only fields.
Writing Output and Reading Input at the Same Time

The write-read operation is a combination of a write operation and a read operation
to the same record format in one high-level language statement like the SNDRCVF
command in a CL program. It behaves as if you had specified a read operation
immediately following a write operation.
Some high-level languages have a write-read operation which writes information on

the display and reads the user response in one statement. For example, ILE RPG
has the execute format (EXFMT) operation. This kind of operation is useful if you
need to both present new information on the display and request information from
the user at the same time. You can also use a write operation followed by a read

operation to the same record format to simulate this operation in languages that do
not support a combined write-read operation.
When this operation is performed, the following happens:

1. The program calls the system display support giving it the data to show on the
display and the record format to use when writing and reading that data.
2. The system combines that data with the information it finds in the record format
and constructs the data stream to be sent to the display.
3. The data stream is then sent to the display and the keyboard is unlocked.
4. The user types the data in the fields which allow input and presses the Enter
key or some other function key.
5. The data is then sent from the display to the system. The system decodes it
and extracts only the information that the application program needs to know
and returns that data to the application program.
When you work with only one record format, this write-read style of working with it
is the most common. On the write portion of the operation, you provide the data
that the user will see. On the read portion, you receive data back that the user has
entered or changed.
Canceling Input That Was Not Waited For

The cancel-invite operation is used to cancel the input request issued to a display
station that was previously invited through the invite operation. The input request is
canceled by performing a write operation to the invited display station. One of the
following occurs:
If the write request is received before the user responds to the input request
from the invite operation, the input request is canceled and the record format
specified on the write operation is sent to the display station. If the record
format has the option indicator set on for the DDS keyword INVITE, the display
station is invited again.
If the write request is received after the user responds to the input request from
the invite operation, the input request is not canceled and the write operation
fails. The read-from-invited-devices operation or a read(wait) operation must be
issued to receive the available data.
Releasing a display station also implicitly cancels any input requests directed to the
display station. If the display station has data available, the data is lost.
Locking the Keyboard and Positioning the Cursor During I/O

Operations
The following lists what happens to the keyboard when a write, write-read, or read
operation is run:
Operation Keyboard
Write The keyboard is unlocked by default. If the LOCK keyword is
specified, the keyboard is not unlocked.
Write-Read The keyboard is unlocked.

Operation Keyboard
Read The keyboard is unlocked (if locked) before display station user
action. After user action, the keyboard is locked by default. If the
UNLOCK keyword is specified, the keyboard is left unlocked.
Every time the keyboard is unlocked, the cursor is repositioned. In some cases,
many write operations between read operations can cause erratic cursor move-
ment. If the user starts typing before the last write operation, the cursor is reposi-
tioned when the keyboard is unlocked and this can cause confusion for the user.
You can prevent this by using the LOCK keyword. By using the LOCK keyword on
each write operation but the last, the keyboard remains locked until the last write
operation. This avoids erratic cursor movement, but prevents the user from starting
to type data.
Normally, a user action, such as pressing a valid command key, locks the key-
board.
To specify that the system unlock of the keyboard on the next input operation
should not occur, specify the retain lock status (RETLCKSTS) keyword. This
keyword prevents the loss of data when the input operation is started and data is
already being transmitted from the keyboard.
Note: Use the RETLCKSTS keyword only when the keyboard is already unlocked.
To position the cursor with the DSPATR(PC), CSRLOC, or

SFLRCDNBR(CURSOR) keyword, the keyboard must be locked. Only the fol-
lowing conditions on an output operation cause the keyboard to be locked and must
be present for the display station to position the cursor. (An output operation
normally unlocks the keyboard before it ends unless the LOCK keyword is specified
so these conditions lock the keyboard only momentarily.)
Input-capable fields are erased (ERASEINP keyword).
Modified data tags are reset (MDTOFF keyword).
Any input-capable field is written to the display.
The complete display is erased (a write operation without an OVERLAY
keyword).
The 5250 format buffer is reset, which can be the result of:
– A record format with an input-capable field is overlaid or erased.
– A record format with a cursor location specification is overlaid or erased.
– The PROTECT keyword is specified on the record being written.
For the cursor positioning keyword to take effect, the keyboard must go from the
lock condition to an unlocked condition. That is, if the keyboard is unlocked prior to
the write operation, the cursor positioning keyword does not take effect immediately
on the write operation. However, there is one exception. If the keyboard is tempo-
rarily locked during an output operation, the cursor positioning keyword will be in
effect if the output operation unlocked the keyboard at the end.
In addition, if any of the preceding conditions happens on a write operation, the

keyboard must be unlocked before any user action either by the same operation or
by a following operation (it should be the last write operation).
A write operation to a subfile never unlocks the keyboard because no input or

output is sent to the display station.

Saving Previously Displayed Information
A display file may be opened to a display station even when another display file is
already using that display station. When an I/O operation is performed to the
second display file, the first display file is suspended.
When a display file is suspended, the information on the display can be saved
automatically by the system if you specify *YES for the RSTDSP parameter on the
Create Display File (CRTDSPF) or Change Display File (CHGDSPF) command.
The contents of a display file can then be restored when an I/O operation is later
performed to that display file. If *NO is specified for the RSTDSP parameter, the
application program needs to rewrite the display to show it again.
The RSTDSP parameter lets you overlap a program call, keyboard input, and file
I/O processing, as shown in the following example:
Display File
Program 1
DSPFILY
Write . . . . . . . . .
Write . . . . . . . . .
RCD Y1
Read . . . . . . . . . .
Display File
DSPFILX
RCD X1
RV2W046-0
.1/ Program 1 issues a write operation to record format RCD Y1 in display file
DSPFILY, which activates display file DSPFILY.
.2/ Program 1 issues a write operation to record format RCD X1 in display file
DSPFILX, which suspends display file DSPFILY and activates display file
DSPFILX. If RSTDSP(*YES) is specified for display file DSPFILY, the data
displayed on the display station is saved. If RSTDSP(*NO) is specified
instead, the data is lost and the program needs to write the information in RCD
Y1 again to show it.
.3/ Program 1 issues a read operation to record format RCD Y1, which suspends
display file DSPFILX and restores display file DSPFILY. If the RSTDSP(*YES)
parameter is specified for DSPFILY, then the data displayed on the display
station when DSPFILY is suspended can be restored.
When RSTDSP(*YES) is specified for a display file, and you are suspending and
restoring that display file because of operations to another display file, some dis-
plays may appear to flash on the screen briefly. If a display file has a record on
the display and an I/O operation is done to a second display file, the first file is
suspended and its screen contents are saved. When returning to the first display
file, the display file and its screen contents are restored. If a write operation is

done to a different record format in the display file, the restored display will flash
briefly before the output operation is complete. If you are going to completely
rewrite the display contents from your program when going back to the first file, use
RSTDSP(*NO).
You should specify *YES for the RSTDSP parameter in the following situations:
When you are writing a record that has the following keywords in effect:
– CLRL
– OVERLAY
– PUTOVR
– PUTRETAIN
– ERRMSG
– ERRMSGID
You must ensure that the records that are on the display are the records that
these keywords apply to. If the display file is suspended, the data must be
restored to the screen so that the write operations to the record formats that
use these keywords are valid.
When you perform multiple read operations to a record format on the display
without intervening write operations. If you should call a program while pro-
cessing the data that has been read and that program presents a display of its
own, the subsequent read operation done by your program restores the display
properly.
Saving and displaying data again requires significant system and data transmission
overhead. For a 1920-character 5250 display station, approximately 3000 charac-
ters are transmitted each time the display data is saved displayed again. To avoid
this overhead, write your application programs to do the following:
Make the programs in the application share the same copy of the display file
among themselves by specifying SHARE(*YES) on the display file.
Perform complete display rewrites each time the programs in the application
write to the display. A complete display rewrite occurs when a record is written
to the screen and the OVERLAY keyword is not used or implied.
Note: If complete display rewrites are not performed and if new input fields,
occupying positions on the screen above the currently displayed fields,
are sent to the display, the program receives a message (CPF5192).
This occurs because the 5250 display station requires that new input
fields sent to the display appear in lower positions than input fields cur-
rently on the display. In normal operations, data management performs
field processing to satisfy the 5250 requirement. See “Avoiding Record
Format Problems on the 5250 Display Station” on page 3-45.
When one program that uses a display file with the SHARE(*YES) parameter speci-
fied calls another program that uses the same display file, the display file is not
suspended even though both programs have opened the file. If the display file is
not shared, the system maintains separate copies of the display file for each
program and suspends and restores the display files separately.
Since system programs do not specify file sharing, you should specify
RSTDSP(*YES) on the CRTDSPF or CHGDSPF command if your program con-
tains a display file and calls system functions that present displays. System func-
tions that break into the normal path of an application, however, such as the

System Request Menu or the presentation of break messages, restore the display
without RSTDSP(*YES) specified.
To display saved display data again after a close operation is issued to a sus-
pended file, specify the KEEP keyword for a record format in the saved display
data.
Understanding the Effects of I/O Operations on Command Keys

Read and write operations may or may not affect how the function keys work:
A write or write-read operation for which no input or output is sent to the
display does not affect which keys are valid. Examples of such operations are
a write operation or an update operation to a subfile record format.
If a write or write-read operation displays a message by selecting either the
ERRMSG or ERRMSGID keyword, the command keys in effect on that output
operation are valid. Therefore, you can specify a different set of command
keys to be valid if an error occurs.
If only one subfile record format is displayed and the subfile control record
format specifies a CAnn or CFnn key for the SFLDROP keyword, that key
remains valid for that function as long as the subfile is still on the display. In
addition, the key specified for the SFLENTER keyword remains valid until
another write or write-read operation is done. At the next output operation, the
specifications for that record apply.
If two subfile record formats are displayed and both specify the SFLDROP
keyword, only the last SFLDROP keyword is used. There can only be one
drop key at a time.
Avoiding Record Format Problems on the 5250 Display Station

Because of the characteristics of the 5250 display stations, certain record format
positioning and operational combinations can produce undesirable results. The fol-
lowing example illustrates a combination that can cause undesirable results and
explains how to avoid these results.
The displays produced and the DDS for the record formats follow:

Enter all information regarding the subscriber:
Last name: First name: MI:
Street: Apt:
City: State: ZIP: -
DETAIL
record
format
CA1-Display state table, CA2-Display subscription table
RSLH166-0
Alabama AL Alaska AS Arkansas AK Arizona AK

California CA Delaware DE DST Columbia DC Florida DC STATES
Y-More state names, N-No more state names record
Enter all information regarding the subscriber: format
Last name: Doe First name: John MI:E
Street: 112 Elm Apt: 3A
City: Anytown State: ZIP: -
DETAIL
record
format
CA1-Display state table, CA2-Display subscription table
RV2W047-0

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R RCDA
A FLD1 1 I 2 4DSPATR(PC)
A\ STATES record format follows
A R STATES OVERLAY
A SNAME1 12 O 1 2
A SCODE1 2 O 1 15
A SNAME2 12 O 1 18
A SCODE2 2 O 1 31
A SNAME3 12 O 1 34
A SCODE3 2 O 1 47
A SNAME4 12 O 1 5ð
A SCODE4 2 O 1 63
A . .
A . .
A . .
A SNAME8 12 O 2 5ð
A SCODE8 2 O 2 63
A 3 2'Y-More state names, N-No more +
A state names'
A MORESNAM 1 I 3 48VALUES('Y' 'N')
A\ DETAIL record format follows
A R DETAIL OVERLAY CAð1(11) CAð2(12)
A 4 2'Enter all information regarding +
A the subscriber:'
A 5 1'Last name:' DSPATR(HI)
A NAMEL 2ð I 5 12
A 5 33'First name:' DSPATR(HI)
A NAMEF 13 I 5 45
A 5 59'MI:' DSPATR(HI)
A MI 1 I 5 63
A 6 1'Street:' DSPATR(HI)
A
A STREET 45 I 6 9
A 6 55'Apt:' DSPATR(HI)
A APT 4 I 6 6ð
A 7 1'City:' DSPATR(HI)
A CITY 15 I 7 7
A 7 23'State:' DSPATR(HI)
A SCODE 2 I 7 3ð
A 7 33'Zip:' DSPATR(HI)
A ZIP1 5 I 7 38
A 7 44'-'
A ZIP2 4 I 7 46
A . .
A . .
A . .
A 1ð 1'CA1-Display state table, +
A CA2-Display subscription table'
Figure 3-12. Sample DDS to Show Record Format Problems
Assume that the DETAIL record format is on the screen, and the user is entering
data for a subscriber. Because the user does not know the state code for the state
to be entered, he or she presses the CA01 key.

Because CA01 is defined as a CAnn key, no data is transmitted to the system
when the CA01 key is pressed. The data, however, remains on the screen. The
program detects that the CAnn key was pressed because response indicator 11 is
set on. The program then displays the STATES record format.
Because the STATES record format is physically above the DETAIL record format,
the system must resend the field formats for the input fields in the DETAIL record
format. (The system would also resend the field formats if the STATES record
format contained only output-only fields and was replacing the RCDA record format.
In this case, the field formats are resent because a record format (RCDA) with a
specific cursor location is being removed.)
The following problems occur because the system resends the field formats for the
DETAIL record format:
All the input fields in the DETAIL record format lose their modified data tags
(MDTs). When the program does the next read to the DETAIL record format
(for example, when the user presses the Enter key), none of the fields typed in
before the user pressed the CA01 key are returned to the program. The
program cannot retrieve that typed data even though the data still remains on
the screen.
To avoid this problem:
– Avoid using a CAnn key.
– If you must use a CAnn key, avoid writing the format containing the CAnn
key to the screen and then writing another format that is physically placed
above the first format if both formats contain input-capable fields.
– Avoid writing a format to the screen that causes the removal of a format
containing a cursor location specification.
The highlight attribute for the constant fields (except Last name) is lost. The
system does not resend the field format for output-only fields. However, if an
output-only field immediately follows an input-capable field so that the leading
attribute character for the output field is in the same position as the ending attri-
bute character for the input-capable field, the attribute of the output field reverts
to normal.
To avoid this problem:
– Do not specify an output-only field with special display attributes imme-
diately following an input-capable field.
– If you must specify an output-only field with special display attributes imme-
diately following an input-capable field, avoid writing that format to the
screen and then writing another format that is physically placed above the
first format if both formats contain input-capable fields.
– Avoid writing a format to the screen that causes the removal of a format
containing a cursor location specification.
Note: The system needs to resend the attributes for the input-capable fields when
a subfile is rolled from a full page to a partial page, a partial page to a full
page, or a partial page to a partial page. The two problems mentioned
above may also occur when resending the field attributes.

Releasing an Acquired Display Station from I/O Operations
The release operation makes a display station ineligible for any further I/O oper-
ations through a file. This operation is used in multiple display file applications or if
you are performing error recovery in your program. If the display station being
released is invited, the invite is ended. If the invited display station had data avail-
able, the data is lost. The release operation can only be performed on display
stations that are currently acquired to the file.
The release operation can also be used to recover from errors from acquire, I/O,
and release operations. After a display station is released, it must be acquired
again with another acquire operation before any I/O operations can be directed to
it. If a program is written to recover from errors by releasing a display station and
then acquiring it again, a value other than *IMMED should be specified on the
WAITFILE keyword. This is because it takes the system a short time to transfer the
allocation of a display station description from a job, to the subsystem, and back
again.
Closing Display Files

The close operation makes the display file ineligible for any further I/O operations
between the program and the system. Refer to the appropriate high-level language
manual for information on how to start the close operation.
If the display file is not being shared, the close operation also implicitly releases all
the display stations acquired to the file and deallocates any file resources allocated
by the open operation or the acquire operation.
If the close operation is successful, the only valid operation to the file is open. If
the close operation fails, the program should issue the close operation a second
time.
Mapping Display Operations to High-Level Language Operations

The following shows the I/O requests supported by the operating system and the
equivalent high-level language operations:
Table 3-6 (Page 1 of 2). Display File Operations Supported by the Operating System and the Equivalent High-
Level Language Commands
BASIC ILE C CL ILE COBOL ILE RPG
Operation Statements Functions Commands Statements Operations
Open OPEN fopen, _Ropen OPEN OPEN
Acquire _Racquire ACQUIRE ACQ
Release _Rrelease DROP REL
Get Attributes _Rdevatr ACCEPT POST
Write WRITE fwrite, SNDF WRITE WRITE,
_Rformat, _Rpgmdev, output
_Rwrite specifications
Read(wait) READ fread, RCVF WAIT(*YES) READ Primary or
_Rformat, _Rpgmdev, secondary
_Rreadn file input,
READ
Read READ RCVF WAIT(*NO) READ
Cancel Read ENDRCV

Table 3-6 (Page 2 of 2). Display File Operations Supported by the Operating System and the Equivalent High-
Level Language Commands
BASIC ILE C CL ILE COBOL ILE RPG
Operation Statements Functions Commands Statements Operations
Wait WAIT
Invite fwrite1, SNDF1 WRITE1 WRITE1
_Rformat, _Rpgmdev,
_Rwrite1
Read from Invited _Rreadindv READ READ
Device
Cancel Invite fwrite, SNDF WRITE WRITE
_Rformat, _Rpgmdev,
_Rwrite
Write-Read(wait) _Rwriterd, _Rformat, SNDRCVF WAIT(*YES) EXFMT
_Rpgmdev
Write-Read(no-wait) SNDRCVF WAIT(*NO)
Close CLOSE, END fclose, _Rclose RETURN, RCLRSC CLOSE, CLOSE,
CANCEL, RETRN
STOP RUN
1 This is the write operation of a record format with the INVITE DDS keyword selected.
If an error occurs during an I/O operation to a display file, the major/minor return
code field in the file dependent I/O feedback area may be used to help diagnose
the error and determine the error recovery action needed.
Sharing Display Files in the Same Job

By specifying the SHARE parameter on the CRTDSPF, CHGDSPF, and OVRDSPF
commands, you can specify that more than one program share the same path to
the data or the display station. Using the SHARE parameter allows more than one
program to share the file status, positions, and storage area, and can improve per-
formance by reducing the amount of main storage the job needs and by reducing
the time it takes to open and close the file.
Using the SHARE(*YES) parameter lets an open data path (ODP) be shared
between two or more programs running in the same job. An open data path is the
path through which all input/output operations for the file are performed. It con-
nects the program to a file. If not specified otherwise, every time a file is opened a
new open data path is built. You can specify that if a file is opened more than
once and an open data path is still active for it in the same job, the active ODP for
the file can be used with the current open of the file, and a new open data path
does not have to be created. This reduces the amount of time required to open the
file after the first open, and the amount of main storage required by the job.
SHARE(*YES) must be specified for the first open and other opens of the same file
for the open data path to be shared. Specifying SHARE(*YES) for other files
depends on the application.
Note: Most high-level language programs process an open or a close operation
independent of whether or not the file is being shared. You do not specify
that the file is being shared in the high-level language program. You indi-
cate that the file is being shared in the same job through the SHARE
parameter. The SHARE parameter is specified only on the create, change,
and override file commands. Refer to your appropriate language manual for
more information.

Understanding the Open Operation for Files Shared in a Job
The following items should be considered when opening a file that is shared in the
same job by specifying SHARE(*YES).
You must make sure that when the shared file is opened for the first time in a
job, all the open options that are needed for subsequent opens of the file are
specified. If the open options specified for subsequent opens of a shared file
do not match those specified for the first open of a shared file, an error
message is sent to the program. (You can correct this by making changes to
your program to remove any incompatible options.)
For example, PGMA is the first program to open FILE1 in the job and PGMA
only needs to read the file. However, PGMA calls PGMB which will delete
records from the same shared file. Because PGMB will delete records from the
shared file, PGMA will have to open the file as if it, PGMA, is also going to
delete records. You can accomplish this by using the correct specifications in
the high-level language. (In order to accomplish this in some high-level lan-
guages, you may have to use file operation statements that are never run.) For
more details, see your appropriate language manual.
If you did not specify a library name in the program or the override command
(*LIBL is used), the system assumes that the library list has not changed since
the last open of the same shared file with *LIBL specified. If the library list has
changed, you should specify the library name on the override command to
ensure that the correct file is opened.
Overrides and program specifications specified on the first open of the shared
file are processed. Overrides and program specifications specified on subse-
quent opens, other than those that change the file name or the value specified
on the SHARE or LVLCHK parameters on the override command, are ignored.
Understanding the Input/Output Operation for Files Shared in a Job

The system uses the same input/output area for all programs sharing the file, so
the order of the operations is sequential regardless of which program does the
operation. For example, if Program A is reading records sequentially from a file
and it reads record 1 just before calling Program B, and Program B also reads the
file sequentially, Program B reads record 2 with the first read operation. If Program
B then ends and Program A reads the next record, it receives record 3. If the file
was not being shared, Program A would read record 1 and record 2, and Program
B would read record 1.
For display files, the display station remains in the same state as the last I/O opera-
tion.
For display and ICF files, programs other than the first program that opens the file
may acquire more display or program display stations or release display or program
display stations already acquired to the open data path. All programs sharing the
file have access to the newly acquired display stations, and do not have access to
any released display stations.

Understanding the Close Operation for Files Shared in a Job
The processing done when a program closes a shared file depends on whether
there are other programs currently sharing the open data path. If there are other
programs, the main function that is performed is to detach the program requesting
the close from the file. All other programs sharing the file are still attached to the
ODP and can perform I/O operations.
If the program closing the file is the last program sharing the file, then the close
operation performs all the functions it would if the file had not been opened with the
share option. This includes releasing any allocated resources for the file and
destroying the open data path.
The function provided by this last close operation is the function that is required for
recovering from certain run-time errors. If your application is written to recover from
such errors and it uses a shared file, this means that all programs that are attached
to the file when the error occurs will have to close the file. This may require
returning to previous programs in the program stack and closing the file in each
one of those programs.

Chapter 4. Displaying Groups of Records Using Subfiles
A subfile is a group of records that have the same record format and are read from
and written to a display station in one operation. The following sample display
shows an example of a subfile:
CUSTOMER NAME SEARCH
Search code: 41401

Prompt
NUMBER NAME ADDRESS CITY STATE Record
Format
41401 Adam’s Home Repair 121 Golden Circle Chicago IL
41402 Jane’s Radio/TV 135 Ransam Drive St Paul MN
41403 Advanced Electronics 809 8th Street St Paul MN
41404 Riteway Repair 443 Western Lane New York NY
41405 Fixtures, Inc. 607 9th Avenue Chicago IL Subfile
41406 Hall’s Electric 200 Main Street St Paul MN
RV2W049-0
This chapter uses DDS keywords to describe subfiles. For more information
about specific DDS keywords, see the DDS Reference.
Recognizing Subfile Uses

Subfiles are useful when multiple records that are alike must be displayed. You
can describe a subfile so that the number of records to be displayed fits on one
display or exceeds the number of lines available on the display.
You can use subfiles for the following purposes:

Display only, which allows the user to review the subfile records on the display
(for example, all the line items for a particular order number, or a group of
records containing customer names and addresses as shown on the previous
sample display).
Display with selection, which allows the user to request more information about
one of the items on the display. On the first sample display of the following
example, the user can request the records for a particular customer by entering
the record number in the record number field. In the second sample display,
the user can request the records for a particular customer by placing an X in
the select number field.

à Enter customer number: 414ð1
ð
Enter record number: ____
RECORD NUMBER NAME ADDRESS CITY STATE
ð1 414ð1 Adam's Home Repair 121 Golden Circle Chicago IL
ð2 414ð2 Jane's Radio/TV 135 Ransom Drive St Paul MN
ð3 414ð3 Advanced Electronics 8ð9 8th Street St Paul MN
ð4 414ð4 Riteway Repair 443 Western Lane New York NY
ð5 414ð5 Fixtures, Inc. 6ð7 9th Avenue Chicago IL
ð6 414ð6 Hall's Electric 2ðð Main Street St Paul MN
à Enter customer number: 414ð1

ð
SELECT
RECORD NUMBER NAME ADDRESS CITY STATE
_ 414ð1 Adam's Home Repair 121 Golden Circle Chicago IL
_ 414ð2 Jane's Radio/TV 135 Ransom Drive St Paul MN
_ 414ð3 Advanced Electronics 8ð9 8th Street St Paul MN
_ 414ð4 Riteway Repair 443 Western Lane New York NY
_ 414ð5 Fixtures, Inc. 6ð7 9th Avenue Chicago IL
_ 414ð6 Hall's Electronic 2ðð Main Street St Paul MN
Changing information, which allows the user to change one or more of the
records in the subfile. The following sample display allows the user to change
the QTY and SHIP values:
à UPDATE SHIP QUANTITY ON ORDERS

ð
Order: 11589 Customer number: 11111 Customer name: Al'Supply
ITEM DESCRIPTION QTY SHIP LOCATION
25764 Pliers 1ð 1ð RST
33624 Hammer 5ðð 25ð RST
49821 Pliers 2ðð 2ðð RST
26837 Wire Cutters 5ð 25 RST
Input only without validity checking, which allows the user to enter data as fast
as possible; or input only with validity checking, which allows the user to enter
data that is validity checked by the system or by the program for valid entries.
The following sample display shows subfiles for input only:
à Enter order number: XXXXX

ð
ITEM NUMBER QUANTITY
XXXXX XXX
XXXXX XXX
XXXXX XXX
XXXXX XXX
XXXXX XXX
XXXXX XXX
XXXXX XXX
_____ ___
Combination of tasks, which can, for example, allow the user to change data as
well as to enter new records. In the following example, the user can change
existing names and addresses or enter new records.
à CUSTOMER NAME SEARCH

ð
Search code: 414ð1
NUMBER NAME ADDRESS CITY STATE
414ð1 Adam's Home Repair 121 Golden Circle Chicago IL
414ð2 Jane's Radio/TV 135 Ransom Drive St Paul MN
414ð3 Advanced Electronics 8ð9 8th Street St Paul MN
_____ ______________________ ______________________ __________ ____
_____ ______________________ ______________________ __________ ____
_____ ______________________ ______________________ __________ ____
Displaying single-choice and multiple-choice selection lists. A single-choice

selection list is a potentially scrollable list from which the user can select one

item. A multiple-choice selection list is a potentially scrollable list from which
the user can select one or more items. For more information on selection lists,
see “Selection Lists—Overview” on page 6-24.
RV3W077-0
Describing Subfiles in Your DDS Source

Each subfile you describe in your DDS source requires two types of record formats:
a subfile record format and a subfile control record format.
The subfile record format defines the fields in one row of the subfile.
The high-level language program uses the subfile record format to read a
subfile, write new records to a subfile, and update the subfile. Operations to
the subfile record format are performed between the subfile and the high-level
language program; the display is not changed on operations to a subfile record
format.
The subfile (SFL) keyword is required on the subfile record format.
The subfile control record format contains heading information and controls
subfile functions such as size, initialization, and clearing.
The high-level language program performs operations on the subfile control
record format to write the subfile to the display and to read the subfile from the
display.
The following DDS keywords are required on a subfile control record format:
– Subfile control (SFLCTL) keyword, which identifies the subfile control record
format for the subfile record format that immediately precedes it
– Subfile size (SFLSIZ) keyword, which specifies the size of the subfile
– Subfile page (SFLPAG) keyword, which specifies the size of the subfile
page
– Subfile display (SFLDSP) keyword, which specifies when to begin dis-
playing records in a subfile
Chapter 4. Displaying Groups of Records Using Subfiles 4-3

The DDS for the subfile record format must precede the DDS for the subfile control
record format.
Each subfile has two types of records:

An active subfile record is a record that has been:
– Added to a subfile by a write operation.
– Initialized as active by the subfile initialize (SFLINZ) keyword.
– Changed when a write or update operation with the subfile next changed
(SFLNXTCHG) keyword in effect was issued to the record.
– Changed by the user.
An inactive subfile record is a record that was:
– Not added to a subfile by the write operation.
– Initialized as inactive by the SFLINZ keyword and the subfile records not
active (SFLRNA) keyword.
You can also perform the following functions on subfiles:
Table 4-1 (Page 1 of 5). Optional Functions for Subfiles

Function DDS keyword Additional information
Allow a subfile to contain mes- Subfile message key See the DDS Reference for
sages from a program (SFLMSGKEY), more information about the
message queue subfile message subfile message keywords.
record
(SFLMSGRCD), and
subfile program
message queue
(SFLPGMQ)
Clear the subfile of all records Subfile clear The subfile is not erased from
before new records are written (SFLCLR) the display, however, until the
SFLDSP keyword is in effect
on the subfile control record. If
the SFLCLR keyword is speci-
fied for a subfile with no
records, it is ignored.
Control when to display a Subfile Display The SFLDSP and SFLDSPCTL
subfile control record Control keywords are the only
(SFLDSPCTL) or keywords that cause the con-
SFLDSP tents of the display to change.
The SFLDSPCTL keyword
must be in effect if an input
operation is done to retrieve
the status of a CFnn or CAnn
key even if no fields are dis-
played.

Delete the subfile to allow Subfile delete Normally, subfiles should not
another subfile to be used or to (SFLDLT) be deleted by the program.
continue processing the display When the file containing the
file with no subfile used subfile is closed, the subfile is
deleted automatically by the
system. However, if the file is
shared and is still open by
another program, the subfile is
not deleted, and you must
delete it in your program. You
should only delete a subfile if
the maximum number of sub-
files are already being used
and you need to use another
one. The SFLDLT keyword is
ignored if the subfile does not
exist.
Display a page of a subfile by Subfile record If CURSOR is specified for the
a record number number SFLRCDNBR keyword, the
(SFLRCDNBR) cursor is placed in the subfile
record whose relative record
number is identified by the
contents of this field. The
cursor is positioned at the first
input-capable field in the
subfile record. If there is no
input-capable field, the cursor
is positioned at the first output-
only or constant field.
Display a plus sign (+) in the Subfile end The plus sign is replaced by a
lower corner at the extreme (SFLEND) or blank when the last record is
right of the subfile display area (SFLEND(*PLUS)) displayed. An option indicator
(page) when there are more must be specified with the
records than fit on the display SFLEND or SFLEND(*PLUS)
keyword.
Display the word 'More...' on Subfile end The word 'More...' is replaced
the line following the subfile SFLEND(*MORE) by the word 'Bottom' when the
display area (page) when there last record is displayed. An
are more records than fit on option indicator must be speci-
the display fied with the SFLEND(*MORE)
keyword.
Display a scroll bar next to a Subfile end For more information, see
subfile SFLEND(*SCRBAR) “Selection Lists—Overview” on
page 6-24.
Return the relative record Subfile scroll For more information, see
number of the record at the top (SFLSCROLL) “Selection Lists—Overview” on
of the current page of records page 6-24.

Enable a command key to fold Subfile fold If the SFLFOLD keyword is
or truncate records in a subfile (SFLFOLD) or subfile specified, the initial display of
drop (SFLDROP) the records is folded. If the
SFLDROP keyword is speci-
fied, the initial display of the
records is automatically trun-
cated. Then the user can
press the command key to
display the truncated or folded
version, respectively, of the
subfile record. If the page size
equals the subfile size or the
subfile fits on one display line,
the specified keyword
(SFLFOLD or SFLDROP) is
ignored.
Both SFLFOLD and SFLDROP
can be used on the same
subfile. Optional indicators can
be used on these keywords.
The optional indicators are
used to determine which mode
the subfiles are initially dis-
played in. If both keywords
are optioned on or optioned
off, then the subfile is initially
displayed in folded mode. If
the keyword is optioned off, the
command key can still be used
to display the truncated or
folded version.
Enable the Enter key as the Subfile enter If more than one subfile using
Roll Up key and enable a (SFLENTER) SFLENTER is displayed at the
command key to return to the same time, the only CAnn or
high-level language program CFnn key in effect as an Enter
key is the CAnn or CFnn key
specified for SFLENTER on
the most recently displayed
subfile. The cursor position at
the time the Enter key is
pressed determines which
subfile is affected.

Initialize a subfile with no SFLINZ and subfile A record becomes active when
active records even though the records not active one of the following happens:
subfile is active (SFLRNA)
An output operation is
issued to the subfile for a
specific record. The record
is not considered changed
unless the SFLNXTCHG
keyword is used.
A user enters data into a
displayed record. The
record is considered active
and changed.
The records are displayed if
the SFLDSP keyword is in
effect. If default values were
specified for fields in the
records, they are included in
the display.
Initialize all records by the field SFLINZ When the SFLINZ keyword is
descriptions in the subfile in effect on an output operation
record format in the display file to the subfile control record
(SFLCTL), the system
assumes that all option indica-
tors on the subfile record are
off; therefore, only those option
indicators that are preceded by
N are in effect. The subfile
records are displayed if
SFLDSP is in effect on an
output operation. When the
SFLINZ keyword is in effect on
an output operation, the con-
tents of input-capable fields
without a default value are
handled as follows:
Numeric fields are initial-
ized to zeros.
Character fields are initial-
ized to blanks.
Floating point fields are ini-
tialized to nulls.
Return a record to the program Subfile next changed The record is returned even if
when a get-next-changed oper- (SFLNXTCHG) the record was not changed by
ation is performed the user
Roll by a specified number of Subfile roll value This field must have the key-
records instead of by page (SFLROLVAL) board shift attribute of signed
numeric with zero decimal
positions. It can be up to 4
digits long and must be defined
as an output/input or input-only
field.

Specify the number of spaces Subfile line (SFLLIN) This keyword is used for a hor-
between each record on a line izontally displayed subfile. If
when more than one record is the display file supports more
displayed on a line than one screen size and the
SFLLIN keyword is to apply to
the secondary screen size in
addition to the default (or
primary) screen size, screen
size condition names must be
specified.
Write a message to the Subfile message See the DDS Reference for
message line on the display (SFLMSG) and more information about the
when your program does an subfile message ID message keywords.
output operation to the subfile (SFLMSGID)
control record
Determines where the cursor is Subfile cursor relative The relative record number on
located in a subfile record number which the cursor is positioned
(SFLCSRRRN) is returned in the hidden field
specified as the parameter on
the keyword.
Specify cursor progression for Subfile cursor The SFLCSRPRG keyword
a subfile progression causes the cursor to move
(SFLCSRPRG) from a field in a subfile record
to the same field in the next
displayed subfile record. For
more information, see “Defining
Cursor Progression for Entry
Fields” on page 2-17.
Determines whether the subfile Subfile mode This is a required parameter
was in folded or truncated (SFLMODE) and is only valid for subfile
mode control records and the
SFLCTL keyword must be
specified.
Define a single-choice Subfile single-choice For more information, see
selection list selection list “Selection Lists—Overview” on
(SFLSNGCHC) page 6-24.
Define a multiple-choice Subfile multiple- For more information, see
selection list choice selection list “Selection Lists—Overview” on
(SFLMLTCHC) page 6-24.
Control the availability of Subfile choice control For more information, see
choices in a selection list (SFLCHCCTL) “Selection Lists—Overview” on
page 6-24.
Return all selected choices in a Subfile return For more information, see
selection list using the get- selected choice “Selection Lists—Overview” on
next-changed operation (SFLRTNSEL) page 6-24.
The DDS keywords can be specified in any order; however, the subfile record
format (SFL) must precede the subfile control record format (SFLCTL).
You can use option indicators to condition many of the DDS subfile keywords.

You can specify a maximum of 512 subfiles in a display file, since the maximum
number of record formats allowed in a display file is 1024. No more than 12 sub-
files can be active at the same time to the same display station. One or more
active subfiles can be displayed at the same time on the display station. A subfile
must contain at least one field that can be displayed, and the subfile record format
must not overlap the subfile control record format. If these records overlap, the
display file cannot be created.
All named fields in a subfile record, including fields that are not input-capable, are
returned to the program.
If any input data validity checking is specified for the subfile record, the validity
checking is performed before any roll function is performed. If the data fails validity
checking, the roll function is not performed.
When the relative record number of the record written to the subfile equals the
subfile size, the system sends the program a CPF5003 message indicating that the
subfile is full. (Not all records need to be active; that is, this message is sent even
if the only record written to the subfile was the last record in the subfile.) If the
subfile size does not equal the page size and the program then writes more records
to the subfile, the system automatically extends the subfile as additional records are
added. The program is not notified that the subfile has been extended. (A subfile
cannot be extended past 9999 records.) Also, if the subfile size equals the page
size, the program is not notified that the subfile is full unless the last record written
to the subfile occupies the last line available on the subfile display area.
Processing of an extended subfile is less efficient because the extended space is

not connected with the subfile. You can avoid extension by specifying a larger
subfile size, but you will be wasting space if the extended space is used very
seldom or never.
Figure 4-1 on page 4-10 illustrates the order in which some of the DDS keywords
used for subfile control are processed at run time:

Start
Initialize Yes Initialize Display Yes Display

subfile subfile subfile subfile
(SFLINZ) (SFLDSP)
No No
Delete Yes Subfile Yes Delete

subfile active subfile
(SFLDLT)
No No
Clear Yes Yes

Subfile Clear
subfile
active subfile
(SFLCLR)
No No
Display Yes Yes

subfile Subfile Display
(SFLDSP) active subfile
No No
Exit
RSLH181-0
Figure 4-1. DDS Keyword Processing Order for Subfile Control
Using a Subfile in a Program

To use a subfile, you perform the following basic operations in your high-level lan-
guage program:
1. Initialize the subfile. One way to initialize the subfile is to read records from a
database file and write them to the subfile. Place the records in the subfile one
at a time until the subfile is full or until there are no more records.

Program File
Database Subfile
File
I/0 Area
RV2W029-3
2. Send the subfile to the display in one output operation using the subfile control
record format.
3. After the user reviews the records, changes them, or enters new records
(depending on the function of the subfile), read the subfile control record
format.
Program File Display

Subfile
RV2W030-2
4. Process each record in the subfile individually, updating the database file or
writing new records to the database file as required. If the function of the
subfile is to update records, the program need only process the changed
records by using the READC operation in ILE RPG or the Read Subfile Next
Modified verb in ILE COBOL.
File
Program
Subfile
Data-
base
File
I/0 Area
RV2W031-2
A display file that uses subfiles may display only a portion of a subfile at a time.
The portion that is displayed is called a subfile page. The data entered into an
input-only field on a subfile display goes to the subfile when a function key (such as
a Roll key) is pressed. The field then displays a value in the subfile, and what
happens when the Enter key is pressed depends on the application code.
Note: In a READC operation in ILE RPG, the data is moved from the subfile to
the program. It does not remove it from the subfile, and it will continue to
be displayed in the input-only field as if the fields were initialized to that
value. Otherwise, it would appear that the subfile was empty when the data
was actually there.

If the subfile is processed (for example, by an UPDAT operation in RPG),
then the data is removed from the subfile, and the input-only fields are
blanked out, reflecting the true condition of empty fields. This should be
done after the READC operation moves the data to the program.
Requesting I/O Operations for a Subfile

An I/O request by a calling program to a subfile record format either writes a record
to a subfile or reads a record from a subfile but never causes actual I/O to the
display. To write subfile records to a display, the program must issue a request to
the subfile control record format.
The valid requests that can be made to a subfile depend on whether the request is
made to the subfile record format or the subfile control record format.
Requesting I/O Operations for a Subfile Record Format

By requesting the correct I/O operation for a subfile record format, you can do the
following:
Add a record (passed from a program) to a specified location in a subfile
Update an active record that already exists in the subfile
Read an active record at a specified location in the subfile
Read the next changed record in the subfile that is greater than the relative
record number previously read with a get-relative or get-next-changed operation
Adding a Record at a Specified Location in a Subfile

The put-relative operation adds a record (passed from a program) at a specified
location in a subfile.
The location must be a valid relative record number in the subfile. The minimum
relative record number is always 1. If the subfile size equals the subfile page, the
maximum relative record number value is the subfile size value. If the subfile size
is greater than the subfile page, the maximum relative record number value is 9999
because the system automatically extends the subfile as required. In addition, the
relative record number cannot be the number of an active record already in the
subfile. The relative record number is ignored when field selection is specified for
the subfile record.
When a put-relative operation adds a record at the last record location (the subfile
size value) in the subfile, a subfile-full condition occurs (message CPF5003). Both
ILE RPG and ILE COBOL have special support for notifying the application
program of this condition. See the appropriate high-level language manual.
The contents of input-capable fields without a default value specified are handled
as follows:
Numeric fields are initialized to zeros
Character fields are initialized to blanks
Floating point fields are initialized to nulls

Updating an Active Record in the Subfile
The update operation updates an active record that already exists in the subfile.
The active record must have been read before the update operation by a get
request (either get relative or get-next-changed). No other I/O operations may be
performed on the subfile to be updated between the read and the update. In addi-
tion, the subfile being updated may not be displayed again between the read and
the update (for example, using subfile roll or SFLDROP processing).
Notes:
1. Some high-level languages do not allow I/O to any format in the display file
between the read and the update of a single subfile record in the display file.
Refer to the documentation for the high-level language you are using for more
information.
2. If field selection is specified for the subfile record, only the fields that were
selected when the record was placed in the subfile can be updated. Selecting
different fields will cause results that cannot be predicted.
Reading an Active Record at a Specified Location in the Subfile

The get-relative operation reads an active record at a specified location in the
subfile.
The location must be a valid relative record number in the subfile. The entire
record, including response indicators (defined at the file level and on fields in a
subfile record), input, output, output/input, and hidden fields, is passed to the
program, the relative record number is placed in the input/output feedback area,
and the record is no longer identified as a changed record. Response indicators
defined at the file level are always returned as off. Response indicators defined on
fields in a subfile record, such as the BLANKS or CHANGE keywords, are returned
as on or off depending on the information in the field at the time the get operation
was done.
If the record specified on the get-relative operation is not active, a not valid record
number condition occurs (message CPF5020). This condition becomes a record-
not-found condition in some high-level languages. See the appropriate high-level
language manual.
Notes:
1. The get-relative operation and get-next-changed operation both update the rela-
tive record number in the input/output feedback area. Subsequent get-next-
changed-record requests retrieve sequentially changed records greater than
this relative record number.
2. The get-relative and get-next-changed operations do not process input data for
overlapping fields in a subfile. The record returned to the program contains the
data already existing in the buffer prior to the read operation for overlapped
fields. If this is a problem, use the subfile initialize function to ensure all subfile
fields are cleared.

Reading the Next Changed Record in a Subfile
The get-next-changed operation reads the next changed record in the subfile that
is greater than the relative record number previously read with a get-relative or get-
next-changed operation.
If the get-next-changed operation is used as the first read operation, the first
changed record in the subfile is read. The entire record, including response indica-
tors (defined at the file level and on fields in a subfile record), input, output,
output/input, and hidden fields, is passed to the program, the relative record
number is placed in the data management feedback area, and the record is reset to
a not changed record. Response indicators defined at the file level are always
returned as off. Response indicators defined on fields in a subfile record, such as
the BLANKS or CHANGE keywords, are returned as on or off depending on the
information in the fields at the time the get operation was done.
If there are no more changed records in the subfile, a message (CPF5037) indi-
cating that the last changed record has already been retrieved, is sent to the
program. See the appropriate high-level language manual for a description of how
this condition is reported to your program.
If a record retrieved by a get-next-changed operation is updated and the

SFLNXTCHG keyword is specified for an updated record, the updated record is set
again as a changed record. This allows the program to ensure that the user has
changed the record. For example, if the program detects an error in a record, it is
advantageous to require the user to correct the error. The use of the SFLNXTCHG
keyword allows the program to read that record again on a get-next-changed oper-
ation so it can continue to reject the record until the error has been corrected. The
next get-next-changed operation does not retrieve this updated record. The record
cannot be retrieved again with a get-next-changed operation until all the changed
records following it in the subfile have been processed. This is because the
changed records are accessed sequentially and the sequence does not start at the
beginning until after the message indicating that there are no more changed
records in the subfile has been sent to the program. A get-next-changed operation
following this message gets the first changed record in the subfile. Because no I/O
operation has been issued to the display, any changed record would be a record
that was processed using the SFLNXTCHG keyword.
Notes:
1. The get-relative operation and get-next-changed operation both update the rela-
tive record number in the input/output feedback area. Subsequent get-next-
changed-record requests retrieve sequentially changed records greater than
this relative record number.
2. The get-relative and get-next-changed operations do not process input data for
overlapping fields in a subfile. The record returned to the program contains the
data already existing in the buffer prior to the read operation for overlapped
fields. If this is a problem, use the subfile initialize function to ensure all subfile
fields are cleared.

Requesting I/O Operations for a Subfile Control Record Format
By requesting the correct I/O operation for a subfile control record format, you can
do the following:
Display subfile records
Place the subfile records on the display into the subfile for processing by the
program
Display and process subfile records at the same time
Displaying Subfile Records

You can display subfile records by issuing a write operation to the subfile control
record format.
You can control the write operation using the following DDS keywords:
SFLDSP Display the subfile.
SFLDSPCTL Display the subfile control record.
SFLCLR Clear the subfile of active records.
SFLDLT Delete the subfile.
SFLINZ Initialize the subfile with active records, or if the SFLRNA keyword
is specified, with inactive records. When the subfile is initialized, all
option indicators in the subfile record are assumed to be off.
SFLEND Notify the user when the last available record is displayed.
SFLRCDNBR Display the specified page of the subfile.
Note: These keywords are described under “Describing Subfiles in Your DDS
Source” on page 4-3.
Placing Subfile Records on the Display for Processing

A read operation must be issued to a displayed record format in order for the
subfile records on the display to be placed into the subfile for processing by the
program. The subfile records from the display are placed in their corresponding
record positions in the subfile.
Displaying and Processing Subfile Records at the Same Time

The write-read operation is a single operation that combines the write and read
operations and is more efficient than a single write operation followed by a single
read operation.
Recognizing Subfile I/O Requests in High-Level Languages

Table 4-2 shows the I/O requests supported by the system and the equivalent
high-level language operations:
Table 4-2 (Page 1 of 2). Subfile Operations Supported by the System and Equivalent HLL Commands
ILE C ILE RPG
Operation Function Operation ILE COBOL Statement BASIC Statement
Put Relative _Rwrited WRITE, WRITE SUBFILE WRITE REC =
output specifi-
cations
Update _Rupdate UPDAT REWRITE SUBFILE REWRITE REC =
Get Relative _Rreadd CHAIN READ SUBFILE READ REC =

Table 4-2 (Page 2 of 2). Subfile Operations Supported by the System and Equivalent HLL Commands
ILE C ILE RPG
Operation Function Operation ILE COBOL Statement BASIC Statement
Get Next _Rreadnc READC READ SUBFILE NEXT MOD- READ MODIFIED
Changed IFIED
Write _Rwrite WRITE WRITE WRITE
Read _Rread READ READ READ
Write-Read _Rwriterd, EXFMT
_Rformat,
_Rpgmdev
Controlling the Appearance of Subfiles

Records in a subfile can be displayed either vertically or horizontally. In a vertically
displayed subfile, a record is displayed on one or more lines, with each record
beginning a new line (see Figure 4-2). In a horizontally displayed subfile, a record
is complete on one line, and more than one record is displayed on a line (see
Figure 4-3). You can specify that a subfile is to be displayed horizontally by using
the SFLLIN keyword to define the number of spaces between each subfile record
on a display line. Figure 4-4 on page 4-17 shows an example of a vertical subfile
and a horizontal subfile being displayed at the same time.
Record 1
Record 2
Record 3
Record 4
.
.
.
.
RSLH702-0
Figure 4-2. Vertically Displayed Subfile
Record 1 Record 5 Record 9

(some other record)

RSLH703-0
Figure 4-3. Horizontally Displayed Subfile

Record 1 Record 5
Record 2 Record 6
Record 3 Record 7
Record 4 Record 8
Record A
Record B
Record C
Record D
Record E
RSLH704-0
Figure 4-4. Horizontally and Vertically Displayed Subfiles Displayed at the Same Time
If a subfile is larger than the space allowed for the subfile on the screen, the user
can roll the display from one group of records in the subfile to another. Each group
of records displayed at the same time is called a page. When you create a display
file with a subfile, you must specify the size of the page for a subfile by specifying
the number of records in the page (SFLPAG keyword). Usually page size is based
on the number of lines available on the display. You must also specify the size of
the subfile by specifying the number of records in the subfile (SFLSIZ keyword).
Page size and subfile size can be the same; that is, all records in the subfile fit on
one page. When page size equals subfile size, variable-length subfile records are
supported. One record can take up only a single line while another record can take
up more than one display line. Each record is placed in the first record position
available in the subfile; this position is always a new line. In addition, the
SFLDROP and SFLROLVAL keywords are ignored by display station support when
page size equals subfile size.
For more information on page size and subfile size, see “Specifying Subfile Size
Equal to Page Size” on page 4-19 and “Specifying Subfile Size Not Equal to Page
Size” on page 4-21.
If records are to be displayed horizontally, the number of records to be displayed in

a subfile (SFLPAG keyword) is adjusted so that the last line on the screen can be
used to display a full line of records. For example, if the number of spaces
between each record on a line (SFLLIN keyword) is specified such that six records
fit on a line and 20 is specified for the page size (SFLPAG keyword), 20 is changed
to 24, which is the nearest multiple of six. The number of records in the subfile
(SFLSIZ keyword) is incremented by the same amount.
Note: For the initial display of a subfile, the more records placed in a subfile
before it is displayed, the slower the response time.
Displaying Horizontal Subfiles with Display Modes

You can use the display mode (DSPMOD) keyword to specify which of the two
modes (or display sizes), 24x80 or 27x132, you want to use for your display
station.
When changing display modes, the display is cleared but the data is not cleared
from the subfile. SFLDSP or SFLDSPCTL must be in effect for DSPMOD to be
active in the control record.
The following example shows how to specify DSPMOD with subfiles:

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A DSPSIZ(\DS4 \DS3)
A R SFLR SFL
A FLD1 8 O 1 5
A FLD2 7 I 1 16
A FLD3 7 B 1 24
A R SFLCTLR SFLCTL(SFLR)
A SFLDSP
A SFLDSPCTL
A SFLSIZ(6ð)
A SFLPAG(12)
A SFLLIN(4)
A \DS3 SFLLIN(6)
A ð2 SFLEND
A 1ð DSPMOD(\DS3)
A
A
Figure 4-5. Sample DDS Using DSPMOD with Subfiles
In the previous example, if the user’s program turns indicator 10 off and issues a
write-read operation to the subfile control record format (SFLCTLR), the subfile is
displayed as follows:
In 27 by 132 (*DS4) mode, because indicator 10 for the DSPMOD keyword is
off.
Horizontally, because SFLLIN is specified. The SFLLIN value indicates the
number of bytes between records. Because each record is 30 bytes long and
the space between each record is 4 bytes long, four records can be displayed
on one horizontal line, (4 x 30) + (3 x 4) = 132 bytes. The subfile is displayed
on three lines because SFLPAG(12) is specified.
The following example shows the subfile displayed in *DS4 mode.
à RECORD 1 RECORD 4 RECORD 7 RECORD 1ð

ð
RECORD 2 RECORD 5 RECORD 8 RECORD 11
RECORD 3 RECORD 6 RECORD 9 RECORD 12
If the user presses the Enter key, control is returned to the user’s program. If the
user’s program turns on indicator 10 and then issues another write-read operation
to the subfile control record format (SFLCTLR), the subfile is displayed as follows:
In 24 by 80 (*DS3) mode, because indicator 10 for the DSPMOD keyword is
on.
Horizontally, because SFLLIN is specified for the *DS3 mode. If SFLLIN was
not specified for the *DS3 mode, the subfile would have been displayed verti-
cally. If the SFLLIN keyword is to be used for more than one screen size, a
screen size condition name for each secondary screen size is required.
Because each record is 30 bytes long and the space between each record is 6
bytes long, two records can be displayed on one horizontal line, (2 x 30) + 6 =
66 bytes). The subfile is displayed on six lines because SFLPAG(12) is speci-
fied. To ensure other records are not erased, the SFLPAG may need to be
specified for the secondary screen size.

The following example shows the subfile displayed in *DS3 mode.
à RECORD 1 RECORD 7
ð
RECORD 2 RECORD 8
RECORD 3 RECORD 9
RECORD 4 RECORD 1ð
RECORD 5 RECORD 11
RECORD 6 RECORD 12
Specifying Subfile Size Equal to Page Size

You must specify the size of the subfile and the number of subfile records to be
displayed at one time with the SFLSIZ and SFLPAG keywords. The use of subfile
size equals page size is recommended when the number of subfile records to be
displayed will fit on one page or when the number of records to be placed in the
subfile is unknown and large. It is not an efficient use of resources to retrieve
many database records to fill a large subfile if the user normally finds the needed
information on the first page.
When subfile size equals page size, the system does not automatically support the
use of the Roll Up and Roll Down keys. If you want the user to roll through the
subfile using these keys, you must specify the ROLLUP or ROLLDOWN keyword in
the subfile control record, and your program must handle the roll up or roll down
function.
For example, if a subfile is used to allow the user to search through a long list, you
can specify SFLSIZ equals SFLPAG and ROLLUP on the subfile control record:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R SFLCTLR SFLCTL(SFLRCD)
A SFLSIZ(16)
A SFLPAG(16)
A ROLLUP(2ð 'Roll Up')
Figure 4-6. Sample DDS Using SFLSIZ, SFLPAG, and ROLLUP Keywords
When the user presses the Roll Up key, indicator 20 is set on and control returns to
the program. In your program, you would:
Clear the subfile (a write operation to the subfile control record with the
SFLCLR keyword in effect).
Use the indicator to control a return to the logic that fills the subfile with another
page of records.
Display the new subfile page.
You could also allow the display station user to press a CFnn key to return to the
start of the search. When the user presses the CFnn key, the associated indicator
is set on and control returns to the program. In your program, you would:
Clear the subfile.
Use the indicator to control a return to the logic that built the first subfile page
based on the search code entered. (The program needs to keep the original
search code in order to do this.)

Using the ROLLDOWN keyword when subfile size equals page size requires more
lines of code in the program because the program must keep track of the record
position in the subfile and in the database file.
When the subfile size equals page size, you can use field selection and variable-
length records in the subfile. If you use field selection, consider the following:
If the fields are selected through the use of option indicators, the relative record
number is ignored and each record is placed in the first available record posi-
tion in the subfile.
If a record is being updated, the field selection that does not match that on the
original output is ignored. For example, assume that FIELD1 and FIELD2 are
selected when the record is placed in the subfile. If the update selects FIELD2
and FIELD3, fields would overlay the original FIELD1 and FIELD2 fields, and
the results could not be predicted.
If field selection is specified on the subfile record, the number of records that
can be displayed on the screen depends on the number of fields selected.
When field selection is specified, the SFLPAG(value) keyword specifies the
number of screen lines available to display the subfile record. In other cases,
the SFLPAG(value) keyword specifies the number of subfile records that can
be displayed at one time.
The SFLFOLD, SFLDROP, and SFLROLVAL keywords are ignored.
When variable-length records are used, each record in the subfile is displayed
beginning on the first available line on the page. If you use field selection for
variable-length records, each record can take up a different number of lines on the
display. Therefore, the number of records that actually fit in the subfile depends on
the field selection of each record written to the subfile. The following shows an
example of the DDS for a variable-length record:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R SFLRCD SFL
A ITMNBR 8Y ð 6 2
A ITMDSC 15 6 11
A QTYOH 4 ð 6 28
A LSTPC 7 2 6 39
A ALLOH 8Y ð 6 49
A SLSMO 1ð 2 6 63
A N8ð SLSYR 12 2 7 7
A N8ð CSTYR 12 2 +3
Figure 4-7. Sample DDS for a Variable-Length Record
When indicator 80 is on, each record in the subfile fits on one line. However, when
indicator 80 is off, each record uses two lines on the display.
Another typical use of variable-length records is where two or more entirely different
formats are used to make up one format. In this case, each field would be sepa-
rately conditioned by option indicators so that one record format might use multiple
lines while another format uses only one line.

Specifying Subfile Size Not Equal to Page Size
Subfile size not equal to page size should be used when a finite number of records
can be placed in the subfile and that number is small (for example, 50). The
SFLSIZ keyword specifies the subfile size. The system allocates space to contain
the subfile records based on the value specified for SFLSIZ. You should specify a
value equal to the number of records that you normally have in the subfile. If your
program places a record with a relative record number larger than the SFLSIZ
value into the subfile, the system extends the subfile to contain it (up to a maximum
of 9999 records).
When the subfile size is not equal to the page size, the use of the Roll Up and Roll
Down keys is automatically supported.
To inform the user that there are more records in the subfile, use the SFLEND
keyword on the subfile control record. When SFLEND is in effect (for example, the
option indicator is on), a + (plus sign) is placed in the lower position to the extreme
right of the screen on each page except the last page. On the last subfile page,
the + is replaced with a blank.
When the subfile size is not equal to page size, you can use the SFLROLVAL
keyword to allow the user to enter a value to specify how many records should be
rolled up or down when the appropriate key is pressed. If the SFLROLVAL
keyword is not used, the subfile is rolled by the SFLPAG value except for subfiles
using SFLFOLD or SFLDROP. If the SFLFOLD or SFLDROP keyword is used,
more records are displayed than the SFLPAG value when records are displayed in
the truncated format. For truncated records, the display rolls by the number of
records displayed in the truncated format. When the SFLROLVAL keyword is used
and the Roll Up key is pressed, the uppermost record number in the displayed
subfile is added to the roll value to determine the new uppermost record number. If
this value is greater than the last record in the subfile, the last full page of records
is displayed. If the Roll Up key is pressed when the last subfile page is displayed
and the roll value is not less than the page size value, an error message is issued.
If the roll value is less than the page size value, the roll function is performed.
Variable-length records and field selection cannot be used when the subfile size is
not equal to the page size.
A technique to improve performance when you are using a multiple page subfile is
to write only one page of subfile records at a time but use the OS/400 support to
roll through the subfile. To do this, you need to define the ROLLUP keyword in
DDS with a response indicator and also use the SFLRCDNBR keyword. In your
program, you would write the records needed to fill one subfile page and then
display that page. When the user wants to see more records, he or she presses
the Roll Up key. The program then writes another page of records to the subfile,
places the relative record number of a record from the second page into the
SFLRCDNBR field, and displays the record.
The second page of subfile records is now displayed, and if the user presses the
Roll Down key, the roll down is handled by the system. If the user presses the Roll
Up key while the first page is displayed, the system will also handle the roll up.
The program is notified only when the user attempts to roll up beyond the records
currently in the subfile. The program would then handle any additional roll up
requests in the same manner as for the second page. When you use this tech-

nique, the subfile appears to be more than one page because of the use of the roll
keys. Yet, you can maintain good response time because the program only fills
one subfile page before writing it to the display.
Checking Validity on Subfile Data

In addition to the DDS validity checking keywords (CHECK, COMP/CMP, RANGE,
and VALUES), you can also do validity checking on subfile data in your program
and require the user to correct the error.
For example, assume that you are using a subfile for an order entry program and
you want to check the item number field to be sure it is a valid order number. You
also want to check the quantity ordered field to ensure there are enough items on
hand to fill the order. To do this, you can use the SFLNXTCHG keyword on the
subfile record (SFL) to allow your program to diagnose the errors and require the
user to correct them. The following DDS shows an example of using the
SFLNXTCHG keyword:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R ORDENTD
A 1 3ð'ORDER ENTRY DISPLAY'
A 3 2'Enter customer number:'
A CUST 5 3 25
A R SFLRCD SFL
A 61 SFLNXTCHG
A LINNBR 2 7 4
A ITMNBR 5 B 7 9
A 4ð DSPATR(RI PC)
A QTYORD 4 B 7 2ð
A 35 DSPATR(RI PC)
A R SFLCTLR SFLCTL(SFLRCD)
A SFLSIZ(5)
A SFLPAG(5)
A 55 SFLDSP
A 5ð SFLDSPCTL
A 3ð SFLCLR
A 1ð SFLINZ
A 4ð SFLMSG('Item number not valid' 4ð)
A 35 SFLMSG('Qty not available' 35)
Figure 4-8. Sample DDS Using the SFLNXTCHG Keyword
When the program detects an error, it sets on the indicator that conditions the
SFLNXTCHG keyword and issues a write operation to the subfile control record
with the SFLDSP keyword in effect. The field in error is displayed in reverse
image, and the cursor is positioned at that field. The associated error message is
also displayed. The user then corrects the error.
A decision you must make when using the SFLNXTCHG keyword is whether to
allow the user to change the subfile fields that were not in error. If you do not want
the display station user to change those fields you can protect them with the
DSPATR(PR) keyword. For those fields you do not want changed, the
DSPATR(PR) keyword must be in effect only when the SFLNXTCHG keyword is in
effect. If you allow the user to change the fields, you can:

Define hidden fields for those fields that are to be checked.
Move the data originally entered by the user into the hidden fields when an
error occurs on a subfile.
Compare the data in the hidden fields to the fields just read to identify which
fields have been changed so you can update the records that have already
been processed when the user makes the changes.
Displaying Error Messages from Subfiles

You can use a subfile to display messages for multiple errors. The messages to be
placed in the subfile are on a program message queue. Each message written to
the subfile is displayed on a separate line and is truncated, if necessary. Each
message line contains an attribute character in position 1 that is displayed as a
blank, followed by the message text. For the 24 by 80 display mode, 76 characters
are displayed. For the 27 by 132 display mode, 128 characters are displayed.
Because both the message identifier and the message data are available from the
program message queue, message help and substitution text are supported for the
messages placed in a message subfile. If the SFLMSGRCD keyword is specified,
the SFLPGMQ and SFLMSGKEY keywords must also be specified.
The following shows an example of the DDS for a message subfile:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R MSGSFL SFL
A SFLMSGRCD(14)
A MSGKEY SFLMSGKEY
A PGMQ SFLPGMQ
A R MSGCTL SFLCTL(MSGSFL)
A SFLSIZ(8)
A SFLPAG(8)
A 5ð SFLDSP
A 55 SFLDSPCTL
A 6ð SFLINZ
A PGMQ SFLPGMQ
A NBR 4 ðH SFLRCDNBR(CURSOR)
A
Figure 4-9. Sample DDS for a Message Subfile
The SFLRCDNBR(CURSOR) keyword is used to position the cursor at the first dis-
played character in the message subfile that is specified in the SFLRCDNBR field
so the Roll Up and Roll Down keys will apply to the message subfile.
For information on sending and receiving messages and on the program message
queue, see the CL Programming book. Message subfiles are the only kind of sub-
files supported for CL programs and for ILE C programs.

Positioning the Cursor on the Displayed Subfile
The DSPATR(PC) keyword lets you position the cursor for each page of the subfile
record that is displayed. Write and update operations can be used to control
DSPATR(PC) for:
The initial display of subfile records. (A write or write-read operation to the
subfile control record when the SFLDSP and SFLDSPCTL keywords are used.)
Subfile records displayed using a roll key or a fold or truncate key (SFLDROP
or SFLFOLD keywords).
Positioning the Cursor Initially

The cursor is positioned by the first of the following conditions that applies:
The CSRLOC keyword on the subfile control record.
The DSPATR(PC) keyword within the records being displayed.
The DSPATR(PC) keyword within a field in the subfile control record.
The SFLRCDNBR(CURSOR) keyword within the subfile control record.
If nothing is specified, the cursor is positioned at the first input-capable field on
the display.
Note: If the keyboard is unlocked prior to the output operation that displays the
subfile, explicit cursor positioning is not performed.
Use the keywords in the following order:

The CSRLOC keyword can be used to position the cursor anywhere on the
screen.
The DSPATR(PC) keyword can be used to position the cursor at any field in
the first record displayed when the output operation specifies the SFLDSP
keyword.
The DSPATR(PC) keyword can be used to position the cursor at any field of
the subfile control record.
The SFLRCDNBR(CURSOR) keyword can be used to position the cursor at the
first input-capable field of the record whose record number is used to select
which page is to be displayed first. If no input fields exist, the cursor is posi-
tioned at the first selected output field in that record.
If neither the DSPATR(PC) nor SFLRCDNBR(CURSOR) keyword is used, the
cursor is positioned at the first input-capable field on the display.
Positioning the Cursor When a Roll Key Is Used

The positioning of the cursor when a roll key is used depends on whether the
DSPATR(PC) keyword is used:
If the DSPATR(PC) keyword is not used, the cursor is positioned at the same
location as when the roll key was pressed.
If the DSPATR(PC) keyword is used, the cursor is positioned at the first field in
the displayed subfile records with the DSPATR(PC) keyword in effect.
The following example illustrates both and shows part of the DDS for a subfile in
which records are displayed vertically. Customer number, name, address, city, and
state are displayed. A user can change customer name, address, city, and state.
Customer number cannot be changed; it is an output field only. The DSPATR(PC)
keyword has been specified for the customer number field (CUST). Subfile size is
21 and page size is 7.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R SUBFIL1 SFL
A TEXT('Subfile record')
A CUST 5 4 3DSPATR(PC)
A NAME 2ð B 4 1ðCHECK(LC)
A ADDR 2ð B 4 32CHECK(LC)
A CITY 2ð B 4 54CHECK(LC)
A STATE 2 B 4 76
A R FILCTL1 SFLCTL(SUBFIL1)
A 5ð SFLDSPCTL
A 55 SFLDSP
A SFLSIZ(21)
A SFLPAG(7)
A 6ð SFLCLR
A TEXT('Subfile control record')
A OVERLAY
A PROTECT
A CAð3(98 'End of program')
A 2 2'NUMBER'
A 2 1ð'NAME'
A 2 32'ADDRESS'
A 2 54'CITY'
A 2 76'STATE'
Figure 4-10. Sample DDS Using the DSPATR(PC) Keyword
The initial display looks like this:
Cursor
41394 Sorensen and Walton 500 5th Avenue New York NY

41395 Charland, Inc. 200 Madison Avenue New York NY
41316 Anderson’s Electric 950 2nd Avenue Atlanta GA
41397 Morem Motors 1300 Pine Street Atlanta GA
41398 Polt Electronics 240 Walters Place Chicago IL
41399 Clark’s TV 560 3rd Street Chicago IL
41400 Jim’s Repair 700 4th Avenue Chicago IL
RSLH709-0
The first seven records in the subfile are displayed and the cursor is positioned
under the customer number in the first record. The user moves the cursor to the
third record, updates the address for that customer, and moves the cursor to the
customer number of the fourth record:

Cursor Changed Field

41395 Charland, Inc. 200 Madison Avenue New York NY
41316 Anderson’s Electric 950 2nd Avenue Atlanta GA
41397 Morem Motors 1300 Pine Street Atlanta GA
41398 Polt Electronics 240 Walters Place Chicago IL
41399 Clark’s TV 560 3rd Street Chicago IL
41400 Jim’s Repair 700 4th Avenue Chicago IL
RSLH183-0
Now the user presses the Roll Up key to display the next seven records. The
cursor is positioned under the customer number in the first record:
Cursor

41405 Fixtures, Inc. 607 9th Avenue Chicago IL
41407 Electric House 903 East Place Atlanta GA
RSLH184-0
If the DSPATR(PC) keyword had not been specified and the user pressed the Roll
Up key, the cursor would have been positioned at the fourth record under customer
number:

Cursor

41405 Fixtures, Inc. 607 9th Avenue Chicago IL
41407 Electric House 903 East Place Atlanta GA
RSLH185-0
Positioning the Cursor When a Fold or Truncate Key Is Used

When you use the SFLFOLD or SFLDROP keyword to assign a CFnn or CAnn key,
cursor positioning is handled the same way as described under “Positioning the
Cursor When a Roll Key Is Used” on page 4-24. The cursor is positioned as speci-
fied for all displayed records, including those folded. When you use the SFLFOLD
or SFLDROP keyword to assign a CFnn or CAnn key, the cursor is positioned only
for those fields displayed. Cursor positioning specifications for fields in the folded
portion of the record are ignored.
Displayed
When you display two or more records at the same time, the position of the cursor
determines the action taken when the user presses a roll key, regardless of which
record was written to the display last.
The cursor can be positioned in the roll-enabled area of the display or in the area
that is not roll-enabled of the display. A roll-enabled area is:
A record without subfiles and with the ROLLUP/ROLLDOWN keyword in effect
A subfile control record with the ROLLUP/ROLLDOWN keyword in effect
A roll-enabled subfile, which is an active subfile with subfile size greater than
page size
An active subfile with subfile size equal to page size and the
ROLLUP/ROLLDOWN keyword in effect for its subfile control record
Based on the location of the cursor, the action taken when the user presses a roll
key is as follows:
If the cursor is positioned in the roll-enabled area at a roll-enabled subfile or at
the subfile control record for a roll-enabled subfile, the subfile is rolled. If the

subfile is at the end of the subfile and the corresponding ROLLUP/ROLLDOWN
keyword is not in effect, the end-of-subfile message is sent to the user. If the
ROLLUP/ROLLDOWN keyword is in effect at the end of the subfile, control
returns to the program.
If the cursor is positioned in the roll-enabled area at a record without subfiles
with the ROLLUP/ROLLDOWN keyword in effect, at a subfile control record
with the ROLLUP/ROLLDOWN keyword in effect, or at an active subfile with
subfile size equal to page size and the ROLLUP/ROLLDOWN keyword in effect
for the subfile control record, control returns to the program.
If the cursor is not positioned in the roll-enabled area, the system attempts to
find the uppermost roll-enabled area on the display and perform the action indi-
cated, as listed previously. If there is no roll-enabled area on the display, the
command-key-not-valid message is sent to the user.
Note: Records that do not occupy display space (record formats with no fields,
with hidden, program-to-system, or message fields only, or with the
CLRL keyword specified and no input-capable fields; and message sub-
files) are assumed to be at line 0. Therefore, these records are consid-
ered to be uppermost on the display, and the system attempts to roll
them first.
The following examples illustrate what action is taken, based on the location of the
cursor, when two records are displayed and the user presses a roll key.
In the following example, control returns to the program if the corresponding

ROLLUP/ROLLDOWN keyword is in effect. This occurs because the cursor is posi-
tioned at a record without subfiles and with the ROLLUP/ROLLDOWN keyword in
effect.

41395 Charland, Inc. 200 Madison Avenue New York NY Subfile
41316 Anderson’s Electric 950 2nd Avenue Atlanta GA with
41397 Morem Motors 1300 Pine Street Atlanta GA SFLSIZ>
41398 Polt Electronics 240 Walters Place Chicago IL + SFLPAG
Nonsubfile
Enter next customer number: Record with
ROLLUP/
ROLLDOWN
in Effect
RV2W050-0
Cursor
In the following example, two subfiles with the subfile size greater than the page
size and their control records are displayed. The user positions the cursor in the

bottom subfile control record. The bottom subfile is rolled because the cursor is
positioned at a roll-enabled subfile in the roll-enabled area of the display.

41402 Jane’s Radio/TV 135 Ransam Drive St Paul MN Subfile 1
41403 Advanced Electronics 809 8th Street St Paul MN with
41404 Riteway Repair 443 Western Lane New York NY SFLSIZ>
41405 Fixtures, Inc. 607 9th Avenue Chicago IL + SFLPAG
ORDER LINE TOTAL

NUMBER NUMBER NUMBER DESCRIPITON QTY Price PRICE Subfile 2
with
41401 35900 1 E35 Motor 10 15.00 150.00 SFLSIZ>
41401 35400 2 F60 Pump 25 20.00 500.00 SFLPAG
RV2W051-0
Cursor
In the following example, a subfile with the subfile size equal to the page size and
the ROLLUP/ROLLDOWN keyword in effect is written to the display first. A record
without subfiles and without the ROLLUP/ROLLDOWN keyword in effect is then
written to the display. If the cursor is positioned at either the subfile record or the
second record, control returns to the program.
Cursor

41395 Charland, Inc. 200 Madison Avenue New York NY Subfile
41316 Anderson’s Electric 950 2nd Avenue Atlanta GA with
41397 Morem Motors 1300 Pine Street Atlanta GA SFLSIZ>
41398 Polt Electronics 240 Walters Place Chicago IL + SFLPAG
Nonsubfile
Enter next customer number: Record without
ROLLUP/
ROLLDOWN
RV2W052-0

In the following example, the first subfile has a subfile size greater than the page
size but the ROLLUP/ROLLDOWN keyword is not specified. The second subfile
has a subfile size equal to the page size but the ROLLUP/ROLLDOWN keyword is
not specified. If the cursor is positioned at the second subfile, the first subfile is
rolled. In this position, the cursor is not in a roll-enabled area; therefore, the
system finds the uppermost roll-enabled area in the display and performs the roll
function.

Subfile with
41401 Adam’s Home Repair 121 Golden Circle Chicago IL SFLSIZ>
41402 Jane’s Radio/TV 135 Ransam Drive St Paul MN SFLPAG
and without
ROLLUP/
41405 Fixtures, Inc. 607 9th Avenue Chicago IL + ROLLDOWN
ORDER LINE TOTAL
NUMBER NUMBER NUMBER DESCRIPITON QTY Price PRICE Subfile with
41401 35900
SFLSIZ=
1 E35 Motor 10 15.00 150.00
41401 35400 SFLPAG
2 F60 Pump 25 20.00 500.00 and without
ROLLUP/
ROLLDOWN
RV2W053-1
Cursor
In the following example, the subfile with a subfile size greater than the page size
and without ROLLUP/ROLLDOWN keyword is written to the display first. The
record without subfiles and with ROLLUP/ROLLDOWN keyword in effect is then
written to the display above the subfile. If the cursor is positioned within the subfile
record, the subfile is rolled. If the cursor is not positioned within the subfile record,
the subfile is not rolled and control returns to the program.

Identifiers Highlight Command Prompt Exit Help
Select a Router identifier and press Enter.
==== Top-of-File ====
RTYP CMGR
RTYP Type of router.
==== Bottom-of-File ====
-------- common user ID.
RTDN Default system name.
RMTN Name of Remote LU alias.
LCLN Name of Local LU alias.
MODN Mode name information.
Enter Esc=Cancel F1=Help
RSLH054-0
Understanding Subfile DDS and Program Logic–Example

The following shows the DDS that describes the customer name search subfile
shown earlier in this section. The DDS is followed by a description of the logic a
program would use to process this subfile.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A\\ DISPLAY CUS22ðD CUSTOMER NAME SEARCH
A CFð3(99 'End of Program')
A R NAMESR OVERLAY
A 1 29'CUSTOMER NAME SEARCH'
A 3 2'Search code'
A SEARCH 5 I 3 15
A R SUBFIL1 SFL
A CUST 5 7 2
A NAME 2ð B 7 9
A ADDR 2ð B 7 31
A CITY 2ð B 7 53
A STATE 2 B 7 75
A R FILCTL SFLCTL(SUBFIL1)
A 55 SFLDSPCTL
A 5ð SFLDSP
A SFLSIZ(18)
A SFLPAG(6)
A 5ð SFLEND
A 6ð SFLCLR
A OVERLAY PROTECT
A RCDNBR 2 ðH SFLRCDNBR(CURSOR)
A 45 5 2'NUMBER'
A 45 5 9'NAME'
A 45 5 31'ADDRESS'
A 45 5 53'CITY'
A 45 5 75'STATE'
Figure 4-11. Sample DDS Showing Customer Name Search Subfile
The following is an example of the logic a user program would use to process the
subfile just shown. A write-read operation is a combined input and output opera-
tion. A read is an input operation. A write is an output operation. See the appro-
priate high-level language manual for the operations that can be performed in the
high-level language program.
User Program
1. Opens a file and issues a write-read operation to the NAMESR record format to
prompt for a search code.
User
2. Enters a zip code in the search code field. The program uses the search code
field as a key field to find the first database record in the file with that key field.
The program will build the subfile using that record as the first record in the
subfile.
User Program
3. Obtains records (read operation) from the database file and places (write oper-
ation to SUBFIL1) them in the subfile one record at a time until the subfile is
full or there are no more records to place in the subfile.
4. When all records are in the subfile, issues a write-read operation to the subfile
control record format (FILCTL) with the following:
a. A + (plus sign) is displayed in the lower right corner of the screen when
there are more records than fit on one subfile page. Because the indicator

for the SFLEND keyword is on, the system replaces the + with a blank
when the last subfile page is displayed.
b. The indicator for the SFLDSP keyword is on, so the first subfile page is
displayed.
c. The indicator for the SFLDSPCTL keyword is on, so the subfile control
record is displayed.
d. The SFLRCDNBR(CURSOR) keyword is specified for a field. The program
placed a value of 1 in this field, so the subfile page that contains relative
record number 1 is displayed first and the cursor is positioned at the first
input field in that record. (If no input field exists, the cursor is positioned at
the first selected output field or constant in that record.)
e. The constant field (heading line) indicators are on, so the constants in the
subfile control record are displayed.
f. The OVERLAY and PROTECT keywords are in effect in the subfile control
record so that the prompt (NAMESR) can remain on the display without
being changed.
User
5. Updates displayed records, using the roll keys to display different subfile
records as needed. Presses the Enter key after completing all updates to the
subfile.
User Program
6. Completes the input portion of the write-read operation to the subfile control
record format. In this example, the subfile control record does not contain any
input fields. The input portion of the write-read operation allows the display
station user to enter data into the subfile.
7. Issues the get-next-changed operation to the subfile record to process the first
subfile record changed by the user.
8. Uses each changed record to update the corresponding database file record.
9. Repeats steps 7 and 8 until a no-more-modified-records condition exists for
step 7. When this condition is detected, step 10 is performed.
10. Issues a write-read operation to the prompt (NAMESR) to determine if the
program should end or display another group of database records. The
OVERLAY keyword is specified, so that the current display contents for the
subfile are left unchanged. If the user presses the CF1 key, which turns on
response indicator 99, the program will close the display file and end. If the
user enters another search code for another group of records to be displayed,
step 11 is performed.
11. Issues a write operation to the subfile control record (FILCTL) with the fol-
lowing:
a. The indicator for the SFLCLR keyword is on, so the subfile is cleared of all
records (the display is unchanged).
b. The indicator for the SFLDSP keyword is off, so the contents of the display
remains unchanged.
c. The indicator for the SFLDSPCTL keyword is off, so the subfile control
record is not displayed again.
12. Repeats steps 3 through 10. The subfile was cleared (SFLCLR keyword) in
step 11 so that new records can be placed in the subfile. The write operation
to the subfile control record in step 4 has the constant field indicator off so that
heading information is not sent to the display again. As long as the subfile

control record remains on the display (no intervening write operations without
the OVERLAY keyword in effect have been performed), the fields do not have
to be sent to the display again.

Chapter 5. Defining Windows with Display Files
This chapter explains how to use the specialized DDS window keywords to create
windows in your applications. The DDS window keywords provide the simplest,
most flexible method of creating windows for a variety of purposes. For example,
they allow you to use subfiles to present data in windows, to have the system auto-
matically save and restore the underlying display, and to position data in the
window by referring to positions in the window itself instead of positions on the full
screen.
Use the DDS window keywords if your windows must use other DDS functions,
such as subfiles, display attributes, validity checking, and optioning. Also use the
DDS window keywords when the window contains multiple input fields, or if the
window location can be varied.
If you have help information defined with DDS and are using the HLPRCD keyword
to display it, the WINDOW keyword can be used to easily display the information in
a window.
The following sections describe the terminology used for windows, the functions of
the window keywords, and how to use the keywords for the following tasks:
Creating windows
Defining window borders
Reading data from windows
Changing window borders and contents
Moving and duplicating windows
Making two windows seem active at one time
Making one window in a series stand out
Removing windows
Improving application performance by bypassing system save and restore oper-
ations
For examples on using the window keywords, see “Programming Examples” on

page 5-15.
For some applications, you might want to use a different method of creating
windows:
Chapter 20, “Defining Online Help Information” on page 20-1 describes how to
create help windows with the user interface manager (UIM). The UIM uses a
different language from DDS. However, it automates many help window func-
tions for you and provides a simple way of adding online help information to
your existing applications.
The IBM WindowTool/400 PRPQ, SC41-0050, describes how to create
windows with the WindowTool/400 PRPQ. Consider using this program if you
use windows primarily to construct application menus.
Chapter 6, “Creating a Graphical Look for Displays” describes how to create
menu bars, pull-down menus, selection fields, continued-entry fields, and how
to use edit masks using DDS keywords.

Window Terminology
A window is information that overlays part of the display. The user can view infor-
mation inside the window and the portion of the display that is not overlayed by the
window. However, only the window is active; the user cannot work with the under-
lying display. When more than one window is displayed, only one window is active
at a time.
The active window is the window subject to the most recent input or output opera-
tion. The active window appears to be the topmost window on the display. It is the
only part of the display with which the work station user can interact.
A window remains on the display until your application or the system takes action
to remove it. Removing a window and overlaying a window are different oper-
ations. When a window is removed, it no longer exists on the display, and you can
no longer write to or read from it. When a window is overlayed by another
window, it might not be visible to the work station user; however, it is still available
for you to work with.
DDS Window Keywords

Four DDS keywords allow your applications to create and work with windows:
WINDOW (Window)
Creates a window on the display, changes the contents of an existing window,
or makes an existing but inactive window active again.
WDWBORDER (Window Border)
Specifies the color, display attributes, and characters of a window border.
WDWTITLE (Window Title)
Specifies the text, color, and display attributes for a title of a window. The title
is embedded in the top or bottom border of the window.
Note: Not all controllers support text in the bottom border of windows, nor the
left and right alignment of text in the top or bottom border.
RMVWDW (Remove Window)
Removes other windows from the display when a new window is displayed or
when an existing window is redisplayed as the active window.
USRRSTDSP (User Restore Display)
Prevents the OS/400 system from automatically saving and restoring the under-
lying display when windows are displayed and removed. In some situations,
save and restore operations are unnecessary; bypassing them speeds up your
application. You can also use the USRRSTDSP keyword to make an earlier
window in a series pop up and overlay later windows, and to make two windows
seem active at the same time.
For detailed reference information about each keyword, see the DDS Reference.

Window Representation and Hardware Configuration
Window borders appear differently, depending on the type of display station and
work station controller you are using.
For more information on how windows appear on different hardware configurations,

see “Hardware Configuration” on page 6-1.
Creating Windows
The record-level keyword WINDOW allows a record format to be displayed inside a
window. A maximum of 12 windows can be created on a display at one time.
To create a window, write a record that specifies a WINDOW keyword. The first
window record you write must be a window definition record specifying the window
size and its location on the display. The window definition record places the
window borders on the display. Then you can write the same window definition
record again or use one or more window reference records to complete the specifi-
cations for the window.
Window Definition Records

A window definition record is a record containing a WINDOW keyword that defines
the window size and location. Size and location attributes include the position of
the upper left corner of the window border and the number of rows and columns
within the window.
A window definition record must be the first record written for each window you
display. It is the record that actually creates the window and makes it visible on the
display. The record can contain the same types of fields or data found in any
typical record. It can also contain a WDWBORDER keyword defining the window
border. (The WDWBORDER keyword can also be used at the file level.)
You can supply all the specifications for the window in the window definition record.
You can supply additional specifications by writing the same window definition
record again, as you would when displaying an error message in the window. You
can also supply additional specifications by writing one or more window reference
records after you write the window definition record.
Window Reference Records

Window reference records provide additional data to be placed in the window.
They allow you to display more than one record format in a window.
Each window reference record contains a WINDOW keyword specifying the name
of the window definition record to which it applies. When the window reference
record is written, the window definition record being referred to must be on the
display. If the referenced record is not on the display, then a notify message
stating that the window does not exist is returned to the application.
Window reference records do not contain size and position attributes, and any
active WDWBORDER keywords are ignored.
Chapter 5. Defining Windows with Display Files 5-3

You can use as many window reference records as needed to complete the
window. However, you do not need to write any window reference records to
display a window. You can display a window using only a window definition record.
Window Size and Location

The following diagram shows the parts of a window that is created when a window
definition record is displayed:
┌───Left border attribute

│┌───Left border
││┌───Leading window attribute
│││┌───First window column
││││ ┌───Last window column
││││ │┌───Right border attribute
││││ ││┌───Right border
││││ │││┌───Right continuation
││││ ││││ attribute
6666 6666
L.......................R %─Top border
L:AwwwwwwwwwwwwwwwwwwwB:R %─First window row
L:AwwwwwwwwwwwwwwwwwwwB:R
L:AwwwwwwwwwwwwwwwwwwwB:R %─Last window row
L:AmmmmmmmmmmmmmmmmmmmB:R %─Message line
L:.....................:R %─Bottom border
Key:
L Left border attribute
. Top and bottom border
R Right continuation attribute
: Left and right border
A Leading window attribute
w Window area
m Message line
B Right border attribute
This window is specified as having a depth of 13 rows (also known as lines) and a
width of 19 columns (also known as positions). The usable area inside the window
borders is 12 rows deep and 19 columns wide. Row 13 is reserved for messages;
it cannot contain fields.
With its border, the window actually takes up additional rows and columns on the
display. All windows take up two more rows, one each for the top and bottom
borders. Most windows also take up six more columns:
Two for border attributes
Two for border characters
One for the leading window attribute
One for the continuation attribute on the right.

If a window starts and ends in the first and last columns of the full display, it takes
up only four more columns instead of six. If a window row overlays DBCS fields,
that row requires the six columns mentioned previously plus up to four more
columns for DBCS shift-out and shift-in characters on each side.
The window is positioned by the upper left corner of the border, which has a
starting row position equal to the top border row and a starting column position
equal to the left border column. Fields that do not fit within the window are diag-
nosed during file compilation. If the SLNO keyword is used and specifies the
starting line number, the DDS compiler flags any fields that do not fit within the
window. If *VAR is specified on the SLNO keyword and the run-time starting line
number does not allow the entire record to be displayed, an exception occurs.
The DDS compiler diagnoses window location problems when either the upper left
window line or upper left window position is specified as a constant. A run-time
error occurs if a dynamically positioned window does not fit on the display.
The special value, *DFT, can be specified in place of the start-line and start-
position parameters on the window keyword. *DFT indicates that the system will
determine the start line and start position of the window. The window is positioned
relative to the cursor location. The system uses the following sequence of rules to
position the window when *DFT is used:
1. If the window will fit below the cursor position on the display, it is placed there.
The top window border is positioned one row below the cursor. If possible, the
left window border is positioned in the same column as the cursor; if not, the
window is positioned as far to the left of the cursor as necessary for it to fit on
the display.
2. If the window will fit above the cursor position, it is placed there. The bottom
window border is positioned one row above the cursor. The window is posi-
tioned horizontally as described in step 1.
3. If the window will fit to the right of the cursor position, it is placed there. The
right window border is positioned in the next-to-last column of the display. If
possible, the top window border is positioned in the same row as the cursor; if
not, the window is positioned as far above that as necessary for it to fit on the
display.
4. If the window will fit to the left of the cursor position, it is placed there. The
right window border is positioned two columns to the left of the cursor. The
window is positioned vertically as described in step 3.
5. If the window cannot be positioned in any of the above areas, it is placed in the
bottom right corner of the display.
Cursor Position
To position the cursor in a window, use the CSRLOC and DSPATR(PC) keywords
in the same way as for a full-screen display. The cursor is positioned with refer-
ence to the upper left corner of the usable area of the window.
If *RSTCSR is specified on the WINDOW keyword, and the cursor is moved

outside the usable area of the active window, only the Print and Home command
function (CF) keys are active. If the work station user presses any other command
function (CF) key, the alarm sounds and the cursor is moved back to its position for
the previous write operation. *RSTCSR is the default.

Note: On display stations attached to a controller that supports an enhanced inter-
face for nonprogrammable work stations, the cursor can be moved out of a
window only with a mouse when *RSTCSR is specified.
If *NORSTCSR is specified on the WINDOW keyword, the user may move the
cursor out of the active window and use any command function (CF) or command
attention (CA) key.
Error Messages
When windows exist on a display and *MSGLIN is specified on the WINDOW
keyword for the window, any error messages are displayed on the last usable line
of the active window. The last usable line in the window is reserved for error mes-
sages; no records are displayed there. If the error message is longer than the line,
it is truncated to fit. When windows exist on a display and *NOMSGLIN is specified
on the WINDOW keyword for the window, any error messages are displayed at the
bottom of the display or the location defined by the MSGLOC keyword.
Help is available through the Help key for error messages displayed in windows.
When messages reporting operational and keyboard errors, such as Function key
not allowed, are displayed, the keyboard is locked and the user must press the
Error Reset key to continue.
An informational message, stating that mismatching shift-out and shift-in characters

were sent to the display, is placed in the job log under the following circumstances:
The base display has a DBCS field that spans more than one line.
A window is displayed and part of the DBCS field from the base display is on
the window message line.
A function key is pressed that results in an operational or keyboard error.
A few message-related keywords function differently when used for windows:

The ERRSFL keyword is ignored. Its function is performed only when there are
no windows on the display.
The MSGLOC keyword is ignored if *MSGLIN is specified on the WINDOW
keyword. Its function is performed only when there are no windows on the
display or when *NOMSGLIN is specified on the WINDOW keyword.
Messages resulting from the ERRMSGID, ERRMSG, SFLMSG, SFLMSGID,
and DDS validity-checking keywords are displayed in the window but do not
lock the keyboard. Such messages do lock the keyboard when displayed on
full-screen displays.
Subfiles
A maximum of 24 subfiles can be active at any one time. A maximum of 12 sub-
files can be displayed on the base display or in a single window at any one time.
If a subfile is displayed in a window and the window is removed from the display,
the subfile is not deleted. The subfile remains active until the display file is closed
or you explicitly delete the subfile.

DDS Help Records
If a window definition record is written to the display as a DDS help record, the
current display is suspended as it normally is for application help, and the applica-
tion help record is written to the display as a window. To avoid errors when using
window records as help records, adhere to these requirements:
Include the ASSUME keyword in the display file containing the help record. If
the ASSUME keyword is not present, the rest of the display is blank while the
help window is displayed.
Use a value of *YES for the Restore Display (RSTDSP) parameter when cre-
ating, changing, or overriding the display file. When returning from help,
RSTDSP(*YES) restores the suspended display and puts the cursor back
where it was when the Help key was pressed.
Use variable line and position values in your window definition record to allow
the operating system to position the help window dynamically, according to
cursor position. The system uses the same sequence of rules to position the
window as if *DFT were specified on the window keyword. These rules are
described in “Window Size and Location” on page 5-4. If the window definition
record specifies that only the line value or only the position value is variable,
the same rules are followed. However, the constant value is not changed.
Defining Window Borders

You can use the system defaults for your window borders or define them using the
WDWBORDER keyword. This keyword specifies three border components: color,
display attributes, and characters. More than one WDWBORDER keyword can be
specified. You can use option indicators with the WDWBORDER keyword.
You can use the WDWBORDER keyword at the file level, where it applies to each
window definition record in the file, or on individual window definition records. If
you use it on window reference records, a warning message is issued when the file
is created.
The following sections describe window border defaults, how the system handles
multiple window border definitions, and how to use the WDWBORDER keyword to
define UIM help window borders.
Border Defaults
When you do not use the WDWBORDER keyword, the system defaults are as
follows:
Border Element Default

Color Blue on color displays. On noncolor display
stations, this attribute is ignored.
Display attribute Normal (that is, no attributes such as high-
lighting or reverse image)
Top and bottom border character Period (.)
Left and right border character Colon (:)
Top left and right corner character Period (.)
Bottom left and right corner character Colon (:)

Note: RUMBA/400 work stations and InfoWindow* II display stations attached to a
controller that supports an enhanced interface have solid-line window
borders. For more information, see Table 6-1 on page 6-2.
Multiple Border Definitions

When the WDWBORDER keyword is specified at the file level and in a window
definition record, the parameter values of the keyword at the file and record level
are combined. If the parameter values conflict, the record-level parameter value is
used. For example, if the following is specified at the file level:
WDWBORDER((\COLOR RED) (\DSPATR RI))
and the following is specified at the record level:
WINDOW(2 5 1ð 2ð) +
WDWBORDER((\COLOR GRN) +
(\CHAR '........'))
then the window border consists of green periods in reverse image.
If more than one WDWBORDER keyword is specified at the same level, the param-
eters for the keywords that are in effect are combined. If different values are speci-
fied for the same parameter, the parameter value of the first keyword in effect is
used. The values for individual components of the border are determined when a
window definition record is written. The border values are determined by the fol-
lowing hierarchy:
1. Start with system defaults.
2. Override the defaults with any file-level border specifications.
3. Override any file-level border specifications with record-level border specifica-
tions.
The process is similar when more than one WDWBORDER keyword is in effect at
the same level and the keywords specify the same WDWBORDER component
(color, attribute, or character). The first component value is used. For example,
assume that two WDWBORDER keywords are in effect at the file level:
WDWBORDER((\COLOR GRN
\CHAR '........'))
WDWBORDER((\CHAR '---|||-|'))
and the following is specified at the record level:
WDWBORDER((\COLOR BLU))
then the border component values are determined as follows:
1. Start with the defaults for each component.
2. Override the character component and color component defaults with the file-
level values. Because the character component is specified more than once,
use the first character component value specified.
3. Override the file-level color value with the record-level value.
The window border is constructed using the record-level border color, the first file-
level border characters, and the default border display attributes.
If a single WDWBORDER keyword does not specify all three border components,
then those not specified use the values from any other WDWBORDER keywords in
effect; they do not use the defaults. In the preceding example, this is demonstrated
at the record level. Only the color component is specified. However, because the

character component is specified at the file level, the file-level value is used instead
of the default. Because the display attribute component is not specified at the
record or file level, the default is used.
UIM Help Window Borders

You can use the WDWBORDER keyword to specify the border attributes of help
windows created with UIM panel groups. Assume that you are using DDS for full-
screen displays and the UIM for help windows. If a window is on the display when
the Help key is pressed, the UIM help window has the same borders as the DDS
window. If no windows are active but the WDWBORDER keyword is specified at
the file level or at the record level of a nonwindow record currently on the display,
the system determines the border attribute and character values for the UIM help
window by combining the file-level, record-level, and default values. Assume that
no windows are currently displayed. First, a nonwindow record with the
WDWBORDER keyword specified is written to the display. A UIM help window is
then written to the display. The UIM help window borders use the attributes speci-
fied in the WDWBORDER keyword on the nonwindow record.
Defining a Window Title

Use the window title (WDWTITLE) keyword to specify the text, color, and display
attributes for a title of a window. The title is embedded in the top or bottom border
of the window. The length of the title can be up to the number of positions speci-
fied on the window-positions parameter specified on the associated window defi-
nition keyword.
Note: Some controllers do not support text in the bottom border of windows.
The WDWTITLE keyword must be specified on a record that contains a WINDOW

keyword (in the definition format). If a WINDOW keyword that refers to another
window is also specified, a warning message is issued.
Figure 5-1 shows an example of a window title.
à ð
NONWINDOW DISPLAY RECORD
............Window Title.............
: :
: WINDOW #1 :
: :
: CUSTOMER NO. nnnnnn : :
: :
: NAME: _ :
: ADDRESS: _ :
: PHONE: _ :
: :
: F12=CANCEL :
: :
:...................................:
F3=Xxxx F4=Xxxxxxxx F6=Xxxxx Xxxxx F7=Xxxx F12=CANCEL
á ñ
Figure 5-1. Window Title—Display Example

DDS for a Window Title—Example
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R RECORD1 WINDOW(6 15 18 51)
A Nð1 WDWTITLE((\TEXT &TTL1) (\COLOR GRN))
A ð1 WDWTITLE((\TEXT &TTL1) (\COLOR RED))
A FIELD1 5A B 2 2
A FIELD2 2ðA B 8 5
A TTL1 1ðA ðP
A\
A R RECORD2 WINDOW(8 2ð 9 3ð)
A WDWTITLE((\TEXT &TTL2) +
A (\COLOR YLW) +
A (\DSPATR RI))
A FIELD3 5A B 2 2
A FIELD4 2ðA B 8 5
A TTL2 1ðA ðP
Figure 5-2. DDS for a Window Title
If the window defined by RECORD1 in Figure 5-2 is written to the display, the title
will be whatever text is contained within the TTL1 field. The title will appear cen-
tered in the top border of the window. If indicator 01 is set off, the text will be
green. If indicator 01 is set on, the text will be red.
If the window defined by RECORD2 is written to the display, the the title will be
whatever text is contained within the TTL2 field. The title will appear centered in
the top border of the window. The title will be in reverse image and yellow.
Reading Data from Windows

When windows are on the display, you can receive input only from the active
window (that is, the last window written to the display). If your application reads a
window record and the window exists on the display but is not the active window,
then any windows subject to more recent input or output operations are removed.
The window containing the record to be read is restored, becoming the active
window. Then the record is read from the display.
If your application attempts to read a window record and the window does not exist
on the display, a notify message stating that the window does not exist is returned.
If the application attempts to read a window record and the window is on the
display but the record is not on the display, a message stating that the record is not
on the display is returned.
Changing Window Borders and Contents

To change the contents of a window already on the display, you must write that
window's window definition record or a window reference record specifying that
window to the display. To change the borders of a window already on the display,
you must write that window definition record to the display.
If a window definition record is written to the display and a window with that name
already exists on the display in the same position, a new window is not created.
The new record is considered a normal write operation to the existing window. If

the new record specifies different border attributes or characters, the new attributes
or characters are displayed when the record is written.
Moving and Duplicating Windows

If a window definition record is written to the display and a window with that name
already exists on the display in a different position, a new window is created. The
new window appears in the specified position and has the same name as the
existing window. To move the window, use the RMVWDW keyword in the window
definition record being written. The existing window with that name and any other
windows on the display are removed when the new window is written. In effect, the
window is moved. If you do not use the RMVWDW keyword, the same window
appears on the display in two different positions.
If a window reference record is written to the display and the specified window is on
the display, the record is written to the most recently created window with the spec-
ified name. To write to an earlier window with that name, use a window definition
record specifying the earlier window's location.
Making Two Windows Seem Active at Once

Although only one window can be truly active at a time, you can make two windows
appear to be active at once. You might use this to display two windows side by
side and allow the work station user to switch back and forth between them.
To make two windows appear active:

1. Set up function keys to perform the switching action for the work station user.
For example, you might provide one key to page through data in the first
window and another key to page through data in the second window.
2. Write the first window to the display.
3. Write the second window to the display using the USRRSTDSP keyword. The
USRRSTDSP keyword keeps the first window from being saved when the
second window is displayed. It keeps the second window from being removed
when the user returns to the first window and then keeps the first window from
being removed when the user returns to the second.
You can also use the USRRSTDSP keyword on the first window; it is not
required on the first window because using it on the second window keeps the
first window and all subsequent windows from being saved.
4. Be prepared to rebuild each window when the work station user presses the
keys that perform the switching action. Once the two windows are displayed,
you must rebuild each window whenever the user wants to move to it. The
USRRSTDSP keyword keeps both windows from being saved and restored, so
they must be rebuilt at every switch. In effect, the system does not know that
the previous window existed on the display.
For more information about the USRRSTDSP keyword, see “Improving Application
Performance” on page 5-13.

Making One Window in a Series Stand Out
Assume that you display a series of windows that looks like this:
┌─────────────────────────┐
│ 1 │
│ ┌──────────────────────┴──┐
│ │ 2 │
│ │ ┌──────────────────────┴──┐
│ │ │ 3 │
│ │ │ ┌──────────────────────┴──┐
└──┤ │ │ 4 │
│ │ │ ┌──────────────────────┴──┐
└──┤ │ │ 5 │
│ │ │ │
└──┤ │ │
│ │ │
└──┤ │
│ │
└─────────────────────────┘
Now you want to return to Window 3 and make it appear to pop out of the series,
so that the display looks like this:
┌─────────────────────────┐
│ 1 │
│ ┌──────────────────────┴──┐
│ │ 2 │
│ │ ┌──────────────────────┴──┐
│ │ │ 3 │
│ │ │ ├──┐
└──┤ │ │ │
│ │ ├──┴──┐
└──┤ │ │
│ │ │
└──┬──┬───────────────────┘ │
│ 4│ │
└──┤ │
│ 5 │
└─────────────────────────┘
To make Window 3 stand out without removing Windows 4 and 5 from the display,
take these steps:
1. Specify the USRRSTDSP keyword on Window 4 or any earlier window (that is,
Windows 1 through 3). The USRRSTDSP keyword prevents the previous
window and any subsequent windows from being saved.
2. Rebuild Window 3 so that it looks the way it did before Window 4 was first
displayed. Because USRRSTDSP was used, the display was not saved when
Window 4 was added to the display or at any later time. Thus, none of the
windows are removed from the display, and Window 3 appears to pop out of
the series.
For more information about the USRRSTDSP keyword, see “Improving Application
Performance” on page 5-13.
Removing Windows
When a window is removed, it no longer exists on the display, and you can no
longer write to or read from it. The window keywords provide you with several
different ways to remove windows. Which method you use depends on which
windows you want to remove and which operation you want to perform next. The
different methods are described in the following sections.

Removing All Windows
Remove all the windows on a display in one of these ways:
1. Write to a nonwindow record. This allows you to remove all existing windows
without displaying a new window.
2. Write to a window record that specifies the RMVWDW keyword. The
RMVWDW keyword causes all other windows on the display to be removed
when the specified window is displayed. If there are no other windows, the
RMVWDW keyword is ignored, and no error is returned.
Removing More Recent Windows

To remove more recent windows that are overlaying the window you want to make
active, read or write to the window you want to make active. Assume that Window
3 exists on the display but is not the active window. Windows 4, 5, and 6 were
subject to more recent write operations than Window 3; therefore, they overlay
Window 3. To remove Windows 4, 5, and 6 so that Window 3 is visible and is the
active window, read or write to Window 3.
Improving Application Performance

In some cases, you can improve application performance by using the
USRRSTDSP keyword to prevent the operating system from saving and restoring
the display. The following sections describe how the system performs the oper-
ations, and how and when to use the USRRSTDSP keyword.
System Save and Restore Operations

If you do not use the USRRSTDSP keyword, the operating system automatically
performs save and restore operations for your application. Before a window is dis-
played, the system saves the display, including any windows not being removed.
When windows are removed, the system restores the display.
If a new window is being created on the display, the record that is active when the
window is written is saved, and the entire display remains as background data.
Then the new window becomes active. The saved record can be a window record
or nonwindow record; the procedure is the same for both.
If a window record is written to the display to change or redisplay an existing

window, any more recent windows are removed without being saved, the target
window is restored, the new record is written, and the window becomes active.
If a nonwindow record is written to the display, any existing windows are removed
without being saved, the new record is written to the initial display, and the display
becomes active.
Response Time
The time needed for the system to perform save and restore operations depends
on your communications setup and on the window being displayed.
The slowest response time occurs during the read and save operations performed
when the first window is added to a display. Assume that the window is of average
size and complexity. If the work station is attached to the AS/400 system by a
twinaxial, local area network (LAN), or other high-speed communications line,

response time is quick. If the work station is attached by a 2400-baud dedicated
line, it takes approximately 10 seconds to complete the read and save operations
and then display the window. If the line speed is increased to 9600 baud, it usually
takes about 2.5 seconds.
Other operations, such as saving the display before the second or third window is
added, or restoring the display after windows are removed, take less time.
For more information, including details about other window sizes, terminal types,
and line speeds, consult your marketing representative.
Bypassing System Save and Restore Operations

You can use the USRRSTDSP keyword to bypass system save and restore pro-
cessing and instead have your application rebuild the display only when necessary.
This technique can improve system performance and response time for the user of
the application. Consider using it when you display only one window at a time and
the windows are in a different display file, or when you display a series of windows
in which the user will not return to earlier windows, or when you want more than
one window to seem active at one time.
For example, under the following conditions, the system ordinarily performs two
save operations:
Your application displays only one window at a time.
The display file is created with RSTDSP(*YES).
The first window record to overlay the display is located in a separate file.
The first save operation is performed when the display file is suspended. The
second save operation is performed because a window is being displayed.
USRRSTDSP eliminates the second, unnecessary save operation.
To bypass system save and restore processing, take these steps:

1. Create your own procedure to rebuild the display after a window is removed.
Be sure to include any data that the user enters and that must be redisplayed.
2. Specify the record-level USRRSTDSP keyword on the window following the first
window you do not want the system to save. The USRRSTDSP keyword
keeps the system from performing save and restore operations. The
USRRSTDSP keyword is allowed only on records containing the WINDOW
keyword; it is ignored on the window reference record.
Once the USRRSTDSP keyword is specified, it remains in effect, even if the
option indicator is set off, until you read or write to either the initial, windowless
display or the window that is two windows before the window on which the
USRRSTDSP keyword was specified.
Assume that six windows are on the display and the USRRSTDSP keyword
was specified on the fourth. To turn off USRRSTDSP and have the system
resume saving the display, you must write to the second window. As shown in
the diagram, the system has saved only the first two windows:

Display Files, Examples
┌─────────────────────────┐
│ 1. Saved │
│ ┌──────────────────────┴──┐
│ │ 2. Saved │
│ │ ┌──────────────────────┴──┐
│ │ │ 3. Not saved │
│ │ │ ┌──────────────────────┴──┐
└──┤ │ │ 4. USRRSTDSP; not saved │
│ │ │ ┌──────────────────────┴──┐
└──┤ │ │ 5. Not saved │
│ │ │ ┌──────────────────────┴──┐
└──┤ │ │ 6. Not saved │
│ │ │ │
└──┤ │ │
│ │ │
└──┤ │
│ │
└─────────────────────────┘
USRRSTDSP Keyword Processing and Interactions

The USRRSTDSP keyword interacts with other keywords and window-related func-
tions. Before using the keyword, you should understand the following (assume that
the USRRSTDSP keyword is in effect):
If a window record is written to a window that was saved (window 1 or 2 in the
above example), the saved display is restored, the current record is written to
the target window, and the target window becomes active. At this point, the
USRRSTDSP keyword is no longer in effect.
If a window definition record is written to a window that was not saved (window
3, 4, or 5 in the above example), it becomes a new window. It is merged with
the previous display image and written to the display. No windows are
removed.
If a window record is read from a window that was not saved (window 3, 4, or 5
in the above example), an error message is returned to the application.
If the initial display has been saved and the application writes to a window
record specifying the RMVWDW keyword, any existing windows are removed.
The new window is displayed on top of the initial display. The new window is
active, and USRRSTDSP is no longer in effect.
If the initial display is not saved and the application writes to a window record
that specifies the RMVWDW keyword, all existing windows are removed. The
new window is displayed on top of the initial display. The new window is
active, and USRRSTDSP is still in effect.
If a nonwindow record is written to the display and USRRSTDSP is specified on
the first window, then the window is not removed, and the nonwindow record
may overlay all or part of the window.
Programming Examples
The following sections illustrate the basic functions of the window keywords. The
first example shows how to use a variety of window functions. It defines a full-
screen display and several windows in one display file. The second example
shows how to create windows for a full-screen display defined in a separate display
file. The third example shows how to simulate menu bar support.

Using Basic Window Functions

The following scenario demonstrates the basic functions of the window keywords.
The scenario is presented in three sections:
The DDS used to define a full-screen display and windows
The RPG program used to display the full-screen display and windows
Discussion and illustration of the results
DDS Full-Screen Display and Window Definitions

The following DDS defines the initial display and two windows used in the scenario:
A\------------------------------------------------------------------------\
A\ DISPLAY FILE - DEMOFM
A\------------------------------------------------------------------------\
A\------------------------------------------------------------------------\
A\ FILE LEVEL KEYWORDS
A\------------------------------------------------------------------------\
A DSPSIZ(24 8ð \DS3)
A HELP
A\
A\------------------------------------------------------------------------\
A\ RECORDS USED IN DEFINING INITIAL DISPLAY
A\------------------------------------------------------------------------\
A R INITIAL
A CAð3(ð3)
A CAð4(ð4)
A CAð6(ð6)
A CAð7(ð7)
A CA12(12)
A CLRL(\ALL)
A 3 28'NONWINDOW DISPLAY RECORD'
A 6 1'FLD #1:'
A FLD48 3ðA B 6 9
A 6 43'FLD #2:'
A FLD49 15A B 6 51
A 1ð 1'FLD #3:'
A FLD5ð 3ðA B 1ð 9
A 1ð 43'FLD #4:'
A FLD51 15A B 1ð 51
A 23 1'F3=Xxxx'
A 23 13'F4=Xxxxxxxx'
A 23 29'F6=Xxxxx Xxxxx'
A 23 48'F7=Xxxx'
A 23 59'F12=CANCEL'
A\
A\------------------------------------------------------------------------\
A\ RECORDS USED IN DEFINING WINDOW1
A\------------------------------------------------------------------------\
A R WINDOW1 WINDOW(7 3 11 33)
A Nð1 WDWBORDER((\COLOR GRN))
A ð1 WDWBORDER((\COLOR RED))
A 2 13'WINDOW #1'
A 4 2'CUSTOMER NO.'
A FLD1 6A O 4 15
A 4 22':'
A\
A R REC2WIN1 WINDOW(WINDOW1)
A OVERLAY
A CA12(12)
A 1ð 2'F12=CANCEL'
A\
A OVERLAY
A 6 2'NAME:'
A FLD2 24A B 6 8
A 7 2'ADDRESS:'
A FLD3 21A B 7 11
A 8 2'PHONE:'
A FLD4 23A B 8 9

A\
A\------------------------------------------------------------------------\
A\ RECORDS USED IN DEFINING WINDOW2
A\------------------------------------------------------------------------\
A\
A 2 12'WINDOW #2'
A FLD5 22A O 4 6
A FLD6 25A O 5 4
A FLD7 25A O 6 4
A FLD8 25A O 7 4
A\
A OVERLAY
A CA12(12)
A 1ð 8'Xxxxxxx :'
A FLD9 6A B 1ð 18
A\
A\------------------------------------------------------------------------\
RPG Display Program

This RPG program displays the full-screen display and windows defined in the pre-
ceding section. Steps 1 through 5 are explained in the sections following the
program.
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
F\ RPG PROGRAM - WINDEMO
F\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
FDEMOFM CF E WORKSTN
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Step 1: Display Initial Display
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C EXFMTINITIAL
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Step 2: Display Window #1
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C MOVE 'nnnnnn' FLD1
C WRITEWINDOW1
C WRITEREC2WIN1
C EXFMTREC3WIN1
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Step 3: Display Window #2
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C MOVEL'Xxxxxxx 'TEMP16 16
C MOVE 'xxxx x x'TEMP16
C MOVELTEMP16 FLD5
C MOVE 'xxxxxx' FLD5
C\
C MOVEL'xxxxxx x'FLD6
C MOVEL'xx xxxx 'TEMP16
C MOVE 'xxx xxxx'TEMP16
C MOVELTEMP16 TEMP17 17
C MOVE ' ' TEMP17
C MOVE TEMP17 FLD6
C\
C MOVEL'xxxx xxx'FLD7
C MOVEL'xxxx x x'TEMP16
C MOVE 'x xxxx x'TEMP16
C MOVELTEMP16 TEMP17
C MOVE 'x' TEMP17
C MOVE TEMP17 FLD7
C\
C MOVEL'xxxxxxx 'FLD8
C MOVEL'xxxx xxx'TEMP16
C MOVE 'xx xxxxx'TEMP16
C MOVELTEMP16 TEMP17
C MOVE '.' TEMP17
C MOVE TEMP17 FLD8
C\
C WRITEWINDOW2
C EXFMTREC2WIN2

C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Step 4: Restore Window #1
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C EXFMTREC3WIN1
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ Step 5: Display Initial Display
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C READ INITIAL 91
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C\ End The RPG Program
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
C SETON LR
C\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
Step 1: Display Initial Display

The application creates the initial display without using a window keyword:
à ð
FLD #1: _ FLD #2: ____________
FLD #3: _ FLD #4: ____________
á ñ
Step 2: Display Window 1

The user types some data on the display and presses the Enter key. The applica-
tion writes to window definition record WINDOW1, which creates the window. Then
the application adds information to the window by writing to window reference
record REC2WIN1 and performing a write/read operation to window reference
record REC3WIN1.
Before the window is displayed, the system performs a read screen immediate
operation to obtain the display image and saves the underlying display. The
system performs a read screen immediate operation only when the first window is
added to the display. It performs a save operation each time a window is created.

à ð
FLD #1: DATA ENTERED HERE FLD #2: DATA ENTERED

.....................................
: :
: WINDOW #1 :
F : : FLD #4: DATA ENTERED
: :
: NAME: _ :
: ADDRESS: _ :
: PHONE: _ :
: :
: F12=CANCEL :
: :
:...................................:
á ñ
Step 3: Display Window 2

The user types some information and presses the Enter key. The application writes
to window definition record WINDOW2. WINDOW2 is not the active window, and it
is not currently on the display; therefore, the system saves the underlying display,
associating the saved data with WINDOW1. Then a new window is created. The
application adds information to the window by performing a write/read operation to
window record REC2WIN2.
à ð

.....................................
: :
: WINDOW ....................................
F : : : D
: CUSTOMER NO. nnnnn : WINDOW #2 :
: : :
: NAME: MY NAME : Xxxxxxx xxxx x xxxxxxx :
: ADDRESS: MY ADDRES : xxxxxx xxx xxxx xxx xxxx :
: PHONE: MY PHONE : xxxx xxxxxxx x xx xxxx xx :
: : xxxxxxx xxxx xxxxx xxxxx. :
: F12=CANCEL : :
: : :
:.................... : Xxxxxxx : _ :
: :
:..................................:
á ñ
Step 4: Restore Window 1

The user types some data and presses the Enter key. The application performs a
write/read operation to window record REC3WIN1. The record format name speci-
fied on the WINDOW keyword, WINDOW1, is not the active window. However, the
window is currently on the display; therefore, the system restores the saved display
associated with WINDOW1. The restore operation removes WINDOW2, which was
written after WINDOW1. Then REC3WIN1 is written to the restored window.

à ð

.....................................
: :
: WINDOW #1 :
F : : FLD #4: DATA ENTERED
: :
: NAME: MY NAME :
: ADDRESS: MY ADDRESS :
: PHONE: MY PHONE :
: :
: F12=CANCEL :
: :
:...................................:
á ñ

The user presses the Enter key. The application performs a read operation to the
initial display, which automatically removes the last window from the display.
à ð
á ñ
Defining Windows in a Separate Display File

The following sections show the DDS code for a full-screen display and window
and the procedural steps needed to use them. In contrast to the preceding
example, this example keeps the window records in a separate display file from the
file for the underlying display. This technique allows you to add windows for items,
such as help, to existing applications, without rewriting the display-file code for the
applications.
In the example, the application uses RSTDSP(*NO) to indicate that a save opera-
tion should not be done when a file is suspended. Because displaying a window
also performs a save operation, using RSTDSP(*NO) prevents two save operations

from being performed. Because removing the window restores the screen that was
present prior to the window operation, the application is not required to rebuild the
display after window processing. For more information on the USRRSTDSP
keyword, see the notes at the end of the example.
DDS Full-Screen Display and Window Definitions

A\---------------------------------------------------------------------\
A\ DISPLAY FILE DISPLAY1 (RSTDSP=NO DFRWRT=\YES)
A\---------------------------------------------------------------------\
A R REC1
A 2 21'FIRST RECORD IN FILE'
A 4 17'Current Customer #:'
A FIELD1 6A B 4 38
A\
A R REC2 OVERLAY CAð3(ð3)
A 6 21'SECOND RECORD IN FILE'
A 8 17'Current Customer #:'
A FIELD2 6A B 8 39DSPATR(HI)
A 24 ð2'CAð3=EXIT'
A\---------------------------------------------------------------------\
RPG Program Source

FDISPLAY1CF E
C WRITEREC1
C WRITEREC2
C RETRY TAG
C READ REC2 9ð
C ð3 GOTO END
C CALL 'WINPGM'
C GOTO RETRY
C END TAG
C SETON LR
A\---------------------------------------------------------------------\
A\ DISPLAY FILE DISPLAY2 (RSTDSP=NO)
A\---------------------------------------------------------------------\
A Nð1 WDWBORDER((\COLOR GRN))
A ð1 WDWBORDER((\COLOR RED))
A 2 9'Window #1'
A \
A CA12(12) OVERLAY
A 4 1'Customer No. nnnnnn:'
A 6 1'Name:'
A FIELD3 19A B 6 7
A 7 1'Address:'
A FIELD4 16A B 7 1ð
A 8 1'Phone:'
A FIELD5 18A B 8 8
A 1ð 1'F12=Cancel'
A\---------------------------------------------------------------------\
A\ Dummy record to remove window from display before returning
A\---------------------------------------------------------------------\
A R RMVWDW CLRL(\NO) OVERLAY FRCDTA
A\---------------------------------------------------------------------\
A\ No I/O will ever be done to this record. This record prevents the
A\ display from clearing.
A\---------------------------------------------------------------------\
A R DUMMY ASSUME
A 11 1' '
A\---------------------------------------------------------------------\

RPG Program Source for WINPGM

FDISPLAY1CF E
C WRITEWINDOW1
C EXFMTREC3WIN1
C WRITERMVWDW
C RETRN
C SETON LR

The application opens display file DISPLAY1, performs a write operation to record
REC1, and performs a write/read operation to REC2.
à ð
FIRST RECORD IN FILE
Current Customer #: ______
SECOND RECORD IN FILE
Previous Customer #: ______
á ñ
Step 2: Display a Window

The user enters data indicating that a window should be displayed. The application
opens window display file DISPLAY2. This can be done from a separate program
such as the one which displayed the screen in Step 1. The ASSUME keyword on
record DUMMY keeps the full-screen display from being cleared, and the system
marks display file DISPLAY2 as suspended. No I/O operation ever needs to be
performed to record DUMMY; it only needs to be present in the file.
The application performs a write operation to record WINDOW1. Display file

DISPLAY1 is suspended; because of the RSTDSP(*NO) setting, no save is per-
formed. Display file DISPLAY2 is restored; because of the RSTDSP(*NO) setting,
no restore data is sent.
The application performs a write operation to record REC2WIN1.

à ð
Current Customer #: xxxxxx

.............................
: : #: xxxxxx
: Window #1 :
: :
: Customer No. nnnnnn: :
: :
: Name: ___________________ :
: Address: ________________ :
: Phone: __________________ :
: :
: F12=Cancel :
: :
:...........................:
á ñ
Step 3: Return to the Initial Display

The user enters data indicating that the application should return to the initial
display file, DISPLAY1. The application performs a write operation to record
RMVWDW, which causes the system to remove all windows from the display.
Because the application does not close the DISPLAY2 display file, and the
USRRSTDSP keyword is not specified, then removing the window restores the
initial display. The application is not required to rebuild the initial display. The
RMVWDW record should contain the FRCDTA keyword or specify DFRWRT(*NO)
when the display file is created.
The application performs a write operation to record REC1. Display file DISPLAY2
is suspended; because of the RSTDSP(*NO) setting, no save operation is per-
formed. Display file DISPLAY1 is restored; because of the RSTDSP(*NO) setting,
no data is sent.
The application performs a write/read operation to record REC2.

à ð
Current Customer #: ______
Previous Customer #: ______
á ñ
Additional notes on this example:
1. If the application closes DISPLAY2 in Step 3, then the application must rebuild
the initial display by performing a write operation to REC1 and then a write/read
operation to REC2. This can be avoided by specifying RSTDSP(*YES) for
DISPLAY1.
2. USRRSTDSP can be added to the window record in DISPLAY2. However, if
this is done, the user must either specify RSTDSP(*YES) for DISPLAY1, or
rebuild the initial display in Step 3. However, in Step 3, the application must
still write RMVWDW, or the borders of the window are not displayed properly
on the next write operation to the window.
3. The KEEP keyword should be added to the window format both of the following
conditions are true:
The application closes DISPLAY2 in Step 3.
No I/O is done to file DISPLAY1 prior to opening DISPLAY2 and displaying
the window again.

Chapter 6. Creating a Graphical Look for Displays
The graphical look is a change in what you see while you run DDS functions.
Instead of dotted windows, you have crisp window borders. Instead of typing
numbers in an option column to make a selection, you can use a mouse or mne-
monics. A mnemonic is an underlined character within the text of a choice that
you can type to select the choice. Instead of seeing option numbers, you can see
radio buttons or check boxes. A radio button is a circle that precedes a choice in
a single-choice selection field on a graphical display station. A check box is a
square box that precedes a choice in a multiple-choice selection field on a graph-
ical display station. You can click on radio buttons and check boxes to make
choices.
.........
: :
: 1. Undo : Undo
: 2. Mark : Mark
: Undo
3. Copy : Copy
: : Mark
.........
Copy
RV2W063-0
Figure 6-1. Radio Buttons and Check Boxes
In addition to a fresher look, the enhanced function includes menu bars and pull-
down menus. Instead of having to simulate a menu bar by using lengthy DDS
coding, you can use DDS keywords.
Factors Affecting the Graphical Look

The graphical functions described in this chapter appear differently, depending on
the hardware configuration you have and the value you specify on the enhanced
display (ENHDSP) parameter.
Hardware Configuration
Table 6-1 on page 6-2 and Table 6-2 on page 6-3 show how each graphical func-
tion appears on different configurations. Letters A through F in the tables identify
the configurations; these letters are referred to throughout this chapter.

Table 6-1. Functions Supported by Hardware Configurations A, B, and C
A B C
InfoWindow II
Graphical User Inter- Display Station2 3477 Display Station
face (GUI) Program- Attached to Con- Attached to Controller
mable Work troller Supporting Supporting Enhanced
Function Stations1 Enhanced Interface3 Interface3
Windows9 GUI4 windows and Character-based GUI5 Character windows and
possible improvement and possible improve- possible improvement in
in performance ment in performance performance
Selection fields and GUI4 Character-based GUI5 Mnemonics, bar
menu bars selection cursor
Selection lists Bar selection cursor. Bar selection cursor. Bar selection cursor.
Possible check boxes Possible check boxes Input field to the left of
for multiple-choice for multiple-choice list.
lists. Possible radio lists. Possible radio
buttons for single- buttons for single-
choice lists. choice lists.
Continued-entry One field One field One field
fields
Edit masks Yes Yes Yes
Highlighting Yes Yes Yes
Cursor progression Yes Yes Yes
Word spill Yes8 Yes Yes
Simple hotspots Yes Yes No
Scroll bars GUI 4 scroll bars Character-based GUI *MORE, *PLUS, or char-
5 scroll bars acter scroll
bars 6
Push buttons Yes Yes Yes
Auto-Selection Yes Yes Yes
Auto-Enter Yes Yes Yes
Programmable Yes8 Yes No
Mouse Buttons
Grid Lines7 No No No
Notes:
1. For example, RUMBA/400 (Microsoft Windows** and OS/2*) and AIX* AS/400 Connection
Program/6000 Release 2.
2. InfoWindow II display stations: 3486, 3487, 3488.
3. Twinaxial controllers: 5494 Release 1.1, and features 6050, 2661, 9146, and 9148.
4. GUI includes solid-line window borders, selectable background colors, use of a pointer device (for
example, a mouse), mnemonic selection, bar selection cursor, radio buttons (for single-choice
selection fields), and check boxes (for multiple-choice selection fields).
5. Character-based GUI is similar to GUI except that in character-based GUI, constructs are created
using characters, and background colors are not selectable.
6. Scroll bars that appear on display stations without pointing devices are for display purposes only.
7. Grid lines are supported only on DBCS display stations. For the specific hardware required for grid
lines, see “Hardware Requirements for Grid Line Structures” on page 6-82.
8. RUMBA/400 does not currently support this function.
9. RUMBA/400 does not currently support window footers.

Table 6-2. Functions Supported by Hardware Configurations D, E, and F
D E F
ASCII Display
5250 Display Station Attached Any Display Station
Station Attached to ASCII Controller Attached to Con-
to Controller Sup- Supporting troller Not Sup-
porting Enhanced Enhanced Inter- porting Enhanced
Function Interface1 face2 Interface3
Windows7 Character windows Character windows Character windows
and possible and possible
improvement in per- improvement in per-
formance formance
Selection fields Bar selection cursor Bar selection cursor Entry field driven
and menu bars
Selection lists Bar selection Bar selection Input field to the left
cursor. Input field cursor. Input field of list.
to the left of list. to the left of list.
Continued-entry One field One field Multiple fields
fields
Edit masks Yes Yes Ignored
Highlighting Yes Yes Ignored
Cursor Yes Yes Ignored
progression
Word spill6 Yes Yes Ignored
Simple hotspots No No No
Scroll bars *MORE, *PLUS, or *MORE, *PLUS, or *MORE, *PLUS, or
character scroll bars character scroll bars character scroll
4 4 bars 4
Push buttons Yes Yes Yes
Auto-Selection Yes Yes No
Auto-Enter Yes Yes Yes
Programmable No No No
Mouse Buttons
Grid Lines5 No No No
Notes:
1. Twinaxial controllers: 5494 Release 1.1, and features 6050, 2661, 9146, and 9148.
2. ASCII controllers that support an enhanced interface: features 6041, 6141, 2637, 9145,
9147.
3. For example: 5250 display stations attached to 5294 and 5394 controllers or features
2638, 6040, and 6140; some programmable work stations emulating a controller with an
attached 5250 display station (for example, Client Access).
4. Scroll bars that appear on display stations without pointing devices are for display pur-
poses only.
5. Grid lines are supported only on DBCS display stations. For the specific hardware
required for grid lines, see “Hardware Requirements for Grid Line Structures” on
page 6-82.
6. RUMBA/400 does not currently support this function.
7. RUMBA/400 does not currently support window footers.
Chapter 6. Creating a Graphical Look for Displays 6-3

Enhanced Display Parameter
The enhanced display (ENHDSP) parameter can be used with the CRTDSPF,
CHGDSPF, and OVRDSPF commands. Use this parameter to specify whether the
data being shown at a display station uses the enhanced capabilities available on
the display station.
Normally, DDS windows and CUA* graphical items are rendered using whatever
enhanced capabilities are available on the display station. For example, window
borders and menu-bar separators are presented graphically on a graphical display
station.
You can use ENHDSP(*NO) to cause all records defined in the display file to be
displayed in character-based mode, regardless of the capabilities of the display
station. When ENHDSP(*NO) is specified, none of the enhanced capabilities that
may be available on a particular display station are used. That is, records display
just as they would on a display station in configuration F in Table 6-2 on page 6-3.
The default value for ENHDSP is *YES. Any enhanced capabilities of the display
station are taken advantage of automatically. If you specify ENHDSP(*YES) and
you use the default window border and menu-bar separator, the window border and
the menu-bar separator appear as solid lines. If the display station is attached to a
controller that does not support an enhanced interface for nonprogrammable work
stations, ENHDSP(*YES) is ignored. The records in the display file are displayed
on that display station in character-based mode (as if ENHDSP(*NO) were speci-
fied).
Writing records from files with ENHDSP(*YES) and files with ENHDSP(*NO) to
the same display. If the record (or records) displayed is from a file with
ENHDSP(*YES), the first write operation of a record (such as a window) from a file
with ENHDSP(*NO) causes all menu bars, pull-down menus, and other windows on
the display to change from graphical to character-based. The records from the file
with ENHDSP(*YES) are switched to the ENHDSP(*NO) mode of display.
If the record displayed is from a file with ENHDSP(*NO), a write operation of a

record (such as a window) from a file with ENHDSP(*YES) does not change the
presentation of any menu bars, pull-down menus, or other windows on the display.
Notes:
1. The system file that is used for UIM help is shipped with ENHDSP(*NO). If you
use UIM help with a file that has ENHDSP(*YES) specified, the display will
changes from graphical to character-based.
2. Some programmable work stations that support an enhanced interface ignore
the window border and menu-bar separator keywords.
3. If a window is written to the display station such that a border is in column 1,
column 80 (for display size 24 by 80), or column 132 (for display size 27 by
132), the window is always displayed as though ENHDSP(*NO) were specified.

DDS Keywords
The tasks in this chapter refer to the DDS keywords, but may not provide all the
details about them. For more information on each keyword, refer to the DDS Ref-
erence.
CCSID (Coded Character Set Identifier)
Specifies that a “G” type field supports UCS-2 Level 1 data instead of
DBCS-graphical data.
CHCACCEL (Choice Accelerator Text)
Specifies the text for the accelerator key on a single-choice selection field in a
pull-down record.
CHCAVAIL (Choice Color/Display Attribute when Available)
Specifies the color or display attributes to be used when displaying the available
choices in a menu bar or selection field.
CHCCTL (Choice Control)
Controls the availability of the choices for the field.
CHCSLT (Choice Color/Display Attribute when Selected)
Specifies the color or display attributes to be used when displaying a selected
choice in a menu bar.
CHCUNAVAIL (Choice Color/Display Attribute when Unavailable)
Specifies the color or display attributes to be used when displaying the unavail-
able choices in a selection field.
CHOICE (Selection Field Choice)
Defines a choice for a selection field.
CNTFLD (Continued-Entry Field)
Defines a field as a continued-entry field. Continued-entry fields are sets of
associated entry fields that are treated by the work station controller as a single-
entry field during field data entry and editing.
EDTMSK (Edit Mask)
Defines an edit mask for fields with EDTCDE or EDTWRD keywords.
ENTFLDATR (Entry-Field Attribute)
Defines the leading attribute of the field that changes to a specified attribute
whenever the cursor enters the field. When defined at both the field- and
record-level, the field-level specification is used for the field.
FLDCSRPRG (Cursor Progression Field)
Defines the next field that the cursor moves to when exiting this field.
GRDATR (Grid Line Attribute)
Defines the color and line-type attributes for grid line structures in the file or
record.
GRDBOX (Grid Box)
Defines the shape, positioning, and attributes of a box.
GRDCLR (Grid Clear)
Defines a rectangular area on a display within which all grid structures are
erased.
GRDLIN (Grid Line)
Defines the shape, positioning, and attributes of a grid line.

GRDRCD (Grid Record)
Specifies that this record defines grid structures. No other display fields are
allowed on records with this keyword.
HLPID (Help Identifier)
Specifies an identifier for the constant in the help for a field.
HTML (Hyper Text Markup Language)
Specifies if a data stream is sent to an AS/400 5250 Workstation Gateway
display, the HTML tags are sent along with the data stream. These HTML tags
are processed on the HTML browser. This allows you to update applications to
use on the Internet through the World Wide Web.
MLTCHCFLD (Multiple-Choice Selection Field)
Defines a field as a multiple-choice selection field. A multiple-choice selection
field is a field that contains a fixed number of choices from which a user can
select multiple choices.
MNUBAR (Menu Bar)
Defines a menu bar. A menu bar is a horizontal list of choices that is followed
by a separator line.
MNUBARCHC (Menu-Bar Choice)
Defines a choice for a menu-bar field. A menu-bar choice represents a group of
related actions that the application user can select.
MNUBARDSP (Menu-Bar Display)
Displays the menu bar.
MNUBARSEP (Menu-Bar Separator)
Specifies the color, display attributes, or character used to form the menu-bar
separator line.
MNUBARSW (Menu-Bar Switch Key)
Assigns a CA key to the Switch-to-menu-bar key.
MNUCNL (Menu Cancel Key)
Assigns a CA key to be the cancel key for menu bars or pull-down menus.
MOUBTN (Programmable Mouse Button)
Allows an attention indicator (AID) to be associated with various pointer device
events.
PSHBTNCHC (Push Button Choice)
Defines a push button within a push button field.
PSHBTNFLD (Push Button Field)
Defines a field as a push button field. A push button field is a field that contains
a fixed number of push buttons. A push button is a button, labeled with text,
graphics, or both that represents an action that starts when a user selects the
push button.
PULLDOWN (Pull-Down Menu)
Defines a record as a pull-down menu for a menu bar.
SFLCSRPRG (Subfile Cursor Progression)
Causes the cursor to move to the same input field in the next subfile record
when exiting this field.
SFLCHCCTL (Subfile Choice Control)
Controls the availability of the choices in a selection list.

SFLEND (Subfile End)
Displays a plus sign (+) or text (More... or Bottom) in the lower right location of
the subfile. It can also display a scroll bar.
SFLMLTCHC (Subfile Multiple-Choice Selection List)
Defines a subfile as a multiple-choice selection list. A multiple-choice
selection list is a potentially scrollable list from which the user can select one
or more items.
SFLRCDNBR (Subfile Record Number)
Displays the page of the subfile containing the record whose relative record
number is in this field.
SFLRTNSEL (Subfile Return Selected Choice)
Returns all selected choices in a selection list using the get-next-changed oper-
ation.
SFLSCROLL (Subfile Scroll)
Returns the relative record number of the subfile record that is at the top of the
subfile when control is given to the application.
SFLSIZ (Subfile Size)
Specifies the number of records in the subfile.
SFLSNGCHC (Subfile Single-Choice Selection List)
Defines a subfile as a single-choice selection list. A single-choice selection
list is a potentially scrollable list from which the user can select one item.
SNGCHCFLD (Single-Choice Selection Field)
Defines a field as a single-choice selection field. A single-choice selection field
is a field that contains a fixed number of choices from which a user can select
one choice.
Creating Menu Bars

Figure 6-2 shows an example of a menu bar, which is a horizontal list of choices
that appears at the top of a display. An optional menu-bar separator appears
below the list. When you select a choice from the menu bar, a pull-down menu
appears. A pull-down menu is a group of actions associated with a menu-bar
choice.
à ð
.File/ Edit View Options Help
______________________________________________________________________________
Figure 6-2. Example of a Menu Bar
Defining the Menu-Bar Choices

A menu bar is a special type of record containing a MNUBAR keyword and one
menu-bar field. The menu-bar field is a numeric field containing one or more
MNUBARCHC keywords. The MNUBARCHC keywords define the menu-bar
choices and the pull-down menus associated with each choice. The menu bar
always displays on the first line. The menu-bar record cannot contain any display-
able fields other than the menu-bar field.

The number of rows occupied by the menu bar is determined by the number of
choices, the maximum lengths of the choice text for all the menu-bar choices, and
whether a menu-bar separator is specified. If you specify a menu-bar separator
(the default), the number of rows the menu bar occupies (including the menu-bar
separator) must be less than or equal to 12. If you do not specify a menu-bar
separator, the number of rows the menu bar occupies must be less than or equal to
11. It is not possible to extend the range of menu-bar choices to line 12. However,
you can use line 12 for another record.
If you define a pull-down record that is too large to fit beneath the maximum
number of rows occupied by the menu bar, the file is not created.
Suppressing the Menu-Bar Separator

The default is for a menu-bar separator to display. To suppress the menu-bar sep-
arator, specify MNUBAR(*NOSEPARATOR). If you suppress the menu-bar sepa-
rator, you cannot specify the menu-bar separator (MNUBARSEP) keyword.
Defining the Menu-Bar Separator

You can use the system defaults for the menu-bar separator or you can use the
MNUBARSEP keyword. Using MNUBARSEP, you can specify the color and
display attributes of the menu-bar separator and the character that makes up the
separator. The default presentation of the menu-bar separator is a solid line on
display stations in configurations A and B in Table 6-1 on page 6-2. The default
character that makes up the menu-bar separator is an underline (_) on display
stations in configuration C in Table 6-1 on page 6-2, and configurations D, E, and
F in Table 6-2 on page 6-3. For an example of using the MNUBARSEP keyword,
see Figure 6-3 on page 6-9.
Note: The menu-bar separator is used as the top border of the pull-down menus.
Its color does not change when a pull-down menu is displayed. To ensure
a consistent appearance for your displays, use the same color and display
attributes for both the menu-bar separator and the pull-down menu borders.
Figure 6-3 on page 6-9 shows an example of the DDS for a menu bar.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R MENUBAR MNUBAR
A MNUFLD 2Y ðB 1 2
A MNUBARCHC(1 PULLFILE +
A '>File ')
A ð2 MNUBARCHC(2 PULLEDIT +
A &EDITTXT)
A MNUBARCHC(3 PULLVIEW +
A '>View ')
A ð4 MNUBARCHC(4 PULLOPT +
A '>Options ' +
A &RTNFLD)
A MNUBARCHC(5 PULLHELP +
A '>Help ')
A MNUBARSEP((\COLOR WHT))
A EDITTXT 2ðA P
A RTNFLD 2Y ðH
A .
A .
A .
Figure 6-3. DDS for a Menu Bar. Assume that field EDITTXT contains the text >Edit.
You can control which menu-bar choices are displayed by specifying option indica-
tors on the MNUBARCHC keywords. Option indicators are used by the application
program to specify if a menu-bar choice should be displayed (optioned on) or
should not be displayed (optioned off). The DDS for option indicators are shown in
Figure 6-3 on page 6-9. The application specifies the option indicators as on or off
and then writes the menu-bar record (without MNUBARDSP in effect) to send the
option indicators to the system. If a menu-bar choice is optioned off, the list of
choices is compressed. However, the number of rows occupied by the menu-bar
record is not compressed (because records cannot be variable length). The
number of rows occupied by the menu bar is the number of rows needed if all the
choices were displayed plus one row for the menu bar separator. If, through
optioning, the list of choices is compressed so that it is displayed using fewer rows,
the separator line is displayed on the line following the last row of choices. There
are blank lines between the menu-bar separator and the next record on the display.
The text which appears for each choice in a menu-bar comes from either the
program-to-system fields named or the text specified for the choice text parameter
of the MNUBARCHC keyword. The number of rows calculated by the system for
the menu-bar record depends on the size of each program-to-system field or length
of choice text. In addition, three spaces are assumed between each choice. Any
trailing blanks in the choice text are removed; the remaining length is used for the
calculation. The length of any program-to-system field is used as is, because
trailing blanks can not be anticipated. However, when the menu-bar record is dis-
played, any trailing blanks are removed. Therefore, the number of rows actually
occupied could be less than the number calculated. When that occurs, blank lines
appear between the menu-bar separator and the next record on the display.
On display stations in configurations A and B from Table 6-1 on page 6-2, the
menu bar looks like this:

à ð
______________________________________________________________________________
Figure 6-4. Menu Bar on a Graphical Display Station with Enhanced Interface
On display stations in configuration C from Table 6-1 on page 6-2, the menu bar
looks like this:
à ð
-------------------------------------------------------------------------------
Figure 6-5. Menu Bar on a Nongraphical Display Station with Underline Capability
On display stations in configurations D and E from Table 6-2 on page 6-3, the
menu bar looks like this:
à ð
-------------------------------------------------------------------------------
Figure 6-6. Menu Bar on a Nongraphical Display Station without Underline Capability
On display stations in configuration F from Table 6-2 on page 6-3, the menu bar
looks like this:
à ð
File Edit View Options Help
-------------------------------------------------------------------------------
Figure 6-7. Menu Bar on a Display Station without Enhanced Interface
Selection Fields—Overview
There are two types of selection fields: single-choice and multiple-choice.
Single-choice selection fields and multiple-choice selection fields contain a

fixed group of choices displayed in a vertical or horizontal list. You can select any
number of choices from the multiple-choice selection field. You can only make one
choice from the single-choice selection field.
selection fields (vertical format) look like this:

RV2W860-1
Figure 6-8. Selection Fields on a Graphical Display Station with Enhanced Interface

On display stations in configuration C from Table 6-1 on page 6-2 and configura-
tions D, E, and F from Table 6-2 on page 6-3, the selection fields (vertical format)
look like this:
RV2W070-0
Figure 6-9. Selection Fields on a Nongraphical Display Station
DDS for Selection Fields—Example

Figure 6-10 on page 6-13 shows an example of the DDS for both single-choice
and multiple-choice selection fields.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R RECORD
A 2 3ð'Display Title'
A 4 5'Single selection field . . . :'
A F1 2Y ðB 4 4ðSNGCHCFLD
A CHOICE(1 '>One')
A CHCCTL(1 &CTLONE1 MSG1111 QUSER/A)
A ð1 CHOICE(2 '>Two')
A CHCCTL(2 &CTLTWO1 &MSG1 &LIB/&MSGF)
A CHOICE(3 'T>hree')
A CHCCTL(3 &CTLTHR1)
A CTLONE1 1Y ðH
A CTLTWO1 1Y ðH
A CTLTHR1 1Y ðH
A MSG1 7A P
A LIB 1ðA P
A MSGF 1ðA P
A 8 5'Multiple selection field . . . :'
A F2 2Y ðB 8 4ðMLTCHCFLD
A CHOICE(1 '>One')
A CHCCTL(1 &CTLONE2 MSG1112 QUSER/A)
A CHCCTL(2 &CTLTWO2 &MSG2 &LIB/&MSGF)
A CHCCTL(3 &CTLTHR2)
A CTLONE2 1Y ðH
A CTLTWO2 1Y ðH
A CTLTHR2 1Y ðH
A MSG2 7A P
Figure 6-10. DDS for Single-Choice and Multiple-Choice Selection Fields
Creating a Vertical Single-Choice Selection Field

You can define the number of choices and the selection numbers for each choice.
choices are preceded by radio buttons. This is true unless *NOSLTIND is specified
on the SNGCHCFLD keyword. A blank line appears between choices that are not
sequential. The location that you specify for the single-choice selection field is the
location of the input field (on a character-based nongraphical display). On display
stations in configurations A and B from Table 6-1 on page 6-2, the location you
specify for the field is the location of the first radio button.
Notes:
1. If you suppress the selection indicators, the location that you specify for the
single-choice selection field is the location of the first character in the first
choice.
2. If the single-choice selection field is within a pull-down menu, the location you
specify is relative to the pull-down menu borders.
A single-choice selection field is a numeric field containing a SNGCHCFLD keyword

and one or more CHOICE keywords. The CHOICE keywords define the choices
within the single-choice selection field. Figure 6-10 shows an example of the
keywords to use.

You can have choice numbers up to two digits long. The maximum number you
can specify for a choice is 99. On output, if the field contains a choice number,
that choice is the default selection.
The default is for vertical selection fields. You can create a horizontal selection
field by using the *NUMCOL or *NUMROW values on the SNGCHCFLD keyword.
See “Creating a Horizontal Selection Field” for more information.
Creating a Vertical Multiple-Choice Selection Field

A multiple-choice selection field is a special numeric field containing:
A MLTCHCFLD keyword to identify it as a multiple-choice selection field. When
a user makes a selection, the field itself contains the number of choices that
are selected.
One or more CHOICE keywords that define the choices.
A CHCCTL keyword for each choice to define a hidden field for each choice.
The hidden field is used to indicate if the choice was selected. For more infor-
mation on the CHCCTL keyword, see “Controlling the Availability of Choices”
on page 6-36.
The default is for vertical selection fields. You can create a horizontal selection
field by using the *NUMCOL or *NUMROW values on the MLTCHCFLD keyword.
See “Creating a Horizontal Selection Field” for more information.
Creating a Horizontal Selection Field

The default orientation for single-choice and multiple-choice selection fields is ver-
tical. To specify a horizontal field, use the *NUMCOL or *NUMROW values on the
SNGCHCFLD and MLTCHCFLD keywords.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R RECORD
A 2 2'Flavor . . . '
A F1 2Y ðB 2 16SNGCHCFLD((\NUMCOL 2))
A CHOICE(1 'Chocolate ')
A ð1 CHOICE(2 'Strawberry ')
A CHOICE(3 'Vanilla ')
A CHOICE(4 'Peach ')
Figure 6-11. Example of DDS for Horizontal Selection Field. The \NUMCOL 2 specifies that
the field should display in two columns.
The following shows how this single-choice selection field would appear on a
character-based display, assuming option indicator 01 is on:
à ð
Flavor . . . _ 1. Chocolate 2. Strawberry
3. Vanilla 4. Peach
The following shows how this single-choice selection field would appear if
*NUMROW 2 were specified:

à ð
Flavor . . . _ 1. Chocolate 3. Vanilla
2. Strawberry 4. Peach
If the choices are nonsequential, no blank line or blank space is left for the omitted
choice as would have happened with *NUMCOL.
You can optionally specify the number of spaces to appear between the choices by
using the *GUTTER value on the SNGCHCFLD and MLTCHCFLD keywords. The
gutter width must be at least 2. If *GUTTER is not specified, the default number of
spaces between choices is 3.
Note: The gutter width includes the beginning and ending attribute of the choices
on either side of the gutter.
The area occupied by the horizontal selection field is determined by the following:
The number of choices specified
The length of the longest choice
The width of the gutter
The number of columns specified
The longest accelerator text specified (for a horizontal single-choice selection
field in a pull-down menu)
A horizontal selection field must fit within the minimum display size specified for the
file (24 x 80 or 27 x 132). If the record is a window or a pull-down menu, the
horizontal selection field must fit within the minimum window size. Other fields may
be specified to the right or to the left of a horizontal selection field. Option indica-
tors can be specified on horizontal selection fields, as they can for other fields.
You can control which choices are displayed at one time by using option indicators
on the CHOICE keywords. Unlike a vertical selection field, if a choice is optioned
off, the remaining choices will be shifted to fill in the space.
Cursor Movement in a Vertical Selection Field

With *NORSTCSR on the SNGCHCFLD and MLTCHCFLD keywords, the cursor
keys move the cursor to the next cursorable choice in the direction of the key that
is pressed. The cursor skips null choices and choices defined as noncursorable.
The up arrow key moves the cursor up one choice. The down arrow key moves
the cursor down one choice. If the cursor is on the top choice and the up arrow
key is pressed, the cursor leaves the field. Likewise, if the cursor is on the bottom
choice and the down arrow is pressed, the cursor leaves the field. If the cursor
input only (CSRINPONLY) keyword is in effect, the cursor moves to the next
cursorable item on the display above or below the current cursor position. The
cursor left and right keys move the cursor one space to the left or right.
Note: If the selection field is the only field defined within a pull-down menu, the
cursor left and right keys close the present pull-down menu and open the
next pull-down menu to the left or right.
To keep the cursor within a selection field, use the *RSTCSR value on the
SNGCHCFLD and MLTCHCFLD keywords. If the cursor up key is pressed when

the cursor is on the top choice in the list, the cursor moves to the last choice in the
list. If the cursor down key is pressed when the cursor is on the bottom choice in
the list, the cursor moves to the top choice in the list. If the cursor left key is
pressed the cursor moves up one choice. If the cursor is on the top choice, the
cursor moves to the bottom choice. If the cursor right key is pressed the cursor
moves down one choice. If the cursor is on the bottom choice, the cursor moves to
the top choice.
Note: If the selection field is the only field defined within a pull-down menu, the
cursor left and right keys close the present pull-down menu and open the
next pull-down menu to the left or right.
Cursor Movement in a Horizontal Selection Field

With *NORSTCSR on the SNGCHCFLD and MLTCHCFLD keywords, the cursor
keys move the cursor to the next cursorable choice in the direction of the key that
is pressed. The cursor skips null choices and choices defined as noncursorable. If
the cursor is on the top choice of any column in the field and the up arrow key is
pressed, the cursor leaves the field. Likewise, if the cursor is on the bottom choice
of any column in the field and the down arrow key is pressed, the cursor leaves the
field. If the cursor input only (CSRINPONLY) keyword is in effect, the cursor
moves to the next cursorable item on the display above or below the current cursor
position. If the left arrow key is pressed and there is a cursorable item to the left of
the current choice, the cursor moves to the choice. If there is no cursorable item to
the left, the cursor leaves the field. If the right arrow key is pressed and there is a
cursorable item to the right of the current choice, the cursor moves to the choice. If
there is no cursorable item to the right, the cursor leaves the field.
Note:
To keep the cursor within a selection field, use the *RSTCSR value on the
SNGCHCFLD and MLTCHCFLD keywords. If the cursor up key is pressed when
the cursor is on the top choice in any column in the field, the cursor moves to one
of the following places:
If there is a cursorable position in a column to the left, the cursor moves to the
last choice in that column.
If there is not a cursorable position in a column to the left or if there is no
column to the left, the cursor moves to the last cursorable choice in right-most
column in the field.
If the cursor down key is pressed when the cursor is on the last choice in any
column in the field, the cursor moves to one of the following places:
If there is a cursorable position in a column to the right, the cursor moves to
the top choice in that column.
If there is not a cursorable position in a column to the right or if there is no
column to the right, the cursor moves to the first cursorable choice in left-most
column in the field.
If the cursor left key is pressed and there is a cursorable choice to the left of the
current choice, the cursor moves to that choice. If there is no cursorable choice to
the left, the cursor moves to the first cursorable choice in the row above the
present row (closest row, right-most choice). If the present row is the top row, the
cursor moves to the right-most choice in the last row.

If the cursor right key is pressed and there is a cursorable choice to the right of the
current choice, the cursor moves to that choice. If there is no cursorable choice to
the right, the cursor moves to the first cursorable choice in the row below the
present row (closest row, left-most choice). If the present row is the bottom row,
the cursor moves to the left-most choice in the first row.
Note: The cursor left and right keys will close the present pull-down menu and
open the next pull-down menu to the left or right when the following are
true:
The selection field is the only field defined within a pull-down menu
There is no cursorable choice to the left or right of the current choice
Controlling the Selection Indicators in a Selection Field

A selection indicator is an indicator that precedes a choice in a selection field or a
selection list. It is used to select the choice or to show that a choice has been
selected. An example of a selection indicator is a radio button. Radio buttons
appear before choices in single-choice selection fields and single-choice selection
lists. The default is for selection indicators to appear in selection fields. You can
suppress the selection indicators in a selection field by specifying the *NOSLTIND
parameter on the SNGCHCFLD and MLTCHCFLD keywords.
The *NOSLTIND value is ignored for display stations that are not attached to a
controller that supports an enhanced interface for nonprogrammable work stations.
Figure 6-12 is an example of the DDS to suppress the selection indicators in a
selection field.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R RECORD
A 2 3ð'Display Title'
A 4 5'Single selection field . . . :'
A F1 2Y ðB 4 4ðSNGCHCFLD(\NOSLTIND)
A CHOICE(1 '>One')
A 8 5'Multiple selection field . . . :'
A F2 2Y ðB 8 4ðMLTCHCFLD(\NOSLTIND)
A CHOICE(1 '>One')
Figure 6-12. DDS for Suppressing Selection Indicators in a Selection Field
selection fields look like this:

RV3W067-0
Figure 6-13. Suppressed Selection Indicators in Selection Field
Creating Pull-Down Menus Using Single-Choice Selection Fields

When you select a choice from the menu bar, a pull-down menu appears. A pull-
down menu is a group of actions associated with a menu bar choice. Figure 6-14
is an example.
File Edit View Help

Undo
Mark
Copy
RV2W859-1
Figure 6-14. Example of a Pull-Down Menu
You must define the pull-down menus and the corresponding menu bar in the same
file.
The last field in any pull-down menu always operates as though the CHECK(FE)
(Field Exit) keyword were specified. This keeps the cursor in the pull-down menu
after you enter the input that is in the last field in the pull-down menu. Then, if you
press the Field Exit key with the cursor in the last field, the field is cleared and the
cursor moves to the next pull-down menu. If the last field did not operate with
CHECK(FE), the cursor automatically moves on to the next pull-down menu after
you press the Enter key.
A pull-down record can contain anything that a window record can contain.
However, use only single-choice selection fields or multiple-choice selection fields
in a pull-down menu. If you use fields other than single-choice selection fields or
multiple-choice selection fields, the cursor does not move consistently on all display

stations. On display stations attached to a controller that supports an enhanced
interface for nonprogrammable work stations, the cursor-right keys and cursor-left
keys display the next pull-down menu when both of these conditions are true:
There is only one selection field in the displayed pull-down menu, and
The cursor is positioned on the selection field.
On display stations attached to a controller that does not support an enhanced
interface for nonprogrammable work stations, the cursor movement keys move the
cursor one character position within the pull-down menu.
Figure 6-15 is an example of the DDS for a pull-down menu. The figures that
follow show how the pull-down menu appears on each type of display.
Note: Assume that the record PULLDOWN is specified on the MNUBARCHC
keyword for the Edit choice, and that the MARKTXT field contains the text,
>Mark.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R PULLDOWN PULLDOWN
A F1 2Y ðB 1 1SNGCHCFLD
A ð1 CHOICE(1 '>Undo ')
A CHOICE(2 &MARKTXT)
A CHOICE(3 '>Copy ')
A
A :
Figure 6-15. DDS for a Pull-Down Menu
On display stations in configurations A and B from Table 6-1 on page 6-2, the pull-
down menu looks like this:
File Edit View Help

Undo
Mark
Copy
RV2W859-1
Figure 6-16. Pull-Down Menu on a Graphical Display Station with Enhanced Interface
On display stations in configuration C from Table 6-1 on page 6-2, the pull-down
menu looks like this:
File Edit View Help

. .
: 1. Undo :
: 2. Mark :
: 3. Copy :
. . . . . . . . . . . . . .
RV2W065-0
Figure 6-17. Pull-Down Menu on a Nongraphical Display Station with Underline Capability

On display stations in configurations D and E from Table 6-2 on page 6-3, the pull-
File Edit View Help

. .
: 1. Undo :
: 2. Mark :
: 3. Copy :
. . . . . . . . . . . . . .
RV2W064-0
Figure 6-18. Pull-Down Menu on a Nongraphical Display Station without Underline Capa-
bility
On display stations in configuration F from Table 6-2 on page 6-3, the pull-down
File Edit View Help

. .
: 1. Undo :
: 2. Mark :
: 3. Copy :
. . . . . . . . . . . . . .
RV3W073-1
Figure 6-19. Pull-Down Menu on a Display without Enhanced Interface
Controlling the Selection Indicators in a Pull-Down Menu

lists. The default is for selection indicators to appear in selection fields. You can
suppress the selection indicators in a pull-down menu by specifying the
*NOSLTIND parameter on the PULLDOWN keyword. Figure 6-20 is an example of
the DDS to suppress the selection indicators in a pull-down menu.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R PULLDOWN PULLDOWN(\NOSLTIND)
Figure 6-20. DDS for Suppressing Selection Indicators in a Pull-Down Menu

Undo
Mark
Copy
RV2W857-1
Figure 6-21. Suppressed Selection Indicators on Graphical Display Station
On display stations in configuration C from Table 6-1 on page 6-2, the pull-down

. .
: Undo :
: Mark :
: Copy :
. . . . . . . . . . . . . . . .
RV2W066-1
Figure 6-22. Suppressed Selection Indicators on Nongraphical Display Station
The *NOSLTIND value is ignored for display stations that are not attached to a
controller that supports an enhanced interface for nonprogrammable work stations.
Defining Accelerator Keys

An accelerator key is a function key that starts the application-defined function and
is displayed next to a pull-down menu choice.
You can specify accelerators for a single-choice selection field in a pull-down menu
by doing the following:
1. Specify the necessary CFnn keys.
2. Use the CHCACCEL keyword.
Specify the accelerator text on the CHCACCEL keyword. You can use a P-field to
specify the text. Note that the CHCACCEL keyword does not define the acceler-
ator key itself. You must define the CFnn keyword for the key and design your
application to recognize this key as an accelerator for this choice. You must also
ensure that the text you specify on CHCACCEL correctly reflects the key you have
defined. For example, if you want CF08 to be an accelerator key, specify some-
thing like F8 or CFð8 on the CHCACCEL keyword for the appropriate choice.
The accelerator text appears three spaces after the length of the longest choice
text in the field.
Because the accelerator key functions even if the pull-down menu is not displayed,
you should define the necessary CFnn keys at the file level. If you define them at
the record level, specify them for every record from which they should be available.
Single-choice selection fields may be defined in any record. However, an acceler-

ator can be defined only for a single-choice selection field within a pull-down menu.
Figure 6-23 on page 6-22 is an example.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R PULLEDIT CFð4 CFð6
A PULLDOWN
A CHECK(ER)
A CHCACCEL(1 'F4')
A CHCACCEL(2 &F6)
A MARKTXT 2ðA P
A F6 2 P
Figure 6-23. DDS for Accelerator Keys

Undo F4
Mark F6
Copy
RV2W855-1
Figure 6-24. Accelerators in a Pull-Down Menu
Defining a Menu-Bar Switch Key

A menu-bar switch key alternates the cursor between the menu bar and the appli-
cation display.
You can define a menu-bar switch key using the MNUBARSW keyword at either
the file level or the record level. If the cursor is in the application record, pressing
the menu-bar switch key moves the cursor to the first choice in the menu bar.
Pressing the key again moves the cursor from the menu bar back to its previous
location in the application record. If you move the cursor using the cursor keys
from the application record to the menu bar and then press the menu-bar switch
key, the cursor returns to its initial position on the application record. This is the
first input field unless cursor positioning keywords are specified on the application
record. If a pull-down menu is displayed, pressing the menu-bar switch key
cancels the pull-down menu and moves the cursor to the application record.
The system always handles the menu-bar switch key regardless of whether the
application or the system displayed the menu bar. (For more information, see the
DDS Reference.)
For the menu-bar switch key to be active, it must have been active on the last
record written to the display. The easiest way to ensure that the menu-bar switch
key will always be active is to specify MNUBARSW at the file level. If you specify
MNUBARSW at the record level, you must specify it on all records on which it
should be active.

Defining a Cancel Key
You can define a cancel key for the menu-bar record and pull-down menu records
using the MNUCNL keyword. You can define them either at the file level or the
record level.
A cancel key closes a pull-down menu and moves the cursor to the associated
choice on the menu bar. This is true even if the cursor is not in the pull-down
menu. If no pull-down menus are displayed and the cursor is located within the
menu bar, the key cancels the menu bar and moves the cursor back to the applica-
tion record. This location is the cursor’s previous location in the application record
if the menu-bar switch key was used to move the cursor to the menu bar. If the
cursor had been moved to the menu bar with the cursor keys, this location is the
initial location of the cursor within the application record. If no pull-down menus are
displayed and the cursor is located on the application record, the key returns
control to the application program. In this case, the MNUCNL keyword works just
as any other key definition keyword, and includes the ability to return a response
indicator.
Like the menu-bar switch key, the cancel key is active only if it was active for the
last record written to the display. The easiest way to ensure that the cancel key
will always be active is to specify the MNUCNL keyword at the file level. If you use
the MNUCNL keyword at the record level, you must specify it on all records on
which it should be active.
Figure 6-25 shows how to use the MNUBARSW keyword and the MNUCNL
keyword. The example sets up command attention key 10 as the menu-bar switch
key and command attention key 12 as the cancel key. (These settings are the
defaults.)
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A MNUBARSW(CA1ð) MNUCNL(CA12)
A R MENUBAR MNUBAR
A MNUFLD 2Y ðB 1 2
A '>File ')
A &EDITTXT)
A '>View ')
A '>Options ')
A '>Help ')
A EDITTXT 2ðA P
A .
A .
A .
Figure 6-25. DDS for Menu-Bar Switch Key and Cancel Key

Limiting Function When Cursor is Outside a Pull-Down Menu
If *NORSTCSR is specified on the PULLDOWN keyword, the user may move the
cursor out of the active window and use any command function (CF) key.
*NORSTCSR is the default.
If *RSTCSR is specified on the PULLDOWN keyword, and the cursor is moved

outside the pull-down menu, only the Print and Home command function (CF) keys
are active. If the work station user presses any other command function (CF) key,
the alarm sounds and the cursor is moved back to its position for the previous write
operation.
Selection Lists—Overview
A selection list is a potentially scrollable list from which the user can select an
item. There are two types of selection lists: single-choice and multiple-choice. A
single-choice selection list is a potentially scrollable list from which the user can
select one item. A multiple-choice selection list is a potentially scrollable list
from which the user can select one or more items.
Single-choice selection lists and multiple-choice selection lists contain a group of

choices displayed in a vertical list. These choices can be scrolled either by using
the Page Up and Page Down keys or by using a scroll bar. A scroll bar is a part of
a display that shows a user that more information is available in a particular direc-
tion and can be moved into view by using a pointing device or the page keys. For
more information on scroll bars, see “Scroll Bars—Overview” on page 6-30.
You can select any number of choices from the multiple-choice selection list. You
can only make one choice from the single-choice selection list. “Selection
Lists—Overview” shows an example of a single-choice selection list, multiple-choice
selection list, and scroll bars used with the selection lists.

The DDS in Figure 6-28 on page 6-26 produces the following displays:
selection lists look like this:
RV3W077-0
Figure 6-26. Selection Lists on a Graphical Display Station with Enhanced Interface
On display stations in configuration F from Table 6-2 on page 6-3, the selection
lists (vertical format) look like this:
RV3W069-2
Figure 6-27. Selection Lists on a Nongraphical Display Station with Underline Capability

DDS for Selection Lists—Example
The DDS in Figure 6-28 creates the displays shown in “Selection Lists—Overview”
on page 6-24.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R SFLRCD SFL
A CTLFLD 1Y ðH SFLCHCCTL
A F1 11A O 6 1ð
A R SFLCTLRCD SFLCTL(SFLRCD)
A SFLSNGCHC
A SFLPAG(5) SFLSIZ(&SFLSIZ)
A SFLDSP SFLDSPCTL
A ROLLUP(1ð)
A 1ð SFLEND(\MORE)
A F3 5S ðH SFLSCROLL
A F2 4S ðH SFLRCDNBR(CURSOR \TOP)
A SFLSIZ 5S ðP
A 1 3ð'Panel Title'
A 4 5'Single selection list:'
A R SFLRCD2 SFL
A F1 11A O 13 1ð
A R SFLCTLRC2 SFLCTL(SFLRCD2)
A SFLMLTCHC(&NUMSEL \RSTCSR)
A SFLDSP SFLDSPCTL
A 1ð SFLEND(\MORE)
A ROLLUP(1ð)
A SFLSIZ 5S ðP
A NUMSEL 4Y ðH
A 11 5'Multiple selection list:'
Figure 6-28. DDS for Selection Lists—Example
Creating Selection Lists

Selection lists are created using subfiles. For more information on subfiles, see
Chapter 4, “Displaying Groups of Records Using Subfiles.” For each selection list
you must specify a subfile record format and a subfile control record format. Within
the subfile record format you must specify an output field for the text of the choice.
You can specify only one output-only field in the record.
To specify a default choice in a selection list, use either the subfile next-changed
(SFLNXTCHG) keyword or a control field. To use the SFLNXTCHG keyword,
specify the keyword on the text field within the subfile record. To use a control
field, specify a control field in the subfile record and specify the subfile choice
control (SFLCHCCTL) keyword on the field. The control field can have the fol-
lowing values:

Control Value Meaning on Meaning on Input
Output
0 Available Not selected
1 Selected Selected
2 Unavailable.
Cannot place
cursor on choice
unless help for
choice is
available.1,2
3 Unavailable.
Placing cursor on
choice is allowed.
4 Unavailable.
Cannot place
cursor on choice
even if help for
choice is
available.1,2
1 Applies only to displays attached to a controller that sup-
ports an enhanced interface for nonprogrammable work
stations.
2 If the choice is the first choice displayed and there are no
other cursorable choices in the list, the choice will be made
unavailable and cursorable. Otherwise, an invalid data stream
error would be issued.
The application uses the get-next-changed operation to determine which choices

are selected. The get-next-changed operation returns all of the changed records.
If the user deselects a default choice, the get-next-changed operation returns the
deselected choice record because its control value changed. To have the get-next-
changed operation return only the selected choices, specify the subfile return
selected choices (SFLRTNSEL) keyword on the subfile control record. The next
get-next-changed operation will return the selected choice. Then, perform an
update operation to the default choice to change its control value to 0.
choices are preceded by radio buttons (single-choice) and check boxes (multiple-
choice). This is true unless *NOSLTIND is specified on the subfile single-choice
selection list (SFLSNGCHC) and multiple-choice selection list (SFLMLTCHC)
keywords. The location that you specify for the first field in the subfile record
format is the location of the input fields (on a character-based nongraphical
display). On display stations in configurations A and B from Table 6-1 on
page 6-2, the location of the first field is the location of the first radio button or
check box.
Notes:
1. If you suppress the selection indicators, the location that you specify for the first
field in the subfile record format is the location of the first character in the first
choice.
2. If the selection list is within a pull-down menu, the location you specify is rela-
tive to the pull-down menu borders.

To specify that the cursor remain in the selection list when the cursor movement
keys are used, use the restrict cursor (*RSTCSR) value on the SFLSNGCHC or
SFLMLTCHC keywords. If the cursor is on the top record of the subfile and the
user presses the up cursor key, the subfile rolls up. If the cursor is on the last
record of the subfile and the user presses the down cursor key, the subfile rolls
down.
The SFLSCROLL keyword is used to return the relative record number of the
record at the top of the current page of records. If the user presses Enter,
SFLSCROLL returns the relative record number of record that is currently displayed
at the top of the page. If control is returned to the application because of the
ROLLUP keyword, SFLSCROLL returns the relative record number of the last
record in the subfile plus 1. If control is returned to the application because of the
ROLLDOWN keyword, SFLSCROLL always returns 1.
To redisplay the subfile with the correct subfile record at the top of the list of
choices, use the subfile record number (SFLRCDNBR) keyword. Specify
SFLRCDNBR(*TOP) as a hidden field and use the relative record number returned
by the SFLSCROLL keyword. Add more records to the subfile and redisplay the
subfile.
Controlling the Selection Indicators in a Selection List

lists. The default is for selection indicators to not appear in selection lists. You can
have the selection indicators display in a selection list by specifying the *SLTIND
parameter on the SFLSNGCHC and SFLMLTCHC keywords.
The *SLTIND value is ignored for display stations that are not attached to a con-
troller that supports an enhanced interface for nonprogrammable work stations.
Figure 6-29 on page 6-29 is an example of the DDS to enable the selection indica-
tors in a selection list.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R SFLRCD SFL
A F1 11A O 6 1ð
A SFLSNGCHC(\SLTIND)
A SFLDSP SFLDSPCTL
A ROLLUP(1ð)
A 1ð SFLEND(\MORE)
A SFLSIZ 5S ðP
A R SFLRCD2 SFL
A F1 11A O 13 1ð
A SFLMLTCHC(&NUMSEL \RSTCSR \SLTIND)
A SFLDSP SFLDSPCTL
A 1ð SFLEND(\MORE)
A ROLLUP(1ð)
A SFLSIZ 5S ðP
A NUMSEL 4Y ðH
Figure 6-29. DDS for Enabling Selection Indicators in a Selection List
selection list looks like this:
RV3W0079-0
Figure 6-30. Selection Indicators on Graphical Display Station

Scroll Bars—Overview
A scroll bar is a part of a display that shows a user that more information is avail-
able in a particular direction and can be moved into view by using a pointing device
or the page keys. A scroll bar can be defined for any subfile. The examples in this
section show examples of scroll bars used with a single-choice selection list and a
multiple-choice selection list.
selection lists and scroll bars look like this:
RV3W078-0
Figure 6-31. Scroll Bar on a Graphical Display Station with Enhanced Interface

On display stations in configuration F from Table 6-2 on page 6-3, the selection
lists (vertical format) look like this:
RV3W080-0
Figure 6-32. Scroll Bar on a Nongraphical Display Station with Underline Capability
Creating a Scroll Bar

To create a scroll bar, use the scroll bar (*SCRBAR) value on the subfile end
(SFLEND) keyword. The *SCRBAR value creates a graphical scroll bar on graph-
ical display stations. It creates a character scroll bar on nongraphical display
stations. The scroll bar appears to the right of the longest choice in the list. To
have the scroll bar appear further to the right, add blanks to the text for the
selection list choices.
In most cases, the number of subfile records represented by the scroll bar is the
number of records that have been written to the subfile. The SFLEND keyword
optioned on indicates that no more records will be written to the subfile. The
SFLPAG value is not added to the number of records represented by the scroll bar.
When the bottom of the subfile is reached and the PAGEDOWN keyword is not
active, the scroll bar box is displayed exactly above the lower scroll bar button.
The SFLEND keyword optioned off indicates that more records will be written to the
subfile. The SFLPAG value is added to the number of records represented by the
scroll bar. Adding the SFLPAG value causes the scroll bar to appear as if more
subfile records exist after the last subfile record. When the last subfile record is
reached and the PAGEDOWN keyword is active, the scroll bar box is not displayed
exactly above the lower scroll bar button. This indicates there are more records to
display. If the PAGEDOWN keyword is active, control is given back to the applica-
tion if the user tries to page down or scroll to the unseen records. The application
can then write more records to the subfile.
Note: The SFLPAG value is not added to the number of records represented by
the scroll bar when PAGEDOWN is active and when the number of records
written is less than the SFLSIZ value. In this case, the number of subfile
records represented by the scroll bar is the SFLSIZ value. The SFLSIZ

value is used to show the total size of the subfile and allows the application
to fill only the subfile records that the user wants to see.
If the PAGEDOWN keyword is active, no partial pages are displayed. If the user
tries to roll to a partial page, control is given back to the application. The subfile
roll value (SFLROLVAL) may override this. For more information on the
SFLROLVAL keyword, see the DDS Reference. If the PAGEDOWN keyword is not
active, the SFLPAG value minus 1 is added to the number of records represented
by the scroll bar. Adding the SFLPAG value minus 1 enables a partial page to be
displayed.
Note: If a scroll bar is displayed with a horizontal subfile, you may not be able to
use the top scroll button when the following are true:
A partial page is reached
Records are displayed in only the first column of the horizontal subfile
See Table 6-3 for a summary of how the scroll bar is sized under different condi-
tions.
Table 6-3. How a Scroll Bar is Sized

then the following values are added (yes or no) to
the number of records represented by the scroll bar
Relative
record
If SFLEND and number
indicator PAGEDOWN and the number of of last
is ... is ... records written is ... SFLPAG SFLPAG - 1 record SFLSIZ
≥SFLSIZ No No Yes No
Active <SFLSIZ No No No Yes
≥SFLSIZ No Yes Yes No
On Not active <SFLSIZ No Yes Yes No
≥SFLSIZ Yes No Yes No
Active <SFLSIZ No No No Yes
≥SFLSIZ Yes Yes Yes No
Off Not active <SFLSIZ Yes Yes Yes No

DDS for Scroll Bars—Example
The DDS in Figure 6-33 creates the displays shown in “Scroll Bars—Overview” on
page 6-30.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R SFLRCD SFL
A F1 11A O 6 1ð
A SFLSNGCHC
A SFLDSP SFLDSPCTL
A ROLLUP(1ð)
A 1ð SFLEND(\SCRBAR)
A SFLSIZ 5S ðP
A R SFLRCD2 SFL
A F1 11A O 13 1ð
A SFLMLTCHC(&NUMSEL \RSTCSR)
A SFLDSP SFLDSPCTL
A 1ð SFLEND(\SCRBAR \MORE)
A ROLLUP(1ð)
A SFLSIZ 5S ðP
A NUMSEL 4Y ðH
Figure 6-33. DDS for Scroll Bars—Example
Scroll Bar Operation

See Table 6-4 for a summary of how the scroll bar operates.
Table 6-4. Scroll Bar Operation

If the user ... then ...
Clicks once on the top scroll button The subfile is scrolled one record toward
the bottom of the subfile
Clicks once on the bottom scroll button The subfile is scrolled one record toward
the top of the subfile
Clicks once on the shaft above the scroll The subfile is scrolled one page toward the
box or presses the Page Down key bottom of the subfile
Clicks once on the shaft below the scroll The subfile is scrolled one page toward the
box or presses the Page Up key top of the subfile
Drags the scroll box with the selection The subfile page is scrolled to correspond
button and releases the selection button to the position indicated by the scroll box

Push Buttons—Overview
A push button is a button, labeled with text, graphics, or both that represents an
action that starts when a user selects the push button.
push buttons look like this:
RV3W070-0
Figure 6-34. Push Buttons on a Graphical Display Station with Enhanced Interface
On display stations in configuration C from Table 6-1 on page 6-2, the push
buttons look like this:
RV3W071-0
Figure 6-35. Push Buttons on a Nongraphical Display Station with Underline Capability
push buttons look like this:
RV3W072-0
Figure 6-36. Push Buttons on a Nongraphical Display Station without Underline Capability
On display stations in configuration F from Table 6-1 on page 6-2, the push
buttons look like this:
RV3W074-0
Figure 6-37. Push Buttons on a Display Station without Enhanced Interface

DDS for Push Buttons—Example
The DDS in Figure 6-38 creates the displays shown in “Push Buttons—Overview”
on page 6-34.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R RECORD
A
A PSHFLD1 2Y ðB 23 4PSHBTNFLD(\RSTCSR (\NUMCOL 3))
A PSHBTNCHC(1 'F1=>Help' HELP)
A PSHBTNCHC(2 &F3 CFð3)
A CHCCTL(2 &CTL)
A ð2 PSHBTNCHC(3 'F4=>Prompt' CFð4)
A CHCAVAIL((\COLOR RED))
A F3 15A P
A CTL 1Y ðH
Figure 6-38. DDS for Push Buttons—Example
Creating Push Buttons

A push button field is defined with the push button field (PSHBTNFLD) keyword.
Each push button field must contain one or more push button choice
(PSHBTNCHC) keywords.
Push buttons can be displayed vertically or horizontally (the default). The

*NUMROW value on the PSHBTNFLD keyword specifies the number of rows to
use when displaying the push buttons vertically. The *NUMCOL value on the
PSHBTNFLD keyword specifies the number of columns to use when displaying the
push buttons horizontally. When no parameters are specified on the PSHBTNFLD
keyword, the push buttons are displayed in as many columns that fit on one line.
Use the choice control (CHCCTL) keyword to control the availability of the indi-
vidual push buttons. Use the choice available (CHCAVAIL) and choice unavailable
(CHCUNAVAIL) keywords to control the color or attribute of the individual push
buttons.
Specify a key for each push button. In the following example, the CF04 key is
returned when the F4=Prompt push button is selected:
PSHBTNCHC(3 'F4=>Prompt' CFð4)
If you do not specify a key, Enter is returned when the push button is selected.
The key defined in the push button choice is automatically enabled for the record
that contains the push button field.
The field that contains the push button contains the number of the push button
choice that is selected. If the user presses the key associated with a push button
(instead of selecting the push button itself), the number of the push button is not
returned. Zero is returned if no choice is made.
Help can be specified for each push button.

Controlling the Availability of Choices
You can control the availability of the choices in a selection field and push button
choices using the CHCCTL keyword. For information on controlling the availability
of choices in selection lists, see “Creating Selection Lists” on page 6-26. Specify
the name of a hidden field on the CHCCTL keyword. Your program can set a
value in this field to specify whether the choice is available, unavailable, or selected
(multiple-choice selection fields only). Figure 6-39 describes the control values and
their meanings.
Control Value Sets Choice to

0 Available (or not selected)
1 Selected
2 Unavailable.
Cannot place cursor on choice unless help for choice is available.
3 Unavailable.
Placing cursor on choice is allowed.
4 Unavailable.
Cannot place cursor on choice even if help for choice is available.
Figure 6-39. Control Values for the CHCCTL Keyword
Note: The cursor restrictions in Figure 6-39 apply only to displays attached to a
controller that supports an enhanced interface for nonprogrammable work
stations.
Value 1 is ignored for single-choice selection fields, because default selection is

done by setting the selection in the single-choice selection field itself. It is also
ignored for push buttons. Value 1 is used for multiple-choice selection fields to let
more than one choice default to the selected choice.
You can also specify a message to be displayed if the user selects an unavailable
choice. If you do not specify a message, the system displays a default message.

Figure 6-40 is an example of the DDS to control the availability of choices showing
a single-choice selection field in an ordinary record:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R RECORD
A 2 2'Flavor . . . '
A CHOICE(1 '>Chocolate ')
A CHCCTL(1 &CTLCHOC MSG1112 QUSER/A)
A ð1 CHOICE(2 '>Strawberry ')
A CHCCTL(2 &CTLSTRA &MSG &LIB/&MSGF)
A CHOICE(3 '>Vanilla ')
A CHCCTL(3 &CTLVANI)
A CHOICE(5 '>Peach ')
A CTLCHOC 1Y ðH
A CTLSTRA 1Y ðH
A CTLVANI 1Y ðH
A MSG 7A P
A LIB 1ðA P
A MSGF 1ðA P
Figure 6-40. DDS to Control the Availability of Choices
On display stations in configuration C from Table 6-1 on page 6-2 and configura-
tions D, E, and F from Table 6-2 on page 6-3, the single-choice selection field
looks like this:
à Flavor . . . _ 1. Chocolate
ð
2. Strawberry
3. Vanilla
5. Peach
Figure 6-41. Single-Choice Selection Field with an Unavailable Choice. Assume that at
run time, CTLCHOC and CTLSTRA are set to 0 (available) and CTLVANI is set to 2 (una-
vailable). The choice text, Vanilla, appears gray to indicate it is unavailable.
Auto-Selection in Single-Choice Selection Fields

The auto-selection function allows a user to select a choice in a single-choice
selection field by placing the cursor on the choice and pressing Enter. It is not
necessary to select the choice by 1) typing the choice number, 2) placing the
cursor on the choice and pressing the spacebar, or 3) placing the pointer on the
choice and pressing the left mouse button. This is the default for single-choice
selection fields in a pull-down menu. The default for single-choice selection fields
that are not in a pull-down menu is manual selection. The *AUTOSLT parameter
on the SNGCHCFLD keyword indicates that the choice should be automatically
selected when Enter is pressed. The *NOAUTOSLT parameter indicates that the
choice must be manually selected. The *AUTOSLTENH parameter indicates that
auto-selection is only in effect for displays attached to a controller that supports an
enhanced interface for nonprogrammable workstations.

Auto-Enter in Single-Choice Selection Fields
The auto-enter function allows a selected choice to be returned to the program
when the choice is selected. It is not necessary to press Enter to return the choice.
The *AUTOENT parameter indicates that the Enter key will be returned as soon as
the choice is selected. The choice is automatically returned on all display stations
except where a double-digit selection number is required for any of the choices.
The *NOAUTOENT parameter indicates that the choice will not be returned until the
user presses Enter after selecting the choice. *NOAUTOENT is the default. The
*AUTOENTNN parameter indicates that the choice will be returned as soon as the
choice is selected only if numeric selection of the choice is not required.
Defining Mnemonics
You can define mnemonics for these items:
Menu-bar choices
Selection field choices (single and multiple)
Selection list choices (single and multiple)
Push buttons
Define mnemonics using a greater-than (>) character. To identify a mnemonic,

place the > character just before the character that you want to be the mnemonic.
The > character is not counted as part of the text length. If you want to use the >
character as a character in the text rather than as a pointer to the mnemonic, you
must use two > characters consecutively. If you specify the > character as the last
character in the text, the > character appears as part of the text and no mnemonic
appears. Figure 6-42 is an example.
Keyword Specification Text Appears as

MNUBARCHC(1 PULLFILE '>File') File
MNUBARCHC(2 PULLFIN 'F>inish') Finish
CHOICE(1 'Save >As...') Save As...
CHOICE(2 'X >= 1') X=1
CHOICE(3 'X >>>= 1') X >= 1
You cannot specify the > character as a mnemonic.
Figure 6-42. Examples of Valid DDS for Mnemonics
The mnemonic cannot be a blank. Only one mnemonic may be specified in the
choice text. If more than one mnemonic is specified, only the first mnemonic is
selectable. Figure 6-43 is an example of incorrect coding.
Keyword Specification Error

MNUBARCHC(1 PULLFILE '>File') Same mnemonic specified for
MNUBARCHC(2 PULLFIN '>finish') more than one choice.
CHOICE(1 'S>ave >As...') Two mnemonic characters

CHOICE(4 'X >>>= >1') specified.
Figure 6-43. Examples of DDS Not Valid for Mnemonics
You can select a mnemonic by typing either the uppercase or lowercase mnemonic
character. This is true for all languages. The system uses the monocase rules for

the appropriate language to identify the mnemonic you typed. Double-byte charac-
ters cannot be mnemonics.
Because the system does not support both mnemonic and numeric selection for a
field, mnemonics work only when choices are not displayed using numbers.
To determine which configurations support mnemonics, see Table 6-1 on

page 6-2.
Defining Choice Colors and Attributes

Normally, the system uses the Common User Access* (CUA) default colors and
display attributes when displaying menu-bar choices, selection-field choices,
selection list choices, and push button choices. If you do not want to use these
defaults, you can define the colors and attributes to be used for most choices using
the CHCAVAIL, CHCUNAVAIL, and CHCSLT keywords. Table 6-5 shows which
keywords can be used with each graphical item.
Table 6-5. Keywords Used to Define Colors and Display Attributes

DDS Keyword
Graphical Item CHCAVAIL CHCUNAVAIL CHCSLT
Menu-Bar Choice X X
Selection Fields X X X
Push Buttons X X
Single Choice X X X
Selection List
Multiple Choice X X X
Selection List
The selection cursor on display stations attached to a controller that supports an

enhanced interface for nonprogrammable work stations uses the reverse image
form of the colors and attributes you specify for each of the choice states. For
example, if you specify pink (normal display) for the available choices, the selection
cursor is reverse image pink when it is located on an available choice. If you
specify pink reverse image for the available choices, the selection cursor is pink
(normal display). Likewise, if you do not specify CHCAVAIL, CHCUNAVAIL, or
CHCSLT and use the CUA default colors and attributes, the selection cursor is the
reverse image of those colors and attributes.
You can use only the CHCAVAIL keyword and the CHCSLT keyword for menu bars
because menu-bar choices are either available or selected. For selection fields,
use only the CHCAVAIL keyword and the CHCUNAVAIL keyword when you are
using selection characters (for example, numbers or radio buttons). The CHCSLT
keyword is ignored in these cases. However, you can use CHCSLT for selection
fields in a pull-down menu on graphical display stations or character-based graph-
ical display stations when you have specified that the pull-down menu should not
contain selection indicators (PULLDOWN(*NOSLTIND) specified).
You can use only the CHCAVAIL keyword and the CHCUNAVAIL keyword for push
buttons because push button choices are either available or unavailable.

The display-attribute (*DSPATR) parameter specifies the way in which the sepa-
rator characters display. The parameter is expressed in this form:
(\DSPATR value1 <value2 <value3...>>)
The valid values for the display attributes are:

Value Meaning
BL Blink
CS Column separator
HI High intensity
ND Nondisplay
RI Reverse image
UL Underline
The default display attribute for unavailable choices in a selection field on

monochrome display stations is normal (or low) intensity. Also, the first character
of an unavailable choice on a monochrome display station is overwritten with an
asterisk (*).
Display attributes CS, HI, and BL can cause fields on 5292, 3179, and 3197 Model
C1 and C2 display stations to appear as color fields. Display attributes HI, RI, and
UL cause a separator line not to be displayed. For more information, see the
CHCAVAIL keyword, the CHCUNAVAIL keyword, and the CHCSLT keyword in
DDS Reference.
In Figure 6-44, the choices in the menu bar are displayed in white on color display
stations and in high intensity on monochrome display stations. When a menu-bar
choice is selected, it is displayed in green on color display stations and reverts to
normal (not high intensity) display on monochrome display stations.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R MENUBAR MNUBAR
A MNUFLD 2Y ðB 1 2
A '>File ')
A &EDITTXT)
A '>View ')
A '>Options ')
A '>Help ')
A CHCAVAIL((\COLOR WHT) (\DSPATR HI))
A CHCSLT((\COLOR GRN))
A EDITTXT 2ðA P
.
.
.
Figure 6-44. DDS Using CHCAVAIL and CHCSLT for Menu-Bar Choices
In Figure 6-45 on page 6-41, the available selection-field choices are displayed in
pink on color display stations and in high intensity on monochrome display stations.

The unavailable selection-field choices are displayed in turquoise on color display
stations. On monochrome display stations, the unavailable choices are displayed
with normal (or low) intensity, and the first character in the choices is overwritten
with an asterisk (*).
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A ð1 CHOICE(1 '>Chocolate ')
A CHOICE(2 '>Strawberry ')
A CHOICE(3 '>Vanilla ')
A CHCCTL(1 &CTLCHOC MSG1112 QUSER/A)
A CHCCTL(2 &CTLSTRA &MSG &LIB/&MSGF)
A CHCCTL(3 &CTLVANI)
A CHCAVAIL((\COLOR PNK) (\DSPATR HI))
A CHCUNAVAIL((\COLOR TRQ))
A CTLCHOC 1Y ðH
A CTLSTRA 1Y ðH
A CTLVANI 1Y ðH
A MSG 7A P
A LIB 1ðA P
A MSGF 1ðA P
Figure 6-45. DDS Using CHCAVAIL and CHCUNAVAIL for Selection Fields
In Figure 6-46, the selection-field choice that is selected is displayed in yellow. If

CHECK(ER) (automatic-enter) is specified on this field, control is returned imme-
diately after selecting the choice.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R PULLDOWN PULLDOWN(\NOSLTIND)
A CHOICE(2 '>Mark ')
A CHCCTL(1 &CTLUNDO MSG1112 QUSER/A)
A CHCCTL(2 &CTLMARK &MSG &LIB/&MSGF)
A CHCCTL(3 &CTLCOPY)
A CHCAVAIL((\COLOR PNK) (\DSPATR HI))
A CHCUNAVAIL((\COLOR TRQ))
A CHCSLT((\COLOR YLW))
A CTLUNDO 1Y ðH
A CTLMARK 1Y ðH
A CTLCOPY 1Y ðH
.
.
.
Figure 6-46. DDS Using CHCAVAIL, CHCUNAVAIL, and CHCSLT for Selection Fields
In Figure 6-47, the DDS source for a Single Choice Selection list is shown (the
example does not show all the keywords necessary for a correct subfile definition).
Available choices within the list will be displayed in yellow. Unavailable choices will
be displayed in red. The selected choice will be displayed in green.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R SFLREC SFL
A R SFLCTLRCD SFLCTL(SFLREC)
A SFLSNGCHC
A .
A .
A .
A CHCAVAIL((\COLOR YLW))
A CHCUNAVAIL((\COLOR RED))
Figure 6-47. DDS Using CHCAVAIL, CHCUNAVAIL, and CHCSLT for Single Choice
Selection List Choices
In Figure 6-48, the DDS source for a Multiple Choice Selection list is shown (the
example does not show all the keywords necessary for a correct subfile definition).
Available choices within the list will be displayed in yellow. Unavailable choices will
be displayed in red. Any selected choices will be displayed in green.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R SFLREC SFL
A R SFLCTLRCD SFLCTL(SFLREC)
A SFLMLTCHC
A .
A .
A .
A CHCAVAIL((\COLOR YLW))
A CHCUNAVAIL((\COLOR RED))
Figure 6-48. DDS Using CHCAVAIL, CHCUNAVAIL, and CHCSLT for Multiple Choice
Selection List Choices
Continued-Entry Fields—Overview
A continued-entry field is a set of associated entry fields. Continued-entry fields
are supported on displays attached to any controller. Controllers that support an
enhanced interface for nonprogrammable work stations treat continued-entry fields
as single-entry fields while data is being entered and edited in the fields.
Note: Controllers that do not support an enhanced interface for nonprogrammable
work stations treat continued-entry fields as separate input fields. Insert
and delete characters one segment at a time. When you reach the end of a
segment, the cursor does not move automatically to the next segment.
Figure 6-49 on page 6-43 illustrates the use of continued-entry fields to create a
rectangular text entry field. Consider using this format to avoid using a single input
field that wraps across multiple lines.

Note: The empty space at the end of the last line is still part of the continued-
entry field. You cannot define another field in this space.
Enter Text . . . ________________________________________

________________________________________
________________________________________
________________________________________
________________________________________
Figure 6-49. Continued-Entry Fields in Rectangular Arrangement
A continued-entry field allows a multiple-row entry field to be defined inside of a

window or display.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A F1 9ðA B 3 4CNTFLD(3ð)
The CNTFLD keyword tells the system that this is a continued-entry field and its
parameter tells the system how wide the field should be. The system breaks the
field into columns and uses as many lines as it needs to reach the specified width.
Specifying Word Wrap on Continued-Entry Fields

To specify the word wrap function for a continued-entry field, use the word wrap
(WRDWRAP) keyword. This keyword can be used at the file, record, or field level.
Note: WRDWRAP cannot be used on DBCS continued-entry fields.
For more information about the WRDWRAP keyword, see “Specifying Word Wrap
for Fields” on page 2-20.
DBCS Considerations with Continued-Entry Fields

DDS supports these DBCS data types:
J Only (only bracketed DBCS characters allowed)
E Either (either only SBCS or only bracketed DBCS characters allowed)
O Open (either SBCS or bracketed DBCS characters allowed - mixed)
G Graphic/Pure (only nonbracketed DBCS characters allowed)
These data types will have the following restrictions:

J The width of each continued-entry field segment must be an even number of
at least 4 bytes.
E The width of each continued-entry field segment must be an even number of
at least 4 bytes.
O The width of each continued-entry field segment must be at least 4 bytes
wide.
G The width of each continued-entry field segment must be an even number of
at least 4 bytes.
The length of the DBCS continued-entry field must account for the SO/SI character
pairs that bracket the DBCS data on each segment of the continued-entry field.
The following total field lengths are required to ensure the field data fits into DBCS
continued-entry fields:

J or E (with DBCS data)
Data Length + (Number of segments - 1) * 2
O Data Length + (Number of segments - 1) * 3
G or E (with SBCS data)
Data Length
Note: The (Number of segments - 1) * 3 portion of the calculation in the second
equation allows for the SO/SI sets that must bracket the DBCS data on the
segments of the continued-entry field after the first segment. Additional
consideration is made for the possibility that a NULL must be placed at the
end of a segment wherever a DBCS character would be split.
How DBCS Data is Returned for Continued-Entry Fields

If the field is a DBCS-only or DBCS-either (with DBCS data) field, the following data
is not returned to the application:
The extra SO characters at the start of the middle and last segments
The extra SI characters at the end of the first and middle segments
If the field is a DBCS-open field, the following are removed before the field is
returned to the application:
All single byte subfields at the end of a segment which consist only of one null
or are empty. This is to remove any SO/SI pairs that most likely have been
automatically inserted as a result of double byte data falling on a segment
boundary. Removing the extra SI/SO characters occurs for all hardware
regardless of whether the controller supports an enhanced interface for nonpro-
grammable work stations.
Single byte nulls that end a segment if the following is true:
– The number of nulls is three or less
– The previous character is not an SI character or null
– The next segment begins with an SO character
This is to remove any nulls that most likely have automatically been inserted as
a result of double byte data falling on a segment boundary.
Keyboard Functions with Continued-Entry Fields

The system processes local keyboard functions specified within the continued-entry
fields on a display station attached to a controller that supports an enhanced inter-
face for nonprogrammable work stations by the following definitions:
Character data
In replace mode, there is no unique character data processing. When character
data is entered in the last character position of the first or one of the middle fields
in the set, the cursor moves to the first character position of the next field in the
set. When character data is entered in the last character position of the last field in
the continued fields, forward field-exit processing is performed (see “Forward Field-
Exit Processing” on page 6-49).
In insert mode and cursor direction matches field direction, the following actions
occur when a character data key is pressed:

The null in the last character position of the last field in the continued-entry
fields is deleted. If there is no null in the last position of this field, operator
error 0012 is posted.
All field data within the continued-entry fields at (and logically following) the
current cursor location are shifted one position. Each data character in the last
character position of the current and remaining fields (except the last) in the set
is shifted to the first character position of the following field.
The data character entered is written at the cursor location.
The cursor advances to the next cursor position.
For DBCS-only, DBCS-either (with DBCS data), and DBCS-pure fields, the two
nulls in the last two character positions (before the SI for DBCS-only or
DBCS-either fields) of the last segment of the continued field are deleted. If
there are not nulls in the last two positions of that segment, operator error 0012
is posted. Otherwise, all field data (not including the SO or SI characters)
within the set of field segments at and logically following the current cursor
location is shifted two positions in the cursor direction. Each double byte char-
acter in the last two character positions of the current and remaining segments
(except the last) is moved to the first two character positions of the following
segment. The DBCS character entered is written at the cursor location, and
the cursor advances to the next double byte cursor position.
For DBCS-open fields the data in the continued field segments, at and to the
right of the cursor, is copied into one continuous buffer. The inserted character
is placed at the start of the buffer. All single byte nulls are removed from the
buffer, and the data is shifted toward the beginning of the buffer. All adjacent
SI/SO character pairs (that is, empty single byte subfields) are also removed
from the buffer. The data is again shifted toward the beginning of the buffer.
The data is then placed back into the continued field one character at a time,
according to the algorithm for writing data into a DBCS-open continued field.
The remaining character positions are replaced with nulls. The cursor also
advances to the next character position. If all the data in the buffer cannot fit
into the continued field, operator error 0012 is posted, and the field data and
cursor position are not changed.
In insert mode and cursor direction does not match field direction, the insert takes
place within a subfield. The insert is the same as if the field and cursor direction
matched, but the insert is performed within the subfield. The extent of a subfield is
defined as follows:
When the cursor direction is right-to-left, the subfield extends from the cursor to
the first null logically following the cursor. If there is no such null, the subfield
includes all positions logically following the cursor.
When the cursor direction is left-to-right, the subfield extends from the cursor to
the first null logically following the cursor. If there is no such null, the subfield
includes all positions logically following the cursor.
Field Mark
Processed the same as character data.

Automatic Shape Determination (ASD) Processing
For Arabic, ASD occurs if the cursor direction is right-to-left.
Delete
If the delete key is pressed within a continued-entry field and the cursor direction
matches the field direction, the following actions occur:
All field data within the continued-entry fields logically following the current
cursor location is shifted toward the cursor one position. Each data character
in the first character position of the remaining fields in the set is shifted to the
last character position of the preceding field.
A null is written in the last character position in the continued-entry fields.
For DBCS-only, DBCS-either (with DBCS data), and DBCS-pure continued
fields, all field data (not including the SO and SI characters) within the set of
field segments logically following the current cursor location is shifted toward
the cursor two positions. Each DBCS character in the first double byte char-
acter position of the remaining segments is moved to the last double byte char-
acter position of the preceding segment. A double byte null is written in the
last double byte character position of the last segment.
For DBCS-open fields, the data in the set of field segments, at and to the right
of the cursor, is copied into one continuous buffer. The deleted character or
subfield is removed from the start of the buffer. In addition, all single byte nulls
are removed from the buffer, and the data is shifted toward the beginning of the
buffer. All adjacent SI/SO character pairs (that is, empty single byte subfields)
are also removed from the buffer. The data is again shifted toward the begin-
ning of the buffer. The remaining data, then, is placed back into the continued
field one character at a time, according to the algorithm for writing data into a
DBCS-open continued field. The remaining character positions are replaced
with nulls.
If the delete key is pressed within a continued field when the cursor direction and
field direction do not match, the delete is performed within a subfield. The defi-
nition for subfields is the same as for the insert key.
Erase EOF
All field positions at (and logically following) the current cursor location within the
continued-entry fields are nulled. In DBCS-only, DBCS-either (with DBCS data),
and DBCS-pure fields, the SO and SI characters are not nulled out. In DBCS-open
fields, an SI character may additionally be written at the current cursor location if
the erase began in a double byte subfield.
Erase Input
All field positions of all changed fields are nulled. This includes all continued-entry
field segments if any continued-entry field segment has been changed. In
DBCS-only, DBCS-either (with DBCS data), and DBCS-pure fields, the SO and SI
characters are not nulled out.
Reverse
The cursor direction is reversed. If the preceding keystroke was not a cursor
movement key, the cursor is repositioned to the new first character position of the
current segment.

Close
The close key operates on a single continued field segment. All embedded nulls
are removed. The cursor direction is set to the field direction. The remaining char-
acters are shifted to begin at the first character position of the continued field
segment. The remainder of the segment is padded with nulls and the cursor is
placed logically following the last non-null character.
Field Exit
Pressing the Field Exit key within a continued-entry field causes the following
actions to occur:
current cursor location are nulled. In DBCS-only, DBCS-either (with DBCS
data), and DBCS-pure fields, the SO and SI characters are not nulled out. In
DBCS-open fields, an SI character may additionally be written at the current
cursor location if the nulling began in a double byte subfield.
Forward field-exit processing is performed (see “Forward Field-Exit Processing”
on page 6-49).
Field Plus
Processed the same as Field Exit.
Field Minus
Not allowed. Operator error 0016 is posted.
Dup
Pressing the Dup key within a continued-entry field causes the following actions to
occur:
current cursor location are set to the Dup character (1C). In DBCS-only,
DBCS-either (with DBCS data), and DBCS-pure fields, the SO and SI charac-
ters are not replaced with the Dup character. In DBCS-open fields, the cursor
must be on the very first character (whether it is a single byte or double byte
character) when the Dup key is pressed. Every character of every segment is
replaced with the Dup character ('1C') including all SO and SI characters. If the
cursor is not on the first character, operator error 0019 is posted.
Forward field-exit processing is performed (see “Forward Field-Exit Processing”
on page 6-49).
Kanji
The Kanji key causes the following actions to occur when pressed within a
DBCS-either continued field:
If the cursor is not at the first field position (when in single byte mode) of the
first segment, or at the second field position (when in double byte mode) of the
first segment, operator error 0062 is posted.
Otherwise, if the field is currently in double byte mode, it is placed into single
byte mode by replacing every character position of every segment with nulls.
The cursor is also placed at the first field position of the first segment.
Otherwise, if the field is currently in single byte mode, it is placed into double
byte mode by replacing every character position of every segment with nulls,
and writing SO and SI characters at the start and end of each field segment
respectively. The cursor is also placed in the first segment immediately fol-
lowing the shift out character.

In DBCS-open continued fields, the Kanji key inserts either a SO/SI character pair,
or an SI/SO character pair as is currently done for non-continued open fields. For
continued fields, this insert is performed using the same algorithm that characters
are inserted into an DBCS-open continued field. However, when a SI/SO pair is
inserted, the empty single byte subfield that is created is not immediately removed.
The cursor is also placed under the second shift character and the keyboard goes
into insert mode.
Character Backspace
Pressing the Character Backspace key in the first position (or first DBCS character
in any DBCS-pure, DBCS-only, or DBCS-either field) of the first segment, moves
the cursor to the last position of the previous field. (The previous field could be a
continued-entry field. The cursor moves to the last position of the last segment
which could be further down on the display.) If the resulting cursor position is in a
DBCS-open, DBCS-only, or DBCS-either field, any SI character at the last position
is skipped. Pressing the Character Backspace key in the first position in a segment
(or first DBCS character in DBCS-pure, DBCS-only, or DBCS-either fields in double
byte mode) other than the first segment, moves the cursor to the last position of the
previous segment. If that resulting position is on a DBCS-only or DBCS-either field
SI character, the SI character is skipped. In addition, within DBCS-open fields,
single byte subfields at the end of a non-last segment are skipped by character
backspace if they consist only of 1 null character. This is to skip nulls that most
likely have been automatically inserted when splitting DBCS data on segment
boundaries.
Character Advance
Pressing the Character Advance key in the last position (or last double byte char-
acter in DBCS-pure, DBCS-only, or DBCS-either fields in double byte mode) of the
last segment, moves the cursor to the first position of the next field. Pressing the
Character Advance key in the last position (or last double byte character in
DBCS-pure, DBCS-only, or DBCS-either fields in double byte mode) of a segment
other than the last segment, moves the cursor to the first position of the next
segment. If the resulting position is on a DBCS-only or DBCS-either field SO char-
acter, the SO character is skipped. In DBCS-open fields, single byte subfields at
the end of a segment are skipped if they consist of only one null. This is to skip
nulls that most likely have been automatically inserted when splitting DBCS data on
segment boundaries.
New Line
Pressing the New Line key generally moves the cursor to the next position on the
display that allows a cursor. If the cursor is in a continued-entry field and an addi-
tional continued-entry field segment is on the next row or a subsequent row, the
cursor moves to the first position of that segment. If the continued-entry field is
also a highlighted field with an invisible text cursor, then pressing the New Line key
exits the continued-entry field. If the resulting position is in a new DBCS-open,
DBCS-only, or DBCS-either field segment of the same field, any S0 character at
the resulting cursor location is skipped. When the cursor moves into a continued-
entry field because the New Line key was pressed, the cursor is always positioned
in the first position of the first segment. Pressing the New Line key never moves
the cursor into a middle or last continued-entry field segment.

Field Advance
Field Advance performs forward field-exit processing (see “Forward Field-Exit
Processing”).
Field Backspace
When pressed while the cursor is not in the first position (or first DBCS character in
a DBCS-pure, DBCS-only, or DBCS-either field) of the first segment, the cursor
moves to the first position (or first DBCS character in a DBCS-pure, DBCS-only, or
DBCS-either field) of the first segment. Otherwise, Field Backspace performs back-
ward field-exit processing (see “Backward Field-Exit Processing”).
Forward Field-Exit Processing

The system does not validate field data when the cursor exits continued-entry fields
because mandatory fill and self-check functions are not supported.
If the continued-entry fields are specified as automatic-enter or forward-edge

trigger, the system performs automatic-enter or forward-edge trigger processing for
the last position of the last segment.
If cursor progression is specified on the first continued-entry field segment, the

cursor moves to the cursor-progression target field when it exits any of the
continued-entry field segments.
If cursor progression is not specified on the first continued-entry field segment, and
the cursor exits the continued-entry field in the forward direction, the cursor skips
any subsequent segments of the continued-entry field and moves to the next non-
protected field. The next nonprotected field is determined by exiting the first con-
tinued field segment, independent of which segment contained the cursor. If the
resulting position is in a DBCS-open, DBCS-only or DBCS-either field, any SO
character at the first position is skipped. The cursor is placed at the second posi-
tion.
Note: If a continued-entry field is also defined as a highlighted field, the system
restores the leading-field attribute of each segment when the cursor exits
the field.
Backward Field-Exit Processing

When exiting the field backward, the cursor skips any previous segments of the
continued-entry field and moves to the previous nonprotected field. Cursor
progression may cause the cursor to move to a different field. The previous non-
protected field is determined by exiting the first continued field segment, inde-
pendent of which segment contained the cursor. If the resulting position is in a
DBCS-open, DBCS-only or DBCS-either field, any SO character at the first position
is skipped. The cursor is placed at the second position.
Note: DBCS support within continued-entry fields are available for displays
attached to any controller. However, the keyboard functions are only available for
displays connected to a controller that supports an enhanced interface for nonpro-
grammable work stations.

How the Menu Bar Interacts with the Application
The MNUBARDSP keyword is used to display a menu bar. The MNUBARDSP
keyword can be used on an application record (the record that defines the applica-
tion display) or on a menu-bar record. Option indicators can be used on the
MNUBARDSP keyword to control when the menu bar is displayed. If
MNUBARDSP is used on the application record, several optioned MNUBARDSP
keywords can be specified so that the application can display different menu bars
for the same record. If more than one MNUBARDSP keyword is in effect, the
system uses the first one.
Defining the MNUBARDSP Keyword on the Application Record

When the MNUBARDSP keyword is used on the record that defines the application
display, the system handles all menu-bar operations for the application. The
system returns the number of the menu-bar choice selected in a hidden field that is
specified on the MNUBARDSP keyword and defined in the application record. If no
menu-bar choice is selected, 0 is returned in the hidden field.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A HELP ALTHELP CFð3
A R MENUBAR MNUBAR
A MNUFLD 2Y ðB 1 2
A '>File ')
A &EDITTXT)
A '>View ')
A '>Options ')
A '>Help ')
:
:
A R APPSCR MNUBARDSP(MENUBAR &MNUCHOICE)
A FIELD1 1ðA B 1ð 12
A FIELD2 5S ðB 14 12
A 24 1'F1=Help F3=Exit +
A F1ð=Actions F12=Cancel '
A MNUCHOICE 2Y ðH
Figure 6-50. DDS Using MNUBARDSP on the Application Record
The DDS in Figure 6-50 causes the following to happen:

1. The application writes any pull-down menu records or menu-bar records that
have output to be supplied by the application.
2. The application does a write-read operation to the record with the
MNUBARDSP keyword.
3. The system displays the menu bar identified by the MNUBARDSP keyword and
handles all interaction between the menu bar and the pull-down menu.

4. If the user selects a menu-bar choice and enters input in the pull-down menu,
the system returns the number of the menu-bar choice selected in the choice-
hidden field specified on MNUBARDSP.
The system displays the menu-bar record first and then performs the write-read
operation to the application record. The active function keys and command keys
are those defined on the application record and not those defined on the menu-bar
record. If you want to use the MNUCNL keyword or the MNUBARSW keyword,
define them at the file level or on the application record.
Ordinarily, writing a record to the display without the OVERLAY keyword causes
the entire display to be erased before the record is displayed. The system displays
the menu-bar record followed by the application record as if they were logically one
record. The system automatically prevents the application record from erasing the
menu-bar record. In Figure 6-50 on page 6-50, when the system writes the appli-
cation record, it clears the entire display except for the menu-bar record. The
menu-bar record is always processed as though it contains the OVERLAY keyword
regardless of any other specifications. For example, if the CLRL keyword is speci-
fied on the menu-bar record, it is not used when the menu-bar record is processed.
The OVERLAY keyword and the CLRL keyword are processed normally for the
application record; however, the menu-bar record is not cleared.
Defining the MNUBARDSP Keyword on the Menu-Bar Record

If you use the MNUBARDSP keyword on the record containing the menu bar, the
application controls when the menu bar is displayed. The system continues to
handle any pull-down menu interaction that takes place, and returns the number of
the menu-bar choice selected in the menu-bar field itself. If no menu-bar choice
was selected, 0 is returned in the menu-bar field. The application must both write
the menu-bar record to display the menu bar and read the menu-bar record to
determine what choice, if any, was selected.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R MENUBAR MNUBAR OVERLAY
A ð1 MNUBARDSP
A MNUFLD 2Y ðB 1 2
A '>File ')
A &EDITTXT)
A '>View ')
A '>Options ')
A '>Help ')
A EDITTXT 2ðA P
:
:
A R APPSCR OVERLAY
Figure 6-51. DDS Using MNUBARDSP on the Menu-Bar Record
Following is one scenario using the DDS in Figure 6-51.

1. The application writes the menu-bar record, with the MNUBARDSP keyword
active, to display the menu bar.
2. The application does a write-read operation to the application record.
3. The system handles any interaction between the menu bar and the pull-down
menu.
4. On input, the application receives the application record.
5. The application reads the menu-bar record to determine which menu-bar
choice, if any, was selected.
The only active command keys and function keys are those defined on the applica-
tion record and not those defined on the menu-bar record. If you want to use the
MNUCNL keyword or the MNUBARSW keyword, define them at the file level or on
the application record.
Following is another scenario using the DDS in Figure 6-51.

1. The application writes the application record.
2. The application performs a write-read operation to the menu-bar record, with
the MNUBARDSP keyword active, to display the menu bar.
3. The system handles any interaction between the menu bar and the pull-down
menu.
4. On input, the application receives the menu-bar record and determines which
menu-bar choice, if any, was selected.

5. The application can also read the application record to receive any input
entered on the display.
The only command keys and function keys that are valid are those defined on the
menu-bar record. If you want to use the MNUCNL keyword or the MNUBARSW
keyword, define them at the file level or on the menu-bar record.
Receiving Input from the Pull-Down Menus

| If a pull-down menu record contains output data, it must be written before writing
| the menu-bar record. For example, option indicators may be set or output fields
may be filled in. These pull-down menu records are not displayed when written;
the system processes and saves the record output until the menu bar is displayed.
A menu-bar record may also be written without being displayed. If the system
attempts to write a pull-down menu record or a menu-bar record (without the
MNUBARDSP keyword optioned on) while the corresponding menu bar is dis-
played, an error occurs and the record is not written.
When a valid attention identifier (AID) key (other than the cancel key and the
menu-bar switch key) is pressed when a pull-down menu is displayed, control is
returned to the application and input may be received from the pull-down menu.
The valid AID keys that return input are the Enter key and any CFxx keys that are
defined on the pull-down menu record. (A CAxx key returns control to the applica-
tion, but does not return input.) Keys that are defined for the background display
are not valid unless they are also defined on the pull-down menu record. There-
fore, define the background keys and the pull-down menu keys once at the file
level.
Once a valid AID key (one that returns input) is pressed for a pull-down menu, the
application receives input for the record being read (either the application record or
the menu-bar record). By looking at the menu-bar choice number that is returned
in this record, the application can determine which pull-down menu record has
input. The application then must read that pull-down menu record. No I/O opera-
tion is done to the display; the input from the pull-down menu is returned to the
application and the pull-down menu remains displayed.
Receiving Input from Pull-Down Menus Using the Pull-Down

Input Parameter
When one or more of the pull-down menu records contain only one single-choice
selection field, you can use the pull-down input (PULLINPUT) parameter on the
MNUBARDSP keyword. This lets you receive the single-selection field choice
along with the menu-bar choice, instead of reading the pull-down menu record to
receive the single-selection field choice.
Figure 6-52 on page 6-54 illustrates the use of the PULLINPUT parameter on the
MNUBARDSP keyword.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R MENUBAR MNUBAR
A MNUFLD 2Y ðB 1 2
A '>File ')
A MNUBARCHC(2 PULLEDIT +
A '>Edit ')
A '>View ')
A R PULLFILE PULLDOWN
A 2 1'File name . . . '
A FNAME 1ðA I 2 18
A R PULLEDIT PULLDOWN
A CHOICE(2 '>Delete ')
A R PULLVIEW PULLDOWN
A CHOICE(1 '>All ')
A CHOICE(2 '>Some... ')
A CHOICE(1 'By >date ')
A CHOICE(2 'By >subject ')
A R APPSCR MNUBARDSP(MENUBAR &MNUCHOICE +
A &PULLINPUT)
A MNUCHOICE 2Y ðH
A PULLINPUT 2S ðH
Figure 6-52. DDS for Pull-Down Input (PULLINPUT) Parameter
When the PULLINPUT parameter is specified on the MNUBARDSP keyword, one

of the following values will be returned to the application:
Note: The value is returned in the hidden field (PULLINPUT in Figure 6-52) you
have defined in the record with the MNUBARDSP keyword.
PULLINPUT Contents Meaning
0 No selection made.
n Choice n in the pull-down menu was selected.
-1 Pull-down menu record contains something other than
one single-choice selection field. You must read the
pull-down menu record to receive its contents.
Table 6-6 on page 6-55 shows the values that are returned in the MNUCHOICE
field and the PULLINPUT field using the DDS in Figure 6-52.

Table 6-6. Values Returned in MNUCHOICE and PULLINPUT
Value Returned in Appropriate Field
Menu-Bar Choice Selected MNUCHOICE PULLINPUT
File 1 -1
Edit (no selection made in pull-down menu) 2 0
Edit (Copy choice in pull-down menu selected) 2 1
View 3 -1
Removing a Pull-Down Menu after Receiving Input

After the application receives input from a pull-down menu, it may remove the pull-
down menu under certain conditions. For example, the application removes the
pull-down menu when the application writes or reads (1) a non-window record (in
the same display file) or (2) a window record (in the same display file) that contains
the RMVWDW keyword. The pull-down menu remains on the display if the applica-
tion writes or reads a window record (without RMVWDW). This allows the applica-
tion, UIM help, or application help to write a help window to the display without
removing the pull-down menu.
To remove a pull-down menu and present another non-window application display,

the application writes the appropriate application record, and the pull-down menu is
removed.
To remove the pull-down menu and keep the current application display (perhaps
updated), the application performs another write-read (or read) operation to the
current (or changed) application record.
To remove the pull-down menu and display a window, the application writes a
window with the RMVWDW keyword specified.
To remove the pull-down menu and call another program, the application writes to
a dummy record and then calls the other program.
To leave the pull-down menu on the display and present a window (perhaps a help
window), the application writes the window record (without RMVWDW).
A pull-down menu remains on the display while UIM help is displayed in a window.
A pull-down menu also remains on the display while application help is displayed if
the application help record is a window and does not have the RMVWDW keyword
specified.
Updating a Pull-Down Menu before Displaying

You can enable your application to update a pull-down menu using the return-field
parameter on the MNUBARCHC keyword. The pull-down menu is updated after a
menu-bar choice is selected and before the pull-down menu is displayed. The
return-field parameter is a hidden field that returns the number of the choice
selected for the application to (1) determine that control was returned before the
pull-down menu was displayed rather than because input was entered in the pull-
down menu, and (2) determine which pull-down menu record to update and write.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A R MENUBAR MNUBAR
A MNUFLD 2Y ðB 1 2
A '>File ' &RTNFLD)
:
:
A MNUBARCHC(4 PULLOPT +
A '>Options ' +
A &RTNFLD)
:
A RTNFLD 2Y ðH
:
A R PULLFILE
A PULLDOWN
:
:
A R PULLOPT
A PULLDOWN
:
:
Figure 6-53. DDS for Return-Field Parameter
For the DDS in Figure 6-53, if the user selects menu-bar choice 1 or 4, control is
returned to the application with the choice number set in the RTNFLD field. The
menu-bar field or the choice field in the application record contains 0, indicating no
pull-down menu input was received. The application must read the menu-bar
record to get the contents of the RTNFLD field. The application then updates the
pull-down menu record for that choice and writes it. The application must read the
menu-bar record or the application record to request the display. After control has
been returned for updating the pull-down menu, the next record written must be the
pull-down menu specified on the MNUBARCHC keyword. In this example, if choice
1 was selected, record PULLFILE must be written; if choice 4 was selected, record
PULLOPT must be written. The system then displays the pull-down menu for the
choice and resumes control of the menu bar and pull-down menu interaction. A
read operation to a pull-down menu is not allowed until input has been received for
the pull-down menu. A write-read operation is never allowed.
Defining Application Help

You can define application help for menu-bar choices, selection-field choices,
named fields, constant fields, menu bars, and pull-down menus.
Defining Choice-Level Help

You can define help for menu-bar choices, single-choice selection fields, and
multiple-choice selection fields using the HLPARA keyword. Figure 6-54 on
page 6-57 is an example of the DDS coding for menu-bar choice help.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A HELP
A R MENUBAR MNUBAR
A H HLPARA(\FLD MNUFLD 1)
A HLPRCD(FILEHLP LIB/FILE)
A HLPRCD(EDITHLP LIB/FILE)
A HLPRCD(VIEWHLP LIB/FILE)
A HLPRCD(OPTHLP LIB/FILE)
A HLPRCD(HLPHLP HLPLIB/HLPFILE)
A MNUFLD 2Y ðB 1 2
A '>File ')
A &EDITTXT)
A '>View ')
A '>Options ')
A '>Help ')
A EDITTXT 1ð P
Figure 6-54. DDS for Menu-Bar Choice Help
Figure 6-55 is an example of the DDS coding for single-selection field choice help.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A HELP
A R PULLEDIT CFð4 CFð6
A WDWBORDER((\CHAR '+-+||+-+'))
A PULLDOWN
A H HLPARA(\FLD F1 1)
A HLPRCD(UNDOHLP LIB/FILE)
A HLPRCD(MARKHLP LIB/FILE)
A HLPRCD(COPYHLP LIB/FILE)
A CHECK(ER)
A CHOICE(2 '>Mark ')
Figure 6-55. DDS for Single-Selection Field Choice Help
Use the \FLD special value on the HLPARA keyword to indicate that the help area
is for a field. Following \FLD, specify the name of the field for which you are
defining help. Following the name of the field, specify the number of the choice for
which you are defining help.

The help area that you specify for a choice is the area that the choice text occupies
(plus the attribute byte positions on either side). If compression occurs, the help
area moves with the choice. When a choice is optioned off, the help specification
for that choice is also optioned off because the help area for that choice does not
exist.
As with any help specification, the text for choice-level help can be defined using
DDS records (HLPRCD keyword), OfficeVision* documents (HLPDOC keyword), or
UIM panel groups (HLPPNLGRP).
Help specifications must define help areas within the area encompassed by the
menu-bar record or the pull-down record.
If you use UIM help, item-specific help for a menu-bar choice includes the help
modules for the menu-bar choice and its pull-down menu. If you use DDS or
OfficeVision document help, item-specific help for the menu-bar choice is the help
for the menu-bar choice. The help area for the menu-bar choice includes the text
for the choice plus one space on each side of the text. The middle space between
the choices is part of the extended help area.
Item-specific help for menu bars is displayed when the cursor is located in one of
the following areas:
A menu-bar choice (if there is help for that choice).
Anywhere within an active pull-down record that does not include an active help
area. When the cursor is on the pull-down menu border, item-specific help is
displayed for the menu-bar choice item.
Item-specific help for a pull-down menu choice is displayed when the cursor is in an
active help area in the pull-down menu. The help area for a pull-down menu
choice starts on the first digit of the number and ends at the border of the selection
field. Help for pull-down menus and menu bars are part of the extended help for
the display. When the pull-down menu is displayed, all help areas are active
except the ones that are overlapped by the pull-down menu. Help for overlapped
areas can be viewed only in extended help. If a base display help area is partially
overlapped by a pull-down menu, the part of the help area that is not overlapped is
still active.
There are two help lists; one for the base display and one for the menu bar and its
pull-down menus. The help list for the menu bar is created when the menu bar is
displayed. The help list is destroyed when the menu bar is removed from the
display. For an example of a help list for a menu bar, see Figure 6-56 on
page 6-59. The help list is updated when the menu bar or pull-down menu is
written again. When the cursor is in a menu bar or pull-down menu, the menu-bar
help list is searched for item-specific help. The menu-bar help list is considered
above the base-display help list. When extended help is displayed, help for menu
bars and pull-down menus is presented immediately after general help. Base
display help is presented after menu-bar help and pull-down menu help. If DDS
help is used and the user initially selects pull-down menu help, the user then can
page up to see menu-bar help and page down to see base-display help.

┌────────────────────────────────────┐
│ Help for File menu bar choice │
├────────────────────────────────────┤
│ Help for File pulldown choice 1 │
├────────────────────────────────────┤
│ Help for File pulldown choice 2 │
├────────────────────────────────────┤
│ . │
│ . │
│ . │
├────────────────────────────────────┤
│ Help for View menu bar choice │
├────────────────────────────────────┤
│ Help for View pulldown choice 1 │
├────────────────────────────────────┤
│ Help for View pulldown choice 2 │
├────────────────────────────────────┤
│ . │
│ . │
│ . │
└────────────────────────────────────┘
Figure 6-56. A Help List for a Menu Bar
Defining Help for a Field

Help can be defined for a field or constant using the HLPARA keyword. For a
named field, specify the help area using the *FLD special value and the name of
the field. For a constant field, specify the help area using the *CNST special value
and an identifier for the constant field. The identifier you specify on the HLPARA
keyword should be the same as the value specified on the HLPID keyword for the
constant field.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A HELP
A R RECORD
A H HLPARA(\FLD FIELD)
A HLPRCD(FIELDHLP LIB/FILE)
A FIELD 1ðA B 5 5
Figure 6-57. Help for a Named Field
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A HELP
A R RECORD
A H HLPARA(\CNST 1)
A HLPRCD(HLPCNST1 LIB/FILE)
A 2 2'Constant field' HLPID(1)
Figure 6-58. Help for a Constant Field
When the display file is created, the actual help area coordinates are determined by
the DDS compiler. These coordinates are shown in the expanded source section
of the DDS listing (unless the field is a choice field).

If the field or constant field location or length is changed and the file is re-created,
the help area for the field is updated to reflect the new location or length.
Key Interaction for Menu Bars and Pull-Down Menus

Figure 6-59 shows an example of a display you might create with a menu bar and
a pull-down menu. Capital letters A, B, C, D, and E indicate possible cursor
locations.
à .A/File.A/ Edit .B/ View Options Help .B/

ð
--------+---------------------+-----------------------------------------------
| _ 1..C/Undo .C/|
| .D/ .D/
| 3. Copy F1ð |
+---------------------+
.E/ F1=Help F3=Exit F9=View all F1ð=Actions F11=Copy
á ñ
Figure 6-59. Cursor Locations
Table 6-7 on page 6-61 describes the actions that are performed when certain
keys are pressed at the cursor locations.

Table 6-7. Actions Performed at Different Cursor Locations
Action Performed When Appropriate Key Is Pressed
Cursor
Location Help Cancel Menu-Bar Switch Enter
.A/ Help for File Pull-down menu is Pull-down menu is File pull-down menu is
menu-bar choice is removed. Cursor removed. Cursor displayed; Edit pull-
displayed. (Includes moves to Edit returns to display down menu is removed.
help for the pull-down menu-bar choice. work area.
menu.)
.B/ Extended help is dis- Pull-down menu is Pull-down menu is Cursor not on menu bar
played. removed. Cursor removed. Cursor choice message is dis-
moves to Edit returns to display played. Cursor does
menu-bar choice. work area. not move.
.C/ Help for Undo choice Pull-down menu is Pull-down menu is If user made a
is displayed. removed. Cursor removed. Cursor selection, control
moves to Edit returns to display returns to application. If
menu-bar choice. work area. not, cursor moves to
input field and message
to make a selection is
sent.
.D/ Help for Edit Pull-down menu is Pull-down menu is If user made a
menu-bar choice is removed. Cursor removed. Cursor selection, control
displayed. (Includes moves to Edit returns to display returns to application. If
help for the pull-down menu-bar choice. work area. not, cursor moves to
menu.) input field and message
to make a selection is
sent.
.E/ Help for function keys Pull-down menu is Pull-down menu is If user made a
is displayed. removed. Cursor removed. Cursor selection, control
moves to Edit returns to display returns to application. If
menu-bar choice. work area. not, sound beep and
cursor moves to input
field.
Cursor Movement
You can move the cursor on the application displays that you create using the Tab
key or the Cursor keys.
Pressing the Tab Key

Pressing the tab key moves the cursor from field to field on the display, progressing
from left to right and top to bottom.
On display stations in configuration F from Table 6-2 on page 6-3, the following is
true:
The Menu-bar choices are individual fields.
The single-choice selection field is one field.
The multiple-choice selection fields are individual fields.
Pressing the Tab key for one of these displays when no pull-down menu is dis-
played moves the cursor from choice to choice in the menu bar. Then, the cursor
moves from input field to input field on the rest of the display. When a pull-down

menu is displayed on one of these displays, pressing the Tab key does the fol-
lowing:
1. Moves the cursor from choice to choice in the menu bar.
2. Skips over the choice selected.
3. Moves the cursor from input field to input field within the pull-down menu.
4. Moves the cursor back to the first choice in the menu bar (the pull-down menu
for that choice is not automatically displayed).
While the pull-down menu is displayed, you cannot enter data in the input fields on
the base display nor can you tab to the input fields.
On display stations in configurations A, B, and C from Table 6-1 on page 6-2, and
configurations D and E from Table 6-2 on page 6-3, the menu bar is a single field.
If no pull-down menu is displayed, pressing the Tab key moves the cursor from
choice to choice within the menu bar. The cursor performs a wraparound. When a
menu-bar choice is selected, the cursor is placed in the first input field within the
pull-down menu. Pressing the Tab key moves the cursor from input field to input
field within the pull-down menu and then moves the cursor to the next menu-bar
choice. While the pull-down menu is displayed, you cannot enter data in the input
fields on the base display nor can you tab to the input fields on the base display.
Pressing the Cursor Keys

On display stations in configuration F from Table 6-2 on page 6-3, pressing a
cursor key moves the cursor one position in the appropriate direction.
On display stations in configurations A, B, and C from Table 6-1 on page 6-2, and
configurations D and E from Table 6-2 on page 6-3, the cursor moves differently
depending on the type of field it is in.
In the menu bar, pressing the cursor-right or cursor-left keys moves the cursor
from choice to choice. The cursor does not perform a wraparound.
In the base display, pressing any cursor key moves the cursor one position in
the appropriate direction.
When the cursor is positioned on a selection field, see:
– “Cursor Movement in a Vertical Selection Field” on page 6-15.
– “Cursor Movement in a Horizontal Selection Field” on page 6-16.
Following are examples of the DDS required to display a menu bar and a pull-down
menu with a description of how the DDS coding works.
Using the MNUBARDSP Keyword on the Application Record

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A CFð4(ð4) CFð6(ð6)
A R MENUBAR MNUBAR
A HLPRCD(FILEHLP HLPLIB/HLPFILE)

A HLPRCD(EDITHLP HLPLIB/HLPFILE)
A HLPRCD(VIEWHLP HLPLIB/HLPFILE)
A HLPRCD(OPTHLP HLPLIB/HLPFILE)
A HLPRCD(HELPHLP HLPLIB/HLPFILE)
A H HLPARA(\FLD MNUFLD)
A HLPRCD(MNUBARHLP HLPLIB/HLPFILE)
A MNUFLD 2Y ðB 1 2
A '>File ')
A &EDITTXT)
A '>View ')
A '>Options ' &RTNFLD)
A '>Help ')
A CHCAVAIL((\COLOR YLW) (\DSPATR HI))
A EDITTXT 2ðA P
A RTNFLD 2Y ðH
A R PULLEDIT
A PULLDOWN
A HLPRCD(UNDOHLP HLPLIB/HLPFILE)
A HLPRCD(MARKHLP HLPLIB/HLPFILE)
A HLPRCD(COPYHLP HLPLIB/HLPFILE)
A CHECK(ER)
A CHCACCEL(1 'F4')
A CHCACCEL(2 'F6')
A CHCAVAIL((\COLOR WHT))
A CHCUNAVAIL((\COLOR BLU))
A MARKTXT 2ðA P
A CTLUNDO 1Y ðH
A CTLMARK 1Y ðH
A CTLCOPY 1Y ðH
A MSG 7A P
A LIB 1ðA P
A MSGF 1ðA P
A R PULLOPT
A PULLDOWN
:
:

:
:
A R APPSCR MNUBARDSP(MENUBAR &MNUCHOICE +
A &PULLINPUT)
A MNUCHOICE 2Y ðH
A PULLINPUT 2S ðH
Description
In the example using the MNUBARDSP keyword on the application record, the
application does a write-read operation to the APPSCR record. This causes the
MENUBAR record and the APPSCR record to be displayed. Because the field
EDITTXT in the MENUBAR record contains the text >Edit, Edit is displayed as the
text for the second menu-bar choice.
Pressing the F10 key provides quick access to the menu bar (which is always
active). Pressing F10 moves the cursor to the first choice in the menu bar.
Pressing F10 again (or F12) moves the cursor back to where it was on the applica-
tion display. On display stations in configuration F from Table 6-2 on page 6-3,
pressing the Tab key moves the cursor from choice to choice in the menu bar. The
cursor skips over any menu-bar choice that is selected. It then moves from input
field to input field on the entire display. On display stations in configurations A, B,
and C from Table 6-1 on page 6-2, and configurations D and E from Table 6-2 on
page 6-3, when the cursor is located within a menu bar, the cursor movement keys
or the Tab key moves the cursor from choice to choice within the menu bar.
If the user selects the Edit action, the system displays the pull-down menu record
(PULLEDIT). CHECK(ER) specifies automatic-enter. When the user types a value
in F1, control is returned to the application without the user having to press the
Enter key. If the user presses F4 or F6, control is also returned to the application.
Because the application performed a write-read operation to the APPSCR record,

the APPSCR record is returned to the application. Field MNUCHOICE contains a 2
to identify that menu-bar choice 2 was selected. The PULLINPUT field contains the
single-selection field choice (the contents of F1) of the PULLEDIT record.
If the user selects the Options action, control is returned to the application, with 4
set in field RTNFLD and 0 set in field MNUCHOICE. The application determines
from the 0 in field MNUCHOICE that control has been returned for pull-down menu
update. The application reads record MENUBAR to obtain the choice number set
in field RTNFLD. The application updates the record PULLOPT and then writes
record PULLOPT. The system then displays PULLOPT as the pull-down menu for
the options choice. The system resumes control of the menu bar interaction when
the application performs a read operation to the APPSCR record.
menu bar separator and the pull-down menus display as solid lines.
On display stations in configuration C from Table 6-1 on page 6-2, and configura-
tions D, E, and F from Table 6-2 on page 6-3), the menu-bar separator is made up
of dashes. The side and bottom borders of the pull-down menu are made up of
colons and periods, respectively.

On display stations in configuration C from Table 6-1 on page 6-2, each menu-bar
choice has a mnemonic. On display stations in configurations A and B from
Table 6-1 on page 6-2, each single-selection field choice in the PULLEDIT pull-
down menu has a mnemonic. This is true unless ENHDSP(*NO) is specified on
the CRTDSPF command or CHGDSPF command). In this example, the mnemonic
has been set up to be the first character in each of the choices.
Using the MNUBARDSP Keyword on the Menu-Bar Record

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A HELP ALTHELP CFð3(ð3)
A MNUBARSW(CA1ð) MNUCNL(CA12 12)
A CFð4(ð4) CFð6(ð6)
A R MENUBAR MNUBAR
A ð1 MNUBARDSP
A HLPRCD(FILEHLP HLPLIB/HLPFILE)
A HLPRCD(EDITHLP HLPLIB/HLPFILE)
A HLPRCD(VIEWHLP HLPLIB/HLPFILE)
A HLPRCD(OPTHLP HLPLIB/HLPFILE)
A HLPRCD(HELPHLP HLPLIB/HLPFILE)
A MNUFLD 2Y ðB 1 2
A '>File ')
A &EDITTXT)
A '>View ')
A '>Options ' &RTNFLD)
A '>Help ')
A MNUBARSEP((\COLOR WHT) +
A (\CHAR '-'))
A EDITTXT 2ðA P
A RTNFLD 2Y ðH
A R PULLEDIT
A PULLDOWN
A HLPRCD(UNDOHLP HLPLIB/HLPFILE)
A HLPRCD(MARKHLP HLPLIB/HLPFILE)
A HLPRCD(COPYHLP HLPLIB/HLPFILE)
A CHCACCEL(1 'F4')
A CHCACCEL(2 'F6')
A MARKTXT 2ðA P

A CTLUNDO 1Y ðH
A CTLMARK 1Y ðH
A CTLCOPY 1Y ðH
A MSG 7A P
A LIB 1ðA P
A MSGF 1ðA P
A
A R PULLOPT
A PULLDOWN
:
:
:
:
A
A R APPSCR
Description
In the example using the MNUBARDSP keyword on the menu-bar record, the appli-
cation writes the MENUBAR record to display the menu bar. The application then
performs a write-read operation to the APPSCR record to display the application
display.
As in the previous example, F10 provides quick access to the menu bar (which is
always active). Pressing F10 moves the cursor to the first choice in the menu bar.
Pressing F10 again (or F12) moves the cursor back to where it was on the applica-
tion display.
On display stations in configuration F from Table 6-2 on page 6-3, pressing the
Tab key moves the cursor from choice to choice in the menu bar and from input
field to input field on the entire display. The cursor skips over any menu-bar choice
that is selected.
When the cursor is located within a menu bar on display stations in configurations
A, B, and C from Table 6-1 on page 6-2, and configurations D and E from
Table 6-2 on page 6-3, the cursor movement keys or the Tab key moves the
cursor from choice to choice within the menu bar.
If the user selects the Edit action, the system displays the pull-down menu record
(PULLEDIT). Because CHECK(ER) is not specified on field F1, the user enters a
value by typing the choice number and pressing the Enter key, or by pressing F4 or
F6. When a value is entered or an accelerator key is pressed, control is returned
to the application. Because the application was doing a write-read operation to the
APPSCR record, the APPSCR record is returned to the application. The applica-
tion must then read the MENUBAR record to determine the choice selected (2 is
returned in field MNUFLD). Because the input-field parameter was not specified on
the MNUBARDSP keyword, the application reads record PULLEDIT to receive the
pull-down menu input.

How the Displays Look
display looks like this:

Undo F4
Mark F6
Copy
RV2W855-1
On display stations in configuration C from Table 6-1 on page 6-2, the display
looks like this:

. .
: 1. Undo F4 :
: 2. Mark F6 :
: 3. Copy :
. . . . . . . . . . . . . .
RV2W067-0
display looks like this:

. .
: 1. Undo F4 :
: 2. Mark F6 :
: 3. Copy :
. . . . . . . . . . . . . .
RV2W068-1
On display stations in configuration F in Table 6-2 on page 6-3, the display looks
like this:

. .
: 1. Undo F4 :
: 2. Mark F6 :
: 3. Copy :
. . . . . . . . . . . . . .
RV3W075-0

Simple Hotspots
Controllers that support an enhanced interface for nonprogrammable work stations
provide simple hotspots. A hotspot is an area of a display that, when clicked on,
performs a function. You must have a display station with a mouse. Hotspots are
available on configurations A and B from Table 6-1 on page 6-2. On InfoWindow
II display stations, the hotspot must be selected with the left mouse button.
The following hotspots are provided by controllers that support an enhanced inter-
face for nonprogrammable work stations:
Command key emulation
Page Up and Page Down key emulation
Enter key emulation
The user can perform the Enter function on InfoWindow II display stations by
double-clicking the left mouse button.
Command Key Emulation

When the user clicks on a command key, the pointer device cursor must be
between the first and last characters (inclusive) of the command key. When the
user selects the command key, the keyboard locks and the command key is pro-
cessed. The function performed is defined by DDS. The system performs the
function as if the actual command key had been pressed. This includes setting
response indicators.
When the user clicks on a command key, the system scans the command key text
to the left until it finds one of the following:
An attribute
Two blanks
Two nulls
A blank and a null
Column one of the row
After finding the beginning of the command key text string, the system scans the
text to the right until it finds a match with one of the following:
Fx= x can be 1 to 9.
Fyx= y can be 0, 1, or 2. If y is 0, x can be 1 to 9. If y is 1, x can be 0 to 9.
If y is 2, x can be 0 to 4.
PFx= x can be 1 to 9.
PFyx= y can be 0, 1, or 2. If y is 0, x can be 1 to 9. If y is 1, x can be 0 to 9.
PFx x can be 1 to 9.
PFyx y can be 0, 1, or 2. If y is 0, x can be 1 to 9. If y is 1, x can be 0 to 9.
After the system finds a match, it performs the command key function.

Page Up and Page Down Key Emulation
The user can click on the plus (+) and minus (−) characters to page down (roll up)
and page up (roll down), respectively. When the user clicks on the + or − charac-
ters, the keyboard locks and a Roll Up AID key and Roll Down AID key is gener-
ated. The function performed is defined by DDS. The system performs the
function as if the actual key had been pressed.
One way to implement this function is to do the following:

1. Specify *MORE on the Subfile End (SFLEND) keyword.
This causes the display file to use the text defined on the CPX6AB2 and
CPX6AB1 messages. The default text for these messages is More ... and
Bottom, respectively.
2. Change the text for the CPX6AB2 message to More: +/-.
3. Change the text for the CPX6AB1 message to Bottom: -.
Programmable Mouse Buttons—Overview

The programmable mouse buttons function allows attention indicators (AIDs) to be
associated with various pointer device events. AID codes are normally associated
with various command keys on the keyboard. These keys are used to communi-
cate action requests from the user to the system or application. Some command
keys that generate AIDs are Enter, Help, Rollup, Rolldown, and the 24 command
attention or function keys. Single event AIDs and two event AIDs can be pro-
grammed. Up to 18 pairs of pointer device events and associated AIDs may be
defined. These events consist of 3 buttons with 3 events each (up, down, and
double click) in two keyboard states (shifted and unshifted).
A single event AID definition would also associate an AID code with a single pointer
device event whereas the two event AID definition would also associate an AID
with two consecutive pointer device events.
Use the programmable mouse button (MOUBTN) keyword to associate a command

key or Event-ID with one or two pointer device events. This keyword can be speci-
fied at the file or record level.
Notes:
1. This function is available only for displays attached to a controller that supports
an enhanced interface for nonprogrammable work stations.
2. The only pointer device supported is a mouse or a device that emulates a
mouse.
Pointer Device Events

With a three button mouse, there are 18 pointer device events possible: 3 buttons
with 3 events each (up, down, double click) in two keyboard states (shifted and
unshifted). The pointer device events are:
Left button pressed
Left button released
Left button double click
Right button pressed

Right button released
Right button double click
Middle button pressed
Middle button released
Middle button double click
Shifted left button pressed
Shifted left button released
Shifted left button double click
Shifted right button pressed
Shifted right button released
Shifted right button double click
Shifted middle button pressed
Shifted middle button released
Shifted middle button double click
Notes:
1. The Shift key or Shift Lock key must be held down for a shifted pointer device
event. Caps Lock state and Shift Lock state are not considered shifted.
Releasing the Shift key does not reset Caps Lock state or Shift Lock state if
used for a shifted pointer device event.
2. The nonprogrammable work station (NWS) has a setup option to switch the
functions of the left and right buttons within the NWS. The system has no
knowledge of this. This provides the concept of left- and right-handed mice.
For this document, all references to the mouse buttons assumes a right-handed
mouse where the left and right buttons follow the usual definitions for left and
right.
AID Codes to be Returned

The AID associated with a pointer device event may be any currently supported
AID or a host-defined AID value between X'70' and X'7F'. The following AIDs
are supported:
X'31' - X'3C' CA/CF01-CA/CF12 (Cmd 1 - 12)
X'70' - X'7F' E00-E15 (EVENTS)
X'B1' - X'BC' CA/CF13-CA/CF24 (Cmd 13 - 24)
X'BD' CLEAR (Clear)
X'F1' Enter or Record Advance
X'F3' HELP (Help - not in error state)
X'F4' ROLLDOWN (Page Down)
X'F5' ROLLUP (Page Up)
X'F6' PRINT (Print)
X'F8' HOME (Record Backspace)
Programmable Mouse Buttons—Benefits

Mouse buttons can be used for such things as reordering the layering of windows
and selecting objects. For example, an application programmer can program
middle button down as a single event AID to enable window reordering when mul-
tiple windows are on a display. When the user presses the middle button, the
cursor moves to the pointer device cursor location and the host-defined AID is
returned. The application uses the host-defined AID to recognize a reorder
request. If the row and column cursor address indicates that the pointer device
event occurred within an overlaid window, the windows can be reordered. If the

row and column cursor address indicates that the pointer device event did not
occur within an overlaid window, the application can ignore the AID or post a
message.
Note: If the EVENT IDs (E00-E15) are used, you may consider defining equivalent
functions to be performed using the keyboard. For example, you may allow
the user to position the text cursor and press a function key to perform a
function equivalent to pressing a mouse button. This would enable func-
tions on displays attached to controllers that do not support an enhanced
interface for nonprogrammable work stations and on nonprogrammable dis-
plays without pointer devices.
Programmable Mouse Buttons Operation

When a pointer device event is performed that has been programmed as a single
event and no other function has higher priority, the following occurs:
1. The keyboard is locked (as it is for function keys).
2. The cursor is moved to the pointer device cursor location.
3. The specified AID is returned to the host.
4. If the AID or moving the cursor normally results in validation of entry field data,
the data is validated.
5. If the specified AID normally returns inbound entry field data, inbound entry
field data is included. The format of the inbound data is like typical inbound
data.
6. Control is returned to the application.
There will be no way for the application to differentiate between the pointer
device event and the corresponding command key. However, the pointer
device event may be associated with an EVENT ID (E00-E15) that is not also
associated with any command key. This provides a way to detect a pointer
device event.
When a two event pointer device event is performed, the system looks for the
leading edge event. When the leading edge event is received, the following occurs:
Note: Inbound data is not returned until the trailing edge event occurs.
1. A programmable-two-event state is entered.
2. A marker box is drawn around the location of the pointer device cursor on non-
programmable work stations capable of displaying a marker box. The marker
box appears as 4 blue lines around the character.
3. The pointer device color is changed to white on nonprogrammable work
stations capable of displaying white.
4. The system looks for the trailing edge event.
Keystrokes and host data streams will cancel the programmable-two-event state.
Some pointer device events are ignored while waiting for the trailing edge event.
For more information, see “Programmable Mouse Buttons—NWS Considerations”
on page 6-72. When the trailing edge event is received, the following occurs:
1. The marker box is erased
2. The pointer device cursor color is changed to input inhibited
3. The keyboard is locked
4. The text cursor is moved to the location of the pointer device cursor
If the specified host-defined AID normally returns inbound entry field data,
inbound data is included. The ending row and column location is returned.

Note: The RTNCSRLOC keyword can also be used to retrieve the starting
location of the cursor. This may be different from the ending cursor
location when using a two event definition.
Using programmable mouse buttons can prohibit other pointer device functions on
the display. For example, the copy and paste function has a lower priority than the
programmable mouse buttons for the shifted left button press and release. For
more information on the priority of pointer device events, see “Programmable
Mouse Buttons—Event Processing Priority” on page 6-73.
Programmable Mouse Buttons—NWS Considerations

Many of the pointer device events result in either the text cursor being moved or an
AID being sent to the host. If the text cursor was in an entry field, entry field
requirements (for example, mandatory fill) are checked before the text cursor is
allowed to move or an AID is sent. This could result in an error code being posted
and the pointer device event would not be processed. For example, the 0014 error
code may be posted indicating that a mandatory fill field contains a null.
The NWS passes an event to the system any time a button is pressed or released.
It passes a double-click event to the system if a button is pressed, released, and
pressed again within a user-specified double click time. The system sees a button
pressed event, button released event, and a double click event, and eventually a
button released event.
A pointer device event will be ignored by the system if any of the following are true:
The keyboard is locked. An exception is single event programmable mouse
buttons which can be defined to be queued if the keyboard is locked.
The keyboard is in system request state or ss message state.
The keyboard is in operator error state. An exception is the left button down
and shifted left button down which can reset an operator error.
The display is in WP mode.
The system has any stored type ahead keystrokes.
The system does not have a pending read. An exception is single event pro-
grammable mouse buttons. When the keyboard is unlocked, the system
normally has a pending read. However, 3270DE sometimes unlocks the key-
board without a pending read. Processing a pointer device event could be con-
fusing in this case.
Programmable Mouse Buttons—Event Processing States

Pointer device event processing can be in various states. The following events,
when received in an unexpected state, cause the state of the pointer device event
processing to be reset:
Most mouse button events (except as noted)
Most keyboard events (not shift key make/break, for example)
All host display updates
The state is reset as follows:

If the scroll bar drag and drop state is active, the drag and drop state is reset
and the scroll bar is re-written to the original state.

If the copy and paste state is active, the copy and paste state is reset and the
ending point indication is removed from the display.
If the programmable mouse buttons two-event state is active, the state is reset
and no AID is posted. The follow events are ignored in the two-event state so
as not to reset the state when that would not be the desired effect:
– A mouse button release event associated with the leading edge event.
– A mouse button press event which must be generated to get to the trailing
edge event. The trailing edge must be the button release or double click
on the same button and shift state.
– A mouse button release event which must be generated to get to the
trailing edge event. The trailing edge must be the double click on the same
button and shift state.
Mouse button events which cause states to be reset are not processed any further.
Keyboard events and host screen updates are processed as usual after resetting
any mouse event processing state.
Programmable Mouse Buttons—Event Processing Priority

This section describes the event processing priorities for the following events:
Unshifted left button pressed
Unshifted left button released
Unshifted left button double clicked
Shifted left button pressed
Shifted left button released
Shifted right button pressed
All other events
Unshifted Left Button Pressed Event Processing

If the shift key is not down and the system receives a left button pressed event, the
system determines the position of the pointer device cursor and performs exactly
one of the following functions, checking in the order listed:
1. If an operator error is on the display, the pointer device cursor can be used to
reset the operator error. Depending on the position of the pointer device
cursor, one of the following functions is performed:
a. If the pointer device cursor is on the operator error line, then the same
function is performed as if the user pressed the Reset key. The reset func-
tion is also performed if the pointer device cursor is on the last line of the
display and the separately displayable operator error line line is being used
(line 25 or line 28).
b. Otherwise, the pointer device event is ignored and the following checks are
not done.
2. If the pointer device cursor is on a selection field choice:
a. If the choice is a cursorable choice, the cursor is moved to the location of
the pointer device cursor. A selection cursor is created. The function of a
Spacebar key is performed (this includes posting operator error 0084 if the
choice is unavailable). The cursor must be somewhere between the first
text attribute and the last text attribute in the choice. If selection indicators
are used, the cursor must be somewhere between the selection indicator
attribute and the last text attribute in the choice.

b. If on a noncursorable or null choice, the cursor is not moved and operator
error 0084 is posted.
3. If the pointer device cursor is on a scroll bar character (arrow character or shaft
character), a roll AID may be sent to the host. If a roll AID is sent to the host
the field MDT is set on. The text cursor may be moved to the position of the
pointer device cursor. This depends on one of the following:
The setting of the "move the cursor to the scroll bar on a pointer device
interaction" flag in the Define Scroll Bar command
The position of the cursor if this scroll bar is associated with a selection
field
The keyboard is locked (as if the user pressed a normal AID key).
a. If the pointer device cursor is in the shaft above the slider, a Roll Down AID
with a scroll increment of X'00000000' is sent to the host. Similarly, if the
pointer device cursor is in the shaft below the slider, a Roll Up AID is sent.
b. If the pointer device cursor is on the top arrow character and the slider is
not already at the top of the scroll bar, a Roll Down AID with a scroll incre-
ment of X'00000001' is sent to the host. Similarly, if the pointer device
cursor is on the bottom arrow character and the slider is not already at the
bottom of the scroll bar, a Roll Up AID with a scroll increment of
X'00000001' is sent to the host. If the pointer device cursor is on the top
arrow character and the slider is already at the top of the scroll bar, the left
button pressed is ignored. The bottom arrow character functions similarly.
c. If the pointer device cursor is on the slider, a drag and drop function should
be started (scroll bar slider drag and drop state). The NWS is told to pass
pointer device cursor movement to the system. In scroll bar drag and drop
state, for each movement event, the system calculates the row of the
pointer device cursor and compares this value with the last row which was
processed. If the row values are different, the scroll bar characters are
re-written. The slider is re-positioned within the shaft. If the pointer device
cursor moved up one row, the slider is moved up one row. If the pointer
device cursor is moved up more rows than exist in the shaft above the
slider, the slider is moved to the top of the scroll bar shaft. When the left
button is released, the drop function is performed; see Left Button
Released for a description of the roll AID request. If any pointer event
other than left button released occurs, or if any keyboard key is pressed, or
if any screen update is done by the host, the following occurs:
The scroll bar characters are re-written to their original state
The scroll bar slider drag and drop state is reset
No roll AID is sent
The MDT is not set
4. If the pointer device cursor is in a light pen field (first field position through the
last field position), the system treats the event as if a light pen tip switch were
activated at the position of the pointer device cursor.
5. If this mouse button event has been programmed with the Programmable
Mouse Buttons structured field, the event is handled as described above.
6. If the pointer device cursor is on a simple hot spot, a hot spot function is per-
formed. Hot spots enable a pointer device to partially drive older applications.
In order to be considered a hot spot, the pointer device cursor must not be in
an entry field. The hot spot functions for unshifted left button pressed events
are:

Command Key emulation. For more information, see “Command Key
Emulation” on page 6-68.
Page Up and Page Down Key Emulation. For more information, see “Page
Up and Page Down Key Emulation” on page 6-69.
Enter key emulation. For more information, see “Unshifted Left Button
Double Click Event Processing.”
7. If pull-down cancel mode is active, the cursor is moved to the position of the
pointer device cursor, the keyboard is locked (treated like a normal AID), and
the specified AID is returned to the host. Pull-down cancel mode is active if a
selection field was written to the display and a Pull-Down Cancel AID was
specified in the Define Selection Field major structure.
Note: Pull-down cancel mode is lower priority than hot spots because pull-
down menus could have command keys or More -/+ inside them.
8. Otherwise, the cursor is moved to the location of the pointer device cursor.
The cursor could be a text cursor or a selection cursor (for a highlighted entry
field). The system allows the text cursor to move to a noncursorable text
location even if cursor movement to input-capable positions only is set on.
Unshifted Left Button Released Event Processing

If the shift key is not down and the system receives a left button released event,
the system determines the position of the pointer device cursor and performs
exactly one of the following functions, checking in the order listed:
1. If scroll bar slider drag and drop state is active, the scroll bar characters may
be updated. For more information on scroll bars, see “Unshifted Left Button
Pressed Event Processing” on page 6-73. If the row position of the pointer
device cursor is different than the row position when the slider was last written,
the scroll bar characters should be written. If the final slider position is different
than the original slider position (when the drag and drop was started), the fol-
lowing occurs:
a. The MDT is set on
b. The text cursor may be moved to the scroll bar slider
c. A Roll AID is sent to the host with a scroll increment indicating the number
of rows or columns to be scrolled
d. The keyboard is locked (treated like a normal AID)
The specific AID depends on the direction the slider moved. If the slider did
not move, no AID is sent. In all cases, the scroll bar slider drag and drop state
is reset.
3. Otherwise, the pointer device event is ignored.
Unshifted Left Button Double Click Event Processing

If the shift key is not down and the system receives a left button double click event,
then the system determines the position of the pointer device cursor and performs

2. Otherwise, if the previous left button pressed event simply positioned the
cursor, the keyboard is locked and the Enter AID is sent to the host. This is a
hot spot function.
3. Otherwise, the unshifted left button double click event is ignored.
Note: The user must have done one of the following:
Selected a selection field choice
Operated against a scroll bar
Caused a pointer device selectable AID
Selected a hot spot (for example, a command key)
Caused some other left button pressed event function, other than
the default action of simply positioning the cursor.
Shifted Left Button Pressed Event Processing

If the shift key is down and the system receives a left button pressed event, the
system determines the position of the pointer device cursor and performs exactly
one of the following functions, checking in the order listed:
1. If an operator error is on the display, the pointer device cursor can be used to
reset the operator error. Depending on the position of the pointer device
cursor, one of the following functions is done:
a. If the pointer device cursor is on the operator error line, then the same
function is performed as if the user pressed the Reset key. The reset func-
tion is also performed if the pointer device cursor is on the last line of the
display and the separately displayable operator error line line is being used
(line 25 or line 28).
b. Otherwise, the pointer device event is ignored and the following checks are
not performed.
3. Otherwise, a copy and paste function (frequently called cut and paste) is
started. The copy and paste state is set. The location of the pointer device
cursor is marked to indicate an end point of the select. A line is drawn above
and below the character location of the pointer device cursor. If any other
pointer device event other than shifted left button released occurs, or the user
presses any key, or any data is received from the host, the copy and paste
state is reset and the two lines are removed. When the shifted left button is
released, copy and paste processing continues (see “Shifted Left Button
Released Event Processing”) for later use in a paste operation (see “Shifted
Right Button Pressed Event Processing” on page 6-78).
Shifted Left Button Released Event Processing

If the shift key is held down and the system receives a left button released event,
the system determines the position of the pointer device cursor and performs
1. If copy and paste state is active, the user has now marked the second end
point of the copy. The second end point is marked by drawing three lines
around the second end point and adding one line around the first end point.
This looks like square brackets enclosing the copy data. The user can mark
either the starting or ending point first. Then, the marked copy data is stored in
the display (for example, 348X NWS) for later use (see “Shifted Right Button

Pressed Event Processing” on page 6-78). For performance reasons, the copy
and paste data will be copied from the display to the system-managed buffer in
the display (without crossing the twinaxial cable). Some formatting may be
done by the system to the copy and paste data after the data has been copied
within display memory:
If the display is a SBCS display (not capable of DBCS) and the data was
copied from a non-display area, the system writes a non-display attribute
over the first position of the copy and paste data. A non-display area is an
area in which a non-display attribute was in effect for the copy and paste
data.
If the display is a DBCS display, but not capable of DBCS-pure fields, the
following formatting takes place:
Note: Support for DBCS-pure fields includes supports extended SO/SI
attributes which do not require a screen position.
– If the first byte of copy and paste data is DBCS data (preceded by a
SO character) and the starting point of the DBCS data is the second
byte of a DBCS character, the starting point of the copy is decreased
by one position (to include the entire character).
– If the last byte of copy and paste data is DBCS data and the ending
point of the DBCS data is the first byte of a DBCS character, the
ending point of the copy is increased by one position (to include the
entire character).
– If the first byte of copy and paste data is DBCS data (preceded by a
SO character), the system writes an SO ahead of the first byte of copy
and paste data.
– If the last byte of copy and paste data is DBCS data, the system writes
an SI after the last byte of copy and paste data.
– If the data was copied from a non-display area, the system writes a
non-display attribute over the first non-SO/SI character in the copy and
paste data. If the character in the copy and paste data is a DBCS
character, the system writes two non-display attributes over the first two
non-SO/SI characters.
The end point indications on the display should be reset when one of the fol-
lowing occurs:
Any key is pressed other than the four cursor movement keys. The system
allows the user to move the text cursor without resetting the end points.
Another pointer device event occurs.
The host updates the display.
The copy and paste data is lost only when the NWS powers down or the user
completes the copy portion of another copy and paste operation.

Shifted Right Button Pressed Event Processing
The system performs exactly one of the following functions, checking in the order
listed:
2. If the system receives a right button pressed event and the user has previously
selected data for a copy and paste operation, the system auto-keys the
selected data at the location of the text cursor. This is done independently of
the location of the pointer device cursor. The system performs the following
steps:
If the text cursor is not in an entry field, operator error X'0005' is posted.
The copy and paste data is read from the display into main storage. The
length of the data read is the smaller of the length of the copy and paste
data, and the length of data which will fit into the entry field.
Note: Continued fields are considered a single entry field.
Data following a non-display attribute is converted to blanks, until another
non-display attribute is found.
Attributes are converted to blanks.
GUI-like characters are converted to blanks.
Nulls are converted to blanks.
The system will perform all normal field checks (for example, digits only,
alphanumeric only, and so on). This could result in an operator error. If an
operator error is posted, no data following the point of the error is pasted.
If the field is a monocase field, the data is monocased.
If the display is a DBCS display and the field is a DBCS field, the following
processing takes place:
– If the field is a DBCS-only field, the copy and paste data must begin
with an SO (otherwise, operator error "0092" is posted). The DBCS
characters are placed into the field until the field ending SI is found, or
an SI is found in the copy and paste data. The SO and SI characters
are not pasted.
– If the field is a DBCS-either field, the copy and paste data must be the
proper format or operator error 0092 is posted. Operator error 0092
indicates that either no SO character is allowed (if the field is SBCS), or
that the data must start with an SO character (if the field is DBCS).
DBCS paste is just like describe above for a DBCS-only field.
– If the field is a DBCS-pure field, the copy and paste data must begin
with an SO (otherwise, operator error "0092" is posted). The DBCS
characters are placed into the field until the end of the field is found, or
an SI is found in the copy and paste data. The SO and SI characters
are not pasted.
– If the field is a DBCS-open field, the copy and paste data is auto-keyed
into the field. If the copy and paste data starts with an SO character,
the SO is pasted if the cursor is under a DBCS character. If the cursor
is under an SBCS character, the SO is not pasted. If the copy and
paste data does not start with an SO character, an SI will be pasted if

the cursor is under a DBCS character. If the last character in the field
is a DBCS character, the system will reserve room for an SI after the
last DBCS character.
If the user is in replace mode and the paste data is too long to fit in the
entry field, as much data is placed in the field as possible, the cursor is
placed in the last position of the entry field, and operator error 0012 is
posted.
If the user is in insert mode and the paste data requires more positions
than the number of nulls at the end of the entry field, as much data is
placed in the field as possible, the cursor is placed on the last export char-
acter, and operator error 0012 is posted.
Note: The copy and paste data is never reset. The user is allowed to paste
the most recent copy and paste data multiple times.
3. If the user has not previously selected data for a copy and paste operation, the
system will ignore the event.
Any Other Pointer Device Event Processing

1. If the mouse button event has been programmed using the Programmable
2. Otherwise, the event is ignored.
Grid Line Structures—Overview

Grid line structures include horizontal lines, vertical lines, and boxes. They can
only be displayed on DBCS display stations. For details on the required hardware,
see “Hardware Requirements for Grid Line Structures” on page 6-82. An example
of grid line structures appears in Figure 6-60 on page 6-80.
The grid line keywords also allow you to do the following:

Clear grid lines within a specified rectangle
Erase a specified grid line structure
Control the attributes of grid line structures such as color and line type

____________________________________________________________________
| |
| ____________________ |
| │ │ |
| │ │ |
| │ │ |
| │____________________│ |
| |
| |
| |
| ______________________________________________________________ |
| │ │ │ │ │ |
| │______________│_______________│________________│______________│ |
| │ FIELD 1 │ │ │ │ |
| │_____________ │_______________│________________│______________│ |
| │ │ │ │ │ |
| │______________│_______________│________________│______________│ |
| │ │ │ FIELD 2 │ │ |
| │______________│_______________│________________│______________│ |
| │ │ │ │ │ |
| │______________│_______________│________________│______________│ |
| |
|__________________________________________________________________|
Figure 6-60. Grid Line Structures
DDS for Grid Line Structures—Example

The DDS in Figure 6-61 creates the grid line structure in Figure 6-60.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A GRDATR((\COLOR BLU) (\LINTYP SLD))
A
A R GRDREC GRDRCD
A 96 GRDCLR
A GRDBOX((\POS (3 1ð 4 2ð)) +
A (\TYPE PLAIN) +
A (\COLOR RED) (\LINTYP THK) +
A (\CONTROL &CNTL1))
A
A GRDBOX((\POS (1ð 2 1ð 6ð)) +
A (\TYPE HRZVRT 2 15) +
A (\CONTROL &CNTL2))
A CNTL1 1S ðP
A CNTL2 1S ðP
A
A R REC1
A
A FIELD1 7A B 15 5CHGINPDFT
A
A FIELD2 7A B 18 35CHGINPDFT
Figure 6-61. DDS for Grid Line Structures—Example

Notes:
1. It is recommended to add a CHGINPDFT keyword to an input/output field when
a grid line structure is defined directly under the field.
2. In general, grid line structures are written in the order that they are coded in the
display file.
3. If a display file is created or changed to nonenhanced display (ENHDSP *NO),
no grid line records are written to the display.
When record GRDREC is written with option indicator 96 on, the GRDCLR keyword
causes all grid line structures on the screen to be cleared. The remainder of the
keywords are then processed in the order that they are coded. If the program-to-
system field CNTL1 contains a 1, the first GRDBOX keyword is ignored. If CNTL1
contains 0, a PLAIN box grid is displayed. This box begins at row 3, column 10. It
has a depth of 4 rows and a width of 20 columns. The box has a thick line type
and is red. If CNTL1 contains -1, the grid line structure at the defined position is
erased and all other grid line structures on the display are left intact.
If the program-to-system field CNTL2 contains 1, the second GRDBOX keyword is

ignored. If CNTL2 contains 0, a horizontally and vertically ruled box is displayed.
This box begins at row 10, column 2. It has a depth of 10 rows and a width of 60
columns. The box has a horizontal rule every 2 rows and a vertical rule every 15
columns. Because there are no attributes defined on the GRDBOX keyword, the
attributes default to those defined on the GRDATR keyword at the file level. These
attributes are a solid line type and color blue. If CNTL1 contains -1, the grid line
structure at the defined position is erased and all other grid line structures on the
display are left intact.
Grid line structures are defined in records separate from other data fields. Grid line
records are displayed independent of all other data records. Grid line records are
also cleared independent of other data records. If the device file has
DFRWRT(*YES), all records written are buffered until a GET operation is done.
This includes all grid line records. A READ or PUTGET operation cannot be done
to a grid line record because there is no possible input for the grid line record. The
FRCDTA keyword is allowed on grid line records. In this case, the grid line record
written is immediately displayed regardless of the DFRWRT keyword.
Grid Line Structures and Windows

If a grid line structure is on the display when a GUI window is displayed, the con-
troller removes all grid lines under the window prior to displaying the window. If
grid lines are on the display when a non-GUI window (for example, a UIM help
window) is displayed, all grid lines are removed from the display. When the
window is removed from the display, the display is restored including all grid line
structures.
A grid line record can define a window or specify a window reference record.
When a grid line structure is defined with a window, all start- row and start-column
parameters are relative to the start of the window. This includes both the start-row
and start-column parameters defined with DDS and the start-row and start-column
values set at run time with program-to-system fields. A grid line structure can be
displayed outside of the window. The depth, width, and length parameters will trun-
cate to the end of the display if they are too large for the display size.

If a window is displayed, writing a grid line record to the base display causes the
window to be removed unless the USRRSTDSP keyword is defined on the window
record. The base screen is restored prior to displaying the grid line structures.
Hardware Requirements for Grid Line Structures

Grid line support requires DBCS hardware. This hardware should have the capa-
bility of running Japanese DOS. Japanese DOS is supported by the following
PS/55 systems:
5523-S, 5523-V, 8551-S
5535-S (laptop)
5530-T/V/W, 5541-T, 5551-S/TV/W, 5561-W (desktop)
5571-T/V, 5580-W/Y (floorstanding model)
Note: PS/1* and PS/2* systems do not support Japanese DOS.
For the desktop and floorstanding PS/55 systems, the Japanese keyboard
(5576-001/002/003/A01) and DBCS-capable display (5574) are required. The 5530
system has an integrated display. As a twinaxial communication adapter, 5250
adapter/A (ID#65X1092) is required.
The AS/400 system can sense if the attached display is capable of displaying grid
line structures. If a grid line record is written to a display that does not support grid
line structures, the record is ignored. However, window keywords on the grid line
record are processed.
Grid line structures (nonfield level file) can be printed using the Print Screen key if
the printer supports DBCS.
Inserting HTML Tags

The World Wide Web (or Web for short) is a graphical interface that provides
access to an enormous amount of information available on the Internet. The Web
allows Internet users to access documents that contain text and non-text objects
(such as video, sound, graphics, and so on). The documents can contain “links”
(hyperlinks) to other documents that may also contain links to other documents.
The text within a Web document that contains hyperlinks is called hypertext. The
chain of reference from document to document is virtually endless since all docu-
ments can link to other documents.
You can tailor documents on the Web to present multimedia information from a
variety of sources allowing end users to optionally access the information identified
by the links.
DDS support of the AS/400 5250 Workstation Gateway allows you to change
existing applications to enable them for the Internet through the World Wide Web.
The AS/400 5250 Workstation Gateway translates all 5250 data streams to an
HTML (Hypertext Markup Language) document and exports the document from
AS/400. You can insert HTML tags into a display file that allow graphic capabilities
of the client web browser to be utilized with only minor changes to the display file
source.
The HTML keyword is given a row/col position in the DDS file. However, row and
column positioning has no meaning in an HTML document. The row and column in

the display file determines the order of HTML tags in the HTML document that is
created. For example, an HTML keyword at row 2/column 4 appears before an
HTML keyword with a row 2/column 6 position. HTML keywords with the exact
same row and column position will be placed into the HTML document in the same
order in which they are defined in the DDS file.
Resolving HTML Field Overlap

The following examples show where the HTML will appear when you use the fol-
lowing coding:
Example 1
The HTML field has a starting column 2 before an output field. The HTML will
appear before the field.
A ð1 FLD1A 2ð O 15 7DFTVAL('Output Field')
A ð1 15 5HTML('<p>HTML code')
will result in:

HTML code
Output Field
Example 2
The HTML field has a starting column 1 before an output field, meaning that the
HTML starts at the attribute byte of the output field. The HTML will appear before
the field.
will result in:

HTML code
Output Field
Example 3
The HTML field has a starting column equal to an output field. The HTML will
appear before the first character of the field.
will result in:

HTML code Output Field
Example 4
The HTML field has a starting column 1 past the starting column of an output field.
The HTML will appear after the 1st character of the output field.
will result in:

OHTML codeutput Field
Example 5

The HTML field has a starting column 1 past the ending column of an output field,
meaning that it overlaps the ending attribute. The HTML will appear after the last
character of the output field.
will result in:

Output FieldHTML code
Example 6
The HTML field has a starting column 2 past the ending column of an output field.
The HTML will appear after the output field.
will result in:

Output Field
HTML code
Notes:
1. Merging of HTML and DDS fields does not occur for input fields. Merging
occurs only for output fields.
2. HTML tags are inserted into the data stream if the device query indicates that
the device is an AS/400 5250 Workstation Gateway virtual terminal. Otherwise
for normal displays, the HTML tags are ignored.

You can add the IMG HTML keyword to an existing display file and show a graphic
image along with the display as the following examples show.
Figure 6-62 shows an example of the DDS before adding HTML keyword
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A
A FILE LEVEL KEYWORDS
A
A CAð3(ð3)
A
A
A R REC1
A CAð1(ð1)
A CAð2(ð2)
A 5 3ð'Description'
A DSPATR(HI)
A DSPATR(UL)
A 5 13'Item'
A DSPATR(HI)
A DSPATR(UL)
A 5 65'Price'
A DSPATR(HI)
A DSPATR(UL)
A FLDðð1 1ðA O 6 13
A FLDðð2 25A O 6 3ð
A FLDðð3 6A O 6 65
A 1 36'Catalog'
Figure 6-62. DDS Coding Before Adding HTML Keyword

Figure 6-63 shows an example of the DDS after adding HTML Keyword
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A
A FILE LEVEL KEYWORDS
A
A CAð3(ð3)
A
A
A R REC1
A CAð1(ð1)
A CAð2(ð2)
A 5 3ð'Description'
A DSPATR(HI)
A DSPATR(UL)
A 5 13'Item'
A DSPATR(HI)
A DSPATR(UL)
A 5 65'Price'
A DSPATR(HI)
A DSPATR(UL)
A FLDðð1 1ðA O 6 13
A FLDðð2 25A O 6 3ð
A FLDðð3 6A O 6 65
A 7 2HTML('<img src="http://www.ice.com +
A /bin/sundae.gif')
A 1 36'Catalog'
Figure 6-63. DDS Coding After Adding HTML Keyword
On AS/400 5250 Gateway display stations, you would see the following graphic
image if you used the DDS source in Figure 6-63:
Figure 6-64. Graphic Image on an AS/400 5250 Gateway Display

Restrictions
The 5250 Gateway reserves the F1 function key as General Help. F1 cannot
be redefined for other uses.
Due to limitations of the web browser, the 5250 Gateway does not support
many of the graphic structures that DDS allows.
The following keywords are allowed, but are not supported. Attempting to
display them will have unpredictable results.
Windows (WINDOW keyword)
Menubars (MNUBAR keyword)
Pulldown (PULLDN Keyword)
Selection Lists (SFLMLTCHC/SFLSNGCHC keywords)
Selection Fields (SNGCHCFLD/MLTCHCFLD keywords)
PushButtons (PSHBUTTON keyword)
Scrollbars (SCRBAR keyword)
Continued Entry Fields (CNTENTFLD keyword)

Chapter 7. Overriding Display Files and Display File
Attributes
You can use overrides to temporarily change a file name, a device name associ-
ated with the file, or some of the other attributes of a file. Overrides allow you to
make minor changes to the way a program functions or to select the data on which
it operates without having to recompile the program.
Determining Whether or Not to Use Overrides

The following properties of overrides will help you decide if overrides are appro-
priate for the task you want to perform:
Overrides remain in effect only for the job, program, or display station session
in which they are issued. They do not permanently change the attributes of a
file.
Overrides have no effect on other jobs that may be running at the same time.
Overrides that are to be applied must be specified either before the file is
opened by a program or before a program that opens the file is compiled.
Override commands may be entered interactively from a display station or as
part of a batch job.
Override commands may be included in a control language (CL) program, or
they may be issued from other programs via a call to the program QCMDEXC.
Overrides allow you to make minor changes to the way a program functions or
for selecting the data on which it operates, without having to recompile the
program.
Overriding File Attributes in HLL Programs

File attributes are built as a result of the following:
Create file commands These commands build file attributes when the file is
first created.
Program using the files At compile time, the user program can specify some of
the file attributes. (The attributes that can be specified
depend on the high-level language in which the
program is written.)
Override commands At program run time, these commands can override the
file attributes previously built by the merging of the file
description and the file parameters specified in the user
program.
The simplest form of overriding a file in a high-level language (HLL) program is to

override some attributes of the file using the Override with Display File (OVRDSPF)
command.
Example: You create a display file named DISPLAY33 using the Create Display
File command:

CRTDSPF FILE(QGPL/DISPLAY33) SRCFILE(DDSFILE1) +
DEV(STATION1) IGCDTA(\YES) WAITFILE(3ð) LVLCHK(\NO)
Your application program specifies display file DISPLAY33 with STATION50 for the
display station and *NO for the IGCDTA parameter, which determines double-byte
character processing.
Before you run the application program, you want to change the display station to
STATION23 and wait file time to 45 seconds. The override command looks like
this:
OVRDSPF FILE(DISPLAY33) DEV(STATION23) WAITFILE(45)
When the application program opens the file, the file overrides, program-specified
attributes, and file attributes are merged to form the open data path (ODP), which is
used during the running of the program to manage access to the file and to
manage its attributes. File overrides have precedence over program-specified attri-
butes. Program-specified attributes have precedence over file-specified attributes.
In this example, when the file is opened, the following is used:
Display station STATION23
A double-byte character processing value of *NO
A wait file time of 45 seconds
The level identifiers of the records formats are not checked when the file is
opened.
The following illustration explains the previous example:
Display
Program A File DISPLAY33
.
SRCFILE(DDSFILE1)
.
DEV(STATION1)
.
IGCDTA(*YES)
Open
WAITFILE(30)
DISPLAY33
LVLCHK(*NO)
.
.
.
Program-Specified
Attributes Open Data Path
DEV(STATION50) SRCFILE(DDSFILE1)
IGCDTA(*NO) DEV(STATION23)
IGCDTA(*NO)
WAITFILE(45)
LVLCHK(*NO)
Override Command
DEV(STATION23)
WAITFILE(45)
RV2W016-3

Overriding File Names in HLL Programs
Another simple form of overriding a file in a high-level language program is to
change the file that is used by the program. This may be useful for files that have
been moved or renamed after the program has been compiled. Use the OVRDSPF
command for file name overrides also.
Example: You want the output from your application program to be displayed
using the display file DISPLAY12 instead of the display file DISPLAY33
(DISPLAY33 is specified in the application program). Before you run the program,
enter the following:
OVRDSPF FILE(DISPLAY33) TOFILE(DISPLAY12)
The file DISPLAY12 must have been created by a CRTDSPF command before it
can be used.
The following illustration explains the previous example:
Display
file
DISPLAY33 DISPLAY33 output
Program
.
Before .
Override: Use display file DISPLAY33
.
.
Record
format RV2W006-2
Display DISPLAY33 output

Program file
. DISPLAY33
After .
Override: Use display file DISPLAY33
.
.
Display
file
DISPLAY12 DISPLAY12 output
Record
format
RV2W007-2
You may want to override a file with a file that has a different file type; for example,
you may want to override a display file with a diskette file using the Override
Diskette File (OVRDKTF) command. To determine if your file can be overridden
with a file that has a different file type, see the information under “Using File Redi-
rection to Override File Names and Libraries or File Types” on page 7-6. More
information about overriding with different file types is available in the Data Man-
agement book.
Overriding Both File Names and Attributes in HLL Programs

This form of overriding a file in a high-level language program is simply a combina-
tion of overriding file attributes and overriding file names or types. With this form of
override, you can override the file that is to be used in a program and you can also
override the attributes of the overriding file. Use the OVRDSPF command to over-
ride both the display file name and attributes.
Chapter 7. Overriding Display Files and Display File Attributes 7-3

Example: You want the output from your application program to be displayed
using the display file REPORTS instead of the display file OUTPUT. (OUTPUT is
specified in the application program.) In addition to having the application program
use the display file REPORTS, you wish to override the wait file time to 50
seconds.
Assume the file REPORTS was created with the following command:
CRTDSPF FILE(REPORTS) SRCFILE(DDSFILE1) SRCMBR(MEMBER1) WAITFILE(25)
Before you run the program, type the following command:

OVRDSPF FILE(OUTPUT) TOFILE(REPORTS) WAITFILE(5ð)
Then call the application program. The display file REPORTS is used with a wait
file time of 50 seconds.
Note that the single override command used in the previous example is not equal
to the following two override commands:
Override 1 OVRDSPF FILE(OUTPUT) TOFILE(REPORTS)
Override 2 OVRDSPF FILE(REPORTS) WAITFILE(5ð)
Only one override is applied for each call level for an open operation of a particular
file. If you want to override the file that is used by the program and also override
the attributes of the overriding file from one call level, you must use a single
command. If two overrides are used, override 1 causes the output to be displayed
using the display file REPORTS, but override 2 is ignored.
Applying Overrides When Compiling a Program

Overrides may be applied at the time a program is being compiled for either of two
purposes:
To select the display file
To provide external data definitions for the compiler to use in defining the
record formats to be used on I/O operations
Overrides to the source file are handled just like any other override. They may
select another file, another member of a database file, or change other file attri-
butes.
Overrides may also be applied to files that are used within the program being com-
piled, if they are being used as externally described files in the program. These
files are not opened at compile time, and thus the overrides are not applied in the
normal manner. These overrides are used at compile time only to determine the
file name and library that will be used to define the record formats and fields for the
program to use I/O operations. Any other file attributes specified on the override
are ignored at compile time. It is necessary that these file overrides be active at
compile time only if the file name specified in the source for the program is not the
file name that contains the record formats that the application needs.
The file name that is opened when the compiled program is run is determined by
the file name that the program source refers to, changed by whatever overrides are
in effect at the time the program runs. The file name used at compile time is not
kept. The record formats in the file that is actually opened must be compatible with

those used when the program was compiled. Obviously, the easiest way to assure
record compatibility is to have the same overrides active at run time that were
active at compile time. If your program uses externally described data and a dif-
ferent field level file is used at run time, it is usually necessary to specify
LVLCHK(*NO) on the override. See “Using File Redirection to Override File Names
and Libraries or File Types” on page 7-6 for details.
Example: Assume that the source for the program INVENTORY, which has a wait
file time of 15 seconds, contains an open to the display file LISTOUT:
Override 1 OVRDBF FILE(RPGSRC) TOFILE(SRCPGMS) MAXRCDLEN(77)
Override 2 OVRDSPF FILE(OUTPUT) TOFILE(REPORTS)
CALL PGM(A)
Program A
Override 3 OVRDSPF FILE(LISTOUT) TOFILE(OUTPUT)
Override 4 OVRDBF FILE(RPGSRC) WAITFILE(3ð)
CRTRPGPGM PGM(INVENTORY) SRCFILE(RPGSRC)
RETURN
Override 5 OVRDSPF FILE(LISTOUT) TOFILE(REPORTS) IGCDTA(\YES)

CALL PGM(INVENTORY)
The program INVENTORY opens the display file REPORTS in place of display file
LISTOUT and allows DBCS data.
The program INVENTORY is created (compiled) from database file SRCPGMS and
allows a maximum record length of 77 characters. Override 4 (applied first) over-
rides an optional file attribute. Override 1 (applied last) causes the file RPGSRC to
be overridden with the database file SRCPGMS and a maximum record length of
77 characters.
The program INVENTORY is created with the display formats from the file
REPORTS. Override 3 (applied first) causes the file LISTOUT to be overridden
with OUTPUT. Override 2 (applied last) overrides OUTPUT with REPORTS. Other
attributes may be specified here, but it is not necessary because only the record
formats are used at compile time.
At run time, override 3 is no longer active, because program A has ended. There-
fore override 2 has no effect on LISTOUT. However, override 5, which is active at
run time, replaces LISTOUT with REPORTS and allows DBCS data. Because the
same file is used for both compilation and run-time, level checking may be left on.
Deleting Overrides
If you want to delete an override, you can use the Delete Override (DLTOVR)
command.
If you use the DLTOVR command in an application that either calls or transfers
control to other programs, the override may or may not be deleted. More informa-
tion about deleting overrides in application programs is available in the Data Man-
agement book.

Displaying Overrides
You can display all file overrides or file overrides for a specific file using the Display
Override (DSPOVR) command.
If you use the DSPOVR command to display the overrides used by an application
that either calls or transfers control to other programs, you can control which over-
rides are displayed. More information about displaying overrides used in applica-
tion programs is available in the Data Management book.
Using File Redirection to Override File Names and Libraries or File

Types
File redirection refers to using overrides to change the file name and library or the
type of the file to be processed. For example, you can substitute one display file
for another or change from using an ICF file to using a display file. The system
may or may not support file redirection. Refer to “Recognizing Commands That
Ignore or Restrict Overrides” on page 7-9 for rules on how the system processes
overrides.
Overriding Files with the Same File Types

When you replace the file that is used in a program with another file of the same
type, the new file is processed in the same manner as the original file. If a field
level file, or any other file containing externally described data is redirected, it
usually is necessary to either specify LVLCHK(*NO) or recompile the program.
With level checking turned off, it is still necessary that the record formats in the file
be compatible with the records in the program. If the formats are not compatible,
the results cannot be predicted.
Overriding Files with Different File Types

If you change to a different type of file, the device-dependent characteristics are
ignored and records are read or written sequentially. Some device parameters
must be specified in the new device file or the override. Defaults are taken for
others. The effect of specific redirection combinations is described later in this
section.
Any attributes specified on overrides of a different file type than the final file type
are ignored. The parameters SPOOL, SHARE, and SECURE are exceptions to
this rule. They will be accepted from any override applied to the file, regardless of
device type.
Some redirection combinations present special problems due to the specific charac-
teristics of the device. In particular:
File redirection is not recommended for save files.
Display files and ICF files that use multiple devices (MAXDEV or
MAXPGMDEV > 1) can be redirected only to a display file or ICF file.
Redirecting a display file to any other file type, or another file type to a display
file, requires that the program be recompiled with the override active if there are
any input-only or output-only fields. This is necessary because the display file
omits these fields from the record buffer in which they are not used, but other
file types do not.

Table 7-1 on page 7-7 summarizes valid file redirections:
Table 7-1. File Redirections

From-File
To-File Printer ICF Diskette Display Database Tape
Printer O* O O O O O
ICF I/O I/O
O O O O O O
I I I I I
Diskette O O O O O O
I I I I I
Display I/O I/O
O O O O O O
I I I I I
Database O O O O O O
I I I I I
Tape O O O O O O
I I I I I
Legend:
I=input file
O=output file
I/O=input/output file
*=redirection to a different type of printer
To use this chart, identify the file type to be overridden in the FROM-FILE columns
and the file type overriding in the TO-FILE column. The intersection specifies an I
or O or both, meaning that the substitution is valid for these two file types when
used as input files or as output files.
For instance, you can override a diskette output file with a tape output file, and a
diskette input file with a tape input file. The chart refers to file type substitutions
only. That is, you cannot change the program function by overriding an input file
with an output file.
The following chart describes the specific defaults taken and what is ignored for
each redirection combination involving display files:
Table 7-2 (Page 1 of 2). File Redirection Combinations

From To Specific Defaults Taken and What Is Ignored
Records are written to the display with each record
overlaying the previous record. For program-described
files, you can request each record using the Enter key.
Printer Display Printer control information is ignored.
Records are retrieved from the display one at a time.
Type in the data for each record and press the Enter
ICF input Display key when the record is complete.
ICF output Display overlaying the previous record.
Input records are retrieved from the display one at a
time. Type in the data for each record and press the
Enter key when the record is complete. Output records
are written to the display with each record overlaying
the previous input or output record. Input and output
records are essentially independent of each other and
ICF input/output Display may be combined in any manner.

Table 7-2 (Page 2 of 2). File Redirection Combinations
From To Specific Defaults Taken and What Is Ignored
key when the record is complete. A non-field-level
display file must be specified. Diskette label informa-
Diskette input Display tion is ignored.
overlaying the previous record. You can request each
Diskette output Display output record using the Enter key.
Display input ICF Records are retrieved from the ICF file one at a time.
Records are retrieved in sequential order. Diskette
label information must be provided in the diskette file or
Diskette on an override command.
Database Input records are retrieved.
Records are retrieved in sequential order. Tape label
information must be specified in the tape file or on an
Tape override command.
Display output ICF Records are written to the ICF file one at a time.
Database Records are written to the database in sequential order.
The amount of data written on diskette is dependent on
the exchange type of the diskette. Diskette label infor-
mation must be provided in the diskette file or on an
Diskette override command.
Records are written on tape in sequential order. Tape
label information must be specified in the tape file or on
Tape an override command.
Records are printed and folding or truncating is per-
Printer formed as specified in the printer file.
Display
input/output ICF Input records are retrieved from the
Database input Type in the data for each record and press the Enter
(sequentially pro- key when the record is complete. A non-field-level
cessed) Display display file must be specified.
Database output Records are written to the display with each record
(sequentially pro- overlaying the previous record. You can request each
cessed) Display output record using the Enter key.
key when the record is complete. A non-field-level
display file must be specified. Tape label information is
Tape input Display ignored.
overlaying the previous record. You can request each
Tape output Display output record using the Enter key.

Recognizing Commands That Ignore or Restrict Overrides
The following commonly used commands ignore overrides entirely:
ADDLFM DSPJRN
ADDPFM EDTOBJAUT
ALCOBJ EDTDLOAUT
APYJRNCHG ENDJRNPF
CHGOBJOWN GRTOBJAUT
CHGPTR INZPFM
CHGSBSD MOVOBJ
CHGXXXF (all change file commands) RGZPFM
CLRPFM RMVJRNCHG
CLRSAVF RMVM
CPYIGCTBL RNMOBJ
CRTDKTF RSTUSRPRF
CRTDUPOBJ RVKOBJAUT
CRTAUTHLR SAVCHGOBJ
CRTSBSD SAVLIB
CRTTAPF SAVOBJ
DLCOBJ SAVPGMPRD
DLTF SAVSAVFDTA
DLTAUTHLR SAVSYS
DSPDBR SBMDBJOB
DSPFD SIGNOFF
DSPFFD STRDBRDR
STRJRNPF
Overrides are not applied to any system files that are opened as part of an end-of-
routing step or end-of-job processing. For example, overrides cannot be specified
for the job log file. In some cases, when you need to override something in a
system file, you may be able to change it through a command other than an over-
ride command. For example, to change the output queue for a job log, the output
queue could be changed before sign-off using the OUTQ parameter on the Change
Job (CHGJOB) command to specify the name of the output queue for the job. If
the printer file for the job log contains the value *JOB for the output queue, the
output queue is the one specified for the job.
The SRCFILE and SRCMBR parameters on the following commands are affected
by overrides: overrides for the SRCFILE
CRTCMD CRTPF
CRTICFF CRTPRTF
CRTDSPF CRTSRCPF
CRTLF CRTTBL
CRTXXXPGM
(All create program commands. These commands also use over-
rides to determine which file will be opened by a compiled program.
See “Applying Overrides When Compiling a Program” on page 7-4
for more information.)
The OPNQRYF command is affected by the following override parameters:

TOFILE, MBR, SEQONLY, LVLCHK, and INHWRT.
The following commands allow overrides, but do not allow changing the MBR to
*ALL:
CPYFRMPCD CPYTOPCD

The following commands do not allow overrides to be applied to the display files
they use. Overrides to the printer files they use should not change the file type or
the file name. Various restrictions are placed on changes that may be made to
printer files used by these commands, but the system cannot guarantee that all
combinations of possible specifications will produce an acceptable report.
DMPOBJ and (In addition to the preceding limitations, these commands
DMPSYSOBJ do not allow overrides to the file they dump.)
DSPXXXXXX (All display commands. The display commands

that display information about a file do not
allow overrides to that file.)
DSPIGCDCT
EDTIGCDCT
GO (Message file can be overridden.)
PRTXXXXXX (All print commands.)
QRYDTA
TRCXXX (All trace commands.)
WRKXXXXXX (All work-with commands.)

Chapter 8. Handling Messages and Errors for Display Files
This chapter covers the following:
Creating and displaying your own messages
Analyzing error messages sent from the system
Creating and Displaying Your Own Messages

You can create and display your own messages on the AS/400. These messages
may indicate that a processing error has occurred, that incorrect input has been
entered, or simply that the keyboard is temporarily locked while the system pro-
cesses a lengthy request.
You can specify the following message handling functions for display files:
Display a message on the message line
Display a message on the message line when a subfile control record is written
Define a message line
Display messages in a field on the display
Display messages in a program message queue
Message line
My menu
ERRMSG and ERRMSGID keywords
F3=Exit
Order not found
Output field
My menu
Ways to show
messages on
the display Order not found MSGID keyword
F3=Exit
Subfile
Message 1
Message 2
Message 3 System message support
RV2W005-2
You can also do the following:

Display error messages on the message line using a system-supplied error
subfile
Have the system automatically handle jobs that are about to receive a perma-
nent I/O error

This section uses DDS keywords to define and display messages. For more
information about specific DDS keywords, see the DDS Reference.
Displaying a Message on the Message Line

You can specify that a message is to be displayed on the message line with the
ERRMSG or ERRMSGID keyword. For a message defined as a constant, use the
ERRMSG keyword; message help is not supported for these kinds of messages.
For a message defined in a message file, use the ERRMSGID keyword. When you
use these keywords, the keyboard locks and the user must press the Reset key to
clear the message from the display and continue.
When you use ERRMSG, the record that you want to present the message for
must already be on the display. If it is not, the ERRMSG function is not performed.
When you use the ERRMSG keyword to present a message, that message is
written to the message line of the display, which is usually the line at the bottom of
the screen. The user would then press the Reset key to clear the message from
the display and unlock the keyboard to continue typing. You provide the text of the
message right on the ERRMSG keyword. When you write a record that has the
ERRMSG keyword in effect, it causes that message to appear. Typically, you
would use an option indicator to cause the ERRMSG keyword to take effect. When
the application program turns on an option indicator, the keywords that have that
option indicator specified in the DDS then take effect. In this case, an application
program would leave an indicator that optioned an ERRMSG keyword off until the
message needed to be displayed.
The ERRMSGID and SFLMSGID keywords have an optional parameter for

message data (msg-data). This allows you to define a program-to-system field that
contains the message data (substitution text). For more information on how the
message data parameter works, refer to the Send Program Message CL command
in the CL Reference.
Note: When you use the ERRMSG or ERRMSGID keyword, you should specify
RSTDSP(*YES) on the CRTDSPF or CHGDSPF command; otherwise, data
may be lost if the display file is suspended.
Displaying a Message on the Message Line When a Subfile Control

Record is Written
You can specify that messages are to be displayed on the message line when a
subfile control record is written using the SFLMSG or SFLMSGID keyword. If the
message is a constant, use the SFLMSG keyword; if it is defined in a message file,
use the SFLMSGID keyword. The restrictions on these keywords are the same as
ERRMSG and ERRMSGID.

Displaying a Message on the Message Line Using a Message Field
You can specify a message field (M in position 38). The value from this output field
will appear on the message line. The value in the field is specified by the applica-
tion program in the output buffer. The length of this field should not exceed 78
positions if the message is to be displayed on a 24 by 80 screen, or 130 positions if
the message is to be displayed on a 27 by 132 screen. Message help and substi-
tution variables are not supported for a message line.
Priorities for Displaying Messages on a Message Line

The message displayed on the message line is determined by the following order of
priority (1 is the highest):
1. ERRMSG
2. ERRMSGID
3. SFLMSG
4. SFLMSGID
5. Position 38 in DDS is M
In addition, you can change the line on which messages are displayed by using the
MSGLOC keyword. If not specified otherwise, the message line is the last line on
the display. If you use the MSGLOC keyword, the new message line applies to
messages that are displayed for validity-checking errors and keys that are not valid
as well as to user-defined messages.
Notes:
1. If the MSGLOC keyword is not specified, and a display station capable of dis-
playing 27 lines is attached to a local display station controller or attached to a
remote 5294 or 5394 controller, the default values are:
Line 28 for the 27 by 132 screen size
Line 25 for the 24 by 80 screen size
2. If line 25 is specified for the 24 by 80 mode, either because the default was
used or line 25 was specified in the MSGLOC keyword, the message actually
appears on line 24 unless the display is capable of displaying the message on
line 25.
3. The normal system display for message help gives the user access to
extended help (by pressing the Help key again), and may allow the user to use
F10 to display all messages in the job log. The message help display used for
a display station other than the job requester display station or for a display
station associated with a multi-display file does not provide these functions.
Displaying Messages in a Field on the Display

You can specify that messages are to be displayed in a field on the display using
the MSGID keyword. The message is truncated if it is longer than the MSGID field.
The message is padded with blanks if it is shorter than the MSGID field.
When the MSGID keyword is used, the keyboard is not locked because the field on
which it is specified is a normal output-capable field. Message help and substi-
tution variables are not supported for the MSGID keyword.
Chapter 8. Handling Messages and Errors for Display Files 8-3

Displaying Messages on a Program Message Queue
You can specify that messages that are contained on a program message queue
are to be displayed by using the SFLMSGRCD, SFLMSGKEY, and SFLPGMQ
keywords. When you use subfile support for messages, you can display more than
one message at a time and the keyboard does not lock while the message is being
displayed. Because the messages specified here are from the program message
queue, both message help and substitution text are supported. See “Displaying
Error Messages from Subfiles” on page 4-23 for more information. See also the
CL Programming book for information on message queues and sending messages.
Displaying Error Messages through a Subfile

The ERRSFL (error subfile) keyword can be used to indicate that the error mes-
sages associated with ERRMSG, ERRMSGID, SFLMSG, and SFLMSGID keywords
will be displayed on the message line using a system-supplied error subfile.
The ERRSFL keyword can be used in addition to the ERRMSG and ERRMSGID or
SFLMSG and SFLMSGID keywords to allow a user to roll through a subfile of error
messages. One error message is displayed at a time. The user's program handles
the validity checking of the fields, setting on the option indicators for the appropriate
message to be sent for the fields in error. The system handles putting the
message associated with the field in error in the error subfile, and displaying the
error messages.
The ERRSFL keyword can also be used to put error messages into an error subfile
when the system handles validity checking. Error messages are put into the error
subfile when input fails the validity check for the following reasons:
DDS keywords CHECK(M10 M11 VN VNE), COMP, RANGE, and VALUES
Floating point operations
More than one decimal point is entered in a field that has one or more decimal
positions
Either too many or too few decimal positions are entered in a field that has one
or more decimal positions
The messages can be viewed by paging through the error subfile. Only one error
message is displayed at a time. When the error subfile is displayed, the keyboard
is not locked. It is not necessary to press the Reset key prior to correcting the
fields in error.
If there is a record format currently displayed that covers the line defined to be the
message line, the ERRSFL keyword is ignored.
When both validity checking and ERRMSG/ERRMSGID or SFLMSG/SFLMSGID

are used on the screen at the same time, the resulting errors are not all present in
the error subfile at the same time. When the write operation is done, the messages
from ERRMSG, ERRMSGID, SFLMSG, and SFLMSGID are present in the error
subfile. After data is typed and validity checking errors occur, the error subfile is
cleared and only the validity checking errors are present.
Following is an example of how the ERRSFL keyword can be used:

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A MSGLOC(24)
A ERRSFL
A R RCD1
A FIELD1 5A B 2 3
A 1ð ERRMSGID(MSGððð1 MSGF1 1ð &MDTA1)
A 11 ERRMSG('Error Msg 1' 11)
A FIELD2 1ðA B 3 3
A 2ð ERRMSG('Error Msg 2' 2ð)
A 21 ERRMSGID(MSGððð2 MSGF1 21)
A 22 ERRMSGID(MSGððð3 MSGF1 22 &MDTA3)
A FIELD3 2A B 4 3
A 3ð ERRMSGID(MSGððð4 MSGF1 3ð)
A MDTA1 78A P
A MDTA3 78A P
A
A
A
A
A
A
Figure 8-1. Sample DDS Source for ERRSFL Keyword
In this example, assume that RCD1 is currently on the display. When validating the
input data, your program detects several errors and sets on the option indicators
11, 21, and 30. On the subsequent output operation:
FIELD1, FIELD2, and FIELD3 are displayed in reverse image.
The cursor is located in position 2, 3 (start of FIELD1).
The keyboard is not locked.
An error subfile is displayed on line 24. The subfile contains three records:
Error Msg 1, the MSG2 message, and the MSG4 message. The user can
page through the messages, and by placing the cursor on the message line
and pressing the Help key, view the message help for MSG2 or MSG4.
Message CPF9897, which indicates that no help information is available, is dis-
played if the cursor is not located on the message line when the user is
attempting to view the message help of MSG2 or MSG4.
If the Help key is pressed on the message line for Error Msg 1, the message
help for message CPF9897 appears. The message help explains that no
message help is available.
On the subsequent display of RCD1, the error subfile is cleared of the previous
error messages.
The following is a DDS example of defining the SFLMSGID keyword in a display

file:

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A MSGLOC(24)
A ERRSFL
A R SFLRCD1 SFL
A SFL1 5A B 2 3
A R CTLRCD1 SFLCTL(SFLRCD1)
A SFLPAG(1)
A SFLSIZ(15)
A SFLDSP SFLDSPCTL
A 1ð SFLMSGID(SFLððð1 USERMSGF 1ð)
A 11 SFLMSG('Error Msg 1' 11)
A R SFLRCD2 SFL
A SFL2 7A O 4 3DFT('FIELD 2')
A R CTLRCD2 SFLCTL(SFLRCD2)
A SFLPAG(1)
A SFLSIZ(15)
A SFLDSP SFLDSPCTL
A 2ð SFLMSG('Error Msg 2' 2ð)
A 21 SFLMSGID(SFLððð2 USERMSGF 21)
A
A
Figure 8-2. Sample DDS Source for SFLMSGID Keyword
Assume that CTLRCD1 and CTLRCD2 are on the display. When validating the
input data, your program detects several errors and sets on the option indicators 11
and 21. On the subsequent output operation:
The cursor is located in position 2, 3 (start of SFLRCD1).
The keyboard is not locked.
An error subfile is displayed on line 24. The subfile contains two records:
Error Msg 1 and the message of SFL0002. The user can page through the
messages, and by placing the cursor on the message line and pressing the
Help key, view the message help for SFL0002. If the Help key is pressed on
the message line for Error Msg 1, the message help for message CPF9897
appears, which explains that no help information is available.
On the subsequent display of CTLRCD1 and CTLRCD2, the error subfile is
cleared of the previous error messages.
The SFLEND keyword is specified on the ERRSFL subfile control record. An error
is issued and the keyboard is locked if the user attempts to roll beyond the top or
bottom of the file.
The following considerations apply to the ERRSFL keyword, except when used with
the ERRMSG and ERRMSGID keywords and the SFLMSG and SFLMSGID
keywords:
When the error subfile is displayed (that is, there are one or more fields in
error), pressing a Roll key results in the error subfile being rolled, regardless of
the cursor position at the time or whether other subfiles are currently displayed.
When processing errors from validity check, the error subfile is built every time
a valid command key, Roll key, or Enter key is pressed and errors occur.

When a valid command key or Enter key is pressed, the message for the first
field in error is always displayed.
If the error subfile is rolled and the field that corresponds to the message that
was displayed when the Roll key was pressed is valid, the error subfile is dis-
played with the message of the first field in error.
If the error subfile is rolled and the field that corresponds to the message that
was displayed when the Roll key was pressed is not valid, the error subfile is
rolled to the next field in error.
When rolling through the error subfile, the cursor is positioned in the field corre-
sponding to the error message being displayed.
If no fields are in error and a Roll key is pressed, a roll is attempted on the
subfile and a roll error message is displayed (assuming no other area that can
be rolled is encountered first). See Chapter 4, “Displaying Groups of Records
Using Subfiles” on page 4-1 for more information about rolling subfiles.
If the program writes a record and the user presses a Roll key after typing data
that is not valid, the error subfile is built and the error message for the first field
in error is displayed.
Sounding an Alarm for Messages

To sound an audible alarm when an active ERRMSG, ERRMSGID, SFLMSG, or
SFLMSGID keyword is detected or when a validity check message is displayed,
specify the MSGALARM keyword. This keyword is allowed at the file or record
level. The alarm sounds for only a short time.
The MSGALARM keyword can be used on any record in a display file, including
subfile control records. The MSGALARM keyword can also be used with the
ERRSFL keyword.
Note: If the MSGALARM and ALARM keywords are specified and active on the
same record format, the alarm sounds only once.
If the SFLMSG or SFLMSGID keyword is active and both the MSGALARM

and ALARM keywords are specified, an alarm is sounded. If no message is
displayed, the ALARM keyword and not the MSGALARM keyword is
responsible for sounding the alarm.
Automatically Handling Permanent I/O Errors on Display Stations

Permanent I/O errors on display stations can be handled automatically when you
use the device-recovery-action job attribute. The Device Recovery Action
(DEVRCYACN) parameter of the Change Job (CHGJOB) command indicates a
system action for jobs that are about to receive a permanent I/O error (such as a
display station being powered off). You can use the following parameter values:
*DSCMSG When the I/O error occurs, the system runs a Disconnect Job
(DSCJOB) command to suspend the job. The user remains dis-
connected until signing on again to the same display. The job is
resumed at the point just after the I/O operation. Display data
management sets the major/minor return code to 83E1 and sends
a CPF509F message to the program message queue. These indi-
cate that the display has been cleared and is again available for
use.

*DSCENDRQS This option also runs the DSCJOB command when an I/O error
occurs, but when the job is resumed, the system runs the End
Request (ENDRQS) command to give control to the most recent
request-processing program.
*ENDJOB When an I/O error occurs, the job ends automatically and its priori-
ties are lowered to conserve system resources.
*ENDJOBNOLIST Again, the job ends automatically and its priorities are lowered to
conserve system resources. However, no job log is produced for
the job.
When an I/O error occurs (especially in the case of a communications line failing
for several active jobs at once), using the device-recovery-action job attribute can
save system resources. Also, the device-recovery-action job attribute makes the
job of coding for I/O errors easier. Once the display station is recovered, the user
application can continue at the point the error occurred by using the *DSCMSG and
*DSCENDRQS values. For *DSCMSG, if the major/minor return code is 83E1 after
an I/O operation, the program needs to assume that the display is blank. The
program must branch back to the point at which the first I/O operation to the display
is done. For *DSCENDRQS, the request-processing program receives control
when connecting to the job again. This is similar to selecting option 2 on the
System Request menu. No error recovery is performed for *MSG or *DSCMSG
until an I/O operation is performed to the device in error. For all other values, the
recovery occurs immediately when the error occurs.
The device-recovery-action job attribute works only for *REQUESTER display

stations and does not apply to batch jobs, pass-through jobs, or work-station-
function jobs.
Analyzing Error Messages Sent from the System

This section describes error conditions that an application program may encounter
during its operation and the provisions that can be made within the program itself to
attempt to deal with these conditions. The CL Programming book discusses how to
use the debug functions to resolve unexpected errors encountered in the applica-
tion programs. The chapter on handling problems in the Basic System Operation,
Administration, and Problem Handling book describes the programs that are avail-
able for analyzing and reporting system errors and hardware failures.
Errors can be detected when a file is opened, when a program device is acquired
or released, during I/O operations to a file, and when the file is closed. When
appropriate, the system will automatically try to run a failing operation again, up to
a retry limit. When a retry is successful, neither operator nor program action is
required. Errors that can affect the processing of the program may be reported in
any or all of the following ways:
A notify, status, diagnostic, or escape message may be sent to the program
message queue of the program using the file. These messages may also
appear in the job log, depending on the message logging level set for the job.
A notify, status, diagnostic, or escape message may be sent to the operator
message queue (QSYSOPR) or the history message queue (QHST).
A file status code may be returned by the high-level language.
A major/minor return code is returned in the I/O feedback area for display files.

Information regarding the error may be saved in the system error log for use by
the problem analysis and resolution programs.
An alert message may be sent to an operator at another system in the network.
The normal program flow may be interrupted and control may be transferred to
an error-handling subroutine, or other language operations may occur. For
additional information about how to handle run-time errors, see the appropriate
high-level language manual.
Only some of these are significant to a program that is attempting error recovery.
Not all file errors allow programmed error recovery. Some errors are considered
permanent; that is, the file, device, or program cannot work until some corrective
action is taken. This might involve resetting the device by varying it off and on
again, or correcting an error in the device configuration or the application program.
Some messages and return codes are used to inform the user or the application
program of conditions that are information rather than errors, such as change in the
status of a communications line, or system action taken for an unexpected condi-
tion. In many cases, it is possible for the application program to test for an error
condition and take some preplanned recovery action which allows the program to
continue without intervention from the user.
Understanding Messages and Message Monitors

Displayed messages are the primary source of information for anyone who is
testing a new application. A message usually contains more specific information
than the file status code, the indicators, or the major/minor return code. The control
language allows messages to be monitored so that the CL program can intercept a
message and take corrective action. See the CL Programming book for more infor-
mation about message types and message monitors. In most high-level languages,
either the file status code or major/minor return code (described in the following
section) is a more convenient source of information.
Message numbers are assigned in categories to make it easier for a program to

monitor for any of a group of related messages. The following message number
ranges are assigned for file error messages:

Table 8-1. System Message Number Ranges
Message IDs Operation Message Type
CPF4001–40FF Open Diagnostic and status.
CPF4101–43FF Open Escapes that make the file unusable.
CPF4401–44FF Close Diagnostic and status.
CPF4501–46FF Close Escapes that make the file unusable.
CPF4701–48FF I/O, Acquire, and Notify with a default reply of cancel, status and
Release escapes that do not make the file or device
unusable.
CPF4901–49FF I/O, Acquire, and Notify with a default reply of ignore.
Release
CPF5001–50FF I/O, Acquire, and Notify with a default reply of cancel.
Release
CPF5101–53FF I/O, Acquire, and Escapes that make the file or device unusable.
Release
CPF5501–56FF I/O, Acquire, and Escapes that make the file or device unusable.
Release
Some status messages, CPF4018 for example, are preceded by a diagnostic

message that provides additional information. Diagnostic messages may be kept in
the job log, depending on the message logging level of the job. If a CL program
monitors for CPF4018, CPF5041, or similar messages, it can retrieve the accompa-
nying diagnostic message from the program message queue.
If an error occurs for which an escape message is issued and the message is not
monitored, your program will be ended and the message displayed in the operator
message queue. Status messages may also be monitored, but if they are not mon-
itored, the program continues. Most high-level languages except CL monitor for all
the file errors that are likely to be encountered, and provide some standard
recovery. Depending on the severity of the error, the high-level language may
simply end the program and issue a message of its own. Alternatively, you may
code an error recovery routine to handle errors that are anticipated in that particular
application.
Within these error-handling routines, it is usually necessary to examine the file

status or major/minor return codes to determine the cause of the error. The
manuals for the language you are using explain how to access file status and
major/minor return codes. The language manuals also explain the file status codes
as they are defined for each language.
Understanding Major/Minor Return Codes

Major/minor return codes are used to report errors and certain status information for
display files. They are usually stated as four characters: the first two referring to
the major code and the second two referring to the minor code. The major code
indicates the general type of error, and the minor provides further detail. Minor
codes, except zero, have the same or a similar meaning, regardless of the major
code with which they are combined.
The application program can test the return code after each I/O operation. If the
major return code is 00, the operation completed successfully and the minor return
code contains status information that indicates whether a read or a write operation
should be performed next. A major return code of 04 or above indicates that an
error occurred. The program may test for any specific errors for which programmed

recovery is attempted. The application program may test for a specific condition by
comparing the major and minor codes as a unit, or may identify a class of condi-
tions by testing the major code alone.
Most major/minor return codes are accompanied by any one of several message
numbers, for which the typical recovery action is similar. File status codes are
defined by the individual languages and may be set based on the major/minor
return codes.
The following table defines the major return codes. Appendix E, “Display File
Return Codes” contains specific definitions of the major and minor return codes as
they are used for display files and the message numbers associated with each.
Table 8-2. Major Return Code Definitions

Code Definition
00 The operation requested by your program completed successfully. The minor
includes state information, such as change direction.
02 Input operation completed successfully, but job is being ended (controlled). The
minor includes state information.
03 Successful input operation, but no data was received. The minor includes state
information.
04 Error occurred because an output operation was attempted while data was
waiting to be read.
08 An acquire operation failed because the device has already been acquired or the
session has already been established.
11 A read-from-invited-program-devices operation failed because no device or
session was invited.
34 An input exception occurred. The data length or record format was not accept-
able for the program.
80 A permanent system or file error, which cannot be recovered from, occurred.
Programmer action is required to correct the problem.
81 A permanent device or session error, which cannot be recovered from, occurred
during an I/O operation.
82 A device or session error occurred during an open or acquire operation.
Recovery may be possible.
83 A device or session error occurred during an I/O operation. Recovery may be
possible.
Recovering from Errors

The following sections describe the error recovery action that is appropriate for
each group of major return codes.
Normal Completion
A major/minor return code of 0000 indicates that the operation requested by your
program was completed successfully. Most of the time, no message is issued. In
some cases, a diagnostic message might be used to inform the user of some
unusual condition that the system was able to handle, but which might be consid-
ered an error under some conditions. For example, a parameter that is not valid
might be ignored, or some default action taken.

Completion with Exceptions
Several rather specific major return codes have been assigned to conditions for
which a specific response from the application program is appropriate.
A major return code of 02 indicates that the requested input operation completed
successfully, but the job is being ended (controlled). The application program
should complete its processing as quickly as possible. The controlled cancel is
intended to allow programs time to end in an orderly manner. If your program does
not end within the time specified on the ENDJOB command, the job will be ended
by the system without further notice.
A major return code of 03 indicates that an input operation completed successfully

without transferring any data. For some applications, this might be an error condi-
tion, or it might be expected when the user presses a function key instead of
entering data. It might also indicate that all the data has been processed, and the
application program should proceed with its completion processing. In any case,
the contents of the input buffer in the program should be ignored.
A major/minor code of 0309 is used to indicate that no data was received and the
job is being ended (controlled). A major/minor code of 0310 indicates that there is
no data because the specified wait time has ended. Other minor return codes
accompanying the 02 or 03 major code are the same as for a 00 major code, indi-
cating communications status and the operation to be performed next.
A major return code of 04 indicates that an output exception occurred. Specifically,

your program attempted to send data when there was data waiting to be received.
This is probably the result of not handling the minor return code properly on the
previous successful completion. Your program can recover by simply receiving the
incoming data and then repeating the write operation.
A major return code of 34 indicates that an input exception occurred. The received
data was either too long or incompatible with the record format. The minor return
code indicates what was wrong with the received data, and whether the data was
truncated or rejected. Your program can probably handle the exception and con-
tinue. If the data was rejected, you may be able to read it by specifying a different
record format.
Two other return codes in this group, 0800 and 1100, are both usually the result of
application programming errors, but are still recoverable. 0800 indicates that an
acquire operation failed because the device has already been acquired or the
session has already been established. 1100 indicates that the program attempted
to read from invited devices with no devices invited. In both cases, the request that
is not valid is ignored, and the program may continue.
No message is issued with a 02 major code or most minor codes with the 03 major
code, but the other exceptions in this group are usually accompanied by a message
in the CPF4701–CPF47FF or CPF5001–CPF50FF range.

Permanent System or File Error
A major return code of 80 indicates a serious error affecting the file. The applica-
tion program must close the file and reopen it before attempting to use it again, but
recovery is unlikely until the problem causing the error is found and corrected. To
reset an error condition in a shared file by closing it and opening it again, all pro-
grams sharing the open data path must close the file. This may require returning to
previous programs in the program stack and closing the shared file in each of those
programs. You should refer to the text of the accompanying message to determine
what action is appropriate for the particular error.
Within this group, several minor return codes are of particular interest. A
major/minor code of 8081 indicates a serious system error for which an APAR
probably will be required. The message sent with the major/minor return code may
direct you to run the Analyze Problem (ANZPRB) command to obtain more informa-
tion.
A major/minor code of 80EB indicates that incompatible options or options that are
not valid were specified in the display file or as parameters on the open operation.
In most cases you can close the file, end the program, correct the parameter that is
not valid with an override command, and run the program again. The override
command affects only the job in which it is issued. It allows you to test the change
easily, but you may eventually want to change or re-create the display file as
appropriate to make the change permanent.
Permanent Device or Session Error on I/O Operation

A major return code of 81 indicates a serious error affecting the device or session.
This includes hardware failures affecting the device, communications line, or com-
munications controller. It also includes errors due to a device being disconnected
or powered off unexpectedly and abnormal conditions that were discovered by the
device and reported back to the system. Both the minor return code and the
accompanying message provide more specific information regarding the cause of
the problem.
Depending on the file type, the program must either close the file and open it again,
release the device and acquire it again, or acquire the session again. To reset an
error condition in a shared file by closing it and opening it again, all programs
sharing the open data path must close the file. In some cases, the message may
instruct you to reset the device by varying it off and on again. It is unlikely that the
program will be able to use the failing device until the problem causing the error is
found and corrected, but recovery within the program may be possible if an alter-
nate device is available.
Some of the minor return codes in this group are the same as those for the 82
major return code. Device or line failures may occur at any time, but an 81 major
code occurs on an I/O operation. This means that your program had already
established a link with the device or session. Therefore, some data may have been
transferred, but when the program is started again, it starts from the beginning. A
possible duplication of data could result.
Message numbers accompanying an 81 major code may be in the range indicating

either an I/O or a close operation. A device failure on a close operation simply may
be the result of a failure in sending the final block of data, rather than action spe-
cific to closing the file. An error on a close operation may result in the file being left
partially closed. Your error recovery program should respond to close failures with

a second close operation. The second close will always complete, regardless of
errors.
Device or Session Error on Open or Acquire Operation

A major return code of 82 indicates that a device or session error occurred during
an open or acquire operation. Both the minor return code and the accompanying
message will provide more specific information regarding the cause of the problem.
Some of the minor return codes in this group are the same as those for the 81
major return code. Device or line failures may occur at any time, but an 82 major
code indicates that the device or session was unusable when your program first
attempted to use it. Thus no data was transferred. The problem may be the result
of a configuration or installation error.
Depending on the minor return code, it may be appropriate for your program to
recover from the error and try the failing operation again after some waiting period.
The number of times you try should be specified in your program. It may also be
possible to use an alternate or backup device or session instead.
Message numbers accompanying an 82 major code may be in the range indicating

either an open or an acquire operation. If the operation was an open, it is neces-
sary to close the partially opened file and reopen it to recover from the error. If the
operation was an acquire, it may be necessary to do a release operation before
trying the acquire again. In either case, the file wait time should be specified long
enough to allow the system to recover from the error.
Recoverable Device or Session Errors on I/O Operation

A major return code of 83 indicates that an error occurred in sending data to a
device or receiving data from the device. Recovery by the application program is
possible. Both the minor return code and the accompanying message provide
more specific information regarding the cause of the problem.
Most of the errors in this group are the result of sending commands or data that are
not valid to the device, or sending valid data at the wrong time or to a device that is
not able to handle it. The application program may recover by skipping the failing
operation or data item and going on to the next one, or by substituting an appro-
priate default. There may be a logic error in the application.

Chapter 9. Creating and Accessing Menus Using Display
Files
This chapter describes user-defined menus and tells you how to create them and
use them with system menus.
The first two types of user-defined menus can be created using the information in
this chapter:
Display file menus Menus that use a display defined by data description specifi-
cations (DDS) to present a menu format. The menu func-
tions are controlled by a message file containing the
commands used to run each of the menu options.
Program menus Menus that use a high-level language program to present the
menu format and provide the functions necessary to run the
menu options.
UIM menus Menus that a menu object defined by the user interface
manager (UIM) panel group definition language. For more
information on defining your own menus using the UIM, see
“Defining a Menu Object Using UIM” on page 16-6.
Information about CL commands
Some of the examples in this chapter use CL commands. For more information
about specific CL commands, see the CL Reference.
Running System and User-Defined Menus

Menus that consist of *MENU object types are run using the Go to Menu (GO)
command. The GO command allows you to specify either a particular menu or a
generic menu name. If you specify a generic name, you are shown the Work with
Menus display, which shows all the menus available for your use. From this list,
you can choose a menu to run.
Returning to a Menu after Running the GO command

Using the Return Point (RTNPNT) parameter of the GO command, you can specify
whether or not you want to return to the menu from which the command was
entered after running the menu specified by the GO command.
Determining the Previous Menu

A menu is placed on an internal menu stack before it is run. If a stack is not avail-
able for the menu, one is created. When the Cancel key is pressed for a menu,
the previous menu in the stack is shown. Each menu stack is 10 elements
(menus) deep. When the eleventh menu is placed on the menu stack, the first, or
oldest, menu is removed from the stack. This menu cannot be returned to by using
the Cancel key.

Using the Cancel and Exit Keys on Menus
In the following example, a series of menus is presented using both the menu
options and the GO command.
1. From the AS/400 Main Menu, GO PROGRAM RTNPNT(\YES) is typed on the
command line. Specifying RTNPNT(*YES) here means that the Main Menu will
be used as a return point.
à MAIN Main Menu

ð
System XXXXXXXX
1. User tasks
2. Office tasks
3. General system tasks
4. Files, libraries, and folders
5. Programming
6. Communications
7. Define or change the system
8. Problem handling
9. Display a menu
9ð. Sign off
Selection or Command
===> GO PROGRAM RTNPNT(\YES)___________________________________________________
______________________________________________________________________________
F3=Exit F4=Prompt F9=Retrieve F12=Cancel F13=Information Assistant
F23=Set initial menu
á ñ
2. Next, by typing GO PROBLEM RTNPNT(\NO) on the command line of the Program-
ming menu and pressing the Enter key, the Problem Handling menu is shown.
The Programming menu is not set as a return point.
à PROGRAM Programming
ð
System XXXXXXXX
1. Programmer's menu
2. Programming Development Manager
3. Utilities
4. Programming language debug
5. SQL pre-compiler
6. Question and answer
7. IBM product information
8. Copy screen image
5ð. System/36 programming
7ð. Related commands
===> GO PROBLEM RTNPNT(\NO)____________________________________________________
______________________________________________________________________________
F16=System main menu
á ñ

à PROBLEM Problem Handling
ð
System XXXXXXXX
1. Question and answer

2. Work with problems
3. Network problem handling
4. Display system operator messages
5. Display the history log
6. System service tools
6ð. More problem handling options
7ð. Related commands
===>___________________________________________________________________________
______________________________________________________________________________
F16=System main menu
á ñ
3. In this example, if the Cancel key is pressed while viewing the Problem Han-
dling menu, the user is returned to the Programming menu because the Pro-
gramming menu is the preceding display on the menu stack. If F3 (Exit) is
pressed while viewing the Problem Handling menu, the user is returned to the
Main Menu, because the Main Menu is the most recent display from which a
GO command was entered with RTNPNT(*YES).
Note that since the default value for the RTNPNT parameter is *YES, GO PROBLEM
will have the same effect as GO PROBLEM RTNPNT(\YES).
Pressing either F3 (Exit) or F12 (Cancel) while viewing the help for a menu returns
the user to the menu itself.
Choosing the Menu That Is Shown at Sign-On Time

To specify a menu as your initial menu, or the first menu you see when you sign
on, press F23 when the menu is shown. F23 sets the initial menu attribute in your
user profile. Unless your initial program requests some other menu, the menu
selected by pressing F23 is shown as the initial menu the next time you sign on.
Note: You can only use this key if LMTCPB(*NO), which allows you to change the
initial menu, is specified in your user profile.
See the Security – Reference for information about initial menus and limited users.
Chapter 9. Creating and Accessing Menus Using Display Files 9-3

Defining Your Own Display File Menus
Display file menus consist of three parts:
A DDS-defined display file to define the way the menu looks at the display
station
A message file to define what action is taken when any of the menu options
are selected
A menu object (*MENU) that contains the menu
Help is available on display file menus for the following:

Commands Command help is shown by typing the command on the
command line, then pressing the Help key.
Function keys Help for function keys is shown by moving the cursor to the func-
tion area and pressing the Help key.
Messages Help for messages is shown by moving the cursor to a message
and pressing the Help key.
Help for the menu options may also be provided using DDS. See “Naming Help
Formats for Menus” on page 9-6 for more about help information.
More information about the specific DDS keywords used in this chapter is found
in the DDS Reference.
Understanding DDS and Display File Considerations for Menus

Several restrictions exist for the DDS used in defining a menu:
Table 9-1 (Page 1 of 2). Restrictions for Display File Menus

Affected Area Restriction
Display size The menu format and the associated help record formats for the
menu in the display file must have a display size of 24 rows by 80
columns, DSPSIZ(*DS3) in DDS.
Display file and The menu record format name must be the same as the display file
record format names name.
Help format names Help format names must follow the convention #Hxxyy, described in
“Naming Help Formats for Menus” on page 9-6. The help record
format is limited to 150 items.
Indicator area A separate indicator area (INDARA keyword) must be declared in
the DDS for the display.
Subfile use Subfiles cannot be used.

Table 9-1 (Page 2 of 2). Restrictions for Display File Menus
Affected Area Restriction
Allowed lines Only the first 21 lines of the display should be described. Only the
first 21 lines of the help display should be described. Lines 22 and
23 are used with long command lines; system messages are
shown on line 24. (Line 23 is used with short command lines and
line 24 is used for messages.)
The following lines can be used when a function key legend is
requested:
For a long command line with no function key legend, lines 1
through 21
For a long command line with a function key legend, lines 1
through 19
For a short command line with no function key legend, lines 1
through 22
For a short command line with a function key legend, lines 1
through 20
For no command line with no function key legend, lines 1
through 21
For no command line with a function key legend, lines 1
through 19
Keyboard locking The LOCK record level keyword should be used to prevent the key-
board from unlocking before the display is shown.
Paging The Allow Roll (ALWROL) record level keyword cannot be speci-
fied.
Deferring the write DFRWRT(*NO) is required on the CRTDSPF command when cre-
operation ating a display file menu. DFRWRT(*NO) ensures the menu format
is displayed when the menu is run.
The following suggestions can also be used to help you define your menu using
DDS:
Table 9-2. Suggestions for Display File Menus

Affected Area Option
Restoring the display The RSTDSP(*NO) is optional on the CRTDSPF command, but
may significantly improve system performance if specified.
Menu and display An alias can be used for the name of the menu and for the name
station alias of the display station (for the System/36 environment). When
issuing the CRTMNU command, you can specify a different name
than the name used in the DDS. This way, the name of the display
station identifier will be displayed with the menu. By giving the
menu a different name, you can use the GO command to find that
menu.
Describing Menu Actions in a Message File

Message files are used to describe what action is taken when a menu option is
selected. Commands controlling the action to be taken are usually placed in the
message. In some cases, the command string may be too long to fit in the
message. In these cases, the message contains the message identifier for the
message; the command is then placed in the message help.

Messages used in display file menus must be named using the message prefix
USR. The remaining four digits of the message identifier correspond to the menu
option number.
For example, if option 3 on a given display file menu is:

3. Personnel Menu
then the message describing the action taken when 3 is entered on the command
line uses identifier USR0003. The message could contain any command, such as
'GO PERSMENU RTNPNT(\NO)'.
See “Creating and Displaying Your Own Messages” on page 8-1 for more informa-
tion about messages.
Naming Help Formats for Menus

Help formats for display file menus are named using the form:
#Hxxyy
where:
xx is the number of the first menu option to which the help information applies
yy is the number of the last menu option to which the help information applies
For example, #Hð1ð3 could be used to name help that applies to menu options 1
through 3. #Hð2ð2 names the help that applies to menu option 2.
#Hðððð names the extended help for the menu.
The help formats may be described in any order in the DDS. The system sorts the
help formats in ascending order when the menu is run.
If two or more help format names apply to the same option, only the first help
format (as sorted by the system) will be shown when Help is requested for that
option. For example, if the following help formats are given:
#Hðððð
#Hð1ð1
#Hð2ð5
#Hð3ð6
#Hð7ð7
Typing 3 on the command line (to select option 3) and pressing the Help key will
show the help designated #Hð2ð5. In this example, #Hð3ð6 can be viewed using the
Page Down key, but will be shown directly only by requesting help for option 6.
Similarly, by moving the cursor to the command line and pressing the Help key with
no option typed on the command line, the user is shown extended help for the
menu (#Hðððð). The cursor movement keys can be used to look through the other
help formats for the menu options.
The following example shows a menu with five options. The names of the help
formats and the menu options to which they apply are shown following the
example.

à PERSMENU Personnel Menu
ð
1. Departments menu
2. Education menu
3. Benefits menu
4. Job openings
5. Job applicants
===>____________________________________________________________________________
_______________________________________________________________________________
á ñ
Help Name Contents
#H0000 General help for the Personnel Menu (PERSMENU)
#H0101 Help for option 1, Departments menu
#H0202 Help for option 2, Education menu
#H0303 Help for option 3, Benefits menu
#H0405 Help for options 4 and 5, Job openings and Job applicants
The help information for the menu options can be shown by typing the option
number on the command line and pressing the Help key, or by pressing Help
(extended help for the menu), and then using the Page Down key to page through
the help for the options.
Building a Display File Menu

The following steps allow you to create a display file (*DSPF) menu:
1. Describing the menu and menu help information
2. Creating the display file
3. Creating the message file
4. Adding messages to the message file
5. Creating the menu
6. Running the menu
The following sections explain each step in detail.
Describing the Menu and Menu Help Information

DDS is used to describe both the appearance and the help for the menu.
The following DDS is for the sample display called PERSMENU. The first record
format (PERSMENU) is used to describe the appearance of the menu when dis-
played. Five menu options are listed, starting in position 7 of lines 5 through 9.
Five more record formats are shown: #H0000, #H0101, #H0202, #H0303, and
#H0405. Each of these is used to provide help information for the menu and its
options. Following the system convention described above (see “Naming Help

Formats for Menus” on page 9-6), #H0000 is used to provide extended help for the
menu. The other record formats provide help for the menu options.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A\ PERSONNEL MENU (PERSMENU) SPECIFICATION
A\
A PRINT DSPSIZ(\DS3)
A INDARA
A\
A R PERSMENU LOCK
A 1 ð2'PERSMENU'
A 1 29'PERSONNEL MENU'
A 3 ð2'SELECT ONE OF THE FOLLOWING:'
A 5 ð7'1. DEPARTMENTS MENU'
A 6 ð7'2. EDUCATION MENU'
A 7 ð7'3. BENEFITS MENU'
A 8 ð7'4. JOB OPENINGS'
A 9 ð7'5. JOB APPLICANTS'
A 21 ð2'SELECTION OR COMMAND'
A\
A R #Hðððð LOCK
A 1 ð2'GENERAL'
A 2 26'HELP FOR THE PERSONNEL MENU
A 3 ð2'THIS IS THE GENERAL HELP'
A
A
A 3 27'FOR THE PERSONNEL MENU.'
A\
A R #Hð1ð1 LOCK
A 1 ð2'HELP1'
A 1 26'HELP FOR OPTION 1'
A 3 ð2'THIS IS THE HELP'
A 3 19'FOR OPTION 1.'
A\
A R #Hð2ð2 LOCK
A 1 ð2'HELP2'
A\
A R #Hð3ð3 LOCK
A 1 ð2'HELP3'
A\
A R #Hð4ð5 LOCK
A 1 ð2'HELP45'
A 1 26'HELP FOR OPTIONS 4 AND 5'
A 3 19'FOR OPTIONS 4 AND 5.'
A\
Figure 9-1. DDS Source for Sample Menu Called PERSMENU

Creating the Display File
To create the display file for the menu, enter the following command:
CRTDSPF FILE(PERLIB/PERSMENU) +
SRCFILE(USERLIB/SFPERS) +
DFRWRT(\NO) +
RSTDSP(\NO)
The DDS source member, PERSMENU, in the source file SFPERS in library
PERLIB, is used to create the display file for the PERSMENU menu.
Creating the Message File

Enter the following Create Message File (CRTMSGF) command to create a
message file called PERSMENU (same name as record format):
CRTMSGF MSGF(PERLIB/PERSMENU) +
TEXT('Message file of commands for menu PERSMENU.')
The message file will be used to contain messages describing the actions taken
when the various menu options are selected.
Adding Messages to the Message File

The Add Message Description (ADDMSGD) command is used to add messages to
the message file. The messages describe the different actions taken when various
menu options are selected.
The MSGID parameter of each ADDMSGD command is in the form USRxxxx, where
xxxx is the menu option number. The MSG parameter contains the command to
run the menu option.
In the following example, the MSG parameters of the first three messages contain
commands to run menus (using the GO command); the last two messages contain
commands which will call programs (using the CALL command) when either of
those menu options are selected from the menu.
ADDMSGD MSGID(USRððð1) MSGF(PERLIB/PERSMENU) +
MSG('GO DEPTMENU RTNPNT(\NO)')
MSG('GO EDUCMENU RTNPNT(\NO)')
MSG('GO BENEMENU RTNPNT(\NO)')
MSG('CALL JOBOPEN')
MSG('CALL JOBAPPS')
Creating the Menu Object

Enter the following Create Menu (CRTMNU) command to create the menu object:
CRTMNU MENU(PERLIB/PERSMENU) TYPE(\DSPF) DSPF(\MENU) +
MSGF(\MENU) DSPKEY(\NO) CMDLIN(\LONG) +
TEXT('Personnel menu')
The DSPKEY parameter specifies whether the function key legend is shown at the
bottom of the menu when the menu is displayed. *NO specifies that the function
key legend is not shown at the bottom of the menu. *YES specifies that the func-
tion key legend is shown at the bottom of the menu. You do not have the option to
display only certain function keys.

The CMDLIN parameter specifies the length of the command line to be displayed.
*LONG specifies a 153-byte long command line. *SHORT specifies a 73-byte long
command line. *NONE specifies a 4-byte option line in place of a command line.
Note: Note that for both the DSPF and MSGF parameters, the value *MENU was
specified. *MENU specifies that the name of the display or message file is
the same as the name of the menu. Display and message file names do
not have to have the same name as the menu.
Running the Menu

The new display file menu can now be run using the GO command:
GO PERSMENU
à PERSMENU Personnel Menu

ð
1. Departments menu
2. Education menu
3. Benefits menu
4. Job openings
5. Job applicants
===>____________________________________________________________________________
_______________________________________________________________________________
á ñ
Defining Your Own Program Menus

Program menus provide an alternative to display file and system menus by using
the GO command to call a program. The user has complete control of the display
and function of the program menu through the program.
Passing Parameters for Program Menus

Three parameters are passed to the program when the menu is run:
The 10-character name of the menu object
The 10-character name of the library containing the menu object
A 2-character binary return code
All three parameters must be declared as variables in the program. The return
code determines how the program menu is exited, simulating the function keys
found on IBM-supplied menus. The four possible values are:
Binary Return Hex

Code Equivalent Description
0 ðððð Call the program (display the menu) again

Binary Return Hex
Code Equivalent Description
-1 FFFF Exit function requested
-2 FFFE Previous function requested
-4 FFFC Home function requested (display the initial menu)
Note: The hexadecimal values shown above are used for those high-level lan-
guages (such as CL) that do not support binary numbers. CL programs
should use a 2-byte character variable.
Building a Program Menu

This example shows how a program (*PGM) menu is created. The following steps
will be shown and described in detail:
1. Describing the menu
2. Creating the display file
3. Entering source and creating a CL program to control the menu function
4. Creating the menu
5. Running the menu
Describing the Menu

The program menu is designed using data description specifications (DDS) to
describe the menu's appearance. The following DDS is for the sample display
called PGMMENU.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
A DSPSIZ(\DS3)
A PRINT
A CAð3(ð1)
A CA12(ð2)
A HOME(ð3)
A INDARA
A R MENUFMT BLINK OVERLAY
A DSPMNUN 1ðA O 1 2
A 1 72 TIME
A 1 31'EXAMPLE PROGRAM MENU'
A DSPATR(HI)
A 2 2'SELECT ONE OF THE FOLLOWING:'
A 3 5'1.' DSPATR(HI)
A 3 1ð'DISPLAY LIBRARY LIST (DSPLIBL)'
A 4 1ð'WORK WITH ACTIVE JOBS (WRKACTJOB)'
A 5 1ð'WORK WITH YOUR JOB (WRKJOB)'
A 6 5'9ð.' DSPATR(HI)
A 6 1ð'RETURN'
A 23 2'OPTION:'
A OPTION 3 I 23 12DSPATR(PC)
Figure 9-2. DDS Source for Program Menu Example

Creating the Display File
Create the display file using the Create Display File (CRTDSPF) command:
CRTDSPF FILE(QGPL/PGMDDS) SRCFILE(USERLIB/SOURCE1)
The DDS source file called SOURCE1 is used to create the display file for the
PGMMENU menu.
Entering the Source and Creating a CL Program

The following CL program is used to control the menu function. (See the CL Pro-
gramming book for more information about entering CL source.) Note that any
high-level language supported by the system could be used to control a menu.
PGM PARM(&MENUNAME &MENULIB &ACTION) /\ Begin the program and +
indicate that 3 parameters will be passed to it when +
called. The parameters include 1) The menu name, 2) +
The menu library name 3) The action desired by this +
program on return. \/
DCL VAR(&MENUNAME) TYPE(\CHAR) LEN(1ð) /\ Menu name \/
DCL VAR(&MENULIB) TYPE(\CHAR) LEN(1ð) /\ Menu library name \/
DCL VAR(&ACTION) TYPE(\CHAR) LEN(2) /\ Action variable \/
DCLF FILE(QGPL/PGMDDS) RCDFMT(MENUFMT) /\ Display file \/
CHGVAR VAR(&DSPMNUN) VALUE(&MENUNAME) /\ Set the menu name on the +
menu \/
SNDRCVF DEV(\FILE) RCDFMT(MENUFMT) /\ Display the menu at the +
display station \/
CHGVAR VAR(&ACTION) VALUE(X'ðððð') /\ Indicate the menu should +
be displayed again \/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ Handle function keys \/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
IF COND(&INð1 \EQ '1') THEN(CHGVAR VAR(&ACTION) +
VALUE(X'FFFF')) /\ If F3 was pressed, set action +
to EXIT \/
VALUE(X'FFFE')) /\ If F12 was pressed, set action +
to PREVIOUS \/
VALUE(X'FFFC')) /\ If HOME was pressed, set action +
to HOME \/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
/\ Handle menu options \/
/\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\/
IF COND(&OPTION \EQ '1') THEN(DSPLIBL) /\ If the menu user +
has selected option 1, then display the library list \/
IF COND(&OPTION \EQ '2') THEN(WRKACTJOB) /\ If the menu user +
has selected option 2, then display the active jobs \/
IF COND(&OPTION \EQ '3') THEN(WRKJOB) /\ If the menu user +
has selected option 3, then display the current job. \/
IF COND(&OPTION \EQ '9ð') THEN(CHGVAR VAR(&ACTION) +
VALUE(X'FFFE')) /\ If the menu user has selected option +
9ð, then set the action to previous. \/
ENDPGM /\ End the program \/
Create the CL program using the Create CL Program (CRTCLPGM) command:

CRTCLPGM PGM(QGPL/PGMCL) SRCFILE(USERLIB/SOURCE1)

Creating the Menu
Create the program menu using the Create Menu (CRTMNU) command:
CRTMNU MENU(QGPL/PGMMENU) TYPE(\PGM) PGM(QGPL/PGMCL)
Running the Menu

The new display file menu can now be run using the GO command:
GO PGMMENU
à PGMMENU EXAMPLE PROGRAM MENU

ð
ð9:ð2:51
SELECT ONE OF THE FOLLOWING:
1. DISPLAY LIBRARY LIST (DSPLIBL)
2. WORK WITH ACTIVE JOBS (WRKACTJOB)
3. WORK WITH YOUR JOB (WRKJOB)
9ð. RETURN
OPTION: ___
á ñ
Exiting from a Program Menu without Returning to the Previous Menu

When you code a TYPE(*PGM) menu to go from one program menu to another
and use the RTNPNT(*NO) parameter, you need to tell the menu driver when to
exit the original menu.
The program menu needs to communicate with the menu driver that F3 was
pressed. If the program menu is coded to go to program MENU2, with a
RTNPNT(*NO), it has to be able to convey information between programs and to
convey information to the menu driver to tell it what should be done. You can use
data queues to communicate between the programs. For more information about
data queues, see the CL Programming book. The following example shows you
how to communicate between program menus if you want to use the
RTNPNT(*NO) parameter to go from one menu to another:

Program 1
PGM
DCL VAR(&FLDLEN) TYPE(\DEC) LEN(5 ð) VALUE (1ð)
DCL VAR(&FIELD) TYPE(\CHAR) LEN(1ð)
DCL VAR(&WAIT) TYPE(\DEC) LEN(5 ð) VALUE(ð) /\ Don't wait \/
.
.
/\ Handle the function keys on the menu \/
IF COND(&INð3 \EQ '1') + /\ F3=Exit pressed \/
THEN(DO)
/\ Delete the Data Queue \/
DLTDTAQ DTAQ(QGPL/DTAQ1)
/\ Create the Data Queue \/
CRTDTAQ DTAQ(QGPL/DTAQ1) MAXLEN(1ð) +
TEXT('Test Data Queue')
GOTO SNDDQ /\ Send info to data queue\/
ENDDO
.
/\ Handle the options on the menu \/
IF COND(&OPTION \EQ 1) +
THEN(GO MENU(\LIBL/MENU2) RTNPNT(\NO)
.
.
/\ Returned from menu 2 after F3 or F12 pressed \/
CALL PGM(QRCVDTAQ) PARM(QGPL DTAQ1 &FLDLEN &FIELD &WAIT)
IF COND((&FLDLEN \NE ð) \AND (&FIELD \EQ 'EXIT '))
THEN(GOTO SNDDQ)
ELSE GOTO END
.
.
SNDDQ:DO
/\ Change the variable so the menu driver will know to \/
/\ exit and send information to the data queue to \/
/\ communicate to next program what happened \/
CHGVAR VAR(&ACTION) VALUE(X'FFFF')
CHGVAR VAR(&FLDLEN) VALUE(4)
CHGVAR VAR(&FIELD) VALUE('EXIT ')
CALL PGM(QSNDDTAQ) PARM(QGPL DTAQ1 \FLDLEN &FIELD)
GOTO END
ENDDO
END: ENDPGM

Program 2
PGM
DCL VAR(&FLDLEN) TYPE(\DEC) LEN(5 ð) VALUE (1ð)
DCL VAR(&FIELD) TYPE(\CHAR) LEN(1ð)
DCL VAR(&WAIT) TYPE(\DEC) LEN(5 ð) VALUE(ð) /\ Don't wait \/
.
.
/\ Handle the function keys on the menu \/
IF COND(&INð3 \EQ '1') + /\ F3=Exit pressed \/
THEN(DO)
/\ Delete the Data Queue \/
DLTDTAQ DTAQ(QGPL/DTAQ1)
/\ Create the Data Queue \/
CRTDTAQ DTAQ(QGPL/DTAQ1) MAXLEN(1ð) +
TEXT('Test Data Queue')
GOTO SNDDQ /\ Send info to data queue\/
ENDDO
.
.
/\ Handle the options on the menu \/
IF COND(&OPTION \EQ 1) +
THEN(GO MENU(\LIBL/MENU2) RTNPNT(\NO)
.
.
/\ Returned from menu 2 after F3 or F12 pressed \/
CALL PGM(QRCVDTAQ) PARM(QGPL DTAQ1 &FLDLEN &FIELD &WAIT)
IF COND((&FLDLEN \NE ð) \AND (&FIELD \EQ 'EXIT '))
THEN(GOTO SNDDQ)
ELSE GOTO END
.
.
SNDDQ:DO
/\ Change the variable so the menu driver will know to \/
/\ exit and send information to the data queue to \/
/\ communicate to next program what happened \/
CHGVAR VAR(&ACTION) VALUE(X'FFFF')
CHGVAR VAR(&FLDLEN) VALUE(4)
CHGVAR VAR(&FIELD) VALUE('EXIT ')
CALL PGM(QSNDDTAQ) PARM(QGPL DTAQ1 \FLDLEN &FIELD)
GOTO END
ENDDO
END: ENDPGM
Avoiding Menu Name Conflict

Because high-level system menus are named by full words, there is some potential
for conflict with user-defined menu names. For example, if you use the CRTMNU
command to create a menu called MAIN, there may be a conflict with the system-
supplied menu, MAIN. If you use the GO command to call that menu (GO MAIN),
the system menu MAIN will probably be shown, because it resides in the QSYS
library. A conflict can also occur if a future release contains a new system menu
that has the same name as a menu you created during the previous release.
Naming Your Menus

To avoid naming conflicts with system command menus, you should avoid menu
names that start with CMD. The system command menu names use the format
CMDxxxxxxx, where xxxxxxx is any subject or verb used in CL command names.

Placing Your Menu in a Higher Library in the Library List
All branches to system menus from other system menus use the library list search
order. Use of the library list search order allows multilingual support for the system
menus. It also allows you to override a system menu by placing your own version
of it in a library higher on the search order than library QSYS.
Specifying the Library That Contains the Menu

You can avoid menu name conflict by specifying the library that contains the menu
you want to run. For example, you can use GO MENU(\USRLIBL/menu-name) to call
user-defined menus, and use GO MENU(\LIBL/menu-name) to call system menus.
Using the Generic Menu Specification

When working interactively, you can use a generic menu specification on the GO
command to avoid menu name conflict. In an example given earlier (see “Avoiding
Menu Name Conflict” on page 9-15), a potential conflict existed between system
and user-defined menus called MAIN. By specifying GO MAIN*, the system will
display a list of all menu names that start with MAIN in your library list and allow you
to select which menu you want.
Changing the Command Default after Duplicating a Command

You can use the Create Duplicate Object (CRTDUPOBJ) command to create a
duplicate of the GO command for calling user-defined menus. The following
example creates a duplicate of the GO command called GOUSR:
CRTDUPOBJ OBJ(GO) FROMLIB(QSYS) OBJTYPE(\CMD) NEWOBJ(GOUSR) TOLIB(QGPL)
Next, use the Change Command Default (CHGCMDDFT) command to change the
command default for the MENU parameter to use library *USRLIBL rather than
*LIBL:
CHGCMDDFT CMD(QGPL/GOUSR) NEWDFT('MENU(\USRLIBL/\N)')
With the MENU parameter default changed to *USRLIBL, the GOUSR command
will bypass system menus and find only those menus in the user portion of your
library list.
Displaying Menu Attributes

The Display Menu Attributes (DSPMNUA) command can be used to show the attri-
butes of a menu object. These include:
The menu type (*UIM, display file, or program menu)
The display and message files used by display file (*DSPF) menus
The programs used by program (*PGM) menus
The current (CURLIB) and product (PRDLIB) libraries associated with the menu
The text describing the menu object
Changing Menu Attributes

The Change Menu (CHGMNU) command can be used to change the attributes of a
menu object without having to re-create the object. The attributes which can be
changed are:
The current (CURLIB) and product (PRDLIB) libraries for all menu types

The descriptive text for all menu types
The display and message files used by display file (*DSPF) menus
The programs used by program (*PGM) menus
Deleting Menus
The Delete Menu (DLTMNU) command can be used to delete menu objects from a
library. The DLTMNU command can be used to delete only the menu object. Ref-
erenced display and message files (used by display file menus) and programs
(used by program menus) can also be deleted.
DLTMNU is a generic command. For example, all menus in a library called OELIB
could be deleted using the command, DLTMNU OELIB/\ALL.
As another example, if only those menus in OELIB whose names started with ACC
were to be deleted, the command, DLTMNU OELIB/ACC\ could be used.

Chapter 10. Using User-Defined Data Streams
Instead of having the system control and process the 5250 display data stream,
you can control and process it. To do so, you must use the USRDFN keyword in
the DDS for a display file. The data is sent to the display station using a normal
output operation that uses the name of the record format containing the USRDFN
keyword. When input data is received after the output operation, your program
must determine through the input record area what was received from the display
station.
Note: You should be careful when using this support because error conditions can
cause an apparent OS/400 malfunction.
When you use the USRDFN keyword at the record level, the format does not
contain any fields. Therefore, the buffer length of the file defaults to the length of
the longest normal record or 100 (whichever is greater). If the user-defined data
stream is longer than this default buffer length, you should perform the following
steps to obtain a larger buffer length:
Define an externally described file, and create the program using this file and a
record format in that file. The format should not have response indicators
defined for it. This includes file-level indicators that are spread to all record
formats. Any fields in the format should be defined with a field use of both
(input and output).
Create a second file and specify LVLCHK(\NO). The second file should have two
record formats:
– A format with the same name as the format in the first file and which con-
tains the USRDFN keyword.
– A format with one field in it. The length of this field must be as long as the
longest user-defined data stream that is to be sent to the screen.
When you run the program, override the first file with the second display file.
Information about 5250 Display Data Streams
For information about coding 5250 display data streams, see the following
manuals:
IBM 5250 Information Display System Functions Reference.
IBM 5494 Remote Control Unit Functions Reference.
Understanding Display Station Differences

If you use user-defined data streams, you should be aware of the following differ-
ences between local display stations (those attached to the display station con-
troller) and remote display stations (those attached to remote display station
controllers).
For local display stations, a start-of-header order length greater than 11 causes
the negative response hex 1005012B to be sent. No negative response is sent
for remote display stations.

For local display stations, do not accept more than four field control words for
each input-field definition. More than four causes the negative response hex
10050130 to be sent. No negative response is sent for remote display stations.
For local display stations, self-check fields can be as long as 33 bytes for
signed numeric fields and 32 bytes for all other fields. If the length is
exceeded, the status response hex 00000287 is sent to the user when he or
she tries to exit the self-check field. For remote display stations, all fields can
be 33 bytes.
Two forms of the Request Maintenance Statistics command are supported for
remote display stations: (1) requests that the error log area be reset, and (2)
requests that the error log area not be reset. For local display stations, the
error log area is always reset.
Understanding User-Defined Data Stream Limitations

The output record area for a user-defined record format must contain the following
in the order specified:
1. Display-station-specific information (required by the system), which causes the
system to send the display-station-specific data stream to the display station.
2. Display-station-specific data stream, which is sent to the display station.
The USRDFN keyword is specified at the record format level and excludes for that
record format most other functions such as the use of indicators and all field-related
functions. However, the display file can contain other record formats not containing
the USRDFN keyword, and the record formats can be used in any order by a
program. When you use such a display file, you should be aware of the following:
When the system write routine recognizes a user-defined request, it disregards
all previous requests to the display. At the completion of the user-defined
request, the system assumes that a single record format is on the screen and
that this is the record format containing the USRDFN keyword. All erasing, all
resetting, and unlocking of the keyboard is your responsibility. The next I/O
request can be another user-defined request or a normal field-level request.
A normal field-level request after a user-defined request is handled as follows:
– If the OVERLAY keyword is not specified, the screen is erased before the
request is run.
– If the OVERLAY keyword is specified, only the portion of the display
needed (entire lines) is erased.
– The 5250 format buffer is reset, which means that all input fields are
changed to output-only fields.
The system assumes that only this record format exists on the screen. All pre-
vious requests are disregarded.
Help specifications are allowed in user-defined record formats.
When the USRDFN keyword is specified in a record format, no fields can be
defined for that record format. The only valid keywords are:
File Level Record Format Level

KEEP ALTNAME
OPENPRT HELP

File Level Record Format Level
PASSRCD HLPCLR
PRINT HLPRTN
INVITE
PRINT
TEXT
The user-defined data stream can alter the CFnn and CAnn keys and the
location of the message line in the display. However, display station support
assumes they are the same as when they were last set.
All display files that contain user-defined data streams should be opened as
both input and output files. This is because read and write commands in the
data stream are not dependent on write and read requests.
The output data stream should start with an escape character hex 04 and be fol-
lowed by a clear unit hex 40 or write to display command hex 11.
The output buffer must include information needed to send and receive the appro-
priate line controls. The buffer format for a 5250 display station is:
Byte Contents
0-1 Send data length (in hexadecimal), defines the output data
stream length
2-3 Receive data length (in hexadecimal), defines the maximum
input data length
4 Requested function
Hex 51 Send (WP mode)
Hex 53 Send/Receive (WP mode)
Hex 61 Send (3270 data stream)
Hex 63 Send/Receive (3270 data stream)
Hex 71 Send
Hex 73 Send/Receive
5-n Output data stream
The 3270 Model 4 display station supports a display size of 43 lines by 80

columns. If you have a 3270 Model 4 display station, you can use function
codes 61 and 63 to write to all 43 lines.
For 3270 Model 4 display stations that are using function code 61 or 63, the
system displays status messages on line 43. Any data that is on line 43 when
a status message is displayed is replaced by the status message.
If you are using function code 61 or 63 and press the key that is defined as the
System Request key, the key is returned to the application program instead of
displaying the System Request menu. If you need access to the system
request function when using function code 61 or 63, you can define the Atten-
tion key to display the System Request menu. Before starting the application
that uses function codes 61 and 63, specify:
SETATNPGM SET(\ON) PGM(QSYS/QWSSYSRQ)
When the Attention key is pressed, the System Request menu is displayed.
Chapter 10. Using User-Defined Data Streams 10-3

This support prohibits the use of a read operation except after a write-read(nowait)
operation. A write-read operation that sends a read command and specifies the
receive data length performs the operation normally performed with a read request.
The write-read function can be performed by doing one of the following:
Control
Operation ILE RPG ILE COBOL Language
SNDRCVF
Write-read(wait) EXFMT WAIT(*YES)
WRITE with WRITE with
INVITE, INVITE, SNDRCVF
Write-read(nowait) READ READ WAIT(*NO)
Both the write-read(wait) and the write-read(nowait) operations are a combination of

a write operation and a read operation to the same record format. When using the
write-read(wait) operation, control does not return to the program until input is
received from the display device. The write-read(nowait) operation is used to send
a request for input to a display device and return to the program without waiting for
the input to arrive. This allows a program to request input from one or more
devices, and continue processing without waiting for any of the devices to respond.
For each I/O request, you must make sure that the function byte and the send
depth actually reflect the data stream sent. The receive length must be long
enough to accommodate all data returned by the display station. If any of these is
wrong, unexpected or unacceptable functions may happen. For example, if the
function byte indicates a send to the display station and the data stream specifies a
read modified command, the system sends the data stream to the display station
and no read is performed.
On input operations, the input buffer of the program contains the data received from
the display station. For example, when a read modified completes, the input buffer
contains an aid identification (AID) byte and the cursor address followed by each
changed field. Each changed field is preceded by the buffer address order and
field location on the screen.
All AID bytes are accepted by display station support for user-defined data streams.
If the Print key is pressed, the system attempts to perform the print function.
All write and write-read operations must specify the record format name. A read
operation that specifies the name of a record format that contains the USRDFN
keyword and is not one of the appropriate read operations for the display station
causes an exception to be issued.
Each request to a 5250 display station can contain more than one command. Each
command must be requested using the appropriate system operation identified as
follows:

Output Output
Buffer Buffer
Send Receive
Length Length Output Buffer
(Bytes (Bytes Request Func- Output Buffer Command
Operation 0–1) 2–3) tion (Byte 4) (Bytes 5–n)
Write nn 0 71 (Send) Clear unit
Clear format table
Write to display
Write error line
Restore
Roll
Copy
Write- nn nn 73 (Send/Receive) Clear unit
Read Clear format table
Write to display
Write error line
Restore
Roll
Read input fields
Read MDT fields
Read immediate
Save
Chapter 10. Using User-Defined Data Streams 10-5

Chapter 11. Passing Data between Programs
You can use the system I/O operations to pass data between programs both in the
same routing step of a job or across routing steps.
Passing Data in the Same Routing Step in a Job

To pass data between programs in the same routing step, you can either share the
file between the programs, or you can use the KEEP and ASSUME DDS keywords
to share a file between programs. The programs must open the same file and the
file must be designated as a shared file. (See “Sharing Display Files in the Same
Job” on page 3-50.) Because the programs share the file, the read operations are
performed as described under “Reading Input from the Display” on page 3-33 and
“Understanding How the System Reads Input from the Display” on page 3-40.
You can also use the KEEP and ASSUME keywords to pass data between pro-
grams. The data is written to the display by the first program, and used from the
display by the second.
You can use the KEEP keyword to keep data on the display for review after the
program has ended, or you can use it to pass data between programs.
Normally, when a file is closed, the current display is cleared. However, you can
control this by using the KEEP keyword. If a record that is on the display when the
file is closed has the KEEP keyword specified, the system saves the name of the
first such record to support passing data. Using this keyword alone, you cannot
support processing of passed data, you must also use the ASSUME keyword in the
display file opened by the next program.
The ASSUME keyword causes a read operation to a specific record format name to
be valid when no preceding write operation to that record format name (or any
other record format) has occurred since the display file was opened. The following
shows a typical example of what happens when the ASSUME keyword is specified:
1. Program PGM1 issues a write operation to the record format PGM1ANY in the
display file DSPFIL1 and calls program PGM2. PGM1ANY specifies the LOCK
keyword.
2. PGM2 opens DSPFIL2 and issues a read operation to record format
PGM2ANY. The ASSUME keyword is specified. Input data is read from the
display and processed by record format PGM2ANY.
Records from record formats having the ASSUME keyword specified cannot overlay
one another on the display. In addition, all records must have at least one field that
is displayed.
When the system reads assumed records from the display, only fields whose modi-
fied data tags (MDTs) are on are returned. (This assumes that either the
DSPATR(MDT) keyword was specified for the field on the last output operation or
the user has typed in the field.) When the ASSUME keyword is in effect, the data
returned to the program is as follows:
For input-only and output/input fields with their MDTs on, the changed data is
returned.

For other input-capable fields, blanks are returned for character fields and
zeros are returned for numeric fields.
In addition, only those fields received whose line and position on the display match
the field of an assumed record are processed. The data is processed using the
field descriptions in the assumed record, independent of how the fields were written
to the display.
For the 5250 display station, the first write operation or write-read operation after
the file is opened sends a CA and CFnn key specification to the display station.
Because there is no write operation after an open when using the ASSUME
keyword, the CFnnkey specification remains as it was left by the last application.
The CA and CFnnkey specification in this file will not be used until after the first
write operation to the file.
After the file is opened and the first write operation is issued, the display will be
erased if the OVERLAY keyword is not specified. When the OVERLAY keyword is
specified, all input-capable fields on the display become output-only fields. After
the first write operation, assumed records cannot be read by a program.
Fields not received from the assumed records on the display are returned to the
user program as follows:
Field Initialized To
Field with DFT keyword used Value specified in DFT keyword
Character field (no DFT keyword) Blanks
Numeric field (no DFT keyword) Zero
Hidden field Zero

Passing Data between Routing Steps in a Job
The following example shows the steps used in passing display data between pro-
grams in different routing steps. Note the use of the KEEP, ASSUME, and
PASSRCD keywords. Programs PGM1 and PGM2 are user programs started by
the subsystem SBS using different routing entries. PGM1 and PGM2 run in dif-
ferent routing steps but are both contained in the job 000618/QUSER/WSN01.
Subsystem
OOO618/QUSER/WSN01
Routing Routing
Step Step
Program Display File Program Display File

PGM1 DSPFIL1 PGM2 DSPFIL2
Open DSPFIL1 Open DSPFIL2

Read ...
Write PGM2RD Close DSPFIL2 R PGM2ANY

Close DSPFIL1
R PGM2RD R PGM2RD
RV2W044-2
.1/ The user signs on and SBS starts a routing step based on the routing data.
The first program in the routing step is PGM1.
.2/ PGM1 opens the display file DSPFIL1.
.3/ PGM1 interacts with the user and issues the following before ending:
A write operation to DSPFIL1 with the record format name PGM2RD. The
KEEP keyword is specified in the record format PGM2RD.
Chapter 11. Passing Data between Programs 11-3

A close operation to DSPFIL1. The information displayed on WSN01 is
not cleared because the KEEP keyword is specified in record format
PGM2RD.
PGM1 then ends by issuing a RRTJOB command specifying routing data that
will cause SBS to call PGM2.
.4/ SBS starts a new routing step based on the data supplied by PGM1 in the
RRTJOB command.
.5/ PGM2 opens the display file DSPFIL2.
.6/ PGM2 performs a read operation to DSPFIL2 with or without the record format
name PGM2ANY. If the record format name is not specified, the system tries
to use the record format PGM2RD to process the data because the KEEP
keyword was specified (in step 5). To do so, record format PGM2RD must
exist in DSPFIL2, but it does not have to be identical to record format
PGM2RD in DSPFIL1; only the fields that are required by PGM2 must be iden-
tical. (If a field is returned from the display station for which no field
description exists in PGM2ANY, the field is ignored. If the field description
requires validation and the data received fails the validity check, PGM2 reis-
sues a read operation to allow the current user to correct the data.) If a record
format is not specified or if record format PGM2RD does not exist in DPSFIL2
or does not have the ASSUME keyword specified, the data passed to the
display station via the KEEP keyword cannot be processed. (The ASSUME
keyword must be specified for the record format used to process passed data.)
.7/ PGM2 processes the data and issues a close operation to DSPFIL2, which
clears the display.
When PGM2 ends, its routing step ends and the display returns to the control
of SBS which shows the sign-on display.

Chapter 12. Waiting for Input from a Display File, an ICF File,
and a Data Queue
You can use data queues for a program that waits for data on a display file, an ICF
file, and a data queue at the same time (in any combination). When you specify
the DTAQ parameter for the following commands:
Create Display File (CRTDSPF) command
Change Display File (CHGDSPF) command
Override with Display File (OVRDSPF) command
Create ICF File (CRTICFF) command
Change ICF File (CHGICFF) command
Override ICF File (OVRICFF) command
you can indicate a data queue that will have entries placed on it when any of the
following occurs:
An enabled command key or Enter key is pressed from an invited display
station.
Data becomes available from an invited ICF session.
By using the IBM-supplied QSNDDTAQ program, jobs running on the system can
also place entries on the same data queue as the one specified in the DTAQ
parameter.
An application program uses the IBM-supplied QRCVDTAQ program to receive

each entry placed on the data queue and then processes the entry based on
whether it was placed there by a display file, by an ICF file, or by the QSNDDTAQ
program. For a display file, the application then issues a read or read-from-invited
devices operation to receive the data. For more information on the QRCVDTAQ
function and syntax, and examples of waiting on one or more files and a data
queue, refer to the CL Programming book.
The display file and ICF file entry that is put on the data queue is 80 characters
long and contains the field attributes described in Table 12-1. Therefore, the data
queue that is specified using the commands listed above must have a length of at
least 80 characters.
Entries placed on the data queue by jobs using QSNDDTAQ are defined by the
user.
Table 12-1 (Page 1 of 2). Display File and ICF File Entry Field Attributes
Position Data Type Meaning
1 through 10 Character The type of file that placed the entry on the data
queue. This field will have one of two values:
*ICFF (ICF file)
*DSPF (display file)
If the job receiving the data from the data queue has
only one display file or one ICF file open, then this is
the only field that needs to be used to determine
what type of entry has been received from the data
queue.

Table 12-1 (Page 2 of 2). Display File and ICF File Entry Field Attributes
Position Data Type Meaning
11 through 12 Binary Unique identifier for the file. The value of the identi-
fier is the same as the value in the open feedback
area for the file. This field should be used by the
program receiving the entry from the data queue
only if more than one file with the same name is
placing entries on the data queue.
13 through 22 Character The name of the display or ICF file. This is the
name of the file actually opened, after all overrides
have been processed, and is the same as the file
name found in the open feedback area for the file.
This field should be used by the program receiving
the entry from the data queue only if more than one
display file or ICF file is placing entries on the data
queue.
23 through 32 Character The library where the file is located. This is the
name of the library, after all overrides have been
processed, and is the same as the library name
found in the open feedback area for the file. This
field should be used by the program receiving the
entry from the data queue only if more than one
display file or ICF file is placing entries on the data
queue.
33 through 42 Character The program device name, after all overrides have
been processed. This name is the same as that
found in the program device definition list of the
open feedback area. For file type *DSPF, this is the
name of the display station where the command or
Enter key was pressed. For file type *ICFF, this is
the name of the program device where data is avail-
able. This field should be used by the program
receiving the entry from the data queue only if the
file that placed the entry on the data queue has
more than one device or session invited prior to
receiving the data queue entry.
43 through 80 Character Reserved

Chapter 13. Using Alternative Character Sets and Code
Pages
In multinational environments, data in one national character set may need to be
displayed or entered on display stations that support another national character set.
This is particularly true of characters with accents and other characters with
diacritical marks (such as c with a cedilla, n with a tilde, and u with an umlaut). In
this section, these characters are called extended alphabetics.
For example, assume that a physical file on the system contains data in the Basic
French code page, and includes an é (e with an acute accent). In the Basic French
character set, this character is hex C0. The data could have been entered on a
display station that can handle the character or could have been sent to this system
from another system over a communications line.
Note: On some display stations, extended alphabetics can be entered on the key-
board (by pressing Cmd, then the key to its right with two diacritical marks
on it, then the 2 hexadecimal digits that represent that character).
Display
Station Physical File
Containing
Hex C0 (e)
RV2W036-3
When the hex C0 is sent to a display station that does not recognize hex C0 as é,
the hex C0 is not displayed as é. For example, a display station that recognizes
the U.S. code page displays hex C0 as { (a left brace). The é is at code point 51 in
the U.S. code page. To properly display é, the hex C0 must be converted to hex
51 for display on a U.S. basic display station.
With the IBM-supplied conversion tables, the system can convert most extended
alphabetics, but not all. If an extended alphabetic character does not have a
clearly preferable equivalent, the system converts the character to a (-) hyphen.
System Has Characters Not Normally Displayed on the Device: The case of an
output/input field shows how character conversion occurs at a display station.
Display
Application File Display
Physical
Program Station
File
Read Write Renee

Renee Renee
Renee
RV2W037-3
Assume that a record in a physical file contains a field with the value Renée. An
application program reads the record from the physical file, and writes a record
containing the data to the display file. One way to achieve character conversion is

in the DDS for the display file, the output/input field in which Renée appears has
the Character Identifier (CHRID) keyword specified.1 This keyword asks the system
to perform character conversion if needed. Character conversion is needed if the
CHRID parameter value for the display file differs from the CHRID value of the
display station. In this case, character translation is needed because the display
file has CHRID(288 297), which is the basic French code page and character set,
and the device description has CHRID(101 37), which is the basic U.S. code page
and character set.
When displaying the data, the system converts the hex C0 to hex 51, and Renée
appears on the display. If no conversion occurred, Ren{e would appear on the
screen.
On input, one of the following occurs:

If the modified data tag (MDT) is turned on for the field (this happens when the
user types into the field or if the DSPATR(MDT) keyword is in effect for the
field) the contents of the field are converted from the device CHRID to the
CHRID parameter value specified on the Display File (DSPF) command and is
returned to the program.
If the modified data tag (MDT) is not turned on for the field, the saved contents
of the field (with original, untranslated, data) is returned to the program.
Another way to achieve character conversion on a file basis is to specify the

*JOBCCSID value on the CHRID parameter for the Create Display File
(CRTDSPF), the Change Display File (CHGDSPF), or the Override Display File
(OVRDPSF) commands. More information about *JOBCCSID is in “Specifying
Character Translation for Fields”
Device Passes Characters Not Displayed on the System: If the user can enter
data not normally displayed on the system (for instance, a user on a French-
language display station in Montreal dials up a remote line to a system in Toronto
with display stations that cannot display extended alphabetics), no change occurs
when the data is sent to the system. The program can read data from the French-
language display station and write it to a physical file. However, when another user
on the Toronto system displays data from the physical file, the system attempts to
translate the data for the display station that cannot display extended alphabetics.
Specifying Character Translation for Fields

If the CHRID keyword is specified on a field, character conversion occurs only if the
CHRID parameter value in the display file is different from the CHRID value in the
device description.
1. The CHRID parameter on the display file is set by the CHRID parameter on the
CRTDSPF, CHGDSPF, or OVRDSPF command. The CHRID parameter can
have one of the following values:
1 If *JOBCCSID is specified by the CHRID parameter on the CRTDSPF, CHGDSPF, or OVRDSPF commands, the DDS keyword
CHRID is ignored. For more information, see the description for *JOBCCSID in “Specifying Character Translation for Fields” on
page 13-2.

*DEVD (the default): Use the CHRID parameter specified on the device
description on which the application is currently running. No character con-
version occurs. Any CHRID keywords specified in the DDS are ignored.
*SYSVAL: Use the character set and code page specified in the system
value QCHRID on which the application is currently running. Specify the
CHRID keyword in the DDS for the display file fields that will need conver-
sion. Constants are not converted.
*JOBCCSID: Use the character set and code page specified by the job.
This allows named fields and unnamed (constant) fields to be automatically
translated when the job CCSID or the display file CCSID does not match
the device description CHRID. If the job CCSID does not match the device
description CHRID, named fields are translated from the job CCSID to the
device description CHRID on output and conversely on input. If the display
file CCSID does not match the device description CHRID, data in the
display file is translated from the display file CCSID to the device
description CHRID on output. When *JOBCCSID is specified, the DDS
CHRID keyword is ignored. Use the No Coded Character Set Identifier
(NOCCSID) keyword on named and unnamed fields that you do not want
translated.
Character set and code page: Use the character set and code page speci-
fied. See Table 13-1 on page 13-5 for the list of valid values.
2. The CHRID value on the device description is set by the CHRID parameter on
the Create Device Description Display (CRTDEVDSP) or Change Device
Description Display (CHGDEVDSP) command. This parameter can have one
of the following values:
*SYSVAL: Use the character set and code page specified in the system
value QCHRID.
*KBDTYPE: Use the character set and code page specified in the key-
board language prompt (KBDTYPE). This value corresponds to the country
keyboard language identifier.
Character set and code page: Use the character set and code page speci-
fied. See Table 13-1 on page 13-5 for the list of valid values.
When dealing with UCS-2 Level 1 data from a physical file, it will be necessary to
convert this data to EBCDIC before displaying the data on the screen. To accom-
plish this conversion, place the DDS CCSID keyword at either the file-, record-, or
field-level to enable conversion of UCS-2 data from the UCS-2 CCSID value speci-
fied with the keyword to the device CHRID on output. On input, the data is con-
verted from the device CHRID to the UCS-2 value. For more information, see
“UCS-2 Level 1 Considerations for DDS” in the DDS Reference book.
Another conversion that occurs every time data is displayed is converting the hex
“3F” character to the hex “1F” character on output and conversely on input. The
Character Data Representation Architecture (CDRA) specifies the hex “3F” char-
acter as a replacement character. This character is also a field attribute definition
for the 5250 data stream specification. Translation to convert hex “3F” character to
hex “1F” character for output is done for all fields whether *JOBCCSID translation is
active or inactive. Use the NOCCSID keyword to prevent translation at the field
level.
Chapter 13. Using Alternative Character Sets and Code Pages 13-3
When character conversions are necessary, the system uses a conversion table in
library QUSRSYS to convert the data. The name of the conversion table used is
derived from parts of the source and target CCSID for which the table is needed as
shown in the following example:
On Output:
Display File Device Description
CHRID(101 037)
CHRID(288 297)
Translation Table Used: Q297101037
On Input:
Display File Device Description
CHRID(101 037)
CHRID(288 297)
Translation Table Used: Q037288297
RV2W038-3
IBM supplies a number of tables in library QUSRSYS to handle conversion among

the most frequently used combinations of character sets and code pages. If you
need to tailor the way characters are converted, you can create your own table in
library QUSRSYS, using the Create Table (CRTTBL) command to do the conver-
sion. To determine what conversion tables are available to use, look in the
QUSRSYS library for object type *TBL.
Determining the Character Identifier (CHRID) Value for Your Display

The CHRID value specified should be based on the attributes of the display station.
The table below shows CHRID values that are appropriate for each display station
keyboard type. For some display stations, you do not need to specify the
KBDTYPE parameter, but the KBDTYPE value for the equivalent keyboard can be
used to determine the CHRID value for the display station:

Table 13-1. CHRID Values
Limited
Language/Country Keyboard Type (KBDTYPE) CHRID Full CHRID
International and US ASCII INB 103 038 697 500
Multinational AGI BLI CAI DMI FAI FNI FQI ICI INI 697 500
ITI JEI NEI NWI PRI SFI SGI SPI SSI
SWI UKI USI
Arabic CLB 235 420
Austria/Germany AGB 265 273 697 273
Belgium Multinational BLI 697 500
Canada/French CAB 277 260 341 260
Cyrillic CYB 960 880
Denmark/Norway DMB NWB 281 277 697 277
Finland/Sweden FNB SWB 285 278 697 278
France FAB FQB 288 297 697 297
Greece GKB 218 423
Hebrew NCB 941 424
Iceland ICB 697 871
Italy ITB 293 280 697 280
Japan/English JEB 297 281 697 281
Japan/Kanji JKB (For Personal System/55*, 5295 and 332 290
3477-J display stations)
Japan/Katakana KAB (For 5251, 5291, 5292, and 3180 332 290
Katakana display stations)
Korean KOB 933 833
Latin 2 ROB 959 870
Netherlands NEB 697 037
Portugal PRB 301 037 697 037
Simplified Chinese RCB 936 836
Spain SPB 305 284 697 284
Spanish Speaking SSB 309 284 697 284
Switzerland/French Multinational SFI 697 500
Switzerland/German Multinational SGI 697 500
Thai THB 938 838
Traditional Chinese TAB 101 037
Turkey TKB 965 905
United Kingdom/English UKB 313 285 697 285
United States/English USB 101 037 697 037
Countries of the former Yugoslavia YGI 959 870
Chapter 13. Using Alternative Character Sets and Code Pages 13-5
Chapter 14. Improving System Performance with Displays
System performance is improved by doing the following:
Minimizing the number of bytes sent and received when designing a display.
For example, to reduce the number of fields on an application display:
– Split a display with many fields into more than one display.
– Consider removing fields which were added to help with development,
testing, or problem reporting.
Taking advantage of the system functions that reduce the number of bytes sent
to and received from the display station. This chapter describes some of these
system functions.
Deferring the Write Operation for a Display File

The DFRWRT parameter on the Create Display File (CRTDSPF) or Change
Display File (CHGDSPF) command allows you to delay the writing of data to the
display until needed. Deferring the write operation is useful when the final display
shown at the display station is formed by several record formats being written to
the display.
Using DFRWRT(*YES) on a display file improves systems performance in some

cases.
More information on the Defer Write parameter can be found in “Deferring the Write
Operation Until a Read Request is Made” on page 3-26.
Designating the Primary Screen Size for a Display File

Normally, the display files are set up for a 24 by 80 screen (default size). The
DSPSIZ keyword specifies which display sizes are valid for a file and indicates
which sizes are the primary and secondary screen sizes. (The primary screen size
is the first or only DSPSIZ value.) On the DSPSIZ keyword, the screen size can be
specified as *DS3, *DS4, 24 80, or 27 132. For example, DSPSIZ (24 80) specifies
a screen size of 24 by 80.
The screen size designated as the primary screen size should be the one with
which the display file will most often be used. A performance benefit will be real-
ized by coding the DSPSIZ keyword in this manner. Additional processing is per-
formed when the actual screen size is the secondary screen size.
Writing Only One Page of Subfile Records at a Time

A technique to improve performance when you are using a multiple page subfile is
to write only one page of subfile records at a time but use the OS/400 support to
roll through the subfile. To do this, you need to define the ROLLUP keyword in
DDS with a response indicator and also use the SFLRCDNBR keyword. In your
program, you would write the records needed to fill one subfile page and then
display that page. When the user wants to see more records, he or she presses
the Roll Up key. The program then writes another page of records to the subfile,

places the relative record number of a record from the second page into the
SFLRCDNBR field, and displays the record.
The second page of subfile records is now displayed, and if the user presses the
Roll Down key, the roll down is handled by the system. If the user presses the Roll
Up key while the first page is displayed, the system will also handle the roll up.
The program is notified only when the user attempts to roll up beyond the records
currently in the subfile. The program would then handle any additional roll up
requests in the same manner as for the second page. When you use this tech-
nique, the subfile appears to be more than one page because of the use of the roll
keys. Yet, you can maintain good response time because the program only fills
one subfile page before writing it to the display.
Sharing an Open Data Path (ODP) for the Same Job

OS/400 data management support offers a close level of sharing within a job that
allows more than one program to share the same path to the data or display
station. By specifying *YES for the SHARE parameter on the Create Display File
(CRTDSPF) command, the Change Display File (CHGDSPF) command, and the
override file commands, more than one program can share the file status, positions,
and storage area. Performance is improved by reducing the amount of main
storage the job needs and the time it takes to open and close the file.
Note: To use SHARE(*YES) to improve performance, you need to define many
record formats within the display file. However, the program may not use
all the record formats in the display file, even though the program has work
storage allocated for all the record formats defined in the display file. This
causes the PAG storage associated with the job to be larger, which can
adversely affect performance.
More information about sharing open data paths is found in “Sharing Display Files
in the Same Job” on page 3-50.
Sending Records with Input Fields to the Display in Order

Records containing input fields should be sent to the display station in the order in
which they appear on the display. This technique provides better performance than
if record formats with input fields are sent randomly or in some other order.
Overlapping and Not Deleting Repeatedly Sent Records

You can use the CLRL(*NO) keyword to prevent an overlapped record from being
deleted when the overlapping record is written to the display. If you use this
keyword, any records being displayed that are to be overlapped are not deleted
from the screen; the new record overlays them entirely or partially. There is a per-
formance advantage to using CLRL(*NO) if you have a display that contains con-
stants and data that is repeatedly sent to the screen. By sending the constants as
a separate format and using CLRL(*NO) for the format containing only the data,
you can reduce the time required to send the record format to the display.
The use of the PUTOVR keyword causes only those fields for which the OVRDTA
or OVRATR keyword have been specified to be sent to the display when a subse-
quent write or write-read operation is issued to the same record format.

You can also use the OVERLAY keyword to clear only that portion of the display
affected by the record format being written.
You can use ERASEINP to improve response time by causing the display to clear
fields instead of requiring blanks to be sent to the display. If the fields erased at
the display do not have their modified data tags set on for the next read operation,
data is returned for those fields from the input save area. This is data saved by the
system from the previous return of the field from the display station.
You can use the INZINP keyword at the record level with ERASEINP(*ALL) and
PUTOVR to initialize the input save area without sending data for the cleared fields
to the display.
Restoring the Display

When *YES is specified for the Restore Display (RSTDSP) parameter, an image of
the current display is saved when the display is suspended. When the display file
is activated again, the saved image is used to restore the display to its appearance
before being suspended.
The RSTDSP(*YES) parameter must be specified for the following keywords. If the
parameter is not specified, data on the display can be lost if the file is suspended.
CLRL
OVERLAY
PUTOVR
PUTRETAIN
ERRMSG
ERRMSGID
If none of the previous keywords are used, you can improve performance by speci-
fying *NO for the RSTDSP parameter.
Defining Command Attention Keys Rather Than Command Function

Keys
Command attention (CAnn) keys return only the indication of the key pressed and
not data. Command function (CFnn) keys cause all input data to be returned. If
you only need to detect a function key and do not need to return data from the
display, define keys as command attention keys.
Using the Invite Operation

The invite operation, specified by the INVITE keyword, allows the program to be
responsive to various display station and system events. The invite operation also
allows the program to process between the last WRITE and READ operations.
Chapter 14. Improving System Performance with Displays 14-3

Using Windows
DDS-described windows may improve performance because they only affect the
portion of the display where they are placed.

Part 3. Programming Application Displays Using Panel
Groups
Chapter 15. Improving Productivity with User Interface Manager . . . . 15-1
Increasing User Productivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1
Increasing Application Programmer Productivity . . . . . . . . . . . . . . . . . 15-1
Specifications (DDS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1
Chapter 16. Introduction to the User Interface Manager . . . . . . . . . . 16-1

Overview of UIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1
What the UIM Supports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2
What Is a Panel Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2
What Is a Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2
Creating Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-3
Elements Within a Panel Group . . . . . . . . . . . . . . . . . . . . . . . . . . 16-3
Using the UIM Language Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-4
Using Dialog Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-4
Using Control Language (CL) Commands . . . . . . . . . . . . . . . . . . . . 16-5
Using an Application Programming Interface (API) . . . . . . . . . . . . . . . 16-5
Defining a Menu Object Using UIM . . . . . . . . . . . . . . . . . . . . . . . . 16-6
Creating a Menu Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-6
Required Tags for a Menu Panel . . . . . . . . . . . . . . . . . . . . . . . . 16-8
Source for Example Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-9
Defining a Panel Group Object Using UIM . . . . . . . . . . . . . . . . . . . 16-13
Creating a List Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-13
Required Tags for a List Panel . . . . . . . . . . . . . . . . . . . . . . . . 16-16
Source for Example List Panel . . . . . . . . . . . . . . . . . . . . . . . . 16-17
Application Programming for a List Panel . . . . . . . . . . . . . . . . . . 16-25
Creating a Confirmation List Panel . . . . . . . . . . . . . . . . . . . . . . . . 16-27
Required Tags for a Confirmation List Panel . . . . . . . . . . . . . . . . 16-28
Source for Example Confirmation Panel . . . . . . . . . . . . . . . . . . . 16-28
Automatic Confirmation Processing . . . . . . . . . . . . . . . . . . . . . . 16-31
Application Programming for Confirmation Processing . . . . . . . . . . . 16-31
Creating a Data Presentation Panel . . . . . . . . . . . . . . . . . . . . . . . 16-32
Required Tags for a Data Presentation Panel . . . . . . . . . . . . . . . . 16-34
Source for Example Data Presentation Panel . . . . . . . . . . . . . . . . 16-35
Application Programming for a Data Presentation Panel . . . . . . . . . . 16-46
Data Entry Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-49
Creating a Panel with a Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . 16-50
Required Tags for a Panel with a Menu Bar . . . . . . . . . . . . . . . . . 16-52
Source for Example Panel with a Menu Bar . . . . . . . . . . . . . . . . . 16-53
Application Programming for a Menu Bar Panel . . . . . . . . . . . . . . 16-63
Chapter 17. Details of Using User Interface Manager . . . . . . . . . . . . 17-1

Opening a UIM Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1
Defining Dialog Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1
Restrictions on Using Dialog Variables . . . . . . . . . . . . . . . . . . . . . 17-3
Dialog Variable Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . 17-3
Providing Field Values for a Display Panel Using Dialog Variables . . . . 17-4
Using Variable Pool Services . . . . . . . . . . . . . . . . . . . . . . . . . . 17-4
Character Set and Code Page Considerations . . . . . . . . . . . . . . . . 17-5

Displaying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-5
Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-6
Managing a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-7
Defining a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-8
Initializing a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-8
Displaying a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-8
Updating a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-9
Incomplete List Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-9
Removing and Inserting an Entry from a List . . . . . . . . . . . . . . . . 17-10
Controlling List Entries on a List Display . . . . . . . . . . . . . . . . . . . 17-10
Improving Interactive Response Time for a List Display . . . . . . . . . . 17-11
Using Action Lists and Selection Lists . . . . . . . . . . . . . . . . . . . . 17-11
Using Action Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-11
Using Selection Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-12
Using Selection Characters . . . . . . . . . . . . . . . . . . . . . . . . . . 17-13
Managing Panel Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-13
Enabling Conversion to a GUI . . . . . . . . . . . . . . . . . . . . . . . . . . 17-14
Scrolling Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-14
Defining Scrollable Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-14
Defining Function Key Scrolling . . . . . . . . . . . . . . . . . . . . . . . . 17-15
Scrolling and Error Conditions . . . . . . . . . . . . . . . . . . . . . . . . . 17-15
Scrolling a List Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-15
Scrolling a Menu Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-16
Scrolling an Information Area . . . . . . . . . . . . . . . . . . . . . . . . . 17-16
Scrolling Data Item Groups . . . . . . . . . . . . . . . . . . . . . . . . . . 17-16
Scrolling a Text Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-16
Defining Contextual Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-16
Command Line Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-19
Command Line Interpretation . . . . . . . . . . . . . . . . . . . . . . . . . 17-19
Entering Commands That Are Too Long . . . . . . . . . . . . . . . . . . . 17-20
Formatting Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-20
Handling Function Keys and VARUPD Value . . . . . . . . . . . . . . . . 17-21
Panel Formatting Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-22
When Panel Formatting Is Performed . . . . . . . . . . . . . . . . . . . . 17-22
Application Control of Panel Formatting . . . . . . . . . . . . . . . . . . . 17-23
Limits of the Panel Formatter . . . . . . . . . . . . . . . . . . . . . . . . . 17-24
Folding Up Multiple Panels When EXIT Is Requested . . . . . . . . . . . . . 17-24
Folding Up a List Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-26
Adding a Pop-Up Window over Another Panel . . . . . . . . . . . . . . . 17-27
Using Menu Bars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-27
Differences Between Pull-Down Menus and Pop-Up Windows . . . . . . 17-28
Using Pop-Up Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-30
Defining Application Windows . . . . . . . . . . . . . . . . . . . . . . . . . 17-30
Adding and Removing Windows . . . . . . . . . . . . . . . . . . . . . . . 17-31
Using the Command Line in a Window . . . . . . . . . . . . . . . . . . . . 17-32
UIM as a Request Processor Program When Displaying a Panel . . . . . . 17-33
Printing Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-33
Printing a Print Head Panel . . . . . . . . . . . . . . . . . . . . . . . . . . 17-35
Printing a Print Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-35
Using Blank Lines for Separating . . . . . . . . . . . . . . . . . . . . . . . 17-36
Fonts and Highlighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-36
Printing the Trailer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-36
Defining Prolog Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-36

Defining Header Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-36
Using the Page-Eject Function During Printing . . . . . . . . . . . . . . . 17-37
Sharing and Overriding Printer Files . . . . . . . . . . . . . . . . . . . . . 17-37
Printing Double-Byte Character Set (DBCS) Considerations . . . . . . . 17-37
Commonly Asked UIM Questions . . . . . . . . . . . . . . . . . . . . . . . 17-37
Part 3. Programming Application Displays Using Panel Groups

Chapter 15. Improving Productivity with User Interface
Manager
Using the user interface manager (UIM) can improve user and application pro-
grammer productivity.
Increasing User Productivity

The UIM controls the panel's appearance and assures consistency with panels
developed by IBM. This gives an application a consistent user interface which
increases user productivity.
Increasing Application Programmer Productivity

Application programmer productivity is increased by using the UIM to create panels.
The application programmer can describe the contents of a panel without specifying
all the details. The format of the panel's elements is handled automatically by the
UIM. For more information on the panel elements that UIM handles, see “What the
UIM Supports” on page 16-2.
Using the UIM language tags allows the application programmer to "link" an option
number or function key to a specific command or program. Then, when a user
selects an option or presses a function key, the UIM automatically handles running
the command or program. The UIM also handles scrolling through a multiple-page
panel. The Major Command Groups menu is an example of a multiple-page panel.

Specifications (DDS)
The UIM and DDS each use a different source language to create interactive dis-
plays. Display functions in interactive applications can be built using DDS, a com-
bination of DDS and UIM, or only UIM. With DDS, the application programmer can
customize display screens, and with UIM, the display screens are automatically for-
matted resulting in a consistent appearance. In addition, the UIM performs more
dialog management functions than DDS, so using UIM results in less application
programming.
The UIM supports the following types of display screens (or panels). Each one can
be scrollable or nonscrollable:
List
Menu
Information
Data entry
For more information on creating these display screens, see Chapter 16, “Introduc-
tion to the User Interface Manager” on page 16-1.
Consider the following before using UIM:

If you are creating a new application, the UIM simplifies making display screens
standard.

If you are rewriting an old application, evaluate the effort involved to rewrite the
display screens versus the productivity benefits already described. In some
cases, conversion to UIM may not be warranted unless a major redesign or
rewrite of an application is required for other reasons.
Because UIM was designed for 525x nonprogrammable workstations, using
UIM does not appreciably simplify converting an application oriented to a pro-
grammable workstation except by ensuring standard display screens.
If an application program makes extensive use of database files, UIM does not
take advantage of file descriptions the way DDS does.
Using UIM to create data panels should be for low frequency and low volume
output/input. Nonscrollable data entry applications with high frequency and
volume of interactions should consider using display files created from DDS for
the best performance. This is because the UIM does not accept high fre-
quency and high volume keyboard input as quickly as DDS does. That is, the
UIM may not be able to accept keyboard input as quickly as the user can type
it. However, a keyboard with type-ahead function may compensate for this.
The following lists some of the advantages and differences between using UIM or
DDS:
UIM Advantages
– Uses same standards as system so no need to redefine standards. User
applications work the same way as the system panels. UIM formats panels
based on what you want displayed.
– List processing offers ability to process commands, to prompt or call pro-
grams easily from a list panel, to specify programs for UIM to call after
option is selected, and allows more efficient list entry access or update pro-
cessing.
– Operates well with languages that efficiently process structures.
– Provides for more modular programming techniques (one program can
process all incomplete list exit calls, open all applications, and so on).
– Offers ability to condition menu options
– Formats and handles scrolling of large areas without user program inter-
vention (data, list, info, menu, and function key areas, for example).
DDS Advantages
– Provides more flexibility in screen design
– SDA helps in initial formatting
– Ability to use UIM help or help in folders
– Ability to take advantage of GUI windows
– Subfile processing
– Use of EDTCDE and EDTWRD and user-defined editing
– Faster for smaller applications since set-up time is less.
For additional factors to consider when using UIM, see “Choosing between Panel
Groups, Documents, and Records for Help” on page 18-2.

Chapter 16. Introduction to the User Interface Manager
This chapter gives an introduction to the user interface manager (UIM) that IBM
uses to develop the AS/400 panels. It explains what the UIM provides to make
creating and managing panels easy and also gives the panels the look of an
AS/400 panel.
For detailed information on the UIM, see Chapter 17, “Details of Using User Inter-
face Manager” on page 17-1.
For information on using the examples mentioned in this chapter, see source
member T0011INF in source file QATTINFO in library QUSRTOOL.
Overview of UIM
The OS/400 UIM is a part of the system that allows you to define panels and
dialogs for your application and provides the following support:
A tag-based language for describing data and panels.
A compiler to create panel group objects and menu objects using the tag-based
language.
A set of application programming interfaces (APIs) to use as panel group
objects to display and print panels.
The UIM also provides the following functions:
– Dialog commands for screen management
– Contextual online help
– Index search
– Access to InfoSeeker
– Pop-up windows
– Menu bars
– Command line for entering CL commands
– Tailoring of the contents of a panel for different users or environments
– Fast paths through menu networks
– Double-byte character set (DBCS) languages
– Bidirectional (BIDI) language support
– Graphical user interface (GUI) support
– UCS-2 support
UIM supports common panel types, such as menus, information displays, list dis-
plays, and entry displays. When all display types and interfaces are consistent,
users adapt more quickly to new applications.
UIM applications can coexist with and share the requester display device with other
open display files that are not under UIM control. However, a UIM panel and a
DDS-defined record format cannot appear on the display at the same time. When
a UIM panel replaces a DDS panel or vice versa, the system suspends operations
of one file or panel group and restores the display as needed.

What the UIM Supports
When you design a panel, the UIM provides the correct placement and format of
many panel elements, such as:
Panel name
Panel title
Separator lines
Column headings
Entry fields
Command line
Message line
Function keys
Pop-up windows
Menu bars
Pull-down menus
In addition, the UIM provides the following support:

Correct placement of the cursor
The user interface style has several rules for positioning the cursor which UIM
supports.
Cursor-sensitive help information
Depending on where the cursor is located when the Help key is pressed, the
user interface style has rules for what type of help information is displayed.
Scrolling
Fast paths through menu networks
National language considerations to make translating easier
Windows for help information and application panels
132-column panels
Left-to-right and right-to-left (bidirectional) national language formatting
Hypertext links
Control over left-to-right and right-to-left orientation of text
Ability to create online help information
Ability to enable a panel for conversion to a graphical user interface (GUI)
What Is a Panel Group

A panel is a visual presentation of data on the screen. A panel group is an object
that contains a collection of display formats, print formats, or help information. The
system-recognized identifier for the object type is *PNLGRP.
For detailed information on the panel group (PNLGRP) language tag, see
“PNLGRP (Panel Group)” on page A-139.
What Is a Menu
A menu is an object that contains the definition of a panel which contains one or
more options. The user can select an option from the panel in order to start using
a program or command, or to go to another menu. The system-recognized identi-
fier for the object type is *MENU.

The OS/400 program provides the GO command to display a menu. Therefore, no
application program is necessary to display and handle the user interaction for a
menu.
You can define the following types of menus using the Create Menu (CRTMNU)
command.
*DSPF An existing display file (*DSPF) and message file (*MSGF) are used to
display the menu.
*PGM The OS/400 program calls an application-defined program to display the
menu. The program is responsible for displaying the menu to the user
and processing options requested by the user.
*UIM The menu object is created using a member in a source file that con-
tains a description of the menu. The source describes the menu using
the UIM tags.
This chapter discusses how to create a *UIM type of menu. For information on
how to create a *DSPF or *PGM type of menu, see Chapter 9, “Creating and
Accessing Menus Using Display Files” on page 9-1.
Creating Objects
The UIM creates and changes the following objects:
Panel group objects
Menu objects
Search index objects
The panel group and menu objects contain panel definitions and online help infor-
mation. A menu object (*MENU), which contains a panel group definition, is
created using the TYPE(*UIM) parameter on the Create Menu (CRTMNU)
command. The panel group and menu objects are created using a tag-based lan-
guage that specifies definitions for UIM elements.
The UIM creates search index objects that contain search terms extracted from
online help information. A search index object makes it more efficient for a user to
locate specific online information using the index search function.
Elements Within a Panel Group

The tag-based language used to define the panels, menus, and online help also
supports definitions of symbolic elements that include the following:
Variable classes
Data elements that can be accessed through the UIM application programming
interface (API), such as dialog variables and lists
Variable records that define buffers passed by application programs
Conditional expressions that must be true if certain processing is to take place
Key lists containing the definition of function keys
Menu bars containing the definition of one or more pull-down menus
Panel definitions containing one or more areas to present data, information,
lists, and menus
Online help text modules
Chapter 16. Introduction to the User Interface Manager 16-3

Using the UIM Language Tags
The language tags are an easy-to-use function for defining panels. Using the lan-
guage tags helps application programmers create consistent appearing panels. For
more information on the language tags, see Appendix A, “UIM Panel Group Defi-
nition Language” on page A-1.
Using Dialog Commands

Dialog commands are special functions, recognized only by the UIM, that allow the
user to navigate through the panels.
Following is a list of the dialog commands and the functions they perform:
ACTIONS Alternates the cursor position between the panel and the menu
bar; removes, if shown, a pull-down menu from the panel.
CALL Calls an application program to perform a function.
CANCEL Backs up one panel (returns to the previous panel).
CHGVIEW Changes the displayed view of a list by switching defined sets of
columns to be shown.
CMD Submits an AS/400 CL command (or System/36 environment
OCL command) to the system for processing.
CMDLINE Displays a pop-up window with a command line.
DSPHELP Displays a module of help text.
ENTER Initiates processing of an action; submits panel input for pro-
cessing.
EXIT Returns the user from a group of displays or menus.
EXTHELP Displays the extended help text for the panel.
HELP Displays help information for the panel, based on the position of
the cursor.
HELPHELP Displays information about how to use the help facilities.
HELPIDX Initiates the index search function for the application to allow the
user to make a search request.
HOME Displays the initial (home) menu of the job.
KEYSHELP Displays the help for the function keys shown on the displayed
panel.
MENU Displays a subsequent menu as a result of selecting a menu
item or pressing a function key.
MOREKEYS Displays an additional set of active function keys and their
descriptions; used when all keys cannot be shown at once.
MOVETOP Moves a cursor-selected line to the top of the scrollable informa-
tion area.
MSG Displays a message on the message line.
PAGEDOWN Pages (scrolls) forward by one panel.
PAGEUP Pages (scrolls) backward by one panel.
PRINT Prints all the information shown on the current display.
PROMPT Prompts (seeks input) for commands, action list options, or entry
fields.
PULLDOWN Displays the pull-down menu for the first choice shown on the
menu bar.
RETRIEVE Retrieves and displays the previously entered command.

RETURN Returns control (and a return value) to an application for pro-
cessing.
Note: To provide the Refresh/Redisplay function for an applica-
tion, use the RETURN dialog command.
For detailed information on the dialog commands, see Appendix B, “UIM Dialog
Commands.”
Using Control Language (CL) Commands

The following CL commands are used to work with panel groups, menus, index
search, and InfoSeeker:
ADDSCHIDXE (Add Search Index Entry)
CHGMNU (Change Menu)
CHGSCHIDX (Change Search Index)
CRTMNU (Create Menu)
CRTPNLGRP (Create Panel Group)
CRTSCHIDX (Create Search Index)
DLTMNU (Delete Menu)
DLTPNLGRP (Delete Panel Group)
DLTSCHIDX (Delete Search Index)
DSPMNUA (Display Menu Attributes)
GO (Go to Menu)
RMVSCHIDXE (Remove Search Index Entry)
STRINFSKR (Start InfoSeeker)
STRSCHIDX (Start Search Index)
WRKSCHIDXE (Work Search Index Entry)
For detailed information on the CL commands, see the CL Reference.
Using an Application Programming Interface (API)

The UIM provides several API services. The service calls to the UIM consist of the
following:
Application services
Variable pool services
List services
Display services
Print services
The application services consist of the following:
Open Display Application (QUIOPNDA)
Open Print Application (QUIOPNPA)
Close Application (QUICLOA)
The variable pool services consist of the following:
Get Dialog Variable (QUIGETV)
Put Dialog Variable (QUIPUTV)
The list services consist of the following:
Add List Entry (QUIADDLE)
Add List Multiple Entries (QUIADDLM)

Get List Entry (QUIGETLE)
Get List Multiple Entries (QUIGETLM)
Update List Entry (QUIUPDLE)
Remove List Entry (QUIRMVLE)
Delete List (QUIDLTL)
Set List Attributes (QUISETLA)
Retrieve List Attributes (QUIRTVLA)
The display services consist of the following:
Display Panel (QUIDSPP)
Display Help (QUHDSPH)
Add Pop-up Window (QUIADDPW)
Remove Pop-up Window (QUIRMVPW)
Set Screen Image (QUISETSC)
Display Long Text (QUILNGTX)
The print services consist of the following:
Print Panel (QUIPRTP)
Print Help (QUHPRTH)
Add Print Application (QUIADDPA)
Remove Print Application (QUIRMVPA)
For details on the APIs, see the System API Reference.
Defining a Menu Object Using UIM

Using the UIM, you can create a *UIM type of menu object. The menu object con-
tains the definition of a menu panel with one or more options. To create a *UIM
type of menu, do the following.
1. Create a member in a source physical file.
2. Enter the UIM tag source to describe the menu using a source editor, such as
the Source Entry Utility (SEU). An example menu exists in member T0011MN2
in file QATTUIM in library QUSRTOOL. You can copy this example to use as a
template to create your own menu.
3. Use the Create Menu (CRTMNU) command to create the menu object using
the tag source as input. Here is an example of using the CRTMNU command.
CRTMNU MENU(MYLIB/MYMENU) TYPE(\UIM) SRCFILE(MYLIB/QMNUSRC)
The source member defaults to the name of the menu being created.
Creating a Menu Panel

The panel shown in Figure 16-1 on page 16-7 is an example menu. If you need
more information on creating help for a menu area, see “Help in a Menu Area” on
page 19-7.

à Tðð11MN2 .1/ Example Menu .2/
ð
.3/ System: SYSNAMXX
Select one of the following: .4/
1. Work with members in a file .5/

2. Work with record definitions
Selection or command .6/

===>
F3=Exit F4=Prompt F9=Retrieve F12=Cancel .7/

(C) COPYRIGHT YOUR COMPANY NAME HERE, 1992. .8/
á ñ
Figure 16-1. An Example Menu
The reference numbers in the example menu do not appear on the display. They
are shown for illustration purposes and also appear in the UIM tag source shown in
“Source for Example Menu” on page 16-9. These reference numbers show the
portions of the source which define text and information that appear on the menu.
.1/ The panel identifier is defined by declaring the UIM-defined Z-variable,
ZMENU, using the VAR tag and specifying the Z-variable to be used as the
panel identifier on the PANELID attribute of the PANEL tag.
.2/ The panel title is defined as text following the period of the PANEL tag.
.3/ The system name is shown because the TOPSEP=SYSNAM attribute was
specified on the PANEL tag.
.4/ The top instruction line is defined as text following the period of the top
instruction (TOPINST) tag.
.5/ Each option on the menu is defined using the menu item (MENUI) tag. The
option number is defined using the OPTION attribute and the text following the
option number is defined as text following the MENUI tag.
.6/ The command line is defined using the command line (CMDLINE) tag. The
command line prompt text is defined as text following the CMDLINE tag. The
UIM automatically provides the arrow (===>) for every command line.
An option line can be defined by using the option line (OPTLINE) tag instead
of the CMDLINE tag. In this case, the user enters option numbers, but is not
allowed to enter system commands.
.7/ Each function key is defined using a key list item (KEYI) tag. The text,
including the function key name, is defined as text following the period of the
KEYI tag.
All function keys for a panel are defined by placing the KEYI tags between a
key list (KEYL) and EKEYL tag. The name specified on the NAME attribute of
the KEYL tag is also specified on the KEYL attribute of the PANEL tag.

Some function keys, such as the Enter key, do not have text specified for the
KEYI tag. In this case, no text appears on the display. However, all function
keys must be defined using the KEYI tag so the UIM knows what action is
assigned for each key and what help module should be displayed when help
is displayed for the function keys.
.8/ The copyright message is defined as text following the period of the copyright
(COPYR) tag. The copyright message is displayed once when the user ini-
tially sees the menu. The message is not shown when the menu is redis-
played after processing an option or command.
This example menu is not defined as scrollable because it contains only two
options. If you need to define a scrollable menu, change SCROLL=NO to
SCROLL=YES on the MENU tag and add one menu item (MENUI) tag for each
additional menu option. You also need to define a new help module for each menu
option.
Required Tags for a Menu Panel

Figure 16-2 shows the required tags for creating a UIM menu panel. For an
example of the required and optional tags, see “Source for Example Menu” on
page 16-9.
Note: The tags in Figure 16-2 require attributes. These attributes are not shown.
Without these attributes, the example in Figure 16-2 will not compile. For a
description of the required attributes for these required tags, see
Appendix A, “UIM Panel Group Definition Language.”
:PNLGRP. ─────────────────┐
. │
. │
. │
:KEYL. ──┐ │
:KEYI. │ │
:EKEYL. ──┘ │
:PANEL. ──────────────┐ │
:MENU. ──┐ │ │
:MENUI. │ │ │
. │ │ │
. │ │ │
. │ │ │
:EMENU. ──┘ │ │
:OPTLINE or :CMDLINE. │ │
:EPANEL. ──────────────┘ │
. │
. │
. │
:HELP. ──┐ │
. │ │
. │ │
. │ │
:EHELP. ──┘ │
. │
. │
. │
:EPNLGRP. ─────────────────┘
Figure 16-2. Required UIM Tags for a Menu Panel

Source for Example Menu
This is a listing of the tag source for the menu shown in Figure 16-1 on page 16-7.
The entire source can be found in member T0011MN2 in source file QATTUIM in
library QUSRTOOL.
.\ -----------------------------------------------------------------
.\
.\ Beginning of menu source.
.\
.\ -----------------------------------------------------------------
:PNLGRP HLPSHELF=LIST
DFTMSGF=tðð11msgf2
SUBMSGF=tðð11msgf2.
.\
.\ -----------------------------------------------------------------
.\ Copyright statement appears when the menu is initially displayed.
.\ -----------------------------------------------------------------
:COPYR. .8/
(C) COPYRIGHT YOUR COMPANY NAME HERE, 1992.
.\
.\ -----------------------------------------------------------------
.\ UIM Z-variable to be used as the panel identifier
.\ -----------------------------------------------------------------
:VAR NAME=ZMENU. .1/
.\
.\ -----------------------------------------------------------------
.\ Define keys for the menu
.\ -----------------------------------------------------------------
:KEYL NAME=menukeys .7/
HELP=keyl.
:KEYI KEY=F1
HELP=helpf1
ACTION=HELP.
:KEYI KEY=F3
HELP=exit
ACTION='EXIT SET'
VARUPD=NO.
F3=Exit .7/
:KEYI KEY=F4
HELP=prompt
ACTION=PROMPT.
F4=Prompt
:KEYI KEY=F9
HELP=retrieve
ACTION=RETRIEVE.
F9=Retrieve
:KEYI KEY=F12
HELP=cancel
ACTION='CANCEL SET'
VARUPD=NO.
F12=Cancel
:KEYI KEY=F24
HELP=morekeys
ACTION=MOREKEYS.
F24=More keys
:KEYI KEY=ENTER
HELP=enter
ACTION=ENTER.
:KEYI KEY=HELP
HELP=help
ACTION=HELP.
:KEYI KEY=HOME
HELP=home

ACTION=HOME.
:KEYI KEY=PAGEDOWN
HELP=pagedown
ACTION=PAGEDOWN.
:KEYI KEY=PAGEUP
HELP=pageup
ACTION=PAGEUP.
:KEYI KEY=PRINT
HELP=print
ACTION=PRINT.
:EKEYL.
.\
.\ -----------------------------------------------------------------
.\ Define Example Menu panel
.\ -----------------------------------------------------------------
:PANEL NAME=xmpmenu
HELP='menu/help'
KEYL=menukeys .7/
ENTER='MSG CPD9817 QCPFMSG'
PANELID=ZMENU .1/
TOPSEP=SYSNAM. .3/
Example Menu .2/
.\
.\ -------------------------------------
.\ Define the menu area
.\ -------------------------------------
:MENU DEPTH='\'
SCROLL=NO
BOTSEP=SPACE.
:TOPINST.Select one of the following: .4/
.\
.\ -------------------------------------
.\ Specify the action to be taken for each option
.\ -------------------------------------
:MENUI OPTION=1 .5/
ACTION='CMD ?tðð11cm2'
HELP='menu/option1'.
Work with members in a file
.\
:MENUI OPTION=2
ACTION='CMD ?tðð11cm3'
HELP='menu/option2'.
Work with record definitions
.\
:EMENU.
.\
.\ -------------------------------------
.\ Use a command line and allow commands and option numbers
.\ -------------------------------------
:CMDLINE SIZE=LONG. .6/
.\
:EPANEL.
.\
.\
.\ -----------------------------------------------------------------
.\ Define help modules for the menu panel
.\ -----------------------------------------------------------------
:HELP NAME=keyl.
Function Keys - Help
:XH3.Function keys
:EHELP.
.\
:HELP NAME=helpf1.

:PARML.
:PT.F1=Help
:PD.
Provides additional information about using the display or a
specific field on the display.
:EPARML.
:EHELP.
.\
:HELP NAME=exit.
:PARML.
:PT.F3=Exit
:PD.
Ends the current task and returns to the display from which the
task was started.
:EPARML.
:EHELP.
.\
:HELP NAME=prompt.
:PARML.
:PT.F4=Prompt
:PD.
Provides assistance in entering or selecting a command.
:EPARML.
:EHELP.
.\
:HELP NAME=retrieve.
:PARML.
:PT.F9=Retrieve
:PD.
Displays the last command you entered on the command line and
any parameters you included. Pressing this key once, shows the
last command you ran. Pressing this key twice, shows the
command you ran before that and so on.
:EPARML.
:EHELP.
.\
:HELP NAME=cancel.
:PARML.
:PT.F12=Cancel
:PD.
Returns to the previous menu or display.
:EPARML.
:EHELP.
.\
:HELP NAME=morekeys.
:PARML.
:PT.F24=More keys
:PD.
Shows additional function keys.
:EPARML.
:EHELP.
.\
:HELP NAME=enter.
:PARML.
:PT.Enter
:PD.
Submits information on the display for processing.
:EPARML.
:EHELP.
.\
:HELP NAME=help.
:PARML.
:PT.Help
:PD.

Provides additional information about using the display.
:EPARML.
:EHELP.
.\
:HELP NAME=home.
:PARML.
:PT.Home
:PD.
Goes to the menu that was shown after you signed on the system.
This menu is either the initial menu defined in your user
profile or the menu you requested from the Sign-On display.
:EPARML.
:EHELP.
.\
:HELP NAME=pagedown.
:PARML.
:PT.Page Down (Roll Up)
:PD.
Moves forward to show additional information for this display.
:EPARML.
:EHELP.
.\
:HELP NAME=pageup.
:PARML.
:PT.Page Up (Roll Down)
:PD.
Moves backward to show additional information for this display.
:EPARML.
:EHELP.
.\
:HELP NAME=print.
:PARML.
:PT.Print
:PD.
Prints information currently shown on the display.
:EPARML.
:EHELP.
.\
:HELP NAME='menu/help'.
Example Menu - Help
:P.
The Example Menu shows an example of a menu created using the UIM.
:XH3.
How to Use a Menu
:P.
To select a menu option, type the option number and press Enter.
:P.
To run a command, type the command and press Enter. For assistance
in selecting a command, press F4 (Prompt) without typing anything.
For assistance in entering a command, type the command and press F4
(Prompt). To see a previous command you entered, press F9
(Retrieve).
:P.
To go to another menu, use the Go to Menu (GO) command. Type GO
followed by the menu ID, then press the Enter key. For example, to
go to the User Tasks (USER) menu, type GO USER and press the Enter
key. The menu ID is shown in the upper left corner of the menu.
For assistance in entering the GO command, type GO and press F4
(Prompt). If you do not know the entire menu name you can use a
generic name. For example, GO US\ will show a list of all menus
that start with US.
:EHELP.
.\
:HELP NAME='menu/option1'.

Option 1 - Help
:XH3.Option 1. Work with members in a file
:P.
Select this option to work with the members in a file. You will be
prompted for the name of the file.
:EHELP.
.\
:HELP NAME='menu/option2'.
Option 2 - Help
:XH3.Option 2. Work with record definitions
:P.
Select this option to work with record definitions for a file.
You will be prompted for the name of the file.
:EHELP.
.\
.\
.\
.\ -----------------------------------------------------------------
.\ End of menu source
.\ -----------------------------------------------------------------
:EPNLGRP.
Defining a Panel Group Object Using UIM

Using the UIM, you can create a panel group object. The panel group object can
contain the definitions for dialog variables, lists, panels and help modules. To
create a panel group object, do the following.
1. Create a member in a source physical file.
2. Enter the UIM tag source to describe the panel group using a source editor
such as the Source Entry Utility (SEU). An example panel group exists in
member T0011PN2 in file QATTUIM in library QUSRTOOL. You can copy this
example to use as a template to create your own panel group.
3. Use the Create Panel Group (CRTPNLGRP) command to create the panel
group object using the tag source as input. Here is an example of using the
CRTPNLGRP command.
CRTPNLRP PNLGRP(MYLIB/MYPNLGRP) SRCFILE(MYLIB/QPNLSRC)
The source member defaults to the name of the panel group being created.
Creating a List Panel

Any of the "Work with..." panels are list panels. In this example, the Work with File
Members panel is used. Defining the list panel is similar to defining a subfile in
DDS, but the UIM determines the appearance of the panel.
The panel shown in Figure 16-3 on page 16-14 shows an example of a mixed
panel with a list area. The panel is mixed because it contains two types of areas: a
data presentation area at the top and a list area at the bottom.
The data presentation area at the top consists of the fields which identify the file
and library name. The list area begins with the instruction line, Type options, press
Enter and ends with the scroll information (More...).
In this example, the panel contains a special type of list area called an action list.
An action list is a list which contains an option column. The user types in allowed

option numbers to perform actions against the object represented by the entry in
the list. If you need more information on creating list panel help, see “Help in a List
Area” on page 19-5.
à Work with File Members .1/

ð
File . . . . . . . . . XXXXXXXXXX F4 for list .2/
Library . . . . . . XXXXXXXXXX library, \CURLIB, \LIBL
Type options, press Enter. .3/

3=Copy 4=Remove 5=Display 7=Reorganize 8=Member description .4/
9=Clear
Opt Member Type Text .5/

.6/
XXXXXXXXXX XXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
.7/ More...
Parameters for options 3 and 5 or command .8/
===>
F3=Exit F4=Prompt F9=Retrieve F11=Display names only F12=Cancel .9/
á ñ
Figure 16-3. Example List Panel
The panel shown in Figure 16-4 is an alternate view shown when the user presses
F11 (Display names only) on the panel shown in Figure 16-3. The alternate view
shown here uses a multiple-column layout. The panel is divided into four layout
columns of equal size. The Opt and Member columns appear in each layout
column. The alternate view shows four times as many list entries as the original
view, but does not show the Type and Text columns for each entry.
à Work with File Members .1/

ð
File . . . . . . . . . XXXXXXXXXX F4 for list .2/
Library . . . . . . XXXXXXXXXX library, \CURLIB, \LIBL
Type options, press Enter. .3/
3=Copy 4=Remove 5=Display 7=Reorganize 8=Member description .4/
9=Clear
Opt Member Opt Member Opt Member Opt Member .5/

.6/
XXXXXXXXXX XXXXXXXXXX XXXXXXXXXX XXXXXXXXXX
.7/ More...
Parameters for options 3 and 5 or command .8/
===>
F3=Exit F4=Prompt F9=Retrieve F11=Display descriptions F12=Cancel .9/
á ñ
Figure 16-4. Example of Alternate View of List

The reference numbers in the example panel do not appear on the display. They
“Source for Example List Panel” on page 16-17. These reference numbers show
which portions of the source define text and information which appears on the
panel.
.1/ The panel title is defined as text following the period of the display panel
(PANEL) tag.
.2/ The text for the file and library name is defined as text following the period of
the data item (DATAI) tag. The file name and library name are dialog variable
values. Each dialog variable is defined using the variable definition (VAR)
tag. The name of the dialog variable is specified on the VAR attribute of the
DATAI tag. The possible choices text for each input field is defined as text
following the period of the data item choices (DATAC) tag.
The file name and library are formatted as a qualified object name because
GRPSEP=QINDENT is specified on the data group (DATAGRP) tag which sur-
rounds the two DATAI tags.
The dialog variables for the file name and library name are defined using the
VAR tags at .A/ and .B/, respectively, shown on page 16-19.
.3/ The instruction line is defined as text following the period of the top instruction
(TOPINST) tag.
.4/ Each list option is defined using the list action (LISTACT) tag. The text,
including the option number with the equal sign, is defined as text following
the period of the LISTACT tag.
.5/ The column heading for each column is defined as text following the period of
the list column (LISTCOL) tag. The VAR attribute of the LISTCOL tag identifies
the name of the dialog variable whose value is displayed under the column
heading.
The dialog variable name specified, must be defined using the VAR tag. The
dialog variable name must also be specified on the VARS attribute of the list
definition (LISTDEF) tag for the list appearing in the panel.
The dialog variables for the option, member name, member type, and
description text are defined using the VAR tags at .C/, .D/, .E/, and .F/,
respectively, shown on page 16-19.
The names of these variables also appear in the VARS attribute of the
LISTDEF tag at .G/ shown on page 16-21. The name of the list definition
must be specified on the LISTDEF attribute of the list area (LIST) tag at .H/,
shown on page 16-23.
.6/ The extended action entry that appears immediately below the column
headings is defined by specifying EXTACT=YES on the LIST tag. Each column
which has an input field in the extended action entry must specify
EXTACT=YES on the LISTCOL tag.
The extended action entry allows the user to perform actions without having to
scroll to a specific entry in the list.
Each list option defined by the LISTACT tag, specifies whether the action is
allowed to be performed against the extended action entry, the list entries
appearing below the extended action entry, or both. This specification is
made using the ACTFOR attribute of the LISTACT tag.

.7/ The scroll information, More... and Bottom, are shown because the list area is
defined as scrollable because the SCROLL attribute defaults to YES on the
LIST tag.
.8/ The command line is defined using the command line (CMDLINE) tag. The
command line prompt text is defined as text following the period of the
CMDLINE tag. The UIM automatically provides the arrow (===>) for every
command line.
The command line can be used to enter parameters for list options. Before
processing list options, the UIM places the contents of the command line into
a dialog variable. The dialog variable can be:
Substituted into a CL command specified as the action to perform on a
LISTACT tag
Used by an exit program specified as the action to perform on the
LISTACT tag
Used by the application program when it is performing the actions for the
list
The dialog variable used to contain parameters from the command line is
defined using the VAR tag at .I/, shown on page 16-19. It is also specified
on the PARMS attribute of the list area (LIST) tag at .J/, shown on page 16-23.
The UIM places the contents of the command line in the dialog variable speci-
fied by the PARMS attribute before beginning list option processing.
Then the dialog variable is used as a substitution variable in a command
string on a LISTACT tag at .K/, shown on page 16-23.
.9/ Each function key is defined using the key list (KEYL) tag. The text, including
the function key name, is defined as text following the period of the KEYI tag.
All function keys are defined by placing the KEYI tags between the key list
(KEYL) and EKEYL tags. The name specified on the NAME attribute of the
KEYL tag is also specified on the KEYL attribute of the PANEL tag.
Some function keys, such as Enter, do not have text specified for the KEYI
tag. In this case, no text appears on the display. However, all function keys
must be defined using the KEYI tag so the UIM knows what action is
assigned to each key and what help module to use when help is displayed for
the function keys.
Required Tags for a List Panel

Figure 16-5 on page 16-17 shows the required tags for creating a UIM list panel.
For an example of the required and optional tags, see “Source for Example List
Panel” on page 16-17.
Note: The tags in Figure 16-5 on page 16-17 require attributes. These attributes
are not shown. Without these attributes, the example in Figure 16-5 on
page 16-17 will not compile. For a description of the required attributes for
these required tags, see Appendix A, “UIM Panel Group Definition
Language.”

:PNLGRP. ──────────┐
:CLASS. ──┐ │
:ECLASS. ──┘ │
:VAR. │
:KEYL. ──┐ │
:KEYI. │ │
:EKEYL. ──┘ │
:PANEL. ──────┐ │
:LISTDEF. │ │
. │ │
. │ │
. │ │
:LIST. ────┐ │ │
:LISTACT. │ │ │
:LISTCOL. │ │ │
:LISTVIEW. │ │ │
. │ │ │
. │ │ │
. │ │ │
:ELIST. ────┘ │ │
. │ │
. │ │
. │ │
:EPANEL. ──────┘ │
. │
. │
. │
:HELP. ───┐ │
. │ │
. │ │
. │ │
:EHELP. ───┘ │
:EPNLGRP. ──────────┘
Figure 16-5. Required UIM Tags for a List Panel
Source for Example List Panel

This is a partial listing of member T0011PN2 in source file QATTUIM in library
QUSRTOOL.
.\ -----------------------------------------------------------------
.\
.\ Beginning of panel group source.
.\
.\ -----------------------------------------------------------------
.\
.\ The import tag specifies that all help is to be found
.\ in panel group Tðð11HL2 searching the library list.
:IMPORT NAME='\'
PNLGRP=tðð11hl2.
.\
.\ -----------------------------------------------------------------
.\ Define all variable classes
.\ -----------------------------------------------------------------
.\ -----------------
.\ Option
.\ Note: Need WIDTH=1 to preserve column alignment on confirmation panel.
:CLASS NAME=optcl
BASETYPE='ACTION'

WIDTH=1.
:ECLASS.
.\ -----------------
.\ Object name
:CLASS NAME=namecl
BASETYPE='OBJNAME 1ð'.
:ECLASS.
.\ -----------------
.\ Library name
:CLASS NAME=libcl
:TL.
:TI VALUE='"\LIBL"'.\LIBL
:TI VALUE='"\CURLIB"'.\CURLIB
:ETL.
:ECLASS.
.\ -----------------
.\ File attribute
:CLASS NAME=attrcl
BASETYPE='CHAR 1ð'
CASE=UPPER.
:ECLASS.
.\ -----------------
.\ Descriptive text
:CLASS NAME=textcl
BASETYPE='IGC 5ð'
SUBST=QUOTED.
:ECLASS.
.\ -----------------
.\ Source type
:CLASS NAME=srctypcl
BASETYPE='CHAR 1ð'.
:ECLASS.
..
.
Additional CLASS tags in member Tðð11PN2 are not shown here
..
.
.\ -----------------
.\ Command line parameters
:CLASS NAME=parmcl
BASETYPE='CHAR 255'.
:ECLASS.
.\ -----------------
.\ Exit program specification for CALL dialog command
:CLASS NAME=exitcl
:ECLASS.
.\ -----------------
.\ View number
:CLASS NAME=vwnumcl
BASETYPE='BIN 15'.
:ECLASS.
.\ -----------------
.\ Classes for pad variables in variable record definitions.
:CLASS NAME=pad1cl
BASETYPE='CHAR 1'.
:ECLASS.
:CLASS NAME=pad2cl
BASETYPE='CHAR 2'.
:ECLASS.
:CLASS NAME=pad1ðcl
:ECLASS.
:CLASS NAME=pad13cl

BASETYPE='CHAR 13'.
:ECLASS.
:CLASS NAME=pad48cl
BASETYPE='CHAR 48'.
:ECLASS.
:ECLASS.
.\
.\ -----------------------------------------------------------------
.\ Define all dialog variables
.\ -----------------------------------------------------------------
.\
.\ -------------------------------------
.\ Variables for file and library
.\ -------------------------------------
.\ -----------------
.\ File name
:VAR NAME=file .A/
CLASS=namecl.
.\ -----------------
.\ Library name
:VAR NAME=lib .B/
CLASS=libcl.
.\ -----------------
.\ attributes
:VAR NAME=fattr
CLASS=attrcl.
.\ -----------------
.\
.\ -------------------------------------
.\ Variables for list of members
.\ -------------------------------------
.\ -----------------
.\ option for list of members
:VAR NAME=mopt .C/
CLASS=optcl.
.\ -----------------
.\ Object name
:VAR NAME=mbr .D/
CLASS=namecl.
.\ -----------------
.\ member type
:VAR NAME=mtype .E/
CLASS=attrcl.
.\ -----------------
.\ Descriptive text
:VAR NAME=mtext .F/
CLASS=textcl.
..
.
Additional VAR tags in member Tðð11PN2 are not shown here
..
.
.\
.\ -------------------------------------
.\ Variable for command line parameters
.\ -------------------------------------
.\ -----------------
:VAR NAME=parms .I/
CLASS=parmcl.
.\
.\ -------------------------------------
.\ Variables for specifying CALL/exit programs
.\ -------------------------------------

.\ -----------------
.\ Program to call for all UIM exits
:VAR NAME=exitpgm
CLASS=exitcl.
.\
.\ -------------------------------------
.\ Variables for controlling list views
.\ -------------------------------------
.\ -----------------
.\ View number for list of members
:VAR NAME=mbrview
CLASS=vwnumcl.
..
.
..
.
.\
.\ -------------------------------------
.\ Variables for padding in variable record definitions.
.\ Padding is needed in variable records so the layout
.\ of the record matches a list format returned from
.\ an API. The pad variables are used as placeholders for
.\ variables not used in the API format or for reserved space
.\ in the API format.
.\ -------------------------------------
:VAR NAME=pad1
CLASS=pad1cl.
:VAR NAME=pad2
CLASS=pad2cl.
:VAR NAME=pad1ð
CLASS=pad1ðcl.
:VAR NAME=pad13
CLASS=pad13cl.
:VAR NAME=pad48
CLASS=pad48cl.
:VAR NAME=pad5ð
CLASS=pad5ðcl.
.\
.\ -----------------------------------------------------------------
.\ Define a variable record for file, library and file attribute
.\ -----------------------------------------------------------------
:VARRCD NAME=filelib
VARS='file lib fattr'
NOGET='fattr'
.
.\
.\ -----------------------------------------------------------------
.\ Define a variable record for exit program
.\ -----------------------------------------------------------------
:VARRCD NAME=exitprog
VARS='exitpgm'
.
.\
.\ -----------------------------------------------------------------
.\ Define a variable record for list of members.
.\ The layout of this record is designed to match the
.\ List Database File Members API (QUSLMBR) format name MBRLð2ðð.
.\ -----------------------------------------------------------------
:VARRCD NAME=mbrlð2ðð
VARS='mbr mtype pad13 pad13 mtext'
NOPUT='pad13'
NOGET='mtype pad13 mtext'
.
..
.
Additional VARRCD tags in member Tðð11PN2 are not shown here

..
.
.\
.\
.\ -----------------------------------------------------------------
.\ Define a list of members
.\ -----------------------------------------------------------------
:LISTDEF NAME=mbrlist
VARS='mopt mbr mtype mtext'
MSGID=USRð1ð1.
..
.
Additional LISTDEF tags in member Tðð11PN2 are not shown here
..
.
.\
.\ -----------------------------------------------------------------
.\ Define all conditions
.\ -----------------------------------------------------------------
.\ -----------------
.\ Condition for physical files
:COND NAME=pf
EXPR='fattr="PF "'.
.\ -----------------
.\ Conditions for views of members list
:COND NAME=mbrview1
EXPR='mbrview=ð'.
:COND NAME=mbrview2
EXPR='mbrview=1'.
..
.
Additional COND tags in member Tðð11PN2 are not shown here
..
.
.\
.\ -----------------------------------------------------------------
.\ Define truth table to specify that mbrview1 and mbrview2
.\ are mutually exclusive conditions
.\ This will cause UIM to reserve only one line of function
.\ keys on the work with members panel
.\ -----------------------------------------------------------------
:TT NAME=mbrtt
CONDS='mbrview1 mbrview2'.
:TTROW VALUES=' 1 ð '.
:TTROW VALUES=' ð 1 '.
:ETT.
..
.
Additional TT tags in member Tðð11PN2 are not shown here
..
.
..
.
All MBAR tags in member Tðð11PN2 are not shown here
..
.
.\
.\
.\ -----------------------------------------------------------------
.\ Define keys for work with members panel
.\ -----------------------------------------------------------------
:KEYL NAME=mbrkeys .9/
HELP=keyl.
:KEYI KEY=F1
HELP=helpf1
ACTION=HELP.
:KEYI KEY=F3
HELP=exit
ACTION='EXIT SET'
VARUPD=NO.
F3=Exit
:KEYI KEY=F4

HELP=prompt
ACTION=PROMPT
PRIORITY=3ð.
F4=Prompt
:KEYI KEY=F9
HELP=retrieve
ACTION=RETRIEVE
PRIORITY=35.
F9=Retrieve
:KEYI KEY=F11
HELP=mbrviewname
ACTION=CHGVIEW
PRIORITY=25
COND=mbrview1.
F11=Display names only
:KEYI KEY=F11
HELP=mbrviewdesc
ACTION=CHGVIEW
PRIORITY=25
COND=mbrview2.
F11=Display descriptions
:KEYI KEY=F12
HELP=cancel
ACTION='CANCEL SET'
VARUPD=NO.
F12=Cancel
:KEYI KEY=F24
HELP=morekeys
ACTION=MOREKEYS.
F24=More keys
:KEYI KEY=ENTER
HELP=enter
ACTION=ENTER.
:KEYI KEY=HELP
HELP=help
ACTION=HELP.
:KEYI KEY=PAGEDOWN
HELP=pagedown
ACTION=PAGEDOWN.
:KEYI KEY=PAGEUP
HELP=pageup
ACTION=PAGEUP.
:KEYI KEY=PRINT
HELP=print
ACTION=PRINT.
:EKEYL.
..
.
Additional KEYL tags in member Tðð11PN2 are not shown here
..
.
.\
.\
.\ -----------------------------------------------------------------
.\ Define Work with Members panel
.\ -----------------------------------------------------------------
:PANEL NAME=wrkmbr
HELP='wrkmbr/'
KEYL=mbrkeys .9/
TT=mbrtt
ENTER='RETURN 5ðð'
TOPSEP=SPACE.
Work with File Members .1/
.\
.\ -------------------------------------
.\ Define a data presentation area to display the

.\ library/file name whose members are listed.
.\ -------------------------------------
:DATA DEPTH=3
SCROLL=NO
LAYOUT=1
BOTSEP=SPACE
COMPACT
.
.\ -------------------------------------
.\ Divide the layout width into two columns.
.\ The first column is for the prompt text with leader dots.
.\ The second column is for the variable values.
:DATACOL WIDTH=22.
:DATACOL WIDTH=12.
:DATACOL WIDTH='\'.
.\ -------------------------------------
.\ Display qualified file name
:DATAGRP GRPSEP=QINDENT
HELP='wrkmbr/filelib'
COMPACT
.
:DATAI VAR=file .2/
USAGE=INOUT
PROMPT='CALL exitpgm'
.
File
:DATAC.F4 for list
:DATAI VAR=lib
USAGE=INOUT
.
Library
:DATAC.library, \CURLIB, \LIBL
:EDATAGRP.
.\
:EDATA.
.\
.\ -------------------------------------
.\ Define the list area
.\ -------------------------------------
:LIST DEPTH='\' .7/
LISTDEF=mbrlist .H/
ACTOR=UIM
EXTACT=YES .6/
MAXHEAD=4
MAXACTL=3
VIEW=mbrview
PARMS=parms .J/
BOTSEP=SPACE.
:TOPINST.Type options, press Enter. .3/
.\
.\ -------------------------------------
.\ -------------------------------------
:LISTACT OPTION=3
ACTFOR=BOTH .6/
NOCMD=PROMPT
NOEXT=PROMPT
HELP='wrkmbr/cpyf'
ENTER='CMD CPYF ?\FROMFILE(&lib./&file.)'
ENTER=' ?\FROMMBR(&mbr.) &parms.' .K/
PROMPT='CMD ?CPYF ?\FROMFILE(&lib./&file.)'
PROMPT=' ?\FROMMBR(&mbr.) &parms.' .K/
EXTENTER='CMD ?CPYF ?\FROMFILE(&lib./&file.)'
EXTENTER=' ??FROMMBR(&mbr.) &parms.' .K/

EXTPROMPT='CMD ?CPYF ?\FROMFILE(&lib./&file.)'
EXTPROMPT=' ??FROMMBR(&mbr.) &parms.'. .K/
3=Copy .4/
.\
:LISTACT OPTION=4
ACTFOR=LISTE
HELP='wrkmbr/rmvm'
ENTER='CMD RMVM FILE(&lib./&file.) MBR(&mbr.)'
PROMPT='CMD ?RMVM ?\FILE(&lib./&file.) ?\MBR(&mbr.)'
USREXIT='CALL exitpgm'.
4=Remove
.\
:LISTACT OPTION=5
COND=pf
ACTFOR=BOTH
NOEXT=PROMPT
HELP='wrkmbr/dsppfm'
ENTER='CMD DSPPFM FILE(&lib./&file.) MBR(&mbr.) &parms.'
PROMPT='CMD DSPPFM ?\FILE(&lib./&file.) ?\MBR(&mbr.) &parms.'
EXTPROMPT='CMD DSPPFM ?\FILE(&lib./&file.) ??MBR(&mbr.) &parms.'.
5=Display
.\
:LISTACT OPTION=7
COND=pf
ACTFOR=BOTH
HELP='wrkmbr/rgzm'
ENTER='CMD RGZPFM FILE(&lib./&file.) MBR(&mbr.)'
PROMPT='CMD ?RGZPFM ?\FILE(&lib./&file.) ?\MBR(&mbr.)'.
7=Reorganize
.\
:LISTACT OPTION=8
ACTFOR=BOTH
HELP='wrkmbr/dspfd'
ENTER='CALL exitpgm'
PROMPT='CALL exitpgm'.
8=Member description
.\
:LISTACT OPTION=9
COND=pf
ACTFOR=LISTE
HELP='wrkmbr/clrm'
ENTER='CMD CLRPFM FILE(&lib./&file.) MBR(&mbr.)'
PROMPT='CMD ?CLRPFM ?\FILE(&lib./&file.) ?\MBR(&mbr.)'.
9=Clear
.\
.\
.\ -------------------------------------
.\ Define the columns and headings to display
.\ -------------------------------------
:LISTCOL VAR=mopt
USAGE=INOUT
EXTACT=YES .6/
HELP='wrkmbr/option'
MAXWIDTH=6.
Opt .5/
:LISTCOL VAR=mbr
USAGE=OUT
EXTACT=YES
HELP='wrkmbr/mbr'
MAXWIDTH=1ð.
Member
:LISTCOL VAR=mtype
USAGE=OUT
HELP='wrkmbr/type'

MAXWIDTH=1ð.
Type
:LISTCOL VAR=mtext
USAGE=OUT
HELP='wrkmbr/text'
MAXWIDTH='\'.
Text
.\
.\ -------------------------------------
.\ Define multiple views for F11 to toggle between
.\ -------------------------------------
:LISTVIEW COLS='mopt mbr mtype mtext'.
:LISTVIEW COLS='mopt mbr' layout=4.
.\
:ELIST.
.\
.\ -------------------------------------
.\ Use a command line and allow parameters to be given
.\ -------------------------------------
:CMDLINE SIZE=SHORT. .8/
Parameters for options 3 and 5 or command
.\
:EPANEL.
..
.
Additional PANEL tags in member Tðð11PN2 are not shown here
..
.
.\
.\ -----------------------------------------------------------------
.\ End of panel group source
.\ -----------------------------------------------------------------
:EPNLGRP.
Application Programming for a List Panel

An example of an application program to display the list panel shown in
Figure 16-3 on page 16-14 can be found in member T0011CP2 in source file
QATTSYSC in library QUSRTOOL. This is an ILE C program which calls the
appropriate UIM application programming interfaces (APIs) to display the panel.
A general example of an RPG application using the UIM APIs can be found in
QUSRTOOL. Refer to member T0011INF in source file QATTINFO in library
QUSRTOOL. See Chapter 21, “Designing IBM AS/400-Style Displays” on
page 21-1 for more information on using the examples.
To write a program in any language to display the example list panel, the program
should do the following:
1. Call the Open Display Application (QUIOPNDA) API to open the panel group.
The panel group must already be created using the Create Panel Group
(CRTPNLGRP) command.
2. Set up a buffer containing the values for the following dialog variables:
FILE A CHAR 10 variable which is the name of the file.
LIB A CHAR 10 variable which is the name of the library where the file
resides.
FATTR A CHAR 10 variable which is the file attribute of the file. This variable
is used to condition on list options which are only allowed for physical
files.

3. Call the Put Dialog Variable (QUIPUTV) API to change the contents of the
dialog variables using variable record FILELIB and the buffer initialized in the
previous step.
4. Set up a buffer containing a value for the following dialog variable:
EXITPGM A CHAR 20 variable which identifies the program to be called as a
UIM exit program. For extended program model (EPM) languages,
this BASETYPE attribute of the CLASS tag used to define the
EXITPGM dialog variable must be changed to a CHAR 130 dialog
variable.
For information on how this dialog variable must be set, see the
description of the CALL dialog command in Appendix B, “UIM
Dialog Commands” on page B-1.
dialog variable using variable record EXITPROG and the buffer initialized in the
previous step.
6. Create a user space that will receive a list of members in a file using the
Create User Space (QUSCRTUS) API. The members in a file are retrieved
using the List Database File Members (QUSLMBR) API. If the application pro-
gramming language supports pointers, use the Retrieve Pointer to User Space
(QUSPTRUS) API to obtain a pointer to the contents of the user space. This
lets the application program directly manipulate the data. Otherwise, use the
Retrieve User Space (QUSRTVUS) API to obtain the contents of the user
space. For a description of these APIs, see the System API Reference.
7. For every member in the file to be displayed, do the following. A list of the
members in a file can be retrieved using the List Database File Members
(QUSLMBR) API. For a description of this API, see “List Database File
Members (QUSLMBR) API” in System API Reference.
a. Set up a buffer containing values for the following dialog variables:
MBR A CHAR 10 variable which is the member name.
MTYPE A CHAR 10 variable which is the member type.
PAD13 A CHAR 13 reserved space in the buffer.
MTEXT A CHAR 50 variable which is the descriptive text for the
member.
Note: The layout of this buffer is designed to match the layout of the
entries in the user space returned by the QUSLMBR API using the
MBRL0200 format. Therefore, instead of setting up a buffer, the
application program can pass the buffer as it exists in the user
space.
The two PAD13 variables are used to tell the UIM to ignore two
variables in the MBRL0200 format returned by the QUSLMBR API.
The variables are the creation date and time and the last source
change data and time.
b. Call the Add List Entry (QUIADDLE) API to add a list entry to the list
named MBRLIST using variable record MBRL0200 and the buffer initialized
in the previous step.

8. Call the Display Panel (QUIDSPP) API to display panel WRKMBR. The UIM
returns control to the application when one of the following occurs:
The user presses the Enter key without typing any list options or a
command on the command line. The program variable passed as the func-
tion requested parameter to the QUIDSPP API is set to 500. This is done
because ENTER='RETURN 500' is specified on the PANEL tag which defines
the WRKMBR panel.
The user presses the F12 (Cancel) key. The program variable passed as
the function requested parameter to the QUIDSPP API is set to -8. This is
the value defined for the CANCEL dialog command.
The user presses the F3 (Exit) key. The program variable passed as the
function requested parameter to the QUIDSPP API is set to -4. This is the
value defined for the CANCEL dialog command.
9. Call the Close Application (QUICLOA) API to close the UIM application. This
frees up the system resources used by the UIM application.
Creating a Confirmation List Panel

Options on an action list panel that perform destructive operations should use a
confirmation panel to allow the user to confirm or cancel the request before it is
performed. A confirmation panel should be provided for actions such as 4=Remove
and 9=Clear shown in the example panel in Figure 16-3 on page 16-14.
An example of a confirmation panel is shown in Figure 16-6. This confirmation

panel is used when the user types option 4 on the panel shown in Figure 16-3 on
page 16-14.
à Confirm Remove of Members

ð
File . . . . . . . . : XXXXXXXXXX
Library . . . . . : XXXXXXXXXX
Press Enter to confirm your choices for 4=Remove.

Press F12 to return to change your choices.
Opt Member Type Text

4 XXXXXXXXXX XXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
More...
F11=Display names only F12=Cancel
á ñ
Figure 16-6. Example Confirmation List Panel
The confirmation panel appears similar to the action list panel with the following
exceptions:
The instructions tell the user to confirm or cancel the option.

The displayed list is for output only. The user cannot change any of the option
numbers.
The F3 (Exit) key is not allowed from a confirmation panel.
There is no command line on a confirmation panel.
When the user presses the F11 key to change to a different view, the view of the
action list panel is changed when it is redisplayed. This is done because the same
dialog variable is specified on the VIEW attribute of the LIST tag for both the action
list panel and the confirmation panel.
Required Tags for a Confirmation List Panel

The required tags for a confirmation list panel are basically the same as those
required for a list panel which are described in Figure 16-5 on page 16-17.
However, the LISTACT tag is not required.
Source for Example Confirmation Panel

To define this confirmation panel, additional source needs to be added to the
source shown in “Source for Example List Panel” on page 16-17. The following
are excepts from member T0011PN2 in source file QATTUIM in library
QUSRTOOL. First, a new list definition needs to be made. This list definition con-
tains a copy of the list entries being confirmed. The confirmation list contains the
same dialog variables as are contained in the list of members. The following list
definition (LISTDEF) tag should be placed after the LISTDEF tag at .G/, shown on
page 16-21.
.\
.\ ---------------------------------------------------------------
.\ Define a list of members for confirmation panels
.\ ---------------------------------------------------------------
:LISTDEF NAME=mbrconf
VARS='mopt mbr mtype mtext'.
Next, function keys need to be defined for the confirmation panel. Confirmation
panels should not allow F3 (Exit). The following key list (KEYL) tag should be
placed after the KEYL tag, shown in “Source for Example List Panel” on
page 16-17.
.\
.\ -----------------------------------------------------------------
.\ Define keys for confirm remove of members
.\ -----------------------------------------------------------------
:KEYL NAME=mconfkeys
HELP=keyl.
:KEYI KEY=F1
HELP=helpf1
ACTION=HELP.
:KEYI KEY=F11
HELP=altview
ACTION=CHGVIEW
COND=mbrview1.
F11=Display names only
:KEYI KEY=F11
HELP=altview
ACTION=CHGVIEW

COND=mbrview2.
F11=Display descriptions
:KEYI KEY=F12
HELP=cancel
ACTION='CANCEL SET'
VARUPD=NO.
F12=Cancel
:KEYI KEY=F24
HELP=morekeys
ACTION=MOREKEYS.
F24=More keys
:KEYI KEY=ENTER
HELP=enter
ACTION=ENTER.
:KEYI KEY=HELP
HELP=help
ACTION=HELP.
:KEYI KEY=PAGEDOWN
HELP=pagedown
ACTION=PAGEDOWN.
:KEYI KEY=PAGEUP
HELP=pageup
ACTION=PAGEUP.
:KEYI KEY=PRINT
HELP=print
ACTION=PRINT.
:EKEYL.
The confirmation panel needs to be defined. The following source should be

placed after the EPANEL tag, shown in “Source for Example List Panel” on
page 16-17.
.\
.\ -----------------------------------------------------------------
.\ Define panel for confirm remove of members from WRKMBR panel
.\ -----------------------------------------------------------------
:PANEL NAME=confrmvm
HELP='confrmvm/'
KEYL=mconfkeys
TT=mbrtt
TOPSEP=space.
Confirm Remove of Members
.\
.\ -------------------------------------
.\ -------------------------------------
:DATA DEPTH=3
SCROLL=NO
LAYOUT=1
BOTSEP=SPACE
COMPACT
.
.\ -------------------------------------
:DATACOL WIDTH=22.
:DATACOL WIDTH='\'.
.\ -------------------------------------

COMPACT
.
:DATAI VAR=file
USAGE=OUT
.
File
:DATAI VAR=lib
USAGE=OUT
.
Library
:EDATAGRP.
.\
:EDATA.
.\
.\ -------------------------------------
.\ -------------------------------------
:LIST DEPTH='\'
MAXHEAD=4
LISTDEF=mbrconf
VIEW=mbrview.
:TOPINST.Press Enter to confirm your choices for 4=Remove.
:TOPINST.Press F12 to return to change your choices.
.\
.\ -------------------------------------
.\ Define the columns of the list
.\ -------------------------------------
:LISTCOL VAR=mopt
USAGE=OUT
HELP='confrmvm/option'
MAXWIDTH=6.
Opt
:LISTCOL VAR=mbr
USAGE=OUT
HELP='wrkmbr/mbr'
MAXWIDTH=1ð.
Member
:LISTCOL VAR=mtype
USAGE=OUT
HELP='wrkmbr/type'
MAXWIDTH=1ð.
Type
:LISTCOL VAR=mtext
USAGE=OUT
HELP='wrkmbr/text'
MAXWIDTH='\'.
Text
.\
.\ -------------------------------------
.\ -------------------------------------
.\
:ELIST.
:EPANEL.

Automatic Confirmation Processing
The UIM provides support to automatically perform confirmation processing. This
support is available when the UIM is in control of processing list options by speci-
fying ACTOR=UIM on the LIST tag that defines the action list.
To have the UIM perform confirmation processing for a list option, specify the name
of the confirmation panel on the CONFIRM attribute of the list action (LISTACT) tag
that defines the option to be confirmed. The following UIM source shows the
LISTACT tag for option 4 with the CONFIRM attribute specifying the name of the con-
firmation panel.
.\
:LISTACT OPTION=4
ACTFOR=LISTE
HELP='wrkmbr/rmvm'
CONFIRM=confrmvm
4=Remove
.\
For more information about defining a confirmation panel using the CONFIRM attri-
bute, see “LISTACT (List Action)” on page A-90.
When the UIM processes list options and finds an option with the CONFIRM attribute
specified, the UIM does the following:
1. Deletes the list specified on the LISTDEF attribute of the LIST tag in the confir-
mation panel.
2. Finds all entries in the action list with an option number the same as the option
number being confirmed, and copies these entries to the confirmation list.
3. Displays the confirmation panel.
4. Remembers that the option number has been confirmed by the user if the user
presses the Enter key. The confirmed options are processed in the order they
appear in the action list. No further confirmation processing is done for this
option number until the user types the option number for additional entries in
the action list.
5. Stops processing list options, if the user presses the F12 (Cancel) key, and
redisplays the action list panel showing the first entry with the option number
that was not confirmed.
Application Programming for Confirmation Processing

When ACTOR=UIM is specified on the LIST tag in the action list panel, there is no
application programming needed because the UIM performs all confirmation pro-
cessing.
When ACTOR=CALLER is specified on the LIST tag in the action list panel, the appli-
cation program that processes the list options should perform confirmation pro-
cessing similar to the UIM processing as described in “Automatic Confirmation
Processing.”

Creating a Data Presentation Panel
Data presentation panels are used to display user data or allow input of user data
in connection with an option on a list panel. When data input/output is scrollable
and low in frequency and volume, UIM simplifies creating consistent data presenta-
tion panels.
The following shows the coding to create the Display Member Description display
from the Work with File Members display.
The panel shown in Figure 16-7 shows an example of a data presentation panel.
This panel is shown as a result of using option 5 on the panel shown in
Figure 16-3 on page 16-14.
This panel contains two data presentation areas. The first area is using a vertical
layout with two layout columns. This area shows the file, library, and member
name. The second area also uses a vertical layout, but only one layout column.
This area shows the detail information for the member identified in the first area. If
you need more information on creating help for a data presentation panel, see
“Help in a Data Area” on page 19-9.
à Display Member Description .1/

ð
File . . . . . . . . : XXXXXXXXXX Member . . . . . . . : XXXXXXXXXX .2/
Type of file . . . . . . . . . . : PF .3/

Remote file . . . . . . . . . . . : No
Allow ODP sharing . . . . . . . . : Yes
Source type . . . . . . . . . . . : XXXXXXXXXX

Last source change date and time : 11/11/11 11:11:11
Creation date and time . . . . . : 11/11/11 11:11:11

Change date and time . . . . . . : 11/11/11 11:11:11
Number of records . . . . . . . . : 111111111

Deleted records . . . . . . . . . : 111111111
Data space size . . . . . . . . . : 111111111
Access path size . . . . . . . . : 111111111
.4/ More...
F3=Exit F12=Cancel .5/
á ñ
Figure 16-7. Example Data Presentation Panel
The second area is defined as a scrollable area because there are more items to
show than will fit on a display at one time. The UIM automatically handles scrolling
when the user presses the Page Up (Rolldown) or Page Down (Rollup) keys.
When the Page Down operation is performed, the contents of the second data
presentation area is replaced with the next set of items to show. This results in the
panel shown in Figure 16-8 on page 16-33.
Notice that the contents of the first area remain the same when the second area is
scrolled. The scroll operation only applies to one area of the panel based on the
location of the cursor. Also, because the first area is not defined as scrollable, the
scroll operation does not apply to that area even when the cursor position is within
the area.

à Display Member Description .1/
ð
File . . . . . . . . : XXXXXXXXXX Member . . . . . . . : XXXXXXXXXX .2/
Save date and time . . . . . . . : 11/11/11 11:11:11 .3/

Restore date and time . . . . . . : 11/11/11 11:11:11
Expiration date and time . . . . : 11/11/11 11:11:11
Number of days used . . . . . . . : 111111111

Date last used . . . . . . . . . : 11/11/11
Use reset date . . . . . . . . . : 11/11/11
Text . . . . . . . . . . . . . . : XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXX
.4/ Bottom
F3=Exit F12=Cancel .5/
á ñ
Figure 16-8. Example Data Presentation Panel after Scrolling
“Source for Example Data Presentation Panel” on page 16-35. These reference
numbers show which portions of the source define text and information which
appears on the panel.
.1/ The panel title is defined as text following the period of the display panel
(PANEL) tag.
.2/ In the first data area, the text for the file, library, and member name is defined
as text following the period of the data item (DATAI) tag. The file, library, and
member names are dialog variable values. Each dialog variable is defined
using the variable definition (VAR) tag. The name of the dialog variable is
specified on the VAR attribute of the DATAI tag.
The file name and library are formatted as a qualified object name because
GRPSEP=QINDENT is specified on the data group (DATAGRP) tag which sur-
rounds the two DATAI tags.
The dialog variables for the file name and library name and member name are
defined using the VAR tags at .A/, .B/, and .C/, respectively, shown on page
16-37.
This data presentation area is defined by specifying LAYOUT=2 on the DATA
tag that defines the area. This is shown at .D/ on page 16-42.
.3/ In the second data area, the text for each item is defined as text following the
period of the DATAI tag. The value for each item is a dialog variable value.
Each dialog variable is defined using the VAR tag. The name of the dialog
variable is specified on the VAR attribute of the DATAI tag.
Several items in the area show date and time values. This is done by speci-
fying the dialog variable for the date value on the VAR attribute of the DATAI
tag and specifying the dialog variable for the time value on the VAR attribute of
the data item extender (DATAIX) tag.

The date and time dialog variables are defined by specifying BASETYPE=DATE
and BASETYPE=TIME on the class definition (CLASS) tag used to define the
variables. This is shown at .E/ on page 16-36. The UIM formats the date
and time variables according to the date format and separator attributes and
the time separator attribute of the job.
.4/ The scroll information, More... and Bottom, is shown because the list area is
defined as scrollable. SCROLL=YES is specified on the DATA tag.
.5/ Each function key is defined using the key list item (KEYI) tag. The text,
including the function key name, is defined as text following the period of the
KEYI tag.
All function keys are defined by placing the KEYI tags between the key list
(KEYL) and EKEYL tags. The name specified on the NAME attribute of the
KEYL tag is also specified on the KEYL attribute of the PANEL tag.
Some function keys, such as Enter, do not have text specified for the KEYI
tag. In this case, no text appears on the display. However, all function keys
must be defined using the KEYI tag so the UIM knows what action is assigned
to each key and what help module to use when help is displayed for the func-
tion keys.
Required Tags for a Data Presentation Panel

Figure 16-9 on page 16-35 shows the required tags for creating a UIM data pres-
entation panel. For an example of the required and optional tags, see “Source for
Example Data Presentation Panel” on page 16-35.
Note: The tags in Figure 16-9 on page 16-35 require attributes. These attributes
are not shown. Without these attributes, the example in Figure 16-9 on
page 16-35 will not compile. For a description of the required attributes for
these required tags, see Appendix A, “UIM Panel Group Definition
Language.”

:PNLGRP. ─────────┐
:CLASS. ──┐ │
:VAR. │
. │
. │
. │
:KEYL. ──┐ │
:KEYI. │ │
:EKEYL. ──┘ │
:PANEL. ──────┐ │
:DATA. ───┐ │ │
:DATACOL. │ │ │
. │ │ │
. │ │ │
. │ │ │
:DATAI. │ │ │
. │ │ │
. │ │ │
. │ │ │
:EDATA. ───┘ │ │
. │ │
. │ │
. │ │
:EPANEL. ──────┘ │
. │
. │
. │
:HELP. ──┐ │
. │ │
. │ │
. │ │
:EHELP. ──┘ │
:EPNLGRP. ─────────┘
Figure 16-9. Required UIM Tags for a Data Presentation Panel
Source for Example Data Presentation Panel

This is a partial listing of the member T0011PN2 in source file QATTUIM in library
QUSRTOOL.
.\ -----------------------------------------------------------------
.\
.\
.\ -----------------------------------------------------------------
.\
.\ in panel group Tðð11HL2 searching the library list.
:IMPORT NAME='\'
PNLGRP=tðð11hl2.
.\
.\ -----------------------------------------------------------------
.\ -----------------------------------------------------------------
.\ -----------------
.\ Option
:CLASS NAME=optcl

BASETYPE='ACTION'
WIDTH=1.
:ECLASS.
.\ -----------------
.\ Object name
:CLASS NAME=namecl
:ECLASS.
.\ -----------------
.\ Library name
:CLASS NAME=libcl
:TL.
:ETL.
:ECLASS.
.\ -----------------
.\ File attribute
:CLASS NAME=attrcl
BASETYPE='CHAR 1ð'
CASE=UPPER.
:ECLASS.
.\ -----------------
.\ Descriptive text
:CLASS NAME=textcl
BASETYPE='IGC 5ð'
SUBST=QUOTED.
:ECLASS.
.\ -----------------
.\ Source type
:ECLASS.
.\ -----------------
.\ Date
:CLASS NAME=datecl .E/
BASETYPE='DATE'.
:TL.
:TI VALUE='" "'.
:TI VALUE='"ððððððð"'.
:ETL.
:ECLASS.
.\ -----------------
.\ Time
:CLASS NAME=timecl .E/
BASETYPE='TIME'.
:TL.
:TI VALUE='" "'.
:TI VALUE='"ðððððð"'.
:ETL.
:ECLASS.
.\ -----------------
.\ Yes or No flag class
:CLASS NAME=yesnocl
BASETYPE='CHAR 1'
WIDTH=3.
:TL.
:TI VALUE='"ð"'.No
:TI VALUE='"1"'.Yes
:ETL.
:ECLASS.
.\ -----------------

.\ Type of file
:CLASS NAME=typfcl
BASETYPE='CHAR 1'
WIDTH=2.
:TL.
:TI VALUE='"ð"'.PF
:TI VALUE='"1"'.LF
:ETL.
:ECLASS.
.\ -----------------
.\ Binary 31
:CLASS NAME=bin31
BASETYPE='BIN 31'.
:ECLASS.
..
.
..
.
.\ -----------------
:CLASS NAME=pad1cl
BASETYPE='CHAR 1'.
:ECLASS.
:CLASS NAME=pad2cl
BASETYPE='CHAR 2'.
:ECLASS.
:ECLASS.
:CLASS NAME=pad13cl
BASETYPE='CHAR 13'.
:ECLASS.
:CLASS NAME=pad48cl
BASETYPE='CHAR 48'.
:ECLASS.
:ECLASS.
.\
.\ -----------------------------------------------------------------
.\ -----------------------------------------------------------------
.\
.\ -------------------------------------
.\ -------------------------------------
.\ -----------------
.\ File name
:VAR NAME=file .A/
CLASS=namecl.
.\ -----------------
.\ Library name
:VAR NAME=lib .B/
CLASS=libcl.
.\ -----------------
.\ attributes
:VAR NAME=fattr
CLASS=attrcl.
.\ -----------------
.\
.\ -------------------------------------
.\ -------------------------------------
.\ -----------------

:VAR NAME=mopt
CLASS=optcl.
.\ -----------------
.\ Object name
:VAR NAME=mbr .C/
CLASS=namecl.
.\ -----------------
.\ member type
:VAR NAME=mtype
CLASS=attrcl.
.\ -----------------
.\ Descriptive text
:VAR NAME=mtext
CLASS=textcl.
.\
.\ -------------------------------------
.\ Variables for member description
.\ -------------------------------------
.\ -----------------
.\ Source type
:VAR NAME=mbrsrc
CLASS=srctypcl.
.\ -----------------
.\ Creation date
:VAR NAME=mbrcrtdat
CLASS=datecl.
.\ -----------------
.\ Creation time
:VAR NAME=mbrcrttim
CLASS=timecl.
.\ -----------------
.\ Member last source change date
:VAR NAME=mbrschgdat
CLASS=datecl.
.\ -----------------
.\ Member last source change time
:VAR NAME=mbrschgtim
CLASS=timecl.
.\ -----------------
.\ Member remote source file indicator
:VAR NAME=mbrsrcfil
CLASS=yesnocl.
.\ -----------------
.\ Member remote file indicator
:VAR NAME=mbrremote
CLASS=yesnocl.
.\ -----------------
.\ Member type of file
:VAR NAME=mbrtypf
CLASS=typfcl.
.\ -----------------
.\ Member ODP sharing
:VAR NAME=mbrodpshr
CLASS=yesnocl.
.\ -----------------
.\ Member current number of records
:VAR NAME=mbrcurrec
CLASS=bin31.
.\ -----------------
.\ Member number of deleted records
:VAR NAME=mbrdltrec
CLASS=bin31.
.\ -----------------

.\ Member data space size
:VAR NAME=mbrspcsiz
CLASS=bin31.
.\ -----------------
.\ Member access path size
:VAR NAME=mbracpsiz
CLASS=bin31.
.\ -----------------
.\ Number of database file members
:VAR NAME=mbrdbfmbrs
CLASS=bin31.
.\ -----------------
.\ Member change date.
:VAR NAME=mbrchgdat
CLASS=datecl.
.\ -----------------
.\ Member change time
:VAR NAME=mbrchgtim
CLASS=timecl.
.\ -----------------
.\ Member save date
:VAR NAME=mbrsavdat
CLASS=datecl.
.\ -----------------
.\ Member save time
:VAR NAME=mbrsavtim
CLASS=timecl.
.\ -----------------
.\ Member restore date
:VAR NAME=mbrrstdat
CLASS=datecl.
.\ -----------------
.\ Member restore time
:VAR NAME=mbrrsttim
CLASS=timecl.
.\ -----------------
.\ Member expiration date
:VAR NAME=mbrexpdat
CLASS=datecl.
.\ -----------------
.\ Member expiration time
:VAR NAME=mbrexptim
CLASS=timecl.
.\ -----------------
.\ Member number of days used
:VAR NAME=mbrdysuse
CLASS=bin31.
.\ -----------------
.\ Member date last used
:VAR NAME=mbrlastuse
CLASS=datecl.
.\ -----------------
.\ Member use reset date
:VAR NAME=mbrrsetdat
CLASS=datecl.
.\ -----------------
..
.
..
.
.\
.\ -------------------------------------

.\ -------------------------------------
:VAR NAME=pad1
CLASS=pad1cl.
:VAR NAME=pad2
CLASS=pad2cl.
:VAR NAME=pad1ð
CLASS=pad1ðcl.
:VAR NAME=pad13
CLASS=pad13cl.
:VAR NAME=pad48
CLASS=pad48cl.
:VAR NAME=pad5ð
CLASS=pad5ðcl.
..
.
The first VARRCD tags in member Tðð11PN2 are not shown here
..
.
.\
.\ -----------------------------------------------------------------
.\ -----------------------------------------------------------------
NOPUT='pad13'
.
.\
.\ -----------------------------------------------------------------
.\ Define a variable record for member description.
.\ Retrieve Member Description API (QUSRMBRD) format name MBRDð2ðð.
.\ -----------------------------------------------------------------
:VARRCD NAME=mbrdð2ðð
VARS='pad48 mbrsrc mbrcrtdat mbrcrttim mbrschgdat'
VARS='mbrschgtim pad5ð mbrsrcfil mbrremote mbrtypf'
VARS='mbrodpshr pad2 mbrcurrec mbrdltrec mbrspcsiz'
VARS='mbracpsiz mbrdbfmbrs mbrchgdat mbrchgtim mbrsavdat'
VARS='mbrsavtim mbrrstdat mbrrsttim mbrexpdat mbrexptim'
VARS='mbrdysuse mbrlastuse mbrrsetdat'
NOPUT='pad48 pad5ð pad2'
NOGET='pad48 pad5ð pad2'
.
..
.
..
.
..
.
All LISTDEF tags in member Tðð11PN2 are not shown here
..
.
.\
.\ -----------------------------------------------------------------
.\ -----------------------------------------------------------------
.\ -----------------
:COND NAME=pf
EXPR='fattr="PF "'.
..
.
..
.

.\ -----------------
.\ Condition for source files
:COND NAME=srcpf
EXPR='mbrsrcfil="1"'.
.\ -----------------
.\ Condition for member in a physical file
:COND NAME=mbrpf
EXPR='mbrtypf="ð"'.
.\ -----------------
.\ Condition for member in a logical file
:COND NAME=mbrlf
EXPR='mbrtypf="1"'.
..
.
..
.
..
.
All TT tags in member Tðð11PN2 are not shown here
..
.
..
.
All MBAR tags in member Tðð11PN2 are not shown here
..
.
..
.
The first KEYL tags in member Tðð11PN2 are not shown here
..
.
.\
.\ -----------------------------------------------------------------
.\ Define basic key for panels without a command line
.\ or multiple views.
.\ -----------------------------------------------------------------
:KEYL NAME=basickeys .5/
HELP=keyl.
:KEYI KEY=F1
HELP=helpf1
ACTION=HELP.
:KEYI KEY=F3
HELP=exit
ACTION='EXIT SET'
VARUPD=NO.
F3=Exit
:KEYI KEY=F12
HELP=cancel
ACTION='CANCEL SET'
VARUPD=NO.
F12=Cancel
:KEYI KEY=F24
HELP=morekeys
ACTION=MOREKEYS.
F24=More keys
:KEYI KEY=ENTER
HELP=enter
ACTION=ENTER.
:KEYI KEY=HELP
HELP=help
ACTION=HELP.
:KEYI KEY=PAGEDOWN
HELP=pagedown
ACTION=PAGEDOWN.
:KEYI KEY=PAGEUP
HELP=pageup
ACTION=PAGEUP.
:KEYI KEY=PRINT
HELP=print

ACTION=PRINT.
:EKEYL.
..
.
The first PANEL tags in member Tðð11PN2 are not shown here
..
.
.\
.\ -----------------------------------------------------------------
.\ Define Display Member Description panel
.\ -----------------------------------------------------------------
:PANEL NAME=dspmbr
HELP='dspmbr/'
KEYL=basickeys .5/
TOPSEP=SPACE.
Display Member Description .1/
.\
.\ -------------------------------------
.\ library/file and member name whose description is displayed.
.\ -------------------------------------
:DATA DEPTH=3
SCROLL=NO
LAYOUT=2 .D/
BOTSEP=SPACE
COMPACT
.
.\ -------------------------------------
:DATACOL WIDTH=22.
:DATACOL WIDTH='\'.
.\ -------------------------------------
HELP='dspmbr/filelib'
COMPACT
.
:DATAI VAR=file .2/
USAGE=OUT
.
File
:DATAI VAR=lib .2/
USAGE=OUT
.
Library
:EDATAGRP.
.\ -------------------------------------
.\ Display member name
:DATAI VAR=mbr .2/
HELP='dspmbr/mbr'
USAGE=OUT
.
Member
.\
:EDATA.
.\
.\ -------------------------------------
.\ member definition.
.\ -------------------------------------
:DATA DEPTH='\'
SCROLL=YES .4/
LAYOUT=1

BOTSEP=SPACE
.
.\ -------------------------------------
:DATACOL WIDTH=35.
:DATACOL WIDTH='\'.
.\ -------------------------------------
.\ Display information about the file
:DATAGRP GRPSEP=NONE
COMPACT
.
.\ -------------------------------------
.\ Display type of file
:DATAI VAR=mbrtypf .3/
HELP='dspmbr/mbrtypf'
USAGE=OUT
.
Type of file
.\ -------------------------------------
.\ Display remote file
:DATAI VAR=mbrremote
HELP='dspmbr/mbrremote'
USAGE=OUT
.
Remote file
.\ -------------------------------------
.\ Display ODP sharing
:DATAI VAR=mbrodpshr
HELP='dspmbr/mbrodpshr'
USAGE=OUT
.
Allow ODP sharing
:EDATAGRP.
.\ -------------------------------------
.\ Display information only if file is a source file
COMPACT
COND=srcpf
.
.\ -------------------------------------
.\ Display source type
:DATAI VAR=mbrsrc
HELP='dspmbr/mbrsrc'
USAGE=OUT
.
Source type
.\ -------------------------------------
.\ Display last source change date and time
:DATAI VAR=mbrschgdat
HELP='dspmbr/mbrschgdt'
USAGE=OUT
.
Last source change date and time
:DATAIX VAR=mbrschgtim
USAGE=OUT
.
:EDATAGRP.
.\ -------------------------------------
.\ Display create and change information
COMPACT

.
.\ -------------------------------------
.\ Display creation date and time
:DATAI VAR=mbrcrtdat
HELP='dspmbr/mbrcrtdt'
USAGE=OUT
.
Creation date and time
:DATAIX VAR=mbrcrttim
USAGE=OUT
.
.\ -------------------------------------
.\ Display change date and time
:DATAI VAR=mbrchgdat
HELP='dspmbr/mbrchgdt'
USAGE=OUT
.
Change date and time
:DATAIX VAR=mbrchgtim
USAGE=OUT
.
:EDATAGRP.
.\ -------------------------------------
.\ Display information about the size of the member
COMPACT
.
.\ -------------------------------------
.\ Display current records for physical file member
:DATAI VAR=mbrcurrec
COND=mbrpf
HELP='dspmbr/mbrcurrec'
USAGE=OUT
.
Number of records
.\ -------------------------------------
.\ Display current index entries for logical file member
:DATAI VAR=mbrcurrec
COND=mbrlf
HELP='dspmbr/mbrcurrec'
USAGE=OUT
.
Number of index entries
.\ -------------------------------------
.\ Display deleted records
:DATAI VAR=mbrdltrec
HELP='dspmbr/mbrdltrec'
USAGE=OUT
.
Deleted records
.\ -------------------------------------
.\ Display data space size for physical file member
:DATAI VAR=mbrspcsiz
COND=mbrpf
HELP='dspmbr/mbrspcsiz'
USAGE=OUT
.
Data space size
.\ -------------------------------------
.\ Display access path size
:DATAI VAR=mbracpsiz
HELP='dspmbr/mbracpsiz'
USAGE=OUT

.
Access path size
.\ -------------------------------------
.\ Display database file members for logical file member
:DATAI VAR=mbrdbfmbrs
COND=mbrlf
HELP='dspmbr/mbrdbfmbrs'
USAGE=OUT
.
Number of database file members
:EDATAGRP.
.\ -------------------------------------
.\ Display save restore information
COMPACT
.
.\ -------------------------------------
.\ Display save date and time
:DATAI VAR=mbrsavdat .3/
HELP='dspmbr/mbrsavdt'
USAGE=OUT
.
Save date and time
:DATAIX VAR=mbrsavtim .3/
USAGE=OUT
.
.\ -------------------------------------
.\ Display restore date and time
:DATAI VAR=mbrrstdat
HELP='dspmbr/mbrrstdt'
USAGE=OUT
.
Restore date and time
:DATAIX VAR=mbrrsttim
USAGE=OUT
.
:EDATAGRP.
.\ -------------------------------------
.\ Display expiration date
:DATAI VAR=mbrexpdat
HELP='dspmbr/mbrexpdt'
USAGE=OUT
.
Expiration date and time
:DATAIX VAR=mbrexptim
USAGE=OUT
.
.\ -------------------------------------
.\ Display usage information
COMPACT
.
.\ -------------------------------------
.\ Display number of days used
:DATAI VAR=mbrdysuse
HELP='dspmbr/mbrdysuse'
USAGE=OUT
.
Number of days used
.\ -------------------------------------
.\ Display date last used
:DATAI VAR=mbrlastuse
HELP='dspmbr/mbrlastuse'
USAGE=OUT

.
Date last used
.\ -------------------------------------
.\ Display use reset date
:DATAI VAR=mbrrsetdat
HELP='dspmbr/mbrrsetdat'
USAGE=OUT
.
Use reset date
:EDATAGRP.
.\ -------------------------------------
.\ Display text description
:DATAI VAR=mtext
HELP='dspmbr/text'
USAGE=OUT
.
Text
.\
:EDATA.
.\
:EPANEL.
..
.
..
.
.\
.\ -----------------------------------------------------------------
.\ -----------------------------------------------------------------
:EPNLGRP.
Application Programming for a Data Presentation Panel

An example of an application program to display the data presentation panel shown
in Figure 16-7 on page 16-32 can be found in member T0011CP3 in file
QATTSYSC in library QUSRTOOL. This is an ILE C program which calls the
appropriate UIM application programming interfaces (APIs) to display the panel.
This program is called by the UIM to process option 5 (Display) from the example
list panel shown in Figure 16-3 on page 16-14.
A general example of an RPG application written using the UIM APIs can be found
in QUSRTOOL. Refer to member T0011INF in source file QATTINFO in library
QUSRTOOL.
To write a program in any language to display the example data presentation panel,
the program should do the following:
1. If the program is not called by the UIM to process option 5 from the example
list panel shown in Figure 16-3 on page 16-14, the program should first do the
following. For example, this would be the case if the user could display the
member description directly by using a CL command.
a. Call the Open Display Application (QUIOPNDA) API to open the panel
group. The panel group must already be created using the Create Panel
Group (CRTPNLGRP) command.
b. Set up a buffer containing the values for the following dialog variables:
FILE A CHAR 10 variable which is the name of the file.
LIB A CHAR 10 variable which is the name of the library where the
file resides.

FATTR A CHAR 10 variable which is the file attribute of the file. This
variable is used to condition on list options which are only allowed
for physical files.
c. Call the Put Dialog Variable (QUIPUTV) API to change the contents of the
dialog variables using variable record FILELIB and the buffer initialized in
the previous step.
d. Set up a buffer containing values for the following dialog variables:
MBR A CHAR 10 variable which is the member name.
MTYPE A CHAR 10 variable which is the member type.
MTEXT A CHAR 50 variable which is the descriptive text for the
member.
Note: The layout of this buffer is designed to match with the layout of the
entries in the user space returned by the QUSLMBR API. There-
fore, instead of setting up a buffer, the application program can
pass the buffer as it exists in the user space.
e. Call the Put Dialog Variable (QUIPUTV) API to change the contents of the
dialog variables using variable record MBRL0200 and the buffer initialized
in the previous step.
Note: If the program is called by the UIM to process option 5 from the
example list panel, the file name and library name were already set by
the application program before displaying the list panel. Also, when the
UIM performs list option processing, the MBR, MTYPE, and MTEXT
dialog variables will already be set to the values from the list entry
which calls the application program to process option 5.
2. Set up a buffer containing values for the following dialog variables:
MBRSRC A CHAR 10 variable which is the source type for the
member.
MBRCRTDAT A CHAR 7 variable which is the creation date for the
member in the form required for BASETYPE=DATE dialog
variables.
MBRCRTTIM A CHAR 6 variable which is the creation time for the
member in the form required for BASETYPE=TIME dialog var-
iables.
MBRSCHGDAT A CHAR 7 variable which is the source changed date for
the member in the form required for BASETYPE=DATE dialog
variables.
MBRSCHGTIM A CHAR 6 variable which is the source changed time for
the member in the form required for BASETYPE=TIME dialog
variables.
MBRSRCFIL A CHAR 1 variable indicating whether or not the member is
in a source file ("0"=no, "1"=yes).

MBRREMOTE A CHAR 1 variable indicating whether or not the member is
in a remote file ("0"=no, "1"=yes).
MBRTYPF A CHAR 1 variable indicating whether the member is in a
physical or logical file ("0"=physical "1"=logical).
MBRODPSHR A CHAR 1 variable indicating whether or not ODP sharing
is allowed for the member ("0"=no, "1"=yes).
MBRCURREC A BINARY 4 variable containing the number of records in
the member.
MBRDLTREC A BINARY 4 variable containing the number of deleted
records in the member.
MBRSPCSIZ A BINARY 4 variable containing the size of the space for
the member.
MBRACPSIZ A BINARY 4 variable containing the access path size for
the member.
MBRDBFMBRS A BINARY 4 variable containing the number of database
file members for this logical file member.
MBRCHGDAT A CHAR 7 variable which is the last changed date for the
variables.
MBRCHGTIM A CHAR 6 variable which is the last changed time for the
iables.
MBRSAVDAT A CHAR 7 variable which is the date the member was last
saved in the form required for BASETYPE=DATE dialog vari-
ables.
MBRSAVTIM A CHAR 6 variable which is the time the member was last
saved in the form required for BASETYPE=TIME dialog vari-
ables.
MBRRSTDAT A CHAR 7 variable which is the date the member was last
restored in the form required for BASETYPE=DATE dialog
variables.
MBRRSTTIM A CHAR 6 variable which is the time the member was last
restored in the form required for BASETYPE=TIME dialog var-
iables.
MBREXPDAT A CHAR 7 variable which is the date of expiration for the
variables.
MBREXPTIM A CHAR 6 variable which is the time of expiration for the
iables.
MBRDYSUSE A BINARY 4 variable containing the number of days the
member has been used.
MBRLASTUSE A CHAR 7 variable which is the date the member was last
used in the form required for BASETYPE=DATE dialog vari-
ables.

MBRRSETDAT A CHAR 7 variable which is the date the use information
was reset for the member in the form required for
BASETYPE=DATE dialog variables.
Note: The layout of this buffer is designed to match with the layout of the data
returned by the Retrieve Member Description (QUSRMBRD) API using
format name MBRD0200. Therefore, instead of setting up a buffer, the
application program can pass the buffer as it is returned by the API.
dialog variables using variable record MBRD0200 and the buffer initialized in
the previous step.
4. Call the Display Panel (QUIDSPP) API to display panel WRKMBR. The UIM
returns control to the application when one of the following occurs:
The user presses the Enter key without typing any list options or a
command on the command line. The program variable passed as the func-
tion requested parameter to the QUIDSPP API is set to 500. This is done
because ENTER='RETURN 500' is specified on the PANEL tag which defines
the WRKMBR panel.
The user presses the F12 (Cancel) key. The program variable passed as
the function requested parameter to the QUIDSPP API is set to -8. This is
the value defined for the CANCEL dialog command.
The user presses the F3 (Exit) key. The program variable passed as the
function requested parameter to the QUIDSPP API is set to -4. This is the
value defined for the CANCEL dialog command.
5. If the program is not called by the UIM to process option 5 from the example
list panel shown in Figure 16-3 on page 16-14, the program should do the fol-
lowing.
a. Call the Close Application (QUICLOA) API to close the UIM application.
This frees up the system resources being used by the UIM application.
Data Entry Panel

A data entry panel is a form of data presentation panel where the user is allowed to
enter new values for one or more of the dialog variables displayed. The USAGE
attribute of the data item (DATAI) and data item extender (DATAIX) tags defines
whether or not the user is allowed to enter a new value for the dialog variable dis-
played by the tag.
When USAGE=INOUT is specified, the user is allowed to enter a new value for the
dialog variable. For data areas using a vertical layout, the leader dots following the
descriptive text for the item end with a period instead of a colon. A colon is used
for data items which do not allow input.
When the UIM returns control from the Display Panel (QUIDSPP) API and the func-
tion requested parameter contains the value specified for the RETURN dialog
command on the ENTER attribute of the display panel (PANEL) tag, the application
program uses the Get Dialog Variable (QUIGETV) API to retrieve the values for the
dialog variables changed by the user.

Creating a Panel with a Menu Bar
A menu bar can be defined for any full-screen panel. The menu bar acts as an
extension of the panel and contains definitions of choices for the menu bar. Each
choice in the menu bar has a pull-down menu defined. When the user selects the
menu bar choice, the UIM displays the pull-down menu in a window below the
menu bar. Each choice within the pull-down menu represents an action which can
be performed. In this example, a Work with File Members panel is defined using a
menu bar. This panel is functionally similar to the panel shown in “Creating a List
Panel” on page 16-13. Although the panel appears slightly different from the
example list panel, this example panel using a menu bar performs the same func-
tion.
The panel shown in Figure 16-10 shows an example of an action list panel which
also has a menu bar. This example explains how the menu bar is defined and how
it interacts with the rest of the panel definition. This example does not describe
how to define the action list portion of the panel. For more information on creating
an action list, see “Creating a List Panel” on page 16-13. If you need more infor-
mation on creating help for a menu bar area, see “Help in a Menu Bar Area” on
page 19-13.
The example panel is shown with a pull-down menu displayed. The pull-down is
active because the user selected entries in the list and pressed the Enter key.
à Member View Help .1/

ð
-.-----------------------------------.------------------------------------------
: 3. Copy... .2/ : File Members
: 4. Remove... :
: 5. Display... : F4 for list
: : library, \CURLIB, \LIBL
: 7. Reorganize :
: 8. Member description... :
: 9. Clear... :
: :
: 9ð. Exit .3/ F3 : XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
:...................................: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXX XXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
/ XXXXXXXXXX XXXXXXXXXX XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
More...
===>
F3=Exit F4=Prompt F9=Retrieve F1ð=Actions F12=Cancel
á ñ
Figure 16-10. Example Panel with a Menu Bar
“Source for Example Panel with a Menu Bar” on page 16-53. These reference
numbers show which portions of the source define text and information which
appears on the panel.
.1/ Each choice in the menu bar is defined using a menu bar choice (MBARC)
tag. The choice shown on the panel is defined as text following the period of
the MBARC tag.

All choices for a menu bar are defined by placing the MBARC tags between
the menu bar (MBAR) and EMBAR tags. The name specified on the NAME
attribute of the MBAR tag is also specified on the MBAR attribute of the PANEL
tag.
.2/ Each option in the pull-down menu is defined using the pull-down field choice
(PDFLDC) tag. The option number is defined using the OPTION attribute and
the text following the option number is defined as text following the period of
the PDFLDC tag.
All choices for a pull-down menu are defined by placing the PDFLDC tags
between the pull-down field (PDFLD) and EPDFLD tags. The PDFLDC and
EPDFLDC tags are placed between a MBARC and EMBARC tag.
.3/ An accelerator key description shown along the right side of the pull-down
menu is defined as text following the period of the PDACCEL tag. An accel-
erator is a key which performs the same function as an option in a pull-down
menu. The PDACCEL tag is placed immediately after the PDFLDC tag for
the option to which the accelerator applies.
From this panel, the application user can perform operations against entries in the
list using either of the following methods:
When the user selects entries in the list and presses the Enter key, the UIM
displays the pull-down menu for the member choice in the menu bar. This is
done because SELECT=PULLDOWN is specified on the PANEL tag shown at
.A/ on page 16-60.
When the user selects option 3, 4, 5, 7, 8 or 9 from the pull-down menu, the
UIM performs the action defined for that option once for each list entry selected
by the user. The UIM does this because ACTFOR=LIST is specified on the
PDFLDC tag at .B/ on page 16-57. The UIM makes these options unavailable
when the users displays the pull-down menu without selecting any entries in
the list.
When the user selects option 90 from the pull-down menu, the UIM returns
control to the application program that displayed the panel. The UIM does this
because ACTFOR=PANEL is specified on the PDFLDC tag at .C/ on page 16-58.
Because EXIT is specified for the ACTION attribute on the PDFLDC tag, the UIM
returns control to the calling program with an indication that the user requested
Exit.
When the user types option numbers next to the desired list entries and
presses the Enter key, the UIM performs the action for each option. The UIM
does this because ACTOR=UIM is specified on the list area (LIST) tag at .D/ on
page 16-61 and a list action (LISTACT) tag at .E/ on page 16-62 specifies the
action for the UIM to perform for each option number.
Note that in this case, no text is shown on the panel describing the option
numbers for the list. This is because no text is specified following the period of
the LISTACT tags. The primary interface defined for this panel is to select
entries in the list and then choose an action from a pull-down menu. The list
option numbers are available as a faster alternative for more experienced
users. Although the list option numbers do not appear on the panel, they are
described in the help shown when the Help key is pressed with the cursor posi-
tioned in the input column of the list.
For this example, the actions for the option numbers in the pull-down menu are
the same as the actions for the option numbers that can be entered in the list.

This design is recommended for a consistent user interface, but the UIM does
not prevent the application developer from defining an action in a pull-down
menu that is different from the action for a list option with the same option
number.
Required Tags for a Panel with a Menu Bar

Figure 16-11 shows the required tags for creating a UIM panel with a menu bar.
For an example of the required and optional tags, see “Source for Example Panel
with a Menu Bar” on page 16-53.
Note: The tags in Figure 16-11 require attributes. These attributes are not
shown. Without these attributes, the example in Figure 16-11 will not
compile. For a description of the required attributes for these required tags,
see Appendix A, “UIM Panel Group Definition Language.”
:PNLGRP. ──────────────┐
. │
. │
. │
:CLASS. ──┐ │
:VAR. │
. │
. │
. │
:MBAR. ──────────┐ │
:MBARC. ─────┐ │ │
:PDFLD. ──┐ │ │ │
:PDFLDC. │ │ │ │
. │ │ │ │
. │ │ │ │
. │ │ │ │
:EPDFLD. ──┘ │ │ │
:EMBARC. ─────┘ │ │
. │ │
. │ │
. │ │
:EMBAR. ──────────┘ │
. │
. │
. │
:KEYL. ──┐ │
:KEYI. │ │
:EKEYL. ──┘ │
:PANEL. ──┐ │
. │ │
. │ │
. │ │
:EPANEL. ──┘ │
. │
. │
. │
:HELP. ──┐ │
. │ │
. │ │
. │ │
:EHELP. ──┘ │
:EPNLGRP. ──────────────┘
Figure 16-11. Required UIM Tags for a Panel with a Menu Bar

Source for Example Panel with a Menu Bar
This is a partial listing of member T0011PN2 in source file QATTUIM in library
QUSRTOOL.
.\ -----------------------------------------------------------------
.\
.\
.\ -----------------------------------------------------------------
.\
.\ in panel group Tðð11HL2 found by searching the library list.
:IMPORT NAME='\'
PNLGRP=tðð11hl2.
.\
.\ -----------------------------------------------------------------
.\ -----------------------------------------------------------------
.\ -----------------
.\ Option
:CLASS NAME=optcl
BASETYPE='ACTION'
WIDTH=1.
:ECLASS.
.\ -----------------
.\ Object name
:CLASS NAME=namecl
:ECLASS.
.\ -----------------
.\ Library name
:CLASS NAME=libcl
:TL.
:ETL.
:ECLASS.
.\ -----------------
.\ File attribute
:CLASS NAME=attrcl
BASETYPE='CHAR 1ð'
CASE=UPPER.
:ECLASS.
.\ -----------------
.\ Descriptive text
:CLASS NAME=textcl
BASETYPE='IGC 5ð'
SUBST=QUOTED.
:ECLASS.
.\ -----------------
.\ Source type

:ECLASS.
..
.
..
.
.\ -----------------
:CLASS NAME=parmcl
BASETYPE='CHAR 255'.
:ECLASS.
.\ -----------------
.\ Exit program specification for CALL dialog command
:CLASS NAME=exitcl
:ECLASS.
.\ -----------------
.\ View number
:CLASS NAME=vwnumcl
BASETYPE='BIN 15'.
:ECLASS.
.\ -----------------
:CLASS NAME=pad1cl
BASETYPE='CHAR 1'.
:ECLASS.
:CLASS NAME=pad2cl
BASETYPE='CHAR 2'.
:ECLASS.
:ECLASS.
:CLASS NAME=pad13cl
BASETYPE='CHAR 13'.
:ECLASS.
:CLASS NAME=pad48cl
BASETYPE='CHAR 48'.
:ECLASS.
:ECLASS.
.\
.\ -----------------------------------------------------------------
.\ -----------------------------------------------------------------
.\
.\ -------------------------------------
.\ -------------------------------------
.\ -----------------
.\ File name
:VAR NAME=file
CLASS=namecl.
.\ -----------------
.\ Library name
:VAR NAME=lib
CLASS=libcl.
.\ -----------------

.\ attributes
:VAR NAME=fattr
CLASS=attrcl.
.\ -----------------
.\
.\ -------------------------------------
.\ -------------------------------------
.\ -----------------
:VAR NAME=mopt
CLASS=optcl.
.\ -----------------
.\ Object name
:VAR NAME=mbr
CLASS=namecl.
.\ -----------------
.\ member type
:VAR NAME=mtype
CLASS=attrcl.
.\ -----------------
.\ Descriptive text
:VAR NAME=mtext
CLASS=textcl.
..
.
..
.
.\
.\ -------------------------------------
.\ Variable for command line parameters
.\ -------------------------------------
.\ -----------------
:VAR NAME=parms
CLASS=parmcl.
.\
.\ -------------------------------------
.\ Variables for specifying CALL/exit programs
.\ -------------------------------------
.\ -----------------
.\ Program to call for all UIM exits
:VAR NAME=exitpgm
CLASS=exitcl.
.\
.\ -------------------------------------
.\ Variables for controlling list views
.\ -------------------------------------
.\ -----------------
.\ View number for list of members
:VAR NAME=mbrview
CLASS=vwnumcl.
..
.
..
.
.\
.\ -------------------------------------

.\ -------------------------------------
:VAR NAME=pad1
CLASS=pad1cl.
:VAR NAME=pad2
CLASS=pad2cl.
:VAR NAME=pad1ð
CLASS=pad1ðcl.
:VAR NAME=pad13
CLASS=pad13cl.
:VAR NAME=pad48
CLASS=pad48cl.
:VAR NAME=pad5ð
CLASS=pad5ðcl.
.\
.\ -----------------------------------------------------------------
.\ Define a variable record for file, library and file attribute
.\ -----------------------------------------------------------------
:VARRCD NAME=filelib
VARS='file lib fattr'
NOGET='fattr'
.
.\
.\ -----------------------------------------------------------------
.\ Define a variable record for exit program
.\ -----------------------------------------------------------------
:VARRCD NAME=exitprog
VARS='exitpgm'
.
.\
.\ -----------------------------------------------------------------
.\ -----------------------------------------------------------------
NOPUT='pad13'
.
..
.
..
.
.\
.\
.\ -----------------------------------------------------------------
.\ Define a list of members
.\ -----------------------------------------------------------------
:LISTDEF NAME=mbrlist
VARS='mopt mbr mtype mtext'
MSGID=USRð1ð1.
..
.
Additional LISTDEF tags in member Tðð11PN2 are not shown here
..

.
.\
.\ -----------------------------------------------------------------
.\ -----------------------------------------------------------------
.\ -----------------
:COND NAME=pf
EXPR='fattr="PF "'.
.\ -----------------------------------------------------------------
.\ Conditions for views of members list
:COND NAME=mbrview1
EXPR='mbrview=ð'.
:COND NAME=mbrview2
EXPR='mbrview=1'.
..
.
..
.
..
.
All TT tags in member Tðð11PN2 are not shown here
..
.
.\
.\ -----------------------------------------------------------------
.\ Define menu bar for work with members panel
.\ -----------------------------------------------------------------
:MBAR NAME=mbarmbr .1/
HELP='mbarmbr/'
.
:MBARC HELP='mbarmbr/member'
.
Member .1/
:PDFLD.
:PDFLDC OPTION=3
ACTFOR=LIST .B/
HELP='mbarmbr/cpyf'
ACTION='CMD CPYF ?\FROMFILE(&lib./&file.)'
ACTION=' ?\FROMMBR(&mbr.) &parms.'
.
Copy... .2/
.\
:PDFLDC OPTION=4
ACTFOR=LIST
HELP='mbarmbr/rmvm'
ACTION='CMD RMVM FILE(&lib./&file.) MBR(&mbr.)'
.\ CONFIRM=confrmvmmb
USREXIT='CALL exitpgm'
.
Remove...
.\
:PDFLDC OPTION=5
COND=pf
ACTFOR=LIST
HELP='mbarmbr/dsppfm'
ACTION='CMD DSPPFM FILE(&lib./&file.) MBR(&mbr.) &parms.'
.
Display...
.\
:PDFLDC OPTION=7

COND=pf
ACTFOR=LIST
HELP='mbarmbr/rgzm'
ACTION='CMD RGZPFM FILE(&lib./&file.) MBR(&mbr.)'
.
Reorganize
.\
:PDFLDC OPTION=8
ACTFOR=LIST
HELP='mbarmbr/dspfd'
ACTION='CALL exitpgm'
.
Member description...
.\
:PDFLDC OPTION=9
COND=pf
ACTFOR=LIST
HELP='mbarmbr/clrm'
.\ CONFIRM=confclrmmb
ACTION='CMD CLRPFM FILE(&lib./&file.) MBR(&mbr.)'
.
Clear...
.\
:PDFLDC OPTION=9ð
ACTFOR=PANEL .C/
HELP='mbarmbr/exit'
ACTION='EXIT SET'
VARUPD=NO
.
Exit
:PDACCEL.F3 .3/
:EPDFLD.
:EMBARC.
.\
:MBARC HELP='mbarmbr/view'
.
View
:PDFLD.
:PDFLDC OPTION=1
ACTFOR=PANEL
HELP='mbarmbr/view2'
AVAIL=mbrview1
ACTION=CHGVIEW
.
Names only
:PDACCEL.F11
:PDFLDC OPTION=2
ACTFOR=PANEL
HELP='mbarmbr/view1'
AVAIL=mbrview2
ACTION=CHGVIEW
.
Names and descriptions
:PDACCEL.F11
:EPDFLD.
:EMBARC.
.\
:MBARC HELP='mbarmbr/help'

.
Help
:PDFLD.
:PDFLDC OPTION=1
ACTFOR=PANEL
HELP='mbarmbr/helphelp'
ACTION=helphelp
.
Help for help...
:PDFLDC OPTION=2
ACTFOR=PANEL
HELP='mbarmbr/exthelp'
ACTION=exthelp
.
Extended help...
:PDFLDC OPTION=3
ACTFOR=PANEL
HELP='mbarmbr/keyshelp'
ACTION=keyshelp
.
Keys help...
:PDFLDC OPTION=4
ACTFOR=PANEL
HELP='mbarmbr/about'
ACTION='DSPHELP about'
.
About...
:EPDFLD.
:EMBARC.
:EMBAR.
..
.
The first KEYL tags in member Tðð11PN2 are not shown here
..
.
.\
.\
.\ -----------------------------------------------------------------
.\ Define keys for work with members panel with a menu bar
.\ The keys are the same but some do not have descriptions
.\ -----------------------------------------------------------------
:KEYL NAME=mbrkeysmb
HELP=keyl.
:KEYI KEY=F1
HELP=helpf1
ACTION=HELP.
:KEYI KEY=F3
HELP=exit
ACTION='EXIT SET'
VARUPD=NO.
F3=Exit
:KEYI KEY=F4
HELP=prompt
ACTION=PROMPT
PRIORITY=3ð.
F4=Prompt
:KEYI KEY=F9
HELP=retrieve
ACTION=RETRIEVE

PRIORITY=35.
F9=Retrieve
:KEYI KEY=F1ð
HELP=actions
ACTION=ACTIONS
PRIORITY=4ð.
F1ð=Actions
:KEYI KEY=F11
HELP=mbrviewname
ACTION=CHGVIEW
COND=mbrview1.
:KEYI KEY=F11
HELP=mbrviewdesc
ACTION=CHGVIEW
COND=mbrview2.
:KEYI KEY=F12
HELP=cancel
ACTION='CANCEL SET'
VARUPD=NO.
F12=Cancel
:KEYI KEY=F24
HELP=morekeys
ACTION=MOREKEYS.
F24=More keys
:KEYI KEY=ENTER
HELP=enter
ACTION=ENTER.
:KEYI KEY=HELP
HELP=help
ACTION=HELP.
:KEYI KEY=PAGEDOWN
HELP=pagedown
ACTION=PAGEDOWN.
:KEYI KEY=PAGEUP
HELP=pageup
ACTION=PAGEUP.
:KEYI KEY=PRINT
HELP=print
ACTION=PRINT.
:EKEYL.
..
.
Additional KEYL tags in member Tðð11PN2 are not shown here
..
.
..
.
The first PANEL tags in member Tðð11PN2 are not shown here
..
.
.\
.\
.\ -----------------------------------------------------------------
.\ Define Work with Members panel with a menu bar to process options
.\ -----------------------------------------------------------------
:PANEL NAME=wrkmbrmbar
HELP='wrkmbr/'
MBAR=mbarmbr .1/
KEYL=mbrkeysmb
SELECT=PULLDOWN .A/

TOPSEP=SPACE.
Work with File Members
.\
.\ -------------------------------------
.\ -------------------------------------
:DATA DEPTH=3
SCROLL=NO
LAYOUT=1
BOTSEP=SPACE
COMPACT
.
.\ -------------------------------------
:DATACOL WIDTH=22.
:DATACOL WIDTH=12.
:DATACOL WIDTH='\'.
.\ -------------------------------------
COMPACT
.
:DATAI VAR=file
USAGE=INOUT
CSRLOC=NO
PROMPT='CALL exitpgm'
.
File
:DATAC.F4 for list
:DATAI VAR=lib
USAGE=INOUT
CSRLOC=NO
.
Library
:DATAC.library, \CURLIB, \LIBL
:EDATAGRP.
.\
:EDATA.
.\
.\ -------------------------------------
.\ -------------------------------------
:LIST DEPTH='\'
LISTDEF=mbrlist
ACTOR=UIM .D/
MAXHEAD=4
MAXACTL=3
VIEW=mbrview
PARMS=parms
BOTSEP=SPACE.
:TOPINST.Select members using /, press Enter.
.\
.\ -------------------------------------

.\ -------------------------------------
:LISTACT OPTION=3 .E/
NOCMD=PROMPT
HELP='wrkmbr/cpyf'
ENTER='CMD CPYF ?\FROMFILE(&lib./&file.)'
ENTER=' ?\FROMMBR(&mbr.) &parms.'
PROMPT='CMD ?CPYF ?\FROMFILE(&lib./&file.)'
PROMPT=' ?\FROMMBR(&mbr.) &parms.'.
.\
:LISTACT OPTION=4
HELP='wrkmbr/rmvm'
.\ CONFIRM=confrmvmmb
.\
:LISTACT OPTION=5
COND=pf
HELP='wrkmbr/dsppfm'
ENTER='CMD DSPPFM FILE(&lib./&file.) MBR(&mbr.) &parms.'
PROMPT='CMD DSPPFM ?\FILE(&lib./&file.) ?\MBR(&mbr.) &parms.'.
.\
:LISTACT OPTION=7
COND=pf
HELP='wrkmbr/rgzm'
ENTER='CMD RGZPFM FILE(&lib./&file.) MBR(&mbr.)'
PROMPT='CMD ?RGZPFM ?\FILE(&lib./&file.) ?\MBR(&mbr.)'.
.\
:LISTACT OPTION=8
HELP='wrkmbr/dspfd'
ENTER='CALL exitpgm'
PROMPT='CALL exitpgm'.
.\
:LISTACT OPTION=9
COND=pf
HELP='wrkmbr/clrm'
.\ CONFIRM=confclrmmb
ENTER='CMD CLRPFM FILE(&lib./&file.) MBR(&mbr.)'
PROMPT='CMD ?CLRPFM ?\FILE(&lib./&file.) ?\MBR(&mbr.)'.
.\
.\
.\ -------------------------------------
.\ Define the columns and headings to display
.\ -------------------------------------
:LISTCOL VAR=mopt
USAGE=INOUT
HELP='wrkmbr/option'
MAXWIDTH=6.
:LISTCOL VAR=mbr
USAGE=OUT
HELP='wrkmbr/mbr'
MAXWIDTH=1ð.
Member
:LISTCOL VAR=mtype
USAGE=OUT
HELP='wrkmbr/type'

MAXWIDTH=1ð.
Type
:LISTCOL VAR=mtext
USAGE=OUT
HELP='wrkmbr/text'
MAXWIDTH='\'.
Text
.\
.\ -------------------------------------
.\ -------------------------------------
.\
:ELIST.
.\
.\ -------------------------------------
.\ Use a command line and allow parameters to be given
.\ -------------------------------------
:CMDLINE SIZE=SHORT.
.\
:EPANEL.
..
.
..
.
.\
.\ -----------------------------------------------------------------
.\ -----------------------------------------------------------------
:EPNLGRP.
Application Programming for a Menu Bar Panel

An example of an application program to display the panel shown in Figure 16-10
on page 16-50 can be found in member T0011CP2 in source file QATTSYSC in
library QUSRTOOL. This is an ILE C program which calls the appropriate UIM
application programming interfaces (APIs) to display the panel.
The application program should do the processing described in “Application Pro-

gramming for a List Panel” on page 16-25.
A general example of an RPG program can be found in member T0011INF in

source file QATTINFO in library QUSRTOOL.

Chapter 17. Details of Using User Interface Manager
This chapter explains the structure of the OS/400 user interface manager (UIM) and
provides an overview of its objects and functions.
Opening a UIM Application

An application program must first open a UIM application that uses the panel group
to access dialog variables, lists, and panel definitions. An application is opened by
the Open Display Application (QUIOPNDA) or Open Print Application (QUIOPNPA)
APIs and closed by the Close Application (QUICLOA) API. A UIM application is
managed much like an open file. It is meaningful only for a particular call for
reclaim resources processing, and it is automatically closed as necessary by the
reclaim resources function or by cleanup processing at the end of a job.
When an application is opened, UIM assigns each application an application

handle. A handle is a variable that represents an object, an instance of an applica-
tion using some function, or a processing session. This handle must be specified
as an input parameter to all APIs that operate with the application. The same
panel group object can be associated with more than one open application in the
same job, but each application contains a completely independent set of dialog var-
iables, active lists, and internal control information that define the state of the UIM
application.
Defining Dialog Variables

A dialog variable is a UIM element that contains a value. This value can be
referred to and updated by programs that use the open application and by the UIM
when it performs functions such as displaying panels to the user.
The dialog variables contained in an open application are determined by the panel
group object associated with the application. Dialog variables are defined using the
variable definition (VAR) language tag in the source for a panel group. Special
dialog variables defined by UIM have names that begin with the letter Z and are
referred to as Z-variables. For more information on the VAR language tag, see
“VAR (Variable Definition)” on page A-166. For more information on Z-variables,
see “Dialog Variables Defined by UIM” on page A-166.
Every open application associated with a particular panel group object contains a
complete set of all the dialog variables defined in the panel group, including what-
ever Z-variables are defined in the tag language for that panel group. The set of all
dialog variables in an application is called the variable pool for the application.
UIM is not able to communicate directly with a program's storage to get the values
of its variables. The program can use the variable pool to communicate to UIM
what it would like to display on the panel. When a panel is to be displayed, UIM
retrieves the values from the variable pool and displays them on the panel. When
the user updates the fields on the panel, UIM reads the values from the panel and
places them into the variable pool for the user program to retrieve and act upon.
Because each open application has its own variable pool, each time a user
program wishes to gain access to the dialog variables in an application, it must
provide the variable pool APIs with the application handle that was assigned by the
QUIOPNDA API.

For more information on variable pools, see “Using Variable Pool Services” on
page 17-4. The dialog variables are used to display panel field values that are not
constant text. The dialog variables are also used to tailor the format of the panel
using the condition definition (COND) tag. For more information on the COND tag,
see “COND (Condition Definition)” on page A-27.
The definition of each dialog variable specifies a base data type value that controls
both the form of the internal storage of the variable and its editing characteristics on
the display. The following base type values are supported:
Character
IGC
Graphic
Binary (numeric)
Packed and zoned decimal
Date
Time
Action (list option or selection)
Name
Object name
Pointer
The class definition (CLASS) language tag defines a class of dialog variables to be
associated with a base data type, specific validity checking, and display value
translation functions. Validity checking is done only for values entered by the user
in an input field on a display. The validity checking is not done for values provided
by an application program through an API. For more information on the CLASS
tag, see “CLASS (Class Definition)” on page A-14.
A translation function allows the application program to operate with internal values.
The values are automatically mapped by the UIM to and from specified character
string values, when displayed or printed. An example of this is the months in a
year. The application program reference the values 1 through 12, but the user
sees only the names of the months on the display. For more information on the
translation function, see “TL (Translation List)” on page A-159.
When the application is initially opened, every dialog variable in the application has
an initial value. For dialog variables defined by the application programmer, the
initial value is determined by the base type as follows:
Table 17-1. Initial Values of Dialog Variable

Dialog Variable Initial Value
Numeric 0
Date and Time 0
Character Single-byte blanks
IGC Single-byte blanks
Graphic Double-byte blanks
Pointer Null
Z-variable Defined by the definition of the variable (see “Defining
Dialog Variables” on page 17-1)

Any dialog variable that is referenced without a set value is assigned the initial
value, whether the reference is made by an application program or by the UIM.
Restrictions on Using Dialog Variables

A dialog variable should not be used for the value of more than one display item
per panel as multiple input fields, because the results might be undesirable. This
means that when used as input fields, no dialog variable should be named on mul-
tiple data item (DATAI), data item extender (DATAIX), or list column (LISTCOL)
tags that are part of the same panel definition without conditioning. This ensures
that the same dialog variable does not appear on the display in more than one
place.
Because the variable pool exists until the application is closed, the UIM, and all
programs that use the application, can determine the last value assigned to any
dialog variable in the pool. Once the application program assigns the value of a
dialog variable, it never needs to be assigned again as long as it does not need to
be changed. Similarly, once an input value is accepted from the user and stored in
a dialog variable, that value continues to be available until the variable is updated
by either an application program or the user.
Dialog Variable Error Messages

By defining a variable of basetype char 1 on the ERRVAR attribute of the VAR tag,
the user may indicate to UIM that a variable is in error by using the Put Dialog
Variable (QUIPUTV) API to set this variable to (X“F1”). When this happens, the
field in error is highlighted and the cursor is positioned to the first input field that is
in error. The application program reports the cause of the error and requests that
the UIM display the messages to the user using the message reference key param-
eter of the Display Panel (QUIDSPP) API.
All variables in error in the open application are reset when the next dialog
command is processed by the UIM. Exceptions to this are the Menu Bar Cursor
Action (ACTIONS), Command Line (CMDLINE), Change View (CHGVIEW), HELP,
Display More Function Keys (MOREKEYS), Move to Top (MOVETOP), PAGEUP,
PAGEDOWN, Print Screen (PRINT), and Retrieve Command String (RETRIEVE)
dialog commands. The error status for each dialog variable is reset when control
returns from the Display Panel (QUIDSPP) API or when control is passed from the
UIM to a program or command identified by a menu item, action list, pull-down
choice, or function key item.
When a function key is pressed or a pull-down choice is selected that performs an

action where VARUPD=YES was specified, ((see “KEYI (Key List Item)” on
page A-74), and “PDFLDC (Pull-Down Field Choice)” on page A-134), the UIM val-
idates the values of all entered (changed) input fields. If an error is found, the
panel is displayed again with the fields in error highlighted and one or more mes-
sages is issued. The values of the dialog variable associated with the input fields
are not changed until the user enters a correct value.
The application developer can specify that some function keys and pull-down
choices operate without updating the variable pool by using VARUPD=NO. If
control returns to the program that ran the QUIDSPP API for such a function, all
values entered by the user are lost. If the requested function causes the UIM to
call a program or system command, all input field values are stored internally by
the UIM in such a way that they can be shown when control returns to the UIM and
Chapter 17. Details of Using User Interface Manager 17-3

the panel is displayed again. These input values are stored locally for the panel
being displayed. Any panel that is presented using the same open application by a
program or command with VARUPD=NO specified, displays the values of all dialog
variables as they exist in the variable pool. However, if VARUPD=YES is specified,
the updated value is used instead of the stored value when control returns and the
original panel is displayed again.
Providing Field Values for a Display Panel Using Dialog Variables

The tag language allows you to use dialog variables to provide field values for a
display panel and substitution values for a CL command that is called by the UIM
for a pull-down choice, menu choice, function key, or action list selection. When-
ever a dialog variable is referred to in one of these ways, the internal value stored
in the variable pool is converted to an external form determined by the editing rules
for the variable base type and any translation list defined for the variable class.
When the external form of a dialog variable contains characters that are incorrect
for a display device, the UIM converts the incorrect characters to hexadecimal 1F
characters ( J ). When the external form of a dialog variable contains characters
that are incorrect for a printer, the UIM converts the incorrect characters to the
replacement characters in effect for the printer file, or to blanks when
RPLUNPRT(*NO) is in effect for the printer file.
Incorrect display characters are characters with hexadecimal values equal to

hexadecimal FF or less than 40, not including hexadecimal 00, 0E, and 0F. Incor-
rect printer characters are the same as the incorrect display characters, except that
hexadecimal 00 is also incorrect. This conversion does not take place on variable
values that have been translated with a translation list.
If the dialog variable that contained the incorrect characters is used as an input
field and retrieved with the Get Dialog Variable (QUIGETV) API by the program, the
incorrect characters might be changed to hexadecimal 3F. This occurs if the user
modifies the field or presses the Help key.
When the UIM displays a panel, it retrieves the current value for all variable fields
from the variable pool or from list entries. If the user types a value in an input field,
the UIM validates and translates the value according to the CLASS attribute of the
associated dialog variable, and then stores the value in the dialog variable or asso-
ciated list entry. The application program can determine the value entered by the
user by using the Get Dialog Variable (QUIGETV) or the Get List Entry
(QUIGETLE) API to retrieve the dialog variable value.
Using Variable Pool Services

The Get Dialog Variable (QUIGETV) and Put Dialog Variable (QUIPUTV) APIs are
the primary interfaces for application programs to retrieve and update dialog vari-
ables. When a dialog variable is updated, the attributes of the new value must
match the base type of the dialog variable. When a dialog variable is retrieved, the
value is always returned to the application program in the internal form specified by
the base type of the dialog variable. On the call to the variable pool services APIs,
a variable record is required. A variable record, defined using the VARRCD tag in
the UIM panel group source, defines a group of dialog variables that may be
updated or accessed together in one call to the APIs.

No data conversion or validity checking is done when variable values are retrieved
or updated using the QUIGETV and QUIPUTV APIs. For more information on
these APIs, see the System API Reference.
Some of the dialog variables defined by UIM, referred to as Z-variables, can be

retrieved but not modified. The tag language does not allow a variable with only
read access to be used as an input field on a panel definition. The UIM returns an
exception to an application program if it attempts to update such a Z-variable using
the QUIPUTV API.
Character Set and Code Page Considerations

Data that is always stored in a specific character set and code page can be con-
verted to another character set and code page when it is displayed or printed by
the UIM. If your application has data that must be converted, do one the following:
Code CHRID=PNLGRP on the CLASS tag of the variables that need to be con-
verted. See “CLASS (Class Definition)” on page A-14. Then, specify the
number of the graphic character set and code page of your data on the CHRID
parameter of the Create Panel Group (CRTPNLGRP) command that is used to
create your panel. For more information on the CRTPNLGRP command, see
the CL Programming book.
On the CHRID parameter of the Create Panel Group (CRTPNLGRP) command
that is used to create your panel, specify *JOBCCSID. For more information on
the CRTPNLGRP command, see the CL Programming book.
Displaying
The UIM compares the character set and code page of the device to the character
set and code page of the panel group. If they are different, then outbound and
inbound conversion tables are used to convert the appropriate dialog variables. If a
conversion table is not available, then the Open Display Application (QUIOPNDA)
API sends a diagnostic message and continues.
Display operations for Arabic and Hebrew bidirectional panel groups, which have
BIDI=LTR or BIDI=RTL specified on the panel group (PNLGRP) tag, are only
allowed when the device is configured to use code page 420 or 424.
See Table 17-2 for a summary of how CCSIDs are converted.
Table 17-2. UIM CCSID/CHRID Conversions for Display

Panel Group CHRID
Type of Data XXX *JOBCCSID *DEVD
Panel group constant No conversion. Convert from No conversion.
text panel group
primary source
file CCSID to
device CCSID.
Variable with Convert from Convert from job No conversion.
CHRID=PNLGRP on XXX to device CCSID to device
CLASS tag CHRID. CCSID.
Variable without No conversion. Convert from job No conversion.
CHRID=PNLGRP on CCSID to device
CLASS tag CCSID.

Printing
The UIM compares the character set and code page of the printer file to the char-
acter set and code page of the panel group. If they are different, an outbound
conversion table is used to translate the appropriate dialog variables. If
CHRID(*DEVD) is specified for either the panel group or the printer file, no conver-
sion of the dialog variables is done. If a translation table is not available, the Open
Display Application (QUIOPNDA) or the Add Print Application (QUIADDPA) API
sends a diagnostic message and continues.
When a printer file is printed on a printer device, the character set and code page
of the printer file is compared to the character set and code page that is loaded in
the printer. If they are different, all the printer file data, including the constant text
from the UIM tags, is translated to the character set and code page of the printer.
To minimize the number of times that character set and code page translations
takes place, specify the same CHRID value on both your printer file and your panel
group.
Print operations for Arabic and Hebrew bidirectional panel groups, which have
BIDI=LTR or BIDI=RTL specified on the panel group (PNLGRP) tag, must have
code page 420 or 424 specified for the printer file. Also, any call to the QUIADDPA
API for a bidirectional panel group must have the same code page specified for the
printer file as is used by the display device.
See Table 17-3 on page 17-7 for a summary of how CCSIDs are converted.

Table 17-3. UIM CCSID/CHRID Conversions for Print
Panel Group CHRID or Menu CHRID
Print File
CHRID XXX *JOBCCSID *DEVD
YYY Panel group constant text: Panel group constant text: Panel group constant text:
no conversion. convert from panel group no conversion.
primary source file CCSID to
YYY.
Variables with Variables with Variables with
CHRID=PNLGRP on CLASS CHRID=PNLGRP on CLASS CHRID=PNLGRP on
tag: convert from XXX to tag: convert from job CCSID CLASS tag: no conversion.
YYY. to YYY.
Variables without Variables without Variables without
tag: no conversion. tag: convert from job CCSID CLASS tag: no conversion.
to YYY.
*JOBCCSID Panel group constant text: Panel group constant text: Panel group constant text:
no conversion. convert from panel group convert from panel group
primary source file CCSID to primary source file CCSID
job CCSID. to job CCSID.
tag: convert from XXX to job tag: no conversion. CLASS tag: no conversion.
CCSID.
tag: no conversion. tag: no conversion. CLASS tag: no conversion.
*DEVD Panel group constant text: Panel group constant text: Panel group constant text:
no conversion. convert from panel group no conversion.
primary source file CCSID to
job CCSID since variables
are in job CCSID and device
CCSID is unknown.
Managing a List
A UIM list is a sequential set of list entries. Each entry contains a copy of the
value for one or more dialog variables. The entries in a list can be presented to the
user in a scrollable area of a display. The UIM provides application programming
interfaces (API) that allow an application program to perform the following oper-
ations on lists:
Add a new entry between any two entries in the list.
Add an entry at the beginning or end of the list.
Update the values in a list entry.
Remove a list entry.

Position the current entry pointer for the list to a specific entry; several position
options are available.
Set and retrieve list attributes that control UIM processing when the list is dis-
played.
Delete an active list. (Remove all entries from a list and make the list inactive
for the application.)
Defining a List
The definition for each list using the list definition (LISTDEF) language tag is speci-
fied in the source for the panel group object. Attributes of the list definition
(LISTDEF) tag specify the name of the list and what dialog variables should be
associated with the list (that is, what variable values are to be stored in each list
entry). For more information on the LISTDEF tag, see “LISTDEF (List Definition)”
on page A-100.
Each entry in a list contains a copy of the values of all dialog variables associated
with the list. The values of the dialog variable are copied into a list entry when the
entry is first added to the list using the Add List Entry (QUIADDLE) or Add List
Multiple Entries (QUIADDLM) API, and whenever the entry is updated using the
Update List Entry (QUIUPDLE) API. The values in a list entry can be copied into
the corresponding dialog variables when the entry is retrieved using the Get List
Entry (QUIGETLE) or Get List Multiple Entries (QUIGETLM) API.
Initializing a List
All UIM APIs for processing lists require the program to specify the list name on the
list object definition (LISTDEF) tag in order to identify the target list for the opera-
tion. Each list defined in a panel group is either active or inactive for each open
application using the panel group. Each list is initially inactive when an application
is opened using the Open Display Application (QUIOPNDA) or Open Print Applica-
tion (QUIOPNPA) API. A list becomes inactive when it is deleted using the Delete
List (QUIDLTL) API. A list may be active in multiple different open applications
using the same panel group. A list becomes active when the first entry is added to
the list using the Add List Entry (QUIADDLE), or Add List Multiple Entries
(QUIADDLM) API, or when the list attributes are set using the Set List Attribute
(QUISETLA) API. The maximum size of a list is approximately 16MB. The
maximum number of entries that can be added to a list is based on the size of
each entry.
Displaying a List
When a panel containing a list area is displayed, entries from the list are used to
build a display area that appears to the user as a table. Each list area is associ-
ated with one list definition (see “LIST (List Area)” on page A-82) and contains an
independent selection of columns to display. For more information on the LISTCOL
language tag, see “LISTCOL (List Column)” on page A-96. A list can be referred
to by more than one list area. The list area allows one list to be presented on
different panels within the same open application. If more than one list area exists
in a panel definition, a different list must be used for each list area.
Use the LISTCOL tag to specify the specific values presented in a list area. A list
area can present all the values in the associated list entries, or it can present only
a subset of the values available in each list entry. The list area the user sees

contains a row for each list entry and a column for each field specified in a
LISTCOL tag in the definition of each view of the list area.
You can define a list area to present the values associated with only one list entry
per display line or with multiple list entries per display line. When multiple entries
are shown on each display line, the display is formatted in multiple layouts with
entries presented in order from top to bottom within layout columns, and from left to
right between layout columns. See “Example 2: List Area with Three Layout
Columns” on page A-87.
Updating a List
Values of list entries are used to fill the display for all fields in the list area; see
“LISTCOL (List Column)” on page A-96. The user can update any input fields on
the display, including those in the list area. If the value specified by the user satis-
fies all validity checks for the associated dialog variable, the corresponding value in
the list entry is updated with the value specified by the user.
The UIM APIs provided to retrieve, add, and update list entries all operate by using
the dialog variables associated with the list. No support is provided to directly
establish or change values of list entries without referencing dialog variables.
Every time a list entry is retrieved, added, or updated, the entire set of values for
dialog variables is copied to or from the list entry. When the UIM refers to or
updates list entries, such as processing user options in an action list, it can also
update values of dialog variables that correspond with the list columns.
Note: When working with an action list you should take care during incomplete list
processing. To avoid undesirable results, the action dialog variable should
be included in the VARRCD for the list entry and updated in the same way
as the other variables in the variable record. If you don't do this, you run
the risk of updating each new list entry (during incomplete list processing)
with the value of the last option that was entered on the panel. For
example, you have a list panel with 12 entries. You enter option “4” on one
entry and scroll down. The incomplete list exit is called to add more entries
to the list. The option dialog variable has a value of “4,” so each entry that
is added may now have a “4” in the option field.
Each entry inserted in a list is assigned an identifier, called a list entry handle,
that uniquely identifies the entry within the active list until the entry is removed from
the list. The identifier is meaningful only for a particular combination of open appli-
cation, active list, and list entry instances. An identifier has no meaning in any
other open UIM application, or even in the same application if the list or the entry is
deleted and then created again. Undesirable results are possible if an identifier is
used outside of this definition.
Incomplete List Processing

When adding entries to an action list during incomplete list processing, take care to
ensure the option field contains the appropriate value (usually blanks) at the time
the QUIADDLE or QUIADDLM API is called. If you are using a VARRCD, the
option variable should be part of the VARRCD.

Removing and Inserting an Entry from a List
After an entry is removed from a list, it can no longer be accessed by the applica-
tion program, and it does not appear even as a blank line in a list area on a panel.
When a new entry is added to a list, the UIM can assign the same list entry handle
for that entry that was used for an entry that was previously removed from the list.
An identifier value has no relationship to the logical position of the entry within the
sequence defined for the entries in the list.
The UIM maintains a current entry pointer for each active list to use as a reference
point for list-entry operations. The list entry manipulation APIs support a list entry
handle parameter. This parameter returns to the application program the identifier
where the current entry pointer for the list was positioned at the end of the opera-
tion. The UIM sets the current entry point to:
The entry just added by the Add List Entry (QUIADDLE) or Add list Multiple
Entries (QUIADDLM) API
The list entry requested by the Get List Entry (QUIGETLE) or Get List Multiple
Entries (QUIGETLM) API, or left unchanged if the requested entry is not found
or not available
The entry that preceded the entry removed by the Remove List Entry
(QUIRMVLE) API
The current entry point is unchanged by the Update List Entry (QUIUPDLE) API.
The Get List Entry (QUIGETLE), Get List Multiple Entries (QUIGETLM), and
Remove List Entry (QUIRMVLE) APIs may set the current entry pointer position to
either the top or bottom of the list. The top is the position that is always logically
before the first entry in the list, and the bottom is the position that is always log-
ically after the last entry in the list. Each of these positions has a special identifier
value for the list entry handle, but because the top and bottom are not "real"
entries, they cannot be updated or removed from the list. The application program
receives an error if it attempts to insert an entry before the top of the list or after
the bottom of the list.
Controlling List Entries on a List Display

The application program can control what list entry appears as the topmost entry in
a list area on a panel by setting the display position attribute to a valid list entry
handle before the Display Panel (QUIDSPP) API is run. For example, this function
can be used to position to a particular list entry specified by the user. When the
display position attribute is not set by the Set List Attributes (QUISETLA) API
between the time the list is initialized and the first time the list is displayed, the UIM
presents the first entry at the top of the list area in the panel. For more information
on the Display Panel (QUIDSPP) API, see the System API Reference.
The display position attribute is updated whenever the user moves to a new page
of the list. Any time the application program removes the entry identified by the
display position attribute, the display position attribute is automatically updated to
refer to the entry preceding the one removed. If there is no entry before the one
removed, the display position attribute is set to the top of the list, and the next
display of the panel presents the first entry at the top of the list area in the panel.
When an entry is added or updated in a list, the error state of every dialog variable
associated with the list is saved with the list entry. The processing described in

“Defining Dialog Variables” on page 17-1 for dialog variables in error state is also
used for list entry values that are in error state. This processing concerns how
validation errors are detected by the UIM and how the VARUPD attribute of the key
item (KEYI) and pull-down field choice (PDFLDC) tags affects updating list values.
Improving Interactive Response Time for a List Display

To improve interactive response for a list display, the UIM list processing allows an
application program (the incomplete list exit program) to build only part of a list
before it is shown to the user. Because the UIM handles scrolling lists as part of
displaying a panel, without returning to the program that ran the Display Panel
(QUIDSPP) API, the application program must tell the UIM whether the entries in
the list represent only the top, middle, or bottom part of the complete list. If the
program calls the Set List Attribute (QUISETLA) API to set the list contents attribute
to a value other than ALL, and if the user attempts to page to list entries that are
available to the application but not yet added to the list, the UIM calls an application
program to add more list entries. The application program is also called by the UIM
as part of Get List Entry (QUIGETLE) or Get List Multiple Entries (QUIGETLM) API
processing if the specified entry is not found but might exist in the part of the list
that has not yet been added.
When a panel is displayed that contains a list area and the associated list is either
not active or contains no entries, the user sees a blank list area and a message
indicates that there are no entries in the list. However, if the list attributes are set
to indicate that the list is not complete, an application program is called to add
entries to the list. The panel is not displayed to the user until either enough entries
are added to the list to present a full display page or the application program marks
the list as complete at either the top or the bottom. The application program is
called not only when the list is empty but any time there are not enough entries in
an incomplete list to fill a list area on the panel.
Using Action Lists and Selection Lists

The UIM supports the following types of lists:
Action list
Selection list
Output only list
Input/output list
Using Action Lists

An action list is a list area where the user can type option numbers to perform
actions against one or more entries in the list. The definition of the UIM list dis-
played as an action list must include a variable defined with BASETYPE=ACTION
specified on the CLASS tag. This variable is referred to as the action variable of
the list.
To define an action list area, the application developer must specify ACTOR=UIM or
ACTOR=CALLER on the LIST tag. In addition, one LISTACT tag must be defined for
each option number that can be entered by the user.
For an ACTOR=UIM action list, each LISTACT tag specifies the action the UIM per-
forms when the user types the option number and presses the Enter key. The
application developer can also define an action the UIM performs when the user
presses a key assigned to the PROMPT dialog command. Two types of actions

can be performed: run a CL command, or call a program. If the action to be per-
formed is to run a CL command, an action-list exit program might be needed to
update the list after the CL command has performed the function for the option. No
interface between UIM and a CL command allows the program called by the CL
command to obtain the application handle. Therefore, if the program called by the
CL command performs a change or delete operation, an action-list exit program is
required to update the list.
For an ACTOR=CALLER action list, there is no specification of an action. When the

user types the option number and presses the Enter key or a function key assigned
to the PROMPT dialog command, the UIM returns control to the application
program. The function requested parameter contains a value which indicates that
the application program should perform the actions associated with the options
selected by the user.
Having the UIM as the actor for the action list is the preferred method because of
the following benefits:
The UIM performs all actions entered by the user.
The UIM automatically displays a confirmation panel for destructive actions,
such as option 4 to delete an object. No application program code needs to be
written to provide confirmation support.
The UIM redisplays the action list panel in cases where an action does not
complete successfully. When the UIM receives an escape message, the UIM
redisplays the list with the cursor located on the option number. The option
number is shown in error. When the Exit (F3) or Cancel (F12) function is
requested from a panel displayed as a result of the list option, the UIM redis-
plays the panel as appropriate. For more information about the UIM processing
a request for Exit and Cancel when displaying an action list, see “Folding Up a
List Panel” on page 17-26.
When the application program is the actor for an action list, the above processing
must be done by the application program.
When a panel contains an action list and a menu bar, pull-down choices can be
defined within the menu bar which operate against each selected entry in the action
list. When at least one pull-down choice is defined which operates against selected
list entries, the UIM allows the user to select entries by typing a valid selection
character. The user selects one or more entries in the list, selects a pull-down
menu from the menu bar, and then selects a choice from the pull-down menu. The
UIM performs the selected pull-down choice for each entry selected by the user.
Using Selection Lists

A selection list is a list area in which the user can type a selection character for
one or more entries in the list. A selection list is defined to allow the user to select
a single entry or multiple entries in the list.
A selection list can be used for the following purposes:

Allow the user to select an object or value from a previously displayed entry
field. This type of selection list is displayed when the user positions the cursor
to an entry field and requests the PROMPT dialog command. The F4 key is
recommended to be assigned to the PROMPT dialog command.

Allow the user to select entries and then perform an action defined in a pull-
down menu from the menu bar.
The definition of the UIM list displayed as a selection list must include a variable
defined with BASETYPE=ACTION specified on the CLASS tag. This variable is
referred to as the action variable of the list. When the user enters a valid
selection character for a list entry, the UIM sets the action variable for that entry to
1000. A value of 1000 for an action variable always indicates that the list entry is
selected.
When a panel contains a selection list and a menu bar, pull-down choices can be
defined within the menu bar which operate against each selected entry in the list.
The user selects one or more entries in the list, selects a pull-down menu from the
menu bar, and then selects a choice from the pull-down menu. The UIM performs
the selected pull-down choice for each entry selected by the user.
Using Selection Characters

The user selects entries in an action list panel that contains a menu bar or a
selection list panel by typing a slash (/), or country-designated selection character,
in the option or selection field for the desired list entries. The country-designated
selection character is determined for each panel group when the panel group is
created. The UIM retrieves the first level text of message CPX5A0C in the CCSID
of the panel group source file. The first two characters of this message are stored
in the panel group object. These characters are the allowed uppercase and lower-
case country-designated selection characters for selection lists and multiple-choice
selection fields defined in the panel group.
If *JOBCCSID is specified for the CHRID attribute when the panel group is created,
the country- designated selection characters are converted at run time from the
panel group source file CCSID to the job CCSID. This enables the comparison to
be done in an equivalent CCSID.
Managing Panel Functions

The UIM supports the following panel management functions:
Enabling panel conversion to a graphical user interface (GUI)
Scrolling
Limiting user capabilities
Defining contextual help
Command line restrictions
Defining function keys
Formatting panels
Folding up panels when exit is requested
Folding up list panels
UIM as a request processor when displaying a panel
All operations performed by the UIM are done in a single process called a routing
step. It is the application developer's responsibility to consider the effects of things
such as recursion, locks, and static storage, for each of the following functions:
Function key action
Menu or action list option
Pull-down choice

Exit program
Command entered by the user on a command line
The UIM does not guarantee that the call-sensitive effects of programs and CL
commands, such as overrides and the Set Attention Program (SETATNPGM)
command, are preserved when commands are run from a panel in any of the ways
listed above. The effect of any command that scopes its function to the program
call that used the command might be lost by the time the next command or
program is called. This is because the UIM call to the function that was scoped was
destroyed in the interim.
Enabling Conversion to a GUI

The UIM supports encoding information in the panel which allows a client program
to convert your panels to a graphical user interface (GUI).
You can use the ENBGUI attribute on the PANEL or PNLGRP tag to specify
whether you want the encoded information included in your panels. More informa-
tion on how to set this attribute can be found in “PANEL (Display Panel)” on
page A-122 and “PNLGRP (Panel Group)” on page A-139.
Scrolling Support
The UIM supports page up and page down scrolling of all panel information, data
presentation, list, and menu areas. Multiple scrollable areas can be defined on a
single panel; the UIM imposes no order on them. However, using scrollable menus
is discouraged because of usability.
No left-to-right scrolling of text is provided, but the Change View (CHGVIEW) dialog
command for lists can be used to show more fields.
Defining Scrollable Areas

To use the UIM scroll function, the panel must have at least one scrollable area
and have function keys defined to perform the PAGEUP and PAGEDOWN dialog
commands. For more information on the PAGEUP and PAGEDOWN dialog com-
mands, see Appendix B, “UIM Dialog Commands” on page B-1.
Panels with scrollable areas must have function keys assigned to the PAGEUP and
PAGEDOWN dialog commands because the UIM does not automatically enable
any function keys. Normally these are the Page Up and Page Down keys,1 but if
you use a function key, F7 and F8 are recommended. The UIM does not prevent
assigning different function keys to the PAGEUP and PAGEDOWN dialog com-
mands, but it does not allow assigning the engraved page keys to anything other
than their implied functions which is page up and page down.
Scrolling status information is also managed by the UIM and is displayed at the
bottom of each scrollable area.
The message line is under UIM control. A plus sign (+) on the message line indi-
cates that more messages can be viewed by pressing the Page Down key.
1 On a 5250 keyboard, these are the Rolldown and Rollup keys respectively.

Because you can scroll a message area, the function keys for scrolling should
always be defined.
Defining Function Key Scrolling

The UIM handles all scroll- and page-key functions for UIM-defined panels; these
functions cannot be overridden by the application. However, you can define other
function keys that work much like scroll keys.
When a function key assigned to the PAGEUP or PAGEDOWN dialog command is

pressed, the UIM scrolls the appropriate amount for the panel type. This is always
a "page," but the UIM tries to avoid having data item groups, menu item groups,
and selection fields split across page boundaries.
The position of the cursor determines which area to scroll. If the cursor is not in a
scrollable area (except for a pull-down menu), the scroll request applies to the
topmost scrollable area on the display. If the cursor is in a scrollable area, the
scroll request applies to that area. The bounds of the scrollable area are the top
and bottom line of that area as defined by the menu area (MENU), data presenta-
tion area (DATA), list area (LIST), and information area (INFO) language tags. For
more information on these language tags, see Appendix A, “UIM Panel Group Defi-
nition Language” on page A-1. Titles and instruction lines are part of the area but
not part of the scrollable portion of the area.
The command line is not considered part of a scrollable area, but it may be associ-
ated with a particular area on the screen. For example, a panel with a scrollable
menu area has a command line and it is associated with the menu. However, for
scrolling purposes, the command line is not part of the area.
Scrolling and Error Conditions

The message line always exists and is always the last scrollable area on the
screen so the scroll function keys must always be active.
When scrolling the message line, the UIM does not perform any validity checking or
updating of the dialog variables. When scrolling any other area, validity checking or
updating of the dialog variables is performed on all input fields on the screen. The
scroll function is not performed if an error is found. All input and output fields on
the screen must be correct before the scroll operation can proceed.
If a page key is pressed and the operation cannot be performed, a message is

displayed. For example, a message is shown if a display is already at the top
when the Page Up key is pressed. The alarm sounds when trying to scroll the
message line past its top or bottom.
Scrolling a List Area

List processing allows an incomplete list to be displayed. If the Page Down key is
pressed and the remainder of the incomplete list does not fill the list area, the UIM
calls the specified application program that handles incomplete lists. This program
adds additional entries to the list or marks the list as complete at the bottom, then
the program returns to the UIM. The UIM knows an incomplete list by the setting of
the contents attribute of lists on the Set List Attributes (QUISETLA) API. Once the
list is complete, the UIM handles scrolling without application program intervention.

A list might be incomplete at both the top and bottom. If a list has missing informa-
tion above the current location, pressing the Page Up key causes the same type of
processing.
Scrolling a Menu Area

The UIM attempts to keep menu item groups together but splits the group if it does
not fit in the defined area. Any individual menu item or text for a menu group must
fit within the available scrollable space or the panel group is not created success-
fully.
Scrolling an Information Area

Using the Move to Top (MOVETOP) dialog command moves a cursor-selected line
to the top of the scrollable information area. This allows the user to position the
information in the most readable manner. For more information on the MOVETOP
dialog command, see “MOVETOP (Move to Top)” on page B-11.
Scrolling Data Item Groups

The UIM keeps data item groups together if possible. A group is split only if it does
not fit within a column of the data area. When a data item group is nested inside
another data item group and the outer group must be split, the UIM still attempts to
keep the inner groups together. If a selection field does not fit in a column of the
data area, the panel group is not created.
Data presentation areas can also be presented in multiple columns and the
columns are filled from left to right. Generally, scrollable data presentation areas
should not be defined with a two-column layout because the usability is poor.
Scrolling a Text Area

Scrolling for a text area must be handled by the text area exit program. UIM does
not handle scrolling for text areas. When a key assigned to a scrolling dialog
command is pressed and the text area should be scrolled, UIM calls the text area
exit program. On return, the UIM redisplays the panel. The text area exit program
should change the value of the dialog variable for the text area in order to scroll the
text area.
A general panel exit program should be used to diagnose if the user has scrolled
too far. If the user has scrolled too far, the general panel exit should send an
appropriate message followed by the special message to cancel the determined
action. For the message to cancel the determined action, see the section on the
general panel exit program in the System API Reference.
Defining Contextual Help

Contextual help is provided jointly by the UIM and the system help function. Using
the tag language, a panel is defined to associate help modules with different areas
on the screen. When the Help key is pressed, the UIM determines which help
modules to display.
When defining a panel, the user can associate help text with the following areas:
Entire panel
Menu bar

Menu bar choice
Pull-down field choice
Specific menu item
Specific data item
Specific data selection field
Choice for data selection field
Specific list column
List column group
Specific function key
Specific option in an action list
Data group
Data area
When the Help key is pressed, the UIM displays the help text depending primarily
on where the cursor is. The rules are as follows:

Cursor Position Help Selection Rules
On a menu item Help for that menu item is displayed.
In a list column Help for that column is displayed.
The left and right boundaries of a column are defined by the left and right edge of the
field or heading, whichever is greater, plus one blank on either side. The top and
bottom boundaries of a column are defined by the first line of the heading or column
group heading and the last line where a list entry may be displayed.
Help can be associated with a list column group rather than the individual entries. In
this case, positioning within the group gives help for the entire group regardless of the
specific column the cursor is in. Boundaries of column groups are defined by the sum
of the individual column boundaries plus any separators between columns of the
group.
If the column for which help is being displayed is the option column of an action list,
the help displayed includes the help specified for the list column and the help specified
for each active list action.
On any line in the function- Help for all active function keys is displayed.
key-definition area
On a message line with a Help for that message is displayed. Help for a message is provided by the Additional
message displayed Message Information display. Help for a message does not use a help module in a
panel group.
On a menu bar choice Help for that menu bar choice and all currently active pull-down choices for that menu
bar choice is displayed.
On a pull-down choice Help for that pull-down choice is displayed.
In a pull-down input field Help for the menu bar choice (see "On a menu bar choice" above) that the pull-down
is associated with is displayed. If a valid pull-down choice is entered in the field, help
for that pull-down choice is displayed.
On a command line The displayed help depends on the contents of the command line.
If the command line is associated with a menu area and the command line contains a
number, help for that menu item is displayed as if the cursor were placed on that menu
item. Help is available for any active menu item regardless of whether it is displayed.
If the command line is assumed to contain a command, help for that command is dis-
played.
If the command line is being treated as a parameter line, extended panel help is dis-
played.
If the command line is blank, extended panel help is displayed.
On a data item If help is specified for the data item, that specific help is displayed.
If no help was specified on the data item, the data item is part of a group, and if help
was specified at the group level, then data group help is displayed.
If no help was specified on the item, the data item is not part of a group, or if no group
help was specified, and help was specified on the area, then area-level help is pre-
sented.
On a data group heading The same rules apply as when the cursor is on a data item. Help is presented for the
lowest level (group, area, or extended panel).
In a data area If help is available for the area, that level of help is displayed. Otherwise, extended
panel help is displayed.
Any other position If none of the above conditions are met, extended panel help is displayed. This is true
whenever the cursor is on the title line, any instruction line, and most blank spaces.
Whenever there is no specific help to display, extended help is displayed.

Although HELP for a specific action on a list option or function key is never dis-
played, help text is individually defined for them. This allows conditioning of active
options and function keys. The displayed help describes only the active function
keys or options.
Command Line Restrictions

The UIM allows two sizes for a command line:
A short command line is one line
A long command line is two lines
Depending on whether the command line is short or long, the UIM formats and
displays the command line to occupy the one or two lines preceding the function
key area. This position remains unchanged regardless of scrolling, item condi-
tioning, or the number of list entries.
Command lines are defined by the command line (CMDLINE) language tag. For
more information on the CMDLINE tag, see “CMDLINE (Command Line)” on
page A-26. The UIM allows specifying this tag on any panel, but does not require
it.
When a command line is defined for a panel, it is recommended that the F4 key be
assigned to the PROMPT dialog command and the F9 key be assigned to the
RETRIEVE dialog command. This allows the user to prompt for commands
entered on the command line and to retrieve previously entered commands. For
more information on dialog commands, see Appendix B, “UIM Dialog Commands”
on page B-1, and for more information on defining function keys, see “KEYL (Key
List)” on page A-76.
The UIM sometimes associates the command line with one area on the panel. If a
menu area is present, the command line is associated with the menu area. If an
action list is present, the command line is associated with the action list. If neither
is present, the command line is not associated with an area on the panel. The UIM
does not allow two menu areas, two action lists, or a combination of these within a
single panel. Also, command lines and menu option lines are mutually exclusive.
For more information on the option line (OPTLINE) tag, see “OPTLINE (Option
Line)” on page A-120.
Command Line Interpretation

Command lines are used to select a menu option, to run OS/400 or System/36
Environment commands, and to specify parameters used in conjunction with
options on an action list. The UIM selectively interprets the character strings
entered on the command line.
Many dialog commands do not require any input on the command line. The fol-
lowing conditions assume the action is one requiring the UIM to know the command
line contents. These actions are for the ENTER, HELP, and PROMPT dialog com-
mands. For more information on the Enter, Help, and Prompt functions, see
Appendix B, “UIM Dialog Commands” on page B-1.
For a command line associated with a menu, the UIM examines the first non-
blank set of characters. If it is composed of only digits (hexadecimal F0

through F9), the command line is assumed to select a menu item. Otherwise,
the command line is treated as containing a command.
For a command line associated with an action list, the command line is
assumed to contain parameters if any option is selected on any action list
entry. Otherwise, the command line is treated as if it contains a command.
For a command line associated with a panel that contains neither a menu nor
an action list, the command line is always assumed to contain a command.
Exactly what function is performed next depends on what function key is
pressed. For details, see the descriptions of the ENTER, HELP, and PROMPT
dialog commands.
Entering Commands That Are Too Long

Commands that are too long for the command line can still be submitted by
prompting for them. If the command causes an exception, the command line is
displayed with the current command contents. If the full command string is too long
for the command line, the display shows as much as possible and replaces the last
three characters on the displayed command line with ellipses (...) to indicate contin-
uation. The UIM still maintains the full command string internally.
Any changes to the command line causes the UIM to discard the internal version
and treat the changed command line as a new request. If no change is made and
the command is prompted or submitted, the internal version is not reset and is sub-
mitted as the new command string. Modification is based on a character compar-
ison of the command line contents.
Defining Function Keys

The UIM does not automatically enable function keys; the application developer is
responsible for enabling the correct set of function keys and ensuring that the
correct functions are assigned to each. Function keys are defined with the key list
(KEYL) and key list item (KEYI) language tags. For more information on these
language tags, see Appendix A, “UIM Panel Group Definition Language” on
page A-1. The UIM requires that engraved keys be assigned to their dialog
command equivalent. The Help, Enter, Page Up, Page Down, Print, and Home
keys must be assigned their respective dialog commands. With the exception of
the PRINT dialog command, this does not prevent assigning these dialog com-
mands to other keys as well. For example, it is recommended that the HELP
dialog command be assigned to the F1 key as well as the Help key. The PRINT
dialog command can be assigned only to the Print key and cannot be conditioned.
F1 through F24 can be assigned to any of the dialog commands except PRINT and
MOREKEYS. The MOREKEYS dialog command can be assigned only to F24.
Formatting Function Keys

When a panel is created, the UIM determines the worst-case display of function
keys and their descriptions and then allocates one or two lines accordingly. Two
lines is the maximum amount of room available to display function keys. Then this
space is fixed. For example, if the UIM determines that two lines are required for a
specific set of conditions, then two lines are always used, even if some conditions
cause only one line of description for the function keys.

Handling Function Keys and VARUPD Value
The dialog command assigned to a function key determines the function of that
particular key. For more information on handling function keys, see Appendix B,
“UIM Dialog Commands” on page B-1.
Function keys that are inactive due to conditioning are treated as if they are not
defined. If the user presses a function key that is not defined, a message is dis-
played to indicate that the key is not allowed. When help is displayed for the func-
tion key area, no help information is displayed for inactive keys.
When defining a function key, the VARUPD attribute of the key list item (KEYI) or
pull-down field choice (PDFLDC) language tag defines whether dialog variables and
list entry values should be updated with user entered values when the function key
is pressed or when the pull-down choice is selected. If any fields on the panel fail
validity checking, the action associated with the function key or pull-down choice is
not performed.
Although most dialog commands have a predefined, unchangeable value for

VARUPD, some dialog commands do not. When a function key is assigned to one
of these dialog commands, processing of that request depends on the value of
VARUPD.
When VARUPD=YES is specified, all values keyed in by the user must pass
validity checks. If any values fail the validity checks, the following occurs:
Any dialog variable that does not pass validity checking is not updated.
The specified function is not performed.
The general exit program for the panel, if specified, is not called.
The UIM displays the same panel again with the appropriate error messages.
When VARUPD=NO is specified, the following occurs:

No validity checking is performed and no dialog variables are updated.
If specified, the general exit is called. This assumes that the dialog command
to be performed is one for which the exit program is normally called.
The specified function is performed unless the general exit program indicates
that the UIM should not perform the function. For more information on exit pro-
grams, see the System API Reference.
When VARUPD=NO is specified for a dialog command, which causes the UIM to
return control to the application program, variable values entered by a user are not
available to the application program. The values are stored for the panel and can
be shown again by using the redisplay parameter of the Display Panel (QUIDSPP)
API. For more information on this, see the System API Reference. When
VARUPD=NO is specified on the CMD and CALL dialog commands, the UIM saves
the screen copies of dialog variables and uses them when the panel is displayed
again after the specified action completes.
Note that when VARUPD=NO is specified on the CMD and CALL dialog com-
mands, any modification of dialog variables or list entries causes the saved version
to be lost. The saved version for any field is used if the underlying dialog variable
has not changed since the field was saved. For lists, the saved version of a vari-
able in a list entry is used unless one of the following occurs:

Underlying list entry has changed
List entry changed position on the screen
List view has changed
If a change was made, the saved version is lost and a new displayed value is
derived from the dialog variable or list entry.
For example, assume dialog variable VARX is present on panel PANELX and is
modified by the user just before pressing a function key using the CALL dialog
command where VARUPD=NO. If the target of that CALL dialog command modi-
fied VARX, the saved version is lost. When the UIM displays the panel again after
the call returns, the displayed version of VARX is based on the modification. This
allows actions, which are unrelated to the current panel, to be performed without
requiring the panel contents to pass all validity checks. VARUPD=NO should not
be used with CMD or CALL dialog commands if the intended action is to use the
same panel or any of its associated dialog variables, lists, or conditioning dialog
variables.
Panel Formatting Concepts

When formatting UIM panels, keep the following in mind:
The application developer does not define the format of a panel in terms of
rows and columns. Instead, the UIM interprets the descriptions of the tag lan-
guage and then determines where to place each element in a panel. For
example, the display panel (PANEL) tag contains a description of the panel
title, but no explicit definition of where the title should be displayed. The UIM
determines that the title should be centered within the panel width, intensified,
and treated as mixed case. The same concept applies to all other areas of the
panel, though most other examples are much more complex.
The UIM performs as much formatting as possible when the panel group is
created, but the actual placement for many panel elements is determined at run
time. This allows the UIM to consider screen depth and other run-time circum-
stances. For example, the UIM allows menu items to be conditionally dis-
played. These conditions are evaluated when a panel is displayed, and the
format of the menu area is based on the results.
When Panel Formatting Is Performed

There is a difference between panel formatting and panel contents. Panel format-
ting refers to the organization of the various areas on the panel. Panel contents
refers to the values of fields as dictated by dialog variable contents.
Panel formatting takes place when the panel group is compiled and again at run
time.
Most decisions are made when the panel group is compiled and the information is
kept in the panel group object. Those formatting decisions that cannot be made
when the panel group is compiled are made during Display Panel (QUIDSPP) API
processing.
An example of this distinction is a data item that is conditioned. All details about
the prompt text layout, number of leader dots, field position, and formatting of pos-
sible choices are performed when the panel is created.

At run time, the QUIDSPP API processing determines whether or not the item
should be displayed by evaluating the conditions and builds an internal format.
Within an application defined by the Open Display Application (QUIOPNDA) and
Close Application (QUICLOA) APIs, each panel has only one internal format at any
time. The internal format is built the first time the panel is displayed, and the
format is kept for subsequent use until the application is closed.
This does not mean that the internal format cannot change within an application.
Most of the internal format does not change, but some panel elements such as
menu items, list actions, and function keys, are conditioned by the application. The
effect of changes to these areas are evaluated each time the panel is displayed,
and then the format is updated.
Because the UIM performs many functions, such as submitting commands and
calling programs, before returning control to the application that called the
QUIDSPP API, the specified panel can be presented to the user several times.
Each time the panel is displayed, the UIM reevaluates the panel formatting. For
example, pressing a function key causes an application program to be called.
When the application program returns control to the UIM, the UIM displays the
panel again, but only after checking to see if the application program changed the
conditions that affected the internal format. For example, if the QUIDSPP API is
called to display a panel with a menu area on it, and the application program
changed a dialog variable affecting the conditioning of some of the menu items,
when the UIM displays the menu area again, it reflects the changes.
Application Control of Panel Formatting

The language tags allows the application developer to control panel formatting in
the following ways:
By specifying part of the formatting, such as column widths, vertical versus hori-
zontal presentation of data areas, and depths of the areas. These specifica-
tions are fixed when the panel is compiled and cannot be changed at run time
by the application. This allows you to select alternate formatting techniques
and it gives the UIM information that helps reduce run-time processing.
By specifying run-time conditioning. Dialog variables can be used to condition
menu items, menu item groups, action list options, function keys, data items,
pull-down choices, data selection fields, selection field choices, and data item
groups. In most cases, these conditions are evaluated every time a panel is
displayed to determine what should be included in the display.
Conditioning can be based on any of the following:
Application defined dialog variable.
UIM defined dialog variable.
Existence of an object on the system or the user's authority to an object on the
system.
User class of the application user.
Conditioning can be based on the setting of a user profile, a user class, or the
Limit User Capability (ZLMTCPB) dialog variable. For more information on
dialog variables, see “Dialog Variables Defined by UIM” on page A-166.
For more information on defining conditions, see “COND (Condition Definition)” on
page A-27.

The UIM allows additional control over conditioning. The panel definition can
specify which conditions are evaluated only once, when first needed, or at all times.
The purpose of this is primarily related to performance. Most items are conditioned
on things that are or should be fixed when the panel is first displayed, such as a
user profile and authorization. Specifying that these conditions be evaluated only
once avoids unnecessarily evaluating the conditions.
Limits of the Panel Formatter

The UIM provides a formatter designed to handle most normal formatting require-
ments. However, the formatter is not always able to match the results of manual
formatting because the formatter is constrained by the run-time environment and
also must handle generalized input. An example of this is formatting descriptions of
function keys. Manual formatting might include changing the wording to achieve
the best alignment and balance. The UIM does not have the option of changing
the text length or assuming a balanced set of lengths.
Generally, the closer information is packed on a panel, the less likely the UIM for-
matter can match what manual formatting might achieve.
Folding Up Multiple Panels When EXIT Is Requested

To support the ability of an application to fold up multiple panels and programs as
part of processing a single exit request, the operating system maintains a flag for
each job indicating whether or not exit is requested. This exit flag is used in combi-
nation with the user task parameter on the Display Panel (QUIDSPP) API to cause
the exit request to fold up multiple panels.
There are two ways the application program can turn on the exit flag:
1. Specify the SET parameter on the EXIT dialog command. When the UIM per-
forms the EXIT dialog command with the SET parameter, it turns on the job's
exit flag. For more information on the EXIT dialog command, see Appendix B,
“UIM Dialog Commands” on page B-1.
2. Set the UIM-defined variable ZEXIT to "1" using the Put Dialog Variable
(QUIPUTV) API. By setting this Z-variable, the UIM turns on the job's exit flag.
The UIM automatically turns off the exit flag when it begins processing actions.
Whenever the UIM regains control after performing a panel-defined action, such as
submitting a command assigned to a function key or calling a program because a
menu item is selected, the job's exit flag is checked. If the flag is on and the panel
is displayed as an old user task (user task parameter on the QUIDSPP API), the
UIM returns control to the calling application at that point. Also, the function-
requested parameter of the QUIDSPP API contains an indication that the panel
display ended due to the EXIT dialog command.
If the job's exit flag is off or the panel is displayed as a new user task, nothing
special happens. The UIM turns off the exit flag and displays the panel again.
If the action performed is not panel-defined, for example, when a command is

entered on the command line, the exit flag is always turned off, and the processing
is not affected by whether the panel is displayed as a new or old user task.

An example of how the exit flag works follows; Figure 17-1 on page 17-25 illus-
trates the example. Assume that program PGMX, displays PANELX that has a
function key assigned to the CALL dialog command. Assume also that the program
that is called, PGMY, displays another panel called PANELY. Now assume that
PANELX is displayed as an old user task, the function key is pressed, and
PANELY is displayed. From PANELY, the user presses the function key assigned
to the EXIT dialog command using the SET parameter and control returns to
PGMY. When the EXIT dialog command is processed, the UIM turns on the exit
flag. If PGMY now returns control to the UIM, the UIM returns control to PGMX
with an indication that the EXIT dialog command was requested. In effect, two
panels are bypassed via a single exit request.
PGMX
QUIDSPP
Job
Exit
Flag
On
PANELX (old user task)
PGMY
EXIT QUIDSPP
PANELY
RV2W058-0
Figure 17-1. Example of Job Exit Flag
If the function key on PANELY assigned to the EXIT dialog command does not use
the SET parameter, the UIM displays PANELX again because the job's exit flag is
not turned on.
For more information on APIs, see the System API Reference.

Folding Up a List Panel
For panels displayed as a result of processing a list option on an action list panel,
the CANCEL, EXIT and ENTER dialog commands should work as follows.
The operating system maintains a flag for each job indicating whether or not cancel
is requested. This flag is similar to the flag described for exit processing; see
“Folding Up Multiple Panels When EXIT Is Requested” on page 17-24. However,
the cancel flag is not used to bypass more than one panel, and it is not used in
conjunction with the user task parameter on the Display Panel (QUIDSPP) API.
There are two ways the application program can turn on the cancel flag:
1. Specify the SET parameter on the CANCEL dialog command. When the UIM
performs the CANCEL dialog command with the SET parameter, it turns on the
job's cancel flag. (For more information on the CANCEL dialog command with
the set parameter, see Appendix B, “UIM Dialog Commands” on page B-1.)
2. Set the UIM defined variable, ZCANCEL, to "1" using the QUIPUTV API. By
setting this Z-variable, the UIM turns on the job's cancel flag.
It is the application developer's responsibility to ensure that pressing the Cancel

key stops processing of list actions and displays the action list panel again at the
point where processing was stopped. If another panel can be displayed as a result
of processing a list option, the job's cancel flag should be turned on when the
Cancel key is pressed by specifying the SET parameter on the CANCEL dialog
command. When the UIM performs action-list processing, it checks the cancel flag
after each list action completes. When the UIM finds that the flag is on, it stops
processing the remaining list options and displays the list again. The option field
for the list entry just processed is cleared and the options of list entries whose
action was not attempted are left in the list. The UIM only checks the cancel flag
after processing a list action.
It is the application developer's responsibility to ensure that pressing the Exit key
stops the processing of list actions and either redisplays the action list panel at the
point where processing was stopped or exits the action list panel. If another panel
can be displayed as a result of processing a list option, the job's exit flag should be
turned on when the Exit key is pressed by specifying the SET parameter on the
EXIT dialog command. When the UIM performs action list processing, it checks the
exit flag after each list action completes. When the UIM finds that the flag is on, it
stops processing the remaining list options and the following occurs:
If the action list panel is displayed as a new user task, the panel is displayed
again.
If the action list panel is displayed as an old user task, the panel is not dis-
played again, and control is returned to the program that displayed the action
list panel with a return function indicating EXIT was used.
In either case, the option field for the list entry just processed is cleared and the
options of list entries whose action was not attempted are left in the list. The UIM
also checks the job's exit flag when it gets control back after processing menu
options, function keys and pull-down menu choices. For more information, see
“Folding Up Multiple Panels When EXIT Is Requested” on page 17-24

It is the application developer's responsibility to ensure that pressing the Enter key
continues the processing of list actions. When neither the cancel flag nor the exit
flag is on, the next list action is processed.
Adding a Pop-Up Window over Another Panel

You can add pop-up windows over another panel in one of the following ways:
Use the CALL dialog command to have the UIM call an application exit
program so it can add and display the window. To achieve consistent results
from the End Request (ENDRQS) command, this is the recommended design.
Use the RETURN dialog command to have the UIM return to the program that
displayed the underlying panel so it can add and display the window.
The UIM does not become a request processor program when displaying a panel in
a pop-up window that has a menu or action list unless the panel also has a
command line. This is true even when the window is displayed over a primary
panel that has a command line, action list, or menu area.
When the UIM becomes a request processor program while displaying a full-screen
panel, and the application is designed to use the CALL dialog command to add and
display a pop-up window, the program stack contains the UIM request processor
program for the full-screen panel. However, when the application is designed to
use the RETURN dialog command to add and display a window, the program stack
does not contain the UIM request processor program. Therefore, the ENDRQS
command causes different results depending on the internal design of the applica-
tion.
As a general guideline, you should avoid designing long-running functions that run
as a result of a list option or menu option from a pop-up window, unless your
program is a request processor at appropriate times.
If your program becomes a request processor program and displays one or more
pop-up windows by using a design that relies on the RETURN dialog command,
then the code needs to clean up the window stack if the function that displayed a
window is canceled by the ENDRQS command. When this happens, the Remove
Pop-up Window (QUIRMVPW) API must be called once for each window to be
removed from the application window stack.
If your program becomes a request processor program and displays one or more
pop-up windows by using a design that relies on the CALL dialog command, then
the UIM cleans up the window stack automatically if the function that displayed a
window is canceled by the ENDRQS command.
For more information on a request processor program, see the CL Programming

book.
Using Menu Bars

A menu bar is located at the top of a panel and extends the entire width of the
panel. Menu bars are allowed only on panels that are 24 by 80 bytes or 27 by 132
bytes and are not allowed within a pop-up window.
The menu bar contains a list of choices that users may request. The choices are
listed horizontally on one to three lines with three blanks between all choices.

When a user selects a choice by pressing the Enter key, a pull-down menu is dis-
played directly below the menu bar. From this menu, the user may select one
choice.
Each choice in a pull-down menu does one of the following:

Performs an action against the panel or an area of the panel as a whole. In
this case, the UIM performs the action once each time the choice is selected by
the user.
Performs an action against each entry selected in an action list or selection list
on the panel. In this case, the UIM performs the action once for each selected
list entry. The user selects an entry or an action on a selection list by entering
a slash (/) or country-designated selection character next to the desired entry.
For more information on defining menu bars, see the following language tags in
Appendix A, “UIM Panel Group Definition Language” on page A-1.
PANEL (Display Panel)
MBAR (Menu Bar)
MBARC (Menu Bar Choice)
PDFLD (Pull-down Field)
PDFLDC (Pull-Down Field Choice)
Differences Between Pull-Down Menus and Pop-Up Windows

A pull-down menu visually appears similar to a pop-up window. While pull-down
menus and pop-up windows overlay a portion of the underlying panel image, a
pop-up window is a separate application panel and a pull-down menu is an exten-
sion of the panel which contains the menu bar.
Visually, a pull-down menu appears different from a pop-up window in the following
ways:
The separator line appearing below the menu bar is always used as the top
border of the pull-down menu. The border for a pop-up window is never part of
the underlying panel.
A pull-down menu does not have a title. A pop-up window can have a title.
A pull-down menu does not have function key descriptions and a pull-down
menu never overlays the function key descriptions of the underlying panel.
Pop-up windows usually have function key descriptions and a window can
overlay the function key descriptions of the underlying panel.
A pull-down menu does not have a message line and any messages displayed
as a result of the user interacting with the pull-down menu appear in the
message line of the underlying panel. A pop-up window always contains a
message line and any messages displayed as a result of interaction with the
pop-up window appear in the message line of the pop-up window.
Pull-down menus and pop-up windows also differ in how the user is allowed to
interact with each. The differences are as follows:
When a pull-down menu is displayed, pressing the cursor tab key moves the
cursor to the first unselected choice within the menu bar. Press the tab key
again to move the cursor to the next unselected choice, until the cursor is
moved back to the pull-down menu. When a pop-up window is displayed,
pressing the cursor tab key moves the cursor to the next input field defined

within the pop-up window. The tab key never moves the cursor outside the
border of the pop-up window.
When a pull-down menu is displayed, all the function keys defined for the
underlying panel are active. Each function key performs the same function as
if the pull-down menu was not displayed with the following exceptions:
– The Enter key, or any other key assigned to the ENTER dialog command,
is used to process the action assigned to the pull-down choice number
selected by the user.
– Any key assigned to the CANCEL dialog command causes the pull-down
menu to be removed and the underlying panel to be redisplayed. Normally,
F12 is the key assigned to the CANCEL dialog command.
– The Page Down and Page Up keys, or any other key assigned to the
PAGEDOWN or PAGEUP dialog commands, are not allowed when the
cursor is within the pull-down menu.
– Any key assigned to the PROMPT dialog command is not allowed when
the cursor is within the pull-down menu. Normally, F4 is the key assigned
to the PROMPT dialog command.
For cursor-sensitive function keys, the user is allowed to move the cursor
outside the border of the pull-down menu and press the function key. In this
case, the UIM removes the pull-down menu and processes the action assigned
to the function key as if the pull-down menu was not displayed at the time the
user pressed the function key. Cursor-sensitive function keys are any keys
assigned to the dialog commands in the following table. The dialog commands
in the table are usually assigned to the keys as shown.
Table 17-4. Cursor-Sensitive Function Keys Assigned to Dialog Commands

Dialog Command That May Have a Dialog Command Is Usually Assigned to
Cursor-Sensitive Function Key Assigned This Key
HELP Help
PAGEDOWN Page Down
PAGEUP Page Up
MOVETOP (move to top) F10
CHGVIEW (change view) F11
PROMPT F4
As an example, assume that a pull-down menu is displayed. If the user moves

the cursor to a field in the underlying panel, outside the border of the pull-down
menu, and presses the Help key, the UIM removes the pull-down menu and
displays the contextual help defined for the field.
When a pop-up window is displayed, only the function keys defined for the
panel displayed within the window are active. When any function key is
pressed and the cursor is located outside the border of the pop-up window, the
window is redisplayed and the alarm sounds to indicate that the cursor is not
allowed outside the window.
Further differences between pull-down menus and pop-up windows are in how the
application developer can control them. Following are the differences:

A pull-down menu can only contain a list of numbered choices. The application
developer defines each choice, which appears in the pull-down menu, and also
assigns an action for each choice. When the user selects one of the choices,
the UIM performs the action defined for that choice. A pop-up window can
contain any panel element, which can appear in a full-screen panel, with the
following exceptions.
– A pop-up window cannot contain a field (dialog variable) which spans mul-
tiple lines of the display. Every field must fit within the width of the window.
– A pop-up window cannot contain a menu bar.
Based on user interaction, the UIM decides when a pull-down menu is dis-
played and removed. The application program cannot control when a pull-
down menu is displayed or removed; nor can the application program control
the location or size of the pull-down menu when it is displayed. The application
program has control over when and where a pop-up window is displayed and
removed. For more information about displaying pop-up windows, see “Adding
and Removing Windows” on page 17-31. The size of a pop-up window is
specified by the application developer by specifying the WIDTH and DEPTH
attributes on the PANEL tag for the panel to be displayed in the window.
Using Pop-Up Windows

A pop-up window is information that overlays part of the display. The user can
view information inside the window and the portion of the screen that is not over-
layed by the window. However, only the window is active; the user cannot work
with the underlying panel. When more than one window is displayed, only one
window is active at a time.
Following are some principles of pop-up windows:

Windows contain a message line, and if the message exceeds the boundary of
the window, the message is truncated. To indicate the message is truncated,
an ellipsis (...) is added to the end of the message. To see the rest of the
message, place the cursor on the message line of the window and press the
Help key.
When a window is displayed, its size and location cannot be changed.
The cursor is positioned in the active window. If the user moves the cursor
outside the active window and presses any function key except Print, the
display alarm sounds and the cursor moves back to its previous window
location.
When you leave a window, you are returned to the underlying display at the
location where you were before you requested the window.
The Print key applies to the entire display, not just to the current window.
Defining Application Windows

Application-defined windows can be displayed over UIM and DDS panels.
Application-defined means that the application developer defines the exact size of
the window on the display panel (PANEL) tag on the panel group source. The
location of the window is specified when the application program calls the Add
Pop-Up Window (QUIADDPW) API.

Adding and Removing Windows
The UIM maintains a stack to keep track of windows. Windows can be added to
the stack in one of the following ways:
The UIM adds windows to the stack in order to display help information and
command line windows.
The application developer can request that a window be added to the stack to
display a window.
Windows can be removed from the stack internally by the UIM or by the application
developer.
Adding and removing windows is controlled by the application program, but the UIM
provides a set of APIs to manipulate these windows.
To display a window, an application program must first use the Add Pop-Up
Window (QUIADDPW) API to inform the UIM that the next display is for a window.
A window displaying a selection list should use field-adjacent positioning, while a
window displaying a prompt for positioning a list should use offset positioning.
The QUIADDPW API call does not specify the panel to be displayed in the window.
It specifies only the location information necessary to position the window.
A window can be added to a display only after a full-screen panel is determined. A

full-screen panel is determined by calling the Display Panel (QUIDSPP) or Set
Screen Image (QUISETSC) API. Once a full-screen panel is displayed within an
application, a window can be added to the application.
To position a selection list window using field-adjacent positioning, the programmer

must specify the name of the field for which the selection window is being dis-
played. When a panel is displayed within the window, the UIM uses a set of
general window positioning rules to position the window so that, if possible, the
window does not overlay the specified field.
For a window displaying the prompt for positioning a list, offset positioning should
be specified on the Add Pop-Up Window (QUIADDPW) API call. The upper left
corner of the window is positioned below and indented to the right of the upper left
corner of the underlying panel.
Once a window is added to the display, the Display Panel (QUIDSPP) API is used
to display a panel within the window. When the QUIDSPP API is called, the UIM
performs the following operations:
1. Determines the actual location for the window. The location is determined
according to the location information provided by the call to the QUIADDPW
API.
2. Formats the panel.
3. Merges the newly formatted panel and window border with the underlying panel
image.
4. Displays the merged panel output.
The end user must interact with the most recently displayed window before inter-
acting with any other underlying panel or window.

Use the Remove Pop-Up Window (QUIRMVPW) API to remove windows from the
display. A window cannot be removed if the UIM is currently processing an action
or running an exit program for the panel displayed in the window. Multiple windows
can be removed at one time.
The QUIRMVPW API does not cause the UIM to automatically display the under-
lying panel again. The panel is displayed again without the window on the next call
to the QUIDSPP API, or when the UIM automatically displays a panel again after
processing a function or running an exit program.
Using the Command Line in a Window

A command line in a window allows the user to enter commands without requiring
any reserved space on the panel for a permanent command line. The UIM pro-
vides support to display a command line in a window. For UIM application panels,
this is done by assigning a function key to the CMDLINE dialog command. The F9
key is recommended. The CMDLINE dialog command is also allowed as the action
for a choice in a pull-down menu. When a function key or pull-down field choice is
assigned to the CMDLINE dialog command, the key or choice can be conditioned
based on the ZLMTCPB dialog variable. Doing this only allows the user to get to
the command line window if the user does not have limited capabilities.
For DDS panels, a command line window can be provided by calling the
QUSCMDLN API.
Keep the following in mind when using a command line in a window:

A pop-up window is displayed when the user presses a function key causing
the Command Line (CMDLINE) dialog command to process. The cursor is
placed on the first position of the command line and the user can use the
command line to enter any system commands.
The UIM provides a panel definition for the window and puts it at the bottom of
the display.
Neither the size nor the location of the window for the command line can be
changed. The user must remove the window by pressing the Enter key or the
F12 (Cancel) function key. Running a command does not remove the window.
The following example shows a command line pop-up window used on a display.
..............................................................................
: Command :
: :
: ===> ____________________________________________________________________ :
: F4=Prompt F9=Retrieve F12=Cancel :
: :
:............................................................................:
á ñ

Print Concepts
UIM as a Request Processor Program When Displaying a Panel

Sometimes the UIM becomes a request processor program when displaying a
panel. When the UIM becomes a request processor program, your application is
isolated from commands entered on the command line. For example, if the End
Request (ENDRQS) command is used to cancel a command entered on the
command line, the UIM handles the end request and the application program is not
ended. The following types of panels cause the UIM to automatically become a
request processor:
Any panel with a command line. The UIM is required to be a request processor
when submitting a command from a command line. When the panel has a
command line, the UIM becomes a request processor program so that all func-
tions it performs for the panel work consistently for the End Request (ENDRQS)
command.
A full-screen panel with an action list. Most action list panels have a command
line to allow parameters for list options. So for consistency, the UIM becomes
a request processor program for all full-screen panels with an action list. This
allows ACTOR=UIM action lists without a command line to work in the same
way as those that have one when the ENDRQS command is requested while a
list option is being processed. This allows a user to perform the ENDRQS
command to cancel a long-running option without also canceling the action list
panel and the program that displayed it. Any unprocessed list options are left
pending in the action list when the ENDRQS command is used to cancel a
UIM-processed list option.
If you code ACTOR=CALLER for an action list, you should consider having
your code become a request processor program for consistency with the UIM.
A full-screen panel with a menu area. Most menu panels have a command
line. For consistency, the UIM becomes a request processor program for all
panels with a menu area. This allows menu panels without a command line to
work in the same way as those that have one when the ENDRQS command is
requested while a menu option is being processed. This allows a user to
perform the ENDRQS command to cancel a long-running option without also
canceling the menu panel and the program that displayed it.
If you code the RETURN dialog command for a menu item, you should con-
sider having your code become a request processor program for consistency
with the UIM.
For more information on a request processor program, see the CL Program-
ming book.
Printing Concepts
The UIM allows applications to define and generate printed output to the level
required for the OUTPUT(*PRINT) parameter on a CL command. This support pro-
vides a hardcopy form of information in a format similar to that displayed by the
UIM, but it does not allow for generalized printing via the UIM.
The application developer does not need to provide a print panel and a display
panel. However, it is recommended that both print and display panels be placed in
the same panel group. For printing panels, use the Print Panel (QUIPRTP) API.

Print Concepts
A panel group can be opened for either display or print. Once a panel group has
been opened for display, it can also be used to produce printed output. The Add
Print Application (QUIADDPA) API is provided to open a printer file for an already
open display application, and the Remove Print Application (QUIRMVPA) API
closes the printer file that was opened with the QUIADDPA API.
For more information on APIs, see the System API Reference.
The UIM tag language is used to define print head panels and print panels. The
print head panel, created with the print head (PRTHEAD) tag, defines the header
information that is printed at the top of each page. The print panel, created with
the print panel (PRTPNL) tag, defines the different panel areas to be printed. Both
the print head panels and print panels must be printed for the same open applica-
tion.
The following areas make up a printed listing and the example that follows is how it
would look:
Title The title consists of two lines printed at the top of every page. The
title lines contain information such as the output title, time and date,
system name, product information, and page number. All of the infor-
mation in the title lines is defined by the print head panel.
Prolog (Optional.) The prolog section is printed only on the first page and
comes right after the title lines. The prolog section is used for such
things as indicating what parameters were specified to print the
output. The prolog section is defined as the portion of the print head
panel that has TYPE=PROLOG specified on the data presentation
area (DATA) or information area (INFO) tag.
Header (Optional.) The header section is used to print the same data on
every page. This data usually includes things such as the file name,
library, and member name for which information is printed. This
section comes after the prolog on the first page and after the title
lines on all remaining pages. The header section is defined as the
portion of the print head panel that has TYPE=NORMAL specified or
defaulted.
Page body The page body is made up of one or more panels of information.
These panels of information appear very similar to panels that are
used to display information on a display. These panels can contain
data, information, and list areas. Menu areas and selection fields
cannot be defined for printing. Because there is no such thing as a
scrollable print panel, all information and data associated with the
panel is printed via the Print Panel (QUIPRTP) API.
Trailer The trailer is a single line of text that is printed after the last panel
area on the last page. This trailer usually says something like
E N D O F L I S T I N G
or
E N D O F S O U R C E

Print Concepts
Page 1 Title time/date, system name

Title product information,
page number
Prologue (optional)
what parameters
were specified
Header (optional)
file name, library,
member name
Page body
(consists of one or more panels)
data, information, list areas
Page 2 Title same as page 1

Title same as page 1
Header same as page 1
Page body
same as page 1
Trailer (End of Listing)
RV2W059-2
Figure 17-2. Example of Printout
Printing a Print Head Panel

When a print head (PRTHEAD) panel is printed by calling the Print Panel
(QUIPRTP) API, the heading is formatted and saved until a print panel is printed.
Printing a Print Panel

When a print panel (PRTPNL) is printed by calling the Print Panel (QUIPRTP) API,
the UIM:
1. Formats one page of data and prints it.
2. Formats the next page of data and prints it.
3. Formats page by page until the entire panel is printed.
4. Formats and prints the last part of the panel on a partial page. The next call to
the QUIPRTP API causes the rest of the partial page to be formatted and
printed, assuming that no page eject is requested. If the first area of this next
panel does not fit on one page, this area is printed on the next page. This
causes the panel title, top separator, and area title, if one exists, to be printed
on the next page.

Print Concepts
Using Blank Lines for Separating

A single blank line is inserted in the following places by the UIM:
After the second title line of every page
After list column and group headings
After data column headings
Before the trailer line
Fonts and Highlighting

Only printer files created without using a DDS source may be used by the UIM. No
special fonts are supported. The H1 through H4 heading tags are printed as
normal text with no highlighting or underlining. H1 headings are centered.
The HP0 through HP9 highlighting phrase tags are not allowed in print panel defi-
nitions. Highlighting, underline, and double strike are not supported. (A double
strike is when the printer prints a letter and then prints the same character or
another character in the same position.)
Printing the Trailer

The one-line trailer is specified using the print trailer message (PRTTRAIL) tag in a
print head panel. This is a one-line statement such as:
'E N D O F L I S T I N G'. It is printed at the end of an application's printout
when the Remove Print Application (QUIRMVPA) or Close Application (QUICLOA)
API is called.
Defining Prolog Areas

A print head panel (PRTHEAD) is used to define the prolog and header sections.
The print head panel can contain only information and data areas. List areas are
not allowed.
With TYPE=PROLOG specified, the prolog section consists of one or more data
areas, one or more information areas, or a combination of both. The prolog section
is printed only from the first print head panel that is printed for each open printer
file. An attempt to print a print head panel containing a prolog section causes an
escape message if the print head panel is not the first one printed for an open
printer file.
Defining Header Areas

With TYPE=NORMAL specified, the header section is made up of one or more data
areas, one or more information areas, or a combination of both. The total depth of
the information and data areas in the header section must be less than or equal to
six lines.
The minimum page length is 18 lines. To ensure that there is room for data on
each page, with the possible exception of the first, the UIM limits the combined total
depth of the prolog and header sections to 14 lines. If these maximums are not
followed, a compile-time error message occurs.
A title line must be printed at the top of every page, so the UIM requires that a print
head panel be printed before any other print panels. The Print Panel (QUIPRTP)
API needs to be called only once for the print head panel for each printer file. After
that, the same header information is printed on each page of the printer file. To

Print Concepts
change the header information, call the QUIPRTP API again for the same or dif-
ferent print head panel.
Using the Page-Eject Function During Printing

An automatic page eject occurs when a print head panel is printed after printing a
print panel. However, even if eject is specified on the print panel (PRTPNL) tag,
when the next print panel is printed, it does not cause a second page eject.
When a print head panel is processed by the Print Panel (QUIPRTP) API, it is not
actually printed until another QUIPRTP API is called for a print panel. Therefore, if
the QUIPRTP API is called for five different print head panels before the QUIPRTP
API is called for a print panel, only the last print head panel affects the listing.
Sharing and Overriding Printer Files

The UIM allows multiple UIM applications to print to the same printer file by
opening the printer file for sharing. However, the UIM does not share information
between multiple UIM applications.
If multiple UIM applications are printing to the same printer file, it is possible to
have more than one prolog section per printer file, because a prolog section, if
there is one, is printed once per open application.
Care must be taken when working with a shared file to avoid inadvertently sharing
with a higher or previous program in the program stack. Sharing a printer file
between a UIM application and an application using a DDS record format file does
not work. The shared file is closed when the last application sharing the shared file
uses a Close Application (QUICLOA) or Remove Print Application (QUIRMVPA)
API.
The printer file is opened to allow most overrides.
Printing Double-Byte Character Set (DBCS) Considerations

The UIM checks the TXTMODE attribute of the panel group (PNLGRP) tag to deter-
mine if double-byte data might be printed. If it might be printed, the UIM opens the
printer file to contain DBCS data. For more information on DBCS, see Appendix D,
“Double-Byte Character Set Support for Displays” on page D-1.
Commonly Asked UIM Questions

Here are some commonly asked questions which relate to exit programs and call
programs:
What are exit programs and call programs?

– Exit programs—UIM provides the ability for the user to define programs that
are called after normal processing has completed in those cases where
further processing on the data is required. For example, a general panel
exit is allowed to do more specific validity checking on the panel than what
UIM functions will handle.
– Call programs—Call programs are programs that are written by the user to
be called by UIM for such items as processing a function key, a pull-down
option, or list option. This processing may include refreshing a list panel,
calling another program to display a more detailed panel or to update a file
with the information entered, and so on.

Print Concepts
What is the difference between an exit program and a call program?

– An exit program is called after normal processing is complete and a call
program is called as part of the normal processing. Normal processing
refers to processing items such as ACTION, ENTER, and PROMPT actions
on a LISTACT tag.

Part 4. Programming Help Displays
Chapter 18. Making Online Help Information Accessible for Your
Display File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1
Enabling the Help Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2
Choosing between Panel Groups, Documents, and Records for Help . . . . 18-2
Defining Which Areas of Your Display Need Online Help Information . . . . . 18-3
Specifying Panel Groups for Help in Your Display File . . . . . . . . . . . . . 18-6
Copying QUSRTOOL Examples That Specify Help Using Panel Groups . 18-9
Specifying Documents in Your Display File . . . . . . . . . . . . . . . . . . . . 18-9
Specifying Records in Your Display File . . . . . . . . . . . . . . . . . . . . . 18-12
Entering the Records That Contain the Help Information . . . . . . . . . 18-14
Using Records and Documents for Help in the Same Display File . . . . 18-15
Understanding the Restrictions on Records . . . . . . . . . . . . . . . . . 18-15
Paging between Help Displays That Use Records . . . . . . . . . . . . . 18-16
Understanding How the System Pages Help Displays . . . . . . . . . 18-16
Displaying Secondary Online Help Information . . . . . . . . . . . . . . 18-17
Returning Control to Your Program after Pressing the Help Key . . . . . . 18-20
Returning Control to Your Program after Showing the Help Display . . . 18-20
Returning Control to Your Program without Showing the Help Display . 18-22
Chapter 19. Making Online Help Accessible for Your Panel Group . . . 19-1
Definitions and Explanations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-1
Giving Help Panel Groups Access to InfoSeeker . . . . . . . . . . . . . 19-3
Giving Help Panel Groups Access to Index Search . . . . . . . . . . . . 19-4
Giving Help Panel Groups Access to A User-Defined Panel Group . . . 19-4
Removing Access to F18=More Indexes . . . . . . . . . . . . . . . . . . 19-5
Help in a List Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-5
Coding Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-6
Help in a Menu Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-7
Coding Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-7
Help in a Data Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-9
Coding Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-10
Help in a Menu Bar Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-13
Coding Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-14
Help in a Function Key Area . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-15
Coding Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-16
Chapter 20. Defining Online Help Information . . . . . . . . . . . . . . . . 20-1

Defining Online Help Information in a Panel Group . . . . . . . . . . . . . . . 20-1
Entering the UIM Source for a Panel Group for Help . . . . . . . . . . . . . 20-1
Organizing a Panel Group with Help Modules . . . . . . . . . . . . . . . 20-2
Using the Information in a Help Module More Than Once . . . . . . . . 20-2
Using a Help Module Contained in a Different Help Panel Group . . . . 20-3
Emphasizing and Formatting the Text within a Help Module . . . . . . . 20-4
Adding Index Search Tags to a Help Panel Group . . . . . . . . . . . . 20-6
Linking Help Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-13
Creating and Deleting Panel Groups . . . . . . . . . . . . . . . . . . . . . 20-15
Assigning Panel Groups as Help for Commands . . . . . . . . . . . . . . 20-16
Using Panel Groups in a Search Index . . . . . . . . . . . . . . . . . . . . 20-16
Creating a Search Index . . . . . . . . . . . . . . . . . . . . . . . . . . 20-16
Adding Entries to a Search Index . . . . . . . . . . . . . . . . . . . . . 20-17

Removing Entries from a Search Index . . . . . . . . . . . . . . . . . . 20-17
Deleting a Search Index . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-17
Copying QUSRTOOL Examples That Define Help in a Panel Group . . 20-18
Defining Online Information in a Document . . . . . . . . . . . . . . . . . . . 20-18
Creating a Document for Help . . . . . . . . . . . . . . . . . . . . . . . . . 20-18
Viewing the Document without Pressing the Help Key . . . . . . . . . . . 20-19
Defining Online Help Information in a DDS Record . . . . . . . . . . . . . . 20-19

Chapter 18. Making Online Help Information Accessible for
Your Display File
Application help is a function provided by the system that lets you define online
help information for the records in a display file and then presents that help to the
user when the Help key is pressed.
The following illustration shows what happens when the Help key is pressed and
online help information is available and accessible:
User presses Help key
F1
Display file suspended
Display
File Display
Online help information displayed
Help XXX
User exits help display
F3 F12 Enter
or or
Display file is displayed
Display
File Display
RV2W018-4
Note: Caution is advised when using application help with multiple display stations
acquired to the file because all display stations wait for the completion of
the application help display.
To provide online help information for your display, you need to do the following:
Add to your display file the necessary DDS keywords to make online help infor-
mation accessible for your display. This chapter provides instructions for
adding these keywords.

Define the help information that the user sees using either a panel group, docu-
ment, or record. Chapter 20, “Defining Online Help Information” on page 20-1
provides instructions for defining the help information.
For more information about the DDS keywords described in this chapter, see
the DDS Reference.
Enabling the Help Key

If online help information is available for your display, you must enable the Help key
on the keyboard. To enable the Help key, specify the HELP keyword at the file or
record level of your DDS source.
Choosing between Panel Groups, Documents, and Records for Help

You can define online help information by using one of the following:
Table 18-1. Different Ways to Define Online Help Information

Method Description
Panel group Objects into which user interface manager (UIM) source is entered
Documents Objects created using AS/400 OfficeVision
Records A set of DDS keywords contained in a source file member
Each method has characteristics that can help you choose the method that will
work best for you. The following table lists these characteristics and the method or
methods that they apply to:
Table 18-2 (Page 1 of 2). Characteristics of Different Methods of Online Help Information
Panel
Characteristic Groups Documents Records
Accessible through H specifications for X X X
DDS-described displays
Allows cursor-sensitive help X X X
Allows extended help X X X
Index search function available X
InfoSeeker function available X
Windows used X
Hypertext linking available X
Used by system displays X
Can be used for command help X
Word processing functions, such as spell X (See X
checking, available note.)

Table 18-2 (Page 2 of 2). Characteristics of Different Methods of Online Help Information
Panel
Characteristic Groups Documents Records
Bookmark and exit function available (allows X
you to return to the same location in the help
the next time you press the Help key)
Allows printing of help information X X X
Index for displayed information available X
Table of contents for displayed information X
available
Can be placed in same member as display X
source
Same source type as display source X
QUSRTOOL example available X
Option indicators allowed X X X
Supports DBCS online help information X X
Right-to-left and left-to-right orientation of X
text
Supported for acquired devices X
Defining Which Areas of Your Display Need Online Help Information

You can define the display file so that you supply the online help information for all
or part of a display, as represented by the shaded areas in the following figure:
RV2W020-2
.1/ Contextual help

Information for rectangular areas that are defined by a record or part of a
record format. Contextual information describes one or more fields on a
display.
.2/ Extended help
All information for the entire display, beginning with the information about the
purpose and use of the display and followed by contextual help for each field.
Extended help is displayed when you press the Help key on an area of the
display that does not have contextual help defined for it. If your online help
information is defined using panel groups, you can also reach extended help
from contextual help by pressing F2.
The cursor location is determined when the Help key is pressed. If the Help key is
enabled and the cursor is in any active help area, the online help information asso-
ciated with that help area is displayed.
Chapter 18. Making Online Help Information Accessible for Your Display File 18-3
Each help area on a display is defined in the DDS source using the following:
H specification
Defines help for the containing record. An H in column 17 of the DDS
source indicates a help specification level. The help specifications are
defined before the first field in the record.
Help Area (HLPARA) keyword
Defines a help area by giving the upper-left row column and lower-right
row column of the rectangular area. These coordinates must be located in
the screen area, but are not required to be in the record area.
If *RCD is specified for the HLPARA keyword, the help is associated with
the entire record area, which includes all columns in the lines occupied by
the record. When the cursor is located in the record area and the Help
key is pressed, the online help information from the record on the HLPRCD
keyword is displayed.
Help (HLPxxx) keyword
Defines whether a panel group (HLPPNLGRP), document (HLPDOC), or
record format (HLPRCD) contains the actual online help information that
you see when you press the Help key.
The following illustration shows how H specifications are entered in your DDS
source:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
H HLPARA(\RCD)
HLPxxx(required-variables)
Figure 18-1. Sample H Specification in DDS Source
This sample DDS defines help for a record. The required variables for the help
keyword depend on whether HLPxx is defined as a HLPPNLGRP, HLPDOC, or
HLPRCD keyword. Only one help keyword can be defined for the file, but you can
specify one or more H specifications for a record.
The order of H specifications is important because the first match found is selected.
Therefore, the more specific HLPARA locations should be listed first.
The following sample display is defined with two record formats, HEADER and
SINFO:

Record
HEADER
(lines 5-7)
Record
SINFO
(lines 15-17)
RV2W022-3
The following table shows one way to define the online help information for the
sample display:
Table 18-3. Help for Sample Display

Location on
Display Location in DDS Source Description of Help Provided
Lines 5-7 Entire record format HEADER Help is specified for the whole
record
Line 15 First line in record format SINFO Help is specified for the line only
Line 16 Second line in record format Help is specified for the line only
SINFO
Line 17 Third line in record format Help is specified for the line only
SINFO
Remaining lines Areas in display file that are not Help is specified for the whole file
defined with record formats
Depending on the help method you plan to use, continue with any of the following
to define H specifications in your DDS source:
Panel groups (UIM)
“Specifying Panel Groups for Help in Your Display File” on page 18-6
Documents (OfficeVision)
“Specifying Documents in Your Display File” on page 18-9
Records (DDS)
“Specifying Records in Your Display File” on page 18-12
To compare and contrast the different ways to create online help information, see
“Choosing between Panel Groups, Documents, and Records for Help” on
page 18-2.
Specifying Panel Groups for Help in Your Display File
The HLPPNLGRP keyword in DDS identifies the panel group that contains online
help information for a display. The HLPPNLGRP keyword may be specified in an H
specification or at the file level. To use the HLPPNLGRP keyword, you need to
know the name of the help module and the name of the panel group and library
that contains that help module.
Several other DDS functions are available for use with panel groups. The functions
and their associated DDS keywords are described in the following table:
Table 18-4 (Page 1 of 2). Other DDS Keywords for UIM Help
Function DDS keyword Description
Defining the name of the HLPTITLE The text to be displayed on the first line of
help screen the help display is defined with the file- or
record-level DDS keyword HLPTITLE (Help
Title). This text should be the name of the
display that is displayed when the Help key
is pressed. The HLPTITLE keyword must
be used in the display file. This keyword is
used only on full-screen displays of help
when no help title is specified in the help
source.
Indicating full-screen HLPFULL Using the DDS file-level HLPFULL (Help
online help information Full) keyword, the UIM-defined online help
information for the application is displayed
in a full-screen replacement display rather
than in a window.
When the HLPFULL keyword is not speci-
fied, the help is displayed in a window
unless the user's profile specifies other-
wise.
Excluding panel group HLPEXCLD The HLPEXCLD keyword excludes a help
help as secondary help panel group with a duplicate name from
information being displayed within extended help. To
do this, place HLPEXCLD on all but the
first H specification that names an identical
help panel group. HLPEXCLD indicates
that the information associated with the H
specification is not displayed as part of the
extended help.
When the HLPEXCLD keyword is not
specified, extended help consists of the
information associated with both the file-
level HLPPNLGRP keyword (if any) and
the HLPPNLGRP keywords on all active H
specifications.
At least one help panel group name must
not specify the HLPEXCLD keyword.
Enabling the Index HLPSCHIDX The Index Search function is enabled, and
Search function the search index object used for the Index
Search function is specified by the file-level
DDS keyword HLPSCHIDX (Help Search
Index).

Table 18-4 (Page 2 of 2). Other DDS Keywords for UIM Help
Function DDS keyword Description
Enabling the InfoSeeker HLPSHELF The InfoSeeker function is enabled, and
function the bookshelf used for the InfoSeeker func-
tion is specified by the file-level DDS
keyword HLPSHELF (Help InfoSeeker).
Using the sample display from “Defining Which Areas of Your Display Need Online
Help Information” on page 18-3, the following online help information is defined for
each help area:
Record
HEADER
(lines 5-7)
Record
SINFO
(lines 15-17)
RV2W023-5
Table 18-5. Help for Sample Display Using Panel Groups

Name of Help Module in Panel
Location on Group SMPPNL in Library
Display Location in DDS Source SMPLIB
Lines 5-7 Entire record format HEADER HLPCMPY
Line 15 First line in record format SINFO HLPADDR
Line 16 Second line in record format HLPCITY
SINFO
Line 17 Third line in record format HLPST
SINFO
All shaded Areas in display file that are not SUPHELP
areas defined with records
The following DDS source shows how the help areas are defined for the sample
display using panel groups:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
HELP
HLPPNLGRP(SUPHELP SMPLIB/SMPPNL)
HLPTITLE('ADD,UPDATE,DISPLAY SUPPLIER')
R HEADER OVERLAY
H HLPARA(\RCD)
HLPPNLGRP(HLPCMPY SMPLIB/SMPPNL)
5 25'ADD, UPDATE, DISPLAY SUPPLIER'
7 1ð'ENTER NEW OR EXISTING NAME:'
CONAME 1ðA I 7 47
R SINFO OVERLAY PROTECT
H HLPARA(15 1 15 79)
HLPPNLGRP(HLPADDR SMPLIB/SMPPNL)
H HLPARA(16 1 16 79)
HLPPNLGRP(HLPCITY SMPLIB/SMPPNL)
H HLPARA(17 1 17 79)
HLPPNLGRP(HLPST SMPLIB/SMPPNL)
15 1ð'ADDRESS:'
ADDR 3ðA B 15 32
16 1ð'CITY:'
CITY 1ðA B 16 32
17 1ð'STATE:'
STATE 2A B 17 32
Figure 18-2. Sample DDS Source Showing HLPPNLGRP
The file-level help in SUPHELP provides extended help for the display (when the
cursor is not located in the record area for either HEADER or SINFO) because
HLPARA(*RCD) is the location specified on the H specification.
The panel groups that contain the online help information must be created by using
the UIM source from a source file member. More information about creating panel
groups is found in “Defining Online Help Information in a Panel Group” on
page 20-1.
Note: HLPPNLGRP and HLPRCD are not allowed in the same display file;
HLPPNLGRP and HLPDOC are also not allowed in the same display file.
Defining Panel Groups with Option Indicators: The HLPPNLGRP keyword can
be specified with option indicators. In the following example, assume the SINFO
record has indicator 90 on and the cursor is in the help area defined for the H
specification. When the Help key is pressed, the panel group HELP1 is displayed.
If indicator 90 is off, panel group HELP2 is displayed.
The DDS for this file is:

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
HELP
R HEADER OVERLAY
7 1ð'ENTER NEW OR EXISTING NAME'
CONAME 1ðA I 7 47
H HLPARA(15 9 15 61)
9ð HLPPNLGRP(HELP1 SMPLIB/SMPPNL)
H HLPARA(15 9 15 61)
N9ð HLPPNLGRP(HELP2 SMPLIB/SMPPNL)
15 1ð'ADDRESS'
ADDR 3ðA B 15 32
Figure 18-3. Sample DDS Source Showing HLPPNLGRP and Option Indicators
Copying QUSRTOOL Examples That Specify Help Using Panel Groups

The QUSRTOOL library provides four sample DDS-described displays that access
online help information using panel groups. You can copy the source for these
sample displays into a library of your choosing and then tailor them for your own
use. For more information about these sample displays, see “Using the Displays
Example in the QUSRTOOL Library” on page 21-1.
Specifying Documents in Your Display File

Online documents used as help information are created by using the word pro-
cessing function of the OfficeVision licensed program. The document and folders
do not have to exist when you create the display file. More information about cre-
ating documents for help is found in “Defining Online Information in a Document” on
page 20-18.
The source of the online help information that is identified by a help document in
DDS source is specified with the help-specification or file-level DDS keyword
HLPDOC (Help Document). To use the HLPDOC keyword, you need to know the
names of the document and folder (or folders) where the information is stored and
the help information label name that marks the specified location in the document
where the information is located.
each help area:
Record
HEADER
(lines 5-7)
Record
SINFO
(lines 15-17)
RV2W023-5
Table 18-6. Help for Sample Display Using HLPDOC

Name of Help Infor-
Location on mation Label (See
Display Location in DDS Source Note.)
Lines 5-7 Entire record format HEADER HLPCMPY
Line 15 First line in record format SINFO HLPADDR
Line 16 Second line in record format SINFO HLPCITY
Line 17 Third line in record format SINFO HLPST
All shaded areas Areas in display file that are not defined SUPHELP
with records
Note: All help information labels are contained in sample document HELP.DOC in sample
folder HELPFLD.
display using help documents:

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
HELP
HLPDOC(SUPHELP HELP.DOC HELPFLD)
R HEADER OVERLAY
H HLPARA(\RCD)
HLPDOC(HLPCMPY HELP.DOC HELPFLD)
CONAME 1ðA I 7 47
H HLPARA(15 1 15 61)
HLPDOC(HLPADDR HELP.DOC HELPFLD)
H HLPARA(16 1 16 41)
HLPDOC(HLPCITY HELP.DOC HELPFLD)
H HLPARA(17 1 17 33)
HLPDOC(HLPST HELP.DOC HELPFLD)
15 1ð'ADDRESS:'
ADDR 3ðA B 15 32
16 1ð'CITY:'
CITY 1ðA B 16 32
17 1ð'STATE:'
STATE 2A B 17 32
Figure 18-4. Sample DDS Source Showing HLPDOC
The file-level help in SUPHELP is used to provide extended help for the display
(when the cursor is not located in the record area for either HEADER or SINFO)
because HLPARA(*RCD) is the location specified on the H specification.
The DDS keywords HLPDOC and HLPPNLGRP are not allowed in the same
display file. The keywords HLPDOC and HLPRCD are allowed in the same display
file; however, several considerations apply when mixing the two keywords. For
more information about HLPRCD and these considerations, see “Specifying
Records in Your Display File” on page 18-12.
Defining Documents with Option Indicators: The HLPDOC keyword can be

specified with option indicators. In the following example, assume the SINFO
record is put with indicator 90 on and the cursor is in the help area defined for the
H specification. When the Help key is pressed, the HELP#1 document in folder
HELP.F1, starting at location CITY1, is displayed. If indicator 90 is off, the HELP#2
document in folder HELP.F1, starting at location CITY2, is displayed.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
HELP
R HEADER OVERLAY
CONAME 1ðA I 7 47
H HLPARA(15 9 15 61)
9ð HLPDOC(CITY1 HELP#1 HELP.F1)
H HLPARA(15 9 15 61)
N9ð HLPDOC(CITY2 HELP#2 HELP.F1)
15 1ð'ADDRESS'
ADDR 3ðA B 15 32
Figure 18-5. Sample DDS Source Showing HLPDOC and Option Indicators
Specifying Records in Your Display File

The source of the online help information that is identified by a help record in DDS
source is specified with the help-specification or file-level DDS keyword HLPRCD
(Help Record).
HLPRCD and HLPPNLGRP are not allowed in the same display file.
each help area:
Record
HEADER
(lines 5-7)
Record
SINFO
(lines 15-17)
RV2W023-5

Table 18-7. Help for Sample Display Using HLPRCD
Location on Name of Record Format that
Display Location in DDS Source Contains Help
Lines 5-7 Entire record format HEADER Record format HLPCMPY
Line 15 First line in record format SINFO Record format HLPADDR
Line 16 Second line in record format Record format HLPCITY
SINFO
Line 17 Third line in record format Record format HLPST
SINFO
All shaded Areas in display file that are not Record format SUPHELP
areas defined with help record
display using help records:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
HELP
HLPRCD(SUPHELP)
R HEADER OVERLAY
H HLPARA(\RCD)
HLPRCD(HLPCMPY)
CONAME 1ðA I 7 47
H HLPARA(15 1 15 61)
HLPRCD(HLPADDR)
H HLPARA(16 1 16 41)
HLPRCD(HLPCITY)
H HLPARA(17 1 17 33)
HLPRCD(HLPST)
15 1ð'ADDRESS:'
ADDR 3ðA B 15 32
16 1ð'CITY:'
CITY 1ðA B 16 32
17 1ð'STATE:'
STATE 2A B 17 32
Figure 18-6. Sample DDS Source Showing HLPRCD
The file level help is used to provide general help for the display when the cursor is
not located in any of the defined help areas for either HEADER or SINFO.
You are not required to define each help area with a different record. This means
that the same record may be used to define one or more help areas on a display,
including the help area that defines the entire display.
Defining Records with Option Indicators: The HLPRCD keyword can be speci-
fied with option indicators. In the following example, assume the SINFO record is
put with indicator 90 on and the cursor is in the help area defined for the H specifi-
cation. When the Help key is pressed, the record HELP#1 is displayed. If indicator
90 is off, the record HELP#2 is displayed.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
HELP
R HEADER OVERLAY
CONAME 1ðA I 7 47
H HLPARA(15 9 15 61)
9ð HLPRCD(HELP#1)
H HLPARA(15 9 15 61)
N9ð HLPRCD(HELP#2)
15 1ð'ADDRESS'
ADDR 3ðA B 15 32
Figure 18-7. Sample DDS Source Showing HLPRCD and Option Indicators
Entering the Records That Contain the Help Information

The records that give the actual online help information may be included in the
same file as the DDS source for the application display. The records may also be
contained in a different file. If the records are contained in a different file, the file
and the library that contains the file must be identified on the HLPRCD keyword.
Regardless of where the information is contained, the DDS source for the previous
example looks like the following:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
R SUPHELP
2 5'TO ADD, UPDATE, OR DISPLAY -
THE SUPPLIER NAME AND -
ADDRESS, ENTER THE SUPPLIER -
NAME. ITS CURRENT ADDRESS, -
IF ANY, WILL BE SHOWN AND MAY -
BE UPDATED.'
R HLPCMPY
2 5'ENTER THE FIRST 1ð -
CHARACTERS OF THE COMPANY'
R HLPADDR
2 5'ENTER THE NEW OR CHANGED -
ADDRESS.'
R HLPCITY
2 5'ENTER THE FIRST 1ð -
CHARACTERS OF THE CITY'
R HLPST
2 5'ENTER THE 2 CHARACTER ABBR -
FOR THE STATE.'
Figure 18-8. Sample DDS Source with HLPRCD

Using Records and Documents for Help in the Same Display File
HLPRCD and HLPDOC are allowed in the same display file; however, the following
considerations apply:
When the Help key is pressed with the cursor location in a help area described
by a document, that document is the only help displayed when the roll keys are
used. No other document or help records are displayed.
When the Help key is pressed with the cursor location in a help area described
by a record, the normal sequencing used for records is followed with docu-
ments being ignored.
The HLPDOC and HLPRCD keywords cannot both be specified at the file level
or on the same H specification.
The HLPBDY keyword cannot be specified with the HLPDOC keyword. For
more information about the HLPBDY keyword, see “Displaying Secondary
Online Help Information” on page 18-17.
Understanding the Restrictions on Records

The following restrictions apply when using the record form of application help:
The application program does not control the displaying of the records. When
the Help key is pressed, the system controls the displaying of help. Because
the system does not control the buffers or hidden message line areas of the
application program, the following takes place:
– Output fields in the record formats are displayed as blanks.
– The ALIAS keyword is allowed but ignored.
– CSRLOC and MSGID are processed by the system, but the hidden and
program-to-system fields are not passed from the application program.
No input is returned to the user program:
– Input-capable fields on a record are displayed with underlines; however, no
input is returned to the application program. Any input typed in an input
field is lost when application help is finished.
– Response indicators are not returned.
Help records can contain H specifications, but they are ignored.
Option indicators are assumed to be off.
Screen size conditioning can be used.
Only the following keywords are active when specified for records:
COLOR
DATE
DFT
DSPATR
DSPSIZ
MSGCON
MSGLOC
TEXT
SLNO (constant value). If SLNO(*VAR) is specified, 1 is used for the
starting line number.
SYSNAME
TIME
USER
All other display file keywords, though allowed, do not make sense for records
and may or may not be processed while displaying the help.
Paging between Help Displays That Use Records

If you use records to define help information, the first display that appears when the
Help key is pressed is called primary help. When a Roll Up or Roll Down key is
pressed on a primary help display, secondary help is shown.
Understanding How the System Pages Help Displays

The system maintains a list of all active H specifications from record formats that
are on the display. This list of H specifications is called the help list. The H spec-
ifications on the front of the help list are the first to be searched when the user
presses the Help key.
Pressing the Help key in a help area on the display does the following:
H
Display
File Display H Help XXX
H
H
H
RV2W019-3
.1/ Suspends the display file.

.2/ Searches the list of active help areas to find the first one in the list that con-
tains the cursor location when the Help key is pressed.
.3/ Opens the display file that contains the help record and displays the informa-
tion.
.4/ Allows the user to roll forward or backward through the online help informa-
tion.
The order and content of the H specifications in the list are determined by the fol-
lowing:
When a record format is added to the display, the H specifications for that
record format are placed on the front of the list.
If the record format contains more than one H specification, they are added to
the help list in the order in which they are defined in the display file.
The help list is cleared either when a record format is written that clears the
display, or when one is written that has the HLPCLR keyword enabled.
If a record has the OVERLAY keyword in effect, has H specifications, or com-
pletely or partially overlaps another record already on the display, the help list
is updated in different ways. The following table describes the type of help-list
updating for records for each combination of the three factors:

Overlay H Specifications Overlaps Help List Update
No No N/A Help list is cleared.
No Yes N/A Help list is cleared and H specifica-
tions for the record are added to the
help list.
Yes No No Help list is not changed.
Yes No Yes H specifications are removed from
the help list if they are within the
boundaries of the record being
written.
Yes Yes No H specifications for the record are
added to the help list. H specifica-
tions are removed from the help list if
they are within the boundaries of any
H specification in the record being
added.
Yes Yes Yes H specifications are removed from
the help list if they are within the
boundaries of the record being
written. Then the H specifications for
the record are added to the list.
Finally, H specifications are removed
from the help list if they are within
the boundaries of any H specification
in the record being added.
Note: An H specification with *NONE specified for the help area is removed from
the help list when the first H specification with a help area defined above it
is removed. If a help specification with *NONE specified for its help area is
the first help specification, then it is only removed when the help list is
cleared or when a help specification with a help area is placed above this
help specification. This H specification is removed when the one above it is
removed.
Displaying Secondary Online Help Information

The record formats that are displayed as secondary help come from the same help
group, or if none is available there, from the same help sublist as the record format
that is currently displayed.
A help group is defined with the HLPSEQ keyword and consists of those record
formats that have the same group name specified. The HLPSEQ keyword allows
you to specify the help group name and the help sequencing number. The help
sequencing number specifies the order in which the help will be displayed. If two
record formats that are in different display files happen to have the same group
name, they are still considered to be in separate help groups. Record formats that
do not have a HLPSEQ keyword specified are considered to be groups of one.
A help sublist contains all of those H specifications defined between help bounda-
ries. The HLPBDY keyword partitions the help list into sublists by defining help
boundaries. (The H specification that has the HLPBDY keyword coded is consid-
ered to be before the boundary.) Sublists are important when using the roll keys to
look at more online help information.
Determining the Sequence of Secondary Help: Depending on whether you are
using the Roll Up or Roll Down key, the system selects secondary help as follows:
1. A help record format that is in the same help group as the current help record
format and has the next highest help sequencing number (if the Roll Up key is
pressed) or next lowest help sequencing number (if the Roll Down key is
pressed) is selected.
2. If the current help record format already has the highest help sequencing
number (if the Roll Up key is pressed) or the lowest help sequencing number (if
the Roll Down key is pressed) in the group, the help sublist is searched for the
next H specification that does not refer to the same help group as the currently
displayed record format.
Notes:
a. To prevent including unexpected help, it is recommended that the HLPBDY
keyword be specified on the last H specification in each record of the appli-
cation display file. This defines one sublist for each record that has help.
However, if multiple records are on the screen, this may not be desirable.
In this case, the HLPBDY keyword should be in effect only on the last
record put to the screen.
b. Because this second method works only when a sublist can be identified, it
is not used if the primary help was the default record format for the file (for
example, if it was selected from the file-level HLPRCD keyword).
3. Searching in the sublist continues until the boundary of the sublist is reached.
The search then wraps to the other end of the sublist and continues until the
current H specification being displayed is reached.
4. If no H specification that has a satisfactory HLPRCD is found, the record format
in the help display file that has the same help group name and the lowest help
sequence number (if the Roll Up key is pressed) or the highest help sequence
number (if the Roll Down key is pressed) is selected. This method always finds
a match because the current help format always meets this criteria if no other
format does.
In the following example, the fields and HLPARA keywords are not specified
because neither has an effect on the order of secondary information:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
HELP
HLPRCD(HELP11)
R RECORD1
H HLPRCD(HELP1)
H HLPRCD(HELPSCR1)
HLPBDY
H HLPRCD(HELP2SRC)
HLPBDY
Figure 18-9. Sample DDS Source to Show Secondary Help
The sample file HELPFILE contains the following record formats with HLPSEQ
keywords coded as shown:

Record Keyword Specification
HELP HLPSEQ(GROUPA 1)
HELP1 HLPSEQ(GROUPA 2)
HELP11 HLPSEQ(GROUPA 3)
HELPSCR1 HLPSEQ(GROUPB 1)
HELPSCR2 HLPSEQ(GROUPB 2)
HELP2SRC
Note that the help record formats HELP and HELPSCR2 are not referred to in the
application display file. Because they are not referred to in this way, they are not
primary help, but they are displayed as secondary help as follows:
Sequence 1:
Primary help format HELP11
Press Roll Down HELP1
Press Roll Down HELP
Press Roll Down HELP11
In this first sequence, HELP1 is shown when the Roll Down key is pressed
because this is the previous help record format in GROUPA. Similarly, HELP is
shown when Roll Down is pressed the second time. When Roll Down is pressed
the third time, the end of the help group is reached. HELP11 is then selected
again because it is the last help record format in the original help group.
Sequence 2:
Primary help format HELPSCR1
Press Roll Up HELPSCR2
Press Roll Up HELP1
Press Roll Down HELP
The second sequence starts with HELPSCR1 being displayed as the primary help
record format. Pressing Roll Up causes HELPSCR2 to be displayed because it is
the next help record format in GROUPB. Rolling up again runs off the end of the
group and HELP1 is found because it is the next help record format found, after
wrapping, in the sublist that contains HELPSCR1. Pressing Roll Down now causes
HELP to be displayed because it is the previous entry in GROUPA.
Sequence 3:
Primary help format HELP2SRC
Press Roll Up or Down HELP2SRC
Because HELP2SRC is not in a help group and is the only one in its sublist,
HELP2SRC is to be shown when rolling in either direction.
Understanding the Restrictions of Records for Secondary Help: The following

restrictions apply when using the record form of application help:
Application help controls all function keys when a help record is displayed:
– The Roll Up key is enabled and causes the next record to be displayed
according to the rules for displaying secondary help.
– The Roll Down key is enabled and causes the previous record to be dis-
played according to the rules for secondary help.
– The Enter key is enabled and causes a return to the application program.
Any CAnn or CFnn key enabled for the record will also cause a return to
the application program. All other function keys, including the Help key, are
ignored.
Records with the USRDFN, SFL, and SFLCTL keywords may not be used as
records. When a display file is created, a diagnostic is issued if the HLPSEQ
keyword is found on a record with one of these keywords. When the applica-
tion is running, error reset message CPD4050 is issued if a record with one of
these keywords is used as help. The help record is not displayed.
The KEEP and ASSUME keywords should be avoided on records because they
cause results that cannot be predicted.
Returning Control to Your Program after Pressing the Help Key

Depending on how you code your DDS, you can return control to your program in
one of two ways after you press the Help key:
You can display online help information and then return control to the program.
You can return control to the program immediately without displaying the online
help information.
Returning Control to Your Program after Showing the Help Display

Use the help command key (HLPCMDKEY) keyword to return control to your appli-
cation program from the application help record format after a command attention
(CAnn) or command function (CFnn) key has been pressed. A CFnn key returns
data to the application program, while a CAnn key does not return data to the appli-
cation program.
The command key must apply to both the application record format and the
application-help record format. If a CAnn or CFnn key does not apply to the
application-help record format, the HLPCMDKEY keyword is ignored.
The following DDS source, which uses help records, shows how the HLPCMDKEY
keyword is specified:

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
R APPRCD CAð1
CAð3
CFð4
HELP
H HLPRCD(HELPRCD)
HLPARA(1 1 24 8ð)
8 2'THIS IS THE APPLICATION'
9 2'RECORD FORMAT'
INPUT1 1ð B 12 1ð
INPUT2 1ð B 13 1ð
INPUT3 1ð B 14 2ð
\
R HELPRCD HLPCMDKEY
CAð1
CFð3
8 2'SPECIFY COMPANY NAME'
9 2'SPECIFY STREET'
1ð 2'SPECIFY CITY, STATE, ZIP'
Figure 18-10. Sample DDS Source to Show HLPCMDKEY
If the user is on the application help display that uses the previous data description
specifications, the following happens when the various keys are pressed:
The CF04 key, which is specified only on the application record format, acts the
same as the Enter key.
The CMD3 key acts the same as the Enter key. Corresponding CAnn or CFnn
keys must be specified on both the application-help record format and applica-
tion record format for control to return to the program.
The CA01 key returns control to the application program.
In the next example, response indicators are used. When a response indicator is
specified on a CAnn or CFnn key on the application record format (for example,
CF12(12)), the response indicator is returned after the application-help record
format is displayed. When a response indicator is specified on a CAnn or CFnn
key on the application-help record format (for example, CF01(11)), the response
indicator is ignored.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7...
R APPRCD CAð1
CAð3
CF12(12)
HELP
H HLPRCD(HELPRCD)
HLPARA(1 1 24 8ð)
8 2'THIS IS THE APPLICATION'
9 2'RECORD FORMAT'
INPUT1 1ð B 12 1ð
INPUT2 1ð B 13 1ð
INPUT3 1ð B 14 2ð
\
R HELPRCD HLPCMDKEY
CFð1(11)
CF12
8 2'SPECIFY COMPANY NAME'
9 2'SPECIFY STREET'
1ð 2'SPECIFY CITY, STATE, ZIP'
Figure 18-11. Sample DDS Source to Show HLPCMDKEY and Response Indicators
Returning Control to Your Program without Showing the Help Display

Use the HLPRTN keyword to immediately return control to your program (instead of
displaying help) when the Help key is pressed.

Chapter 19. Making Online Help Accessible for Your Panel
Group
The Help key on most keyboards is either a key specifically labeled Help, or it is a
key defined to work as a Help key and labeled with another name. This varies
among keyboards, but the F1 key is commonly defined as an alternate for the Help
key.
When the user presses the Help key, a sequence of events occur, as illustrated by
the following diagram:
UIM Panel
F1 Help
or
Online help information displayed Current UIM

panel is
displayed
Help XXX
User exits help display
1
F3 F12 Enter
or or
1
If the cursor is on a hypertext link when you press the
Enter key, instead of returning to the current UIM panel,
you are taken to the hypertext information.
RV2W061-2
When the user presses the Help key, the current panel is suspended by the UIM
and a help panel is displayed with information about a specific item, group of items,
area on a panel, or the entire panel. When the user has read the displayed help,
the user presses the F3, F12, or Enter key to return to the current panel before the
Help key was pressed.
Definitions and Explanations

Help for a panel is constructed from help modules referred to in the panel definition.
The UIM requires you to define online help information for panels in a panel group,
and presents the help to the user when the HELP dialog command is requested.

The user requests the HELP dialog command by pressing a key assigned to it.
Typically, the engraved Help key and the F1 key are assigned to the HELP dialog
command. In this section, the term Help key refers to any key which is assigned
to the HELP dialog command.
Online help information is the information displayed to the user when the Help
key is pressed on the keyboard. The level of help displayed depends on the
location of the cursor when the user presses the Help key.
Help is always available for the entire panel. This help is known as extended
help, which is the general information for a panel. Extended help begins with infor-
mation about the purpose and use of the panel and is followed by contextual help
for each item on the panel. Extended help includes contextual help for items that
do not currently show on the screen, but which can be shown by using the Page
Up and Page Down keys. (Contextual help provides information about a single
item or group of related items where the cursor is positioned when the user
requests help.) An item is excluded from extended help when the item is not cur-
rently active for the panel by using the COND attribute for a specific item on the
panel.
Extended help is displayed when the Help key is pressed for an area of the screen
that does not have contextual help defined. It is also displayed when the user
presses F2 (Extended help) while viewing contextual help.
The extended help is defined on the HELP attribute of the display panel (PANEL)
tag. This attribute identifies the help module containing the beginning of the
extended help for the panel.
When coding online help for a panel, the tag which actually contains the information
that is displayed when the user presses the Help key is the help module (HELP)
tag. For more information on the attributes of this tag, see “HELP (Help Module)”
on page A-60.
To code for help in a panel, the HELP attribute must be specified on the tag for
which the help is provided. The name of the help module containing the help infor-
mation is specified on the HELP attribute of a tag.
The help module identified on a HELP attribute exists in the same panel group or
menu where that HELP attribute appears, or in another panel group. When the
panel group or menu is created, the UIM compiler determines the panel group in
which the UIM will find the help module when the Help key is pressed by finding a
help module name that matches the name specified on the HELP attribute in one of
the following places:
1. If the panel group or menu being created contains a matching name on the
NAME attribute of a HELP tag, the help module is found in the same panel group
or menu when the Help key is pressed.
2. If the panel group or menu being created contains a matching name on the
NEWNAME attribute of an import (IMPORT) tag, the help module is found in the
panel group specified on the PNLGRP attribute of the IMPORT tag.
3. If the panel group or menu being created contains an IMPORT tag with NAME='*'
specified, the help module is found in the panel group specified on the PNLGRP
attribute of the IMPORT tag.

If all of the above are not true, the UIM compiler reports an error message and the
panel group or menu is not created.
When specifying the name of a help module, apostrophes are not necessary unless
characters other than A through Z, a through z, and 0 through 9 are used. If any
other keyboard characters are used, apostrophes are required. For example, in a
name specifying HELP='key/enter', the apostrophes are required because the slash
(/) is not an alphabetic character or a numeral. For more information on the rules
for names, see “Name Syntax” on page A-4.
Giving Help Panel Groups Access to InfoSeeker

InfoSeeker provides access to AS/400 online books. You can give a UIM help
panel group access to InfoSeeker using the :HLPSHELF parameter on the
:PNLGRP tag. Here is an example of the UIM coding to give a help panel group
access to InfoSeeker:
:PNLGRP HLPSHELF=LIST.
..
.
:HELP.
..
.
:EHELP.
..
.
:EPNLGRP.
The :HLPSHELF parameter causes the F11=InfoSeeker key to display on the help
panel for the UIM panel. Pressing F11=InfoSeeker displays the InfoSeeker main
display as shown in Figure 19-1. The LIST value on the :HLPSHELF parameter
causes the default list of online books and bookshelves to display.
à InfoSeeker
ð
1=Open 2=Search 4=Remove from view 8=Display description
9=Put in shelf 11=Update bookshelf
Opt Description
__ (S) AS/4ðð General System Information
__ \ (S) AS/4ðð Planning and Installation
__ (S) AS/4ðð Operation
__ (S) AS/4ðð System Management
__ (S) AS/4ðð Communications and Connectivity
__ (S) AS/4ðð Using Applications
__ (S) AS/4ðð Application Development
__ (S) AS/4ðð Environments, Program Interfaces, and Enablers
__ \ (S) AS/4ðð Migration
__ (S) AS/4ðð Service
__ (S) AS/4ðð All System Books
__ (S) AS/4ðð Redbooks
__ (B) My Little User's Guide
Bottom
F3=Exit F5=Refresh F6=Change list F9=Command line
F12=Cancel F13=Sort F17=Position to F24=More keys
á ñ
Figure 19-1. InfoSeeker Display
Chapter 19. Making Online Help Accessible for Your Panel Group 19-3
Giving Help Panel Groups Access to Index Search
Index search provides access to user created search indexes. You can give a UIM
help panel group access to these search indexes using the :SCHIDX parameter on
the :PNLGRP tag. Here is an example of the UIM coding to give a help panel
group access to index search:
:PNLGRP SCHIDX=search index
..
.
:PANEL.
..
.
:EPANEL.
..
.
:EPNLGRP.
The :SCHIDX parameter causes the F11=Search Index key to display on the help
panel for the UIM panel. Pressing F11=Search Index displays the index search
main display as shown in Figure 19-2. The search index specified on the :SCHIDX
parameter will be the search index displayed on the index search screen.
à Search Index
ð
Type options, press Enter. (+ indicates an expandable topic)
5=Display topic 6=Print topic 7=Expand topic 8=Compress topic
Opt Topic
Title of this index
_ Main Help Topic
_ Help number 1
_ Help number 3
_ Help number 4
_ Help number 2
_ Help number 3
Bottom
Or type search words and press Enter. (\ indicates a topic match)
________________________________________________________________________
F3=Exit help F5=All topics F6=Main topics F11=Hide structure

F12=Cancel F13=Information Assistant F18=More indexes F24=More keys
á ñ
Figure 19-2. Index Search Display
Giving Help Panel Groups Access to A User-Defined Panel

Group
The help panels provides access to a user-created panel group. This user-defined
panel group object (*PNLGRP) must be called QGUHISF9, contain a panel called
USERDEF, be located in the user's library list, and the user must have *USE
authority to this object. If the above criteria is met, a function key, F9=User defined
menu will appear on all UIM help and search index panels. This panel group is
intended to be set up in a menu format (similar to the Information Assistant menu
that appears when the user presses F13 from a help panel). An example panel
group would be:

:PNLGRP.
:KEYL NAME=mainkeys help=helpname.
:KEYI KEY=f1 HELP=helpname ACTION='help'.
F1=Help
:KEYI KEY=f3 HELP=helpname ACTION='exit' VARUPD=no.
F3=Exit
:KEYI KEY=f12 HELP=helpname ACTION='cancel' VARUPD=no.
F12=Cancel
:KEYI KEY=f24 HELP=helpname ACTION='morekeys'.
F24=More keys
:KEYI KEY=enter HELP=helpname ACTION='enter'.
:KEYI KEY=help HELP=helpname ACTION='help'.
:KEYI KEY=print HELP=helpname ACTION='print'.
:EKEYL.
:PANEL NAME=userdef HELP=helpname KEYL=mainkeys TOPSEP=sysnam
ENTER='MSG CPD9817'.
User's Info Assist Menu
:MENU DEPTH='\' BOTSEP=space SCROLL=no.
:TOPINST.To select one of the following, type its number below and
press Enter:
:MENUI HELP=helpname OPTION=1 ACTION='cmd dsplibl'.
Display user's library list
:EMENU.
:OPTLINE.Type a menu option below
:EPANEL.
:HELP name=helpname.Option 1 - Help
help text for given help name

:EHELP.
:EPNLGRP.
Removing Access to F18=More Indexes

To not allow users the ability to change the search indexes they are using, create a
data area called QUHISF18 in the user's library list. The user must have at least
*USE authority to this data area. Creating this data area will condition off the
F18=More indexes function key on the Search Index panel.
Help in a List Area

A list area displays the contents of a UIM list. The list consists of rows and
columns of variable information, which appear in a table format. The following
screen is an example of a panel using a list area to display a list of eight rows.
For this panel, the user may enter numbers 2, 4, 5, 7, or 8 in the Opt column to
specify an action to be performed against one of the rows in the list.
à Spooled Files
ð
2=Change 4=Cancel 5=Display 7=Hold 8=Release
-----Created------
Opt File Nbr User Pty Date Time
_ ffffffffff nnnn uuuuuuuuuu p mm/dd/yy hh:mm:ss
Help in a list area must be defined at the group level and at the column level for
columns which are not part of a group.
Group Level Help

To define help at the group level, specify the HELP attribute on the list group
(LISTGRP) tag. This attribute identifies the help module which explains the
group of columns in the list.
Column Level Help

To define help at the column level in a list area, specify the HELP attribute on
the list column (LISTCOL) tag. This attribute identifies online help information
which explains the purpose of the column in the list.
The HELP attribute is not allowed if the column is part of a list column group
defined by the LISTGRP tag, but is required if the column is not part of a
group.
The HELP attribute of the list action (LISTACT) tag identifies the help module
which explains the list action. The online help information for all active list
actions is displayed as part of the contextual help for the action column.
Coding Help
The following source shows how help is defined for the sample panel with a list
area shown above. All help modules for this sample list area are imported from
panel group *LIBL/EXAMPL2. When the cursor is positioned on the Opt column,
the 'splf/option' help module is displayed, followed by these help modules:
'splf/change'
'splf/cancel'
'splf/display'
'splf/hold'
'splf/release'
When the cursor is positioned on either the Date or Time column, the 'splf/created
date time' help module is displayed. With the cursor on any other column, the help
module identified on the LISTCOL tag is displayed.
:import name='\' pnlgrp='\libl/example2'.
..
.
:listact option=2 help='splf/change' enter='call listactpgm'.2=Change
:listact option=4 help='splf/cancel' enter='call listactpgm'.4=Cancel
:listact option=5 help='splf/display' enter='call listactpgm'.5=Display
:listact option=7 help='splf/hold' enter='call listactpgm'.7=Hold
:listact option=8 help='splf/release'enter='call listactpgm'.8=Release
..
.
:listcol var=option help='splf/option' usage=inout maxwidth=6.Opt
:listcol var=filenam help='splf/file_name' usage=out maxwidth=12.File
:listcol var=filenbr help='splf/file_number' usage=out maxwidth=6.Nbr
:listcol var=usernam help='splf/user_name' usage=out maxwidth=12.User
:listcol var=filepty help='splf/file_priority' usage=out maxwidth=6.Pty
:listgrp col=filecrt help='splf/created_date_time'.Created
:listcol var=filedat usage=out maxwidth=8.Date
:listcol var=filetim1 usage=out maxwidth=8.Time
:elistgrp.
:listview cols='option filenam filenbr usernam filepty filecrt'.

Help in a Menu Area
A menu area contains one or more items, each of which contains an option number
and a description of an action which can be performed. To select an option, the
user enters the number of the option on the command or option line and presses
the Enter key. The following screen is an example of a panel with a menu area.
This panel has six options the user can choose, and each option has a brief
description of the action it performs. The option number chosen by the user is
entered on the Selection line.
à Work with Files

ð
System: xxxxxxxx
1. Display file attributes

2. Display file contents
3. Change ownership
4. Change authorizations
5. Delete
6. Backup to tape
Selection
_
á ñ
Help in a menu area must be defined at the item level.
Item Level Help

To define help for a menu area, specify the HELP attribute on the menu item
(MENUI) tag. This attribute identifies the help module which explains the
purpose of the menu item.
The online information identified by the HELP attribute is displayed when help is
requested while the cursor is positioned on the text for the menu item, or while
the cursor is on the command or option line and a valid menu item number has
been entered.
Coding Help
The following source shows how help is defined for the sample panel shown on
page 19-7.
Reference numbers (.n/) are used in this example to show the relationship
between referring to a help module using the HELP attribute of a tag, and the defi-
nition of the help module using the HELP tag.
:menui option=1 help='option/display_attr' action='call menuipgm' .1/
.Display file attributes
:menui option=2 help='option/display_cont' action='call menuipgm' .2/
.Display file contents
:menui option=3 help='option/change_owner' action='call menuipgm' .3/
.Change ownership
:menui option=4 help='option/change_auth' action='call menuipgm' .4/
.Change authorizations
:menui option=5 help='option/delete' action='call menuipgm' .5/
.Delete
:menui option=6 help='option/backup_tape' action='call menuipgm' .6/
.Backup to tape
..
.
:help name='option/display_attr' .1/
.Display File Attributes - Help
:xh3.1. Display file attributes
:p.Choose this option to display the attributes associated with this file.
The attributes include all the information about the definition of the file.
:ehelp.
:help name='option/display_contents' .2/
.Display File Contents - Help
:xh3.2. Display file contents
:p.Choose this option to display the data contained in this file.
:ehelp.
:help name='option/change_owner' .3/
.Change Ownership - Help
:xh3.3. Change ownership
:p.Choose this option to change the owner of this file.
You are prompted to enter the name of the new owner.
:ehelp.
:help name='option/change_auth' .4/
.Change Authorizations - Help
:xh3.4. Change authorizations
:p.Choose this option to change the list of users
who have authority to access this file.
You are prompted for the user names and authorizations for the file.
:ehelp.
:help name='option/delete' .5/
.Delete - Help
:xh3.5. Delete
:p.Choose this option to delete this file.
The file and all the data in the file is erased from the system
and the storage used by the file is made available for other use.
:ehelp.
:help name='option/backup_tape' .6/
.Backup to Tape - Help
:xh3.6. Backup to tape
:p.Choose this option to
save a copy of this file on a magnetic tape.
You are prompted for more information about how to back up the
file on the tape.
:ehelp.

Help in a Data Area
A data area contains one or more data entry items whose variable information may
be changed by the user. A data area can also contain output items whose variable
information can be viewed by the user but cannot be changed. The following
screen is an example of a panel with a data area.
à Sample Entry Panel

ð
Type choices, press Enter:
File name . . . . . Name of document to be printed
Type style for

printing . . . . . 1 1=Prestige Elite (12 pitch)
2=Courier (1ð pitch)
3=Essay Standard (proportional)
4=Essay Bold (proportional)
Help in a data area must be defined for every item at one of three levels.
Area Level Help

To define help at the area level, specify the HELP attribute on the data presenta-
tion area (DATA) tag. This attribute identifies the help module which explains
all items in the area.
If no HELP attribute is specified on the DATA tag, a help module name must be
associated with each item in the area by specifying the HELP attribute on the
data group (DATAGRP), the data item (DATAI), and data selection field
(DATASLT) tags.
To provide the user with easy access to the online information for a data area
with the LAYOUT=HORIZ attribute specified on the DATA tag, specify the HELP
attribute on the DATA tag instead of the HELP attribute on the individual DATAI
tags.
Group Level Help

To define help at the group level, specify the HELP attribute on the DATAGRP
tag. This attribute identifies the help module that explains all items in the
group.
If no HELP attribute is specified on the DATA tag or on any outer or nested
DATAGRP tags, the HELP attribute is required on all DATAI and DATASLT tags
within the group.
Item Level Help

To define help at the item level, specify the HELP attribute on the DATAI or
DATASLT tag. This attribute identifies the help module that explains the data
item or selection field.
If no HELP attribute is specified on the DATA tag or on DATAGRP tags con-
taining a data item, the HELP attribute is required on the DATAI and DATASLT
tags.
To provide the user with easy access to the online information for a
LAYOUT=HORIZ data area, use the HELP attribute on the DATA tag instead of the
HELP attribute on the individual DATAI tags in the horizontal area.
The HELP attribute applies to all data item extender (DATAIX) tags associated
with a data item.
If the HELP attribute is specified on the DATASLT tag, the HELP attribute can
also be specified for each choice on the DATASLTC tag. If the HELP attribute is
specified on a DATASLTC tag within a selection field, all DATASLTC tags
within that selection field must have the HELP attribute specified.
For multiple-choice selection fields, the online information identified for each
choice is included as part of the contextual help displayed when the cursor is
positioned anywhere within the selection field.
For single-choice selection fields, the online information identified for each
choice is displayed when help is requested while the cursor is positioned on the
text of the choice. This online information is also included as part of the con-
textual help displayed when the cursor is positioned within the selection field
but not on the text for one of the choices within the field. This includes occur-
rences when the cursor is positioned on the prompt text for the selection field
or in the entry field for the selection field. If the cursor is in the entry field and
a valid choice is entered, when help is requested, the help for that choice is
displayed.
Coding Help
The following source shows how help is defined for the sample data area panel
shown previously. All the help modules for this sample data area are imported
from panel group *LIBL/DATAXMP.
..
.
:import name='\' pnlgrp='\libl/dataxmp'.
..
.
:datai var=filename help='print/filename' usage=inout.File name
:datac.Name of document to be printed
:datai var=typestyle help='print/style' usage=inout.Type style for printing
:datac.1=Prestige Elite (12 pitch)
:datac.2=Courier (1ð pitch)
:datac.3=Essay Standard (proportional)
:datac.4=Essay Bold (proportional)
:datai var=leftmarg help='print/left_margin' usage=inout.Left margin
:datac.Number of spaces from the left edge of the paper (1-2ð)
:datai var=copies help='print/copies' usage=inout.Copies
:datac.Number of copies (1-99)
:datai var=duplex help='print/duplex' usage=inout.Duplex
:datac.1=Yes (Print both sides of paper)
:datac.2=No (Print one side only)
..
.
The following source defines the help modules in panel group *LIBL/DATAXMP.
These help modules are imported when the Help key is pressed for the previous
sample data area.

..
.
:help name='print/filename'.File Name - Help
:xh3.File name
:p.Enter the name of document to be printed.
:ehelp.
:help name='print/style'.Type Style for Printing - Help
:xh3.Type style for printing
:p.Enter one of the following to select the type style.
:parml.
:pt.1
:pd.A 12 pitch elite style is used.
:pt.2
:pd.A 1ð pitch courier style is used.
:pt.3
:pd.A proportional essay standard style is used.
:pt.4
:pd.A proportional essay bold style is used.
:eparml.
:ehelp.
:help name='print/left_margin'.Left Margin - Help
:xh3.Left margin
:p.Enter a number from 1 to 2ð for the number of spaces from
the left edge of the paper to the beginning of the printed text.
:ehelp.
:help name='print/copies'.Copies - Help
:xh3.Copies
:p.Enter a number from 1 to 99 for the number of copies of the
document to be printed.
:ehelp.
:help name='print/duplex'.Duplex - Help
:xh3.Duplex
:p.Enter one of the following to select whether or not to print on
both sides of the paper.
:parml.
:pt.1
:pd.Print text on both sides of the paper.
:pt.2
:pd.Print text only on one side of the paper.
:eparml.
:ehelp.
..
.
The following example panel shows the file name and library name in a data area
with a horizontal layout.
à Work with File Members

ð
File: FILEð1 Library: QGPL
The following source shows how help is defined for the sample data area shown
above. This is an example of providing area level help. When the cursor is posi-
tioned anywhere on the line containing the file name, help for the file name and
library are displayed.
between a reference to a help module using the HELP attribute of a tag, and the
definition of the help module using the HELP tag.
..
.
:data depth=2 help='file_and_library' layout=horiz. .1/
:datai var=filename usage=out.File
:datai var=library usage=out.Library
:edata.
..
.
:help name='file_and_library'.File and Library - Help .1/
:xh3.File and library
:p.The qualified name of the file whose members are being displayed.
:ehelp.
..
.
The following example panel shows a qualified file name and a record name in a
data area with a two-column, vertical layout.
à Work with Field Definitions

ð
File . . . . . . FILE Record . . . . . MASTERð1
Library . . . QGPL
The following source shows how help is defined for the sample data area shown
above. This includes providing group level help for the qualified file name. When
the cursor is positioned on the file or library, help for the qualified file name is dis-
played. When the cursor is positioned on the record name, help for the record
name is displayed.
..
.
:data depth=3 layout=2.
:datacol width=16.
:datacol width='\'.
:datagrp grpsep=qindent help='library/file' compact. .1/
:datai var=filename usage=out.File
:datai var=library usage=out.Library
:edatagrp.
:datai var=record help=record usage=out.Record .2/
:edata.
..
.

:help name='library/file'.File and Library - Help .1/
:xh3.File and library
:p.The qualified name of the file whose field definitions are displayed.
:ehelp.
:help name=record.Record - Help .2/
:xh3.Record
:p.The name of the record whose field definitions are displayed.
:ehelp.
Help in a Menu Bar Area

A menu bar area is located at the top of the panel and contains choices which give
the user access to actions available for the panel. To select a choice in the menu
bar, the user positions the cursor on the desired choice and presses the Enter key.
After the user selects a choice in a menu bar, a pull-down menu appears below the
menu bar containing choices for actions against the panel.
This partial screen contains an example of a menu bar area. The menu bar is the
line near the top of the panel, listing File and Help as choices for the user. The
user may select one of the choices to display the pull-down menu for that choice.
The second screen in this example shows the pull-down menu displayed after
selecting File.
à File Help
ð
------------------------------------------------------------------------------
Work with Programs
System: ROCHððð1
2=Change 4=Delete 5=Display
Opt Program Library Text

PPPPPPPPPP LLLLLLLLLL Description textxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
When File is selected, a pull-down menu appears containing choices for actions for
the panel. The actions available in the pull-down menu are Change, Delete,
Display, and Exit. A pull-down menu with another list of actions appears when the
user selects the Help menu bar choice while in the menu bar.
à File _Help
ð
-.-------------------.--------------------------------------------------------
: 2. Change : Work with Programs
: : System: ROCHððð1
: 4. Delete : er.
: 5. Display : 5=Display
: 6. Exit F3 :
:...................: y Text
Contextual help for a menu bar choice includes help for the choice on the menu
bar, as well as help for each active choice in the pull-down menu for that menu bar
choice. Help in a menu bar area must be defined at the menu bar choice level and
at the pull-down choice level.
Menu Bar Choice Level Help
To define help at the menu bar choice level, specify the HELP attribute on the
menu bar choice (MBARC) tag. This attribute identifies the help module which
explains the purpose of the menu bar choice.
Pull-Down Choice Level Help

To define help at the pull-down choice level, specify the HELP attribute on the
pull-down field choice (PDFLDC) tag. This attribute identifies the help module
which explains the purpose of the pull-down choice.
Coding Help
The following source shows how help is defined for the first menu bar choice and
the pull-down menu shown on page 19-13.
..
.
:mbarc help='mbarpgm/file'.File .1/
:pdfld.
:pdfldc option=2 help='mbarpgm/file/change' .2/
action='cmd ?CHGPGM PGM(&var2./&var1.)'
actfor=list.Change
:pdfldc option=4 help='mbarpgm/file/delete' .3/
action='cmd DLTPGM PGM(&var2./&var1.)'
actfor=list confirm=confpgm usrexit='call exitpgm'.Delete
:pdfldc option=5 help='mbarpgm/file/display' .4/
action='cmd DSPPGM PGM(&var2./&var1.)'
actfor=list.Display
:pdfldc option=6 help='mbarpgm/file/exit' action='exit set' .5/
varupd=no.Exit
:pdaccel.F3
:epdfld.
:embarc.
..
.
:help name='mbarpgm/file'.File - Help .1/
:xh3.File
:p.Select this choice to display a pull-down menu containing options
to perform against selected programs.
:ehelp.
:help name='mbarpgm/file/change'.Change - Help .2/
:parml.
:pt.Change
:pd.Choose this option to change attributes of the selected
programs.
This choice is not available if no programs were selected
from the list.
:eparml.
:ehelp.
:help name='mbarpgm/file/delete'.Delete - Help .3/
:parml.
:pt.Delete
:pd.Choose this option to delete the selected programs.
from the list.
:eparml.

:ehelp.
:help name='mbarpgm/file/display'.Display - Help .4/
:parml.
:pt.Display
:pd.Choose this option to display the attributes of the selected
programs.
from the list.
:eparml.
:ehelp.
:help name='mbarpgm/file/exit'.Exit - Help .5/
:parml.
:pt.Exit
:pd.Choose this option to end the current task and return
to the display from which the task was started.
:eparml.
:ehelp.
Help in a Function Key Area

A function key area is located at the bottom of the panel and contains descriptions
of the actions available to the user when the user presses a function key. The
function key area appears on most panels.
The following partial screen contains an example of a function key area for function
keys F3, F4, F9, and F12. The descriptions for these keys are listed in the function
key area, which contains the text F3=Exit, F4=Prompt, F9=Retrieve, and
F12=Cancel.
===> ___________________________________________________________________________
________________________________________________________________________________
F3=Exit F4=Prompt F9=Retrieve F12=Cancel
á ñ
Contextual help for the function key area includes help for the entire list of keys, as
well as help for each active function key. This includes function keys which do not
have text displayed on the panel. Help in a function key area can be defined at the
area level and must be defined at the item level.
Area Level Help

To define help at the area level, specify the HELP attribute on the key list
(KEYL) tag. This attribute identifies the help module which explains the
purpose of the function key area as a whole.
Item Level Help

To define help at the item level, specify the HELP attribute on the key item
(KEYI) tag. This attribute identifies the help module which explains the purpose
of the function key.
Coding Help
The following source shows how help is defined for the function key area shown on
page 19-15. The help module, fkey, contains no help information. This help
module only provides a title for contextual help for the function key area and a
heading for the function keys in extended help. There is no title or extended help
heading tag in the help for each function key because the contextual help is for the
entire function key area, not for an individual key.
..
.
:keyl name=keys help=fkey. .1/
:keyi key=f3 help='fkey/exit' action='exit set' varupd=no.F3=Exit .2/
:keyi key=f4 help='fkey/prompt' action=prompt.F4=Prompt .3/
:keyi key=f9 help='fkey/retrieve' action=retrieve.F9=Retrieve .4/
:keyi key=f12 help='fkey/cancel' action='cancel set' varupd=no.F12=Cancel .5/
:keyi key=enter help='fkey/enter' action=enter. .6/
:keyi key=help help='fkey/help' action=help. .7/
:keyi key=pagedown help='fkey/pagedown' action=pagedown. .8/
:keyi key=pageup help='fkey/pageup' action=pageup. .9/
:keyi key=print help='fkey/print' action=print. .1ð/
:ekeyl.
..
.
:help name='fkey'.Function Keys - Help .1/
:xh3.Function keys
:ehelp.
:help name='fkey/exit'. .2/
:parml.
:pt.F3=Exit
:pd.Ends the current task and returns you to the display from
which the task was started.
:eparml.
:ehelp.
:help name='fkey/prompt'. .3/
:parml.
:pt.F4=Prompt
:pd.Provides assistance in entering or selecting a command.
:eparml.
:ehelp.
:help name='fkey/retrieve'. .4/
:parml.
:pt.:F9=Retrieve
:pd.Shows the last command you entered on the command line,
along with any parameters you included. By pressing this key
once, you receive the last command you ran. By pressing this
key twice, you receive the next to last command that you ran,
and so on.
:eparml.
:ehelp.
:help name='fkey/retrieve'. .5/
:parml.
:pt.F12=Cancel
:pd.Returns to the previous menu or display.
:eparml.
:ehelp.

:help name='fkey/enter' .6/
:parml.
:pt.Enter
:pd.Submits information on the display for processing.
:eparml.
:ehelp.
:help name='fkey/help' .7/
:parml.
:pt.Help
:pd.Provides more information about using the display.
:eparml.
:ehelp.
:help name='fkey/pagedown' .8/
:parml.
:pt.Page Down or Roll Up
:pd.Moves forward to show additional information for this display.
:eparml.
:ehelp.
:help name='fkey/pageup' .9/
:parml.
:pt.Page Up or Roll Down
:pd.Moves backward to show additional information for this display.
:eparml.
:ehelp.
:help name='fkey/print' .1ð/
:parml.
:pt.Print
:pd.Prints the information currently shown on the display.
:eparml.
:ehelp.
..
.
Chapter 20. Defining Online Help Information
When the Help key is pressed and the DDS source for your display file specifies
that online help information is available for the display, the system shows the infor-
mation referred to by the panel group or document or, if you used DDS, contained
in the record.
The following sections in this chapter tell you how to create the actual information
that the user sees:
“Defining Online Help Information in a Panel Group”
For more information on creating online help using the UIM, see Chapter 19,
“Making Online Help Accessible for Your Panel Group” on page 19-1 and
Part 3, “Programming Application Displays Using Panel Groups” on page 14-5.
“Defining Online Information in a Document” on page 20-18
“Defining Online Help Information in a DDS Record” on page 20-19
If the DDS source for your display does not specify that online help information is
accessible for your display, go to Chapter 18, “Making Online Help Information
Accessible for Your Display File.”
Defining Online Help Information in a Panel Group

The user interface manager (UIM) uses panel groups to access online help infor-
mation. The online help information in panel groups may be used in several ways:
Display help
Command help
Index search topics
To use panel groups for online help information, you must specify them in the DDS
source for your application display. If you plan to use panel groups for help but
have not yet specified them in your DDS source, see “Specifying Panel Groups for
Help in Your Display File” on page 18-6.
Entering the UIM Source for a Panel Group for Help

Like display files that are created by compiling DDS source, panel groups are
created by compiling UIM source. The UIM source for a panel group is entered in
a source file member. The source type for all panel groups is *PNLGRP. Steps for
creating and entering data in a source file member are found in Chapter 1,
“Building a Sample Display with Online Help Information.”
UIM tags, which always begin with a colon (:) and end with a period (.), are used to
help format and identify the information. Detailed information about UIM tags is
found in Appendix A, “UIM Panel Group Definition Language.”

Organizing a Panel Group with Help Modules
The UIM source for every panel group, whether used for display help, command
help, or an index search topic, starts with a :PNLGRP tag and ends with an
:EPNLGRP tag.
Units of help information, known as help modules, are defined in the panel group
between the :PNLGRP and :EPNLGRP tags. Each help module starts with a
named :HELP tag and ends with an :EHELP tag, as follows:
:PNLGRP.
:HELP name=firsthelp.Title of First Help Module
:P.
Information for first help module
:EHELP.
:HELP name=secondhelp.Title of Second Help Module
:P.
Information for second help module.
:EHELP.
:EPNLGRP.
A panel group may contain one or more help modules. The help module name,
which is the value for the name attribute on the :HELP tag, identifies the help
module and must be unique for each help module in the panel group. The text that
follows the period (.) on the :HELP tag is used as the title when the online help
information is displayed.
Using the Information in a Help Module More Than Once

The :IMHELP tag allows information to be imbedded, which means that information
that is used more than once can be defined in one help module and then used
within another help module, as follows:
:PNLGRP.
:HELP name=pacific.Pacific Ocean
:P.
The Pacific Ocean is the largest ocean in the
world.
:IMHELP name=ocean.
:EHELP.
:HELP name=atlantic.Atlantic Ocean
:P.
The Atlantic Ocean separates North and South America from
Europe and Africa.
:IMHELP name=ocean.
:EHELP.
:HELP name=ocean.
:P.
An ocean is one of the five large bodies of salt water, which
together cover nearly three-fourths of the world.
:EHELP.
:EPNLGRP.
Note: The :P tag used in the previous UIM source indicates the start of a para-
graph. More information on the :P tag is available in Appendix A, “UIM
Panel Group Definition Language.”

When the user sees the online help information in the previous example, the defi-
nition of ocean is the second sentence for the definitions of both the Pacific Ocean
and the Atlantic Ocean.
Using a Help Module Contained in a Different Help Panel Group

If the help module that contains the repeated information is contained in a different
panel group, an :IMPORT tag is needed. The :IMPORT tag identifies the panel
group that contains the needed help module and makes that panel group available
for use within the current panel group. The :IMPORT tag is placed after the
:PNLGRP tag and before the first :HELP tag in the panel group that refers to the
help module.
First panel group (named PNLSAM1):

:PNLGRP.
:IMPORT pnlgrp=pnlsam2 name=ocean.
:HELP name=pacific.Pacific Ocean
:P.
The Pacific Ocean is the largest ocean in the
world.
:IMHELP name=ocean.
:EHELP.
:HELP name=atlantic.Atlantic Ocean
:P.
The Atlantic Ocean separates North and South America from
Europe and Africa.
:IMHELP name=ocean.
:EHELP.
:EPNLGRP.
Second panel group (named PNLSAM2):

:PNLGRP.
:HELP name=ocean.
:P.
:EHELP.
:EPNLGRP.
Panel group Panel group

PNLSAM1 PNLSAM2
HELP name = pacific.

HELP name = ocean.
HELP name = atlantic.
RV2W056-2
Chapter 20. Defining Online Help Information 20-3

Emphasizing and Formatting the Text within a Help Module
Panel markup tags are UIM tags used within help modules to help format and
emphasize the information. More detailed information about the panel markup tags,
including examples that show how the tags are used, is found in Appendix A, “UIM
Panel Group Definition Language.”
Defining Paragraphs and Notes: The following panel markup tags format blocks
of text into paragraphs or notes:
Function UIM Tags Use

Notes :NT and :ENT A note with one or more paragraphs. A note begins
:NOTE and with Note: and usually refers to something in the text
:ENOTE that precedes it. Displayed note text is indented.
Paragraphs :P A block of text that forms a paragraph. Paragraph
text is separated from other paragraphs and text by
a blank line.
Paragraph :PC Continuation of a paragraph that has been inter-
continuation rupted by another panel markup tag, such as a
figure, example, or list. When you specify paragraph
continuation for text, paragraph formatting returns.
Adding Headings: The following panel markup tags identify associated text as
headings:

Extended help :XH1 through :XH4 Conditional headings for main topic and
headings subtopics of information. (When displaying
contextual help, the first extended help
heading tag is ignored so that its text is not
shown.) Headings are useful for separating
and organizing sections of text. Displayed
heading text is highlighted and placed on its
own line.
Headings :H1 through :H4 Main topics and subtopics of information.
Headings are useful for separating and
organizing sections of text. Displayed
heading text is highlighted and placed on its
own line.
Highlighting Text: The following panel markup tags allow you to highlight text:

Highlighted phrases :HP0 through :HP9 A word or phrase to be highlighted. Text
and :EHP0 through may be highlighted to emphasize it from the
:EHP9 surrounding text. Depending on the tag,
displayed highlighted text may be shown
normal, underlined, brightened or colored
differently, in reverse image, or a combina-
tion of these effects.
Title Citation :CIT and :ECIT The title of a publication. Publication titles
are underlined when displayed.

Making Lists: You may organize your text in lists using the following panel
markup tags:

Definition List :DL and :EDL A list of words or phrases and their corre-
(starts and ends sponding definitions, descriptions, or expla-
list); :DTHD and nations. When definition lists are displayed,
:DDHD (provides each term appears in the left column with its
column headings): definition across from it in the right column.
:DT and :DD (iden-
tify terms and their
definitions)
List part :LP A comment or explanation that applies to a
part of a list. A list part allows you to enter
text after a list item without making the text
part of the previous list item and without
interrupting the list. List part text is not
indented when displayed.
Ordered list of items :OL and :LI and An ordered list of items. Items in an
:EOL ordered list are preceded by numbers or
alphabetic letters to show sequence or
order. Displayed list items in an ordered list
are indented.
Parameter list :PARML and Parameter terms and descriptions. The
:EPARML parameter list is commonly used to define
programming keywords and variables. The
parameter term is shown in the left column;
its definition appears indented on the line
following the term.
Simple list :SL and :LI and List of items. Simple lists are commonly
:ESL used when list items are contained on one
line and no sequence is required. List items
in a simple list are indented only and not
preceded by numbers, letters, hyphens, or
dashes.
Unordered list :UL and :LI and Unordered list of items. Unordered lists are
:EUL commonly used when sequence is not
required for the items in the list. List items
in an unordered list are indented and pre-
ceded by the lowercase letter o, a hyphen,
or a dash.
Identifying Programming Keywords and Variables: The following panel markup

tags allow you to highlight programming keywords and variables, and are often
used with the parameter list tags:

Programming :PK and :EPK A programming keyword. Programming
keyword keywords are used to explain the elements
of programming syntax. Programming
keywords are highlighted and, if specified as
a default also, underlined.
Programming vari- :PV and :EPV A programming variable. Programming vari-
able ables are used to explain the elements of
programming syntax. Programming vari-
ables are underlined when displayed.
Indicating Structured Text: If you want text to be displayed as it is entered, you

can use the following panel markup tags:

Example :XMP and :EXMP An area of text that is displayed exactly as it
is entered. Examples are commonly used
to show sample computer input or output.
Displayed example text is indented.
Figures :FIG and :EFIG A diagram, chart, or other illustration. If
desired, figures may be displayed with cap-
tions.
Unformatted lines :LINES and An area of text that is displayed exactly as it
:ELINES is entered. Unformatted lines are used for
any text that needs to be displayed without
being concatenated.
For more information on the language tags, see Appendix A, “UIM Panel Group
Definition Language” on page A-1.
Adding Index Search Tags to a Help Panel Group

Help panel groups may also contain index search modules. Index search supple-
ments the help information that is provided for each display. To use the information
in help panel groups for the index search function, you need to add the appropriate
UIM tags to your help modules.
Understanding How Index Search Works: Users can access the index search
function from any display help that specifies that the index search function is avail-
able.
When the user presses the Help key from a working display, help information is
displayed. On all help displays that support the index search function, F11=Index
search is active. When the user presses F11, the Index Search display appears.
This display shows a list of main topics in the topic hierarchy. It has an input field
at the bottom for search words.
The user can browse or print any topic in the list or type a word (or words) on the
input field. To view one or more topics, the user types a 5 in the option field beside
the topic title and presses the Enter key. To print one or more topics, the user
types a 6 in the option field.
A plus sign (+) next to a topic means that the user can expand the topic to show its
subtopics in the hierarchy using option 7 (Expand topic). Or, the user can use

option 8 (Compress topic) to compress a topic so that the subtopics are no longer
shown.
If the user types a word or words on the input field, the index search function
matches the words with synonym tables, and presents a list of topics that match
the search words entered.
The following illustration shows how the index search function is accessed from
display help:

Application Display
Bookkeeping
Amount . . . .
---------
Receivable ---------
Owed .... ---------

Net .... ---------
Help Display
HELP Receivable
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXX XXXXXXXXXX
XXXXXXXXXX Cursor- XXXXXXXXXX
XXXXXXXXXX sensitive XXXXXXXXXX
XXXXXXXXXX help XXXXXXXXXX
If using UIM help facility
User presses Index Search key User presses Help key
Index Search How to Use Help
Select topic:
Topic A
Topic B Types of
Topic C help and how
Enter words to find to get it
Topic D
User
enters
search
words
Index Search HELP Glossary

XXXXXXXXXXXXXXXXXXXXXXXXXX
Select topic: User XXXXXXXXXXXXXXXXXXXXXXXXXX
Topic D XXXXXXXX Information XXXXXXXXX
displays XXXXXXXX about topic XXXXXXXXX
topic XXXXXXXX XXXXXXXXX
Enter words to find XXXXXXXXXXXXXXXXXXXXXXXXXX
Topic D XXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXX
RV3W130-0
The user may also reach the index search function by using the Start Search Index
(STRSCHIDX) command. The STRSCHIDX command lets a user access search
indexes without using the Help key or F11.

Deciding Which Topics to Put in Index Search: Index search topics usually
consist of conceptual, procedural, and reference information.
Conceptual information usually answers the question “Why?” Conceptual informa-

tion includes overviews, rationales, advantages, comparisons and contrasts, and
diagrams.
Procedural information answers the question “How do I . . . ?” Procedural informa-

tion always consists of a series of steps.
Reference Information typically answers the question “What is . . . ?” Reference

information includes definitions, examples, commands, tables, prerequisites, and
cautions.
Defining Index Search Topics and Root Words: The :ISCH tag defines the title
of a topic in the index and specifies the root words that serve as the link between
the topic and the search words (synonyms) entered by the user. The tag appears
immediately after the :HELP tag to which it refers. There can only be one :ISCH
tag within a single help module.
For each :ISCH tag, there can be several lines of root words, provided that the total
number of root words is no more than 50. If more than one line of root words is
used, ROOTS= must be repeated at the beginning of the second line and subsequent
lines:
:PNLGRP.
:HELP name=entry1.
:ISCH ROOTS='root1 root2 root3 root4 root5'
ROOTS='root6 root7 root8 root9 root1ð'
ROOTS='root11 root12 root13 ... root5ð'.
Title of First Topic
:P.
This is the first index search module in this panel group.
:EHELP.
:EPNLGRP.
The root words on all lines must be enclosed in apostrophes and a period must be
placed only at the end of the last line of root words. The topic title follows the
period on the :ISCH tag and may be placed on the line immediately following the
period.
Designating Synonyms for Root Words: The :ISCHSYN tag defines the words
(synonyms) that, if entered by a user, match a specific root word. If a word that is
entered by a user is a synonym for a root word, then a match is found for each
topic whose :ISCH tag contains that root.
If you want a word that is used as a root word to be used as a synonym as well,
you must include the word as a synonym on the :ISCHSYN tag. For example:
:ISCHSYN ROOT='ocean'.ocean water sea
The synonyms for the :ISCHSYN tag must be entered on one line, and at least one
:ISCHSYN tag must exist for each root word. If more than one line is needed,
more :ISCHSYN tags may be entered for the same root word.

UIM does not differentiate between synonyms entered in uppercase, lowercase, or
mixed case. For this reason, it is not necessary to repeat synonyms to cover all
the different cases.
You may use alphabetic or numeric characters for synonyms; however, the fol-
lowing characters (including their hexadecimal equivalents) are not allowed to be
used as a synonym or part of a synonym:
. (period)
( (left parenthesis)
) (right parenthesis)
; (semicolon)
, (comma)
? (question mark)
: (colon)
The :ISCHSYN tags may be placed anywhere in the panel group, but to make
maintenance easier, place them all in one area (such as at the beginning of your
panel group or in a panel group object that contains only :ISCHSYN tags).
The following example shows some :ISCHSYN tags and the :ISCH tags that use
them:
:PNLGRP.
:ISCHSYN ROOT='ocean'.ocean water sea
:ISCHSYN ROOT='lake'.lake water pond
:ISCHSYN ROOT='definition'.definition define description what
:ISCHSYN ROOT='definition'.summary concept information explanation
:HELP name='defocean'.
:ISCH ROOTS='definition ocean'.
Definition of ocean
:P.
:EHELP.
:HELP name='deflake'.
:ISCH ROOTS='definition lake'.
Definition of lake
:P.
A lake is a body of standing water that is enclosed by land.
:EHELP.
:EPNLGRP.
Choosing Root Words and Synonyms for Index Search Topics: The following
tips help you decide which words to use as root words and synonyms for your
index search topics:
Design the root words as building blocks that can be put together in different
combinations for different topics.
The significant words in the title of a topic provide a good start on an appro-
priate set of root words for the topic.
Use only one form of a word as a root word if all forms of the word have the
same synonyms.
If two similar words have the same synonyms, use only one of the words as a
root word, not both.

There will be cases where it is appropriate to use two separate root words that
have many common synonyms.
Include all synonyms that seem reasonable for the root word.
Remember that the root words are only used to connect synonyms with help
topics.
You may have to create a special root word that applies to only one topic or a
few specific topics, but these special root words should be the exception, not
the rule.
For topics whose titles include an abbreviation, the abbreviation and the major
words making up the abbreviation should all be used as root words.
Either uppercase or lowercase may be used.
Use comment lines liberally to clarify the context in which particular root words
are to be used.
If the root word is a real word, include the same word as a synonym for the
root word.
You may want to include misspellings of commonly misspelled words as syno-
nyms.
Defining an Index Search Hierarchy: The index search subtopic (ISCHSUBT)

tag identifies the help modules within the same panel group that are subtopics
under the preceding topic specified on an index search (ISCH) tag. The
ISCHSUBT tag must appear after the ISCH tag. Any help module that is not identi-
fied by an ISCHSUBT tag is a primary topic in the index search hierarchy. There-
fore, if no ISCHSUBT tags are used, all help modules are primary topics and there
is no hierarchy.
The TOPIC attribute on the ISCHSUBT tag is used to define the subtopics for a
topic. The order in which the help modules appear on the TOPICS attribute is the
order in which they are displayed in the index search hierarchy. For more informa-
tion on the rules for help module names, see “Name Syntax” on page A-4.
A topic can be the subtopic of more than one topic.
Topics can be nested to no more than 16 levels.
The following example shows how the ISCH tags and ISCHSUBT tags work
together to form an index search hierarchy:
:PNLGRP.
:HELP name=mainhelp.
:ISCH roots='root words'.
Main Help Topic
:ISCHSUBT topics='help1'
topics='help2'.
..
.
:EHELP.
:HELP name=help1.
Help number 1
:ISCHSUBT topics='help3 help4'.
..
.

:EHELP.
:HELP name=help2.
Help number 2
:ISCHSUBT topics='help3'
..
.
:EHELP.
:HELP name=help3.
Help number 3
..
.
:EHELP.
:HELP name=help4.
Help number 4
..
.
:EHELP.
:EPNLGRP.
This UIM source creates the following index search hierarchy:
à Search Index
ð
Type options, press Enter. (+ indicates an expandable topic)
5=Display topic 6=Print topic 7=Expand topic 8=Compress topic
Opt Topic
Title of this index
_ Main Help Topic
_ Help number 1
_ Help number 3
_ Help number 4
_ Help number 2
_ Help number 3
Bottom
Or type search words and press Enter. (\ indicates a topic match)
________________________________________________________________________
F3=Exit help F5=All topics F6=Main topics F11=Hide structure

F12=Cancel F13=Information Assistant F18=More indexes F24=More keys
á ñ
National Language Considerations: The index search function can be used with
either double-byte character support (DBCS) or single-byte character support
(SBCS) data. When DBCS data is used, the device from which it is requested
must be capable of entering and presenting the data in DBCS. The object which
contains the index search data is marked as containing DBCS data when appro-
priate. The system determines if the device is capable of handling the DBCS data.
When the data is being prepared for DBCS format and the index search function is
used with that data, consider the following:
When the index search data is prepared for a DBCS system, the synonyms
entered on the ISCHSYN tag must be in double-byte character mode. That is,
the first byte after the tag must be a shift-out character and the last byte of the
data must be a shift-in character. The system does not convert data on the
ISCHSYN tag to double-byte.

Words must be separated by a single-byte blank. From 1 to 19 double-byte
characters may be combined to form a word. Intervening shift-out and shift-in
characters are allowed, but are ignored by index search.
The words that are used to link the ISCH and ISCHSYN tags (the ROOTS attri-
bute of the ISCH tag and the ROOT attribute of ISCHSYN tag) must be identical
and should not be entered in DBCS.
Search words can be entered in either single-byte mode or double-byte mode.
Single-byte blanks can be entered to separate the words.
When the search words are shown on the screen, the double-byte character repre-
sentation (the character that was actually used in the search) is shown. Special
processing takes place so that index search is not case sensitive. The search
words from the ISCHSYN tag are uppercased using a translation table for the code
page that is specified with the TXTCHRID attribute of the PNLGRP tag. If the search
words are DBCS, they are not uppercased. Shift-out and shift-in characters are
treated as blanks during parsing; leading and trailing blanks are removed. All
SBCS words are uppercased using a translate table for the code page of the
device description. For more information on DBCS, see Appendix D, “Double-Byte
Character Set Support for Displays” on page D-1
Linking Help Modules

Hypertext is a structure of related help modules that are linked together by their
common areas. The linking allows users to select one or more help modules of
interest from another help module. A help module that links to one or more help
modules is called an information node.
Without hypertext, the only way you can access help is through the associated
display or the command prompter. You cannot go directly from one help module to
another unless a link, an association between two information nodes, exists that
makes each help module a node in a hypertext network.
Display Display Display

1 2 3
Help Help Help
RV2W014-2
Similarly, the only way you can access an index search topic is through the index
search function. You cannot go directly from one index search topic to another.

Index
Search
- Topic A
- Topic B
- Topic C
Topic A Topic B Topic C
RV3W131-0
These restrictions make it difficult for you, first, to determine what related informa-
tion exists and, second, to access the information conveniently. Hypertext makes it
possible for you to identify relationships among information nodes so that you and
other users can easily access the information you need.
Designing Your Links: The structure of your hypertext nodes determines the
relationships among the different nodes.
Relationships that involve hierarchy (such as those between a task and its subtasks
or between a command and its parameters) can be expressed as subordinate
nodes below a larger node that they relate to, in the same way that an organization
chart represents the management structure.
Relationships that do not involve hierarchy (such as those between a procedural

node and a reference node or between two similar procedures) can be expressed
as clusters of nodes.
If you are designing a complex hypertext structure, the following questions may
help you make design decisions about what to link to what:
“What don’t I understand here?”
“What words are unfamiliar?”
“What conceptual information is assumed?”
“What else do I need to know to complete my task?”
“What is the next task I want to do after this one?”
“What other tasks are similar to this one?”
“What would a graphical representation of this information look like?”
“What is a specific example of this general information?”
“What other displays or commands are related to this one?”
You are allowed as many links as you want from any one information node;
however, it is not essential that each information node be linked to another node.
A link implies a clear logical relationship. If the relationship is not clear and logical,
no link should exist.
Creating Links: A hypertext reference phrase is a word or phrase that identifies

a selectable hypertext link. The reference phrase is emphasized (with high inten-
sity or color or underlining or a combination of these, depending on the display
station). The hypertext reference phrase tells the user that there is more informa-
tion at the other end of the link.

To create a hypertext link, use the :LINK tag to mark the beginning of the reference
phrase. Use the corresponding :ELINK tag to mark the end of the reference
phrase.
You define a link in one direction only, from node A to node B. The link back from
node B to node A is not defined by a :LINK tag. However, the user can return from
node B to node A by pressing F12. The user can also press F6 to display a list of
the titles of nodes previously displayed, then position the cursor next to a title on
that list and press Enter to return to and display the selected node again.
The following example uses the :LINK tag to create a link from one help module to
another help module:
:HELP NAME='wrkjob'.Work with Jobs - Help
:XH3.Work with jobs
:P.
The Work with Jobs display shows you the status of your
:LINK PERFORM='DSPHELP job pnlgrp1'.
jobs.
:ELINK.
:EHELP.
The following display shows how the preceding example would look to the user:
à ð
Work with Jobs - Help
The Work with Jobs display shows you the status of your jobs.
Note that the reference phrase is emphasized when displayed. It is also preceded
by three blanks for an attribute byte, a one-character field, and another attribute
byte. By using the Tab key to place the cursor on this field, the user can see the
additional information about the highlighted word or phrase by pressing the Enter
key.
Creating and Deleting Panel Groups

The Create Panel Group (CRTPNLGRP) command creates panel groups for help
displays. In the following example, the panel group named PNLSAM in library
LIBSAM is created by using source file member HDMSAM in the same library.
CRTPNLGRP PNLGRP(LIBSAM/PNLSAM) SRCFILE(LIBSAM/SRCSAM) SRCMBR(HDMSAM)
The Delete Panel Group command (DLTPNLGRP) deletes panel groups from the
system. In the following example, the panel group named PNLSAM in library
LIBSAM is deleted:
DLTPNLGRP PNLGRP(LIBSAM/PNLSAM)

Assigning Panel Groups as Help for Commands
Panel groups can be created as help for command parameters that may be
prompted.
The first help module, which contains extended help for the command, is specified
for the Help identifier parameter for the Create Command (CRTCMD) command.
Each additional help item in the panel group corresponds to a parameter in the
command. Only one help module can exist for each parameter that can be
prompted.
For a help module to be associated with a parameter, the :HELP name must use
the following convention:
:HELP name='help-identifier/parameter-name'.
where help-identifier is the name specified for the Help identifier parameter in
the Create Command (CRTCMD) command, and parameter-name is the name of
the parameter that the help module describes.
The following example shows one way to organize a panel group for command
help:
:PNLGRP.
:HELP name=startcmd.
:P.
The text for this help module is used as the
extended help for the command.
:EHELP.
:HELP name='startcmd/parameter1'.
:P.
This help item is used for information about the first
parameter.
:EHELP.
:HELP name='startcmd/parameter2'.
:P.
This help item is used for information about the second
parameter.
:EHELP.
:EPNLGRP.
Using Panel Groups in a Search Index

Panel groups that contain :ISCH, :ISCHSYN, and :ISCHSUBT tags can be added
as entries in a search index. To find out how to access the index search function,
see “Understanding How Index Search Works” on page 20-6.
Creating a Search Index

The Create Search Index (CRTSCHIDX) command creates a search index object.
Search index entries that provide the reference to the online help information con-
tained in one or more panel group objects may be added to this object. These
referenced panel groups can be added and removed from the search index.
In the following example, a search index object named ACCOUNTING is created in

the current library:

CRTSCHIDX SCHIDX(ACCOUNTING)
TITLE('Accounting Help Index')
TEXT('Accounting Help Index')
Adding Entries to a Search Index

The Add Search Index Entry (ADDSCHIDXE) command causes a search index
object to build references to the root words and synonyms for each help module in
a panel group that contains an ISCH tag. The help modules in the panel group
then become entries in the search index object.
When a search index object refers to several panel groups as entries, the order
that the panel groups are added into the search index object determines the order
the entries are displayed when search index function is shown. Similarly, the order
of the help modules in a panel group define the order in which those topics appear
in the search index. If the panel group defines a hierarchy, then the topics appear
in the order defined by the hierarchy.
A limit of 1000 panel groups may be added to a search index object. Only one
type of panel group may be added to a search index object. That is, a search
index object cannot contain panel groups that use the ISCHSUBT tag and panel
groups that do not use the ISCHSUBT tag.
In the following example, the panel group named PAYROLL is added to the search
index named ACCOUNTING. Both the panel group object and the search index
object must exist in the library list.
ADDSCHIDXE SCHIDX(ACCOUNTING) PNLGRP(PAYROLL)
Removing Entries from a Search Index

The Remove Search Index Entry (RMVSCHIDXE) command removes the refer-
ences to a panel group from the search index object. The RMVSCHIDXE
command removes references to a panel group object that was added using the
ADDSCHIDXE command.
In the following example, entries for the panel group PAYROLL are removed from
the search index ACCOUNTING. The search index object is found by searching
the library list.
RMVSCHIDXE SCHIDX(ACCOUNTING) PNLGRP(PAYROLL)
Deleting a Search Index

The Delete Search Index (DLTSCHIDX) command deletes a search index object
from the system. The DLTSCHIDX command does not delete any panel groups
that are referred to by the search index object.
In the following example, a search index object named ACCOUNTING is deleted

from the library where the object is first found in the library list.
DLTSCHIDX SCHIDX(ACCOUNTING)

Copying QUSRTOOL Examples That Define Help in a Panel Group
The QUSRTOOL library provides sample DDS-described displays that access
online help information using panel groups. You can copy these examples into a
library of your choosing and then tailor them for your own use. For more informa-
tion about these sample displays, see “Using the Displays Example in the
QUSRTOOL Library” on page 21-1.
Defining Online Information in a Document

You can use documents created by the word processing function of AS/400
OfficeVision to contain the online help information for your display.
To use documents for online help information, you must specify them in the DDS
source for your application display. If you plan to use documents but have not yet
specified them in your DDS source, see “Specifying Documents in Your Display
File” on page 18-9.
Online documents used as help information are created using the word processing
function of the OfficeVision licensed program. You do not need the OfficeVision
licensed program on your system to run online help information, but you do need
the licensed program to create an online help document.
When you create your document, you need to use help information labels to mark
the specific location in the document where the information is located.
Creating a Document for Help

Follow these steps to create a help document:
1. Create a document to contain the help information source. Create the docu-
ment using the Create Document (CRTDOC) command. The following example
shows how to create a document named HELP.DOC in folder HELPFLD:
CRTDOC DOC(HELP.DOC) FLR(HELPFLD)
2. Place a help information label instruction at the beginning of the document for
general information about the application display. To do this, follow these
steps:
a. Press F5.
b. Type .help
c. Press the Enter key.
d. Type a label name.
e. Do not type a document and folder name unless referring to help informa-
tion that is stored in another document.
3. Type general information about the display for which you are creating help
information. This information appears when the Help key is pressed while the
cursor is not on one of the help areas defined in the DDS for the display.
4. Perform the following for each individual prompt in the display for which you are
writing the help information:
a. Insert a help information label instruction with a label name that describes
the prompt (for example, CUSTNBR, NAME, ADDR, and STATE).
b. Type the help information for the prompt immediately following the help
information label.

5. If desired, insert help information label instructions for the following special
areas of the help information document:
Insert a help information label called TOC immediately before the table of
contents instruction (.toc) if your help information document contains a table
of contents.
Note: The Outline Heading Instruction (.h) display contains two options
specifically for help information documents. The Start on new
display and Show heading text prompts give you greater control
over where and how your help information appears in the resolved
help information document.
Insert a help information label called INDEX immediately before the index
instruction (.ix) if your help information document contains an index.
Note: If you specify Y for the Create help tags prompt on the Index
Instruction display, help information labels are automatically created
for each letter section of the index when your document is resolved.
This allows you to type, for example, the letter s to go directly to the
index words starting with s when viewing the help document.
If your help information document contains a glossary, insert a help infor-
mation label called GLOSSARY immediately before that section.
6. When you finish creating your help document source, press F3 (Exit), type Y for
the Print document and Display print options prompts, and press the Enter key.
7. Page forward to page three of the Print Options display.
8. Specify Y for the Save resolved output prompt, specify a unique document
name for the Document prompt, and also specify the folder where you want the
help information document stored.
The resolved document is your help information document.
More information about using documents in applications is found in the Office Ser-
vices Concepts and Programmer’s Guide.
Viewing the Document without Pressing the Help Key

The Display Help Document (DSPHLPDOC) command allows you to display the
help information document without running an application. This command can be
entered in one of the following ways:
Specify the document name and folder in the DSPHLPDOC command to
display the beginning of the help information document.
Specify a document name, folder, and label with the DSPHLPDOC command to
display the help information associated with the specified label.
Defining Online Help Information in a DDS Record

You can use DDS records for the online help information for your display.
The record formats that give the actual online help information may be included in
the same member as the DDS source for the application display. The record
formats may also be contained in a different display file. An example of DDS

source used for online help information is shown in “Entering the Records That
Contain the Help Information” on page 18-14.

Part 5. Guidelines for IBM AS/400-Style Displays
Chapter 21. Designing IBM AS/400-Style Displays . . . . . . . . . . . . . 21-1
Using the Displays Example in the QUSRTOOL Library . . . . . . . . . . . . 21-1
Recognizing the Example Objects . . . . . . . . . . . . . . . . . . . . . . . 21-1
Installing the Example Objects . . . . . . . . . . . . . . . . . . . . . . . . . 21-4
Viewing the Sample Displays, Command, and Online Help Information . . 21-4
Copying the Source for the Example Objects for Your Own Use . . . . . . 21-7
Defining Special Functions and Attributes for All Displays . . . . . . . . . . . 21-8
Designing the Single-Choice Menu Display . . . . . . . . . . . . . . . . . . . . 21-8
Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-9
Instruction Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-9
Menu Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-9
Menu Selection Entry Field . . . . . . . . . . . . . . . . . . . . . . . . . . 21-10
Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-10
General Menu Display Operation . . . . . . . . . . . . . . . . . . . . . . . 21-10
Designing the Entry Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-11
Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-11
Prompt Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-12
Field Prompts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-12
Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-17
General Entry Display Operation . . . . . . . . . . . . . . . . . . . . . . . 21-17
Designing the Information Display . . . . . . . . . . . . . . . . . . . . . . . . 21-17
Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-19
Location Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-19
Prompt Area 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-19
Prompt Area 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-20
Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-20
General Information Display Operation . . . . . . . . . . . . . . . . . . . . 21-21
Designing the List Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-21
Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-22
Prompt Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-22
Options Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-23
Column Headings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-24
Extended Action Entry Area . . . . . . . . . . . . . . . . . . . . . . . . . . 21-24
List Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-24
Paging Location Information . . . . . . . . . . . . . . . . . . . . . . . . . . 21-25
Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-25
General List Display Operation . . . . . . . . . . . . . . . . . . . . . . . . 21-26
Operating the List Control Field . . . . . . . . . . . . . . . . . . . . . . 21-26
Positioning the List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-26
Positioning to Lowercase Names in a List . . . . . . . . . . . . . . . . 21-27
Changing the List Control Field and Positioning the List . . . . . . . . 21-28
Operating the Extended Action Entry Area . . . . . . . . . . . . . . . . 21-28
List Operation When Options Are Specified . . . . . . . . . . . . . . . 21-29

Cursor Positioning Rules . . . . . . . . . . . . . . . . . . . . . . . . . . 21-31
Error Condition Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-32
List Where Only One Item Can Be Selected . . . . . . . . . . . . . . . 21-33
List Format in Empty List Situation . . . . . . . . . . . . . . . . . . . . 21-33
Defining the Function Key Area for All Displays . . . . . . . . . . . . . . . . 21-33
Optional Command Line and Identifier Field . . . . . . . . . . . . . . . . . 21-34
Available Command Line Tool . . . . . . . . . . . . . . . . . . . . . . . 21-37
Common Key Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . 21-38
Defining Help Information for All Displays . . . . . . . . . . . . . . . . . . . . 21-44
Help for the Menu Display . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-44
Help for the Entry Display . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-46
Help for the Information Display . . . . . . . . . . . . . . . . . . . . . . . . 21-47
Help for the List Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-48
Defining and Presenting Messages . . . . . . . . . . . . . . . . . . . . . . . 21-49
Designing Common User Access (CUA) Entry Level Models . . . . . . . . 21-50
Entry Dialog Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-51
Single-Choice Selection (Menu) . . . . . . . . . . . . . . . . . . . . . . . . 21-52
Selection Choices and Choice Entry Field . . . . . . . . . . . . . . . . 21-53
Guidelines for Single Selection Field Operation . . . . . . . . . . . . . 21-53
Entry Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-53
Entry Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-54
Information Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-55
List Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-55
Help Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-57

Chapter 21. Designing IBM AS/400-Style Displays
If you use data description specifications (DDS) to implement your displays, this
chapter shows the format of each AS/400 system display type, giving the position
and characteristics of all key display elements, both constants and data fields. In
addition, this chapter describes the common actions assigned to function keys
across the AS/400 system. However, if you use the user interface manager (UIM)
to implement your displays, the UIM provides the correct formatting and placement
for you. For more information on UIM, see Part 3, “Programming Application Dis-
plays Using Panel Groups” on page 14-5.
By using the guidelines in this chapter, your displays will be compatible with the
Systems Application Architecture* (SAA*) environment, which makes significant use
of the IBM Systems Application Architecture Common User Access (CUA) rules
and guidelines that apply to display stations.
Using the Displays Example in the QUSRTOOL Library

The purpose of the QUSRTOOL library, which is optionally installable on the base
operating system, is to provide you access to examples of various tools and pro-
gramming techniques that may help you with application development and manage-
ment of your system.
Before you can use any of these program examples, the save files in which they
are packaged must first be changed into source physical files. This may have
already been done for you; if not, an UNPACKAGE tool is provided to do it for you.
For instructions for unpackaging the files, see member TTTINFO in source physical
file QATTINFO. (You can use the DSPPFM command to display the physical file
member.)
Source physical file QATTINFO contains all the information you'll need to get
started. For each example program in the QUSRTOOL library, there is a member
in QATTINFO that describes the tool and how to install it.
The displays example in the QUSRTOOL library gives you access to four sample
displays and a sample command. Online information is available for the displays
and the command and includes the index search function and hypertext links.
Recognizing the Example Objects

The sample displays tool in QUSRTOOL is made up of several members that will
help you install, create, and delete the objects used by the example:

Table 21-1. Source Members for Displays Example in QUSRTOOL (Install, Create, and
Delete)
Source Object
Source Member File Type Description
T0011INF QATTINFO N/A Primary documentation member that
tells you what to do to install the
example objects in a library of your
choosing. The documentation may be
viewed using the DSPPFM command,
CPYF to a printer, or using the SEU
display function.
T0011CRT QATTCL *PGM Installation program for creating all the
example #1 objects
T0011CR2 QATTCL *PGM Installation program for creating all the
example #2 objects
T0011CR5 QATTCL *PGM Installation program for creating all the
example #3 objects
T0011DCL QATTCL *PGM Program that shows the example display
file with its four sample displays,
command, and online help information
T0011DLT QATTCMD *CMD Command to delete all the example
objects for example #1
T0011DC2 QATTCMD *CMD Command to delete all the example
T0011DC5 QATTCMD *CMD Command to delete all the example
T0011DEL QATTCL *PGM Program used by the T0011DLT
command to delete the example objects
for example #1
T0011DL2 QATTCL *PGM Program used by the T0011DC2
for example #2
T0011DL5 QATTCL *PGM Program used by the T0011DC5
for example #3
The sample displays, command, and online help information are contained in the
following members of QUSRTOOL:

Table 21-2. Source Members for Displays Example in QUSRTOOL (Sample Displays,
Command, and Online Help Information)
Source Member Source Object Description
File Type
T0011CMD QATTCMD *CMD Sample commands
T0011CM2
T0011CM3
T0011CM5
T0011CLP QATTCL *PGM Command processing program (CPP)
T0011CP2 used by the sample command
T0011CP3
T0011CP5
T0011CHL QATTUIM *PNLGRP Online help information for the sample
command
TOO11DDS QATTDDS *FILE Example display file that contains the
DDS source for a sample AS/400-style
menu, entry display, information display,
and list display
T0011DHL QATTUIM *PNLGRP Online help information for the example
display file for example #1
T0011IDX QATTUIM *PNLGRP Online help information referred to by
the index search object
T0011DD5 QATTDD5 *FILE Source for physical file for example #3.
T0011HL2 QATTUIM *PNLGRP Online help for example #2.
T0011MN2 QATTUIM *MENU Menu for example #2.
T0011PNI QATTUIM *PNLGRP Panel group for example #3 (contains
various declarations).
T0011PN2 QATTUIM *PNLGRP Panel group for example #2.
T0011PN5 QATTUIM *PNLGRP Panel group for example #3.
T0011PN6 QATTUIM *PNLGRP Online help for example #3.
T0011RA5 QATTRPG *PGM List option processing program for
example #3.
T0011RE5 QATTRPG *PGM General panel exit program for example
#3.
T0011RF5 QATTRPG *PGM Program to process F4 for example #3.
T0011RF6 QATTRPG *PGM Function key processor for example #3.
T0011RI6 QATTRPG *PGM RPG PLISTs used by programs for
example #3.
T0011RI7 QATTRPG *PGM VARRCD definitions used by programs
for example #3.
T0011RL5 QATTRPG *PGM Incomplete list processing exit program
for example #3.
T0011RP5 QATTRPG *PGM Main program for example #3.
T0011RP6 QATTRPG *PGM F4 prompt processor for example #3.
The other objects are not contained in the QUSRTOOL library but are created
when you create the example objects into your library:
Chapter 21. Designing IBM AS/400-Style Displays 21-3

Table 21-3. Objects Created When Creating Example Objects
Object
Source Member Type Description
T0011IDX *SCHIDX Search index object
T0011MSGFL *MSGF Message file used when creating the
sample command and display file
Installing the Example Objects

To install the displays example, follow the installation instructions in T0011INF.
The install programs place all the example objects in a library of your choosing.
Viewing the Sample Displays, Command, and Online Help Information

You can view the sample displays, command, and online help information after
installing the example objects. To view the samples, enter the following com-
mands:
To view the sample menu, enter:
CALL PGM(your-library/Tðð11DCL) PARM(MENU)
The sample menu appears:
à Go To Another List
ð

Selection
_
F3=Exit F12=Cancel
á ñ
Figure 21-1. Sample Menu in QUSRTOOL
Press the Help key to view the online help information for the display. The
online help information shown depends on where the cursor is located when
you press the Help key.
To view the sample entry display, enter:
CALL PGM(your-library/Tðð11DCL) PARM(ENTRY)
The sample entry display appears.

à Merge Options
ð
Place on job queue . . . . . . _ Y=Yes, N=No

Send completion message . . . . _ Y=Yes, N=No
Job description . . . . . . . . __________ Name, F4 for list
Library . . . . . . . . . . . __________ Name, \LIBL
Adjust/paginate option . . . . _ 1=Do not adjust
2=Line ending only
3=Line and page ending
Multiple line report . . . . . _ Y=Yes, N=No
Collect footnotes
in merged document . . . . . _ Y=Yes, N=No
F3=Exit F4=Prompt F12=Cancel
á ñ
Figure 21-2. Sample Entry Display in QUSRTOOL
To view the sample information display, enter:
CALL PGM(your-library/Tðð11DCL) PARM(INFO)
The sample information display appears:

à View Document Details Page 1 of 2
ð
Creation date . . . . . : oooooooo
Document . . . . . . . . : oooooooooooo
Document description . . : ooooooooooooooooooooooooooooooooooooooooooooo

Subject . . . . . . . . : ooooooooooooooooooooooooooooooooooooooooooooooooo
ooooooooooo
Change formats/
options . . . . . . . : o Y=Yes, N=No
Authors . . . . . . . . : oooooooooooooooooooo ooooooooooooooooooo
Keywords . . . . . . . . : ooooooooooooooooooooooooooooooooooooooooooooooooo
oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
ooooooooooooooooooooooooooooooooooooooooooooooooooooooo
Document class . . . . . : oooooooooooooooo

Print as labels . . . . : o Y=Yes, N=No
Press Enter to continue.
F3=Exit F12=Cancel
á ñ
ð
Project . . . . . . . . : oooooooooo
Reference . . . . . . . : ooooooooooooooooooooooooooooooooooooooooooooooooo
oooooooooo
Status . . . . . . . . . : oooooooooooooooooooo
Document date . . . . . : oooooooo
Expiration date . . . . : oooooooo
Sent to . . . . . . . . : ooooooooooooooooooooooooooooooooooooooooooooooooo
ooooooooo
Date action due . . . . : oooooooo

Date action
completed . . . . . . : oooooooo
Mark for
offline storage . . . : o 1=Do not mark
2=Mark and keep
3=Mark and delete document content
4=Mark and delete document
F3=Exit F12=Cancel
á ñ
Figure 21-3. Sample Information Display (Two Pages) in QUSRTOOL
To view the sample list display, enter:
CALL PGM(your-library/Tðð11DCL) PARM(LIST)
The sample list display appears:

à Work with Documents in Folders
ð
Folder . . . ______________________________________________________________
Position to . . . . . . ____________ Starting character(s)
Type options (and Document), press Enter.

1=Create 2=Revise 3=Copy 4=Delete 5=View
6=Print 7=Rename 8=Details 9=Print options 1ð=Send
11=Spell 12=File remote 13=Paginate 14=Authority
Opt Document Document Description Revised Type

__ ____________
__ oooooooooooo ooooooooooooooooooooooooooooooooooo oooooooo oooooooooo
Bottom
F3=Exit F4=Folder list F5=Refresh F6=Print list
F9=Goto F1ð=Search for document F12=Cancel
á ñ
Figure 21-4. Sample List Display in QUSRTOOL
To view the index search function, do the following:
1. Type the command to show any of the displays shown in Figure 21-1 on
page 21-4, Figure 21-2 on page 21-5, Figure 21-3 on page 21-6, or
Figure 21-4.
2. Press the Help key to show the help for the display.
3. Press F11 to use the index search function.
4. Press F5 to show all the topics available in index search.
5. You can choose to view any topic shown in the list. The second topic in
the list contains a hypertext link. The fourth topic in the list uses the same
panel group as the help for the command.
To view the sample command, enter Tðð11CMD:
Press the Help key to view the online help information for the command. The
Copying the Source for the Example Objects for Your Own Use
You can tailor the example objects for your own use after you copy the source from
the QUSRTOOL source file. There are basically two different ways that you can
copy the source from the QUSRTOOL source file:
You can copy one member at a time using the browse/copy services function of
SEU.
You can copy all members from a QUSRTOOL source file (for example, all CL
source members contained in QATTCL) at one time using the Copy Source File
(CPYSRCF) command.

Defining Special Functions and Attributes for All Displays
The following functions and attributes are required for all AS/400-style displays:
Table 21-4. Required Functions and Attributes of All AS/400-Style Displays

Function Description
Online help informa- Available from every display using the Help key and a command
tion attention (CAnn) key as an alternative Help key. The default for
the alternative Help key is CA01, which assigns the help function to
F1 (the CUA designated Help key).
Blinking cursor Blinks as long as the record appears on the display screen.
Command function Allows the corresponding function keys (F3 and F12) to be active
keys CF03 and on the display
CF12
Help clearing Ensures that only the current help is available.
The following functions and attributes are optional for all AS/400-style displays:
Table 21-5. Optional Functions and Attributes of All AS/400-Style Displays

Function Description
Print key Allows the user to print a display
Page Up and Page Allows the user to page the message subfile
Down (Roll Up or
Roll Down) keys
Alternative Page Up Assigns a command function (CFnn) key as an alternative paging
and Alternative Page key (default keys are CF07 and CF08, respectively)
Down (Alternative
Roll Up and Alterna-
tive Roll Down) keys
Keyboard locking Avoids unlocking the keyboard until the system has finished writing
the display and is ready for input.
Designing the Single-Choice Menu Display

An AS/400 system menu shows a list of choices from which the user can select
one choice. It always has a title, an instruction, a list of choices, and a labeled field
for typing the number of the choice selected. Figure 21-5 on page 21-9 shows an
example of a menu.

ð

Selection
_
F3=Exit F12=Cancel
á ñ
Figure 21-5. Sample Application Menu
Before you continue designing this display, define the required and, if desired,
optional functions and attributes found in “Defining Special Functions and Attributes
for All Displays” on page 21-8.
For information about viewing this sample display or copying the source for your
own use, see “Using the Displays Example in the QUSRTOOL Library” on
page 21-1.
Title
The title should be centered on line 1, in mixed case, and displayed in high inten-
sity.
Instruction Line
The guidelines for an instruction line are as follows:
The instruction line is located on line 3 and begins in position 2. It tells the
user to choose between the options listed on the display.
The instruction line format for a menu is:
Note that the instruction line ends in a colon.
All instruction lines on system displays are specified as blue on color displays.
Leave line 4 blank and begin the menu options on line 5.
Menu Options
The guidelines for menu options are as follows:
Begin the options following one blank line after the instruction line.

List the options (one per line) starting in position 7 for options 1 through 9 and
position 6 for options 10 and above. The option number is followed by a period
and is not highlighted.
Limit the number of options to a maximum of 10 wherever possible.
Options are single-spaced and in numeric order. A gap in the numeric
sequence is indicated by one blank line, regardless of how many numbered
options are missing.
Capitalize the first letter of the first word of the option text; the remaining words
should be capitalized as appropriate for a sentence.
There is no punctuation at the end of each line of the option text.
If Sign-off is an option on a menu, it should have option number 90.
Existing option numbers should not change when new options are added.
Menu Selection Entry Field

The guidelines for the menu selection entry field are as follows:
The length of a menu selection entry field is one position for option numbers 1
through 9, and two positions for option numbers 10 or greater (up to 99).
The menu selection entry field is located in a fixed position relative to the func-
tion key area. It begins in position 7 on the second line above the top (or only)
line of the function key area.
The selection prompt is on the line above the menu selection entry field and
begins in position 2.
The text of the selection prompt is:
Selection
The line immediately above the top line of the function key area is blank.
Function Keys
Guidelines for defining the function key area are available in “Defining the Function
Key Area for All Displays” on page 21-33.
Online Help Information

Online help information for this sample display using the user interface manager
(UIM) is available in QUSRTOOL. For information on how to use the source in
QUSRTOOL, see “Using the Displays Example in the QUSRTOOL Library” on
page 21-1.
Guidelines for defining the online help information are available in “Help for the
Menu Display” on page 21-44.
General Menu Display Operation

Following is a summary of what happens when the user presses the Enter key with
or without making any entries on the menu:
If there is no entry in the selection entry field, the menu remains on the display
(no-operation instruction) and an informational message is displayed, if the key-
board is not locked. For example:
Enter option number or command. Press Help for details.

If the value entered was not a valid menu option, a message such as:
Value entered is not a valid menu selection
should be issued.
If there is an entry that is determined to be a valid option, the requested action
is processed.
Designing the Entry Display

Entry displays let users type in entry field, and are typically used to provide the
system parameters and options associated with an action request. Figure 21-6
shows an example of an entry display.
à Merge Options
ð
Place on job queue . . . . . . _ Y=Yes, N=No

Job description . . . . . . . . __________ Name, F4 for list
Adjust/paginate option . . . . _ 1=Do not adjust
2=Line ending only
3=Line and page ending
Multiple line report . . . . . _ Y=Yes, N=No
Collect footnotes
in merged document . . . . . _ Y=Yes, N=No
á ñ
Figure 21-6. Sample Entry Display
page 21-1.
Title
sity.

Instruction Line
The guidelines for an instruction line are as follows:
The first character of each instruction line begins in position 2.
The instruction line for an entry display is a mandatory field in mixed case char-
acters. The format is one of the following, depending on what is to be entered:
Type choices, press the Enter key.
Type changes, press the Enter key.
Type information, press the Enter key.
The top instruction line for an entry display ends in a period.
Although a single instruction (one sentence) is recommended, two instructions
are allowed. Each instruction should fit on a single line with the first character
of each line beginning in position 2. There is no blank line between the
instructions. For example,
Press F16 to send.
A single instruction can have a maximum length of two lines. The line that is
carried over is indented two spaces (begins in position 4).
Type information to define the...............
of the distribution list, press Enter.
Prompt Area
In general, the columns containing the field prompts and entry fields should be on
the left half of the display, and the column containing the list of possible choices
should be on the right half of the display. If all the prompts for a request cannot be
shown in the prompt area of a single display, make paging of the prompt area pos-
sible.
Field Prompts
The guidelines for field prompts are as follows:
Field prompts are in normal sentence capitalization and are located to the left
of the field they identify.
The first letter of the first word of the prompt should be uppercase; the
remaining text should be lowercase, unless grammatically incorrect to do so.
There is no punctuation at the end of the prompt.
A series of periods (dots) is used to connect the field prompt and the input
field.
Dots are spaced every other character. The farthest right dot is in the last
position within the column width specified for the field prompt, and the dots are
placed every other position back to the prompt text. There must be three blank
spaces between the farthest right dot and the input field the prompt identifies.
The closest dot to the prompt text is two or three positions after the prompt
(minimum of one blank between prompt text and dot).
For input fields, there should be room for two or more dots; otherwise dots
should not be shown.

Prompt . . . _______ (room for at least 2 dots)
Long prompt _______ (no room for 2 dots)
Indentation of field prompts and their corresponding input fields is allowed to
show a level of hierarchy.
The field prompt column is separated from the column containing the input field
by 3 character positions (blanks).
When two or more lines of field prompts are presented, the starting positions of
the prompts, the dots, and the input fields are aligned.
Field prompts on entry displays are preceded by an instruction line beginning in
position 2. The field prompts start in position 4.
For example:
Type changes, press Enter.
Customer name . . . . . . . . . ______________________________
Customer address . . . . . . . ______________________________
Telephone number . . . . . . . _____________
The instruction line is separated from the first field prompt by one blank line.
If field prompt text carries over to a second line, it is indented an additional two
spaces. The input field is after the last line.
Record format
of file . . . . . . . ______________________________
The use of leader dots with an unformatted (continuous) entry field that carries
over to multiple lines is the same as with standard formatting. If the field
carries over to another line, however, it must extend to position 80 and carry
over to position 1 on the following line.
Cause . . . . . _____________________________________________________
_________________________________________________________________________
Entry fields formatted on a line-by-line basis should occupy individual lines
beginning with the line following the prompt. The entry fields should be
indented two positions from the beginning of the prompt.
The prompt is not followed by leader dots. Never use leader dots unless the
field being identified is on the same line.
Memo
_____________________________________________________________________
_____________________________________________________________________
_____________________________________________________________________
_____________________________________________________________________
When a single piece of data to be entered has multiple parts, the parts can be
put on one line if they are understood by the user and considered one piece of
data.
Social security number . . . . ___ __ ____
Row/column . . . . . . . . . . ___ ___
A From/To date in a field prompt should be formatted as two fields on one line
as follows:
Date filed . . . . . . . . From __/__/__ To __/__/__ MM/DD/YY
Document date . . . . . . . From __/__/__ To __/__/__ MM/DD/YY
Any indication of the type of value (for example, Name), range of value (for
example, 1 to 99), or specific value (for example, Y=Yes, N=No) should not

appear with the field prompt, but should be shown only in the possible choices
area.
For a qualified name hierarchy, indent both the prompt text and the entry field
by two positions.
Indent prompts under a group heading by two positions. A group heading has
no corresponding input field. The group heading should be followed by a
colon. It can extend to more than one line, but only one level of indent is
allowed.
Do not show an entry field if the value on the display is not meaningful. If entry
fields are conditionally meaningful, place conditionally valid prompts on a
display separate from the prompt they are dependent on.
As an alternative, the prompt can be indented under a group heading that
defines the conditions. For example:
Place on job queue . . . . . . . . . _ Y=Yes, N=No
For choice Y=Yes:
Entry Fields: A required entry field requires the user to type a value. Such a field
cannot be supported by a default. An optional entry field does not require the user
to type a value. The program can always get a value for an optional entry field by
defining a default.
Entry fields take two forms. The first form requests a user-supplied value, like a
name, descriptive text, or address. Frequently, these fields can accept a value
from a list of values of variable length and contents. When such a list of valid
choices exists, F4 should be supported to allow the user to request the list and
simply choose from it.
File . . . . . . . . . __________ Name, F4 for list
The second type of entry field supports a selection from a fixed set of choices. CUA
calls this a Selection field. If only one choice can be selected, the choices should
be numbered. For example:
Type style . . . . . 1 1=Prestige elite (12 pitch)
3=Essay standard
The only exceptions to numbering the choices are when the answers are Yes or No
and when the choice value has significance to the user by itself.
If the list of values is longer than five lines, F4 should be supported.
When the prompt requires a Yes or No response, Y and N should be valid entries.
For example:
Duplex . . . . . . . Y Y=Yes, N=No
When a display first appears, the cursor should be positioned on the first entry field
that the user will type into. This is usually the first field unless a field specified on
an earlier display is carried over to this display.
On some entry displays it is desirable to indicate previous user entries in an entry

field. For example, if a user typed some command values prior to requesting
prompting, those user-supplied values would be flagged on the prompt.

The greater than symbol ( > ) is used as the indication. In the entry display format,
there are three blank spaces between the last leader dot and the beginning of the
input field. The > is placed in the middle space of those three blank spaces.
Rules for Entry Fields: The following rules apply to the entry fields themselves:
Required fields cannot have a default. A subvalue of a required specification
can have a default. For example, a file name parameter is required. No
default file name is defined but a default library qualification of the file name
can be provided.
Required entry fields must be displayed in high intensity. The field prompt and
possible choices information are in normal intensity. If a value is entered in
error the value should be shown again in reverse image and underlined.
Optional entry fields should be normal intensity.
Wherever possible, optional entry fields should have a defined and displayed
default value.
Starting positions for entry fields must be left-justified and aligned (unless there
are hierarchical fields).
If defined, default values should appear in the input fields. Values shown in
fields are left-justified, including numbers that are displayed as character values
(see Figure 21-6 on page 21-11). When values shown in fields are specified
as numeric, they are right-justified.
User-supplied values typed in the entry fields override the default values.
Use the underline attribute to indicate the length of the entry field. The indi-
cated length should be the same as the maximum number of characters that
can be entered.
The entry field can extend into the possible choices information and even carry
over into the field prompt area on subsequent lines if needed. If an unfor-
matted, or continuous, field carries over to another line, it must extend to posi-
tion 80 and carry over to position 1 on the following line. For example:
Message text . . . . . . ________________________________________________
____________________________________________________________________________
____________________________________________________________________________
If a list of possible choices is appropriate for an extended length input field (see
“Descriptive Text Area (Possible Choices Information)” on page 21-16), the
choices may be shown after the input field or accessed through F4.
Echoed errors (incorrect values in input fields) are displayed again in reverse
image. The keyboard should be unlocked so that the user can correct the error
without having to press Error Reset before making the correction. The cursor
should be positioned at the first field in error.
Note: If reverse image is used in a highlighted input field (for example, a
required field), the highlight attribute should be turned off (changed to
normal intensity) to avoid a no display situation with 5250 display
stations.
If a field supports F4 for a list of choices, F4 must remain available if an error is
made in the field. This is important in helping the user correct the error.
If the entry display can be paged and the first error is on the currently displayed
fields, show the display as is without special positioning. If the first error is not

on the currently displayed fields, position the first error at the top of the area
that can be paged.
Descriptive Text Area (Possible Choices Information): Possible Choices infor-

mation should be shown in the description area to the right of entry fields for which
only a predefined set of values or a limited range of values is allowed . If the
number of values is too great to be shown, or if the values are dynamic, as in a list
of document names, F4 should be supported. The phrase F4 for list must appear
as Possible Choices information for that field. (If F4 is supported for all fields on
the display, F4 for list does not have to appear for each field.) A description of the
values should also be provided in the Help information supporting the entry field.
The following rules apply to Possible Choices information:

Information for all entry fields on a display should have the same starting posi-
tion.
Choices are separated by one comma and one blank if shown in a horizontal
character string.
Y=Yes, N=No
QDKT, QTAPE1, QTAPE2, \SAVF
Name, \ALL
Choices are aligned on the left and on separate lines if shown vertically. No
comma or other punctuation is shown at the end of any line.
Y=Yes
N=No
1=Prestige elite (12 pitch)
3=Essay standard (proportional)
4=Essay bold (proportional)
Capitalize the first word on either side of the equal sign, regardless of whether
it is the first value, last value, or only value. For example:
1-255, Blank=Entire instruction
Blank=Entire instruction, \NONE=None of instruction
Specific values that can be typed are shown in uppercase.
Files . . . . . . . . . __________ Name, \NONE
Yes and No should be specified by Y=Yes, N=No.
Use 'generic*' to indicate that generic names must be followed by an asterisk.
For example:
Files . . . . . . . . . __________ Name, generic\
Identify key numeric ranges. For example:
ð-99
If the range is not important, do not include it. For example, if there is no limit
to the value, do not show anything.
If a numeric value is being prompted and the value must be in specific units,
identify the type of units. For example:
Time in seconds
In a series of possible choices without space to show all the values, show the
most useful beginning with the default and ending with an ellipsis.

Show a word in quotation marks only when the value being prompted needs to
be in quotation marks.
Function Keys

page 21-1.
Entry Display” on page 21-46.
General Entry Display Operation

The guidelines for entry display operations are as follows:
If a user blanks out a field that has a default, return the default to the field
when you show the display again after other checking is completed. Do not
issue an error message. The function of the display is not performed so the
user can accept or change the returned default.
If a user blanks out an optional field that does not have a default, leave the
field blank. Do not issue an error message. Processing can occur as appro-
priate.
If a user blanks out a required field that has no default, a message such as
Library name is required
is displayed.
The other fields on the display screen are checked for errors when a field is
blanked out and the Enter key is pressed. In some cases, returning the default
may cause an error, depending on another field on the display screen. When
these errors occur, error messages should be displayed.
In all cases, if required values are not supplied or there is no valid entries, the
display is shown again with an error message indicating what is needed. Fields
that have an entry that is not valid or that require an entry are shown in reverse
image. If all fields have valid entries or defaults, the display is processed and
the dialog proceeds to the next logical display defined for the Enter action.
Designing the Information Display

Information displays show protected information. Figure 21-7 on page 21-18
shows a two-part information display. This example shows a series of output fields
that are identified or labeled by field prompts.

ð

ooooooooooo
Change formats/
options . . . . . . . : o Y=Yes, N=No

Print as labels . . . . : o Y=Yes, N=No
F3=Exit F12=Cancel
á ñ
ð
oooooooooo
Status . . . . . . . . . : oooooooooooooooooooo
Document date . . . . . : oooooooo
Expiration date . . . . : oooooooo
Sent to . . . . . . . . : ooooooooooooooooooooooooooooooooooooooooooooooooo
ooooooooo
Date action due . . . . : oooooooo

Date action
completed . . . . . . : oooooooo
Mark for
offline storage . . . : o 1=Do not mark
2=Mark and keep
3=Mark and delete document content
4=Mark and delete document
F3=Exit F12=Cancel
á ñ
Figure 21-7. Sample Information Display (Two Pages)
page 21-1.

Title
sity.
Location Information
Location information for a multiple-part display is right-aligned on line 1 and is in
the form:
Page xx of xx
Prompt Area 1
Field prompts for output fields are not preceded by an instruction line and begin
in position 2.
A series of periods (dots) and a colon are used to connect the field prompt and
the output field.
The colon is in the last position within the column width specified for the field
prompt, and the dots are placed every other position back to the prompt text.
The closest dot to the prompt text is two or three positions after the prompt
(minimum of one blank between prompt text and dot).
The field prompt column is separated from the column containing the output
field by 3 character positions (blanks).
When two or more lines of field prompts are presented, the dots and colons on
each line are aligned vertically.
Output fields are always preceded by a colon, and have no underline attributes
marking the field length.
If the prompt requires more than one line, indent the second line two positions.
The output field is after the last line.
Record format
of file . . . . . . : ______________________________
For output fields, dots should be used if there is room for one or more in addi-
tion to the colon. The colon is required. There must be one blank space
before the colon in the output field format.
Prompt . . . : Xxxxxxx (room for more than 1 dot)
Med prompt . : Xxxxxxx (room for 1 dot only)
Long prompt : Xxxxxxx (no room for 1 dot)
Indentation of field prompts and their corresponding output fields is allowed to
show a level of hierarchy.
When two or more lines of field prompts are presented, the starting positions of
the prompts, the dots and colons, and the output fields are aligned.
The use of leader dots and the colon with an unformatted (continuous) output
field that carries over to multiple lines is the same as with standard formatting.
The second and subsequent lines, in the case of output fields, are indented by
two positions from the beginning of the prompt text.

Cause . . . . : Xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxx. Xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.
Output fields formatted on a line-by-line basis should occupy individual lines
beginning with the line following the prompt. The output fields should be
indented two positions from the beginning of the prompt.
The prompt is followed by a colon with no intervening blank. The prompt is not
followed by leader dots. Never use leader dots unless the field being identified
is on the same line.
Buckslip:
Xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
When the information to be shown has multiple parts, the parts can be put on
one line if they are understood by the user and considered as one piece of
data.
Social security number . . . : XXX XX XXXX
Row/column . . . . . . . . . : 27 43
Prompt Area 2
The prompts on the second part of the information display follow the same format
as those on the first part of the display.
Instruction Line
Multipart information displays use an instruction line that tells the user how to con-
tinue or end the dialog with the display. For example:
This bottom instruction line is placed one blank line after the last line of information
or one blank line above the first function key line.
Function Keys

page 21-1.
Information Display” on page 21-47.

General Information Display Operation
This output information has been set up as separate information displays that the
user progresses through by pressing the Enter key. A paging model can also be
used. When the Enter key is pressed, the dialog proceeds to the next logical
display. The instruction Press Enter to continue should be shown on the display.
Designing the List Display

List displays show a list of items from which users may select one or more and
then specify one or more actions to perform on those items. Figure 21-8 is an
example of a list display with entry fields. This is called a mixed display. A mixed
display is a display that combines different types of display elements.
à Work with Documents in Folders.1/

ð
Folder . . . .2/_____________________________________________________________
Position to . . . . . . .3/___________ Starting character(s)
Type options (and Document), press Enter. .4/

1=Create 2=Revise 3=Copy 4=Delete 5=View .5/
Opt Document Document Description Revised Type .6/

__ ____________ .7/
__ oooooooooooo ooooooooooooooooooooooooooooooooooo oooooooo oooooooooo .8/
.9/ Bottom
F3=Exit F4=Folder list F5=Refresh F6=Print list .1ð/
á ñ
Figure 21-8. Sample List Display
Reference Key Display Element

.1/ Title
.2/ List control field
.3/ Position to field
.4/ Instruction line
.5/ Options line
.6/ Column heading
.7/ Extended action entry area
.8/ List field
.9/ Paging location information
.1ð/ Function keys
page 21-1.

Title
sity.
Prompt Area
In Figure 21-8 on page 21-21, the prompt area consists of the list control field and
the Position to field.

A series of periods (dots) is used to connect the field prompt and the input
field. The farthest right dot is in the last position within the column width speci-
fied for the field prompt, and the dots are placed every other position back to
the prompt text. The closest dot to the prompt text is two or three positions
after the prompt (minimum of one blank between prompt text and dot).
The field prompt column is separated from the column containing the input or
output field by 3 character positions (blanks).
When two or more lines of field prompts are presented, the farthest right dots
should be vertically aligned if possible.
Field prompts that are not preceded by an instruction line (on some mixed dis-
plays) begin in position 2.
Input fields have underline attributes marking their length.
Instruction Line
The guidelines for the instruction line are as follows:
The first character of an instruction line begins in position 2.
There is no blank line between an instruction line and a following options line.
The top instruction line for a list display ends in a period.
If the instruction line is preceded by any information, such as an entry field, it
must be separated from that information by one blank line.
The instruction line for a standard action list is as follows:
The instruction line for an action list with an extended action entry is as follows:
Type options (and Xxxx), press Enter.
where Xxxx identifies the type of item the list contains, such as Dictionary, Doc-
ument, and so on.
When an instruction line followed by an options line is used with a list, the
instruction and option combination is separated from the list column headings
by one blank line.

Options Line
The guidelines for the options line are as follows:
The options line begins in position 4.
Each listed option has its first letter in uppercase and is preceded by a number
and equal sign with no intervening spaces. A minimum of two spaces must be
left between listed options.
Three lines of options is the maximum (it is recommended that the options line
be held to two lines). When options extend to more than one line, the digits
are vertically aligned. List displays can have up to three lines of options if pref-
erable to a switch to the F23=More options function.
Use full word names for option labels (for example, 5=Display jobs, 8=Save
library).
If more options are not shown, put an ellipsis after the last option shown and
support and show F23=More options to switch a second set of option
descriptions into the instruction area.
Use the following standardized list action codes:
1 Select (used on the display resulting from pressing F4). Selects for return
of value to entry field where F4 was pressed. Do not use to select an
action. The other action codes for the actual action should be used. This
is only used when an object or item in the list is just being chosen.
1 Create. Used on lists with an extended action entry in the list, reserved
for Create on all Work with... displays.
2 Change or Edit.
3 Copy or Hold.
4 Delete or End.
5 Display or Work with the actual object represented and its content. If it is
an object with content, display or work with the content. If it is a
description, display or work with the attributes it describes.
6 Print or Release.
7 Rename.
8 Display attributes or Detail (the secondary display option) Work with ...
attributes or Detail (the secondary work with).
9 Run.
Work with... actions should be assigned to 5 or 8 if they are not needed for
Display actions. If both are used, 9 or 12 may be used for the work with
option.
The option numbers supported for any list display must be listed in order, but
gaps are allowed in the sequence.
If the option field is 2 characters (because of the number of options), typing a
one-digit selection code in either position of the field should be accepted.

Column Headings
The guidelines for column headings are as follows:
Column headings are required on list displays and must be in mixed case.
Column headings should be left-justified over the corresponding data if the data
is character or character and numeric. Column headings over numeric data
only is right-justified. When the heading is longer than the data, it should be
centered over the data.
The column heading for the option field should be Option. (Option can be
abbreviated Opt when space is limited.)
Columns should be separated by no fewer than two spaces and no more than
seven spaces.
Column headings can occupy a maximum vertical size of three lines.
Extended Action Entry Area

In the extended action entry area, the first line under the column headings is an
entry area that cannot be paged. The entry area contains an option field and an
identifier field. The identifier field is an input field with its length indicated by under-
line attributes and is the same length as the corresponding output fields on those
lines of the list that can be paged. For example:
__ ____________
Both fields have the attributes of entry fields: underline plus reverse image and
cursor positioning in case of errors.
List Fields
The farthest left column in the list area is the Option column. It contains input fields
(underlined) 1 or 2 characters long, depending on the number of options available.
One-character entries are accepted in either position for two-character input fields.
The column to the right of the Option column should contain the information for
identifying the list item or for sequencing (if the list is ordered). This column usually
names the item.
Lists can be described using subfiles (see Chapter 4, “Displaying Groups of

Records Using Subfiles”). Use of subfiles, however, does not support the descrip-
tive paging information used by the system interface at the bottom of the area to be
paged.
In the sample list display shown in Figure 21-8 on page 21-21, the fields on the
available list lines are described using five fields on a line and nine lines in each
field. The program then loads the successive nine-line blocks of data as the user
pages through the file.
The fields in the Option column have the attributes of entry fields. The fields in the
other columns, being defined as input/output (B), have the protect attribute to
prevent user access.

Paging Location Information
Whenever the user is on any part other than the last part of an area that can be
paged, the phrase More... appears highlighted (high intensity) in the location infor-
mation field on the bottom separator line. When the user is on the last display of
an area that can be paged, More... is replaced by Bottom.
The location information field is defined as the seven farthest right display positions
of the bottom separator line. More... and Bottom are right-aligned in this field.
When multiple areas on a mixed display can be paged, each requires its own
paging information. Figure 21-9 shows the layout of a display with location infor-
mation.
ð1 Display Title
ð2 Top Separator Line
ð3 Display Body
ð4
ð5 - - - - - - - - - - - - start of paging area - - - - - - - - - - - - - - -
ð6
ð7
ð8
ð9
1ð
11
16
12
13
14
15
17
18
19
2ð
21 - - - - - - - - - - - - -end of paging area- - - - - - - - - - - - - - - -
22 Bottom Separator Line More...
23 Function Key Area
24 Message Area
Figure 21-9. Layout of Display with Location Information
Each allowable constant is conditioned by an indicator. The program must display

the correct constant, depending on the status of the paging.
Function Keys

(UIM) is available in QUSRTOOL. For information on how to use the source on
page 21-1.
Information Display” on page 21-47.

General List Display Operation
The processing priority of a mixed list display when the Enter key is pressed is as
follows:
The list control field (folder, dictionary, and so on) at the top of the display
The Position to prompt
The extended action entry area
Options within the list proper
Error diagnosis follows this same sequence.
On this type of mixed list display, the list control field at the top of the display
normally contains the name of the object (folder, dictionary, and so on) whose con-
tents are being displayed. By changing the name, for example to another valid
folder name, the user is essentially issuing a display command for the contents of
the newly specified folder. When the user presses the Enter key, the list display
area is then replaced with a new list display.
Operating the List Control Field

The list control field specifies what the list contains. For example, by changing the
list control field from FOLDER1 to FOLDER2 and pressing the Enter key, the user
gets a new list that displays the contents of FOLDER2.
The guidelines for the operation of the list control field are as follows:
Once a list of items is displayed, changing the name of the list in the list control
field while selections within the list are pending causes an error message. The
pending selections are saved and the list control field with the changed name is
in reverse image. The error message must include the name that was changed
so the user can change the name back, if desired.
Blanking out the name simply results in the name being restored when the list
is displayed again after pending operations are completed.
If a list of items from folder A is being displayed and there are no pending
selections entered in the list, the user may obtain a list of items from folder B
by changing folder A to folder B in the list control field and pressing the Enter
key.
While a list of items from folder A is being displayed with no pending requests,
the user may perform a specific function on a particular item in folder B by
changing folder A to folder B, typing in the selected option number and the
identifier in the extended action entry area, and then pressing the Enter key.
After the option is performed, the folder B list is displayed.
If folder A is changed to folder B in the list control field and the Enter key is not
pressed, and then a page/roll operation is attempted (with or without selections
pending), the page/roll is not performed, an error message is shown, and the
list control field is in reverse image.
Positioning the List

The guidelines for positioning the list are as follows:
The Position to function is used for quick repositioning of the list.
– If the user specifies the character S as the starting point, the resulting list
starts with the first S item and includes all items after that as well, not just

the items beginning with S. When positioning to S, if the list contains AA,
BB, SA, SB, the list is positioned to SA.
– Once the list has been repositioned, the Page Up and Page Down keys
can still be used to page to any other items in the list.
– The special values *TOP and *BOT are supported to position the list to the
beginning or end.
– If no items are found that begin with the characters entered, the list is posi-
tioned beginning with the item immediately preceding the requested posi-
tion.
After a Position to function, the item to which the list is positioned should be at
the top of the list area, the cursor should be on the first option field that follows
the input-capable field (if one exists), and the Position to field should be
blanked out.
The Position to field is not checked for being a valid syntax name or a direct
match on a name in the list. Instead, the user is positioned in the list where
the entered string would fit based on collating sequence rules (the user can
enter A& to position to where A& is in the collating sequence).
Position to field entries in the list option column are ignored. If the user types
characters into this prompt and presses the Enter key while operations are
pending in the list area of the list, the list is repositioned and the selections are
saved, just as if a page/roll key had been pressed.
Positioning to Lowercase Names in a List

If you support a Position to prompt for your list, and the items in the list have lower-
case characters, you should follow these rules to let the user position the list to
those items:
If the input in the Position to field does not begin with double quotation marks
("), the input should be folded to uppercase and positioned to the name closest
to that uppercase name.
If the input in the Position to field begins with double quotation marks ("b or
"b"), the list should be positioned to the name closest to "b.
If the user types the ending quotation marks ("b"), you must strip them off so
that list positions to the name beginning with the double quotation marks ("b).
Otherwise, it will look for "b" in the collating sequence.
If double quotation marks are used on a string that has no special or lowercase
characters that would require quotation marks, they are removed, and the list is
positioned to the name that is not marked by quotation marks.
Using the following list,
"aa"
"bb"
AAAAA
BBBBB
– Position to "b and Position to "b" should both put "bb" at the top of the list.
– Position to "AAA," Position to "AAA, and Position to AAA should all put
AAAAA at the top of the list.

Changing the List Control Field and Positioning the List
Options for positioning the list include:
If the list control field is changed to a valid value (a new list can be shown),
and a value is typed in the Position to field, show the new list positioned
according to the Position to field.
If the list control field is changed to a value that is not valid and a value is
typed in the Position to field:
– Display the same list
– Reverse image the list control field and show the message
– Position to field remains as typed; list is not positioned
Operating the Extended Action Entry Area

The guidelines for the operation of the extended action entry area are as follows:
The cursor is initially positioned on the option field of the extended action entry
area. The cursor returns to this position after either of the following operations:
– Position to
– Any paging operation
Figure 21-10 shows the processing priority used by the system when the
Create function is used with an extended action entry area:
Are
other options No
(if any) in Error.
list Create is not done.
valid?
Yes
Does Create field goes to reverse image.

the item Yes
Error message.
to create already List is not repositioned to existing item.
exist?
No
Is
there a No Create is done.
"Position to" Other options (if any) specified
value? in list are performed.
Yes
List is positioned.
No create is done.
Other options (if any) are not processed.
RV3W066-0
Figure 21-10. Example of Processing Priority with List Display

Specifying the Create option on any list line other than the extended action
entry area results in an error.
Specifying the Create option creates a single new list item identified by the user
(using the extended action entry area). If the program requires other user-
supplied information to create the list item, it must present the user with an
entry display on which to supply that information.
The user can enter any of the other options valid for that list using the
extended action entry area. The user must identify the list item the action is to
be performed against by typing the name of that item in the input field on the
extended action entry area.
Options entered in the extended action entry area are valid against any item in
the list proper. The user can perform an option against any item identified in
the list proper.
In the extended action entry area, if an option is entered and an identifier is
not, an error message should state that no function can be performed unless
an identifier is specified. There are two exceptions:
– The identifier is one of the items prompted for on an accompanying entry
display that is always presented to the user
– The program supports creating a temporary object (for example, a query)
that can be named later
If an identifier is entered and an option is not, no operation is performed
against the contents of the identifier field.
The identifier field can contain a defaulted value. When list processing is per-
formed, the option field in the extended action entry area is restored to blanks.
The identifier field, however, can keep a defaulted value.
List Operation When Options Are Specified

The following rules cover the general operation of lists that have options (actions)
specified against items (objects) in the list.
List processing should follow these general rules:

The sequence of list processing should match the sequence in which the list
items are presented on the display screen; that is, proceeding from the top line
to the bottom line (and from left to right if there is more than a single item on a
line).
After processing, the same view of the list that was presented before pro-
cessing should be shown again (unless an error occurs).
Specific rules for list operations are as follows:

The user can choose the same or different options for more than one list item.
The choices can be made on any of the item displays that can be paged.
Options are not processed until the Enter key is pressed (on the list display
itself or on an entry display that was displayed after the Prompt key was
pressed).
There should not be a limit on the number of options that can be typed on a list
(except the Select option).
If the user does not have the proper authority to perform the operation, display
such a message on the message line.

Operations are performed in the order shown in the list area.
Note: Some operations supported on list displays (Delete is an example) can
be grouped together on a separate display when presented for confir-
mation. Confirmation is given on the group of operations, but then each
operation is performed in the order shown in the list.
When list processing has completed, after having started from a page other
than the first, the user is returned to the same page of the list, and the list
position does not change (unless an error occurs). However, if the top entry of
the page was removed as a result of a delete operation, the list is positioned
such that the next remaining entry prior to the deleted entry is at the top of the
list.
When processing is completed, after being started from the first page, the list is
positioned with the current top entry in the list, even if entries were added to or
deleted from the beginning of the list.
The page/roll keys are used to move forward and backward through the list.
Pressing a page/roll key causes a full page roll (all items are replaced).
Even if a list allows a user to perform only one operation, the user should be
allowed to roll even after one item has been chosen, because processing will
not occur until the Enter key is pressed.
When a page/roll key is pressed, any selections made should be saved (the
operations should not be performed).
Lists that can page will not wraparound at the beginning or end of the list.
If multiple display operations are being performed, they should be done one at
a time, with completion of each indicated by the user pressing the Enter key on
the last display.
If the user interrupts list processing before it is finished (for example, by
pressing F3 or F12 from an interim display), the list is shown with all processed
options blanked out (in the Option column). All unprocessed options are still
marked. The option that was being processed when F3 or F12 was pressed
(the one where the cursor was positioned), is considered processed and, there-
fore, is unmarked.
If no processing errors occur, all operations are completed prior to the list being
shown again.
If a processing error is detected, processing is interrupted at that point to allow
the user to handle the error. The list can be displayed again with the option
field corresponding to the error in reverse image and the cursor positioned to
that field. A separate display may also be presented that allows the user to
handle the error. The appropriate error message is always presented on the
message line. When the user has resolved the error condition, list processing
is started again.
If multiple errors are detected, the list is displayed again with all option fields
corresponding to the errors in reverse image. The cursor is positioned to the
first field in error.
If the list display can be paged and the first error is on the currently displayed
fields, show the display as is without special positioning. If the first error is not
on the currently displayed fields, position the first error at the top of the area
that can be paged.

You can elect to have applications either dynamically update the list as the
operations in the Option column are performed, or wait to display the updated
list until the user presses F5=Refresh. Each option is described as follows:
– A dynamic update of the list can be done if the number of entries in the list
is not large and the update can occur as operations are performed without
a significant delay.
– If the number of entries is large and updating the list would result in a
noticeable delay, the list should be updated only when the user presses
F5=Refresh. If dynamic updating is not used, the entries that the user has
operated on (by entering an option next to one or more), and therefore
changed, should be annotated as to what operation has been performed on
them. The annotation should be made in a status field to the right of the
entry. Annotation should only be made by type of operation (for example,
operations that change the item or its status, such as Delete or Change,
should be annotated; operations such as Display should not.) No anno-
tation should be made on an entry where the operation failed. The anno-
tation should indicate the type of operation performed on the item. Show
(Ended) if the entry was ended, (Held) if held, (Changed) if changed, or
(Released) if released. Abbreviations that correspond to the operation per-
formed, such as Cnl, Hld, Chg, Rls, can be used if needed.
Cursor Positioning Rules

Cursor positioning rules are as follows:
When a list display is initially shown, position the cursor to the option field for
the first item in the list. Follow this rule even when there are some secondary
fields (for example Position to) at the top of the display.
When a list is presented after a position list or a page/roll function, position the
cursor to the first option field in the list area. After a position list function, the
item to which the list is to be positioned should be at the top of the list area
and the cursor should be in the option field for that item.
When another view of the list is presented, the cursor should remain on the
entry where it was (unless the cursor was not in the list area originally; then it is
positioned at the first item in list).
After selected operations have been performed and the list reappears, the fol-
lowing rules apply:
– The user should always return to the same page of the list from which the
Enter key was pressed. This is the primary rule.
– Place the cursor by the last item selected. If that item is not on the current
display, place the cursor by the first item on the current display.
– If the list was positioned at the top before the Enter key was pressed, the
list should stay at the top when processing is complete. For example, if an
item was added to the beginning of the list, position the list to start with the
new item. The user expects to see the top of the list if positioned to the
top.
– When errors are detected, position the cursor in the first option in error
(options in error should be in reverse image). The list should be positioned
again only if the entry that caused the error is not on the current display
page.

Error Condition Rules
Error condition rules are as follows:
When a page/roll key is pressed, option number fields are checked for entries
that are valid.
When an Exit or Refresh function is performed, the entries on the display are
not processed, and errors are not returned to the user.
If errors occur, the option field corresponding to the error is in reverse image,
the cursor is positioned to that field, and the appropriate error message
appears on the message line.
If the list display is can be paged and the first error is on the currently dis-
played fields, show the display as is without special positioning. If the first error
is not on the currently displayed fields, position the first error at the top of the
area that can be paged.
If the first error is on the currently displayed fields, show the display as is
without special positioning. If the first error is not on the currently displayed
fields, position the first error at the top of the area that can be paged.
Each product can have an internal limit for the number of selections that can be
made from a list at one time. If the user exceeds this limit, display an error
message. This error message should include these items:
– The fact that the maximum number of allowed selections has been
exceeded.
– The amount by which this maximum number was exceeded (so the user
knows how many selections to remove).
When this message is presented, the pending selections should not be in
reverse image.
Issue the following errors if the user attempts to page past the top or bottom of
an area that can be paged:
– Top message
Message Text: Already at top of area.
Cause: You pressed a key to move backward in an area. However, you
cannot move in that direction because you are already at the top of that
area.
Recovery: If you want to move displayed information backward in another
area, move the cursor to that area and press either the Page Up key or the
Roll Down key again.
– Bottom message
Message Text: Already at bottom of area.
Cause: You pressed a key to move forward in an area. However, you
cannot move in that direction because you are already at the bottom of that
area.
Recovery: If you want to move displayed information forward in another
area, move the cursor to that area and press either the Page Down key or
the Roll Up key again.

List Where Only One Item Can Be Selected
If more than one item is selected and the Enter key is pressed:
List is shown again with all selections still marked
All selections are in reverse image
Issue the message: Only one selection allowed
If one or more items are selected and a Roll key is pressed:

No message is issued
Roll is performed
List Format in Empty List Situation

If the user requests a list of items and there are no items available, the rules are as
follows:
1. Start the text in column 4 on the second line following the list area column
headers (leave one blank line). If only one list line is available, place the text
on the line immediately following the column headers.
Opt Document Date Text
_ __________
...blank line...
(No documents in folder)
2. The attributes of the text should be of normal emphasis and normal color
(green).
3. If the Help key is pressed while the cursor is anywhere in the list area, pro-
cessing should be done as though the list is not empty (online help information
is available for the columns).
4. The text should be generic and state that the list is empty, but should not state
the reason. The text should be in parentheses.
5. The text should begin with No xxxxxxxx where xxxxxxxx identifies what is not
displayed. The phrase should not be followed with a period, because it is not a
full sentence. For example:
(No objects in library)
6. If information about why the list is empty is desired, present it in a message on
the message line.
Defining the Function Key Area for All Displays

The guidelines for the function key area are as follows:
List active key assignments from left to right in numeric order, beginning at
position 2. Active F keys cannot be omitted (with the exception of F1) unless
they are displayed by the More keys function, in another set of keys. Capitalize
only the first letter of the first word in the function descriptions.
Leave three spaces between key assignments unless more are needed for
alignment.
When function keys are displayed on two lines, align the key assignments on
the left (on F) if possible.
F3=Xxxxxxxxx F4=Xxxxx F5=Xxxxxxxxxxx F6=Xxxxxxxxxxxx
F7=Xxxxxxx F12=Xxxxxxx F13=Xxxxxxx

Display the keys in ascending numeric sequence (gaps in the sequence can
exist).
If one line of a two-line function key area contains a function key description
that is very long (that is, forces a gap of up to seven blanks), this description
may span two or more function key descriptions on the other line for the
purpose of alignment. For example:
F13=Information Assistant F16=System main menu
If all the active keys cannot be displayed in two lines, support F24=More keys.
The guidelines for what to display are:
– Enter, Help, and the Roll or Page keys should not be displayed.
– Display active function keys in multiple one-line or two-line sets. Use
F24=More keys to see the next set of function keys in the function key area
of a display. All sets must reserve the same number of lines, one or two.
F3=Xxxxxxxxx F4=Xxxxx F5=Xxxxxxxxxxx F6=Xxxxxxxxxxxx
F7=Xxxxxxx F12=Xxxxxxx F24=More keys
– F3=Exit and F12=Cancel must be shown in the primary set (and only in that
set). Only F24 is displayed in all sets.
– Although the function keys should be in numeric sequence in each set, the
application can determine which keys are in each set. The functions dis-
played in the primary set should be those that are used the most.
Displayed function keys on system displays are specified as blue on color dis-
plays.
Optional Command Line and Identifier Field

You have probably seen other system menus with a slightly different format.
Figure 21-5 on page 21-9 shows a menu from within an application, and is the
type of menu you should create. System menus have an additional system identi-
fier in the upper left corner. This is used as a name in conjunction with the GO
command. Such names have to be present as object names in system tables.
The system uses names in this identifier field only on menus accessed by the GO
command. Using this identifier field on application menus could confuse the user
because the names would not work with the GO command. A user can access the
system menus, given the menu identifier. Using the GO command, a user can
specify a particular menu, by the menu identifier, or, if a particular menu is not
known, a generic identifier can be used. In this case, the user is shown the Work
with Menus display and from this list, can specify a menu to run. For more infor-
mation on how to create display file menus, see Chapter 9, “Creating and
Accessing Menus Using Display Files” on page 9-1.
System menus also use a command line as the entry field for menu selection. The
only command area support DDS provides is to allow you to define an entry field
(with accompanying field prompt) into which a command could be entered. You
write all code to support this entry area as a command area, including passing the
command to the system, handling the Prompt function, handling the Retrieve func-
tion, and handling help for the command. “Available Command Line Tool” on
page 21-37 provides information on a command line function available in the
QUSRTOOL library to assist in putting a command line on an application display.

To support commands from within an application, make one or more system dis-
plays with a command line available or provide a command line on one or more
application displays.
Note: If the commands change something the application is dependent on, results
that cannot be predicted can occur.
With the AS/400 system you can limit command entry to the system commands
and application commands you want. Typically, this is the best approach for the
user. You can limit the user to special commands by specifying *YES for the Limit
capabilities prompt on the Create User Profile (CRTUSRPRF) display, as in
Figure 21-11. You can then create commands with the Create Command
(CRTCMD) command. Specify *YES for the Allow limited users prompt to make
the command available to limited users as in Figure 21-12 on page 21-36 and
Figure 21-13 on page 21-36.
Note: Most commands are shipped with ALWLMTUSR(*NO). See the Limit capa-
bilities (LMTCPB) prompt on the Create User Profile (CRTUSRPRF) display
for a list of ALWLMTUSR(*YES) commands. You can change IBM-supplied
commands with the Change Command (CHGCMD) command. If you
change an IBM-supplied command you must keep track of your changes in
a control language (CL) program because the commands are replaced with
each release.
à Create User Profile (CRTUSRPRF)

ð
User profile . . . . . . . . . . __________ Name

User password . . . . . . . . . \USRPRF___ Name, \USRPRF, \NONE
Set password to expired . . . . \NO_ \NO, \YES
User class . . . . . . . . . . . \USER__ \USER, \SYSOPR, \PGMR...
Current library . . . . . . . . __________ Name, \NONE
Initial program to call . . . . \NONE_____ Name, \NONE
Library . . . . . . . . . . . __________ Name, \LIBL, \CURLIB
Initial menu . . . . . . . . . . MAIN______ Name, \SIGNOFF
Library . . . . . . . . . . . \LIBL_____ Name, \LIBL, \CURLIB
Limit capabilities . . . . . . . \YES____ \NO, \PARTIAL, \YES
Text 'description' . . . . . . . \BLANK_____________________________________
______
Bottom
F3=Exit F4=Prompt F5=Refresh F1ð=Additional parameters F12=Cancel
F13=How to use this display F24=More keys
á ñ
Figure 21-11. Create User Profile Entry Display

à Create Command (CRTCMD)
ð
Command . . . . . . . . . . . . __________ Name

Library . . . . . . . . . . . \CURLIB___ Name, \CURLIB
Program to process command . . . __________ Name
Source file . . . . . . . . . . QCMDSRC___ Name
Source member . . . . . . . . . \CMD______ Name, \CMD
Text 'description' . . . . . . . \SRCMBRTXT_________________________________
______
Additional Parameters
Validity checking program . . . \NONE_____ Name, \NONE

Library . . . . . . . . . . . __________ Name, \LIBL, \CURLIB
Mode in which valid . . . . . . \ALL______ \ALL, \PROD, \DEBUG, \SERVICE
+ for more values ________
More...
F24=More keys
á ñ
Figure 21-12. Create Command Display with Additional Parameters Selected
à Create Command (CRTCMD)

ð
Where allowed to run . . . . . . \ALL______ \ALL, \BATCH, \INTERACT...

+ for more values ________
Allow limited users . . . . . . \YES \NO, \YES
Maximum positional parameters . \NOMAX ð-75, \NOMAX
Message file for prompt text . . \NONE_____ Name, \NONE
Message file . . . . . . . . . . QCPFMSG___ Name
Current library . . . . . . . . \NOCHG____ Name, \NOCHG, \CRTDFT
Product library . . . . . . . . \NOCHG____ Name, \NOCHG, \NONE
Authority . . . . . . . . . . . \USE______ Name, \USE, \ALL, \CHANGE...
Bottom
F24=More keys
á ñ
Figure 21-13. Second Display of Additional Parameters
If your application uses commands, you should define an entry field (with accompa-
nying field prompt) on the display. To match the AS/400 system, command lines
should appear as follows:
===> ________________________________________________________________
The one-line command line begins in position 7 on the line immediately above
the function key area and ends in position 79 on the same line.

The command line is identified by a command line prompt, beginning in posi-
tion 2. If the command line is used to enter either the menu selection or a
command, the text of the prompt is:
The command entry arrow (===>) is in positions 2 through 5 of the first line of
the command line.
The command entry arrow (===>) is normal intensity like the command line.
Available Command Line Tool

General-Use Programming Interface
The QUSCMDLN program can be used to display a pop-up window that contains a
command line. The command line can be used to enter system commands.
QUSCMDLN can be called by any user program. More information about
QUSCMDLN is available in the System API Reference.
End of General-Use Programming Interface
The QUSRTOOL library on the AS/400 system contains a command line function
and documentation to assist in putting a command line function on an application
display (member CMDLINE, in file QATTINFO, in QUSRTOOL). One way to
access this function is by using the Work with Members Using PDM
(WRKMBRPDM) display, shown in Figure 21-14.
à Work with Members Using PDM (WRKMBRPDM)

ð
File . . . . . . . . . . . . . . QUSRTOOL \PRV, name

Library . . . . . . . . . . . QATTINFO__ \PRV, name, \LIBL, \CURLIB
Member . . . . . . . . . . . . . CMDLINE____ \PRV, name, \generic\...
Member type . . . . . . . . . . \ALL_______ \PRV, name, \generic\...
Bottom
F24=More keys
á ñ
Figure 21-14. Work with Members Using PDM Entry Display

Common Key Assignments
Table 21-6 summarizes common AS/400 function key assignments and indicates
when each key is used. The keys identified as CUA can be used only for the func-
tion defined. If the function is not available, the key should not be used for another
function.
Non-CUA keys are keys commonly used on the system for a particular function. If
the function is available on a display, the key assignment given should be used for
compatibility with system key assignments. If the function is not being used, you
can use the key assignment for an application-specific function.
Table 21-6 (Page 1 of 7). Function Key Assignments

Name Key CUA Usage/Function
Help F1 Yes Active on all displays, but not shown on the
display. F1 is also mapped to the Help func-
tion but is not displayed in the function key
area.
Set 1/Set 2 F2 Yes Required when applications need more func-
tion keys than can be assigned to the 24
numbered keys. F1=Help, F2=Set n, F3=Exit,
F9=Retrieve/command, and F12=Cancel are
required in both sets of function keys.
Exit F3 Yes Usually active and shown on all displays. F3
exits the application or a unit of work within
the application. If the application is exited,
the user is returned to the display from which
the application was requested. If a unit of
work within an application is exited, the user
is returned to a predefined point within the
application that serves as a point of focus for
requesting work (usually a primary menu).
User input is normally discarded; however, if
pressing the Exit key could cause loss of data
and require extensive user effort to retrieve or
reconstruct, an exit display should be pro-
vided to give the user the option of saving the
data before exiting.
The Exit function must be available on all dis-
plays except:
Displays used for confirmation of the
delete action
List display shown as a result of pressing
F4
Exit displays provided to give the user the
option of saving the data before exiting

The following describes the use of the Exit
key for specific display types:
Menu. If the menu is part of a dialog that
began with a primary menu or the initial
menu after sign-on (for example, the
primary or initial menu is the first menu
on the current menu stack), returns to this
primary or initial menu. Pressing the Exit
key from the primary menu exits the
current dialog and returns to the display
from which the dialog was entered.
List display. Returns to the menu or
other display from which the list display
was requested. User input is discarded.
Entry display. Returns to the menu or
other display from which the entry display
(or set of entry displays) was requested.
User input is discarded. However, an exit
display can be provided to give the user
the option of saving the entries or
changes.
Information display. Returns to the
menu or other display from which the
information display (or set of information
displays) was requested.
Any help display. Returns to the display
from which help was originally requested.

Prompt F4 Yes Should be supported whenever the display
contains an entry field for which the valid
entries are known but are not shown on the
display. F4 provides a list of selectable
values (usually a list of names) related to the
field where the cursor is currently positioned.
When the user selects one or more values
from the list, those values are used as input
values for the field.
If F4 is pressed and the function is not sup-
ported for the field containing the cursor, the
user receives an error message.
If the function is supported for the field con-
taining the cursor and either a default value
exists or the user makes an entry in the field,
the value in the field is kept and the list is dis-
played. If the user selects a value from the
list, this value replaces the previous value in
the field. If the user does not select a value,
the previous value is kept.
If the user leaves the field blank and presses
F4, the list is also displayed for a value to be
selected.
When a command is typed on a system
command line and F4 is pressed, a prompt
for the command (an entry display with input
fields for the command parameters) is dis-
played.

Refresh F5 Yes Should be used where the Refresh function is
appropriate. F5 can start resetting defaults
on an entry display, or update (refresh)
system output being displayed. The using
program determines what is appropriate
depending on the display type:
Menu and help display. Not usually
used.
Entry display. Clears user input and
shows the display again with the original
values provided at the time the display
was first shown. The cursor is reposi-
tioned at the first logical input field on the
display. If the entry fields are on a
display that can be paged, Refresh
should position the cursor at the begin-
ning of the list of entry fields.
List display. Clears user input and
updates the display to show the current
status. Refresh should maintain the
same position in the list. The list should
be shown again with the entry that was at
the top of the list page when F5 was
pressed still at the top of the list page,
and with the cursor positioned at the top
list item.
Display with output-only fields (data
output items). Updates the information
variable fields to show the current values.
If the information variable fields are in a
display that can be paged, Refresh
should maintain the same position in the
list of fields.

Summary of list positioning rules with the
Refresh function:
1. The display is shown again with the entry
that was at the top of the display still at
the top of the display.
2. If that entry no longer exists, the entry fol-
lowing it is shown at the top of the
display.
3. When the first entry in the list was at the
top, the first entry is shown at the top
again (even though it may be a new first
entry).
4. If the entry that was at the top of the
display no longer exists and there are no
entries following it, the display is shown
with the first entry of the entire set of
values at the top of the display.
5. If the location-determining attributes of the
entry at the top of the display have
changed, the list is shown with the entries
starting where the old entry would have
been.
Create F6 No Optional. F6 is used for the Create function
on a list display that has not converted to the
combination list with 1=Create. However,
using a combination list is preferred on the
AS/400 system. Summary of uses for F6:
May be requested with the cursor in any
position.
Go to separate display in which additional
object(s) can be defined.
On completion, show list display from
which Create request was made again.
Show created object(s) sorted into the list.
Requests that were pending at the time
F6 was pressed should not be processed,
but should still be pending.
Note: When a very large number of new
entries can be added, such as
with Add Entries to a Distribution
List, it may be a good application
decision to not allow an Add or
Create function until other pending
requests are completed. In this
case, a message can be issued
when F6 is requested and other
requests are pending.
Retrieve F9 Yes Required on all panels or pop-up windows
with a command line.

Command F9 Yes Used to display a pop-up window containing a
command line.
Cancel F12 Yes Must be active and shown on all displays.
F12 returns to the previous logical display. It
provides the basic navigation function of
backing up one step in the interface, as
described for the following displays:
Menu. Backs up to the previous menu or
other display from which the menu was
directly started. Any user input is dis-
carded.
Entry and List displays. Backs up to
the previous display. User input is dis-
carded. (If significant data would be lost,
an exit display should be shown.)
Information displays. Backs up to the
display previously shown.
Note: If a set of information (including
input or output fields) can logically
be presented in a paging format,
use a display that can be paged
instead of the Enter and Cancel
keys for forward and backward
navigation through the information.
This function must be available on all dis-
plays, except when a logical Cancel function
is precluded by other factors. An example is
when only the Exit function is appropriate
because the user must first verify (using an
exit display) whether data is to be saved or
not.
XXXX Main Menu F16 No Optional for applications. F16 must be active
and shown on system menus. It provides a
direct path to the system or application
primary menu. A target menu other than the
system main menu must be explicitly stated.
This key would normally be used within an
application to provide a direct path to the
application main menu. When this key is
pressed, any user input is discarded. If F3 or
F12 is pressed on the target menu, the user
is returned to the display where F16 was
pressed.
Top of list F17 No Optional on displays that can be paged. F17
pages to the top or beginning (same as *TOP
in the Position to field). This key should be
supported when the Position to field is not
present.

Bottom of list F18 No Optional on displays that can be paged. F18
pages to the bottom or end (same as *BOT in
the Position to field). This key should be sup-
ported when the Position to field is not
present.
Left F19 Yes Should be operational on all displays with a
horizontal area that can be paged. There are
no common columns of information between
successive views.
Right F20 Yes Should be operational on all displays with a
horizontal area that can be paged. There are
no common columns of information between
successive views.
More options F23 No Optional. List displays only. Use F23 to
display the next set of options in the instruc-
tion area of a list display. Use when the first
set of options shown in up to three lines is
not complete. It is recommended that an
ellipsis be shown after the last option in the
options area if other options exist that cannot
be seen until F23 is pressed. The most
important functions are shown first, and the
less frequently used options are shown after
F23 is pressed.
More keys F24 No Optional. Use F24 to see more active func-
tion keys in the function key area of a display.
Use when all key descriptions will not fit in
the two-line function key area.
Defining Help Information for All Displays

Help for AS/400 system displays consists of specific information on fields where the
cursor is positioned, and, when the cursor is positioned anywhere else, general
information on what the display is for and how the user interacts with it.
Help on the system also includes a system help index. This section describes the
type of help support for fields provided by the system for each display type.
Help for the Menu Display

The following table and illustration describe the help information for each menu help
area:

Table 21-7. Type of Help for Each Help Area–Menu Display
Cursor Position Help Information UIM Tag
On line containing option What function each option HELP element of MENUI tag
number and description performs
In function key area Function performed by HELP element of KEYL and
each function key turned KEYI tag
on for the display
Any other display position Beginning of general help HELP element of PANEL tag
for display (user can page
through all help for
display, which includes
description of how to use
the entry line)
On command line with no Entry at beginning of HELP element of PANEL tag
entries general help for panel
(user can page through all
help for display)
On command line with What function each option HELP element of MENUI tag
option number entered performs
Cursor not on
any area defined
=== top ===
with contextual
help
What panel does
Extended
Menu Panel How to get help Help
Select one of the following: Using command line
Cursor in
1. Option 1 description What option 1 does
contextual
What option 2 does
2. Option 2 description
help area
3. Option 3 description What option 3 does
.
. .. .
. .
.
n. Option n description . Contextual
= = Help
What option n does
F2=xxx F3=xxx . . . Fn=xxx
Function keys
=== bottom ===
From contextual help,

user can press F2 to go
to extended help.
RV2W027-4
The following table gives the DDS considerations for help on menu displays:
Table 21-8. DDS Considerations–Help on Menu Displays

Item Help Area Area Covered
Each menu option From position 1 to the farthest right display position on the
line containing the option number and the option text
Function key area From position 1 on the first line of the function key
descriptions to the farthest right display position on the last
line of the function key descriptions

The remainder of the display is defined as the general help area.
Help for the Entry Display

The following table and illustration describe the help information for each entry
display help area:
Table 21-9. Type of Help for Each Help Area–Entry Display

On input field or descriptive Use of each possible entry HELP element of DATAI tag
lines associated with input in input field
fields (data entry item)
In function key area Function performed by HELP element of KEYL tag
each function key turned
on for the display
display)
Cursor not on
any area defined
with contextual === top ===
help
What panel does
Extended
Entry Panel Help
Item Choice Position Choices How to get help
aaaa . . Cursor in
Help for aaaa
contextual
bbbb . . Help for bbbb
help area
cccc . . Help for cccc
.. ..
. . .
. Contextual
nnnn . . . Help
Help for nnnn
Function keys
=== bottom ===

user can press F2 to
go to extended help.
RV2W026-6
Figure 21-15. Help Areas for Entry Displays
The following table gives the DDS considerations for help on menu displays:
Table 21-10. DDS Considerations–Help on Entry Displays

Each item From position 1 on the first line of the item text to the far-
thest right display position on the last line of either (1) the
input field(s) or (2) the possible choices text, whichever
occupies the most lines (see Figure 21-15).

Help for the Information Display
The following table and illustration describe the help information for each informa-
tion display help area:
Table 21-11. Type of Help for Each Help Area–Information Display

Cursor Position Help Information
In output field or descriptive Meaning of output field. (A data output field is an area on
lines associated with output a display consisting of descriptive text and an associated
field. output field into which variable data is written at display
time.)
In function key area Function performed by each function key turned on for the
display
Any other display position Beginning of general help for display (user can page
through all help for display)
Cursor not
on any
area defined
with
contextual === top ===
help
What panel does

Extended
Information Panel Help
Item Choice Position Choices How to get help
Cursor in
Help for aaaa
aaaa . . : wwwww
contextual
bbbb . . : xxxxx Help for bbbb
help area
cccc . . : yyyyy Help for cccc
.. ..
. . .
. Contextual
nnnn . . : zzzzz . Help
Help for nnnn
Function keys
=== bottom ===

RV2W043-5
Figure 21-16. Help Areas for Information Displays
The following table gives the DDS considerations for help on information displays:
Table 21-12. DDS Considerations–Help on Information Displays

Data output items From position 1 to the farthest right display position on the
line (see Figure 21-16)

Help for the List Display
The following table and illustration describe the help information for each list display
help area:
Table 21-13. Type of Help for Each Help Area–List Display

In input field or descriptive Use of each possible entry HELP element of LISTCOL
lines associated with input in input field tag
fields
In specific column Meaning and use of HELP element of LISTCOL
column. This includes tag
how to use that entry field
(for example, creating a
list entry or performing an
action against a list entry
without paging to it) for the
column containing the
extended action entry.
In function key area Function performed by HELP element of KEYL tag
each function key turned
on for the display
display)
List Panel
Position cursor, enter choices
1=xxx 2=xxx 3=xxxxx 4=xxxx
0 AAA BBB CCC NNN
xxx xxx xxx ... xxx
Cursor not on
xxx xxx xxx xxx any area defined
with contextual === top ===
. . . . .
. . . help Extended
. .
. . . . . How to use panel
Help
How to get help

Option column and
text for all option
list actions
Cursor in
Column AAA
contextual
Column BBB
help area
Column CCC Contextual
Help
.
.
.
Column NNN
Function keys
=== bottom ===

RV2W025-3
Figure 21-17. Help Areas for List Displays

The following table gives the DDS considerations for help on list displays:
Table 21-14. DDS Considerations–Help on List Displays

Each column From the farthest left position on the first line of the column
heading to the farthest right position on the last line of
column data. The farthest left position is defined as the far-
thest left character position of either the longest heading
line or the data column, whichever is wider. The farthest
right position is defined as the farthest right character posi-
tion of either the longest heading line or the data column,
whichever is wider. (See Figure 21-17 on page 21-48).
Defining and Presenting Messages

For compatibility with the system, an application should present an error message
any time a user types a selection or actual value that is not allowed. The message
itself should provide as much information as possible to allow users to continue
processing. On the system, messages appear on the bottom line of the display.
Messages should be supported by help information that gives an expanded

description of the error (if necessary) and a remedy to the problem. In general, the
help information should state what happened and, if possible, what to do if an
action is required. The highest priority should be given to a statement of action
required.
The user can request help for the message being displayed by moving the cursor
to the message line and pressing the Help key. Message help is presented on a
separate display and can extend to more than one display if needed.
The DDS keyword ERRMSG is easy to use, but locks the keyboard and lets the
user see only one message at a time. This option is acceptable if there are only a
few messages. However, to keep the user's interaction with the message easy, the
goals are to:
Not make the user unlock the keyboard to respond to the message
Provide a formatted display that can be paged for additional message informa-
tion
To accomplish this, you should use a subfile containing messages from a program
message queue (SFLMSGKEY, SFLMSGRCD, and SFLPGMQ keywords) rather
than use the ERRMSG, ERRMSGID, SFLMSGID, and SFLMSG keywords.
To provide messages that tell the user what is correct, not simply that an entry is
not valid, validity checking in your program is recommended over using the
CHECK, RANGE, VALUES, and COMP keywords in DDS. When these keywords
are used, a message tells the user that what is entered is not valid, but no explana-
tion or indication of what is valid is given.

Message presentation on the AS/400 system adheres as closely as possible to the
following rules:
Detected input errors result in an error message and the function is not per-
formed.
Error messages are shown on the display where the values that are not valid or
options were entered. The error message does not appear on a separate
display started by the data entered and the Enter action.
When errors are detected on data entered on a display, the display is shown
again with:
– The first value(s) in error visible. In the case of a display that cannot be
paged, the display is shown again with the erroneous values still in the
fields where they were entered. For the display that can be paged where
the user only entered values on one display page of values, the display is
shown again as it appeared when the Enter key was pressed. For the
display that can be paged where the user has paged and entered values
on multiple pages, the display is shown again with the first page of values
that contains an error.
– The erroneous values are shown in reverse image (if the display station
supports this).
Note: If reverse image is used in a highlighted input field, the highlight
attribute should be turned off (changed to normal intensity) to avoid
a no display situation with 5250 display stations.
– The cursor is positioned on the first field with a value in error.
– The keyboard is not locked.
When multiple errors are detected on data entered on a display:
– Error messages for all errors on the display can be viewed, one at a time,
on the message line using the roll/page key.
– If multiple messages are waiting, the last three positions of the message
line contain "b+b" (b indicates blank) in high intensity to indicate additional
messages are present. The roll/page keys allow viewing the other mes-
sages. To page through the messages, the user moves the cursor to the
message line and presses the appropriate roll/page key.
– When multiple messages are presented, the messages are in the same
order as the values in error appear on the display.
– When the user takes the appropriate corrective action (pressing a key, for
example), the error message is removed. Only messages for errors that
have not been corrected are present on the message line or waiting to be
viewed.
If a user requests help for an item other than the message (the cursor is not on
the message line when the user presses the Help key), the message remains
on the display when the user returns from the Help displays.
Designing Common User Access (CUA) Entry Level Models

CUA has defined the entry model to guide the programmer of an existing simple,
transaction-oriented application in redesigning the user interface of that application
to use some of the standard interface components defined by CUA. The key differ-
ence between entry and the other CUA models is that entry is action oriented and

follows an action-object process sequence. Other CUA models have an object-
action orientation.
The CUA entry model closely resembles the existing AS/400 interface. The user is
typically asked to select an action or task from a menu or list and then indicate the
object to which that action applies.
Entry Dialog Actions

Certain CUA entry dialog actions must be shown in the function key area when
they are available on the display area. Table 21-15 summarizes CUA entry dialog
actions indicating the function key assignments and when each key is used. If the
function is not available, the key should not be used for another function.
Table 21-15 (Page 1 of 2). CUA Entry Dialog Actions

Function Key Usage Requirements
Enter Enter Active on all displays, but not shown in function key area
Help F1, Help Help must be active on all displays, but is not shown on
the display. F1 must also be mapped to the Help function.
F1 is not shown in the function key area.
CUA screens should have F1 turned on for help;
however, DDS also allows the Help key to be assigned to
this function.
Exit F3 Must be active and shown on all displays except:
Confirmation displays.
List display that appear as a result of the user
pressing F4.
Exit displays that result from the user pressing
F3=Exit where the decision is made as to save or not.
Pop-up windows
Prompt F4 Must be supported whenever the display contains an
entry field for which the valid entries are known but
cannot be shown in the possible choice description area.
Required on any display with a command line.
Refresh F5 Required on action list displays (except selection lists)
and strongly recommended on other list displays. Should
be used on other displays where the refresh function is
appropriate.
Backward Page Up, Must be operational on all displays with an area that can
F7 be paged. Not shown in function key area. Page up
shows the previous page of data.
CUA displays should have Page up turned on for paging;
however, DDS also allows F7 to be assigned to this func-
tion.
Forward Page Down, Must be operational on all displays with an area that can
F8 be paged. Not shown in function key area. Page down
shows the next page of data.
CUA displays should have the Page Down key turned on
for paging; however, DDS also allows F8 key to be
assigned to this function.
Retrieve F9 Required on all displays with a command line.
Command F9 Used to display a pop-up command line.

Table 21-15 (Page 2 of 2). CUA Entry Dialog Actions
Function Key Usage Requirements
Cancel F12 Must be active and shown on all displays except:
When the previous display was a prompt for a func-
tion that had already been processed.
On a display where only the Exit function is appro-
priate because the user must not be allowed to exit
without first verifying (by way of an Exit display)
whether data is to be saved.
Left F19 Must be operational on all displays with a horizontal area
that can be paged. There are no common columns of
information between these successive views.
Right F20 Must be operational on all displays with a horizontal area
that can be paged. There are no common columns of
information between these successive views.
Function Key Area and Message Line Relationship: The entry model has the
message line placed as a separator between other display areas and the function
key area, and command area if used. A command line would be above the func-
tion key area and below the message line.
The guidelines for the function key area do not change, except for placement. A
single line of function keys is on line 24. Two lines of function keys occupy lines 23
and 24. The message area is on the line immediately above the function keys.
Single-Choice Selection (Menu)

A CUA single-choice selection field displays a list of choices from which the user
can select one choice. The display always has a title, an instruction, a list of
choices, and a labeled field for typing the number of the choice selected.
Figure 21-18 shows an example of a CUA single-choice selection field on a
display.
ð
_ 1. Work with documents in folder

F3=Exit F12=Cancel
á ñ
Figure 21-18. Example of an Application Menu

Selection Choices and Choice Entry Field
The guidelines for selection choices and the choice entry field are as follows:
Begin the choices one blank line after the instruction line.
A choice entry field is on line 5 preceding the first choice. The length of a
choice entry field is one position if the number of choices is less than 10, two
positions if any choice numbers are 10 or greater (up to 99).
The choice entry field starts in position 2.
List the choices (one per line) starting in position 4 if the number of options is
nine or less. The number is followed by a period and is not highlighted.
If any choice number exceeds 9, the choice entry field requires 2 characters (in
positions 2 and 3). Option numbers 1 through 9 start in position 6, and
numbers 10 and higher start in position 5.
Guidelines for Single Selection Field Operation

The single selection field allows two methods of interaction. The user can enter the
number of the choice in the choice entry field and press the Enter key, or can move
the cursor directly to the desired choice and press the Enter key.
Use the following rules:

If the cursor is in the choice entry field, or 1 character position to the right (posi-
tion 3 or 4), process the choice in the choice entry field.
If the cursor is not in or immediately to the right of the choice entry field, and
the choice entry field contains a blank, process the choice on the same line as
the cursor.
If the cursor is not in or immediately to the right of the choice entry field, the
choice entry field is not blank (a value has been entered), and the value in the
field is not the same as the choice being selected, present a message that
asks the user to choose between the choice being pointed at and the choice
indicated by the value in the choice entry field.
Entry Display
Entry displays let users type in entry fields, and are typically used to indicate the
system parameters and options associated with an action request. Figure 21-19
on page 21-54 shows an example of an entry display.

à Merge Options
ð
Job queue . . . . . . . . . . . _ 1. Placed on job queue

2. Not on job queue
Completion message . . . . . . _ 1. Message sent
2. Message not sent
Job description . . . . . . . . __________ + Name
Adjust/paginate option . . . . _ 1. Do not adjust
2. Line ending only
3. Line and page ending
Report line format . . . . . . _ 1. Multiple lines
2. No multiple lines
Footnotes . . . . . . . . . . . _ 1. Collected
2. Not collected

á ñ
Figure 21-19. Entry Display
Entry Fields
CUA entry fields take two forms. The first form is an entry field that requests a
user-supplied value, like a name, descriptive text, or address. Frequently, these
fields can accept a value from a list of values that is of variable length and con-
tents. When such a list of valid choices exists, support F4 to allow the user to
request the list and simply choose from it.
Using descriptive text (F4 for list) is preferred method for identifying a field sup-
porting F4. As an alternative, CUA specifies a plus sign (+) to follow the entry field
(with one intervening blank for an attribute byte) if the field supports F4.
File . . . . . . . . . __________ + Name
The second type of entry field supports a selection from a fixed set of choices. CUA
calls this a Selection field. If only one choice can be selected, number the choices.
For example:
Type style . . . . . _ 1. Prestige elite (12 pitch)
2. Courier (1ð pitch)
3. Essay standard
The user selects by either moving the cursor or typing in the entry field (see
“Guidelines for Single Selection Field Operation” on page 21-53).
If the list of values is more than can be shown in one to five lines, support F4.
CUA discourages prompts that are phrased to require selection of a Yes or No

response. For example, for setting printing options, instead of using:
Duplex . . . . . . . . _ 1. Yes
2. No
CUA recommends:

One or both sides . . _ 1. Both sides
2. One side
Selection choices are aligned on the left and shown on separate lines. No comma
or other punctuation is shown at the end of any line.
_ 1. Prestige elite (12 pitch)
3. Essay standard (proportional)
4. Essay bold (proportional)
Information Display
A CUA version of the information display shown could be paged instead of being in
two parts as the AS/400 example shown in Figure 21-7 on page 21-18. Also, the
explanatory information for Yes and No would not be required because Yes and No
would not have been used for the entry function for which this information display is
based. See “List Display” for a discussion of CUA paging information.
Figure 21-20 shows an example of the sample information display in CUA format.
à View Document Details

ð
More: +

ooooooooooo
Change formats/
options . . . . . . . : ooooooooooooooo

Print as labels . . . . : ooooooooooo
oooooooooo
F3=Exit F12=Cancel
á ñ
Figure 21-20. Example of an Information Display
List Display
Like the information display, a CUA version of the sample list display would differ
primarily in the display of paging information. Figure 21-21 on page 21-56 shows
an example of a list display.
CUA uses the word More followed by a colon and then paging symbols to indicate
additional information exists outside the visible area, and the direction to page to
see that information.
If the user can page in all four directions, backward, forward, left, and right, reserve
space for all four paging symbols. If the user can page in only two directions,

reserve space for two. Symbols are not shown if the user cannot page in the direc-
tion they represent; blanks are shown instead.
The four paging symbols are:

< indicates there is information to the left
– indicates there is information backward
+ indicates there is information forward
> indicates there is information to the right
à Work with Documents in Folders

ð
Folder . . . ______________________________________________________________
Position to . . . . . . ____________ Starting character(s)
Type options (and Document), press Enter.

1=Create 2=Revise 3=Copy 4=Delete 5=View
More: -+
__ ____________
F3=Exit F4=Folder list F5=Refresh F6=Print list

á ñ
Figure 21-21. Example of a List Display
According to CUA, the following paging indicators can be used instead of More: - +
for alternative text paging indicators:
Top Above the area that is paged when users view the beginning of the
information
More Above the area that is paged when users can page backward
Bottom Below the area that is paged when users view the end of the information
More Below the area that is paged when users can page forward
Note: This technique takes extra lines above and below the area that will be
paged.
Using CUA defined paging information is not possible when using subfiles. The
application program itself must handle the paging. See “List Fields” on page 21-24
for more information.
The paging method used should be cursor independent when the information is
paged in fixed amounts.

Help Information
CUA help information resembles AS/400 help information by having a number of
defined functions available from every help display via function keys. These func-
tion keys and their functions are:
F1=Help for help
F2=Extended help
F3=Exit
F5=Tutorial
F9=Keys help
F11=Help index
F14=Tutorial
These functions cannot be provided by DDS using function keys from help displays.
For information on DDS capabilities for help information, see “Defining Help Infor-
mation for All Displays” on page 21-44.

Part 6. Appendixes
Appendix A. UIM Panel Group Definition Language . . . . . . . . . . . . A-1
Tag Content Formatted as Paragraphs . . . . . . . . . . . . . . . . . . . A-2
Panel Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2
Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2
Panel Group Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Help on Panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3
Panel Group Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4
Name Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4
Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-5
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
Imbeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
DBCS Graphic Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
Hexadecimal Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6
APPFMT (Application Formatted Area) . . . . . . . . . . . . . . . . . . . . . . A-8
Application Formatted Data . . . . . . . . . . . . . . . . . . . . . . . . . . . A-9
Example: Application Formatted Area . . . . . . . . . . . . . . . . . . . . . A-9
BOTINST (Bottom Instruction) . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-10
CHECK (Validity Checking) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-11
Example: Validity Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . A-12
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-12
CIT (Title Citation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13
Example: Title Citations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-13
CLASS (Class Definition) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-14
Example: Class Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . A-24
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-24
Display Forms of Numeric Values . . . . . . . . . . . . . . . . . . . . . . . . A-24
Display Forms of Character, Date, and Time Values . . . . . . . . . . . . . A-25
CMDLINE (Command Line) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-26
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-26
COND (Condition Definition) . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-27
Example: Conditioning an Option . . . . . . . . . . . . . . . . . . . . . . . . A-29
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-29
COPYR (Copyright) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-30
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-30
DATA (Data Presentation Area) . . . . . . . . . . . . . . . . . . . . . . . . . . A-31

Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-33
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-34
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-34
Example 2: Two-Column Format in a Data Entry Panel . . . . . . . . . . . A-34
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-34
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-35
Example 3: Two Presentation Areas for Data Items . . . . . . . . . . . . . A-35
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-35
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-36
Example 4: Data Presentation Area with a Menu Area . . . . . . . . . . . A-36
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-36
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-36
Example 5: Data Entry Panel with a Nested Data Group . . . . . . . . . . A-36
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-36
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-37
DATAC (Data Item Choices) . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-38
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-38
DATACOL (Data Column) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-39
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-39
DATAGRP (Data Group) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-40
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-41
DATAI (Data Item) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-42
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-45
DATAIX (Data Item Extender) . . . . . . . . . . . . . . . . . . . . . . . . . . . A-47
DATASLT (Data Selection Field) . . . . . . . . . . . . . . . . . . . . . . . . . . A-51
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-52
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-53
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-53
Example 2: Multiple-Selection Field . . . . . . . . . . . . . . . . . . . . . . A-53
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-54
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-54
DATASLTC (Data Selection Field Choice) . . . . . . . . . . . . . . . . . . . . A-55
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-56
DL (Definition List) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-57
Required Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-57
Optional Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-58
Example 1: Definition List . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-58
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-58

Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-58
Example 2: Compact Definition List . . . . . . . . . . . . . . . . . . . . . . A-58
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-58
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-58
FIG (Figure) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-59
Optional Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-59
Example: Sample Figure . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-59
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-59
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-59
HELP (Help Module) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-60
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-61
Example: Help Panel Definition . . . . . . . . . . . . . . . . . . . . . . . . . A-62
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-62
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-62
HP0 through HP9 (Highlighted Phrase) . . . . . . . . . . . . . . . . . . . . . . A-63
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-63
H1 through H4 (Heading) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-65
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-65
Example: Heading Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-65
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-65
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-65
IMHELP (Imbed Help) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-66
Example: Imbedded Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-66
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-66
IMPORT (Import) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-67
INFO (Information Area) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-68
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-68
ISCH (Index Search) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-70
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-70
Example: Index Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-70
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-70
ISCHSUBT (Index Search Subtopic) . . . . . . . . . . . . . . . . . . . . . . . . A-71
Example: Index Search Hierarchy . . . . . . . . . . . . . . . . . . . . . . . A-71
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-71
ISCHSYN (Index Search Synonym) . . . . . . . . . . . . . . . . . . . . . . . . A-72
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-72
Example: Index Search Synonyms . . . . . . . . . . . . . . . . . . . . . . . A-72
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-72
KEYI (Key List Item) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-74
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-75
Part 6. Appendixes
Example: Key Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-75
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-75
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-75
KEYL (Key List) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-76
Example: Key List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-76
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-76
LINES (Unformatted Lines) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-77
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-77
Example: Unformatted Lines . . . . . . . . . . . . . . . . . . . . . . . . . . A-77
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-77
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-77
LINK (Hypertext Link Definition) . . . . . . . . . . . . . . . . . . . . . . . . . . A-78
Conditional Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-79
Bidirectional Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . A-80
Example: Hypertext Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-80
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-80
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-81
LIST (List Area) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-82
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-85
Example 1: List Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-86
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-86
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-87
Example 2: List Area with Three Layout Columns . . . . . . . . . . . . . . A-87
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-87
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-87
Example 3: List Area with List Column Groups . . . . . . . . . . . . . . . . A-87
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-87
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-88
Example 4: Dynamic List Column Heading Formatting . . . . . . . . . . . A-88
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-88
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-89
LISTACT (List Action) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-90
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-94
Confirmation Panel Requirements . . . . . . . . . . . . . . . . . . . . . . . A-94
Confirmation Panel Conventions . . . . . . . . . . . . . . . . . . . . . . . . A-94
Example: List Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-95
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-95
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-95
LISTCOL (List Column) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-96
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-99
Formatting Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-99
LISTDEF (List Definition) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-100

LISTGRP (List Column Group) . . . . . . . . . . . . . . . . . . . . . . . . . . A-103
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-104
Example: List Column Group . . . . . . . . . . . . . . . . . . . . . . . . . A-104
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-104
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-104
LISTVIEW (List View) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-105
LP (List Part) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-107
Example: List Part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-107
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-107
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-107
MBAR (Menu Bar) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-108
Example: Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-108
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-109
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-109
MBARC (Menu Bar Choice) . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-110
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-110
MENU (Menu Area) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-111
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-112
Example 1: Simple Menu Area . . . . . . . . . . . . . . . . . . . . . . . . A-112
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-112
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-112
Example 2: Menu Area with Groups . . . . . . . . . . . . . . . . . . . . . A-112
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-112
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-113
MENUGRP (Menu Group) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-114
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-114
MENUI or MI (Menu Item) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-115
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-116
NT or NOTE (Note) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-117
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-117
Example: Using a Note . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-117
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-117
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-117
OL (Ordered List) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-118
Required Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-119
Example: Ordered List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-119
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-119
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-119
OPTLINE (Option Line) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-120
Part 6. Appendixes
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-120
P (Paragraph) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-121
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-121
Example: Paragraph Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . A-121
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-121
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-121
PANEL (Display Panel) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-122
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-127
Example: Panel Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . A-127
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-127
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-128
PARML (Parameter List) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-129
Required Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-129
Example: Parameter List . . . . . . . . . . . . . . . . . . . . . . . . . . . A-130
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-130
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-130
PC (Paragraph Continuation) . . . . . . . . . . . . . . . . . . . . . . . . . . . A-131
Example: Paragraph Continuation . . . . . . . . . . . . . . . . . . . . . . A-131
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-131
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-131
PDACCEL (Pull-Down Accelerator) . . . . . . . . . . . . . . . . . . . . . . . A-132
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-132
PDFLD (Pull-Down Field) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-133
PDFLDC (Pull-Down Field Choice) . . . . . . . . . . . . . . . . . . . . . . . . A-134
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-136
Confirmation Panel Requirements . . . . . . . . . . . . . . . . . . . . . . A-136
Confirmation Panel Conventions . . . . . . . . . . . . . . . . . . . . . . . A-136
PK (Programming Keyword) . . . . . . . . . . . . . . . . . . . . . . . . . . . A-138
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-138
PNLGRP (Panel Group) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-139
PRTHEAD (Print Head Panel) . . . . . . . . . . . . . . . . . . . . . . . . . . A-142
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-143
Layout of the Title Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-143
Example: Print Title Line . . . . . . . . . . . . . . . . . . . . . . . . . . . A-145
PRTPNL (Print Panel) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-146
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-146
PRTTRAIL (Print Trailer Message) . . . . . . . . . . . . . . . . . . . . . . . . A-148
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-148
Example: Trailer Message . . . . . . . . . . . . . . . . . . . . . . . . . . . A-148
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-148
PV (Programming Variable) . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-149
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-149
RT (Reverse Text) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-150

Example 1: Left-to-Right Formatting on a Right-to-Left Panel . . . . . . A-150
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-150
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-150
Example 2: Left-to-Right Formatting on a Left-to-Right Panel . . . . . . A-151
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-151
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-151
SL (Simple List) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-152
Required Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-152
Example: Simple Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-153
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-153
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-153
TEXT (Text Area) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-154
Cursor positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-155
Text Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-155
Example: Text area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-157
TI (Translation List Item) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-158
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-158
TL (Translation List) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-159
Examples: Translation List . . . . . . . . . . . . . . . . . . . . . . . . . . A-159
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-159
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-160
TOPINST (Top Instruction) . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-161
Optional Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-161
TT (Truth Table) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-162
Example: Truth Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-162
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-162
TTROW (Truth Table Row) . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-163
UL (Unordered List) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-164
Required Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-165
Example: Unordered Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . A-165
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-165
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-165
VAR (Variable Definition) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-166
Dialog Variables Defined by UIM . . . . . . . . . . . . . . . . . . . . . . . A-166
VARRCD (Variable Record Definition) . . . . . . . . . . . . . . . . . . . . . . A-169
XH1 through XH4 (Extended Help Headings) . . . . . . . . . . . . . . . . . A-170
Required Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-170
Formatting Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-170
Example: Sample Headings . . . . . . . . . . . . . . . . . . . . . . . . . . A-170
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-170
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-170
Part 6. Appendixes
XMP (Example) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-171
Example: Formatting an Example . . . . . . . . . . . . . . . . . . . . . . A-171
UIM Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-171
Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-171
Appendix B. UIM Dialog Commands . . . . . . . . . . . . . . . . . . . . . . B-1

The VARUPD Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4
ACTIONS (Menu Bar Cursor Action) . . . . . . . . . . . . . . . . . . . . . . B-4
CALL (Call Program) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4
Required Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-5
CANCEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-6
Optional Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-6
CHGVIEW (Change View) . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-6
CMD (System Command) . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-7
CMDLINE (Command Line) . . . . . . . . . . . . . . . . . . . . . . . . . . . B-7
DSPHELP (Display Help) . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-7
ENTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-8
Considerations for Using the ENTER, HELP, and PROMPT Dialog
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-8
EXIT (Exit Display) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-8
EXTHELP (Extended Help) . . . . . . . . . . . . . . . . . . . . . . . . . . . B-9
HELP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-9
HELPHELP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-9
HELPIDX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-9
HOME (Display Home Menu) . . . . . . . . . . . . . . . . . . . . . . . . . . B-9
KEYSHELP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-10
MENU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-10
MOREKEYS (Display More Function Keys) . . . . . . . . . . . . . . . . . . B-10
MOVETOP (Move to Top) . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-11
MSG (Display Message) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-11
PAGEDOWN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-11
PAGEUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-12
PRINT (Print Display) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-12
PROMPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-13
Prompting an Entry Field . . . . . . . . . . . . . . . . . . . . . . . . . . . B-13
Prompting an Action List Option or Command . . . . . . . . . . . . . . . B-13
PULLDOWN (Display Pull-Down Menu) . . . . . . . . . . . . . . . . . . . . B-14
RETRIEVE (Retrieve Command String) . . . . . . . . . . . . . . . . . . . . B-14
RETURN (Return Control to Application) . . . . . . . . . . . . . . . . . . . B-14
Appendix C. Feedback Area Layouts for Display Files . . . . . . . . . . . C-1

Open Feedback Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1
Device Definition List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-4
I/O Feedback Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-6
Common I/O Feedback Area . . . . . . . . . . . . . . . . . . . . . . . . . . C-6
I/O Feedback Area for Display Files . . . . . . . . . . . . . . . . . . . . . . C-9

Get Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-12
Appendix D. Double-Byte Character Set Support for Displays . . . . . . D-1

Double-Byte Character Set Fundamentals . . . . . . . . . . . . . . . . . . . . D-1
DBCS Code Scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-1
Shift-Control Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-3
Using Double-Byte Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-3
How You Can Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-3
How You Cannot Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-4
Double-Byte Character Size . . . . . . . . . . . . . . . . . . . . . . . . . . . D-4
Processing Double-Byte Characters . . . . . . . . . . . . . . . . . . . . . . . . D-4
Basic Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-4
Extended Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-4
What Happens When Extended Characters Are Not Processed . . . . . . D-4
Device File Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-5
What a DBCS File Is . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-5
When to Indicate a DBCS File . . . . . . . . . . . . . . . . . . . . . . . . . . D-5
How to Indicate a DBCS File . . . . . . . . . . . . . . . . . . . . . . . . . . D-5
Improperly Indicated DBCS Files . . . . . . . . . . . . . . . . . . . . . . . . D-6
Display Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-6
Inserting Shift-Control Characters . . . . . . . . . . . . . . . . . . . . . . . . D-6
Number of Displayed Extended Characters . . . . . . . . . . . . . . . . . . D-6
Number of Input Fields on a Display . . . . . . . . . . . . . . . . . . . . . . D-6
Effects of Displaying Double-Byte Data at Alphanumeric Work Stations . . D-7
Effects of Displaying DBCS-Graphic Fields on Double-Byte Displays . . . D-7
Application Program Considerations . . . . . . . . . . . . . . . . . . . . . . . . D-7
Designing Application Programs That Process Double-Byte Data . . . . . D-7
Changing Alphanumeric Application Programs to DBCS Application
Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-8
DBCS Font Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-8
Finding Out if a DBCS Font Table Exists . . . . . . . . . . . . . . . . . . . D-8
Copying a DBCS Font Table onto Tape or Diskette . . . . . . . . . . . . . D-9
How to Copy a Table onto Tape or Diskette . . . . . . . . . . . . . . . . D-9
Copying a DBCS Font Table from Tape or Diskette . . . . . . . . . . . . . D-9
How to Copy a Table from a Tape or Diskette . . . . . . . . . . . . . . . D-9
Deleting a DBCS Font Table . . . . . . . . . . . . . . . . . . . . . . . . . . D-10
How to Delete a DBCS Font Table . . . . . . . . . . . . . . . . . . . . . D-10
Starting the Character Generator Utility . . . . . . . . . . . . . . . . . . . . D-10
Copying User-Defined Double-Byte Characters . . . . . . . . . . . . . . . . D-10
DBCS Font Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-10
DBCS Sort Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-11
Using DBCS Sort Tables on the System . . . . . . . . . . . . . . . . . . . . D-12
Finding Out if a DBCS Sort Table Exists . . . . . . . . . . . . . . . . . . . . D-12
Saving a DBCS Sort Table onto Tape or Diskette . . . . . . . . . . . . . . D-12
When to Save a DBCS Sort Table onto Tape or Diskette . . . . . . . . D-12
Restoring a DBCS Sort Table from Tape or Diskette . . . . . . . . . . . . . D-12
Copying a Japanese DBCS Master Sort Table to a Data File . . . . . . . . D-12
When to Copy the Japanese DBCS Master Sort Table to a Data File . D-12
How to Copy the Japanese DBCS Master Sort Table to a Data File . . D-13
Copying a Japanese DBCS Master Sort Table from a Data File . . . . . . D-13
When to Copy the Japanese DBCS Master Sort Table from a Data File D-13
How to Copy the Japanese DBCS Master Sort Table from a Data File D-13
Deleting a DBCS Sort Table . . . . . . . . . . . . . . . . . . . . . . . . . . . D-14
When to Delete a DBCS Sort Table . . . . . . . . . . . . . . . . . . . . . D-14
Part 6. Appendixes
How to Delete a DBCS Sort Table . . . . . . . . . . . . . . . . . . . . . . D-14
DBCS Conversion Dictionaries . . . . . . . . . . . . . . . . . . . . . . . . . . . D-14
System-Supplied Dictionary (for Japanese Use Only) . . . . . . . . . . . . D-14
User-Created Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-15
Commands for DBCS Conversion Dictionaries . . . . . . . . . . . . . . . . D-15
Creating a DBCS Conversion Dictionary . . . . . . . . . . . . . . . . . . D-15
Editing a DBCS Conversion Dictionary . . . . . . . . . . . . . . . . . . . D-16
Displaying and Printing the DBCS Conversion Dictionary . . . . . . . . . . D-19
Deleting a DBCS Conversion Dictionary . . . . . . . . . . . . . . . . . . . . D-19
DBCS Conversion (for Japanese Use Only) . . . . . . . . . . . . . . . . . . . D-19
Where You Can Use DBCS Conversion . . . . . . . . . . . . . . . . . . . . D-20
How DBCS Conversion Works . . . . . . . . . . . . . . . . . . . . . . . . . D-20
Using DBCS Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-20
Performing DBCS Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . D-21
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D-22
Considerations for Using DBCS Conversion . . . . . . . . . . . . . . . . D-25
Appendix E. Display File Return Codes . . . . . . . . . . . . . . . . . . . . E-1

Major Code 00 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1
Major Code 02 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-1
Major Code 03 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2
Major Code 04 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-2
Major Codes 08–11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3
Major Code 34 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3
Major Code 80 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-3
Major Code 81 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-5
Major Code 82 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-6
Major Code 83 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . E-10
Appendix F. Edit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-1

OS/400 Edit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-1
Examples of Editing Using OS/400 Edit Codes . . . . . . . . . . . . . . . . . F-3
User-Defined Edit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-4
Using User-Defined Edit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . F-5
Example of a User-Defined Edit Code . . . . . . . . . . . . . . . . . . . . . . F-5
Appendix G. System/36-Compatible Display Data Management . . . . . G-1

Clearing Lines on the Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-1
Input Data for Display File Records . . . . . . . . . . . . . . . . . . . . . . . . G-2
Input Data from the Work Station Controller . . . . . . . . . . . . . . . . . . . G-2
Self-Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-2
Return Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-3
Erase Input Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-3
Display Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-3
Positioning the Cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-4
Displaying Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-4
Put Override . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-6
Handling Signed Numeric Data . . . . . . . . . . . . . . . . . . . . . . . . . . . G-7
Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-7
Help Key Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-7
Using Command Keys to Exit Application Help . . . . . . . . . . . . . . . . . G-8
Cancel-Invite Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . G-8
Retain Command and Function Keys . . . . . . . . . . . . . . . . . . . . . . . G-9
System/36 Functions Not Supported . . . . . . . . . . . . . . . . . . . . . . . . G-10

Restricted DDS Keywords/Functions . . . . . . . . . . . . . . . . . . . . . . . . G-10
Part 6. Appendixes
Tag Language
Appendix A. UIM Panel Group Definition Language
This appendix describes the UIM panel group defi- actual statements of the language, the tags, are
nition language. Following some introductory defined. The tag definitions in this chapter are
material on the nature of the language syntax and organized alphabetically.
the structure of the panel group definitions, the
A sample syntax diagram is shown below:
55──:TAGNAME──VATTR=value──┬─────────────────────┬──.──┬─────────────┬──────────────────5%
│ ┌─DEFAULT─┐ │ └─tag-content─┘
└─KATTR=─┼─VALUE1──┼──┘
└─VALUE2──┘
The TAGNAME specifies the name of the tag. appropriate during the compile process. For
This sample tag has two attributes: VATTR, for example, the following uses of the example tag,
value attribute; and KATTR, for keyword attribute. TAGNAME, are equivalent specifications:
The second attribute in this example is shown on :TAGNAME VATTR=VALUE.
the alternate branch to indicate that it is an :tagname vattr=value.
optional attribute. This attribute can have one of :Tagname Vattr=Value.
three values: DEFAULT, VALUE1, and VALUE2.
Tag attributes do not need to be specified in the
DEFAULT is the value used when you do not order specified in the syntax diagram. For
specify a value for the KATTR attribute. If there is a example, the following uses of the example tag,
default value, it appears on the group choice line TAGNAME, are equivalent specifications:
above the attribute name, as DEFAULT appears
:tagname vattr=value kattr=value1.
on the line above the KATTR attribute name.
:tagname kattr=value1 vattr=value.
Instead of using the DEFAULT value, you may
choose either VALUE1 or VALUE2. These values Sometimes it is necessary to continue the attribute
are entered as shown in the syntax diagram. of a tag to another source line. However, not all
attributes can be continued. The attributes in the
The value is a value you enter, as specified for
following table are the only ones that can be con-
that attribute. An attribute value must be enclosed
tinued.
with apostrophes (') when it contains characters
other than A through Z or 0 through 9, and it must Table A-1 (Page 1 of 2). Tag Attributes That Can Be
be contained on one source line. To enter an Continued
apostrophe in a value surrounded by apostrophes,
Attribute Tag
type the apostrophe twice.
ACTION KEYI
The tag-content is text associated with that tag ACTION MENUI
that may be displayed or printed for the user. It is ACTION PDFLDC
COLHEAD LISTCOL
designed to allow national language translation.
COLS LISTVIEW
CONDS TT
The period at the end of the tag and before the
EMPHASIS LISTDEF
tag content is known as the markup/content sep- ENTER LISTACT
arator. This separator is required for all tag ENTER PANEL
markup. EXPR COND
EXTENTER LISTACT
The source for a panel group can be entered in EXTPROMPT LISTACT
either lowercase, uppercase, or mixed case char- LINKWHEN LINK
acters. The UIM converts the tag names, attribute NOGET VARRCD
names, and attribute values to uppercase as NOPUT VARRCD
 Copyright IBM Corp. 1997 A-1

Tag Language
Table A-1 (Page 2 of 2). Tag Attributes That Can Be This is the first sentence. This is the
Continued second! This is the third.
Attribute Tag There are two spaces between the first and
PERFORM LINK second sentences. There are three spaces
PROMPT LISTACT between the second and third sentences.
PROTECT LISTDEF
RANGE CHECK Because the CPI6AB9 message affects the
REL CHECK amount of space that follows the end of a source
ROOTS ISCH line, if the CPI6AB9 message is changed to xxx,
TOPICS ISCHSUBT there will be three spaces between each sentence
UNLESSn LINK
in the previous example.
VALUES CHECK
VALUES TTROW Note: The CPI6AB9 message should already be
VARS LISTDEF translated to the proper number of x's for your
VARS VARRCD country.
To continue an attribute, repeat the attribute on Panel Areas: The five types of panel areas
the next source line, as in the following example: are menu, information, data, list, and text areas.
:TAGNAME A mixed panel is constructed by using two or
VATTR='value1 value2 value3' more of these areas within the same panel.
VATTR='value4 value5 value6'
VATTR='value7 value8 value9'. The restrictions associated with mixed panels are
tag-content listed in Table A-2.
A maximum of fifty attribute names can be speci- Table A-2. Restrictions Associated With Mixed Panels
fied for any tag, including each repeated attribute Menu Info Data Non- Action Text
name. Action List
List
Tag Content Formatted as Menu No Yes Yes Yes No No
Paragraphs: The period (.), question mark Info Yes Yes Yes Yes Yes No
(?), and exclamation point (!) are sentence-ending
Data Yes Yes Yes Yes Yes No
characters. Depending on the national language
requirements, one or more blanks are placed after Non- Yes Yes Yes Yes Yes No
each of the sentence-ending characters that end a Action
UIM source line when the panel group or menu List
object is created. The number of blanks can be Action No Yes Yes Yes No No
from one to six, and is specified in the message List
text of the CPI6AB9 message in the message file Text No No No No No No
QCPFMSG.
All of these area types can be scrolled. Scrolling,
The following example shows how the CPI6AB9
as well as presentation of the appropriate scroll
message works.
location information, is handled by the UIM for
:p.This is the first sentence. menu, information, data, and list areas. Scrolling
This is the second! This is the third. for text areas is handled by the text area user exit
program.
In this example, :p. is the tag name. The :p. tag
does not require attributes. There are three
spaces between the second sentence and the Panels: A panel is made up of one or more
third sentence because of national language panel areas, each of which has a specific layout
requirements. If the CPI6AB9 message is set to and function. Specific panels are usually categor-
xx, this paragraph appears this way to the UIM ized according to the nature of their application
after it is compiled: areas, such as information panels, menu panels,
list panels, and text panels.
A-2 Application Display Programming V4R1

Tag Language
Panel Group Objects: A panel group is a Help on Panels: Help for a panel is con-
logical grouping of panels that can correspond to structed from help modules referred to in the
a software product, a command, or a related col- panel definition. Extended help for a panel is a
lection of commands or other services. It can concatenation of the help for the panel, the menu
contain panels of any type. Panel groups provide bar, items in all areas in the order of their defi-
a context for names of panels, variables, list definitions, and function keys in the order of their defi-
nitions, and help modules. nitions.
Appendix A. UIM Panel Group Definition Language A-3

Tag Language
Panel Group Organization UIM Menu Outline

Panel Group (PNLGRP)
The following list shows the required order of tags
in the UIM source for panel groups and menus. Prolog section
Copyright statement (COPYR)
Panel Group Outline Import statements (IMPORT)
Variable definitions (VAR)
Panel Group (PNLGRP)
Condition definitions (COND)
Prolog section Truth table definitions (TT)
Copyright statement (COPYR) Menu Bar (MBAR)
Import statements (IMPORT) Key list definitions (KEYL)
Class definitions (CLASS) Body section
Variable definitions (VAR) Panel definitions (PANEL)2
Variable Record Definitions (VARRCD) – Area definitions (MENU, INFO,
List definitions (LISTDEF) DATA)
Condition definitions (COND) – Command and option line defi-
Truth table definitions (TT) nitions (CMDLINE, OPTLINE)
Menu bar definitions (MBAR) Help module definitions (HELP)2
Key list definitions (KEYL)
Body section
Display panel definitions (PANEL)1 Name Syntax
– Area definitions (MENU, INFO,
DATA, LIST, TEXT) There are several elements, identified with tags,
– Command and option line defi- within a panel group that can be named so that
nitions (CMDLINE, OPTLINE) they can be referred to from other elements within
Print head panel definitions that panel group, such as classes, dialog vari-
(PRTHEAD)1 ables, lists, and conditions. The application
– Area definitions (INFO, DATA) program can also refer to named elements by
– Print trailer message (PRTTRAIL) passing the name to the UIM as a parameter on
Print panel definitions (PRTPNL)1 an application programming interface (API) call.
– Area definitions (INFO, DATA, These elements have a NAME attribute on the tags
LIST) that define them. These names may be up to 10
Help module definitions (HELP)1 characters long and can contain only the charac-
ters A through Z and 0 through 9. The first char-
acter of a name must be an A through Z
A UIM menu, created with the Create Menu character.
(CRTMNU) command, is a special form of panel
group. These menus are limited to the following Names of help modules defined by the HELP tag
panel group tags: can be up to 32 characters long and are defined
in the same name space as other elements. As a
result, a help module and another element cannot
have the same name in a panel group. They can
contain the characters A through Z, 0 through 9,
slash (/), and underscore (_). If the name con-
tains a slash or an underscore, it must be
enclosed between apostrophes. The first char-
acter of a help name must be an A through Z
character, a slash, or an underscore.
1 PANEL, PRTHEAD, PRTPNL, and HELP tags can be used in any order.
2 The PANEL and HELP tags can be used in any order.

Tag Language
Because all names are stored in the panel group When the &cont. symbol is used to
object in uppercase format, lowercase alphabetic continue the two parts of a double-byte
characters (a through z) are converted to upper- character set (DBCS) word, both the
case alphabetic characters (A through Z). When ending shift-in character of the first line
the name of an element is passed to the UIM and the starting shift-out character of
through an application program interface, the the second line are discarded.
name must be passed in uppercase characters.
The &cont. symbol is useful with a
figure, a line, or an example. The
Because these names stay within the panel group
symbol can be used when a CIT, HPn,
and reside in the same name space, a dialog vari-
or LINK tag would cause the resulting
able and a UIM list cannot have the same name.
source line to be longer than the length
There is an occasional need to refer to object of the source record.
names in the panel group source. These names Here is an example of how to use the
must obey the rules for OS/400 object names. &cont. symbol.
They must be enclosed between apostrophes
:LINES.
when they contain characters other than A through Text to be continued &cont.
Z and 0 through 9. :LINK perform='dsphelp hyper'
linkwhen='chkusrcls("\PGMR")'.&cont.
Symbols reference phrase&cont.
:ELINK.&cont.
A symbol is a name that can be replaced with more text on line.
something else while the panel group is compiling. :ELINES.
All symbols use an ampersand (&), followed by
55──&cont.───────────────────────5%
the symbol name, followed by a period. Symbols
must appear in the text following the period of a &msg(msgid,msgf,lib).
tag. The compiler extracts the first-level
message text for the message MSGID
Symbols can be entered in either uppercase or
from the message file MSGF in library
lowercase.
LIB and substitutes the text in place of
this symbol. The message text is
The following symbols are defined by the UIM:
retrieved in the CCSID of the panel
&amp. Creates an ampersand (&) without trig- group source file without any substi-
gering symbol processing. This symbol tution variables.
is used when an ampersand is needed
The message file defaults to the
in the text of a tag. If this symbol is
message file specified on the SUBMSGF
not used, the UIM replaces the symbol
attribute of the PNLGRP tag. If
name with its actual value.
SUBMSGF is not specified, the message
55──&amp.────────────────────────5% file must be specified in the symbol.
&colon. Creates a colon (:) without triggering 55──&msg(msgid────────────────────5

tag processing. This symbol is used 5──┬─────────────────┬──).───────5%
when a colon is needed in the text of a └─,msgf─┬──────┬──┘
└─,lib─┘
tag.
55──&colon.──────────────────────5% &period. Creates a period (.) in the text. This
symbol is used when a period is
&cont. Forces the concatenation of the next needed in column one of the text
source line with the current source line. without triggering control word pro-
Concatenation occurs only when the cessing.
symbol is the last character in a source
55──&period.─────────────────────5%
line. No visible symbol is created for
the &cont. symbol.

Tag Language
&slr. Creates a right slash (/) in the text. DBCS Graphic Literals
This symbol is used if a right slash is
needed in column one of the tag DBCS graphic literals are supported by the UIM to
source. If this symbol is not used, right support processing of strings of literal characters
slashes in column one of the source of DBCS graphic data. The syntax of the literals
file can cause problems if the source follows:
file is part of the input stream for a
┌──
─────┐
batch job. (1) 6
55──"shift-out── (2)
───D─── (3)
┴─shift-in── "──g────5%
55──&slr.────────────────────────5%
Notes:
1 Shift-out is X'0E'
2 D is one DBCS character
Comments 3 Shift-in is X'0F'
In addition to markup done with tags, comments

The value must be enclosed in apostrophes
can also be inserted into the source of the panel
because it contains special characters.
group. Typically, comments are used to describe
the content of the file, or to give information as to All strings of literal characters coded on UIM tags
the structure, format, date, author, and so on. that are compared against a DBCS graphic field
must be in the form of DBCS graphic literals. The
Comments begin with a period followed by an
shift-out and shift-in characters are removed from
asterisk (.*). They must be used in columns one
the graphic strings before the comparison is per-
and two of the source record. They are ignored
formed.
by the compiler, but are listed in the source listing.
They are not preserved in the panel group object. Caution should be used when literals are com-
An example using comments follows: pared to input-capable graphic fields. You must
.\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ realize that on a nongraphic DBCS device, there
.\ panel group xxx.xxx are two fewer bytes available for input. As a
.\ author X. X. Xxxxxxx result, you should always use literals that are two
.\ change history 9/18/92 (xxx) Created bytes less than the maximum length of the entry
.\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ field of the DBCS graphic variable.
:pnlgrp ...
..
. When DBCS graphic characters are used after the
:epnlgrp. period of a tag, (such as on the translation list
item (TI) tag) a graphic literal should not be used.
Imbeds What should be used is everything between and
not including the quotation marks in the diagram
Source from other files can be brought into a above.
panel group at the time the panel group is com-
piled. This allows you to create a panel group or
Hexadecimal Literals
menu from multiple source file members. Imbeds
are done with the .IM control word. An example Hexadecimal data can be entered in attributes
using imbeds follows: wherever a character string literal is allowed. The
.im member1 syntax of hexadecimal literals follows:
The member (member1) in the file named in the ┌──
──────┐
include file (INCFILE) parameter on the Create 55──"──6─xx───
(1)
┴─"──x────────────────────────5%
Panel Group (CRTPNLGRP) or Create Menu Note:
1 xx is a pair of hexadecimal digits (0 through 9, a
(CRTMNU) command is opened and processed as
if it appeared in the original source file. Imbeds through f, or A through F)
can be nested up to 10 deep; attempting to nest
deeper than 10 results in an error and the panel
The following example shows how to code a
group or menu object is not created.
hexadecimal value for a translation item.

Tag Language
:TI value='"ð1"x'.\YES The value must be enclosed in apostrophes

:TI value='"ð2"x'.\NO because it contains special characters.

APPFMT tag
APPFMT (Application Formatted Area)
55──:APPFMT──VAR=dialog-variable-name──WIDTH=area-width──DEPTH=area-depth────────────────5
5──┬──────────────────────────────────┬──.──────────────────────────────────────────────5%
└─USREXIT='CALL program-reference'─┘
The application formatted area (APPFMT) tag is variable using a class definition (CLASS) tag
an optional tag which defines an area in the upper with a BASETYPE of CHAR x, where x equals
right corner of a menu area to be formatted by the the product of the area width times the area
application. Only one APPFMT tag can be speci- depth.
fied in each menu area. It must immediately
You can use the exit program for application
follow the menu area (MENU) and top instruction
formatted data, specified on the USREXIT attri-
(TOPINST) tags.
bute of this tag, to update this dialog variable
each time the panel is displayed. The UIM
The application formatted area is part of the menu
uses the value of the dialog variable as the
area, appearing at the right edge of the menu
application formatted data, described in “Appli-
area and ending one character position before the
cation Formatted Data” on page A-9.
right edge of the panel. The width is determined
by the WIDTH attribute of this tag. The application WIDTH=area-width
formatted area extends from the blank line fol- The width, in characters, for the application
lowing the top instruction lines of the menu area to formatted area associated with the menu area.
the number of lines defined in the DEPTH attribute The width specified must be an integer in the
of this tag. A two-byte separator is maintained range of 1 to 40, or the panel width minus 17,
between the menu item descriptions and the appli- whichever is less.
cation formatted area.
DEPTH=area-depth
If the depth of the application formatted area is The depth, in lines, of the application for-
less than the depth of the menu area, the area matted area. This depth must be no greater
below the application formatted area and to the than the number of lines available for the body
right of the menu area is blank. The depth of the of the menu. The body of the menu is the
application formatted area may not be greater area between and excluding the top instruc-
than the depth of the menu area. tion line and the bottom instruction line or
bottom separator.
If the menu area is scrollable, the scroll indicators
appear to the left of the separator between the Optional Attribute
menu area and the application formatted area.
You cannot scroll the application formatted area, USREXIT='CALL program-reference'
even if you can scroll the menu area. The exit program for application formatted
data, called to update the value of the dialog
The application formatted data is described in variable containing the application formatted
“Application Formatted Data” on page A-9. data each time the panel is displayed.
For a description of the CALL dialog
Extended help for the panel is displayed if the
command, see Appendix B, “UIM Dialog
Help key is pressed while the cursor is in the
Commands” on page B-1.
application formatted area.
For a description of the interface between the
Required Attributes UIM and the exit program for application for-
matted data, see the System API Reference.
VAR=dialog-variable-name
The name of the dialog variable containing the
application formatted area. Define the dialog

APPFMT tag
Application Formatted Data through X'FE' (normal, displayable characters),

are passed unchanged to the screen.
The dialog variable containing the application for-
matted data is specified on the VAR attribute of The UIM inserts a normal text attribute before
this tag. The contents of this variable is viewed each line of the application formatted area and a
by the UIM as a d by w array of characters, where field-ending attribute after each line of the applica-
d is the depth and w is the width of the application tion formatted area. This effectively isolates the
formatted area. Each row of the array is dis- application formatted area from the rest of the
played as one line of the application formatted panel with respect to highlighting attributes.
area.
No character set and code page conversion is
Any character within the data can be a selection done on the application formatted data. If conver-
character for a highlighting class. Only output and sion is necessary, it must be done by the applica-
text classes are allowed in an application for- tion.
matted area; no input fields are allowed. The
When the UIM calls the exit program to format the
class selection applies to the following characters
application area of a menu, it passes a value
up to another class selection character or the end
which identifies the BIDI attribute on the panel
of the row, whichever occurs first. The UIM sets
group (PNLGRP) tag and the code page number
the highlighting class to normal text at the begin-
of the display device.
ning of each row of the area.
The NBRSHAPE and SYMSWAP attributes of the
The selection characters for highlighting are in the
CLASS tag used for the application formatted area
range of X'01' through X'06'. The following
are determined from the class of the dialog vari-
selection characters for highlighting are recog-
able containing the application formatted data.
nized by the UIM:
X'01' Normal variable output
X'02' De-emphasized variable output
Example: Application Formatted
X'03' Emphasized variable output Area
X'04' Normal text
X'05' De-emphasized text à OfficeVision/4ðð
ð
X'06' Emphasized text Select one of the following:
System: SYSNAMXX
1. Calendars Time: 9:ð9

2. Mail
The UIM replaces each class selection character 3.
4.
Send message
Send note
February
S M T W T
1992
F S
with the appropriate display attributes for the 5.
6.
Documents and folders
Word processing 2 3 4 5 6 7 8
1
7. Directories/distribution lists 9 1ð 11 12 13 14 15
class. Other character values in the ranges X'01' 8. Decision support 16 17 18 19 2ð 21 22
9. Administration 23 24 25 26 27 28 29
through X'06', and X'10' through X'3F', as well 9ð. Sign off
as X'FF', are converted to X'1F', appearing as a
Bottom
reverse image box on the screen. Characters Press ATTN to suspend a selected option.
Selection
X'00' (null), X'0E' (shift-out for double-byte),
X'0F' (shift-in for double-byte), and X'40' F3=Exit F12=Cancel F19=Display messages
(C) COPYRIGHT IBM CORP. 1985, 1991.
á ñ

BOTINST Tag
BOTINST (Bottom Instruction)
55──:BOTINST──┬───────────────────────────┬──.──┬──────────────────┬────────────────────5%
└─INST=dialog-variable-name─┘ └─instruction-text─┘
The bottom instruction (BOTINST) tag specifies is used, no instruction-text can be specified for
the bottom instruction lines for an area of the this tag.
panel. This tag appears immediately before the
Dialog variables must be defined with a
ending tag for the area. You can use multiple
BASETYPE of CHAR, IGC, or BIN on the class
bottom instruction tags to present multiple instruc-
definition (CLASS) tag.
tion lines if the tag contains instruction text after
the period. If multiple tags are coded, no blank The error state of the dialog variable is not
lines appear between the text on different tags. used for determining the highlighting of the
Only one bottom instruction tag is allowed per text.
area if the INST attribute is used on this tag. Special formatting for IGC. (The abbrevi-
ation IGC is used in commands and keywords
If you do not specify a BOTINST tag for an area,
to represent double-byte character set func-
no instruction line is allocated for the area.
tions.) When a dialog variable with a
BASETYPE of IGC is specified on the CLASS
For menus and information areas, a blank line is
tag, the UIM does special formatting. If the
always left between the body of the area and the
dialog variable value begins with a shift-out
instruction lines. If you can scroll the area, a
character (X'0E'), the UIM shifts the value
blank line is reserved for the scroll information
one byte to the left to preserve vertical align-
between the body of the area and the bottom
ment with other lines.
instruction. For information about how instruction
lines are formatted with respect to the body of
data and list areas, see the BODYSEP attribute in Optional Text
“DATA (Data Presentation Area)” on page A-31
instruction-text
and “LIST (List Area)” on page A-82.
The text appearing as bottom instructions for
the area. The text is an implied paragraph.
Optional Attribute When the display is formatted, any text that
does not fit onto one display line is formatted
INST=dialog-variable-name
on multiple lines as necessary and indented
The name of a dialog variable that contains
two display positions. The text can be a
the bottom instruction text to be displayed.
maximum of 255 characters, and can contain
The dialog variable must be defined with a
only the reverse text (RT) tag. The instruction
width less than or equal to the width specified
text is required unless the INST attribute is
on the panel tag minus 2. If the INST attribute
specified on this tag.

CHECK Tag
CHECK (Validity Checking)
55──:CHECK──MSGID=message-identifier──┬────────────────────────────────────┬─────────────5
└─MSGF='qualified-message-file-name'─┘
5──┬─────────────────────────────┬──┬─────────────────────────┬──────────────────────────5
│ ┌──
───────────────┐ │ │ ┌──
─────────────┐ │
└─RANGE='──6─value1 value2─┴─'─┘ └─REL='──6─relop value─┴─'─┘
5──┬──────────────────────┬──.──────────────────────────────────────────────────────────5%
│ ┌──
───────┐ │
└─VALUES='──6─value─┴─'─┘
The validity checking (CHECK) tag is used within the DFTMSGF attribute is not specified on the
a class definition to specify validity checks associ- panel group (PNLGRP) tag, this attribute must
ated with variables of that class. be specified.
Validity checking occurs on input of the variable RANGE='value1 value2'

value and after translation list processing. If a A range check is valid for both character and
translation list is specified for this class and can numeric types. The check passes if the value
be applied to an input value, no validity checking entered by the user is greater than or equal to
is performed on the translated input value. If the value1 and less than or equal to value2. This
translation list is not applicable and indicates no attribute can be specified more than once.
error, the validity checks defined by this tag are Each value must be numeric or character to
applied to the input value. For more information match the BASETYPE of the variable as speci-
on using the CHECK tag with translation lists, see fied on the class definition (CLASS) tag, and
“TI (Translation List Item)” on page A-158 and “TL cannot be a dialog variable. All character
(Translation List)” on page A-159. values must be enclosed in quotation marks.
At least one RANGE, REL, or VALUE attribute of this REL='relop value'

tag must be coded. If more than one validity A relational check is valid for both numeric
check is coded on the tag, the value must pass and character types. This attribute can be
only one of the check attributes to be accepted for specified more than once.
this check. If more than one CHECK tag is used, Each value must be numeric or character to
a value must pass all the check tags to be match the BASETYPE of the variable as speci-
accepted. Operations from multiple attributes are fied on the CLASS tag, and cannot be a
ORed together. dialog variable. All character values must be
enclosed in quotation marks.
Required Attribute Relational operators are listed below. All
MSGID=message-identifier operators are valid for both character and
The message identifier of the error message numeric types. The check is affected by the
displayed to the user if a validity check fails. CASE and BLANKS attributes of the CLASS tag.
The message should have no substitution var-
= Equal. The check passes if the value
iables defined, because the UIM does not
entered by the user is equal to this literal
supply replacement text when the message is
value.
sent.
¬= Not equal. The check passes if the
value entered by the user is not equal to
Optional Attributes this literal value.
MSGF='qualified-message-file-name'. > Greater than. The check passes if the
The message file that contains the message value entered by the user is greater than
specified on the MSGID attribute of this tag. If this literal value.

CHECK Tag
< Less than. The check passes if the attributes of the CLASS tag. The VALUES attri-
value entered by the user is less than bute can be specified more than once, and up
this literal value. to 50 values can be specified for this tag.
>= Greater than or equal. The check Each value must be numeric or character to
passes if the value entered by the user is match the BASETYPE of the variable as speci-
greater than or equal to this literal value. fied on the CLASS tag, and cannot be a
dialog variable. The values in the list are sep-
<= Less than or equal. The check passes
arated by blanks. All character values must
if the value entered by the user is less
be enclosed in quotation marks.
than or equal to this literal value.
The relational operator may be specified as =, Example: Validity Checking

¬=, >, <, >=, or <=, if the code page of the
source maps the not character (¬) to X'5F'.
Otherwise, it is suggested that the special
UIM Source
values *EQ, *NE, *GT, *LT, *GE, or *LE be :CHECK RANGE='1 1ð' REL='= 99' MSGID=USRð234.
used, respectively, for the relational operator. :CHECK REL='< 5' REL='> 1ð' MSGID=USR1234.
:CHECK VALUES='"\YES" "\NO"'
VALUES='value1 value2 ... value-n' MSGID=MMMððð1 MSGF=USRMSGF.
A values check is valid for both character and
The range check allows values 1 through 10, or
numeric types. The check passes if the value
99, for any variables of the class to which it
entered by the user is equal to one of the
applies. The relational check allows values less
values in the list. Checking on character
than 5 or greater than 10. The values check
values is affected by the CASE and BLANKS
accepts two special values.

CIT Tag
CIT (Title Citation)
55──:CIT.─┬────────────┬─:ECIT.─────────────────────────────────────────────────────────5%
└─title-text─┘
The title citation (CIT) tag identifies the title of a Optional Text
publication and requires a matching end tag. This
tag is only allowed in information areas and help title-text
areas. Title citations are underscored for online Although the title to be cited is not required,
and printed text, and can occur anywhere in the the tag has no meaning when no title is speci-
text. fied.
The CIT and ECIT tags must be specified on word Example: Title Citations
boundaries. If the two characters immediately fol-
lowing the ECIT tag are a punctuation mark and a
UIM Source
blank, the UIM extends the emphasis attribute to
include the punctuation mark. This allows the :P.For more information about the UIM,
punctuation mark and the title to be displayed see the :cit.Application Display Programming:ecit. book.
using the same emphasis.
Results
For more information about the UIM,

see the Application Display Programming book.

CLASS Tag
CLASS (Class Definition)

.
55──:CLASS──NAME=class-name──BASETYPE=─┬─'CHAR n'───────────────────────┬────────────────5
├─'IGC n─┬──────────────┬─'──────┤
│ └──┬─OPEN───┬──┘ │
│ └─EITHER─┘ │
├─'GRAPHIC w c'──────────────────┤
├─'NAME n─┬───────────────┬─'────┤
│ └──┬─SIMPLE──┬──┘ │
│ └─GENERIC─┘ │
├─'OBJNAME n─┬───────────────┬─'─┤
│ └──┬─SIMPLE──┬──┘ │
│ ├─GENERIC─┤ │
│ └─POSTO───┘ │
├─'BIN b'────────────────────────┤
├─'PACKED t f'───────────────────┤
├─'ZONED t f'────────────────────┤
├─'PTR'──────────────────────────┤
├─'DATE'─────────────────────────┤
├─'TIME'─────────────────────────┤
└─'ACTION'───────────────────────┘
5──┬─────────────────────┬──┬────────────────────┬──┬───────────────────┬────────────────5
└─WIDTH=display-width─┘ └─CHRID=─┬─NONE───┬──┘ └─SHIFT=─┬─NONE──┬──┘
└─PNLGRP─┘ └─UPPER─┘
5──┬──────────────────┬──┬──────────────────────┬──┬─────────────────────┬───────────────5
└─CASE=─┬─MIXED─┬──┘ └─BLANKS=─┬─RESPECT─┬──┘ └─SUBST=─┬─DISPLAY─┬──┘
└─UPPER─┘ └─IGNORE──┘ └─QUOTED──┘
5──┬───────────────────┬──┬─────────────────────┬──┬───────────────────────┬─────────────5
└─BIDI=─┬─PNLGRP─┬──┘ └─CONTXTREV=─┬─NO──┬──┘ └─NBRSHAPE=─┬─PNLGRP─┬──┘
├─LTR────┤ └─YES─┘ ├─ARABIC─┤
└─RTL────┘ └─HINDI──┘
5──┬───────────────────┬──.──:ECLASS.───────────────────────────────────────────────────5%
└─SYMSWAP=─┬─NO──┬──┘
└─YES─┘
The class definition (CLASS) tag defines variable order number. For example, a tag with an order
types in variable pools and on panels. Attributes number of three cannot precede a tag with an
of the CLASS tag define the data type for the order number of one or two.
class of the dialog variable and the validity
checking necessary for all variables of that class. Table A-3. Tags Allowed Between the CLASS and
The attributes of this tag also determine the ECLASS Tag
methods for mapping an internal dialog variable of Tag Name Order Page
a particular class to or from a displayed form. TL 1 A-159
(Translation list)
Other tags can be nested within the CLASS tag.
These tags are listed in the following table. The CHECK 2 A-11
(Validity checking)
table defines the order in which the tags must
appear and specifies on which page more infor-
mation can be found about each tag. Required Attributes
When more than one tag is listed with the same NAME=class-name
order number, all tags of that number can be The name assigned to the class. For more
mixed in any order. However, a tag with a higher information on the rules for naming, see
order number cannot precede a tag with a lower “Name Syntax” on page A-4.

CLASS Tag
BASETYPE only contain a CCSID using the UCS-2

The base data type for variables in the class. encoding scheme.
The BASETYPE for a class determines the
The contents of a GRAPHIC dialog variable
internal storage representation and basic input
must only be DBCS data or UCS-2 data.
and output editing characteristics for variables
When GRAPHIC is specified on this tag and
of a class.
the CCSID parameter is not specified, the
CHAR n field will contain graphic DBCS data.
Variables of this class are character When GRAPHIC is specified on this tag and
strings of a fixed length. The number of the CCSID parameter is specified with a
bytes, n, is from 1 to 32 767. CCSID using the UCS-2 encoding
scheme, the field will contain UCS-2 data.
IGC n [OPEN | EITHER] In both cases, shift-out and shift-in charac-
Variables of this class are fixed-length ters are not placed in the variable pool by
character strings which may contain either the application or the UIM. On
double-byte data surrounded by shift-out output, the UCS-2 data will be converted
and shift-in characters. The number of from the specified UCS-2 CCSID to the
bytes, n, is from 4 to 32 767. CCSID of the device. On input, the data
OPEN indicates that variables defined with will be converted from the device CCSID
this class can contain both single-byte and to the specified UCS-2 CCSID.
double-byte data. When the CCSID parameter is specified,
EITHER indicates that variables defined several restrictions are enforced. First, all
with this class can contain single-byte or graphic fields using the CCSID parameter
double-byte data, but not both. If EITHER will not be allowed to span multiple lines
is specified, the number of bytes, n must on a print panel. The COND tag will be
be an even number. limited to comparing other variables of the
same UCS-2 Level 1 encoding scheme.
The CASE attribute on this tag is not UCS-2 dialog variables will not be allowed
allowed for IGC classes. For IGC classes, on the CMD dialog command. Also, the
processing for CHRID=PNLGRP on this tag following tags will not be allowed.
depends on whether or not the field value
contains double-byte character set CHECK tag
(DBCS) data. TI tag
A dialog variable with a BASETYPE of IGC As in current graphic DBCS support, each
can be presented on a device that is not UCS-2 character is 2 bytes long. Since
DBCS-capable, as long as the panel the length of data displayed on the device
group object in which the variable is after a conversion from a UCS-2 CCSID
declared does not have TEXTMODE=DBCS to the device CCSID is dependent upon
specified on the panel group (PNLGRP) what CCSID the device is capable of, the
tag. This allows the same panel group WIDTH attribute can be used to provide a
object and application to support both more accurate field width. This will allow
single-byte character set (SBCS) and you to bypass the default field width to
DBCS field values as long as the prede- either avoid truncation of field data or to
fined text in the panel group is only SBCS. increase the display space on the screen
by decreasing the field length.
GRAPHIC w c
Variables of this class can contain only When the optional WIDTH attribute is not
DBCS characters which are not sur- specified in conjunction with the GRAPHIC
rounded by shift-out and shift-in charac- basetype with the CCSID parameter, the
ters or UCS-2 characters. The number of number of characters on the screen is two
DBCS characters or UCS-2 characters, w, times the number of UCS-2 characters.
is from 1 to 16 383 (1 DBCS character When the WIDTH attribute is specified in
equals 2 bytes). The CCSID, c, should conjunction with the GRAPHIC basetype
with the CCSID parameter, this value will

CLASS Tag
be used for the field length instead of tion on converting lowercase characters to
default field width. The value entered for uppercase characters, see the CL Refer-
the WIDTH attribute represents the ence.
number of UCS-2 characters that would
The number of bytes, n, is from 1 to 255.
be displayed on the screen.
SIMPLE indicates that the name entered
For example, a panel group contains the
must be allowed as a simple OS/400
following line:
name.
:class name=example
basetype='graphic 1ð X' width=Y. GENERIC indicates that the name must
be a syntactically correct OS/400 generic
X is the UCS-2 CCSID that the data is name.
stored as. Y is the width of this field.
A translation list must be specified in the
If Y was not specified then the length
class definition if blanks or any other
of the field on the screen is 20 (two
name value that is not valid is allowed as
times the number of UCS-2 charac-
an input value for a dialog variable of this
ters).
BASETYPE.
If you know that the UCS-2 data is
constructed from single-byte data, OBJNAME n [SIMPLE | GENERIC | POSTO]
then the field width, Y, could be speci- Use a BASETYPE of OBJNAME for OS/400
fied as 5 UCS-2 characters so that the object names. SIMPLE indicates that the
field would have a width of 10 single- name entered must be a single OS/400
byte characters on the screen. object name.
If you know that the UCS-2 data is
GENERIC indicates that the name must
constructed from double-byte data,
be a syntactically correct OS/400 generic
then the field width, Y, could be speci-
object name.
fied as 11 UCS-2 characters so that
the field would have a length of 22 POSTO indicates that the name is used
single-byte characters on the screen. for a position-to field, and does not have
This would allow space for the to be a syntactically correct OS/400 name.
shift-out and shift-in characters. Lowercase characters (a through z) are
converted to uppercase characters (A
On output, field data that is longer than through Z) unless the name is enclosed in
the specified field length will be truncated. double quotation marks. The number of
On input, if too many characters were bytes, n, is from 1 to 255.
entered into the UCS-2 field, then the field
will be reverse image and an error will When POSTO is specified, if the first and
appear on the error line stating too many last character of the name is a double
characters were entered. The maximum quotation mark, the last double quote is
number of characters to enter will be dis- removed from the name. If the first char-
played in the error message. acter is not a quotation mark, all lower-
case characters (a through z) are
Variables defined with the UCS-2 converted to uppercase characters (A
basetype are not allowed on print panels. through Z). When POSTO is specified,
NAME n [SIMPLE | GENERIC] the name does not have to be a valid
Use a BASETYPE of NAME for System/38 object name.
names and names which follow the same A translation list must be specified in the
rules as System/38 object names, such as class definition if blanks or any other
names of record formats. name value that is not valid is allowed as
Lowercase characters (a through z) are an input value for a dialog variable of this
converted to upper case characters (A BASETYPE. For example, a translation list
through Z) according to the same rules is necessary when \LIBL should be an
that commands follow. For more informa- allowed value for a variable containing the
library name. For an example of a trans-

CLASS Tag
lation list, see “TL (Translation List)” on area. For more information on text areas,
page A-159. see “TEXT (Text Area)” on page A-154.
The CASE attribute on this tag cannot be DATE
specified for an object name class. The The variable is a 7-byte string repre-
UIM automatically adds or removes delim- senting the date in the form cyymmdd.
iter characters (quotation marks) and con- The date abbreviations are represented as
verts lowercase input values to uppercase follows:
as necessary.
c Century. Zero indicates the twentieth
BIN b century and one indicates the twenty-
Variables of this BASETYPE are signed and first century.
unsigned binary numbers. The number of yy Year
bits, b, is either 15, 16, 31, or 32. mm Month
'BIN 15' and 'BIN 31' are signed binary dd Day
numbers. 'BIN 16' and 'BIN 32' are TIME
unsigned binary numbers. A value of this class is a 6-byte string
'BIN 15' is the same as BINARY(2) and representing the time in the form hhmmss.
'BIN 31' is the same as BINARY(4), as The time abbreviations are represented as
described in chapter two of the System follows:
API Reference.
hh Hours
PACKED t f mm Minutes
Variables of this class are packed decimal ss Seconds
numbers. The number of digits, t, is from
ACTION
1 to 31. The number of decimal positions,
The variable is a 2-byte binary number
f, is from 0 to t.
with the same internal form as BIN 15,
ZONED t f used as the option column for an action
Variables of this class are zoned decimal list or the selection column for a selection
numbers. The number of digits, t, is from list.
1 to 31. The number of decimal positions, When a variable with this BASETYPE is
f, is from 0 to t. specified for the VAR attribute on a list
PTR column (LISTCOL) tag for an action list,
Variables of this class are pointers. Any the UIM determines the width of the input
variables of this BASETYPE cannot be dis- field based on the maximum OPTION attri-
played or printed. The data pointed to by bute value specified for any list action
a PTR variable can be displayed in a text (LISTACT) tag in the area.

CLASS Tag
Table A-4. Attribute Summary for Each BASETYPE

BASETYPE Default Minimum Maximum Default Default Default
WIDTH WIDTH WIDTH SHIFT CASE BLANKS
Attribute Attribute Attribute Attribute Attribute Attribute
BIN 15 6 1 255 UPPER UPPER IGNORE
CHAR n n n 32767 NONE MIXED RESPECT
IGC n n n 32767 NONE MIXED RESPECT
GRAPHIC w w w 16383 NONE MIXED RESPECT
GRAPHIC w c w w/2 16383 NONE MIXED RESPECT
NAME n n n 255 UPPER UPPER IGNORE
OBJNAME n n n 255 NONE See text IGNORE
PACKED t f t+3 f+3 255 UPPER n/a n/a
where t=f
PACKED t f t+2 f+2 255 UPPER n/a n/a
where t¬=f and f>0
PACKED t f t+1 1 255 UPPER n/a n/a
where t¬=f and f=0
ZONED t f t+3 f+3 255 UPPER n/a n/a
where t=f
ZONED t f t+2 f+2 255 UPPER n/a n/a
where t¬=f and f>0
ZONED t f t+1 1 255 UPPER n/a n/a
where t¬=f and f=0
DATE 8 8 255 UPPER n/a n/a
TIME 8 8 255 UPPER n/a n/a
ACTION 6 (See 1 255 UPPER UPPER IGNORE
text)
Optional Attributes For more information on translation lists, see

“TL (Translation List)” on page A-159.
WIDTH=display-width.
The width of a display field in which values of CHRID=NONE | PNLGRP
this class are presented. For a BASETYPE of If the CHRID parameter on the CRTPNLGRP
GRAPHIC, this value is the number of DBCS command is *JOBCCSID, the compiler issues
characters or UCS-2 characters. The defaults a warning message and the CHRID attribute
and allowable values for the display width on the CLASS tag is ignored. All variables
depend on the BASETYPE attribute, as specified are converted from the job CCSID to the
in Table A-4. device CHRID when *JOBCCSID is specified.
For variables that use this class, a value If NONE is specified, the data is assumed to
larger than the default for the BASETYPE may be in the correct character set and code page
be needed to support the external display for the display or printer device.
form of values appearing in a translation list. If PNLGRP is specified, the data associated
with this class is interpreted with the character

CLASS Tag
set and code page specified on the CHRID inbound processing of a translation list. For a
parameter on the CRTPNLGRP control lan- BASETYPE of GRAPHIC, CASE=UPPER is not
guage command. For devices that do not allowed. The default case is determined by
allow the downloading of this code page to the BASETYPE. For a summary of the BASETYPE
handle the display of such data, character and corresponding default, see Table A-4 on
conversion occurs on both output and input for page A-18.
variables of this class. The conversion table
BLANKS=RESPECT | IGNORE
for such cases is determined by the following
RESPECT indicates that blanks in the input
rules:
field are preserved when the value is assigned
Character set Code page to the variable pool.
Panel group xxx yyy
Device aaa bbb IGNORE indicates that the value is left justi-
Output conversion table = QUSRSYS/Qyyyaaabbb fied when it is assigned to the variable pool.
Input conversion table = QUSRSYS/Qbbbxxxyyy The default is determined by the BASETYPE.
The processing to remove leading blanks
If the conversion table is not found, no conver-
takes place after any processing for the CHRID
sion takes place. This conversion is done
and CASE attributes on this tag, and before
before any validity checking or inbound pro-
validity checking or inbound processing of a
cessing of a translation list.
translation list. For a summary of the
For a BASETYPE of GRAPHIC, CHRID=PNLGRP BASETYPE and corresponding default, see
is not allowed on this tag. The UIM does not Table A-4 on page A-18.
perform character set and code page conver-
When BLANKS=IGNORE is specified for a
sion on GRAPHIC fields containing DBCS
BASETYPE of IGC, only leading SBCS blanks
data because there is no single-byte part of a
are removed from the field value. The pro-
GRAPHIC field. For GRAPHIC fields con-
cessing to remove leading blanks stops at the
taining UCS-2 data, conversions will occur
first shift-out character in the field.
only between the specified UCS-2 CCSID and
the device CCSID. SUBST=DISPLAY | QUOTED
When CHRID=PNLGRP is specified for a class If DISPLAY is specified, the substitution
with BASETYPE of IGC, the UIM converts only values used on the CMD dialog command for
the single-byte portion of the field. No conver- this class of variables is the same as their dis-
sion is done on the DBCS portion of the field. played values.
If QUOTED is specified, the substitution
SHIFT=NONE | UPPER
values used on the CMD dialog command for
If NONE is coded, no special keyboard shift is
this class of variables are enclosed in apostro-
used for fields of this class.
phes, and apostrophes within the values are
If UPPER is coded, the keyboard is shifted to doubled. Values translated with the trans-
uppercase for data entry for display input lation list (TL) tag are not quoted.
fields associated with variables of this class.
The default keyboard shift is determined by BIDI=PNLGRP | LTR | RTL
the BASETYPE. For a summary of the BASETYPE Sets the left-to-right or right-to-left orientation
and corresponding default, see Table A-4 on for variables of this class. This attribute is
page A-18. ignored when BIDI=NONE is specified on the
PNLGRP tag.
CASE=MIXED | UPPER
PNLGRP indicates that the parameter from
MIXED indicates that characters from any field
the BIDI attribute on the PNLGRP tag should
of this class are preserved when assigned to
be used to set the orientation for variables of
the variable pool.
this class.
UPPER indicates that lowercase characters (a
LTR indicates that a left-to-right orientation
through z) are uppercased before assignment
should be used for variables of this class.
to the pool. This translation takes place after
any processing for the CHRID attribute on this RTL indicates that a right-to-left orientation
tag and before any validity checking or should be used for variables of this class.

CLASS Tag
The orientation defaults to PNLGRP for The Arabic and Hebrew code pages used to
classes with a BASETYPE of CHAR and IGC. determine if the variable must have its display
Orientation defaults to LTR for classes with a orientation flipped are described as follows:
BASETYPE of NAME, OBJNAME, BIN,
For code page 420
PACKED, ZONED, DATE, TIME, and
ACTION. – The following hex values represent
Arabic characters: 42 through 49, 51,
The cursor direction is reversed for any input
52, 55 through 59, 62 through 69, 70
field which has an orientation opposite the
through 79, 80, 8A through 8F, 90, 9A
panel's orientation. The cursor direction can
through 9F, A0, AA through AF, B0
be changed later when the CONTXTREV attribute
through B5, B8 through BF, CB, CD,
of this tag is processed.
CF, D0, and DA through DE.
CONTXTREV=NO | YES
– The following hex values represent
Specifies that a context-sensitive reversal is
Latin characters: 6F, 81 through 89,
performed for bidirectional variables of this
91 through 99, A2 through A9, C1
class. This attribute is ignored when
through C9, D1 through D9, DF, E2
BIDI=NONE is specified on the PNLGRP tag.
through EB, ED, EE, EF, F0 through
For CONTXTREV=NO, when the orientation of a F9, and FB through FE.
variable does not match the orientation of the
– The remaining characters are not con-
panel group, the value for each display line of
sidered to be Arabic and Latin.
the variable is reversed before it is displayed.
On entry, the contents of each display line of For code page 424
a field that has an orientation opposite to the – The following hex values represent
panel is also reversed before it is moved from Hebrew characters: 41 through 49, 51
the display field to the variable pool. NO is through 59, 62 through 69, and 71.
the default.
– The following hex values represent
For CONTXTREV=YES, the contents of dialog Latin characters: 81 through 89, 91
variables are checked to determine the ulti- through 99, A2 through A9, C1
mate display orientation of the variable. The through C9, D1 through D9, E2
dialog variable value is checked before it is through E9, and F0 through F9.
displayed. If the dialog variable is used in an
input field, the value is checked again before – The remaining characters are not con-
the input value is copied to the variable pool. sidered to be Hebrew and Latin.
A description of the checking follows: For a CONTXTREV=YES input field, the initial
When BIDI=LTR is specified on the cursor direction is determined the same way
PNLGRP tag, as for a CONTXTREV=NO input field. Then it is
further processed and redetermined, based on
– The dialog variable is inverted if and the results of the following content inversion:
only if the dialog variable value con-
tains at least one Arabic or one BIDI=LTR is specified on the PNLGRP
Hebrew alphabetic character, or if it tag:
contains no Latin characters and – When BIDI=LTR is specified on the
BIDI=RTL is specified on the CLASS CLASS tag:
tag.
- The cursor direction is inverted if
When BIDI=RTL is specified on the and only if the content of the
PNLGRP tag, dialog variable is inverted.
– The dialog variable is inverted if and – When BIDI=RTL is specified on the
only if the dialog variable value does CLASS tag:
not contain any Arabic or Hebrew
alphabetic characters, and if either it - The cursor direction is inverted if
contains Latin characters or BIDI=LTR and only if the content of the
is specified on the CLASS tag.

CLASS Tag
dialog variable is not inverted and – When BIDI=RTL is specified on the

if it contains at least one Latin CLASS tag:
alphabetic character. (This pre-
- The cursor direction is inverted if
vents the inversion of the cursor
and only if the content is inverted
direction in an empty field.)
and if the variable contains at
BIDI=RTL is specified on the PNLGRP least one Latin alphabetic char-
tag: acter. (This prevents the inver-
sion of the cursor direction in an
– When BIDI=LTR is specified on the
empty field.)
CLASS tag:
- The cursor direction is inverted if For a detailed summary of how
and only if the content of the CONTXTREV=YES works for various fields and
dialog variable is not inverted. panels, see the following decision tree.

CLASS Tag
No Are Any
Yes
Arabic or Hebrew
Characters Found?
Are Any Latin

Characters
Found?
No Yes
PNLGRP PNLGRP PNLGRP

BIDI attribute BIDI attribute BIDI attribute
RTL LTR
LTR RTL
LTR
RTL
CLASS CLASS
BIDI attribute BIDI attribute
Result Result
3 2
RTL LTR RTL LTR

Result Result
4 1
Result Result
2 1
Result Result
4 3
Result 1: Result 2: Result 3: Result 4:

Right-to-left Right-to-left Left-to-right Left-to right
cursor motion. cursor motion. cursor motion. cursor motion.
Invert value Invert value
of dialog of dialog
variable. variable.
RV2W060-0
NBRSHAPE=PNLGRP | ARABIC | HINDI When HINDI is specified, the translation of

Controls the display shape of application- digits is performed with a set of two translation
generated numbers for bidirectional variables tables defined for each national language.
of this class. This attribute is ignored when The first table is used for output operations,
BIDI=NONE is specified on the PNLGRP tag, and the second table is used for input oper-
or when any code page other than 420 ations.
(Arabic) is used by the display device.
The NBRSHAPE attribute allows the application
When PNLGRP is specified, the parameter program to not know the actual code points
from the NBRSHAPE attribute on the PNLGRP used to display the numeric digits.
tag should be used for variables of this class.
SYMSWAP=NO | YES
PNLGRP is the default.
Controls the exchange of symmetric charac-
When ARABIC is specified, the normal digits ters for bidirectional variables of this class.
X'F0' through X'F9' are used for numbers.

CLASS Tag
This attribute is ignored when BIDI=NONE is The complete list of symmetric characters for
specified on the PNLGRP tag. An example of Hebrew (code page 424) is:
two pairs of symmetric characters are:
( with ) Right and left parentheses, 4D
'(' with ')' with 5D
'<' with '>' { with } Right and left braces, C0 with D0
[ with ] Right and left square brackets,
When YES is specified, the symmetric char- BA with BB
acter exchange is performed for both input
< with > Less than and greater than signs,
and output operations on any field displayed
4C with 6E
with a right-to-left orientation. The situations h with i Double less than and double
where this can occur are: greater than signs, 8A with 8B
CONTXTREV=NO is specified on this tag for
The complete list of symmetric characters for
a variable that has a right-to-left orien- Arabic (code page 420) is:
tation.
( with ) Right and left parentheses, 4D
CONTXTREV=YES is specified on this tag for
with 5D
a variable that has a right-to-left orien-
< with > Less than and greater than signs,
tation, and the contents of the field causes
4C with 6E
the resulting field orientation to stay right-
to-left. All symmetric characters generated by the
CONTXTREV=YES is specified on this tag for UIM are processed as if SYMSWAP=YES is
a variable that has a left-to-right orien- specified. At this time, the symmetric charac-
tation, and the contents of the field causes ters include:
the resulting field orientation to change to > Greater than symbol. Used to mark menu
right-to-left. options and used in the command line
When SYMSWAP=NO is specified, symmetric prompt
character exchanges are not performed. NO ( ) Right and left parentheses symbols. Used
is the default. around an empty list message.

CLASS Tag
Example: Class Definitions checks are performed on the field and the value of
the variable in the variable pool is left unchanged.
UIM Source Numeric literals must be of the form:

.\ Class of options whose only legal values ┌─+─┐ ┌─────────┐
.\ are Y, N, and blank. 55──┼───┼───6─digit─┴──┬──────────────┬─────5%
.\ These values are translated to an └─-─┘ │ ┌──
───────┐ │
.\ internal form. └─.──6─digit─┴──┘
:class name=option
basetype='bin 15'
or
case=upper width=1.
:tl msgid=MMM1234. ┌─+─┐ ┌──
───────┐
:ti value=1.Y 55──┼───┼──┬───────────┬──.──6─digit─┴──────5%
:ti value=2.N └─-─┘ │ ┌─────────┐ │
└──6─digit─┴─┘
:ti value=3.
:etl.
A comma may be used in place of a period for
:eclass.
.\ decimal point on input. If conversion to the
.\ class of object names or the special internal form loses significant digits, the field is
.\ value \all considered in error and the UIM displays an error
:class name=object message to the user without altering the contents
basetype='objname 1ð generic'. of the variable pool. All nonzero digits after the
:tl. decimal point are considered significant, and
:ti value='"\ALL"'.\ALL attempts to truncate result in an error. Leading
:etl. zeros before the decimal point and trailing zeros
:eclass. after the decimal point are not considered signif-
.\ icant. If a sign is not supplied, the value is
.\ Class of options from 1-5 or 7-9, assumed to be positive.
.\ in a field of width 1.
:class name=listoption Binary values can also be translated to character
basetype='bin 15' width=1.
strings on output and from character strings on
:check range='1 5' range='7 9'.
entry. In this case, the value specified for the
:eclass.
WIDTH attribute on this tag must allow for the width
of the translated character string specified on the
Display Forms of Numeric Values translation list item (TI) tag. For more information
on translation lists, see “TL (Translation List)” on
Numbers are usually displayed without leading page A-159 and “TI (Translation List Item)” on
zeros. If the absolute value of the number is less page A-158.
than one, a leading zero before the decimal point
is supplied or suppressed, based on the Any variable with a BASETYPE of ACTION is
QDECFMT system value. Numbers are signed handled with editing rules for a numeric value,
only if the number is negative. A decimal point is except that a zero value is displayed as blanks,
displayed only if there are fractional digits. The and a zero input value is not valid. Plus signs are
decimal point character used is the one defined by not allowed on entry. Translation lists and validity
the system value QDECFMT. Numbers are dis- check processing are not allowed for variables
played preserving all fraction digits. whose BASETYPE is ACTION.
If a value is too large to fit in the display field on Some examples of the display for numeric values
output, the field is filled with plus signs. If a field are shown in the following table.
consists entirely of plus signs on entry, no validity

CLASS Tag
Internal Displayed Notes

BASETYPE WIDTH Value Value
BIN 15 1 1 1
BIN 15 1 -1 + (Value too large to display)
BIN 15 5 1 1
BIN 15 5 -1 -1
BIN 15 5 -3456 -3456
BIN 15 5 -32768 +++++ (Value too large to display)
BIN 16 5 65535 65535
BIN 31 10 2147483645 2147483645
BIN 31 9 2147483645 +++++++++ (Value too large to display)
BIN 32 10 4294967295 4294967295
BIN 32 9 4294967295 +++++++++ (Value too large to display)
PACKED 2 2 .45 .45 Calculated field width is 5
PACKED 2 2 -.45 -.45 Calculated field width is 5
PACKED 5 2 000.45 ð.45 Calculated field width is 7
PACKED 5 2 -000.45 -ð.45 Calculated field width is 7
PACKED 5 2 8 000.45 ð.45
PACKED 5 2 8 -000.45 -ð.45
PACKED 5 2 8 123.45 123.45
PACKED 5 2 8 -123.45 -123.45
PACKED 5 2 4 -123.45 ++++ (Value too large to display)
PACKED 5 2 4 003.45 3.45
PACKED 5 0 00001 1 Calculated field width is 6
PACKED 5 0 00000 ð Calculated field width is 6
PACKED 5 0 -00000 ð Calculated field width is 6
PACKED 5 0 -00001 -1 Calculated field width is 6
Display Forms of Character, Date, must be in the format specified by the date format
of the current job, but the separator characters
and Time Values specified by the date separator of the current job
Character values are displayed as they appear are optional. Because the date formats do not
from the variable pool, padding with nulls on the allow the entry of the century digit, it is assumed
right as necessary. If the value entered into the to be 0 if the year number is greater than 40. If
input field is not translated using a translation list, the year number is less than or equal to 40, the
an error is reported to the user and the dialog var- century digit is assumed to be 1.
iable is not updated if the value is longer than the
Times are always displayed in a 24-hour time
BASETYPE of the variable after trailing blanks are
format, with the time separator as specified by the
removed. Only trailing SBCS blanks are removed;
time separator of the current job. The separator
DBCS blanks are considered significant.
characters specified by the time separator of the
Dates are always displayed in the form specified current job are optional. If a time is entered
by the date format and date separator of the without a time separator, either four or six digits
current job. When a date is entered by a user, it must be supplied.

CMDLINE Tag
CMDLINE (Command Line)
55──:CMDLINE──SIZE=─┬─SHORT─┬───┬────────────────────────┬──.──┬──────────────────┬─────5%
└─LONG──┘ └─NAME=command-line-name─┘ └─instruction-text─┘
The command line (CMDLINE) tag specifies that SIZE=LONG is valid only for a 27-row by
the panel has a command line and provides addi- 132-byte panel or a 24-row by 80-byte panel.
tional command line information. This tag is
When BIDI=RTL is specified on the panel
allowed only for display panels. A command line
group (PNLGRP) tag, all SIZE=LONG
may appear on any panel and may be inde-
command lines are automatically formatted by
pendent of all areas on the panel, or it may be
the compiler to a one-line command line with
associated with an action list or menu area on the
a blank line separator between the command
panel.
line and the function key area.
Only system commands can be entered on the
command line, unless the panel contains a menu Optional Attribute
area or an action list area. If the panel contains a
NAME=command-line-name
menu area, the user enters either a menu option
The name associated with the command line.
or a command on the command line. For an
This name can be used later with the Add
action list, the user enters a string that is either
Pop-Up Window (QUIADDPW) API to position
run as a command or acts as parameter informa-
a window near the command line.
tion for action list processing.
For more information on the rules for naming,
This tag must be the final tag in the panel, and is see “Name Syntax” on page A-4.
placed just before the end of the display panel.
The CMDLINE tag and the option line (OPTLINE) Optional Text
tag are mutually exclusive.
instruction-text
Required Attribute The text appearing as instructions for the
command line. The text is an implied para-
SIZE=SHORT | LONG graph.
A SHORT command line takes up only one
When the display is formatted, any text that
line of the display and fills up that line.
does not fit on one display line is formatted on
A LONG command line takes up two lines on multiple lines as necessary and indented two
the display. display positions. The text can be a maximum
of 255 characters and can only contain the
SIZE=SHORT must be specified if a panel
reverse text (RT) tag. If no text is provided,
width other than 80 bytes (or 132 bytes) is
no instruction line is displayed above the
specified on the display panel (PANEL) tag.
command line.

COND Tag
COND (Condition Definition)
55──:COND──NAME=condition-name──EXPR='conditional-expression'──┬───────────────────┬─────5
└─EVAL=─┬─ALWAYS─┬──┘
└─ONCE───┘
5──.────────────────────────────────────────────────────────────────────────────────────5%
The condition definition (COND) tag defines a con- page 00037, the common USA code page, the
dition that must be true if certain processing is to hexadecimal value of the logical OR character
take place. Other tags may refer to this condition, is X'4F', and the hexadecimal value of the
which is evaluated before a panel is displayed. If logical NOT character is X'5F'. The UIM
the condition is true, the action or formatting spec- compiler uses these hexadecimal values
ified by the referring tag is performed. regardless of the code page of the source.
When operand A is a comparison between a
Required Attributes dialog variable and a literal value, or between
two dialog variables, it must be in the fol-
NAME=condition-name
lowing form:
The name of the condition specified in the
expression. The name must be unique within 55──┬─dialog-variable-name─┬─────────────5
the panel group. └─literal-value────────┘
5────relational-operator─────────────────5
see “Name Syntax” on page A-4. 5──┬─dialog-variable-name─┬─────────────5%
└─literal-value────────┘
EXPR='conditional-expression'.
A conditional expression is a true or false The relational operator may be specified as =,
expression in the following form: ¬=, >, <, >=, or <=, if the code page of the
┌─\AND──────────────┐ source maps the not character (¬) to X'5F'.
│ ┌─\OR───────────┐ │ Otherwise, it is suggested that the special
55───6──6──┬─A───────┬──┴─┴───────────────5% values *EQ, *NE, *GT, *LT, *GE, or *LE be
├─(A)─────┤
└─\NOT(A)─┘ used, respectively for the relational operator.
Comparisons may take place only between
where A is an operand which can be one of items of matching BASETYPE and precision as
the following: defined on the class definition (CLASS) tag.
Comparisons between two literals are not
A conditional expression allowed.
A comparison between a dialog variable
and a literal value Character string literals must be enclosed in
A comparison between two dialog vari- double quotation marks ("). The UIM does
ables not automatically uppercase character strings.
A built-in function Hexadecimal strings are allowed as character
strings. Hexadecimal strings cannot be used
When operand A is a conditional expression,
for comparison with dialog variables defined
the *AND and *OR logic becomes more
with a BASETYPE of GRAPHIC on the CLASS
complex.
tag. For more information about specifying
The logical OR character (|) can be used in hexadecimal strings, see “Hexadecimal
place of *OR, the ampersand character (&) Literals” on page A-6.
can be used in place of *AND, and the logical
For a comparison between a dialog variable
NOT character (¬) can be used in place of
whose BASETYPE is GRAPHIC (as defined on
*NOT. Since the logical OR and logical NOT
the CLASS tag) and a literal, a double-byte
characters are not in the invariant character
character set (DBCS) graphic literal must be
set, their use is not recommended. For code

COND Tag
used. For more information about specifying 55──CHKOBJ(──┬─obj-name───┬──,──"obj-type"─────5

a DBCS graphic literal, see “DBCS Graphic └─"obj-name"─┘
Literals” on page A-6. 5──┬───────────────────────────────────┬──)───5%
└─,──"──┬─\CHANGE──────────────┬──"─┘
├─\ALL─────────────────┤
Numeric literals must be of the form: ├─\USE─────────────────┤
┌─+─┐ ┌─────────┐ ├─\EXCLUDE─────────────┤
├─\AUTLMGT─────────────┤
55──┼───┼───6─digit─┴──┬──────────────┬──5% │ ┌──
──────────────────┐ │
└─-─┘ │ ┌──
───────┐ │ └──6─┬─\OBJEXIST─┬───
(1) ─┴─┘
└─.──6─digit─┴──┘ ├─\OBJMGT───┤
├─\OBJOPR───┤
├─\OBJALTER─┤
├─\OBJREF───┤
or ├─\ADD──────┤
├─\DLT──────┤
┌─+─┐ ┌──
───────┐ ├─\READ─────┤
55──┼───┼──┬───────────┬──.──6─digit─┴───5% ├─\UPD──────┤
└─-─┘ │ ┌─────────┐ │ └─\EXECUTE──┘
└──6─digit─┴─┘ Note:
1 Each value can be used only once, with
where d is a digit from 0 through 9. a maximum of 7.
This attribute is repeatable so that an

If no authorities are specified, no authori-
expression can span several lines.
zation check is performed and the function
When operand A is a built-in function, it can becomes an existence check.
be used as follows:
CHKUSRCLS
CHKOBJ The user class argument specified for the
Evaluates to true if the object is found on function is compared to the user class
the system and the current job possesses parameter from the user profile of the
at least the level of authorization to the current job. The function evaluates to true
object specified by the authorities. Argu- if the user profile has the same or greater
ments must be character strings enclosed value than the function argument. The
in double quotation marks ("). The object function argument must be enclosed in
name follows OS/400 object naming con- double quotation marks (").
ventions. The object type is any of the
The following syntax diagram illustrates
allowable object types for the DSPOBJD
the valid argument values for the user
command and the authorities must be a
class:
single value or a list of authorizations to
be checked for. The values of these 55──CHKUSRCLS(─┬─\SECOFR─┬─)────────5%
authorizations are separated by blanks. ├─\SECADM─┤
├─\PGMR───┤
The following syntax diagram illustrates ├─\SYSOPR─┤
the authorities and how to use them: └─\USER───┘
CHKOBJ("OBJECT","\FILE","\USE")
CHKOBJ("PANELGRP","\PNLGRP")
\AND CHKUSRCLS("\PGMR")
CHKOBJ("DOCUMENT","\DOC","\READ \UPD")
\OR CHKUSRCLS("\SYSOPR")
\NOT(CHKOBJ("PROGRAM","\PGM"))
Optional Attribute
EVAL=ALWAYS | ONCE
Indicates whether or not the expression speci-
fied on the EXPR attribute of this tag must be

COND Tag
evaluated every time the condition is referred UIM Source

to, or if it needs to be evaluated only once.
If EVAL=ALWAYS is used, the expression is ..
.
evaluated to determine a new truth value :cond name=a
every time the condition is referred to. All expr='(var1 = 1ðð \AND var2 > ð)'
EVAL=ALWAYS conditions in a panel group or expr='\OR \NOT(var3 = ð)'.
menu are evaluated each time a panel or :cond name=b
menu is displayed. ALWAYS is the default. expr='chkobj("MENU2","\MENU","\READ, \UPD")'.
:cond name=c
If EVAL=ONCE is specified, the expression is expr='chkusrcls("\PGMR")'.
evaluated only once for every open application
that uses the panel group. The UIM only ..
.
evaluates the expression for a condition of this :menui
type the first time the condition is referred to. cond=a
Every reference after the first one uses the help='option1/help'
same truth value determined by the first refer- action='CMD CALL PGMð1'
ence. ONCE may be specified to improve option=1.Run report
performance for conditions that do not change :menui
while the application is open, particularly if the cond=b
expression requires the evaluation of a func- help='option2/help'
tion (like CHKOBJ) that may be costly. action='MENU MENU2'
option=2.Administration
:menui
Example: Conditioning an Option cond=c
help='option3ð/help'
The following example shows how the COND tag action='MENU UTIL'
might be used to condition menu items. The first option=3ð.Utilities
condition uses a complex expression which is split
..
onto two source lines. The second condition .
checks for the application user's authority to use a
menu on the system, and the third condition
checks for the user class of the application user.

COPYR Tag
COPYR (Copyright)
55──:COPYR──.──notice-text──────────────────────────────────────────────────────────────5%
The copyright (COPYR) tag provides a way to Required Text

present a copyright notice. Only one COPYR tag
is allowed. The copyright notice is displayed in notice-text
the message area of the first panel displayed after The text of the copyright notice that is dis-
the panel group is opened. This tag must be played. The text must be between 1 to 76
coded immediately after the panel group characters.
(PNLGRP) tag.

DATA Tag
DATA (Data Presentation Area)

Syntax for Display Panels
55──:DATA──DEPTH=─┬─area-depth─┬───┬───────────────────────┬──┬────────────────────┬───────5
└─'\'────────┘ └─HELP=help-module-name─┘ │ ┌─SPACE─┐ │
└─BOTSEP=─┼─NONE──┼──┘
└─RULE──┘
5──┬──────────────────┬──┬────────────────────┬──┬─────────────────┬───────────────────────5
│ ┌─NO──┐ │ │ ┌─1─────┐ │ │ ┌─ð─┐ │
└─SCROLL=─┴─YES─┴──┘ └─LAYOUT=─┼─2─────┼──┘ └─MAXHEAD=─┼─1─┼──┘
└─HORIZ─┘ ├─2─┤
├─3─┤
└─4─┘
5──┬──────────────────────┬──┬─────────┬──.──┬────────────┬──:EDATA.──────────────────────5%
│ ┌─SPACE──┐ │ └─COMPACT─┘ └─area-title─┘
└─BODYSEP=─┼─INDENT─┼──┘
├─BOTH───┤
└─NONE───┘
Syntax for Print Panels
55──:DATA──┬────────────────────┬──┬────────────────────┬──┬─────────────────┬─────────────5
│ ┌─SPACE─┐ │ │ ┌─1─────┐ │ │ ┌─ð─┐ │
└─BOTSEP=─┼─NONE──┼──┘ └─LAYOUT=─┼─2─────┼──┘ └─MAXHEAD=─┼─1─┼──┘
└─RULE──┘ └─HORIZ─┘ ├─2─┤
├─3─┤
└─4─┘
5──┬──────────────────────┬──┬─────────┬──┬───────────────────┬──.──┬────────────┬─────────5
│ ┌─SPACE──┐ │ └─COMPACT─┘ │ ┌─NORMAL─┐ │ └─area-title─┘
└─BODYSEP=─┼─INDENT─┼──┘ └─TYPE=─┴─PROLOG─┴──┘
5──:EDATA.────────────────────────────────────────────────────────────────────────────────5%
The data presentation area (DATA) tag describes (specified by a D, P, or B, respectively), and spec-
a data presentation area in a panel. This tag is ifies on which page more information can be found
allowed for display panels and print panels. This for each tag.
area can be used for data entry items or output
data items, or any combination of the two. When more than one tag is listed with the same
order number, all tags of that number can be
Other tags can be nested within the DATA tag. mixed in any order. However, a tag with a higher
These tags are listed in the following table. The order number cannot precede a tag with a lower
table defines the order in which the tags must order number. For example, a tag with an order
appear, indicates which tags can be used in number of three cannot precede a tag with an
display panels only, print panels only, or both order number of one or two.

DATA Tag
Table A-5. Tags Allowed Between the DATA and If no HELP attribute is specified on the DATA
EDATA Tags tag, a help module name must be associated
Tag Name Order Use Page with each item in the area by specifying the
HELP attribute on the DATAGRP tags or the
TOPINST 1 D A-161
DATAI and DATASLT tags.
(Top instruction
line) To provide the user with easy access to the
DATACOL 2 B A-39 online information for a data area with the
(Data column) LAYOUT=HORIZ attribute specified on this tag,
specify the HELP attribute on the DATA tag
DATAGRP 3 B A-40
(Data item group) instead of the HELP attribute on the individual
DATAI tags.
DATAI 3 B A-42
(Data item) BOTSEP=SPACE | NONE | RULE
DATASLT 3 D A-51 Defines the bottom separator for the data
(Data selection presentation area. If SPACE is specified, a
field) line of spaces is used. SPACE is the default.
BOTINST 4 D A-10 NONE indicates that no separator line exists.
(Bottom instruc-
tion line) RULE indicates that a line of underscored
spaces is used.
SCROLL=NO | YES
Required Attribute
Specifies whether or not the area is scrollable.
DEPTH=area-depth | '*' This attribute is allowed only for display
The depth of the area in lines, including sepa- panels. NO indicates that the area is not
rators if any are specified. This attribute is scrollable. NO is the default.
required for display panels but is not allowed
YES indicates that the data presentation area
for print panels. If '*' is specified, the space
is scrollable. SCROLL=YES is not allowed
remaining on the display after all else is allo-
when LAYOUT=HORIZ is specified. A line of
cated is given to this area. Only one area in
spaces is used by the UIM to provide a line
the panel may have '*' coded.
for the scroll information. If BOTSEP=SPACE,
only one line of spaces is used unless this
Optional Attributes area also contains bottom instructions.
HELP=help-module-name LAYOUT=1 | 2 | HORIZ
Identifies online information explaining all Indicates either the number of layout columns
items in the area. This attribute is allowed for a vertically formatted area or that a hori-
only for display panels. The help module zontal format should be used.
name may be a name imported from another
For LAYOUT=1, there is only one column of
panel group, but must follow the rules for
data items. For panels with WIDTH=80 bytes
names outlined earlier in this chapter. For
on the panel definition (PANEL) tag, the single
more information on the rules for naming, see
column of data items is in positions 2 through
“Name Syntax” on page A-4.
79. For panels with WIDTH=132, the single
A single help module name must be associ- column of data items is in positions 2 through
ated with every item in the area. If the HELP 131.
attribute is specified on the DATA tag, the
For LAYOUT=2, two layout columns of equal
help applies to all groups and items in the
width are used for data items. The data items
area, and the HELP attribute is not allowed on
specified within the area appear in order, from
any data group (DATAGRP), data item
top to bottom within a layout column and from
(DATAI), data selection field (DATASLT), and
left to right between layout columns. For
data selection field choice (DATASLTC) tags
panels with WIDTH=80, the two layout columns
in the area.
are in positions 2 through 38 and 43 through
79. For panels with WIDTH=132, the two layout

DATA Tag
columns of data items are in positions 2 except if the area is scrollable. If the area is
through 64 and 69 through 131. scrollable, a blank line is reserved to provide a
line for the scroll information.
For LAYOUT=HORIZ, the data fields are listed
horizontally across the width of the panel, with BOTH leaves a blank line after the last top
five spaces between items. This layout is instruction line and before the first bottom
useful if only two or three short values are instruction line, and also indents items in the
necessary. It should be limited to a single body of the area by two bytes from the left-
display line, because the UIM does not verti- most position in the layout column where the
cally align items appearing on different lines instruction lines begin. If the area contains no
within the area. top or bottom instruction lines, no blank lines
are reserved before or after the area body.
MAXHEAD=0 | 1 | 2 | 3 | 4
The maximum number of lines that can be NONE does not leave a blank line between
used for column headings. The column the instruction line and the body, and does not
headings are specified using the data column indent the body with respect to the layout
(DATACOL) tag. From zero to four lines can column except if the area is scrollable. If the
be specified. Zero is the default, meaning that area is scrollable, a blank line is reserved to
no column headings are allowed. Only provide a line for the scroll information.
MAXHEAD=0 is valid for a data presentation area
COMPACT
with a horizontal layout, because column
If COMPACT is specified, no blank lines are left
headings are not allowed in horizontal presen-
between column headings and all items and
tation. For more information on column
outer groups in the area. If COMPACT is not
headings, see “DATACOL (Data Column)” on
specified, a blank line appears after the area
page A-39.
column headings and between all items and
When column headings are used, you may outer groups.
want to provide expansion space for national
TYPE=NORMAL | PROLOG
language translation by specifying a MAXHEAD
Indicates whether or not this data area is a
value larger than the number of heading lines
prolog area. The prolog area is printed only
required. If this is not done, expansion space
once after the title line on the first page. This
must be provided within the column widths
attribute is allowed only for the print head
determined by the DATACOL tag.
panel (PRTHEAD) tag. NORMAL is the
BODYSEP=SPACE | INDENT | BOTH | NONE default value.
The type of visual separation distinguishing
the body of the area from other elements on Optional Text
the display, particularly any top and bottom
instruction lines within the area. area-title
The title of the area. If no text is specified, no
SPACE leaves a blank line after the last top
title line is allocated to the area. The text
instruction line and before the first bottom
must appear on the same or next line as the
instruction line. Items in the body of the area
tag, can contain only the reverse text (RT)
begin in the leftmost position of the layout
tag, and is a maximum of 55 characters long.
column. They are not indented with respect to
instruction lines. If the area contains no top or
bottom instruction lines, no blank lines are Print Formatting Considerations
reserved before or after the area body.
Printed data areas are formatted similarly to data
INDENT is used to indent items in the body of areas that are displayed, with the following
the area by two bytes from the leftmost posi- exceptions:
tion in the layout column where the instruction
lines begin. If the area contains top or bottom When printing, there is a minimum of two lines
instruction lines, no blank line is reserved of data entries on a page besides the data
between the instructions and the area body group headings and the data column
headings.

DATA Tag
If two lines of data entries do not fit on a :datac.Number of copies (1─99)

page, a page eject occurs and the data :datai usage=inout
entries are printed on the next page. help=hduplx
var=duplex.Duplex
For formatting of data areas with LAYOUT=2, the :datac.1=Yes (Print both sides of paper)
UIM balances the data entries across the page :datac.2=No (Print one side only)
and ignores keep processing. :edata.
:epanel.
This format may not look good in some cases, but
LAYOUT=2 data areas should only be used on small Results
data areas or when the user is not concerned
about keep processing. à ð
Sample Entry Panel
Type choices, press Enter:

If there are data column headings, they are Item Choice Possible Choices
repeated on each page if the data area is con- File name . . . . . Name of document to be printed
tinued onto another page. Type style for

printing . . . . . 1 1=Prestige Elite (12 pitch)
3=Essay Standard (proportional)
4=Essay Bold (proportional)
Example 1: Data Entry Panel Left margin . . . . 6 Number of spaces from the left edge of
the paper (1-2ð)
Copies . . . . . . . 1 Number of copies (1-99)

The following example shows a sample data entry
Duplex . . . . . . . 1 1=Yes (Print both sides of paper)
panel. The panel has 5 prompts; 4 prompts have 2=No (Print one side only)
defaults supplied to the calling program by previ- F3=Exit F12=Cancel
ously setting the dialog variables for the function. á ñ

UIM Source Example 2: Two-Column Format
:panel name=entry1 in a Data Entry Panel
help=hentry1
topsep=space The following example shows a data area using
keyl=keys two-column format containing output items, and a
.Sample Entry Panel
form of data entry field that has no prompt.
:data depth='\'
maxhead=2.
:topinst.Type choices, press Enter: UIM Source
:datacol width=2ð.Item :panel name=panelx
:datacol width=1ð.Choice help=helpx
:datacol width='\'.'Possible Choices' topsep=space
:datai usage=inout keyl=keys
help=hfname .Another Sample Panel
var=fname.File name :data depth=14 layout=2.
:datac.Name of document to be printed :datacol width='24'.
:datai usage=inout :datacol width='\'.
help=hstyle :datagrp compact.Compact data group
var=prtstyle.Type style for printing :datai usage=out
:datac.1=Prestige Elite (12 pitch) help=hvar1
:datac.2=Courier (1ð pitch) var=var1.First element
:datac.3=Essay Standard (proportional) :datai usage=out
:datac.4=Essay Bold (proportional) help=hvar2
:datai usage=inout var=var2.Second element
help=hmargn :edatagrp.
var=margin.Left margin :datai usage=out
:datac.Number of spaces from the left help=hvar3
edge of the paper (1─2ð) var=var3.Third element
:datai usage=inout :datagrp grpsep=qindent
help=hcopy compact.
var=copies.Copies :datai usage=out

DATA Tag
help=hvar4
var=var4.Fourth element
à Another Sample Panel
ð
Compact data group: Another compact group:
:datai usage=out First element . . . : XXXXXXXXXX Seventh element . . : XXXXXXXX
Second element . . . : XXXXXXXXXX Eighth element . . . : XXXXXXXX
help=hvar5 Ninth element . . . : XXXX
Third element . . . . : XXXXXXXX
var=var5.Fifth element Fourth element . . . . : XXXXXXXX
Tenth element . . . . : XXXXXXXX
XXXXXXXX
:datai usage=out Fifth element . . . :
Sixth element . . . :
XXXXXXXX
XXXXXXXX
XXXXXXXX
help=hvar6 Thirteenth element . . :

Fourteenth element . . :
XXXXXXXX
XXXXXXXX
Fifteenth element . . : XXXXXXXX
var=var6.Sixth element
:edatagrp. Sixteenth element:
___________________________________________________
:datagrp compact.Another compact group
:datai usage=out
help=hvar7 F3=Exit F12=Cancel
var=var7.Seventh element á ñ
:datai usage=out
help=hvar8
var=var8.Eighth element Example 3: Two Presentation
:datai usage=out Areas for Data Items
help=hvar9
var=var9.Ninth element The following two examples show three data
:edatagrp. areas, which are initialized from the dialog vari-
:datagrp help=hvar1ð12
ables in the variable pool. The first two areas are
grpsep=none compact.
aligned horizontally, and the third area is for-
:datai usage=out
var=var1ð.Tenth element matted vertically.
:datai usage=out
var=var11 cond=cond11. UIM Source
:datai usage=out
:panel name=xmp3
var=var12 cond=cond12.
keyl=x1
:edatagrp.
help=hxmp3
:datagrp grpsep=none
.Data Item Extenders
compact.
:data depth=2
:datai usage=out
layout=horiz
help=hvar13
botsep=space.
var=var13.Thirteenth element
:datai usage=out
:datai usage=out
var=date
help=hvar14
help=hdatetime.Date and time
var=var14.Fourteenth element
:dataix usage=out
:datai usage=out
var=time
help=hvar15
newline=no
var=var15.Fifteenth element
itemsep=1.
:edatagrp.
:edata.
:edata.
:data depth=2
:data depth=3
layout=horiz
bodysep=none.
botsep=space.
:datacol width=ð.
:datai usage=out
:datacol width='\'.
var=jobname
:datagrp.Sixteenth element
help=hdatetime.Job name
:datai usage=inout
:dataix usage=out
help=hvarx
var=user
var=varx.
newline=no
:edatagrp.
itemsep=1.
:edata.
:dataix usage=out
:epanel.
var=jobnbr
newline=no itemsep=1.
Results :edata.
:data depth='\'
layout=1

DATA Tag
botsep=space :topinst.Select one of the following:

compact. :menui action='return 1'
:datacol width=ð. help='hoption1'
:datacol width='\'. option=1.Display file attributes
:datagrp grpsep=indent :menui action='return 2'
help=dependptfs help='hoption2'
compact.Dependent PTFs option=2.Display file contents
:datai usage=out :menui action='return 3'
var=ptf1. help='hoption3'
:dataix usage=out option=3.Change ownership
var=ptf2. :menui action='return4'
:dataix usage=out help='hoption4'
var=ptf3. option=4.Change authorizations
:dataix usage=out :menui action='return 5'
var=ptf4 help='hoption5'
newline=yes. option=5.Destroy
:dataix usage=out :menui action='return 6'
var=ptf5. help='hoption6'
:edatagrp. option=6.Backup to tape
:edata. :emenu.
:epanel. :optline.Selection
:epanel.
Results
Results
à Data Item Extenders
ð
Date and time: 12/31/99 12:59:59 à Work with Files
ð
System: xxxxxxxx
Job name: DSPð1 QSECOFR ð12345 File: MEMO47123 Library: QGPL
Dependent PTFs: Select one of the following:
XXXXXXXXXXXXXXX XXXXXXXXXXXXXXX XXXXXXXXXXXXXXX
XXXXXXXXXXXXXXX XXXXXXXXXXXXXXX 1. Display file attributes
2. Display file contents
3. Change ownership
4. Change authorizations
5. Destroy
6. Backup to tape
Selection
F3=Exit F12=Cancel _
á ñ F3=Exit F12=Cancel
á ñ
Example 4: Data Presentation
Area with a Menu Area Example 5: Data Entry Panel
with a Nested Data Group
UIM Source
:panel name=xxx
UIM Source
keyl=x1 :panel name=nestg
help=hxxx help=helpn
.Work with Files topsep=space
:data depth=2 keyl=keys
layout=horiz. .Nested Data Group
:datai var=fname :data depth='\'
help='filename'.File scroll=no.
:datai var=lname :topinst.Type choices, press Enter.
help='libname'.Library :datacol width=4ð.
:edata. :datacol width=1ð.
:menu depth='\'. :datacol width='\'.
:datagrp compact

DATA Tag
grpsep=none. :edatagrp.
:datai usage=inout :epanel.
help=hjobq
var=jobq.Place on job queue Results
:datac.Y=Yes, N=No
.\ The following "datagrp" tag is
.\needed to cause indentation for à Nested Data Group
ð
.\ the "For choice Y=Yes" data group. Type choices, press Enter.
:datagrp compact Place job on job queue . . . . . . . . . Y=Yes, N=No

For choice Y=Yes:
grpsep=indent. Send completion message . . . . . . Y=Yes, N=No
:datagrp compact
grpsep=indent.For choice Y=Yes:
:datai usage=inout
help=hcmpmsg
var=cmpmsg.Send completion message
:datac.Y=Yes, N=No F3=Exit F12=Cancel
:edatagrp.
:edatagrp.
á ñ

DATAC Tag
DATAC (Data Item Choices)
55──:DATAC──┬─────────────────────────────┬──.──┬──────────────────┬────────────────────5%
└─CHOICE=dialog-variable-name─┘ └─text-for-choices─┘
The data item choices (DATAC) tag provides the Dialog variables must be defined with a
text for the possible choices column of a data BASETYPE of CHAR, IGC, or BIN on the class
presentation area. This tag is allowed for display definition (CLASS) tag.
panels and print panels. It is not valid if only two
The error state of the dialog variable is not
data column (DATACOL) tags are specified for the
used for determining the highlighting of the
area, or if LAYOUT=HORIZ is specified on the data
text.
presentation area (DATA) tag for the area.
Special formatting for IGC. (The abbrevi-
The DATAC tag must appear after the corre- ation IGC is used in commands and keywords
sponding data item (DATAI) tag. More than one to represent double-byte character set func-
DATAC tag may be specified after the DATAI tag tions.) When a dialog variable with a
to provide several lines of text. If no DATAC tags BASETYPE of IGC is specified on the CLASS
are entered, no text exists in the possible choices tag, the UIM does special formatting. If the
column for the data item. variable value begins with a shift-out character
(X'0E'), the UIM shifts the value one byte to
Optional Attribute the left to preserve vertical alignment with
data choices on other lines.
CHOICE=dialog-variable-name
The name of a dialog variable containing the
Optional Text
choices text to be displayed. The dialog vari-
able must be defined with a width less than or text-for-choices
equal to the width specified on the third The text is an implied paragraph. Lines are
DATACOL tag for the data area, the possible formatted as necessary onto multiple lines
choices column. If the CHOICE attribute is within the column and indented two spaces
used, no text-for-choices can be specified from the beginning of the column. The text is
after the period of this tag. a maximum of 255 characters and can only
contain the reverse text (RT) tag. The text-
for-choices is required unless the CHOICE attri-
bute is specified on this tag.

DATACOL Tag
DATACOL (Data Column)
55──:DATACOL──WIDTH=─┬─column-width─┬───.──┬────────────────┬───────────────────────────5%
└─'\'──────────┘ └─column-heading─┘
The data column (DATACOL) tag specifies the case, the item column is not allocated and
width of the item, choice, and possible choices there is no separator in front of the choice
columns, and can also provide column headings. column.
This tag is allowed for display panels and print
The value for any data item may span
panels. It is not valid if LAYOUT=HORIZ is speci-
columns, but must begin on the correct
fied for the data presentation area. It must appear
column boundary. The possible choices text
after the data presentation area (DATA) tag for the
for that item, assuming three DATACOL tags
area and before the first data item (DATAI), data
are specified, begins in the location assigned
selection field (DATASLT), or data group
to the possible choices. This possible choices
(DATAGRP) tag.
text may be on the same or next line as the
data item field.
Two or three DATACOL tags must be specified
when the LAYOUT attribute of on the DATA tag
specifies 1 or 2. If only two DATACOL tags are Optional Text
used, the area has no possible choices column
column-heading
and no data item choices (DATAC) tags are
The column heading placed above the data
allowed in the area. If three DATACOL tags are
items in the data area. If no column heading
specified, all three columns are allocated,
is specified, none is displayed.
including the possible choices column.
The text may appear on more than one line
and can contain only the reverse text (RT)
Required Attribute
tag. Each word of the column heading is
WIDTH=column-width | '*' placed on a new line. If multiple words are
The width, in bytes, for the column. The width necessary in a line of the column heading,
specified must be a positive integer, and the they must be enclosed in apostrophes (').
sum of the widths of the columns and separa- Each word or quoted string must fit within the
tors in the data presentation area must not column width defined by the WIDTH attribute on
exceed the width of the layout column deter- this tag. The maximum number of words or
mined by the DATA tag. WIDTH=0 is allowed quoted strings allowed is specified by the
only for the first DATACOL tag; it formats the MAXHEAD attribute on the DATA tag. Column
area without an item column for data item or headings are not allowed if MAXHEAD=0 is used
data selection field prompt text. for the data area.
If '*' is coded, the remainder of the area The column headings are left-justified. If no
width is used for the column. Only one column heading text is specified on any
DATACOL in the area may have '*' specified. DATACOL tag for the area, no lines are
A three-column separator is maintained reserved on the display for heading informa-
between columns, except when WIDTH=0 is tion.
specified for the first DATACOL tag. In this

DATAGRP Tag
DATAGRP (Data Group)

55──:DATAGRP──┬───────────────────────┬──┬──────────────────────┬──────────────────────────5
└─HELP=help-module-name─┘ └─NAME=data-group-name─┘
5──┬──────────────────────┬──┬─────────────────────┬──┬─────────┬──.──┬───────────────┬────5
│ ┌─INDENT──┐ │ └─COND=condition-name─┘ └─COMPACT─┘ └─group-heading─┘
└─GRPSEP=─┼─QINDENT─┼──┘
└─NONE────┘
5──:EDATAGRP.─────────────────────────────────────────────────────────────────────────────5%
55──:DATAGRP──┬──────────────────────┬──┬─────────────────────┬──┬─────────┬──.────────────5
│ ┌─INDENT──┐ │ └─COND=condition-name─┘ └─COMPACT─┘
└─GRPSEP=─┼─QINDENT─┼──┘
└─NONE────┘
5──┬───────────────┬──:EDATAGRP.──────────────────────────────────────────────────────────5%
└─group-heading─┘
The data group (DATAGRP) tag is used to group name may be a name imported from another
data items and data selection fields in a data pres- panel group, but must follow the rules for
entation area. This tag is allowed for display names outlined earlier in this chapter. For
panels and print panels. One data group may be more information on the rules for naming, see
nested within another data group; up to four levels “Name Syntax” on page A-4.
of data group nesting are allowed, including the
A single help module name must be associ-
outermost group. This tag is not valid if
ated with every item in the area. If the HELP
LAYOUT=HORIZ is specified for the data presenta-
tion area (DATA) tag.
help applies to all groups and items in the
area, and the HELP attribute is not allowed on
The UIM does keep processing for data item
any data group (DATAGRP), data item
groups. When data groups are nested within
(DATAI), data selection field (DATASLT), and
other data groups, keep processing is done for all
data selection field choice (DATASLTC) tags
the groups. If an outer group must be split, keep
in the area.
processing is attempted for groups nested within
it. If the number of lines required for an entire If the HELP attribute is specified on the
group exceeds the number of lines remaining in DATAGRP tag, the help applies to all items in
the layout column, the entire group is forced to the the group, and the HELP attribute is not
next column. In the case of single-column layout, allowed on any DATAI, DATASLT,
the entire group is forced to the next scrollable DATASLTC, or nested DATAGRP tags within
page. Any data group that becomes too large for the data group.
one layout column begins at the top of one
If no HELP attribute is specified on the DATA
column and continues onto as many columns or
tag or on any outer or nested DATAGRP tags,
pages as required for all items.
the HELP attribute is required on all DATAI and
DATASLT tags within the group.
Optional Attributes
NAME=data-group-name
HELP=help-module-name The name associated with the group. This
Identifies online information explaining all name can be used with the Add Pop-Up
items in the group. This attribute is allowed Window (QUIADDPW) API to position a
only for display panels. The help module

DATAGRP Tag
window near this data group. This attribute is the group. This option is not recommended
allowed only for display panels. when group heading text is specified. It can
be used to group related data items, data item
groups, and data selection fields together
see “Name Syntax” on page A-4.
without a group heading. It does this by
GRPSEP=INDENT | NONE | QINDENT defining a compact group of items and nested
Specifies what type of visual separation groups in a non-compact area.
should be used to distinguish the items in the
COND=condition-name
group.
The group is displayed or printed only if the
INDENT is used to indent the left-most condition specified is true. All tags within the
column, prompt, or value for every data item, group appear only if this data group appears.
group heading of a nested data group, or data The condition must be defined in the panel
selection field within the group by two posi- group prolog with the condition definition
tions. Only the left-most column is indented. (COND) tag.
The group heading is not indented.
COMPACT
QINDENT is used to indent each data item or If COMPACT is specified, then no blank lines are
nested data group or data selection field, left between individual items or nested data
except the first one in the group. The first group headings. If this data group is nested
item or imbedded group within this data item inside another data group for which COMPACT is
group are not indented. All other items, fields, specified, COMPACT is implied for this data
and imbedded groups are indented. Both the group whether it is specified or not.
prompt column and the value column of a
data item or data selection field are indented
by two positions. The group heading of an
Optional Text
nested data group and all items within it are group-heading
indented by two positions. The heading placed above the data items of
The determination of which data items, the group. The text occupies only one line of
selection fields and groups are indented is the panel, but may span several columns.
made when the panel group is created and is The text must appear on the same line or next
unaffected by conditioning. This option pre- line as the tag and can only contain the
sents data items in the same format the reverse text (RT) tag.
control language (CL) prompter uses for quali- If the text is omitted, no lines are allocated on
fied names. Because qualified name the display for a group heading, but the items
indenting of a value would be backward for a between the DATAGRP and EDATAGRP tags
BIDI=RTL panel group, the value column is are processed as a group with respect to keep
not indented when QINDENT is specified for a processing on the display and other UIM oper-
BIDI=RTL panel group. The prompt text of ations.
each item after the first one is still indented.
A colon is added to the end of the text if one
NONE does not indent any data items, data is not already specified and if there is room for
selection fields, or nested data item groups in it.

DATAI Tag
DATAI (Data Item)

55──:DATAI──VAR=dialog-variable-name──USAGE=─┬─OUT───┬───┬───────────────────────┬─────────5
└─INOUT─┘ └─HELP=help-module-name─┘
5──┬─────────────────────┬──┬─────────────────────┬──┬────────────────────┬────────────────5
└─NAME=data-item-name─┘ │ ┌─BEFORE─┐ │ │ ┌─AFTER─┐ │
└─PMTLOC=─┴─ABOVE──┴──┘ └─CHCLOC=─┴─ABOVE─┴──┘
5──┬───────────────────┬──┬─────────────────────┬──┬────────────────────┬──────────────────5
│ ┌─LEFT──┐ │ └─JUSTIFY=─┬─LEFT──┬──┘ │ ┌─NO──┐ │
└─ALIGN=─┼─RIGHT─┼──┘ ├─RIGHT─┤ └─REQUIRED=─┴─YES─┴──┘
├─START─┤ ├─START─┤
└─END───┘ └─END───┘
5──┬──────────────────┬──┬───────────────────┬──┬────────────────────┬─────────────────────5
│ ┌─YES─┐ │ │ ┌─YES─┐ │ │ ┌─NO──┐ │
└─CSRLOC=─┴─NO──┴──┘ └─DISPLAY=─┴─NO──┴──┘ └─AUTOENTR=─┴─YES─┴──┘
5──┬─────────────────────┬──┬──────────────────────┬──┬───────────────────────────────┬────5
└─COND=condition-name─┘ └─PROMPT='action-text'─┘ └─DSPVALUE=dialog-variable-name─┘
5──.──┬────────────────┬──────────────────────────────────────────────────────────────────5%
└─data-item-text─┘
55──:DATAI──VAR=dialog-variable-name──┬───────────┬──┬─────────────────────┬───────────────5
└─USAGE=OUT─┘ │ ┌─BEFORE─┐ │
└─PMTLOC=─┴─ABOVE──┴──┘
5──┬────────────────────┬──┬───────────────────┬──┬─────────────────────┬──────────────────5
│ ┌─AFTER─┐ │ │ ┌─LEFT──┐ │ └─JUSTIFY=─┬─LEFT──┬──┘
└─CHCLOC=─┴─ABOVE─┴──┘ └─ALIGN=─┼─RIGHT─┼──┘ ├─RIGHT─┤
├─START─┤ ├─START─┤
└─END───┘ └─END───┘
5──┬─────────────────────┬──.──┬────────────────┬─────────────────────────────────────────5%
└─COND=condition-name─┘ └─data-item-text─┘
The data item (DATAI) tag defines an item placed The UIM does not allow an individual data item to
in a data presentation area. This tag is allowed be split while scrolling.
for display panels and print panels.
The data item extender (DATAIX) tag can be used

Required Attributes
to specify additional dialog variables, which are VAR=dialog-variable-name
displayed as part of the data item. The data The name of the dialog variable constructing
selection choices (DATAC) tag can be used to the data item. The current value of the dialog
specify possible choices text, which is displayed variable is displayed or printed.
as part of the data item. The DATAIX and
If the item appears in an area with LAYOUT=1
DATAC tag are considered part of the DATAI tag
specified on the data presentation area
with respect to formatting, conditioning, scrolling,
(DATA) tag, its value can exceed the width of
and help.
the choice column. In this case, the value is
presented as a single field that wraps onto as
Note that the prompt, field and extenders, and
many display lines as necessary. If LAYOUT=2
possible choices text must fit within the data area.
is specified on the DATA tag, the width of the
value must fit between the starting position

DATAI Tag
determined from the second data column To provide the user with easy access to the
(DATACOL) tag and the ending position for online information for a LAYOUT=HORIZ data
the layout column. area, use the HELP attribute on the DATA tag
instead of the HELP attribute on the individual
For a data presentation area specified with
DATAI tags in the horizontal area.
LAYOUT=HORIZ, if there are already data items
on the display line and if the length of the The HELP attribute applies to all DATAIX tags
prompt plus the value does not fit on the associated with this data item.
current line and allow a five column separator
NAME=data-item-name
between data items, the prompt and values
The name associated with the item. This
are placed on the next display line. For hori-
name can be used with the Add Pop-Up
zontal layout, the prompt plus the value must
Window (QUIADDPW) API to position a
fit on a single line of the panel.
window near this data item. This attribute is
USAGE=OUT | INOUT allowed only for display panels.
Indicates the display use of the data item.
This attribute is required for display panels
and is optional for print panels.
PMTLOC=BEFORE | ABOVE
USAGE=OUT defines an output data item. OUT
Governs the placement of the variable value
indicates that the variable displayed is for
in relationship to the prompt text for the data
output only and cannot be changed by the
item.
user.
BEFORE indicates that the prompt text is
USAGE=INOUT defines a data entry item.
placed before (to the left of) the variable
INOUT indicates that the variable is for data
value. The variable value begins on the line
entry and can be changed by the user.
the prompt text ended on.
Optional Attributes ABOVE indicates that the prompt text is

placed above the data item variable. The var-
HELP=help-module-name iable is indented two spaces from the begin-
Identifies online information which explains the ning of the prompt text. ABOVE is not
data item. This attribute is allowed only for allowed when LAYOUT=HORIZ is specified on
display panels. The name of the help module the DATA tag.
can be a name imported from another panel
If the prompt text is placed above the data
group, but must follow the rules for names
item variable as a result of ABOVE, the ALIGN
outlined earlier in this chapter. For more infor-
attribute on this tag is not used for formatting.
mation on the rules for names, see “Name
Syntax” on page A-4. All data item extenders placed on a new line
as a result of NEWLINE=CALC or NEWLINE=YES
on the DATAIX tag begin in the same column
as the data item variable.
help applies to all groups and items in the CHCLOC=AFTER | ABOVE
area, and the HELP attribute is not allowed on Governs the placement of the data choices
any data group (DATAGRP) and DATAI tags text in relationship to the variable value for the
in the area. data item.
If the HELP attribute is specified on the AFTER indicates that the data choices text is
DATAGRP tag, the help applies to all data placed after the variable value. This is either
items in the group and the HELP attribute is not on the same line or on the line below the end
allowed on DATAI tags within the group. of the variable value.
If no HELP attribute is specified on the DATA ABOVE indicates that the data choices text is
tag or on DATAGRP tags containing a data placed above the data item variable. ABOVE
item, the HELP attribute is required on the is allowed only if PMTLOC=ABOVE is specified.
DATAI tag.

DATAI Tag
This attribute is not allowed when When REQUIRED=YES is coded, no explicit

LAYOUT=HORIZ is specified on the DATA tag. checks are made for user entry. However,
REQUIRED=YES causes the UIM to do input
This attribute governs placement of data
editing and validity check processing, even if
choices text only for DATAC tags immediately
the user does not enter anything into the field.
following the DATAI tag. DATAC tags fol-
This allows you to use the validity checking
lowing a DATAIX tag are not affected by this
(CHECK) tag to ensure that the user enters
attribute.
data into a required field.
ALIGN=LEFT | RIGHT | START | END
CSRLOC=YES | NO
Governs how the display value of the variable
Indicates whether or not the cursor is allowed
is positioned within the choice column defined
on the input field when the UIM does default
by the second DATACOL tag.
cursor positioning. This attribute is allowed
ALIGN=LEFT positions the leftmost character only for display panels.
of the display value with the left edge of the
YES does not guarantee that the cursor is
choice column.
placed on the input field; it only indicates to
ALIGN=RIGHT positions the rightmost char- the UIM that the cursor may be placed on the
acter of the display value with the right edge input field when the UIM does default cursor
of the choice column. ALIGN=RIGHT is not positioning.
allowed when LAYOUT=HORIZ is specified on
NO indicates that the cursor should not be
the DATA tag. If the width of the display
placed on the field. CSRLOC=NO is intended
value, set by the WIDTH attribute on the class
for input fields such as the position-to field
definition (CLASS) tag, exceeds the width of
found in a data area above a list area. The
the choice column, ALIGN=RIGHT will work the
cursor should not be placed on a position-to
same way as ALIGN=LEFT.
field when the panel is first displayed or after
START is a synonym for LEFT, and END is a a position-to operation completes. When
synonym for RIGHT. CSRLOC=NO is coded, it is still possible for the
UIM to place the cursor on the field when
JUSTIFY=LEFT | RIGHT | START | END
default cursor positioning is performed. This
Governs how the dialog variable is edited into
may occur in the following situations:
the display value. The default for this attribute
is the same value as was specified on the All input fields on the current page of the
ALIGN attribute for this tag. panel are marked with CRSLOC=NO.
For JUSTIFY=LEFT, the dialog variable is left- The input field is marked in error.
justified into the display value and leading
The cursor positioning under an applica-
blanks are preserved.
tion program's control specifies that the
For JUSTIFY=RIGHT, the dialog variable is cursor should be placed on the field.
right-justified into the display value and trailing
blanks are stripped. The CSRLOC attribute applies to all DATAIX
tags associated with this data item.
START is a synonym for LEFT, and END is a
synonym for RIGHT. DISPLAY=YES | NO
Indicates whether or not the contents of the
REQUIRED=NO | YES field are visible when the panel is displayed.
Indicates whether or not the item is required. This attribute is allowed only for display
This attribute is allowed only for display panels.
panels. NO indicates that the item is not
required. YES indicates that the field is visible.
YES indicates that the item is required on the NO indicates that the field is not visible.
display and that the field is highlighted accord- DISPLAY=NO is intended for input fields, such
ingly. YES is only valid if USAGE=INOUT is as a password field, which should not be
specified on this tag for the data item. visible.

DATAI Tag
AUTOENTR=NO | YES attribute used to define the function key. This

Indicates whether or not the field is an auto- updating is independent of the display value
matic enter input field. This attribute is variable processing.
allowed only for display panels. An automatic
The dialog variable specified must be defined
enter input field returns from the device to the
on the CLASS tag as a CHAR or IGC variable
host when the user enters a character,
whose length is the same as the width of the
including a blank, into the last position of the
dialog variable specified on the VAR attribute of
field. This has the same effect as the user
this tag. No translation list processing or
pressing the Enter key.
value checking is performed for the value
NO indicates that the field is not an automatic before it is placed in this variable. Character
enter field. set and code page conversion are performed
for this variable if the class of the variable
YES indicates that the field is an automatic
named on the VAR attribute of this tag speci-
enter field. If YES is specified, USAGE=INOUT
fies that character set and code page conver-
must also be specified on this tag.
sion should be performed.
Although the UIM does not restrict its usage,
AUTOENTR=YES is intended for input fields that
are one character wide.
Optional Text
data-item-text
COND=condition-name
The text describing the data item. The text
The item is in effect on a display only if the
may appear on more than one line and can
condition specified is true. All associated
only contain the reverse text (RT) tag.
DATAC and DATAIX tags are displayed only if
this data item appears on the display. The If the item appears in a data item group, it is
condition must be defined in the panel group indented as specified by the GRPSEP attribute
with the condition definition (COND) tag. on the DATAGRP tag. If the text is too long
to fit in the prompt column, it is formatted onto
PROMPT='action-text' additional lines as necessary to fit within the
The action occurring when F4=List is item column and is indented two spaces.
requested through the PROMPT dialog
command. This attribute is allowed only for If no text is specified, the data value appears
display panels. The PROMPT attribute is only without a prompt. Prompt text should be
allowed when USAGE=INOUT is specified for specified for all DATAI tags, except for the fol-
this data item. The valid forms of action-text lowing special cases:
are: When the data item is described com-
'CALL program-reference' pletely by the instruction or group heading
For a description of the interface between text appearing above the item.
the UIM and the exit program for the When the data item contains a value that
cursor-sensitive prompt, see the System is a logical continuation of the value for a
API Reference. data item appearing immediately before it
'RETURN positive-integer' in the panel. Conditioning may be used to
present only as many lines on the panel
For a description of these actions, see as there are values available.
Appendix B, “UIM Dialog Commands” on
The set of DATAI tags presenting this type
page B-1.
of information should always be specified
DSPVALUE=dialog-variable-name in a data group to ensure that the UIM
The dialog variable containing the current data keeps related values together on the
entered in this data item. This attribute is display, and to present appropriate infor-
allowed only for display panels and when the mation in extended help for the panel.
PROMPT attribute is coded on this tag. This Prompt text should be specified for the
variable is updated regardless of whether or first data item in the group, or heading text
not VARUPD processing is performed. The vari- should be specified on the DATAGRP tag
able pool is updated based on the VARUPD to describe the entire group. Help should

DATAI Tag
be specified for the group or for the entire columns or even on different scrollable
area. pages. If the same help module is speci-
fied for multiple data items, extended help
When data groups are not used, the UIM
for the panel repeats the online informa-
may present items in different layout
tion for each item on the panel.

DATAIX Tag
DATAIX (Data Item Extender)

55──:DATAIX──VAR=dialog-variable-name──USAGE=─┬─OUT───┬───┬────────────────────┬───────────5
└─INOUT─┘ │ ┌─CALC─┐ │
└─NEWLINE=─┼─NO───┼──┘
└─YES──┘
5──┬────────────────────────────────────┬──┬───────────────────┬───────────────────────────5
│ ┌─2────────────────────┐ │ │ ┌─LEFT──┐ │
└─ITEMSEP=─┴─item-separator-value─┴──┘ └─ALIGN=─┼─RIGHT─┼──┘
├─START─┤
└─END───┘
5──┬─────────────────────┬──┬────────────────────┬──┬───────────────────┬──────────────────5
└─JUSTIFY=─┬─LEFT──┬──┘ │ ┌─NO──┐ │ │ ┌─YES─┐ │
├─RIGHT─┤ └─REQUIRED=─┴─YES─┴──┘ └─DISPLAY=─┴─NO──┴──┘
├─START─┤
└─END───┘
5──┬──────────────────────┬──┬───────────────────────────────┬──┬────────────────────┬─────5
└─PROMPT='action-text'─┘ └─DSPVALUE=dialog-variable-name─┘ │ ┌─NO──┐ │
└─AUTOENTR=─┴─YES─┴──┘
5──.──────────────────────────────────────────────────────────────────────────────────────5%
55──:DATAIX──VAR=dialog-variable-name──┬───────────┬──┬────────────────────┬───────────────5
└─USAGE=OUT─┘ │ ┌─CALC─┐ │
└─NEWLINE=─┼─NO───┼──┘
└─YES──┘
5──┬────────────────────────────────────┬──┬───────────────────┬───────────────────────────5
│ ┌─2────────────────────┐ │ │ ┌─LEFT──┐ │
└─ITEMSEP=─┴─item-separator-value─┴──┘ └─ALIGN=─┼─RIGHT─┼──┘
├─START─┤
└─END───┘
5──┬─────────────────────┬──.─────────────────────────────────────────────────────────────5%
└─JUSTIFY=─┬─LEFT──┬──┘
├─RIGHT─┤
├─START─┤
└─END───┘
The data item extender (DATAIX) tag provides an are specified determines where they appear in
additional dialog variable to be associated with a relationship to the dialog variable of the DATAI
data item (DATAI) tag. This tag is allowed for tag.
display panels and print panels.
The DATAIX tags must appear after the corre-

Required Attributes
sponding DATAI tag. More than one DATAIX tag VAR=dialog-variable-name
may be specified after the DATAI tag to provide The name of the additional dialog variable dis-
several dialog variables. If no DATAIX tags are played with the previous DATAI tag. The
entered, only one dialog variable, specified on the current value of the dialog variable is dis-
DATAI tag, appears for the data item. played or printed.
For a LAYOUT=1 data presentation area, the
The DATAIX and data choices (DATAC) tags can
display value can exceed the width of the
be specified in any order. The order in which they

DATAIX Tag
panel. In this case, the value is presented as display or print line. It is positioned according
a single field that wraps onto as many lines as to the ALIGN attribute of this tag.
necessary. For a LAYOUT=2 data presentation
When NEWLINE=CALC is specified in a data
area, the display value must fit on one line.
presentation area with LAYOUT=HORIZ speci-
For a LAYOUT=HORIZ data presentation area, fied, the value is placed on the same line as
the data item prompt, value, and all DATAIX the previous value.
values must all fit on a single line of the panel.
NEWLINE=NO indicates that the value should
If there are already data items on one line of
be placed on the same line and to the right of
the panel and if the prompt text and dialog
the previous value. The previous value is the
variable for the DATAI tag plus the value of
dialog variable for either the DATAI tag or a
this dialog variable do not fit on the current
previous DATAIX tag. If the DATAIX tag
line and still allow a five-column separator
appears immediately after a DATAC tag,
between data items, the entire data item,
NEWLINE=NO is not allowed.
including this item extender, are placed on the
next line of the panel. NEWLINE=YES indicates that the value should
be placed on the next display or print line.
USAGE=OUT | INOUT NEWLINE=YES is not allowed for data presenta-
The display use of the data item. This attri- tion areas with LAYOUT=HORIZ specified.
bute is required for display panels but is
optional for print panels. ITEMSEP=2 | item-separator-value
Indicates how many spaces separate the
USAGE=OUT defines an output data item. OUT
dialog variable of this data item extender and
indicates that the variable displayed is for
the previous dialog variable.
output only and cannot be changed by the
user. For data presentation areas with LAYOUT=1 or
LAYOUT=2, the maximum value for this attribute
USAGE=INOUT defines a data entry item.
is the width of the choice column, as defined
by the second DATACOL tag. For data pres-
entation areas with LAYOUT=HORIZ specified,
the maximum value for this attribute is 5. The
Optional Attributes default value is 2, and the minimum value is
1.
NEWLINE=CALC | NO | YES
Governs the placement of the variable for the The ITEMSEP attribute is not allowed when
data item extender in relationship to the vari- NEWLINE=YES is specified on this tag, and has
able value for the data item, possible choices no effect when NEWLINE=CALC is specified
text, and previously-defined data item and the extender variable is placed on a new
extenders. line.
NEWLINE=CALC indicates that the UIM deter- ALIGN=LEFT | RIGHT | START | END
mines the placement of the variable. The var- Governs how the display value is positioned
iable is placed on the same line as the within the choice column defined by the
previous dialog variable if all of the following second DATACOL tag.
conditions are true:
If the dialog variable is preceded by the dialog
The variable fits within the value column, variable for the DATAI tag or by a previous
defined by the second data column DATAIX tag, the ALIGN attribute has no effect
(DATACOL) tag of the current line. on the position of the display value within the
choice column.
The DATAIX tag is not immediately fol-
lowed by a DATAC tag. If the dialog variable is the first variable on the
display or print line, the ALIGN attribute formats
The current line is not wrapped from the
text as follows:
previous line
ALIGN=LEFT positions the leftmost char-
If any of the above conditions are not true, the
acter of the display value with the left
data item extender is placed on the next
edge of the choice column.

DATAIX Tag
ALIGN=RIGHT positions the rightmost as a password field, which should not be

character of the display value with the visible.
right edge of the choice column. If the
PROMPT='action-text'
width of the display value exceeds the
The action occurring when F4=List is
width of the choice column, ALIGN=RIGHT
requested through the PROMPT dialog
works the same as ALIGN=LEFT.
command. This attribute is allowed only for
ALIGN=RIGHT is not allowed for data presen- display panels, and when USAGE=INOUT is
tation areas with LAYOUT=HORIZ specified. specified on this tag for this data item
extender. The valid forms of action text are:
START is a synonym for LEFT and END is a
synonym for RIGHT. 'CALL program-reference'
For a description of the interface between
the UIM and the exit program for the
Governs how the dialog variable is edited into
cursor-sensitive prompt, see the System
the display value. The default for this attribute
API Reference.
is the same value as was specified or
defaulted to on the ALIGN attribute of this tag. 'RETURN positive-integer'
For JUSTIFY=LEFT, the dialog variable is left- For a description of these actions, see
justified into the display value. Leading blanks Appendix B, “UIM Dialog Commands” on
are preserved. page B-1.
For JUSTIFY=RIGHT, the dialog variable is DSPVALUE=dialog-variable-name
right-justified into the display value and trailing The dialog variable containing the current data
blanks are stripped. entered into this data item extender. This
START is a synonym for LEFT and END is a attribute is allowed only for display panels and
synonym for RIGHT. when the PROMPT attribute is coded on this tag.
The JUSTIFY attribute is ignored for variables This variable is updated regardless of whether
defined as UCS-2. or not VARUPD processing is performed. The
variable pool is updated based on the VARUPD
REQUIRED=NO | YES attribute used to define the function key. This
NO indicates that the item is not required. updating is independent of the display value
This attribute is allowed only for display variable processing.
panels.
The dialog variable specified must be defined
YES indicates that the item is required on the on the class definition (CLASS) tag as a
display and that the field is highlighted accord- CHAR or IGC variable whose length is the
ingly. YES is only valid if USAGE=INOUT is same as the width of the dialog variable speci-
specified for the data item extender. fied on the VAR attribute of this tag.
When REQUIRED=YES is coded, no explicit No translation list processing or value
checks are made for user entry. checking is performed for the value before it is
REQUIRED=YES causes the UIM to perform placed in this variable. Character set and
input editing and validity check processing, code page conversion are performed for this
even if the user does not enter anything into variable if the class of the variable named on
the field. This allows you to use the validity the VAR attribute of this tag specifies that char-
checking (CHECK) tag to ensure that the user acter set and code page conversion should be
enters data into a required field. performed.
DISPLAY=YES | NO AUTOENTR=NO | YES
Indicates whether or not the field is visible Indicates whether or not the field is an auto-
when the panel is displayed. This attribute is matic enter input field. This attribute is
allowed only for display panels. YES indi- allowed only for display panels. An automatic
cates that the field is visible. enter input field returns from the device to the
NO indicates that the field is not visible. host when the user enters a character,
DISPLAY=NO is intended for input fields such including a blank, into the last position of the

DATAIX Tag
field. This has the same effect as the user YES indicates that the field is an automatic
pressing the Enter key. enter field. If YES is specified, USAGE=INOUT
must also be specified on this tag. Although
NO indicates that the field is not an automatic
the UIM does not restrict its usage,
enter field. This is the default value.
AUTOENTR=YES is intended for input fields that
are one character wide.

DATASLT tag
DATASLT (Data Selection Field)
55──:DATASLT──TYPE=─┬─SINGLE─┬───┬──────────────────────────┬────────────────────────────5
└─MULTI──┘ └─VAR=dialog-variable-name─┘
5──┬───────────────────────┬──┬───────────────────────────┬──┬─────────────────────┬─────5
└─HELP=help-module-name─┘ └─NAME=selection-field-name─┘ └─PMTLOC=─┬─BEFORE─┬──┘
└─ABOVE──┘
5──┬────────────────────┬──┬─────────────────────┬──┬─────────────────────┬──.───────────5
└─REQUIRED=─┬─NO──┬──┘ └─AUTOENTER=─┬─NO──┬──┘ └─COND=condition-name─┘
└─YES─┘ └─YES─┘
5──┬─────────────────────────────┬──:EDATASLT.──────────────────────────────────────────5%
└─selection-field-prompt-text─┘
The data selection field (DATASLT) tag defines a Table A-6. Tag Allowed Between the DATASLT and
selection field in the data presentation area. This EDATASLT Tags
tag is allowed only for display panels. Tag Name Order Use Page
DATASLTC 1 D A-55
The DATASLT may be a single- or multiple-choice
(Data selection
selection field. The selection field is fixed in field choice)
content and number of choices. A data selection
field can only be specified when LAYOUT=1 or 2 on
the data presentation area (DATA) tag. Required Attributes
The data selection field choice (DATASLTC) tag TYPE=SINGLE | MULTI
specifies the choices for the selection field. The Specifies whether or not the selection field is
DATASLTC tag is part of the DATASLT tag with a selection field for single or multiple choices.
respect to formatting, conditioning, scrolling, and SINGLE indicates that the selection field is for
help. a single choice.
The prompt, field, and choices must fit within the MULTI indicates that the selection field is for
data area. The UIM does not allow a selection multiple choices.
field to be split while scrolling.
Optional Attributes
Other tags can be nested within the DATASLT
tag. These tags are listed in the following table. VAR=dialog-variable-name
The table defines the order in which the tags must The name of the dialog variable used to con-
appear, indicates which tags can be used in struct the single-choice selection field. This
display panels only, print panels only, or both attribute is required for TYPE=SINGLE. The
(specified by a D, P, or B, respectively), and spec- variable is presented on the display if
ifies on which page more information can be found TYPE=SINGLE, and must be declared with a
for each tag. BASETYPE of BIN(31) on the class definition
(CLASS) tag. This variable contains the
When more than one tag is listed with the same option number of the choice selected by the
order number, all tags of that number can be user. If no choices are selected, the variable
mixed in any order. However, a tag with a higher returns a zero. The current value of the
order number cannot precede a tag with a lower dialog variable is presented on the display.
order number. For example, a tag with an order If TYPE=MULTI is specified on this tag, this
number of three cannot precede a tag with an attribute is not allowed.
order number of one or two.
HELP=help-module-name
Identifies online information explaining the
purpose of the data selection field. The name

DATASLT tag
of the help module may be a name imported explicit checks are made for user entry.
from another panel group, but the name must However, YES causes the UIM to perform
follow the rules for names outlined earlier in input editing and validity check processing
this chapter. For more information on the even if the user does not enter anything into
rules for names, see “Name Syntax” on the field. This allows you to use the validity
page A-4. checking (CHECK) tag to ensure that the user
enters data into a required field.
REQUIRED=YES cannot be specified when
TYPE=MULTI is specified on this tag.
help applies to all groups and items in the AUTOENTR=NO | YES
area, and the HELP attribute is not allowed on Indicates whether or not the field is an auto-
any data group (DATAGRP) and DATASLT matic enter input field. An automatic enter
tags in the area. input field returns the screen from the device
If the HELP attribute is specified on the to the host when the user enters a character,
DATAGRP tag, the help applies to all data including a blank, into the last position of the
selection fields in the group, and the HELP field. This has the same effect as the user
attribute is not allowed on DATASLT tags pressing the Enter key.
within the group. NO indicates that the field is not an automatic
If no HELP attribute is specified on the DATA enter field. This is the default value.
tag nor on DATAGRP tags containing a data YES indicates that the field is an automatic
selection field, the HELP attribute is required on enter field. Although the UIM does not restrict
the DATASLT tag. its usage, AUTOENTR=YES is intended to be
used only on input fields that are one char-
NAME=selection-field-name
acter wide. YES is not allowed when
The name associated with the selection field.
TYPE=MULTI is specified on this tag.
This name can be used later with the Add
Pop-Up Window (QUIADDPW) API to position COND=condition-name
a window associated with this selection field. The selection field is displayed only if the con-
For more information on the rules for naming, dition specified is true. Associated
see “Name Syntax” on page A-4. DATASLTC tags are displayed only if this
selection field appears on the display. The
PMTLOC=BEFORE | ABOVE
condition must be defined in the panel group
Governs the placement of the prompt text in
with the condition definition (COND) tag.
relationship to the input field associated with
the selection field.
BEFORE indicates that the prompt text is
Optional Text
placed before (to the left of) the variable value selection-field-prompt-text
of the data field. The variable value begins on The text which describes the selection field.
the same line on which the prompt text ended. The text may appear on more than one line
BEFORE is the default. and can contain only the reverse text (RT)
tag. The length of the text is 255 bytes or
ABOVE indicates that the prompt text is
less.
placed above the data item variable. The var-
iable is indented two spaces from the begin- If the selection field appears in a data item
ning of the prompt text. group, it is indented as specified by the
GRPSEP attribute on the DATAGRP tag. If the
REQUIRED=NO | YES
text is too long to fit in the prompt column, it is
This attribute is allowed only for
formatted on the following lines as necessary
TYPE=SINGLE. NO indicates that the field is
to fit within the column and indented two
not required. NO is the default value.
spaces from the beginning of the first line.
YES indicates that the field is required on the
If no text is specified, the selection field
display, and the field is highlighted accord-
appears without a prompt. Prompt text should
ingly. When REQUIRED=YES is coded, no
be specified for all DATASLT tags, except for

DATASLT tag
when the selection field is described com- .Essay standard (proportional)

pletely by the instruction or group heading text :datasltc help=hstyleeb
appearing above the item. option=4
.Essay bold (proportional)
:edataslt.
Example 1: Data Entry Panel :dataslt type=single
help=hduplx
The example shows a sample data entry panel. var=duplex
The panel has 2 selection fields with the defaults .Duplex
supplied by the calling program by previously :datasltc help=hduplxy
setting the dialog variables for the function. option=1
.Print both sides of paper
UIM Source :datasltc help=hduplxn
option=2
:class name=select .Print one side only
basetype='bin 31'. :edataslt.
:var name=prtstyle :edata.
class=select. :epanel.
:var name=duplex :invellip.
class=select.
..
.
:panel name=entry1
Results
help=hentry1
topsep=space à Sample Entry Panel
ð
... Type choices, press Enter.
.Sample Entry Panel Type style for printing . . . 1 1. Prestige elite
:data depth='\' 3. Essay standard (proportional)
4. Essay bold (proportional)
bodysep=both. Duplex . . . . . . . . . . . 1 1. Print both sides of paper
:topinst.Type choices, press Enter. 2. Print one side only
:datacol width=3ð.
:datacol width='\'.
:dataslt help=hstyle In this example, the PRTSTYLE and DUPLEX
var=prtstyle dialog variables must be BIN 31, and the option
type=single value selected is returned to the calling program in
.Type style for printing these variables.
:datasltc help=hstylep
option=1 Example 2: Multiple-Selection
.Prestige elite (12 pitch)
:datasltc help=hstylec Field
option=2
.Courier (1ð pitch) This example shows a multiple-selection field.
:datasltc help=hstylees The user selects the values by typing a slash (/)
option=3 or the country-designated character into the entry
field preceding the desired options. More than
one heading option may be selected.

DATASLT tag
UIM Source help=hsecn.Section numbers

:datasltc var=heoptstm
:class name=sfield help=htime.Time
basetype='char 1'. :datasltc var=hdoptsdt
:var name=hdoptsb help=hdate.Date
class=sfield. :edataslt.
:var name=hdoptsu :edata.
class=sfield.
:var name=hdoptsuc
class=sfield. Results
:var name=hdoptssn
class=sfield. à ð
Heading Options
:var name=hdoptstm System: xxxxxxxx
Select one or more choices, press Enter.
class=sfield. Heading options . . . . . . . _ Bold
:var name=hdoptsdt _
_
Underline
Uppercase
class=sfield. _
_
Section numbers
Time
_ Date
:panel name=xxx
keyl=x1.Heading Options
:data depth='\'
bodysep=both. If the user chooses Underline, Section numbers,
:topinst.Select one or more and Date in this example, the value in the dialog
choices, press Enter. variables are:
:datacol width=3ð.
hdoptsb=0
:datacol width='\'.
:dataslt type=multi hdoptsu=1
help=haward.Heading options hdoptsuc=0
:datasltc var=hdoptsb hdoptssn=1
help=hbold.Bold hdoptstm=0
:datasltc var=hdoptsu hdoptsdt=1
help=hundl.Underline
:datasltc var=hdoptsuc
help=hupperc.Uppercase
:datasltc var=hdoptssn

DATASLTC tag
DATASLTC (Data Selection Field Choice)
55──:DATASLTC──┬─────────────────────────────┬──┬──────────────────────┬─────────────────5
└─CHOICE=dialog-variable-name─┘ └─OPTION=option-number─┘
5──┬──────────────────────────┬──┬───────────────────────┬──┬─────────────────────┬──────5
└─VAR=dialog-variable-name─┘ └─HELP=help-module-name─┘ └─COND=condition-name─┘
5──┬──────────────────────┬──┬─────────────────────────────┬─────────────────────────────5
└─AVAIL=condition-name─┘ └─AVLMSGID=message-identifier─┘
5──┬───────────────────────────────────────┬──.──┬──────────────────┬───────────────────5%
└─AVLMSGF='qualified-message-file-name'─┘ └─text-for-choices─┘
The data selection field choice (DATASLTC) tag acter to the left to preserve vertical alignment
defines a possible choice for a single- or multiple- with data choices on other lines.
choice selection field. This tag is allowed only for
OPTION=option-number
display panels. It is not valid if LAYOUT=HORIZ is
The number assigned to this option. Option
specified on the data presentation area (DATA)
numbers are integers in the range of 1 to 99.
tag for the area.
This attribute is required if specified within a
The DATASLTC tags must appear after the corre- DATASLT tag that has TYPE=SINGLE speci-
sponding data selection field (DATASLT) tag and fied, but cannot be used if TYPE=MULTI is
at least one DATASLTC tag must be specified specified.
between the DATASLT and the EDATASLTC tags. Selection field choices are displayed in the
The DATASLTC tag defines the choices for the order defined in the selection field. If the
selection field. numbering of two choices is not consecutive,
a blank line is automatically placed between
Optional Attributes the two choices. If two choices have the
same option number and both are
CHOICE=dialog-variable-name conditioned-on at the same time, the choice
The name of a dialog variable containing the defined first is displayed.
possible choices text to be displayed. The
dialog variable must be defined so that the VAR=dialog-variable-name
text fits on a single line. The name of the dialog variable used to indi-
cate whether or not the selection field choice
Dialog variables must be defined with a is selected. This attribute is required for
BASETYPE of CHAR, IGC, or BIN on the class TYPE=MULTI. The variable must be declared
definition (CLASS) tag. with a BASETYPE of CHAR 1 on the CLASS
The error state of the dialog variable is not tag.
used for determining the highlighting of the If the choice is not selected, the value of the
text. dialog variable is '0'. If the choice is selected,
If the CHOICE attribute is specified, the text-for- a value of '1' is returned in the dialog variable.
choices cannot be specified. If the current value of the variable is '1' when
the screen is displayed, a slash (/) is dis-
Special formatting for IGC. (The abbrevi-
played on the screen. The user may enter
either a slash or the country-designated char-
to represent double-byte character set func-
acter and a '1' is returned to the user. Which-
tions.) When a dialog variable with a
ever character is used for selection by the
user is shown when the panel is redisplayed.
If the current value of the dialog variable is
variable value begins with a shift-out character
something other than '1' when the panel is
(X'0E'), the UIM shifts the value one char-
displayed, the variable is presented as unse-
lected.

DATASLTC tag
The VAR attribute is required if TYPE=MULTI on for the choice is not included in requests to
the DATASLT tag. If TYPE=SINGLE is speci- display help.
fied, the VAR attribute is not allowed.
AVAIL=condition-name
HELP=help-module-name The name of a condition indicating whether or
Identifies online information explaining the not the selection field choice is available. The
purpose of the selection field choice. The condition must be defined in the panel group
name of the help module may be a name prolog with the COND tag.
imported from another panel group, but must
When the condition is true, the selection field
follow the rules for names outlined earlier in
choice is available. When the condition is
this chapter. For more information on the
false, the selection field choice is not avail-
rules for names, see “Name Syntax” on
able. Any condition specified on the COND
page A-4.
attribute on this tag takes precedence over
This attribute is allowed only when the HELP this attribute.
attribute is specified on the DATASLT tag that
Unavailable choices are displayed with a color
contains this DATASLTC tag.
change and an asterisk (*) overlaying the first
If the HELP attribute is specified on a part of the choice option number.
DATASLTC tag within a selection field, all
The AVAIL attribute cannot be specified if the
DATASLTC tags within that selection field
selection field is specified as TYPE=MULTI on
must have the HELP attribute specified.
the DATASLT tag.
For multiple-choice selection fields with
AVLMSGID=message-identifier
SELECT=MULTI specified on the DATASLT tag,
The message identifier of the message dis-
the online information identified by this attri-
played when the selection field choice is
bute is included as part of the contextual help
selected when it is not available as specified
displayed when the cursor is positioned any-
by the AVAIL attribute on this tag. This attri-
where within the selection field.
bute is allowed only when the AVAIL attribute
For single-choice selection fields with is specified.
SELECT=SINGLE specified on the DATASLT
If this attribute is not specified, the UIM dis-
tag, the online information identified by this
plays a default message stating that the
attribute is displayed when help is requested
choice is not currently available.
while the cursor is positioned on the choice
text for this tag. This online information is AVLMSGF='qualified-message-file-name'
also included as part of the contextual help The message file name containing the
displayed when the cursor is positioned within message identifier. This attribute is allowed
the selection field but not on the text for one when the AVLMSGID attribute on this tag is
of the choices within the field. This includes specified. If the DFTMSGF attribute is not speci-
when the cursor is positioned on the prompt fied on the panel group (PNLGRP) tag and
text for the selection field or in the entry field the AVLMSGID attribute on this tag is specified,
for the selection field. If the cursor is in the this attribute must be specified.
entry field and a valid choice is entered, when
help is requested, the help for that choice is
displayed.
Optional Text
text-for-choices
COND=condition-name
This text is an implied paragraph. When the
The selection field choice is in effect on the
display is formatted, any text that does not fit
panel only if the condition specified is true.
onto one line is formatted on the following
The condition must be defined in the panel
lines and indented two columns. The text can
group prolog with the condition definition
be a maximum of 255 characters and can only
(COND) tag. When the choice is
contain the reverse text (RT) tag. Text-for-
conditioned-off, the selection field choice does
choices is required unless the CHOICE attribute
not appear in the selection field and the help
is specified on this tag.

DL, DT, DD, DTHD, DDHD Tags
DL (Definition List)
55──:DL──┬─────────┬──.──┬──────────────────────────────┬──┬─────────────────────────┬───5
└─COMPACT─┘ └─:DTHD.definition-term-header─┘ └─:DDHD.definition-header─┘
┌──
─────────────────────────────────────┐
5───6─:DT.definition-term──:DD.definition─┴──:EDL.───────────────────────────────────────5%
The definition list (DL) is a list of words or phrases Table A-7. Tags Allowed Between the DL and EDL
and their corresponding definitions, descriptions, Tags
or explanations. This tag requires a matching end Tag Name Order Use Page
tag. A definition list is only allowed in information
LINES 1 B A-77
areas and help areas. (Unformatted
lines)
The terms being defined and their definitions are
identified by the definition term (DT) tag and the XMP 1 B A-171
(Example)
definition description (DD) tag. A heading for the
column of terms and the column of definitions can NT 1 B A-117
be identified by the definition term heading (Note)
(DTHD) tag and the definition description heading P 1 B A-121
(DDHD) tags, respectively. (Paragraph)
PC 1 B A-131
Definition lists can occur anywhere in text; they (Paragraph con-
can be nested within other lists or definition lists, tinuation)
and other lists can be nested within definition lists.
LP 1 B A-107
(List part)
Two DT or DD tags cannot be used consecutively.
OL 1 B A-118
Other tags can be nested within the DL tag. (Ordered list)
These tags are listed in the following table. The SL 1 B A-152
table defines the order in which the tags must (Simple list)
appear, indicates which tags can be used in UL 1 B A-164
display panels only, print panels only, or both (Unordered list)
(specified by a D, P, or B, respectively), and spec-
PARML 1 B A-129
ifies on which page more information can be found
(Parameter list)
for each tag.
DL 1 B A-57
When more than one tag is listed with the same (Definition list)
mixed in any order. However, a tag with a higher
order number cannot precede a tag with a lower
Optional Attribute
order number. For example, a tag with an order COMPACT
number of three cannot precede a tag with an Formats the list without the blank line between
order number of one or two. the items.
Table A-7. Tags Allowed Between the DL and EDL

Tags Required Tags
Tag Name Order Use Page DT.definition-term
FIG 1 B A-59 The text for the definition term. The term
(Figure) formats the way it is entered, in highlight
phrase 2 (HP2).

DL, DT, DD, DTHD, DDHD Tags
The term is assumed to be 10 single-byte Results

character set (SBCS) characters or 4 double-
byte character set (DBCS) characters, and Term Description
starts at position 2 relative to the left margin. DL This is a sample definition list
If the term is longer than the assumed number term and description.
of characters, it is extended into the
EDL Here is another.
description line.
DD.definition Example 2: Compact Definition

The text for the definition. The description of
the term is an implied paragraph and can
List
contain text items. Additional paragraphs can This is a definition list using the COMPACT attribute.
be inserted following the description para-
graph, using the paragraph (P) tag.
UIM Source
The description starts at position 14 relative to
:DL compact.
the left margin, unless the term extends into
:DT.COMPACT
the description area.
:DD.This causes the list
to be compacted, so the
blank lines are removed.
Optional Tags :DT.ANOTHER
:DD.Here is another.
DDHD.definition-header
:EDL.
The text for the definition header. The header
formats the way it is entered, in highlight
phrase 2 (HP2). Results
COMPACT This causes the list to be
DTHD.definition-term-header
compacted, so the blank lines are
The text for the definition term header. The
removed.
header formats the way it is entered, in high-
ANOTHER Here is another.
light phrase 2 (HP2).
Care should be taken when using unformatted
Example 1: Definition List lines (LINES), figure (FIG), and example (XMP)
tags within a definition list, because text that does
This example illustrates how a definition list with not fit on one line wraps to column one of the next
headings will format. line. Lines and figures start at the current left
margin and examples are indented four spaces
UIM Source from the current left margin. The current left
:DL. margin changes when nested lists are formatted.
:DTHD.Term If there is an information source containing the
:DDHD.Description LINES, FIG, or XMP tag imbedded at various
:DT.DL locations, including within lists, it may not look the
:DD.This is a sample same each time.
definition list term
and description.
:DT.EDL
:DD.Here is another.
:EDL.

FIG, FIGCAP Tags
FIG (Figure)
55──:FIG──┬──────────────────┬──.──figure-content──┬─────────────────────────────┬───────5
│ ┌─RULE─┐ │ └─:FIGCAP.figure-caption-text─┘
└─FRAME=─┴─NONE─┴──┘
5──:EFIG.───────────────────────────────────────────────────────────────────────────────5%
The figure (FIG) tag identifies a diagram, chart, or NONE indicates that no frame is used; a blank
other illustration. This tag requires a matching line is placed ahead of and behind the figure.
end tag. The figure tag is only allowed in informa-
tion areas and help areas. A figure can also Optional Tag
contain a figure caption, which is identified by the
figure caption (FIGCAP) tag. FIGCAP.figure caption text
A caption for the figure, if needed. The
Figures turn off automatic formatting, so the text is caption may appear on more than one line in
formatted the same way it is entered. The figure the source. The FIGCAP tag must appear
formats where it is entered, across the full width of immediately before the EFIG tag.
the screen or window.
Care should be taken when using figures within

Example: Sample Figure
lists, because figure text that does not fit on one This example shows how text formats the way it is
line wraps to column one of the next line. entered with a FIG tag, and how a FIG tag can
specify a frame to set the figure off from the rest
Figures are always formatted with the left margin
of the text.
set to column 2. The formatting width is two
columns less than the width specified on the help
module. When the FIG tag appears in an informa- UIM Source
tion area, the formatting width initially is two bytes :FIG frame=rule.
less than the width specified on the panel tag. some
sample
The figure caption begins at the left margin. text
There are two spaces between the figure tag, :FIGCAP.A Sample Figure
"Figure:", and the figure caption text if either the :EFIG.
figure tag or the figure caption text are single-byte
characters. There are four spaces between the Results
figure tag and the figure caption if both are
double-byte characters. If the figure caption does
not fit on one line, it wraps onto the second line some
starting at position 4 relative to the left margin. sample
text
Figure: A Sample Figure
Optional Attribute
FRAME=RULE | NONE
The type of frame to put around the figure.
RULE is the default. A row of hyphens is dis-
played above and below the figure.

HELP Tag
HELP (Help Module)
55──:HELP──NAME=help-module-name──┬───────────────────────────────┬──────────────────────5
│ ┌─'\'───────────────┐ │
└─WIDTH=─┴─help-window-width─┴──┘
5──┬───────────────────────────────┬──.──┬─────────────────┬──:EHELP.───────────────────5%
│ ┌─'\'───────────────┐ │ └─help-title-text─┘
└─DEPTH=─┴─help-window-depth─┴──┘
The help module (HELP) tag indicates the begin- The maximum length of the value for the NAME
ning of a help module. An EHELP tag must be attribute is 32 characters. A slash (/) can be
specified at the end of the help module. A help used in the name as a delimiter or separator
module can be used for help displays and for character. The slash is used to separate a
index search topics. For more information on the command name from a parameter name when
index search function, see “ISCH (Index Search)” naming a help module for commands. If the
on page A-70. Help modules may also be linked slash is used, the name must be enclosed in
to each other. For more information on how help apostrophes ('). Help modules may not be
modules may be linked together, see “LINK nested.
(Hypertext Link Definition)” on page A-78.
Any tag that has a HELP attribute may refer to this

Optional Attributes
module. WIDTH='*' | help-window-depth
The width of the help window when it is dis-
Required Attribute played. A value specified for the WIDTH attri-
bute must include 2 bytes of space for the
NAME=help-module-name right and left margin. The minimum width is
The name of this help module. For more 32 bytes, and the maximum width is 74 bytes.
information on the rules for naming, see
Help modules that are displayed as full screen
or in an extended help window are indented
This name can be referred to from: by 4 bytes. Therefore, the formatting width is
6 bytes less than the width. For example, a
The HELP attribute on UIM panel definition
help module formatted with the maximum
tags.
width of 74 bytes has a formatting width of 68
The NAME attribute on an import (IMPORT) bytes.
tag.
The UIM does not increase or decrease the
The NAME attribute on an imbed help width of the window if a value other than '*' is
(IMHELP) tag within another help module. specified. The width should be specified only
if the text between the HELP and EHELP tags
The TOPICS attribute on an index search
depends on a window of a particular width.
subtopic (ISCHSUBT) tag.
If the help is for the function keys or a list
The HLPPNLGRP keyword in data
area and if WIDTH='*', the UIM uses a width of
description specifications (DDS) specifica-
38 bytes. If the help is for a menu area or
tions.
data area, the UIM uses a width of 60 bytes.
A control language (CL) command defi- The UIM finds a location for the window using
nition. this width, then expands the window to a size
The help identifier array parameter on the which displays the online information in the
Display Help (QUHDSPH) API. most appropriate fashion.
The DSPHELP dialog command. The width used is that of the first HELP tag
found when the UIM assembles the online
help information.

HELP Tag
DEPTH='*' | help-window-depth requested and whether the help is displayed

The depth of the help window when it is dis- as a full screen or in a pop-up window.
played. The value specified for the depth may
Help information presented in pop-up windows
not be less than nine lines, and must include
is titled as follows:
the following:
For contextual help, the title of the HELP
One line for a help title
tag for the associated item is used. If no
One line for a top separator line
title is defined on the HELP tag, a default
One line for a bottom separator
title of "Help" is used.
Two lines for the function keys
One line for the message line For extended help, the title from the first
HELP tag for the panel is used. If no title
For help displayed in a pop-up window, the is defined on the HELP tag, the default
maximum value for the DEPTH attribute is 21. title or the full display title of the
The UIM does not increase or decrease the QUHDSPH API is used.
depth of a window if a value other than '*' is
If the text for the help title is longer than the
specified. A specific depth should be speci-
pop-up window width, the title text is truncated
fied only if the text between the HELP and the
at a word boundary to the width of the pop-up
EHELP tags depends on a particular window
window. The default title or the full display
width.
title of the QUHDSPH API is used.
If the help is for a data area, menu area, or
Help information presented in full screen
the function keys, and if DEPTH='*', the UIM
mode is titled as follows:
chooses a depth of 9. If the help is for a list
area, the UIM chooses a depth of 14. The For contextual help, the title from the
UIM finds a location for the window using this HELP tag is used.
depth, then expands the window to a size
For extended help, the title from the first
designed to display the online help information
HELP tag is used.
in the most appropriate fashion.
If no title is defined on the HELP tag, the
The depth used is that of the first HELP tag
default title or the full display title of the
found when the UIM assembles the online
QUHDSPH API is used.
help information.
Help modules must be coded so that each module

Optional Text can be individually formatted. Help modules must
help-title-text begin with one of the following tags:
The title used on the help panel. The text DL Definition list
must appear on the same or next line as the FIG Figure
tag and can only contain the reverse text (RT) H1-H4 Headings
tag. If the help-title-text is longer than the IMHELP Imbed help
pop-up window width, the title text is truncated ISCH Index search
to the width of the pop-up window. If the LINES Unformatted lines
value for the WIDTH attribute on this tag is NT Note
greater than 57 or equal to '*', the maximum OL Ordered list
length of the help-title-text is 55 characters. P Paragraph
Otherwise, the maximum length is the value PARML Parameter list
specified for the WIDTH attribute minus two. SL Simple list
The help panel title displayed depends on UL Unordered list
whether contextual or extended help is XH1-XH4 Extended help headings
XMP Example

HELP Tag
Example: Help Panel Definition

This example shows how a help panel is defined
and how the text is displayed.
UIM Source
:help name=hmain.Main System Menu - Help
:p.
This panel allows you to ...
(extended description of the panel)
:ehelp.
Results
à HELP Main System Menu

ð
This panel allows you to ...
______________________________________________________________________________
á ñ

HP0 through HP9 Tags
HP0 through HP9 (Highlighted Phrase)
55───┬─:HPð.──┬──────┬──:EHPð.─┬────────────────────────────────────────────────────────5%
│ └─text─┘ │
├─:HP1.──┬──────┬──:EHP1.─┤
│ └─text─┘ │
├─:HP2.──┬──────┬──:EHP2.─┤
│ └─text─┘ │
├─:HP3.──┬──────┬──:EHP3.─┤
│ └─text─┘ │
├─:HP4.──┬──────┬──:EHP4.─┤
│ └─text─┘ │
├─:HP5.──┬──────┬──:EHP5.─┤
│ └─text─┘ │
├─:HP6.──┬──────┬──:EHP6.─┤
│ └─text─┘ │
├─:HP7.──┬──────┬──:EHP7.─┤
│ └─text─┘ │
├─:HP8.──┬──────┬──:EHP8.─┤
│ └─text─┘ │
└─:HP9.──┬──────┬──:EHP9.─┘
└─text─┘
These highlighted phrase (HP0-HP9) tags identify punctuation mark. This allows the punctuation
a word or phrase which is highlighted. All HPn mark and the text associated with it to be dis-
tags require matching end tags. These tags are played using the same emphasis.
only allowed in help areas and in information
areas that are not in the print head (PRTHEAD) or Highlighting tags may be nested. For example,
print panel (PRTPNL) tags. :HP1.text:HP2.text2:EHP2.text3:EHP1. is valid.
The HPn and EHPn tag phrase should be speci- Optional Text
fied on word boundaries. If the two characters
immediately following the EHPn tag are a punctu- text
ation mark and a blank, the UIM automatically Although the word or phrase to be highlighted
extends the emphasis attribute to include the is not required, the tag has no meaning when
no text is specified.

HP0 through HP9 Tags
Tag Color Device Formatting Monochrome Device Formatting Print Formatting

For Help
HP0 Green Normal Normal
HP1 Green, underscored Underscored Underlined
HP2 White High intensity Bold
HP3 White, underscored High intensity, underscored Bold, underlined
HP4 Green Normal Normal
HP5 Green, reverse image Normal, reverse image Underlined
HP6 Green, underscore, reverse image Underscore, reverse image Underlined
HP7 White, reverse image High intensity, reverse image Bold, underlined
HP8 White, reverse image High intensity, reverse image Bold, underlined
HP9 White, reverse image Normal, reverse image Underlined
RV2W062-0

H1 through H4 Tags
H1 through H4 (Heading)
55───┬─:H1─┬─.heading-text──────────────────────────────────────────────────────────────5%
├─:H2─┤
├─:H3─┤
└─:H4─┘
The heading (H1-H4) tags identify main topics and text according to the current publishing style,
subtopics of information. These tags are only with significant words in initial caps.
allowed in information areas and help areas.
In a help area, text after the headings is indented

Example: Heading Tags
four spaces from the margin to separate the This example illustrates how the different headings
headings from the text. In an information area, are justified and formatted.
text formats flush left, against the left margin.
Headings have one blank line formatted before UIM Source

and after the heading text. :H1.A One Heading
:p.Here's a paragraph.
Specific formatting rules are as follow: :H2.A Two Heading
:p.Another paragraph.
H1 Centers and formats text as underscored and
:H3.A Three Heading
highlighted, like the HP3 tag. This tag :p.Still another paragraph.
causes a page eject when it appears in a :H4.A Four Heading
printed help module. :p.Still another paragraph.
H2 Left justifies and formats text as underscored
and highlighted, like the HP3 tag. Results:
H3 Left justifies and formats text as highlighted
A One Heading
text, like the HP2 tag.
H4 Left justifies and formats text as under- Here's a paragraph.
scored, like the HP1 tag.
A Two Heading
Required Text Another paragraph.
heading-text
The text for the heading. The text of a A Three Heading
heading must be entered on a single line and
Still another paragraph.
is formatted as entered. It cannot contain any
other tags. A common practice is to enter the
A Four Heading

IMHELP Tag
IMHELP (Imbed Help)
55──:IMHELP──NAME=help-module-name──.───────────────────────────────────────────────────5%
The imbed help (IMHELP) tag embeds a help active HPn tags must be ended with EHPn
module from another panel group object. This tag tags before coding the IMHELP tag.
can occur only in help modules within the help
module (HELP) and EHELP tags. Example: Imbedded Help
Required Attribute This example uses imported help for the help on
function keys.
NAME=help-module-name
The name of a help module imbedded where
this tag occurs. For more information on the
UIM Source
rules for naming, see “Name Syntax” on :HELP name='menu1'.
page A-4. The name must be the name of :H2.Purpose of MENU1
another help module defined within the same Menu1 is intended for the use of...
..
panel group, or it must be imported from .
another panel group using the import :IMHELP name='keydefs'.
..
(IMPORT) tag. IMHELP tags have a nesting .
limit of 16. :EHELP.
..
.
If the index search (ISCH) or index search :HELP name='keydefs'.
synonym (ISCHSYN) tags are a part of the :PARML.
embedded help module, they are not part of :PT.F1=Help
the module where the the IMHELP tag occurs. :PD.This key...
:PT.F3=Exit
An active highlight phrase (HPn) tag is not :PD.This key...
allowed when an IMHELP tag is coded. Any :EPARML.
:EHELP.

IMPORT Tag
IMPORT (Import)
55──:IMPORT──NAME=─┬─imported-name─┬───PNLGRP=panel-group-name───────────────────────────5
└─'\'───────────┘
5──┬────────────────────────────┬──┬─────────────────────────────┬──.───────────────────5%
│ ┌─SAME─────────┐ │ └─PRDLIB=product-library-name─┘
└─NEWNAME=─┴─private-name─┴──┘
The import (IMPORT) tag makes help modules PNLGRP=panel-group-name

defined in another panel group object available in The name of the panel group that contains the
the current panel group. This tag must appear in help module specified by NAME. This is an
the prolog section of the panel group source fol- OS/400 object name which obeys all object
lowing the panel group (PNLGRP) tags and the name rules. This name may be fully qualified.
copyright (COPYR) tag. An IMPORT tag must be
specified before any references by other tags to Optional Attributes
the help modules it defines.
NEWNAME=SAME | private-name
This tag may also assign a private name to the A new name used instead of the imported
imported help module. If a private name is name within the current panel group. The
assigned, the private name replaces the imported new name suppresses the visibility of the
name in the scope of the current panel group. imported name and serves as its replacement.
This allows names to be imported that would have Only NEWNAME=SAME is allowed when
conflicted with other names within the current NAME='*' is specified.
panel group.
PRDLIB=product-library-name
The name of the library added into the library
Required Attributes search list as a product library, used to locate
NAME=imported-name | '*' the panel group defining the help module
The internal name of the help module specified by the NAME attribute on this tag.
imported for use within the current panel This attribute is not allowed when the PNLGRP
group. For more information on the rules for attribute is fully qualified.
naming, see “Name Syntax” on page A-4. The product library is only used when imbed-
If '*' is coded, all unresolved names are ding help information using the imbed help
assumed to be imported from this panel (IMHELP) tag. The product library is ignored
group. Only one IMPORT tag may be coded when referring to a help module using the
with NAME='*'. HELP attribute on other UIM tags.

INFO Tag
INFO (Information Area)

55──:INFO──DEPTH=─┬─area-depth─┬───┬────────────────────┬──┬──────────────────┬──.─────────5
└─'\'────────┘ │ ┌─SPACE─┐ │ │ ┌─NO──┐ │
└─BOTSEP=─┼─NONE──┼──┘ └─SCROLL=─┴─YES─┴──┘
└─RULE──┘
5──┬────────────┬──:EINFO.────────────────────────────────────────────────────────────────5%
└─area-title─┘
55──:INFO──┬────────────────────┬──┬───────────────────┬──.──┬────────────┬──:EINFO.──────5%
│ ┌─SPACE─┐ │ │ ┌─NORMAL─┐ │ └─area-title─┘
└─BOTSEP=─┼─NONE──┼──┘ └─TYPE=─┴─PROLOG─┴──┘
└─RULE──┘
An information area (INFO) tag provides textual If RULE is specified, a line of underscored
information to explain the operation of an applica- spaces is used.
tion or panel. This tag is allowed for display
SCROLL=NO | YES
panels and print panels. It can construct a
Indicates whether or not this area is scrollable.
detailed instruction area on a panel.
This attribute is allowed only for display
Information areas are formatted with a width of 72 panels. NO indicates that the area is not
columns unless the width attribute on the panel scrollable.
tag is less than 74 columns. In this case, the YES indicates that the area is intended to be
information area is formatted with a width of two scrollable. For a SCROLL=YES area, a line of
columns less than the width attribute on the panel spaces is used by the UIM to provide a line
tag. for the scroll information. If BOTSEP=SPACE is
specified also, one line is used for both the
Required Attribute separator and the scroll information line.
DEPTH=area-depth | '*' TYPE=NORMAL | PROLOG

The depth of the area in lines, including sepa- Indicates whether or not this information area
rators if any are specified. This attribute is is a prolog area. The prolog area is printed
required for display panels, but not allowed for only once after the title line on the first page.
print panels. If '*' is specified, the space This attribute is allowed only for the print head
remaining on the display after other panel ele- (PRTHEAD) tag. This attribute is valid only
ments are allocated is given to this area. when the INFO tag appears between the
Only one area in the panel may have '*' PRTHEAD and the EPRTHEAD tags for infor-
coded. mation areas in a PRTHEAD panel. NORMAL
is the default value.
Optional Attributes
Optional Text
BOTSEP=SPACE | NONE | RULE
Defines the bottom separator for the informa- area-title
tion area. If SPACE is specified, a line of The title of the area. If no text is specified, no
spaces is used. title line is allocated to the area. The text
NONE indicates that no separator line exists. tag, can contain only the reverse text (RT)

INFO Tag
tag, and cannot exceed a maximum length of tion areas are formatted to a width of 72 columns,
55 characters long. as is done for information areas on display panels,
regardless of the width specified on the PRTHEAD
Print Formatting Considerations or print panel (PRTPNL) tag.
Printed information areas are formatted like dis-

played areas, except when four lines of an infor-
mation area do not fit on a page when printing. If
this is the case, a page eject occurs and the infor-
mation area is printed on the next page. Informa-

ISCH Tag
ISCH (Index Search)
55──:ISCH──ROOTS='root-word-list'──.──index-entry-text──────────────────────────────────5%
The index search (ISCH) tag identifies the text dis- same or next line as the period which ends
played by the index search function if the user the tag definition and cannot span two lines in
enters a word that matches a synonym. The the source.
ISCH tag is only allowed in source code for panel
If the index entry is a subtopic, the index-
group objects and is not allowed in the source for
entry-text is indented two spaces from the text
menu objects. The placement of the ISCH tag
of the first higher index entry in the hierarchy
determines the help module displayed when the
of index entries.
index entry is selected. The ISCH tags should
appear immediately after the help module (HELP) The text which is provided is used as the topic
tag it refers to. title when topics are presented for selection.
If no text is specified on the HELP tag of the
topic, the text provided on the ISCH tag is
Required Attribute also used as the panel title when the topic is
ROOTS='root-word-list' selected for presentation. When used as a
A list of up to 50 root words that apply to the panel title, no more than 55 characters of the
index entry. Each root word may be up to 20 text is shown. If the text contains more than
characters and can contain only the charac- 55 characters, it is truncated at a blank and
ters A through Z, a through z, and 0 through an ellipse (...) is placed after the text to indi-
9. One or more blanks must be specified cate that truncation has occurred.
between words, so the entire list must be
enclosed in apostrophes. The ROOTS attribute Example: Index Search
may be repeated, allowing you to define more
root words for an index entry than fits on one This example shows some ISCHSYN tags and the
source line. ISCH tags that use them:
The root words serve as a link between the
ISCH tags and the index search synonym UIM Source
(ISCHSYN) tags, and do not appear to the :ISCHSYN ROOT='copy'.copy copying copies
user. To allow the user to search for an index :ISCHSYN ROOT='delete'.delete deleting deletes
entry, each root word specified here must :ISCHSYN ROOT='delete'.remove removes removing
have a matching root word on an ISCHSYN :ISCHSYN ROOT='folder'.folder folders
tag. :ISCHSYN ROOT='folder'.document documents
..
.
Required Text :help name=fldcpy.
:ISCH ROOTS='copy folder'.Copying folders
..
index-entry-text .
The text of the index entry presented when :ehelp.
one of the synonym words is selected. The :help name=flddlt.
text may contain up to 72 characters but can :ISCH ROOTS='delete folder'.
not contain other tags. It must appear on the Deleting folders
:ehelp.

ISCHSUBT Tag
ISCHSUBT (Index Search Subtopic)
55──:ISCHSUBT──TOPICS='help-module-name-list'──.────────────────────────────────────────5%
The index search subtopic (ISCHSUBT) tag identi- UIM Source

fies the help modules within the same panel group
:HELP name=mainhelp.
that are subtopics under the preceding topic speci-
fied on an index search (ISCH) tag. The
Main Help Topic
ISCHSUBT tag must appear after the ISCH tag. :ISCHSUBT topics='help1'
This tag is repeatable. topics='help2'.
..
.
Any help module with an ISCH tag that is not :EHELP.
identified by an ISCHSUBT tag is a primary topic :HELP name=help1.
in the index search hierarchy. Therefore, if no :ISCH roots='root words'.
ISCHSUBT tags are used, all help modules are Help number 1
primary topics and there is no hierarchy in the :ISCHSUBT topics='help3 help4'.
..
index search. The ISCHSUBT tag is allowed only .
in source code for panel group objects; it is not :EHELP.
allowed in the source code for menu objects. :HELP name=help2.
Help number 2
Required Attribute :ISCHSUBT topics='help3'
..
TOPICS='help-module-name-list' .
Identifies the help modules within the same :EHELP.
panel group that are subtopics under the pre- :HELP name=help3.
ceding topic specified on an index search
Help number 3
(ISCH) tag. The order in which the help ..
.
modules appear on the TOPICS attribute is
:EHELP.
the order in which they are displayed in the
:HELP name=help4.
index search hierarchy. A help topic name :ISCH roots='root words'.
cannot be specified twice in this list. For more Help number 4
information on the rules for help modules ..
.
names, see “Name Syntax” on page A-4. :EHELP.
This attribute is repeatable.
A topic can be the subtopic of more than one This UIM source creates the following index
topic. search hierarchy:
Title of this index
Topics can be nested to no more than 16
Main Help Topic
levels.
Help number 1
Help number 3
Example: Index Search Help number 4
Hierarchy Help number 2
Help number 3
The following example shows how the ISCH tags
and ISCHSUBT tags work together to form an
index search hierarchy:

ISCHSYN Tag
ISCHSYN (Index Search Synonym)
55──:ISCHSYN──ROOT=root-word──.──synonym-words──────────────────────────────────────────5%
The index search synonym (ISCHSYN) tag identi- additional ISCHSYN tags should be entered
fies the variations and synonyms for the root specifying the same root word. The additional
words used in the index search function. The synonyms are added to the previous syno-
ISCHSYN tag is only allowed in source for panel nyms.
group objects and is not allowed in the source for
Each synonym word must be 40 characters or
menu objects.
less and can contain no spaces. It cannot
contain a period, left or right parenthesis, a
The text must be entered on one line. If more
semicolon, a comma, question mark, or colon.
than one line is needed, multiple ISCHSYN tags
may be coded. This text, when combined with the Different languages have a larger or smaller
index search (ISCH) tag, determines the index number of synonyms for each word. To
entries displayed when the user enters words for provide meaningful results, the translation of a
the index search function. root word must be done by providing a list of
synonym words and by not translating each
The ISCHSYN tags build a table of synonyms, English synonym.
which serves as a link to the ISCH tags. As
The UIM automatically handles lowercase,
words are entered for an index search, they are
single-byte character set (SBCS) synonym
matched with the words in the synonym table to
words the same way as uppercase words,
link to the entries displayed.
using the code page specified on the TXTCHRID
There is no restriction on the placement of the attribute of the panel group (PNLGRP) tag.
ISCHSYN tags, but to make maintenance and
translation easier, they should be placed in one Example: Index Search
area, such as the beginning of the panel group or Synonyms
in a panel group object which contains only
ISCHSYN tags. This example shows several ISCHSYN tags and
how they are referred to by ISCH tags.
Required Attribute
UIM Source
ROOT='root-word'
The root word to which the synonyms apply. :pnlgrp...
..
If a real word is used for the root word, like .
“copy,” that word should also be entered in :ISCHSYN ROOT='copy'.copy copying
the synonym-words field. :ISCHSYN ROOT='copy'.duplicate duplicating
:ISCHSYN ROOT='copy'.model
The root word is used in the ROOTS attribute of :ISCHSYN ROOT='root1'.remove removing
the ISCH tag and may be up to 20 characters. :ISCHSYN ROOT='root1'.delete deleting
A root word can contain only the characters A :ISCHSYN ROOT='root1'.trash discard
through Z, a through z, and 0 through 9. :ISCHSYN ROOT='folder'.folder folders
:ISCHSYN ROOT='folder'.document documents
:ISCHSYN ROOT='folder'.data information
Required Text ..
.
synonym-words :help name=fldcpy.
Special Format. Specifies variations and :ISCH ROOTS='copy folder'.Copying a folder
:h2.Copying a Folder
synonyms for the root word. The synonym ..
words must be separated by blanks. If addi- .
:ehelp.
tional synonyms are needed for a root word, ..
.

ISCHSYN Tag
:help name=flddlt. folder folder folders document documents

:ISCH ROOTS='root1 folder'.Deleting a folder data information
:h2.Deleting a folder
..
. The ISCH tag for the “Copying a folder” entry
:ehelp. points to the “copy” and “folder” search synonym
lists.
In this example, the ISCHSYN tags builds a
synonym table containing the following entries: When the user requests "copy folders," the entry
Root Word Synonym Words is found and displayed because "copy" and
copy copy copying duplicate "folders" are both listed as matches in the
duplicating model ISCHSYN table. If the user entered "copy
root1 remove removing delete deleting folders," "folders, copy," or "copying documents,"
trash discard the entry "Copying a folder" is displayed.

KEYI Tag
KEYI (Key List Item)
55──:KEYI──KEY=key-name──HELP=help-module-name──┬──────────────────────┬─────────────────5
└─ACTION='action-text'─┘
5──┬─────────────────────┬──┬──────────────────┬──┬──────────────────────────┬──.────────5
└─COND=condition-name─┘ │ ┌─YES─┐ │ └─PRIORITY=priority-number─┘
└─VARUPD=─┴─NO──┴──┘
5──┬──────────────────────┬─────────────────────────────────────────────────────────────5%
└─key-description-text─┘
The key list item (KEYI) tag defines a single func- Any dialog variable in the command string
tion key. This tag must occur between the KEYL must be preceded by an ampersand to
and EKEYL tags. It assigns displayable text for a denote variable substitution.
specified key and identifies the action to take 'CMDLINE'
place when that key is pressed. 'ENTER'
'EXIT'
Required Attributes 'HELP'
'HOME'
KEY=key-name 'MENU qualified-menu-name
The names for the engraved or software RTNPNT|NORTNPNT'
defined function keys are Attn, Enter, F1-F24, 'MOREKEYS'
Help, Home, Print, Pagedown, Pageup, and 'MOVETOP'
Sysreq. 'PRINT'
'PROMPT'
HELP=help-module-name
'RETRIEVE'
The associated help module for the key
'RETURN positive-integer'
description. The help module name may be a
'PAGEUP'
name imported from another panel group, but
'PAGEDOWN'
it must follow the rules for names outlined
earlier in this chapter. For more information For a description of each of these actions, see
on the rules for naming, see “Name Syntax” Appendix B, “UIM Dialog Commands” on
on page A-4. page B-1.
ACTION='action-text' Engraved key assignments are enforced by
The action occurring when the function key is the compiler. These keys are the keys listed,
pressed. This attribute is conditionally except for F1 through F24. If engraved keys
required. For certain keys, the ACTION attri- are assigned anything but their corresponding
bute must not be specified since the UIM does dialog function (or no action in certain cases),
not handle that particular key. For all other a compile error results. The following is a list
keys, the ACTION attribute is required. of the engraved keys and their corresponding
actions:
The valid forms of action text are:
Key Action
'ACTIONS'
Attn No action
'CALL program-reference'
Enter 'ENTER'
Help 'HELP'
the UIM and the function key CALL
Home 'HOME'
program, see the System API Reference.
Print 'PRINT'
'CANCEL'
Pageup 'PAGEUP'
'CHGVIEW'
Pagedown 'PAGEDOWN'
'CMD command-string'
Sysreq No action

KEYI Tag
Optional Attributes fied on one of the KEYI tags. Otherwise, the

priority attribute is ignored.
COND=condition-name
The key is in effect on the panel only if the Optional Text
condition specified is true. The condition must
be defined in the panel group with the condi- key-description-text
tion definition (COND) tag. The displayable description for the associated
key. For example, "F5=Refresh" or
VARUPD=YES | NO "F12=Cancel". If no text is specified, a
If YES is coded, validity checking occurs and description of the key is not displayed on the
the variable pool is updated with values panel, although the key is active. The text
entered by the user before the action takes must appear on the same or next line as the
place. tag and can only contain the reverse text (RT)
If NO is coded, the action is performed imme- tag.
diately and no variable pool updating occurs. The function key area is formed by concat-
If the VARUPD attribute is not specified and the enating the text from the various key list
EXIT or CANCEL dialog command is specified items, with each key separated by at least
on the ACTION attribute of this tag, a warning three spaces. If the text does not fit on the
message is generated at compile time stating rest of a line, it is placed on the next line.
that VARUPD=YES is assumed. This is done as
a reminder to you, because you may not want
to check for valid input data before allowing Example: Key Definitions
the user to exit a screen through these dialog
commands. To avoid this message, specify The following example defines the function keys
VARUPD=YES or VARUPD=NO on the key assign- F3, F5, F11, and F12.
ment.
UIM Source
If no ACTION attribute is specified, this attribute
is ignored. :keyl name=keylist
help=hkeylist.
PRIORITY=priority-number :keyi key=f3
The order in which keys should be displayed action='exit set'
when the MOREKEYS dialog command is help=exit
performed. .F3=End task
:keyi key=f5
Key items with a lower number priority are dis- action='return 5'
played before key items with a higher number help=refresh
priority. A specified priority number must be .F5=Refresh
greater than or equal to one and less than or :keyi key=f11
equal to 99. action=chgview
help=chgview
If a priority is not specified for a key, the .F11=Alternate view
default value depends on the action specified: &gms.keyi key=f12
Action Default action='cancel set'
help=cancel
EXIT 1
.F12=Cancel
CANCEL 2
:ekeyl.
All others 99
No action 99
Results
The PRIORITY attribute is used only within a
key list that has ACTION=MOREKEYS speci- F3=End task F5=Refresh F11=Alternate view F12=Cancel
á ñ

KEYL Tag
KEYL (Key List)
55──:KEYL──NAME=key-list-name──┬───────────────────────┬──.──:EKEYL.────────────────────5%
└─HELP=help-module-name─┘
The key list (KEYL) tag indicates the beginning of Example: Key List
a list of key definitions. Each list may be referred
to by one or more panel definitions. An EKEYL This is an example of a key list.
tag must be specified at the end of the key list.
UIM Source: An example of a key list follows:
Other tags can be nested within the KEYL tag.
These tags are listed in the following table. The :keyl name=keylist.
table defines the order in which the tags must :keyi key=f1
appear and specifies on which page more infor- help='key/helpf1'
mation can be found for each tag. action=help.
:keyi key=f3
Table A-8. Tag Allowed Between the KEYL and help='key/exit'
EKEYL Tags. action='exit set'.F3=Exit
:keyi key=f12
Tag Name Order Page help='key/cancel'
KEYI 1 A-76 action='cancel set'.F12=Cancel
(Key list item) :keyi key=f24
help='key/morekeys'
action=morekeys.F24=More keys
Required Attribute :keyi key=enter
help='key/enter'
NAME=key-list-name action=enter.
The name assigned to the key list. For more :keyi key=help
information on the rules for naming, see help='key/help'
“Name Syntax” on page A-4. action=help.
:keyi key=pagedown
help='key/pagedown'
Optional Attribute action=pagedown.
HELP=help-module-name :keyi key=pageup
Identifies online help information explaining help='key/pageup'
the purpose of the function keys. The name action=pageup.
:keyi key=print
of the help module can be a name imported
help='key/print'
from another panel group, but must follow the
action=print.
rules for names outlined earlier in this chapter. :ekeyl.
For more information on the rules for names,

LINES Tag
LINES (Unformatted Lines)
55──:LINES.──┬───────────────────┬──:ELINES.────────────────────────────────────────────5%
└─unformatted-lines─┘
The unformatted lines (LINES) tag identifies an Optional Text

area of user-controlled line entry where the lines
are not automatically concatenated. Text is for- unformatted-lines
matted the same way it is entered. This tag is Although the text for the unformatted lines is
only allowed in information areas and help areas. not required, the tag has no meaning when no
The LINES tag requires a matching end tag. text is specified.
Note: Care should be taken when using unfor-

matted lines within lists, because text that does Example: Unformatted Lines
not fit on one line wraps to column one of the next
line. The current left margin changes when This example illustrates how text is formatted the
nested lists are being formatted. If there is online same way it is entered.
help information containing unformatted lines
imbedded at various locations, including within UIM Source
lists, it may not look the same each time. :LINES.
First line
Help modules displayed in full-screen format or in Second line
an extended help window are indented by 4 bytes. :ELINES.
Therefore, the formatting width initially is 6 bytes
less than the width specified on the help module. Results
When the LINES tag appears in an information
area, the formatting width initially is two bytes less First line
than the width specified on the panel tag. Second line

LINK Tag
LINK (Hypertext Link Definition)
55──:LINK──PERFORM='action-text'──┬────────────────────────────────────────┬─────────────5
└──┬─UNLESS1─┬─='conditional-expression'─┘
├─UNLESS2─┤
├─UNLESS3─┤
└─UNLESS4─┘
5──┬─────────────────────────────┬──┬───────────────────────────────────┬──.─────────────5
└──┬─THENDO1─┬─='action-text'─┘ └─LINKWHEN='conditional-expression'─┘
├─THENDO2─┤
├─THENDO3─┤
└─THENDO4─┘
5──┬──────────────────┬──:ELINK.────────────────────────────────────────────────────────5%
└─hypertext-phrase─┘
The hypertext link definition (LINK) tag identifies LINES Unformatted lines
the reference phrase text which is the anchor of a LP List part
static hypertext link. A reference phrase may NT Note
appear in any UIM help area, but may not appear P Paragraph
in an information area. This tag requires a PC Paragraph continuation
matching end tag. It also identifies action taken PD Parameter description
when the reference phrase is selected. The only PK Programming keyword
type of action supported is to display a help PV Programming variable
module. XMP Example
The LINK and ELINK tag must be specified on

word boundaries. If the two characters imme-
Required Attribute
diately following the ELINK tag are a punctuation PERFORM='action-text'
mark and a blank, the UIM automatically extends The action occurring when the reference
the emphasis attribute to include the punctuation phrase is selected and all of the condition
mark. This allows the punctuation mark and the expressions for the UNLESSn attributes have
text associated with it to be displayed using the evaluated to false. The valid form of action
same emphasis. text is:
On a monochrome device, the reference phrase 'DSPHELP help-module-name [ panel-

text is displayed as highlighted, underscored text. group-name ]'
On a color device, the reference phrase text is Note: The brackets in the action text above
displayed as underscored, yellow text. Because indicate that the panel group name is optional.
of hardware limitations, the underscore is not They are not required in the UIM source.
visible on a PS/2* computer or on a personal com-
puter with a color device. For a description of the DSPHELP action, see
The only tag that can be used within a link tag is page B-1.
the reverse text (RT) tag. LINK tags may not be
used within other LINK tags, but may be used Optional Attributes
within any of the following tags:
UNLESSn='conditional-expression'.
CIT Title citation The only allowed values for n are 1 through 4.
DD Definition
FIG Figure The UNLESSn and THENDOn attributes must be
FIGCAP Figure caption text coded as pairs. The expressions on the
HPn Highlighted phrase UNLESSn attributes are evaluated in numeric
LI List item order. If one evaluates to true, the corre-

LINK Tag
sponding THENDOn action is performed and all Conditional Expressions

higher-numbered UNLESSn and THENn attributes
and the PERFORM attribute on this tag are Although the set of conditions that can be formed
ignored. with the LINKWHEN attribute is identical to the set of
For information on using conditional conditions that can be formed with the UNLESSn
expressions with the UNLESSn attribute, see attributes, the significance of those conditions is
“Conditional Expressions.” different. The LINKWHEN attribute activates or
deactivates the LINK tag, while the UNLESSn attri-
THENDOn='action-text' bute selects the action performed when an active
The only allowed values for n are 1 through 4. LINK tag is selected. A conditional expression is
This attribute specifies the action occurring a true or false expression in the following form:
when the reference phrase is selected and the ┌─\AND──────────────┐
conditional expression for the corresponding │ ┌─\OR───────────┐ │
UNLESSn attribute evaluates to true and all the 55───6──6──┬─A───────┬──┴─┴──────────────────5%
├─(A)─────┤
conditional expressions for the lower- └─\NOT(A)─┘
numbered UNLESSn attributes evaluate to false.
The UNLESSn and THENDOn attributes must be where A is an operand which can be one of the
coded as pairs. The UNLESSn attributes are following:
evaluated in numeric order. If one evaluates
to true, the corresponding THENDOn action is A conditional expression
performed and all higher-numbered UNLESSn A built-in function
attributes and the PERFORM attribute on this tag
The logical OR character (|) can be used in place
are ignored.
of *OR, the ampersand character (&) can be used
The valid form of action text is: in place of *AND, and the logical NOT character
(¬) can be used in place of *NOT. Because the
'DSPHELP help-module-name [ panel-
logical OR and logical NOT characters are not in
group-name ]'
the invariant character set, their use is not recom-
Note: The brackets in the option text above mended. For code page 00037, the common USA
indicate that the panel group name is optional. code page, the hexadecimal value of the logical
They are not required in the UIM source. OR character is X'4F', and the hexadecimal
value of the logical NOT character is X'5F'. The
For a description of the DSPHELP action, see
UIM compiler uses these hexadecimal values
regardless of the code page of the source.
page B-1.
LINKWHEN='conditional-expression'. There are two built-in functions:

When the LINKWHEN expression evaluates to CHKOBJ
true or is not coded, the reference phrase is Evaluates to true if the object is found on the
made available and a user is allowed to select system and the current job possesses at least
it. When the LINKWHEN expression evaluates the level of authorization to the object speci-
to false, the reference phrase is not activated fied by the authorities. Arguments must be
and may not be selected. character strings enclosed in double quotation
For more information on using conditional marks ("). The object name follows OS/400
expressions with the LINKWHEN attributes, see object naming conventions. The object type is
“Conditional Expressions.” any of the allowable object types for the
DSPOBJD command and the authorities must
be a single value or a list of authorizations to
be checked for. The values of these authori-
zations are separated by blanks. The fol-
lowing syntax diagram illustrates the
authorities and how to use them:

LINK Tag
55──CHKOBJ(──┬─obj-name───┬──,──"obj-type"─────────5 Examples of conditional expressions follow:

└─"obj-name"─┘
5──┬───────────────────────────────────┬──)───────5% CHKOBJ("OBJECT","\FILE","\USE")
└─,──"──┬─\CHANGE──────────────┬──"─┘
├─\ALL─────────────────┤ CHKOBJ("PANELGRP","\PNLGRP")
├─\USE─────────────────┤ \AND CHKUSRCLS("\PGMR")
├─\EXCLUDE─────────────┤
├─\AUTLMGT─────────────┤
│ ┌──
──────────────────┐ │
CHKOBJ("DOCUMENT","\DOC","\READ \UPD")
└──6─┬─\OBJEXIST─┬───
(1) ─┴─┘ \OR CHKUSRCLS("\SYSOPR")
├─\OBJMGT───┤
├─\OBJOPR───┤ \NOT(CHKOBJ("PROGRAM","\PGM"))
├─\OBJALTER─┤
├─\OBJREF───┤
├─\ADD──────┤
├─\DLT──────┤ Bidirectional Considerations
├─\READ─────┤
├─\UPD──────┤
└─\EXECUTE──┘
The value of the BIDI attribute on the panel group
(PNLGRP) tag of all possible panel groups that
Note:
1 Each value can be used only once, a
can be reached by taking hypertext links should
be the same. If they are not the same, it is pos-
maximum of 7
sible that the resulting screen or pop-up window is
displayed with the opposite orientation when a ref-
If no authorities are specified, no authorization erence phrase is selected.
check is performed and the function becomes
an existence check.
Example: Hypertext Link
When a program adopts the authority of its
owner, that authority is normally used to This example shows how hypertext links can be
authorize operations performed by that used to provide definitions for terms.
program. However, when help is requested,
those adopted authorities are ignored while UIM Source
the UIM displays the online help information.
Therefore, no adopted authorities are used :HELP NAME='hyper/help'.Hypertext in OS/4ðð
:P.
when the CHKOBJ function is used on the
Hypertext lets users explore
UNLESS or LINKWHEN attributes on the
the online help information in a way that is most
LINK tag. natural for them.
For more information about programs adopting Hypertext links can be used within :LINK
the authority of the owner, see the PERFORM='DSPHELP item/specific/help'
USRPRF(*OWNER) parameter on the .item specific help:ELINK.,
:LINK PERFORM='dsphelp extended/help'
CRTCLPGM command.
.extended help:ELINK., and
CHKUSRCLS :LINK PERFORM='dsphelp index/search'
The user class argument specified for the .index search help:ELINK..
function is compared to the user class param- :EHELP.
eter from the user profile of the current job.
:HELP NAME='item/specific/help'
The function evaluates to true if the user
.Definition of Item Specific Help
profile has the same or greater value than the
:P.
function argument. The function argument Item specific help is . . .
must be enclosed in double quotation marks :EHELP.
(").
The following syntax diagram illustrates the :HELP NAME='extended/help'
valid argument values for the user class: .Definition of Extended Help
:P.
55──CHKUSRCLS(─┬─\SECOFR─┬─)────────────5% Extended help is . . .
├─\SECADM─┤ :EHELP.
├─\PGMR───┤
├─\SYSOPR─┤
└─\USER───┘ :HELP NAME='index/search'
.Definition of Index Search
:P.

LINK Tag
Index search allows you to tell the

system to search for specific information.
à ......................................................................
ð
: Hypertext on OS/4ðð :
: :
Index search information is made more : Hypertext lets users explore the online information in a way :
: that is most natural for them. Hypertext links can be used :
useful by the addition of : within item specific help, extended help, and :
: index search help. :
:LINK PERFORM='dsphelp hyper/help' :
: F2=Extended help F1ð=Move to top F11=Index search
Bottom :
:
.hypertext:ELINK. because : F12=Cancel
:
F13=User support F24=More keys :
:
it allows you to link to additional help :....................................................................:
topics.
:EHELP. When the cursor is moved to INDEX SEARCH
HELP and the Enter key is pressed, the following
Results screen is shown.
à ......................................................................
ð
: Definition of Index Search :
: :
: Index search allows you to tell the system to search for specific :
: information. Index search information is made more useful by the :
: addition of > hypertext because it allows you to link to :
: additional help topics. :
: Bottom :
: F6=Viewed topics F1ð=Move to top F11=Index search :
: F12=Cancel F13=User support F24=More keys :
: :
:....................................................................:

LIST Tag
LIST (List Area)

55──:LIST──DEPTH=─┬─area-depth─┬───LISTDEF=list-name──┬────────────────────┬───────────────5
└─'\'────────┘ │ ┌─SPACE─┐ │
└─BOTSEP=─┼─NONE──┼──┘
└─RULE──┘
5──┬──────────────────┬──┬─────────────────┬──┬──────────────────────┬─────────────────────5
│ ┌─YES─┐ │ │ ┌─ð─┐ │ │ ┌─SPACE──┐ │
└─SCROLL=─┴─NO──┴──┘ └─MAXHEAD=─┼─1─┼──┘ └─BODYSEP=─┼─INDENT─┼──┘
├─2─┤ ├─BOTH───┤
├─3─┤ └─NONE───┘
└─4─┘
5──┬───────────────────────────┬──┬────────────────────┬──┬──────────────────┬─────────────5
└─VIEW=dialog-variable-name─┘ │ ┌─NONE───┐ │ │ ┌─NO──┐ │
└─ACTOR=─┼─UIM────┼──┘ └─EXTACT=─┴─YES─┴──┘
└─CALLER─┘
5──┬─────────────────────┬──┬─────────────────┬──┬────────────────────────────┬────────────5
│ ┌─NONE───┐ │ │ ┌─2─┐ │ └─PARMS=dialog-variable-name─┘
└─SELECT=─┼─SINGLE─┼──┘ └─MAXACTL=─┼─1─┼──┘
└─MULTI──┘ └─3─┘
5──┬───────────────────────────────┬──.──┬────────────┬──:ELIST.──────────────────────────5%
└─HEADSIZE=dialog-variable-name─┘ └─area-title─┘
55──:LIST──LISTDEF=list-name──┬────────────────────┬──┬─────────────────┬──────────────────5
│ ┌─SPACE─┐ │ │ ┌─ð─┐ │
└─BOTSEP=─┼─NONE──┼──┘ └─MAXHEAD=─┼─1─┼──┘
└─RULE──┘ ├─2─┤
├─3─┤
└─4─┘
5──┬──────────────────────┬──┬───────────────────────────┬─────────────────────────────────5
│ ┌─SPACE──┐ │ └─VIEW=dialog-variable-name─┘
└─BODYSEP=─┼─INDENT─┼──┘
5──┬───────────────────────────────┬──.──┬────────────┬──:ELIST.──────────────────────────5%
└─HEADSIZE=dialog-variable-name─┘ └─area-title─┘
The list area (LIST) tag defines a list area on a described by the list definition (LISTDEF) tag.
panel. The UIM displays the entries in the list, handling
the scroll operations which allow the user to see
This tag is allowed for display panels and print all the entries.
panels, except for the print head panel
(PRTHEAD) tag. A list area consists of an arbi- The area may have multiple views, which are
trary number of rows of like columns, and can be selected by the CHGVIEW dialog command. The
scrolled up and down if the number of rows CHGVIEW dialog command can be assigned to a
exceeds the area in which the list is displayed. function key which alternates between the views.
A list area presents a view of a UIM list, which is Other tags can be nested within the LIST tag.
manipulated by the UIM application programming These tags are listed in the following table. The
interfaces (APIs). UIM lists are named and table defines the order in which the tags must

LIST Tag
appear, indicates which tags can be used in Optional Attributes

display panels only, print panels only, or both
(specified by a D, P, or B, respectively), and spec- BOTSEP=SPACE | NONE | RULE
ifies on which page more information can be found Defines the bottom separator for the list area.
for each tag. If SPACE is specified, a line of spaces is
used.
When more than one tag is listed with the same
NONE indicates that no separator line exists.
mixed in any order. However, a tag with a higher If RULE is specified, a line of underscored
order number cannot precede a tag with a lower spaces is used as a separator line.
order number. For example, a tag with an order
SCROLL=YES | NO
number of three cannot precede a tag with an
Indicates whether or not the list area is
scrollable. This attribute is allowed only for
Table A-9. Tags Allowed Between the LIST and display panels. YES indicates that the list
ELIST Tags area is intended to be scrollable. For
SCROLL=YES, a line of spaces is used by the
Tag Name Order Use Page
UIM to provide a line for the scroll information.
TOPINST 1 D A-161
(Top instruction NO indicates that the list is not scrollable.
line) Ordinarily, NO would not be used, but for
short lists it can be specified to disable the
LISTACT 2 D A-90
(List action) scrolling keys for the list area.
LISTGRP 3 B A-103 If BOTSEP=SPACE is specified and there are

(List column no bottom instructions for both the separator
group) and scroll information line, one line is used.
LISTCOL 3 B A-96 MAXHEAD= 0 | 1 | 2 | 3 | 4
(List column)
The maximum number of lines for column
LISTVIEW 4 B A-105 headings. From 0 to 4 lines can be specified.
(List view) The default is 0, indicating that no column
BOTINST 5 D A-10 headings are allowed. For more information
(Bottom instruc- on column headings, see “LISTCOL (List
tion line) Column)” on page A-96. This attribute
includes any heading line required by the
column group headings.
Required Attributes
When column headings are used, provide
DEPTH=area-depth | '*' expansion space for national language trans-
This attribute is required for display panels but lation by specifying a MAXHEAD value larger
is not allowed for print panels. The depth of than the number of heading lines required. If
the area in lines, including separators if any this expansion space is not provided, it must
are specified. If '*' is specified, the space be provided within the column width deter-
remaining on the display after all other panel mined by the MAXWIDTH attribute of each list
elements are allocated is given to this area. column (LISTCOL) tag.
Only one area in the panel may have '*'
coded. This attribute cannot be specified if the
HEADSIZE attribute on this tag is specified for
LISTDEF=list-name use with variable column headings.
The name of the UIM list from which the data
for this list area is taken. The list must be BODYSEP=SPACE | INDENT | BOTH | NONE
defined in the panel group using the LISTDEF The type of visual separation distinguishing
tag. the body of the area from other elements in
the area, particularly any top and bottom
instruction lines within the area.

LIST Tag
SPACE leaves a blank line after the top one LISTVIEW tag is specified for the list
instruction lines and before the bottom instruc- area.
tion lines. List columns in the body of the
ACTOR=NONE | UIM | CALLER.
area begin in the leftmost position of the
If ACTOR=NONE is used, the list is not an
layout column and are not indented with
action list. This attribute is allowed only for
respect to instruction lines. If the area con-
display panels. No list action (LISTACT) tags
tains no top or bottom instruction lines, no
can be specified and the UIM does not do
blank lines are reserved before or after the
action list processing for the list area.
area body.
If ACTOR=UIM is specified, the actions indicated
INDENT is used to indent list columns in the
by the LISTACT tags are performed by the
body of the area by two positions from the
UIM and must have the ENTER attribute speci-
leftmost position in the layout column where
fied.
the instruction lines begin. If the area con-
tains top or bottom instruction lines, no blank If ACTOR=CALLER, the actions indicated by the
line is reserved between the instructions and LISTACT tags must be performed by the
the area body except if the area is scrollable. calling program of the display panel
If the area is scrollable, a blank line is (QUIDSPP) API.
reserved for the scroll information.
EXTACT=NO | YES
BOTH leaves a blank line after the top instruc- Specifies whether or not an action list has
tion lines and before the bottom instruction extended action capability. This attribute is
lines, and indents the body two positions from allowed only for display panels. With an
the leftmost position in the layout column extended action list, the first line below the
where the instruction lines begin. If the area column headings is used for an extended
contains no top or bottom instruction lines, no action entry. This line contains the action
blank lines are reserved before or after the option column, along with input-capable fields
area body. for additional list columns.
NONE does not leave a blank line between The user can enter a list action option in the
instruction lines and the body and does not option field for the extended action entry,
indent the body with respect to the layout along with data in the other columns. The
column except if the area is scrollable. If the action identified by the list action tag is per-
area is scrollable, a blank line is reserved to formed using the data entered for the other list
provide a line for the scroll information. columns. The data entered into the extended
action entry columns does not have to match
VIEW=dialog-variable-name
the data in an existing list entry.
This is a BIN 15 dialog variable which deter-
mines the view of the list which appears to the EXTACT=NO indicates that the list does not
user. Valid values are 0 through one less have extended action capability.
than the number of views defined. The UIM
EXTACT=YES indicates that the list does have
changes this variable to match the number of
extended action capability. This is allowed
the view that is active (where 0 is the first
only if ACTOR=UIM or ACTOR=CALLER is speci-
view) when the value is not valid or when the
fied on this tag. The action list option column
CHGVIEW dialog command is run for the list
and at least one other list column defined in
area.
each list view must be defined for extended
The first list view (LISTVIEW) tag for the list action use with EXTACT=YES on the LISTCOL
area defines view 0, the second LISTVIEW tag. Any LISTACT tags which can operate on
tag for the list area defines view 1, and so on the extended action field must have
for each LISTVIEW tag in the list area. ACTFOR=BOTH or ACTFOR=EXTACTE specified.
For more information on list views, see When a panel is displayed which has an
“LISTVIEW (List View)” on page A-105. The extended action list but the list is not currently
VIEW attribute must be specified if more than active in the open application, the list is acti-
vated by the QUIDSPP API.

LIST Tag
SELECT=NONE | SINGLE | MULTI used when the list area operates in conjunc-
If SELECT=NONE is used, the list is not a tion with a command line on the same panel.
selection list. This attribute is allowed only for This provides a way for the user to specify
display panels. parameters that affect action list processing.
If SELECT=SINGLE is specified, the list area is The UIM stores the contents of the command
a single-choice selection list. When a single- line in this variable when the command line
choice selection list is displayed, a period (.) contains parameters for action list processing.
precedes each list entry. The user can select The UIM sets the variable to blanks before
only one list entry by typing the slash (/) or the action list processing when the command line
country-designated character over the period. does not contain parameter information.
If SELECT=MULTI is specified, the list is a This dialog variable is intended for use in the
multiple-choice selection list. Multiple list action string for a CMD dialog command spec-
entries may be chosen by entering the slash ified on the ENTER, EXTENTER, PROMPT, or
(/) or the country-designated character into the EXTPROMPT attribute on the LISTACT tag.
entry field preceding each list entry to select.
Note: This variable only contains command
To deselect a choice, the user should type a
line contents when the command line is inter-
blank over, or delete the slash or country-
preted as specifying parameters for action list
designated character, in the list entry.
processing. It does not provide generalized
A value of 1000 is set in the action variable access to the contents of the command line.
for the selected list entries.
HEADSIZE=dialog-variable-name
ACTOR=NONE must be specified or made a This dialog variable specifies the number of
default on this tag if the value of SELECT is dialog variables specified on the COLHEAD attri-
either SINGLE or MULTI. An action variable bute of the LISTCOL tag that should be used
must be declared for each view of the list. for the list column headings. This attribute is
not allowed if MAXHEAD is specified.
MAXACTL= 2 | 1 | 3
The maximum number of lines used for list This dialog variable can only contain the
action descriptions. From 1 to 3 lines can be values 0 through 10, as these are the valid
specified; 2 is the default. Only as many list number of lines for heading text. If this dialog
action lines as needed are used. This attri- variable is not a valid value from 0 through 10,
bute is allowed only for display panels. the maximum of 10 is used. When using the
dialog variables from the list specified on the
The only time that MAXACTL=1 would be useful
COLHEAD attribute of the LISTCOL tag, the vari-
is when there are two or more list actions and
ables are used in the order defined on the
you do not want two lines of list actions after
COLHEAD attribute. This dialog variable must
national language translation.
be defined with a BASETYPE of 'BIN 15' on the
When the UIM formats the first two list action class definition (CLASS) tag.
lines, it attempts to align the start of each
The dialog variables on the HEADSIZE attribute
action with the line above or below it. This is
and the COLHEAD attribute of the LISTCOL tag
done by moving text a few columns to the
are evaluated like normal dialog variables. It
right on either the first or second line. When
is recommend that you set the HEADSIZE
the text for the third list action line is for-
dialog variable before calling the QUIDSPP
matted, the text for the first two lines is not
API and not change it when changing from
moved, but the UIM tries to align the text on
one view to another. It is up to the application
the third line with the text on the second line.
programmer to not let the list and headings
PARMS=dialog-variable-name shift up and down on panels.
This attribute must name a CHAR 255 dialog
This attribute may not be specified if the list
variable, used by the UIM to store parameter
area contains list column groups.
information for action list processing. This
attribute is allowed only for display panels and
is only valid when the ACTOR attribute on this Optional Text
tag has a value other than NONE. It must be

LIST Tag
area-title Column 1 Column 2

The title of the area. If no text is specified, no xxxxxxxx xxxxxxxxxx
title line is allocated to the area. The text xxxxxxxx xxxxxxxxxx
tag, can only contain the reverse text (RT) List column headings and group headings are
tag, and cannot exceed a maximum length of repeated on each page if the list area is con-
55 characters. tinued onto another page.
Print Formatting Considerations Example 1: List Area

Printed list areas are formatted like those dis- This example shows an action where the UIM per-
played with the following changes:. forms the action requested by the user.
Printing always starts with the first entry in the
list. UIM Source
For lists which are incomplete at the top, the :listdef name=outflist
UIM starts printing with the first entry in the list vars='opt fil nbr usr pri pg sts co'.
and does not require the list to be marked :panel topsep=space
complete at the top. ...
.Output Files
For lists which are incomplete at the bottom, :list depth='\'
the UIM formats and prints until it runs out of listdef=outflist
list entries, then calls the exit program for pro- maxhead=2
cessing the incomplete list for more entries. actor=uim
In general, the exit program is asked for a parms=pvar.
large number of list entries, and if the list is :topinst.Type options, press Enter.
not marked complete at the bottom, the exit :listact
program is called again for more list entries. enter='CMD CHGSPLFA FILE(&FIL.)'
enter='JOB(&USR./&SPID.) SPLNBR(&NBR.) &PVAR.'
For layouts greater than one, the UIM formats help=opt2
as many entries as can be printed on one option=2.2=Change
page, then prints that page. If there are not :listact
enough entries to fill up a page, the entries enter='CMD CNLSPLF FILE(&FIL.)'
are balanced across the layout columns. enter='JOB(&USR./&SPID.) SPLNBR(&NBR.)'
There is always a minimum of two entries in help=opt4
option=4.4=Cancel
the first column before putting entries into sub-
:listact
sequent columns. This helps the user under-
enter='CMD DSPSPLF FILE(&FIL.)'
stand how to read the list. For example, a list enter='JOB(&USR./&SPID.) SPLNBR(&NBR.)'
with LAYOUT=2 and only two list entries would help=opt5
print as follows: option=5.5=Display
:listact
Column 1 Column 2 enter='CMD HLDSPLF FILE(&FIL.)'
xxxxxxxx enter='JOB(&USR./&SPID.) SPLNBR(&NBR.)'
xxxxxxxx help=opt7
option=7.7=Hold
:listact
For list panels, there must be room for a enter='CMD RLSSPLF FILE(&FIL.)'
minimum of two lines of list entries on a page enter='JOB(&USR./&SPID.) SPLNBR(&NBR.)'
besides the column headings. If two lines of help=opt8
list entries do not fit on a page, a page eject option=8.8=Release
occurs and the list entries are printed on the :listcol var=opt
next page. The following example would need usage=inout
to fit on one page, or a new page would be maxwidth=6
used. help=hopt.Opt
:listcol var=fil

LIST Tag
usage=out UIM Source

maxwidth=1ð
help=hfil.File :listdef name=dist
:listcol var=nbr vars='name node'.
usage=out :panel panel-attributes.Distribution
maxwidth=6 :list listdef=dist
help=hnbr.Nbr depth=8
:listcol var=usr maxhead=1.
usage=out :listcol var=name
maxwidth=1ð usage=inout
help=huser.User maxwidth=1ð
:listcol var=pri help=hxxyy1.Name
usage=out :listcol var=node
maxwidth=6 usage=inout
help=hpri.Pty maxwidth=1ð
:listcol var=pg help=hxxyy2.Node
usage=out :listview layout=3
maxwidth=8 cols='name node'.
help=hpg.Pages :elist.
:listcol var=sts :epanel.
usage=out
maxwidth=1ð Results
help=hsts.Status
:listcol var=co
usage=out
à Distribution
ð
maxwidth=1ð Name
__________
Node
__________
Name
__________
Node
__________
Name
__________
Node
__________
__________ __________ __________ __________ __________ __________
help=hco.Copies __________ __________ __________ __________ __________ __________
__________ __________ __________ __________ __________ __________
:listview layout=1 __________ __________ __________ __________ __________ __________
__________ __________ __________ __________ __________ __________
cols='opt fil nbr usr pri pg sts co'. More...
:elist.
:cmdline size=short.Parameters or command:
:epanel.
Results F3=Exit F12=Cancel
á ñ
à Output Files
ð
2=Change
OPT FILE
4=Cancel
NBR
5=Display
USER
7=Hold
PTY
8=Release
PAGES STATUS COPIES

Example 3: List Area with List
_
_
_
ffffffffff
ffffffffff
ffffffffff
nnnn
nnnn
nnnn
uuuuuuuuuu
uuuuuuuuuu
uuuuuuuuuu
p
p
p
nnnn
nnnn
nnnn
xxxx
xxxx
xxxx
nnnn
nnnn
nnnn
Column Groups
_ ffffffffff nnnn uuuuuuuuuu p nnnn xxxx nnnn
_
_
ffffffffff
ffffffffff
nnnn
nnnn
uuuuuuuuuu
uuuuuuuuuu
p
p
nnnn
nnnn
xxxx
xxxx
nnnn
nnnn
This example shows how list columns can be
_
_
ffffffffff
ffffffffff
nnnn
nnnn
uuuuuuuuuu
uuuuuuuuuu
p
p
nnnn
nnnn
xxxx
xxxx
nnnn
nnnn grouped together.
Parameters or command:
More... UIM Source
===> _________________________________________________________________________
F3=Exit F12=Cancel :listdef name=auth
á ñ vars='user oper mgmt exist'
vars='read add update delete'.
:panel panel─attributes.User Authorizations
Example 2: List Area with Three :list listdef=auth
Layout Columns depth='\'
maxhead=3.
This example shows a list area where three :listcol var=user
usage=out
entries appear in each row of the display.
maxwidth=1ð
help=huser

LIST Tag
.User Name
:listgrp col=objrights
à User Authorizations
ð
System: XXXXXXXX
-----Object Rights----- --------Data Rights---------
help=hobjaut.Object Rights User Name Oper Mgmt Exist Read Add Upd Dlt
XXXXXXXXXX X X X X X X X
:listcol var=oper XXXXXXXXXX X X X X X X X
usage=out XXXXXXXXXX
XXXXXXXXXX
X
X
X
X
X
X
X
X
X
X
X
X
X
X
maxwidth=7 XXXXXXXXXX
XXXXXXXXXX
X
X
X
X
X
X
X
X
X
X
X
X
X
X
.Oper XXXXXXXXXX
XXXXXXXXXX
X
X
X
X
X
X
X
X
X
X
X
X
X
X
:listcol var=mgmt XXXXXXXXXX X X X X X X X
usage=out XXXXXXXXXX X X X X X X X
maxwidth=7 XXXXXXXXXX
XXXXXXXXXX
X
X
X
X
X
X
X
X
X
X
X
X
X
X
.Mgmt XXXXXXXXXX X X X X X X X
More...
:listcol var=exist F3=Exit F12=Cancel
usage=out maxwidth=7 á ñ
.Exist
:elistgrp.
:listgrp col=dtarights Example 4: Dynamic List
help=hdtaaut.Data Rights Column Heading Formatting
:listcol var=read
usage=out This example shows how the column headings are
maxwidth=7 contained in dialog variables.
.Read
:listcol var=add
usage=out UIM Source
maxwidth=7 :listdef name=xmp4
.Add vars='var1 var2 var3'.
:listcol var=update :panel panel-attributes.
usage=out Example of Dynamic Column Headings
maxwidth=7 :list listdef=xmp4
.Upd depth='\'
:listcol var=delete headsize=colhsize.
usage=out :listcol var=var1
maxwidth=7 usage=inout
.Dlt maxwidth=1ð
:elistgrp. colhead='A B C D E F'.
:listview layout=1 :listcol var=var2
cols='user objrights dtarights' usage=inout
:elist. maxwidth=14
:epanel. colhead='G H'.
:listcol var=var3
Results usage=inout
maxwidth=1ð
colhead='I J K L'.
:listview layout=1
cols='var1 var2 var3'.
:elist.
:epanel.
Note: In this example, A B C D E F G H I J K
and L are dialog variables that would each be set
to one line of column heading text. In the screen
that follows, the actual text appears instead of the
dialog variable names. COLHSIZE is also a
dialog variable, and in this example it is set equal
to 4.

LIST Tag
Results
à Example of Dynamic Column Headings

ð
A I
B J
C G K
D H L
__________ ______________ __________
__________ ______________ __________
__________ ______________ __________
__________ ______________ __________
__________ ______________ __________
__________ ______________ __________
__________ ______________ __________
__________ ______________ __________
__________ ______________ __________
__________ ______________ __________
__________ ______________ __________
__________ ______________ __________
__________ ______________ __________
__________ ______________ __________
__________ ______________ __________
F3=Exit F12=Cancel
á ñ

LISTACT Tag
LISTACT (List Action)
55──:LISTACT──HELP=help-module-name──OPTION=number──┬──────────────────────┬─────────────5
│ ┌─BOTH────┐ │
└─ACTFOR=─┼─LISTE───┼──┘
└─EXTACTE─┘
5──┬────────────────────┬──┬─────────────────────┬──┬────────────────────────┬───────────5
└─CONFIRM=panel-name─┘ └─ENTER='action-text'─┘ └─EXTENTER='action-text'─┘
5──┬──────────────────────┬──┬─────────────────────────┬──┬────────────────────┬─────────5
└─PROMPT='action-text'─┘ └─EXTPROMPT='action-text'─┘ │ ┌─ENTER──┐ │
└─NOCMD=─┴─PROMPT─┴──┘
5──┬────────────────────┬──┬──────────────────────────────────┬──────────────────────────5
│ ┌─ENTER──┐ │ └─USREXIT='CALL program-reference'─┘
└─NOEXT=─┼─PROMPT─┼──┘
└─MSG────┘
5──┬─────────────────────────────┬──┬───────────────────────────────────────┬────────────5
└─EXTMSGID=message-identifier─┘ └─EXTMSGF='qualified-message-file-name'─┘
5──┬─────────────────────┬──┬──────────────────────┬──┬─────────────────────────────┬────5
└─COND=condition-name─┘ └─AVAIL=condition-name─┘ └─AVLMSGID=message-identifier─┘
5──┬───────────────────────────────────────┬──.──┬────────────────────┬─────────────────5%
└─AVLMSGF='qualified-message-file-name'─┘ └─action-description─┘
The list action (LISTACT) tag defines an operation There is no way to have the UIM perform some
which takes place on individual items of a list. actions and the calling program perform others.
This tag is allowed only for display panels.
Options entered by a user are not actually run When the CMD dialog command is used as the
until an Enter or Prompt function key is pressed, action performed for the extended action entry in
allowing the user to select several list items while an action list, the command text should be a
using the Page Up or Page Down keys. Control Language command, not a System/36
Environment OCL command. The value *N is
If ACTOR=UIM is specified on the list area (LIST) substituted in the command text for any dialog
tag, all actions indicated by LISTACT tags are per- variable from the extended action entry that has a
formed by the UIM. These actions must have the blank value. An exception to this is when
ENTER attribute specified, and may also have the NOEXT=MSG is specified on this tag, indicating that
PROMPT and USREXIT attributes specified. If the command should not be submitted when any
ACTOR=CALLER is specified on the LIST tag, the of the values for the extended action entry are
actions are handled by the program which called blank. This consideration applies to the following
the Display Panel (QUIDSPP) API. In this case, attributes of this tag:
none of the following attributes can be specified
ENTER
on the LISTACT tag:
PROMPT
CONFIRM EXTENTER
ENTER EXTPROMPT
PROMPT
USREXIT Required Attributes
EXTENTER
EXTPROMPT HELP=help-module-name
NOEXT Identifies the associated help module for this
EXTMSGID list action. The online help information for all
EXTMSGF actively-conditioned list actions is always
added to the online help information for the
action column.

LISTACT Tag
OPTION=number ified on this tag, NOEXT=MSG must also be

The value associated with the option selected specified on this tag.
for this item in the list. The value must be an
A maximum of 20 different LISTACT tags for a
integer value in the range of 1 through 999.
single action list may specify the CONFIRM attri-
The action field variable must be defined with
bute. This does not impose any restriction on
a BASETYPE of ACTION on the class definition
the number of list entries that any one of the
(CLASS) tag. The values of the action field
actions may be applied to.
are automatically limited to the valid options
by the UIM. An error occurs when the user For more information on required and recom-
enters a number in the action field for which mended conventions for this attribute, see
there is no active LISTACT tag. “Confirmation Panel Requirements” on
page A-94 and “Confirmation Panel
Conventions” on page A-94.
Optional Attributes
ENTER='action-text'
ACTFOR=BOTH | LISTE | EXTACTE
Specifies the action occurring when the list
Indicates whether the list action defined is
action is requested through the ENTER dialog
allowed for the existing list entries, the
command. This attribute is required if
extended action entry, or both. The default is
ACTOR=UIM is specified on the LIST tag. The
BOTH.
valid forms of action-text are:
If LISTE is specified, the action defined is
valid only in the action fields associated with 'CALL program-reference'
the existing list entries on the display. For a description of the interface between
the UIM and the exit program for an action
EXTACTE indicates that the action defined is list option, see the System API Reference.
valid only in the action field for the extended
action entry. For example, ACTFOR=EXTACTE 'CMD command-string'
might be used for Option 1=Create, because Any dialog variable name in the command
the create option is not allowed for an existing string must be preceded by an ampersand
entry. and should be ended with a period to
denote variable substitution.
CONFIRM=panel-name
The confirmation panel displayed before the For a description of each of these actions, see
list action is performed. The confirmation Appendix B, “UIM Dialog Commands” on
panel must give the user the option to confirm page B-1.
or not confirm the list action. If the action is This attribute is repeatable, allowing the con-
confirmed, the appropriate actions from the struction of long command strings.
ENTER, EXTENTER, and USREXIT attributes of
this tag are performed. If the action is not The PARMS attribute on the LIST tag identifies
confirmed, none of those actions are per- a dialog variable that can be substituted into a
formed. command string on the CMD dialog command.
Additional functions are provided for list
The actions coded on the PROMPT and actions which use the CMD dialog command.
EXTPROMPT attributes of this tag are not con- When parameters from the command line are
firmed. The prompt screen that results from substituted into a command string, the param-
the PROMPT and EXTPROMPT actions serves as eters from the command line override the
the confirmation panel, allowing users to same parameter defined in the command
change their minds and cancel the action. string if the parameter in the command string
The confirmation panel must be another panel is preceded by the "?<" or "??" selective
defined within this panel group. prompting characters.
The CONFIRM attribute is only allowed when This function allows a prompt for a command
ACTOR=UIM is specified in the LIST tag. to show the parameter values from the
When the CONFIRM attribute is specified, command line, or to show the current param-
EXTACT=YES is specified on the LIST tag and eter values for the object when an overriding
if ACTFOR=BOTH or ACTFOR=EXTACTE is spec- parameter is not on the command line. When

LISTACT Tag
the "?<" or "??" selective prompting characters command line, or to show the current param-
are used, it is your responsibility to have the eter values for the object when an overriding
current parameter values substituted into the parameter is not on the command line. When
command string. the "?<" or "??" selective prompting characters
are used, it is your responsibility to have the
EXTENTER='action-text'
current parameter values substituted into the
command string.
action for the extended action field is
requested through the ENTER dialog EXTPROMPT='action-text'
command. This attribute is not allowed when Specifies the action occurring when the list
ACTFOR=LISTE is specified on the LISTACT action for the extended action field is
tag, or when EXTACT=NO is specified on the requested through the PROMPT dialog
LIST tag. command. The EXTPROMPT attribute is not
allowed when ACTFOR=LISTE is specified on
The syntax and usage of this attribute is the
the LISTACT tag, when EXTACT=NO is speci-
same as the ENTER attribute for this tag. If the
fied on the LIST tag, or when the PROMPT attri-
EXTENTER attribute is not specified, the action
bute is not specified on this tag.
specified on the ENTER attribute is used.
The syntax and use of this attribute is the
PROMPT='action-text'
same as for the PROMPT attribute on this tag. If
the EXTPROMPT attribute is not specified, the
action is requested through the PROMPT
action specified on the PROMPT attribute is
dialog command. The valid forms of action
used.
text are:
NOCMD=ENTER | PROMPT
Specifies the action the UIM performs for the
ENTER dialog command when the command
the UIM and the exit program for an action
line is blank.
list option, see the System API Reference.
ENTER indicates that the action on the ENTER
'CMD command-string'
attribute of this tag should be performed.
Any dialog variable name in the command
string must be preceded by an ampersand PROMPT indicates that the action on the
to denote variable substitution. PROMPT attribute of this tag should be per-
formed.
For a description of these actions, see
Appendix B, “UIM Dialog Commands” on This allows you to have a command prompted
page B-1. when the command line is empty, but not
prompted if the command line contains param-
This attribute is repeatable, allowing the con- eters.
struction of long command strings.
For an explanation of how this attribute inter-
The PARMS attribute on the LIST tag identifies acts with the NOEXT attribute of this tag, see
a dialog variable that can be substituted into a Table A-10 on page A-93.
command string on the CMD dialog command.
Additional command submission support is NOEXT=ENTER | PROMPT | MSG
activated for list actions which use the CMD Specifies the action the UIM should perform
dialog command. When parameters from the for the ENTER dialog command when one or
command line are substituted into a command more of the input fields on the extended action
string, the parameters from the command line entry are blank.
override the same parameter defined in the ENTER indicates that the action on the
command string if the parameter in the EXTENTER attribute of this tag should be per-
command string is preceded by the "?<" or formed.
"??" selective prompting characters.
PROMPT indicates that the action on the
This function allows a prompt for a command EXTPROMPT attribute of this tag should be per-
to show the parameter values from the formed.

LISTACT Tag
MSG indicates that no action should be per- EXTMSGID='message-identifier'

formed and that the message specified on the The message identifier of the message dis-
EXTMSGID attribute of this tag should be sent to played when the action defined by this tag
the user. When MSG is specified, the cannot be performed because one or more
EXTMSGID attribute is required. input fields on the extended action entry are
blank. This attribute is required when
For an explanation of how this attribute inter-
NOEXT=MSG is specified on this tag; it is not
acts with the NOCMD attribute, see Table A-10.
allowed otherwise.
This table shows how the NOCMD and NOEXT
attributes operate when the command line is EXTMSGF='qualified-message-file-name'
blank and one or more of the input fields on The message file name that contains the
the extended action entry are blank. message identifier. The attribute is allowed
only when the EXTMSGID attribute is specified
Table A-10. NOCMD and NOEXT Attribute Inter- on this tag. If the DFTMSGF attribute is not
action
specified on the panel group (PNLGRP) tag,
NOCMD NOEXT Result this attribute must be specified when the
ENTER ENTER EXTENTER attribute is EXTMSGID attribute on this tag is specified.
used
COND=condition-name
PROMPT ENTER EXTPROMPT attribute is The list action is in effect on the panel only if
used the condition specified is true. The condition
ENTER PROMPT EXTPROMPT attribute is must be defined in the panel group prolog with
used the condition definition (COND) tag. If the
PROMPT PROMPT EXTPROMPT attribute is conditions for all LISTACT tags are false, the
used action column still appears on the display, but
no option numbers are valid. It is up to you to
ENTER MSG EXTMSGID message is
displayed ensure that some options remain valid for the
list.
PROMPT MSG EXTMSGID message is
displayed AVAIL=condition-name
The list action is available only if the condition
This table is used only when all of the fol- specified evaluates to true. The condition
lowing are true: must be defined in the panel group prolog with
the COND tag.
1. A list action option is being processed for
the extended action entry. Unavailable actions are displayed with an
2. The command line is blank. asterisk (*) overlaying the first part of the
3. One or more of the input fields on the action description. Online help information is
extended action entry are blank. displayed for unavailable list actions.
When the condition is true, the list action is
USREXIT='CALL program-reference'
available. When the condition is false, the list
Specifies the list exit program the UIM calls to
action is not available. Any condition speci-
update or delete this list entry after the action
fied on the COND attribute takes precedence
defined in either the ENTER, EXTENTER, PROMPT,
over this attribute.
or EXTPROMPT attribute of this tag is performed.
The program is passed information that AVLMSGID=message-identifier
includes an indication of whether the option The message identifier of the message dis-
succeeded or failed. played when a number is entered and is not
For a description of the CALL dialog available as specified by the AVAIL attribute of
command, see Appendix B, “UIM Dialog this tag. This attribute is allowed only when
Commands” on page B-1. the AVAIL attribute is specified.
For a description of the interface between the If this attribute is not specified, the UIM dis-
UIM and the program for an action list, see plays a default message stating that the
the System API Reference. option number is not currently available.

LISTACT Tag
AVLMSGF='qualified-message-file-name' Confirmation Panel Conventions

The message file name that contains the
message identifier. The attribute is allowed The panel named in the CONFIRM attribute of this
only when the AVLMSGID attribute of this tag is tag should follow these conventions:
specified. If the DFTMSGF attribute is not speci-
fied on the PNLGRP tag, this attribute must It should have title text and top instructions to
be specified when the AVLMSGID attribute on describe the panel.
this tag is specified. It should have a single list area with a list defi-
nition containing the same (or a subset of) the
Optional Text columns defined in the original action list.
action-description The list should be scrollable.

The text shown as part of the top instructions If the action list has multiple views, the confir-
for the list area. If no text is supplied, none is mation list should also have multiple views
listed in the instruction part of the list area for and the same dialog variable should be used
this action. The text must appear on the for the view variable on both lists. The confir-
same or next line as the tag and can only mation panel should have a function key
contain the reverse text (RT) tag. defined for the CHGVIEW dialog command.
The instruction line is formed by concatenating When the same view variable is used for both
the text from the various list actions, sepa- lists, it allows a change view operation on the
rated by three spaces. If the text does not fit confirmation panel to change the view of the
on the rest of a line, it is placed on the next action list panel when it is redisplayed.
line. It should have function key definitions for the
ENTER, CANCEL, PAGEDOWN, PAGEUP,
Confirmation Panel Requirements HELP, and PRINT dialog commands.
If a general exit program is defined, it should
The panel named on the CONFIRM attribute of this avoid making changes to the action list and
tag must follow these conventions: avoid changing condition values that affect the
The ENTER attribute on the display panel redisplay of the original action list panel.
(PANEL) tag of the confirmation panel must The list used on the confirmation panel should
have 'RETURN 100' coded. This indicates to not be used on anything but a confirmation
the UIM that the action is confirmed by the panel, because the UIM deletes and changes
user. the contents of that list. If multiple confirma-
No ACTION attribute on a key list item (KEYI) tion panels are used within a UIM application,
tag can be assigned to the RETURN dialog they use the same list definition.
command, because the UIM is handling the Most of the help information for the action list
display of the panel and is not able to interpret panel can be used for the confirmation panel,
the returned value. but separate help information should be pro-
The confirmation panel must have a list area. vided for the action column and the extended
help.
The list used as the confirmation list must not
be the same list displayed in the action list The class definition for the list option variable
panel. defined with a BASETYPE of ACTION on the
CLASS tag should have a WIDTH attribute on
The confirmation panel must not have a menu
the CLASS tag to accommodate the largest
bar, action list, command line, or menu area.
list action option on the action list panel. For
example, if the largest option number on the
action list panel is 12, WIDTH=2 should be
specified on the class definition for the action
variable. This ensures that the option number
is displayed in the same position under the

LISTACT Tag
column heading on the confirmation panel as will be shown as blanks even though there
it was on the action list panel. may be a value there.
Only the values for the input capable fields of
the extended list action entry will be displayed Example: List Actions
on the confirmation panel. All other columns
This example shows how the action options on a
display are defined.
UIM Source Results
:listact option=2
help='option/2' à ð
enter='CALL CHGPGM' Type choices, press Enter.
2=Change 4=Delete 5=Display
.2=Change
:listact option=4
help='option/4'
enter='CALL DLTPGM'
confirm=CONFDLT
.4=Delete
:listact option=5
help='option/5'
enter='CALL DSPPGM'
.5=Display

LISTCOL Tag
LISTCOL (List Column)

55──:LISTCOL──VAR=list-object-variable-name──MAXWIDTH=─┬─column-width─┬────────────────────5
└─'\'──────────┘
5──USAGE=─┬─OUT───┬───┬───────────────────────┬──┬───────────────────────┬─────────────────5
└─INOUT─┘ └─HELP=help-module-name─┘ └─COL=column-identifier─┘
5──┬───────────────────────┬──┬─────────────────────┬──┬──────────────────┬────────────────5
└─NAME=list-column-name─┘ └─JUSTIFY=─┬─LEFT──┬──┘ │ ┌─NO──┐ │
├─RIGHT─┤ └─EXTACT=─┴─YES─┴──┘
├─START─┤
└─END───┘
5──┬──────────────────────┬──┬───────────────────────────────┬─────────────────────────────5
└─PROMPT='action-text'─┘ └─DSPVALUE=dialog-variable-name─┘
5──┬─────────────────────────────────────┬──┬───────────────────┬──────────────────────────5
└─COLHEAD='dialog-variable-name-list'─┘ │ ┌─YES─┐ │
└─DISPLAY=─┴─NO──┴──┘
5──┬────────────────────┬──.──┬────────────────┬──────────────────────────────────────────5%
│ ┌─YES─┐ │ └─column-heading─┘
└─AUTOSKIP=─┴─NO──┴──┘
55──:LISTCOL──VAR=list-object-variable-name──MAXWIDTH=─┬─column-width─┬───┬───────────┬────5
└─'\'──────────┘ └─USAGE=OUT─┘
5──┬───────────────────────┬──┬─────────────────────┬──────────────────────────────────────5
└─COL=column-identifier─┘ └─JUSTIFY=─┬─LEFT──┬──┘
├─RIGHT─┤
├─START─┤
└─END───┘
5──┬─────────────────────────────────────┬──.──┬────────────────┬─────────────────────────5%
└─COLHEAD='dialog-variable-name-list'─┘ └─column-heading─┘
The list column (LISTCOL) tag defines a column size for a column heading is four characters.
that may belong to any of several list views. This Specification of a width longer than that
tag is allowed for display panels and print panels. defined in the class definition (CLASS) tag
It specifies the dialog variable, whether the field allows more room for the formatting of column
allows the user to enter data or is for output only, headings, but does not allow more data to be
the column width, and the column heading. entered into the field. Specification of a width
shorter than the class width on the CLASS tag
Required Attributes is allowed only for CHAR or IGC variables,
and is not allowed for input columns.
VAR=list-object-variable-name
If '*' is coded, the remainder of the area width
The name of the variable from the underlying
is used for the column, and values in that
list object to display in this column.
column can be truncated. Only one column
MAXWIDTH=column-width | '*' may have '*' coded. A warning message is
The maximum width of the column. The width put in the compiler listing if the column with '*'
may allow for translation of the column specified is not the last column of all views. A
heading into other languages. The minimum two- to five-character separator is maintained
between columns.

LISTCOL Tag
USAGE=OUT | INOUT window near this list column. This attribute is

The display use of the column. This attribute allowed only for display panels.
is required for display panels, but is optional
If the list column is part of a list column group
for print panels.
defined by the LISTGRP tag and both the
USAGE=OUT defines an output data column. LISTCOL and LISTGRP tags have the NAME
OUT indicates that the variable displayed is attribute specified, the list column name is set
for output only and cannot be changed by the in the dialog variable specified on the CSRNAME
user. attribute of the display panel (PANEL) tag
when the cursor is anywhere in the list
USAGE=INOUT defines a data entry column.
column. The list group name is set for the
CSRNAME attribute on the PANEL tag when the
cursor is positioned between columns or on
USAGE=INOUT fields are not allowed for print
an unnamed list column within the named list
panels, but are required for the action column
group. For a description of the CSRNAME attri-
of an active list.
bute, see “PANEL (Display Panel)” on
page A-122.
Optional Attributes
HELP=help-module-name Indicates whether the dialog variable values
Identifies online help information which should be left-justified or right-justified within
explains the purpose of the column in this list. the list column. If the ALIGN attribute of this
This attribute is allowed only for display tag is omitted, the default right-justifies values
panels. The help module name may be a for numeric dialog variables and left-justifies
name imported from another panel group, but nonnumeric dialog variables.
must follow the rules for names outlined
earlier in this chapter. For more information Leading blanks are preserved when the dialog
on the rules for names, see “Name Syntax” on variable is left-justified. Right-justification
page A-4. strips all trailing blanks. The UIM rules for
editing a numeric dialog variable produces a
The HELP attribute is not allowed if this column displayable value which does not contain any
is part of a list column group defined by the leading blanks.
list group (LISTGRP) tag, but is required if the
column is not part of a group. A common case where you might want to
override the alignment default is for a column
COL=column-identifier of values whose BASETYPE is defined as
The identifier of the column, which can be numeric on the CLASS tag, but whose dis-
referred to in the COLS attribute on the list playable values are sometimes special values
view (LISTVIEW) tag. If the identifier is not generated through a translation list. For more
supplied, it defaults to the dialog variable information on translation lists, see “TL
name specified on the VAR attribute of this tag. (Translation List)” on page A-159.
These names are in a separate name space
START is a synonym for LEFT and END is a
from all other names and are meaningful only
synonym for RIGHT.
within the list area, not to the panel group.
A list column identifier cannot be specified and EXTACT=NO | YES
no default column name is assumed if the Specifies whether or not this list column is
column is part of a list column group defined input-capable for the extended action entry.
by the LISTGRP tag. This attribute is allowed only for display
panels.
NAME=list-column-name
EXTACT=NO specifies that this list column does
The name associated with the column. For
not have an input-capable field in the
more information on the rules for naming, see
extended action entry.
EXTACT=YES specifies that this list column
This name can be used with the Add Pop-Up
does have an input-capable field in the
Window (QUIADDPW) API to position a
extended action entry. When EXTACT=YES is

LISTCOL Tag
specified on the list area (LIST) tag, COLHEAD='dialog-variable-name-list'

EXTACT=YES must be specified on at least two A list of dialog variables separated by blanks,
columns in each list view, including the action specifying the column heading placed above
column. the list items in the list area. Up to ten dialog
variables can be specified. These dialog vari-
Any column with EXTACT=YES specified must
ables must have a BASETYPE of CHAR or IGC
be in every view of the list area.
specified on the CLASS tag, and must have a
PROMPT='action-text' width greater than or equal to the class width
The action occurring when F4=List is of the dialog variable specified on the VAR
requested through the PROMPT dialog attribute of this tag, and less than or equal to
command. This attribute is allowed only for the width specified on the MAXWIDTH attribute of
display panels. This attribute is not allowed this tag. All variables specified on a single
for a dialog variable defined with a BASETYPE COLHEAD attribute must be defined with the
of ACTION on the CLASS tag or for any identical class.
USAGE=OUT list columns on this tag. The valid
Each dialog variable is used as a line of
forms of action text are:
column heading text. The UIM does no
'CALL program-reference' aligning or justification on the contents of
For a description of the interface between these dialog variables.
the UIM and the exit program for a cursor- If this attribute is used, column heading text
sensitive prompt, see the System API Ref- cannot be specified after the period for this
erence. tag, the MAXHEAD attribute must not be speci-
'RETURN positive-integer' fied on the LIST tag, but the HEADSIZE attribute
of the LIST tag must be specified.
For a description of these actions, see
Appendix B, “UIM Dialog Commands” on This attribute may not be used on list columns
page B-1. that are part of list column groups.
DSPVALUE='dialog-variable-name' DISPLAY=YES | NO
The dialog variable containing the current data Indicates whether or not the fields in the list
entered in the list entry which contains the column are visible when the panel is dis-
cursor. This attribute is allowed only for played. This attribute is allowed only for
display panels and when the PROMPT attribute display panels. YES indicates that the fields
is coded on this tag. This variable is updated in the list column are visible.
regardless of whether or not the variable pool NO indicates that the fields in the list column
is updated. The variable pool is updated are not visible. NO can only be specified for a
based on the VARUPD attribute of the key item column in the list when USAGE=INOUT is spec-
(KEYI) or pull-down field choice (PDFLDC) ified on this tag and ACTOR=NONE is specified
tag. This updating is independent of the on the LIST tag.
normal updating of the variable pool.
AUTOSKIP=YES | NO
The dialog variable specified must be defined Indicates whether or not the cursor should
on the CLASS tag as a CHAR or IGC variable automatically move to the next input field
whose length is the same as the width of the when data is entered in the last position of the
dialog variable specified on the VAR attribute of list column field. This attribute is allowed only
this tag. No translation processing or validity for display panels. YES is the default.
checking is performed for the value before it is
placed in this variable. Character set and YES indicates that the cursor automatically
code page conversion is performed for this moves to the next input field.
variable if the class of the variable named on NO indicates that the cursor does not auto-
the VAR attribute of this tag specifies that the matically move to the next input field. NO can
character set and code page conversion only be specified for a column in the list when
should be performed. USAGE=INOUT is specified on this tag and
ACTOR=NONE is specified on the LIST tag.

LISTCOL Tag
Optional Text right for JUSTIFY=LEFT and on the left for

JUSTIFY=RIGHT. The following example shows all
column-heading three situations:
The column heading placed above the column Center Data Align Left Align Right
in the reserved part of the list area. If no xxxxxxx xxxxxxx nnnnnnnn
column heading or the COLHEAD attribute is xxxxxxx xxxxxxx nnnnnnnn
specified, no column heading is displayed. xxxxxxx xxxxxxx nnnnnnnn
The text may appear on more than one line xxxxxxx xxxxxxx nnnnnnnn
and can only contain the reverse text (RT)
When the width of the column data is greater than
tag.
the width of the column heading text, the column
Each word of the column heading is placed on heading text is adjusted to the left for
a new line. If multiple words are necessary in JUSTIFY=LEFT and to the right for
a line of the column heading, they must be JUSTIFY=RIGHT. The following example shows
enclosed in apostrophes ('). Each word or these situations:
quoted string must fit within the maximum
Align Left Align Right
column width defined by the MAXWIDTH attri- xxxxxxxxxxxx nnnnnnnnnnnnn
bute of this tag. The maximum number of xxxxxxxxxxxx nnnnnnnnnnnnn
words or quoted strings allowed is specified xxxxxxxxxxxx nnnnnnnnnnnnn
by the MAXHEAD attribute on the LIST tag. xxxxxxxxxxxx nnnnnnnnnnnnn
Column headings are not allowed if MAXHEAD=0
is used for the list area. If the column heading text requires more than one
Column headings are justified according to the line, the shorter lines of text are centered with
JUSTIFY attribute of this tag only if they are respect to the longest line. If the shorter lines do
specified as text. No justification is done not center evenly under the longer lines, the addi-
when the COLHEAD attribute is specified on this tional space is on the right for JUSTIFY=LEFT and
tag. on the left for JUSTIFY=RIGHT. The following
example shows all situations:
If no column heading text or COLHEAD attribute
Line Up Line Up Line Up Line Up
is specified on any LISTCOL tag for the area,
Line Up Head Head Head Head
no lines are reserved on the display for Right Right Right Right Left
heading information. nnnnnnn nnnnnnn nnn nnnnnnnnn xx
nnnnnnn nnnnnnn nnn nnnnnnnnn xx
Formatting Considerations nnnnnnn nnnnnnn nnn nnnnnnnnn xx
nnnnnnn nnnnnnn nnn nnnnnnnnn xx
When the width of the column data is less than
the width of the column heading text, the column
data is centered under the column heading text. If
the data does not center evenly under the
heading, the additional space is placed on the

LISTDEF Tag
LISTDEF (List Definition)
55──:LISTDEF──NAME=list-name──VARS='dialog-variable-list'────────────────────────────────5
5──┬─────────────────────────────┬──┬──────────────────────────┬─────────────────────────5
└─CHGVAR=dialog-variable-name─┘ └─MSGID=message-identifier─┘
5──┬───────────────────────────────┬──┬────────────────────────────────────┬─────────────5
└─MSGIDVAR=dialog-variable-name─┘ └─MSGF='qualified-message-file-name'─┘
5──┬──────────────────────────────┬──┬──────────────────────────────────────────┬────────5
└─PRTFLAG=dialog-variable-name─┘ └─EMPHASIS='dialog-variable-emphasis-list'─┘
5──┬──────────────────────────────────────┬──.──────────────────────────────────────────5%
└─PROTECT='dialog-variable-usage-list'─┘
The list definition (LISTDEF) tag defines UIM lists list area (LIST) tag. Only one column of a list
which are data structures maintained by the UIM. may be specified as an action column.
These lists contain the data for list areas pre-
sented on the display. UIM lists consist of a vari- Optional Attributes
able number of rows. Each row contains one or
more columns, and each column in the row con- CHGVAR=dialog-variable-name
tains a copy of one dialog variable value. These Specifies that any list entry values entered by
lists are manipulated by the program using the the user must be compared to values already
UIM application programming interfaces (APIs). in the list entry. This attribute also indicates
Lists may be shared among panels which contain where the comparison result should be stored.
list areas. The dialog variable specified must be one of
the variables listed on the VARS attribute of
this tag, and must be defined with a BASETYPE
Required Attributes
of CHAR 1 on the CLASS tag.
NAME=list-name
List values are compared using the internal
The name of the list object. This name must
form of each dialog variable rather than its
be unique within the panel group. For more
display form. If any values in the list entry are
information on the rules for naming, see
changed, the list value associated with the
dialog variable specified on this attribute is set
VARS='dialog-variable-list' to '1'. If all the new list values are equal to
The list of up to 50 variables which make up the old list values, no special processing is
the columns of the list. All dialog variables in performed; the dialog variable specified for
this list must be previously defined using the this attribute is not changed.
variable definition (VAR) tag in this panel Note: The dialog variable specified on this
group. Not all of these variables need to be attribute is set to '1' each time the user
displayed in a view defined with the list view changes the list entry, scrolls the list, or uses
(LISTVIEW) tag. The variable names in the some other function key. The list value asso-
list are separated by blanks. ciated with the dialog variable specified on this
The UIM automatically determines what attribute is set to '1' twice if a value in the list
column is used for action list or selection list is changed, the list is scrolled, scrolled back
processing by identifying the variable specified again to the original position, and the list entry
on the VARS attribute and defined with a is changed back to its original value.
BASETYPE of ACTION on the class definition An application program can use the list value
(CLASS) tag. An action column is required for for the dialog variable specified on this attri-
each list view when an ACTOR or SELECT value bute to determine which list entries are
other than NONE is specified, or when changed by the user. The application is
SELECT=SINGLE or MULTI is specified on the responsible for setting and resetting the list
entry value to something other than '1'. It

LISTDEF Tag
does this by updating the list entry after the tag. The number of items in the list must be
input values are processed and before the list the same as the number of dialog variables
is redisplayed to make the comparison reli- specified on the VARS attribute. Only one
able. emphasis is allowed for each variable listed,
but a particular emphasis value may apply to
MSGID=message-identifier
more than one variable. A value of '*' should
The message identifier of a message that is
be specified to indicate that normal emphasis
displayed to the user when the UIM list is
should be used with the corresponding vari-
empty. If no message identifier is specified
able listed on the VARS attribute, and also used
with either the MSGID or MSGIDVAR attribute on
for list columns not displayed in any list view.
this tag, no message is displayed when the
list is empty. The MSGID and the MSGIDVAR The dialog variables specified on this attribute
attributes cannot both be used on the same cannot be one of the variables listed on the
LISTDEF tag. VARS attribute of this tag.
MSGIDVAR=dialog-variable-name Each variable in the list must be defined with

A dialog variable containing the message a BASETYPE of CHAR 1 on the CLASS tag.
identifier of a message displayed to the user When an entry is added to the list or an
when the UIM list is empty. The dialog vari- existing entry is updated, the values for these
able specified must be defined with a variables determine the emphasis used when
BASETYPE of 'CHAR 7' on the CLASS tag. If that entry is displayed. The following table
no message identifier is specified with either shows the values that can control the
the MSGID or MSGIDVAR attribute on this tag, no emphasis.
message is displayed when the list is empty.
The MSGID and the MSGIDVAR attributes cannot Table A-11. Emphasis Values
both be used on the same LISTDEF tag. Value Output Field Input
Field
MSGF='qualified-message-file-name'
The message file name containing the 0 Normal Normal
message identifier specified on the MSGID or 1 Emphasize Emphasize
MSGIDVAR attribute. The attribute is allowed
2 De-emphasize Normal
only when the MSGID or MSGIDVAR attribute is
specified on this tag. If the DFTMSGF attribute
is not specified on the panel group (PNLGRP) Normal and de-emphasis are the same on a
tag, this attribute must be specified when the monochrome device.
MSGID or MSGIDVAR attribute on this tag is If a dialog variable listed in this attribute has a
specified. value specified other than one of the above
PRTFLAG=dialog-variable-name values, normal emphasis is used. If this attri-
Specifies the name of a dialog variable in the bute is not specified, normal emphasis is
list definition containing a character printed on used.
the first character of each list entry. For each This attribute does not control emphasis
list entry printed, the character stored in the during printing.
dialog variable is printed on the first column.
The dialog variable specified must be one of PROTECT='dialog-variable-usage-list'
the variables listed on the VARS attribute of this The list of dialog variables containing the
tag, and must be defined on the CLASS tag value used to override the USAGE attribute of
with a BASETYPE of CHAR 1 and a width of 1. the list column (LISTCOL) tag for each of the
This attribute is intended to be used for output variables listed on the VARS attribute of this
listing applications where a special character tag. The number of items in the list must be
needs to be printed in column one. the same as the number of dialog variables
specified on the VARS attribute. Only one pro-
EMPHASIS='dialog-variable-emphasis-list.' tection value is allowed for each variable
The list of dialog variables containing the listed, but a particular protection value may
emphasis or color associated with each of the apply to more than one variable.
variables listed on the VARS attribute of this

LISTDEF Tag
A value of '*' should be specified to indicate tag. The valid values for the dialog variables
that there is no override for the USAGE attribute specified on this attribute are as follows:
on the LISTCOL tag for the corresponding
'1' The variable use is output-only.
variable listed on the VARS attribute. A value
of '*' is also used for list columns not dis- '0' The use is controlled by the USAGE
played in any list view. attribute on the LISTCOL tag.
The dialog variables specified on this attribute Changing a list option field for an action list or
cannot be one of the variables listed on the selection list to output-only does not affect list
VARS attribute. processing. If the action field contains an
Each variable in the list must be defined with option number or selection value but is dis-
a BASETYPE of CHAR 1 on the CLASS tag. played as output-only, the option is processed.
When an entry is added to the list or an If a dialog variable listed in this attribute is not
existing entry is updated, the values for these specified or has a value specified other than
variables determine the protection whenever '1' or '0', the use is controlled by the USAGE
that entry is displayed. This attribute over- attribute of the LISTCOL tag.
rides the USAGE attribute from the LISTCOL

LISTGRP Tag
LISTGRP (List Column Group)

55──:LISTGRP──COL=column-identifier──HELP=help-module-name─────────────────────────────────5
5──┬─────────────────────────────┬──┬────────────────┬──.──┬───────────────┬───────────────5
└─NAME=list-column-group-name─┘ │ ┌─\─┐ │ └─group-heading─┘
└─COLSEP=─┴─N─┴──┘
5──:ELISTGRP.─────────────────────────────────────────────────────────────────────────────5%
55──:LISTGRP──COL=column-identifier──┬────────────────┬──.──┬───────────────┬──────────────5
│ ┌─\─┐ │ └─group-heading─┘
└─COLSEP=─┴─N─┴──┘
5──:ELISTGRP.─────────────────────────────────────────────────────────────────────────────5%
The list column group (LISTGRP) tag groups this list. This attribute is required for display
columns in a list area together under a single panels; it is not allowed for print panels. The
heading that applies to all the columns. This tag help module name may be a name imported
is allowed for display panels and print panels. from another panel group, but must follow the
Columns may be defined within the list area that rules for names outlined earlier in this chapter.
do not belong to any list column group. This tag For more information on the rules for names,
cannot be used in a list area if MAXHEAD=0 is spec- see “Name Syntax” on page A-4.
ified on the list area (LIST) tag for the area.
There are some restrictions on the kinds of

Optional Attribute
columns that can exist within a column group. NAME=list-column-group-name
The name associated with the group. This
The action column of the list cannot be in a
attribute is allowed only for display panels.
column group.
All or none of the columns can have column see “Name Syntax” on page A-4. This name
headings. can be used with the Add Pop-Up Windows
Column groups cannot be nested. (QUIADDPW) API to position a window near
this list column group.
At least one column must be defined within a
column group. COLSEP=* | N
The number of spaces by which to separate
columns in a list column group. COLSEP=\
Required Attributes causes UIM to calculate the width of the
COL=column-identifier. column separator. The calculated width is
The identifier of the column group, which is between 2 and 5 spaces. COLSEP=N can be
referred to in the COLS attribute on the list view any positive number. When choosing a value
(LISTVIEW) tag. These names are in a sepa- for N, keep in mind the widths of the columns.
rate name space from all other names and are This attribute does not affect the space
meaningful only within the list area, not within between list column groups and other list
the panel group. columns. It also does not affect the space fol-
lowing selection columns in list column
HELP=help-module-name groups.
Identifies online help information which
explains the purpose of the column group in

LISTGRP Tag
Optional Text UIM Source

:listdef name=list1
group-heading
vars='seq colname more table text'.
The group heading text placed above the
:panel panel-attributes.Select and Sequence Columns
column group in the heading part of the list :list listdef=list1
area. This heading must fit on one line over depth='\'
the columns in the group. It is centered over maxhead=3.
the group of columns and has a graphic indi- :topinst.Type sequence numbers (1-999) to select
cation of the number of columns over which it columns, press Enter.
spans. The headings of the columns in a :listcol var=seq
column group may span different numbers of usage=inout
lines. The group heading appears on the line maxwidth=3
immediately above the tallest column heading help=hseq.Seq
of the group. :listgrp col=column
colsep=1
No column in a column group may have help=hlistgrp.
MAXWIDTH='*' specified on the list column :listcol var=colname
(LISTCOL) tag. The columns and the separa- usage=out
tors between the columns define the width maxwidth=18.Column
allocated for the group heading. The group :listcol var=more
heading must be no longer than this width. usage=out
maxwidth=1.
If no column headings are specified on any of :elistgrp.
the columns of the group, the group heading :listcol var=table
appears immediately above the column data. usage=out
maxwidth=2ð
The text must appear on the same or next line
help=htable.Table
as the tag and can only contain the reverse
:listcol var=text
text (RT) tag. usage=out
maxwidth=25
Example: List Column Group help=htext.Text
:listview layout=1
This example uses a column separator of 1. cols='seq column table text'.
:elist.
:epanel.
Results
à Select and Sequence Columns

ð
Type sequence numbers (1-999) to select columns, press Enter.
Seq Column Table Text

___ EXTRALONGCOLUMNNAM > TABLE DESCRIPTION TEXT DESCRIPTION
___ SHORTCOLUMNNAME TABLE DESCRIPTION TEXT DESCRIPTION
Bottom
á ñ

LISTVIEW Tag
LISTVIEW (List View)
55──:LISTVIEW──COLS='column-identifier-list'─────────────────────────────────────────────5
5──┬───────────────────────────────────────┬──.─────────────────────────────────────────5%
│ ┌─1────────────────────────┐ │
└─LAYOUT=─┴─number-of-layout-columns─┴──┘
The list view (LISTVIEW) tag defines one of the Required Attribute
views of a list presented in a list area. This tag is
allowed for both display panels and print panels. COLS='column-identifier-list'
A list of column or column group identifiers
Multiple list views can be defined in an area and which are separated by blanks. This list iden-
can be changed using the CHGVIEW dialog tifies columns and groups that are part of this
command, which can be assigned to a function view.
key or to a pull-down choice. If there is more than All variables used in this view must be distinct.
one list view on the panel and the CHGVIEW
dialog command is performed, the list area with
the cursor in it changes views. Optional Attribute
LAYOUT=1 | number-of-layout-columns
The view may also be established in a program by
Indicates whether more than one set of
changing the value of the dialog variable specified
columns should be presented on the display
on the VIEW attribute on the list area (LIST) tag.
at one time. If the width of columns defined
Views are numbered consecutively from zero to
by the COLS attribute of this tag is small, it
one less than the number of LISTVIEW tags
may be possible to position more than one set
defined in this area. The first LISTVIEW tag for
of the columns on the display or page.
the list area defines view zero, the second
LISTVIEW tag defines view one, and so on for The format used for multiple-column layout
each LISTVIEW tag in the list area. divides the entire display or page width into
layout columns of equal size, with a separator
If the ACTOR attribute on the LIST tag has a value of at least three characters between layout
other than NONE, the action column of the list columns. All list columns specified on the
must appear in all views of the list area for the COLS attribute of this tag must fit within a
panel. If the SELECT attribute on the LIST tag has single layout column.
a value other than NONE or MULTI, the action
For all panels with WIDTH=132 on the display
column of the list must appear in all views of the
panel (PANEL) or print panel (PRTPNL) tags,
list area.
a value from 1 through 10 is allowed. For
panels with WIDTH less than 132, a value from
Although multiple views can be defined for a print
1 through 6 is allowed.
panel, only the view identified by the VIEW attribute
on the LIST tag is printed when the Print Panel
The following tables show the available column
(QUIPRTP) API is called. To print more than one
width and what positions are used for each layout
view, the QUIPRTP API must be called multiple
column, depending on the value of the LAYOUT
times, updating the view dialog variable between
attribute. The first table applies to all panels with
each call to QUIPRTP.
WIDTH=80 specified on the PANEL or PRTPNL
tags. The second table applies to panels with
WIDTH=132 specified.

LISTVIEW Tag
Table A-12. Layout Values for Width=80. Layout column widths and positions for panels with WIDTH=80.
Layout Layout Layout 1 Layout 2 Layout 3 Layout 4 Layout 5 Layout 6
Width Column Column Column Column Column Column
Positions Positions Positions Positions Positions Positions
1 78 2-79
2 37 2-38 43-79
3 24 2-25 29-52 56-79
4 17 2-18 22-38 42-58 62-78
5 13 2-14 18-30 34-46 50-62 66-78
6 10 2-11 15-24 28-37 41-50 54-63 67-76
Table A-13. Layout Values for WIDTH=132. Layout column widths and positions for panels with WIDTH=132.
Layout Layout Layout 1 Layout 2 Layout 3 Layout 4 Layout 5 Layout 6
Width Column Column Column Column Column Column
Positions Positions Positions Positions Positions Positions
1 130 2-131
2 63 2-64 69-131
3 41 2-42 46-86 90-130
4 30 2-31 35-64 68-97 101-130
5 23 2-24 28-50 54-76 80-102 106-128
6 19 2-20 24-42 46-64 68-86 90-108 112-130
Table A-14. Layout Values for WIDTH=132. Layout column widths and positions for panels with WIDTH=132.
Layout Layout Width Layout 7 Layout 8 Layout 9 Layout 10
Column Column Column Column
Positions Positions Positions Positions
7 16 97-112
8 13 66-78 82-94
9 11 86-96 100-110 114-124
10 10 80-89 93-102 106-115 119-128
If a WIDTH of less than 80 or a width between 81 3. Divide the result of step 2 by the layout; do
and 131 is specified on the PANEL tag, the fol- not round up. This is the layout width.
lowing algorithm can be used to determine the
4. If the remainder from step 3 is greater than
layout width:
(layout-1), the separator between the layouts
1. Subtract 2 from the width of the panel. is 4. Otherwise, the separator space is 3.
2. Subtract 3*(layout-1) from the result of step 1.
This is the total separator space between the
layouts.

LP Tag
LP (List Part)
55──:LP.list-part-text──────────────────────────────────────────────────────────────────5%
The list part (LP) tag identifies a comment or an UIM Source

explanation applying to a part of a list. This tag is
:ol.
only allowed in information areas and help areas.
:li.First item
It can be placed anywhere within the list.
:lp.This is a list part.
:li.Second item
The text following the LP tag starts at the left :eol.
margin of the current level of the list. It is not
numbered or lettered. When used with the
ordered list (OL) tag, the LP tag does not interrupt Results
or increase the ordered sequence. 1. First item
This is a list part.
Example: List Part
2. Second item
This example uses a list part tag to keep the flow
of the list from being interrupted.

MBAR tag
MBAR (Menu Bar)
55──:MBAR──NAME=menu-bar-name──┬───────────────────────┬──┬────────────────┬──.──────────5
└─HELP=help-module-name─┘ │ ┌─1─┐ │
└─MAXBARL─┼─2─┼──┘
└─3─┘
5──:EMBAR.──────────────────────────────────────────────────────────────────────────────5%
The menu bar (MBAR) tag defines a menu bar Table A-15. Tag Allowed Between the MBAR and
area of a panel. The menu bar appears as the EMBAR Tags.
topmost element in a panel and consists of one or Tag Name Order Page
more menu bar choices. When the user positions
MBARC 1 A-110
the cursor at a menu bar choice and requests the (Menu bar choice)
ENTER dialog command, the pull-down menu for
the selected menu bar choice is displayed below
the text for the menu bar choice. Required Attribute
The resulting pull-down menu contains a selection NAME=menu-bar-name
field which has one or more pull-down choices. The name assigned to the menu bar. For
The user is allowed to choose only one pull-down more information on the rules for naming, see
menu choice. Each selection field has one or “Name Syntax” on page A-4.
more pull-down menu choices.
Optional Attributes
All menu bars must be defined after any condi-
tional statements and before the key lists. HELP=help-module-name
The name of the help information explaining
When a menu bar is specified for a panel with a the purpose of the menu bar. The help
list action column, a slash (/) or country- module name may be a name imported from
designated selection character may be entered on another panel group, but must follow the rules
the list action column to indicate the elements the for names outlined earlier in this chapter. For
menu bar choice is to act against. The slashes more information on the rules for names, see
are processed in the same top-to-bottom pro- “Name Syntax” on page A-4.
cessing as in normal list action processing. The
MAXBARL=1 | 2 | 3
slash (/) is not allowed on the extended action
The maximum number of lines that can be
entry of an action list.
used for the descriptions of the menu bar.
From 1 to 3 lines can be specified; 1 is the
Other tags can be nested within the MBAR tag.
default. Only as many menu bar lines as
These tags are listed in the following table. This
needed up to the maximum number allowed
by MAXBARL are used. If all the menu bar
appear and specifies on what page more informa-
choices do not fit in the number of lines speci-
tion can be found for each tag.
fied, a compiler error results.
Example: Menu Bar

This example defines the menu bar seen on the
Work with Programs panel.

MBAR tag
UIM Source .Keys help...

:pdfldc option=4
.\ Menu bar for Work with Programs panel help='mbarpgm/help/schidx'
:mbar name=mbarpgm action=helpidx
help='mbarpgm/' varupd=no
. .Help index...
.\ :pdfldc option=5
.\ Menu bar choice for the "File" pull-down help='mbarpgm/help/about'
:mbarc help='mbarpgm/file' action='call logopgm'
.File varupd=no
:pdfld. .About...
:pdfldc option=2 :epdfld.
help='mbarpgm/file/change' :embarc.
action='cmd ?CHGPGM PGM(&var2./&var1.)' :embar.
actfor=list
.Change
:pdfldc option=4 Results
help='mbarpgm/file/delete'
action='cmd DLTPGM PGM(&var2./&var1.)' à ð
File Help
actfor=list ------------------------------------------------------------------------------
Work with Programs
confirm=confpgm Select items in list, press F1ð to select action.
System: SYSTEMð1
usrexit='call exitpgm' Opt Program Library Text

.Delete PPPPPPPPP1
PPPPPPPPP2
LLLLLLLLLL
LLLLLLLLLL
Description
Description
text
text
PPPPPPPPP3 LLLLLLLLLL Description text
:pdfldc option=5 PPPPPPPPP4 LLLLLLLLLL Description text
help='mbarpgm/file/display'
action='cmd DSPPGM PGM(&var2./&var1.)' The File pull-down is displayed as shown below.
actfor=list
.Display
:pdfldc option=6 à File Help
ð
-.-------------------.--------------------------------------------------------
help='mbarpgm/file/exit' : 2. Change : Work with Programs
: : System: SYSTEMð1
action=exit : 4. Delete : ress F1ð to select action.
: 5. Display :
varupd=no : 6. Exit F3 : y Text
:...................: LLLL Description text
.Exit PPPPPPPPP2 LLLLLLLLLL Description text
:pdaccel.F3 PPPPPPPPP4 LLLLLLLLLL Description text
:epdfld.
:embarc. The Help pull-down is displayed as shown below.
.\
.\ Menu bar choice for the "Help" pull-down
:mbarc help='mbarpgm/help'
à File Help
ð
--------.------------------------.--------------------------------------------
: 1. Help for help... : with programs
.Help : 2. Extended help... : System: SYSTEMð1
Select : 3. Keys help... : select action.
:pdfld. : 4. Help index... :
Opt Pr : 5. About... :
:pdfldc option=1 PP :........................: ption text
help='mbarpgm/help/helphelp' PPPPPPPPP3 LLLLLLLLLL Description text
action=helphelp
varupd=no
.Help for help... When F10 (ACTIONS) is pressed, the cursor is
:pdfldc option=2 positioned in the space before the first menu bar
help='mbarpgm/help/help' choice.
action=exthelp
varupd=no When a menu bar choice is selected, the cursor is
.Extended help... located at the pull-down field and the tab key
:pdfldc option=3 moves to the first unselected menu bar choice.
help='mbarpgm/help/keyshelp' Repeated pressing of the tab key moves the
action=keyshelp cursor through the menu bar area and then back
varupd=no to the pull-down menu.

MBARC tag
MBARC (Menu Bar Choice)
55──:MBARC──HELP=help-module-name──.──menu-bar-choice-text──:EMBARC.────────────────────5%
The menu bar choice (MBARC) tag defines one for names outlined earlier in this chapter. For
choice within a menu bar. The end of the menu more information on the rules for names, see
bar choice must be indicated with an EMBARC “Name Syntax” on page A-4.
tag.
Other tags can be nested within the MBARC tag.

Required Text
These tags are listed in the following table. This menu-bar-choice-text
table defines the order in which the tags must The displayable description for the menu bar
appear and specifies on what page more informa- choice. The text must appear on the same
tion can be found for each tag. line or the next line as the tag, the text can
contain only the reverse text (RT) tag, and the
Table A-16. Tags Allowed Between the MBARC and text must be no longer than 32 bytes.
EMBARC Tags.
The menu bar is formed by concatenating the
Tag Name Order Page
text from the various menu bar choices. If the
PDFLD 1 A-133 text does not fit on the rest of a line, it is
(Pull-down field) placed on the next line. The menu bar is
PDFLDC 2 A-134 limited to the number of lines specified on the
(Pull-down field choice) MAXBARL attribute on the MBAR tag.
The text is displayed with a tabable space in
Required Attributes front of it. When the tab keys are used to
position the cursor at one of the menu bar
HELP=help-module-name choices, the cursor appears one character to
The name of the help information explaining the left of the text. Two spaces are placed
the purpose of the menu bar choice. The help between each text field for the menu bar. The
module name may be a name imported from visual result has three spaces between
another panel group, but must follow the rules choices.

MENU Tag
MENU (Menu Area)
55──:MENU──DEPTH=─┬─area-depth─┬───┬────────────────────┬──┬──────────────────┬──.───────5
└─'\'────────┘ │ ┌─SPACE─┐ │ │ ┌─NO──┐ │
└─BOTSEP=─┼─NONE──┼──┘ └─SCROLL=─┴─YES─┴──┘
└─RULE──┘
5──┬────────────┬──:EMENU.──────────────────────────────────────────────────────────────5%
└─area-title─┘
The menu area (MENU) tag defines a menu area. Table A-17. Tags Allowed Between the MENU and
This tag is allowed only for display panels. The EMENU Tags
end of the menu area must have a EMENU tag. Tag Name Order Use Page
MENUGRP 3 D A-114
The menu area is included in the panel with all the
(Menu column
other areas that are defined on the panel. Only group)
one menu area may be present on any panel.
MENUI 3 D A-115
Either the command line (CMDLINE) tag or the (Menu item)
option line (OPTLINE) tag must be specified for a BOTINST 4 D A-10
menu panel. The user selects a menu option by (Bottom instruc-
entering the option number on the command line tion line)
or option line.
Other tags can be nested within the MENU tag.

Required Attribute
These tags are listed in the following table. The DEPTH=area-depth | '*'
table defines the order in which the tags must The depth of the area in lines, including sepa-
appear, indicates which tags can be used in rators if any are specified.
(specified by a D, P, or B, respectively), and spec- If '*' is specified, the space remaining on the
ifies on which page more information can be found display after everything else is allocated is
for each tag. given to this area. Only one area in the panel
may have '*' coded.
order number, all tags of that number can be Optional Attribute
order number cannot precede a tag with a lower BOTSEP=SPACE | NONE | RULE
order number. For example, a tag with an order Defines the bottom separator for the menu
number of three cannot precede a tag with an area. If SPACE is specified, a line of spaces
order number of one or two. is used.
NONE indicates that no separator line exists.
Table A-17. Tags Allowed Between the MENU and
EMENU Tags If RULE is specified, a line of underscored
spaces is used as a separator line.
TOPINST 1 D A-161 SCROLL=NO | YES
(Top instruction NO indicates that the menu is not scrollable.
line)
YES indicates that the menu area is intended
APPFMT 2 D A-8 to be scrollable. Ordinarily YES should not be
(Application for- used, but longer, scrollable menus can be
matted area)
constructed with SCROLL=YES. For a
SCROLL=YES area, a line of spaces is used by
the UIM to provide a line for the scroll infor-
mation. If BOTSEP=SPACE is also specified on

MENU Tag
this tag, only one line of spaces is used

unless this area also contains bottom
à MAIN My Main Menu
ð
instructions.
1. Display menu X
2. System operations
9ð. Sign off

Optional Text
area-title
The title of the area. If no text is specified, no
title line is allocated to the area. The text
must appear on the same or next line as the Selection or command
===> __________________________________________________________________________
_______________________________________________________________________________
tag, the text can contain only the reverse text F3=Exit F4=Prompt F9=Retrieve F12=Cancel
(RT) tag, and cannot exceed a maximum

á ñ
length of 55 characters.
Example 1: Simple Menu Area Example 2: Menu Area with

Groups
This example defines a menu area with three
options. This example has three menu areas, each of
which has options that can be chosen.
UIM Source
UIM Source
:panel name=main
help='menu/main' :panel name=cfg2
keyl=small help='menu/cfg2'
panelid=zmenu panelid=zmenu
topsep=space keyl=small
.My Main Menu .Configuration Templates
:menu depth='\'. :menu depth='\'.
:topinst.Select one of the following: :topinst.Select one of the following:
:menui help=MNUSER :menugrp.Local Hardware:
option=1 :menui help='opt/lcl/wsprt'
action='MENU X' option=1
.Display menu X action='MENU LCLWSPRT'
:menui help=MNSYS .Work stations and printers
option=2 :menui help='opt/lcl/ctl'
action='MENU SYSOPR' option=2
.System operations action='MENU LCLCTL '
:menui help=MNOFF .Controllers
option=9ð :menui help='opt/lcl/tapdkt'
action='CMD SIGNOFF' option=3
.Sign off action='MENU LCLTAPDKT'
:emenu. .Tape drives and diskette drives
:cmdline size=long.Selection or command :emenugrp.
:epanel. :menugrp.Remote Hardware:
:menui help='opt/rmt/wsprt'
option=4
Results action='MENU RMTWSPRT'
.Work stations and printers
:menui help='opt/rmt/ctl'
option=5
action='MENU RMTCTL '
.Controllers
:menui help='opt/rmt/tapdkt'
option=6
action='MENU RMTTAPDKT'

MENU Tag
.Tape drives and diskette drives Results

:emenugrp.
:menugrp.Communications Support:
:menui help='opt/cmn/lines' à CFG2 Configuration Templates
ð
System: xxxxxxxx
option=7 Select one of the following:
action='MENU CMNLINES' Local

1.
Hardware:
Work stations and printers
2. Controllers
.Communications lines 3. Tape drives and diskette drives
:menui help='opt/cmn/ctl' Remote Hardware:
4. Work stations and printers
option=8 5. Controllers
6. Tape drives and diskette drives
action='MENU CMNCTL ' Communications Support:
.Communications controllers 7. Communications lines
8. Communications controllers
:emenugrp.
:emenu. ===> ___________________________________________________________________________
________________________________________________________________________________
:cmdline size=long.Selection or command F3=Exit F4=Prompt F9=Retrieve F12=Cancel
:epanel. á ñ

MENUGRP Tag
MENUGRP (Menu Group)
55──:MENUGRP──┬─────────────────────┬──.──┬───────────────┬──:EMENUGRP.─────────────────5%
└─COND=condition-name─┘ └─group=heading─┘
The menu group (MENUGRP) tag groups menu number of three cannot precede a tag with an
items of a menu area together and supplies a order number of one or two.
heading for the group. This tag is allowed only for
display panels. Table A-18. Tag Allowed Between the MENUGRP
and EMENUGRP Tags
If the number of lines required to display the first Tag Name Order Use Page
two items of the menu group exceeds the number
MENUI 1 D A-115
of lines remaining in the current page, the entire (Menu item)
group is forced to the next page. When all items
in the menu group are not completely displayed
on one page, the group is continued onto as many Optional Attribute
pages as required to display all items.
COND=condition-name
Other tags can be nested within the MENUGRP The group is displayed and active on the
tag. These tags are listed in the following table. panel only if the condition specified is true. If
The table defines the order in which the tags must the condition is false, the entire group is not
appear, indicates which tags can be used in shown. The condition must be defined in the
display panels only, print panels only, or both panel group prolog with the condition definition
(specified by a D, P, or B, respectively), and spec- (COND) tag.
for each tag. Optional Text
When more than one tag is listed with the same group-heading
order number, all tags of that number can be The heading placed above the menu items of
mixed in any order. However, a tag with a higher the group. The text must appear on the same
order number cannot precede a tag with a lower or next line as the tag and can only contain
order number. For example, a tag with an order the reverse text (RT) tag. The group heading
always appears on one display line beginning
in column four.

MENUI or MI Tag
MENUI or MI (Menu Item)
55──:MENUI or MI──HELP=help-module-name──OPTION=option-number──ACTION='action-text'──────5
5──┬─────────────────────┬──┬─────────────────────┬──┬──────────────────────┬────────────5
└─NAME=menu-item-name─┘ └─COND=condition-name─┘ └─AVAIL=condition-name─┘
5──┬─────────────────────────────┬──┬─────────────────────────────────────┬──────────────5
└─AVLMSGID=message-identifier─┘ └─AVLMSGF=qualified-message-file-name─┘
5──┬───────────────────────┬──┬───────────────────────────┬──.───────────────────────────5
└─MARKER=condition-name─┘ └─ITEM=dialog-variable-name─┘
5──┬────────────────────────────┬───────────────────────────────────────────────────────5%
└─menu-item-description-text─┘
Required Attributes 'MENU qualified-menu-name

RTNPNT|NORTNPNT'
HELP=help-module-name 'RETURN positive-integer'
Identifies online information explaining the
purpose of the menu item. The help module For a description of each of these actions, see
name may be a name imported from another Appendix B, “UIM Dialog Commands” on
panel group, but must follow the rules for page B-1.
names outlined earlier in this chapter. For
more information on the rules for names, see Optional Attributes
NAME=menu-item-name
The online information identified by this attri- The name associated with the menu item.
bute is displayed when help is requested while This name can be used with the Add Pop-Up
the cursor is positioned on the text for this tag Window (QUIADDPW) API to position a
or while the cursor is on the command or window near this menu item. For more infor-
option line and a valid menu item number has mation on the rules for naming, see “Name
been entered. Syntax” on page A-4.
OPTION=option-number COND=condition-name
The number to assign this option. Option The menu item is in effect on the panel only if
numbers are integers in the range 0 through the condition specified is true. The condition
999. must be defined in the panel group prolog with
The menu items are displayed in the order the condition definition (COND) tag.
defined for the menu area. If the numbering
AVAIL=condition-name
of two items is not consecutive, a blank line is
The name of a condition indicating to the UIM
automatically placed between the two items.
whether or not the menu item is available for
ACTION='action-text' selection by the user. The condition must be
The action occurring when the menu item is defined in the panel group prolog with the
selected by the user. The valid forms of COND tag.
action-text are: Unavailable menu items are displayed with an
'CALL program-reference' asterisk (*) overlaying the first part of the
'CANCEL' menu item number.
'CMD command-string' When the condition is true, the menu item is
Any dialog variable name in the command available. When the condition is false, the
string must be preceded by an ampersand menu item is not available. Any condition
and should be ended with a period to specified on the COND attribute of this tag takes
denote variable substitution. precedence over this attribute.
'EXIT'

MENUI or MI Tag
AVLMSGID=message-identifier ITEM=dialog-variable-name
The message identifier of the message dis- The name of a dialog variable containing the
played when the pull-down choice is selected text for the menu item description when the
but is not available as specified by the AVAIL panel is displayed. The dialog variable may
attribute of this tag. This attribute is allowed be defined with a BASETYPE of CHAR, IGC, or
only when the AVAIL attribute is specified. BIN on the class definition (CLASS) tag. The
declared length of the dialog variable must be
If this attribute is not specified, the UIM dis-
no longer than what fits on one line of the
plays a default message stating that the
panel, starting in column 10. Allowance must
choice is currently not available.
be made if there is an application formatted
AVLMSGF='qualified-message-file-name' area.
The message file name containing the
If this attribute is used, no menu-item-
message identifier. This attribute is allowed
description-text can be specified after the
only when the AVLMSGID attribute is specified
period for this tag.
on this tag. If the DFTMSGF attribute is not
specified on the panel group (PNLGRP) tag,
and if the AVLMSGID attribute is specified on Optional Text
this tag, then this attribute must be specified. menu-item-description-text
MARKER=condition-name The descriptive text accompanying the option
The name of a condition indicating whether or and shown on the menu. The text may
not the menu item is marked with a greater appear on more than one line in the source.
than sign (>). The marker is displayed only if The text can contain only the reverse text
the condition specified is true. The condition (RT) tag, and cannot exceed 70 characters in
must be defined in the panel group prolog with length.
the COND tag. The item description text begins in column 10
When the condition is true, a greater than sign of the panel. The option number, a period,
is displayed to the left of the option number of and one blank appear immediately before the
the menu item. When the condition is false, item description text. The item number begins
the line is blank before the option number of in column 7, 6, or 5, depending on whether
the menu item. If this attribute is omitted, no the option number has 1, 2, or 3 digits. The
marker appears on the menu item. text is formatted onto additional lines as nec-
essary, and the additional lines are not
indented two spaces to fit on the panel.

NT or NOTE Tag
NT or NOTE (Note)
55──:NT. or :NOTE.──┬───────────┬──:ENT. or :ENOTE.─────────────────────────────────────5%

└─note-text─┘
The note (NT) tag identifies a single- or multiple- Table A-19. Tags Allowed Between the NOTE and
paragraph note. This tag must have a matching ENOTE Tags
end tag. You can also use :NOTE and :ENOTE in Tag Name Order Use Page
place of the :NT and :ENT tags. These tags are
P 1 B A-121
only allowed in information areas and help areas. (Paragraph)
Notes cannot be nested.
PC 1 B A-131
Notes can occur anywhere in text that a para- (Paragraph con-
tinuation)
graph is allowed. They can contain any basic text
items, but cannot contain headings, figures, lines,
examples, or any type of list. If this tag has not Optional Text
been ended when a heading tag is encountered,
the note ends and a warning message is issued note-text
by the compiler. Although the text of the note is not required,
the tag has no meaning when text is not spec-
The note is an implied paragraph. It is formatted ified.
as a block and indented 6 spaces from the current
margin. The word Note, formatted in highlight Example: Using a Note
phrase 2 (HP2) and followed by a colon, begins
the paragraph. There are two spaces between The note tag makes important information stand
the note tag and the text if either the note tag or out in a paragraph, as in this example.
the text are single-byte characters. There are four
spaces between the note tag and the text if both
UIM Source
are double-byte characters.
:P.Here's a paragraph.
A note is aligned with the text of a list item when :NT.
used within a list. Here's the first paragraph
of the note.
Other tags can be nested within the NOTE tag. :P.
These tags are listed in the following table. The Here's the second paragraph
of the note.
:ENT.
appear, indicates which tags can be used in
:P.Here's a paragraph.
ifies on which page more information can be found Results
for each tag.
Here's a paragraph.
Note: Here's the first paragraph of the
note.
Here's the second paragraph of the note.
number of three cannot precede a tag with an Here's a paragraph.

OL, LI Tags
OL (Ordered List)
┌──
───────────────┐
55──:OL ─┬─────────┬─.───6─:LI.item-text─┴──:EOL.────────────────────────────────────────5%
└─COMPACT─┘
The ordered list (OL) tag identifies an ordered list ifies on which page more information can be found
of items. It requires a matching end tag. These for each tag.
tags are only allowed in information areas and
help areas. When more than one tag is listed with the same
Ordered lists can occur anywhere in text and can mixed in any order. However, a tag with a higher
be nested within other lists. order number cannot precede a tag with a lower
Note: Care should be taken when using unfor-
matted lines (LINES), figure (FIG), and example
(XMP) tags within ordered lists, because text that
does not fit on one line wraps to column one of Table A-20. Tags Allowed Between the OL and EOL
the next line. Lines and figures start at the current Tags
left margin, and examples are indented four
spaces from the current left margin. The current
left margin changes when nested lists are for- FIG 1 B A-59
matted. If online help information has the LINES, (Figure)
FIG, or XMP tag imbedded at various locations, LINES 1 B A-77
including within lists, it may not look the same (Unformatted
each time. lines)
XMP 1 B A-171
The OL tag is formatted as a hanging, indented (Example)
list, with the item identifier (1,2,...a,b,...) at position
NT 1 B A-117
four relative to the left margin. The text begins at
(Note)
position eight relative to the left margin.
P 1 B A-121
Ordered lists are identified in a formatted docu- (Paragraph)
ment by sequential numbers or letters, depending PC 1 B A-131
on the definition for each level. The levels of defi- (Paragraph con-
nition are as follows: tinuation)
1. 1., 2., 3., . . .,11., 12., . . ., 99. LP 1 B A-107

(List part)
2. a., b., c., . . ., z., aa., bb., . . ., zz.
3. 1), 2), 3), . . .,11), 12), . . ., 99) OL 1 B A-118
4. a), b), c), . . ., z), aa), bb), . . ., zz) (Ordered list)
SL 1 B A-152
Any additional levels repeat the sequence from (Simple list)
the beginning.
UL 1 B A-164
(Unordered list)
Other tags can be nested within the OL tag.
These tags are listed in the following table. The PARML 1 B A-129
table defines the order in which the tags must (Parameter list)
appear, indicates which tags can be used in DL 1 B A-57
display panels only, print panels only, or both (Definition list)

OL, LI Tags
Optional Attribute Some normal text...

:ol.
COMPACT :li.First item (number)
This attribute formats the list without a blank :ol compact.
line between items. :li.First item (letter)
:li.Second item (letter)
:eol.
Required Tag :li.Second item (number)
:eol.
:LI.item-text
The text for the list item. The text is preceded
by a number or a letter and a period. Results
Example: Ordered List Some normal text...

1. First item (number)
This example has two ordered lists, one imbedded
within the other. The second ordered list uses the a. First item (letter)
COMPACT attribute. b. Second item (letter)
2. Second item (number)
UIM Source

OPTLINE Tag
OPTLINE (Option Line)
55──:OPTLINE──┬───────────────────────┬──.──┬──────────────────┬────────────────────────5%
└─NAME=option-line-name─┘ └─instruction-text─┘
The option line (OPTLINE) tag specifies that a Window (QUIADDPW) API to position a
panel has a menu option field as opposed to a window near the option line. For more infor-
command line which allows commands or options mation on the rules for naming, see “Name
to be entered. This tag is allowed only for display Syntax” on page A-4.
panels. The OPTLINE tag can be used only on a
panel that has a menu area. Optional Text
Any text associated with this tag is used as an instruction-text
instruction line, appearing immediately above the The text appearing as instructions for the
option field on the panel. option line. This text is an implied paragraph.
When the display is formatted, any text that
This tag must be the final tag in a panel, placed
does not fit onto one display line is formatted
just before the EPANEL tag. The command line
on the following blank lines and indented two
(CMDLINE) tag and the OPTLINE tag are mutually
columns. The text can be a maximum of 255
exclusive.
characters and can contain only the reverse
text (RT) tag. If no text is provided, no
Optional Attribute instruction line is allocated or displayed above
NAME=option-line-name the option line.
The name associated with the option line.
This name can be used with the Add Pop-Up

P Tag
P (Paragraph)
55──:P.paragraph-text───────────────────────────────────────────────────────────────────5%
The paragraph (P) tag identifies a paragraph, Example: Paragraph Tag

which is one or more sentences related by their
subject matter. This tag is only allowed in infor- This example illustrates how the paragraph tag is
mation areas and help areas. used.
Paragraphs can occur anywhere in text and can

UIM Source
contain text items. A matching end tag is not
allowed; a paragraph is ended by another para- :P.Here's a paragraph.
graph or by a higher-level element. Lines are formatted to
fill the column.
Each paragraph is formatted as a block of text :P.Here's another
without indenting the first line. One blank line paragraph.
separates paragraphs from other text items.
Results
Paragraphs inserted within a list align with the text
of the list item. Here's a paragraph. Lines are formatted to
fill the column.
Optional Text
Here's another paragraph.
Although the paragraph text is not required, the
tag has no meaning when text is not specified.

PANEL Tag
PANEL (Display Panel)
55──:PANEL──NAME=panel-name──HELP=help-module-name──KEYL=key-list-name───────────────────5
5──┬──────────────────────────────┬──┬────────────────────────────┬──────────────────────5
└─PANELID=dialog-variable-name─┘ └─TITLE=dialog-variable-name─┘
5──┬─────────────────────────┬──┬─────────────────────────┬──┬────────────────────┬──────5
│ ┌─8ð──────────┐ │ │ ┌─FIT─────────┐ │ └─MBAR=menu-bar-name─┘
└─WIDTH=─┴─panel-width─┴──┘ └─DEPTH=─┴─panel-depth─┴──┘
5──┬──────────────┬──┬───────────────────────┬──┬───────────────────────────┬────────────5
│ ┌─1─┐ │ │ ┌─SYSNAM───┐ │ └─DATE=dialog-variable-name─┘
└─MSGL=─┼─2─┼──┘ └─TOPSEP=─┼─SPACE────┼──┘
├─3─┤ ├─RULE─────┤
└─4─┘ ├─DATETIME─┤
└─NONE─────┘
5──┬───────────────────────────┬──┬─────────────────────┬──┬─────────────────────┬───────5
└─TIME=dialog-variable-name─┘ │ ┌─PNLGRP─┐ │ └─ENTER='action-text'─┘
└─ENBGUI=─┼─NO─────┼──┘
└─YES────┘
5──┬──────────────────────┬──┬──────────────────────────────────┬────────────────────────5
└─SELECT='action-text'─┘ └─USREXIT='CALL program-reference'─┘
5──┬─────────────────────┬──┬─────────────────────────────┬──────────────────────────────5
└─TT=truth-table-name─┘ └─CSRVAR=dialog-variable-name─┘
5──┬─────────────────────────────┬──┬─────────────────────────────┬──────────────────────5
└─CSRPOS=dialog-variable-name─┘ └─CSRLST=dialog-variable-name─┘
5──┬─────────────────────────────┬──┬──────────────────────────────┬──.──────────────────5
└─CSREID=dialog-variable-name─┘ └─CSRNAME=dialog-variable-name─┘
5──┬──────────────────┬──:EPANEL.───────────────────────────────────────────────────────5%
└─panel-title-text─┘
The display panel (PANEL) tag is opened using Table A-21. Tags Allowed Between the PANEL and
the PANEL tag and closed using the EPANEL tag. EPANEL Tag
It contains tags to define one or more panel area Tag Name Order Use Page
definitions.
DATA 1 D A-31
(Data presenta-
Other tags can be nested within the PANEL tag. tion area)
These tags are listed in the following table. The
table defines the order in which the tags must INFO 1 D A-68
(Information area)
display panels only, print panels only, or both LIST 1 D A-82
(specified by a D, P, or B, respectively), and spec- (List area)
ifies on which page more information can be found MENU 1 D A-111
for each tag. (Menu area)
TEXT 1 D A-154
When more than one tag is listed with the same (Text area)
CMDLINE 2 D A-26
(Command line)
order number. For example, a tag with an order OPTLINE 2 D A-120
number of three cannot precede a tag with an (Option line)
Required Attributes

PANEL Tag
NAME=panel-name with WIDTH=80 results in 78 bytes of space for

The name of the panel. For more information panel data.
on the rules for naming, see “Name Syntax”
The maximum width supported for a panel dis-
on page A-4.
played as a full screen is 132 bytes. The
HELP=help-module-name maximum width supported for a pop-up
The name of a help module containing the window depends on what size screen the
beginning of the extended help for the panel. device supports. On a device that supports
24 rows by 80 bytes, 74 bytes is the
KEYL=key-list-name maximum width of a pop-up window. On a
The name of a key list for the panel. device that supports 27 rows by 132 bytes,
126 bytes is the maximum width of a pop-up
Optional Attributes window. The minimum width for a pop-up
window is 20 bytes.
PANELID=dialog-variable-name
The name of a dialog variable containing the DEPTH=FIT | panel-depth
text for the panel identifier when the panel is The depth of the panel. If the depth is not
displayed. The dialog variable must be specified, the panel depth defaults to FIT. If
defined on a class definition (CLASS) tag with DEPTH=FIT, the UIM uses the depth of the
BASETYPE='CHAR 10', 'NAME 10', or device at display time to determine the depth
'OBJNAME 10'. The UIM displays the con- of the panel. When DEPTH=FIT, the compiler
tents of the variable in the upper left corner of verifies that all panel elements fit within 24
the panel. If this attribute is omitted, no panel lines.
identifier appears on the display. The specified depth includes:
To specify a panel identifier for a menu
One line for a panel title
created by using the Create Menu (CRTMNU)
One line of area data
command, the dialog variable for ZMENU
One or two lines for function key
should be declared with PANELID=ZMENU on
descriptions
the PANEL tag. The value of the ZMENU
One line for the message line
dialog variable is displayed as the panel iden-
tifier. The maximum supported depth is 27 lines for
a panel displayed in a full display. The
TITLE=dialog-variable-name
maximum supported depth for a pop-up panel
depends on what the display device can
text for the panel title. The dialog variable
support. On a device that can only support 24
must be defined with a display width of 55 or
rows by 80 bytes, the maximum depth of a
the width of the panel minus 2, whichever is
pop-up window is 21 lines. On a device that
less. A translation list may be used to provide
can support 27 rows by 132 bytes, the
the panel title.
maximum depth of a pop-up window is 24
The UIM trims trailing blanks from the string lines.
and centers the resulting text in the panel title
The minimum allowed depth is 5 lines.
area of the display. If this attribute is used, no
panel-title-text can be specified. MBAR=menu-bar-name
For a pop-up panel, the declared length of the The name of the menu bar used on the panel.
dialog variable must be equal to the width of This attribute is not allowed on confirmation
the pop-up panel minus 2 bytes, and less if panels or panels that will be used as pop-up
PANELID or TOPSEP=DATETIME is specified on windows.
this tag for the panel. Menu bars are only allowed on panels defined
with one of the following sizes:
WIDTH=80 | panel-width
The width of the panel. If the width is not WIDTH=80 or 132 bytes, and DEPTH=FIT
specified, the panel width defaults to 80 bytes. WIDTH=80 bytes, DEPTH=24 lines
The specified width must contain 2 bytes of WIDTH=132 bytes, DEPTH=27 lines
space for the left and right margins. A panel

PANEL Tag
MSGL=1 | 2 | 3 | 4 When ENBGUI=YES is specified, the UIM

The number of message lines that should includes information about the layout and
appear on this panel. One message line is content of the panel in the 5250 data stream.
the default. This information is used by client programs to
create the graphical interface on the client.
TOPSEP=SYSNAM | SPACE | RULE
Table A-22 describes the information that is
| DATETIME | NONE
included in the 5250 data stream:
Defines the top separator for the panel. If
SYSNAM is specified, the separator line con- Table A-22. Layout of UIM finger print
tains only the system name.
Byte Value and Description
If SPACE is specified, a line of spaces is 0 Hex 27 - Non-display attribute
used.
1 Hex 40 - Blank
If RULE is specified, a line of underscored
2 Hex 20 - Terminating attribute
spaces is used. RULE cannot be specified if
the MBAR attribute is specified on this tag. 3 Reserved
If DATETIME is specified, the separator line 4 Hex 00 - Panel BIDI=NONE or LTR

contains the date and time from the dialog Hex 40 - Panel BIDI=RTL
variables identified on the DATE and TIME attri- 5 Hex 00 - Panel does not contain a list area
butes of this tag. DATETIME also causes the Hex 40 - Panel might contain a list area
system name to be on the right side of the 6 Hex 00 - Panel does not contain a menu
title line. When date and time is used as the area
top separator for the panel, it should not be Hex 40 - Panel might contain a menu area
used to provide a current time clock. This 7 Hex 00 - Panel does not contain a help
function should be used to show the date and area
time in which the important data on the panel Hex 40 - Panel might contain a help area
is collected or generated.
This includes the UIM Help (UH) panels as
NONE indicates that no separator line exists. well as application panels containing a
:TEXT area (for example, InfoSeeker).
Values other than TOPSEP=SPACE or NONE
8 Hex 00 - Panel does not contain any other
may cause undesirable results when the panel
areas
width is less than 80.
Hex 40 - Panel might contain one or more
DATE=dialog-variable-name other areas
The name of a dialog variable containing a Other types of areas are :DATA (input
date displayed on the top separator for the and/or output), :INFO (similar to help).
panel. This attribute is required when 9 Hex 27 - Non-display attribute
TOPSEP=DATETIME is specified on this tag.
10 Hex 40 - Blank
The dialog variable must be defined with
BASETYPE='DATE' on the CLASS tag. 11 Hex 20 - Terminating attribute
TIME=dialog-variable-name
When ENBGUI=NO is specified, the UIM does
The name of a dialog variable containing a
not include the extra information in the data
time displayed on the top separator for the
stream.
panel. This attribute is required when
TOPSEP=DATETIME is specified. The dialog ENTER='action-text'
variable must be defined with The default enter action for the panel, occur-
BASETYPE='TIME' on the CLASS tag. ring when the Enter key is pressed and no
UIM-defined action, such as menu or action
ENBGUI=PNLGRP | NO | YES
list processing, is necessary. If this attribute
Specifies whether the panel is enabled for
is omitted, the panel is redisplayed to the user
conversion to a graphical user interface (GUI)
with no message or error indication. The valid
by a client program.
forms of action text are:

PANEL Tag
For a description of the interface between the user presses an inactive function key. If
the UIM and the program for a function the user presses a function key defined with
key CALL, see the System API Reference. VARUPD=NO on the KEYI tag, the values
'CMD command-string' entered on the panel by the user are not avail-
Any dialog variable name in the command able to this program. They are only stored
string must be preceded by an ampersand internally in the UIM.
to denote variable substitution.
For a description of the CALL dialog
'MSG message-identifier [ qualified-
message-file-name ]'
'RETURN positive-integer'
For a description of the interface between the
For a description of each of these dialog com- UIM and the general exit program, see the
mands, see Appendix B, “UIM Dialog System API Reference.
TT=truth-table-name
SELECT='action-text' The name of a truth table defined by the truth
The default selection action for the panel, table (TT) tag, specifying what combinations
occurring when items are selected in a of truth values may occur for conditions
selection list or an action list and no action is defined by condition definition (COND) tags
selected from the menu bar. If this attribute is while the application is running.
not specified, the panel is displayed to the
user with no message or error indication. The The table specified may contain any subset or
valid forms of action text are: superset of the conditions referred to by tags
in the panel definition. Only the truth value
'ACTIONS' combinations specified in the table, aug-
'MSG message-identifier [ qualified- mented by worst-case assumptions for any
message-file-name ]' truth values not specified in the table, are con-
'PULLDOWN' sidered in evaluating whether or not the panel
'RETURN positive-integer' definition is usable. The table should not
exclude any truth value combination that could
The PULLDOWN and ACTIONS dialog com-
occur when the panel is displayed. If a valid
mands cannot be specified if the MBAR attribute
truth value combination is omitted, a panel
is not specified on this tag.
group object may create without error and
USREXIT='CALL program-reference' have undesirable results when panels are dis-
A general exit program called each time the played. For example, the UIM may fail to
user presses a function key or the Enter key show panel elements that are conditioned-on
after dialog variables and list entries are for display. For more information about truth
updated and before any action specified on tables, see “TT (Truth Table)” on page A-162.
the key list item (KEYI), list action (LISTACT),
If this attribute is omitted, all combinations of
pull-down field choice (PDFLDC), or menu
truth values are considered possible. This
item (MENUI) tag is performed.
causes the tag language compiler to make
The program is passed parameters that worst-case assumptions for all conditions in
include what function is requested by the user. evaluating whether or not the panel definition
The exit program may do application-defined is valid.
validity checks, change the display position
CSRVAR=dialog-variable-name
attribute of lists that appear on the screen, or
both. If the exit program sends a CPF6A02
variable which is used by the UIM to contain
status message to the UIM, the UIM redis-
either the name of the dialog variable or the
plays the panel without performing the normal
name of the command line where the cursor is
action processing.
or will be positioned.
The panel is redisplayed without calling this
The UIM updates this variable after the panel
exit program if validity check errors associated
is displayed and before the general exit
with the CLASS, validity checking (CHECK),
program or any action routines are called. It
or translation list (TL) tags are detected, or if

PANEL Tag
contains the name of the dialog variable asso- identifies a position that is not valid for the
ciated with the field, or the name of the display field, the UIM default cursor posi-
command line (if named) where the cursor is tioning is used and no error is reported.
positioned on exit from the panel. If the
CSRLST=dialog-variable-name
cursor is not in a field or on a named
command line, the CSRVAR dialog variable is
variable used by the UIM to contain the name
set to blanks.
of the list where the cursor is or will be posi-
The Display Panel (QUIDSPP) API supports tioned.
an option that allows the application program
to control the initial cursor position by setting
is displayed, before the panel exit program or
the dialog variables associated with the
any action routines are called. It contains the
CSRVAR, CSRPOS, CSRLST, and CSREID panel
name of the list associated with the list area
attributes before the panel is displayed. If the
where the cursor is positioned on exit from the
CSRVAR dialog variable does not contain the
panel. If the cursor is not in a list area, the
name of a dialog variable or command line
dialog variable is set to blanks.
displayed on the panel, the UIM default cursor
positioning is used and no error is reported. The QUIDSPP API supports an option that
allows the using program to control initial
If a data item is defined using data item
cursor position by setting the dialog variables
extenders, the CSRVAR attribute contains the
associated with the CSRVAR, CSRPOS, CSRLST,
name of the extender dialog variable if the
and CSREID attributes of this tag before the
cursor is positioned within the extender field.
panel is displayed. If the CSRLST attribute is
If the cursor is positioned between fields,
not blank and does not contain the name of a
CSRVAR is set to the name of the dialog vari-
list displayed on the panel, the UIM default
able specified on the VAR attribute of the data
cursor positioning is used and no error is
presentation area (DATA) tag, and the
reported.
CSRPOS dialog variable is set to zero.
CSREID=dialog-variable-name
CSRPOS=dialog-variable-name
This attribute must name a BIN 15 dialog vari-
variable used by the UIM to contain the list
able used by the UIM to contain the character
entry handle within the list identified by the
position within the field identified by the
CSRLST attribute where the cursor is or will be
CSRVAR attribute on this tag where the cursor is
positioned.
or will be positioned.
list entry identifier where the cursor was posi-
position within a field where the cursor is posi-
tioned on exit from the panel. If the cursor
tioned on exit from the panel. If the cursor is
was not in any list entry, the CSREID dialog
not in a field, the dialog variable is set to zero.
variable is set to X'00'. If the cursor was
If the cursor is positioned in a text area asso-
positioned in a text area associated with a list
ciated with the field, such as a prompt label or
column, such as a column heading, the
column heading for a list area, the CSRVAR
CSRLST attribute contains the name of the cor-
attribute contains the name of the dialog vari-
responding list and the CSREID dialog vari-
able for the corresponding data item or list
able is set to X'00'.
column, and the CSRPOS dialog variable is
set to zero. The QUIDSPP API supports an option that
allows the using program to control the initial
The QUIDSPP API supports an option which
allows the using program to control the initial
and CSREID attributes of this tag before the
panel is displayed. If the CSREID attribute
and CSREID attributes on this tag before the
identifies an unusable position that does not
panel is displayed. If the CSRPOS attribute
specify a list entry displayed on the panel, the

PANEL Tag
UIM default cursor positioning is used and no than 55 bytes long and is required unless the
error is reported. TITLE attribute is specified on this tag.
CSRNAME=dialog-variable-name
This attribute must name a CHAR 10 dialog Example: Panel Definition
variable used by the UIM to contain the name
of the item where the cursor is positioned. This example defines a panel and sets up the ele-
ments used within the panel.
UIM Source
name of the item where the cursor is posi- :panel name=main
tioned on exit from the panel. If the cursor help=hmain
was not on any item, the CSRNAME dialog panelid=zmenu
keyl=small
variable is set to blanks.
.My Main Menu
The value of this variable may be used to :menu depth='\'.
position pop-up windows adjacent to a field :topinst.Select one of the following:
using the Add Pop-Up Window (QUIADDPW) :menui help=MNUSER option=1
API. action='CMD MENU X'
.Display menu X
:menui help=MNSYS
Optional Text option=2
action='CMD MENU SYSOPR'
panel-title-text
.System operations
The title used on this panel. The text must
:menui help=MNOFF
appear on the same or next line as the tag. option=9ð
The text cannot contain other tags, and is action='CMD SIGNOFF'
limited in length based on the width of the .Sign off
panel. The panel-title-text may be no more :emenu.
:cmdline size=long.Selection or command
:epanel.

PANEL Tag
Results à ð
MAIN My Main Menu
System: SYSTEMð1
1. Display menu X
2. System operations
9ð. Sign off
===> __________________________________________________________________________
_______________________________________________________________________________
á ñ

PARML, PT, PD Tags
PARML (Parameter List)
┌──
─────────────────────────────────────┐
55──:PARML.───6─:PT.parameter-term──:PD.description─┴──:EPARML.──────────────────────────5%
The parameter list (PARML) tag identifies param- Table A-23. Tags Allowed Between the PARML and
eter terms and descriptions. These tags are only EPARML Tags
allowed in information areas and help areas. This Tag Name Order Use Page
tag requires a matching end tag. The terms
FIG 1 B A-59
defined and their definitions are identified by the (Figure)
parameter term (PT) tag and the parameter defi-
nition (PD) tag, respectively. LINES 1 B A-77
(Unformatted
Note: Care should be taken when using unfor- lines)
matted lines (LINES), figure (FIG), and example XMP 1 B A-171
(XMP) tags within parameter lists because text (Example)
that does not fit on one line wraps to column one
NT 1 B A-117
of the next line. Lines and figures start at the
(Note)
current left margin, and examples are indented
four spaces from the current left margin. The P 1 B A-121
current left margin changes when nested lists are (Paragraph)
formatted. If there is online help information con- PC 1 B A-131
taining lines, figures, or examples imbedded at (Paragraph con-
various locations, including within lists, it may not tinuation)
look the same each time. LP 1 B A-107
(List part)
Parameter lists can occur anywhere in text; they
OL 1 B A-118
can be nested within other lists, and other lists (Ordered list)
can be nested within parameter lists. Two PT or
SL 1 B A-152
two PD tags cannot be used consecutively.
(Simple list)
Nested PARML tags increase the current left UL 1 B A-164
margin by four. (Unordered list)
PARML 1 B A-129
Other tags can be nested within the PARML tag. (Parameter list)
These tags are listed in the following table. The
DL 1 B A-57
table defines the order in which the tags must (Definition list)
(specified by a D, P, or B, respectively), and spec- Required Tags
for each tag. PT.parameter-term
The parameter term. The term formats in
When more than one tag is listed with the same highlight phrase 2 (HP2) and can contain the
order number, all tags of that number can be programming keyword (PK) or programming
mixed in any order. However, a tag with a higher variable (PV) tags.
order number cannot precede a tag with a lower The term appears on a line by itself, starting
order number. For example, a tag with an order at position four relative to the current left
number of three cannot precede a tag with an margin.
PD.parameter-description
The description of the parameter. It can also
contain the PK and PV tags.

PARML, PT, PD Tags
The definition is printed on the following line, UIM Source

with the paragraph indented eight spaces from
:PARML.
the current left margin. It is an implied para-
:PT.TERM
graph and can contain any text items. Addi- :PD.This is a description of
tional paragraphs can be inserted following the term. :PK.Term:EPK. is
the description paragraph by using the para- a programming keyword.
graph tag. :PT.:PK def.DEFAULT:EPK.
:PD.This is a sample default
Example: Parameter List parameter.
:PT.:PV.variable:EPV.
This example uses a parameter list to define :PD.This is a parameter variable.
:EPARML.
terms or parameters.
Results
TERM
This is a description of the term. Term
is a programming keyword.
DEFAULT
This is a sample default parameter.
variable
This is a parameter variable.

PC Tag
PC (Paragraph Continuation)
55──:PC.paragraph-continuation-text─────────────────────────────────────────────────────5%
The paragraph continuation (PC) tag identifies the UIM Source

continuation of a paragraph that has been inter-
:p.If you enter the following
rupted by another document element. This tag is
command
allowed only in information areas and help areas.
:xmp.
WRKSPLF
A paragraph continuation usually occurs after a :exmp.
figure, example, or a list. It indicates that the fol- :pc.a listing of all my spool files
lowing text is a continuation of the paragraph appears on the
interrupted by a figure, example, or list. terminal.
A matching end tag is not allowed. A paragraph

Results
continuation is implicitly ended by another para-
graph or by a higher-level element.
If you enter the following command
Example: Paragraph WRKSPLF
Continuation a listing of all my spool files appears on
the terminal.
The paragraph continuation tag continues the par-
agraph after the interruption of an example.

PDACCEL tag
PDACCEL (Pull-Down Accelerator)
55──:PDACCEL──.──accelerator-text───────────────────────────────────────────────────────5%
The pull-down choice accelerator (PDACCEL) tag Required Text

defines text to be displayed as the accelerator key
for a pull-down choice. accelerator-text
The displayable description for the accelerator
This tag defines only the text displayed. It does key. The text must appear on the same or
not automatically define the function key. It is next line as the tag. The text cannot contain
your responsibility to define the function key with any other tags, and cannot exceed 4 bytes in
the key list item (KEYI) tag to perform the action length.
defined for the pull-down choice accelerator. The accelerator text is displayed to the right of
its pull-down choice. The first character of
each accelerator in the pull-down field is left-
aligned two spaces after the longest text for
any pull-down choice.

PDFLD tag
PDFLD (Pull-Down Field)
55──:PDFLD──┬───────────────────────────┬──.──:EPDFLD.──────────────────────────────────5%
└─NAME=pull-down-field-name─┘
The pull-down field (PDFLD) tag defines a When more than one tag is listed with the same
selection field within the menu bar pull-down. A order number, all tags of that number can be
pull-down field consists of one or more pull-down mixed in any order. However, a tag with a higher
choices. The pull-down fields are formatted order number cannot precede a tag with a lower
according to the IBM Systems Application Archi- order number. For example, a tag with an order
tecture (SAA) basic interface. number of three cannot precede a tag with an
A single pull-down field can be defined for one
menu bar choice between the menu bar choice Table A-24. Tags Allowed Between the PDFLD and
(MBARC) and the EMBARC tags. The largest EPDFLD Tags
option number allowed for a pull-down choice is Tag Name Order Use Page
99. The number of pull-down choices allowed to
PDACCEL 1 D A-132
be specified between the PDFLD tag and the (Pull-down choice
EPDFLD tag is determined by how many choices accelerator)
fit on the screen, based on conditioning. The
PDFLDC 1 D A-134
maximum number of pull-down choices active at
(Pull-down field
one time is determined by what fits on a screen. choice)
Other tags can be nested within the PDFLD tag.

These tags are listed in the following table. The Optional Attribute
appear, indicates which tags can be used in NAME=pull-down-field-name
display panels only, print panels only, or both The name associated with the pull-down field.
(specified by a D, P, or B, respectively), and spec- For more information on the rules for naming,
ifies on which page more information can be found see “Name Syntax” on page A-4.
for each tag.

PDFLDC tag
PDFLDC (Pull-Down Field Choice)
55──:PDFLDC──OPTION=option-number──HELP=help-module-name──ACTION='action-text'───────────5
5──┬────────────────────┬──┬─────────────────────────────┬───────────────────────────────5
│ ┌─PANEL─┐ │ └─CONFIRM=internal-panel-name─┘
└─ACTFOR=─┴─LIST──┴──┘
5──┬──────────────────────────────────┬──┬──────────────────┬────────────────────────────5
└─USREXIT='CALL program-reference'─┘ └─VARUPD=─┬─YES─┬──┘
└─NO──┘
5──┬─────────────────────┬──┬──────────────────────┬──┬─────────────────────────────┬────5
└─COND=condition-name─┘ └─AVAIL=condition-name─┘ └─AVLMSGID=message-identifier─┘
5──┬───────────────────────────────────────┬──┬─────────────────────────────┬──.─────────5
└─AVLMSGF='qualified-message-file-name'─┘ └─CHOICE=dialog-variable-name─┘
5──┬───────────────────────┬────────────────────────────────────────────────────────────5%
└─pull-down-choice-text─┘
The pull-down field choice (PDFLDC) tag defines choices. If the cursor is in the entry field and
one choice within a pull-down field. A pull-down a valid choice has been entered when help is
field consists of one or more pull-down choices. requested, the help for that choice is dis-
played.
Required Attributes ACTION='action-text'
OPTION=option-number The action occurring when the pull-down
The number assigned to this option. Option choice is selected.
numbers are integers in the range of 1
through 99. Table A-25. Valid Action Text for ACTION Values
The pull-down choices are displayed in the Dialog

Command ACTFOR=PANEL ACTFOR=LIST
order defined in the pull-down field. If the
numbering of two choices is not consecutive, CALL X X
a blank line is automatically placed between CHGVIEW X
the two choices. CMD X X
CMDLINE X
HELP=help-module-name DSPHELP X
Identifies help information explaining the EXIT X
purpose of the pull-down field choice. The EXTHELP X
name of the help module may be a name HELPHELP X
HELPIDX X
imported from another panel group, but must
KEYSHELP X
follow the rules for names outlined earlier in MENU X
this chapter. For more information on the RETRIEVE X
rules for names, see “Name Syntax” on RETURN X X
page A-4.
The online information identified by this attri- For a description of each of these actions,
bute is displayed when help is requested while see Appendix B, “UIM Dialog Commands” on
the cursor is positioned on text for this tag. page B-1.
This online information is also included as part
of the contextual help displayed when the Optional Attributes
cursor is positioned on the text for the menu
bar choice for this pull-down menu, or when ACTFOR=PANEL | LIST
the cursor is positioned within the pull-down If PANEL is specified, the pull-down choice
menu but not on the text for one of the performs actions against the whole panel.

PDFLDC tag
If LIST is specified, the pull-down choice per- If NO is specified, the action is performed
forms actions against items in a selection list immediately and no variable pool updating
or in an action list. occurs.
When LIST is specified on a pull-down choice
and if the user has not selected a list to be Dialog Command VARUPD Values
processed, the pull-down choice is displayed CALL YES | NO
with an asterisk (*) overlaying the option CHGVIEW YES
number to indicate that the pull-down choice is CMD YES | NO
not available. CMDLINE NO
DSPHELP NO
CONFIRM=internal-panel-name EXIT NO | YES
The name of the confirmation panel displayed EXTHELP NO
before the action is performed. This attribute HELPHELP NO
is allowed only when ACTFOR=LIST and KEYSHELP NO
HELPIDX NO
ACTION=CALL or ACTION=CMD is specified on
MENU YES
this tag. The confirmation panel must give the RETRIEVE NO
user the option to confirm or not confirm the RETURN YES | NO
action. If the action is confirmed, the appro-
priate actions from this tag are performed. If Note: The default value is based on the
the action is not confirmed, none of those ACTION attribute. The first value is the default
actions are performed. value.
The confirmation panel must be another panel

defined within this panel group. COND=condition-name
The pull-down choice is in effect on the panel
For a list of the recommended and required only if the condition specified evaluates to
conventions for this attribute, see “Confirma- true. The condition must be defined in the
tion Panel Requirements” on page A-136 and panel group prolog with the condition definition
“Confirmation Panel Conventions” on (COND) tag. When the choice is
page A-136. conditioned-off, it does not appear in the pull-
USREXIT='CALL program-reference' down and the help for the choice is not
Specifies the exit program for the action list included in requests to display help.
program called to update the list entries after AVAIL=condition-name
the action defined in the ACTION attribute is The name of a condition used by the UIM to
performed. This attribute is allowed only determine whether or not the pull-down choice
when ACTFOR=LIST and ACTION=CALL or is available. The condition must be defined in
ACTION=CMD is specified on this tag. The the panel group prolog with the COND tag.
program is passed information that includes
the name of the list and an indication of When the condition is true, the pull-down
whether the option succeeded or failed. choice is available. When the condition is
false, the pull-down choice is not available.
For a description of the CALL dialog Any condition specified on the COND attribute of
command, see Appendix B, “UIM Dialog this tag takes precedence over this attribute.
Unavailable choices are displayed with a color
For a description of the interface between the change on color devices and an asterisk (*)
UIM and the exit program for action lists, see overlaying the first part of the choice option
the System API Reference. number.
VARUPD=YES | NO AVLMSGID=message-identifier
This attribute is allowed only when PANEL is The message identifier of the message dis-
specified on the ACTFOR attribute for this tag. played when the pull-down choice is selected
When ACTFOR=LIST is specified, variable pool when it is not available as specified by the
updating is performed. If YES is specified, AVAIL attribute. This attribute is allowed only
validity checking occurs and the variable pool when the AVAIL attribute is specified on this
is updated before the action takes place.

PDFLDC tag
tag. If this attribute is not specified, the UIM when BIDI=LTR or when BIDI=RTL is speci-
displays a default message stating that the fied on the PNLGRP tag.
choice is currently not available.
AVLMSGF='qualified-message-file-name' Confirmation Panel Requirements

The message file name containing the
message identifier. This attribute is allowed The panel named on the CONFIRM attribute of this
only when the AVLMSGID attribute is specified tag must follow these conventions:
on this tag. If the DFTMSGF attribute is not The ENTER attribute on the display panel
specified on the panel group (PNLGRP) tag, (PANEL) tag of the confirmation panel should
and if the AVLMSGID attribute on this tag is have 'RETURN 100' coded. This indicates to
specified, this attribute must be specified. the UIM that the action is confirmed by the
user.
CHOICE=dialog-variable-name
The name of a dialog variable containing the No ACTION attribute on a key list item (KEYI)
pull-down choice text to be displayed. The tag can be assigned to the RETURN action,
dialog variable must be defined with a width because the UIM is handling the display of the
less than or equal to 32 bytes. If this attribute panel and is unable to interpret the returned
is used, no pull-down-choice-text can be spec- value.
ified. The confirmation panel must have a list area.
Dialog variables must be defined with a The list used as the confirmation list must not
BASETYPE of CHAR, IGC, or BIN on the class also be used on the action list panel.
The confirmation panel must not have an
The error state of the dialog variable is not action list, a command line, a menu area, or a
used for determining the highlighting of the menu bar.
text.
Special formatting for IGC. (The abbrevi- Confirmation Panel Conventions
to represent double-byte character set func- The panel named on the CONFIRM attribute of this
tions.) When a dialog variable with a tag should follow these conventions:
tag, the UIM does special formatting. If the It should have title text and top instructions as
variable value begins with a shift-out character appropriate to describe the panel.
(X'0E'), the UIM shifts the value 1 byte to the It should have a single list area with a list defi-
left to preserve vertical alignment with choices nition that contains the same (or a subset of)
on other lines. columns defined in the original action or
selection list.
Optional Text The list should be scrollable.
pull-down-choice-text If the action list has multiple views, the confir-
The descriptive text shown in the pull-down mation list should also have multiple views
field. The text may appear on a single line in and the same dialog variable should be used
the source. The text can contain only the for the view variable on both lists. The confir-
reverse text (RT) tag, and cannot exceed 32 mation panel should also have a function key
bytes in length. The pull-down-choice-text is defined for the CHGVIEW dialog command.
required unless the CHOICE attribute is speci- This allows a change view operation on the
fied on this tag. confirmation panel to change the view of the
action or selection list panel when it is redis-
For a pull-down choice, the option number, a
played.
period, and one blank appears immediately
before the choice description text. The The confirmation panel should have function
NBRSHAPE attribute of the PNLGRP tag key definitions for the ENTER, CANCEL,
explains how option numbers are presented PAGEUP, PAGEDOWN, HELP, and PRINT
dialog commands.

PDFLDC tag
If a general exit program is defined, it should tion panels are used within a UIM application,
avoid making changes to the list or condition they can share the same list.
values that affect the redisplay of the original
Most of the online help information for the
panel.
action list panel can be used for the confirma-
The list used on the confirmation panel should tion panel, but separate help information
not be used on anything but a confirmation should be provided for the action column and
panel, because the UIM deletes and changes for the extended panel help.
the contents of that list. If multiple confirma-

PK Tag
PK (Programming Keyword)
55──:PK──┬─────┬──.──programming-keyword-text──:EPK.────────────────────────────────────5%
└─DEF─┘
The programming keyword (PK) tag identifies a text associated with it to be displayed with the
programming keyword. This tag is only allowed in same emphasis.
information areas and help areas. It requires a
matching end tag. Optional Attribute
A programming keyword can occur anywhere in DEF
text. It helps explain the elements of program- Specifies that the programming keyword is a
ming syntax and is frequently used within param- default value. The programming keyword
eter lists. For more information on parameter lists, formats in highlight phrase 2 (HP2) unless the
see “PARML (Parameter List)” on page A-129, DEF attribute is specified. If the DEF attribute is
specified, the programming keyword formats
The PK and EPK tag phrase must be specified on as highlight phrase 3 (HP3).
diately following the EPK tag are a punctuation
mark and a blank, the UIM automatically extends
Required Text
the emphasis attribute to include the punctuation programming-keyword-text
mark. This allows the punctuation mark and the Specifies the programming keyword.

PNLGRP Tag
PNLGRP (Panel Group)
55──:PNLGRP──┬──────────────────────────────┬──┬───────────────────────────────┬─────────5
└─SCHIDX=qualified-object-name─┘ └─HLPSHELF=─┬─LIST───────────┬──┘
└─bookshelf-name─┘
5──┬──────────────────┬──┬────────────────────┬──────────────────────────────────────────5
│ ┌─NO──┐ │ │ ┌─SBCS─┐ │
└─ENBGUI=─┴─YES─┴──┘ └─TXTMODE=─┴─DBCS─┴──┘
5──┬────────────────────────────────────┬──┬─────────────────┬───────────────────────────5
└─TXTCHRID='character-set code-page'─┘ │ ┌─NONE─┐ │
└─BIDI=─┼─LTR──┼──┘
└─RTL──┘
5──┬───────────────────────┬──┬─────────────────────────────────────┬────────────────────5
│ ┌─ARABIC─┐ │ └─DFTMSGF=qualified-message-file-name─┘
└─NBRSHAPE=─┴─HINDI──┴──┘
5──┬───────────────────────────────────────┬──.──:EPNLGRP.──────────────────────────────5%
└─SUBMSGF='qualified-message-file-name'─┘
The panel group (PNLGRP) tag begins the defi- Table A-26. Tags Allowed Between the PNLGRP and
nition of a panel group. Only one PNLGRP tag is EPNLGRP Tags
allowed and a matching EPNLGRP tag is Tag Name Order Page
required.
VARRCD 5 A-169
(Variable record defi-
Other tags can be nested within the PNLGRP tag. nition)
These tags are listed in the following table. This
table defines the order in which the tags must LISTDEF 6 A-100
(List definition)
mation can be found for each tag. COND 7 A-27
(Condition definition)
When more than one tag is listed with the same TT 8 A-162
order number, all tags of that number can be (Truth table)
MBAR 9 A-108
order number cannot precede a tag with a lower (Menu bar)
KEYL 10 A-76
(Key list)
PANEL 11 A-122
Table A-26. Tags Allowed Between the PNLGRP and (Display panel)
EPNLGRP Tags PRTHEAD 11 A-142
Tag Name Order Page (Print head panel)
COPYR 1 A-30 PRTPNL 11 A-146
(Copyright) (Print panel)
ISCHSYN any A-72 HELP 11 A-60
(Index search synonym) (Help module)
IMPORT 2 A-67
(Import)
Optional Attributes
CLASS 3 A-14
(Class definition) SCHIDX=qualified-object-name
The index search object used when the index
VAR 4 A-166
search function is requested from the help
(Variable definition)
modules for panels defined in this panel
group. If SCHIDX is not specified, the index

PNLGRP Tag
search function is not accessible when help present DBCS help information on a device
modules are displayed for panels in this panel that does not support DBCS results in an
group. This attribute has no effect on help exception.
modules defined in the panel group unless
TXTCHRID='character-set code-page'
panels in the panel group use the help
Specifies the character set and code page for
modules. This attribute is mutually exclusive
SBCS text data in the panel group source.
with the HLPSHELF attribute.
This information is used for synonyms defined
HLPSHELF=LIST | bookshelf-name using the index search synonym (ISCHSYN)
Specifies the bookshelf to be used when tag. For more information on this tag, see
InfoSeeker is requested from the help “ISCHSYN (Index Search Synonym)” on
modules for the panels defined in the panel page A-72. If this attribute is omitted, all text
group. LIST indicates that the default list of must be on the index search (ISCH) and
books and bookshelves are to be used. If the ISCHSYN tags to be in the character set and
HLPSHELF attribute is not specified, code page specified by the QCHRID system
InfoSeeker is not accessible when help value at the time the panel group is created.
modules are displayed for the panels in the
The TXTCHRID attribute specifies the code
panel group. This attribute has no effect on
page and character set of the text information
help modules defined in the panel group
in the panel group source. It must not be con-
unless panels in the panel group use the help
fused with the CHRID parameter on the
modules. This attribute is mutually exclusive
CRTPNLGRP command, which controls the
with the SCHIDX attribute.
way dialog variables with CHRID=PNLGRP
ENBGUI=NO | YES specified on the class definition (CLASS) tag
Specifies the default value for enabling a are handled when the dialog variable value is
client program for all panels in the panel sent to or from the display station.
group. This attribute establishes the value
BIDI=NONE | LTR | RTL
when ENBGUI=PNLGRP is specified or
Indicates the orientation of the panels in the
defaulted on the PANEL tag.
panel group. NONE indicates that the panels
When ENBGUI=YES is specified for a panel, the in the panel group should be displayed in a
UIM includes information about the layout and single direction with a left-to-right orientation.
content of the panel in the 5250 data stream. NONE is the default and is required when
This information is used by a client program to TXTMODE=DBCS is specified on this tag.
create the graphical interface on the client.
When BIDI=NONE is coded, the following
Table A-22 on page A-124 describes the
items are ignored:
information that is included in the 5250 data
stream. The NBRSHAPE attribute on this tag
The BIDI, NBRSHAPE, CONTXTREV, and
When ENBGUI=NO is specified for a panel, the
SYMSWAP attributes on the CLASS tag
UIM does not include the extra information in
All reverse text (RT) tags
the data stream.
LTR indicates that the panels in the panel
TXTMODE=SBCS | DBCS
group are bidirectional and should be dis-
Specifies whether a single-byte character set
played with a left-to-right orientation.
(SBCS) or double-byte character set (DBCS)
is used in the tag text. If DBCS is specified, RTL indicates that the panels in the panel
the tag text must have the shift-in or shift-out group are bidirectional and should be dis-
characters to indicate the start and end of played with a right-to-left orientation.
DBCS text.
When either LTR or RTL is specified for a
A panel group object for which TXTMODE=DBCS panel group, the work station controller
is specified can only be used on a display enables the hot key to flip the panel so that
station and system capable of handling DBCS the user can flip the panel if necessary.
information. An attempt to display a DBCS When RTL is specified, the controller automat-
menu, open a DBCS panel group object, or

PNLGRP Tag
ically flips all panels of the panel group as Numbers generated by the UIM for
they are displayed. ordered list numbers
The normal use of LTR is for panels written in Numbers generated by the UIM for pull-
a left-to-right language with a small amount of down field choices
right-to-left language text in it. The normal
Page number information on a print panel
use of RTL is for panels written in a right-to-
and printed help information
left language with a small amount of text in a
left-to-right language. Numbers that are not affected by the NBRSHAPE
attribute are:
The UIM does not allow a LTR or RTL panel
to be used on a display device that does not The digits used in the system name
have the correct code page for bidirectional Messages displayed on the message line
languages. Hebrew uses code page 424 and Copyright dates on the message line
Arabic uses code page 420. Product number information on a print
The value of this attribute of all possible panel panel and in printed help information
groups that can be reached through hypertext Because the Hindi zero looks like a period,
links should be the same. If they are not the the format of the number in front of a menu
same when a reference phrase is selected, item or pull-down choice is 'n)' instead of
the resulting screen or pop-up window may be 'n.', where 'n' is the menu item or choice
displayed with the opposite orientation. option number.
NBRSHAPE=ARABIC | HINDI DFTMSGF= qualified-message-file-name
This attribute is ignored when BIDI=NONE is The default message file used when a
specified on this. The NBRSHAPE attribute con- message file is not specified for a message
trols the display shape of UIM-generated identifier on any of the following tags:
numbers. This attribute is ignored except
when code page 420 (Arabic) is being used. CHECK Validity checking
LISTDEF List definition
When ARABIC is specified, the normal digits,
TL Translation list
X'F0' through X'F9', are used for numbers.
DATASLTC Data selection field
ARABIC is the default.
PDFLDC Pull-down field choice
When HINDI is specified, the translation of LISTACT List action
digits is performed with a translation table MENUI Menu item
defined for each national language.
If the corresponding message file attribute is
Digits that come from the panel group source not specified on any of these tags when the
or from messages are not affected by the MSGID attribute is specified for this tag, this
NBRSHAPE attribute because they are expected attribute is required.
to already be translated to the correct char-
acter. The numbers that are affected by the SUBMSGF= qualified-message-file-name
NBRSHAPE attribute are: The default message file used when a
message file is not specified on the &msg
Numbers generated by the UIM for menu symbol.
items

PRTHEAD Tag
PRTHEAD (Print Head Panel)
55──:PRTHEAD──NAME=panel-name──┬───────────────────────────────┬─────────────────────────5
└─PRODINFO=dialog-variable-name─┘
5──┬──────────────────────────────┬──┬──────────────────────────────┬────────────────────5
└─PRTDATE=dialog-variable-name─┘ └─PRTTIME=dialog-variable-name─┘
5──┬────────────────────────────┬──┬─────────────────────┬──┬─────────────────┬──────────5
└─TITLE=dialog-variable-name─┘ └─TT=truth-table-name─┘ │ ┌─8ð──┐ │
└─WIDTH=─┴─132─┴──┘
5──┬──────────────────────────┬──┬─────────────────────────────┬──.──────────────────────5
└─OBJ=dialog-variable-name─┘ └─OBJLIB=dialog-variable-name─┘
5──┬─────────────────┬──:EPRTHEAD.──────────────────────────────────────────────────────5%
└─page-title-text─┘
A print head panel (PRTHEAD) tag contains tags Required Attribute

defining heading information and data used with a
UIM print application. A print heading panel NAME=panel-name
establishes the prolog section printed after the title The name of the print head panel. For more
line on the first page and the header data printed information on the rules for naming, see
at the top of every page. The prolog and header “Name Syntax” on page A-4.
sections can be made up of data and information
areas. A PRTHEAD panel causes an automatic Optional Attributes
page eject.
PRODINFO=dialog-variable-name
Other tags can be nested within the PRTHEAD The name of a dialog variable containing the
tag. These tags are listed in the following table. product information printed on the second title
The table defines the order in which the tags must line of the print output.
appear, indicates which tags can be used in The dialog variable must be defined with a
display panels only, print panels only, or both BASETYPE of CHAR or IGC on the class defi-
(specified by a D, P, or B, respectively), and spec- nition (CLASS) tag, and the maximum width is
ifies on which page more information can be found 22 bytes.
for each tag.
PRTDATE=dialog-variable-name
When more than one tag is listed with the same The name of a dialog variable containing the
order number, all tags of that number can be date printed on the page title. If this attribute
mixed in any order. However, a tag with a higher is specified, the PRTTIME attribute must also be
order number cannot precede a tag with a lower specified on this tag. If this attribute is not
order number. For example, a tag with an order specified, the UIM uses the current system
number of three cannot precede a tag with an date when the Open Print Application
order number of one or two. (QUIOPNPA) API or the Add Print Application
(QUIADDPA) API is called.
Table A-27. Tags Allowed Between the PRTHEAD
and EPRTHEAD Tags The dialog variable must be defined with a
class that has a BASETYPE of DATE on the
CLASS tag.
DATA 1 P A-31
(Data presenta- PRTTIME=dialog-variable-name
tion area) The name of a dialog variable containing the
INFO 1 P A-68
time printed on the page title. The dialog vari-
(Information area) able must be defined with a class that has a
BASETYPE of TIME on the CLASS tag. If this
PRTTRAIL 2 P A-148
(Print trail)

PRTHEAD Tag
attribute is specified, the PRTDATE attribute OBJ=dialog-variable-name

must also be specified on this tag. If this attri- The name of a dialog variable containing the
bute is not specified, the UIM uses the current name of the object whose information is
system time when the QUIOPNPA API or the printed on the title line of the printout. If this
QUIADDPA API is called. attribute is not specified, an object name is
not printed.
TITLE=dialog-variable-name
The name of a dialog variable containing the If the OBJLIB attribute on this tag is specified,
text for the page title line. The dialog variable the class for this dialog variable must be
must be defined on a CLASS tag with a defined with a width of 10 characters. If the
display width of 55. A translation list may be OBJLIB attribute is not specified, the class for
used to provide the panel title or the width of this dialog must be defined with a width of 1
the panel minus two, whichever is less. The to 21 characters.
dialog variable may also be defined with a
OBJLIB=dialog-variable-name
BASETYPE of CHAR 55 or IGC 55 on the
CLASS tag. The UIM trims trailing blanks
name of the library where the specified object
from the string and centers the resulting text
from the OBJ attribute on this tag is found.
in the page title area. If this attribute is used,
This library name is printed on the title line of
no title-text can be specified.
the printout. If this attribute is not specified, a
TT=truth-table-name library name is not printed.
The name of a truth table specifying what You are responsible for the validity of the data
combinations of truth values may occur at run contained in the OBJ and OBJLIB attributes.
time when the panel head is formatted. The UIM does not perform validity checking
The table specified on this tag may contain a on these variables. If only the OBJ attribute is
subset of the conditions referred to by tags in specified, only the OBJ is printed. However, if
the print head panel. Only the truth value only the OBJLIB attribute is specified, a
combinations specified in the table, aug- message is issued at compile time.
mented by worst-case assumptions for any The class for this dialog variable must be
truth values not specified in the table, are con- defined with a width of 10 characters.
sidered in evaluating whether or not the print
head panel is valid. The table should not
exclude any truth value combination that could Optional Text
occur when the print head panel is formatted page-title-text
at run time. If a valid truth value combination The title used on the title line. The text must
is omitted, a panel group object may create appear on the same line or next line as the
without error and produce undesirable results tag. The text can only contain the reverse
when panels are printed. text (RT) tag, and cannot exceed 55 charac-
If this attribute is omitted, all combinations of ters in length. The page-title-text is required
truth values are considered possible. This unless the TITLE attribute is specified on this
causes the tag language compiler to make tag.
worst-case assumptions for all conditions in
evaluating whether or not the print head panel Layout of the Title Lines
is valid.
The title lines for the PRTHEAD tag appear on the
WIDTH=80 | 132
top two lines of each printed page. The place-
Defines the width, in bytes, of the PRTHEAD
ment of fields in the title lines depends on the
panel. The default value is 80 bytes.
width specified on this tag.

PRTHEAD Tag
Table A-28. First Line of Heading with Print Width 132 Table A-30. Second Line of Heading with Print Width
132
Start
Data Column Length Start
Data Column Length
Title See Max. 55
note. Product information 1 22
Separator See 4 Separator 23 Min. 55
note.
Library See Max. 10
"Page" (with expansion) See Max. 11 note.
note.
Slash See 1
Separator 125 2 note.
Page number 127 4 Object See Max. 10
note.
Separator 131 2
Separator 99 4
Note: The start column for this data is variable. The
title is centered between the left margin and the sepa- System name 103 8
rator following the title.
Separator 111 2
Date 113 8
Table A-29. First Line of Heading with Print Width 80
Separator 121 2
Start
Data Column Length Time 123 8
Title See Max. 55 Separator 131 2
note.
Note: The library and object are formatted as
Separator See 4 OBJLIB/OBJ with trailing blanks stripped from the
note. OBJLIB and OBJ values. The OBJLIB/OBJ aggregate
is right-justified against the separator before the system
"Page" (with expansion) See Max. 11
name.
note.
Separator 73 2
Page number 75 4
Separator 79 2
Note: The start column for this data is variable.

PRTHEAD Tag
Table A-31. Second Line of Heading with Print Width Example: Print Title Line
80
Start The following example has a title line for output
Data Column Length with a width of 132 bytes. The title is from the
Product code 1 Max. 22 print head panel or the first print panel. The page
text and page number are provided by the UIM.
Separator 23 Min. 3
Library See Max. 10 Either the UIM or the application can provide the
note. date and time. The application must use the
Slash See 1 PRTDATE and PRTTIME attributes on the PRTHEAD
note. tag to specify a date and time. If the PRTDATE and
Object See Max. 10
PRTTIME attributes are not specified, the UIM uses
note. the system date and time when the QUIOPNPA
API or the QUIADDPA API is called. The date
Separator 47 4
and time are formatted using the job attributes.
System name 51 8
Separator 59 2
Date 61 8
Separator 69 2
Time 71 8
Separator 79 2
Note: The library and object are formatted as
OBJLIB/OBJ with trailing blanks stripped from the
OBJLIB and OBJ values. The OBJLIB/OBJ aggregate
is right-justified against the separator before the system
name.
This is an Example of a Print Title Line Page 1

5738SS1 V2R1Mð 9ðð1ð1 QNETUSER/EXAMPLE SYSTEMð1 ð5/25/9ð 11:ð9:ð4

PRTPNL Tag
PRTPNL (Print Panel)
55──:PRTPNL──NAME=panel-name──┬────────────────────────────┬──┬─────────────────────┬────5
└─TITLE=dialog-variable-name─┘ └─TT=truth-table-name─┘
5──┬─────────────────┬──.──┬────────────┬──:EPRTPNL.────────────────────────────────────5%
│ ┌─8ð──┐ │ └─title-text─┘
└─WIDTH=─┴─132─┴──┘
A print panel (PRTPNL) tag contains tags to Optional Attributes

define one or more area definitions for a print
panel. It requires a matching EPRTPNL tag. TITLE=dialog-variable-name
Other tags can be nested within the PRTPNL tag. text for the panel title when the panel is
These tags are listed in the following table. The printed. The dialog variable must be defined
table defines the order in which the tags must with a class that has a width of 55. The UIM
appear, indicates which tags can be used in trims trailing blanks from the string and
display panels only, print panels only, or both centers the resulting text in the title line of the
(specified by a D, P, or B, respectively), and spec- print panel. If this attribute is used, no title-
ifies on which page more information can be found text can be specified.
for each tag.
TT=truth-table-name
When more than one tag is listed with the same The name of a truth table that specifies what
order number, all tags of that number can be combinations of truth values may occur at run
mixed in any order. However, a tag with a higher time when the panel is printed.
order number cannot precede a tag with a lower The table specified on this tag may contain a
order number. For example, a tag with an order subset of the conditions referred to by tags in
number of three cannot precede a tag with an the print panel. Only the truth value combina-
order number of one or two. tions specified in the table, augmented by
worst-case assumptions for any truth values
Table A-32. Tags Allowed Between the PRTPNL and not specified in the table, are considered in
EPRTPNL Tags
evaluating whether or not the print panel defi-
Tag Name Order Use Page nition is valid. The table should not exclude
DATA 1 P A-31 any truth value combination that could occur
(Data presenta- when the print panel is printed. If a valid truth
tion area) value combination is omitted, a panel group
INFO 1 P A-68
object may create without error and produce
(Information area) undesirable results when panels are printed.
LIST 1 P A-82 If this attribute is omitted, all combinations of
(List area) truth values are considered possible. This
causes the tag language compiler to make
worst-case assumptions for all conditions in
Required Attribute evaluating whether or not the print panel is
NAME=panel-name valid.
The name of the print panel. For more infor- WIDTH=80 | 132
mation on the rules for naming, see “Name Defines the width, in bytes, of the print panel.
Syntax” on page A-4. The default value is 80 bytes.
Optional Text

PRTPNL Tag
title-text text (RT) tag, and cannot exceed 55 charac-

The title used on this print panel. The text ters in length. The title-text is not allowed if
must appear on the same or next line as the the TITLE attribute is specified on this tag.
tag. The text can only contain the reverse

PRTTRAIL Tag
PRTTRAIL (Print Trailer Message)
55──:PRTTRAIL.trailer-message-text──────────────────────────────────────────────────────5%
The print trailer message (PRTTRAIL) tag is leading or trailing asterisks (*). The UIM adds
allowed only within the print head panel asterisks before and after the text.
(PRTHEAD) tag, appearing immediately before the
The text can be a maximum of 106 bytes for
EPRTHEAD tag. The trailer message is printed at
WIDTH=132 and a maximum of 54 bytes for
the end of the print listing. If no trailer is speci-
WIDTH=80, specified on a PRTHEAD tag. The
fied, no default trailer is printed.
text can contain only the reverse text (RT) tag.
Note: The trailer is only printed when the printer
file is closed by using the option for a normal Example: Trailer Message
close on either the Close Application (QUICLOA)
API or the Remove Application (QUIRMVPA) API. This example shows what kind of text a print
The trailer is not printed if the application is closed trailer message might have.
using the option for an abnormal close.
UIM Source
Required Text :prttrail.E N D O F L I S T I N G
trailer-message-text
The text appearing at the end of the print
listing. This text can be entered without

PV Tag
PV (Programming Variable)
55──:PV.programming-variable:EPV.───────────────────────────────────────────────────────5%
The programming variable (PV) tag identifies a diately following the EPV tag are a punctuation
programming variable. It requires a matching end mark and a blank, the UIM automatically extends
tag. These tags are only allowed in information the emphasis attribute to include the punctuation
areas and help areas. It is frequently used within mark. This allows the punctuation mark and the
parameter lists. For more information on param- text associated with it to be displayed using the
eter lists, see “PARML (Parameter List)” on same emphasis.
page A-129.
A programming variable can occur anywhere in

Required Text
the text to help explain the elements of program- programming-variable
ming syntax. The programming variable. The text formats
in highlight phrase 1 (HP1).
The PV and EPV tag phrase must be specified on

RT Tag
RT (Reverse Text)
55──:RT.reverse-direction-text:ERT.─────────────────────────────────────────────────────5%
The reverse text (RT) tag indicates that the LISTGRP List group
enclosed text has an orientation opposite to the LI List item
orientation of the panel group. This tag is ignored LP List part
for panel groups with BIDI=NONE specified on MBARC Menu bar choice
the panel group (PNLGRP) tag. On a BIDI=RTL MENU Menu area
panel group, text in a left-to-right language is MENUI Menu item
placed between the RT and ERT tags, while on a NT Note
BIDI=LTR panel group, text in a right-to-left lan- OPTLINE Option line
guage is placed between the RT and ERT tags. P Paragraph
PC Paragraph continuation
With the import (IMPORT) tag, it is possible to PD Parameter description
combine help information from panel groups that PT Parameter term
have BIDI=RTL specified with help information PRTHEAD Print head panel
from panel groups that have BIDI=LTR specified. PRTPNL Print panel
This is not recommended, but when it does occur, PRTTRAIL Print trailer message
the user needs to use the hot key sequence for PDFLDC Pull-down field choice
the work station controller to flip the screen to TOPINST Top instruction line
read the help information with the opposite orien-
tation. Any text within the RT and ERT tags is for- The RT tag cannot be used within a figure (FIG),
matted correctly for its panel group orientation. unformatted lines (LINES), or an example (XMP)
Therefore, when the RT tag is used for text that is tag. No tag is allowed between an RT tag and its
imported into help information with the opposite matching ERT tag.
orientation, the imported text is also readable
when the screen is flipped. Blanks found between an RT tag and its matching
ERT tag are preserved. This includes the trailing
Unlike the highlight phrase tags, the RT tag is blank at the end of each source line. Therefore,
allowed within the text of most tags. The following starting a source line with an ERT tag is not
tags allow an imbedded RT tag: recommended.
BOTINST Bottom instructions
CIT Title citation Example 1: Left-to-Right
CMDLINE Command line Formatting on a Right-to-Left
DATA Data area Panel
DATASLTC Data selection choices
DATAGRP Data group This example illustrates left-to-right source for-
DATAI Data item matted and displayed on a right-to-left panel.
DD Definition
DDHD Definition header
UIM Source
DT Definition term
DTHD Definition term header :P.For more information see the
FIGCAP Figure caption text :CIT.:RT.IBM OS/4ðð User Interface
Hn Headings Manager Reference Manual:ERT.:ECIT.
HPn Highlighted phrase which you can find in your library.
INFO Information area
KEYI Key list item Results
LINK Hypertext link definition IBM OS/4ðð User eht ees noitamrofni erom roF
LIST List area uoy hcihw Interface Manager Reference Manual
LISTACT List action .yrarbil ruoy ni dnif nac

RT Tag
Example 2: Left-to-Right :P.This is an example of some

:RT.PRETEND HEBREW TEXT:ERT.
Formatting on a Left-to-Right imbedded within some real
Panel English text.
This example illustrates left-to-right source for- Results

matted and displayed on a left-to-right panel.
This is an example of some DNETERP
TXET WERBEH imbedded within some
UIM Source real English text.

SL, LI Tags
SL (Simple List)
┌──
───────────────┐
55──:SL──┬─────────┬──.───6─:LI.item-text─┴──:ESL.───────────────────────────────────────5%
└─COMPACT─┘
The simple list (SL) tag identifies a list of items. It Table A-33. Tags Allowed Between the SL and ESL
requires a matching end tag. These tags are only Tags
allowed in information areas and help areas. Tag Name Order Use Page
LINES 1 B A-77
Simple lists can occur anywhere in text and can
(Unformatted
be nested within other lists. lines)
Care should be taken when using the unformatted XMP 1 B A-171

lines (LINES), figure (FIG), and example (XMP) (Example)
tags within simple lists, because text that does not NT 1 B A-117
fit on one line wraps to column one of the next (Note)
line. Lines and figures start at the current left P 1 B A-121
margin, and examples are indented four spaces (Paragraph)
from the current left margin. The current left
PC 1 B A-131
margin changes when nested lists are formatted. (Paragraph con-
If there is help information containing the LINES, tinuation)
FIG, or XMP tags imbedded at various locations,
LP 1 B A-107
including within lists, it may not look the same
(List part)
each time and can cause undesirable results.
OL 1 B A-118
Simple lists are formatted as hanging, indented (Ordered list)
lists, with no item identifier. SL 1 B A-152
(Simple list)
Other tags can be nested within the SL tag. UL 1 B A-164
These tags are listed in the following table. The (Unordered list)
PARML 1 B A-129
(Parameter list)
(specified by a D, P, or B, respectively), and spec- DL 1 B A-57
ifies on which page more information can be found (Definition list)
for each tag.

Optional Attribute
order number, all tags of that number can be COMPACT
mixed in any order. However, a tag with a higher The list is formatted with no blank line
order number cannot precede a tag with a lower between the items.
Required Tag
:LI.item-text
Table A-33. Tags Allowed Between the SL and ESL The text for the list item. The text is indented
Tags four spaces from the current margin.
FIG 1 B A-59
(Figure)

SL, LI Tags
Example: Simple Lists Results
This example uses two simple lists, one imbedded Some normal text...
within the other. The second simple list uses the
COMPACT attribute. First item
First item
UIM Source Second item
Second item
Some normal text...
:sl.
:li.First item
:sl compact.
:li.First item
:li.Second item
:esl.
:li.Second item
:esl.

TEXT tag
TEXT (Text Area)
55──:TEXT──VAR=dialog-variable-name──USREXIT='CALL program-reference'────────────────────5
5──┬────────────────────────────────────────────────────┬──.────────────────────────────5%
└─ROW=dialog-variable-name COL=dialog-variable-name─┘
The text area (TEXT) tag defines a text area in a If the dialog-variable-name has a BASETYPE of
panel to be formatted by the application. Only CHAR on its CLASS tag, this dialog variable
one TEXT tag can be specified in each panel. contains the data for the text area.
Menu bars and command lines are allowed,
If the dialog-variable-name has a BASETYPE of
however, no other areas can be defined in the
PTR on its CLASS tag, this dialog variable
panel.
contains a pointer to the data for the text area.
The data pointed to by this pointer is viewed
The width of this area is determined by the WIDTH
by UIM the same as for a dialog variable with
attribute of the PANEL tag which this area is
a BASETYPE of CHAR. Any exception the UIM
defined in.
receives while accessing this data will result in
The depth of this area is the depth of the panel. an escape message sent to the calling
The depth of the panel is determined by the DEPTH program.
attribute of the PANEL tag which this area is The dialog variable can be declared as any
defined in. The DEPTH value is reduced by any size. If there is not enough data to fill the text
lines used for other parts of the panel such as a area the remainder of the text area will be
menu bar lines, the panel title line, the command blank. If there is more than enough data to fill
lines, the function key line(s), and the message the text area only the data needed to fill the
line(s). See the PANEL tag for a description of text area will be used.
these dimensions.
You can use the exit program for the text
The data passed to the UIM to be displayed in this area, specified on the USREXIT attribute of this
area is described in the “Text Data” on tag, to update this dialog variable each time
page A-155 section below. the panel is displayed. The UIM uses the
value of the dialog variable to work with the
If the Help key is pressed while the cursor is in data for the text area as described in “Text
the text area extended help for the panel is dis- Data” on page A-155. The value of the dialog
played. variable depends on the BASETYPE attribute on
the CLASS tag of the dialog variable.
Required Attribute The size of the text area can vary depending
on the number of rows taken up by the func-
VAR=dialog-variable-name tion keys. This is important to remember when
The name of the dialog variable containing the coding for multiple languages or conditioning
data, or a pointer to the data, for the text area. function keys with the condition (COND) tag.
Define the dialog variable using a class defi-
nition (CLASS) tag with basetype of CHAR X USREXIT='CALL program-reference'
or PTR. The CHRID=PNLGRP attribute is not The exit program called to update the value of
allowed on the class definition for this dialog the dialog variable on the VAR attribute each
variable. time the panel is displayed.
The data in the dialog variable is viewed by This area will be considered scrollable by the
the UIM as a d by w array of characters, UIM. If the user presses a key assigned to a
where d is the depth and w is the width of the scrolling dialog command and the text area
text area. Each row of the array is displayed should be scrolled (as opposed to other
as one line of the text area. scrollable areas on the panel) the UIM will call
the user exit program. On return the UIM will

TEXT tag
redisplay the panel. For a description of the the user exited the panel the row and column
user exit program structure passed by the dialog variables will both be zero.
UIM, see the System API Reference.
COL=dialog-variable-name
A general panel exit program should be used The same as ROW except this is the column of
to diagnose if the user has scrolled too far. If the cursor.
the user has scrolled too far the general panel
exit should send an appropriate message fol-
lowed by the special message to cancel the
Cursor positioning
determined action. For a description of the The cursor position in a panel with a text area
general panel exit program structure passed depends on many things. The following is a prior-
by the UIM, see the System API Reference. If itized list for where the cursor will be positioned.
this is done the message telling the user he The first item that holds true will position the
has scrolled to far will only be seen once. If cursor.
the text area exit sends the message it may
be displayed on the screen longer than 1. If the ROW and COL attributes are used on the
desired. TEXT tag and the value of the dialog variables
are valid when the panel is displayed, the
For a description of the CALL dialog cursor is positioned at that row and column.
Commands” on page B-1. 2. If the panel has a command line the cursor is
positioned at the command line.
Optional Attributes 3. If the panel has a menu bar the cursor is posi-
tioned at the first menu bar choice.
ROW=dialog-variable-name
The row of the cursor. Define the dialog vari- 4. If the text area has tabable highlighting
able using a class definition (CLASS) tag with classes the cursor is positioned at the first
BASETYPE of BIN(31). one.
The dialog variables for the row and column 5. If none of the above position the cursor the
can be set by the application before calling cursor will be positioned at the upper left
the UIM to set the location of the cursor within corner of the panel or pop-up window.
the text area. The first character of the first
row in the text area would be row 1 and Text Data
column 1. A value of zero in either of the
dialog variables tells the UIM to use default Any character within the data can be a selection
cursor positioning. character for a highlighting class. Only output
data is allowed in a text area; no input fields are
When the UIM returns to the application, it will
allowed. The highlighting of the text applies to the
set these dialog variables to the row and
characters following the class selection character
column where the cursor was positioned in the
up to another class selection character or the end
text area when the user exited the panel. If
of the area, whichever occurs first.
the cursor was not within the text area when
The following table describes the selection characters for highlighting that are recognized by the UIM:

TEXT tag
Hexadecimal Value Decimal Value Color Display Monochrome Display

X’01’ 01 Blue Normal
X’02’ 02 Green Normal
X’03’ 03 Turquoise* Normal
X’04’ 04 Red High Intensity
X’05’ 05 Pink Normal
X’06’ 06 Yellow* High intensity
X’07’ 07 White High intensity
X’11’ 17 Blue reverse image Normal reverse image

X’12’ 18 Green reverse image Normal reverse image
X’13’ 19 Turquoise reverse image * Normal reverse image

X’14’ 20 Red reverse image High intensity reverse image
X’15’ 21 Pink reverse image Normal reverse image
X’16’ 22 Yellow reverse image * High intensity reverse image
X’17’ 23 White reverse image High intensity reverse image
X’19’ 25 Blue underscore Normal underscore
X’1A’ 26 Green underscore Normal underscore
X’1B’ 27 Turquoise underscore * Normal underscore
X’1C’ 28 Red underscore High intensity underscore
X’1D’ 29 Pink underscore Normal underscore
X’1E’ 30 Yellow underscore * High intensity underscore
X’1F’ 31 White underscore High intensity underscore

X’21’ 33 Blue tab Normal tab
X’22’ 34 Green tab Normal tab
X’23’ 35 Turquoise tab * Normal tab
X’24’ 36 Red tab High intensity tab
X’25’ 37 Pink tab Normal tab
X’26’ 38 Yellow tab * High intensity tab
X’27’ 39 White tab High intensity tab

X’31’ 49 Blue reverse image tab Normal reverse image tab
X’32’ 50 Green reverse image tab Normal reverse image tab
X’33’ 51 Turquoise reverse image tab * Normal reverse image tab
X’34’ 52 Red reverse image tab High intensity reverse image tab
X’35’ 53 Pink reverse image tab Normal reverse image tab
X’36’ 54 Yellow reverse image tab * High intensity reverse image tab
X’37’ 55 White reverse image tab High intensity reverse image tab
X’39’ 57 Blue underscore tab Normal underscore tab
X’3A’ 58 Green underscore tab Normal underscore tab
X’3B’ 59 Turquoise underscore tab * Normal underscore tab
X’3C’ 60 Red underscore tab High intensity underscore tab
X’3D’ 61 Pink underscore tab Normal underscore tab
X’3E’ 62 Yellow underscore tab * High intensity underscore tab

X’3F’ 63 White underscore tab High intensity underscore tab
* On some displays this highlighting class will display column separators RV3W081-0
and the blank character will look like a small box on the screen.
Figure A-1. Highlighting Classes Allowed in TEXT Area

TEXT tag
The UIM replaces each class selection character For pop-up windows highlighting classes never
with the appropriate display attributes for the continue on the next line. You must use another
class. Other character values in the ranges X'10' highlighting class if you want it to continue.
through X'3F', as well as X'FF', are converted
to X'1F', appearing as a reverse image box on If a panel smaller than the device is displayed
the screen. Characters X'00' (null), X'0E' without adding a pop-up window first, highlighting
(shift-out for double-byte), X'0F' (shift-in for classes continue into the blank space to the right
double-byte), and X'40' through X'FE' (normal, of the panel on the screen. To turn off these high-
displayable characters), are passed unchanged to lighting classes use other highlighting classes at
the screen. the end of each row that look like blank space.
For best appearance you should not place text in No character set and code page conversion is
the first and last column of a panel. This also done on the text area data. The application should
allows you to highlight the first word in any row provide the data in the correct character set and
easily. code page for the device.
If you are trying to create a tabable phrase of a When the UIM calls the exit program to format the
particular color do not use blanks between the text area, it passes a value which identifies the
words of the phrase. You should use the non- BIDI attribute on the panel group (PNLGRP) tag
tabable highlighting class of the same color. This and the code page number of the display device.
will give you the most effective display on all work
stations. If the NBRSHAPE and SYMSWAP attributes are used on
the CLASS tag for the text area dialog variable
When a panel is displayed with tabable high- they will be ignored.
lighting classes in the text area the cursor is not
automatically located on the first one. If you want If DBCS data is used the application is fully
this to happen you must use the ROW and COL responsible to make sure it displays properly. An
attributes of this tag to set the location of the error will occur if you attempt to display half of a
cursor. DBCS character or if one of the IGC shift charac-
ters (X'0E', X'0F') is missing.
If one or more tabable highlight classes are placed
next to each other in the data only the last one will Example: Text area
allow tabbing. The others will be ignored. The
maximum number of tabable fields is 240. It may
be less if there are other input capable or tabable
à Computer bug
ð
..............................................................................
fields on the display such as the command line or ..............................................................................
..............................................................................
..............................................................................
menu bar choices. ..............................................................................
..............................................................................
...............................\\\............................................
...............................((():..........................................
If any highlighting class is placed in the last ...............................///............................................
..............................................................................
..............................................................................
column of the last row in a full screen panel or in ..............................................................................
..............................................................................
the last column of any row in a pop-up window, it ..............................................................................
..............................................................................
will be ignored. ..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
..............................................................................
F3=Exit F12=Cancel
á ñ

TI Tag
TI (Translation List Item)
55──:TI──┬────────────────────────┬──.──┬─────────────────┬─────────────────────────────5%
└─VALUE='internal-value'─┘ └─displayed-value─┘
The translation list item (TI) tag specifies a list If the internal value is specified in string or
item in a translation list. This tag must occur hexadecimal notation, the value must be
between translation list (TL) and ETL tags. The enclosed in quotation marks in addition to
item is translated on output to the panel and on apostrophes. For example, an internal value
input to the variable pool. of *YES must be specified as VALUE='"*YES"'.
Omitting the VALUE attribute leaves the internal
Optional Attribute dialog variable value unchanged when the
user enters the displayed-value specified as
VALUE='internal-value'.
tag content after the period. A TI tag of this
The internal value for the dialog variable in the
type has no effect on the way internal values
variable pool. This internal value is not
are presented to the user for display.
subject to validity checks defined by the
validity checking (CHECK) tag for this class.
If the same internal value is specified more Optional Text
than once in the list, the first item in the list is
displayed-value
chosen for translation on output.
The value appearing on the panel or entered
If the BASETYPE of this class is BIN, as speci- by the user. The comparisons done by the
fied on the class definition (CLASS) tag, the UIM to determine what internal value to use
value may be specified in either integer or for an external value specified by the user
hexadecimal notation. If the BASETYPE speci- may be changed by the CASE and BLANKS attri-
fied on the CLASS tag is CHAR, IGC, DATE, butes of the CLASS tag. If the same external
TIME, NAME, or OBJNAME, the value may be value appears more than once in the list, the
specified in either string or hexadecimal string first item is used for translation on entry. If no
notation. Strings are implicitly padded on the value is specified, a display value of blanks is
right with blanks, but no implicit padding is used.
done for hexadecimal notation.

TL Tag
TL (Translation List)
55──:TL──┬──────────────────┬──┬──────────────────────────┬──────────────────────────────5
│ ┌─UPPER─┐ │ └─MSGID=message-identifier─┘
└─CASE=─┴─MIXED─┴──┘
5──┬────────────────────────────────────┬──.──:ETL──────────────────────────────────────5%
└─MSGF='qualified-message-file-name'─┘
The translation list (TL) tag allows the specification MSGID=message-identifier

of a translation list for a class, shielding the vari- The message identifier of the message sent if
able pool from the values actually entered on the the translation fails because the user entered
display. Values with a BASETYPE of CHAR, IGC, a value not specified in the list. If this attri-
DATE, TIME, NAME, OBJNAME, or that are bute is not specified, the UIM assumes that
numeric on the class definition (CLASS) tag can the entered value is valid as it is entered and
have a translation list. Only one translation list is passes the value on to validity checking for
allowed for each class. Translation occurs before the class.
any validity checks are performed.
MSGF='qualified-message-file-name'
Other tags can be nested within the TL and ETL The message file containing the message sent
tags. These tags are listed in the following table. for this error if the translation fails. If the
This table defines the order in which the tags must DFTMSGF attribute is not specified on the panel
appear and specifies on which page more infor- group (PNLGRP) tag, this attribute must be
mation can be found for each tag. specified if the MSGID attribute is specified on
this tag.
Table A-34. Tag Allowed Between the TL and ETL
Tags Examples: Translation List
Tag Name Order Page
TI 1 A-158
This example shows how a translation list is
(Translation list item) defined.
UIM Source
Optional Attributes
:tl msgid=MMMððð1 msgf='\LIBL/QCPFMSG'.
CASE=UPPER | MIXED :ti value=1.Blue
UPPER indicates that lowercase characters (a :ti value=1.BLUE
through z) in an input field value are con- :ti value=2.Red
verted to uppercase characters (A through Z) :ti value=2.RED
before comparison to the external value for :ti value=3.Green
:ti value=3.GREEN
each translation list item. This conversion to
:ti value=4.Turquoise
uppercase occurs after any conversion for the
:ti value=4.TURQUOISE
CASE attribute on the CLASS tag, but has no :etl.
effect on the value assigned to the dialog vari-
able or list entry if no matching translation list On entry, Blue, due to the default CASE=UPPER
item is found. It also does not change the and the uppercase version of the translation item,
external display value specified on each trans- is mapped to the value 1. On output, 1 is mapped
lation list item (TI) tag; the text on the TI tag to the value Blue, which is mixed case, because
must be specified in uppercase to get a the first matching translation list item is always
match. used. Notice that because the integer notation is
used for the value, the BASETYPE on the CLASS
MIXED indicates that an input value is com- tag that this translation list applies to must be
pared as it is entered with the external value numeric.
specified on each TI tag.

TL Tag
This is an example of a class definition and a UIM Source

translation list for a dialogue variable that allows a
:class name=objlibc
valid OS/400 library name (*LIBL, *CURLIB, or
basetype='objname 1ð'.
blanks). :tl.
:ti value='"\LIBL"'.\LIBL
:ti value='"\CURLIB"'.\CURLIB
:ti value='" "'.
:etl.
:eclass.

TOPINST Tag
TOPINST (Top Instruction)
55──:TOPINST──┬───────────────────────────┬──.──┬──────────────────┬────────────────────5%
└─INST=dialog-variable-name─┘ └─instruction-text─┘
The top instruction (TOPINST) tag of an area minus two. If this attribute is used, no
specifies the top instruction lines. This tag is valid instruction-text can be specified for this tag.
for all areas, but is allowed only for display panels.
Dialog variables must be defined with a
It appears immediately after the introducing tag for
BASETYPE of CHAR, IGC, or BIN on the class
the area.
Multiple top instruction tags may be used to The error state of the dialog variable is not
present multiple lines of instructions if the used for determining the highlighting of the
TOPINST tag contains instruction-text. If multiple text.
TOPINST tags are coded, no blank lines appear
Special formatting for IGC. The abbrevi-
between the text on different tags. Only one top
instruction tag is allowed per area if an INST attri-
to represent double-byte character set (DBCS)
bute variable is used for this tag.
functions. When a dialog variable with a
For menus, a blank line is always left between the
body and the instruction lines area. For more
variable value begins with a shift-out character
information about how instruction lines are for-
(X'0E'), the UIM shifts the value 1 byte to the
matted with respect to the body of certain areas,
left to preserve vertical alignment with other
see the BODYSEP attribute in “DATA (Data Presen-
lines.
tation Area)” on page A-31.
If no TOPINST tag is specified for an area, no text Optional Text

is used for the instruction line and the line is not
allocated in the area.
instruction-text
The text appearing as top instructions for the
area. The text is an implied paragraph.
Optional Attribute When the display is formatted, any text that
INST=dialog-variable-name does not fit onto one display line is formatted
The name of a dialog variable containing the onto additional lines as necessary and
top instruction text displayed. The dialog vari- indented two positions. The text can be a
able must be defined with a width less than or maximum of 255 characters, and can only
equal to the width specified on the panel tag contain the reverse text (RT) tag. The instruc-
tion text is required unless the INST attribute is
specified on this tag.

TT Tag
TT (Truth Table)
55──:TT──NAME=truth-table-name──CONDS='condition-name-list'──.──:ETT.───────────────────5%
The truth table (TT) tag begins the definition of a Table A-35. Tag Allowed Between the TT and ETT
truth table used by the compiler when processing Tags
panel definitions. The TT tag must occur in the Tag Name Order Page
prolog section of the panel group after the condi-
TTROW 1 A-163
tion definition (COND) tags and before any menu (Truth table row)
bar (MBAR) tags. You should use a truth table to
assert to the UIM which conditions are mutually
exclusive. Required Attributes
During compilation of a panel group, a panel is NAME='truth-table-name'
formatted once for each row of a truth table. The name of the truth table. For more infor-
Using the truth value for each condition, the com- mation on the rules for naming, see “Name
piler checks if the panel definition is valid. If a Syntax” on page A-4. This name is referred
panel element is conditioned using the COND attri- to by all panels which use this truth table for
bute on this tag, and if that condition is not men- compile-time checking. This name must be
tioned in the truth table, it is assumed to have a unique within the panel group.
true value by the compiler. CONDS='condition-name-list'.
A list of condition names separated by blanks.
The name of a truth table must be specified on
Each condition in the list must have been pre-
the TT attribute of the display panel (PANEL), print
viously defined with the COND tag. The rows
panel (PRTPNL), or print head panel (PRTHEAD)
of the truth table are defined with the truth
tag for the compiler to use the truth table for panel
table row (TTROW) tag. Each item in the
verification.
VALUES attribute of the TTROW tag corre-
sponds positionally with the condition specified
After the compile, if the truth table is wrong and
in this attribute. A maximum of 50 condition
the conditioning causes more panel elements to
names can be specified.
be active in an area than can be displayed, only
the elements that fit are displayed, and no excep-
tion is reported. Example: Truth Table
Other tags can be nested within the TT tag. If conditions A, B, and C are known to be mutually
These tags are listed in the following table. This exclusive on panel X, this example would illustrate
table defines the order in which the tags must how to assert this to the compiler.
mation can be found for each tag. UIM Source
:tt name=tt1 conds='A B C'.
:ttrow values='1 ð ð'.
:ttrow values='ð 1 ð'.
:ttrow values='ð ð 1'.
:ett.

TTROW Tag
TTROW (Truth Table Row)
55──:TTROW──VALUES='condition-value-list'──.────────────────────────────────────────────5%
The truth table row (TTROW) tag defines a row in Required Attribute
a truth table used by the compiler when pro-
cessing panel definitions. The TTROW tag must VALUES='condition-value-list'.
occur between the truth table (TT) and ETT tags The value of each condition used by the com-
in the prolog section of the panel group. piler to check the panel definition. Each item
in the VALUES attribute of the TTROW tag cor-
During compilation of a panel group, a panel is responds positionally with the condition speci-
formatted once for each row of a truth table, and fied in this attribute. The following values can
the truth value for each condition is used to check be used for the condition:
if the panel definition is valid. A truth table can
0 The condition is false.
describe which of the conditions that control the
1 The condition is true
formatting of a panel are mutually exclusive. If a
* No truth value is specified. The compiler
condition is used within the panel definition and is
assumes the value is true for a worst
not mentioned in the truth table, it is assumed to
case.
be true for the purposes of compile time checking;
this is the same as specifying an asterisk (*) in the The items in the list of condition values are
VALUES attribute on this tag. separated by blanks. The number of items in
the list must equal the number of items in the
CONDS attribute of the TT tag.

UL, LI Tags
UL (Unordered List)
┌──
───────────────┐
55──:UL ─┬─────────┬───.───6─:LI.item-text─┴──:EUL.──────────────────────────────────────5%
└─COMPACT─┘
The unordered list (UL) tag identifies an unordered mixed in any order. However, a tag with a higher
list of items. The UL tag requires a matching end order number cannot precede a tag with a lower
tag. These tags are only allowed in information order number. For example, a tag with an order
areas and help areas. number of three cannot precede a tag with an
Unordered lists can occur anywhere in text and
can be nested within other lists. Table A-36. Tags Allowed Between the UL and EUL
Tags
Note: Care should be taken when using the
unformatted lines (LINES), figure (FIG), and Tag Name Order Use Page
example (XMP) tags within unordered lists, FIG 1 B A-59
because text that does not fit on one line wraps to (Figure)
column one of the next line. Lines and figures LINES 1 B A-77
start at the current left margin and examples are (Unformatted
indented four spaces from the current left margin. lines)
The current left margin changes when nested lists XMP 1 B A-171
are formatted. If there is help information con- (Example)
taining the LINES, FIG, or XMP tag imbedded at
NT 1 B A-117
various locations, including within lists, it may not
(Note)
look the same each time and can cause undesir-
able results. P 1 B A-121
(Paragraph)
Unordered lists are formatted as hanging, PC 1 B A-131
indented lists, with the item identifier at the current (Paragraph con-
left margin. There are three levels of item identi- tinuation)
fiers for nested, unordered lists: LP 1 B A-107
(List part)
Bullets (lowercase letter o)
Hyphens (-) OL 1 B A-118
Dashes (--). (Ordered list)
SL 1 B A-152
These levels are repeated for more than three (Simple list)
levels of nested, unordered lists.
UL 1 B A-164
(Unordered list)
Other tags can be nested within the UL tag.
These tags are listed in the following table. The PARML 1 B A-129
table defines the order in which the tags must (Parameter list)
appear, indicates which tags can be used in DL 1 B A-57
display panels only, print panels only, or both (Definition list)
for each tag. Optional Attribute
COMPACT
When more than one tag is listed with the same The list is formatted without a blank line
order number, all tags of that number can be between the items.

UL, LI Tags
Required Tag Some normal text...

:ul.
:LI.item-text :li.First item (bullet)
The text for the list item. This text is pre- :ul compact.
ceded by the item identifier; the text is :li.First item (hyphen)
indented four spaces from the current margin. :li.Second item (hyphen)
:eul.
:li.Second item (bullet)
Example: Unordered Lists :eul.
This example uses two unordered lists, one

Results
imbedded within the other. The second unordered
list uses the COMPACT attribute.
Some normal text...
UIM Source First item (bullet)
– First item (hyphen)
– Second item (hyphen)
Second item (bullet)

VAR Tag
VAR (Variable Definition)
55──:VAR──NAME=variable-name──┬──────────────────┬───────────────────────────────────────5
└─CLASS=class-name─┘
5──┬───────────────────────────────────┬──.─────────────────────────────────────────────5%
└─ERRVAR=error-status-variable-name─┘
The variable definition (VAR) tag declares a dialog tag. This name must also be unique within
variable in the panel group. The VAR tag does the panel group.
not allow nested tags and must be placed after
This dialog variable contains the error status
the last class definition (CLASS) tag and before
of the variable defined by this tag. This attri-
the first variable record definition (VARRCD) tag.
bute is used with the Put Dialog Variable
(QUIPUTV) API and the Get Dialog Variable
A value for each dialog variable exists in the vari-
(QUIGETV) API.
able pool for an application opened using this
panel group. The dialog variables communicate During the QUIPUTV API, the current value of
values to and from panels when the panels are the error variable determines the error status.
presented to the user. Dialog variable values are A value of 1 (X'F1') indicates that the dialog
set and retrieved using the UIM application pro- variable specified on the NAME attribute on this
gramming interfaces (APIs). tag is in error. A value other than 1 (X'F1')
indicates that the dialog variable is not in
The VAR tag defines all Z-variables, as well as error. If the error status variable is updated
other dialog variables used by an application. during the same QUIPUTV API request as its
Only variables defined by a VAR tag in the panel associated dialog variable, the new value of
group source are available in an open application. the error status variable is used.
During the QUIGETV API for either the NAME
Required Attribute dialog variable or the ERRVAR dialog vari-
NAME=variable-name able, the value of the error status variable is
The name of a dialog variable. This name set to 1 (X'F1') if the dialog variable specified
must be unique within the panel group. For on the NAME attribute of this tag is in error.
more information on the rules for naming, see Otherwise, the value of the error status vari-
“Name Syntax” on page A-4. able is set to zero (X'F0').
Note: Simply updating the ERRVAR dialog
Optional Attributes variable does not set the error state of the
dialog variable specified in the VAR attribute of
CLASS=class-name this tag. The VAR dialog variable must be
The name of the class to which this variable updated using the QUIPUTV API to change its
belongs. The class must have been previ- error state.
ously defined in the panel group.
The error dialog variable cannot be referred to
The class definition for all Z-variables is deter- any place in the panel group source where
mined by the UIM, so this attribute cannot be dialog variables can normally be specified.
specified on the VAR tag for a Z-variable. A
class must be specified for other variables
declared in the panel group.
Dialog Variables Defined by UIM
ERRVAR=error-status-variable-name The UIM defines a set of dialog variables that can
The name of a dialog variable, automatically be automatically available in the variable pool for
defined by the UIM with a BASETYPE of every open application. The variables must be
CHAR 1 on the CLASS tag. The error status defined using the variable definition (VAR) tag in
variable must not be defined by another VAR order to be available in the variable pool. These
variables can be referenced by user programs

VAR Tag
(see the QUIGETV API) and in panel definitions, This Z-variable can be changed by
and some can be modified by user programs (see the calling (application) program using
the QUIPUTV API) to control UIM processing the Put Dialog Variable API service.
functions. Dialog variables are not allowed for Changing this dialog variable results
input fields on any panel. in changing the job's exit flag. For
more information on the job's exit
All dialog variables defined by the UIM have flag, see “Folding Up Multiple Panels
names that begin with the letter Z. If you define a When EXIT Is Requested” on
dialog variable for your application with the same page 17-24.
name as a UIM dialog variable, you receive a
ZJOB Simple name of the current job (the
warning message. The message states that you
first qualifier of the job name).
do not have access to the UIM dialog variable with
the same name. However, you are allowed to use ZJOBNBR Job number of the current job (the
the dialog variable that you defined. The following last qualifier of the job name).
is a description of all UIM-defined dialog variables:
ZLMTCPB Indicates the limits to which the user
ZCANCEL Indicates whether the CANCEL func- controls the initial program, initial
tion is requested and is set as menu, current library, and Attention
follows: key handling program values and is
set as follows:
0 The CANCEL function was not
requested. *NO
1 The CANCEL function is *PARTIAL
requested. *YES
This Z-variable can be changed by ZMENU Name of the menu object currently
the calling (application) program using displayed by the UIM. This dialog
the QUIPUTV API. Changing this variable can be used only in defi-
dialog variable results in changing the nitions of *MENU objects.
job's cancel flag. For more informa-
ZMNULIB The name of the library that contains
tion on the cancel flag, see “Folding
the menu object currently displayed
Up a List Panel” on page 17-26.
by the UIM. This dialog variable can
ZDBCS Indicates whether the job is currently be used only in definitions of *MENU
in DBCS mode, and is set as follows: objects.
0 The job is not in DBCS mode. ZSYSNAM Current system name retrieved from
1 The job is in DBCS mode. the SYSNAM network attribute.
ZDSPSIZ Indicates the maximum size of the ZUSER User profile name for the current job
display that the device is capable of (which is also the middle qualifier of
displaying and is set as follows: the job name).
*DS3 The largest size panel the Z36ENV Indicates whether the job is currently
device can display is 24 x 80. running in the System/36 environment
*DS4 The largest size panel the and is set as follows:
device can display is 27 x 132.
0 The job is not running in the
This device can also display
System/36 environment.
panels of size 24 x 80.
1 The job is running in the
ZEXIT Indicates whether the EXIT function System/36 environment.
was requested and is set as follows:
For a description of the characteristics (including
0 The EXIT function is not
external display form) for the base type of each
requested.
Z-variable, see “CLASS (Class Definition)” on
1 The EXIT function is requested.
page A-14.

VAR Tag
Table A-37. Attributes of UIM-Defined Variables (Z-Variables)

Program
Base Modifi-
Name Type Length able Description
ZCANCEL CHAR 1 Yes Indicates whether the CANCEL function is required
ZDBCS CHAR 1 No Indicates whether the job is in DBCS mode
ZDSPSIZ CHAR 4 No Indicates the maximum size of display
ZEXIT CHAR 1 Yes Indicates whether the EXIT function is requested
ZJOB OBJNAME 10 No Job name of the current job (first qualifier)
ZJOBNBR CHAR 6 No Job number of the current job
ZLMTCPB CHAR 10 No Limits the capabilities the user has
ZMENU OBJNAME 10 No Name of the menu object
ZMNULIB OBJNAME 10 No Name of the library containing the menu object
ZSYSNAM CHAR 8 No Current system name
ZUSER OBJNAME 10 No User profile name
Z36ENV CHAR 1 No Indicates if running in the System/36 environment

VARRCD Tag
VARRCD (Variable Record Definition)
55──:VARRCD──NAME=variable-record-name──VARS='variable-list'─────────────────────────────5
5──┬───────────────────────┬──┬───────────────────────┬──.──────────────────────────────5%
└─NOPUT='variable-list'─┘ └─NOGET='variable-list'─┘
The variable record definition (VARRCD) tag does UIM makes no boundary alignment adjust-
not allow nested tags, and must be placed after ments when calculating the offsets to vari-
the last variable definition (VAR) tag and before ables within the buffer.
the first list definition (LISTDEF) tag.
If any read-only Z-variables are listed in the
VARS attribute of this tag, they must also
When data is passed between a calling program
appear in the NOPUT attribute of this tag.
and the variable pool, a variable buffer is used.
The variable buffer contains values for one or
more dialog variables. A VARRCD tag defines Optional Attributes
which dialog variables are in the variable buffer as
NOPUT='variable-list'
well as the sequence the variables appear in the
A list of up to 256 variables which should not
variable buffer.
be processed when the QUIPUTV API is
requested. All variables in this variable list
The VARRCD tag must be used to define a vari-
must appear in the variable list specified on
able record definition for use with the Get Dialog
the VARS attribute of this tag. The variable
Variable (QUIGETV) API and the Put Dialog Vari-
names in the list are separated by blanks.
able (QUIPUTV) API requests. Only variables
defined by a VAR tag in the panel group source Using this attribute, you can specify that only
may appear in the variable record definition. a subset of the variables in the variable buffer
should be copied to the variable pool during
Required Attributes the QUIPUTV API.
If this attribute is not specified, all variables
NAME=variable-record-name
specified on the VARS attribute of this tag are
The name of a variable record definition. This
copied from the variable buffer to the variable
name must be unique within the panel group.
pool during the QUIPUTV API.
see “Name Syntax” on page A-4. NOGET='variable-list'
A list of up to 256 variables which should not
VARS='variable-list'
be processed when the QUIGETV API is
A list of up to 256 dialog variables which
requested. All variables in this variable list
make up the variable record. All dialog vari-
must appear in the variable list specified on
ables in this variable list must be previously
the VARS attribute of this tag. The variable
defined using the VAR tag. The dialog vari-
names in the list are separated by blanks.
able names in the list are separated by one or
more blanks. Using this attribute, you can specify that only
a subset of the variables in the variable buffer
The order in which the variable names appear
should be copied from the variable pool during
in the variable list is the order the variable
the QUIGETV API.
values must appear in the variable buffer of
the calling program when the QUIPUTV and If this attribute is not specified, all variables
QUIGETV APIs are called. specified on the VARS attribute of this tag are
copied from the variable pool to the variable
The variables must appear contiguously in the
buffer during the QUIGETV API.
variable buffer for the calling program. The

XH1 through XH4 Tags
XH1 through XH4 (Extended Help Headings)
55───┬─:XH1.─┬─extended-help-heading-text───────────────────────────────────────────────5%
├─:XH2.─┤
├─:XH3.─┤
└─:XH4.─┘
The extended help heading (XH1-XH4) tag identi- XH1 Centers, underscores and highlights text
fies the heading used over contextual help when it (HP3). This tag causes a page eject when
is displayed as part of an extended panel help, it appears in a printed help module.
including help for index search topics. This tag
XH2 Left-justifies, underscores, and highlights
must appear within a help module (HELP) tag and
text (HP3).
EHELP boundary and is not allowed on the infor-
mation (INFO) tag. The text associated with this XH3 Left-justifies and highlights text (HP2).
tag is used as the heading text. XH4 Left-justifies and underscores text (HP1).
This tag allows headings to appear with help infor-
mation, based on whether the text is displayed for Example: Sample Headings
extended panel help or for contextual help. The
text from XHn tags always appears in extended This example shows how extended help headings
panel help. The text also appears in contextual are highlighted and justified.
help if any tag containing help information pre-
cedes the XHn tag, or the contextual help is dis- UIM Source
played in a full screen and no help panel title is :XH1.Main Subject
specified on the HELP tag. :p.Here's a paragraph.
:XH2.Topic
In all cases of contextual help, with the exception :p.Another paragraph.
of the two previously mentioned, the text from the :XH3.Subtopic
XHn tag does not appear when the XHn tag is the :p.Still another paragraph.
first tag used for contextual help. :XH4.A Four Heading
:p.Still another paragraph.
Required Text
Results:
extended-help-heading-text
The text associated with this tag is used as a Main Subject
heading when the help item is used in
extended panel help. The text must be on the Here's a paragraph.
same or next line as the period ending the
tag. Topic
Another paragraph.
Formatting Rules
Subtopic
Headings have one blank line formatted before
and after them. The heading tag generates a Still another paragraph.
blank line before the heading, and the tag fol-
lowing the heading generates the space after the A Four Heading
heading.
Specific formatting rules follow:

XMP Tag
XMP (Example)
55──:XMP.──:EXMP.───────────────────────────────────────────────────────────────────────5%
The example (XMP) tag identifies an example of are indented by 4 bytes. Therefore, the formatting
computer input or output. The XMP tag requires a width initially is 10 bytes less than the width speci-
matching end tag. These tags are only allowed in fied on the help module. When the XMP tag
information areas and help areas. appears in an information area, the formatting
width initially is 6 bytes less than the width speci-
Examples can occur anywhere in text, except in fied on the panel tag.
other examples. The body of an example is com-
posed of the text between the XMP tag and the
EXMP tags.
Example: Formatting an Example
This example illustrates how to use an example.
The normal formatting of text is suspended within
an example; that is, the lines are not concat-
enated. UIM Source
Some normal text...
Note: Care should be taken when using exam-
:xmp.
ples within lists, because example text that does
This is an example
not fit on a line wraps to column one of the next right here
line. The current left margin changes when :exmp.
nested lists are formatted. If there is help informa-
tion containing examples imbedded at various
locations, including within lists, it may not look the
Results:
same each time and can cause undesirable
Some normal text...
results. An example is indented 4 spaces from
the current margin. Help modules displayed in This is an example
full-screen format or in an extended help window right here

XMP Tag

Dialog Commands
Appendix B. UIM Dialog Commands

Dialog commands are special functions, recog- bypassed, while others cause the calling of the
nized only by the UIM, that equate actions entered general exit to be bypassed.
by a user with screen management functions.
Dialog commands differ from CL commands in Dialog commands can be assigned to the fol-
that they cannot be entered on a command line lowing:
nor are they valid outside the scope of the UIM. Menu items
Function keys
Exactly what function the UIM performs for each
Options on action lists
dialog command depends largely on the type of
Hypertext links
screen being presented and other attributes
Pull-down field choices
defined by the function key, key list item (KEYI),
ENTER and SELECT attributes of the PANEL tag
menu item (MENUI), list action (LISTACT), or pull-
down field choice (PDFLDC) language tags. For Not all dialog commands are allowed in all of
more information on the language tags, see these situations. For example, the dialog com-
Appendix A, “UIM Panel Group Definition mands PAGEUP and PAGEDOWN cannot be
Language” on page A-1. assigned to options of an action list because they
apply to the entire screen, and not to an individual
Some dialog commands are defined in terms of list entry.
the content of the current command line, the posi-
tion of the cursor, and the type of screen. Dialog For a summary of the valid uses of the dialog
commands also affect messages specified by the commands, see Table B-1 on page B-2. For a
application, by the condition evaluation, and by summary of the effect of the different dialog com-
calling the general exit. For example, some dialog mands, see Table B-2 on page B-3. Later in this
commands cause condition evaluation to be appendix, there is a detailed description of each
dialog command.
 Copyright IBM Corp. 1997 B-1

Dialog Commands
Table B-1. Summary of the Valid Uses of Dialog Commands

Valid Uses
ENTER SELECT
Dialog Pull-down on on
Command Function Menu Menu List PANEL PANEL Hypertext
Name Key Choices Item Action Tag Tag Link Action
ACTIONS X X3
CALL X X X X X
CANCEL X X
CHGVIEW X X2
CMD X X X X X
CMDLINE X X2
DSPHELP X2 X
ENTER X
EXIT X X2 X
EXTHELP X2
HELP X
HELPHELP X2
HELPIDX X2
HOME X
KEYSHELP X2
MENU X X2 X
MOREKEYS X
MOVETOP X
MSG X X
PAGEDOWN X
PAGEUP X
PRINT X
PROMPT1 X
PULLDOWN X3
RETRIEVE X X2
RETURN X X X X X
Notes:
1 PROMPT becomes CALL or RETURN when processing a cursor-sensitive prompt defined by the PROMPT attri-
bute of a DATAI, DATAIX, or LISTCOL language tag.
2 Valid only when ACTFOR=PANEL is specified on the PDFLDC tag.
3 Valid only when MBAR attribute is specified on the PANEL tag.
B-2 Application Display Programming V4R1

Dialog Commands
Table B-2. Summary of the Effects of Dialog Commands

Effects
Stop Dis-
Dialog playing Call
Command User Mes- Evaluate General
Name VARUPD on KEYI or PDFLDC Tag1 sages2 Conditions Exit
ACTIONS No No No No
CALL Yes or No Yes Yes Yes
CANCEL Yes or No Yes N/A Yes
CHGVIEW Yes Yes Yes Yes
CMD Yes or No Yes Yes Yes
CMDLINE No No No No
DSPHELP No No No No
ENTER Yes N/A3 N/A3 N/A3
EXIT Yes or No Yes N/A Yes
EXTHELP No No No No
HELP No No No No
HELPHELP No No No No
HELPIDX No No No No
HOME Yes Yes Yes Yes
KEYSHELP No No No No
MENU Yes Yes Yes Yes
MOREKEYS No No No No
MOVETOP Yes No No No
MSG N/A Yes Yes Yes
PAGEDOWN Yes6 No No Yes6
PAGEUP Yes6 No No Yes6
PRINT No No No No
PROMPT5 Yes or No Yes Yes Yes
PULLDOWN No No No No
RETRIEVE No No No No
RETURN Yes or No Yes N/A Yes
Default4 N/A Yes Yes Yes
Notes:
1 VARUPD attribute applies only when the action is assigned to a function key or pull-down choice. When ACTFOR=LIST is
specified on the PDFLDC tag, VARUPD is YES.
2 The UIM stops displaying messages generated by an application (user messages) when another function is about to start.
HELP can become a function if the help is for a command and the user directly starts the prompt and processing of the
command from the help screen.
3 These ENTER values are not applicable (N/A) because ENTER always equates with another function by the time these
actions are performed.
4 The UIM displays the panel again for the default ENTER or SELECT action.
5 PROMPT becomes CALL or RETURN when processing a cursor-sensitive prompt defined by the PROMPT attribute of a DATAI,
DATAIX, or LISTCOL language tag.
6 When PAGEUP and PAGEDOWN apply to the message area, an information area, or a menu area, these values are not
applicable.
Appendix B. UIM Dialog Commands B-3

CALL Command
The VARUPD Attribute values entered by the user. It also defines

whether the function associated with the key
One of the main qualifiers of a function is the should be processed if errors are detected while
VARUPD attribute of the KEYI (key list item) and validity checking the values of input fields on the
PDFLDC (pull-down field choice) language tag. display. Most dialog commands assume a partic-
This attribute defines whether or not dialog vari- ular value for VARUPD that cannot be overridden by
ables and list entries should be updated with the panel definition. The following is a summary
of the effect of VARUPD:
Effect of VARUPD Attribute

Type of Action VARUPD=YES VARUPD=NO
Returning control to the appli- All validity checking is per- No validity checking is performed and no
cation that called the formed, and dialog variables updates are made to the dialog variables and
QUIDSPP API. and list entries are updated list entries. Changes made to the input field
when correct. When one or by the user since the last operation are lost.
more variables fail the validity The values entered by the user can some-
checking, the panel is dis- times be recovered by calling QUIDSPP and
played again with error mes- specifying yes on the redisplay parameter.
sages. For more information, see the System API
Reference.
An action performed under All validity checking is per- No validity checking is performed and no
the control of the UIM without formed, and dialog variables updates are made to the dialog variables and
returning to the application and list entries are updated list entries. Contents of the input fields are
when correct. When one or saved by the UIM and are used when dis-
more variables fail the validity playing the panel again, providing updates
checking, the panel is dis- have not been made that make the saved
played again with error mes- values obsolete. For example, changing a
sages. dialog variable that was displayed on the
saved panel causes the saved value to be dis-
carded and the new value shown when the
panel is displayed again.
ACTIONS (Menu Bar Cursor then presses the ACTIONS function key, the UIM
determines the best position for the cursor.
Action)
Messages: No messages are issued by the UIM
55──ACTIONS──────────────────────────5% during processing.
CALL (Call Program)

Alternates the cursor position between the panel
and the menu bar. The Common User Access
(CUA) guidelines recommend this function be 55──CALL──dialog-variable-name───────5%
assigned to F10.
When the ACTIONS function key is pressed, the Calls an application program and allows applica-
UIM saves the information where the cursor was tions to link programs and screens together.
located and moves the cursor to the first choice
on the menu bar. If the ACTIONS function key is The call function calls by address, by name, or by
pressed again, the cursor returns to its previous an extended program model (EPM) call.
location before it was moved to the menu bar. If
the user moves the cursor to the menu bar area For best performance, use call by address. If call
using the cursor movement keys (arrow keys) and by address is not feasible, use the call by name or
an EPM call with a library qualified program name
(do not use *LIBL).

CALL Command
For a description of the interface between the UIM program and library names should be left
and the program being called, see the section justified and put in uppercase unless a
called "User Interface Management EXIT quoted object name is used.
Program" in the System API Reference. The
Call by extended program model (EPM)
CALL dialog command can be used with the fol-
This type of call allows calling an entry
lowing:
point in an EPM language program. The
Menu item action UIM uses the QPXXCALL interface to
Function key action make the call. Define the specified dialog
Action list option variable with BASETYPE='CHAR 13ð'. When
Action list exit the call function is requested, the dialog
General panel exit variable must contain the following:
Default enter action
Characters Contents
Application format exit
Contextual prompt exit 1-20 The name of the EPM
Pull-down choice action program object and the name
of the library that the object
The CALL dialog command cannot be used on resides in
menu objects created using the Create Menu
21-120 The name of the external
(CRTMNU) command, but can be used within a
entry point to be called
panel group object created using the Create Panel
Group (CRTPNLGRP) command. If calling a 121-130 The name of the environment
program is the desired result of a menu option in to which the entry point
an external menu, use the CMD dialog command belongs
to submit the CALL CL command. The user must Because UIM is simply passing this infor-
have the proper authority to the CALL CL mation to the QPXXCALL language inter-
command and the program being called. face program, ensure that the contents of
the dialog variable adhere to the require-
Required Parameter ments defined by QPXXCALL. When UIM
calls the QPXXCALL program, the EPM
dialog-variable-name
environment is implicitly started and
Specifies a dialog variable containing the call
remains active until explicitly deleted.
information as described below for each of the
three types of call. Note: There is a high performance over-
head for calling an EPM program. If pos-
Call by address sible, call by address or call by name
This type of call is used within OS/400 instead. The support for calling an EPM
system programs to allow calls of other program is provided for cases where, due
system modules. Define the specified to application design, an EPM program is
dialog variable with BASETYPE='PTR'. used as the target of the CALL dialog
When the call function is requested, the command.
dialog variable must contain a system
pointer to the program. Ensure the proper
VARUPD Value: The CALL dialog command
authority is contained in the pointer.
does not have a predefined VARUPD value. When
Call by name CALL is assigned to a function key, the VARUPD
Allows calling an application program using value of the function key dictates whether or not to
a qualified name of a program object. perform validity checking and then updates the
Define the specified dialog variable with dialog variables.
BASETYPE='CHAR 2ð'. When the call func-
tion is requested, the first 10 characters of Messages: The following errors may be encoun-
the dialog variable must contain the name tered during processing:
of the program object. The second 10
Program not found.
characters must contain the name of the
Not authorized to specified program.
library where the program resides. The

CHGVIEW Command
Number of parameters for specified program CHGVIEW (Change View)

is not valid.
Program saved with STG(*FREE).
Any exception signalled by the QPXXCALL 55──CHGVIEW──────────────────────────5%
language interface program.
The UIM does not stop processing if these errors Changes the displayed view of a list and can only
occurred on a call for the general panel exit, on a be assigned to a function key or a pull-down field
call for the list action exit, and on application for- choice action.
matted area calls.
If there are several columns of information that a
For all other types of calls, the UIM ends the user needs to see, and all the columns do not fit
action it was performing. In most cases, this on the display, you can change the view so the
involves displaying the panel again with an error user sees one set of columns and then another
message indicating that the program call was not set of columns. This continues until all the
successful. columns of information are viewed.
You can specify several different ways to present

CANCEL
a list area on the LISTVIEW language tag and
which columns belong to each view. List views
┌─NOSET─┐ are numbered sequentially starting with 0. For
55──CANCEL──┼───────┼────────────────5% example, if a list areas has five presentation
└─SET───┘ views, the views are numbered from 0 to 4. The
first LISTVIEW tag in the panel source for the list
area defines view 0, the second LISTVIEW tag in
Backs up one screen and is used with a menu the panel source for the list area defines view 1,
item action or a function key action. and so on for all LISTVIEW tags in the list area.
If the current screen was called by the QUIDSPP With the CHGVIEW dialog command, you can
API, the function parameter contains an indication switch views. The function operates in a circular
that CANCEL was requested. fashion. For example, if the current view is 3,
CHGVIEW presents view 4 (if there is a view 4),
If the current screen is a menu called from the
or back to view 0 if there is not a view 4. Applica-
previous screen via the menu fast-path function
tions can specifically select a view by changing
(for example, entering GO on the command line),
the dialog variable coded on the VIEW attribute of
the UIM displays the previous screen.
the LIST tag. The UIM also modifies this dialog
variable whenever the CHGVIEW dialog command
Optional Parameter is performed.
NOSET|SET
Which list the request applies to depends on the
Indicates whether the cancel flag is set.
cursor position. The rules are very similar to
NOSET means that the cancel flag is not set;
those for the PAGEDOWN and PAGEUP dialog
this is the default value. SET means that the
commands.
cancel flag is set. For more information on
the cancel flag, see “Folding Up a List Panel” If the cursor is in a list area defined as having
on page 17-26. multiple views, the request applies to that
area.
VARUPD Value: CANCEL does not have a pre-
If the cursor is not in a list area defined as
defined VARUPD value. When CANCEL is assigned
having multiple views, the request applies to
to a function key, the VARUPD value of the function
the first list area on the screen that does have
key determines whether or not to perform validity
multiple views.
checking and then updates the dialog variables.
Parameters: None
Messages: No messages are issued during pro-
cessing.

DSPHELP Command
VARUPD Value: The CHGVIEW dialog dialog variables. Because substituting commands
command always operates with VARUPD=YES depends on the values of dialog variables, care
and the following occurs: should be taken when using VARUPD=NO.
Validity checking is always performed.
Valid values are processed and the dialog var-
cessing unless there are errors from a validity
iables are updated.
check.
Any failures from validity checking prevent
changing the view and the screen is displayed Hint: Because these commands are not logged
again with the appropriate error messages. to the job log, it is sometimes difficult to discover
and correct command syntax errors. One way to
see the command after all dialog variables have
cessing unless there are errors from a validity
been substituted is to make the command the
check.
value of the message on a SNDMSG command
as follows:
CMD (System Command)
SNDMSG MSG (command here) TOUSR (\REQUESTER)
55──CMD──command-text────────────────5%
CMDLINE (Command Line)
Submits a CL or OCL command to the system

55──CMDLINE──────────────────────────5%
command.
Parameter Displays a pop-up window containing a command

command-text line on the bottom of the display.
All text following the CMD dialog command is
treated as a command and is submitted to the Parameters: None
system for processing. Whether the
command is native or System/36 environment
cessing.
is determined by the system, not by the UIM.
The command string may contain the names
of dialog variables to be substituted into the
DSPHELP (Display Help)
command string before the UIM submits the
command to the system. Each dialog variable 55──DSPHELP──help-module-name──────────────5
name must be preceded by an ampersand (&) 5──┬──────────────────────────────────┬───5%
and followed by a period (.). Although the └─panel-group──┬─────────────────┬─┘
ending period is not required, its use is recom- └─product-library─┘
mended to avoid ambiguity.
Before submitting the command, the UIM per- Displays a specified UIM help module.
forms substitution for dialog variables. Each
dialog variable specified as part of the Required Parameter
command string is replaced by its displayable
value. This value is always calculated from help-module-name
the current value of the dialog variable. Specifies the name of the help module to be
displayed.
VARUPD Value: The CMD dialog command
does not have a predefined VARUPD value. When Optional Parameter
CMD is assigned to a function key or pull-down
field choice, the VARUPD attribute on the KEYI or qualified-panel-group-name
PDFLDC language tag dictates whether or not to Specifies the name of the panel group con-
perform validity checking and then updates the taining the help module. If it is not specified,
then 1) the help module must be from the

EXIT Command
same panel group that contains the DSPHELP acteristics than other dialog commands. These
dialog command, or 2) the help module must dialog commands are more like action qualifiers;
be imported from another panel group by things used to determine or modify a more con-
using an IMPORT tag. crete action like a system command string.
For example, an action list panel describes

product-library several actions that are performed, based on the
Specifies the name of a library which
contents of various fields. The ENTER and
becomes the product library when the help
PROMPT dialog commands, and to a lesser
module is displayed. This parameter is only
extent HELP dialog commands, are initially
used when the DSPHELP dialog command is
requested, but serve only to describe how the rest
used for a hypertext link action.
of the panel is interpreted. They are not sufficient
by themselves to describe what should be done.
cessing.
Some important aspects to remember when
reading descriptions of these dialog commands
ENTER are:
A menu with a command line can contain a
55──ENTER────────────────────────────5% selection from a menu item or a command. If
the first nonblank character string is unquoted
and contains only numeric values, it is inter-
Allows processing of an action and is only allowed preted as a menu item. Otherwise, it is
on the Enter key. assumed to be a command.
An action list with a command line can contain
For more information, see “Considerations for
parameter strings or commands. If any entry
Using the ENTER, HELP, and PROMPT Dialog
on an action list is selected, any string in the
Commands.”
command line is treated as a parameter list.
Otherwise, it is treated as a command.
Parameters: None
VARUPD Value: The ENTER dialog command EXIT (Exit Display)

always operates with VARUPD=YES and the fol-
lowing occurs:
┌─NOSET─┐
Validity checking is always performed. 55──EXIT──┼───────┼──────────────────5%
Valid values are processed and the dialog var- └─SET───┘
iables are updated.
Any failures from validity checking stop the
operation. The display is shown again with Allows the user to back out of groups of displays.
the appropriate error messages.
If the current display was displayed using
Messages: Any messages resulting from submit- QUIDSPP API, the UIM sets the function
ting or canceling the commands are displayed on requested parameter indicating that the EXIT
the message line. Additional messages can be dialog command was requested. It is up to the
sent if validity-checking errors are encountered. application to determine what must be done next.
If the current display is a menu called from a

Considerations for Using the ENTER, series of displays, the UIM presents the display
HELP, and PROMPT Dialog where the MENU command was initially
Commands: The actions performed for requested. The EXIT dialog command backs
ENTER, HELP, and PROMPT depend heavily on completely out of a series of menus.
the type of display and contents of the command
line. These dialog commands can be assigned Optional Parameter
only to function keys, and they have different char-

HOME Command
NOSET|SET Messages: The message Help information is

Indicates whether the job's exit flag is set. not available can be issued during processing
NOSET means that the exit flag is not set; this and can occur if the user chooses to delete or not
is the default. SET means that the exit flag is install help text supplied by the system.
set. For more information on the exit flag, see
“Folding Up Multiple Panels When EXIT Is Additional messages are also possible when help
Requested” on page 17-24. is requested for a specific command on a
command line. Possible messages might be that
VARUPD Value: The EXIT dialog command the command does not exist, or the user might not
does not have a predefined VARUPD value although have authority to it. If these messages are issued,
the user interface style implies VARUPD=NO they appear as the first message in the message
should normally be used. When EXIT is assigned area. Messages describing other conditions on
to a function key or pull-down choice, the VARUPD the screen can still be viewed by scrolling forward.
value of the function key dictates whether or not to
perform validity checking and then updates the HELPHELP
dialog variables.
Messages: No messages are issued during pro- 55──HELPHELP─────────────────────────5%

cessing.
EXTHELP (Extended Help) Displays information about how to use the help
facilities for contextual help, extended help, help
on function keys, and the help index from help
55──EXTHELP──────────────────────────5% panels. The HELPHELP dialog command can be
coded only on pull-down choices for menu bars.
Displays the extended help for the panel. Parameters: None
Parameters: None Messages: No messages are issued during pro-

cessing.
HELP
HELPIDX
55──HELP─────────────────────────────5%
55──HELPIDX──────────────────────────5%
Displays help information. The Common User

Access (CUA) guidelines recommend assigning Begins the index search function for the SCHIDX
this to the Help and F1 keys. attribute specified on the panel group tag. Users
may select a topic in the index to be displayed or
The specific action taken (and help text displayed) printed. The HELPIDX dialog command can be
depends on the screen type, cursor position, and coded only on pull-down choices for menu bars.
so on. For the UIM rules, see “Defining Contex-
tual Help” on page 17-16, and for more informa- Parameters: None
tion on the specific attributes, see “Considerations
for Using the ENTER, HELP, and PROMPT Dialog Messages: No messages are issued during pro-
Commands” on page B-8. cessing.
Parameters: None HOME (Display Home Menu)

VARUPD Value: It is always VARUPD=NO. No
validity checking is performed on the current con- 55──HOME─────────────────────────────5%
tents of the current panel and no updates to dialog
variables are made.

MOREKEYS Command
Displays the job's home menu. This menu is Optional Parameter

added to the stack of menus. It does not imply
returning to the beginning of the stack of menus. RTNPNT|NORTNPNT
The HOME dialog command can be used only on This parameter indicates whether the current
function keys. menu is considered a return point when the
Note: HOME is allowed only on panels con- dialog command is requested. This parameter
taining a menu area. functions the same as the return point
(RTNPNT) parameter of the GO CL
Parameters: None command. RTNPNT indicates that the current
menu is returned when the Exit key is
VARUPD Value: The HOME dialog command pressed; this is the default. No return point
always operates with VARUPD=YES and the fol- (NORTNPNT) indicates to not return to the
lowing occurs: current menu when the Exit key is pressed.
Validity checking is always performed. This parameter has no effect when it is coded
Valid values are processed and the dialog var- in a panel group object using the Create
iables are updated. Panel Group (CRTPNLGRP) command. It is
Any failures from validity checking prevent the meaningful only when it is used in a menu
operation and the screen is displayed again object created using the Create Menu
with the appropriate error messages. (CRTMNU) command.
Messages: No messages are issued during pro- Messages: No messages are issued during pro-
cessing. cessing.
KEYSHELP MOREKEYS (Display More

Function Keys)
55──KEYSHELP─────────────────────────5%
55──MOREKEYS─────────────────────────5%
Displays the help for the function keys on the dis-

played panel. The Common User Access (CUA) Displays an additional list of active function keys
guidelines recommend assigning this to the F1 when they cannot all fit on the panel. The action
key. of the MOREKEYS dialog command can be
assigned only to Function Key F24. When it is, it
Messages: No messages are issued during pro- cannot be conditioned using the COND attribute of
cessing. the key item (KEYI) language tag.
MENU If an application codes ACTION=MOREKEYS on

the KEYI tag, the UIM manages the situation if all
of the function key descriptions do not fit on the
55──MENU──qualified-menu-name─────────5 panel at once.
┌─RTNPNT───┐
5──┼──────────┼──────────────────────5% When a panel is displayed with a KEYL (Key List)
└─NORTNPNT─┘ language tag using the MOREKEYS dialog
command, the UIM gathers a list of all currently
active function keys. This is based on the priority
Displays a subsequent menu as a result of assigned to each key item on the PRIORITY attri-
selecting a menu item or pressing a function key. bute of the KEYI language tag. The UIM attempts
to fit as many of the function keys as possible in
Required Parameter the function key area of the panel.
qualified-menu-name
Specifies the qualified name of the menu to
be displayed.

PAGEDOWN Command
If not all of the function key descriptions fit in the VARUPD Value: The MOVETOP dialog
area, the UIM enables the function key assigned command operates with VARUPD=YES (except
to the MOREKEYS dialog command and places when scrolling the message line) and the following
the descriptions of the function keys on the panel. occurs:
If all of the descriptions of the function keys fit, the
Validity checking is always performed.
function key assigned to the MOREKEYS dialog
command is not enabled.
iables are updated.
Any failures from validity checking prevent the
If a user presses the function key assigned to the
operation and the panel is displayed again
MOREKEYS dialog command, the UIM starts
with the appropriate error messages.
where it left off in the key list and gathers as many
active descriptions of function keys that fit in the
Messages: The UIM can issue Cursor not
function key area in order of priority. The function
positioned on valid line.
key assigned to the MOREKEYS dialog command
is enabled.
MSG (Display Message)
This process continues until the end of the key list
is reached. If the MOREKEYS dialog command is
selected again, the UIM starts back at the begin- 55──MSG──message-id───────────────────5
ning of the key list and begins processing the 5──┬─────────────────────────────┬───5%
MOREKEYS dialog command again. └─qualified-message-file-name─┘
Parameters: None
Displays a message on the message line. It can
Messages: No messages are issued during pro- only be assigned as the default enter action or the
cessing. default selection action to perform when the Enter
key is pressed, and the UIM cannot find any other
specific function to perform.
MOVETOP (Move to Top)
One intended use of this dialog command is to
inform the user that they must select an option or
55──MOVETOP──────────────────────────5%
press a function key.
Moves a cursor-selected line to the top of the Required Parameter

scrollable information area.
message-id
When a function key assigned to this dialog Specifies the message identifier of the
command is pressed, the UIM moves the line con- message to be displayed.
taining the cursor to the top of the scrollable area.
If the cursor is on a blank line inserted by the UIM Optional Parameter
(paragraph separators, and so on), the next line is
qualified-message-file-name
moved to the top of the scrollable area.
Specifies the qualified name of the message
The MOVETOP dialog command applies only to file containing the message. It defaults to the
information areas, and is intended primarily to message file specified on the DFTMSGF attribute
allow users of online text to position the informa- of the PNLGRP tag.
tion in the most readable manner. For example,
VARUPD Value: Because the MSG dialog
an entire chart positioned on one display is easier
command can only be specified on the ENTER attri-
to read than a chart that appears on two displays.
bute of the PANEL tag, VARUPD has no meaning.
Parameters: None The VARUPD value is defined by the function key
assigned to the ENTER action.
PAGEDOWN

PRINT Command
The boundaries of a scrollable area are

55──PAGEDOWN─────────────────────────5% defined by the top and bottom line of a menu,
information, list, or data area, although not all
information in that area (such as instruction
Scrolls forward by one screen or panel and can be lines) is actually scrolled.
assigned to only a function key.
If the cursor is outside a scrollable area, the
When processing incomplete lists, selecting scroll first scrollable area on the panel (top to
areas, and specifying VARUPD=YES, the process bottom) is selected for scrolling.
is the same for the PAGEDOWN dialog command
as it is for the PAGEUP dialog command. Parameters: None
Parameters: None VARUPD Value: PAGEUP operates with

VARUPD=YES except when scrolling the
Messages: UIM can issue Already at bottom of message line, and the following occurs:
area. Validity checking is always performed.
Additional messages can be sent if validity
iables are updated.
checking encounters errors.
Any failures from validity checking prevent
scrolling and the panel is displayed again with
PAGEUP the appropriate error messages.
When scrolling the message line, the PAGEUP

55──PAGEUP───────────────────────────5% dialog command operates as if VARUPD=NO is in
effect. Fields need not be correct and dialog vari-
ables are not updated.
Scrolls backward by one screen or panel and can
be assigned to only a function key. Messages: UIM can issue Already at top of
area.
If a full scrollable area of data is available to the
UIM, or the scrollable area is complete, scrolling is Additional messages can be sent if validity
performed without intervention of the application. checking encounters errors.
If the scrollable area is an action list with selected
actions, none are performed at this time.
PRINT (Print Display)
A special case exists where an incomplete list is
displayed and the PAGEUP scroll results in an
55──PRINT────────────────────────────5%
incomplete panel. In this case, the UIM calls the
program specified to add additional list entries or
mark the list complete. Prints the current display and can be assigned
only to the 5250 PRINT key.
For screens and panels with multiple scrollable
areas, the position of the cursor determines what Parameters: None
is scrolled. The rules are as follows:
If the cursor is in a scrollable area, that area VARUPD Value: Does not apply.
is selected. The message line is considered a
scrollable area. Messages: No messages are issued during pro-
cessing unless errors are found during validity
checking.

PROMPT Command
PROMPT If VARUPD=NO is specified for the function key,

the application program can get access to the
keyed data that is not verified by using the
55──PROMPT───────────────────────────5% DSPVALUE attribute of the tag where the prompt
was defined.
Prompts for commands, action list options, and For more information about entry field prompting,
entry fields and can be assigned only to function see the description of the PROMPT attribute for the
keys. Its specific function depends on the fol- following tags found in Appendix A, “UIM Panel
lowing: Group Definition Language” on page A-1.
Type of screen being managed Data item (DATAI)
Location of the cursor Data item Extender (DATAIX)
Contents of the command or parameter line List column (LISTCOL)
Parameters: None Prompting an Action List Option or

VARUPD Value: For more information, see Command: When prompting an option on an
“Prompting an Entry Field” and “Prompting an action list or command line, the PROMPT dialog
Action List Option or Command.” command always operates with VARUPD=YES
and the following occurs:
Messages: Any messages resulting from submit- Validity checking is always performed.
ting or canceling the commands are displayed on Valid values are processed and the dialog var-
the message line. In addition, the UIM can issue iables are updated.
the following messages: Any failures from validity checking prevent
The prompt attempt for the menu item was prompting and the panel is displayed again
not valid. with the appropriate error messages.
Cursor is in a location where the prompt
function is not allowed. The prompt function results in either submitting a
command string to the system or calling an appli-
Additional messages can be sent if errors from cation program. This occurs according to the fol-
validity checking are encountered. lowing rules:
If the command line contains a menu item, an
Prompting an Entry Field: The prompt error is sent. The UIM does not support
function becomes a CALL or RETURN function prompting for menu items.
based on the prompt definition specified on the If the cursor is on the command line or in the
PROMPT attribute of the associated panel definition option column and if the panel has an action
tag. Prompting an entry field should be assigned list panel with options specified, the UIM
to the F4 key. selects the PROMPT action associated with
each selected option. The PROMPT action
When prompting an entry field, VARUPD processing
can either be to submit a command to the
is done if it is specified on the definition of the
system or to call an application program.
function key.
If an option is selected that does not have a
If VARUPD=YES is specified for the function key, defined prompt action, action list processing
the following occurs: stops, and the panel is displayed again with
an error message. The error message indi-
Validity checking is always performed cates that the user cannot prompt for the
Valid values are processed and the dialog var- selected option. In this case, the selected
iables are updated option number is displayed with error
Any failures from validity checking prevent emphasis.
prompting and the panel is displayed again
The contents of the command line are param-
with the appropriate error messages.
eters for the list action. These parameters
can be accessed by defining a dialog variable

RETURN Command
for the UIM to update. The update is with the The UIM keeps a series of commands entered on
contents of the command line when the action command lines. When the RETRIEVE dialog
list is processed. For more information see command is issued, the previous command is dis-
the LIST tag in Appendix A, “UIM Panel played on the command line. If the RETRIEVE
Group Definition Language” on page A-1 dialog command is issued again before any other
function is performed, the next most recent
Each individual option receives a separate
command is displayed.
prompt. The UIM does not apply information
added during prompting from one command to
Menu item selections and parameter strings
another.
cannot be retrieved. Also, commands submitted
When the prompt action is to call an applica- via the CMD dialog command cannot be retrieved.
tion program, the option is processed without
prompting by the UIM. When the UIM calls Parameters: None
the application program, an indication is given
that the user requested the prompt function. It VARUPD Value: The RETRIEVE dialog
is the responsibility of the application program command always operates with VARUPD=NO.
to provide its own version of prompting. No validity checking is performed on the contents
of the current panel and no updates are made to
If the command line contains a command, the the dialog variables.
command is submitted for prompting and pro-
cessing. The command can then be run or Messages: No messages are issued during pro-
canceled through normal prompter functions. cessing.
Depending on the environment the job is
running in, the system can pass the command
to the System/36 environment or REXX.
RETURN (Return Control to
Application)
If the command line was blank (a subclass of
assuming it contains a command), the Major
Command Groups menu is displayed. 55──RETURN──n────────────────────────5%
For additional information about the PROMPT

dialog command, see “Considerations for Using Provides the application with a method of handling
the ENTER, HELP, and PROMPT Dialog function keys, menu items, and pull-down choices
Commands” on page B-8. by having the UIM return control to the application
with the appropriate indication.
PULLDOWN (Display Pull-Down Note: To provide the Refresh/Redisplay function
Menu) for an application, use the RETURN dialog
command.
55──PULLDOWN─────────────────────────5% The effect of the RETURN dialog command can

be obtained for action lists by using the ACTOR
attribute of the LIST tag. This attribute determines
Displays the first pull-down menu of the menu bar. whether or not the UIM should handle the action
list.
Parameters: None
Required Parameter
RETRIEVE (Retrieve Command
String) n This parameter specifies a numeric value from
1 through 32767. This value is returned to the
application, on the function requested param-
55──RETRIEVE─────────────────────────5% eter of QUIDSPP API, when the RETURN
function is encountered.
Displays the previously entered command.

VARUPD Value: The RETURN dialog command whether or not to perform validity checking and
does not have a predefined VARUPD value. When then updates the dialog variables.
RETURN is assigned to a function key, the
VARUPD value of the function key determines Messages: No messages are issued during pro-
cessing unless errors are found during validity
checking.

Appendix C. Feedback Area Layouts for Display Files
This appendix contains Product-Sensitive Pro- The support provided by the high-level language
gramming Interface and Associated Guidance you are using determines how to access this infor-
Information. mation and how the data types are represented.
See your high-level language manual for more
Tables in this section describe the open and I/O information.
feedback areas associated with any opened
display file. The following information is presented
for each item in these feedback areas: Open Feedback Area
Offset, which is the number of bytes from the
start of the feedback area to the location of The open feedback area is the part of the open
each item. data path (ODP) that contains general information
Data Type. about the file after it has been opened. It also
Length, which is given in number of bytes. contains file-specific information for display files,
Contents, which is the description of the item plus information about each device defined for the
and the valid values for it. file. This information is set during open pro-
cessing and may be updated as other operations
For information about feedback area layouts for are performed.
files other than display files, see the Data Man-
agement book.
Table C-1 (Page 1 of 3). Open Feedback Area

Data
Offset Type Length Contents
0 Character 2 Open data path (ODP) type:
DS Display, tape, ICF, save, printer file not being spooled, or diskette file
not being spooled.
DB Database member.
SP Printer or diskette file being spooled or inline data file.
2 Character 10 Name of the file being opened. If the ODP type is DS (for display files), this is
the name of the display file.
12 Character 10 Name of the library containing the file. For an inline data file, the value is *N.
22 Character 10 Not applicable to displays.
42 Binary 2 Not applicable to displays.
44 Binary 2 Maximum record length.
58 Binary 4 Reserved.
 Copyright IBM Corp. 1997 C-1

Data
66 Binary 2 File type:
1 Display
2 Printer
4 Diskette
5 Tape
9 Save
10 DDM
11 ICF
20 Inline data
21 Database
68 Character 3 Reserved.
71 Binary 2 Number of lines on a display screen.
73 Binary 2 Number of positions on a display screen.
105 Binary 2 Maximum number of records that can be read or written in a block when using
blocked record I/O.
109 Binary 2 Blocked record I/O record increase. Number of bytes that must be added to the
start of each record in a block to address the next record in the block.
115 Character 1 Miscellaneous flags.
Bit 1: Reserved.
Bit 2: File with sharing

0 File was not opened with sharing.
1 File was opened with sharing (SHARE(*YES)).
Bits 3-5: Not applicable to displays.
Bit 6: Field-level descriptions
0 File does not contain field-level descriptions.
1 File contains field-level descriptions.
Bit 7: DBCS-capable file
0 File is not DBCS-capable.
1 File is DBCS-capable.
Bit 8: Not applicable to displays.
C-2 Application Display Programming V4R1

Data
116 Character 10 For display files, this is the name of the display device description that is the
requesting program device.
This field is supplied only when a device name of *REQUESTER is being
attached to the display file by an open or acquire operation. Otherwise, this field
contains *N.
126 Binary 2 File open count. If the file has not been opened with sharing, this field contains
a 1. If the file has been opened with sharing, this field contains the number of
programs currently attached to this file.
Bit 5: Separate indicator area
0 Indicators are in the I/O buffer of the program.
1 Indicators are not in the I/O buffer of the program. The DDS
keyword, INDARA, was used when the file was created.
Bit 6: User buffers
0 System creates I/O buffers for the program.
1 User program supplies I/O buffers.
Bit 7: Reserved.
133 Character 2 Open identifier. The value is unique for a full open operation (SHARE (*NO)) of
a file or the first open operation of a file opened with SHARE(*YES). It allows
you to match this file to an entry on the associated data queue.
135 Binary 2 The field value is the maximum record format length, including both data and
file-specific information such as: option indicators, response indicators, source
sequence numbers, and program-to-system data. If the value is zero, then use
the field at offset 44.
Bit 4: CCSID character substitution
0 No substitution characters will be used during CCSID data con-
version.
1 Substitution characters may be used during CCSID data conver-
sion.
Bits 5-8: Reserved.
146 Binary 2 Number of devices defined for this ODP. For displays, this is determined by the
number of devices defined on the DEV parameter of the Create Display File
(CRTDSPF) command.
148 Character Device name definition list. See “Device Definition List” on page C-4 for a
description of this array.
Appendix C. Feedback Area Layouts for Display Files C-3

Device Definition List open feedback area. The device definition list
begins at offset 148 of the open feedback area.
The device definition list part of the open feedback The offsets shown for it are from the start of the
area is an array structure. Each entry in the array device definition list rather than the start of the
contains information about each device attached open feedback area.
to the file. The number of entries in this array is
determined by the number at offset 146 of the
Table C-2 (Page 1 of 2). Device Definition List

Data
Program device name. For display files, the value is the name of the device
0 Character 10 description.
Device description name. For display files, the value is the name of the device
60 Character 10 description.
70 Character 1 Device class. For displays, the device class is hex 01.
Device type.
hex 07 5251 Display Station
hex 0B 5291 Display Station
hex 0D 5292 Display Station
hex 12 5555-B01 Display Station
hex 15 Graphic-capable device
hex 16 Financial terminal
hex 19 3277 DHCF Device
hex 26 3179-2 Display Station
hex 27 3196-A Display Station
hex 28 3196-B Display Station
hex 33 3197-C1 Display Station
hex 35 3197-D1 Display Station
hex 37 3197-W1 Display Station
hex 39 5555-E01 Display Station
hex 3E 3476-EA Display Station
hex 3F 3477-FG Display Station
hex 40 3278 DHCF device
hex 42 ICF finance device
hex 43 Retail communications device
hex 44 3477-FA Display Station
hex 45 3477-FC Display Station
hex 46 3477-FD Display Station
hex 47 3477-FW Display Station
hex 48 3477-FE Display Station
hex 4D Network Virtual Terminal display station
hex 52 5555-F01 Display Station
hex 56 3476-EC Display Station
71 Character 1 hex 58 5555-G01 Display Station

Table C-2 (Page 2 of 2). Device Definition List
Data
hex 59 5555-G02 Display Station
hex 5D 3486-BA Display Station
hex 5F 3487-HA Display Station
hex 60 3487-HG Display Station
hex 61 3487-HW Display Station
hex 62 3487-HC Display Station
72 Binary 2 Number of lines on the display screen.
74 Binary 2 Number of positions in each line of the display screen.
Bit flags.
Bit 1: Blinking capability.
0 Display is not capable of blinking.
76 Character 2 1 Display is capable of blinking.
Bit 2: Device location.
0 Local device.
1 Remote device.
Bit 3: Acquire status. This bit is set even if the device is implicitly acquired
at open time.
0 Device is not acquired.
1 Device is acquired.
Bit 4: Invite status.
0 Device is not invited.
1 Device is invited.
Bit 5: Data available status (only if device is invited).
0 Data is not available.
1 Data is available.
Bit 7: Requesting program device.
0 Not a requesting program device.
1 A requesting program device.
Bit 8: DBCS device.
0 Device is not capable of processing double-byte data.
1 Device is capable of processing double-byte data.
Bits 9-10: Reserved.
Bit 11: DBCS keyboard.
0 Keyboard is not capable of entering double-byte data.
1 Keyboard is capable of entering double-byte data.

information, such as the count of I/O operations,
I/O Feedback Area reflects the number of operations on blocks of
records and not the number of records. See your
The results of I/O operations are communicated to high-level language manual to determine if your
the program using OS/400 messages and I/O program uses blocked record I/O.
feedback information. The I/O feedback area is
updated for every I/O operation unless your The I/O feedback area consists of two parts: a
program is using blocked record I/O. In that case, common area and a file-dependent area.
the feedback area is updated only when a block of
records is read or written. Some of the informa-
tion reflects the last record in the block. Other
Common I/O Feedback Area
Table C-3 (Page 1 of 3). Common I/O Feedback Area

Data
0 Binary 2 Offset to file-dependent feedback area.
2 Binary 4 Write operation count. Updated only when a write operation completes success-
fully. For blocked record I/O operations, this count is the number of blocks, not
the number of records.
6 Binary 4 Read operation count. Updated only when a read operation completes success-
fully. For blocked record I/O operations, this count is the number of blocks, not
the number of records.
10 Binary 4 Write-read operation count. Updated only when a write-read operation com-
pletes successfully.
14 Binary 4 Other operation count. Number of successful operations other than write, read,
or write-read. Updated only when the operation completes successfully. This
count includes update, delete, force-end-of-data, force-end-of-volume, change-
end-of-data, release record lock, and acquire/release device operations.
19 Character 1 Current operation.
hex 01 Read or read block or read from invited devices
hex 02 Read direct
hex 03 Read by key
hex 05 Write or write block
hex 06 Write-read
hex 07 Update
hex 08 Delete
hex 09 Force-end-of-data
hex 0A Force-end-of-volume
hex 0D Release record lock
hex 0E Change end-of-data
hex 0F Put delete
hex 11 Release device
hex 12 Acquire device
20 Character 10 Name of the record format just processed, which is either:
Specified on the I/O request, or
Determined by default or format selection processing
For display files, the default name is either the name of the only record format in
the file or the previous record format name for the record written to the display
that contains input-capable fields. Because a display file may have multiple
formats on the display at the same time, this format may not represent the
format where the last cursor position was typed.

Data
30 Character 2 Device class:
Byte 1:
hex 00 Database
hex 01 Display
hex 02 Printer
hex 04 Diskette
hex 05 Tape
hex 09 Save
hex 0B ICF
Byte 2 (if byte 1 contains hex 01 for displays):
hex 0B 5291 Display Station
hex 0D 5292 Display Station
hex 12 5555-B01 Display Station
hex 15 Graphic-capable device
hex 16 Financial terminal
hex 26 3179-2 Display Station
hex 27 3196-A Display Station
hex 28 3196-B Display Station
hex 39 5555-E01 Display Station
hex 3E 3476-EA Display Station
hex 3F 3477-FG Display Station
hex 42 ICF finance device
hex 43 Retail communications device
hex 44 3477-FA Display Station
hex 45 3477-FC Display Station
hex 46 3477-FD Display Station
hex 47 3477-FW Display Station
hex 48 3477-FE Display Station
hex 4D Network Virtual Terminal display station
hex 52 5555-F01 Display Station
hex 56 3476-EC Display Station
hex 5D 3486-BA Display Station
hex 5E 3486-BG Display Station
hex 5F 3487-HE Display Station
hex 60 3487-HD Display Station
hex 61 3487-HW Display Station
hex 62 3487-HC Display Station

Data
32 Character 10 Device name. For displays, the name of the device for which the operation just
completed.
42 Binary 4 Length of the record processed by the last I/O operation.
126 Binary 2 Number of records retrieved on a read request for blocked records or sent on a
write or force-end-of-data or force-end-of-volume request for blocked records.
128 Binary 2 For output, the field value is the record format length, including first-character
forms control, option indicators, source sequence numbers, and program-to-
system data. If the value is zero, use the field at offset 42.
For input, the field value is the record format length, including response indica-
tors and source sequence numbers. If the value is zero, use the field at offset
42.

I/O Feedback Area for Display
Files
Table C-4 (Page 1 of 3). I/O Feedback Area for Display Files
Data
0 Character 2 Flag bits.
Bit 1: Cancel-read indicator.
0 The cancel-read operation did not cancel the read request.
1 The cancel-read operation canceled the read request.
Bit 2: Data-returned indicator.
0 The cancel-read operation did not change the contents of the
input buffer.
1 The cancel-read operation placed the data from the read-with-
no-wait operation into the input buffer.
Bit 3: Command key indicator.
0 Conditions for setting this indicator did not occur.
1 The Print, Help, Home, Roll Up, Roll Down, or Clear key was
pressed. The key is enabled with a DDS keyword, but without a
response indicator specified.
2 Character 1 Attention indicator byte (AID). This field identifies which function key was
pressed. This field will always contain the value hex F1 to imitate the Enter key
being pressed on a display device. For display files, this field will contain the
1-byte hexadecimal value returned from the device.
Hex Codes Function Keys
hex 31 1
hex 32 2
hex 33 3
hex 34 4
hex 35 5
hex 36 6
hex 37 7
hex 38 8
hex 39 9
hex 3A 10
hex 3B 11
hex 3C 12
hex B1 13
hex B2 14
hex B3 15
hex B4 16
hex B5 17
hex B6 18
hex B7 19
hex B8 20
hex B9 21
hex BA 22
hex BB 23
hex BC 24
hex BD Clear

Data
hex F1 Enter/Rec Adv
hex F3 Help (not in operator-error mode)
hex F4 Roll Down
hex F5 Roll Up
hex F6 Print
hex F8 Record Backspace
hex 3F Automatic Enter (for Selector Light Pen)
3 Character 2 Cursor location (line and position). Updated on input operations that are not
subfile operations that return data to the program. For example, hex 0102
means line 1, position 2. Line 10, position 33 would be hex 0A21.
5 Binary 4 Actual data length. The length of the record format processed by the I/O opera-
tion.
9 Binary 2 Relative record number of a subfile record. Updated for a subfile record opera-
tion. For input operations, updated only if data is returned to the program. If
multiple subfiles are on the display, this offset will contain the relative record
number for the last subfile updated.
11 Binary 2 Indicates the lowest subfile relative record number currently displayed in the
uppermost subfile display area if the last write operation was done to the subfile
control record with SFLDSP specified. Updated for roll up and roll down oper-
ations. Reset to 0 on a write operation to another record. Not set for message
subfiles.
13 Binary 2 Total number of records in a subfile. Updated on a put-relative operation to any
subfile record. The number is set to zero on a write or write-read operation to
any subfile control record with the SFLINZ keyword optioned on. If records are
put to multiple subfiles on the display, this offset will contain the total number of
records for all subfiles assuming that no write or write-read operations were per-
formed to any subfile control record with the SFLINZ keyword optioned on.
15 Character 2 Cursor location relative to active DDS WINDOW keyword (line and position).
Updated on input operations that are not subfile operations that return data to
the program. The cursor location is based off the usable positions within the
window. For example, hex 0C13 means line 12, position 19.
34 Character 2 Major return code.
00 Operation completed successfully.
02 Input operation completed successfully, but job is being canceled
(controlled).
03 Input operation completed successfully, but no data received.
04 Output exception.
08 Device already acquired.
11 Read from invited devices was not successful.
34 Input exception.
80 Permanent system or file error.
81 Permanent session or device error.
82 Acquire or open operation failed.
83 Recoverable session or device error.
36 Character 2 Minor return code. For the values for a display file, see Appendix E, “Display
File Return Codes” on page E-1.

Data

Get Attributes
Performing the get attributes operation allows you
to obtain certain information about a specific
display device.
Table C-5 (Page 1 of 3). Get Attributes

Data
0 Character 10 Program device name.
10 Character 10 Device description name. Name of the device description associated with this
entry.
20 Character 10 User ID.
30 Character 1 Device class. For displays, the device class is D.
31 Character 6 Device type:
3179 3179 Display Station
317902 3179-2 Display Station
3196A 3196-A1/A2 Display Station
3196B 3196-B1/B2 Display Station
3197C1 3197-C1 Display Station
3197D1 3197-D1 Display Station
3197D2 3197-D2 Display Station
3197W1 3197-W1 Display Station
3197W2 3197-W2 Display Station
3476EA 3476-EA Display Station
3476-EC 3476-EC Display Station
3477FA 3477-FA Display Station
3477FC 3477-FC Display Station
3477FD 3477-FD Display Station
3477FE 3477-FE Display Station
3477FG 3477-FG Display Station
3477FW 3477-FW Display Station
529202 5292-2 Display Station
5555B1 5555-B01 Display Station
5555E1 5555-E01 Display Station
5555F1 5555-F1 Display Station
5555-G1 5555-G01 Display Station
5555-G2 5555-G02 Display Station
3486BA 3486-BA Display Station
3486BG 3486-BG Display Station
3487HC 3487-HC Display Station
3487HD 3487-HD Display Station
3487HE 3487-HE Display Station
3487HW 3487-HW Display Station
DHCF77 3277 DHCF device

Data
37 Character 1 Requesting program device. This flag indicates whether this entry is defining a
*REQUESTER device.
N Not a *REQUESTER device (communications source device).
Y A *REQUESTER device (communications target device).
38 Character 1 Acquire status. Set even if device is implicitly acquired at open time.
N Device is not acquired.
Y Device is acquired.
39 Character 1 Invite status.
Y Device is invited.
N Device is not invited.
40 Character 1 Data available.
Y Invited data is available.
N Invited data is not available.
41 Binary 2 Number of rows on display.
43 Binary 2 Number of columns on display.
45 Character 1 Display allow blink.
Y Display is capable of blinking.
N Display is not capable of blinking.
46 Character 1 Online/offline status.
O Display is online.
F Display is offline.
47 Character 1 Display location.
L Local display.
R Remote display.
48 Character 1 Display type.
A Alphanumeric or Katakana.
I DBCS.
49 Character 1 Keyboard type of display.
A Alphanumeric or Katakana keyboard.
I DBCS keyboard.

Data
101 Character 1 Controller information.
N Display is not attached to a controller that supports an enhanced
interface for nonprogrammable work stations.
1 Display is attached to a controller (type 1) 1 that supports an
enhanced interface for nonprogrammable work stations.
102 Character 1 Color capability of display.
Y Color display
N Monochrome display
103 Character 1 Grid line support by display.
Y Display supports grid lines
N Display does not support grid lines
Type 1 Controllers available at V2R2 which support such things as windows, selection fields, scroll bars, and continued cursor
progression.
Type 2 Controllers available at V2R3. These support all of the V2R2 functions as well as menu bars, continued-entry fields,
edit masks, and simple hotspots.
Type 3 Controllers available at V3R1. These support all of the V2R2 and V2R3 functions. They also support text in the bottom
border of windows.

Appendix D. Double-Byte Character Set Support for Displays
This appendix contains information that you need
if you use double-byte characters. This includes Double-Byte Character Set
the following topics: Fundamentals
Double-byte character set (DBCS) fundamen- Some languages, such as Chinese, Japanese,
tals and Korean, have a writing scheme that uses
Processing double-byte characters many different characters that cannot be repre-
Device file support sented with single-byte codes. To create coded
Display support character sets for such languages, the system
Writing application programs that process uses two bytes to represent each character.
double-byte characters Characters that are encoded in two-byte code are
DBCS font tables called double-byte characters.
DBCS sort tables
DBCS conversion dictionaries The following example shows alphanumeric char-
Using DBCS conversion acters coded in a single-byte code scheme and
double-byte characters coded in a double-byte
DBCS printer and spooling support information code scheme.
can be found in the Printer Device Programming
book.
1-Byte Code 2-Byte Code
(SBCS) (DBCS)
A X’C1’ X’42C1’
B X’C2’ X’42C2’
1 X’F1’ X’42F1’
2 X’F2’ X’42F2’
X’4481’
X’457D’ ( Japanese )
X’8877’ ( Japanese )
X’525F’ ( Korean )
X’4F99’ ( Simplified Chinese )
X’5B70’ ( Traditional Chinese )
X’hhhh’ indicates that the code has the hexadecimal value, "hhhh".
1-Byte Codes: 256 characters

. .
. .
2-Byte Codes: 256 X 256 characters . .
. .
. . HRSLS338-1
You can use double-byte characters as well as DBCS Code Scheme

single-byte characters in one application. For
instance, you may want to store double-byte data IBM supports two DBCS code schemes: one for
and single-byte data in your database, create your the host system, the other for personal computers.
displays with double-byte text and fields, or print The IBM host-system code scheme has the fol-
reports with double-byte characters. lowing code-range characteristics:
First byte hex 41 to hex FE
Second byte hex 41 to hex FE
Double-byte blank hex 4040
In the following figure, using the first byte as the

vertical axis and the second byte as the horizontal
 Copyright IBM Corp. 1997 D-1

axis, 256 x 256 intersections (code points) are Table D-1. IBM Japanese Character Set
expressed. The lower-right code area is desig- Number of
nated as the valid double-byte code area and x is Wards Content Characters
assigned to the double-byte blank.
41 to 44 Non-Kanji characters 549
2nd byte Greek, Russian,
1st Roman numeric
0 4 4 F F
byte 0 0 1 E F (ward 41)
00 Alphanumeric and
related symbols
(ward 42)
Katakana,
40 x Hiragana, and
41 special symbols
(ward 43-44)
45 to 55 Basic Kanji characters 3226
D 56 to 68 Extended Kanji charac- 3487
ters
69 to 7F User-defined characters Up to 4370
80 to FE Reserved
FE Total number of IBM-defined characters: 7263
FF
Table D-2. IBM Korean Character Set
D: double-byte code area Number of
x: double-byte blank RSLH712-4
Wards Content Characters
Figure D-1. IBM Host-System Code Scheme 40 Space in 4040 1
41 to 46 Non-Hangeul/Hanja 939
By assigning the values hex 41 to hex FE in the characters (Latin
first and second bytes as the DBCS character alphabet, Greek,
codes, the codes can be grouped in wards with Roman, Japanese
192 code points in each ward. For example, the Kana, numeric, special
code group with the first byte starting with hex 42 symbols)
is called ward 42. Ward 42 has the same alpha- 47 to 4F Reserved
50 to 6C Hanja characters 5265
numeric characters as those in a corresponding
6D to 83 Reserved
single-byte EBCDIC code page, but with double- 84 to D3 Hangeul characters 2672
byte codes. For example, the character A is (Jamo included)
represented in single-byte EBCDIC code as hex D4 to DD User-defined characters Up to 1880
C1 and in IBM-host code as hex 42C1. DE to FE Reserved
Total number of IBM-defined characters: 8877
The AS/400 system supports the following double-
byte character sets: Table D-3. IBM Simplified Chinese Character Set
IBM Japanese Number of

IBM Korean
IBM Simplified Chinese 40 Space in 4040 1
IBM Traditional Chinese 41 to 47 Non-Chinese charac- 712
ters (Latin alphabet,
The following tables show the code ranges for Greek, Russian,
each character set and the number of characters Japanese Kana,
supported in each character set. numeric, special
symbols)
Table D-1. IBM Japanese Character Set 48 to 6F Chinese characters: 3755 and
Level 1 and Level 2 3008
Number of
70 to 75 Reserved
76 to 7F User-defined characters Up to 1880
40 Space in 4040 1 80 to FE Reserved
D-2 Application Display Programming V4R1

Table D-4. IBM Traditional Chinese Character Set
1-Byte Data 1-Byte Data
Number of
40 Space in 4040 1 2-Byte Data
41 to 46 Non-Chinese charac- 674
ters (Latin alphabet,
Greek, Roman, 1-Byte Data SO 2-Byte Data SI 1-Byte Data
Japanese Kana,
numeric, special Control
symbols) Character
47 to 4B Reserved RSLH713-1
4C to 68 Primary Chinese char- 5401

acters
69 to 91 Secondary Chinese 7652
Each shift-control character occupies the same
characters amount of space as one alphanumeric character.
92 to CF Reserved By contrast, double-byte characters occupy the
D0 to DD User-defined characters Up to 2632 same amount of space as two alphanumeric char-
DE to FE Reserved acters.
This code scheme applies to the AS/400 system,

Using Double-Byte Data
System/36, System/38, as well as the
This section tells you how you can use double-
System/370* system. A different DBCS code
byte data and discusses the limitations to its use.
scheme, called the IBM personal computer DBCS
code scheme, is used on the Personal System/55.
For details of the IBM personal computer DBCS How You Can Use: You can use double-
code scheme, refer to IBM PS/55 publications. byte data in the following ways:
As data in files:
Double-byte code that is not valid has a double-
byte code value that is not in the valid double-byte – Data entered in input-capable fields and
code range. Double-byte code that is not valid is data displayed in output-capable fields of
not the same as undefined double-byte code, display files.
which has valid double-byte code value but no – Data used as literals in display files.
graphic symbol currently defined for the code. As the text of messages.
As the text of object descriptions.
Shift-Control Characters
As literals and constants, and as data to be
When the IBM host-system code scheme is used, processed by high-level language programs.
the system uses shift-control characters to identify As search words when using the information
the beginning and end of a string of double-byte search function. For more information on
characters. The shift-out (SO) character, hex 0E, DBCS and the search information function,
indicates the beginning of a double-byte character see “National Language Considerations” on
string. The shift-in (SI) character, hex 0F, indi- page 20-12.
cates the end of a double-byte character string.
Double-byte data can be displayed only at DBCS
display stations. Double-byte data can be written
onto diskettes and tape, as well as onto disk
storage.
Appendix D. Double-Byte Character Set Support for Displays D-3

How You Cannot Use: You cannot use Extended Characters
double-byte data in the following ways:
As AS/400 object names. When processing extended characters, the display
As command names or variable names in station requires the assistance of the system. The
control language (CL) and other high-level lan- system must tell the display station what the char-
guages. acter looks like before the display station can
As displayed output on alphanumeric display display the character. Extended characters are
stations. stored in a DBCS font table, not in the DBCS
display station. When displaying extended char-
acters, the display station receives them from the
Double-Byte Character Size DBCS font table under control of the operating
system.
When displayed, double-byte characters are twice
as wide as alphanumeric characters. Extended character processing is a function of the
operating system that is required to make charac-
Consider the width of double-byte characters ters stored in a DBCS font table available to a
when you calculate the length of a double-byte DBCS display station.
data field because field lengths are usually identi-
fied as the number of alphanumeric character To request extended character processing, specify
positions used. For more information on calcu- the double-byte extended character parameter,
lating the length of fields containing double-byte IGCEXNCHR(*YES), on the file creation command
data, refer to the DDS Reference. when you create a display (CRTDSPF command)
file that processes double-byte data. Because
IGCEXNCHR(*YES) is the default value, the
Processing Double-Byte system automatically processes extended charac-
Characters ters unless you instruct it otherwise. You can
change this file attribute by using a change file
Due to the large number of double-byte charac- (CHGDSPF) or override file (OVRDSPF)
ters, the system needs more information to identify command. For example, to override the display
each double-byte character than is needed to file DBCSDSPF so that extended characters are
identify each alphanumeric character. processed, enter:
OVRDSPF DSPF(DBCSDSPF) IGCEXNCHR(\YES)
There are two types of double-byte characters:
basic and extended. These characters are usually Note: The system ignores the IGCEXNCHR
processed by the display station on which the parameter when processing alphanumeric files.
characters are displayed.
What Happens When Extended
Basic Characters Characters Are Not Processed
A DBCS display station can process basic charac- When extended characters are not processed, the
ters without any assistance from the system. The following happens:
display station knows about the graphic characters
because they are stored in the display station. Basic characters are displayed.
The number of double-byte characters that are The system displays the undefined character
stored in the display station varies with the lan- where it would otherwise display extended
guage supported and the storage size of the characters.
display station. A DBCS display station can The extended characters, though not dis-
display basic characters without using the played, are stored correctly in the system.
extended character processing function of the
operating system.

DBCS-Open Field
Device File Support DBCS-open fields display and accept both
single-byte and double-byte characters.
The following sections describe DBCS device files Double-byte characters are enclosed in
and special considerations for working with DBCS shift-out and shift-in characters that have to
device files. Data description specifications (DDS) be paired.
can be used with DBCS device files. For informa-
tion about using DDS, refer to the DDS DBCS-Either Field
Reference. DBCS-either fields display and accept either
single-byte or double-byte characters, but not
both. Double-byte characters are enclosed in
What a DBCS File Is shift-out and shift-in character pairs.
A DBCS file is a file that contains double-byte DBCS-Graphic Field
data or is used to process double-byte data. DBCS-graphic fields do not contain shift-out
Other files are called alphanumeric files. and shift-in characters.
Display files can be DBCS files. In display files, you can define fields with
DBCS-only data type (type J), either data type
When to Indicate a DBCS File (type E), open data type (type O), or
DBCS-graphic data type (type G).
You should indicate that a file is DBCS in one or
more of the following situations: You can also use a double-byte literal that is used
with the file at processing time, such as literals
The file receives input, or displays output, specified with the Default (DFT) and Error
which has double-byte characters. Message (ERRMSG) DDS keywords.
The file contains double-byte literals.
The file has double-byte literals in the DDS Note: You may also use double-byte literals as
that are used in the file at processing time text and comments in a file, such as with the DDS
(such as constant fields and error messages). keyword TEXT. However, the system does not
The DDS of the file includes DBCS keywords. consider a file, whose only DBCS attribute is that
See the DDS Reference for information on it has double-byte comments, to be a DBCS file.
these keywords.
You may also specify the Alternative Data Type
The file stores double-byte data (database
(IGCALTTYP) DDS keyword in display files. This
files).
keyword lets you use display files with both alpha-
numeric and double-byte applications. When you
How to Indicate a DBCS File put the IGCALTTYP keyword into effect, you can
use double-byte data with the file.
You must indicate that a device file is a DBCS file
in order for the system to process double-byte Put the IGCALTTYP keyword into effect by cre-
data properly. You can do this in one of the fol- ating, changing, or overriding display files with the
lowing ways: IGCDTA(*YES) value. You can put the
By specifying IGCDTA(*YES) on the Create IGCALTTYP keyword into effect for display files by
Display File (CRTDSPF) command specifying IGCDTA(*YES) on the following device
file commands:
Through DDS
Create Display File (CRTDSPF)
DDS provides fields of the following data types: Change Display File (CHGDSPF)
Override with Display File (OVRDSPF)
DBCS-Only Field
DBCS-only fields display and accept only When you specify IGCDTA(*NO), the IGCALTTYP
double-byte characters. Double-byte charac- keyword is not in effect and you can use only
ters are always enclosed in shift-out and alphanumeric data with the file. Changing or over-
shift-in characters that have to be paired. riding the file to put the IGCALTTYP keyword into
effect does not change the DDS of the file.

Except when using the IGCALTTYP function, you 1. Position the cursor in the field in which you
do not need to specify IGCDTA(*YES) on the file want to insert double-byte data.
creation command if you have already specified 2. Press the Insert Shift Control Character key
DBCS functions in the DDS. Instead, specify (according to your DBCS display station user's
IGCDTA(*YES) when the file has DBCS functions guide).
that are not indicated in the DDS. For example,
specify IGCDTA(*YES) on the file creation The system inserts a pair of shift-control charac-
command if the file is intended to contain double- ters at the same time, as follows (where 0E repre-
byte data. sents the shift-out character and 0F represents the
shift-in character):
Improperly Indicated DBCS Files ðEðF
If you do not properly indicate that a display file is The system leaves the cursor under the shift-in
a DBCS file, one of the following happens: character and puts the keyboard in insert mode.
Display data management assumes that the Insert double-byte characters between the shift-
output data to the display does not contain control characters. To insert double-byte charac-
double-byte data. The end result depends on ters, start typing in double-byte characters at the
whether the display is an alphanumeric or cursor position. For example, enter the double-
DBCS display. byte character string D1D2D3, as follows (where
0E represents the shift-out character, 0F repre-
If the display is an alphanumeric display, the
sents the shift-in character, and D1, D2, and D3
double-byte data is interpreted as alphanu-
represent three double-byte characters):
meric data. The shift-control characters
appear as blanks. The displayed double-byte ðED1D2D3ðF
data does not make sense.
If the display is a DBCS display, the double- To find out if a field already has the shift-control
byte data is displayed with the exception of characters, press the Display Shift Control Char-
extended characters. The system does not acter key.
perform extended character processing on the
data. Therefore, extended characters are dis- Number of Displayed Extended
played with the symbol for undefined double-
Characters
byte characters.
The system does not recognize literals with The system can display up to 512 different
DBCS text as double-byte literals if the source extended characters on a Japanese display at one
file is not specified as a DBCS file. time. Additional extended characters are dis-
played as undefined characters. However, the
additional extended characters are stored correctly
Display Support in the system.
The following sections describe information on dis- Number of Input Fields on a

playing double-byte characters.
Display
Inserting Shift-Control Characters The use of DBCS input fields affects the total
number of input fields allowed on a display. For a
The system inserts shift-control characters into 5250 display station, you can specify as many as
DBCS-only fields automatically. 256 input fields. However, each three instances
of a DBCS field reduces the maximum number of
To insert shift-control characters into DBCS-open fields by one. For example, if there are 9 DBCS
fields or DBCS-either fields, do the following: fields on a display, then the maximum is
256-(9/3)=253 input fields.

Effects of Displaying Double-Byte Application Program
Data at Alphanumeric Work Considerations
Stations
The following sections describe considerations for
Alphanumeric display stations cannot display writing applications that process double-byte data.
double-byte data correctly. If you try to display
double-byte data at an alphanumeric display
station, the following happens:
Designing Application Programs
That Process Double-Byte Data
The system sends an inquiry message to that
display station, asking whether you want to Design your application programs for processing
continue using the program with double-byte double-byte data in the same way you design
data or to cancel it. application programs for processing alphanumeric
If you continue using the program, the system data, with the following additional considerations:
ignores the shift-control characters and inter- Design display formats that can be used with
prets the double-byte characters as though double-byte data.
they were alphanumeric. Displayed double-
byte data does not make sense. If needed, provide DBCS conversion as a
means of entering double-byte data for inter-
active applications. Use the DDS keyword for
Effects of Displaying DBCS conversion (IGCCNV) to specify DBCS
DBCS-Graphic Fields on conversion in display files. Because DBCS
Double-Byte Displays display stations provide a variety of double-
byte data entry methods, you are not required
The following occurs when displaying to use the AS/400 DBCS conversion function
DBCS-graphic fields on a DBCS-graphic display to enter double-byte data.
without graphic capabilities.
Create double-byte messages to be used by
If a DBCS-graphic field is sent to a DBCS the program.
device without graphic capabilities, shift
Specify extended character processing so that
control characters are added to the field and
the system displays all double-byte data. See
one DBCS character is truncated from the end
“Extended Characters” on page D-4 for
of the field. For example, assume an output
instructions.
buffer contained the graphic characters
'ABCD', and also assume the characters are Determine whether additional double-byte
displayed on a device without graphic capabili- characters need to be defined. User-defined
ties. When the characters are displayed, they characters can be defined and maintained
appear as 'ABC' with shift control characters using the character generator utility (CGU).
at the beginning and end of the field. Information on CGU can be found in the
ADTS/400: Character Generator Utility book.
If the program is displaying an output
DBCS-graphic field one character long, the Make sure that the double-byte data is always
field is displayed with 2 null characters. This processed in a double-byte unit and do not
is because a DBCS field needs to be defined split a double-byte character.
at least 4 bytes long to allow room for the shift Double-byte characters displayed on a DBCS
control characters and a DBCS character. display that are located at the end of the
If the program is displaying an input column and that do not allow room for the
DBCS-graphic field 1 character long, message shift-out character, are not included in the
CPF501F will be sent to the calling program. print of the display. This is because shift
The message explains that an incorrect field characters have to be matched for each
length caused the output operation to fail. printed line when the print key is pressed.
Ensure that DBCS input capable fields sent to
the DBCS device are at least 4 bytes long.

Changing Alphanumeric attached to display stations, 5227
Model 1 Printer, and the 5327 Model
Application Programs to DBCS 1 Printer.
Application Programs
QIGC2424C A Traditional Chinese DBCS font
If an alphanumeric application program uses table used to print extended charac-
externally described files, you can change that ters in a 24-by-24 dot matrix image.
application program to a DBCS application The system uses the table with the
program by changing the externally described 5227 Model 3 Printer and the 5327
files. To convert an application program, do the Model 3 Printer.
following: QIGC2424K A Korean DBCS font table used to
1. Create a duplicate copy of the source state- print extended characters in a
ments for the alphanumeric file that you want 24-by-24 dot matrix image. The
to change. system uses the table with the 5227
Model 2 Printer and the 5327 Model
2. Change alphanumeric constants and literals to 2 Printer.
double-byte constants and literals.
QIGC2424S A Simplified Chinese DBCS font
3. Change fields in the file to the open (O) data table used to print extended charac-
type or specify the Alternative Data Type ters in a 24-by-24 dot matrix image.
(IGCALTTYP) DDS keyword so that you can The system uses the table with the
enter both double-byte and alphanumeric data 5227 Model 5 Printer.
in these fields. You may want to change the
length of the fields as the double-byte data QIGC3232 A Japanese DBCS font table used to
takes more space. print characters in a 32-by-32 dot
matrix image. The system uses the
4. Store the converted file in a separate library. table with the 5583 Printer and the
Give the file the same name as its alphanu- 5337 Model 1 Printer.
meric version.
QIGC3232S A Simplified Chinese DBCS font
5. When you want to use the changed file in a table used to print characters in a
job, change the library list, using the Change 32-by-32 dot matrix image. The
Library List (CHGLIBL) command, for the job system uses the table with the 5337
in which the file will be used. The library in Model R05 Printer.
which the DBCS display file is stored is then
checked before the library in which the alpha- All DBCS font tables have an object type of
numeric version of the file is stored. *ICGTBL. You can find instructions for adding
user-defined characters to DBCS font tables in the
the ADTS/400: Character Generator Utility book.
DBCS Font Tables
DBCS font tables contain the images of the
Finding Out if a DBCS Font Table
double-byte extended characters used on the Exists
system. The system uses these images to display
and print extended characters. Use the Check DBCS Font Table (CHKIGCTBL)
command to find out if a DBCS font table exists in
The following DBCS font tables are objects that your system.
you can save or restore. These font tables are
distributed with the DBCS national language ver- For example, to find out if the table QIGC2424
sions of the OS/400 licensed program: exists, enter:
CHKIGCTBL IGCTBL(QIGC2424)
QIGC2424 A Japanese DBCS font table used to
display and print extended charac-
If the table does not exist, the system responds
ters in a 24-by-24 dot matrix image.
with a message. If the table does exist, the
The system uses the table with
system simply returns without a message.
Japanese display stations, printers

Check for the existence of a table when adding a To copy the DBCS font table QIGC2424
new type of DBCS display station to make sure onto diskettes, enter:
that the table used by the device exists in the CPYIGCTBL IGCTBL(QIGC2424) OPTION(\OUT) DEV(QDKT)
system.
To copy just the user-defined characters
from DBCS font table QIGC2424 onto
Copying a DBCS Font Table onto tape, enter:
Tape or Diskette CPYIGCTBL IGCTBL(QIGC2424) OPTION(\OUT) +
DEV(QTAPð1) SELECT(\USER)
Use the Copy DBCS Font Table (CPYIGCTBL)
command to copy a DBCS font table onto tape or 4. Press the Enter key. The system copies the
diskette. DBCS font table onto the specified media.
Copy a DBCS font table onto tape or diskette in 5. Remove the tape or diskette after the system
the following instances: finishes copying the table.
Before deleting that table.
After new user-defined characters are added Copying a DBCS Font Table from
to the tables. Tape or Diskette
When planning to use the tables on another
system. Use the Copy DBCS Font Table (CPYIGCTBL)
command to copy a DBCS font table from a tape
The DBCS font tables are saved when you use or a diskette onto the system. The system auto-
the Save System (SAVSYS) command so you do matically creates the DBCS font table again when
not have to use the CPYIGCTBL command when copying its contents if the following are true:
performing normal system backup.
The specified table does not already exist in
the system.
How to Copy a Table onto Tape or The media from which you are copying the
Diskette: To copy a DBCS font table onto a table contains all of the IBM-defined double-
tape or diskettes, do the following: byte characters.
SELECT(*ALL) or SELECT(*SYS) is specified
1. Make sure that you have a tape or diskettes
on the CPYIGCTBL command.
initialized to the *DATA format. If necessary,
specify the FMT(*DATA) parameter on the Ini-
tialize Diskette (INZDKT) command to let0the How to Copy a Table from a Tape or
system prepare the tape or diskettes. Diskette: To copy a DBCS font table from tape
or diskette onto the system:
2. Load the initialized tape or diskette onto the
system. 1. Load the removable media from which the
table will be copied onto the system.
3. Enter the CPYIGCTBL command as follows:
2. Enter the CPYIGCTBL command as follows:
a. Choose the value OPTION(*OUT). a. Choose the OPTION(*IN) value.
b. Use the DEV parameter to select the b. Use the DEV parameter to select the
device to which you want to copy the device from which to copy the DBCS font
table. table.
c. Use the SELECT and RANGE parameters c. Use the SELECT and RANGE parameters
to specify which portion of the table you to specify which portion of the table will be
want copied from the system. See the copied from the tape or diskette. See the
description of the CPYIGCTBL command CL Reference for a description of the
in the CL Reference for instructions on CPYIGCTBL command and for
choosing SELECT and RANGE parameter instructions on choosing SELECT and
values. RANGE parameter values.
The following are two examples of the The following are two examples of commands
CPYIGCTBL command used to copy a DBCS used to copy a DBCS font table to the system.
font table to removable media.

To copy the DBCS font table QIGC2424 Warning: Do not delete a DBCS font table if any
from diskette, enter: device using that table is currently varied on.
CPYIGCTBL IGCTBL(QIGC2424) OPTION(\IN) + Also, make sure that the affected controller is not
DEV(QDKT) varied on. If you try to delete the table while the
device and controller are varied on, the system
To copy just the user-defined characters reports any devices attached to the same
from DBCS font table QIGC2424 from controller(s) as those devices, and the controller(s)
tape and to replace the user-defined char- as damaged the next time you try to print or
acters in the table with the ones from the display extended characters on an affected
tape, enter: device. If such damage is reported, do the fol-
CPYIGCTBL IGCTBL(QIGC2424) OPTION(\IN) + lowing:
DEV(QTAPð1) SELECT(\USER) RPLIMG(\YES)
1. Vary off the affected devices, using the Vary
3. Press the Enter key. The system copies the Configuration (VRYCFG) command.
DBCS font table from the tape or diskette onto 2. Vary off the affected controller.
the system. 3. Vary on the affected controller.
4. Remove the tape or diskette after the system 4. Vary on the affected devices.
finishes copying the table. 5. Continue normal work.
Deleting a DBCS Font Table Starting the Character Generator

Utility
Use the Delete DBCS Font Table (DLTIGCTBL)
command to delete a DBCS font table from the You must use the character generator utility
system. (CGU) to regenerate the font tables. Use the
STRCGU command to start the character gener-
Delete an unused DBCS font table to make more ator utility. You may call the CGU main menu or
storage space available. For example, if you do specify a specific CGU function, depending on the
not plan to use Japanese printer 5583 or 5337 parameter used. Refer to the ADTS/400: Char-
with your system, DBCS font table QIGC3232 is acter Generator Utility book for more information.
not needed and can be deleted.
Copying User-Defined
How to Delete a DBCS Font Table: To
delete a table, do the following: Double-Byte Characters
1. If desired, copy the table onto tape or Use the STRFMA command to copy user-defined
diskettes. See “Copying a DBCS Font Table double-byte characters between an AS/400 DBCS
onto Tape or Diskette” on page D-9 for font table and a user font file at a Personal
instructions. If you do not copy the table to System/55, a 5295 Display Station, or an
removable media before deleting it, you will InfoWindow 3477 Display Station.
not have a copy of the table for future use.
2. Vary off all devices using that table.
DBCS Font Files
3. Enter the DLTIGCTBL command.
For example, to delete the DBCS font table In addition to the system-supplied DBCS font
QIGC3232, enter: tables, the system also provides DBCS font files.
These DBCS font files are physical files which
DLTIGCTBL IGCTBL(QIGC3232)
contain frequently used double-byte characters.
4. Press the Enter key. The system sends When using the character generator utility, you
inquiry message CPA8424 to the system can use the characters in these files as the base
operator message queue for you to confirm for a new user-defined character. These files are
your intention to delete a DBCS font table. supplied with read-only authority as they are not to
be changed. If you do not use the character gen-
5. Respond to the inquiry message. The system
erator utility or the Advanced DBCS Printer
sends you a message when it has deleted the
table.

Support/400 licensed program, you may delete QCGACTV A Japanese DBCS active sort table
these files to save space. They all exist in the used to store the sort collating
QSYS library. sequences for the Japanese double-
byte character set.
The following DBCS font files are distributed with
QCGMSTRC A Traditional Chinese DBCS master
the DBCS national language versions of the
sort table used to store the sort infor-
OS/400 licensed program. They are used as a
mation for the Traditional Chinese
reference for the CGU and the Advanced DBCS
double-byte character set.
Printer Support/400 licensed program.
QCGACTVC A Traditional Chinese DBCS active
QCGF2424 A Japanese DBCS font file used to
sort table used to store the sort col-
store a copy of the Japanese DBCS
lating sequences for the Traditional
basic character images.
Chinese double-byte character set.
QCGF2424K A Korean DBCS font file used to
QCGACTVK A Korean DBCS active sort table
store a copy of the Korean DBCS
used to map Hanja characters to
basic character images.
Hangeul characters with equivalent
QCGF2424C A Traditional Chinese DBCS font file pronunciation.
used to store a copy of the Tradi-
QCGMSTRS A Simplified Chinese DBCS master
tional Chinese DBCS basic character
sort table used to store the sort infor-
images.
mation for the Simplified Chinese
QCGF2424S A Simplified Chinese DBCS font file double-byte character set.
used to store a copy of the Simpli-
QCGACTVS A Simplified Chinese DBCS active
fied Chinese DBCS basic character
sort table used to store the sort col-
images.
lating sequences for the Simplified
Chinese double-byte character set.
DBCS Sort Tables You may sort Japanese, Korean, Simplified
Chinese, and Traditional Chinese double-byte
DBCS sort tables contain the sort information and
characters. Each of these languages has two
collating sequences of all the double-byte charac-
DBCS sort tables, a DBCS master sort table and
ters used on the system. The system uses these
a DBCS active sort table, except for Korean which
tables to sort double-byte characters using the
has only a DBCS active sort table. The DBCS
sort utility.
master sort table contains sort information for all
defined DBCS characters. The DBCS active sort
DBCS sort tables are objects that you can save,
table for Japanese, Simplified Chinese, and Tradi-
restore, and delete. Using the character generator
tional Chinese is created from the master sort
utility you can also add, delete, and change
table information and contains the collating
entries in these tables corresponding to the image
sequences for the double-byte characters of that
entries in the DBCS font tables. For Japanese
given language. These collating sequences have
use only, you can also copy the DBCS master sort
a purpose similar to the EBCDIC and ASCII col-
table to and from a data file.
lating sequences for the single-byte alphanumeric
The following DBCS sort tables are distributed character set. For Korean characters, the
with the DBCS national language versions of the Hangeul characters are assigned both their col-
OS/400 licensed program: lating sequence as well as their DBCS codes
according to their pronunciation. Hence, a sepa-
QCGMSTR A Japanese DBCS master sort table rate collating sequence is not required, and each
used to store the sort information for of the Hanja characters is mapped to a Hangeul
the Japanese double-byte character character of the same pronunciation using the
set. DBCS active sort table QCGACTVK.
All DBCS sort tables have an object type of

*IGCSRT.

Using DBCS Sort Tables on the When to Save a DBCS Sort Table onto
System Tape or Diskette: Save a DBCS sort table
onto tape or diskette in the following instances:
You can save the tables to tape or diskette, delete Before deleting that table
them from the system, and restore them to the After information is added, updated, or
system. The Japanese DBCS master sort table changed in the tables using the character gen-
can also be copied to a data file and copied from erator utility
a data file so that it can be shared with a When planning to use the tables on another
System/36 or Application System/Entry* (AS/Entry) AS/400 system
system. You can also add sort information for
each user-defined character, and add that char-
acter to the DBCS collating sequence, as you Restoring a DBCS Sort Table
create it using the character generator utility. from Tape or Diskette
Use the RSTOBJ command to restore a DBCS
Finding Out if a DBCS Sort Table sort table from a tape or a diskette onto the
Exists system. The tables on the tape or diskette must
previously have been saved using the SAVOBJ
Use the Check Object (CHKOBJ) command to find command. Specify *IGCSRT for the object type.
out if a DBCS sort table exists in your system. The system automatically re-creates the DBCS
sort table when the specified table does not
For example, to find out if the table QCGMSTR
already exist in the system.
exists, enter:
CHKOBJ OBJ(QSYS/QCGMSTR) OBJTYPE(\IGCSRT) These tables must be restored to the QSYS library
for the system to know they exist. For that
If the table does not exist, the system responds reason, RSTOBJ restores *IGCSRT objects only
with a message. If the table does exist, the to the QSYS library and only if the objects do not
system simply returns without a message. already exist there.
Check for the existence of a DBCS active sort

table when you want to sort double-byte charac-
Copying a Japanese DBCS
ters for the first time. The DBCS active table for Master Sort Table to a Data File
the DBCS language must exist to sort the charac-
ters. Through the character generator utility, use the
CPYIGCSRT command to copy the Japanese
DBCS master sort table (QCGMSTR) to a data
Saving a DBCS Sort Table onto file. This data file can then be moved to a
Tape or Diskette System/36 system or AS/Entry system to replace
the Japanese master sort table there.
Use the Save Object (SAVOBJ) command to save
a DBCS sort table onto tape or diskette. Specify
When to Copy the Japanese DBCS
*IGCSRT for the object type.
Master Sort Table to a Data File: Copy
The DBCS sort tables are saved when you use the Japanese DBCS master sort table to a data
the SAVSYS command so you do not have to use file in the following instances:
the SAVOBJ command when performing normal When planning to move the table to a
system backup. System/36 or AS/Entry system for use there.
You should always transport the Japanese
DBCS master sort table together with the
Japanese DBCS font tables.
Before deleting that table, as an alternative to
the SAVOBJ command. You can then keep
the file or save it on diskette or tape.

How to Copy the Japanese DBCS When to Copy the Japanese DBCS
Master Sort Table to a Data File Master Sort Table from a Data File:
Note: In this section, the AS/Entry system also You may use the System/36 Migration Aid to
migrate the System/36 or AS/Entry system master
applies to every instance of System/36.: To copy
sort file (#KAMAST) to the AS/400 system. When
the Japanese DBCS master sort table to a data
you migrate the #KAMAST file using the
file, do the following:
System/36 Migration Aid, you do not have to use
1. Decide what data file you want to copy it to. the CPYIGCSRT command.
The file need not exist, it will be automatically
created. Copy the Japanese DBCS master sort table from
a data file in the following instances:
2. Enter the CPYIGCSRT command as follows:
When you do not use the System/36 Migration
a. Choose the value OPTION(*OUT).
Aid, you may copy the #KAMAST file from the
b. Use the FILE parameter to specify the
System/36 or AS/Entry system to the AS/400
name of the data file to which you want to
system. Then use the CPYIGCSRT command
copy the master table. If you are trans-
to copy sort information from the #KAMAST
porting the master table to the System/36
file to the AS/400 master sort table
for use there, you should specify a file
(QCGMSTR). Delete the #KAMAST file from
name of #KAMAST, or you will have to
the AS/400 system after you complete the
rename the file when you get it to the
copy operation.
System/36. Use the AS/400 CPYF
command for copying the file onto When you have copied a version of the
diskette, and the System/36 TRANSFER master table to a data file and you now want
command for copying the file from diskette to restore that version.
to the System/36.
c. Use the MBR parameter to specify the You should always migrate or copy the
name of the data file member to which Japanese DBCS master sort table together
you want to copy the master table. If you with the Japanese DBCS font tables.
are transporting the master table to the
System/36 for use there, you should How to Copy the Japanese DBCS
specify *FILE for the MBR parameter. Master Sort Table from a Data File: To
3. Press the Enter key. The system creates the copy the Japanese DBCS master sort table from a
file and member if they do not exist, and data file, do the following:
writes over the existing member if it does 1. Enter the CPYIGCSRT command as follows:
exist.
a. Choose the value OPTION(*IN).
4. If you now transport this file to your System/36 b. Use the FILE parameter to specify the
to replace the #KAMAST file there, you should name of the data file that contains a
also use the SRTXBLD procedure to update migrated System/36 or AS/Entry system
the active table to reflect the new master master file or an AS/400 master table pre-
table. viously copied to the file using
OPTION(*OUT) with the CPYIGCSRT
Copying a Japanese DBCS command. To migrate your System/36 or
Master Sort Table from a Data AS/Entry system master file without using
the System/36 Migration Aid, use the
File TRANSFER command with the IFORMAT
Use the CPYIGCSRT command to copy the parameter on the System/36 or AS/Entry
Japanese DBCS master sort table (QCGMSTR) system to save the #KAMAST master file
from a data file. on diskette. Use the AS/400 Copy File
(CPYF) command to copy the master file
#KAMAST from diskette. Use the
CPYIGCSRT command as described here

to copy data from the file to the AS/400 For example, to delete the DBCS sort table
Japanese DBCS master sort table. QCGACTV, enter:
c. Use the MBR parameter to specify the DLTIGCSRT IGCSRT(QCGACTV)
name of the data file member from which
you want to copy the master table data. 3. Press the Enter key. The system sends you a
message when it has deleted the table.
2. Press the Enter key. Even though the infor-
mation in the existing Japanese DBCS master
sort table is overridden, that table must exist DBCS Conversion Dictionaries
before you can use this command.
3. To update the Japanese DBCS active table to The DBCS conversion dictionary is a collection of
reflect the new copied information, use the alphanumeric entries and their related DBCS
SRTXBLD procedure in the System/36 or words. The system refers to the dictionary when
AS/Entry system environment, or the performing DBCS conversion. See “How DBCS
STRCGU command specifying OPTION(5). Conversion Works” on page D-20 for information
This must be done before you can use the on how the system uses the DBCS conversion
sort utility to sort Japanese double-byte char- dictionary during DBCS conversion.
acters.
All DBCS conversion dictionaries have an object
type of *IGCDCT. A system-supplied and a user-
Deleting a DBCS Sort Table created dictionary are used with DBCS conver-
sion.
Use the DLTIGCSRT command to delete a DBCS
sort table from the system.
System-Supplied Dictionary (for
When to Delete a DBCS Sort Table: Japanese Use Only)
Delete an unused DBCS sort table to free disk
QSYSIGCDCT, the system-supplied dictionary that
space, but you should always first save a copy of
is stored in the library, QSYS, is a collection of
the table using the SAVOBJ command. You
entries with a Japanese pronunciation expressed
should delete the DBCS master sort table for a
in alphanumeric characters and the DBCS words
DBCS language if any of the following are true:
related to those entries. The system checks this
1. You will not be creating any new characters dictionary second when performing DBCS conver-
for that language using the character gener- sion.
ator utility.
QSYSIGCDCT contains these entries:
2. You will not be using the sort utility to sort
characters for that language. Personal names
You should delete the DBCS active sort table for a – Family names
DBCS language if you will not be using the sort – First names
utility to sort characters for that language. The
Organization names
DBCS active sort table must be on the system to
use the sort utility for this language. – Private enterprises registered in the secu-
rity market
How to Delete a DBCS Sort Table To – Public corporations
delete a table, do the following: – Typical organizations in the central and
local governments
1. If desired, save the table onto tape or – Most universities and colleges
diskettes. See “Saving a DBCS Sort Table
onto Tape or Diskette” on page D-12 for Addresses
instructions. If you do not save the table onto – Public administration units within the
removable media before deleting it, you will prefectures
not have a copy of the table for future use. – Towns and streets in 11 major cities
2. Enter the DLTIGCSRT command.

Business terms, such as department names DMPSYSOBJ: Dump the system-supplied
and position titles commonly used in enter- dictionary
prises DSPOBJAUT: Display a user’s authority to
the dictionary
Individual double-byte characters, including
GRTOBJAUT: Grant authority to use the dic-
basic characters, as defined by IBM
tionary
You cannot add or delete entries from this dic- MOVOBJ: Move the dictionary to another
tionary. However, you may rearrange the related library
DBCS words so that the words used most fre- RNMOBJ: Rename the dictionary
quently are displayed first during DBCS conver- RSTOBJ: Restore the dictionary
sion. See “Editing a DBCS Conversion Dictionary” RVKOBJAUT: Revoke authority to use the
on page D-16 for instructions on rearranging dictionary
terms. SAVCHGOBJ: Save a changed dictionary
SAVOBJ: Save the dictionary
User-Created Dictionary The system saves or restores DBCS conversion

dictionaries when you use these commands:
A user-created dictionary contains any alphanu-
meric entries and related DBCS words that you RSTLIB: Restore a library in which the dic-
choose to include. You might create a user dictionary is stored
tionary to contain words unique to your business SAVLIB: Save a library in which the dic-
or words that you use regularly but that are not tionary is stored
included in the system-supplied dictionary. SAVSYS: Save QSYSIGCDCT, the system
DBCS conversion dictionary, when saving the
You can create one or more DBCS conversion system
dictionaries with any name and store them in any
library. When performing DBCS conversion, Creating a DBCS Conversion Dic-
however, the system only refers to the first user tionary: To create a DBCS conversion dic-
dictionary named QUSRIGCDCT in the user’s tionary, do the following:
library list, no matter how many dictionaries you
have or what they are named. Make sure that the 1. Use the Create DBCS Conversion Dictionary
library list is properly specified so that the system (CRTIGCDCT) command.
checks the correct dictionary. 2. Name the dictionary, QUSRIGCDCT, so it can
be used during DBCS conversion. The
During DBCS conversion, the system checks system uses the dictionary if it is the first user-
QUSRIGCDCT before checking QSYSIGCDCT. created dictionary found when searching a
user’s library list.
Commands for DBCS Conversion You might call the dictionary by another name
Dictionaries while it is being created to prevent application
programs from using it for conversion. Later,
You can use the following commands to perform change the dictionary name using the
object management functions with the DBCS con- Rename Object (RNMOBJ) command.
version dictionary. Specify the
OBJTYPE(*IGCDCT) parameter when entering For example, to create a user DBCS conver-
these commands: sion dictionary to be stored in the library
DBCSLIB, enter:
CHGOBJOWN: Change the owner of a
DBCS conversion dictionary CRTIGCDCT IGCDCT(DBCSLIB/QUSRIGCDCT)
CHKOBJ: Check a DBCS conversion dic- 3. Use the EDTIGCDCT command to put entries
tionary and related words into the dictionary after cre-
CRTDUPOBJ: Create a duplicate object of ating it. See “Editing a DBCS Conversion
the dictionary Dictionary” on page D-16 for instructions on
DMPOBJ: Dump a DBCS conversion dic- putting entries in the dictionary.
tionary

Editing a DBCS Conversion created). The dictionary can contain as many
Dictionary: Use the Edit DBCS Conversion as 99,999 entries.
Dictionary (EDTIGCDCT) command to edit the Delete entries from the dictionary.
DBCS conversion dictionary. Use editing to add Change entries in the dictionary, such as
user-defined characters to the dictionary, so that replacing the DBCS words related to an
users can enter characters using DBCS conver- alphanumeric entry.
sion, and rearrange terms in a DBCS conversion Move the DBCS words related to an alphanu-
dictionary to suit individual needs. meric entry to rearrange the order in which
they appear during DBCS conversion.
Requirements for a DBCS Conversion Dic-
tionary: The display station needed for use while The only editing function that you can perform with
editing the DBCS conversion dictionary depends QSYSIGCDCT, the system-supplied dictionary, is
on the value that you entered for the ENTRY to move DBCS words related to an alphanumeric
parameter on the EDTIGCDCT command: entry. Move words in order to rearrange the order
in which they appear during DBCS conversion.
If you specified a specific string with the
ENTRY parameter or if you want to display Displays Used for Editing a DBCS Conversion
double-byte characters, you must use a DBCS Dictionary: After you enter the EDTIGCDCT
display station. command, the system presents either the Work
If you did not specify a specific string with the With DBCS Conversion Dictionary display or the
ENTRY parameter, or if you do not want to Edit Related Words display, depending on the
display double-byte characters, use either a value entered for the ENTRY parameter on the
DBCS display station, or a 24-row by command.
80-column alphanumeric display station.
Work with DBCS Conversion Dictionary Display:
DBCS Conversion Dictionary Operations: You Use this display to work with alphanumeric entries,
may perform the following editing operations on a such as choosing an entry to edit or deleting an
user-created DBCS conversion dictionary: entry. The system displays the Work with DBCS
Conversion Dictionary display if you enter *ALL or
Add entries to the dictionary (including adding a generic string for the ENTRY parameter of the
the first entries to the dictionary after it is EDTIGCDCT command.
HRSLS332-1
See the discussion of the EDTIGCDCT command the Work with DBCS Conversion Dictionary
in the CL Reference for a complete description of display.

Edit Related Words Display: Use this display to Edit Related Words display if you choose an entry
work with the DBCS words related to an alphanu- to edit from the Work with DBCS Conversion Dic-
meric entry. The system displays the Edit Related tionary display. Following is an example of the
Words display if you enter a specific string for the Edit Related Words display:
ENTRY parameter. The system also displays the
HRSLS328-2
See the discussion of the EDTIGCDCT command Adding the First Entries in a Dictionary: To
in the CL Reference for a complete description of add the first entries into a dictionary, do the fol-
the Edit Related Words display. lowing:
1. Specify ENTRY(*ALL) when entering the
Examples of Editing Operations: The following
EDTIGCDCT command. For example, to edit
sections give examples of the editing operations
the dictionary QUSRIGCDCT stored in the
that you can perform using the EDTIGCDCT dis-
library DBCSLIB, enter:
plays:
EDTIGCDCT IGCDCT(DBCSLIB/QUSRIGCDCT) ENTRY(\ALL)
Beginning to edit a dictionary
Adding the first entries in a dictionary The system displays the Work with DBCS
Deleting an entry Conversion Dictionary display.
Moving a related word 2. Enter a 1 in the first option field in the list and
Ending editing the dictionary enter an alphanumeric entry to be added to
the dictionary in the entry field.
Beginning to Edit a Dictionary: Enter the
EDTIGCDCT command to start editing the dic- The system then displays the Edit Related
tionary for any type of editing operation. For Words display showing only two lines of data:
example, to put the first entry in the dictionary, BEGINNING OF DATA and END OF DATA.
enter: 3. Enter an I in the NBR field beside the
EDTIGCDCT IGCDCT(DBCSLIB/QUSRIGCDCT) ENTRY(\ALL) BEGINNING OF DATA line to insert a line.
4. Press the Enter key. The system displays a
Or, to edit the entries beginning with the string blank line.
ABC enter:
5. On the blank line, enter a DBCS word to be
EDTIGCDCT IGCDCT(DBCSLIB/QUSRIGCDCT) ENTRY('ABC\')
related to the new alphanumeric entry.
If you enter data on the inserted line and
leave the cursor on that line, another new line

appears below when you press the Enter key. Dictionary display. Enter option 1 again and
You can enter another DBCS word on this enter another alphanumeric entry in the entry
line, or delete it by leaving it blank, and field to continue adding entries to the dic-
pressing the Enter key. tionary, or press F3 to end editing the dic-
tionary.
6. When you finish adding this first entry, press
F12 to get the Exit Dictionary Entry display.
Deleting an Entry: Enter a 4 in the input field
Enter the Y option to save the entry and then
beside the entry to be deleted as follows:
return to the Work With DBCS Conversion
HRSLS331-2
Moving a Related Word: Moving the words Ending the Editing Process: To end the editing
related to an alphanumeric entry changes the operation, press F3. The Exit Dictionary Entry
order in which the words appear during DBCS display is displayed, and you can choose to save
conversion. To move a word, do the following: the entry or not. The system then returns you to
your basic working display, such as the Command
1. Display the Edit Related Words display for the
Entry display.
entry in which you want to move DBCS words,
either by entering a specific entry with the
Suggestions for Editing the Dictionary: When
EDTIGCDCT command, or by choosing an
editing the DBCS conversion dictionary, consider
entry to edit from the Work with DBCS Con-
the following:
version Dictionary display.
You can use DBCS conversion with the Edit
2. When the display appears, enter an M in the
Related Words display to enter related words
NBR field beside the DBCS word to be
into a user-created dictionary. See “DBCS
moved.
Conversion (for Japanese Use Only)” on
3. Enter an A in the NBR field of the line after page D-19 for information on this procedure.
which the word will be moved.
Place the most commonly used DBCS words
4. Press the Enter key. The system moves the at the beginning of the list of related words on
word, on the line marked M to a position imme- the Edit Related Words display. This simpli-
diately following the line marked with an A. fies DBCS conversion because the system
displays the related words in the same order
in which those words are listed in the dic-
tionary.

Displaying and Printing the DBCS DSPIGCDCT IGCDCT(DBCSLIB/QUSRIGCDCT) +
ENTRY(ABC) OUTPUT(\PRINT)
Conversion Dictionary
To display all of the entries from the system-
Use the Display DBCS Conversion Dictionary supplied dictionary QSYSIGCDCT and their
(DSPIGCDCT) command to display and print the related words, enter:
DBCS conversion dictionary. You can display or
print the entire dictionary or just a certain part of it, DSPIGCDCT IGCDCT(QSYS/QSYSIGCDCT)
depending on the value you specify for the
Following is an example of the display produced
ENTRY parameter.
by the DSPIGCDCT command. It shows alphanu-
For example, to print the entry ABC from the dic- meric entries and their related words.
tionary QUSRIGCDCT and its related words,
enter:
HRSLS337-2
See the discussion of the DSPIGCDCT command named QUSRIGCDCT, stored in their libraries. If
in the CL Reference for a complete description of you do not specify any library name, the system
the command and the display it produces. deletes the first DBCS conversion dictionary in
your library list.
Deleting a DBCS Conversion For example, to delete the DBCS conversion dic-
Dictionary tionary QUSRIGCDCT in the library DBCSLIB,
enter:
Use the Delete DBCS Conversion Dictionary
(DLTIGCDCT) command to delete a DBCS con- DLTIGCDCT IGCDCT(DBCSLIB/QUSRIGCDCT)
version dictionary from the system.
In order to delete the dictionary, you must have DBCS Conversion (for Japanese
object existence authority to the dictionary and Use Only)
object operational authorities to the library in
which the dictionary is stored. When you use DBCS display stations to enter
double-byte data, you may use the various data
When you delete a dictionary, make sure that you entry methods supported on the display station, or
specify the correct library name. It is possible that you may choose to use the AS/400 DBCS conver-
many users have their own dictionaries, each sion support. DBCS conversion lets you enter an

alphanumeric entry or DBCS code and convert the The system determines which words are related to
entry or code to its related DBCS word. DBCS an alphanumeric entry by checking DBCS conver-
conversion is intended for Japanese character sion dictionaries. The system checks two DBCS
sets and its use is limited for application to other conversion dictionaries when performing DBCS
double-byte character sets. conversion. It checks the first user-created dic-
tionary named QUSRIGCDCT found when
Specifically, DBCS conversion lets you convert the searching a user’s library list. Then, it checks the
following: system-supplied dictionary, QSYSIGCDCT, stored
A string of alphanumeric characters to a in the library QSYS. (QSYSIGCDCT contains only
DBCS word Japanese double-byte characters.) You can
English alphanumeric characters to double- create other user dictionaries, and you can give
byte alphanumeric characters them names other than QUSRIGCDCT, but the
Alphanumeric Katakana to double-byte system only refers to the first user-created dic-
Hiragana and Katakana letters tionary named QUSRIGCDCT found in your library
A DBCS code to its corresponding double- list when performing DBCS conversion.
byte character
After checking the dictionaries, the system dis-
A DBCS number to its corresponding double-
plays words related to the alphanumeric entry.
byte character
You then position the cursor under the word of
your choice, and press the Enter key. The system
Where You Can Use DBCS enters that word where the cursor was positioned
Conversion when you began DBCS conversion.
You can use DBCS conversion in the following

Using DBCS Conversion
instances:
When entering data into input fields of certain You can change the user-defined dictionary used
SEU displays. For information about which during DBCS conversion. Before you change the
fields you can use with DBCS conversion, user-defined dictionary, end your application
refer to the ADTS/400: Source Entry Utility. program or end the command that the system is
performing. Then change the dictionary that is
When prompting for double-byte data using
used by changing the library list (using the
QCMDEXEC. For instructions on this proce-
CHGLIBL command).
dure, see the CL Reference.
When entering data into input fields of DBCS You can create your own DBCS conversion dic-
display files in user-written applications. tionary for DBCS conversion. The system-
Specify DBCS conversion with the DDS supplied dictionary is a collection of entries with a
keyword IGCCNV. See the DDS Reference Japanese pronunciation expressed in alphanu-
for information on this keyword. meric characters and Japanese DBCS words
related to the entry. See “Creating a DBCS Con-
When editing the related words on the Edit
version Dictionary” on page D-15 for instructions
Related Words display, which is displayed
on this procedure.
when editing the DBCS conversion dictionary
(EDTIGCDCT command). See “Editing a If no user-created dictionary is found, the system
DBCS Conversion Dictionary” on page D-16 refers only to QSYSIGCDCT. See “DBCS Con-
for information on the Edit Related Words version Dictionaries” on page D-14 for more infor-
display. mation on creating and using DBCS conversion
dictionaries.
How DBCS Conversion Works
DBCS conversion is an interactive function
between you and the system in which you enter
an alphanumeric entry. The system displays
related DBCS words, and you choose which word
to use.

Performing DBCS Conversion No entry Converts the entry in field B
from alphanumeric to double-
The following procedure describes how to convert byte by referring to the DBCS
one alphanumeric entry to its related DBCS word conversion dictionaries.
using DBCS conversion. You must start DBCS G Converts the 2- to 5-digit
conversion separately for each field in which you DBCS number in field B to the
want to enter double-byte data. character it represents.
Note: DBCS conversion is intended for Japanese H Converts the entry in field B to
data entry. Its use with other languages is limited. double-byte Hiragana, upper-
case alphabetic, numeric, or
While performing DBCS conversion, you can special characters.
display information about the function by pressing
the Help key. Help is available until you end K Converts the entry in field B to
DBCS conversion. double-byte Hiragana, lower-
case alphabetic, numeric, or
1. Position the cursor in the field in which you special characters.
want to enter double-byte characters. Insert
shift-control characters into the field if they X Converts the 4-character
have not yet been inserted. To find out how DBCS code to the character it
to insert shift characters, see “Inserting Shift- represents.
Control Characters” on page D-6. 5. Press the Enter key. The system displays
2. Position the cursor under the shift-in char- words related to the entry in the second field.
acter, in a blank area between the shift-control If you see a plus (+) sign following the last
characters, or under a double-byte character. displayed word, the system has additional
3. Press the function key used to start DBCS words to display. Press the Roll Up key to
conversion. see these entries. Then, to return to a word
displayed earlier, press the Roll Down key.
In SEU, as well as from the Edit Related
Words display (displayed when using the If a word is shown in a reverse image, the
EDTIGCDCT command), press F18. word contains an imbedded blank.
4. Enter the following values: 6. Choose the DBCS word from the last field that
best suits your needs by positioning the cursor
a. In the first field, enter one of the following: under that DBCS word.
I Inserts the converted word before 7. Press the Enter key. The system enters the
the character under which you posi- word where the cursor was positioned in step
tioned the cursor in step 2. 2, either by inserting the word or by replacing
R Replaces the character under which another word, depending on what you entered
you positioned the cursor in step 2 in the first field.
with the converted word. 8. Do one of the following:
b. In the second field, enter one of the fol- a. Continue using DBCS conversion. Repeat
lowing: steps 4 through 7 until you finish entering
1) A string of alphanumeric characters to data into the field.
be converted. The string can have as b. End DBCS conversion by pressing the
many as 12 characters. same function key used to start conver-
2) The 4-character DBCS code of a sion. The system automatically ends the
double-byte character. conversion when you reach the end of the
field.
3) The 2- to 5-digit DBCS number of a
double-byte character. In SEU, as well as from the Edit Related
Words display (displayed when using the
c. In the third field, enter one of the following
EDTIGCDCT command), press F18.
conversion codes:

Note: Until DBCS conversion is ended, Converting One Alphanumeric Entry to a
you cannot perform any other system Double-Byte Entry: The following example
function. For example, the F3 key cannot shows how to convert one entry and enter it into a
be used to exit an SEU display. field.
1. Position the cursor in the field in which you
Examples want to enter double-byte data.
Position the cursor here.
HRSLS321-0
2. Insert shift-control characters into the field. 3. Press the function key used to start DBCS
See “Inserting Shift-Control Characters” on conversion. For the display just shown, the
page D-6 for instructions on inserting shift- function key is F18. The system displays a
control characters. prompt line.

Notice that shift control characters
have been inserted into the field.
HRSLS322-0
The prompt line.
Because the cursor was placed under a 4. Enter an alphanumeric entry to be converted
shift-in character when conversion was in the second field.
started, conversion automatically is set to I
Leave the third field blank.
(inserting the converted word).
HRSLS323-0
Enter an alphameric entry here.
5. Press the Enter key. The system displays 6. Position the cursor under the DBCS word that
related DBCS words. you want to enter, if that word is not the first

DBCS word shown. In the following example,
the first word is the one to be entered.
HRSLS324-0
Position the cursor here.
7. Press the Enter key. The DBCS word is

entered into the field.
The system enters the word into the field.
HRSLS325-0
Converting Many Alphanumeric Entries at One 1. Enter as many alphanumeric entries as will fit
Time: You do not have to continually start DBCS into field B. Separate each entry by a blank.
conversion for each alphanumeric entry. Instead, Field B contains space for 12 alphanumeric
you can do the following: characters:

These are the entries to be converted. Move the cursor here.
| | | |
I XXX_YYY_ZZZ_ _ XXXXXX
A B C D _ ____________ _ _________________________
A B C D
The system converts the entries one at a time,
in the order entered. When the system con- 2. Do one of the following:
verts an entry, the system displays the DBCS a. Position the cursor under the first position
words related to that entry in field D. of the field in which you want to enter
2. Position the cursor under the DBCS word that alphanumeric entries.
you want to use. b. Enter a different alphanumeric entry.
c. Change the conversion code in field C,
3. Press the Enter key. Then, the system
such as from H to K.
adjusts field B; the next entry is moved to the
position farthest left of the field. The DBCS 3. Press the Enter key.
words related to that entry are displayed in 4. Continue DBCS conversion.
field D.
At this time, you can enter additional alphanu- Using DBCS Conversion to Enter Words in the
meric entries to be converted at the end of DBCS Conversion Dictionary: You can use
field B. DBCS conversion when entering DBCS words on
the Edit Related Words display.
Converting Alphanumeric Blanks to DBCS
Blanks: You can convert alphanumeric blanks To start DBCS conversion, do the following:
(one position wide) to DBCS blanks (two positions 1. Position the cursor at the position where the
wide, the same width as double-byte characters) DBCS word is to be entered.
using DBCS conversion.
2. Press F18. The system displays the conver-
To convert blanks, do the following: sion prompt line at the bottom of the display.
1. Enter one or more blanks in field B. Perform DBCS conversion according to the
_ ____________ _ instructions described in “Performing DBCS
A B C D Conversion” on page D-21.
2. Press the Enter key. The system displays in Note: You must start and end DBCS conversion
field D the same number of DBCS blanks as separately for each line of data.
the alphanumeric blanks that you entered in
field B. The DBCS blanks are displayed in Considerations for Using DBCS Con-
reverse image.
version: Consider the following when per-
3. Press the Enter key again. The system enters forming DBCS conversion:
the DBCS blanks into the field where you
You can only perform DBCS conversion at a
started DBCS conversion.
DBCS display station, using the 5556 key-
board.
Changing Alphanumeric Entries or Conversion
Code: If none of the related words shown during You may use DBCS conversion to insert or
conversion are suitable candidates for the alpha- replace characters only if the line in which
numeric entry, and you would like to try a conver- double-byte characters are to be inserted has
sion again (by using a different type of conversion sufficient space.
or a different alphanumeric entry), do the fol-
– The space available for inserting charac-
lowing:
ters is equal to the number of characters
1. Move the cursor to field B. For example: from the last character on the line that is
not blank to the right edge of the display.
– The space available for replacing charac-
ters is equal to the number of characters
from the cursor position (including the

character marked by the cursor) to the – If you ignore the message and press the
end of the DBCS portion of the field. Enter key again, the system truncates the
characters in excess of the limit from the
The following happens when you do not have
right side of the string to be inserted or
enough space:
replaced.
– If you try to insert or replace a string of
characters where there is no space avail-
able, the system sends a message.

Appendix E. Display File Return Codes
This section contains descriptions of all major and condition that may be significant to your
minor return codes for display files. These return program even though it is not an error.
codes are set in the I/O feedback area of the
Messages:
display file. The return codes report the results of
each operation. The appropriate return code is CPF4ð18 (Status)
available to the application program that issued CPF4ð19 (Diagnostic)
the operation. The program then checks the CPF4ð54 (Diagnostic)
return code and acts accordingly. Refer to your CPF4ð82 (Diagnostic)
high-level language manual for information about CPF441ð (Diagnostic)
how to access these return codes. CPF5ðð3 (Status)
CPF55ð8 (Diagnostic)
The return code is a four-digit value: the first two
digits contain the major code, and the last two
digits contain the minor code. With some return Major Code 02
codes, a message is also sent to the job log or
the operator message queue (QSYSOPR). You
Major Code 02–Input operation completed
can refer to the message for additional informa-
successfully, but your job is being ended (con-
tion.
trolled).
Description: The input operation issued by
Major Code 00 your program was completed successfully.
However, your job is being ended (controlled).
Major Code 00–Operation completed suc- Action: Your program should complete its
cessfully. display processing as soon as possible to
allow your program to complete in an orderly
Description: The operation issued by your
manner. The system eventually changes a job
program completed successfully.
ended (controlled) to a job ended (immediate)
Action: Continue with the next operation. and forces all processing to stop for your job.
Code Description/Action Code Description/Action

0000 Description: For input operations per- 0200 Description: On a successful input oper-
formed by your program, 0000 indicates ation, an indication was received that a
that some data was received on a suc- job ended (controlled) request is pending.
cessful input operation. Also, 0200 indicates that some data was
received.
For output operations performed by your
program, 0000 indicates that the last Action: Your program may continue.
output operation completed successfully. However, the recommended action is to
complete the display processing and end
Action: Your program may continue.
the program, because the system will
One of the messages listed below may
eventually cancel your job and cause all
have been issued to warn of an unusual
processing to stop for your job.
 Copyright IBM Corp. 1997 E-1

This return code is only applicable to the
Major Code 03 read-from-invited-devices operation.
Note: Because no device is associated
Major Code 03–Input operation completed with the completion of this operation, the
successfully, but no data received. device name in the I/O feedback area
Description: The input operation was com- contains an *N.
pleted successfully, but no data was received. Action: Issue the operation to perform
Action: Check the minor return code for addi- the intended function after the specified
tional information, and continue with the next time interval has ended. For example, if
operation. you are using the time interval to control
the length of time to wait for data, you can
then issue another read-from-invited-
Code Description/Action
devices operation to receive the data.
0300 Description: No data was received on a
Messages:
successful input operation. Examples of
conditions causing this are no data being CPF4742 (Status)
available on a get-relative or a get-next- CPF4743 (Status)
changed operation to a subfile record
format.
Action: Continue with whatever pro-
Major Code 04
cessing is appropriate. For example, if
your program issued a get-next-changed Major Code 04–Output exception occurred.
operation to a subfile record format, then Description: An output exception occurred
a 0300 indicates that there are no more because your program attempted to send
subfile records changed by the user and output when it should have been receiving the
no more user input data to process. data that had already been sent by the
Messages: display. Your data, associated with this output
operation, was not sent to the display. Your
CPF5ð17 (Notify)
program can attempt to send its output later.
CPF5ð2ð (Notify)
CPF5ð37 (Notify) Action: Issue an input operation to receive
the data.
0309 Description: Your program is being
ended (controlled). No data was received.
This return code is only applicable to the
read-from-invited-devices operation. 0412 Description: An output exception
occurred because your program attempted
Action: Your program can continue pro-
to send data when it should have been
cessing. However, the recommended
receiving the data that had already been
action is to complete the display pro-
sent by the display. Your program data
cessing and end the program, because
was not sent and should be sent later,
the system will eventually cancel your job
after the data from the display has been
and cause all processing to stop for your
received.
job.
Action: Issue an input operation to
Messages:
receive the data.
CPF4741 (Notify)
Messages:
0310 Description: The time interval specified
CPF4737 (Notify)
by the WAITRCD value for the display file
has ended.
E-2 Application Display Programming V4R1

Major Codes 08–11
3431 Description: The input operation issued
by your program was not successful
Major Codes 08 and 11–Miscellaneous because the length of the data received
program errors occurred. from the display exceeds the receive data
Description: The operation just attempted by length specified in the user-defined data
your program was not successful. The opera- stream. The data received is truncated.
tion may have failed because it was issued at This return code is only applicable to input
the wrong time. operations using a record format speci-
Action: Refer to the individual return code fying a user-defined data stream
descriptions for the appropriate recovery (USRDFN DDS keyword).
actions. Action: Close the device file and end
your program. Then, change your
Code Description/Action program so that the input record length is
at least as long as the data record to be
0800 Description: The acquire operation just
received.
performed was not successful. It tried to
acquire a device that had already been Messages:
acquired. CPF5ð62 (Notify)
Action: If the display device requested
by the original acquire operation is the
one needed, your program can begin Major Code 80
using it because it is already available. If
a different device is required, issue Major Code 80–Permanent system or file
another acquire operation for a different error (not recoverable).
device name.
Description: A file or system error that is not
Messages: recoverable has occurred. Recovery is
CPD4ð77 (Diagnostic) unlikely until the problem causing the error has
CPF5ðAð (Status) been corrected.
1100 Description: The read-from-invited- Action: The following general actions can be
devices operation was not successful taken by your program for each 80xx return
because no devices were invited. code. Other specific actions are given in each
return code description.
Action: Issue an invite function followed
by a read-from-invited-devices operation. Continue processing without the display.
Close the device file and open the file
Messages:
again. If the operation is still unsuc-
CPF474ð (Notify) cessful, try it again only a limited number
of times. (The number of times should be
specified in your program.)
Major Code 34 End.
Major Code 34–Input exception occurred. Code Description/Action

Description: The input operation attempted 8081 Description: The operation was not suc-
by your program was not successful. The cessful because a system error condition
data received was too long for the record was detected.
format specified on the input operation. Action: Your display device may need to
Action: Refer to the individual return code be varied off and then on again. Your
descriptions for the appropriate recovery program can either:
actions.
Appendix E. Display File Return Codes E-3

Continue processing without the tion. This may be the result of a device
display device. configuration error. The device may be
Close the device file and open the file unusable. No operations should be
again. issued to the device.
End.
Action: Refer to the device response
Messages: code in the accompanying error message
to determine the cause of the failure.
CPF4182 (Escape) CPF5416 (Escape)
Vary the device off and then on again to
CPF451ð (Escape) CPF5418 (Escape)
reset the error. Correct the error and try
your program again.
CPF54ð3 (Escape) CPF5431 (Escape) Messages:
CPF54ð4 (Escape) CPF5433 (Escape)
CPF4527 (Escape)
CPF54ð8 (Escape) CPF5441 (Escape) 80B3 Description: The open operation was not
CPF54ð9 (Escape) CPF5447 (Escape) successful because the display file is not
CPF541ð (Escape) CPF5455 (Escape) available. The file cannot be opened
CPF5411 (Escape) CPF5456 (Escape) again until the necessary resources are
CPF5414 (Escape) CPF55ð7 (Escape) available.
CPF5415 (Escape) Action: Your program can wait for the
8082 Description: The operation was not suc- display file to become available, then
cessful because the display device is issue another open operation. Otherwise,
unusable. This may occur because a you may continue other processing or end
cancel reply has been taken to an error the program.
recovery message for the device or Consider increasing the WAITFILE param-
because the display has been held by a eter with the Change Display File
Hold Communications Device (CHGDSPF) command or Override with
(HLDCMNDEV) command. No operations Display File (OVRDSPF) command to
should be issued to the device. allow more time for the file to become
Action: Communications with the display available.
cannot be resumed until the device has Messages:
been reset to a varied-on state. If the
device has been held, use the Release CPF4128 (Escape)
Communications Device (RLSCMNDEV) 80C0 Description: An error that is not recover-
command to reset the device. If the able has occurred on the display device.
device is in an error state, vary the device
off and then on again. Once the device is Action: Your display devices may need
reset, normal operation can be started by to be varied off and then on again. Your
opening the display device file again. program can either:
Your program can either: Continue processing without the
Continue processing without the display station.
display device. Close the device file and open the file
Close the device file and open the file again.
again. End.
End. Messages:
Messages: CPF51ð3 (Escape) CPF542ð (Escape)
CPF4354 (Escape) CPF5192 (Escape) CPF5421 (Escape)
CPF5269 (Escape) CPF5412 (Escape) CPF543ð (Escape)
80A6 Description: A Systems Network Archi- CPF5419 (Escape) CPF5439 (Escape)
tecture (SNA) unbind operation was not
successful on a close or release opera-

80EB Description: An open operation was not
Major Code 81–Permanent device error (not
successful because an open option that is
recoverable).
not valid or a combination of options that
is not valid was specified in your program, Description: A device-related error that is not
in the display file, or in an override recoverable occurred during an I/O operation.
command. Any attempt to continue using this display
device will probably fail again until the cause
Action: Close the display file, correct the
of the problem is found and corrected, but
problem, and open the file again. See the
operations directed to other display devices
individual messages to determine what
associated with the file should be expected to
options are not valid.
work.
Messages:
Action: The following general actions can be
CPF4ð62 (Escape) CPF4345 (Escape) taken for each 81xx return code. Other spe-
CPF4129 (Escape) CPF5151 (Escape) cific actions are given in each return code
CPF4148 (Escape) CPF551ð (Escape) description.
Continue processing without the display
device.
Release the device or close the file,
correct the problem, and acquire the
CPF4238 (Escape)
device again or open the file. If the opera-
80ED Description: The open operation was not tion is still unsuccessful, try it again only a
successful because the record format limited number of times. (The number of
descriptions in the file have changed since times should be specified in your
your program was compiled. program.)
Action: Close the file and end the End.
program. Determine whether the changes Several return codes indicate that an error
affect your application program. If they condition must be corrected by varying the
do, recompile the program. If the changes device off and on again.
do not affect your program, the file should
be changed or overridden to
LVLCHK(*NO). When LVLCHK(*NO) is
specified, the system does not compare 8181 Description: A system error condition
the record format descriptions. was detected during the I/O operation to
the device.
Messages:
Action: Release the device in error or
CPF4131 (Escape)
close the file. You may need to vary the
80F8 Description: An operation to a file was device off and on again to clear the error.
not successful because the file is marked Determine the cause of the failure from
in error. the accompanying message. Check for
Action: Close the file. Refer to mes- any system operator messages indicating
sages in the job log to determine what that additional corrective action must be
errors occurred. Take the appropriate performed. Open the file again or acquire
action for those errors. the device to continue.
Messages: Messages:

CPF455ð (Escape) CPF5427 (Escape) CPF51ð5 (Escape)
CPF5189 (Escape)
CPF5254 (Escape)
Major Code 81

8191 Description: The operation was not suc-
cessful because a permanent line error Major Code 82
occurred, and the system operator took a
recovery option in response to the line Major Code 82–Open or acquire operation
error message. (You can find out what failed.
type of line error occurred by asking the
system operator.) The device has been Description: An attempt to open the display
marked unusable. file or acquire the display device was not suc-
cessful. The error may be recoverable or per-
Action: Release the device in error or manent, but is limited to the specific display
close the file. Vary the device off and on device. Recovery is unlikely until the problem
again to clear the error. Open the file causing the error has been corrected.
again or acquire the device to continue.
Action: The following general actions can be
Messages: taken for each 82xx return code. Other spe-
CPF4526 (Escape) cific actions are given in each return code
CPF4542 (Escape) description. You can either:
CPF4551 (Escape) Continue processing without the device.
CPF5128 (Escape)
CPF5143 (Escape) Release the device or close the file,
CPF5198 (Escape) correct the problem, and acquire the
device or open the file again. A subse-
8197 Description: An error condition that is quent operation could be successful if the
not recoverable was detected at the error occurred because of some temporary
device. An example of such an error is condition such as the device being in use
the user turning off the display device. at the time.
Action: Release the device in error or If the operation is still unsuccessful, try it
close the file. The display device may again only a limited number of times.
need to be varied off and then on again to (The number of times should be specified
clear the error. Refer to the accompa- in your program.)
nying error message for additional infor-
mation regarding the source of the specific – If the attempted operation was an
error detected. Open the file or acquire acquire operation, release the device
the device again to continue. and issue the acquire operation again.
Messages: – If the attempted operation was an

open operation, close the file and
CPF4149 (Escape) CPF51ð6 (Escape) issue the open operation again.
CPF4197 (Escape) CPF514ð (Escape)
CPF4524 (Escape) CPF5143 (Escape) End.
CPF4533 (Escape) CPF5199 (Escape) Several return codes indicate that an error
CPF4538 (Escape) CPF5265 (Escape) condition must be corrected by changing a
CPF5ð47 (Escape) value in the file. To change a parameter value
81C2 Description: The operation issued by for the file, use the Change Display File
your program was not successful because (CHGDSPF) or Override with Display File
the Systems Network Architecture (SNA) (OVRDSPF) command.
session with the display is not active.
Action: Release the device or close the
file. Vary the device off and on again to 8281 Description: A system error condition
clear the error. Open the file or acquire was detected on an open or acquire oper-
the device again to continue. ation. The file may previously have been
in error, or the file could not be opened
Messages:
due to a system error.
CPF517ð (Escape)
CPF5422 (Escape)

Action: Determine the cause of the Action: Release the device in error or
failure from the accompanying message. close the file. Vary the device off and on
Check for any system operator messages again to clear the error. Open the file
indicating that additional corrective action again to continue.
must be performed.
Messages:
The display device may need to be varied
CPF4146 (Escape)
off and then on again to clear the error.
CPF4179 (Escape)
Your program can either:
CPF4193 (Escape)
Continue processing without the CPF4291 (Escape)
display device. CPF5198 (Escape)
Release the device or close the file, CPF526ð (Escape)
correct the problem, and acquire the
8297 Description: The open or acquire opera-
device or open the file again.
tion has ended abnormally due to an error
End.
condition detected at the display device
Messages: that is not recoverable. An example of
such an error is the user turning off the
display device.
CPF4221 (Escape) CPF5424 (Escape) Action: Release the device in error or
CPF51ð5 (Escape) CPF5447 (Escape) close the file. The display device may
CPF5254 (Escape) CPF5455 (Escape) need to be varied off and then on again to
CPF5257 (Escape) CPF919E (Escape) clear the error. Refer to the accompa-
nying error message for additional infor-
8282 Description: The open or acquire opera-
mation regarding the source of the specific
tion was not successful because the
error detected. Open the file or acquire
display device is unusable. This may
the device again to continue.
occur because a cancel reply has been
taken to an error recovery message for Messages:
the device or because the display has
CPF4192 (Escape)
been held by a Hold Communications
CPF5ð47 (Escape)
Device (HLDCMNDEV) command. No
CPF51ð6 (Escape)
operations should be issued to the device.
CPF514ð (Escape)
Communications with the display cannot
CPF5143 (Escape)
be resumed until the device has been
CPF5199 (Escape)
reset to a varied-on state.
82A6 Description: The open or acquire opera-
Action: Close the display device file. If
tion failed because the Systems Network
the device has been held, use the
Architecture (SNA) bind command was not
Release Communications Device
successful.
(RLSCMNDEV) command to reset the
device. If the device is in an error state, Action: Ensure that the display device
vary the device off and then on again. with which your program is communicating
Once the device is reset, start normal is configured properly. Refer to the device
operation by opening the display device response codes in the accompanying error
file again. message for additional information
regarding the specific error detected.
Messages:
Messages:
CPF4171 (Escape)
CPF51ð3 (Escape)
8291 Description: A permanent line error
CPF5517 (Escape)
occurred on an open or acquire operation.
The device has been marked unusable.

82A8 Description: The acquire operation was different display device, or end. Vary on
not successful because the maximum the display device and attempt the open
number of devices allowed for the display or acquire operation again.
file has been reached.
If you want your program to continue with
Action: Your program can recover by the same display, release the device or
releasing a different device and issuing close the file, correct the problem, and
the acquire operation again. If more acquire the device or open the file again.
devices are needed, close your file and
Messages:
increase the MAXDEV value in the display
file. CPF4285 (Escape)
CPF5333 (Escape)
Messages:
82B3 Description: The open or acquire opera-
CPF4745 (Escape)
tion was not successful because the
CPF5ð41 (Status)
display device you are acquiring is in use
CPD4757 (Diagnostic)
in another process.
82A9 Description: The acquire operation was
Action: Wait for the display device to
not successful because the requesting
become available, then issue the acquire
program device is not available. The
operation again. Otherwise, you may con-
requesting program device may not be
tinue other processing without the display,
available because your program is not
or end the program.
running in an interactive job.
You can use the Work with Configuration
Action: Your program can continue
Status (WRKCFGSTS) command to deter-
without the display, attempt to use a dif-
mine which job is using the display device.
ferent display device, or end.
Consider increasing the WAITFILE param-
If your program needs to use the
eter of the CHGDSPF or OVRDSPF
requesting program device, make sure
command to allow more time for the
that it runs in an interactive job.
device to become available.
Messages:
Messages:
CPF4366 (Escape)
CPF41ð9 (Escape)
CPF5381 (Escape)
CPF413ð (Escape)
82AA Description: The open or acquire opera- CPF4282 (Escape)
tion was not successful because the CPF5217 (Escape)
display device description was not found. CPF5332 (Escape)
Action: Your program can continue 82EE Description: An open or acquire opera-
without the display, attempt to use a dif- tion was attempted to a device that is not
ferent display device, or end. supported for a display file.
Verify that the name of the display device Your program is attempting to acquire a
was correctly specified in the DEV param- device that is not a valid display device; or
eter on the CRTDSPF, CHGDSPF, it is trying to acquire the requesting
CRTDEVDSP, or OVRDSPF command. program device, but the requesting
program device for the job is a commu-
Messages:
nications device, not a display device.
CPF41ð3 (Escape)
CPF4747 (Escape)
without the display, attempt to acquire a
82AB Description: The open or acquire opera- different display device, or close the file
tion was not successful because the and end.
display device was not varied on.
Verify that the name of the display device
Action: Your program can continue was specified correctly on the CHGDSPF,

CRTDEVDSP, CRTDSPF, or OVRDSPF correct the problem and issue the acquire
command. operation again.
If your program was attempting to acquire For authority errors, obtain authority to the
the requesting program device, verify that device from your security officer or device
your program is running in an interactive owner. If the device is in service mode,
job so that the requesting program device the system service tools (SST) function is
is a display device. currently using the device. Wait until the
device is available to issue the operation
Messages:
again.
CPF41ð5 (Escape)
Messages:
CPF4223 (Escape)
CPF476ð (Escape) CPF41ð4 (Escape)
CPF5278 (Escape)
82EF Description: An open or acquire opera-
CPF5279 (Escape)
tion was attempted for a device that the
user is not authorized to or that is in 82F8 Description: Your program attempted an
service mode. acquire operation to a device that is
marked in error due to a previous error
during an I/O or acquire operation.
different display device, or end. Action: Release the device or close the
file, correct the previous error, and acquire
If the operation was an open operation,
the device or open the file again.
close the file, correct the problem, and
then issue the open operation again. If Messages:
the operation was an acquire operation,
CPF5293 (Escape)

831D Description: The operation just
Major Code 83 attempted by your program was rejected
because a parameter was not valid, out of
Major Code 83–Device error occurred (recov- limits, or missing.
erable). Action: Your program can bypass the
Description: An error occurred during an I/O failing step and continue, or close the file
operation, but the display device is still usable. and end. Refer to the accompanying
Recovery within your program might be pos- message to determine what parameter
sible. was incorrect. Correct the error in your
program before attempting to try the oper-
Action: The following general actions can be ation again.
taken for each 83xx return code. Other spe-
cific actions are given in each return code Messages:
description. CPF4912 (Notify) CPF5ð21 (Notify)
Continue processing without the display CPF5ðð2 (Notify) CPF5218 (Escape)
device. CPF5ðð8 (Notify) CPF53ð2 (Escape)
CPF5ð12 (Notify) CPF53ð3 (Escape)
Correct the problem and continue pro- CPF5ð14 (Notify) CPF5398 (Escape)
cessing with the display device. If the
attempt to recover from the operation is 831E Description: The operation just issued
unsuccessful, try it again only a limited by your program was not valid or a combi-
number of times. (The number of times nation of operations that is not valid was
should be specified in your program.) specified. The error may have been
caused by one of the following:
End.
Either your program issued an opera-
Several return codes indicate that an error tion with an unrecognized code, or the
condition must be corrected by changing a operation specified by the code or
value in the display file. To change a param- DDS keyword is not supported by the
eter value for the file, use the Change Display display.
File (CHGDSPF) or Override with Display File
(OVRDSPF) command. A combination of operations or
keywords that is not valid was
requested.
A user-defined data stream contained
830B Description: Your program has
a command that is not valid for the
attempted to issue an input or output
display.
operation either before the device was
acquired or after it was released. Action: Your program can bypass the
operation that is not valid and continue, or
Your program may have improperly
close the file and end. Refer to the
handled a permanent device or acquire
accompanying message to determine why
failed error.
the operation was rejected. Correct the
Action: Verify that your program tries no error in your program before attempting to
input or output operation with a display try the failing operation again.
device that is not connected to the file and
Messages:
that return codes from acquire or I/O oper-
ations are handled properly. CPF4564 (Escape) CPF5ð55 (Notify)
CPF5ðð5 (Notify) CPF5ð56 (Notify)
Messages:
CPF5ð11 (Notify) CPF5ð59 (Notify)
CPD4ð79 (Diagnostic) CPF5ð7ð (Escape) CPF5ð39 (Notify) CPF5ð66 (Notify)
CPF4739 (Status) CPF517ð (Escape) CPF5ð45 (Notify) CPF5149 (Escape)
CPF5ð67 (Escape) CPF5217 (Escape) CPF5ð51 (Notify)
CPF5ð68 (Escape)

831F Description: A length that is not valid 8343 Description: An attempt was made to
was specified on the operation. add another record to a subfile after the
subfile was full.
On an output operation, your program has
tried to send a data record having a length Action: Your program can clear the
that exceeds the maximum record length subfile, or continue without adding more
allowed for the display device. The data records to the subfile. Otherwise, close
has been truncated. the file and end.
Action: Issue the output operation again Increase the subfile length in the DDS
with a smaller output length. The record statements. If a coding error in your
length for a non-field-level display file program caused the error, correct your
cannot exceed the display size. The program.
record length for any display file must be
Messages:
no greater than 32 763 characters.
CPF5ð43 (Notify)
Messages:
83E0 Description: Your program attempted to
CPF4ð1ð (Diagnostic)
issue an operation using a record format
CPF4ð78 (Diagnostic)
that was not defined for the display file, or
8322 Description: The attempted operation is omitted the record format name.
not valid in the current state. Either a
Action: Check the name of the record
write operation was attempted while your
format in your program to be sure it is
program was not in the send state or a
correct. Then check that the record
subfile operation was attempted when the
format is defined properly in the DDS for
subfile was not active.
the file.
Action: Your program can bypass the
Messages:
operation that is not valid and continue, or
close the file and end. Correct the CPF5ð22 (Notify)
sequence of operations in your program CPF5ð23 (Notify)
before attempting to run the job again. CPF5ð53 (Notify)
CPF5ð54 (Notify)
Messages:
83E1 Description: An error occurred during an
CPF5ð13 (Notify)
I/O operation. The requesting program
CPF5ð6ð (Notify)
device was set to automatically disconnect
832D Description: Your program attempted an your program. The same user signed on
operation that is not valid when an invite to the same display device, so the
operation is outstanding. Once you have program was started up again. The
issued an invite or get-no-wait operation, display was cleared of any data present
another invite operation cannot be issued when the error occurred.
for the same display device until the first
Action: Branch to a normal starting point
invite has been completed by a read or
in your program and rewrite the display.
read-from-invited-devices operation.
There is no need to perform a close or
Action: Issue an input operation to open operation on the display files that
receive the data that was invited before were active when the error occurred.
issuing another invite operation. Other-
Messages:
wise, close the file and end. If a coding
error in your program caused the error, CPF5ð9F (Notify)
correct the sequence of operations in your 83E8 Description: Your CL program issued an
program. End Receive (ENDRCV) command when
Messages: there is no outstanding read-with-no-wait
operation.
CPF5ð52 (Notify)

Action: Your program can issue an file. Correct the error in your program
output operation to continue sending, before attempting to repeat the failing
issue an input operation to begin operation.
receiving, or close the file and end.
Messages:
Correct the error in your program before
attempting to repeat the failing operation. CPF5ð63 (Notify)
CPF5216 (Escape)
Messages:
CPF53ð1 (Escape)
CPF491ð (Notify)
83F8 Description: Your program attempted an
83F6 Description: Your program sent data to I/O operation to a device that is marked in
the display that is not valid. The data type error due to a previous error during an I/O
may not be correct for the field in which it or acquire operation.
is used.
Action: Release the device or close the
Action: Check the name of the record file, correct the previous error, and acquire
format in your program to be sure it is the device or open the file again.
correct. Verify that the data definition
Messages:
statements in your program match the
output record defined in the DDS for the CPF5293 (Escape)

Appendix F. Edit Codes
OS/400 Edit Codes

The following table summarizes the functions pro-
vided by OS/400 edit codes.
Table F-1 (Page 1 of 2). Summary Chart for OS/400 Edit Codes
Sign Blank I J
Displayed Value of Value of Value of
Decimal When QDECFMT QDECFMT QDECFMT Leading
Edit Commas1 Points1 Negative System System System Zero
Codes Displayed Displayed Value Value Value Value Suppressed
1 Yes Yes No sign .00 or 0 ,00 or 0 0,00 or 0 Yes
2 Yes Yes No sign Blanks Blanks Blanks Yes
3 Yes No sign .00 or 0 ,00 or 0 0,00 or 0 Yes
4 Yes No sign Blanks Blanks Blanks Yes
A Yes Yes CR .00 or 0 ,00 or 0 0,00 or 0 Yes
B Yes Yes CR Blanks Blanks Blanks Yes
C Yes CR .00 or 0 ,00 or 0 0,00 or 0 Yes
D Yes CR Blanks Blanks Blanks Yes
J Yes Yes −(Minus) .00 or 0 ,00 or 0 0,00 or 0 Yes
K Yes Yes −(Minus) Blanks Blanks Blanks Yes
L Yes −(Minus) .00 or 0 ,00 or 0 0,00 or 0 Yes
M Yes −(Minus) Blanks Blanks Blanks Yes
N Yes Yes −(Minus) .00 or 0 ,00 or 0 0,00 or 0 Yes
O Yes Yes −(Minus) Blanks Blanks Blanks Yes
P Yes −(Minus) .00 or 0 ,00 or 0 0,00 or 0 Yes
Q Yes −(Minus) Blanks Blanks Blanks Yes
Y2 Yes
 Copyright IBM Corp. 1997 F-1

Table F-1 (Page 2 of 2). Summary Chart for OS/400 Edit Codes
Sign Blank I J
Displayed Value of Value of Value of
Decimal When QDECFMT QDECFMT QDECFMT Leading
Edit Commas1 Points1 Negative System System System Zero
Codes Displayed Displayed Value Value Value Value Suppressed
Z3 Yes
Notes:
1. The QDECFMT system value determines the decimal point character (period in U.S. usage), the character
used to separate groups of three digits (comma in U.S. usage), and the type of zero suppression (depending
on comma and period placement). For more information on the QDECFMT system value, see the Work Man-
agement book.
2. The Y edit code suppresses the farthest left zero of a date field that is three to six digits long, and it sup-
presses the two farthest left zeros of a field that is seven positions long. The Y edit code also inserts slashes
(/) between the month, day, and year according to the following pattern:
nn/n
nn/nn
nn/nn/n
nn/nn/nn
nnn/nn/nn
If the DATE keyword is specified with EDTCDE(Y), the separator character used is the job attribute, DATSEP.
The slash (/) is the default DATSEP. If, at file creation time, DATFMT is JUL (Julian), the date is normally
formatted as nn/nnn and EDTCDE(Y) is not valid.
3. The Z edit code removes the sign (plus and minus) from a numeric field. The sign of the units position is
changed to a hexadecimal F before the field is written.
Note: Edit code X can be specified but has no other effect on the display file and is ignored for
effect on display files and is ignored. The AS/400 all other processing. The display length of the
system hardware operates with a preferred sign of field is determined by the keyboard shift and not
F, which is equivalent to using edit code X. Edit by edit code X (the default numeric-only Y attri-
code X causes a blank keyboard shift (position 35) bute may add 1 position to the field for decimals).
to default to numeric only (attribute Y), but has no
F-2 Application Display Programming V4R1

Examples of Editing Using The date separator character is determined by the
job attribute DATSEP. In this figure, QDECFMT is
OS/400 Edit Codes assumed to equal x, and DATSEP is assumed to
equal /.
The following table shows valid edit codes with
examples of unedited source data and edited
output. Zero suppression and decimal characters
are determined by the system value QDECFMT.
Table F-2. Valid Edit Codes, Source Data, and Edited Output
Positive Positive Negative Negative Zero Zero
Number– Number– Number– Number– Balance– Balance–
Two No Three No Two No
Decimal Decimal Decimal Decimal Decimal Decimal
Edit Codes Positions Positions Positions1 Positions1 Positions1 Positions1
Unedited 1234567 1234567 xxxx.125– xxxx.125– xxxxxx xxxxxx
1 12,345.67 1,234,567 .125 125 .00 0
2 12,345.67 1,234,567 .125 125
3 12345.67 1234567 .125 125 .00 0
4 12345.67 1234567 .125 125
A 12,345.67 1,234,567 .125CR 125CR .00 0
B 12,345.67 1,234,567 .125CR 125CR
C 12345.67 1234567 .125CR 125CR .00 0
D 12345.67 1234567 .125CR 125CR
J 12,345.67 1,234,567 .125− 125− .00 0
K 12,345.67 1,234,567 .125− 125−
L 12345.67 1234567 .125− 125− .00 0
M 12345.67 1234567 .125− 125−
N 12,345.67 1,234,567 −.125 −125 .00 0
O 12,345.67 1,234,567 −.125 −125
P 12345.67 1234567 −.125 −125 .00 0
Q 12345.67 1234567 −.125 −125
Y2 123/45/67 123/45/67 0/01/25 0/01/25 0/00/00 0/00/00
Z3 1234567 1234567 125 125
Notes:
1. The x represents a blank.
2. The Y edit code suppresses the farthest left zero of a date field that is three to six digits long, and
it suppresses the two farthest left zeros of a field that is seven positions long. For more informa-
tion, see the second footnote in Table F-1 on page F-1.
3. The Z edit code removes the sign (plus or minus) and suppresses leading zeros.
Appendix F. Edit Codes F-3

You can define your own edit codes using the
User-Defined Edit Codes Create Edit Description (CRTEDTD) command.
You can define five edit codes to provide more

editing function than is available with the OS/400
edit codes, and to handle common editing func-
tions that would otherwise require the use of an
edit word.
Table F-3. IBM-Supplied Edit Descriptions

QEDIT5 Edit QEDIT6 Edit QEDIT7 Edit QEDIT8 Edit QEDIT9 Edit
Description Codes1 Codes1 Codes1 Codes1 Codes1
Integer xxx,xxx,xxx,xxx,xx0 xxx,xxx,xxx,xxx,xx0 xxx,xxx,xxx,xxx,x0x xxx,xxx,xxx,xxx,x0x 0xx-xx-xx
mask
Decimal . (period) . (period) . (period) . (period) . (period)
point
Fraction xxxxxxxxx xxxxxxxxx xxxxxxxxx xxxxxxxxx None
mask
Fill character x x x x x
Floating cur- None None None $ None
rency
symbol
Zero Replace with fill Replace with fill Normal editing Normal editing Normal editing
balance character character rules rules rules
Negative CR - (minus sign) - (minus sign) - (minus sign) None
status
Positive DR None None None None
status
Left constant None None $ None None
Right con- None x* None None None
stant
1 The x represents a blank.
An edit description contains the following items: Fraction mask

Describes the editing of the fraction
Integer mask
portion of a field. Ampersand is the
Describes the editing of the integer
same as for the integer mask. All
portion of a field. All characters except
zeros are treated as constants and all
blank, zero, and ampersand (&) are
blanks are replaced with digits (no fill
treated as constants:
character is used).
Blank means to replace the blank
Fill character
with a digit if zero suppression has
Defines what character is used in each
ended; otherwise, replace the
position of a result that is zero-
blank with the fill character.
suppressed. By default, a blank is
The zero to the farthest left means
used.
to replace the zero with a digit and
Floating currency symbol
end zero suppression. All other
Defines the floating currency symbol to
zeros are treated as constants.
be used to edit the field.
Ampersand means to replace the &
Zero balance
with a blank.
Specifies how zero values are to be
Decimal point
edited. They can be edited using the
Defines what character is used as the
fill character or the integer and fraction
decimal point. By default, a period (.)
masks.
is used.

Negative status – Length of truncated integer mask
Defines the characters that are to – Length of decimal point (which is always 1
follow the edited result of a field if the unless no decimal point is used)
field is negative. – Length of truncated fraction mask
Positive status – Length of negative or positive status value
Defines the characters that are to (whichever is longer)
follow the edited result of a field if the
Note: If the text you specify for negative
field is positive or zero.
status is a different length than the one for
Left constant
positive status, the CRTEDTD command
Defines a constant that is to be the
pads the shorter value with blanks. This
portion to the farthest left of the edited
makes the shorter value equal in length to
result of a field.
the longer value.
Right constant
– Length of right constant
Defines a constant that is to be the
If either the integer mask or fraction mask
portion to the farthest right of the
does not contain enough digit replace charac-
edited result of a field.
ters for the field to be edited, the field is not
edited and is ignored.
Using User-Defined Edit Codes
The following rules apply to using edit
Example of a User-Defined Edit
descriptions. These rules are affected by the Code
length and decimal positions of the field being
edited. The following Create Edit Description (CRTEDTD)
command shows how to create an edit description
The field to be edited is aligned by the integer to edit a numeric field and indicate if the value is a
and fraction masks. credit or debit (x indicates a blank):
The entire integer mask is not always used.
CRTEDTD EDTD(5) INTMASK('xxx,xxx,xx')
The integer mask is truncated on the left side
FRACMASK('xxxx') NEGSTS('DEBITx')
immediately before the farthest left significant
POSSTS('CREDIT') LFTCNS('$')
digit or farthest left, or forced, zero. RGTCNS('xB\\')
The decimal point immediately follows the
integer mask and the fraction mask imme- The field that uses the previous edit description
diately follows the decimal point. If no contains the value 001234 and has two decimal
decimal point is used, the fraction mask imme- positions. The edited field looks like this:
diately follows the integer mask.
The entire fraction mask is not always used. $xx12.34CREDITx\\
The fraction mask is truncated on the right
Note that when you create an edit description, you
side immediately following the farthest right
specify only the number (5, 6, 7, 8, or 9) that is
significant digit.
associated with the edit code. The system auto-
The width of the edited result is equal to the
matically affixes QEDIT to the number you specify.
total of the following:
(In the preceding example, EDTD(5) was speci-
– Length of left constant
fied. This would then be QEDIT5.)
– Length of floating currency symbol
Appendix F. Edit Codes F-5

Appendix G. System/36-Compatible Display Data
Management
This appendix describes how to use OS/400 For example, if an application running in the
display data to provide System/36-compatible System/36 environment uses the MSGID DDS
functions. Additional information on System/36 keyword to display the message from a user
compatibility can be found in the DDS Reference. message file, the message file used is the
message file specified on the USER1 param-
In order to migrate System/36 applications that eter of the MEMBER OCL statement. If this
use display devices, OS/400 display data manage- same application is not run in the System/36
ment has functions that allow the operating environment, the message file used is a
system to work like System/36 work station data message file named USR1 in the job’s library
management. The level of compatibility with the list.
System/36 depends on the following:
The remainder of this appendix contains a section
The User Display Management
for each display data management topic you may
(USRDSPMGT) keyword
need to know about if you are interested in S/36
This keyword is automatically put in the DDS compatibility. Where appropriate, each topic con-
source when the $SFGR utility or the Create tains the following information:
System/36 Display File (CRTS36DSPF) CL
How the System/36 supports the function.
command converts SFGR source to DDS
More information on the System/36 functions
source. Specifying this keyword indicates that
can be found in the following manuals:
the System/36 work station data management
function is to be used instead of OS/400 – System/36 Creating Displays: Screen
display data management functions. Design Aid and System Support Program.
For example, the USRDSPMGT keyword – System/36 Concepts and Programmer's
specifies that the cursor is positioned as it is Guide.
on the System/36. If the USRDSPMGT
How the default OS/400 display data manage-
keyword is not specified, the cursor is posi-
ment supports the function.
tioned according to the OS/400 display data
management rules. How to get the System/36-compatible function
with OS/400 display data management,
The programming language used to write the
including which of the three level-of-
program
compatibility items previously listed is required
To get application-level System/36 compat- to get the compatible function.
ibility, the programs must be written in
System/36-compatible RPG II or
System/36-compatible COBOL. Clearing Lines on the Display
For example, if a program is written in a
When a System/36 application writes the first
System/36-compatible language, the file status
record in a job, System/36 work station data man-
codes set by the high-level language and
agement clears the display before displaying the
return codes set by data management are the
application data. The System/36 function is pro-
same as the System/36. If a program is not
vided on the AS/400 system for the first write
written in a System/36-compatible language,
operation in a System/36-environment job if the
the file status codes and return codes are the
program is written in a System/36-compatible lan-
AS/400 values.
guage or the display file contains the
The environment where the application runs USRDSPMGT keyword. The System/36 Environ-
To get environment-level System/36 compat- ment Programming book describes starting and
ibility, the programs must run in the System/36 ending a System/36-environment job.
environment.
 Copyright IBM Corp. 1997 G-1

OS/400 display data management normally clears The application program can read data from either
the display when a display file is opened; record. Only the data for the input-capable fields
System/36 work station data management does defined by the specific record is returned. In the
not. The System/36 function is provided by the previous example, if the application program
OS/400 operating system for programs written in a needs to get all the data from all the input-capable
System/36-compatible language or that open a fields on the display, the application has to issue
display file that specifies the USRDSPMGT two read operations: one for REC1 and one for
keyword. REC2.
Applications can clear all or just parts of the OS/400 display data management allows only one
display by using the clear line (CLRL) keyword. record with input fields for programs written in a
The CLRL keyword is automatically put in the System/36-compatible language or for display files
DDS source when the System/36 environment that specify the USRDSPMGT keyword.
converts the SFGR source to DDS. The value
generated for the number of lines to clear is based
on the value in columns 19 and 20 of the SFGR S Input Data from the Work Station
specification. Controller
Because some of the OS/400 and The System/36 work station controller returns the
System/36-compatible display-clearing functions data for all input-capable fields. With the default
are different, the following DDS keywords cannot OS/400 display data management support, the
be used in display files that specify the work station controller returns only data from the
USRDSPMGT keyword: display for the input-capable fields that the display
ERASE station operator has changed.
PUTRETAIN
KEEP OS/400 display data management provides the
ASSUME System/36 function with the Modified Data Tag
(MDT) value of the DSPATR DDS keyword. The
Also, the OVERLAY keyword is ignored for pro- DSPATR(MDT) keyword is automatically put in the
grams written in a System/36-compatible language DDS source for every input-capable field when the
and for display files that specify the USRDSPMGT System/36 environment converts SFGR source to
keyword. DDS. This keyword sets on an indicator in the
work station controller that makes the work station
controller act as if the field with DSPATR(MDT)
Input Data for Display File was changed by the display station operator.
Records Because this keyword is specified for all input-
capable fields, all the input data is returned to the
On the System/36, only one record with input system and to the program when the program
fields can be displayed. For example, if an appli- issues a read operation.
cation on the System/36 writes record REC1 and
then record REC2, only the last record written
(REC2) has input-capable fields. When REC1 is Self-Check
written, the input fields defined by REC1 are input-
capable. When REC2 is written, REC1 fields are On System/36, if a field specifies modulus 10 or
then no longer input-capable, and the input fields modulus 11 self-checking (column 30 of SFGR D
defined by REC2 are input-capable. specification), the work station controller verifies
that valid data is entered into the field. If a display
With the default OS/400 display data management station operator enters an incorrect modulus 10 or
support, many different records with input fields modulus 11 number for a field, the work station
can be displayed at the same time. For example, controller displays a blinking four-digit error code,
record REC1 (which occupies lines 1 through 12) and the user must enter data into the field again.
and record REC2 (which occupies lines 21
through 24) can be displayed at the same time. OS/400 display data management support for self-
check, which uses the CHECK(M10) and
G-2 Application Display Programming V4R1

CHECK(M11) DDS keywords, verifies that the field writes record REC1 to the display and then writes
has a valid modulus 10 or modulus 11 number record REC2 to the display (where REC2 has the
when you press the Enter key or another function erase-input-fields function enabled), all the input
key. This verification is used in place of issuing fields defined by REC1 are erased and REC2 is
an error message as you type data into the field. not sent to the display.
If the CHECK(M10F) or CHECK(M11F) keyword is
specified, the workstation controller verifies that OS/400 display data management follows the
valid data is entered into the field as described in System/36 handling of erase-input-fields when the
the previous paragraph. program is written in a System/36-compatible lan-
guage, the USRDSPMGT keyword is specified,
If a display file contains the CHECK(M10) or and the ERASEINP keyword is enabled for the
CHECK(M11) DDS keyword and also the record.
USRDSPMGT keyword, OS/400 display data man-
agement, like the System/36, issues an error On System/36, if a program writes a record to the
message as you type the data. The DDS display and the erase-input-fields and put-override
keywords CHECK(M10F) and CHECK(M11F) are functions are both enabled for the record, the
not allowed with the USRDSPMGT keyword. input fields on the display are erased, and the put-
override data for the specified record is sent to the
display.
Return Input
OS/400 display data management follows the
System/36 work station data management has System/36 handling of erase-input-fields when the
support to indicate to an application program program is written in a System/36-compatible lan-
whether any fields on the display have been guage, the USRDSPMGT keyword is specified,
changed by the display station operator. To use and the ERASEINP and PUTOVR keywords are
this support, the SFGR source must specify N for enabled for the record.
return input (column 22) in the SFGR S specifica-
tion. If N is specified and the user does not
change any fields on the display, all blanks are Display Attributes
received as input data for a read operation.
Some fields do not have beginning display attri-
OS/400 display data management provides the butes on the System/36. A field has a beginning
System/36 support. If the CHANGE keyword is display attribute only if one or more of the fol-
specified at the record level without a response lowing is true:
indicator in a display file that specifies the The field is input-capable.
USRDSPMGT keyword, and the program doing
the read operation is written in a The output data is based on an indicator
System/36-compatible language, the program (column 23-24 of SFGR D specification).
receives a blank record when the display station The field specifies a display attribute (such as
operator does not change any data on the display. high intensity, blink, reverse image, underline,
The CHANGE keyword is automatically put in the or column separators).
DDS source when SFGR source is converted to
DDS by the System/36 environment if N is speci- The field appears on a row that is not cleared
fied for return input. by the record.
To provide application compatibility with the

System/36, OS/400 display data management
Erase Input Fields
follows the System/36 rules to determine if a field
should have a beginning attribute when the
On System/36, if a program writes a record to the
USRDSPMGT keyword is specified in a display
display and the erase-input-fields function
file. Also, if a field does not have a beginning
(columns 31 and 32 of the SFGR S specification)
attribute and the OVRATR keyword is specified on
is enabled for the record, the input fields on the
the field, the OVRATR keyword is ignored (no field
display are erased, but the specified record is not
attribute is sent).
sent to the display. For example, if a program
Appendix G. System/36-Compatible Display Data Management G-3

On the System/36, some fields do not have 4. If the cursor is not positioned by any of the
ending display attributes. A field has an ending previous rules, the cursor is positioned to the
attribute only if one or more of the following is upper-left-hand corner of the display.
true:
OS/400 display data management positions the
The field is input-capable.
cursor following the System/36 rules for display
The output data is based on an indicator files that have the USRDSPMGT keyword speci-
(columns 23-24 of SFGR D specification). fied.
The field specifies a display attribute (such as
high intensity, blink, reverse image, underline,
or column separators).
Displaying Messages
OS/400 display data management follows the On System/36, fields can be defined that have
System/36 rules to determine if a field should message text automatically inserted into the field
have an ending attribute when the USRDSPMGT when a record is displayed. System/36 work
keyword is specified in a display file. station data management retrieves the message
text defined for the field and supplies the message
text as output data for the field. To display
Positioning the Cursor message text, System/36 applications must
specify the following:
System/36 uses the following rules to determine M for constant type (column 56 of SFGR D
where the cursor should be positioned when a specification).
record is displayed:
The message identification code (MIC)
1. The cursor is positioned to the first input field (columns 57 through 60 of SFGR D specifica-
(defined by the SFGR source statements) that tion or output data supplied by the program).
has an indicator specified for the position-
The message member identifier (columns 61
cursor attribute, has this indicator set on, and
and 62 of SFGR D specification or output data
where one of the following conditions is true:
supplied by the program).
This field does not have the protect attri-
bute specified (columns 37 and 38 of the OS/400 applications can display messages in a
SFGR D specification). variety of different ways. For information on dis-
playing messages, see “Creating and Displaying
This field has an indicator specified for the
Your Own Messages” on page 8-1.
protect attribute, but the indicator is off.
This field has an unoptioned-protect attri- To provide application compatibility with
bute specified (columns 37 or 38 of the System/36, the MSGID keyword can be used to
SFGR D specification is Y or N). display messages. The MSGID keyword is auto-
matically generated by the System/36 environment
2. If the cursor is not positioned by rule 1, a
if M is specified for constant type in the SFGR D
check is made for fields with an unoptioned-
specification.
position-cursor attribute (columns 32 or 33 of
the SFGR D specification is Y). If there is a
Either of the following formats can be used to
field with an unoptioned-position-cursor attri-
display messages that follow the System/36 con-
bute, the cursor is positioned to this field.
ventions for sending messages:
3. If the cursor is not positioned by rule 1 or 2, MSGID(message-identifier message-file)
the cursor is positioned to the first input field MSGID(USR message-identification-code message-file)
(as defined by the SFGR source statements)
that does not have an unoptioned-protect attri- Message-identifier consists of two parts: a
bute (columns 37 or 38 of the SFGR D spec- message prefix and a message-identification-code
ification are blank). (MIC). If an application uses the first format of the
MSGID keyword, the three-character message
prefix should be the first three characters of the

seven-character message-identifier. If an applica-
Table G-1. Message Files for MSGID
tion uses the second format of the MSGID
keyword, the prefix does not need to be provided. Value of
The prefix is already specified as USR in the Field-Name Message File Used
MSGID keyword. U1 Message text from the
message file specified on
The message-identification-code parameter speci-
USER1 parameter on
fies the four-character message ID of the
MEMBER OCL statement.
message to be displayed.
U2 Message help text from
For more information on specifying display file the message file specified
message-identifiers, see the DDS Reference. on USER2 parameter on
The message-file parameter identifies the
P1 Message text from the
message file that contains the message to be dis-
played. For System/36 compatibility, this param-
PROGRAM1 parameter on
eter can be specified in one of two formats.
The first format for specifying the message-file P2 Message help text from
parameter is in a two-character field-name. The the message file specified
field-name must exist in the same record as the on PROGRAM2 parameter
MSGID field, and the field must be defined as a on MEMBER OCL state-
character field with usage H (hidden), P (program- ment.
to-system), B (both), or O (output-only). The field
M1 Message text from
identified by field-name indicates the message file
IBM-supplied message file
that the System/36 environment uses to display a
##MSG1.
message. The values allowed for the field are:
M2 Message help text from
##MSG1.
The second format for specifying the message-file

parameter is a special value. The following
special values can be specified for the message
file:
Table G-2 (Page 1 of 2). Message Files for

MSGID
Special Message File Used
Value
*USR1 Message text from message file
specified on USER1 parameter
on MEMBER OCL statement.
*USR2 Message help text from
USER2 parameter on MEMBER
OCL statement.
*PGM1 Message text from message file
specified on PROGRAM1
parameter on MEMBER OCL
statement.

message identification code followed by two
Table G-2 (Page 2 of 2). Message Files for
MSGID
question marks (??).
Special Message File Used The following DDS keywords cannot be speci-
Value fied on a field with the MSGID keyword:
*PGM2 Message help text from DFT

message file specified on DFTVAL
PROGRAM2 parameter on FLTFIXDEC
MEMBER OCL statement. FLTPCN
MSGCON
*SYS1 Message text from IBM-supplied
message file ##MSG1.
*SYS2 Message help text from Put Override
##MSG1. On System/36, if the put-override option is
enabled (columns 33 and 34 of SFGR S specifica-
tion) and the number of lines to clear (columns 19
The following are considerations you should be and 20 of SFGR S specification) is specified, the
aware of when using the System/36-compatible number of lines to clear is ignored. System/36
functions of the MSGID keyword: work station data management does not clear the
If a field name or a special value is specified, display when the put-override option is enabled.
the processing done by OS/400 display data OS/400 display data management also has
management depends on the environment support to ignore the clear function (CLRL
where the application runs. For example, if keyword) for records that have the put-override
the application is run in the System/36 envi- option (PUTOVR keyword) enabled. This support
ronment, *USR1 indicates to use the message is used for programs written in a
file identified by the USER1 parameter on the System/36-compatible language or using a display
MEMBER OCL statement. If the same appli- file that specifies the USRDSPMGT keyword.
cation is not run in the System/36 environ-
ment, *USR1 indicates to use message file On System/36, if the put-override option is
USR1. enabled, no input-field definitions are sent to the
display. Input-field definitions contain information
If the message is to be displayed and it only such as length of the input-field, mandatory-fill
has message help, the message help is dis- attribute, mandatory-enter attribute,
played. modified-data-tag attribute, and protected input-
If the message help is to be displayed but the field attribute. If there are input fields currently on
message has no message help, only the the display, these fields remain input-capable.
message is displayed. The default OS/400 display data management
support sends input-field definitions when the put
If the message text to be displayed is longer
override option is enabled. OS/400 display data
than the length of the output field, the
management provides the System/36 function of
message text is truncated to the length of the
not sending input-field definitions to the display
output field. If the message text to be dis-
when the put-override function is enabled and the
played is shorter than the length of the output
record to be displayed is in a display file that
field, the message text is padded with blanks.
specifies the USRDSPMGT keyword. If the appli-
If the message identifier contains any charac- cation uses the System/36 function of not sending
ters that are not valid (valid characters are 0-9 input-field definitions to the display when the put-
and A-F), the message text displayed is the override function is enabled, attributes that are
message identifier followed by the two- defined by the input-field definitions cannot be
character message file identifier. changed when put-override is enabled. For
example, the protected input-field attribute
If the message identifier or the message file is
(DSPATR(PR)) is ignored when put-override is
not found, the message text displayed is the
enabled, because the input-field definitions are not
sent to the display.

On System/36, the put-override option can be data management replaces any incorrect signed
specified for records that are currently displayed numeric data with zeros before the data is given
and for records that are not currently on the to the application program. OS/400 display data
display. For example, if record REC1 is currently management supports the System/36 function for
displayed and the application program issues a programs written in a System/36-compatible lan-
write operation with the put-override function guage.
enabled for record REC2, the request to display
record REC2 is processed as a put-override On System/36, if zeros are entered in a signed
request. The default support in OS/400 display numeric field and the field-minus key is used to
data management supports the put-override func- exit the field, a value of negative zero is returned
tion only for records that are currently displayed. to the application program. The default support in
For example, if record REC1 is currently displayed OS/400 display data management returns zeros to
and the application program issues a write opera- the application instead of negative zero. OS/400
tion with the put-override function enabled for display data management supports the System/36
record REC2, the put-override function is ignored function for programs written in a
and the request to display record REC2 is pro- System/36-compatible language or using a display
cessed as if the PUTOVR keyword was not file that specifies the USRDSPMGT keyword.
enabled. If the display file specifies the
USRDSPMGT keyword, OS/400 display data man-
agement provides the System/36 function of Function Keys
allowing the put-override function even if the
record is not currently displayed. On System/36, application programs can receive
control when a function key is pressed. To use
During an override operation, OS/400 display data this support, the application must enable the
management may ignore help specifications con- desired function key in the SFGR source and the
tained in the record format that is displayed by the program must indicate that it can process the
application program. This occurs if the function key.
USRDSPMGT keyword is used. If the Help
Cleared (HLPCLR) keyword is also specified on The default OS/400 display data management
the record format, no online help is available. support does not allow a program not written in a
System/36 compatible language to indicate which
function keys the program can process. The func-
Handling Signed Numeric Data tion keys that are enabled in the DDS for the
display file are the function keys that OS/400
System/36 does no checking when incorrect data display data management passes to the program
(data other than 0 through 9) is specified for a to handle.
signed numeric field on a write operation. For
example, if the data in a signed numeric field is OS/400 display data management supports the
character data, the character data is displayed. System/36 function of a program indicating which
The default support in OS/400 display data man- function keys it can process for programs written
agement is to replace any incorrect signed in a System/36-compatible language. See the
numeric data with nulls when the field is dis- appropriate System/36-compatible language
played. OS/400 display data management sup- manual for information on enabling function-key
ports the System/36 function when the handling in a program.
USRDSPMGT keyword is specified in the display
file.
Help Key Considerations
System/36 also does no checking when a read
operation returns incorrect data for a signed The HELP and HLPRTN DDS keywords are used
numeric field. For example, if the data returned to indicate what processing should be done by the
for a signed numeric field is character data, the system when the Help key is pressed. The HELP
character data is passed to the application keyword indicates that the application wants the
program. The default support in OS/400 display Help key enabled. The HELP keyword is auto-
matically put in the DDS source when SFGR

source is converted to DDS by the System/36 record, the application help for the record is
environment. displayed.
4. If the Help key is not processed by rules 1, 2
The HLPRTN keyword indicates that the applica-
or 3, an error message is displayed indicating
tion program wants to process the Help key when
that the key is not allowed.
the display station operator presses the Help key.
When the Help key is enabled in the SFGR key
mask (columns 64 through 79 of the SFGR S
specification) the HLPRTN keyword is put in the
Using Command Keys to Exit
DDS source when the System/36 environment Application Help
converts SFGR source to DDS.
On System/36, if application help is displayed and
If the HELP and HLPRTN keywords are not speci- the display station operator presses a command
fied and the display station operator presses the key to exit application help, an indication of what
Help key, a message is displayed by OS/400 command key was pressed is given to the applica-
display data management indicating that the Help tion program. To use this support, the application
key is not allowed. must enable the desired command key on the
display where the Help key is pressed, and the
If the USRDSPMGT and HELP keywords are key must be enabled on the application help
specified, the HLPRTN keyword is not specified, display. If the display file containing application
and the display station operator presses the Help help specifies the USRDSPMGT keyword, OS/400
key, OS/400 display data management uses the display data management returns the indication of
following rules to determine how the Help key is what command key was pressed to exit applica-
be processed: tion help. If the command key was not specified
on both the application record and the help record,
1. If the Help key is pressed when a message is
the message, Function Key not Allowed is dis-
being displayed, the message help for the
played.
message is displayed.
2. If the Help key is not processed by rule 1 and On System/36, if application help is displayed and
there is application help defined for the record, the display station operator presses a command
the application help for the record is dis- key to exit application help, the data from the
played. display where the Help key is pressed is returned
to the application program. To use this support,
3. If the Help key is not processed by rules 1 or
the application must indicate restore yes (columns
2, an error message is displayed indicating
47 and 48 of the SFGR H specification) on the
that the key is not allowed.
display where the Help key is pressed. OS/400
If the USRDSPMGT, HELP, and HLPRTN display data management returns the data from
keywords are specified and the display station the display where the Help key is pressed if the
operator presses the Help key, OS/400 display display file containing application help specifies
data management uses the following rules to the USRDSPMGT keyword.
determine how the Help key is be processed:
1. If the application program has indicated that it Cancel-Invite Operation
can process the Help key, an indication is
returned to the application program that the On System/36, if a program issues a cancel-invite
Help key was pressed. operation and data has already been received by
2. If the Help key is not processed by rule 1 and the system (for example, the display station oper-
the Help key is pressed when a message is ator pressed the Enter key before the cancel-invite
being displayed, the message help for the was issued), the data is lost and the application is
message is displayed. not notified.
3. If the Help key is not processed by rules 1 or The default OS/400 display data management
2 and there is application help defined for the support causes the cancel-invite operation to fail if
the data is available. Message CPF4737 and

return code 0412 are sent to the application PGM1 (RPG PROGRAM)
program. The application can check the return MOVE \ON \IN24
code and issue a read operation to receive the WRITERECORDB
data that was returned from the display station. WRITERECORDD
WRITERECORDA
OS/400 display data management supports the EXFMTRECORDC
System/36 function and does not send message ENDSR
CPF4737 or set the return code for programs
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
written in a System/36-compatible language or for
display files that have the USRDSPMGT keyword FILE1
specified. USRDSPMGT
R RECORDB OVERLAY
For an application running in an OS/400 display CF(ð1)
data management environment that contains the INVITE
USRDSPMGT keyword and the INVITE keyword 1 18'TESTB'
in the display file, the following will occur: R RECORDC OVERLAY
1 18'TESTC'
If a file is active with a read outstanding when
R RECORDD OVERLAY
a record is written from another display file, a
save of the currently displayed screen takes \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
place before the write of the new record.
The suspended file is restored when a write is FILE2
done to the suspended file. USRDSPMGT
R RECORDA OVERLAY
On a System/36, the save is not done for this 22 5'TEST________A'
situation. 24 DSPATR(ND)
Figure G-1. Circumventing the Save Command
To circumvent the save command in the OS/400
display data management environment, do the fol-
lowing:
Retain Command and Function
1. Define a record named RECORDD in the file Keys
FILE1 as shown in Figure G-1.
2. Write record RECORDD to program PGM1 On System/36, when a program issues a write
before writing record RECORDA operation to display a record, the application can
indicate that the command and function keys cur-
By writing record RECORDD, the read outstanding rently active for the display station should be the
for record RECORDB is canceled, and the command and function keys that are used for the
save/restore of the record RECORDB is not new record. For example, if an application writes
required because there is no longer an out- record REC1 (where REC1 enables command
standing invite. keys 1 through 12 and all of the function keys),
and then the application writes record REC2
(where REC2 keeps the command and function
keys from REC1), then command keys 1 through
12 and all of the function keys are enabled when
REC2 is displayed. System/36 applications indi-
cate that the command keys should be kept by
specifying an R for the enable command keys
option in the SFGR source (column 28 of the
SFGR S specification). System/36 applications
indicate that the function keys should be kept by
specifying an R for the enable function keys option
in the SFGR source (column 27 of the SFGR S
specification).

AS/400 application programs can specify either a enabled, all the input fields on the display are
list of command and function keys that are valid changed to output-only fields when the put-
when a record is displayed or an indication that override function is handled by OS/400 display
the command and function keys that are currently data management.
active should remain active when a record is dis-
played. On System/36, application help can return the
data from input fields on an application help
OS/400 display data management allows an appli- display. This is not supported by OS/400 display
cation to keep the current command keys for a data management.
record if the RETCMDKEY keyword is specified
for the record. The RETCMDKEY keyword is
automatically generated by the System/36 environ- Restricted DDS
ment if R is specified for command keys in the Keywords/Functions
SFGR S specification.
If the USRDSPMGT keyword is specified in the
Also, OS/400 display data management allows an DDS source, the following DDS functions cannot
application to keep the current function keys for a be used:
record if the RETKEY keyword is specified for the
record. The RETKEY keyword is automatically DDS keywords that control clearing the
generated by the System/36 environment if R is display:
specified for function keys in the SFGR S specifi- – ASSUME
cation. – ERASE
– KEEP
– PUTRETAIN
System/36 Functions Not
ERRSFL DDS keyword
Supported
HLPCMDKEY DDS keyword
This section describes the System/36 work station Subfile DDS keywords:
data management functions that are not supported
by OS/400 display data management. – SFL
– SFLCTL
If one program issues a write operation that invites Because System/36-compatible languages do
the display and another program issues a write not support subfiles, subfiles cannot be used
operation with the put-override function enabled in a display file if USRDSPMGT is specified.
for the same display, all the write and read oper-
ations must use record formats from the same Response indicators
display file. For example, if program A sets up a Because System/36-compatible languages do
read-under-format (RUF) request by writing record not return indicators from the read operation
REC1 from file FILE1, the second program must to a display file, response indicators should
also use FILE1 for any write operations with the not be specified if USRDSPMGT is used.
put-override function enabled. If a different
display file is used, all the input fields from REC1 IGC conversion
are changed to output-only fields when the put- Because only one input-capable format is
override function is handled by OS/400 display maintained on the screen at on time, IGC con-
data management. version is not supported on the System/36 or
on the AS/400 in the System/36 environment.
The put-override function can be used only across The IGCCNV keyword is not allowed any-
different jobs (for example, a single-requester- where in the file definition when you use the
terminal (SRT) program that gives control to a USRDSPMGT keyword.
multiple-requester-terminal (MRT) program) when
the application programs are using RUF. If RUF DDS keywords:
is not in progress and the second job issues a – CHECK(M10F)
write operation with the put-override function – CHECK(M11F)

Because specifying the DDS keywords CHECK(M10F) and CHECK(M11F) without
CHECK(M10) and CHECK(M11) with USRDSPMGT.
USRDSPMGT provide the same function as

Bibliography
The following list of manuals and guides are related to Use this guide and reference to learn how to enter
this book. The manuals are listed with their full title, DDS and UIM source.
base order number, and a description of the content.
ADTS/400: Screen Design Aid, SC09-1768
The description of each manual includes the relation-
ship of that manual to this book. This guide and reference provides information about
using the Application Development Tools screen
design aid (SDA) to design, create, and maintain
System Use displays, menus, and online help information.
System Operation, SC41-4203, is intended for
Use this guide and reference if you want to let the
system operators or administrators and includes
system create the DDS as you design your own dis-
information on operating the console, starting and
plays.
stopping the system, responding to messages, and
controlling jobs and printer output. It also provides ADTS/400: Source Entry Utility, SC09-1774
information on devices, communications, tapes and This guide provides the application programmer or
diskettes, using online education and electronic cus- programmer with information about using the Appli-
tomer support, managing system operations, cation Development Tools source entry utility (SEU)
working with program temporary fixes and handling to create and edit source members. This manual
problems. explains how to start and end an SEU session and
Basic System Operation, Administration, and how to use the many features of this full-screen text
Problem Handling, SC41-5206, is intended for editor.
system operators or administrators and includes Use this guide to understand the functions of SEU
information about the system unit control panel, that are available for creating and editing your DDS
starting and stopping the system, using tapes and and CL and other code.
diskettes, working with program temporary fixes, as
well as handling problems. Common User Access Basic Interface Design
Guide, SC26-4583.
System Management This guide assists you in designing a user interface

that is consistent within your application and across
Security – Reference, SC41-5302. other applications. This guide presents the user
This manual provides information about system interface style guidelines and implementation con-
security concepts, planning for security, and setting siderations that you, the designer and/or developer,
up security on your system. must be concerned with.
Use this manual to learn how to specify authority for Office Services Concepts and Programmer’s Guide,
your display files. SH21-0703.
This guide provides information about writing appli-
Application Development cations that use OfficeVision functions.
ADTS/400: Character Generator Utility, SC09-1769 Use this guide to develop office documents, which
can be used as online help information.
This guide provides information about using the
Application Development Tools character generator
utility (CGU) to create and maintain a double-byte Communications and Connectivity
character set (DBCS) on the AS/400 system. ICF Programming, SC41-5442
Use this guide to add user-defined characters to This guide provides the information needed to write
DBCS font tables. application programs that use AS/400 communica-
ADTS/400: Programming Development Manager, tions and the OS/400 intersystem communications
SC09-1771 function (OS/400-ICF). This manual also contains
information on data description specifications (DDS)
This guide and reference provides information about keywords, system-supplied formats, return codes,
using the Application Development Tools program- file transfer support, and program examples.
ming development manager (PDM) to work with lists
of libraries, objects, members, and user-defined Use this guide to work with applications on remote
options to easily do such operations as copy, systems.
delete, and rename. IBM 5250 Information Display System Functions
Reference Manual, SA21-9247.
 Copyright IBM Corp. 1997 H-1

This reference manual provides information about cation program is run), copying files by using
using the functions of the 5250 Information Display. system commands to copy data from one place to
another, and tailoring a system using double-byte
Use this manual to use the 5250 Display Data
data.
Stream.
Use this guide for general information about using
IBM 5494 Remote Control Unit Functions Reference
files in application programs.
Manual, SC30-3533.
Printer Device Programming, SC41-5713.
This reference manual describes how the IBM 5494
Remote Control Unit uses Systems Network Archi- This guide provides information on how to control
tecture (SNA), Synchronous Data Link Control and understand printing, including printer
(SDLC), X.25, X.21, or Token-Ring protocols to connectivity, PC attached printers, and advanced
communicate with the AS/400 system. In addition, function printing (AFP*) printers.
this book describes how the 5494 manages the
Use this guide to understand printer device files.
attached work stations and converts network data
streams into protocols for 5250 work stations and Tape and Diskette Device Programming,
printers. SC41-5716.
This guide provides information about data manage-
Program Enablers ment support for tapes and diskette.
DDS Reference, SC41-5712. Use this guide to understand tape and diskette
device files.
This reference provides detailed descriptions of the
entries and keywords needed to describe database System/36 Concepts and Programmer's Guide,
files (both logical and physical) and certain device SC21-9019.
files (for displays, printers, and ICF) external to the This guide tells the application programmer how the
user's programs. System/36 works, how to design and develop care-
Use this reference to get detailed information about fully planned applications that make best use of
specific DDS keywords used in display files. system resources and features, and how to design
and develop application components.
CL Programming, SC41-5721.
Using this guide, a programmer can begin to under-
This guide provides a wide-ranging discussion of
stand what the system components are, how the
AS/400 programming topics, including control lan-
system works, and how to design and develop
guage (CL) programming, controlling flow and com-
application components. Actual coding will require
municating between programs, working with objects
the use of other manuals in the System/36 library.
in CL programs, and creating CL programs. Other
topics include predefined and impromptu messages System/36 Creating Displays: Screen Design Aid
and message handling, defining and creating user- and System Support Program, SC21-7902.
defined commands and menus, and application This guide describes how to use the Screen Design
testing, including debug mode, breakpoints, traces, Aid (SDA) or the System Support Program (SSP) to
and display functions. create and maintain menus and display formats.
Use this guide to understand how to use CL for cre- This manual also describes how to do the following:
ating application programs. – Use SDA to create RPG II WORKSTN file spec-
CL Reference, SC41-5722. ifications and WSU programs.
This guide provides a description of the AS/400 – Create and maintain source and procedure
control language (CL) and its OS/400 commands. members using Source Edit Utility (SEU)
(Non-OS/400 commands are described in the through SDA.
respective licensed program publications.) It also – View, print, and compile display formats.
provides an overview of all the CL commands for
the AS/400 system, and it describes the syntax System/36 Environment Programming, SC41-4730.
rules needed to code them. This guide provides information identifying the differ-
Data Management, SC41-5710. ences in the applications process in the System/36
environment on the AS/400 system. It helps the
This guide provides information about using files in user understand the functional and operational dif-
application programs. This guide includes informa- ferences (from a System/36 perspective) when pro-
tion on fundamental structure and concepts of data cessing in the System/36 environment on the
management support on the system. It also AS/400 system. This includes an environment func-
includes information on overrides and file redirection tional overview, considerations for migration, pro-
(temporarily making changes to files when an appli-
H-2 Application Display Programming V4R1

gramming, communications, security, and Program Interfaces
coexistence.
System API Reference, SC41-5801
This reference provides information about using
application programming interfaces (APIs) from
high-level language programs to list data or retrieve
descriptions and information more rapidly than using
other interfaces.
Use this guide to find out more information about
the APIs.
Bibliography H-3
H-4 Application Display Programming V4R1
Index
adding (continued)
Special Characters window to display stack 17-31
*DSPATR (display attribute) parameter 6-40 ADDMSGD (Add Message Description)
*FLD (field) special value 6-57 command 9-9
*JOBCCSID special value 13-3 ADDSCHIDXE (Add Search Index Entry)
*MENU (menu) OS/400 object type 9-1 command 20-17
*PGM (program) OS/400 object type alarm
defining *PGM menu 9-11 sounding for messages 8-7
menu object defining 9-11 ALCOBJ (Allocate Object) command 3-1
Allocate Object (ALCOBJ) command 3-1
Allow Roll (ALWROL) keyword
Numerics effects on rolling 3-16
5250 display data stream
use 3-16
See user-defined data stream (UDDS)
alphabetic conversion
5250 display station
name syntax A-4
avoiding record format problems 3-45
alphanumeric application
UNLOCK results 3-35
converting to DBCS D-8
5250 engraved key restriction 17-14
alphanumeric device
displaying double-byte data D-7
A alternative character sets and code pages 13-1
Alternative Data Type (IGCALTTYP) keyword D-5
accelerator key
defining 6-21 alternative keywords, specifying
definition 6-21 Help (HELP) 2-13
example 6-22 Page Down (PAGEDOWN) 2-13
acquire operation Page Up (PAGEUP) 2-13
definition 3-2 ALTHELP (Alternative Help) keyword 2-13
file resource allocation for 3-1 ALTPAGEDWN (Alternative Page Down)
ILE C function for 3-49 keyword 2-14
ILE COBOL statement for 3-49 ALTPAGEUP (Alternative Page Up) keyword 2-14
ILE RPG operation for 3-49 ALWROL (Allow Roll) keyword
acquired display station effects on rolling 3-16
additional, for I/O operations 3-2 use 3-16
releasing from I/O operations 3-49 ampersand (&) symbol A-5
action list definition 17-11 analyzing
action list option prompting B-13 system error messages 8-8
action variable definition 17-11, 17-13 API (application programming interface)
ACTIONS (Menu Bar Cursor Action) dialog adding and removing windows 17-30
command B-4 services 16-5
active record format APPFMT (application formatted area) tag
determining 3-5 application formatted data A-8
table 3-5 example
active subfile record an application formatted area A-9
definition 4-4 overview A-8
Add Message Description (ADDMSGD) application
command 9-9 help 6-56
Add Search Index Entry (ADDSCHIDXE) interaction with menu bar 6-50
command 20-17 application control of panel formatting 17-23
adding application display
entries during incomplete processing 17-9 changing record formats on a 3-8
pop-up window over another panel 17-31 creating a sample 1-1
pop-up windows using APIs 17-30 DBCS conversion dictionary D-19
window over another panel 17-31 defining in display file 2-1
 Copyright IBM Corp. 1997 X-1

application display (continued) application program (continued)
determining active record formats 3-5 passing display data 11-1
entry processing double-byte data D-8
See entry display record format used by 2-8
erasing unprotected input and output/input fields application programming
on 3-23 confirmation processing 16-31
field, defining in a record format 2-7 data presentation panel 16-46
functions, defining in record format 2-7 list panel 16-25
how the system reads input from 3-40 menu bar panel 16-63
improving system performance 14-1 application programming interface (API)
information adding and removing windows 17-30
See information display services 16-5
inviting input to 3-30 application record
keeping record or field on 3-23 MNUBARDSP 6-62
list 21-21 application window
order of record formats written to 3-9 defining 17-30
overlaying and erasing record formats on 3-10 area
placing records on 3-5 on a panel A-2
printing 2-25 assignments, common key
reading input from 3-33 See common key assignments
reading invited input from 3-31 ASSUME (Assume) keyword
rolling data between two lines 3-16 considerations 11-1
single-choice menu example DDS source 11-1, 11-3
See menu display OVERLAY keyword, used with 11-2
understanding which records do not occupy restriction with USRDSPMGT keyword G-10
space 3-8 sharing file between programs 11-1
viewing record format 2-8 System/36 application compatibility G-2
writing output to 3-5 attribute
application formatted area (APPFMT) tag continued
application formatted data A-8 example A-1
example display 6-40
an application formatted area A-9 display stations 3-4
overview A-8 entry fields 2-18
application formatted data field
selection characters A-9 color 2-22
application handle definition 17-1 emphasizing 2-21
application help System/36 application compatibility G-3
See also online help information modified data tag 2-10
caution for multiple display stations 18-1 overriding 3-18
definition 18-1 UIM-defined variable A-167
exiting, System/36 application compatibility G-8 z-variable A-167
application pop-up window attribute character 2-8
defining 17-30 attribute interaction table A-93
application program auto-enter
applying overrides when compiling 7-4 single-choice selection field 6-38
converting alphanumeric applications to DBCS appli- auto-selection
cations D-8 single-choice selection field 6-37
DBCS considerations D-7 automatic confirmation processing 16-31
describing data inside or outside 2-3 availability of choices
display files, use with 3-1 controlling 6-36
double-byte data, for D-7
file resource allocation for on remote system 3-1
opening 17-1 B
overriding backward field-exit processing 6-49
display file attributes in HLL 7-1 BASETYPE
display file names and attributes in HLL 7-3 summary table A-18
display file names in HLL 7-3
X-2 Application Display Programming V4R1

BASETYPE (continued) CFnn (command function) key
values A-14 CHCACCEL keyword 6-21
basic character D-4 defining 2-12
BASIC statement returning to program from online help
I/O requests for subfiles 4-15 information 18-20
beginning attribute character system performance considerations 14-3
definition 2-8 validity considerations 3-45
benefits CFnn (Command Function) keyword 2-11, 2-12
programmable mouse button 6-70 CGU (character generator utility)
bibliography H-1 DBCS sort table
bidirectional considerations copying from data file D-13
formatting A-80 copying to data file D-12
binary return codes for program menus 9-10 Japanese DBCS master sort table
binary value copying from data file D-13
display form A-24, A-25 copying to data file D-12
formatting A-24 CHANGE (Change) keyword 3-36
blank Change Command Default (CHGCMDDFT)
how to convert alphanumeric to DBCS D-25 command 9-16
blank lines for separating 17-36 Change Device Description (Display) (CHGDEVDSP)
border of window 5-7 command 2-26
BOTINST (bottom instruction) tag Change Display File (CHGDSPF) command
overview A-10 Change Display File (CHGDSPF)
bottom instruction (BOTINST) tag changing file description 2-2
overview A-10 changing
built-in function display files 2-5
CHKOBJ (check object) A-28, A-79 file description 2-2
CHKUSRCLS (check user class) A-28, A-80 DFRWRT (defer write) parameter
creating display file 3-26
described 14-1
C ENHDSP (enhance display) parameter 6-4
CALL (Call Program) dialog command B-4 indicating DBCS files D-5
call program running 2-5
commonly asked questions 17-37 SHARE parameter 14-2
Call Program (CALL) dialog command B-4 Change Job (CHGJOB) command 8-7
CANCEL dialog command B-6 Change Library List (CHGLIBL) command D-8
cancel key Change Menu (CHGMNU) command 9-16
defining 6-23 Change Printer File (CHGPRTF) command D-5
definition 6-23 Change View (CHGVIEW) dialog command B-6
menu panel 9-2 changing
cancel read operation, CL command for 3-49 DBCS conversion dictionaries
cancel-invite operation See editing DBCS conversion dictionaries
CL command for 3-49 display file 2-5
ILE C function for 3-49 file description 2-2
ILE COBOL statement for 3-49 file descriptions 2-5
ILE RPG operation for 3-49 window 5-10
System/36 application compatibility G-8 character
when to use 3-41 basic D-4
CAnn (command attention) key double-byte
defining 2-12 size D-4
returning to program from online help system processing of D-4
information 18-20 extended D-4
system performance considerations 14-3 selection A-9, A-155
validity considerations 3-45 sentence-ending A-2
CAnn (Command Attention) keyword shift-control
for keyboard control 2-11 See shift-control characters
symmetric
Arabic A-23
Index X-3
character (continued) CHKOBJ (Check Object) function A-28, A-79
symmetric (continued) CHKUSRCLS (Check User Class) function A-28,
Hebrew A-23 A-80
character beginning attribute 2-8 choice entry field, Common User Access 21-53
character ending attribute 2-8 choice-level help 6-56
character field attribute 2-8 CHRID (Character Identifier) keyword
character generator utility (CGU) description 13-1
DBCS sort table example 13-1
copying from data file D-13 CHRID (Character Identifier) parameter
copying to data file D-12 specifying 13-3
Japanese DBCS master sort table values, table of 13-5
copying from data file D-13 CIT (title citation) tag
copying to data file D-12 example, title citations A-13
Character Identifier (CHRID) keyword overview A-13
description 13-1 use in help module 20-4
example 13-1 CL (control language) program
character set and code page examples
considerations when printing 17-5 program menu 9-12
conversion, DDS 13-1 RTNPNT(*NO) for program menu 9-14
conversion, UIM A-19 I/O operations using 3-49
character translation inviting input from 3-30
using 13-2 reading-from-invited-devices from 3-33
character value CLASS (class definition) tag
display form A-25 BASETYPE summary table A-18
CHECK (Check) keyword decision tree for orientation A-21
parameters for cursor movement 2-16 display forms
RL and RLTB parameters 2-16 character value A-25
CHECK (validity checking) tag date value A-25
example, validity checking A-12 numeric values A-24
overview A-11 time value A-25
check box example
definition 6-1 class definitions A-24
example 6-1 numeric values table A-24
CHECK(FE) (Field Exit) keyword 6-18 overview A-14
CHGCMDDFT (Change Command Default) tags allowed table A-14
command 9-16 class definition (CLASS) tag
CHGDEVDSP (Change Device Description (Display)) BASETYPE summary table A-18
command 2-26 decision tree for orientation A-21
CHGDSPF (Change Display File) command display forms
changing character value A-25
display files 2-5 date value A-25
file description 2-2 numeric values A-24
DFRWRT (defer write) parameter time value A-25
described 3-26 example
when creating display file 3-26 class definitions A-24
DFRWRT parameter 14-1 example numeric values table A-24
ENHDSP (enhance display) parameter 6-4 overview A-14
indicating DBCS files D-5 tags allowed table A-14
running 2-5 CLEAR (Clear) keyword 2-11
SHARE parameter 14-2 Clear Lines (CLRL) keyword
CHGJOB (Change Job) command 8-7 example
CHGLIBL (Change Library List) command D-8 differences between OVERLAY and 3-15
CHGMNU (Change Menu) command 9-16 with (*NO) value 3-14
CHGPRTF (Change Printer File) command D-5 S/36 environment considerations G-1
CHGVIEW (Change View) dialog command B-6 system performance considerations 14-2
when to use 3-13

clearing Command Function (CFnn) keyword 2-12
environment considerations G-1 command key
lines on display See command attention (CAnn) key
S/36 environment considerations G-1 See command function (CFnn) key
using the CLRL keyword 3-13 command line
close operation entered too long 17-20
CL command for 3-49 interpretation 17-19
definition 3-49 optional 21-34
files shared in job 3-52 pop-up window 17-32
ILE C function for 3-49 restrictions 17-19
ILE COBOL statement for 3-49 tools 21-37
ILE RPG operation for 3-49 window 17-32
CLRL (Clear Lines) keyword window example 17-32
example Command Line (CMDLINE) dialog command B-7
differences between OVERLAY and 3-15 command line (CMDLINE) tag
with (*NO) value 3-14 overview A-26
S/36 environment considerations G-1 command prompting B-13
system performance considerations 14-2 command, CL
use 3-13 Add Message Description (ADDMSGD) 9-9
CMD (System Command) dialog command B-7 Add Search Index Entry (ADDSCHIDXE) 20-17
CMDLINE (Command Line) dialog command B-7 ADDMSGD (Add Message Description) 9-9
CMDLINE (command line) tag ADDSCHIDXE (Add Search Index Entry) 20-17
overview A-26 ALCOBJ (Allocate Object) 3-1
code page Allocate Object (ALCOBJ) 3-1
alternative display 13-1 canceling read operation with 3-49
conversion, UIM A-19 Change Command Default (CHGCMDDFT) 9-16
page 420 A-20 Change Device Description (CHGDEVDSP) 2-26
page 424 A-20 Change Display File (CHGDSPF)
part of CHRID keyword for display files 13-1 changing file description 2-5
code page and character set considerations when indicating DBCS files D-5
printing 17-5 running 2-5
codes, major/minor return SHARE parameter 14-2
See major/minor return code Change Job (CHGJOB) 8-7
colon (:) symbol A-5 Change Library List (CHGLIBL) D-8
COLOR (Color) keyword 2-22 Change Menu (CHGMNU) 9-16
color attribute 6-39 Change Printer File (CHGPRTF) D-5
color, adding to displays 2-22 CHGCMDDFT (Change Command Default) 9-16
column data CHGDEVDSP (Change Device Description) 2-26
formatting A-99 CHGDSPF (Change Display File)
column heading changing file description 2-5
list display 21-24 DFRWRT parameter 14-1
command attention (CAnn) key indicating DBCS files D-5
defining 2-12 SHARE parameter 14-2
returning to program from online help CHGJOB (Change Job) 8-7
information 18-20 CHGLIBL (Change Library List) D-8
system performance considerations 14-3 CHGMNU (Change Menu) 9-16
validity considerations 3-45 CHGPRTF (Change Printer File) D-5
Command Attention (CAnn) keyword Copy DBCS Font Table (CPYIGCTBL) D-9
for keyboard control 2-11 Copy DBCS Sort Table (CPYIGCSRT)
command function (CFnn) key copying DBCS master sort table from data
defining 2-12 file D-13
returning to program from online help copying DBCS master sort table to data
information 18-20 file D-12
system performance considerations 14-3 CPYIGCSRT (Copy DBCS Sort Table)
validity considerations 3-45 copying DBCS master sort table from data
file D-13
copying DBCS master sort table to data
file D-12
Index X-5
command, CL (continued) command, CL (continued)
CPYIGCTBL (Copy DBCS Font Table) D-9 CRTPRTF (Create Printer File) D-5
Create Command (CRTCMD) 20-16 CRTSCHIDX (Create Search Index) 20-16
Create Control Language Program (CRTCLPGM) CRTTBL (Create Table) 13-4
program menus 9-12 Delete DBCS Conversion Dictionary
Create DBCS Conversion Dictionary (DLTIGCDCT) D-19
(CRTIGCDCT) D-15 Delete DBCS Font Table (DLTIGCTBL) D-10
Create Display File (CRTDSPF) Delete DBCS Sort Table (DLTIGCSRT) D-14
building display with 1-4 Delete Menu (DLTMNU) 9-17
creating display files 2-4 Delete Override (DLTOVR) 7-5
DFRWRT parameter 14-1 Delete Panel Group (DLTPNLGRP) 20-15
display file menus 9-9 Delete Search Index (DLTSCHIDXE) 20-17
indicating DBCS files D-5 Display DBCS Conversion Dictionary
program menus 9-12 (DSPIGCDCT) D-19
SHARE parameter 14-2 Display Edit Description (DSPEDTD) 2-24
Create Document (CRTDOC) 20-18 Display File Description (DSPFD) 2-7
Create Duplicate Object (CRTDUPOBJ) Display File Field Description (DSPFFD) 2-7
DBCS conversion dictionary D-15 Display Help Document (DSPHLPDOC) 20-19
use 9-16 Display Menu Attributes (DSPMNUA) 9-16
Create Edit Description (CRTEDTD) 2-23 Display Override (DSPOVR) 7-6
Create Menu (CRTMNU) Display Program References (DSPPGMREF) 2-7
display file menus 9-9 DLTIGCDCT (Delete DBCS Conversion
program menus 9-13 Dictionary) D-19
Create Message File (CRTMSGF) 9-9 DLTIGCSRT (Delete DBCS Sort Table) D-14
Create Panel Group (CRTPNLGRP) DLTIGCTBL (Delete DBCS Font Table) D-10
building display with 1-5 DLTMNU (Delete Menu) 9-17
use 20-15 DLTOVR (Delete Override) 7-5
Create Printer File (CRTPRTF) D-5 DLTPNLGRP (Delete Panel Group) 20-15
Create Search Index (CRTSCHIDX) 20-16 DLTSCHIDXE (Delete Search Index Entry) 20-17
Create Table (CRTTBL) 13-4 DSPEDTD (Display Edit Description) 2-24
creating your own 20-16 DSPFD (Display File Description) 2-7
CRTCLPGM (Create Control Language Program) DSPFFD (Display File Field Description) 2-7
program menus 9-12 DSPHLPDOC (Display Help Document) 20-19
CRTCMD (Create Command) 20-16 DSPIGCDCT (Display DBCS Conversion
CRTDOC (Create Document) 20-18 Dictionary) D-19
CRTDSPF (Create Display File) DSPMNUA (Display Menu Attributes) 9-16
building display with 1-4 DSPOVR (Display Override) 7-6
creating display files 2-4 DSPPGMREF (Display Program References) 2-7
DFRWRT (defer write) parameter 14-1 Edit DBCS Conversion Dictionary
display file menus 9-9 (EDTIGCDCT) D-16
indicating DBCS files D-5 EDTIGCDCT (Edit DBCS Conversion
program menus 9-12 Dictionary) D-16
SHARE parameter 14-2 End Receive (ENDRCV) 3-31
CRTDUPOBJ (Create Duplicate Object) ENDRCV (End Receive) 3-31
saving and restoring DBCS dictionaries D-15 GO (Go to Menu)
use 9-16 generic menu specification 9-16
CRTEDTD (Create Edit Description) 2-23 use 9-1
CRTIGCDCT (Create DBCS Conversion Go to Menu (GO)
Dictionary) D-15 generic menu specification 9-16
CRTMNU (Create Menu) use 9-1
display file menus 9-9 help for, assigning 20-16
program menus 9-13 Initialize Diskette (INZDKT) D-9
CRTMSGF (Create Message File) 9-9 INZDKT (Initialize Diskette) D-9
CRTPNLGRP (Create Panel Group) Move Object (MOVOBJ) D-15
building display with 1-5 MOVOBJ (Move Object) D-15
use 20-15 OVERLAY (Overlay) keyword
effect on help-list updating 18-16

command, CL (continued) command, CL (continued)
Override with Display File (OVRDSPF) STRSEU (Start Source Entry Utility) 2-7
compared to CHGDSPF 2-2 Vary Configuration (VRYCFG) D-10
file attributes 7-1 VRYCFG (Vary Configuration) D-10
file names 7-3 commands that are too long 17-20
file names and attributes 7-3 comment A-6
indicating DBCS files D-5 common feedback area
Override with Printer File (OVRPRTF) D-5 definition 3-3
overrides common key assignments 21-38
commands that restrict 7-9 Common User Access (CUA)
improving performance for 14-2 choice entry field 21-53
OVRDSPF (Override with Display File) description 21-50
compared to CHGDSPF 2-2 entry dialog actions, table of 21-51
file attributes 7-1 entry display 21-53
file names 7-3 entry fields 21-54
file names and attributes 7-3 function key area 21-52
indicating DBCS files D-5 information displays 21-55
OVRPRTF (Override with Printer File) D-5 list display, example 21-55
Remove Search Index Entry (RMVSCHIDXE) 20-17 menu display, single-choice 21-52
Rename Object (RNMOBJ) D-15 message line relationship 21-52
Restore Library (RSTLIB) D-15 relationship to AS/400 system 21-1
Restore Object (RSTOBJ) selection choices 21-53
DBCS conversion dictionary D-15 single selection field operation, guidelines 21-53
DBCS sort table D-12 compact definition list
RMVSCHIDXE (Remove Search Index Entry) 20-17 example A-58
RNMOBJ (Rename Object) D-15 concatenation symbol A-5
RSTLIB (Restore Library) D-15 COND (condition definition) tag
RSTOBJ (Restore Object) CHKOBJ (Check Object) built-in function A-28
DBCS conversion dictionary D-15 CHKUSRCLS (Check User Class) built-in
DBCS sort table D-12 function A-28
RVKOBJAUT (Revoke Object Authority) D-15 example, conditioning option A-29
SAVCHGOBJ (Save Changed Object) D-15 overview A-27
Save Changed Object (SAVCHGOBJ) D-15 condition definition (COND) tag
Save Library (SAVLIB) D-15 CHKOBJ (Check Object) built-in function A-28
Save Object (SAVOBJ) CHKUSRCLS (Check User Class) built-in
DBCS conversion dictionaries D-15 function A-28
DBCS sort table D-12 example, conditioning option A-29
Save System (SAVSYS) overview A-27
DBCS conversion dictionary D-15 condition name, screen size 2-24
saving DBCS sort tables D-12 conditional expression A-27, A-79
SAVLIB (Save Library) D-15 conditional operator A-27
SAVOBJ (Save Object) conditioning
DBCS conversion dictionaries D-15 option
DBCS sort table D-12 example A-29
SAVSYS (Save System) confirmation list panel, creating 16-27
DBCS conversion dictionaries D-15 confirmation panel source 16-28
saving DBCS sort tables D-12 confirmation processing
Start Character Generator Utility (STRCGU) D-10 application programming 16-31
Start Programming Development Manager automatically 16-31
(STRPDM) 1-1 constant field
Start Search Index (STRSCHIDX) 20-8 definition 2-10
Start Source Entry Utility (STRSEU) 2-7 inserting text from message description 2-16
STRCGU (Start Character Generator Utility) D-10 using 2-10
STRPDM (Start Programming Development content separator A-1
Manager) 1-1 contextual help
STRSCHIDX (Start Search Index) 20-8 defining in UIM 17-16
Index X-7
contextual help (continued) Copy DBCS Sort Table (CPYIGCSRT) command
defining on display 18-3 copying DBCS master sort table from data file D-13
definition 19-2 copying DBCS master sort table to data file D-12
continued attribute copying
example A-1 DBCS files
continued-entry field from tape or diskette D-9
backward field-exit processing 6-49 onto tape or diskette D-9
creating 6-42 DBCS font table
DBCS considerations 6-43 copying from tape or diskette (restoring) D-9
example 6-43 copying onto diskette (saving) D-9
forward field-exit processing 6-49 DBCS sort table
keyboard function 6-44 copying from file (move from System/36) D-13
word wrap 6-43 copying to file (move to System/36 or
control character, shift AS/Entry) D-12
description of D-3 COPYR (copyright) tag
inserting D-6 overview A-30
control language (CL) program copyright (COPYR) tag
examples overview A-30
program menu 9-12 country-designated selection character 17-13
RTNPNT(*NO) for program menu 9-14 CPA8424 inquiry message D-10
I/O operations using 3-49 CPF4001-40FF message 8-10
inviting input from 3-30 CPF4101-43FF message 8-10
reading-from-invited-devices from 3-33 CPF4401-44FF message 8-10
control value 6-36 CPF4501-46FF message 8-10
controller, display station G-2 CPF4701-48FF message 8-10
controlling CPF4901-49FF message 8-10
availability of choices 6-36 CPF5001-50FF message 8-10
list entries on list display 17-10 CPF5101-53FF message 8-10
convention CPF5501-56FF message 8-10
recommended CPYIGCSRT (Copy DBCS Sort Table) command
list action (LISTACT) tag A-94 copying DBCS master sort table from data file D-13
pull-down field choice (PDFLDC) tag A-136 copying DBCS master sort table to data file D-12
required CPYIGCTBL (Copy DBCS Font Table) command
list action (LISTACT) tag A-94 copying from tape or diskette D-9
pull-down field choice (PDFLDC) tag A-136 copying onto tape or diskette D-9
conversion Create Command (CRTCMD) command 20-16
alphabetic A-4 Create Control Language Program (CRTCLPGM)
character set and code page, DDS 13-1 command 9-12
character set and code page, UIM A-19 Create DBCS Conversion Dictionary (CRTIGCDCT)
conversion, DBCS command D-15
alphanumeric applications to DBCS Create Display File (CRTDSPF) command
applications D-8 building display with 1-4
alphanumeric blanks to DBCS blanks D-25 creating display files 2-4
changing DBCS conversion dictionaries used D-20 DFRWRT (defer write) parameter
deleting unwanted DBCS words D-25 improving performance with 14-1
description D-19 write operation 3-26
entering double-byte data D-21 display file menus 9-9
function D-20 ENHDSP (enhance display) parameter 6-4
many alphanumeric entries at one time D-24 indicating DBCS files D-5
one alphanumeric entry to double-byte entry D-22 program menus 9-12
performing (including example operations) D-21 SHARE parameter 14-2
use while editing DBCS conversion dictionary D-25 Create Document (CRTDOC) command 20-18
where you can use D-20 Create Duplicate Object (CRTDUPOBJ) command
Copy DBCS Font Table (CPYIGCTBL) command DBCS conversion dictionaries D-15
copying from tape or diskette D-9 use 9-16
copying onto tape or diskette D-9

Create Edit Description (CRTEDTD) command CRTEDTD (Create Edit Description) command
example F-5 example F-5
running 2-23 running 2-23
use F-5 use F-5
Create Menu (CRTMNU) command CRTIGCDCT (Create DBCS Conversion Dictionary)
display file menus 9-9 command D-15
program menus 9-13 CRTMNU (Create Menu) command
Create Message File (CRTMSGF) command 9-9 display file menus 9-9
Create Panel Group (CRTPNLGRP) command program menus 9-13
building display with 1-5 CRTMSGF (Create Message File) command 9-9
use 20-15 CRTPNLGRP (Create Panel Group) command
Create Printer File (CRTPRTF) command D-5 building display with 1-5
Create Search Index (CRTSCHIDX) command 20-16 use 20-15
Create Table (CRTTBL) command 13-4 CRTPRTF (Create Printer File) command D-5
creating CRTSCHIDX (Create Search Index) command 20-16
application display with online help information, steps CRTTBL (Create Table) command 13-4
for 1-1 CSRINPONLY (Cursor Input Only) keyword 2-16
confirmation list panel 16-27 CSRLOC (Cursor Location) keyword 3-28
continued-entry field 6-42 CUA (Common User Access)
creating 6-35 choice entry field 21-53
data presentation panel 16-32 description 21-50
DBCS conversion dictionaries D-15 entry dialog actions, table of 21-51
display file and description 2-4 entry display 21-53
edit description F-5 entry fields 21-54
graphical look 6-1 function key area 21-52
horizontal selection field 6-14 information displays 21-55
list panel 16-13 list display, example 21-55
menu bar 6-7 menu display, single-choice 21-52
menu bar panel 16-50 message line relationship 21-52
menu panel 16-6 relationship to AS/400 system 21-1
message 8-1 selection choices 21-53
object 16-3 single selection field operation, guidelines 21-53
pull-down menu 6-18 cursor
scroll bar 6-31 actions 6-61
selection list 6-26 movement
vertical multiple-choice selection field 6-14 cursor keys 6-62
vertical single-choice selection field 6-13 horizontal selection field 6-16
window 5-3 right-to-left 2-16
CRTCLPGM (Create Control Language Program) tab key 6-61
command 9-12 to input-capable positions only 2-16
CRTCMD (Create Command) command 20-16 vertical selection field 6-15
CRTDOC (Create Document) command 20-18 position when help text displayed 17-17
CRTDSPF (Create Display File) command positioning
building display with 1-4 after output operation 3-28
creating display files 2-4 during I/O operations 3-41
DFRWRT (defer write) parameter each page of the subfile record 4-24
improving performance with 14-1 rules for list displays 21-31
write operation 3-26 subfiles 4-24
display file menus 9-9 System/36 application compatibility for display
ENHDSP (enhance display) parameter 6-4 files G-4
indicating DBCS files D-5 progression
program menus 9-12 entry field 2-17
SHARE parameter 14-2 restrict
CRTDUPOBJ (Create Duplicate Object) command PULLDOWN keyword 6-24
DBCS conversion dictionaries D-15 WINDOW keyword 5-5
use 9-16 returning position to an application 3-29
Index X-9
cursor in window 5-5 data description specifications (DDS) (continued)
Cursor Input Only (CSRINPONLY) keyword 2-16 display files (continued)
cursor key passing data between routing steps 11-3
movement 6-62 use in 2-7
DSPRL (Display Right-to-Left) keyword 2-19
entry displays 21-46
D ERRMSG (Error Message) keyword 5-6
damaged DBCS devices D-10 ERRMSGID (Error Message ID) keyword 5-6
data ERRSFL (Error Subfile) keyword 5-6
ASSUME keyword considerations for passing 11-1 example
checking validity of 3-37 5250 display station problems 3-45
data CLRL and OVERLAY keywords, differences
receiving 3-4 between 3-15
describing inside or outside your program 2-3 display file menu 9-8
externally described display file source 2-7
definition 2-3 DSPATR(PC) keyword 4-24
using 2-3 DSPMOD keyword 3-27
input DSPMOD keyword with subfiles 4-17
handling negative numeric 3-40 ERRSFL keyword 8-4
keeping 3-36 GRDATR (Grid Line Attribute) keyword 6-80
KEEP keyword considerations for passing 11-1 GRDBOX (Grid Box) keyword 6-80
levels of description 2-2 GRDCLR (Grid Clear) keyword 6-80
passing GRDLIN (Grid Line) keyword 6-80
between programs 11-1 GRDRCD (Grid Record) keyword 6-80
between programs in same routing step 11-1 grid line structure 6-80
between routing steps 11-3 HLPCMDKEY keyword 18-20
program-described HLPCMDKEY keyword with response
definition 2-3 indicators 18-21
described 2-4 HLPDOC keyword 18-10
using 2-27 HLPDOC keyword with option indicators 18-11
receiving 3-4 HLPPNLGRP keyword 18-7
relationship to display file 2-2 HLPPNLGRP keyword with option
rolling between two lines on display 3-16 indicators 18-8
sending and receiving 3-4 HLPRCD keyword 18-13
DATA (data presentation area) tag HLPRCD keyword with option indicators 18-14
example message subfile 4-23
data entry panel A-34 mnemonic 6-38
data entry panel with nested data group A-36 OVERLAY and CLRL keywords, differences
data presentation area with menu area A-36 between 3-15
two presentation areas for data items A-35 program menu 9-11
two-column format in data entry panel A-34 PULLINPUT keyword 6-54
overview A-31 push button 6-35
tags allowed table A-31 PUTOVR keyword 3-18
data area help 19-8 PUTOVR keyword for more efficient coding 3-20
data column (DATACOL) tag PUTOVR keyword for repeatedly entered
overview A-39 data 3-21
data description specifications (DDS) PUTRETAIN keyword, field level 3-24
See also display file PUTRETAIN keyword, record level 3-24
See also keyword, DDS ROLLUP, SFLSIZ, and SFLPAG keywords 4-19
CAnn keys, restrictions 2-13 scroll bar 6-33
changing 2-5 secondary help 18-18
CHECK(FE) (Field Exit) keyword 6-18 selection field 6-12
DBCS capabilities D-5 selection list 6-26
DDS form 2-7 SFLMSGID keyword 8-5
definition 1-1 SFLNXTCHG keyword 4-22
display files SFLPAG, SFLSIZ, and ROLLUP keywords 4-19
passing data between programs 11-1 SFLSIZ, ROLLUP, and SFLPAG keywords 4-19

data description specifications (DDS) (continued) data presentation panel source 16-35
example (continued) data queue
subfiles for two display sizes 2-25 waiting on display file and ICF file 12-1
two display sizes 2-24 data selection field (DATASLT) tag
variable-length record 4-20 example
field data entry panel A-53
color (table) 2-22 multiple-selection field A-53
emphasizing (table) 2-21 overview A-51
help record 5-7 tags allowed table A-51
information displays 21-47 data selection field choice (DATASLTC) tag
keywords ignored if display modes are overview A-55
changed 3-28 data stream, 5250 display
list display 21-49 See user-defined data stream (UDDS)
menu displays 21-45 data stream, user-defined
MSGLOC (Message Location) keyword 5-6 See user-defined data stream (UDDS)
NOCCSID (No CCSID) keyword 13-3 data tag, modified 2-10
processing order for subfile control 4-9 DATAC (data item choices) tag
program logic 4-31 overview A-38
programming example 5-15 DATACOL (data column) tag
RMVWDW (Remove Window) keyword 5-12 overview A-39
SFLMSG (Subfile Message) keyword 5-6 DATAGRP (data group) tag
SFLMSGID (Subfile Message identifier) overview A-40
keyword 5-6 DATAI (data item) tag
subfile, describing with 4-3 overview A-42
use 2-1 DATAIX (data item extender) tag
USRRSTDSP (User Restore Display) keyword 5-13 overview A-47
validity-checking keyword 5-6 DATASLT (data selection field) tag
WDWBORDER (Window Border) keyword 5-7 example
window 5-1 data entry panel A-53
WINDOW (Window) keyword 5-3 multiple-selection field A-53
data entry panel overview A-51
example A-34 tags allowed table A-51
introduction 16-49 DATASLTC (data selection field choice) tag
nested data group example A-36 overview A-55
data group (DATAGRP) tag date value
overview A-40 display form A-25
data item (DATAI) tag DBCS (double-byte character set) printing 17-37
overview A-42 DBCS and national language considerations 20-12
data item choices (DATAC) tag DBCS applications, converted from alphanumeric
overview A-38 applications D-8
data item extender (DATAIX) tag DBCS code scheme D-1
overview A-47 DBCS codes, not valid D-3
data item group scrolling 17-16 DBCS command
data presentation area (DATA) tag See command
example DBCS conversion
data entry panel A-34 alphanumeric blanks to DBCS blanks D-25
data entry panel with nested data group A-36 changing DBCS conversion dictionaries used D-20
data presentation area with menu area A-36 deleting unwanted DBCS words D-25
two presentation areas for data items A-35 description D-19
two-column format in data entry panel A-34 entering double-byte data D-21
overview A-31 function D-20
tags allowed table A-31 many alphanumeric entries at one time D-24
data presentation panel application one alphanumeric entry to double-byte entry D-22
programming 16-46 performing (including example operations) D-21
data presentation panel creating 16-32 use while editing DBCS conversion dictionary D-25
where you can use D-20
Index X-11
DBCS conversion dictionary DBCS-graphic fields on double-byte displays D-7
adding the first entries to D-17 DDS (data description specifications)
beginning editing D-17 See also display file
creating D-15 See also keyword, DDS
deleting D-19 CAnn keys, restrictions 2-13
deleting entry D-18 changing 2-5
description D-14 CHECK(FE) (Field Exit) keyword 6-18
displaying and printing D-19 DBCS capabilities D-5
editing (adding and changing terms) D-16 DDS form 2-7
editing suggestions D-18 definition 1-1
ending editing D-18 display files
moving entries D-18 passing data between programs 11-1
printing after displaying D-19 passing data between routing steps 11-3
system-supplied D-14 use in 2-7
user-created D-15 DSPRL (Display Right-to-Left) keyword 2-19
DBCS device entry displays 21-46
damaged D-10 ERRMSG (Error Message) keyword 5-6
display stations D-6 ERRMSGID (Error Message ID) keyword 5-6
DBCS display stations and number of input ERRSFL (Error Subfile) keyword 5-6
fields D-6 example
DBCS field 5250 display station problems 3-45
continued-entry field 6-43 CLRL and OVERLAY keywords, differences
determining the length D-4 between 3-15
DBCS file display file menu 9-8
description of D-5 display file source 2-7
restrictions D-6 DSPATR(PC) keyword 4-24
specifying D-5 DSPMOD keyword 3-27
DBCS font table DSPMOD keyword with subfiles 4-17
checking for existence of D-8 ERRSFL keyword 8-4
copying GRDATR (Grid Line Attribute) keyword 6-80
from tape (restore) D-10 GRDBOX (Grid Box) keyword 6-80
onto diskette (save) D-9 GRDCLR (Grid Clear) keyword 6-80
deleting D-10 GRDLIN (Grid Line) keyword 6-80
description of D-8 GRDRCD (Grid Record) keyword 6-80
restoring from tape or diskette D-9 grid line structure 6-80
saving onto diskette D-9 HLPCMDKEY keyword 18-20
system-supplied D-8 HLPCMDKEY keyword with response
DBCS grid line structure indicators 18-21
See grid line structure HLPDOC keyword 18-10
DBCS master sort table, Japanese HLPDOC keyword with option indicators 18-11
copying from data file D-13 HLPPNLGRP keyword 18-7
copying to data file D-13 HLPPNLGRP keyword with option
DBCS sort table indicators 18-8
checking for existence of D-12 HLPRCD keyword 18-13
copying HLPRCD keyword with option indicators 18-14
from data file (move from System/36) D-13 message subfile 4-23
to data file (move to System/36 or mnemonic 6-38
AS/Entry) D-12 OVERLAY and CLRL keywords, differences
deleting D-14 between 3-15
description D-11 program menu 9-11
restoring from tape or diskette D-12 PULLINPUT keyword 6-54
saving onto diskette D-12 push button 6-35
DBCS words, deleting during DBCS PUTOVR keyword 3-18
conversion D-25 PUTOVR keyword for more efficient coding 3-20
DBCS-graphic and shift control characters D-6 PUTOVR keyword for repeatedly entered
data 3-21
PUTRETAIN keyword, field level 3-24

DDS (data description specifications) (continued) defining (continued)
example (continued) attributes for entry fields 2-18
PUTRETAIN keyword, record level 3-24 cancel key 6-23
ROLLUP, SFLSIZ, and SFLPAG keywords 4-19 choice colors and attributes 6-39
scroll bar 6-33 choice-level help 6-56
secondary help 18-18 contextual help in UIM 17-16
selection field 6-12 cursor progression for entry fields 2-17
selection list 6-26 dialog variables 17-1
SFLMSGID keyword 8-5 function keys 17-20
SFLNXTCHG keyword 4-22 function keys and VARUPD value 17-21
SFLPAG, SFLSIZ, and ROLLUP keywords 4-19 header area 17-36
SFLSIZ, ROLLUP, and SFLPAG keywords 4-19 help for field 6-59
subfiles for two display sizes 2-25 lists 17-8
two display sizes 2-24 menu object 16-6
variable-length record 4-20 menu-bar switch key 6-22
field mnemonic 6-38
color (table) 2-22 MNUBARDSP (Menu-Bar Display) keyword
emphasizing (table) 2-21 application record 6-50, 6-62
help record 5-7 menu-bar record 6-51, 6-65
information displays 21-47 panel group object 16-13
keywords ignored if display modes are prolog area 17-36
changed 3-28 scrollable areas 17-14
list display 21-49 definition
menu displays 21-45 panel A-2
MSGLOC (Message Location) keyword 5-6 definition list
NOCCSID (No CCSID) keyword 13-3 device C-4
processing order for subfile control 4-9 definition list (DL) tag
program logic 4-31 example
programming example 5-15 compact definition list A-58
RMVWDW (Remove Window) keyword 5-12 definition list A-58
SFLMSG (Subfile Message) keyword 5-6 overview A-57
SFLMSGID (Subfile Message identifier) tags allowed table A-57
keyword 5-6 use in help module 20-5
subfile, describing with 4-3 Delete DBCS Conversion Dictionary (DLTIGCDCT)
use 2-1 command D-19
USRRSTDSP (User Restore Display) keyword 5-13 Delete DBCS Font Table (DLTIGCTBL) command
validity-checking keyword 5-6 deleting D-10
WDWBORDER (Window Border) keyword 5-7 use D-10
window 5-1 Delete DBCS Sort Table (DLTIGCSRT)
WINDOW (Window) keyword 5-3 command D-14
DDS form 2-7 Delete Menu (DLTMNU) command 9-17
DDS keyword Delete Override (DLTOVR) command 7-5
See keyword, DDS Delete Panel Group (DLTPNLGRP) command 20-15
DDS record Delete Search Index Entry (RMVSCHIDXE)
See record, DDS command 20-17
decimal point, edit description for F-4 deleting
Default (DFT) keyword DBCS conversion dictionary D-19
use 3-26 DBCS font table D-10
with ASSUME keyword 11-1 DBCS sort tables D-14
default value DBCS words D-25
fields 3-26 menu displays 9-17
defining overrides 7-5
accelerator key 6-21 panel group 20-15
application help 6-56 search index 20-17
application pop-up window 17-30 window 5-12
application window 17-30
Index X-13
description dialog command (continued)
field-level HELP (Help) B-9
definition 2-2 HELPHELP (Help Help) B-9
use 2-2 HELPIDX (Help Index) B-9
file-level HOME (Display Home Menu) B-9
definition 2-3 introduction B-1
use 2-3 KEYSHELP (Keys Help) B-10
record-level MENU (Menu) B-10
definition 2-3 Menu Bar Cursor Action (ACTIONS) B-4
use 2-3 MOREKEYS (Display More Function Keys) B-10
description, file Move to Top (MOVETOP) B-11
changing MOVETOP (Move to Top) B-11
reasons for 2-2 MSG (Display Message) B-11
with the CHGDSPF command 2-5 PAGEDOWN (Page Down) B-11
creating for display file 2-4 PAGEUP (Page Up) B-12
definition 1-1 PRINT (Print Display) B-12
detecting changes in 2-6 Print Display (PRINT) B-12
determining 2-2 PROMPT (Prompt) B-13
descriptive text area, entry displays 21-16 prompting an entry field B-13
device PULLDOWN (Display Pull-down Menu) B-14
DBCS RETRIEVE (Retrieve Command String) B-14
damaged D-10 Retrieve Command String (RETRIEVE) B-14
display stations D-6 RETURN (Return Control to Application) B-14
device definition list Return Control to Application (RETURN) B-14
definition 3-3 System Command (CMD) B-7
part of open feedback area C-4 valid uses B-1
DFRWRT (defer write) parameter variable update (VARUPD) attribute B-4
improving performance with 14-1 VARUPD attribute B-4
restrictions 3-26 dialog variable
using 3-26 defined by UIM A-167
DFT (Default) keyword defining 17-1
use 3-26 definition 17-1
with ASSUME keyword 11-1 displaying panel field value using 17-4
DFTVAL (Default Value) keyword 3-26 error messages 17-3
dialog command incorrect display characters 17-4
ACTIONS (Menu Bar Cursor Action) B-4 initial value 17-2
CALL (Call Program) B-4 restrictions 17-3
Call Program (CALL) B-4 variable pool 17-2
CANCEL (Cancel) B-6 Z36ENV A-167
Change View (Change View) B-6 ZCANCEL A-167
CHGVIEW (Change View) B-6 ZDBCS A-167
CMD (System Command) B-7 ZDSPSIZ A-167
CMDLINE (Command Line) B-7 ZEXIT A-167
Command Line (CMDLINE) B-7 ZJOB A-167
Display Help (DSPHELP) B-7 ZJOBNBR A-167
Display Home Menu (HOME) B-9 ZLMTCPB A-167
Display Message (MSG) B-11 ZMENU A-167
Display More Function Keys (MOREKEYS) B-10 ZMNULIB A-167
DSPHELP (Display Help) B-7 ZSYSNAM A-167
effects of B-1 ZUSER A-167
ENTER (Enter) B-8 dictionary, DBCS conversion
entry field prompting B-13 adding the first entries to D-17
EXIT (Exit Display) B-8 beginning editing D-17
Exit Display (EXIT) B-8 creating D-15
Extended Help (EXTHELP) B-9 deleting D-19
EXTHELP (Extended Help) B-9 deleting entry D-18

dictionary, DBCS conversion (continued) display file (continued)
description D-14 cursor positioning, System/36 application compat-
displaying and printing D-19 ibility G-4
editing (adding and changing terms) D-16 DBCS D-5
editing suggestions D-18 defining input and output 2-28
ending editing D-18 defining your display in 2-1
moving entries D-18 definition 1-1
printing after displaying D-19 description
system-supplied D-14 creating 2-4
user-created D-15 how changes are applied to 2-6
differences between pull-down menus and pop-up display station controller, System/36 application com-
windows 17-28 patibility G-2
diskette file displaying messages, System/36 application compat-
DBCS D-5 ibility G-4
display edit codes, user-defined F-4
creating UIM 16-13 edit descriptions F-1
list 17-8 erase-input-fields function, System/36 application
panel field value using dialog variables 17-4 compatibility G-3
UIM 16-13 establishing 2-1
user interface manager 16-13 example, programming 5-15
display attribute examples
choices 6-39 assigning space to program-described 2-27
color fields 2-22 building with online help 1-1
emphasizing fields 2-21 DDS source 2-7
display attribute (*DSPATR) parameter 6-40 replacing record formats on display 3-8
Display Attribute (DSPATR) keyword file entry field attributes 12-1
example source for PC value 4-24 function keys, System/36 application
use 3-28 compatibility G-7
with ASSUME keyword 11-1 HELP and HLPRTN keywords, System/36 application
with program-to-system field 2-21 compatibility G-7
display character input data
incorrect 17-4 System/36 application compatibility G-2
Display DBCS Conversion Dictionary (DSPIGCDCT) input data, System/36 application compatibility G-2
command D-19 input-only, defining 2-28
display device file lock 3-1
See display file maximum number of record formats in 2-15
display device support, DBCS D-6 obtaining information about 3-3
Display Edit Description (DSPEDTD) online help information
command 2-24 See online help information
display file opening 3-2
See also data description specifications (DDS) operations supported by the system and high-level
See also subfile languages
See also window CL commands 3-49
ASSUME (Assume) ILE C functions 3-49
considerations 11-1 ILE COBOL statements 3-49
attributes for fields, System/36 application compat- ILE RPG operations 3-49
ibility G-3 operator changes, System/36 application compat-
cancel-invite operation, System/36 application com- ibility G-3
patibility G-8 output-only, defining 2-28
characteristics of 2-1 overriding
closing 3-49 attributes in HLL programs 7-1
command key validity 3-45 file names and attributes in HLL programs 7-3
creating file names in HLL programs 7-3
ways for 2-5 passing data
with DDS 2-4 between programs 11-1
without DDS 2-27 between routing steps 11-3
Index X-15
display file (continued) display panel (PANEL) tag
put with explicit override, System/36 example
compatibility G-6 panel definition A-127
relationship to data 2-2 overview A-122
retain command and function keys, System/36 appli- tags allowed table A-122
cation compatibility G-9 display panel field value using dialog
return codes E-1 variables 17-4
screen size, specifying to improve Display Program References (DSPPGMREF)
performance 14-1 command 2-7
self-check, System/36 application compatibility G-2 Display Right-to-Left (DSPRL) keyword 2-19
sharing in same job 3-50 Display Size (DSPSIZ) keyword 2-24
signed numeric data, System/36 application compat- display station
ibility G-7 acquired, releasing from I/O operations 3-49
suspended 3-43 calculating maximum number of fields 3-39
System/36 application compatibility G-1 device description, changing for printers 2-26
System/36 functions not supported G-10 enhanced capabilities 6-4
use 3-1 models
waiting for data with ICF file, data queue 12-1 3180-2 3-27
window use 5-1 3197 3-27
display file attribute 5250, avoiding record format problems on 3-45
See file attribute obtaining information about 3-3
Display File Description (DSPFD) command 2-7 types 5-3, 6-1
Display File Field Description (DSPFFD) user-defined data streams, differences for 10-1
command 2-7 with UNLOCK 3-35
display file menu display station controller, System/36 application
See menu display compatibility G-2
display form display, application
binary value A-24 See application display
character value A-25 displaying
date value A-25 list 17-8
example numeric values A-24 message
numeric value A-24 about 8-1
time value A-25 in field 8-3
Display Help (DSPHELP) dialog command B-7 in program message queue 8-4
Display Help Document (DSPHLPDOC) on message line 8-2
command 20-19 on message line using message field 8-3
Display Home Menu (HOME) dialog command B-9 on message line when subfile control record
display I/O feedback area C-9 written 8-2
Display Menu Attributes (DSPMNUA) through subfile 8-4
command 9-16 override 7-6
Display Message (MSG) dialog command B-11 panel using request processor program 17-33
display mode System/36 application compatibility G-4
changing 4-17 DL (definition list) tag
DDS keywords ignored if changed 3-28 example
definition 4-17 a definition list A-58
displaying subfiles horizontally with 4-17 compact definition list A-58
Display Mode (DSPMOD) keyword overview A-57
description 3-27 tags allowed table A-57
example for subfiles 4-17 use in help module 20-5
sample subfile display for *DS3 4-19 DLTIGCDCT (Delete DBCS Conversion Dictionary)
sample subfile display for *DS4 4-18 command D-19
subfile use 4-17 DLTIGCSRT (Delete DBCS Sort Table)
Display More Function Keys (MOREKEYS) dialog command D-14
command B-10 DLTIGCTBL (Delete DBCS Font Table) command
Display Override (DSPOVR) command 7-6 deleting D-10
use D-10

DLTMNU (Delete Menu) command 9-17 DSPATR (Display Attribute) keyword (continued)
DLTOVR (Delete Override) command 7-5 with ASSUME keyword 11-1
DLTPNLGRP (Delete Panel Group) command 20-15 with program-to-system field 2-21
DLTSCHIDXE (Delete Search Index Entry) DSPEDTD (Display Edit Description)
command 20-17 command 2-24
document, office DSPFD (Display File Description) command 2-7
comparing with panel groups and records 18-2 DSPFFD (Display File Field Description)
creating for help 20-18 command 2-7
definition for help 1-6 DSPHELP (Display Help) dialog command B-7
examples DSPHLPDOC (Display Help Document)
HLPDOC keyword 18-10 command 20-19
HLPDOC keyword with option indicators 18-11 DSPIGCDCT (Display DBCS Conversion Dictionary)
steps for creating sample 20-18 command D-19
help, defining for 20-18 DSPMNUA (Display Menu Attributes)
help, specifying for 18-9 command 9-16
viewing without Help key 20-19 DSPMOD (Display Mode) keyword
double strike 17-36 description 3-27
double-byte character Display Mode (DSPMOD) 4-17
basic D-4 example for subfiles 4-17
code scheme D-1 sample subfile display for *DS3 4-19
DBCS-graphic D-6 sample subfile display for *DS4 4-18
examples subfile use 4-17
alphabetic characters coded in single-byte and use 3-27
double-byte scheme D-1 DSPOVR (Display Override) command 7-6
converting and entering an entry into a DSPPGMREF (Display Program References)
field D-22 command 2-7
copying DBCS font table to diskette D-9 DSPRL (Display Right-to-Left) keyword 2-19
copying DBCS font table to system D-9 DSPSIZ (Display Size) keyword
copying DBCS font table to tape D-9 specifying to improve performance 14-1
extended D-4 use 2-24
identifying a string of D-3, D-6 DTAQ (data queue) parameter 12-1
maximum number (extended) that can be duplicate object
displayed D-6 creating D-15
maximum number input fields displayed D-6 duplicating window 5-11
processing extended characters D-4 dynamic list column heading formatting
shift-control characters D-6 example A-88
shift-control characters, inserting D-6
size D-4
system processing of D-4 E
double-byte character set edit code
mnemonics 6-39 defining your own 2-23
double-byte code definition 2-23
effects of printing invalid D-3 description F-4
double-byte data IBM-supplied F-1
basic information D-1 use 2-23
considerations for using D-3 Edit Code (EDTCDE) keyword 2-23
designing application programs that process D-7 Edit DBCS Conversion Dictionary (EDTIGCDCT)
fields, determining the length D-4 command D-16
identifying D-3 edit description
restrictions on D-4 creating F-5
where you can use D-3 about F-5
double-byte display example F-5
effects of displaying DBCS-graphic fields D-7 decimal point F-4
DSPATR (Display Attribute) keyword description F-4
example source for PC value 4-24 IBM-supplied F-4
use 3-28 rules F-5
Index X-17
edit mask entry field
creating 2-19 attributes for 2-18
Edit Related Words display D-17 CUA 21-54
edit word cursor progression for 2-17
definition 2-23 entry displays 21-14
Edit Word (EDTWRD) keyword 2-23 menu selection 21-10
editing prompting B-13
DBCS conversion dictionary D-16 protecting using Edit Masks 2-19
EDTCDE (Edit Code) keyword 2-23 rules for displays 21-15
EDTIGCDCT (Edit DBCS Conversion Dictionary) entry field attribute
command D-16 creating 2-18
EDTWRD (Edit Word) keyword 2-23 entry pointer for list 17-10
effects of displaying DBCS-graphic fields on ERASE (Erase) keyword
double-byte displays D-7 erasing records 3-10
elements within a panel group 16-3 restriction with USRDSPMGT keyword G-10
embed System/36 application compatibility G-2
See imbed with OVERLAY keyword 3-10
emphasis values table A-101 Erase Input (ERASEINP) keyword
emphasizing fields 2-21 system performance considerations 14-3
enabled selection indicator in selection list use 3-23
example 6-29 erase-input-fields function, System/36 application
enabling graphical user interface (GUI) compatibility G-3
support 17-14 ERASEINP (Erase Input) keyword
End Receive (ENDRCV) command 3-31 system performance considerations 14-3
ending attribute character use 3-23
definition 2-8 erasing input 3-23
ENDRCV (End Receive) command 3-31 ERRMSG (Error Message) keyword 5-6, 8-2
engraved key restrictions 17-14 ERRMSGID (Error Message Identifier) keyword 5-6,
enhanced display (ENHDSP) parameter 8-2
writing records 6-4 error
ENHDSP (enhanced display) parameter See also major/minor return code
writing records 6-4 See also message
ENTER dialog command B-8 field validation 3-34
entering recovering from 8-11
commands that are too long 17-20 recovering from run-time 3-52
entry dialog actions, table of CUA 21-51 while scrolling 17-15
entry display error condition 17-15
CUA entry field 21-53 error message
description 21-11 dialog variables 17-3
descriptive text area 21-16 window 5-6
entry fields 21-14 Error Message (ERRMSG) keyword 5-6, 8-2
examples Error Message ID (ERRMSGID) keyword 5-6
AS/400-style 21-11 Error Message Identifier (ERRMSGID) keyword 8-2
CUA entry field 21-53 Error Message Subfile (ERRSFL) keyword
field prompts 21-12 example DDS source 8-4
instruction lines 21-12 message received from 5-6
online help information restriction with USRDSPMGT keyword G-10
DDS considerations 21-46 use 8-4
description 21-46 ERRSFL (Error Message Subfile) keyword
help areas for 21-46 example DDS source 8-4
types 21-46 message received from 5-6
operating guidelines 21-17 restriction with USRDSPMGT keyword G-10
possible choices information 21-16 use 8-4
prompt areas 21-12 example
title 21-11 a text area A-157
accelerator key 6-22

example (continued) example (continued)
alternate view of list 16-15 data description specifications (DDS) (continued)
application formatted area A-9 SFLSIZ, ROLLUP, and SFLPAG keywords 4-19
building sample display with online help 1-1 SLNO(*VAR) keyword 3-12
check box 6-1 subfiles for two display sizes 2-25
CL programs UNLOCK and INZRCD keywords 3-36
program menu 9-12 variable-length record 4-20
RTNPNT(*NO) for program menu, CL source data entry panel A-34, A-53
for 9-14 data entry panel with nested data group A-36
class definition A-24 data entry panel, two-column format A-34
command line pop-up window 17-32 data presentation panel 16-32
compact definition A-58 data presentation panel after scrolling 16-33
conditioning option A-29 defining MNUBARDSP on application record 6-50,
continued attribute A-1 6-62
continued-entry field 6-43 defining MNUBARDSP on menu-bar record 6-51,
data description specifications (DDS) 6-65
5250 display station problems 3-45 definition list A-58
ALWROL keyword 3-16 display with output and input fields displayed in
CHRID keyword 13-1 response to request 2-10
CLRL and OVERLAY keywords, differences documents, office
between 3-15 HLPDOC keyword 18-10
CLRL(*NO) keyword 3-14 HLPDOC keyword with option indicators 18-11
display file menu 9-8 double-byte characters
display file source 2-7 alphabetic characters coded in single-byte and
display size, for more than one 2-24 double-byte scheme D-1
DSPATR(PC) keyword 4-24 converting and entering entry into field D-22
DSPMOD keyword 3-27 copying DBCS font table to diskette D-9
DSPMOD keyword with subfiles 4-17 copying DBCS font table to system D-9
ERRSFL keyword 8-4 copying DBCS font table to tape D-9
HLPCMDKEY keyword 18-20 inserting shift-control characters D-6
HLPCMDKEY keyword with response dynamic list column heading A-88
indicators 18-21 edit description, creating F-5
HLPDOC keyword 18-10 enabled selection indicator in selection list 6-29
HLPDOC keyword with option indicators 18-11 entry displays
HLPPNLGRP keyword 18-7 CUA 21-53
HLPPNLGRP keyword with option typical 21-11
indicators 18-8 formatting example A-171
HLPRCD keyword 18-13 graphic image
HLPRCD keyword with option indicators 18-14 HTML keyword 6-85
INZRCD and UNLOCK keywords 3-36 grid line structure 6-80
message subfile 4-23 heading tags A-65
OVERLAY and CLRL keywords, differences help modules
between 3-15 command help 20-16
program logic for subfiles 4-31 imbedded 20-2
program menu 9-11 imported 20-3
PUTOVR keyword 3-18 ISCH tag 20-9
PUTOVR keyword for repeatedly entered ISCHSYN tag 20-9
data 3-21 LINK tag 20-15
PUTOVR keyword, more efficient coding 3-20 panel group with 20-2
PUTRETAIN keyword, field level 3-24 help panel definition A-61
PUTRETAIN keyword, record level 3-24 horizontal selection field 6-14
ROLLUP, SFLSIZ, and SFLPAG keywords 4-19 HTML keyword
RSTDSP parameter 3-43 graphic image 6-85
secondary help 18-18 resolving field overlap 6-83
SFLMSGID keyword 8-5 hypertext link A-80
SFLNXTCHG keyword 4-22 imbedded help A-66
SFLPAG, SFLSIZ, and ROLLUP keywords 4-19
Index X-19
example (continued) example (continued)
index search A-70 online help information (continued)
index search synonym A-72 HLPCMDKEY keyword 18-20
information display 21-17 HLPCMDKEY keyword with response
key definitions A-75 indicators 18-21
key list A-76 HLPDOC keyword 18-10
left-to-right formatting on left-to-right panel A-150 HLPDOC keyword with option indicators 18-11
left-to-right formatting on right-to-left panel A-150 HLPPNLGRP keyword 18-7
list HLPPNLGRP keyword with option
ordered A-119 indicators 18-8
simple A-152 HLPRCD keyword 18-13
translation A-159 HLPRCD keyword with option indicators 18-14
unordered A-165 imbedded help modules in panel group 20-2
list actions A-95 imported help modules in panel group 20-3
list area ISCH tag 20-9
example, UIM source A-86 ISCHSYN tag 20-9
list column groups A-87 LINK tag 20-15
three layout columns A-87 panel groups with help modules 20-2
list display secondary help 18-18
CUA 21-55 ordered list A-119
extended action entry area 21-21 output operation
list panel 16-14 effect of OVERLAY and ERASE on 3-10
list part A-107 overrides
menu area with groups A-112 applying when compiling program 7-5
menu bar attribute of display file 7-1
choices 6-7 different display file 7-3
DDS 6-62 different display file and attributes 7-4
panel 16-50 panel definition A-127
UIM A-108 panel groups
menu displays command help 20-16
display file menu 9-8 help modules 20-2
message file, adding messages to 9-9 HLPPNLGRP keyword 18-7
message file, describing menu actions in 9-6 HLPPNLGRP keyword with option
naming help formats in message file 9-6 indicators 18-8
program menu 9-11 imbedded help modules 20-2
program menu, CL source for 9-12 imported help modules 20-3
RTNPNT(*NO) for program menu, CL source ISCH tag 20-9
for 9-14 ISCHSYN tag 20-9
single choice 21-8 LINK tag 20-15
using options and GO command 9-2 paragraph continuation A-131
menu panel 16-6 paragraph tag A-121
creating 16-6 parameter list A-130
menu source 16-9 passing data
menu-bar choice help 6-57 between routing steps 11-3
menu-bar help list 6-59 in same routing step 11-1
message print title line A-145
ERRSFL keyword 8-4 program-described display file 2-27
SFLMSGID keyword 8-5 pull-down menu 6-18, 6-62
message, trailer A-148 PULLINPUT parameter 6-54
mnemonic, not valid DDS for 6-38 push button 6-35
multiple-choice selection list 6-25 radio button 6-1
multiple-selection field (UIM) A-53 record format, replacing 3-8
note A-117 record, DDS
numeric values table A-24 HLPCMDKEY keyword 18-20
online help information HLPCMDKEY keyword with response
command help 20-16 indicators 18-21
display showing help areas 18-4 HLPRCD keyword 18-13

example (continued) example (XMP) tag
record, DDS (continued) example, formatting an example A-171
HLPRCD keyword with option indicators 18-14 help module 20-6
secondary help 18-18 overview A-171
return-field (RTNFLD) parameter 6-56 EXIT (Exit Display) dialog command B-8
roll operation 3-16 Exit Display (EXIT) dialog command B-8
sample figure A-59 Exit key, using on menus 9-2
sample heading A-170 exit program
scroll bar 6-25, 6-30 commonly asked questions 17-37
selection field 6-12, 6-13 expression
selection list 6-26 conditional A-27, A-79
simple list A-152 extended action entry area
simple menu area A-112 list displays 21-24
single-choice selection field choice help 6-57 extended alphabetics
single-choice selection list 6-25 definition 13-1
SLNO (Starting Line Number) keyword 3-12 extended character
subfile processing D-4
*DS3 mode display 4-19 what happens when not processed D-4
*DS4 mode display 4-18 extended help
DSPATR(PC) keyword 4-24 definition 18-3, 19-2
DSPMOD keyword 4-17 Extended Help (EXTHELP) dialog command B-9
message subfile 4-23 extended help heading (XH1 through XH4) tag
program logic for subfiles 4-31 example, sample heading A-170
ROLLUP, SFLSIZ, and SFLPAG keywords 4-19 formatting rules A-170
sample display for changing information 4-2 overview A-170
sample display for display only 4-1 use in help module 20-4
sample display for input only 4-2 externally described data
sample display for task combination 4-2 advantages of 2-3
sample display with selection 4-1 definition 2-3
sample displays when rolling two or more use 2-3
records 4-28 EXTHELP (Extended Help) dialog command B-9
SFLNXTCHG keyword 4-22
SFLPAG, SFLSIZ, and ROLLUP keywords 4-19
SFLSIZ, ROLLUP, and SFLPAG keywords 4-19 F
variable-length record 4-20 F18=More indexes
vertical and horizontal, displayed at same removing access
time 4-16 feedback area
suppressed selection indicator in pull-down common 3-3
menu 6-21 error information 3-4
suppressed selection indicator in selection file-dependent 3-3
field 6-18 function keys 2-12
title citation A-13 get attributes C-12
translation list A-159 I/O
truth table A-162 common C-6
two presentation areas definition 3-3
data items A-35 display C-9
menu area A-36 for function keys 2-12
unavailable choice 6-37 open
unformatted lines A-77 definition 3-3
unordered list A-165 device definition list C-4
valid DDS for mnemonic 6-38 individual descriptions C-1
validity checking A-12 field
vertical multiple-choice selection field 6-14 attribute
vertical single-choice selection field 6-13 defining 2-18
window title 5-10 attributes, System/36 application compatibility G-3
window use 5-15 calculating maximum number for display
station 3-39
Index X-21
field (continued) field-level description
character, maximum length 2-11 definition 2-2
characteristics of 2-2 use 2-2
choice entry, Common User Access 21-53 field, graphic A-6
color 2-22 FIG (figure) tag
constant 2-10 example, sample figure A-59
cursor progression overview A-59
defining 2-17 use in help module 20-6
default values, specifying 3-26 figure (FIG) tag
defining example, sample figure A-59
attribute 2-18 overview A-59
cursor progression 2-17 use in help module 20-6
definition 2-2 file
display 2-7 DBCS
displaying 2-8 diskette D-5
emphasizing 2-21 display D-5
entry ICF D-5
See entry field printer D-5
erasing unprotected input and output/input 3-23 tape D-5
hidden 2-9 definition 2-3
input 2-9 display
input and output, displayed in response to See display file
request 2-10 shared in job
input-capable, limitations on number of 3-39 close operation for 3-52
keeping on display 3-23 input/output operation for 3-51
list 21-24 open operation for 3-51
maximum number in record format 2-10 source 1-2
menu selection entry 21-10 file attribute
message 2-10 building 7-1
numeric overriding
maximum length 2-11 along with display file name in HLL
output 2-9 programs 7-3
output/input 2-9 display files in HLL programs 7-1
overriding attributes or content of 3-18 file description
previously described 2-11 changing
program-to-system reasons for 2-2
understanding how to use 2-10 with the CHGDSPF command 2-5
with DSPATR keyword 2-21 creating for display file 2-4
record format 2-9 definition 1-1
reference 2-11 detecting changes in 2-6
validation errors 3-34 determining 2-2
zoned decimal, maximum length 2-11 file redirection
field (*FLD) special value 6-57 definition 7-6
field attribute character 2-8 different file types 7-6
Field Cursor Progression (FLDCSRPRG) level checking 7-6
keyword 2-17 same file types 7-6
Field Exit (CHECK(FE)) keyword 6-18 table of defaults for combinations 7-7
field location valid for input and output 7-7
input and output records 2-9 file resource
when to specify 2-11 how allocated 3-1
field prompt, entry displays 21-12 file-dependent feedback area 3-3
field value for display panel using dialog file-level description 2-3
variables 17-4 FLDCSRPRG (Field Cursor Progression)
field-exit processing keyword 2-17
backward 6-49 folding
forward 6-49 list panel 17-26

folding (continued) function key (continued)
multiple panels when EXIT requested 17-24 VARUPD value 17-21
when EXIT requested 17-24 function key area
font CUA 21-52
highlighting 17-36 menu displays, single-choice 21-8
font table, DBCS function key area help 19-15
description of D-8 function, built-in
determining existence D-8 CHKOBJ (check object) A-28, A-79
restoring from tape or diskette D-9 CHKUSRCLS (check user class) A-28, A-80
saving onto diskette D-9
format, record
See record format G
formatting get-attributes feedback area C-12
bidirectional considerations A-80 get-attributes operation
column data A-99 definition 3-4
display form ILE C function for 3-49
binary value A-24 ILE COBOL statement for 3-49
character value A-25 ILE RPG operation for 3-49
date value A-25 table of information available from 3-4
time value A-25 get-next-changed operation
example A-171 definition 4-14
function keys 17-20 get-next-changed operation for subfiles
IGC (ideographic characters) BASIC statement for 4-15
BOTINST (bottom instruction) tag A-10 ILE C function for 4-15
DATAC (data item choices) tag A-38 ILE COBOL statement for 4-15
PDFLDC (pull-down field choice) tag A-136 ILE RPG operation for 4-15
TOPINST (top instruction) tag A-161 get-relative operation
numeric value definition 4-13
example values table A-24 get-relative operation for subfiles
panel BASIC statement for 4-15
concepts 17-22 ILE C function for 4-15
user control 17-24 ILE COBOL statement for 4-15
panels 17-22 ILE RPG operation for 4-15
printed GETRETAIN (Get Retain) keyword 3-36
information area A-69 GO (Go to Menu) command
list area A-86 generic menu specification 9-16
forward field-exit processing 6-49 use 9-1
full screen mode Go to Menu (GO) command
help information A-61 generic menu specification 9-16
function key use 9-1
assignments, table 21-38 Grant Object Authority (GRTOBJAUT)
common assignments on AS/400-style command D-15
displays 21-38 graphical user interface (GUI)
CUA entry dialog actions, table of 21-51 support 17-14
DDS keywords for 2-11 graphics
defining field A-6
in DDS 2-11 literal A-6
in UIM 17-20 GRDATR (Grid Line Attribute) keyword 6-80
formatting in UIM 17-20 GRDBOX (Grid Box) keyword 6-80
handling in UIM 17-21 GRDCLR (Grid Clear) 6-80
optional for AS/400-style displays, table of 21-8 GRDLIN (Grid Line) 6-80
required for AS/400-style displays, table of 21-8 GRDRCD (Grid Record) 6-80
retain command, System/36 application Grid Box (GRDBOX) keyword 6-80
compatibility G-9 Grid Clear (GRDCLR) 6-80
scrolling in UIM 17-15 Grid Line (GRDLIN) 6-80
System/36 application compatibility G-7
Index X-23
Grid Line Attribute (GRDATR) keyword 6-80 help (continued)
grid line structure panels A-3
definition 6-79 HELP (help module) tag
example, DDS 6-80 example, help panel definition A-61
hardware requirements 6-82 overview A-60
overview 6-79 placement in UIM source 20-2
window 6-81 UIM source showing panel groups with help
Grid Record (GRDRCD) 6-80 modules 20-2
group object, panel A-2 HELP (Help) keyword
GRTOBJAUT (Grant Object Authority) enabling the Help key 18-2
command D-15 function key use 2-12
GUI (graphical user interface) specifying alternative 2-13
support 17-14 System/36 application compatibility G-7
guideline help area
CUA, single selection field operation 21-53 See online help information
message 21-49 Help Area (HLPARA) keyword 18-4
operating help boundary
entry displays 21-17 definition 18-17
information displays 21-21 Help Boundary (HLPBDY) keyword
list display 21-26 secondary help 18-18
menu displays 21-10 use 18-17
Help Command Key (HLPCMDKEY) keyword
restriction with USRDSPMGT keyword G-10
H use 18-20
H specification HELP dialog command B-9
definition 18-4 help display
effect on help-list updating 18-16 See online help information
entering in DDS source 18-4 Help Document (HLPDOC) keyword
order in DDS source 18-4 for specifying the document name 18-9
paging order 18-16 with HLPRCD and HLPPNLGRP 18-11
H1 through H4 (headings) with option indicators 18-11
example Help Exclude (HLPEXCLD) keyword 18-6
heading tags A-65 help for field 6-59
help module 20-4 Help Full (HLPFULL) keyword 18-6
overview A-65 help group
handle on list entry 17-9 definition 18-17
handling function keys and VARUPD value 17-21 help information
header area See online help information
defining 17-36 Help InfoSeeker (HLPSHELF) keyword 18-6
heading (H1 through H4) tag Help key 19-1
example See also ALTHELP (Alternate Help) keyword
heading tags A-65 See also HELP (Help) keyword
overview A-65 enabling 18-2
use in help module 20-4 results when pressed 18-1
heading, column 21-24 returning to program after pressing 18-20
help returning to program without pressing 18-22
choice-level 6-56 help list
data area 19-8 defining for application 6-58
defining for application 6-56 definition 18-16
displayed in window 5-7, 5-9 help module
field 6-59 contained in different help panel group, using 20-3
function key area 19-15 definition 20-2
item specific 6-58 emphasizing and formatting text within 20-4
list area 19-3 examples
menu area 19-6 command help 20-16
menu bar area 19-13 imbedded 20-2
imported 20-3

help module (continued) highlight phrases table A-63
examples (continued) highlighted phrase (HP0 through HP9) tag
ISCH tag 20-9 overview A-63
ISCHSYN tag 20-9 use in help module 20-4
LINK tag 20-15 highlighting
panel group with 20-2 selection characters A-9, A-155
headings, adding 20-4 highlighting and fonts 17-36
highlighting text 20-4 HLL (high-level language)
hypertext 20-13 overriding display file attributes in programs 7-1
linking 20-13 overriding display file names and attributes in pro-
making lists 20-5 grams 7-3
names 20-2 overriding display file names in programs 7-3
organizing panel group with 20-2 recognizing the I/O requests supported by 3-49
paragraphs and notes, defining 20-4 System/36 application compatibility G-1
programming keywords and variables, HLPARA (Help Area) keyword 18-4
identifying 20-5 HLPBDY (Help Boundary) keyword
structured text, indicating 20-6 secondary help 18-18
using more than once 20-2 use 18-17
help module (HELP) tag HLPCMDKEY (Help Command Key) keyword
example, help panel definition A-61 response indicators, sample source with 18-21
overview A-60 restriction with USRDSPMGT keyword G-10
placement in UIM source 20-2 sample DDS source 18-20
Help Panel Group (HLPPNLGRP) keyword use 18-20
use 18-6 HLPDOC (Help Document) keyword
with HLPRCD and HLPDOC keywords 18-8 examples
with option indicators 18-8 option indicators, sample source with 18-11
Help Record (HLPRCD) keyword sample DDS source 18-10
with HLPDOC keyword in same file 18-15 specifying the document name 18-9
with HLPPNLGRP keyword in same file 18-12 with HLPRCD and HLPPNLGRP keywords 18-11
with option indicators 18-13 with option indicators 18-11
Help Return (HLPRTN) keyword HLPEXCLD (Help Exclude) keyword 18-6
returning to your program after help 18-22 HLPFULL (Help Full) keyword 18-6
System/36 application compatibility G-7 HLPPNLGRP (Help Panel Group) keyword
Help Search Index (HLPSCHIDX) keyword 18-6 example
Help Sequencing (HLPSEQ) keyword 18-17 option indicators, sample source with 18-8
help sublist sample DDS source 18-7
definition 18-17 use 18-6
help text with HLPRCD and HLPDOC keywords 18-8
See online help information with option indicators 18-8
help text displayed according to cursor HLPRCD (Help Record) keyword
position 17-17 example
Help Title (HLPTITLE) keyword 18-6 option indicators, sample source with 18-14
HELPHELP dialog command B-9 sample DDS source 18-13
HELPIDX dialog command B-9 secondary help 18-18
hexadecimal data A-6 with HLPDOC keyword in same file 18-15
hidden field with HLPPNLGRP keyword in same file 18-12
definition 2-9 with option indicators 18-13
using 2-9 HLPRTN (Help Return) keyword
hierarchy, index search 20-11 returning to your program after help 18-22
high-level language (HLL) System/36 application compatibility G-7
overriding display file attributes in programs 7-1 HLPSCHIDX (Help Search Index) keyword 18-6
overriding display file names and attributes in pro- HLPSEQ (Help Sequencing) keyword 18-17
grams 7-3 HLPSHELF (Help InfoSeeker) keyword 18-6
overriding display file names in programs 7-3 HLPTITLE (Help Title) keyword 18-6
recognizing the I/O requests supported by 3-49 HOME (Display Home Menu) dialog command B-9
Index X-25
HOME (Home) keyword 2-12 ICF file
horizontal selection field DBCS D-5
cursor movement 6-16, 6-17 file entry field attributes 12-1
example 6-14 waiting for data with display file, data queue 12-1
HP0 through HP9 (highlighted phrase) tag identifier fields for menu displays 21-34
overview A-63 identifier, level 2-6
use in help module 20-4 ideographic characters (IGC)
HTML (Hypertext Markup Language) keyword formatting
inserting 6-82 BOTINST (bottom instruction) tag A-10
resolving field overlap 6-83 DATAC (data item choices) tag A-38
examples 6-83 PDFLDC (pull-down field choice) tag A-136
restrictions 6-87 TOPINST (top instruction) tag A-161
hypertext IGC (ideographic characters)
See also online help information formatting
definition 20-13 BOTINST (bottom instruction) tag A-10
hypertext link DATAC (data item choices) tag A-38
example A-80 PDFLDC (pull-down field choice) tag A-136
hypertext link definition (LINK) tag TOPINST (top instruction) tag A-161
conditional expressions IGCALTTYP (Alternative Data Type) keyword D-5
CHKOBJ built-in function A-79 ILE C functions
CHKUSRCLS (check user class) built-in I/O requests for subfiles 4-15
function A-80 mapping to I/O operations 3-49
example, hypertext link A-80 ILE COBOL statement
overview A-78 I/O requests for subfiles 4-15
placement in UIM source 20-15 mapping to I/O operations 3-49
Hypertext Markup Language (HTML) keyword ILE RPG operation
resolving field overlap 6-83 I/O requests for subfiles 4-15
using 6-82 mapping to I/O operations 3-49
hypertext reference phrase imbed help (IMHELP) tag
See also online help information example, imbedded help A-66
definition 20-14 overview A-66
placement in UIM source 20-2
imbedding
I nesting source files A-6
I/O feedback area imbedding source files
common C-6 nesting imbeds A-6
contents 3-3 imbedding UIM source files A-6
definition 3-3 IMHELP (imbed help) tag
display C-9 example, imbedded help A-66
I/O operation overview A-66
acquiring a display station for 3-2 placement in UIM source 20-2
locking keyboard and positioning cursor 3-41 UIM source showing panel groups using 20-2
mapping to HLL operations UIM source showing panel groups with help
CL commands 3-49 modules 20-2
ILE C functions 3-49 IMPORT (import) tag
ILE COBOL statements 3-49 overview A-67
ILE RPG operations 3-49 placement in UIM source 20-3
obtaining information about 3-3 UIM source showing panel groups using 20-3
releasing an acquired display station from 3-49 improving
requesting productivity with UIM 15-1
for subfile control record formats 4-15 system performance with displays 14-1
for subfile record formats 4-12 improving productivity with UIM 15-1
for subfiles 4-12 inactive subfile record
I/O request definition 4-4
high-level languages, table of subfile 4-15 incorrect characters in dialog variable 17-4
supported by high-level languages 3-49

incorrect display characters 17-4 information display (continued)
incorrect printer characters 17-4 operating guidelines 21-21
INDARA (Indicator Area) keyword 2-15 prompt areas 21-19
index search titles 21-19
See also online help information information, help
F18=More indexes See online help information
removing access 19-5 information, location
index search (ISCH) tag See location information, displays
parameter list A-70 information, online help
placement in UIM source 20-9 See online help information
index search function InfoSeeker
See online help information See online help information
index search hierarchy 20-11 initial menu
Index search key (F11) 20-6 definition 9-3
index search subtopic (ISCHSUBT) tag Initialize Diskette (INZDKT) command D-9
parameter list A-71 Initialize Record (INZRCD) keyword 3-35
placement in UIM source 20-11 initializing
index search synonym (ISCHSYN) tag list display 17-8
parameter list A-72 output/input fields 3-29
placement in UIM source 20-9 initializing list 17-8
indicator input data
definition 2-14 from the display
option how the system reads 3-40
definition 2-14 reading 3-33
for display files 2-14 reading invited 3-31
passing information via 2-14 handling negative numeric 3-40
response inviting
definition 2-12 from CL programs 3-30
for display files 2-14 to the display 3-30
selection keeping 3-36
in pull-down menu 6-20 reading while writing output 3-40
in selection field 6-17 System/36 application compatibility G-2
in selection list 6-28 input field
setting off 2-15 definition 2-9
setting when data is changed 3-36 displayed characters on DBCS display D-6
types for display files 2-14 erasing 3-23
Indicator Area (INDARA) keyword 2-15 example, display with output and 2-10
INFO (information area) tag improving performance when sending records
overview A-68 with 14-2
print formatting considerations A-69 using 2-9
information area input file
printed A-69 defining 2-28
scrolling 17-16 input not waited for, canceling 3-41
information area (INFO) tag input operation
overview A-68 effect of INZRCD and UNLOCK keywords on 3-36
print formatting considerations A-69 input-capable field
information area scrolling 17-16 limitations on number of 3-39
information display input-only file
CUA 21-55 defining 2-28
description 21-17 input/output feedback area
example 21-17 common C-6
instruction lines 21-20 contents 3-3
location information 21-19 definition 2-12, 3-3
online help information display C-9
DDS considerations 21-47 input/output operation
description 21-47 acquiring a display station for 3-2
help areas for 21-47
Index X-27
input/output operation (continued) ISCHSYN (index search synonym) tag
files shared in a job 3-51 parameter list A-72
locking keyboard and positioning cursor 3-41 placement in UIM source 20-9
mapping to HLL operations item-specific help 6-58
CL commands 3-49
ILE C functions 3-49
ILE COBOL statements 3-49 J
ILE RPG. operations 3-49 job
mapping to I/O operations 3-49 close operation for files shared in 3-52
obtaining information about 3-3 input/output operation for files shared in 3-51
releasing an acquired display station from 3-49 open operation for files shared in 3-51
requesting
for subfile control record formats 4-15
for subfile record formats 4-12
K
KEEP (Keep) keyword
for subfiles 4-12
considerations 11-1
input/output request
example DDS source 11-3
high-level languages, table of subfile 4-15
restriction with USRDSPMGT keyword G-10
supported by high-level languages 3-49
sharing file between programs 11-1
inserting
entry from list display 17-10
key
HTML tags 6-82
Cancel and Exit, using on menus 9-2
inserting entry from list 17-10
CAnn and CFnn, defining 2-12
instruction line
CFnn (command function), validity
entry displays 21-12
considerations 3-45
information displays 21-20
command
list display 21-22
defining 2-12
menu displays, single-choice 21-9
validity considerations 3-45
interaction
command attention (CAnn) 2-12
between menu bar and application 6-50
command function (CFnn) 2-12
between menu bar and pull-down menu 6-60
function
interactive response time for list displays 17-11
defining 2-11
interpretation of command line 17-19
INVITE (Invite) keyword
key assignments, common
system performance considerations 14-3
See common key assignments
use 3-30
key definition
invite operation
example A-75
CL command for 3-49
key interaction for menu bars and pull-down
definition 3-30
menus 6-60
ILE C function for 3-49
key list (KEYL) tag
ILE COBOL statement for 3-49
example, key list A-76
ILE RPG operation for 3-49
overview A-76
system performance considerations 14-3
tags allowed table A-76
invited input, reading from the display 3-31
key list item (KEYI) tag
INZDKT (Initialize Diskette) command D-9
example, key definitions A-75
INZINP (Initialize Input) keyword
overview A-74
performance considerations 14-3
keyboard
INZRCD (Initialize Record) keyword
locking 3-10
example with UNLOCK keyword 3-36
locking during I/O operations 3-41
use 3-35
unlocking while the program is processing
ISCH (index search) tag
data 3-35
parameter list A-70
keyboard function
continued-entry field 6-44
ISCHSUBT (index search subtopic) tag
KEYI (key list item) tag
parameter list A-71
example, key definitions A-75
overview A-74

KEYL (key list) tag keyword, DDS (continued)
example, key list A-76 DSPATR (Display Attribute) (continued)
overview A-76 emphasizing fields with 2-21
tags allowed table A-76 PC value 3-28, 4-24
KEYSHELP dialog command B-10 table of color effects 2-22
keyword, DDS table of values for 2-21
Alternative Help (ALTHELP) 2-13 with ASSUME keyword 11-1
ALTHELP (Alternative Help) 2-13 DSPMOD (Display Mode)
ALTPAGEDWN (Alternative Page Down) 2-13 description 3-27
ALTPAGEUP (Alternative Page Up) 2-13 example for subfiles 4-17
ALWROL (Allow Roll) subfile display for *DS3 4-19
example 3-16 subfile display for *DS4 4-18
use 3-16 DSPRL (Display Right-to-Left) keyword 2-19
ASSUME (Assume) DSPSIZ (Display Size)
example DDS source 11-1, 11-3 specifying to improve performance 14-1
use 11-1 use 2-24
with DFT keyword 11-1 EDTCDE (Edit Code) 2-23
CAnn (Command Attention) 2-11 EDTWRD (Edit Word) 2-23
CFnn (Command Function) 2-11 ERASE (Erase)
CHANGE (Change) 3-36 effect on output operation 3-10
CHECK (Check) example of effects with OVERLAY 3-10
AB value 3-37 Erase Input (ERASEINP)
description 2-16 system performance considerations 14-3
M10 value 3-37 use 3-23
M11 value 3-37 ERASEINP (Erase Input)
ME value 3-37 system performance considerations 14-3
MF value 3-37 use 3-23
VN value 3-37 ERRMSG (Error Message) 8-2
VNE value 3-37 ERRMSGID (Error Message Identifier) 8-2
CHRID (Character Identifier) keyword 13-1 Error Message (ERRMSG) 8-2
CLEAR (Clear) 2-11 Error Message Identifier (ERRMSGID) 8-2
CLRL (Clear Line) 3-13 Error Subfile (ERRSFL)
example with *NO value description 8-4
example with OVERLAY 3-15 example DDS source 8-4
system performance considerations 14-2 ERRSFL (Error Subfile)
coding, more efficient 3-20 description 8-4
COLOR (Color) 2-22 example DDS source 8-4
COMP (Comparison) 3-37 field
CSRINPONLY (Cursor Input Only) 2-16 color (table) 2-22
CSRLOC (Cursor Location) 3-28 emphasizing (table) 2-21
Cursor Input Only (CSRINPONLY) 2-16 Field Cursor Progression (FLDCSRPRG) 2-17
data, repeatedly entered 3-21 field level 3-24
DFT (Default) FLDCSRPRG (Field Cursor Progression) 2-17
description 3-26 function keys, defining with 2-11
with ASSUME keyword 11-1 GETRETAIN (Get Retain) 3-36
DFTVAL (Default Value) 3-26 GRDATR (Grid Line Attribute) 6-80
Display Attribute (DSPATR) GRDBOX (Grid Box) 6-80
adding color to fields with 2-22 GRDCLR (Grid Clear) 6-80
emphasizing fields with 2-21 GRDLIN (Grid Line) 6-80
PC value 3-28, 4-24 GRDRCD (Grid Record) 6-80
table of values for 2-21, 2-22 Grid Box (GRDBOX) 6-80
with ASSUME keyword 11-1 Grid Clear (GRDCLR) 6-80
Display Right-to-Left (DSPRL) keyword 2-19 Grid Line (GRDLIN) 6-80
Display Size (DSPSIZ) Grid Line Attribute (GRDATR) 6-80
use 2-24 Grid Record (GRDRCD) 6-80
DSPATR (Display Attribute) H specifications
adding to color to fields with 2-22 See H specifications
Index X-29
keyword, DDS (continued) keyword, DDS (continued)
HELP (Help) HOME (Home) 2-12
enabling Help key 18-2 HTML (Hypertext Markup Language)
function key use 2-12 resolving field overlap 6-83
Help Area (HLPARA) 18-4 restrictions 6-87
Help Boundary (HLPBDY) use 6-82
use 18-17 INDARA (Indicator Area) 2-15
Help Command Key (HLPCMDKEY) Indicator Area (INDARA) 2-15
use 18-20 Initialize Record (INZRCD)
Help Document (HLPDOC) use 3-35
description 18-9 INVITE (Invite)
with option indicators 18-11 description 3-30
Help Exclude (HLPEXCLD) 18-6 system performance considerations 14-3
Help Full (HLPFULL) 18-6 INZINP (Initialize Input), system performance consid-
Help InfoSeeker (HLPSHELF) 18-6 erations 14-3
Help Panel Group (HLPPNLGRP) INZRCD (Initialize Record)
description 18-6 example with UNLOCK keyword 3-36
with option indicators 18-8 use 3-35
Help Record (HLPRCD) KEEP (Keep)
description 18-12 description 11-1
with option indicators 18-13 example DDS source 11-3
Help Return (HLPRTN) 18-22 keywords ignored if display modes are
Help Search Index (HLPSCHIDX) 18-6 changed 3-28
Help Sequencing (HLPSEQ) 18-17 LOCK (Lock) 3-42
Help Title (HLPTITLE) 18-6 MDTOFF (Modified Data Tag Off) 3-23
HLPARA (Help Area) 18-4 MOUBTN (Programmable Mouse Button) 6-69
HLPBDY (Help Boundary) MSGALARM (Message Alarm) 8-7
secondary help 18-18 MSGID (Message Identifier) 8-3
use 18-17 OVERLAY (Overlay)
HLPCMDKEY (Help Command Key) description 3-10
response indicators, sample source with 18-21 effect on output operation 3-10
sample DDS source 18-20 example of effects with ERASE 3-10
use 18-20 example with CLRL 3-15
HLPDOC (Help Document) system performance considerations 14-3
description 18-9 Override Attribute (OVRATR)
option indicators, sample source with 18-11 system performance considerations 14-2
sample DDS source 18-10 use 3-18
with option indicators 18-11 Override Data (OVRDTA) 3-20
HLPEXCLD (Help Exclude) 18-6 system performance considerations 14-2
HLPFULL (Help Full) 18-6 OVRATR (Override Attribute)
HLPPNLGRP (Help Panel Group) system performance considerations 14-2
description 18-6 use 3-18
option indicators, sample source with 18-8 OVRDTA (Override Data) 3-20
sample DDS source 18-7 system performance considerations 14-2
with option indicators 18-8 Page Down (PAGEDOWN) 2-12
HLPRCD (Help Record) Page Up (PAGEUP)
description 18-12 defining 2-12
option indicators, sample source with 18-14 PAGEDOWN (Page Down) 2-12
sample DDS source 18-13 PAGEUP (Page Up) 2-12
secondary help 18-18 PASSRCD (Passed Record) 11-3
with option indicators 18-13 PRINT (Print)
HLPRTN (Help Return) 18-22 enabling 2-25
HLPSCHIDX (Help Search Index) 18-6 for function key 2-12
HLPSEQ (Help Sequencing) 18-17 results available (table) 2-25
HLPSHELF (Help InfoSeeker) 18-6 Programmable Mouse Button (MOUBTN) 6-69
HLPTITLE (Help Title) 18-6 PSHBTNCHC (Push Button Choice) 6-35

PSHBTNFLD (Push Button Field) 6-35 SFLMSG (Subfile Message) (continued)
Push Button Choice (PSHBTNCHC) 6-35 displaying on message line when subfile control
Push Button Field (PSHBTNFLD) 6-35 record written 8-2
Put with Explicit Override (PUTOVR) SFLMSGID (Subfile Message Identifier)
description 3-18 defining 4-4
system performance considerations 14-2 description 4-4
Put-Retain (PUTRETAIN) displaying on message line when subfile control
description 3-23 record written 8-2
PUTOVR (Put with Explicit Override) sample DDS 8-5
description 3-18 SFLMSGKEY (Subfile Message Key)
example 3-18 description 4-4
system performance considerations 14-2 displaying messages from a program message
PUTRETAIN (Put-Retain) queue 8-4
description 3-23 SFLMSGRCD (Subfile Message Record)
for record level 3-24 description 4-4
RANGE (Range) 3-37 displaying messages from a program message
Return Cursor Location (RTNCSRLOC) 3-29 queue 8-4
Roll Down (ROLLDOWN) SFLNXTCHG (Subfile Next Changed)
defining 2-12 description 4-4
response indicators for 2-15 example 4-22
Roll Up (ROLLUP) SFLPAG (Subfile Page)
example with SFLSIZ and SFLPAG 4-19 example with ROLLUP and SFLSIZ 4-19
for function key 2-12 use in subfile control record format 4-3
improving subfile performance 14-1 SFLPGMQ (Subfile Program Message Queue)
response indicators for 2-15 description 4-4
ROLLDOWN (Roll Down) displaying messages from a program message
defining 2-12 queue 8-4
response indicators for 2-15 SFLRCDNBR (Subfile Record Number)
ROLLUP (Roll Up) description 4-4
example with SFLSIZ and SFLPAG 4-19 improving subfile performance 14-1
for function key 2-12 SFLRNA (Subfile Records Not Active) 4-4
improving subfile performance 14-1 SFLROLVAL (Subfile Roll Value) 4-4
response indicators for 2-15 SFLRTNSEL (Subfile Return Selected Choice) 6-27
RTNCSRLOC (Return Cursor Location) 3-29 SFLSCROLL (Subfile Scroll) 6-28
Set Off (SETOF or SETOFF) 2-15 SFLSIZ (Subfile Size)
SETOF or SETOFF (Set Off) 2-15 example with ROLLUP and SFLPAG 4-19
SFL (Subfile) 4-3 use in subfile control record format 4-3
SFLCHCCTL (Subfile Choice Control) 6-26 SFLSNGCHC (Subfile Single-Choice
SFLCLR (Subfile Clear) 4-4 Selection) 6-26
SFLCSRPRG (Subfile Cursor Progression) 2-18 SLNO (Starting Line Number)
SFLCSRRRN (Subfile Cursor Relative Record example with *VAR value 3-12
Number) 3-29 use 3-11
SFLCTL (Subfile Control) 4-3 Starting Line Number (SLNO)
SFLDLT (Subfile Delete) 4-4 example with *VAR value 3-12
SFLDROP (Subfile Drop) 4-4 use 3-11
SFLDSP (Subfile Display) 4-3 Subfile Choice Control (SFLCHCCTL) 6-26
SFLDSPCTL (Subfile Display Control) 4-4 Subfile Clear (SFLCLR) 4-4
SFLEND (Subfile End) 4-4 Subfile Control (SFLCTL) 4-3
SFLENTER (Subfile Enter) 4-4 Subfile Cursor Progression (SFLCSRPRG) 2-18
SFLFOLD (Subfile Fold) 4-4 Subfile Cursor Relative Record Number
SFLINZ (Subfile Initialize) 4-4 (SFLCSRRRN) 3-29
SFLLIN (Subfile Line) 4-4 Subfile Delete (SFLDLT) 4-4
SFLMODE (Subfile Mode) 3-29 Subfile Display (SFLDSP) 4-3
SFLMSG (Subfile Message) Subfile Display Control (SFLDSPCTL) 4-4
defining 4-4 Subfile Drop (SFLDROP) 4-4
description 4-4
Index X-31
Subfile End (SFLEND) 4-4 Window Title (WDWTITLE) 5-9
Subfile Enter (SFLENTER) 4-4 Word Wrap (WRDWRAP) 2-20, 6-43
Subfile Fold (SFLFOLD) 4-4
Subfile Initialize (SFLINZ) 4-4
Subfile Line (SFLLIN) 4-4 L
Subfile Message (SFLMSG) layout
defining 4-4 title lines table A-143
description 4-4 layout and positions summary table A-105, A-106
displaying on message line when subfile control left-to-right formatting on a left-to-right panel
record written 8-2 example A-150
Subfile Message Identifier (SFLMSGID) left-to-right formatting on a right-to-left panel
defining 4-4 example A-150
description 4-4 level identifier
displaying on message line when subfile control changes in 2-6
record written 8-2 definition of 2-6
sample DDS 8-5 determining 2-6
Subfile Message Key (SFLMSGKEY) library
description 4-4 QUSRSYS library 13-4
displaying messages from a program message QUSRTOOL
queue 8-4 definition 1-5
Subfile Message Record (SFLMSGRCD) display examples 21-1
description 4-4 panel groups, using word processing functions
displaying messages from a program message when creating 18-2
queue 8-4 limitations
Subfile Mode (SFLMODE) 3-29 panel formatter 17-24
Subfile Next Changed (SFLNXTCHG) line
description 4-4 clearing a specified number of 3-13
example 4-22 rolling data between 3-16
Subfile Page (SFLPAG) line, instruction
example with ROLLUP and SFLSIZ 4-19 See instruction line
use in subfile control record format 4-3 line, options 21-23
Subfile Program Message Queue (SFLPGMQ) LINES (unformatted lines) tag
description 4-4 example, unformatted lines A-77
displaying messages from a program message overview A-77
queue 8-4 use in help module 20-6
Subfile Record Number (SFLRCDNBR) LINK (hypertext link) tag
description 4-4 conditional expressions
improving subfile performance 14-1 CHKOBJ built-in function A-79
Subfile Records Not Active (SFLRNA) 4-4 CHKUSRCLS (check user class) built-in
Subfile Return Selected Choice (SFLRTNSEL) 6-27 function A-80
Subfile Roll Value (SFLROLVAL) 4-4 example, hypertext link A-80
Subfile Scroll (SFLSCROLL) 6-28 overview A-78
Subfile Single-Choice Selection placement in UIM source 20-15
(SFLSNGCHC) 6-26 UIM source showing panel groups using 20-15
Subfile Size (SFLSIZ) list
example with ROLLUP and SFLPAG 4-19 adding entries, 17-9
use in subfile control record format 4-3 displaying 17-8
UNLOCK (Unlock) incomplete processing 17-9
effects on input operation 3-36 initializing 17-8
example with INZRCD keyword 3-36 inserting entry from 17-10
unlocking while program is processing data 3-35 key A-76
USRDFN (User-Defined) 10-1 managing 17-7
validity-checking 3-37 ordered A-118
VALNUM 3-37 parameter A-129
VALUES (Values) 3-37 part A-107

list (continued) list display (continued)
removing entry from 17-10 list entries on 17-10
simple A-152 list fields 21-24
unordered A-164 list format, empty list 21-33
updating 17-9 list one selection item 21-33
LIST (list area) tag online help information
example DDS considerations 21-49
dynamic list column heading formatting A-88 description 21-48
list area A-86 help areas for 21-48
list area with list group columns A-87 types 21-48
list area with three layout columns A-87 operating
overview A-82 extended action entry area 21-28
print formatting considerations A-86 guidelines 21-26
tags allowed table A-83 list control field 21-26
list action (LISTACT) tag lists when options are specified 21-29
example, list actions A-95 options line 21-23
overview A-90 paging location information 21-25
recommended conventions A-94 positioning
required conventions A-94 lists 21-26
list area lowercase names in a list 21-27
example rules for cursor 21-31
with list group columns A-87 prompt areas 21-22
with three layout columns A-87 response time for 17-11
help 19-3 rules, error condition 21-32
printed A-86 titles 21-22
scrolling 17-15 list entries on a list display 17-10
list area (LIST) tag list entry handle 17-9
example list entry pointer 17-10
dynamic list column heading formatting A-88 list fields on list displays 21-24
list area A-86 list panel
list area with list group columns A-87 application programming 16-25
list area with three layout columns A-87 creating 16-13
overview A-82 source 16-17
print formatting considerations A-86 list part (LP) tag
tags allowed table A-83 example, list part A-107
list area scrolling 17-15 overview A-107
list column (LISTCOL) tag use in help module 20-5
formatting considerations A-99 list view (LISTVIEW) tag
overview A-96 layout and positions summary table A-105, A-106
list column group (LISTGRP) tag overview A-105
overview A-103 LISTACT (list action) tag
list defining in UIM example, list actions A-95
list definition (LISTDEF) tag overview A-90
emphasis values table A-101 recommended conventions A-94
overview A-100 required conventions A-94
list display LISTCOL (list column) tag
changing list control field 21-28 formatting considerations A-99
column headings 21-24 overview A-96
description 21-21 LISTDEF (list definition) tag
error condition rules 21-32 emphasis values table A-101
example overview A-100
CUA 21-55 LISTGRP (list column group) tag
extended action entry area 21-21 overview A-103
extended action entry area 21-24 LISTVIEW (list view) tag
format in an empty situation 21-33 layout and positions summary table A-105, A-106
instruction line 21-22 overview A-105
Index X-33
literal, graphic A-6 MDTOFF (Modified Data Tag Off) keyword 3-23
location information, displays 21-19 member
location of window 5-4, 5-5 source
LOCK (Lock) keyword 3-42 definition 1-2
locked display file 3-1 MENU (menu area) tag
locking keyboard and positioning cursor 3-41 example
LP (list part) tag menu area with groups A-112
example, list part A-107 simple menu area A-112
overview A-107 tags allowed table A-111
use in help module 20-5 menu area
help 19-6
scrolling 17-16
M with groups
Main Menu display 9-2 example A-112
major/minor return code menu area (MENU) tag
major return code definitions example
00 8-11 menu area with groups A-112
02 8-11 simple menu area A-112
03 8-11 tags allowed table A-111
04 8-11 menu bar
08 8-11 area help 19-13
11 8-11 creating 6-7
34 8-11 definition 6-7
80 8-11 example 6-7, 6-62
81 8-11 interaction with application 6-50
82 8-11 interaction with pull-down menu 6-60
83 8-11 using 17-27
recovering from errors menu bar (MBAR) tag
completion with exceptions 8-12 example, menu bar A-108
device or session error on open or acquire opera- overview A-108
tion 8-14 tags allowed table A-108
normal completion 8-11 menu bar choice (MBARC) tag
permanent device or session error on I/O opera- overview A-110
tion 8-13 tags allowed table A-110
permanent system or file errors 8-13 Menu Bar Cursor Action (ACTIONS) dialog
recoverable device or session errors on I/O oper- command B-4
ation 8-14 menu bar panel
understanding 8-10 application programming 16-63
managing creating 16-50
panel functions 17-13 source 16-53
managing list 17-7 menu definition 16-2
managing panel functions 17-13 MENU dialog command B-10
markup separator A-1 menu display
MBAR (menu bar) tag See also application display
example, menu bar A-108 Cancel key, using on 9-2
overview A-108 changing attributes 9-16
tags allowed table A-108 choosing which to display at sign-on time 9-3
MBARC (menu bar choice) tag creating UIM 16-6
overview A-110 CUA 21-52
tags allowed table A-110 deleting 9-17
MDT (modified data tag) description 21-8
character translation 13-2 determining the previous menu 9-1
definition 2-10 display file
resetting 3-23 building 9-7
with ASSUME keyword 11-1 creating for 9-9
creating menu object for 9-9
creating message file for 9-9

menu display (continued) menu display (continued)
display file (continued) program (continued)
DDS considerations 9-4 exiting without returning to previous menu 9-13
DDS, specifying 9-7 passing parameters for 9-10
defining 9-4 returning to after running the GO command 9-1
definition 9-1 selection entry field 21-10
help for 9-4 system, running 9-1
menu and help information, describing 9-7 user interface manager (UIM) 16-6
message file, adding messages to 9-9 user-defined
message file, describing menu actions in 9-5 running 9-1
naming help formats for 9-6 types 9-1
parts of 9-4 menu group (MENUGRP) tag
displaying attributes 9-16 tags allowed table A-114
example menu group (MNUGRP) tag
display file menu 9-8 overview A-114
message file, adding messages to 9-9 menu item (MENUI or MI) tag
message file, describing menu actions in 9-6 overview A-115
naming help formats in message file 9-6 MENU object type 9-1
program menu 9-11 menu object, defining
program menu, CL source for 9-12 *DSPF menu 9-7
RTNPNT(*NO) for program menu, CL source *UIM menu 16-6
for 9-14 menu-bar choice
sample single-choice 21-8 defining 6-7
using options and GO command 9-2 translation of 6-9
Exit key, using on 9-2 menu-bar choice help
function key area 21-8 example 6-57
identifier fields 21-34 Menu-Bar Display (MNUBARDSP) keyword
initial 9-3 application record 6-50, 6-62
instruction line 21-9 menu-bar record 6-51, 6-65
menu displays, single-choice 21-9, 21-10 menu-bar help list
menu selection entry field 21-10 example 6-59
menu stack 9-1 menu-bar record
naming conflicts, avoiding MNUBARDSP 6-65
changing command default after command dupli- menu-bar separator
cation 9-16 creating 6-7
generic menu specifications 9-16 defining 6-8
naming, deciding how to 9-15 definition 6-7
placement in library list 9-16 suppressing 6-8
specifying library 9-16 menu-bar switch key
ways 9-15 defining 6-22
online help information definition 6-22
DDS considerations 21-45 MENUGRP (menu group) tag
description 21-44 overview A-114
help areas for 21-44 tags allowed table A-114
types 21-44 MENUI or MI (menu item) tag
operating guidelines 21-10 overview A-115
optional 21-34 message
options 21-9 automatically handling error 8-7
program available functions for display files 8-1
building 9-11 CPF4001-40FF 8-10
creating CL program for 9-12 CPF4101-43FF 8-10
creating display file 9-12 CPF4401-44FF 8-10
creating menu for 9-13 CPF4501-46FF 8-10
defining 9-10 CPF4701-48FF 8-10
definition 9-1 CPF4901-49FF 8-10
describing 9-11 CPF5001-50FF 8-10
entering CL source for 9-12
Index X-35
message (continued) messages displayed on message line priorities 8-3
CPF5101-53FF 8-10 mixed display
CPF5501-56FF 8-10 example 21-21
creating and displaying 8-1 mnemonic
description 21-49 coding, not valid 6-38
displaying defining 6-38
in field 8-3 definition 6-1
in program message queue 8-4 valid coding for 6-38
message line for 8-3 MNUBARDSP (Menu-Bar Display) keyword
on message line 8-2 application record 6-50, 6-62
on message line when subfile control record menu-bar record 6-51, 6-65
written 8-2 mode, display
priorities for 8-3 changing 4-17
through subfile 8-4 definition 4-17
error displaying subfiles horizontally with 4-17
displaying from subfiles 4-23 modified data tag (MDT)
examples character translation 13-2
ERRSFL keyword 8-4 definition 2-10
SFLMSGID keyword 8-5 resetting 3-23
guidelines 21-49 with ASSUME keyword 11-1
line relationship, CUA 21-52 Modified Data Tag Off (MDTOFF) keyword 3-23
reasons for 8-1 monitor message 8-9
sounding alarm for 8-7 MOREKEYS (Display More Function Keys) dialog
system command B-10
alert 8-9 MOUBTN (Programmable Mouse Button)
analyzing 8-8 keyword 6-69
detecting 8-8 mouse button, programmable
diagnostic 8-8 See Programmable Mouse Button (MOUBTN)
escape 8-8 keyword
file status code 8-8 Move Object (MOVOBJ) command D-15
message queues 8-8 Move to Top (MOVETOP) dialog command B-11
notifying 8-8 MOVETOP (Move to Top) dialog command B-11
permanent 8-9 moving
reporting 8-8 cursor
status 8-8 CSRINPONLY keyword 2-16
System/36 application compatibility G-4 using cursor keys 6-62
understanding 8-9 using tab key 6-61
window 5-6 window 5-11
Message Alarm (MSGALARM) keyword 8-7 MOVOBJ (Move Object) command D-15
message description 2-16 MSG (Display Message) dialog command B-11
message field to display message on message MSGALARM (Message Alarm) keyword 8-7
line 8-3 MSGID (Message Identifier) keyword 8-3
message file MSGLOC (Message Location) keyword 5-6
adding messages to 9-9 multiple panel foldup when EXIT requested 17-24
creating 9-9 multiple-choice selection field
describing menu action in 9-5 colors and display attributes 6-40
message line definition 6-10
definition 2-10 vertical 6-14
scrolling 17-15 multiple-choice selection list
use 2-10 creating 6-26
Message Location (MSGLOC) keyword 5-6 definition 6-24
message subfile 4-23 example 6-25
message text symbol A-5 multiple-selection field (UIM)
message, monitor example A-53
See message

OfficeVision/400* document
N See document, office
name syntax OL (ordered list) tag
alphabetic conversion A-4 example, ordered list A-119
object name overview A-118
restrictions A-4 tags allowed table A-118
on HELP tag use in help module 20-5
restrictions A-4 online help information
national language considerations and DBCS 20-12 adding to a display 18-1
national language translation contextual help 18-3
sentence-ending characters A-2 creating a sample display with 1-1
negative numeric input data, handling 3-40 description 21-44
nesting documents, office
imbeds comparing with panel groups and records 18-2
source files A-6 creating for help 20-18
No CCSID (NOCCSID) keyword 13-3 help, defining for 20-18
NOCCSID (No CCSID) keyword 13-3 help, specifying for 18-9
node (hypertext), definition HLPDOC keyword 18-10
See online help information, hypertext HLPDOC keyword with option indicators 18-11
NOTE (note) tag option indicators, specifying with 18-11
use in help module 20-4 panel groups and records in same file,
note (NT or NOTE) tag with 18-11
overview A-117 viewing without Help key 20-19
note (NT) tag enabling Help key 18-2
example, using a note A-117 entry displays
tags allowed table A-117 DDS considerations 21-46
use in help module 20-4 description 21-46
NT (note) tag help areas for 21-46
example, using a note A-117 types 21-46
tags allowed table A-117 example
use in help module 20-4 building with display file 1-1
NT or NOTE (note) tag command help 20-16
overview A-117 display showing help areas 18-4
numeric input data, handling negative 3-40 HLPCMDKEY keyword 18-20
numeric value HLPCMDKEY keyword with response
display form A-24 indicators 18-21
binary A-24 HLPDOC keyword 18-10
example values table A-24 HLPDOC keyword with option indicators 18-11
HLPPNLGRP keyword 18-7
HLPPNLGRP keyword with option
O indicators 18-8
object
HLPRCD keyword 18-13
creating 16-3
HLPRCD keyword with option indicators 18-14
definition 2-1
imbedded help modules in panel group 20-2
enhancements to object management D-15
imported help modules 20-3
panel group A-3
ISCH tag 20-9
object name
ISCHSYN tag 20-9
name syntax A-4
LINK tag 20-15
restrictions A-4
panel groups with help modules 20-2
ODP (open data path)
secondary help 18-18
definition 3-50
exiting, System/36 application compatibility G-8
for improving system performance 14-2
extended help 18-3
sharing for same job 14-2
H specifications
office document
definition 18-4
See document, office
entering in DDS source 18-4
order in DDS source 18-4
Index X-37
online help information (continued) online help information (continued)
help areas panel groups (continued)
DDS keywords for 18-4 deleting 20-15
defining 18-3 deleting search index 20-17
office documents, specifying for 18-9 designing hypertext links 20-14
panel groups, specifying 18-6 documents and records in same file with 18-8
record 18-4 emphasizing and formatting text in help
records, specifying for 18-12 modules 20-4
required DDS source 18-4 entering UIM source for 20-1
Help key full-screen help, indicating 18-6
enabling 18-2 headings in help modules, adding 20-4
returning control to program after pressing 18-20 help modules, linking 20-13
returning control to program without help modules, using more than once 20-2
pressing 18-22 help, specifying for 18-6
help text displayed according to cursor highlighting text in help modules 20-4
position 17-17 HLPPNLGRP keyword 18-7
hypertext HLPPNLGRP keyword with option
creating links 20-14 indicators 18-8
definition 20-13 hypertext 20-13
designing links 20-14 hypertext reference phrase 20-14
reference phrase, definition 20-14 index search function 20-6
index search Index search, enabling 18-6, 19-4
accessing 19-4 InfoSeeker, enabling 18-6, 19-3
index search function making lists in help modules 20-5
See also InfoSeeker function name of help screen, defining 18-6
deciding topics 20-9 option indicators, specifying with 18-8
function 20-6 organizing with help modules 20-2
root words, choosing for topic 20-10 paragraphs and notes, defining in help
root words, defining 20-9 modules 20-4
root words, including as synonyms 20-9 programming keywords and variables, identifying
synonyms for root words, designating 20-9 in help modules 20-5
synonyms, choosing for topic 20-10 purpose of UIM tags 20-1
topics, defining 20-9 records and documents in same file with 18-8
UIM tags for 20-6 removing entries from search index 20-17
information display root words, choosing for index search
DDS considerations 21-47 topic 20-10
description 21-47 root words, defining 20-9
help areas for 21-47 root words, including as index search
InfoSeeker synonyms 20-9
accessing 19-3 secondary help, excluding as 18-6
list display structured text in help modules, indicating 20-6
DDS considerations 21-49 synonyms for root words, designating 20-9
description 21-48 synonyms, choosing for index search
help areas for 21-48 topic 20-10
menu display topics, defining 20-9
DDS considerations 21-45 user-defined, enabling 19-4
help areas for 21-44 uses for 20-1
types 21-44 using a help module contained in different 20-3
overview 19-2 record, DDS
panel groups comparing with panel groups and
adding entries to search index 20-17 documents 18-2
command help, assigning 20-16 entering source 18-14
comparing with documents and records 18-2 help boundaries 18-17
creating 20-15 help group 18-17
creating hypertext links 20-14 help list 18-16
creating search index 20-16 help sublist 18-17
DDS functions for 18-6 help, defining for 20-19

online help information (continued) option indicator (continued)
record, DDS (continued) example (continued)
help, specifying for 18-12 HLPRCD keyword with option indicators 18-14
HLPCMDKEY keyword 18-20 MNUBARCHC (Menu Bar Choice) keyword 6-9
HLPCMDKEY keyword with response secondary help 18-18
indicators 18-21 office documents, defining for help with 18-11
HLPRCD keyword 18-13 panel groups, defining with 18-8
HLPRCD keyword with option indicators 18-14 records, defining with 18-13
option indicators, specifying with 18-13 removing from record area 2-15
paging between help displays 18-16 option line (OPTLINE) tag
paging through H specifications 18-16 overview A-120
primary help 18-16 options line, list displays 21-23
restrictions on 18-15 OPTLINE (option line) tag
restrictions on secondary help 18-19 overview A-120
secondary help 18-16, 18-18 ordered list (OL) tag
secondary help, displaying 18-17 example, ordered list A-119
secondary, determining the sequence of 18-18 overview A-118
with documents in same file 18-15 tags allowed table A-118
with panel groups in same file 18-12 use in help module 20-5
returning control to program after pressing Help organization
key 18-20 panel outline A-4
returning control to program without pressing Help UIM menu outline A-4
key 18-22 outline, panel
user-defined panel group organization A-4
accessing 19-4 UIM menu outline A-4
open data path (ODP) outline, UIM menu
definition 3-50 organization A-4
for improving system performance 14-2 output data
sharing for same job 14-2 writing and reading input at same time 3-40
open feedback area writing to display 3-5
contents 3-3 output field
definition 3-3 definition 2-9
device definition list C-4 editing 2-23
individual descriptions C-1 examples
open operation displayed in response to request, display with
definition 3-2 input and 2-10
file resource allocation for 3-1 using 2-9
files shared in job 3-51 output file
ILE C function for 3-49 defining 2-28
ILE COBOL statement for 3-49 output operation
ILE RPG operation for 3-49 effect of OVERLAY and ERASE on 3-10
obtaining information about 3-3 positioning cursor after 3-28
opening returning cursor position to application 3-29
UIM application 17-1 output-only file, defining 2-28
operating guideline output/input field
entry displays 21-17 definition 2-9
information displays 21-21 erasing 3-23
list display using 2-9
See list display OVERLAY (Overlay) keyword
menu displays, single choice 21-10 description 3-10
operator effect on help-list updating 18-16
conditional A-27 erasing records 3-10
relational A-11 example
option indicator differences between CLRL and 3-15
example examples
HLPDOC keyword with option indicators 18-11 with ERASE keyword 3-10
HLPPNLGRP keyword with option
indicators 18-8
Index X-39
OVERLAY (Overlay) keyword (continued) overriding and sharing printer file 17-37
system performance considerations 14-3 OVRATR (Override Attribute) keyword
System/36 application compatibility G-2 system performance considerations 14-2
override use 3-18
applying when compiling program 7-4 OVRDSPF (Override with Display File) command
attributes 3-18 compared to CHGDSPF 2-2
CL programs file attributes 7-1
included in 7-1 file names 7-3
QCMDEXC, use of 7-1 file names and attributes 7-3
commands that ignore or restrict 7-9 indicating DBCS files D-5
Delete Override (DLTOVR) command 7-5 OVRDTA (Override Data) keyword
deleting 7-5 description 3-20
determining whether or not to use 7-1 system performance considerations 14-2
different file types 7-6 OVRPRTF (Override with Printer File)
display file attributes in HLL programs 7-1 command D-5
display file names and attributes in HLL
programs 7-3
display file names in HLL programs 7-3 P
Display Override (DSPOVR) command 7-6 P (paragraph) tag
displaying 7-6 example, paragraph tag A-121
effect on other jobs 7-1 overview A-121
entering 7-1 placement in UIM source 20-2
examples use in help module 20-4
applying when compiling program 7-5 page 420 for code page conversion A-20
attribute of display file 7-1 page 424 for code page conversion A-20
different display file 7-3 Page Down (PAGEDOWN) keyword
different display file and attributes 7-4 for function key 2-12
file redirection specifying alternative 2-13
definition 7-6 page eject during printing 17-37
different file types 7-6 Page Up (PAGEUP) keyword
level checking (LVLCHK) 7-6 for function key 2-12
same file types 7-6 specifying alternative 2-13
table of defaults for combinations 7-7 page, code
valid for input and output 7-7 See code page
Override with Display File (OVRDSPF) command PAGEDOWN (Page Down) keyword
file attributes 7-1 for function key 2-12
file names 7-3 specifying alternative 2-13
file names and attributes 7-3 PAGEDOWN dialog command B-11
performance considerations 14-2 PAGEUP (Page Up) keyword
properties of 7-1 for function key 2-12
same file types 7-6 specifying alternative 2-13
when in effect 7-1 PAGEUP dialog command B-12
when to apply 7-1 paging
Override Attribute (OVRATR) keyword help displays, DDS records 18-16
system performance considerations 14-2 location information, list displays 21-25
use 3-18 panel
Override Data (OVRDTA) keyword areas A-2
description 3-20 definition 16-2, A-2
system performance considerations 14-2 group object A-2
Override with Display File (OVRDSPF) command help A-2
compared to CHGDSPF 2-2 organization A-2
file attributes 7-1 outline A-2
file names 7-3 UIM menu outline A-2
file names and attributes 7-3 PANEL (display panel) tag
Override with Printer File (OVRPRTF) example, panel definition A-127
command D-5 overview A-122

PANEL (display panel) tag (continued) panel group (continued)
tags allowed table A-122 search index (continued)
panel contents definition 17-22 creating 20-16
panel formatter limitations 17-24 deleting 20-17
panel formatting removing entries from a search index 20-17
application control 17-23 structured text in help modules, indicating 20-6
concepts 17-22 topics, defining 20-9
definition 17-22 uses for 20-1
panel group panel group (PNLGRP) tag
See also tag, UIM overview A-139
accessing index search 19-4 placement in UIM source 20-2
accessing user-defined 19-4 tags allowed table A-139
adding UIM tags for index search function 20-6 panel group definition language
command help, assigning 20-16 imbedding source files A-6
comparing with documents and records 18-2 markup/content separator A-1
creating 20-15 national language translation
definition 1-1, 16-2 sentence-ending characters A-2
deleting 20-15 overview A-2
entering UIM source for 20-1 panel group element 16-3
examples panel group object
command help 20-16 creating 16-13
help modules 20-2 definition A-3
HLPPNLGRP keyword 18-7 panel list foldup 17-26
HLPPNLGRP keyword with option panel markup tag
indicators 18-8 See also tag
imbedded help modules 20-2 definition 20-4
imported help modules 20-3 paragraph (P) tag
ISCH tag 20-9 example, paragraph tag A-121
ISCHSYN tag 20-9 overview A-121
LINK tag 20-15 placement in UIM source 20-2
heading, adding in help modules 20-4 use in help module 20-4
help modules paragraph continuation (PC) tag
emphasizing and formatting text 20-4 example, paragraph continuation A-131
highlighting text 20-4 overview A-131
hypertext 20-13 use in help module 20-4
linking 20-13 parameter
using more than once 20-2 data queue (DTAQ) 12-1
using ones contained in different panel DTAQ (data queue) 12-1
group 20-3 passed for program menus 9-10
help, specifying for 18-6 restore display (RSTDSP)
hypertext, definition 20-13 example 3-43
index search function return point (RTNPNT) parameter
function 20-6 for display file menus 9-1
root words, choosing for topic 20-10 for program menus 9-1
root words, including as synonyms 20-9 RSTDSP (restore display)
synonyms for root words, designating 20-9 example 3-43
synonyms, choosing for topic 20-10 RTNPNT (return point) parameter
topics, deciding 20-9 for display file menus 9-1
InfoSeeker, accessing 19-3 for program menus 9-1, 9-13
making lists in help modules 20-5 SHARE (share) 14-2
organizing with help modules 20-2 parameter list (PARML) tag
paragraphs and notes, defining in help example, parameter list A-130
modules 20-4 overview A-129
programming keywords and variables, tags allowed table A-129
identifying 20-5 use in help module 20-5
search index
adding entries to 20-17
Index X-41
PARML (parameter list) tag PNLGRP (panel group) tag
example, parameter list A-130 overview A-139
overview A-129 placement in UIM source 20-2
tags allowed table A-129 tags allowed table A-139
use in help module 20-5 UIM source showing panel groups with help
Passed Record (PASSRCD) keyword 11-3 modules 20-2
passing data pointer device event
between routing steps 11-3 processing priority
in the same routing step 11-1 other pointer device 6-79
PASSRCD (Passed Record) keyword shifted left button pressed 6-76
example DDS source 11-3 shifted left button released 6-76
use 11-3 shifted right button pressed 6-78
PC (paragraph continuation) tag unshifted left button double click 6-75
example, paragraph continuation A-131 unshifted left button pressed 6-73
overview A-131 unshifted left button released 6-75
use in help module 20-4 processing states 6-72
PDACCEL (pull-down accelerator) tag programmable mouse button 6-69
overview A-132 pop-up window
PDFLD (pull-down field) tag adding 17-31
overview A-133 adding over another panel 17-27
tags allowed table A-133 adding to display stack 17-31
PDFLDC (pull-down field choice) tag help information A-61
overview A-134 removing 17-31
recommended conventions A-136 pop-up window and pull-down menu
required conventions A-136 differences 17-28
PDM (programming development manager) position of window 5-4, 5-5
definition 1-2 possible choices information, entry displays 21-16
performance primary help, definition 18-16
command attention keys versus command function PRINT (Print Display) dialog command B-12
keys 14-3 PRINT (Print) keyword
DDS windows 14-4 enabling 2-25
deferring write operation 14-1 for function key 2-12
designating primary screen size 14-1 results available (table) 2-25
ERASEINP keyword, considerations with 14-3 Print Display (PRINT) dialog command B-12
invite operation 14-3 print head panel (PRTHEAD) tag
INZINP keyword, considerations with 14-3 example, print title lines A-145
overlapping but not deleting records 14-2 layout of title lines tables A-144, A-145
OVERLAY keyword, considerations with 14-3 overview A-142
override commands 14-2 tags allowed table A-142
PUTOVR, OVRDTA and OVRATR keywords, consid- print head panel printing 17-35
erations with 14-2 Print key
restoring display 14-3 enabling 2-25
RSTDSP (restore display) results available (table) 2-25
keywords that require 14-3 print panel (PRTPNL) tag
system performance considerations 14-3 overview A-146
sending records with input fields 14-2 tags allowed table A-146
sharing open data paths for same job 14-2 print panel printing 17-35
subfile use 14-1 print title lines
ways to improve using displays 14-1 example A-145
window application 5-13 print trailer message (PRTTRAIL) tag
period (.) symbol A-5 example, trailer message A-148
PK (programming keyword) tag overview A-148
overview A-138 printer characters, incorrect 17-4
use in help module 20-5 printer file sharing and overriding 17-37
placement of window 5-4, 5-5 printer files in DBCS D-5

PRINTER parameter 2-26 programming development manager (PDM)
printing definition 1-2
concepts 17-33 programming example
DBCS conversion dictionary D-19 window use 5-15
display 2-25 programming keyword (PK) tag
double-byte character set (DBCS) overview A-138
considerations 17-37 use in help module 20-5
information area A-69 Programming menu 9-2
introduction 17-33 programming variable (PV) tag
list area A-86 overview A-149
page eject 17-37 use in help module 20-5
print head panel 17-35 prolog area
print panel 17-35 defining 17-36
trailer 17-36 prolog section
priorities for displaying messages on message panel group A-4
line 8-3 prompt area
problem analysis entry displays 21-12
damaged DBCS devices D-10 list display 21-22
Problem Handling menu 9-2 PROMPT dialog command B-13
productivity gains with UIM 15-1 prompt, field
productivity improvements with UIM 15-1 See field prompts
program menu prompting
See also menu display action list option B-13
definition 9-1 command B-13
return code values, table of 9-10 entry field B-13
program-described data protecting entry field 2-19
definition 2-3 PRTHEAD (print head panel) tag
description 2-4 example, print title lines A-145
example for assigning display space 2-27 layout of title lines tables A-144, A-145
program versus system view 2-4 overview A-142
using 2-27 tags allowed table A-142
program-to-system field PRTPNL (print panel) tag
understanding how to use 2-10 overview A-146
with DSPATR keyword 2-21 tags allowed table A-146
program, CL PRTTRAIL (print trailer message) tag
See CL programs example, trailer message A-148
program, IBM-supplied overview A-148
QRCVDTAQ (receive data queue) 12-1 PSHBTNCHC (Push Button Choice) keyword 6-35
QSNDDTAQ (send data queue) 12-1 PSHBTNFLD (Push Button Field) keyword 6-35
Programmable Mouse Button (MOUBTN) keyword pull-down accelerator (PDACCEL) tag
AID codes to be returned 6-70 overview A-132
benefits 6-70 pull-down field (PDFLD) tag
event processing priority overview A-133
other pointer device 6-79 tags allowed table A-133
shifted left button pressed 6-76 pull-down field choice (PDFLDC) tag
shifted left button released 6-76 overview A-134
shifted right button pressed 6-78 recommended conventions A-136
unshifted left button double click 6-75 required conventions A-136
unshifted left button pressed 6-73 pull-down menu
unshifted left button released 6-75 CHECK(FE) keyword 6-18
event processing states 6-72 creating 6-18
NWS considerations 6-72 definition 6-7
operation 6-71 example 6-18, 6-62
overview 6-69 interaction with menu bar 6-60
pointer device event 6-69 receiving input 6-53
removing after receiving input 6-55
Index X-43
pull-down menu (continued) QIGC system value (continued)
restrict cursor 6-24 DBCS conversion dictionaries (continued)
single-choice selection field 6-18 display D-19
updating before displaying 6-55 edit, examples of D-17
pull-down menu and pop-up window editing (adding and changing terms) D-16
differences 17-28 perform object management functions with D-15
PULLDOWN dialog command B-14 printing D-19
PULLINPUT (Pull-Down Menu Input) parameter QIGC2424 (DBCS font table) D-8
example 6-54 QRCVDTAQ (receive data queue) program 12-1
push button QSNDDTAQ (send data queue) program 12-1
creating 6-35 QSYSIGCDCT (system-supplied DBCS conversion
definition 6-34 dictionary)
example, DDS 6-35 contents D-14
Push Button Choice (PSHBTNCHC) keyword 6-35 definition D-14
Push Button Field (PSHBTNFLD) keyword 6-35 queue, data
Put with Explicit Override (PUTOVR) keyword See DTAQ (data queue) parameter
for repeatedly entered data 3-21 QUSRIGCDCT (user-created dictionary) D-15
more efficient coding 3-20 QUSRSYS library 13-4
sample DDS source 3-18 QUSRTOOL library
put-relative operation for subfiles definition 1-5
BASIC statement for 4-15 display examples 21-1
definition 4-12 panel groups, using word processing functions when
ILE C function for 4-15 creating 18-2
Put-Retain (PUTRETAIN) keyword R
example radio button
field level 3-24 definition 6-1
record level 3-24 example 6-1
restriction with USRDSPMGT keyword G-10 read operation
System/36 application compatibility G-2 canceling read operation, CL command for 3-49
using 3-23 definition 3-33
PUTOVR (Put with Explicit Override) keyword definition for subfile 4-15
description 3-18 subfiles
example BASIC statement 4-15
more efficient coding 3-20 ILE C function for 4-15
repeatedly entered data 3-21 ILE COBOL statement for 4-15
sample DDS source 3-18 ILE RPG operation for 4-15
system performance considerations 14-2 with no wait
System/36 application compatibility G-6 CL command for 3-49
PUTRETAIN (Put-Retain) keyword ILE COBOL statement for 3-49
example ILE RPG operation for 3-49
field level 3-24 with wait
record level 3-24 CL command for 3-49
restriction with USRDSPMGT keyword G-10 ILE C function for 3-49
System/36 application compatibility G-2 ILE COBOL statement for 3-49
using 3-23 ILE RPG operation for 3-49
PV (programming variable) tag read-from-invited-program-devices operation
overview A-149 after inviting input 3-30
use in help module 20-5 from CL programs,
reading-from-invited-devices 3-33
Q ILE COBOL statement for 3-49
QIGC system value ILE RPG operation for 3-49
DBCS conversion dictionaries understanding 3-32
creating D-15
deleting D-19

reading record, DDS (continued)
data from window 5-10 initializing (diagram) 3-36
receiving keeping on display 3-23
data 3-4 mode to display 3-27
receiving input not occupying space on display 3-8
from pull-down menu 6-53 overlapping but not deleting to improve system per-
using PULLINPUT 6-53 formance 14-2
recommended convention paging between display 18-16
list action (LISTACT) tag A-94 placing on display 3-5
pull-down field choice (PDFLDC) tag A-136 resetting modified data tags for 3-23
record area, removing option and response indica- restrictions on 18-15
tors from 2-15 restrictions on secondary help 18-19
record format retrieving with WAIT command 3-33
changing on display 3-8 rules for displaying on more than one line 3-5
checking for changes to 2-7 secondary help, determining sequence of 18-18
contents 2-7 use by I/O statements 3-4
defining display fields and functions in 2-7 valid placement of, figure 3-6
definition 1-1 recovering from errors 8-11
description 2-7 reference field
determining active 3-5 definition 2-11
field, how to use 2-9 relational operator A-11
maximum number for display file 2-15 release operation
maximum number of fields in 2-10 definition 3-49
order written to display 3-9 ILE C function for 3-49
output and input, for 3-5 ILE COBOL statement for 3-49
overlaying and erasing on display 3-10 ILE RPG operation for 3-49
replacing 3-9 Remove Search Index Entry (RMVSCHIDXE)
replacing on display 3-8 command 20-17
starting on specific line 3-11 Remove Window (RMVWDW) keyword 5-12
viewing on display 2-8 removing
record format table, active 3-5 entry from list 17-10
record-level description pop-up window 17-30
definition 2-3 pop-windows using APIs 17-30
with field-level descriptions 2-3 pull-down menu 6-55
with no field-level descriptions 2-3 window 5-12, 17-30
record, DDS removing access
comparing with panel groups and documents 18-2 F18=More indexes 19-5
containing input fields, improving performance Rename Object (RNMOBJ) command D-15
with 14-2 request processor program when displaying
definition 2-3 panel 17-33
definition for help 1-6 required convention
displaying secondary help 18-17 list action (LISTACT) tag A-94
displaying two or more 3-10 pull-down field choice (PDFLDC) tag A-136
entering for help 18-14 resolving
erasing from display during overlay 3-10 HTML field overlap 6-83
examples resource allocation
HLPCMDKEY keyword 18-20 description 3-1
HLPCMDKEY keyword with response effect on display station error handling 3-1
indicators 18-21 understanding how system allocates 3-1
HLPRCD keyword 18-13 response indicator
HLPRCD keyword with option indicators 18-14 CAnn key, use with 2-13
secondary help 18-18 CFnn key, use with 2-12
help definition 2-12
defining for 20-19 enabling simultaneously 2-15
specifying for 18-12 function keys, use with 2-12
improving performance when sending 14-2 HLPCMDKEY keyword, use with 18-21
Index X-45
response indicator (continued) return code (continued)
removing from record area 2-15 display file (continued)
restriction with USRDSPMGT G-10 major 00 E-1
ROLLDOWN keyword, use with 2-15 major 02 E-1
ROLLUP keyword, use with 2-15 major 03 E-2
SETOF or SETOFF keyword, use with 2-15 major 04 E-2
response time major 08 and 11 E-3
for list displays 17-11 major 34 E-3
list displays 17-11 major 80 E-3
window application 5-13 major 81 E-5
restore display (RSTDSP) parameter major 82 E-6
example 3-43 major 83 E-10
keywords that require 14-3 major/minor
system performance considerations 14-3 See major/minor return code
use 3-43 Return Control to Application (RETURN) dialog
Restore Library (RSTLIB) command D-15 command B-14
Restore Object (RSTOBJ) command Return Cursor Location (RTNCSRLOC)
DBCS conversion dictionaries D-15 keyword 3-29
DBCS sort table D-12 return point (RTNPNT) parameter
restoring DBCS font tables for program menus 9-13
copying from tape or diskette (restoring) D-9 return-field (RTNFLD) parameter
copying onto diskette (saving) D-9 description 6-55
restoring DBCS sort tables example 6-56
copying from file (move from System/36) D-13 returning cursor position within subfile to applica-
copying to file (move to System/36 or tion 3-29
AS/Entry) D-12 returning mode of subfile to application 3-29
restrict cursor returning to menu after running GO command 9-1
PULLDOWN keyword 6-24 reverse text (RT) tag
WINDOW keyword 5-5 example
restrictions left-to-right formatting on a left-to-right
5250 engraved keys 17-14 panel A-150
command line 17-19 left-to-right formatting on right-to-left panel A-150
name syntax overview A-150
HELP tag A-4 Revoke Object Authority (RVKOBJAUT)
object names A-4 command D-15
on command line 17-19 right slash (/) symbol A-5
using dialog variables 17-3 right-to-left cursor movement 2-16
retain command and function keys right-to-left display processing 2-19
System/36 application compatibility G-9 RMVSCHIDXE (Remove Search Index Entry)
Retain Command Keys (RETCMDKEY) keyword command 20-17
System/36 application compatibility G-10 RMVWDW (Remove Window) keyword 5-12
Retain Function Keys (RETKEY) keyword RNMOBJ (Rename Object) command D-15
System/36 application compatibility G-10 Roll Down (ROLLDOWN) keyword
RETCMDKEY (Retain Command Keys) keyword for function keys 2-12
System/36 application compatibility G-10 Roll Up (ROLLUP) keyword
RETKEY (Retain Function Keys) keyword example with SFLSIZ and SFLPAG 4-19
System/36 application compatibility G-10 ROLLDOWN (Roll Down) keyword
RETRIEVE (Retrieve Command String) dialog function keys 2-12
command B-14 response indicators for 2-15
Retrieve Command String (RETRIEVE) dialog ROLLUP (Roll Up) keyword
command B-14 example with SFLSIZ and SFLPAG 4-19
RETURN (Return Control to Application) dialog function keys 2-12
command B-14 improving subfile performance 14-1
return code response indicators for 2-15
binary program menus 9-10 root words for index search
display file See online help information
description E-1

routing step SAVOBJ (Save Object) command (continued)
passing data between programs in same 11-1 DBCS sort table D-12
passing data between steps 11-3 SAVSYS (Save System) command
RSTDSP (restore display) parameter DBCS conversion dictionaries D-15
example 3-43 DBCS sort tables D-12
keywords that require 14-3 screen design aid (SDA)
system performance considerations 14-3 compared to direct DDS source entry 2-5
use 3-43 definition 1-5
RSTLIB (Restore Library) command D-15 screen size
RSTOBJ (Restore Object) command alternate 3-27
DBCS conversion dictionaries D-15 condition names 2-24
DBCS sort table D-12 examples
RT (reverse text) tag DDS for subfiles for two 2-25
example DDS for two 2-24
left-to-right formatting on left-to-right panel A-150 improving performance with 14-1
left-to-right formatting on right-to-left panel A-150 primary and secondary 2-25
overview A-150 valid 2-24
RTNCSRLOC (Return Cursor Location) scroll bar
keyword 3-29 creating 6-31
RTNFLD (return field) parameter definition 6-24, 6-30
description 6-55 example 6-25
example 6-56 example, DDS 6-33
rule operation 6-33
edit description use F-5 sizing 6-32
entry fields 21-15 scrollable area definition 17-14
list display scrolling
cursor positioning 21-31 area definition 17-14
error conditions 21-32 areas that can be scrolled 17-14
run-time errors, recovering from 3-52 data item groups 17-16
running defining 17-14
system and user-defined menus 9-1 error conditions 17-15
RVKOBJAUT (Revoke Object Authority) function keys 17-15
command D-15 incomplete list 17-15
information area 17-16
list area 17-15
S menu area 17-16
sample figure message line 17-15
example A-59 status information 17-14
sample heading support 17-14
example A-170 text area 17-16
SAVCHGOBJ (Save Changed Object) SDA (screen design aid)
command D-15 compared to direct DDS source entry 2-5
Save Changed Object (SAVCHGOBJ) definition 1-5
command D-15 search index
Save Library (SAVLIB) command D-15 See online help information
Save Object (SAVOBJ) command secondary help
DBCS conversion dictionaries D-15 definition 18-16
DBCS sort table D-12 determining the sequence of records 18-18
Save System (SAVSYS) command displaying records 18-17
DBCS conversion dictionaries D-15 selection
DBCS sort tables D-12 choices, Common User Access 21-53
saving list where singular item can be selected, list
DBCS sort tables D-12 displays 21-33
SAVLIB (Save Library) command D-15 selection character
SAVOBJ (Save Object) command country-designated 17-13
DBCS conversion dictionaries D-15 highlighting A-9, A-155
Index X-47
selection field SFLCSRRRN (Subfile Cursor Relative Record
example 6-10 Number) keyword 3-29
example, DDS 6-12 SFLCTL (Subfile Control) keyword 4-3
horizontal 6-14 SFLDLT (Subfile Delete) keyword 4-4
cursor movement 6-16 SFLDROP (Subfile Drop) keyword 4-4
multiple-choice SFLDSP (Subfile Display) keyword 4-3
definition 6-10 SFLDSPCTL (Subfile Display Control) keyword 4-4
vertical 6-14 SFLEND (Subfile End) keyword 4-4
pull-down menu 6-18 SFLENTER (Subfile Enter) keyword 4-4
selection indicator 6-17 SFLFOLD (Subfile Fold) keyword 4-4
single-choice SFLINZ (Subfile Initialize) keyword 4-4
auto-enter 6-38 SFLLIN (Subfile Line) keyword 4-4
auto-selection 6-37 SFLMLTCHC (Subfile Multiple-Choice Selection)
definition 6-10 keyword 6-26
vertical 6-13 SFLMODE (Subfile Mode) keyword 3-29
vertical SFLMSG (Subfile Message) keyword
creating 6-13, 6-14 description 4-4
cursor movement 6-15 displaying on message line when subfile control
selection field choice record written 8-2
colors and display attributes 6-40 messages resulting from 5-6
selection indicator SFLMSGID (Subfile Message Identifier) keyword
definition 6-17 description 4-4
suppressing displaying on message line when subfile control
in pull-down menu 6-20 record written 8-2
in selection field 6-17 example DDS source 8-5
in selection list 6-28 messages resulting from 5-6
selection list SFLMSGKEY (Subfile Message Key) keyword
creating 6-26 description 4-4
definition 6-24 displaying messages from program message
example, DDS 6-26 queue 8-4
multiple 6-26 SFLMSGRCD (Subfile Message Record) keyword
selection indicator 6-28 description 4-4
single 6-26 displaying messages from program message
selection list (UIM) 17-12 queue 8-4
self-check, System/36 application compatibility G-2 SFLNXTCHG (Subfile Next Changed) keyword
sending description 4-4
data 3-4 example DDS 4-22
sentence-ending characters A-2 SFLPAG (Subfile Page) keyword
separating with blank lines 17-36 example with ROLLUP and SFLSIZ 4-19
separator use in subfile control record format 4-3
content A-1 SFLPGMQ (Subfile Program Message Queue)
markup A-1 keyword
Set Off (SETOF or SETOFF) keywords description 4-4
response indicators for 2-15 displaying messages from program message
SETOF or SETOFF (Set Off) keyword queue 8-4
response indicators for 2-15 SFLRCDNBR (Subfile Record Number) keyword
SEU (source entry utility) description 4-4
definition 1-3 improving subfile performance 14-1
Edit display 1-3 SFLRNA (Subfile Records Not Active) keyword 4-4
SFL (Subfile) keyword 4-3 SFLROLVAL (Subfile Roll Value) keyword 4-4
SFLCHCCTL (Subfile Choice Control) keyword 6-26 SFLRTNSEL (Subfile Return Selected Choice)
SFLCLR (Subfile Clear) keyword keyword 6-27
description 4-4 SFLSCROLL (Subfile Scroll) keyword 6-28
SFLCSRPRG (Subfile Cursor Progression) SFLSIZ (Subfile Size) keyword
keyword 2-18 example with ROLLUP and SFLPAG 4-19
use in subfile control record format 4-3

SFLSNGCHC (Subfile Single-Choice Selection) sort table
keyword 6-26 copying DBCS master from data file D-13
SFLMLTCHC (Subfile Multiple-Choice copying DBCS master to data file D-12
Selection) 6-26 source
Subfile Multiple-Choice Selection example confirmation panel 16-28
(SFLMLTCHC) 6-26 example data presentation panel 16-35
SHARE (share) parameter example list panel 16-17
sharing display files in same job 3-50 example menu 16-9
system performance considerations 14-2 example menu bar panel 16-53
sharing source entry utility (SEU)
open data paths 14-2 definition 1-3
sharing and overriding with printer file 17-37 Edit display 1-3
shift-control character source file
DBCS-graphic characters D-6 definition 1-2
description of D-3 source member
inserting D-6 definition 1-2
sign on Specify Members to Work with display 1-2
choosing sign on menu 9-3 specifying
signed numeric data, System/36 application compat- enhanced display capability 6-4
ibility G-7 right-to-left display processing 2-19
simple list (SL) tag Start Character Generator Utility (STRCGU)
example, simple lists A-152 command D-10
overview A-152 Start Programming Development Manager
tags allowed table A-152 (STRPDM) command 1-1
use in help module 20-5 Start Search Index (STRSCHIDX) command 20-8
simple menu area Start Source Entry Utility (SEU) display 1-3
example A-112 Start Source Entry Utility (STRSEU) command 2-7
single selection field operation, CUA Starting Line Number (SLNO) keyword
guidelines 21-53 restrictions 3-11
single-choice menu display table of values and results 3-11
See menu display use 3-11
single-choice selection field used with other DDS keywords 3-11
colors and display attributes 6-40 with *VAR value 3-12
definition 6-10 STRCGU (Start Character Generator Utility)
horizontal 6-14 command D-10
in a pull-down menu 6-18 stream, user-defined data
vertical 6-13 See user-defined data stream (UDDS)
single-choice selection list STRPDM (Start Programming Development
creating 6-26 Manager) command 1-1
definition 6-24 STRSCHIDX (Start Search Index) command 20-8
example 6-25 STRSEU (Start Source Entry Utility) command 2-7
size subfile
window 5-4 See also display file
SL (simple list) tag active record in, updating 4-13
example, simple lists A-152 adding record at a specified location in 4-12
overview A-152 checking validity of data 4-22
tags allowed table A-152 controlling appearance of 4-16
use in help module 20-5 cursor, positioning
slash (/) symbol A-5 initially 4-24
SLNO (Starting Line Number) keyword when Fold or Truncate key used 4-27
examples when more than one record displayed 4-27
restrictions 3-11 when Roll key used 4-24
table of values and results 3-11 definition 2-9
use 3-11 describing in DDS source 4-3
used with other DDS keywords 3-11 displaying
with *VAR value 3-12 and processing records at the same time 4-15
error messages from 4-23
Index X-49
subfile (continued) subfile (continued)
displaying (continued) SFLDSP keyword, use of 4-3
horizontally 4-16 SFLPAG keyword, use of 4-3
horizontally with display modes 4-17 SFLSCROLL keyword, use of 6-28
records 4-15 SFLSIZ keyword, use of 4-3
vertically 4-16 size equal to page size 4-19
example size not equal to page size 4-21
*DS3 mode display 4-19 subfile control record format, purpose 4-3
*DS4 mode display 4-18 subfile control, processing order of DDS keywords
DDS for two display sizes 2-25 for 4-9
DSPATR(PC) keyword, use of 4-24 subfile record format, purpose 4-3
DSPMOD keyword, use of 4-17 table of I/O requests in high-level languages
message subfile 4-23 BASIC statements 4-15
program logic for subfiles 4-31 ILE C functions 4-15
ROLLUP, SFLSIZ, and SFLPAG keywords 4-19 ILE COBOL statements 4-15
sample display for changing information 4-2 ILE RPG operations 4-15
sample display for display only 4-1 USRDSPMGT keyword restriction G-10
sample display for input only 4-2 validity checking before rolling 4-9
sample display for task combination 4-2 window 5-6
sample display with selection 4-1 Subfile Choice Control (SFLCHCCTL) keyword 6-26
sample displays when rolling two or more Subfile Clear (SFLCLR) keyword
records 4-28 description 4-4
SFLNXTCHG keyword, use of 4-22 Subfile Control (SFLCTL) keyword 4-3
SFLPAG, SFLSIZ, and ROLLUP keywords 4-19 subfile control record format
SFLSIZ, ROLLUP, and SFLPAG keywords 4-19 definition 4-3
variable-length record 4-20 placement after subfile record format 4-4
vertical and horizontal, displayed at same read operation 4-15
time 4-16 requesting I/O operations for 4-15
extending full 4-9 required DDS keywords 4-3
functions for 4-4 SFLCTL keyword, use of 4-3
high-level language programs, use in 4-10 SFLDSP keyword, use of 4-3
maximum number active to display station 4-9 SFLPAG keyword, use of 4-3
maximum number allowed in display file 4-9 SFLSIZ keyword, use of 4-3
multiple records 4-1 write operation 4-15
optional functions, table of 4-4 write-read operation 4-15
order of subfile record format and subfile control Subfile Cursor Progression (SFLCSRPRG)
record format 4-4 keyword 2-18
performance considerations 14-1 Subfile Cursor Relative Record Number
placing records on display for processing 4-15 (SFLSCRRRN) keyword 3-29
positioning cursor for each page of records 4-24 Subfile Delete (SFLDLT) keyword 4-4
program logic for 4-31 Subfile Display (SFLDSP) keyword 4-3
reading active record at specified location in 4-13 Subfile Display Control (SFLDSPCTL) keyword 4-4
reading next changed record in 4-14 Subfile Drop (SFLDROP) keyword 4-4
recognizing uses of Subfile End (SFLEND) keyword 4-4
changing information 4-2 Subfile Enter (SFLENTER) keyword 4-4
combination of tasks 4-2 Subfile Fold (SFLFOLD) keyword 4-4
display only 4-1 Subfile Initialize (SFLINZ) keyword 4-4
input only without validity checking 4-2 Subfile Line (SFLLIN) keyword 4-4
sample display with selection 4-1 Subfile Message (SFLMSG) keyword
records description 4-4
active subfile 4-4 displaying on message line when subfile control
inactive subfile 4-4 record written 8-2
requesting I/O operations for 4-12 messages resulting from 5-6
rolling and validity checking 4-9 Subfile Message Identifier (SFLMSGID) keyword
SFL keyword, use of 4-3 defining in display 8-4
SFLCTL keyword, use of 4-3 description 4-4

Subfile Message Identifier (SFLMSGID) keyword symbol (continued)
(continued) message text
displaying on message line when subfile control message file default A-5
record written 8-2 period (.) A-5
messages resulting from 5-6 right slash (/) A-5
Subfile Message Key (SFLMSGKEY) keyword symmetric character
description 4-4 Arabic A-23
displaying messages from program message Hebrew A-23
queue 8-4 synonym, index search
Subfile Message Record (SFLMSGRCD) keyword See online help information
description 4-4 System Command (CMD) dialog command B-7
displaying messages from program message system menu 9-1
queue 8-4 system message
Subfile Mode (SFLMODE) keyword 3-29 See message
Subfile Multiple-Choice Selection (SFLMLTCHC) system performance
keyword 6-26 See performance
Subfile Next Changed (SFLNXTCHG) keyword system value
description 4-4 QIGC for DBCS conversion dictionaries
example DDS 4-22 creating D-15
Subfile Page (SFLPAG) keyword deleting D-19
example with ROLLUP and SFLSIZ 4-19 display D-19
use in subfile control record format 4-3 edit, examples of D-17
Subfile Program Message Queue (SFLPGMQ) editing (adding and changing terms) D-16
keyword perform object management functions with D-15
description 4-4 printing D-19
displaying messages from program message System/36 application compatibility
queue 8-4 ASSUME (Assume) keyword G-2
subfile record format cancel-invite operation G-8
definition 4-3 display files G-1
get-next-changed operation 4-14 ERASE (Erase) keyword G-2
get-relative operation 4-13 function keys G-7
placement before subfile control record format 4-4 HELP (Help) keyword G-7
put-relative operation 4-12 Help Return (HLPRTN) keyword G-7
requesting I/O operations for 4-12 high-level languages G-1
SFL keyword, use of 4-3 HLPRTN (Help Return) keyword G-7
update operation 4-13 input data G-2
Subfile Record Number (SFLRCDNBR) keyword KEEP (Keep) keyword G-2
description 4-4 messages G-4
Subfile Records not Active (SFLRNA) keyword 4-4 OVERLAY keyword G-2
Subfile Return Selected Choice (SFLRTNSEL) PUTOVR (Put with Explicit Override) keyword G-6
keyword 6-27 PUTRETAIN (Put-Retain) keyword G-2
Subfile Roll Value (SFLROLVAL) keyword 4-4
Subfile Scroll (SFLSCROLL) keyword 6-28
Subfile Single-Choice Selection (SFLSNGCHC) T
keyword 6-26 tab key
Subfile Size (SFLSIZ) keyword movement 6-61
example with ROLLUP and SFLPAG 4-19 tag
use in subfile control record format 4-3 definition A-1
suppressed selection indicator in pull-down menu MENUGRP (menu group) A-114
example 6-21 tag language
suppressed selection indicator in selection field See panel group definition language
example 6-18 tag within help module
symbol CIT (title citation)
ampersand (&) A-5 use in help module 20-4
colon (:) A-5 definition list (DL)
concatenation A-5 use in help module 20-5
Index X-51
tag within help module (continued) tag within help module (continued)
DL (definition list) note (NT)
use in help module 20-5 use in help module 20-4
example (XMP) NT (note)
use in help module 20-6 OL (ordered list)
extended help headings (XH1-XH4) use in help module 20-5
use in help module 20-4 ordered list (OL)
FIG (figure) use in help module 20-5
use in help module 20-6 P (paragraph)
figure (FIG) placement in UIM source 20-2
H1 through H4 (headings) panel group (PNLGRP)
use in help module 20-4 placement in UIM source 20-2
heading (H1 through H4) panel markup
use in help module 20-4 definition 20-4
HELP (help module) paragraph (P)
panel groups with help modules 20-2 use in help module 20-4
placement in UIM source 20-2 paragraph continuation (PC)
help module (HELP) use in help module 20-4
panel groups with help modules 20-2 parameter list (PARML)
placement in UIM source 20-2 use in help module 20-5
highlighted phrase (HP0-HP9) PARML (parameter list)
HP0-HP9 (highlighted phrase) PC (paragraph continuation)
hypertext link (LINK) PK (programming keyword)
imbed help (IMHELP) PNLGRP (panel group)
placement in panel group source 20-2 panel groups with help modules 20-2
IMHELP (imbed help) placement in UIM source 20-2
panel groups using 20-2 programming keyword (PK)
placement in panel group source 20-2 use in help module 20-5
IMPORT (import) programming variable (PV)
panel groups using 20-3 use in help module 20-5
placement in UIM source 20-3 purpose 20-1
index search (ISCH) PV (programming variable)
index search synonym (ISCHSYN) simple list (SL)
ISCH (index search) SL (simple list)
placement in UIM source 20-9 title citation (CIT)
ISCHSYN (index search synonym) use in help module 20-4
panel groups using 20-9 UL (unordered list)
LINES (unformatted lines) unformatted lines (LINES)
LINK (hypertext link) unordered list (UL)
placement in UIM source 20-15 XH1 through XH4 (extended help heading)
list part (LP) use in help module 20-4
use in help module 20-5 XMP (example)
LP (list part) use in help module 20-6
use in help module 20-5 tag, modified data 2-10
NOTE (note) tag, UIM
use in help module 20-4 APPFMT (application formatted area) A-8

tag, UIM (continued) tag, UIM (continued)
BOTINST (bottom instruction) A-10 PRTTRAIL (print trailer message) A-148
CHECK (validity checking) A-11 PV (programming variable) A-149
CIT (title citation) A-13 RT (reverse text) A-150
CLASS (class definition) A-14 SL (simple list) A-152
CMDLINE (command line) A-26 TEXT (text area) A-154
COND (condition definition) A-27 TI (translation list item) A-158
COPYR (copyright) A-30 TL (translation list) A-159
DATA (data presentation area) A-31 TOPINST (top instruction) A-161
DATAC (data item choices) A-38 TT (truth table) A-162
DATACOL (data column) A-39 TTROW (truth table row) A-163
DATAGRP (data group) A-40 UL (unordered list) A-164
DATAI (data item) A-42 VAR (variable definition) A-166
DATAIX (data item extender) A-47 VARRCD (variable record definition) A-169
DATASLT (data selection field) A-51 XH1 through XH4 (extended help headings) A-170
DATASLTC (data selection field choice) A-55 XMP (example) A-171
DL (definition list) A-57 tape device file
FIG (figure) A-59 DBCS D-5
H1 through H4 (heading) A-65 text (TEXT area) tag
HELP (help module) A-60 overview A-154
HP0 through HP9 (highlighted phrase) A-63 text area
IMHELP (imbed help) A-66 scrolling 17-16
IMPORT (import) A-67 text area (TEXT) tag
INFO (information area) A-68 example
ISCH (index search) A-70 a text area A-157
ISCHSUBT (index search subtopic) A-71 text data A-155
ISCHSYN (index search synonym) A-72 text area scrolling 17-16
KEYI (key list item) A-74 text area, descriptive
KEYL (key list) A-76 entry displays 21-16
LINES (unformatted lines) A-77 text data
LINK (hypertext link definition) A-78 selection characters A-155
LIST (list area) A-82 TI (translation list item) tag
LISTACT (list action) A-90 overview A-158
LISTCOL (list column) A-96 time value
LISTDEF (list definition) A-100 display form A-25
LISTGRP (list column group) A-103 timing function on WAITRCD parameter 3-33
LISTVIEW (list view) A-105 tips
LP (list part) A-107 Word Wrap (WRDWRAP) keyword 2-21
MBAR (menu bar) A-108 title
MBARC (menu bar choice) A-110 entry displays 21-11
MENU (menu area) A-111 information displays 21-19
MENUI or MI (menu item) A-115 list display 21-22
NT or NOTE (note) A-117 single-choice menu displays 21-9
OL (ordered list) A-118 window 5-9
OPTLINE (option line) A-120 title citation (CIT) tag
P (paragraph) A-121 example
PANEL (display panel) A-122 title citations A-13
PARML (parameter list) A-129 overview A-13
PC (paragraph continuation) A-131 use in help module 20-4
PDACCEL (pull-down accelerator) A-132 title lines
PDFLD (pull-down field) A-133 table A-144
PDFLDC (pull-down field choice) A-134 TL (translation list) tag
PK (programming keyword) A-138 list, translation A-159
PNLGRP (panel group) A-139 overview A-159
PRTHEAD (print head panel) A-142 tags allowed table A-159
PRTPNL (print panel) A-146
Index X-53
tool, command line 21-37 UDDS (user-defined data streams) (continued)
top instruction (TOPINST) tag output record area for record format 10-2
overview A-161 system operations to request commands 10-4
topics, index search understanding limitations 10-2
See online help information using 10-1
TOPINST (top instruction) tag USRDFN (User-Defined) keyword 10-1
overview A-161 valid keywords with USRDFN keyword 10-2
trailer message write-read function 10-4
example A-148 write-read operations
trailer printing 17-36 CL (control language) 10-4
translation ILE COBOL 10-4
character set and code page, UIM A-19 ILE RPG 10-4
translation list (TL) tag UIM
list, translation A-159 commonly asked questions 17-37
overview A-159 UIM (user interface manager)
tags allowed table A-159 See also panel group
translation list item (TI) tag 5250 engraved key restrictions 17-14
overview A-158 action list definition 17-11
translation table 13-4 action variable definition 17-11, 17-13
truth table (TT) tag adding pop-up window over another panel 17-27
example, truth table A-162 adding window over another panel 17-27
overview A-162 after scrolling example 16-33
tags allowed table A-162 alternate view of list example 16-15
truth table row (TTROW) tag API services 16-5
overview A-163 application handle definition 17-1
TT (truth table) tag application programming
example, truth table A-162 confirmation processing 16-31
overview A-162 data presentation panel 16-46
tags allowed table A-162 list panel 16-25
TTROW (truth table row) tag menu bar panel 16-63
overview A-163 application window, defining 17-30
two presentation areas for data items automatic confirmation processing 16-31
example A-35 command line
two-column format in a data entry panel entered too long 17-20
example A-34 interpretation 17-19
type pop-up window 17-32
display station 5-3, 6-1 restrictions 17-19
window 17-32
window example 17-32
U confirmation list panel, creating 16-27
UDDS (user-defined data streams) confirmation panel source 16-28
3270 Model 4 display station support 10-3 confirmation processing
available functions 10-2 application programming 16-31
buffer format for 5250 display station 10-3 automatically 16-31
command attention keys, effects on 10-3 considerations before using 15-1
command function keys, effects on 10-3 contextual help, defining 17-16
defining output buffer 10-3 controlling list entries on list display 17-10
defining output data stream 10-3 conversion of character set and code page A-19
display station differences, understanding 10-1 creating
handling of field-level requests after user-defined confirmation list panel 16-27
requests 10-2 data presentation panel 16-32
help information for 10-2 list panel 16-13
I/O requests, effect on 10-2 menu bar panel 16-50
input operations 10-4 menu panel 16-6
limitations 10-2 object 16-3
opening display files containing 10-3 cursor position when help text displayed 17-17

UIM (user interface manager) (continued) UIM (user interface manager) (continued)
data entry panel 16-49 help (continued)
data presentation panel index search 19-4
application programming 16-46 index search hierarchy 20-11
creating 16-32 InfoSeeker 19-3
example 16-32 user-defined panel group 19-4
source 16-35 help text displayed according to cursor
DBCS and national language considerations 20-12 position 17-17
DDS instead of 15-1 help window 5-9
defining incorrect characters in dialog variable 17-4
application window 17-30 incorrect display characters 17-4
contextual help 17-16 incorrect printer characters 17-4
dialog variable 17-1 increasing user productivity 15-1
function keys 17-20 index search
function keys and VARUPD value 17-21 giving help panels access 19-4
menu object 16-6 InfoSeeker 19-3
panel group object 16-13 initial value of dialog variable 17-2
definition 1-1 initializing list 17-8
details 17-1 inserting entry from list 17-10
dialog variable interactive response time for list displays 17-11
definition 17-1 introduction 16-1
error messages 17-3 limitations of panel formatter 17-24
incorrect characters 17-4 list
initial value 17-2 displaying 17-8
restrictions 17-3 incomplete processing 17-9
differences between pull-down menus and pop-up initialing 17-8
windows 17-28 inserting entry from 17-10
display characters, incorrect 17-4 managing 17-7
display panel field value using dialog variables 17-4 removing entry from 17-10
displaying list 17-8 updating 17-9
displaying panel using request processor list display
program 17-33 controlling list entries 17-10
elements within panel group 16-3 list entry
entry pointer for list 17-10 handle 17-9
error messages for dialog variables 17-3 on list display 17-10
example pointer 17-10
alternate view of list 16-15 list panel
list panel 16-14 application programming 16-25
menu bar panel 16-50 creating 16-13
menu source 16-9 example 16-14
exit flag 17-24 fold up 17-26
field value for display panel using dialog source 16-17
variables 17-4 managing panel functions 17-13
folding up list panel 17-26 menu area, scrolling 17-16
folding up multiple panels when EXIT menu bar panel
requested 17-24 application programming 16-63
folding when EXIT requested 17-24 creating 16-50
formatting function keys 17-20 example 16-50
function key source 16-53
defining 17-20 menu bars 17-27
formatting 17-20 menu definition 16-2
scrolling 17-15 menu object 16-6
VARUPD value 17-21 menu panel
functions supported 16-2 creating 16-6
graphical user interface (GUI) 17-14 example 16-6
help message line, scrolling 17-15
hierarchy, index search 20-11
Index X-55
UIM (user interface manager) (continued) UIM (user interface manager) (continued)
national language considerations and DBCS 20-12 removing entry from list 17-10
opening application 17-1 request processor program when displaying
panel elements supported 16-2 panel 17-33
panel formatter limitations 17-24 response time for list displays 17-11
panel formatting restrictions
application control 17-23 5250 engraved keys 17-14
concepts 17-22 using dialog variables 17-3
definition 17-22 routing step 17-13
when to perform 17-22 scrolling
panel function managing 17-13 area definition 17-14
panel group areas that can be scrolled 17-14
definition 16-2 data item groups 17-16
elements 16-3 defining scrollable areas 17-14
panel group object, defining 16-13 error conditions 17-15
panel list fold up 17-26 function key 17-15
pop-up window incomplete list 17-15
adding 17-30, 17-31 information area 17-16
adding and removing using APIs 17-30 list area 17-15
adding over another panel 17-27 menu area 17-16
adding to display stack 17-30, 17-31 message line 17-15
API for adding and removing 17-30 status information 17-14
command line 17-32 text area 17-16
defining application 17-30 selection characters 17-13
example in command line 17-32 selection list definition 17-12
removing 17-31 source
removing using APIs 17-30 example confirmation panel 16-28
using 17-30 example data presentation panel 16-35
pop-up window and pull-down menu example list panel 16-17
differences 17-28 example menu 16-9
printer characters, incorrect 17-4 example menu bar panel 16-53
printing 17-33 updating list 17-9
blank lines for separating 17-36 user-defined panel group
character set and code page 17-5 giving help panels access 19-4
code page and character set 17-5 using DDS instead of 15-1
concepts 17-33 variable pool services 17-4
DBCS (double-byte character set) 17-37 VARUPD value and function keys 17-21
double-byte character set (DBCS) 17-37 when to use to gain productivity 15-1
fonts and highlighting 17-36 window
header area 17-36 adding 17-30, 17-31
highlighting 17-36 adding and removing using APIs 17-30
highlighting and fonts 17-36 adding over another panel 17-27
introduction 17-33 adding to display stack 17-30, 17-31
overriding with and sharing printer file 17-37 API for adding and removing 17-30
page eject 17-37 command line 17-32
print head panel 17-35 defining application 17-30
print panel 17-35 example in command line 17-32
printer file, sharing and overriding with 17-37 removing 17-31
prolog area 17-36 removing using APIs 17-30
separating with blank lines 17-36 using 17-30
sharing and overriding with printer file 17-37 UIM-defined variable attributes A-167
trailer 17-36 UL (unordered list) tag
productivity example, unordered list A-165
improvements 15-1 overview A-164
increasing application programmer 15-1 tags allowed table A-164
pull-down menu and pop-up window use in help module 20-5
differences 17-28

unavailable choice user interface manager (UIM) (continued)
example 6-37 confirmation panel source 16-28
unformatted lines (LINES) tag confirmation processing
example, unformatted lines A-77 application programming 16-31
overview A-77 automatically 16-31
use in help module 20-6 considerations before using 15-1
UNLOCK (Unlock Keyboard) keyword contextual help, defining 17-16
effects on input operation 3-36 controlling list entries on list display 17-10
example with INZRCD keyword 3-36 conversion of character set and code page A-19
unlocking keyboard while the program is processing creating
data 3-35 confirmation list panel 16-27
unordered list (UL) tag data presentation panel 16-32
example, unordered list A-165 list panel 16-13
overview A-164 menu bar panel 16-50
tags allowed table A-164 menu panel 16-6
use in help module 20-5 object 16-3
update operation for subfiles cursor position when help text displayed 17-17
BASIC statement for 4-15 data entry panel 16-49
definition 4-13 data presentation panel
ILE C function for 4-15 after scrolling example 16-33
ILE COBOL statement for 4-15 creating 16-32
ILE RPG operation for 4-15 example 16-32
updating source 16-35
list in UIM 17-9 DBCS and national language considerations 20-12
updating pull-down menu 6-55 DDS instead of 15-1
User Defined (USRDFN) keyword defining
See user-defined data stream (UDDS) application window 17-30
User Display Management (USRDSPMGT) keyword contextual help 17-16
DDS keywords that cannot be used with G-2 dialog variable 17-1
use G-1 function keys 17-20
user interface manager (UIM) function keys and VARUPD value 17-21
See also panel group menu object 16-6
5250 engraved key restrictions 17-14 panel group object 16-13
action list definition 17-11 defining menu object 16-6
action variable definition 17-11, 17-13 defining panel group object 16-13
adding pop-up window over another panel 17-27 definition 1-1
adding window over another panel 17-27 details 17-1
alternate view of list example 16-15 dialog variable
API services 16-5 definition 17-1
application handle definition 17-1 error messages 17-3
application programming incorrect characters 17-4
confirmation processing 16-31 initial value 17-2
data presentation panel 16-46 restrictions 17-3
list panel 16-25 differences between pull-down menus and pop-up
menu bar panel 16-63 windows 17-28
application window, defining 17-30 display characters, incorrect 17-4
automatic confirmation processing 16-31 display panel field value using dialog variables 17-4
command line displaying list 17-8
entered too long 17-20 displaying panel using request processor
interpretation 17-19 program 17-33
pop-up window 17-32 elements within panel group 16-3
restrictions 17-19 enabling graphical user interface (GUI) 17-14
window 17-32 entry pointer for list 17-10
window example 17-32 error messages for dialog variables 17-3
commonly asked questions 17-37 example
confirmation list panel, creating 16-27 alternate view of list 16-15
list panel 16-14
Index X-57
user interface manager (UIM) (continued) user interface manager (UIM) (continued)
example (continued) list panel (continued)
menu bar panel 16-49 creating 16-13
menu source 16-9 example 16-14
exit flag 17-24 fold up 17-26
field value for display panel using dialog source 16-17
variables 17-4 managing panel functions 17-13
folding up list panel 17-26 menu area, scrolling 17-16
folding up multiple panels when EXIT menu bar 17-27
requested 17-24 menu bar panel 16-50
folding when EXIT requested 17-24 application programming 16-63
formatting function keys 17-20 creating 16-50
function key example 16-49
defining 17-20 source 16-53
formatting 17-20 menu definition 16-2
scrolling 17-15 menu object, defining 16-6
VARUPD value 17-21 menu panel
functions supported 16-2 creating 16-6
graphical user interface (GUI) 17-14 example 16-6
help message line, scrolling 17-15
hierarchy, index search 20-11 national language considerations and DBCS 20-12
index search 19-4 opening application 17-1
index search hierarchy 20-11 panel elements supported 16-2
user-defined panel group 19-4 panel formatter limitations 17-24
help text displayed according to cursor panel formatting
position 17-17 application control 17-23
help window 5-9 concepts 17-22
incorrect characters in dialog variable 17-4 definition 17-22
incorrect display characters 17-4 when to perform 17-22
incorrect printer characters 17-4 panel function managing 17-13
increasing user productivity 15-1 panel group
index search definition 16-2
giving help panels access 19-4 elements 16-3
InfoSeeker 19-3 panel group object, defining 16-13
initial value of dialog variable 17-2 panel list fold up 17-26
initializing list 17-8 pop-up window
inserting entry from list 17-10 adding 17-30, 17-31
interactive response time for list displays 17-11 adding and removing using APIs 17-30
introduction 16-1 adding over another panel 17-27
limitations of panel formatter 17-24 adding to display stack 17-30, 17-31
list API for adding and removing 17-30
defining 17-8 command line 17-32
displaying 17-8 defining application 17-30
incomplete processing 17-9 example in command line 17-32
initialing 17-8 removing 17-31
inserting entry from 17-10 removing using APIs 17-30
managing 17-7, 17-8 using 17-30
removing entry from 17-10 pop-up window and pull-down menu
updating 17-9 differences 17-28
list display printer characters, incorrect 17-4
controlling list entries 17-10 printing 17-33
list entry blank lines for separating 17-36
handle 17-9 character set and code page 17-5
on list display 17-10 code page and character set 17-5
pointer 17-10 concepts 17-33
list panel DBCS (double-byte character set) 17-37
application programming 16-25 double-byte character set (DBCS) 17-37

user interface manager (UIM) (continued) user interface manager (UIM) (continued)
printing (continued) when to use to gain productivity 15-1
fonts and highlighting 17-36 window
header area 17-36 adding 17-30, 17-31
highlighting and fonts 17-36 adding and removing using APIs 17-30
introduction 17-33 adding over another panel 17-27
overriding with and sharing printer files 17-37 adding to display stack 17-30, 17-31
page eject 17-37 API for adding and removing 17-30
print head panel 17-35 command line 17-32
print panel 17-35 defining application 17-30
printer file, sharing and overriding with 17-37 example in command line 17-32
prolog area 17-36 removing 17-31
separating with blank lines 17-36 removing using APIs 17-30
sharing and overriding with printer files 17-37 using 17-30
trailer 17-36 User Restore Display (USRRSTDSP) keyword 5-13
productivity user-created dictionary (QUSRIGCDCT) D-15
improvements 15-1 user-defined data streams (UDDS)
increasing application programmer 15-1 3270 Model 4 display station support 10-3
pull-down menu and pop-up window available functions 10-2
differences 17-28 buffer format for 5250 display station 10-3
removing entry from list 17-10 command attention keys, effects on 10-3
request processor program when displaying command function keys, effects on 10-3
panel 17-33 defining output buffer 10-3
response time for list displays 17-11 defining output data stream 10-3
restrictions display station differences, understanding 10-1
5250 engraved keys 17-14 handling of field-level requests after user-defined
using dialog variables 17-3 requests 10-2
routing step 17-13 help information for 10-2
scrolling I/O requests, effect on 10-2
area definition 17-14 input operations 10-4
areas that can be scrolled 17-14 limitations 10-2
data item group 17-16 opening display files containing 10-3
defining scrollable areas 17-14 output record area for record format 10-2
error conditions 17-15 system operations to request commands 10-4
function key 17-15 understanding limitations 10-2
incomplete list 17-15 using 10-1
information area 17-16 USRDFN (User-Defined) keyword 10-1
list area 17-15 valid keywords with USRDFN keyword 10-2
menu area 17-16 write-read function 10-4
message line 17-15 write-read operations
status information 17-14 CL (control language) 10-4
text area 17-16 ILE COBOL 10-4
selection characters 17-13 ILE RPG 10-4
selection list definition 17-12 user-defined edit code
source about 2-23
example confirmation panel 16-28 edit descriptions F-4
example data presentation panel 16-35 user-defined menus
example list panel 16-17 See menu display
example menu bar panel 16-53 user-defined panel group
source for example menu 16-9 See online help information
updating list 17-9 using note
user-defined panel group example A-117
giving help panels access 19-4 USRDFN (User-Defined) keyword
using DDS instead of 15-1 See user-defined data stream (UDDS)
variable pool services 17-4 USRDSPMGT (User Display Management) keyword
VARUPD value and function keys 17-21 restricted DDS keywords G-2, G-10
Index X-59
USRDSPMGT (User Display Management) keyword vertical (continued)
(continued) single-choice selection field 6-13
restrictions for response indicators G-10 VRYCFG (Vary Configuration) command D-10
restrictions for subfiles G-10
use G-1
USRRSTDSP (User Restore Display) keyword 5-13 W
WAIT (wait) command 3-33
WAIT(*NO) parameter 3-30
V WAITFILE (wait file) parameter
valid DDS for mnemonic for acquire operation 3-3
example 6-38 for open operation 3-2
validity checking for system allocation of resources 3-1
functions, specifying 3-37 WAITRCD (wait record) parameter
keywords 3-37 timing function for 3-33
performing 17-2 WDWBORDER (Window Border) keyword 5-7
restrictions when using CAnn keys 2-13 WDWTITLE (Window Title) keyword 5-9
subfile data 4-22 window
validity checking (CHECK) tag adding over another panel 17-27
example, validity checking A-12 border 5-7
overview A-11 changing 5-10
validity-checking keyword 5-6 creating 5-3
value cursor position 5-5
BASETYPE A-14 defining 17-30
character A-25 definition 2-27
date A-25 duplicating 5-11
numeric A-24 grid line structure 6-81
time A-25 help displayed in 5-7, 5-9
VAR (variable definition) tag location 5-4, 5-5
overview A-166 making one pop out of series 5-12
variable definition (VAR) tag making two active 5-11
overview A-166 maximum displayed 5-3
variable pool message in 5-6
definition 17-2 moving 5-11
services 17-4 performance 5-13
variable record definition (VARRCD) tag programming example 5-15
overview A-169 reading data from 5-10
variable update (VARUPD) attribute removing 5-12
dialog command B-4 size 5-4
function keys 17-21 subfile used in 5-6
KEYI tag A-75 system performance considerations 14-4
PDFLDC tag A-135 title 5-9
variable value 17-4 WINDOW (Window) keyword 5-3
variable-length record 4-20 Window Border (WDWBORDER) keyword 5-7
VARRCD (variable record definition) tag window definition record 5-3
overview A-169 window reference record 5-3
VARUPD (variable update) attribute window title
dialog command B-4 example, DDS 5-9
function keys 17-21 Window Title (WDWTITLE) keyword 5-9
KEYI tag A-75 Word Wrap (WRDWRAP) keyword 2-20, 6-43
PDFLDC tag A-135 words, index search root
VARUPD value and function keys 17-21 See online help information
Vary Configuration (VRYCFG) command D-10 Work with DBCS Conversion Dictionary
vertical display D-16
multiple-choice selection field Work with Members Using PDM display 1-3
cursor movement 6-15 wrap
example 6-14 word 2-20, 6-43

WRDWRAP (Word Wrap) keyword 2-20, 6-43
write operation
CL command for 3-49
deferring until a read request is made 3-26
definition 3-5
subfiles
BASIC statement for 4-15
definition 4-15
write-read operation
with no wait, CL command for 3-49
with wait
CL command for 3-49
write-read operation for subfiles
definition 4-15
X
XH1 through XH4 (extended help headings) tag
example, sample heading A-170
formatting rules A-170
overview A-170
use in help module 20-4
XMP (example) tag
example, formatting an example A-171
help module 20-6
overview A-171
Z
Z-variable
attributes A-167
definition A-167
Z36ENV dialog variable A-167
ZCANCEL dialog variable A-167
ZDBCS dialog variable A-167
ZDSPSIZ dialog variable A-167
ZEXIT dialog variable A-167
ZJOB dialog variable A-167
ZJOBNBR dialog variable A-167
ZLMTCPB dialog variable A-167
ZMENU dialog variable A-167
ZMNULIB dialog variable A-167
ZSYSNAM dialog variable A-167
ZUSER dialog variable A-167
Index X-61
Reader Comments—We'd Like to Hear from You!
AS/400 Advanced Series
Version 4
Publication No. SC41-5715-00
Overall, how would you rate this manual?
Very
Very Dissatis-
Satisfied Dissatis-
Satisfied fied
fied
Overall satisfaction
How satisfied are you that the information in this manual is:
Accurate
Complete
Easy to find
Easy to understand
Well organized
Applicable to your tasks
THANK YOU!
Please tell us how we can improve this manual:
May we contact you to discuss your responses? __ Yes __ No

Phone: (____) ___________ Fax: (____) ___________ Internet: ___________
To return this form:

Mail it
Fax it
United States and Canada: 800+937-3430
Other countries: (+1)+507+253-5192
Hand it to your IBM representative.
Note that IBM may use or distribute the responses to this form without obligation.
Name Address
Company or Organization
Phone No.
Cut or Fold
Reader Comments—We'd Like to Hear from You!
IBM
Along Line
SC41-5715-00

Fold and Tape Please do not staple Fold and Tape
NO POSTAGE
NECESSARY
IF MAILED IN THE
UNITED STATES
BUSINESS REPLY MAIL

FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK
POSTAGE WILL BE PAID BY ADDRESSEE
ATTN DEPT 542 IDCLERK

IBM CORPORATION
3605 HWY 52 N
ROCHESTER MN 55901-9986
Fold and Tape Please do not staple Fold and Tape
Cut or Fold
SC41-5715-00 Along Line
IBM 
Printed in the United States of America

on recycled paper containing 10%
recovered post-consumer fiber.
SC41-5715-ðð
Spine information:
IBM AS/400 Advanced Series Application Display Programming Version 4

DSMKPO660W POSTSCRIPT FILE'S LINE LENGTH VIOLATES ADOBE STRUCTURING CONVE
NTIONS.
DSMMOM395I '.EDFPO' LINE 70: .po @E@P@S
DSMMOM397I '.EDFPO' WAS IMBEDDED AT LINE 70 OF '.EDFPO'
DSMMOM397I '.EDFPO' WAS IMBEDDED AT LINE 910 OF '.EDFAWRK'
DSMMOM397I '.EDFAWRK' WAS IMBEDDED AT LINE 2733 OF 'RBAHGAPD'
DSMMOM397I 'RBAHGAPD' WAS IMBEDDED AT LINE 87 OF 'RBAHGMST'
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
DSMBEG323I STARTING PASS 2 OF 4.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.
NTIONS.

Display Rpgle

Uploaded by

Copyright:

Available Formats

Display Rpgle

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Display Rpgle

Uploaded by

Copyright:

Available Formats

AS/400 Advanced Series IBM

Application Display Programming

First Edition (August 1997)

or you can fax your comments to:

United States and Canada: 800+937-3430

 Copyright International Business Machines Corporation 1997. All rights reserved.

About Application Display Programming (SC41-5715) . . . . . . . . . . . xxxi

Summary of Changes to Application Display Programming . . . . . . . . xxxiii

Part 1. Building a Sample Display with Online Help Information

Chapter 1. Building a Sample Display with Online Help Information . . . 1-1

Part 2. Programming Application Displays Using Display Files

Chapter 2. Defining Your Display in a Display File . . . . . . . . . . . . . . 2-1

 Copyright IBM Corp. 1997 iii

Chapter 3. Working with Display Files in an Application . . . . . . . . . . 3-1

Chapter 4. Displaying Groups of Records Using Subfiles . . . . . . . . . . 4-1

Chapter 5. Defining Windows with Display Files . . . . . . . . . . . . . . . 5-1

iv Application Display Programming V4R1

Chapter 6. Creating a Graphical Look for Displays . . . . . . . . . . . . . . 6-1

vi Application Display Programming V4R1

Chapter 7. Overriding Display Files and Display File Attributes . . . . . . 7-1

Chapter 8. Handling Messages and Errors for Display Files . . . . . . . . 8-1

Chapter 9. Creating and Accessing Menus Using Display Files . . . . . . 9-1

Chapter 10. Using User-Defined Data Streams . . . . . . . . . . . . . . . . 10-1

Chapter 11. Passing Data between Programs . . . . . . . . . . . . . . . . 11-1

Chapter 14. Improving System Performance with Displays . . . . . . . . 14-1

Part 3. Programming Application Displays Using Panel Groups

Chapter 15. Improving Productivity with User Interface Manager . . . . 15-1

Chapter 16. Introduction to the User Interface Manager . . . . . . . . . . 16-1

viii Application Display Programming V4R1

Chapter 17. Details of Using User Interface Manager . . . . . . . . . . . . 17-1

Part 4. Programming Help Displays

Chapter 18. Making Online Help Information Accessible for Your

x Application Display Programming V4R1

Chapter 20. Defining Online Help Information . . . . . . . . . . . . . . . . 20-1

Part 5. Guidelines for IBM AS/400-Style Displays

Chapter 21. Designing IBM AS/400-Style Displays . . . . . . . . . . . . . 21-1

Appendix A. UIM Panel Group Definition Language . . . . . . . . . . . . A-1

xii Application Display Programming V4R1

xiv Application Display Programming V4R1

xvi Application Display Programming V4R1

Appendix B. UIM Dialog Commands . . . . . . . . . . . . . . . . . . . . . . B-1

Appendix C. Feedback Area Layouts for Display Files . . . . . . . . . . . C-1

Appendix D. Double-Byte Character Set Support for Displays . . . . . . D-1

xviii Application Display Programming V4R1

Appendix E. Display File Return Codes . . . . . . . . . . . . . . . . . . . . E-1

Appendix F. Edit Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . F-1

Appendix G. System/36-Compatible Display Data Management . . . . . G-1

xx Application Display Programming V4R1

 Copyright IBM Corp. 1997 xxi

xxii Application Display Programming V4R1

xxiv Application Display Programming V4R1

 Copyright IBM Corp. 1997 xxv

xxvi Application Display Programming V4R1

Address your questions to:

This publication could contain technical inaccuracies or typographical errors.

 Copyright IBM Corp. 1997 xxix

AFP Operating System/400

C-bus is a trademark of Corollary, Inc.

Java and HotJava are trademarks of Sun Microsystems, Inc.