MODIFY Statement

The MODIFY verb is used to change the characteristics of an existing screen control item or window. It acts on control handles, elementary Screen Section control items, and window handles.

Format 1

MODIFY {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]

SIZE    {IS} length  [CELL  ]
        {= }         [CELLS ]
                     [PIXEL ]
                     [PIXELS]

LINES   {IS} height  [CELL  ]
        {= }         [CELLS ]
                     [PIXEL ]
                     [PIXELS]

CSIZE   {IS} clength  [CELL ]
        {= }          [CELLS]

CLINES  {IS} cheight  [CELL ]
        {= }          [CELLS]

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

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

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

MIN-WIDTH  {IS} min-width
           {= }
TITLE {IS} title
      {= }

{COLOR } IS color-val
{COLOUR}

{FOREGROUND-COLOR } IS fg-color
{FOREGROUND-COLOUR}

{BACKGROUND-COLOR } IS bg-color
{BACKGROUND-COLOUR}

{HIGHLIGHT}
{HIGH     }
{BOLD     }
{LOWLIGHT }
{LOW      }
{STANDARD }

{BACKGROUND-HIGH}
{BACKGROUND-LOW}
{BACKGROUND-STANDARD}

STYLE {IS} style-flags
      {= }

{ [NOT] style-name } ...

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

LAYOUT-DATA {IS} layout-data
            {= }
FONT  {IS} font-handle
      {= }

ENABLED  {IS} {TRUE         }
         {= } {FALSE        }
              {enabled-state}

VISIBLE  {IS} {TRUE         }
         {= } {FALSE        }
              {visible-state}

POP-UP MENU {IS} {menu-1}
            {= } {NULL  }

EVENT-LIST    {IS} ( event-value { event-value ... } )
              {= }

AX-EVENT-LIST {IS} ( ax-event-value { ax-event-value ... } )
              {= }

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

EVENT PROCEDURE IS { proc-1 [ {THROUGH} proc-2 ] }
                              {THRU   }
                   { NULL                        }

{ property-name          } {IS } { prop-option 
                                     [GIVING result-1] }...
{ PROPERTY property-type } {ARE} 
{ method-name            } {=  } 
{ object-expression      }

prop-option is one of the following:

{ property-value [ LENGTH {IS} length-1 ] }
{                         {= }            }
{                                         )
{ ( {property-value} ... )                }
{                                         }
{ { MULTIPLE } property-table             }
{ { TABLE    }                            }
{                                         }
{ parameter-expression                  }
{                                         }
{ ( { parameter-expression } ... )      }

parameter-expression is one of the following:

{ parameter                               } [ AS type-num ]
{                                         }
{ {BY} NAME parameter-name {IS} parameter }
{                          {= }           }
{ parameter-name {IS} parameter           }
{                {= }                     }

object-expression has the following format:

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

Format 2

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

Remaining phrases are optional, can appear in any order.

AT screen-loc

LINE NUMBER line-num

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

SCREEN LINE NUMBER screen-line

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

SIZE width

LINES height

TITLE title

ON EXCEPTION statement-1

NOT ON EXCEPTION statement-2

VISIBLE  {IS} {TRUE         }
         {= } {FALSE        }
              {visible-state}

POP-UP MENU {IS} {menu-1}
            {= } {NULL  }

ENABLED  {IS} {TRUE         }
         {= } {FALSE        }
              {enabled-state}

EVENT PROCEDURE IS { proc-1 [ {THROUGH} proc-2 ] }
                              {THRU   }
                   { NULL                        }

ACTION  {IS} action
        {= }

END-MODIFY

Syntax Rules

