Skip to content

Class: cEntity

Include: Use Db\cEntity.pkg

Runtime entity instance and metadata access class for code-defined TechStack entities.

Hierarchy

Package: Db\cEntity.pkg

Description

An Entity ... End_Entity declaration defines table metadata, fields, indexes, relations, and attributes. At End_Entity, the language creates an entity class derived from cEntity with Entity_Meta set to the compiled metadata handle.

cEntity exposes that metadata through the Entity_* functions and holds an optional entity buffer value through Entity_Value and Entity_Field_Value.

Metadata model

  • Entity-level brace attributes are read with Entity_Attribute, Entity_Attributes, and Entity_Has_Attribute.
  • Field metadata is enumerated with Entity_Field_Count, Entity_Field_Type, Entity_Field_Attribute, Entity_Field_Attributes, and Entity_Field_Has_Attribute.
  • Index metadata is enumerated with Entity_Index_Count, Entity_Index_Segment_Count, Entity_Index_Segment_Field, Entity_Index_Segment_Mode, Entity_Index_Attribute, Entity_Index_Attributes, Entity_Index_Has_Attribute, and Entity_Index_Has_Field.
  • Relation metadata is enumerated with Entity_Relation_Count, Entity_Relation_Segment_Count, Entity_Relation_Segment_Local_Field, Entity_Relation_Segment_Foreign_Entity, Entity_Relation_Segment_Foreign_Field, Entity_Relation_Attribute, Entity_Relation_Attributes, and Entity_Relation_Has_Attribute.
  • Entity_StructHandle returns the runtime type handle for the entity buffer structure; Entity_Meta gets or sets the metadata handle used by a generic cEntity object.

Attribute lookup

Attribute lookup is case-insensitive; Name and name select the same metadata key.

The Name attribute is always available. If the source does not declare it, the API returns a synthesized name: entity or field name for entity and field metadata, or the stringified zero-based index or relation number for index and relation metadata.

Missing non-Name attributes return an empty string from Entity_*_Attribute and False from Entity_*_Has_Attribute.

Entity_*_Attributes returns String[][]; each row is [attributeName, attributeValue]. Returned attribute names are metadata keys and should not be used to infer original source casing.

Out-of-range field, index, index segment, relation, or relation segment arguments raise a DataFlex error.

Driver introspection

A database driver or adapter receives or uses entity handles (DbTable) and field handles (DbField) and can inspect exactly the metadata it needs before generating SQL, creating tables, binding parameters, or deciding whether it supports an attribute.

For example, an adapter can read a table-level Connection attribute with Entity_Attribute. Helper code can build a table definition from Entity_Attribute, Entity_Attributes, Entity_Field_Count, field metadata, and active relations. A SQL driver can then consume that table definition, inspect primary-key field attributes, derive table and field names, and map field types when generating SQL.

Driver-specific support is additive. If a driver does not use a metadata attribute, the attribute remains available through the API for drivers that do need it.

Examples

Entity declaration example

{ 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 ASC
End_Entity

Introspection example

A generic object can point at a compiled entity with RefEntity(Customer).

Handle hoEntity
Integer iField iFieldCount eType
String sTableName sFieldName sConnection

Get Create (RefClass(cEntity)) to hoEntity
Set Entity_Meta of hoEntity to (RefEntity(Customer))

Get Entity_Attribute of hoEntity "Name" to sTableName
Get Entity_Attribute of hoEntity "Connection" to sConnection
Get Entity_Field_Count of hoEntity to iFieldCount

For iField from 0 to (iFieldCount - 1)
    Get Entity_Field_Attribute of hoEntity iField "Name" to sFieldName
    Get Entity_Field_Type of hoEntity iField to eType
Loop

Send Destroy of hoEntity

See also