DeclareData Method
The DeclareData method declares a specified active field so that you can refer to it in a dynamic expression.
This method has the following syntax:
status = ActiveField.DeclareData([result = byref(variable)]
[userclass = byref(UserClassObject)])
Each parameter has the following requirements:
• It must be named.
• If it is a table field with a control button, the control button must also be named.
• The field must be a top-level field (without named ancestors).
• It must be part of a running frame (a descendant of a running frame's form that is specified by the TopForm attribute of the running frame's FrameExec).
• It must not be already declared.
• It must be a dynamically created field or a field with a Declared attribute that was FALSE.
• The field must not have been previously declared by the DeclareData method, unless it was subsequently undeclared using the UndeclareData method.
This method has the following parameters:
result
Specifies a variable that is set to the value of the variable that was created. For example, if a table field is being declared, the result variable is set to point to the array associated with the table field. The array is the data object the DeclareData method creates.
userclass
Is valid only when declaring a composite field. There are three scenarios when declaring a composite field. When you invoke the DeclareData method:
• You can provide a UserClassObject object to construct the data object.
• If you do not provide a UserClassObject object but the field has a value in the DataType attribute (which stores the field's data type), OpenROAD obtains the data type from the scope for the field's frame and its application.
The data type must be a class (not a scalar type), for example, a user class defined for the current application.
• If the field does not contain a value in the DataType attribute and you do not provide a UserClassObject object, OpenROAD constructs a UserClassObject object from the child fields (much as it does for fields grouped into a composite field in Workbench).
To construct the attributes of a composite field's UserClassObject, OpenROAD does the following:
– If the child field has a value in the DataType attribute, OpenROAD obtains the data type from the scope for the field's frame and its application.
– If the child field does not contain a value in the DataType attribute, OpenROAD constructs a UserClassObject object from the children of the child field.
In the second and third scenarios, if you specify a userclassobject variable that contains a null, OpenROAD sets the variable to the UserClassObject object that the DeclareData method found (scenario two) or constructed (scenario three).
If the method is successful, it returns ER_OK. If it is not successful, it returns a non-zero value. Descriptions of system constant values and their numeric equivalents are listed in
Error Codes (see
Error Codes).
For a detailed discussion of using the DeclareData method, see the Programming Guide.