control-item is a USAGE HANDLE data item or elementary Screen Section item that describes a control.
index-1 is a numeric expression. The parentheses surrounding index-1 are required.
window-handle is a USAGE HANDLE OF WINDOW or PIC X(10) data item.
generic-handle is a USAGE HANDLE, HANDLE OF WINDOW or PIC X(10) data item.
screen-loc is an integer data item or literal that contains exactly 4, 6, or 8 digits, or a group item of 4, 6, or 8 characters.
line-num, col-num, cline-num, ccol-num, length, height, width, clength, and cheight are numeric data items or literals. They can be non-integer values, except when pixels are specified.
screen-line and screen-col are numeric expressions. They should be integer values.
If the CELLS option is used with either the SIZE or CSIZE phrase, then it must be present in both phrases if both are specified. The same is true for use of the CELLS option in the LINES and CLINES phrases.
max-height, max-width, min-height, and min-width are numeric data items, literals, or expressions.
color-val is an integer data item or literal.
fg-color and bg-color are integer literals or numeric data items. They may be arithmetic expressions. See FOREGROUND-COLOR and BACKGROUND-COLOR Phrases for a more detailed discussion of color settings and values.
If you use the AT phrase, you may not use the LINE, COLUMN, SCREEN LINE, or SCREEN COLUMN phrases.
The SCREEN LINE and SCREEN COLUMN phrases must be used together. If used, the AT, LINE, and COLUMN phrases may not be used.
If the COLOR phrase is specified, neither the FOREGROUND-COLOR nor the BACKGROUND-COLOR phrase may be specified.
style-flags is a numeric expression.
style-name is the name of a style associated with the class of control being described. The style-name phrase adds the named style to the control. If control-handle refers to a generic handle, or if the CONTROL phrase is used, you may not use the style-name phrase. Use the STYLE phrase instead. If the NOT option is used with the style-name phrase, the named style is removed from the control instead. When a style is added, any conflicting styles are removed first. For example, if you add the FRAMED style to a button, then the UNFRAMED style is removed first.
value is a literal or data item. If the MULTIPLE option is specified, then value must be a one-dimensional table. In this case, value is not subscripted.
length-1 is a numeric literal or data item. The LENGTH phrase may be specified only if the value or property-value immediately preceding it is an alphanumeric literal or data item, and not a figurative constant. In addition, the MULTIPLE option may not be specified along with the LENGTH phrase.
title is an alphanumeric literal or data item.
layout-data is an integer literal, data item, or expression.
font-handle is a USAGE HANDLE data item that identifies a font.
enabled-state and visible-state are integer numeric literals or data items.
menu-1 is a USAGE HANDLE or HANDLE OF MENU data item.
event-value and ax-event-value are numeric literals or data items that identify an event type. List elements must be enclosed by parentheses. Elements must be separated by a space. If the list contains a single element, the parentheses can be omitted.
list-state is an integer literal or numeric data item. Valid values are 0 and 1.
proc-1 and proc-2 are procedure names.
You must allow recursive paragraphs in order to specify the EVENT PROCEDURE phrase. Compiling for recursive paragraphs is allowed by default, but you can turn it off if you use the -Zr0 option.
property-name is the name of a property specific to the type of control being referenced. If the type of control is unknown to the compiler (as in a DISPLAY OBJECT object-1 statement), then property-name may not be used. You must use the PROPERTY property-type option instead.
property-type is a numeric literal or data item. It identifies the property to modify. The numeric values that identify the various control properties can be found in the COPY library controls.def.
method-name is the name of method specific to the type of ActiveX control or COM object being referenced. If the type of the control or object is unknown to the compiler, then method-name cannot be used. You must use the PROPERTY property-type option instead.
property-value is a literal or data item. In the Procedure Division, property-value may also be a numeric expression (however, only the first property-value in a phrase may be an expression, subsequent values must be literals or data items). Note that the parentheses are required.
property-table is a data item that appears in a one-dimensional table. No index should be specified.
result-1 is a numeric data item.
In parameter-expression:
1. parameter is a literal, data-item, or numeric expression used when invoking methods or setting properties of an ActiveX control or COM object.
2. type-num is a numeric data item or numeric literal.
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.
statement-1 and statement-2 are imperative statements.
action is a numeric literal or a data item.

Format 1 General Rules

A Format 1 MODIFY statement updates an existing control or invokes a method on an ActiveX control, COM object, or .NET control (also known as an assembly). control-item should contain a handle returned by a DISPLAY control-Type statement, or the name of an elementary Screen Section control item. If control-item does not refer to a valid control, the MODIFY statement has no effect. Note that controls referenced in the Screen Section are not valid until they have been created via a DISPLAY statement. If control-item refers to a valid control, the effect of the statement is to update the specified properties of the control and to redisplay it.

If index-1 is specified, then certain properties in the control being modified are changed to match the value of index-1. This occurs before any modification occurs. The exact set of properties changed by the index-1 depends on the control's type. Currently, two controls have properties that are changed in this way:

Control Type	Properties Affected
List Box	QUERY-INDEX
Grid	Y, X

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

MODIFY grid-1(2, 3), color is red

would have the effect of setting the grid property Y to 2 and X to 3 before changing the cell color to red. 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 modification of specific elements of controls that hold multiple values. For example, you can modify the contents of row 2, column 3 in a grid with the statement:

MODIFY grid-1(2, 3), CELL-DATA = data-1

This is exactly equivalent to the more cumbersome:

MODIFY grid-1, Y = 2, X = 3
MODIFY grid-1, CELL-DATA = data-1

