Data Dictionaries¶

cDataDictionary is the standard application Data Dictionary base class for TechStack entity-backed records. A Data Dictionary attaches an entity to local record buffers, field rules, related Data Dictionary objects, validation, and adapter-backed database operations.

What cDataDictionary provides¶

cDataDictionary extends cBaseDataDictionary. cBaseDataDictionary extends cEntity and composes the adapter, buffer, constraints, create, DEO, delete, entity helpers, field events, finds, message, metadata, operation, query, relations, save, shared config, sync, lookup, and validations mixins.

cDataDictionary adds the standard field-option and validation mixins for required fields, find-required fields, capslock, checkbox values, field access options, labels/status help, and standard validation hooks.

Data Dictionaries own local entity buffers for find, edit, save, and delete operations. They do not expose a shared global File.Field table buffer model.

Related concepts:

Entities define entity metadata.
Connections configure connection manager and adapter lookup.
Data Binding migrates UI Entry_Item bindings to Data Dictionary object buffers.
Validations explains validation events, built-in field options, and reusable custom validators.
cDataDictionary provides the class reference subtopic.

Defining a Data Dictionary class¶

A Data Dictionary class subclasses cDataDictionary, attaches entity metadata, and configures field rules in Construct_Object.

Use Db\cDataDictionary.pkg
Use Database\OrderEntryModel.pkg

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

        Set phEntity to (RefEntity(Customer))

        Set Field_Option (RefTable(Self.Name)) DD_Required to True
        Set Field_Option (RefTable(Self.State)) DD_Capslock to True
        Set Field_Checkbox_Values (RefTable(Self.Status)) to "Y" "N"
        Set Field_Label_Long (RefTable(Self.Status)) to "Active Status"
        Set Field_Label_Short (RefTable(Self.Status)) to "Status"
        Set Field_Status_Help (RefTable(Self.Status)) to "Active Inactive Status of customer"
    End_Procedure
End_Class

{ Entity=Customer } documents the entity relationship. Set phEntity to (RefEntity(Customer)) attaches the runtime entity metadata.

Inside a Data Dictionary class, use RefTable(Self.FieldName) for field options and metadata. Prefer this over file-number or FD-file style references.

Compatibility names such as Main_File may appear when porting older code, but new TechStack code should prefer entity references and phEntity.

Local record buffers¶

Field_Current_Value reads or writes the current local buffer without automatically marking the field changed.

Field_Changed_Value writes a value and marks the field changed unless access options such as DD_NoPut or committed-field rules block the changed state.

Field_Changed_State reports or sets whether a field is in the changed-field list.

HasRecord reports whether the Data Dictionary currently represents a found or saved record. CurrentRowId and GetRowID return the current row id.

BufferChanged reports whether any field is changed. ParentsChanged and Parent_Changed_State report parent-switch state.

PushBuffer and PopBuffer save and restore the full DDO structure buffer state, including children, parents, current row ids, and changed-state flags.

Send Clear of oCustomerDD

Set Field_Current_Value of oCustomerDD (RefTable(oCustomerDD.Name)) to "Access Miles"
Set Field_Changed_Value of oCustomerDD (RefTable(oCustomerDD.City)) to "Miami"

Get Field_Current_Value of oCustomerDD (RefTable(oCustomerDD.Name)) to sName
Get Field_Changed_State of oCustomerDD (RefTable(oCustomerDD.City)) to bChanged

Calculated display fields can be written to the local buffer without marking them as user edits.

Get Field_Current_Value (RefTable(Self.Qty_Ordered)) to iQty
Get Field_Current_Value (RefTable(Self.Price)) to nAmount
Set Field_Current_Value (RefTable(Self.Extended_Price)) to (nAmount * iQty)

Field options, labels, and checkbox values¶

Set and read field options through field references.

Set Field_Option (RefTable(Self.Name)) DD_Required to True
Get Field_Option of oCustomerDD (RefTable(oCustomerDD.Name)) DD_Required to vValue
Get Field_Option_Boolean of oCustomerDD (RefTable(oCustomerDD.Name)) DD_Required to bRequired
Set Foreign_Field_Option of oCustomerDD DD_KEYFIELD DD_FindReq to True
Get Foreign_Field_Option_Boolean of oCustomerDD DD_KEYFIELD DD_FindReq to bFindReq
Get File_Field_Effective_Option of oOrderHeaderDD oCustomerDD (RefTable(oCustomerDD.Customer_Number)) DD_NoPut to bNoPut

