8.4.1 DEFINE_COM Parameters
CLASS is the type of the component, for example command button, check box, form etc.
For fields, the class can be a simple field such as #SALARY or any of its visualizations such as #SALARY.VISUAL or #SALARY.MYPART.
*VARIANT allows the use of a variant variable. You can read or write values from a variant variable. It has no properties. At the moment a better alternative is to use a 8.25.3 Variant Variable.
The Options parameter can have a keyword LIST_ENTRIES with value *COMPUTE or *MAX. For example:
OPTIONS(*LIST_ENTRIES *MAX)
The *List_Entries keyword specifies the number of entries a list-type component can have. List type components are:
Grid
ListView
TreeView
ComboBox
ListBox
Memo
Graph
Property Sheet
The number of entries allowed depends on whether the list contains RDMLX fields and if the list is in a component that is enabled for Full RDMLX.
*COMPUTE sets the maximum number of entries required based on the fields in the list. If the list contains only RDML fields, the number of entries is restricted to RDML levels( limited to 32767 entries). If the list contains RDMLX fields, the list is treated as a Full RDMLX list which can have a much higher platform-dependent maximum number of entries.
*MAX sets the limit of entries to the maximum allowed by the containing component. Independent of whether the fields in the list are RDMLX or not, if the list is in an RDML component, it will be limited to RDML list entries but if it is a Full RDMLX component, it will be an RDMLX list
NAME is the unique name of this instance of a component.
The SCOPE parameter can be used to create component instances that are shared between different instances of owner components by specifying *SHARED as the value. When *SHARED is specified in the DEFINE_COM, only one single shared instance of a member component is created regardless of how many instances of the owner component are created.
*SHARED can only be used in DEFINE_COM commands that are placed directly after the BEGIN_COM statement of the component.
When the value of the SCOPE parameter is *DEFAULT, the scope of the DEFINE_COM command is determined by its position. If it is placed immediately after the BEGIN_COM statement, the scope is interpreted as *INSTANCE. If the DEFINE_COM command is located after an event, method or property routine, the scope is interpreted as *LOCAL.
A scope of *INSTANCE causes a new instance of a member component to be created whenever a new instance of its owner component is created. This value can only be specified in DEFINE_COM commands that immediately follow the BEGIN_COM statement.
A scope of *LOCAL causes a new local instance of a component to be created every time an event, method or property routine is executed. This value can only be specified in DEFINE_COM commands that immediately follow the event, method or property routine.
All *APPLICATION variables are identified by variable name. Therefore, two different component classes can share a component instance simply by including a DEFINE_COM for the variable name and specifying a scope of *APPLICATION.
The first reference to an *APPLICATION scoped variable that is not *DYNAMIC will cause the component instance to be created. All other accesses retrieve that instance.
When a component instance at scope *APPLICATION is retrieved, the only checking performed is to ensure that the class of the component instance can be dynamically cast to the class specified on the variable's DEFINE_COM.
*APPLICATION variables are released when the application terminates. Care must be taken to ensure that the component classes used by an instance of a component at *APPLICATION scope are fully understood. All the component DLL's required to implement these component classes will remain in memory for the lifetime of the component instance and this could correspond to the lifetime of the application.
The REFERENCE parameter is used to define how the reference to the component being defined is resolved. The reference is created to the object defined by the CLASS parameter and assigned to the variable defined by the NAME parameter in the DEFINE_COM statement.
By assigning references, you can use system resources economically because you can control when a reference to an object is created and released and thus free memory locations as they are no longer required. Also, when you are using external components and applications via ActiveX you will need to set references at run time.
*DEFAULT indicates that the default reference determined by the *SCOPE parameter is used.
*STATIC indicates that when the DEFINE_COM statement is encountered during execution, a reference is created to the component defined by the CLASS parameter and the reference is assigned to the variable defined by the NAME parameter. The CLASS parameter must define a concrete class. This is the default when SCOPE is *INSTANCE (except for forms) or *LOCAL.
*DEFERRED indicates that when the DEFINE_COM statement is encountered during execution, the component reference is set to *NULL. Then when the component used in the code, a reference is created to the component defined by the CLASS parameter and the reference is assigned to the variable defined by the NAME parameter. This means that if the code that uses this component is not executed, no reference is created. The CLASS parameter must define a concrete class. This is the default for forms which have a SCOPE of *INSTANCE.
*DYNAMIC indicates that when the DEFINE_COM statement is encountered during execution, the component reference is set to *NULL and no reference to a component is created automatically. You must use a SET_REF command to assign a reference to the component defined by the CLASS parameter and to assign the reference to the variable defined by the NAME parameter.
RDMLX Functions can use the DEFINE_COM command. For functions that are running as *HEAVYUSAGE, the state of referenced components is retained between invocations. If the state is not to be retained, use components that are *DYNAMIC.
Note:Any property you change for this instance of the component is shown in the DEFINE_COM statement. Default values for properties are not shown.
Use the DESC parameter to write a brief description for this instance of the component. It can be 40 characters long.
The setting of the OPTIONS parameter in the DEFINE_EVT command automatically set the value of the OPTIONS parameters for the EVTROUTINE command handling the event.
Use the HELP parameter to write a longer description for this instance of the component. The help text can be viewed using the Features option of the Help menu. It can be 250 characters long.