INQUIRE Statement

The INQUIRE verb allows you to retrieve information from a control, or retrieve the dimensions of a window.

General Format

INQUIRE { control-item } [ ( {index-1} ... ) ]
        { CONTROL      }

Remaining phrases are optional, can appear in any order. 

AT screen-loc   [CELL  ]
                [CELLS ]
                [PIXEL ]
                [PIXELS]

AT LINE NUMBER line-num   [CELL  ]
                          [CELLS ]
                          [PIXEL ]
                          [PIXELS]

AT {COLUMN  } NUMBER col-num   [CELL  ]
   {COL     }                  [CELLS ]
   {POSITION}                  [PIXEL ]
   {POS     }                  [PIXELS]

AT CLINE NUMBER cline-num   [CELL ]
                            [CELLS]

AT CCOL NUMBER ccol-num   [CELL ]
                          [CELLS]

TITLE {IN} title
      {= }

VALUE {IN} [ MULTIPLE ] value [ LENGTH {IN} length-1 ]
      {= } [ TABLE    ]                {= }

STYLE {IN} style-flags
      {= }

HELP-ID {IN} help-id
        {= }

{{property-name         } [({param-expr}...)] {IN} property-value ...
 {PROPERTY property-name}                     {= }   
 {object-expression     }
     [ LENGTH {IN} length-1 ] }
              {= }
SYSTEM HANDLE {IN} system-handle
              {= }

POP-UP MENU {IN}  {menu-1}
            {= }

LINE NUMBER {IN} line-num
            {= }

{COLUMN  } NUMBER {IN} col-num
{COL     }        {= }
{POSITION}
{POS     }

SIZE {IN} width
     {= }

LINES {IN} height
      {= }

MAX-HEIGHT {IN} max-height
           {= }

MAX-WIDTH  {IN} max-width
           {= }

MIN-HEIGHT {IN} min-height
           {= }

MIN-WIDTH  {IN} min-width
           {= }
ID {IN} id
   {= }

CLASS {IN} class-code
      {= }

EXCLUDE-EVENT-LIST {IN} list-state
                   {= }

LAYOUT-DATA {IN} layout-data          
            {= }
ENABLED {IN} enabled-state          
        {= }

VISIBLE {IN} visible-state        
        {= }

where param-expr is one of the following: 

{ param                               } [ AS type_num ]

{ {BY} NAME parameter-name {IS} param }
{                          {= }       }

{ parameter-name {IS} param           }
{                {= }                 }

object-expression has the following format: 

{ {^} property-1 [ (param-expr ... ) ]
  [ :: property-2 [ ( param-expr ... ) ] ... }

Format 2

INQUIRE { window-handle           }
        { WINDOW [generic-handle] }

Remaining phrases are optional, can appear in any order. 

LINE NUMBER {IN} line-no
            {= }

{COLUMN  } NUMBER {IN} col-num
{COL     }        {= }
{POSITION}
{POS     }

TITLE {IN} title
      {= }

SCREEN LINE NUMBER {IN} screen-line
                   {= }

SCREEN {COLUMN  } NUMBER {IN} screen-col
       {COL     }        {= }
       {POSITION}
       {POS     }

SIZE {IN} width
     {= }

LINES {IN} height
      {= }

SYSTEM HANDLE {IN} system-handle
              {= }

LAYOUT-MANAGER {IN} layout-manager
               {= }
VISIBLE {IN} visible-state
        {= }

POP-UP MENU {IN} menu-1
            {= }

Syntax Rules

  1. control-item is a USAGE HANDLE data item that identifies the control to be inquired. If it is a typed handle, then it must be associated with a control. control-item can also be an elementary Screen Section item that describes a control.
  2. index-1 is a numeric expression. The parentheses surrounding index-1 are required.
  3. The AT, LINE, COLUMN, CLINE, and CCOL phrases must appear in conjunction with the CONTROL phrase.
  4. screen-loc is an integer data item or literal that contains exactly 4, 6, or 8 digits.
  5. line-num, col-num, cline-num, and ccol-num are numeric data items or literals. Note that they may contain non-integer values, except when pixels are specified.
  6. title is an alphanumeric data item.
  7. value may be any data item.
  8. style-flags is a numeric data item capable of holding 10 or more digits.
  9. help-id is a numeric data item.
  10. property-name is the name of a property specific to the type of control being inquired. If control-item refers to a generic handle, or if the CONTROL option is specified, then property-name cannot be used. Use the PROPERTY phrase instead.
  11. property-type is a numeric literal or data item.
  12. property-value is a data item. Its data type should be appropriate for the specified property.
  13. In param-expr:
    1. param is a literal, data-item, or numeric expression used when inquiring the property value of an ActiveX control or COM object.
    2. type-num is a numeric data item or numeric literal.
  14. In object-expression:
    1. ^ can only be used in conjunction with a Format 5 USE verb for an ActiveX control or COM object.
    2. property-1 is the name of a property of the ActiveX control or COM object. property-1 cannot be a write-only property.
    3. property-2 is the name of a property of the ActiveX control or COM object that is the value of property-1. property-2 cannot be a write-only property.
  15. length-1 is a numeric data item. The LENGTH phrase may be specified only if the value or property-value immediately preceding it is an alphanumeric data item.
  16. window-handle is a USAGE HANDLE OF WINDOW or PIC X(10) data item.
  17. generic-handle is a USAGE HANDLE, HANDLE OF WINDOW, or PIC X(10) data item.
  18. line-no, col-no, screen-line, screen-col, width, height, max-height, max-width, min-height, and min-width are numeric data items. line-no and col-no should be signed and have at least two digits after the decimal point to get the best results. screen-line and screen-col should be signed to get the best result.
  19. system-handle, visible-state, and layout-data are numeric data items.
  20. menu-1 is a USAGE HANDLE or HANDLE OF MENU data item.
  21. id, class-code, and enabled-state are numeric data items.
  22. list-state is a numeric data item.
  23. layout-manager is a HANDLE or HANDLE OF LAYOUT-MANAGER data item.
  24. In Format 1, the LINE IN phrase and the COLUMN IN phrase may be used only if the control-item option is specified.

Format 1 General Rules