Option	Behavior
`DD_Required`	Adds required-field validation.
`DD_FindReq`	Requires a related parent record before save for relation fields or matching foreign-field categories.
`DD_Capslock`	Uppercases values when written to the Data Dictionary buffer.
`DD_NoEnter`	Marks the field as no-enter for DEO/UI access.
`DD_NoPut`	Prevents the field from being marked changed by `Field_Changed_Value`.
`DD_DisplayOnly`	Applies both `DD_NoEnter` and `DD_NoPut`.
`DD_Commit`	Makes a field committed once `IsCommitted` is true; committed fields can block changed-state marking.

Foreign-field options apply by category.

Category	Applies to
`DD_KEYFIELD`	Primary-key fields.
`DD_INDEXFIELD`	Indexed fields that are not primary keys.
`DD_DEFAULT`	Non-indexed, non-primary-key fields.

Labels, status help, and checkbox values are field metadata.

Set Field_Label_Short (RefTable(Self.Status)) to "Status"
Set Field_Label_Long (RefTable(Self.Status)) to "Active Status"
Set Field_Status_Help (RefTable(Self.Status)) to "Active Inactive Status of customer"
Set Field_Checkbox_Values (RefTable(Self.Status)) to "Y" "N"
Get Field_CheckBox_Value of oCustomerDD (RefTable(oCustomerDD.Status)) True to sValue

Validations and custom validators¶

Request_Validate, Request_Validate_All, and Validate_Field run Data Dictionary validation. FieldError hField eErrNr sErrText raises field-specific validation errors.

Built-in options such as DD_Required, DD_FindReq, and DD_Capslock are event-driven field option behaviors.

For custom reusable validators and event API details, see Validations.

Finding records¶

Clear and find operations work against the Data Dictionary's local buffer.

Send Clear of oCustomerDD
Send Clear_All of oCustomerDD
Send Find of oCustomerDD GT 3
Send FindByField of oCustomerDD EQ (RefTable(oCustomerDD.Name))
Send FindByIndex of oCustomerDD GT 3
Send FindByRowId of oCustomerDD rRowId
Get FindByRowIdEx of oCustomerDD rRowId to bFound
Set Ordering of oCustomerDD to 3
Get Field_Index of oCustomerDD (RefTable(oCustomerDD.Name)) to iIndex

Find delegates to FindByIndex. FindByField finds by a field's preferred index. FindByRowId clears the Data Dictionary when passed a null row id.

Failed next/greater finds leave the last buffer values in place while Found is false.

Send Clear of oCustomerDD
Set Field_Current_Value of oCustomerDD (RefTable(oCustomerDD.Name)) to "Access Miles"
Send FindByField of oCustomerDD EQ (RefTable(oCustomerDD.Name))

If (Found) Begin
    Get CurrentRowId of oCustomerDD to rCustomer
End

Saving, deleting, and creating storage¶

Request_Save is the main save entry point. It updates foreign keys from active parent DDs and then calls SaveRecord.

SaveRecord creates a record when HasRecord is false and updates the current record when HasRecord is true.

Should_Save is true when the Data Dictionary or parent state has changes.

pbReadOnly=True blocks Request_Save, Request_Delete, and ZeroFile. Read_Only_State is a compatibility property for the same setting.

pbNoDelete=True blocks Request_Delete. No_Delete_State is a compatibility setter for the same setting.

Can_Delete is true only when an entity is attached and the Data Dictionary is not read-only and not no-delete.

Request_Delete deletes the current record. DeleteRecord is the lower-level delete path used by cascade delete and enforces pbReadOnly.

pbCascadeDelete defaults to True and allows parent deletes to delete related children when the relation permits cascade delete.

CreateDatabase bParents bChildren bOverwrite asks the adapter to create storage for the current DD, optionally including parent and/or child DDOs. ExistsInDb bParents bChildren checks whether the selected tables exist.

