PROPERTY and Property-Name Phrases

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

where prop-option is one of the following:

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

The PROPERTY phrase assigns a value to one of a control's special properties or invokes a control-specific method. The PROPERTY phrase takes the types of only special properties and methods for controls. See The Components of a Control for more information. See Methods for more information about methods. Each type of control has its own set of special properties and methods. These are described in the help topics for each control type. property-value specifies which special property to modify or which method to invoke (each of a control's special properties and methods is uniquely identified by a number). property-value is the value to assign to that special property. property-value must be a data type that is appropriate for the specified property. If property-type specifies a special property that does not exist, it is ignored for most control types. If the control type is ACTIVE-X, then an exception is raised.Each property's unique value is defined in the file controls.def or in the ActiveX control's COPY file. See ActiveXfor more information.
property-value and method-name provide an alternate method for identifying which special property to modify or which method to invoke. The compiler knows the names of the special properties and methods that belong to each control type. In situations where the compiler knows which type of control is being acted upon, you can use the appropriate property-name or method-name directly instead of using the special property's or method's identifying number in the PROPERTY phrase.
For example, the MAX-TEXT special property of entry fields is property number 1. You can set the value of this property to 10 with either of the following phrases:
```
PROPERTY 1 = 10
MAX-TEXT = 10
```
The second method can be used only when your code makes it clear to the compiler that you're acting on an entry field.

You can use either the PROPERTY phrase or method-name to specify which method to invoke. For example, the LoadFile method of the Microsoft Rich Textbox Control is method number 37. You can invoke this method with either of the following phrases:
```
PROPERTY 37 ("myfile.rtf", rtfRtf)
LoadFile ("myfile.rtf", rtfRtf)
```
The second method can be used only when your code makes it clear to the compiler that you're acting on a Microsoft Rich Textbox Control.
Some properties return specific values when set. These values are placed in result-1 of the GIVING phrase. The meaning of the value depends on the property being set; see the documentation for the specific property. Properties that do not have a pre-defined return value set result-1 to 1 if the property was set successfully, or "0" if not. When a property is being given multiple values in a single assignment (for example: Display-Columns = (1, 10, 30)), then result-1 is set in response to the last value assigned.
When multiple special property assignments are made in a single statement, those assignments are performed in the order listed in the statement.
If more than one property-value is specified, each one is applied to the property in the order listed. This is normally used for cumulative properties. These are properties that perform some special action each time they have a value assigned to them. For example, you can set three columns in a list box with DISPLAY-COLUMNS = (1, 20, 35 ). In the case of the DISPLAY-COLUMNS property, each time it is assigned a value, it sets a new column location. Note that the parentheses are required.
When you specify property-table, then each element of the table is assigned to the property. The elements are assigned in ascending occurrence order. For example, the following code fragment fills a list box with the names of three colors:
```
01  COLOR-NAMES.
    03  PIC X(10) VALUE "Red".
    03  PIC X(10) VALUE "Green".
    03  PIC X(10) VALUE "Blue".

01  COLOR-TABLE REDEFINES COLOR-NAMES
    OCCURS 3 TIMES
    PIC X(10).

PROCEDURE DIVISION.
MAIN-LOGIC.
    DISPLAY LIST-BOX, SIZE 10, LINES 3,
            ITEM-TO-ADD = TABLE COLOR-TABLE.
```
Note: The current size of the table is used, so you can use OCCURS DEPENDING ON tables when you want to have a variable number of items in a table.

You should use caution when specifying property tables in the Screen Section. Remember that each DISPLAY statement of a Screen Section item reloads all of that item's properties into the control. This can be inefficient if the property table is large, and it can cause duplicate entries if you are not careful. To avoid this, you can create your controls in the Screen Section, but use the MODIFY statement to set any table-oriented properties at the appropriate point in your program. In this way, the tables are not referenced in the Screen Section and a DISPLAY will not cause those tables to be reprocessed.
When the LENGTH option is specified, length-1 establishes the exact size of property-value. The text value presented to the control must not contain trailing spaces or have trailing spaces added. When you specify the LENGTH option, the control uses exactly the number of characters of length-1. However, if length-1 is a value larger than the size of the data item it is modifying, the size of the data item is used instead. If length-1 is negative, it is ignored and the default handling occurs.
{parameter}... is a list of parameters to pass when invoking one of a control's methods or setting a multiple-parameter property. When setting a multiple-parameter property, the first parameters identify which aspect of the property to set. The last parameter is the actual property value. For example, to set the Microsoft Chart Control DataGrid::RowLabel property you must specify the row number and label index. You could use the following phrase:
```
DataGrid::RowLabel( ROW-NUMBER, ROW-LABEL-INDEX, 
    "My Row Label" )
```
object-expression can only be used in the procedure division, not the screen section. It has the following format:
```
{ {^} property-1 [ ( param-1 ... ) ]
  [ :: property-2 [ ( param-2 ... ) ] ]... }
```
object-expression specifies a property or method of an object referenced by another object. This object in turn can be referenced by yet another object. The "root" object can be an ActiveX control or COM object or a graphical control. "^" can only be used in conjunction with Format 5 USE verb (see the documentation for the USE verb for more information). property-1 is the name of a property of the ActiveX control or COM object. property-1 must not be a write-only property. property-2 is the name of a property of the ActiveX control or COM object which is the value of property-1. property-2 must not be a write-only property. param-1 and param-2 are literals, data items or numeric expressions. param-1 is the first parameter passed when getting the value of property-1 and param-2 is the first parameter passed when getting the value of property-2.

For example, to set the Microsoft Chart Control legend, you get the value of the Legend property. This value is an object that you may then modify to change the legend. The Legend object has properties whose values are other objects, and so on. The following phrases set properties and invoke methods of the Microsoft Chart Legend object:
```
Legend::Location::Visible = 1
Legend::Location::LocationType = VtChLocationTypeRight
Legend::TextLayout::HorzAlignment = 
           VtHorizontalAlignmentRight
Legend::VtFont::VtColor::Set (255, 255, 0)
Legend::BackDrop::Fill::Style = VtFillStyleBrush
Legend::BackDrop::Fill::Brush::Style = VtBrushStyleSolid
Legend::BackDrop::Fill::Brush::FillColor::Set (255, 0, 255)
```
or assuming the handle to the Microsoft Chart Control is MS-CHART-1:
```
USE MS-CHART-1 Legend
      MODIFY ^Location::Visible = 1
         ^Location::LocationType = VtChLocationTypeRight
         ^TextLayout::HorzAlignment = 
               VtHorizontalAlignmentRight
         ^VtFont::VtColor::Set ( 255, 255, 0 ).
USE MS-CHART-1 Legend::BackDrop::Fill
      MODIFY ^Style = VtFillStyleBrush
         ^Brush::Style = VtBrushStyleSolid
         ^Brush::FillColor::Set ( 255, 0, 255 ).
```