  1. The INQUIRE CONTROL statement retrieves some or all of a control's current properties, and stores them as data items. It can also be used to retrieve property data from ActiveX controls, COM objects, and .NET controls (also known as assemblies). control-item identifies the control to inquire. If the CONTROL phrase is used instead, the runtime inquires the control located at the screen position specified by the AT, LINE, and COLUMN phrases in the current window (on non-graphical systems, the CLINE and CCOL phrases also apply). The runtime system maintains a list of controls in each window. When you are attempting to inquire from a control at a specific location, the runtime searches this list, inquiring the first control it finds that exactly matches the given location. The list is maintained in the order in which the controls are created.
  2. If control-item does not refer to a valid control, or if the runtime cannot locate a control at the specified screen location, the INQUIRE statement has no effect.
  3. If index-1 is specified, then certain properties in the control being inquired are modified to match the value of index-1. This modification occurs before any inquiry occurs. The exact set of properties modified depends on the control's type. Three controls have properties that are modified in this way:
    Control Type Properties Affected
    List Box QUERY-INDEX
    Grid Y, X
    Tree View ITEM

    Each occurrence of index-1 modifies one property. The first occurrence modifies the first property in the list presented in the preceding table. The second occurrence modifies the second property. For example, the statement fragment 

    INQUIRE grid-1(2, 3)

    Would have the effect of setting the grid property Y to 2 and X to 3. Supplying more index values than the control supports has no additional effect. You may omit trailing indexes; this leaves the corresponding properties unchanged. This feature can be used to simplify inquiry on specific elements of controls that hold multiple values. For example, you can retrieve the contents of row 2, column 3 in a grid with the statement: 

    INQUIRE grid-1(2, 3), CELL-DATA IN data-1

    This is exactly equivalent to the more cumbersome: 