Send Clear of oCustomerDD
Set Field_Changed_Value of oCustomerDD (RefTable(oCustomerDD.Name)) to "Access Miles"
Set Field_Changed_Value of oCustomerDD (RefTable(oCustomerDD.City)) to "Miami"
Send Request_Save of oCustomerDD

Set Field_Changed_Value of oCustomerDD (RefTable(oCustomerDD.City)) to "Jacksonville"
Send Request_Save of oCustomerDD

Send FindByField of oCustomerDD EQ (RefTable(oCustomerDD.Name))
If (Found) Begin
    Send Request_Delete of oCustomerDD
End

DD operations participate in Begin_Transaction / End_Transaction. If an error occurs before the transaction completes, DD changes in that transaction are rolled back.

A DDO structure connects parent and child Data Dictionary objects.

Object oCustomer_DD is a cCustomerDataDictionary
End_Object

Object oSalesPerson_DD is a cSalesPersonDataDictionary
End_Object

Object oOrderHeader_DD is a cOrderHeaderDataDictionary
    Set DDO_Server to oCustomer_DD
    Set DDO_Server to oSalesPerson_DD
End_Object

Object oOrderDetail_DD is a cOrderDetailDataDictionary
    Set DDO_Server to oOrderHeader_DD
    Set DDO_Server to oInventory_DD
    Set Constrain_File to (RefTable(oOrderHeader_DD))
End_Object

Set DDO_Server registers a parent Data Dictionary and requires a relation to that parent entity to exist.

If Set DDO_Server is used for a parent entity with no defined relation, it raises DFERR_PROGRAM with No relation defined for server '<name>'.

Data_Set finds a Data Dictionary for an entity anywhere in the DDO structure. Which_Data_Set resolves applicable server paths. Both return C_UnresolvedObject when no suitable DDO exists.

Traversal methods include Parents, ParentsAll, ParentsAllDepthFirst, ParentsAllButConstrained, Children, ChildrenAllDepthFirst, AllDDOsChildrenBreathFirst, and AllDDOsBottomUp.

Relation option APIs include CascadeDeleteAllowed, CascadeDeleteNull, ParentNullAllowed, and ParentNoSwitchIfCommitted.

AllowParentFind reports whether a parent DD can switch records when committed child records exist.

Constraints and auto-fill¶

Constraints limit the rows visible to a Data Dictionary.

Set Constrain_File of oOrderDetail_DD to (RefTable(oOrderHeader_DD))
Set Constrain_File of oOrderDetail_DD to C_UnresolvedObject
Send RebuildConstraints of oOrderDetail_DD
Send RebuildAllConstraints of oOrderDetail_DD
Constrain oCustomerDD.Balance gt 30000
Constrain Self.Name contains "Corp"
Set pbAutoFill of oOrderDetail_DD to True
Set pbAutoFillFromFirst of oOrderDetail_DD to False

Constrain_File limits a child DD to the active parent record for that parent entity.

Clearing Constrain_File removes that parent limit. Resetting it and rebuilding constraints restores the limit.

OnConstrain is the Data Dictionary event where subclasses define reusable constraints.

Object oCustomer_DD is a cCustomerDataDictionary
    Procedure OnConstrain
        Constrain Self.Name contains "Corp"
    End_Procedure
End_Object

Send RebuildConstraints of oCustomer_DD

With pbAutoFill=True, a constrained child DD loads a matching child record when the parent changes. pbAutoFillFromFirst chooses first versus last matching child.

Data binding and DEO refresh¶

Entry_Item oCustomer_DD.Name binds a data-aware object to the Name field in oCustomer_DD's local buffer.

Set Server to oCustomer_DD connects a view/container to the main Data Dictionary server.

Bound DEO objects use Data_File and Data_Field to resolve the DD field and read Field_Current_Value during refresh.

Successful finds call NotifyDEORefresh, which refreshes attached DEOs through Add_User_Interface / Remove_User_Interface.

Set Server to oCustomer_DD

Object oCustomer_Name is a cWebForm
    Entry_Item oCustomer_DD.Name
    Set psLabel to "Name"
End_Object

For UI migration examples, see Data Binding.

Method and event reference¶

Setup and metadata¶

