Data Function Structure DM-Datafunc-Data

4.8 Data Function Structure DM-Datafunc-Data

This structure is always passed as a parameter to data functions.

The structure is shown simplified here. The complete definition can be found in the file IDMcoboc.cob.

01 DM-Datafunc-Data.
   02 DM-df-object                  pic 9(9) binary.
   02 DM-df-task                    pic 9(9) binary.
   02 DM-df-attribute               pic 9(9) binary.
   02 DM-df-method                  pic 9(9) binary.
   02 DM-df-identifier              pic X(80).

   02 DM-df-args.
*     Is identical to the structure DM-ValueArray.

   02 DM-df-index.
*     Is identical to the structure DM-Value.

   02 DM-df-data-pointer            pointer.
   02 DM-df-retval-pointer          pointer.

Meaning of elements

DM-df-object

In this element, the object ID of the Data Model is passed to the data function.

DM-df-task

This element specifies the reason for the call. Currently the following values are possible: MT-get, MT-set and MT-call. For MT-get, the data function should return the necessary data for a Model attribute. MT-set forwards changes from the view to the data function. MT-call is used to implement data actions, i.e. calls that lead to a manifold manipulation of the data. It is reasonable to always signal changes to data via DMcob_DataChanged.

DM-df-attribute

For the call reasons MT-get and MT-set, this element contains the attribute on which the function shall be applied.

DM-df-method

For the call reason MT-call, this element contains the method that the data function shall execute. This is triggered by invoking a data action through the method :calldata(<Method>,<Arg1>,...<Arg15>).

DM-df-identifier
DM-df-indentifier-u

These elements contain the attribute identifier (from the DM-df-attribute element) or the method identifier (from the DM-df-method element) as a string to facilitate the implementation of user-defined attributes or to enable a module-independent comparison of attributes or methods.

In DM-df-indentifier-u identifiers may also be passed as National Character (PIC N) when working with Unicode texts (UTF-16).

DM-df-args

In this element, the number of arguments (DM-df-args-count) and the argument list (DM-df-valuerec) are stored for the call reason MT-call (data action invoked via :calldata()). A return or change of arguments with this is not intended respectively will have no effect.

Note

The design of this structure is identical to DM-ValueArray.

DM-df-index

This element contains the index value for the attribute access that the call reason MT-get or MT-set refers to. If the DM-df-index element has the data type DT-void, it refers to the entire value. For indexed data values, the relationship kinds and also the processing of incomplete index values (e.g. [0], [?,0] oder [0,?]) should be taken into account.

Note

The design of this structure is identical to DM-Value.

DM-df-data-pointer

For the call reason MT-set, this element contains the data value to be processed by the data function.

Note

The data is passed as value of type DT-anyvalue, since it will usually be collections. The value(s) can be retrieved with DMcob_ValueGet and the other DMcob_Value* functions.

DM-df-retval-pointer

For the call reason MT-get, in this element the data value for the specified attribute and the given index has to be returned.

Note

The return value is passed as value of type DT-anyvalue, since it will usually be collections. The return value can be changed and populated with DMcob_ValueChange.

Availability

COBOL Interface for Micro Focus Visual COBOL only.