The INQUIRE Verb: A Window Into Your Controls

by Bob Cavanagh

The 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, 
   . . .
 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.
     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
       display screen-1
     stop run.
     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.
     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.
     display ef-property-screen upon property-handle.
     accept ef-property-screen.
     close window property-handle.
     if ctl-value not = prv-ctl-value
       move ctl-value-tbl to entry-tbl
       modify entry-1 value is multiple entry-table.
     if ctl-max-text not = prv-ctl-max-text
       modify entry-1 max-text = ctl-max-text.
     if ctl-max-lines not = prv-ctl-max-lines
       modify entry-1 max-lines = ctl-max-lines.
     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. 
     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.
* 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.
     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. 
     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
     evaluate true
       when tab-key-pressed
         if current-field < 5
           add 1 to current-field
           if current-field = 5
             move 1 to current-field
       when event-happend
         if event-type = cmd-goto
           move event-control-id to current-field
     accept emp-handle.
     accept num-handle.
     accept date-handle.
     accept sal-handle.
     accept dept-handle.
Your Session will expire in 90 minutes
Notification will be shown in:
600 seconds