Symbol	Purpose
`phEntity`	Runtime entity metadata attached to the DD.
`Main_File`	Compatibility entity/file accessor used by older DD code.
`FieldAttribute`	Reads field metadata attributes.
`FieldDefinition`	Returns field definition data.
`FieldName`	Returns a field's display/source name.
`FieldType`	Returns a field's data type.
`TableAttribute`	Reads table metadata attributes.
`TableDbName`	Returns the database table name.
`TableLogicalName`	Returns the logical table name.
`TableFieldCount`	Returns the field count.
`TableDefinition`	Returns table definition data.
`TablePrimaryKeyFields`	Returns primary-key fields.
`IsPrimaryKeyField`	Reports whether a field is in the primary key.
`IsFieldIndexed`	Reports whether a field participates in an index.

Buffers¶

Symbol	Purpose
`Field_Current_Value`	Reads or writes a local buffer field.
`Field_Current_Value_Mid`	Reads or writes a substring of a local buffer field.
`Field_Changed_Value`	Writes a field and marks it changed when allowed.
`Field_Changed_State`	Reads or sets the changed flag for a field.
`Buffer`	Provides direct buffer access for the DD.
`BufferChanged`	Reports whether any local field is changed.
`HasRecord`	Reports whether the DD currently has a found or saved record.
`CurrentRowId`	Returns the current row id.
`GetRowID`	Returns the current row id.
`PushBuffer`	Saves the DDO structure buffer state.
`PopBuffer`	Restores the DDO structure buffer state.
`UpdateAllFields`	Copies current buffer values through field update logic.
`ParentsChanged`	Reports parent-switch state.
`Parent_Changed_State`	Reads or sets parent changed state.

Finds¶

Symbol	Purpose
`Clear`	Clears the DD's local buffer.
`ClearForTable`	Clears buffer state for a table/entity path.
`Clear_Main_File`	Compatibility clear entry point.
`Clear_All`	Clears the DDO structure.
`Find`	Finds using current ordering.
`FindByField`	Finds through a field's preferred index.
`FindByIndex`	Finds through an explicit index.
`FindByRowId`	Finds by row id or clears for a null row id.
`FindByRowIdEx`	Finds by row id and returns success.
`FindByRowIdExNoAutoFill`	Finds by row id without auto-fill.
`Ordering`	Gets or sets find ordering.
`Field_Index`	Returns a field's preferred index.
`File_Field_Index`	Compatibility field-index lookup.

Save/delete/storage¶

Symbol	Purpose
`Request_Save`	Validates and saves through the DD.
`SaveRecord`	Creates or updates the current record.
`CreateRecord`	Creates a new database record.
`UpdateRecord`	Updates the current database record.
`Should_Save`	Reports whether DD or parent changes need saving.
`Should_Save_Row`	Reports whether one row should save.
`UpdateForeignKeys`	Copies active parent keys into child foreign keys.
`Request_Delete`	Deletes the current record through the DD.
`DeleteRecord`	Lower-level delete path.
`ZeroFile`	Clears records from the selected storage.
`Can_Delete`	Reports whether delete is allowed.
`CreateDatabase`	Creates selected database storage.
`ExistsInDb`	Checks whether selected storage exists.
`pbReadOnly`	Blocks save, delete, and zero-file operations.
`Read_Only_State`	Compatibility property for read-only state.
`pbNoDelete`	Blocks request-delete operations.
`No_Delete_State`	Compatibility setter for no-delete state.
`pbCascadeDelete`	Enables allowed cascade deletes.

Options and labels¶

Symbol	Purpose
`Field_Option`	Sets or gets a field option.
`Field_Option_Boolean`	Gets a field option as a Boolean.
`Foreign_Field_Option`	Sets or gets an option by foreign-field category.
`Foreign_Field_Option_Boolean`	Gets a foreign-field option as a Boolean.
`ForeignFieldCategory`	Resolves a field's foreign-field category.
`File_Field_Effective_Option`	Resolves effective field options across DD paths.
`File_Field_Committed_Option`	Resolves committed-field option state.
`Field_Label_Short`	Sets or gets a short field label.
`Field_Label_Long`	Sets or gets a long field label.
`Field_Label`	Resolves the field label.
`Field_Status_Help`	Sets or gets field status help.
`Field_CheckBox_Values`	Sets true/false checkbox stored values.
`Field_CheckBox_Value`	Gets the stored checkbox value for a Boolean state.

