The INQUIRE Verb: A Window Into Your Controls
by Bob CavanaghThe INQUIRE verb, available with ACUCOBOL-GT® Version 3.1 and later versions, allows the programmer to return the values of the special properties of a control, as well as its TITLE and VALUE properties, into data items. The INQUIRE verb is documented in the ACUCOBOL-GT Reference Manual (See Paragraph 6.6.21, INQUIRE Statement). Additional references in the User Interface Programming Manual describe how to use it to return the value of a list box item via the Item-Value special property. (See Paragraph 5.8, List-Box Control, Special Properties.)
There are two forms of the INQUIRE verb. They reflect an internal redundancy in the runtime, with respect to the storage of information for controls.
The first form, and the more useful, inquires about the handle of a control. To make a FILE I-O analogy which may be useful, INQUIREing about a control handle is like OPENing a file INPUT, so you can READ it. The HANDLE is basically just a pointer to the area of memory where the information about the properties of a control is stored.
The second form of the INQUIRE verb identifies the control by its location. This form takes advantage of an internal table maintained by the runtime, which tracks controls by their location. In its current implementation, it has more limited usefulness than the inquiry via a typed handle. The second form cannot be used to return information about special properties, and can be depended upon only if precisely one control exists at a given location. This second form of the INQUIRE verb would look like this:
77 ctl-value pic x(30).
77 ctl-title pic x(30).
INQUIRE CONTROL at 0505
VALUE in ctl-value
TITLE in ctl-title.
In future versions of ACUCOBOL-GT, we plan to enable this construct to return information about special properties, as well.
Here is an example of the first form of the INQUIRE verb, operating on an ENTRY-FIELD:
77 entry-field-handle usage handle of entry-field.
77 ctl-value pic x(30).
77 ctl-max-text pic 99.
77 ctl-max-lines pic 99.
77 ctl-cursor pic 99.
INQUIRE entry-field-handle
VALUE in ctl-value
MAX-TEXT in ctl-max-text
MAX-LINES in ctl-max-lines
CURSOR in ctl-cursor.
Note that entry-field-handle is a typed handle. That is, it has been declared as USAGE HANDLE OF ENTRY-FIELD. If it were declared merely as USAGE HANDLE, the program would not compile, and the compiler would report an inability to resolve the special properties MAX-TEXT, MAX-LINES, and CURSOR.
In order to return information about special properties, the INQUIRE verb must have a typed handle. With a generic handle, it can return information only about the common properties VALUE and TITLE. An obviously important concept then is, how do you get a typed handle out of a Screen Section entry in which the handle is not declared explicitly? In the following code fragment, we accomplish this by associating the control's name with a SET phrase:
01 screen-1.
. . .
03 entry-1, entry-field, using multiple entry-table
line + 1.5, column 8, size 50, lines 5,
no-autosel, max-lines = 20, vscroll-bar, 3-d,
use-return.
. . .
set entry-field-handle to handle of entry-1.
Let's look at more of the code. The following fragment sets up a feedback loop between INQUIRE and MODIFY, via a PROPERTIES floating window that displays the current values of the special properties of a control and allows the user to modify them. The result is the modification of the properties within the control.
I chose to use entry-fields and "after procedures" to accomplish the feedback loop in the PROPERTY-SCREEN. It is, I think, the easiest way to accomplish this, though alternatives using a single entry-field at the top of the PROPERTY-SCREEN and a list box would also work.
identification division.
program-id. inquir.
environment division.
data division.
*
working-storage section.
*
77 property-handle usage handle.
77 entry-field-handle usage handle of entry-field.
*
01 property-fields.
05 ctl-value pic x(350).
05 ctl-value-tbl redefines ctl-value.
10 ctl-value-table occurs 5 times pic x(70).
05 ctl-max-text pic 999.
05 ctl-max-lines pic 9 value 0.
05 ctl-cursor pic 999 value 0.
*
01 prv-property-fields.
05 prv-ctl-value pic x(350).
05 prv-ctl-value-tbl
redefines prv-ctl-value.
10 prv-ctl-value-table
occurs 5 times pic x(70).
05 prv-ctl-max-text pic 999.
05 prv-ctl-max-lines pic 9.
05 prv-ctl-cursor pic 999.
*
77 key-status is special-names crt status
pic 9(4).
88 property-button-pushed value 1.
88 exit-button-pushed value 15.
01 entry-tbl.
05 entry-table occurs 5 times pic x(70).
*
screen section.
01 screen-1.
03 label "&Scrolling entry box", line + 2.5,
lines 3.5, column 5.
03 entry-1, entry-field, using multiple entry-table
line + 1.5, column 8, size 50, lines 5,
no-autosel, vscroll-bar, 3-d, use-return.
03 push-button, "&Properties", line 24 column 17,
size 13 self-act, exception-value 1.
03 push-button, "E&xit Program", self-act,
exception-value 15 line 24, column 36, size 13.
*
01 ef-property-screen.
05 entry-field value "Value" read-only, no-autosel
line 2.5 col 5 size 30 lines 1.2.
05 entry-field value ctl-value col 32 size 30
after procedure mod-value.
05 entry-field value "Max Text" read-only, no-autosel
line + 1.2 col 5 size 30.
05 entry-field value ctl-max-text col 32 size 30
after procedure mod-max-text.
05 entry-field value "Max Lines" read-only, no-autosel
line + 1.2 col 5 size 30.
05 entry-field value ctl-max-lines col 32 size 30
after procedure mod-max-lines.
05 entry-field value "Cursor" read-only, no-autosel
line + 1.2 col 5 size 30.
05 entry-field value ctl-cursor col 32 size 30
after procedure mod-cursor.
*
procedure division.
main-logic.
*
display standard graphical window, title "Inquire
Sample" lines 26, size 66, background-low.
display screen-1.
set entry-field-handle to handle of entry-1.
*
perform, with test after, until exit-button-pushed
accept screen-1 on exception
if property-button-pushed
perform review-inquiry
end-if
end-accept
display screen-1
end-perform.
stop run.
*
review-inquiry.
display floating window at 0808 size 64 lines 8
title-bar top centered title is "Properties"
with system menu handle in property-handle.
perform return-entryfield-properties.
perform do-ef-property-screen.
*
return-entryfield-properties.
inquire entry-field-handle
value in ctl-value
max-text in ctl-max-text
max-lines in ctl-max-lines
cursor in ctl-cursor.
move property-fields to prv-property-fields.
*
do-ef-property-screen.
display ef-property-screen upon property-handle.
accept ef-property-screen.
close window property-handle.
*
mod-value.
if ctl-value not = prv-ctl-value
move ctl-value-tbl to entry-tbl
modify entry-1 value is multiple entry-table.
*
mod-max-text.
if ctl-max-text not = prv-ctl-max-text
modify entry-1 max-text = ctl-max-text.
*
mod-max-lines.
if ctl-max-lines not = prv-ctl-max-lines
modify entry-1 max-lines = ctl-max-lines.
*
mod-cursor.
if ctl-cursor not = prv-ctl-cursor
modify entry-1 cursor = ctl-cursor.
identification division.
program-id. handler.
* Copyright (c) 1997 by Acucorp, Inc. Users of ACUCOBOL-GT
* may freely modify and redistribute this program.
remarks.
This program demonstrates various types of floating
windows. It is driven by a list box from the
program's initial window.
data division.
working-storage section.
copy "acucobol.def".
copy "acugui.def".
01 all-handles.
03 emp-handle usage handle.
03 num-handle usage handle.
03 date-handle usage handle.
03 sal-handle usage handle.
03 dept-handle usage handle.
77 float-title pic x(20) value space.
77 large-font handle.
77 small-font handle.
77 key-status is special-names crt status pic 9(4).
88 return-key-pressed value 13.
88 tab-key-pressed value 10.
88 event-happend value 96.
88 display-window-pushed value 100.
88 upon-pressed value 200.
01 emp-name pic x(30) value "Joe Cobol".
01 emp-num pic x(20) value "1123456".
01 emp-hire pic 9(8) value 010196.
01 emp-sal pic 9(9) value 2345.
01 emp-dept pic 9(6) value 987.
01 current-field pic 9(9) value 1.
01 event-status is special-names event status.
03 event-type pic x(4) comp-x.
88 new-field value cmd-goto.
03 event-window-handle usage handle.
03 event-control-handle usage handle.
03 event-control-id pic x(2) comp-x.
03 event-data-1 usage signed-short.
03 event-data-1 usage signed-long.
procedure division.
main-logic.
* Set up a gray screen background
display standard window lines 15 size 40
title "Event Handler" background-low.
perform paint-screen.
perform enter-data until return-key-pressed.
stop run.
paint-screen.
display label "Employee Name: " line 2 column 2.
display label "Employee Number: " line 4 column 2.
display label "Hire Date: " line 6 column 2.
display label "Current Salary: " line 8 column 2.
display label "Department: " line 10 column 2.
display push-button line 13 column 14 title
"&Exit Program" size 14 self-act,
termination-value = 13.
display entry-field line 2 column 23 size 15
value emp-name handle in emp-handle id = 1.
display entry-field line 4 column 23 size 15
value emp-num handle in num-handle id = 2.
display entry-field line 6 column 23 size 15
value emp-hire handle in date-handle id = 3.
display entry-field line 8 column 23 size 15
value emp-sal handle in sal-handle id = 4.
display entry-field line 10 column 23 size 15
value emp-dept handle in dept-handle id = 5.
enter-data.
evaluate current-field
when 1
perform accept-1
when 2
perform accept-2
when 3
perform accept-3
when 4
perform accept-4
when 5
perform accept-5
end-evaluate.
evaluate true
when tab-key-pressed
if current-field < 5
add 1 to current-field
else
if current-field = 5
move 1 to current-field
end-if
end-if
when event-happend
if event-type = cmd-goto
move event-control-id to current-field
end-if
end-evaluate.
accept-1.
accept emp-handle.
accept-2.
accept num-handle.
accept-3.
accept date-handle.
accept-4.
accept sal-handle.
accept-5.
accept dept-handle.
####
Acucorp, extend and ACUCOBOL are trademarks or registered trademarks of Acucorp, Inc. All rights reserved. All other trademarks are the property of their respective owners.