    MODIFY grid-1, Y = 2, X = 3
INQUIRE grid-1, CELL-DATA IN data-1
  4. When the runtime is storing data items, the rules for the MOVE statement are applied. The source for the title is alphanumeric. The type of control determines the source format of the value. The source format for a property is either numeric or alphanumeric depending on the specific property.
  5. When used with an ActiveX control or COM object, INQUIRE gets the value of a property or gets the style flags.
  6. When the PROPERTY phrase is used to set an ActiveX control or COM object, the runtime automatically converts parameters to the appropriate styles.
  7. When the LENGTH option is specified, length-1 gives you the exact number of characters that were placed by the control in value or property-value. This option is useful in determining how long the logical data is in value or property-value, or if there are trailing spaces. If, for example, you inquired the SELECTION-TEXT property in an entry-field and specified the LENGTH option, you could tell if the user's selection contains trailing spaces. If you do not use the LENGTH option, your program will not distinguish between the trailing spaces in the selection and the trailing spaces added by the runtime.
  8. The SYSTEM HANDLE phrase retrieves the host graphical system's handle that corresponds to the control and stores this value in system-handle. This value is the way the host graphical system identifies the control. You usually need it if you want to affect the control from some other language such as C. There is no use for the host system's handle if you are using only ACUCOBOL-GT; the handle is useful only when you need to have another language interact with an ACUCOBOL-GT screen.
  9. Each host system defines its own technique for identifying graphical components. Under Windows, the Windows API uses the HWND type, which is a 32-bit unsigned value. You can use UNSIGNED-INT as an appropriate USAGE type for system-handle to cover these two cases portably.
  10. If the control does not have a corresponding host handle, then system-handle is set to zero. This indicates that either the host system does not have an underlying graphical system, or that the particular control does not use the host's notion of a control in its implementation.
  11. The POP-UP MENU option returns the handle of the pop-up menu associated with the control in menu-1. If the control has no pop-up menu, menu-1 is set to NULL.
  12. The LINE NUMBER IN and COLUMN NUMBER IN phrases return the location of the control in line-num and col-num respectively. The SIZE IN and LINES IN phrases return the dimensions of the control in width and height respectively. These values have the same meaning and units that they have in a DISPLAY or MODIFY statement.
    Note: In order for the LINES IN and SIZE IN phrases to return a value, the control must have been created with its LINE and SIZE dimensions specified. Then the value returned is in the units used to create the control. If the control was not given dimensions when it was created, the INQUIRE statement has no effect.
  13. The MAX-HEIGHT, MAX-WIDTH, MIN-HEIGHT, and MIN-WIDTH phrases return the value of the control's current maximum and minimum size restrictions in max-height, max-width, min-height, and min-width, respectively. These values have the same meaning and units that they have in a DISPLAY or MODIFY statement.
  14. The ID IN phrase returns the control's ID if it has one. If it does not (or the control does not exist), id is set to zero.
  15. The CLASS IN phrase returns the type of the control (label, entry field, etc). This is coded as a unique number for each class. The appropriate values can be found in the COPY library controls.def.
  16. The LAYOUT-DATA IN phrase sets layout-data to the current value of the control's LAYOUT-DATA property.
  17. The ENABLED IN phrase sets enabled-state to 1 if the control is enabled and 0 if the control is disabled.
  18. The VISIBLE IN phrase sets visible-state to 1 if the control is visible and 0 if it is invisible.
  19. You cannot use named parameters to avoid entering required parameters. You can omit optional parameters only.
  20. You must specify only unnamed parameters before the BY NAME clause, and only named parameters after the BY NAME clause.
  21. You can use one- and two-dimensional COBOL tables as property and method parameters for use in COM SAFEARRAYs. The runtime automatically converts the table to an COM SAFEARRAY, as long as it contains only one elementary item that is USAGE HANDLE or USAGE HANDLE OF VARIANT. See Properties Styles and Methods in A Guide to Interoperating with ACUCOBOL-GT.
  22. Use the AS type-num phrase in the parameter expression if you want to force the parameter to be converted to a particular VARIANT type before it is passed to a property or method of an ActiveX control or COM object. You can tell from the object's documentation and the name of the parameter whether the object expects a particular VARIANT type, such as boolean.

    Use the AS phrase if the ActiveX or COM object requires a method or property parameter to be something different from the default VARIANT type chosen by the runtime for the particular COBOL data item or literal. Specify the word AS followed by a numeric literal or level 78 numeric constant that indicates the variant type to which you want the parameter converted. The activex.def COPY file in the ACUCOBOL-GT sample/def directory contains predefined level 78 constants for each of the VARIANT types. See Properties Styles and Methods in A Guide to Interoperating with ACUCOBOL-GT for the rules that the runtime uses to determine the VARIANT type.

Format 2 General Rules

  1. The INQUIRE WINDOW statement returns one or more attributes of the window identified by window-handle or generic-handle. If the WINDOW phrase is used and generic-handle is omitted, information is retrieved from the current window.
  2. The LINE NUMBER and COLUMN NUMBER phrases return the position of the window relative to the interior of its parent. For the initial window, this will always be line 1, column 1. Note that the position returned can be negative, or larger than the parent window, indicating that the window's upper left corner is outside of its parent's interior.
  3. The TITLE phrase returns the title of the current window.
  4. The SCREEN LINE and SCREEN COLUMN phrases return the position of the window on the screen. This is an absolute position, not relative to any other window. The position is expressed in the screen's base units, with 1, 1 being the upper left corner of the screen. Screen base units are machine dependent. Under character systems, the base unit is a character cell, for graphical systems, the base unit is a pixel. A negative value indicates that the window's home location (the upper left corner) is off the screen.
  5. The SIZE and LINES phrases return the window's width and height, respectively.
  6. The SYSTEM HANDLE phrase retrieves the host graphical system's handle that corresponds to the window and stores this value in system-handle. This value is the way the host graphical system identifies the window. You usually need it if you want to affect the window from some other language such as C. There is no use for the host system's handle if you are using only ACUCOBOL-GT; the handle is useful only when you need to have another language interact with an ACUCOBOL-GT screen.
  7. Each host system defines its own technique for identifying graphical components. Under Windows, the Windows API uses the HWND type, which is a 32-bit unsigned value. You can use UNSIGNED-INT as an appropriate USAGE type for system-handle to cover these two cases portably.
  8. If the window does not have a corresponding host handle, then system-handle is set to zero. This indicates that either the host system does not have an underlying graphical system, or that the particular window does not use the host's notion of a control in its implementation.
  9. The LAYOUT-MANAGER phrase sets layout-manager to the handle of the layout manager currently attached to the window.
  10. The VISIBLE option returns in visible-state whether the window is visible or invisible. visible-state is set to 1 if the window is visible, or 0 if it is invisible.
    Note: A visible window may actually be hidden behind other windows on the screen, and thus may not actually be viewable by the user.
  11. The POP-UP MENU option returns the handle of the pop-up menu associated with the window in menu-1. If the window has no pop-up menu, menu-1 is set to NULL.
Parent topic: Procedure Division Statements