The meaning of each of the phrases is the same as for a Format 14 DISPLAY statement. Note that you can move a control by changing its row or column property.
MODIFY simply locates the corresponding control and makes the specified modifications. This process does not examine any phrases specified in the Screen Section.
This capability is particularly convenient when you want to make one or two changes to a Screen Section control. For example, if you want to add an item to a list box, you can simply modify the list box specifying the item-to-add property. For example:
```
* Screen Section
01  list-box-1, list-box, value list-item, line 5,
       column 15, size 20, lines 6.

* Procedure Division
modify list-box-1, item-to-add = new-list-item.
```
By using the MODIFY verb, you do not need to specify an item-to-add property in the Screen Section, and thus you do not need to closely manage the item-to-add variable.
If the CONTROL phrase is used, the runtime modifies 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 maintains a list of controls in each window. When attempting to modify a control at a specific location, the runtime searches this list, using the first control it finds that exactly matches the location. The list is maintained in the order in which the controls are created. If the runtime does not find a control at the specified location, then the statement has no effect.
Note that you cannot move a control with a MODIFY statement if it includes the CONTROL phrase. This is due to the fact that the AT, LINE, and COLUMN phrases are used to find the control instead of specifying its new position. To move a control, you must use the control-handle phrase instead. Also note that when you use the CONTROL phrase, the compiler does not know the type of control being modified. This means that the compiler will not recognize any control-type specific style and property names. If you need to specify these, you will need to use their numeric equivalents found in the controls.def COPY library.
The following example creates an anonymous list box and adds two items to it. Note the use of the PROPERTY phrase in the MODIFY statement: the compiler does not know that the control is a list box so it does not recognize the list-box specific property names. As a result, the generic PROPERTY phrase is used in the example, specifying the level 78 data name that corresponds to the ITEM-TO-ADD property (found in controls.def).
```
COPY "controls.def".

DISPLAY LIST-BOX, LINE 5, COL 30, LINES 5.
MODIFY CONTROL, LINE 5, COL 30, 
   PROPERTY LBP-ITEM-TO-ADD = 
            ( "Item 1", "Item 2" ).
```
The style-name phrase adds the named style to the control. If the NOT option is used with the style-name phrase, the named style is removed from the control instead. When a style is added, any conflicting styles are removed first. For example, if you add the FRAMED style to a button, then the UNFRAMED style is removed first.
When the LENGTH option is specified, length-1 establishes the exact size of the value or property-value. The text value presented to the control may have no trailing spaces or may have trailing spaces added. When you specify the LENGTH option, the control uses exactly length-1 characters of data with or without trailing spaces. However, when length-1 is a value larger than the size of the data item it is modifying, then the size of the data item is used instead. If length-1 is negative, it is ignored and the default handling occurs.
The POP-UP MENU option changes the pop-up menu for the control. If menu-1 is specified, then the corresponding menu becomes the new pop-up menu. If NULL is specified, any existing pop-up menu is removed (but not destroyed).
The EVENT PROCEDURE phrase adds, changes, or removes a control's event procedure. Specifying NULL removes any event procedure. Otherwise, proc-1 (through proc-2, if specified) becomes the control's new event procedure.
When properties return specific values, these values are placed in result-1 of the GIVING phrase. If the property does not have a pre-defined return value, result-1 is set to 1 if the property is set successfully, otherwise, result-1 is set to 0. When a property is being given multiple values in a single assignment, as shown here,
```
DISPLAY COLUMNS = ( 1, 10, 30 )
```
then result-1 is set in response to the last value assigned. In the example above, result-1 is set to 30. Because the meaning of each value depends on the property being set, you should consult the documentation on the specific property for the exact meaning.
You can also change the properties of most controls described in the Screen Section with a Format 2 DISPLAY statement. You must use MODIFY to change special properties of an ActiveX or .NET control.
To invoke (call) a method, you use the MODIFY verb in much the same way as you set a property or style. Note that unlike common properties and styles, you cannot use the DISPLAY statement to invoke an ActiveX method specified in the Screen Section. You must use the MODIFY verb. ActiveX methods can take any number of parameters or no parameters. They can also take optional parameters (i.e., parameters that can be omitted). You specify the parameters in COBOL by enclosing them in parentheses. The optional parameters are always last. To invoke a method with no parameters, use empty parentheses ().
Each property or method name can be followed by '::' and then another property or method name to invoke methods in-line. MethodName1::MethodName2 means invoke the method "MethodName1" of the current object and set the current object to the return value. When a property or method name is followed by a token other than '::', then it means to actually invoke the method on the current object passing the specified arguments or set the property to the specified value and reset the current object to null.
The MODIFY verb takes a control's home position (upper left corner), its handle, the name of an elementary Screen Section item, or '^', as its first parameter. Only the properties of the control that are specified in the MODIFY statement are updated.
The runtime automatically converts parameters to the appropriate types.
If a method has a return value, the runtime converts and moves it to the item specified in the GIVING clause.
You cannot use named parameters to avoid entering required parameters. You can omit optional parameters only.
You must specify only unnamed parameters before the BY NAME clause, and only named parameters after the BY NAME clause.
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.
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.

