| Migrating to Different Platforms | Using the Client/Server Binding | |
Dialog System has Panels Version 2 (Panels V2) as its underlying technology.
Using Panels V2 with Dialog System enables you to:
For example, using Panels V2 calls, you can switch off the System Menu.
For example, the rubber banding techniques that you see in the Definition Facility software do not exist in Dialog System but are available in Panels V2.
This chapter shows how you can enhance your Dialog System application with Panels V2.
The following fragment is an example of a Panels V2 call statement.
call "PANELS2" using p2-parameter-block
p2d-dialog-box-record
new-title-buffer
attribute-buffer
Panels V2 calls Pan2win, and Pan2win issues the appropriate Windows API calls.
The set of functions that Panels V2 provides are the same regardless of the environment you are using, assuming of course that the environment supports the display feature.
Dialog System is based on this technology.
Figure 13-1 shows a typical Dialog System application that contains calls to Panels V2.
Figure 13-1: Dialog System/Panels V2 Events
Notice how events are handled. There is no direct line for events between Panels V2 and your application. When an event occurs, Panels V2 detects the event and returns the event information through Dialog System (Dsgrun). Dialog System then returns the event information to your program through the Dialog System Event Block (dssysinf.cpy). You must use dialog to determine if (and how) you want to handle the event in Dialog System or your application.
You must include several copyfiles in the Working-Storage Section of your program. For example:
working-storage section.
copy "ds-cntrl.mf".
copy "clip.cpb".
copy "pan2link.cpy".
copy "dssysinf.cpy".
The first two you are already familiar with: the Dialog System Control Block and the Data Block generated from your screenset. See the topic The Call Interface in the Help for a description of these files.
The other two copyfiles are described in the next two sections.
Your COBOL program also should contain the pan2link.cpy copyfile .
The file contains:
Although this file is not absolutely necessary, the definitions in this file greatly simplify the writing of the Panels V2 part of the application.
Browse this file to get an idea of the type of information it contains.
This file contains the definitions of the Dialog System Event Block. When an event occurs, information about the event is passed through the Panels V2 Event Block back to Dialog System. (Refer to Figure 13-1.) dssysinf.cpy is just a copy of the Panels V2 Event Block with extra fields added on for Dialog System use.
01 ds-event-block.
78 ds-eb-start value next.
03 ds-ancestor pic 9(9) comp-5.
03 ds-descendant pic 9(9) comp-5.
03 ds-screenset-id pic x(8).
03 ds-event-screenset-details.
05 ds-event-screenset-id pic x(8).
05 ds-event-screenset-instance-no pic 9(2) comp-x.
03 ds-event-reserved pic x(11).
03 ds-event-type pic 9(4) comp-5.
03 ds-event-data.
05 ds-gadget-event-data.
07 ds-gadget-type pic 9(2) comp-x.
07 ds-gadget-command pic 9(2) comp-x.
07 ds-gadget-id pic 9(4) comp-5.
07 ds-gadget-return pic 9(4) comp-5.
05 ds-mouse-event-data.
07 ds-mouse-x pic s9(4) comp-5.
07 ds-mouse-y pic s9(4) comp-5.
07 ds-mouse-state pic 9(2) comp-x.
07 ds-mouse-moved-flag pic 9(2) comp-x.
07 ds-mouse-over pic 9(2) comp-x.
07 filler pic x(3).
78 ds-eb-size value next - ds-eb-start.
05 ds-keyboard-event-data redefines ds-mouse-event-data.
07 ds-char-1.
09 ds-byte-1 pic 9(2) comp-x.
07 ds-char-2.
09 ds-byte-2 pic 9(2) comp-x.
07 filler pic x(8).
05 ds-window-event-data redefines ds-mouse-event-data.
07 ds-window-x pic s9(9) comp-5.
07 ds-window-y pic s9(9) comp-5.
07 ds-window-command pic 9(2) comp-x.
07 filler pic x.
The fields in dssysinf.cpy of particular interest are ds-descendant
and ds-ancestor.
When Dialog System creates an object it gets back a unique
identifier for that object called a handle. If an event occurs on that
object, Panels V2 passes back to Dialog System the handle of the object
as well as the handle of the parent window
of the object. These two handles, ds-descendant and
ds-ancestor, are filled whenever an event occurs.
Note: The format of dssysinf.cpy has changed from Dialog System V2.1. If you have any Dialog System V2.1 programs that used dssysinf.cpy, you must re-compile them.
The steps you must follow in a Dialog System/Panels V2 application are:
To illustrate these steps, the following sections present a simple example of a Panels V2 function that renames a push button. Although a dialog function is available to do this (SET-OBJECT-LABEL), this example illustrates the main features of the Panels V2 call interface.
In your COBOL program, initialize Dialog System with a statement like:
call "dsgrun" using ds-control-block
data-block
ds-event-block
One of the items returned by Dialog System is ds-session-id
(this item is stored in the Control Block). ds-session-id
is the thread identifier of the Dialog System session. For your
application to cooperate with Dialog System in its communication with
Panels V2, you must make this identifier known to Panels V2. Do this with
a statement like:
move ds-session-id to p2-mf-reserved
where p2-mf-reserved is a data item in the Panels V2
parameter block.
This statement establishes the necessary communication link between Dialog System and Panels V2. Now you can make direct Panels V2 calls.
The MOVE-OBJECT-HANDLE function lets you save the handle of an object in a numeric data item in the Data Block. This ensures the same objects are being referenced by both the Panels V2 and the Dialog System parts of your application. As an example:
MOVE-OBJECT-HANDLE RENAME-PB PB-HAND MOVE-OBJECT-HANDLE RENAME-WIN WIND-HAND
stores the handle of a push button named RENAME-PB in a
numeric item PB-HAND and the handle of the window named
RENAME-WIN in WIND-HAND. RENAME-WIN
and WIND-HAND are defined in data definition as:
RENAME-HAND C 4.00 WIND-HAND C 4.00
Now your application (and hence Panels V2), has access to your Dialog System objects.
This fragment shows the code necessary to change the title of a push button.
1 rename-button section. 2 3 initialize p2-parameter-block 4 initialize p2g-button-record 5 move 250 to p2g-button-text-length 6 move pb-hand to p2-descendant 7 move ds-session-id to p2-mf-reserved 8 move pf-get-button-details to p2-function 9 call "PANELS2" using p2-parameter-block 10 p2g-button-record 11 text-buffer 12 end-call 13 perform varying ndx1 from 30 by -1 until ndx1 = 1 or 14 rename-text(ndx1:1) not = " " 15 continue 16 end-perform 17 move ndx1 to p2g-button-text-length 18 move pf-set-button-details to p2-function 19 call "PANELS2" using p2-parameter-block 20 p2g-button-record 21 rename-text 22 end-call.
rename-button section.
This section illustrates the Panels V2 call interface.
initialize p2-parameter-block
initialize p2g-button-record
move 250 to p2g-button-text-length
Initialize some Panels V2 parameters.
move pb-hand to p2-descendant
pb-hand is the handle of the push button. This field is in
the Data Block.
move ds-session-id to p2-mf-reserved
ds-session-id is the thread identifier of the Dialog
System session. See the section Establishing Dialog System and Panels
V2 Communication.
move pf-get-button-details to p2-function
pf-get-button-details is a Panels V2 function to retrieve
the details of a push button. Because we are only interested in changing
the title, all the remaining features are the same.
call "PANELS2" using p2-parameter-block
p2g-button-record
text-buffer
end-call
Panels V2 call statement.
perform varying ndx1 from 30 by -1 until ndx1 = 1 or
rename-text(ndx1:1) not = " "
continue
end-perform
This perform clause removes trailing spaces from rename-text,
which contains the new name for the button.
move ndx1 to p2g-button-text-length
After removing trailing spaces, ndx1 contains the actual
length of the name. p2g-button-text-length is the Panels V2
parameter that contains the length of the title buffer.
move pf-set-button-details to p2-function
This Panels V2 function changes the attributes of a push button.
call "PANELS2" using p2-parameter-block
p2g-button-record
rename-text
end-call.
Another Panels V2 call.
Warning: Do not create or delete any objects with Panels V2. Dialog System assumes it is in complete control. For example, if Panels V2 creates an object, the handle is never passed to Dialog System. As a result, any events related to that object by-pass Dialog System.
Two more extensive applications illustrating the Dialog System/Panels V2 interface are available in the demo directory. One, Clip, shows how you can incorporate some basic Panels V2 clipboard read and write functions into your Dialog System application. The other, Dsp2demo, shows some clipboard functions, setting colors, and window scrolling.
You can generate and receive Panels V2 user events in Dialog System. See the function descriptions for POST-USER-EVENT and GET-USER-EVENT-DATA in the Help. The first 32,000 events are reserved for Micro Focus use.
Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Migrating to Different Platforms | Using the Client/Server Binding | |