The Field_Option properties are used to set a number of options for any field. These options determine a variety of attributes including finding behaviors (e.g., Auto-Find, Find-Required), data entry behaviors (e.g., Capslock, No-Enter) and update behaviors (e.g., No-Put, Force-Put). These options are defined with various “DD_” constants and are listed below.
The options below shown with an asterisk (*) are finding options, and may be used only on indexed fields. The other options may be used with any field.
DD_AutoFind * |
|
DD_AutoFind_GE * |
|
DD_Commit |
|
DD_DisplayOnly |
|
DD_FindReq * |
|
DD_ForcePut |
|
DD_NoEnter |
|
DD_NoPut |
|
see DD_Remember |
|
DD_Retain (obsolete) |
|
DD_RetainAll (obsolete) |
|
DD_Required |
|
DD_SkipFound |
|
DD_CapsLock |
|
DD_Zero_Suppress |
For example, you could define that a field should be No-Put, Auto-Find and Capslock by setting the following properties:
Set Field_Option field Customer.Id DD_NoPut to True
Set Field_Option field Customer.Id DD_AutoFind to True
Set Field_Option field Customer.Id DD_CapsLock to True
Field_Options can be set and changed at the DD object level. See Changing Field Properties within a DD Object for more information.
Set Field_Option field Customer.State DD_Retain to True
Set Field_Option field Customer.State DD_Retain to False
Set Field_Option field Customer.State DD_Retain to bOpt
Get Field_Option field Customer.State DD_Retain to (not(bOpt))
Set Field_Option field Customer.Id DD_AutoFind to True
DD_AutoFind executes an automatic find eq (equals) by the Main Index of the field when the user navigates out of a data-entry form for the field. This option will not work on a field that does not have a main index.
If a record is found whose value in the main index of the field exactly matches the values in the data-entry form and any other items whose fields participate in the index, it is displayed to the screen. If no such record is found, the cursor exits the form normally and no record is moved into the buffer. No error will be declared.
You would usually set this option on every key field in your database.
Where you wish to find by a non-unique index, use Auto-Find GE.
Where you are auto finding by a multi-segment index, place the DD_AutoFind option on the last field that participates in the index.
If used together with Find-Required, Auto-find will require users to enter a valid existing key before continuing.
Set Field_Option field Customer.Id DD_AutoFind_GE to True
DD_AutoFind_GE performs a find ge (greater than or equal to) by the main index of the field when the user navigates out of a data-entry form for the field. This option will not work on a field that does not have a main index. If a record is found whose value in the main index of the field exactly matches the values in the field’s data-entry form and any other forms whose fields participate in the index, it is displayed to the screen. If no such record is found, the record whose index value next follows that in the form(s) is displayed.
Auto-Find GE is useful for finding records on partial entries to items or, in multi-segment indexes, by keys for only the first segment or segments (rather than all of them). All non-unique indexes, for example, are multi-segment (being composed of at least one field plus a record ID field).
You may use Auto-Find GE with any indexed field regardless of whether the field’s main index is unique or non-unique.
If you are using Auto-Find GE by a multi-segment index, place the DD_AutoFind_GE option on the last field in the index for which you wish to use an entered key value. If any field that comes before the one with the DD_AutoFind_GE option on it in the index lacks an entered key value in its form, the value of that field will be considered empty for purposes of the find. The found record will be the one whose value for the first such field is the lowest in the index.
If you want to execute an automatic find eq (equals) command for an exact match with the entered data, use the Auto-Find option instead (above).
Auto-Find GE will always find a record, unless the table has no records in it.
Set Field_Option field Customer.Id DD_Commit to True
A record goes through two states, not committed and committed, which may require different data entry behaviors. By default a record that is new is not committed and a record that is saved is committed. This can be altered to use some other kind of indicator, but new and old will work in many cases. When a record is new, you should pretty much be able to change anything. Once a record is saved, there may be parts of the record that you no longer want to be changed. For example, once an order is saved, you may not want users to be able to edit the "Order Date". In addition, once an order is saved, you may not want to be able to switch the parent customer. For the sake of argument let's say that once saved, you cannot switch the customer but you can switch the sales-person. Actually the order entry system always had this rule, but it required custom complicated DEO code to enforce it. The concept of a committed option allows this to be modeled at the DD class or object level. This allows you to treat this as a modeled DD business rule.
Set ParentNoSwitchIfCommitted File.File_Number to True
This is set in the main DD and determines if a parent record can be switched, once it is committed.
Function IsCommitted Returns Boolean
The framework calls this to determine if a record is committed. It returns true if the record is committed. By default, it is true if the record is saved. This can be augmented to change the definition of committed for a record. This can be augmented but will often require no changes.
Note that committed behavior is only applied if the record is committed (IsCommitted is True) and either a field is marked as committed (DD_COMMIT) or ParentNoSwitchIfCommitted is true.
Consider the following DD:
Object OrderHea_DD is a OrderHea_DataDictionary
Set DDO_Server to Customer_DD
Set DDO_Server to SalesP_DD
// If committed order, don't allow customer to be changed (would normally be set in the dd class)
Set ParentNoSwitchIfCommitted Customer.File_Number to True
// Once committed, we don't want to be able to change ordered by (would normally be set in the dd class)
Set Field_Option Field OrderHea.Ordered_By DD_COMMIT to True
End_Object
This would disallow switching customers after the order is saved and disallow changing the value of Ordered-by once saved.
The DEOs intelligently support DD_Commit. We want to enable and disable controls based on their edit-ability. This changes dynamically as the commitment state of the record changes. If the record is new, you can select a customer and add an ordered-by value. Once saved, those DEOs will be NoPut and possibly NoEnter. The NoEnter part of this is complex, as making a DEO NoEnter makes it impossible to use that field for finding new records. For example, if Order_Date in the Order sample workspace, which has an index, were made a committed field, you'd not be able to find orders by date if it were NoEnter. The DEOs are smart enough to recognize this case, and they make indexed fields NoPut and non-indexed fields NoPut and NoEnter.
In addition, there is a similar issue with allowing finds to switch parents. You'd normally think that you'd want to make a no-switch parent NoEnter so you cannot change a switched record. Most of the time this is correct. However, if the no-switch parent has a relates-to constraint to the child, you want to allow the parent to be changed. In this case, changing the parent doesn't do a switch; it refinds the child records for the new parent. The DEOs handle this automatically and they just do the right thing.
Set Field_Option field Customer.Id DD_DisplayOnly to True
DD_DisplayOnly causes the cursor to skip the data-entry form associated with this field and prevents any data in the form from being changed. The form will display the field data as disabled.
DD_DisplayOnly is the equivalent of a combination of the DD_NoEnter and DD_NoPut options
// This is the same as DD_DisplayOnly
Set Field_Option field Customer.Id DD_NoPut to True
Set Field_Option field Customer.Id DD_NoEnter to True
Setting DD_NoPut or DD_DisplayOnly blocks data import (e.g. pasting), so DD_NoEnter is usually preferred.
Set Field_Option field Customer.Id DD_FindReq to True
DD_FindReq prevents the cursor from going to the next data-entry form until a successful find on the form connected to this field places an active record in the view. An unsuccessful find causes Error DFERR_ENTER_VALID_REC_ID (90) - Please enter a valid record ID.
Find required has no effect if an active record for the field’s table is already in the view.
You would normally apply Find Required only as a foreign-field option in a parent table to ensure that a related parent record is found before a save occurs in the child.
An Auto-Find option on the field with a Find Required will attempt the required find automatically when a user attempts to move the cursor out of the form. If the automatic find is successful, the cursor will proceed. If it is not, Error DFERR_ENTER_VALID_REC_ID, Please enter a valid record ID, is declared.
A Find Required with an Auto-Find GE is unnecessary. Auto Find GE always finds a record in a non-empty database file.
This find required validation is also applied during a save.
Set Field_Option field Customer.Id DD_ForcePut to True
DD_ForcePut forces the contents of data-entry forms connected to the field to be put to the table’s record buffer before a save even if no changes were made to the form.
Normally the contents of a data-entry form are put to the buffer only if they have been changed from what was originally displayed from the disk
Set Field_Option field Customer.Id DD_NoEnter to True
DD_NoEnter prevents data entry through any form associated with the field.
The Skip-Found option (DD_SkipFound) has a similar effect, except that it allows the cursor to go to the item only if no record is found. No-Enter skips the form regardless of whether a record is found.
The DD_DisplayOnly option is a combination of DD_NoEnter and DD_NoPut.
Although data cannot be entered from the keyboard to a form controlled by No-Enter, data can still be moved to the form under program control. Such data changes will be moved to the record buffer and saved, unlike with the Display-Only or No-Put field options.
Set Field_Option field Customer.Id DD_NoPut to True
DD_NoPut stops data being moved from the data-entry form back to the record buffer for the field, even if new data is entered from the keyboard. No-Put is useful for allowing data to be entered into a form for finding, where you do not wish to allow the field to be changed.
Use the No-Put field option when you want to prevent users from changing data.
The DD_DisplayOnly option is a combination of DD_NoEnter and DD_NoPut.
Set Field_Option field Customer.Id DD_Required to True
DD_Required ensures that data is entered into a field.
Any character or characters entered in the data-entry form will allow the cursor to move on to the next form.
This required validation is also applied during a save.
Set Field_Option field Customer.Id DD_CapsLock to True
DD_CapsLock automatically converts any lower-case characters entered into a data-entry form associated with the field, to upper case (capital letters). It has no effect on non-alphabetic characters. This assures that all input to the field through data-entry forms will be saved with letters in upper case.
Set Field_Option field Customer.Id DD_Zero_Suppress to True
DD_Zero_Suppress blanks the display of the field’s data-entry form if it is a numeric field with value of zero (0).
DD_Zero_Suppress will appear not to work where a small absolute value is put to a form. For example, if a form specifies integer-only display and a field value less than 1 is put to it (say, 0.5), a zero will display in the form. Only a value that is truly zero will be displayed as blanks.
This field option is considered obsolete, use DD_Remember instead.
Set Field_Option field Customer.Id DD_Retain to True
DD_Retain prevents data-entry forms associated with the field from clearing when the user initiates an operation that would normally clear all the forms in a view.
If the user initiates a clear-all operation, then even retained data-entry forms will be cleared.
The choice to retain or not retain a value is not something that can usually be applied to all objects in all views using a particular DD class. Instead retains should be applied based on the data entry requirements of a particular view. Therefore, it is really expected that Retain will be applied at the DD object level and not as part of the class definition.
This field option is considered obsolete, use DD_Remember instead.
Set Field_Option field Customer.Id DD_RetainAll to True
DD_RetainAll prevents data-entry forms associated with the field from ever being cleared.
Even though users cannot clear the data-entry form by pressing the Clear key, they still may erase it manually (character-by-character).
The choice to retain or not retain a value is not something that can usually be applied to all objects in all views using a particular DD class. Instead retains should be applied based on the data entry requirements of a particular view. Therefore, it is really expected that Retain will be applied at the DD object level and not as part of the class definition.
The DD_Commit and DD_Skipfound field options can, in some cases, provide similar functionality. Normally, using DD_Commit is a better choice as it is more flexible.
Set Field_Option field Customer.Id DD_SkipFound to True
DD_SkipFound prevents data entry to the field’s data-entry form if the buffer for the table has an active record in it.
DD_NoEnter is a similar field option. However, it skips the form in all cases, regardless of whether an active record is in the buffer.
Defining Data Dictionary Field Attributes