Commonly Used Data Dictionary Object Properties and Functions

When working with Data Dictionary objects, you will actually use a small set of DD properties and functions. These methods allow you to check the status of a DDO (is it changed, does it have a record) and enable you to get and set DDO field values. The most commonly used methods are:

• HasRecord
• Should_Save
• CurrentRowId
• Field_Current_Value
• Field_Changed_Value

HasRecord

Get HasRecord of hoDDO to bHasRecord

HasRecord is used to determine if your DDO has a current record. This can be used to determine if a find operation succeeded (if HasRecord is true), or if the DDO buffer did not contain a record prior to the find operation (otherwise, check the Found indicator).

It can also be used to determine if a save will result in a new record save (if HasRecord is false) or an edit of an existing record (if HasRecord is true).

Procedure Refresh integer iMode
    Boolean bHasRecord
    Handle hoDD
    Forward Send Refresh iMode
    // if record exists, enable the print button.
    Get Server to hoDD
    Get HasRecord of hoDD to bHasRecord
    Set Enabled_State of oPrintBtn to bHasRecord
End_Procedure  // Refresh

Should_Save

Get Should_Save of hoDDO to bChanged

Should_Save can be used to determine if a DDO has changed. If Should_Save is true, the DDO structure has changed and a save may be needed. Should_Save checks the changed state of a DDO and its parent DDOs. It also checks to see if a parent record has been switched.

There is no set variant of this message. Should_Save is set indirectly through data-input or by other messages such as Set File_Field_Changed_Value, Find, Clear, Request_Save, etc.

Get Should_Save of hoDDO to bChanged
If bChanged begin
    Get Request_Validate of hoDDO to bError
    If (not(bError)) begin
        Send Request_Save of hoDDO
    End
End

By evaluating Should_Save and HasRecord, you can determine the major states of any DDO:

	HasRecord=True	HasRecord=False
Should_Save=True	A changed record exists. A save will edit the existing record.	A new changed record. A save will create a new record.
Should_Save=False	An unchanged record exists. A save is not needed.	A new unchanged record. A save is not needed.

CurrentRowId

Get CurrentRowId of hoDDO to riRec

CurrentRowId returns the RowId of the current record. If there is no current record (HasRecord=false), CurrentRowId will be null. This is often used to store the value of a current record so that it can be re-found at a later time.

Procedure RunUpdate
    RowId riCust
    // remember the original record
    Get CurrentRowId of oCustomer_DD to riCust
    // this may change the current record
    Send ProcessAllCustomers
    // re-find the original record
    Send FindByRowId of oCustomer_DD Customer.File_Number riCust
End_Procedure

Field_Current_Value

Get Field_Current_Value of hoDD Field Customer.Name to sName
Set Field_Current_Value of hoDD Field Customer.Name to sName
Get File_Field_Current_Value of hoDD File_Field Customer.Name to sName
Set File_Field_Current_Value of hoDD File_Field Customer.Name to sName

These messages are used to retrieve and change a field’s value. Get Field_Current_Value is used to retrieve the current value of a field. This message is used frequently.

You will note that many of the samples use the file buffer to directly obtain the value of a field (e.g., Move Customer.Name to sName). This is discussed in detail in Understanding File Buffers and DDO Field Buffers.

There are two variants of the message, “Field” and “File_Field”. This is discussed in Understanding the File_Field and Field Keywords.

The set version of this message is used to change the current value of a field. You change the value of a DDO field in preparation for a save. When you change a field’s value, you must also change its changed-state. This can be done with the Field_Changed_State message.

Set Field_Current_Value of hoDD Field Customer.Name to sName
Set Field_Changed_State of hoDD Field Customer.Name to True

The message File_Field_Changed_Value performs both of these operations and is usually used for this purpose. Therefore, the Set File_Field_Current_Value message is rarely used.

Important

If a save operation is not changing the value of a changed field, check if you are using Field_Current_Value instead of Field_Changed_Value. This is a common mistake.

Field_Changed_Value

Set Field_Changed_Value of hoDD Field Customer.Name to sName
Set File_Field_Changed_Value of hoDD File_Field Customer.Name to sName

This message is used to change the current value of a field and to set the field’s changed state to true. This is a commonly used message and is the suggested method for changing DDO field values in preparation for a save. This message is only used for changing values. There is no get version of this message.

Function ChangeName RowId riRecId string sName returns Boolean
    Boolean bErr
    Send Clear of oUser_DD
    Send FindByRowId of oUser_DD User.File_Number riRecId
    If (Found) Begin
        // update name and save
        Set Field_Changed_Value of oUser_DD field User.Name to sName
        Get Request_Validate of oUser_DD to bErr
        If (not(bErr)) begin
            Send Request_Save of oUser_DD
            // if save succeeds, Err indicator is False
            Move (Err) to bErr
        End
    End
    Else Begin
        Move True to bErr
    End
    Function_Return bErr
End_Function

You will note that many of the samples use the file buffer to directly set the value of a field (e.g., Move sName to Customer.Name). This is discussed in detail in Understanding File Buffers and DDO Field Buffers.

There are two variants of the message, “Field” and “File_Field”. This is discussed in Understanding the File_Field and Field Keywords.