Class: cDataDictionary¶

Include: Use Db\cDataDictionary.pkg

Standard Data Dictionary class for entity-backed records, local record buffers, validation, related DDOs, constraints, and adapter-backed save/delete/find operations.

Hierarchy¶

cObject
- cEntity
  - cBaseDataDictionary
    - cDataDictionary

Package: Db\cDataDictionary.pkg

Description¶

cDataDictionary extends cBaseDataDictionary, which extends cEntity. cBaseDataDictionary supplies the adapter, buffer, constraints, create, DEO, delete, entity helper, field event, find, message, metadata, operation, query, relation, save, shared configuration, sync, lookup, and validation behavior used by Data Dictionary Objects.

cDataDictionary adds the standard required-field, find-required, capslock, checkbox value, field-access, label/status-help, and validation hooks on top of those base DD mixins.

Entity attachment¶

{ 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
    End_Procedure
End_Class

New TechStack code should prefer entity handles and RefTable(Self.FieldName) over file-number or FD-file references.

Local buffers and operations¶

Field_Current_Value reads and writes the local buffer. Field_Changed_Value writes a value through changed-field rules, and Field_Changed_State reports or sets the changed flag. HasRecord reports whether the DD holds a found or saved record, CurrentRowId returns the active row id, and BufferChanged reports whether any field is changed. PushBuffer and PopBuffer save and restore DDO structure buffer state. Use FindByField, FindByIndex, or FindByRowId to navigate records, Request_Save to create or update records, and Request_Delete to delete the current record.

Set DDO_Server connects parent Data Dictionaries. Constrain_File limits a child DD to the active parent record. OnConstrain defines reusable subclass constraints, and RebuildConstraints or RebuildAllConstraints rebuilds active constraints. With pbAutoFill=True, a constrained child DD loads a matching child when the parent changes; pbAutoFillFromFirst chooses first versus last matching child.

Member summary¶

Member topics:

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.

Examples¶

Data Dictionary subclass¶

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

Save and find¶

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

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