Format 2 (MODIFY WINDOW)

A Format 2 MODIFY statement changes one or more attributes of an existing FLOATING or INITIAL WINDOW (not a subwindow). Attributes that are not specifically changed remain unchanged, except when a window is made larger, in which case it may also be repositioned in order to keep it on the screen. window-handle or generic-handle identify the window to modify. If the WINDOW phrase is used and generic-handle is omitted, the current window is modified.
The LINE and COLUMN phrases specify the location of the window on the screen. The coordinates are relative to the interior space of the parent window. If the window being modified is the initial window, the coordinates are relative to its own interior. If either phrase is omitted, the corresponding row or column position is unchanged.
The AT phrase specifies both the row and column position. The first two or three digits of screen-loc, depending on the size of screen-loc, specify the row position. The remaining digits specify the column position. The values are treated in the same manner as in the LINE and COLUMN phrases. If either half of screen-loc is zero, the corresponding coordinate remains unchanged.
The SCREEN LINE and SCREEN COLUMN phrases set the location of the window. The coordinates indicate the absolute position desired on the screen. screen-line and screen-col are given in the screen's base units. Base units are machine dependent. For character systems, the base unit is a character cell. For graphical systems, the base unit is a pixel. The upper left corner of the screen is position 1,1. The SCREEN LINE and SCREEN COLUMN phrases cannot be used if the LINE, COLUMN, or AT phrases are used.
The SIZE and LINES phrases change the size of the window. The dimensions indicate the interior of the window. The requested size must fit on the screen. If it does not, the size is not changed. After resizing the window, the runtime ensures that the window is fully visible on the screen. Resizing a window that has the RESIZABLE property will not change the window's physical dimensions if that window is not maximized. Note that only the window's logical dimensions are changed (thus increasing the scrolling region). The user will see the new size only if he or she later maximizes the window.
The TITLE phrase specifies a new title for the window. For this phrase to have an effect, the window must have a title area.
statement-1 executes if any part of the operation fails. An exception may be caused by one of the following situations:
- The specified window size does not fit the screen. Note that this error occurs only on a non-Windows host. Because Windows allows you to have a desktop that is larger than the physical screen, you do not get an exception in this instance on Windows. You should use ACCEPT FROM TERMINAL-INFO to determine the maximum physical window size on a Windows host.
- The window cannot be created, either because of an out-of-memory situation or the operating system fails to create it.
- A window that has no input is activated.
- An external window error occurs. For example, the window does not exist or cannot be created for some reason.
- An illegal instruction is used.
statement-2 executes if the MODIFY statement succeeds.
The VISIBLE option makes a window visible or invisible. If the TRUE phrase is used, or visible-state is non-zero, then the window is made visible. Otherwise, it is made invisible.
The POP-UP MENU option changes the pop-up menu for the window. If menu-1 is specified, then the corresponding menu becomes the new pop-up menu. If NULL is specified, any existing pop-up menu is removed (but not destroyed).
The Format 2 ENABLED phrase can be used to disable or enable a window. A user cannot interact with a disabled window.
The Format 2 EVENT PROCEDURE phrase changes the window's event procedure to proc-1 (through proc-2, if specified). If the NULL option is used, then the window's event procedure, if any, is removed from the window. Additional information can be found in the DISPLAY Statement above and in PROCEDURE Clause.

The ACTION phrase allows you to programmatically maximize, minimize, or restore a window. To use ACTION, assign it one of the following values (these names are found in acugui.def):

ACTION-MAXIMIZE	maximizes the window. It has the same effect as if the user clicked the maximize button. Allowed only for windows that have RESIZABLE or AUTO-RESIZE specified or implied for them.
ACTION-MINIMIZE	minimizes the window. Allowed only with INDEPENDENT windows that have the AUTO-MINIMIZE property set to true. It is not supported with other types of floating windows; if set, it is ignored by the runtime. ACTION-MINIMIZE has the same effect as if the user clicked the minimize button.
ACTION-RESTORE	If the window is currently maximized or minimized, restores the window to its previous size and position; otherwise, it has no effect. Allowed only for windows that can be maximized or minimized.

If you assign an ACTION value that is not allowed, then there is no effect other than to trigger the ON EXCEPTION phrase of the MODIFY statement (if present). Note that you can use the ACTION phrase to create a window that is initially maximized or minimized.