OVERVIEW.............An Overview of the Field Specification Editor
FIELD CONFIG.........Editing, Adding, Inserting a Database Field
FIELD REPLICATE......Adding a Replicated Group of Fields
FIELD MOVE...........Moving a Field
GROUP NAME...........Editing the Name and Description of a Field Group
LOAD GROUP...........Loading the Editor with a Field Group
SAVE GROUP...........Saving the Field Group to a File
GROUP IMPORT.........Importing or Exporting a Field Group
UPDATE STRUCTURE.....Updating the Structure of the Database
VALIDATION-A.........Type "A" (Auto-Fill) Field Validation
VALIDATION-C.........Type "C" (Choice) Field Validation
VALIDATION-F.........Type "F" (Calculated) Field Validation
VALIDATION-I.........Type "I" (Increment/Append) Field Validation
VALIDATION-P.........Type "P" (Program) Field Validation
VALIDATION-R.........Type "R" (Range) Field Validation
VALIDATION-T.........Type "T" (Table-Lookup) Field Validation
VALIDATION-V.........Type "V" (View/Browse) Look-Up Field Validation
VALIDATION-X.........Type "X" (Logical) Field Validation
OVERVIEW
An Overview of the Field Specification Editor
Description:
The Field Group Editor is an Editor that is used to define
and maintain the "properties" of database fields. In a
standard xBASE-language application, there are only four
(4) standard properties that can be assigned to a database
field:
Field Name
Field Type
Field Length
Field Decimals
These properties are saved in the header of the database
file so any third-party utility program can use this
database. In a custom Clipper application, it is necessary
to add more field properties to improve the look and feel
and to establish requirements for data entry. Most
applications maintain these additional properties by hard-
coding them into the application. A Data-Driven application
can maintain these additional properties by storing them in a
Data Table that is referred to as a "Data-Dictionary". In
dCLIP, the Data-Dictionary for Field Specfication definition
is referred to as the "Field Group Dictionary" and its
contents are maintained by the "Field Group Editor".
This editor is used to edit an "array" of field-group
information. The array can be loaded into the editor from
a variety of sources:
1. From the DCFIELDS.DBF Field Dictionary
2. From an Array File
3. From a Function
4. From a "capture" of the structure of an open work-area.
A field group is used to establish the default conditions
for data-entry, browsing, reports, pick-list etc. for every
"real" field in every database of an application.
The FIELD GROUP editor can be called from the Dot-Prompt
with the command FIELD EDIT, from source code with the
function DC_FIELDEDIT(), from the DATA-ENTRY EDITOR menu, from
the BROWSE EDITOR menu, or from the ASSIST menu.
The FIELD SPEC, DATA-ENTRY, and BROWSE sub-systems share the
same array structure for each database field, data-entry field
or browse-column, even though some properties are not used or
accessible by one or more of the sub-systems. The system was
designed this way to make it easier to fill-in and pass field
default information to the DATA-ENTRY or BROWSE systems, then
allow customization for each separate configuration. This kind
of design also provides for using a common Field Editing system
regardless of whether they are REAL database fields, or field
placements within a data-entry or browse configuration. This
design keeps code size at a minimum and prevents reduncancy and
ambiguity.
The following field properties are maintained by the Field
Group Editor and stored in the Field Group Dictionary:
File Alias - The Database Alias associated with this
field group.
Field Name - The 10-character name stored in the Database
header.
Field Type - The 1-character field typed stored in the
database header. (C,N,L,D,M,A,etc.)
Field Length - The Field length stored in the database header.
Field Decimals - The number of Field Decimals stored in the
database header. (Numeric fields only)
Field Order - The numeric order that the field appears in
the database.
Descriptor - A Default Descriptor that appears in field
pick-lists, data-entry screens and Browse
headers.
Picture - A clause or expression that defines how the
data is presented on the screen.
Default Value - An expression defining the value to place into
this field when appending a new record.
Validation - A single character defining how the data in
Type is field is to be validated during data-entry.
Validations may include choosing values from
other databases, specifying a valid range,
automatic incrementation, evaluating a
logical expression, choosing from a pick-list,
automatically filling in data into other
fields, etc.
Validation - A formula (set of tokens) that is used to
Formula define validation parameters.
When Clause - A logical expression that limits access to
this field based on the contents of other
fields or values returned from expressions.
Help Prompt - Additional information about this field that
appears in the Help Window area of Browse
and Data-Entry screens.
Help Code - A special code that is used as a "hyper-link"
to display information about this field
from the DCHELP.DBF database when requested
by the operator by pressing (F1).
Lock Code - A special code that prevents unauthorized
users from modifying the contents of this
field.
Encrypt - A Password for encrypting the data so it can
Password not be viewed by other utility programs.
Empty Allowed - A Flag that determines whether this field
can be left empty after data-entry.
See Also:
dc_fieldedit()
FIELD CONFIG
Editing, Adding, Inserting a Database Field
Description:
To ADD a field to the end of the list, select (E) then (A)
from the pull-down menu.
To INSERT a field preceding the highlighted field, select (E)
then (I) from the pull-down menu.
To Edit the highlighted field, Press (ENTER) or select (E)
then (E) from the pull-down menu.
NOTE: Editing some properties of a field will require that
the database structure be updated. Editing other
properties will not affect the database structure.
The structure of the actual database will be compared
to the structure of the contents of the editor and
notify the programmer that the contents do not match
and give him/her the option of updating the database
or saving it for a later time.
An input screen for editing the field properties will appear.
Enter the following information:
ALIAS
This is a non-editable entry and is only displayed for
reference purposes. This should be the same name as the
database alias.
FIELD NAME
This MUST be a unique field name of up to 10 characters.
The first character must be an alphanumeric character.
This is referred to as a REAL FIELD that actually exists
in the database.
FIELD TYPE
Enter the Type of field.
C - Character String
M - Memo
N - Numeric
D - Date
L - Logical
A - Array (Supported only by Data-Drivers that allow
Array-type fields)
CA - Character/Array ( This is a MEMO field that stores
arrays by converting them to a character string ). The
Data-Entry and Browsing system automatically handle this
kind of field regardless of the data-driver being used.
FIELD LENGTH
Enter the length of the field. This will automatically be
filled in for MEMO, CHARACTER/ARRAY, DATE, and LOGICAL fields.
The maximum length of a CHARACTER field is 64,000 and the
maximum length of a NUMERIC field is 20.
FIELD DECIMALS
Enter the number of decimal places. (This entry is
applicable to NUMERIC fields only.
DESCRIPTOR
Enter a Default Descriptor that will appear in field
pick-lists, data-entry screens and browse screens. To break
up the descriptor into multiple lines on the screen, use
semi-colons (;).
PICTURE
Enter a Picture clause to establish the way the field will
appear on the screen in data-entry and browse screens.
Picture clauses must conform to the standard picture clauses
supported by the Clipper TRANSFORM() function.
Examples:
@! - Capitalize All Alphabetic Characters
@A - Allow only Alphabetic Characters
@B - Display Numbers Left Justified
@C - Display CR after positive numbers
@D - Display Dates in SET DATE format
@E - Display Dates EUROPEAN style
@K - Delete Default text if First Key is not cursor key
@R - Non-template characters displayed but not saved
@X - Display DB aftre negative numbers
@Z - Display zeros as blanks
@( - Display neg numbers in parens with leading spaces
@) - Display neg numbers in parens without leading spaces
NOTE: Any expression which returns a character string that
conforms to the Picture specification may also be entered.
DEFAULT VALUE
Enter an expression to evaluate for writing a default value
to the field whenever a new record is added to the file.
If this entry is left blank, then the field will default to
blank. The expression must return a value of the same TYPE
as the field.
Examples for CHARACTER Fields:
INVOICE-)INV_NMBR
"New Entry"
Examples for NUMERIC Fields:
100
RecNo()
Examples for DATE Fields:
DATE()
DATE()+14
VALIDATION TYPE
Enter a single character representing the type of
Validation to perform on this field during data-entry.
N - None
F - Calculated Field
X - Logical Expression
R - Range
T - Table Look-Up
V - View (Browse) Look-Up
A - Auto-Fill
C - Choice from Pick-list
P - Run a Program
I - Increment field on Append
See the separate documention on how to create data-entry
validations. For specific help on each validation, press
F1 when the item is high-lighted in the pick-list.
VALIDATION FORMULA
Enter a formula for the validation type entered. A
formula is a set of parameters separated by the vertical
bar | character. A more efficient way of entering the
formula is to use the "formula editor" by clicking on
the down arrow at the end of the input field, double-
clicking within the field or pressing (CTRL-ENTER).
While in the formula editor, you can press F1 or click on
F1 for more information from the HELP system on building
a validation formula. The formula field is ignored if
the validation type is "N".
WHEN CLAUSE
Enter an optional expression that will be evaluated when
attempting to move to the next editable field in the
data-entry screen. This expression must return a logical
.TRUE. to allow entry to the field or a logical .FALSE.
to deny entry to the field and to skip to the next field.
Example: INV_TYPE='I'
HELP PROMPT
Enter the HELP PROMPT to display in the Help-Window area
of the Browse or Data-Entry screen when this field is
selected.
HELP CODE
Enter a Help Code to use as a look-up into the DCHELP.DBF
database for context-specific help on this field when the
operator pressed the F1 key.
LOCK CODE
Enter an optional 3-character code designated the LOCK to
place on this field. If no lock is placed on this field
then any user will have access to editing this field. If
however, a lock is placed on the field, then only the
users who have been assigned a specific key or a master
key to the lock will be allowed access. A DCLOCKS.DBF
database is used to define and maintain the list of locks
available. Press (CTRL-ENTER) or double-click the mouse
to display or maintain the LOCK database and/or choose a
lock from the pick-list.
ENCRYPT PASSWORD
Enter a password to use for encrypting this field. If no
password is entered, then the data will not be encrypted.
If a password is entered, then it will be used as the
"seed" in the encryption algorithm that encrypts the data
written to the database. Utility Database browsers and
editors will not be able to decipher the encrypted
information in this field. Each field may be encrypted
with a different "seed". The only fields which may be
encrypted are CHARACTER, MEMO or NUMERIC.
EMPTY ALLOWED?
Click the mouse in the check area or press (ENTER) to toggle
the check mark. When checked, this entry will allow this
field to remain empty in the data-entry screen, otherwise
a value must be entered.
See Also:
dc_fieldedit()
FIELD EDIT
FIELD REPLICATE
Adding a Replicated Group of Fields
Description:
REPLICATING fields is a procedure that will create a set of
new fields with an automatic Incrementation of any imbedded
number string in the field name. Use this feature if you
want to create a group of fields like so:
PCODE_00
PCODE_01
.......
.......
PCODE_98
PCODE_99
Replicated fields all have the same alpha characters but
will contain an incremented set of numeric characters.
Replicated fields are all the same Type, Length and
Decimals.
NOTE: If replicating 10-99 fields, use 1 leading zero
on start number. Ex: NMBR_01_A
If replicating 100-999 fields, use 2 leading zeros
on start number. Ex: TRANS_001
To Add a REPLICATED group of fields to the end of the list,
select (E) then (R) from the pull-down menu.
Fill in the following information on the screen:
STARTING FIELD NAME
This is the name of the first field to replicate
FIELD TYPE
Enter the Type of field.
C - Character String
M - Memo
N - Numeric
D - Date
L - Logical
A - Array (Supported only by Data-Drivers that allow
Array-type fields)
CA - Character/Array ( This is a MEMO field that stores
arrays by converting them to a character string ). The
Data-Entry and Browsing system automatically handle this
kind of field regardless of the data-driver being used.
FIELD LENGTH
Enter the length of the field. This will automatically be
filled in for MEMO, CHARACTER/ARRAY, DATE, and LOGICAL fields.
The maximum length of a CHARACTER field is 64,000 and the
maximum length of a NUMERIC field is 20.
FIELD DECIMALS
Enter the number of decimal places. (This entry is
applicable to NUMERIC fields only.
#FIELDS TO REPLICATE
Enter the number of new fields to create.
See Also:
dc_fieldedit()
FIELD MOVE
Moving a Field
Description:
A field can be moved from its current order in the field
list to any other position in the field list. When a field
is moved, it will required that the database structure be
updated to match the order in the Field Dictionary.
To move a field, first make a note of the location in which
you want to move the field. This is displayed in the Field
Order column of the display. Next, select the field you
wish to move with the up/down arrow keys or the mouse.
Select (E) then (M) from the pull-down menu and enter the
number of the target location.
See Also:
dc_fieldedit()
GROUP NAME
Editing the Name and Description of a Field Group
Description:
A field group must be given a unique name that also matches
the Alias of the database to which is is associated.
To change the name or description of the field group, select
(E) then (G) from the pull-down menu.
FIELD GROUP NAME (FILE ALIAS)
Enter the File Alias name of the database that is associated
with this field group. For example, if the database is
named CUSTOMER.DBF, then the Alias is CUSTOMER.
FIELD GROUP DESCRIPTION
Enter a description of this field group.
See Also:
dc_fieldedit()
LOAD GROUP
Loading the Editor with a Field Group
Description:
A Field Group can be loaded into the Field Group editor from
a variety of sources. Field Groups are saved to the
DCFIELDS.DBF dictionary, an array file, or source code, so
they also be retreived for editing, copying or exporting.
Field Groups can also be loaded into the editor by scanning
the structure of an open work area.
FIELD DICTIONARY
To load the Editor with a Field Group from the Field
dictionary, select (F), (L) and (D) from the pull-down menu
then choose the Field Group to load from the pick-list. The
pick-list will display all Field Groups that exist in the
DCFIELDS.DBF file.
ARRAY FILE
To load the Editor with a Field Group that was saved to an
array file, select (F), (L) and (A) from the pull-down menu
then enter the name of the *.DCG file to load. Press
(CTRL-ENTER) or double-click the mouse to pop-up a list of
all *.DCG files on the disk.
CODE
To load the Editor with a Field Group that was saved to source
code, first you must make sure that the code was compiled and
linked into the .EXEcutable program that the Field Group editor
also resides. This may be a dCLIP.EXE program or a custom
program. If you are running the Field Group Editor from dCLIP,
then you may exit to the dot-prompt, load the .OBJ file that
contains the source code for the Field Group with the OBJ
command, then re-start the Field Group editor. Select (F),
(L) and (C) then enter the name of the function to execute.
This function must return a Field Group array of the proper
type or an error will occur.
NOTE: The recommended function name to use for assigning a
field group to source code is the name of the Field
Group (File Alias) followed by _G(). For example, the
function to call for returning a field group array
for the "CUSTOMER" database is CUSTOMER_G().
DATABASE STRUCTURE
When creating field groups for databases that already exist,
it is much quicker and simpler to open the database, either
from Dot-Prompt commands or the Assistant, then "capture"
the work area structure into the editor.
To load the Editor with a Field Group from a work area,
first you must make sure that the Datafile is open. If you
are running the Field Group Editor from dCLIP, then you may
exit to the dot-prompt, open the file with the USE command
the restart the File Group Editor.
Ex: USE DCHELP
Select (F), (L), then (S) from the pull-down menu. Select
the work area to read. If you select a blank work area
then a dialogue box will appear with the option of opening
a database file in the selected area.
See Also:
dc_fieldedit()
dc_fieldload()
SAVE GROUP
Saving the Field Group to a File
Description:
The Fields that are displayed in the Editor can be saved to
the DCFIELDS.DBF dictionary, an array file, or source code,
for later retreival by the editor or the the application
program.
FIELD DICTIONARY
To save the Editor contents to the Field dictionary,
select (F), (S) and (D) from the pull-down menu.
CAUTION: Any Field Group in the DCFIELDS.DBF dictionary with
the same name as the group in the editor will be
overwritten. If you do not want to overwrite an
existing group, make sure to assign a unique name
by selecting Field Group Name.
ARRAY FILE
To save the Editor contents to an array file, select (F), (S)
and (A) from the pull-down menu then enter the name of the
*.DCG file to create.
SOURCE CODE
To save the Editor contents to source code, select (F), (S)
and (S) from the pull-down menu. Enter the name of the
source-code *.PRG file to create and the name of the function
to assign. The source code can be compiled with the Clipper
compiler, linked into an application then the menu can be
loaded an executed by calling the DC_WORKRESTORE() function
with the array passed back from the function.
NOTE: The recommended function name to use for assigning a
field group to source code is the name of the Field
Group followed by _G(). For example, the function to
call for returning a field group array for the "CUSTOMER"
database is CUSTOMER_G(). The DC_FIELDLOAD() function
will look first to see if the CUSTOMER_G() function has
been linked into the program and grab the field array
from this function, otherwise it will attempt to
restore the field array from the Field Dictionary.
Restoring from source code is much faster and more
reliable.
See Also:
dc_fieldedit()
dc_fieldsave()
GROUP IMPORT
Importing or Exporting a Field Group
Description:
A Field Group can be EXPORTed to a file named DXFIELDS.DBF
for later IMPORTing into another application. For example,
let's say you have 3 separate applications, each with its own
set of dCLIP dictionary files. Each application will have
its own DCFIELDS.DBF Field dictionary. Field Groups can be
easily exported to a DXFIELDS.DBF file. This file has the
same structure as the DCFIELDS.DBF file so the group can then
be imported to the DCFIELDS.DBF file of the target
application.
To export a Field Group, first load the Field Group into the
editor, then select (F) and (E) from the pull-down menu.
CAUTION: The Field Group will overwrite any Group in the
DXFIELDS.DBF file with the same group name, so make
sure to change the name first under "Group Name"
to a unique name.
To import a Field Group, select (F) and (I) from the pull-down
menu, then select the group to import from the group pick-
list. The list will include the name and description of all
Field Groups in the DXFIELDS.DBF Field Group export file. The
current contents of the editor will be replaced by the
imported group.
See Also:
dc_fieldedit()
UPDATE STRUCTURE
Updating the Structure of the Database
Description:
If new fields have been added to the Field Group in the
editor, or if fields have been deleted or moved in the order
list, or if a Field Name, Type, Length or Decimals has been
changed, then the database structure must be updated to
match the Field Dictionary.
You will automatically be notified if the field group does
not match the database at the time the fields are saved to
the Field dictionary. At this point you will be given the
option to update the database structure. It is important
that the database structure match the Field Dictionary,
otherwise pick-lists, data-entry screens and browse screens
may display incorrect information.
You may choose to force the database structure to be
updated by selecting (F), (S) and (S) from the pull-down
menus.
A backup file with the same name as the original file but
with the *.DBK extension will be created. If the file has
a least one MEMO type field, then the back-up of the memo
file will have the *.DTK extension.
See Also:
dc_fieldedit()
dc_struupdate()
VALIDATION-A
Type "A" (Auto-Fill) Field Validation
Description:
Validation type "A" is used to automatically fill the
field with a value from a relational file after the
operator enter data in an associated field in the field
list. A type "A" validation is also referred to as
"AUTOFILL" and must also be associated with a type "V"
or type "T" validation elsewhere in the data-field table.
AUTOFILL validations are "triggered" by a "V" or "T"
validation in the following manner:
1. The operator chooses a record from a relational file
or a code table while validating a field that has a
type "V" or "T" validation. After the data record is
selected from the relational file, a pointer to the
relational file is stored away in a variable, the
relational file remains open, and the record pointer in
the relational file is pointing to the selected record.
2. The field list is then scanned to see if there are any
fields with type "A" validations that also have a
reference to the field name that triggered the "V" or "T"
validation. For each field that has a reference, the
data from the specified relational file field will be
written to that field.
Fields that have been filled by an AUTOFILL validation may
be overwritten when the field is entered provided that it
is an "editable" field.
To create a type "A" validation, enter "A" as VALIDATION TYPE
when using the FIELD EDITOR via the command "FIELD EDIT" or
function "DC_FIELDEDIT()". When entering the VALIDATION FORMULA,
enter two (2) parameters, separated by a vertical bar |
character:
Param 1 - The name of the field in the field list that triggered
the AUTOFILL with a type "V" or "T" validation.
Param 2 - The name of the field in the relational file chosen
by the type "V" or "T" validation that contains the
data to be written to this field. If the "V" or
"T" validation uses only a single relational file
then it is not necessary to use the alias in front
of the field name, however, it is always a good
idea.
An easier method of entering the formula and preventing mistakes
is to use the FORMULA EDITOR by pressing CTRL-ENTER, double-
clicking the mouse or leaving the formula empty. The FORMULA
EDITOR reads the existing formula and provides a series of data-
entry fields and pick-lists to simplify the creating of
validations.
Example:
Lookup Field/Expr :CUST_NMBR :
Return Field/Expr :CUSTOMER-)NAME :
See Also:
OVERVIEW
EDIT
dc_fieldedit()
FIELD EDIT
VALIDATION-C
Type "C" (Choice) Field Validation
Description:
Validation type "C" is used to choose a value from a pick-list
table of up to 15 choices. If more than 15 choices are
required, then use Validation type "T". If the entered value
already matches a value in the choice pick-list, or if the
"allow override" flag is "YES", then the pick-list of choices
will not be displayed unless the operator double-clicks in the
field area when in data-entry mode, clicks on the down-arrow at
the end of the field or presses CTRL-ENTER when editing the
field.
When the operator chooses an item from the pick-list, the number
of characters in the chosen item will be truncated (cut-off) to
the length of the field. Choice Pick-lists are allowed only for
character-type fields.
To create a type "C" validation, enter "C" as VALIDATION TYPE
when using the FIELD EDITOR via the command "FIELD EDIT" or
function "DC_FIELDEDIT()". When entering the VALIDATION FORMULA,
each pick-list item is separated by a vertical bar | character
followed by a 16th parameter which is a "Y" for YES or "N" for
NO to establish whether or not the operator has the option to
override the value selected from the pick-list.
An easier method of entering the formula and preventing mistakes
is to use the FORMULA EDITOR by pressing CTRL-ENTER, double-
clicking the mouse or leaving the formula empty. The FORMULA
EDITOR reads the existing formula and provides a series of data-
entry fields and pick-lists to simplify the creating of
validations.
Example:
Choice # 1 :1B - First Base :
Choice # 2 :2B - Second Base :
Choice # 3 :3B - Third Base :
Choice # 4 :P - Pitcher :
Choice # 5 :SS - Short Stop :
Choice # 6 :RF - Right Field :
Choice # 7 :LF - Left Field :
Choice # 8 :CF - Center Field :
Choice # 9 :C - Catcher :
Choice #10 :DH - Designated Hitter :
Choice #11 : :
Choice #12 : :
Choice #13 : :
Choice #14 : :
Choice #15 : :
Allow Override? :Y:
See Also:
OVERVIEW
EDIT
dc_fieldedit()
FIELD EDIT
VALIDATION-F
Type "F" (Calculated) Field Validation
Description:
Validation type "F" is used to calculate a value from an
expression that includes references to other fields in the
database and automatically insert the value returned by
the expression. Use a type "F" validation to update "non-
entry" fields whenever the value in another field changes.
To create a type "F" validation, enter "F" as VALIDATION TYPE
when using the FIELD EDITOR via the command "FIELD EDIT" or
function "DC_FIELDEDIT()". When entering the VALIDATION FORMULA,
it must be a valid expression that when macro-expanded, returns
a value of the same "type" as the field being validated.
For example you may have a field named "HOURS" that is
automatically filled-in whenever the operator changes the value
of another field named "MINUTES". The expression for creating
this type of calculation is: MINUTES/60.
Example :
Formula :MINUTES/60 :
See Also:
OVERVIEW
EDIT
dc_fieldedit()
FIELD EDIT
VALIDATION-I
Type "I" (Increment/Append) Field Validation
Description:
Validation type "I" is used to assign a default value to a
field, when appending a new record to the database, that is
equivalent to an "incremented" value extracted from another
field in the same database or any other database. For example,
if you wish to automatically assign a new invoice number to
a new record, a type "I" validation can be used to go to the
last record of the file, extract the last invoice number,
increment it by a value of 1 and store the new value in the
field. Type "I" validations will increment both character
and numeric fields.
Examples:
Type Last Value Incremented Value
---- ---------- -----------------
N 2345 2346
C 56710 56711
C AX-389-BL AX-390-BL
To create a type "I" validation, enter "I" as VALIDATION TYPE
when using the FIELD EDITOR via the command "FIELD EDIT" or
function "DC_FIELDEDIT()". When entering the VALIDATION FORMULA,
enter five (5) parameters separated by the vertical bar |
character:
Param 1 - The FILE ALIAS NAME of the "Look-Up" FILE that must be
opened for extracting the last value. This must be a
valid ALIAS for a file that is already opened when the
record is being added. Leave this parameter empty
if extracting a value from the last record in the
current database.
Param 2 - The LOOK-UP FIELD OR EXPRESSION to use for extracting
the value to "seek" in the "Look-Up" database. This
expression must return a value of the same type as
the index key of the controlling index to seek the
value. Leave this parameter empty if extracting a
value from the last record in the current database
or if the record is already at the correct location,
such as a 1-record "SYSTEM.DBF".
Param 3 - The RETURN FIELD OR EXPRESSION to use for extracting
the value to return and increment into the field being
initialized. This expression must return a value of the
same type as the database field being validated. Leave
this parameter empty if extracting a value from the
last record in the current database. If not extracting
a value from the current database, then the new value
will be stored in the return field of the related
database in addition to the storing in the validated
field of the current database.
Param 4 - The SEARCH INDEX NUMBER of the controlling index to
use when "seeking" to the record in the "Look-Up"
database. The key of this index must match the value
of the Look-Up field or Expression to seek the value.
Leave this as 0 if the record in the Look-up database
does not need to be seeked.
Param 5 - The DEFAULT or STARTING value to enter into the
database field in the event that an empty value is
returned from the target (Look-Up) database.
An easier method of entering the formula and preventing mistakes
is to use the FORMULA EDITOR by pressing CTRL-ENTER, double-
clicking the mouse or leaving the formula empty. The FORMULA
EDITOR reads the existing formula and provides a series of data-
entry fields and pick-lists to simplify the creating of
validations.
Example :
Lookup File Alias :DCFILES :
Lookup Field/Expr :"INVOICE" :
Return Field/Expr :REF_NO :
Seek Index No. : 1:
Start Value : IN-10001 :
See Also:
OVERVIEW
EDIT
FIELD EDIT
dc_numincr()
VALIDATION-P
Type "P" (Program) Field Validation
Description:
Validation type "P" is used to validate a field entry based
on the results returned by executing a specified program.
The program may be a function that is linked into the
.EXEcutable engine or an "interpreted" program that exists
in the DCPROG.DBF program catalog. The program may return
a value to place into the field or a logical value to validate
proper data input.
To create a type "P" validation, enter "P" as VALIDATION TYPE
when using the FIELD EDITOR via the command "FIELD EDIT" or
function "DC_FIELDEDIT()". When entering the VALIDATION FORMULA,
each formula item is separated by a vertical bar | character.
Item 1 - The PROGRAM NAME. This is a program name of up to
10 characters. This program must exist in the
DCPROG.DBF Program Catalog. To create or maintain
this program use the command "PROGRAM MAINTENANCE"
or the function "DC_PROGMAINT()". If you wish to
use a compiled and linked function rather than an
interpreted program, then include parenthesis ()
after the PROGRAM NAMe.
Item 2 - Enter Y for YES or N for NO if this is a LOGICAL
validation rather than a return value. A LOGICAL
validation returns a .TRUE. or .FALSE. to validate
whether or not the data-entry was valid. If a
.FALSE. is returned, then the operator will not be
allowed to move to the next field until a valid
input is received. If a NO is entered, then it is
assumed that the program is returning a value that
is the same type as the field being validated and
that this value will be placed into the field.
Items 3 thru 17 - Enter up to 15 PARAMETERS to pass to the
program. These may be literal values, functions,
field names, or expressions. Each value in each item
will be macro-expanded before being passed on to the
program.
An easier method of entering the formula and preventing mistakes
is to use the FORMULA EDITOR by pressing CTRL-ENTER, double-
clicking the mouse or leaving the formula empty. The FORMULA
EDITOR reads the existing formula and provides a series of data-
entry fields and pick-lists to simplify the creating of
validations.
See Also:
OVERVIEW
EDIT
PROGRAM
FIELD EDIT
dc_program()
VALIDATION-R
Type "R" (Range) Field Validation
Description:
Validation type "R" is used to validate that the entered
field value falls between a specified range of values. If
the operator fails to enter a proper value, an error message
similar to "Entry must be in the Range between 100 and 500"
will be displayed and the operator will not be allowed to
exit the field other than by entering a correct value or
pressing ESCape.
To create a type "R" validation, enter "R" as VALIDATION TYPE
when using the FIELD EDITOR via the command "FIELD EDIT" or
function "DC_FIELDEDIT()". When entering the VALIDATION FORMULA,
the first parameter is the STARTING RANGE and the second
parameter is the ENDING RANGE. Parameters are separated by a
vertical bar | character.
An easier method of entering the formula and preventing mistakes
is to use the FORMULA EDITOR by pressing CTRL-ENTER, double-
clicking the mouse or leaving the formula empty. The FORMULA
EDITOR reads the existing formula and provides a series of data-
entry fields and pick-lists to simplify the creating of
validations.
Example :
Starting Range :100 :
Ending Range :500 :
See Also:
OVERVIEW
EDIT
dc_fieldedit()
FIELD EDIT
VALIDATION-T
Type "T" (Table-Lookup) Field Validation
Description:
Validation type "T" is used to choose a value from a code
table in the DCCODES.DBF Code-Table dictionary and enter it
into the field. If the entered value already matches a
value in the code table, or if the "allow override" flag is
"YES", then the pick-list of codes will not be displayed
unless the operator double-clicks in the field area when in
data-entry mode, clicks on the down-arrow at the end of the
field or presses CTRL-ENTER when editing the field.
A "T" validation also provides for moving data between fields
of different databases upon completion of the successful
validation by referencing a previously created "Field Map".
Use the CODE EDIT command, DC_CodeEdit() function or select
CODE TABLE EDITOR from the Assistant to create and maintain
code tables.
Example of a Code-Table table:
1B First Base
2B Second Base
3B Third Base
P Pitcher
SS Short Stop
RF Right Field
LF Left Field
CF Center Field
C Catcher
DH Designated Hitter
When the operator chooses an item from the code-table pick-list,
the value in the CODE field of the DCCODES.DBF database item
selected will be returned into the data field. Code-Tables
are allowed only for validating character-type fields.
To create a type "T" validation, enter "T" as VALIDATION TYPE
when using the FIELD EDITOR via the command "FIELD EDIT" or
function "DC_FIELDEDIT()". Enter a VALIDATION FORMULA consisting
of four (4) parameters separated by a vertical bar | character.
Param 1 - The CODE TABLE name to open.
Param 2 - A Y for YES or N for NO to establish whether or not
the operator is allowed to OVERRIDE the value returned
from the browse. If YES and the operator presses
ESCAPE, then nothing is returned, otherwise if NO
then the selected value is returned regardless of the
method of exiting the pick-list by the operator.
Param 3 - An 'optional' FIELD MAP TAG NAME to use for moving
information from the Code Table database to the current
database or from any other open database to any other
open database. This must be a valid field map tag name
that exists in the DCMAPS.DBF database which is
maintained by the command "FMAP EDIT" or the function
"DC_FMAPEDIT()". The value returned by the code table
will be passed to the Field Mapping routine to select
a mapping "Sub-Group". If the Map data does not
include Sub-Groups, then all items in the map will be
evaluated.
NOTE: A type "T" validation will leave the DCCODES.DBF database
(code-table) record pointer at the selected code table
record. This record can then be use to transfer the
value in CODE_DESC to any other field using a type "A"
validation.
An easier method of entering the formula and preventing mistakes
is to use the FORMULA EDITOR by pressing CTRL-ENTER, double-
clicking the mouse or leaving the formula empty. The FORMULA
EDITOR reads the existing formula and provides a series of data-
entry fields and pick-lists to simplify the creating of
validations.
Example:
Code Table No. :BASEBALL :
Allow Override? :N:
Field Map Tag : :
See Also:
OVERVIEW
EDIT
CODE EDIT
FIELD EDIT
VALIDATION-V
Type "V" (View/Browse) Look-Up Field Validation
Description:
Validation type "V" is used to seek a value from another
database based on a passed value and then optionally choose a
value from a BROWSE pick-list whose configuration was previously
created and stored in the DCBROWSE.DBF Browse Catalog using the
BROWSE editor.
If the entered value already matches a "seek" value in the
target database, or if the "allow override" flag is "YES",
then the database browse will not be displayed unless the
operator double-clicks in the field area when in data-entry
mode, clicks on the down-arrow at the end of the field or
presses CTRL-ENTER when editing the field. A "V" validation
also provides for moving data between fields of different
databases upon completion of the successful validation by
referencing a previously created "Field Map".
To create a type "V" validation, enter "V" as VALIDATION TYPE
when using the FIELD EDITOR via the command "FIELD EDIT" or
function "DC_FIELDEDIT()". When entering the VALIDATION FORMULA,
enter seven (7) parameters separated by the vertical bar |
character:
Param 1 - The TAG NAME of the "Look-Up" FILE GROUP that must be
opened for performing this validation. This must be a
valid File Group Name in the DCFILES.DBF database that
was assigned by the FILE EDITOR via the command
"FILE EDIT" or the function "DC_FILEEDIT()". A FILE
GROUP is a set of database files, indexes and/or
relations required to perform the validation. If no
TAG NAME is entered, then it is assumed that the
"Look-Up" file is already opened.
Param 2 - The TAG NAME of the "Look-Up" BROWSE CONFIGURATION to
use for choosing a record from the target (Look-Up)
database(s). This must be a valid Browse Configuration
in the DCBROWSE.DBF database that was assigned by the
BROWSE EDITOR from the command "BROWSE" or the function
"DC_BROWSEDB()". If NO Tag Name is entered, then a
DEFAULT BROWSE will be created for the target (Look-Up)
database that will consist of all database fields.
Param 3 - The FILE ALIAS of the "Look-Up" File to select for
performing the validatiion.
Param 4 - The SEARCH INDEX NUMBER of the controlling index to
use when "seeking" to the record in the "Look-Up"
database. The key of this index must match the value
of the Look-Up field or Expression to seek the value.
Param 5 - The LOOK-UP FIELD OR EXPRESSION to use for extracting
the value to "seek" in the "Look-Up" database. This
expression must return a value of the same type as
the index key of the controlling index to seek the
value.
Param 6 - The RETURN FIELD OR EXPRESSION to use for extracting
the value to return into the field being validated.
This expression must return a value of the same type
as the database field being validated.
Param 7 - A Y for YES or N for NO to establish whether or not
the operator is allowed to OVERRIDE the value returned
from the browse. If YES and the operator presses
ESCAPE, then nothing is returned, otherwise if NO
then the selected value is returned regardless of the
method of exiting the browse by the operator.
Param 8 - The 'optional' FIELD MAP TAG NAME to use for moving
information from the Look-Up database to the current
database or from any other open database to any other
open database. This must be a valid field map tag name
that exists in the DCMAPS.DBF database which is
maintained by the command "FMAP EDIT" or the function
"DC_FMAPEDIT()".
Param 9 - The 'optional' FIELD NAME to extract information to
pass to the FIELD MAP as the FIELD MAP SUBGROUP. Only
the items in the Field Map that match the value in this
field will be evaluated when performing the mapping
process. This parameter is ignored if parameter 9 is
empty.
NOTE: A type "V" validation will leave the Look-up database
record pointer at the record selected by the operator
or at the record automatically found that matches the
data entered in the field. This record can then be used
to transfer information from any set of fields in the
Look-Up database to any set of fields in the current
database by using a type "A" validation on each field.
An easier method of entering the formula and preventing mistakes
is to use the FORMULA EDITOR by pressing CTRL-ENTER, double-
clicking the mouse or leaving the formula empty. The FORMULA
EDITOR reads the existing formula and provides a series of data-
entry fields and pick-lists to simplify the creating of
validations.
Example:
Look-up Files Tag :CUSTOMER :
Look-up Browse Tag :CUSTOMER1 :
Look-up File Alias :CUSTOMER :
Look-up Index # : 2:
Look-up Field/Expr :CUST_NMBR :
Return Field/Expr :CUST_NMBR :
Allow Override? :N:
Field Map Tag : :
Field Map SubGroup : :
See Also:
OVERVIEW
EDIT
dc_fieldedit()
FIELD EDIT
dc_browrestore()
VALIDATION-X
Type "X" (Logical) Field Validation
Description:
Validation type "X" is used to evaluate an expression that
returns a logical .TRUE. or .FALSE. based on the operator
input and/or other field data.
To create a type "X" validation, enter "X" as VALIDATION TYPE
when using the FIELD EDITOR via the command "FIELD EDIT" or
function "DC_FIELDEDIT()". When entering the VALIDATION FORMULA,
it must be a valid expression that when macro-expanded, returns
a "logical" value of .TRUE. for a valid entry or a .FALSE. for
an invalid entry.
For example you may have a field named "HOURS" that is allowed
to have a range of 0-4 when the DATE field has a week-end date
or a range of 0-8 when the DATE field has a weekday date.
The expression for creating this type of validation is:
IIF(DOW(DATE)=1.OR.DOW(DATE)=7,HOURS(=4,HOURS(=8)
If the operator attempts to enter more than 8 hours for a
weekday or more than 4 hours for a weekend, a message similar
to the following will appear:
"Invalid Input. Must meet following Condition"
See Also:
OVERVIEW
EDIT
dc_fieldedit()
FIELD EDIT