Entities¶

An entity is the code-defined DataFlex TechStack description of a persistent table: its name, connection, fields, indexes, relations, and metadata.

Before: filelists, FD files, and global buffers¶

In Windows DataFlex, FILELIST.CFG is the table registry. Each entry links the DataFlex table name, filelist number, user-display name, and physical file name.

FD files give the compiler the table and field constants it needs to translate Table.Column names into the table and field numbers used at runtime.

Opening a table creates one global file buffer for that table. File.Field syntax reads from and writes to that one shared record buffer.

Windows DDO field buffers provide local Data Dictionary Object field state, but they exist around the global file buffer model. The file buffer remains the shared table-level record buffer.

Now: entities in code¶

DataFlex TechStack entities replace the filelist and FD files for TechStack data models. The Entity ... End_Entity block contains table metadata in source code.

Entity-level brace attributes can define metadata for the table, including a connection name such as { Connection="OrderData" }. Field declarations inside the entity define the table fields and their DataFlex data types.

Field-level brace attributes define field metadata. Common examples include { PrimaryKey=On }, { AutoIncrement=On }, { Type=NVARCHAR, Length=100 }, and { DefaultIndex=1 }.

Add_Index defines index segments and their direction, ASC or DESC. Add { Unique=On } before an index when the index must be unique.

Add_Relation LocalField to ParentEntity.ParentField defines relationships. Multi-segment relations use and ; continuation.

The following compact example shows the entity metadata in context with the Data Dictionary that uses it:

{ Connection="OrderData" }
Entity Customer
    {
        PrimaryKey=On
        AutoIncrement=On
    }
    Integer Customer_Number
    { DefaultIndex=1 }
    String Name
    { Type=NVARCHAR, Length=100 }
    String Address

    { Unique=On }
    Add_Index Customer_Number ASC
    { Unique=On }
    Add_Index Name ASC Customer_Number DESC
End_Entity

{ Entity=Customer }
Class cCustomerDataDictionary is a cDataDictionary
    Procedure Construct_Object
        Forward Send Construct_Object

        Set phEntity to (RefEntity(Customer))
        Set Field_Label_Long (RefTable(Self.Customer_Number)) to "Customer Number"
        Set Field_Option (RefTable(Self.Name)) DD_REQUIRED to True
    End_Procedure
End_Class

• The entity declares the persistent model: connection, fields, indexes, relations, and metadata.
• The Data Dictionary owns a local record buffer for that entity model.
• Field metadata references use the entity field, such as RefTable(Self.Customer_Number), instead of FD-file numeric constants.

Multi-segment relations use the same source-defined model:

Add_Relation iField1 to TestEntity.iField1 and ;
             sField2 to TestEntity.sField2

Entities and Data Dictionaries¶

A cDataDictionary subclass is attached to an entity with { Entity=Name } and Set phEntity to (RefEntity(Name)), as shown above.

Data Dictionaries own the local entity buffer used for find, edit, save, and delete operations. The TechStack does not expose a shared global File.Field buffer model; field reads and writes should go through Data Dictionary APIs and field references.

For UI and column Entry_Item migration from File.Field to oDataDictionary.Field, see Data Binding.

For the runtime metadata APIs exposed by entity objects, see cEntity.

Inside a Data Dictionary, use RefTable(Self.FieldName) for field metadata and options:

Set Field_Label_Long (RefTable(Self.Customer_Number)) to "Customer Number"
Set Field_Option (RefTable(Self.Name)) DD_REQUIRED to True

Compatibility method names such as Main_File may appear when porting older code, but file numbers are not the primary TechStack data model. Prefer entity and field references in new TechStack code.

Why the model changed¶

Data definitions now live in source code instead of a sidecar filelist plus generated FD files. Entity definitions are versionable, reviewable, and deploy with the application source.

Removing global buffers avoids hidden shared mutable record state. Multiple Data Dictionary instances can hold independent local record buffers for the same entity.

Connections, indexes, relations, and field metadata stay close to the code that uses them, which makes data model changes easier to review and deploy with the application.

For how the connection manager maps those logical names to drivers and connection URIs, see Connections.

Migration map¶