Validation events¶

Symbol	Purpose
`Request_Validate`	Validates the DD and required parent path.
`Request_Validate_All`	Collects validation across the DDO structure.
`Validate_Field`	Validates one field.
`FieldError`	Raises a validation error for a field.
`Extended_Error_File`	Returns extended error file/entity information.
`Extended_Error_Field`	Returns extended error field information.
`Extended_Error_Message`	Returns extended error text.
`Current_Validate_Field`	Returns the field currently being validated.
`OnValidate_Add`	Adds a DD-level validation handler.
`OnValidate_Del`	Removes a DD-level validation handler.
`OnValidate_Has`	Reports whether a DD-level validation handler is registered.
`OnFieldValidate_Add`	Adds a field validation handler.
`OnFieldValidate_Del`	Removes a field validation handler.
`OnFieldValidate_Has`	Reports whether a field validation handler is registered.
`OnForeignFieldValidate_Add`	Adds a foreign-field validation handler.
`OnForeignFieldValidate_Del`	Removes a foreign-field validation handler.
`OnForeignFieldValidate_Has`	Reports whether a foreign-field validation handler is registered.

Relations and constraints¶

Symbol	Purpose
`DDO_Server`	Registers a parent Data Dictionary.
`DefineRelation`	Defines relation metadata for DD behavior.
`Parents`	Returns direct parent DDs.
`ParentsAll`	Returns all parent DDs.
`ParentsAllDepthFirst`	Returns all parent DDs depth-first.
`ParentsAllButConstrained`	Returns parent DDs except the constrained parent.
`Children`	Returns direct child DDs.
`ChildrenAllDepthFirst`	Returns all child DDs depth-first.
`AllDDOsChildrenBreathFirst`	Returns child DDOs breadth-first.
`AllDDOsBottomUp`	Returns DDOs bottom-up.
`Data_Set`	Finds a DD for an entity in the DDO structure.
`Which_Data_Set`	Resolves applicable server paths.
`Data_Set_Server_Count`	Returns server count.
`Data_Set_Server`	Returns a server by index.
`Constrain_File`	Limits a child DD to an active parent.
`ActiveConstraints`	Returns active constraint state.
`Add_Value_Constraint`	Adds a value constraint.
`Add_Field_Value_Constraint`	Adds a field-value constraint.
`Add_Relates_To_Constraint`	Adds a relation constraint.
`RebuildConstraints`	Rebuilds constraints for one DD.
`RebuildAllConstraints`	Rebuilds constraints for a DDO structure.
`OnConstrain`	Event for reusable subclass constraints.
`CascadeDeleteAllowed`	Reports whether relation cascade delete is allowed.
`CascadeDeleteNull`	Reports whether cascade delete can null the relation.
`ParentNullAllowed`	Reports whether a null parent is allowed.
`ParentNoSwitchIfCommitted`	Reports committed child parent-switch behavior.
`AllowParentFind`	Reports whether a parent DD can switch records.

DEO, adapter, and operation helpers¶

Symbol	Purpose
`Add_User_Interface`	Attaches a DEO to DD refresh notifications.
`Remove_User_Interface`	Detaches a DEO from DD refresh notifications.
`phoAdapter`	Stores the current adapter object.
`Adapter`	Returns the active adapter.
`pbUpdateDEOs`	Enables DEO refresh updates.
`pbReportReentrancyErrors`	Enables operation reentrancy error reporting.
`CurrentOperationMode`	Returns the current operation mode.
`CurrentOrigin`	Returns the current operation origin.
`RootOperationMode`	Returns the root operation mode.
`OperationName`	Returns a display name for an operation mode.

Checklist¶

Define the entity first.
Create a cDataDictionary subclass for the entity.
Set phEntity in Construct_Object.
Configure labels, options, validators, and checkbox values with RefTable(Self.FieldName).
Connect parent dictionaries with Set DDO_Server.
Set Constrain_File when a child should follow an active parent record.
Bind UI controls with Entry_Item oDataDictionary.FieldName.
Use Field_Changed_Value plus Request_Save for edits.
Use FindByField, FindByIndex, or FindByRowId for record navigation.
Use Request_Validate before saving when code needs an explicit validation check.