VA FileMan Version
22.0 allows you to create two types of New-style cross-references: Regular and
MUMPS. As you have seen in previous lessons, Regular cross-references build
indexes that can be used to lookup and/or sort entries in a file.
The advanced capabilities of Regular
cross-references, which include the ability to define compound indexes,
computed subscripts, and subscript transforms, means that most of the indexes
you previously had to define as Traditional MUMPS cross-references can, with
Version 22.0, be defined as New-style Regular indexes. You can usually reserve
MUMPS cross-references for performing actions other than building
indexes.
Lesson
6.
Create a
New-Style MUMPS Cross-Reference
This lesson introduces you to New-style
MUMPS cross-references. It covers two topics:
1. The X, X1, and X2 arrays.
2. The set and kill logic and conditions of cross-references.
The X, X1, and X2 Arrays
The
set
and kill logic and the set and Kill Conditions of New-style
cross-references can reference the X, X1, and X2 arrays. Here is what those
arrays contain when a record is edited, and the cross-reference is
fired:
Contains the old cross-reference values when the kill logic
and Kill Condition are executed. Contains the new cross-reference
values when the Set Logic and Set Condition are executed.
X1(order#)
Contains the
old cross-reference values when the set and kill logic and conditions
are executed.
X2(order#)
Contains the
new cross-reference values when the set and kill logic and conditions
are executed.
When a new record is added to a file, VA
FileMan sets the .01 field and immediately fires the Set Logic of all the
cross-references on the .01 field. If a New-style cross-reference contains the
.01 field as a cross-reference value, the X1(order#) array element that
corresponds to the .01 field is guaranteed to be null at this point.
When a record is deleted from a file, the
kill logic of all cross-references for that record is executed. All X2(order#)
array elements are null at this point.
Set and Kill Condition
You can define Set and Kill Conditions on
both Regular and MUMPS cross-references to prevent a cross-reference from
firing under conditions you specify.
If there is a Set Condition, the Set Logic
will be executed only if the Set Condition sets X to Boolean true (that is,
after the Set Condition code is executed, the command IF X evaluates to true).
Similarly, if there is Kill Condition, the Kill Logic is executed only if the
Kill Condition sets X to Boolean true.
Typically, your Set and Kill Conditions
would check the X, X1 and/or X2 arrays to decide whether the Set and Kill Logic
should be executed.
Exercise 6.1. Create Your First
New-Style MUMPS Cross-Reference
In this exercise, you will create a MUMPS
cross-reference that should be executed only when a new record is added to the
file. To do this you will add the .01 field as the only cross-reference value
in the cross-reference, make it order number 1, and include a Set Condition
that sets X to 1 only if X1(1) is null. The Set Logic itself will update the
DATE CREATED field with the current date and time.
Step 1.
Use VA FileMan's Cross Reference a Field or File option to create
a MUMPS cross-reference named "AD".
Select OPTION: UTILITY FUNCTIONS
Select UTILITY OPTION: CROSS-REFERENCE A FIELD OR FILE
What type of cross-reference (Traditional or New)? Traditional// NEW
MODIFY WHAT FILE: ZZINDIVIDUAL// <Enter>
Select Subfile: <Enter>
Current Indexes on file #662nnn:
nnn 'C' index
nnn 'D' index
Choose E (Edit)/D (Delete)/C (Create): CREATE
Want to create a new Index for this file? No// YES
Type of index: REGULAR// MUMPS
How is this MUMPS cross reference to be used: ACTION// <Enter>
Note:
Recall that our other choices at this prompt are LOOKUP &
SORTING and SORTING ONLY. Instead of setting index for lookup and/or sorting,
our MUMPS cross-reference will perform an action, namely, set the DATE CREATED
field (#4.1) to the current date and time.
Index Name: AD// <Enter>
Note:
ACTION cross-references, just like SORTING ONLY indexes, must have
names that begin with the letter "A".
Step 2.
Use the ScreenMan form to select the .01 field as a
cross-reference value for the MUMPS cross-reference.
1.
On page 1 of the ScreenMan form, at the "Short Description:" field
enter Set the DATE CREATED field when a new record is added.
2.
On page 2,
in the "Order..." column type 1 and press Enter.
3.
For
"Cross-Reference Values Type of Value", enter FIELD.
4.
In the
pop-up window at the "Field:" prompt, enter .01.
5.
Press
<PF1>C to close the pop-up page.
Note:
Because you are defining a MUMPS cross-reference, FileMan assumes
your cross-reference value will not be used as a subscript, and so doesn't
automatically assign it a subscript number. Since most of the time,
cross-references that set an index can be defined as Regular indexes, most
MUMPS cross-references don't have values that are used as subscripts in an
index. If your MUMPS cross-reference has cross-reference values that are used
as subscripts, you must manually enter subscript numbers for them.
Step 3.
At
the "Set Logic:" prompt enter (on a single line):
This code sets a node in the ZZFDA array, which is passed to the
Filer (FILE^DIE). The Filer sets the current date and time (NOW) into the DATE
CREATED field (#4.1) of the ZZINDIVIDUAL file. To simplify the example,
you will ignore any error messages the Filer returns in the ZZMSG
array.
Tips:
<CTRL-U> is a toggle between the values: null, last
edited, and the default of the ScreenMan field you are editing.
Press
<PF1>Z ("zoom") at any field to open up an editing window at the
bottom of the screen. This editing window is often easier to use than the usual
scrolling window, especially when the value of the field is very long, as is
the case with the Set Logic.
Step 4.
At
the "Set Condition:" prompt enter:
S X=X1(1)=""
Note:
This Set Condition sets X to 1 if X1(1)=""; otherwise, it sets it
to 0. Since X1(1) refers to the old value of the .01 field (the cross-reference
value with order number 1), the Set Condition means that the Set Logic of our
MUMPS cross-reference should be executed only if the record is new.
Number: nnn
EDIT
AN INDEX
Page 2 of 2
CROSS-REFERENCE VALUES:
Order...
Subscr
Type
Length
Field or Computed
Expression
----------
-------
-----
--------
-------------------------------------
1
FIELD
30
NAME (#.01)
Set Logic: N ZZFDA,ZZMSG,DIERR S ZZFDA(662nnn,DA_",",4.1)="NOW"
D FILE^DIE("E"
Kill Logic: Q
Whole Kill:
Set Condition: S X=X1(1)="" Kill
Condition:
Enter
a command or '^' followed by a caption to jump to a specific
field.
COMMAND:
Press
<>PF1>H for help Insert
Step 5.
Press <PF1>E to exit the form.
Step 6.
At
the "Do you want to cross reference existing data now?" prompt, answer
NO.
Do you want to cross reference existing data now? NO
Note:
If you answered "YES" at this point, VA FileMan will loop through
all the entries in the file, and execute the Set Condition. If the Set
Condition sets X to true (1), VA FileMan would execute the Set Logic. We want
FileMan to update the DATE CREATED field only for new records subsequently
added to the file, not for entries already in the file. Also, X1(1) would
evaluate to true (1) for every existing entry, since all entries have non-null
.01 field values, so the Set Logic wouldn't get executed anyway.
End of Exercise
6.1.
Exercise 6.2. Test the New MUMPS
Cross-Reference
In this exercise, you will check the
behavior of the new MUMPS cross-reference you created in Exercise 6.1. To do
this, you will add a record to the file and make sure the DATE CREATED field is
correctly updated with the current date and time. You will then edit the .01
field of an existing record to make sure the DATE CREATED field is not
updated.
Step 1.
Use VA FileMan's Enter or Edit File Entries option to add a new
record 'NEW,ENTRY' to the ZZINDIVIDUAL file:
Select OPTION NAME: ENTER OR EDIT FILE ENTRIES
INPUT TO WHAT FILE: ZZINDIVIDUAL// <Enter>
EDIT WHICH FIELD: ALL// .01 NAME
THEN EDIT FIELD: <Enter>
Select ZZINDIVIDUAL NAME: NEW,ENTRY
Are you adding 'NEW,ENTRY' as a new ZZINDIVIDUAL (the 14TH)? No//
Y (Yes)
Step 2.
Use VA FileMan's Inquire to File Entries to look at the
'NEW,ENTRY' record you just added:
Select OPTION NAME: INQUIRE TO FILE ENTRIES
OUTPUT FROM WHAT FILE: ZZINDIVIDUAL// <Enter>
Select ZZINDIVIDUAL NAME: <space><Enter> NEW,ENTRY
ANOTHER ONE: <Enter>
STANDARD CAPTIONED OUTPUT? Yes// <Enter> (Yes)
Include COMPUTED fields: (N/Y/R/B): NO// <Enter> - No record number (IEN), no
Computed Fields
NAME: NEW,ENTRY DATE CREATED: FEB 21,2001@10:42:27
Note:
The MUMPS cross-reference stuffed the current date and time into
the DATE CREATED field.
Step 3.
Use VA FileMan's Enter or Edit File Entries option to edit the
NAME field of our 'NEW,ENTRY' record to 'MODIFIED,ENTRY':
Select OPTION NAME: ENTER OR EDIT FILE ENTRIES
INPUT TO WHAT FILE: ZZINDIVIDUAL// <Enter>
EDIT WHICH FIELD: ALL// NAME
THEN EDIT FIELD: <Enter>
Select ZZINDIVIDUAL NAME: <space><Enter> NEW,ENTRY
NAME: NEW,ENTRY// MODIFIED,ENTRY
Step 4.
Use VA FileMan's Inquire to File Entries again to see if the DATE
CREATED field has changed:
Select OPTION NAME: INQUIRE TO FILE ENTRIES
OUTPUT FROM WHAT FILE: ZZINDIVIDUAL// <Enter>
Select ZZINDIVIDUAL NAME: <space><Enter> MODIFIED,ENTRY
ANOTHER ONE: <Enter>
STANDARD CAPTIONED OUTPUT? Yes// <Enter> (Yes)
Include COMPUTED fields: (N/Y/R/B): NO// <Enter> - No record number (IEN), no
Computed Fields
NAME: MODIFIED,ENTRY DATE CREATED: FEB 21,2001@10:42:27
Note:
The date and time stored in the DATE CREATED field has not
changed, even though the value of the .01 field was changed. Our Set Condition
prevented the Set Logic from executing since during the edit, the values of the
.01 field and the corresponding X1(1) array element are not null.
End of Exercise
6.2.
Congratulations! You have
just created your first New-Style MUMPS cross-reference!
Select this
link to test yourself on what you've learned in this lesson.