In this lesson, you will see examples of how
VA FileMan enforces the integrity of the key you created in Lesson 9, and
worked with in Lesson 10.
When Does VA FileMan Check Key
Integrity?
VA FileMan checks the integrity of keys at
the following times:
1.
In the Key Definition option
When you create or edit a key, VA FileMan asks if you want to
check the integrity of the key. You can select to verify a key at any time.
(You've already seen examples of this.)
If
the field selected for verification is a key field, the integrity of the key(s)
to which it is a part is checked.
4.
When records are added
All of the VA FileMan APIs and options that add records (FILE^DICN,
UPDATE^DIE,
the
Enter
or Edit File Entries option, etc.) have been modified to verify the
integrity of keys as records are added to the file. By default, if the new
record violates key integrity, the record is deleted.
5.
When records are edited
Similarly, all of the VA FileMan APIs and options that allow you to edit the
value of key fields (^DIE,
FILE^DIE^DDS,
the Enter or Edit File Entries option, etc.) have been modified to ensure that
edits don't cause key integrity to be violated.
All of VA FileMan's editing APIs, including
^DIE and FILE^DIE, automatically enforce key integrity when you edit key
fields.
^DIE checks the integrity of simple
keys (i.e., one-field keys) immediately after the field is edited. It
checks the integrity of compound keys (i.e., keys that are composed of
more than one field) at the very end of the editing session, after all the
fields in the record have been edited.
Exercise 11.1. Try to Delete the Value
of the Key Field SSN
In this exercise, you will see how VA
FileMan's Enter or Edit File Entries automatically enforces key
integrity.
Step 1.
Use VA FileMan's Enter or Edit File Entries option to edit the
NAME field and the SSN field, the two fields in the Primary Key A you created
in Lesson 9.
Select OPTION NAME: ENTER OR EDIT FILE ENTRIES
INPUT TO WHAT FILE: ZZINDIVIDUAL// <Enter>
EDIT WHICH FIELD: ALL// SSN
THEN EDIT FIELD: <Enter>
Step 2.
Select the MODIFIED,ENTRY record and enter and at-sign (@) at the
SSN field to try to delete it.
Because the SSN field is a key field, VA FileMan does not let you
delete its value.
End of Exercise 11.1
Exercise 11.2. Try to Create a
Duplicate Key
In this exercise, you will try to change the
NAME and SSN of the MODIFIED,ENTRY record to see how VA FileMan handles edits
that cause duplicate keys.
Step 1.
Use VA FileMan's Enter or Edit File Entries option to edit the
fields in Primary Key A: NAME field (#.01) and SSN field (#.02) in the
ZZINDIVIDUAL file.
Select OPTION NAME: E <Enter>NTER OR EDIT FILE ENTRIES
INPUT TO WHAT FILE: ZZINDIVIDUAL// <Enter>
EDIT WHICH FIELD: ALL// .01 NAME
THEN EDIT FIELD: SSN
THEN EDIT FIELD: <Enter>
Step 2.
Select the MODIFIED,ENTRY record and try to change the Name to
LAKE,MARIGOLD and the SSN to 111223333.
Some of the previous edits are not valid because they create one or
more duplicate keys. Some fields have been restored to their pre-edited
values.
Note:
Another record in the ZZINDIVIDUAL already has these exact
values for NAME and SSN. VA FileMan displayed a message indicating that this
would violate key integrity. In addition, VA FileMan automatically restored the
values of the NAME and SSN to their pre-edited values.
Step 3.
Answer YES when asked if you want to see a list of the fields that
were edited with values that violate key integrity.
Do you want to see a list of those fields? YES// <Enter>
The following field(s) have been restored to their pre-edited values:
File: ZZINDIVIDUAL File (#662nnn)
Key: A
Record: 'MODIFIED,ENTRY' (#14)
Field: NAME (#.01)
Invalid value: LAKE,MARIGOLD
Restored to: MODIFIED,ENTRY
Field: SSN (#.02)
Invalid value: 111223333
Restored to: 123456789
Note:
VA FileMan displays the record that was edited, the invalid key
field values, and the original values to which the fields were
restored.
Step 4.
Now try changing just the name of MODIFIED,ENTRY to
LAKE,MARIGOLD.
Select OPTION NAME: ENTER OR EDIT FILE ENTRIES
INPUT TO WHAT FILE: ZZINDIVIDUAL// <Enter>
EDIT WHICH FIELD: ALL// .01 <Enter> NAME
THEN EDIT FIELD: SSN
THEN EDIT FIELD: <Enter>
Select ZZINDIVIDUAL NAME: MODIFIED,ENTRY 123456789
NAME: MODIFIED,ENTRY// LAKE,MARIGOLD
SSN: 123456789// <Enter>
Note:
This time FileMan accepted our edits. Now there are two entries in
the ZZINDIVIDUAL file with the name LAKE,MARIGOLD, but since they have
different SSNs, key integrity has not been violated.
End of Exercise
11.2
The DIEFIRE Variable
You can set the variable DIEFIRE in an input
template or within any of the semicolon-pieces of the DR input variable to ^DIE
to instruct VA FileMan to fire the record-level indexes and check the integrity
of all compound keys at that point in the template or DR string. If the
integrity of any key is violated, VA FileMan sets the variable X to the string
"BADKEY", which can be checked by M code in the next field in the template, or
the next semicolon-piece of the DR string.
You can control what VA FileMan does if it
finds any problems with the keys by setting DIEFIRE to null or any combination
of the following flags:
M
=
Prints an error message to user.
L
=
Returns the DIEBADK array.
R
=
Restores invalid key fields to their pre-edited
values.
If you include the L flag in DIEFIRE and a
key is invalid, VA FileMan sets the DIEBADK array, which can be checked by M
code in the next field in the template, or the next semicolon-piece of the DR
string. The format of the DIEBADK array is as follows:
DIEBADK(rFile#,key#,file#,IENS,field#,"O") = The original value of
the field.
DIEBADK(rFile#,key#,file#,IENS,field#,"N") = The new (invalid)
value of the field.
where,
rFile#
=
The root file of the Uniqueness Index of the key. This is the file
or subfile number of the fields that make up the key.
key#
=
The internal entry number (IEN) of the key in the KEY
file.
file#
=
The file of the Uniqueness Index of the key. This is the file or
subfile where the Uniqueness Index resides. For whole file indexes, this is a
file or subfile at a higher level than root file.
IENS
=
The IENS of the record that - with the edits - would have a non-unique
key.
field#
=
The field number of the field being edited.
Exercise 11.3. Use the DIEFIRE
Variable to Check Key Integrity at a Specific Point
In this lesson you will create an input
template that contains the NAME and SSN fields. Immediately after the SSN
field, the input template sets the DIEFIRE variable to "R" to check the
integrity of Key A and restore the fields to their original values if the edits
to NAME and SSN cause a duplicate key. If edits result in a duplicate key, the
input template sets Y to jump back to the NAME field, so that the user can try
entering values for NAME and SSN again.
Step 1.
Use VA FileMan's Enter or Edit File Entries option to create an
input template called ZZINDIVIDUAL.
Select OPTION NAME: ENTER OR EDIT FILE ENTRIES
INPUT TO WHAT FILE: ZZINDIVIDUAL// <Enter>
EDIT WHICH FIELD: ALL// @1
THEN EDIT FIELD: .01 <Enter> NAME
THEN EDIT FIELD: .02 <Enter> SSN
Note:
The @1, which is entered as the first field, serves as a label to
which we return if a duplicate key would be created with the user's new NAME
and SSN values.
Step 2.
Enter as the next field code to set DIEFIRE to an R.
THEN EDIT FIELD: S DIEFIRE="R"
Note:
This tells VA FileMan to fire the compound (record-level)
cross-references and to validate any keys at this point. The "R" tells FileMan
to restore the NAME and SSN to their pre-edited values if the user-supplied
values resulted in a duplicate key.
Step 3.
Enter the following as the next field in the template.
THEN EDIT FIELD: I X="BADKEY" W !!,"An entry already exists
with that NAME and SSN. Please try again.",! S Y="@1"
THEN EDIT FIELD: <Enter>
Note:
Here, immediately after the code that sets DIEFIRE, we check the
variable X to see if it is set to "BADKEY". If so, the new NAME and SSN caused
a duplicate, so we print a message to the user and branch back to label @1 in
the template to prompt for NAME and SSN again.
Step 4.
Save the input template as ZZINDIVIDUAL.
STORE THESE FIELDS IN TEMPLATE: ZZINDIVIDUAL
Are you adding 'ZZINDIVIDUAL' as a new INPUT TEMPLATE? No//
Y <Enter> (Yes)
Step 5.
Select the LAKE,MARIGOLD entry with SSN 123456789.
This time, no messages are printed, since this new NAME-SSN
combination is not a duplicate. FileMan does not branch you back to NAME, and
you exit the template.
End of Exercise
11.3.
Select this
link to test yourself on what you've learned in this lesson.
[Tutorial Data
Dictionary -->]