7 114 1 SET_REF Parameters

7.114.1 SET_REF Parameters

COM

The COM parameter specifies the component or components to which the result of the reference expression specified in the TO parameter is assigned. The components specified in this parameter must have been specified with a dynamic reference in the DEFINE_COM parameter.

SET_REF *create only works with object Identifiers (i.e. short names). It cannot load objects using their Names (i.e. long names) because in runtime long names are not available.

The TO parameter derives a component reference which is assigned to the variables named in the COM parameter. The reference expression has to be in one of the following forms:

#VariableName	Assigns the reference contained in the variable name to each of the variables identified by the COM parameter. The variables must be compatible.
*NULL	Assigns a *NULL reference to all the component variables identified by the COM parameter.
*DYNAMIC #VariableName	Assigns the reference contained in the variable name to each of the variables identified by the COM parameter. No compile time checking is performed to see if the variables are compatible. At run-time, if the variable name cannot be cast to any of the variables identified by the COM parameter, an error is raised.
*CREATE_AS ClassName	Creates an instance of the component identified by the class name. The class must be defined in the LANSA repository, for instance #SALARY.Visual. Note that if you create an instance of a keyed collection you must use the parameterized version of the collection syntax: SET_REF #variable To(*Create_As #Prim-KCol<#PRIM_PHBN #STD_NUM>)
*CREATE_FROM ClassName	Creates an instance of the component identified by the class name. The class name can be either a string or a variable. The value specified must be the Identifier of the class, rather than the mixed case Name. At run-time, if the class name cannot be resolved, an error is raised.

CONTEXT

The CONTEXT parameter controls how the new component reference is assigned a context in which it can obtain memory. This parameter enables management of object pooling.

By default the memory usage of objects is managed automatically by loading/unloading of a DLL or by passing of an component from one form to another. Memory is removed when no more objects are active in the pool.

The CONTEXT parameter allows you to control the memory pooling of objects programmatically, for instance you can load related objects into their own memory area.

For example you may load a large and complex form into memory then close the form but a single component (or an instance of an object) in the form may still be active and therefore the memory is not released. The CONTEXT parameter can be used to manage that form by creating a separate pool for the remaining object so that the main memory can be released.

The CONTEXT parameter can only be used when the TO parameter is set to *CREATE_AS or *CREATE_FROM. It can have one of these values:

*DEFAULT	For primitive component classes DEFAULT is OWNER. For non-primitive component classes it is *MODULE.
*OWNER	Use the context of the instance of the component for which the routine is executing.
*MODULE	Use the context allocated to the module (DLL) that contains the routine that is executing the SET_REF command.
*NEW	Create a new context for this component.
*NAMED #Variable	The context is the component reference identified by the variable name.

COM_ERROR

The COM_ERROR parameter indicates the action to be taken when a SET_REF assignment fails. The assignment can fail because:

It is unable to find the component DLL for the name supplied for the *CREATE_FROM/*CREATE_AS options.
It is unable to cast the component to the class required by the variable supplied to the SET_REF's COM() parameter

The COM_ERROR parameter can have these values:

*ABORT	The component execution is aborted if the SET_REF assignment fails.
*IGNORE	The failed SET_REF assignment is ignored. *IGNORE does not change the value of the reference variable.
*SET_NULL	The failed SET_REF assignment is ignored. A *NULL reference is set to the variable supplied in the SET_REF's COM() parameter.