SAA Dialog Manager
AS/400 Screen Handling Under SAA
Are you an AS/400 programmer wondering how to make your
programs consistent with the SAA Common Programming
Interface. Well here is the missing bit.
The SAA RPG CPI specifications do not allow WORKSTATION
files in an RPG/400 program. Check this by setting the
SAAFLAG parameter to *FLAG on the CRTRPGPGM compiler
command. The message you get is in the SAA Message Summary
at the bottom of the compiler listing. It reads:
QRG8110 - SAA RPG does not support device entry of WORKSTN.
You need an SAA Dialog Manager for the AS/400 to send
information to the screen. What is a Dialog Manager and what
does it look like? Let us look at where it fits into SAA
first.
SAA Common Programming Interface
One of the components of Systems Application Architecture
(SAA) is the Common Programming Interface (CPI). This
interface specifies the languages, commands and calls that a
programmer can use to write SAA applications. These
applications can then be implemented across all the SAA
environments.
The Languages component of CPI provides consistent
implementation of common programming languages. These
include RPG, COBOL, FORTRAN, C and others. The Services
component of CPI provides for programming services such as
Query, Database, Communication, Presentation and Dialog.
When writing an application all you have to worry about is
the internal logic of your programs. You CALL all the other
services. For example, you may use SQL/400, which adheres to
the Database CPI, to manage the database; or you may use
OS/2 Dialog Manager, which adheres to the Dialog CPI, to
manage the screens and interaction with users.
1
Presentation or Dialog ?
If using a Presentation Manager, you have to design the
screen and handle all the user interaction from within your
application. You have to draw all the action bars, pull down
windows and manage the help function. Your application has
to adhere to CUA specification as well. Presentation
Managers are best suited for the Programmable Workstation
(PWS) models of CUA mainly for the OS/2 environment.
On the other hand, Dialog Managers will draw all the panels,
action bars, windows, manage the help function and handle
user interaction. Dialog Managers will open the pull down
windows if a valid action bar choice is selected and they
will display help panels when the help key is pressed. Help
can be field specific, panel specific or message specific.
On top of it all, the Dialog Manager automatically enforces
much of CUA. A Dialog Manager is best suited for the Entry
CUA model.
Products already on the market are the IBM OS/2 Presentation
Manager, IBM OS/2 Dialog Manager, ISL AS/400 Dialog Manager
and IBM ISPF V3 for the VM and MVS environments.
Dialog Manager
The Dialog Manager comes in two parts. The first is the
Dialog Tag Language (DTL) that is used to define the panels
and dialog elements in a source member. The source member
may contain one or more panels for an application. The
source is compiled, using a DTL compiler, into a highly
compressed format.
The second part is the run-time module (ISPCI). You issue
calls from your program to the run-time module using dialog
services. These services allow you to start a dialog
session, display panels, display messages and interact with
the dialog manager. The runtime module displays the selected
panels with all the data and waits for user interaction.
2
The following figure shows the flow of using a Dialog
manager.
-----------------------------------------------------------+--------+
+--------+
+---------+
Ý HLL
Ý HLL
Ý *PGM
+------------------>Ý Printer Ý
Ý Source +--------->Ý Object Ý<-+
Ý
+-----+
+--------+ Compiler +--------+ Ý +---------+
+---+
+->Ý DM
Ý
+---------+
+--------+
+--------+
Ý (ISPCI) Ý<->Ý Screen Ý
Ý DTL
Ý DTL
Ý Panel +---->+---------+
Ý
Ý
Ý Source +--------->Ý Object Ý
+---------+
+--------+ Compiler +--------+
-----------------------------------------------------------Figure 1.
Dialog Tag Language
The DTL is a programming markup language that is based on
the Standard Generalized Markup Language (SGML). It is used
to define dialog elements in a source member. These dialog
elements include panels, messages, key lists and variables.
Each element starts with a tag and ends with a tag. For
example to define a panel, the following markup would by
used.
-----------------------------------------------------------<panel name=custlist>Customer List
* Panel Defn
:
:
</panel>
* End Panel
-----------------------------------------------------------Within the panel definitions, you can further define the
following elements:
action bars
action bar choices
pull down choices
pull down separator
mnemonic
regions
top instructions
line dividers
data columns
data fields
data field descriptions
list fields
list columns
and many more...
<ab>
<abc>
<pdc>
<pdsep>
<m>
<region>
<topinst>
<divider>
<dtacol>
<dtafld>
<dtafldd>
<lstfld>
<lstcol>
3
The following DTL source and the panel it produces, may
simply the definition further. (Not all tags and tag
parameters are shown.)
-----------------------------------------------------------<panel name=EnvCtl >Environment Control
* Panel Start
<ab>
<abc><m>Jobs
</abc>
<abc><m>Printers
</abc>
<abc><m>Messages
</abc>
<abc><m>Configuration
</abc>
<abc>E<m>xit
<pdc>1. Resume
<action run=RES>
<pdc>2. Exit
<action run=EXT>
</abc>
</ab>
<topinst>Enter default values.
<divider>
* Action bar
* Action Choice
* Pull Down
* Run Command
* End Action Bar
* Spacing Line
<dtacol>
* Data Column
<dtafld name=PRTDEV usage=both >Printer Device
<dtafld name=OUTQ
usage=both >Output Queue
<divider>
<dtafld name=DFTLIB usage=both >Default Library
<dtafldd>*CURLIB, Char
</dtacol>
* End Column
</panel>
* End Panel
-----------------------------------------------------------Figure 2.
4
+----------------------------------------------------------+
Ý _ Jobs Printers Messages Configuration Exit
Ý
+----------------------------------------------------------Ý
Ý ENVCTL
Environment Control
Ý _ 1. Resume Ý
Ý
Ý
2. Exit
Ý
Ý
Enter default values.
+--------------Ý
Ý
Ý F3=Cancel
Ý
Ý
Printer Device . . . . __________
+--------------Ý
Ý
Output Queue . . . . . __________
Ý
Ý
Ý
Ý
Default Library . . . __________
*CURLIB, Char
Ý
Ý
Ý
Ý
Ý
Ý
Ý
Ý
Ý
Ý
Ý
+----------------------------------------------------------Ý
Ý Enter
F1=Help
F10=Action
Ý
+----------------------------------------------------------+
Figure 3.
If an action bar is defined for a panel, your application
program does not have to activate it. All you have to do is
activate the main panel. The Dialog Manager moves the cursor
to the action bar if the Action key is pressed. It accepts a
valid action bar choice and displays the pull down choice
menu, if defined. It then waits for a valid pull down choice
before returning to your application program.
Error messages are automatically displayed when invalid
choices are entered. The Dialog Manager also checks for all
valid function keys that have been defined in the key list.
If the user presses the help key and a help panel has been
defined, the Dialog Manager will load the help processor and
pass on the help panel name. The same applies to the print
key.
Help panels can be defined for the main panel, action bar
choice, pull down choice, data fields, list columns and
messages. The help panel is defined using the <help> and
</help> tags and includes a host of text formatting tags
similar to GML.
Key lists define the keys that are allowed in a panel. The
key list is attached to the panel by defining it on the
panel tag (<panel keyl=xxxx>). The Dialog Manager displays
the key descriptions on the panel and makes only those keys
active.
Windows are defined by filling in the WIDTH= and DEPTH=
parameters of the <panel> tag. Panels as well as help panels
can be made into windows.
5
The syntax of the <panel> tag as follows:
+----------------------------------------------------------+
Ý >>--<PANEL--NAME=panel-name---------------------------> Ý
Ý
+-WIDTH=n---DEPTH=n--+
Ý
Ý
Ý
Ý >----------------------------------------------------> Ý
Ý
+-HELP=panel-name-+
+-KEYL=key-list-+
Ý
Ý
Ý
Ý >-->--panel-title-------------------------</PANEL>--->< Ý
+----------------------------------------------------------+
Figure 4.
Dialog Services
Dialog Services are used to communicate with the Dialog
Manager. These services are passed to the Dialog manager in
parameters. The CALL syntax is as follows:
CALL ISPCI PARM(dmcomm buflen buffer)
Dmcomm is the Dialog Manager's reserved parameter. It
returns to your application return codes, reason codes and
other environment specific information.
The buflen parameter contains the length of the dialog
service that is contained in the buffer parameter.
All dialog services are sent in the 512 byte buffer
parameter. Some of the common services are DMOPEN, DMCLOSE,
DISPLAY, SETMSG, etc.
6
The following diagram better explains how the services can
be issued through your application (note that only the
buffer parameter of the CALL to the Dialog Manager, ISPCI,
is shown).
-----------------------------------------------------------Initialize variables
CALL ISPCI ('DMOPEN')
:
:
Loop
CALL ISPCI ('DISPLAY PANEL(xxxx)')
If Exit or Cancel, End Loop
If Action Bar, Do action specified on DTL <action>
Else, Check panel data
If Error, CALL ISPCI ('SETMSG MSG(xxxx)')
Else, Exit Loop
End Loop
:
:
CALL ISPCI ('DMCLOSE')
End of program
-----------------------------------------------------------Figure 5.
The most often used service is the DISPLAY service. It
allows you to display a panel, display a message on the
panel, position the cursor on a field, lock the display from
user input or sound the alarm. Syntax of the Display service
is as follows:
+----------------------------------------------------------+
Ý >>---DISPLAY---PANEL(panel-name)-----------------------> Ý
Ý
+--MSG(message-id)-+
Ý
Ý >-----------------------------------------------------><Ý
Ý
+--CURSOR(field-name)-+ +-LOCK-+ +-ALARM-+
Ý
+----------------------------------------------------------+
Figure 6.
Summary
Why use a Dialog Manager ?
It simplifies and speeds up programming. This is achieved by
providing standard programming interfaces for panel and
message display and by controlling program flow. It allows
for standardization of user interaction over multiple
applications and multiple environments. It helps in creating
panels that conform to SAA Common User Access.
7
The ISL AS/400 Dialog Manager will give your programs the
look and feel of any Entry model OS/2 written program. It
also paves the way for migrating AS/400 programs to the OS/2
or MVS environments.
To get a better understanding of how a Dialog Manager
operates and how to design your applications around one, the
listed references are a must.
References
SAA An Overview (GC26-4341)
SAA Writing Applications: A Design Guide (SC26-4362)
SAA CUA Basic Interface Design Guide (SC26-4583)
SAA CPI Dialog Reference (SC26-4356)
OS/2 Dialog Manager V1.2 Guide & Reference (64F0284)
ISL AS/400 Dialog Manager V1.12 Reference, August 1990
Trademarks
SAA, OS/2, AS/400, SQL/400 and RPG/400 are trademarks of IBM
Corporation.
Ashok Kumar
Technical Manager
Infodata Systems Limited
P O Box 1574
Dunedin, NEW ZEALAND
Contact phone (3) 477-6971
fax
(3) 474-1564
8