VA FileMan V. 22 Key and Index Tutorial
[<-- Previous Lesson]   Lesson 6 Quiz Button   [Next Lesson -->]

Part 2 - MUMPS Cross-References

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:

X(order#) 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):
N ZZFDA,ZZMSG,DIERR S ZZFDA(662nnn,DA_",",4.1)="NOW"
D FILE^DIE("E","ZZFDA","ZZMSG")
Note: 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!



Lesson 6 Quiz Button Select this link to test yourself on what you've learned in this lesson.

[<-- Previous Lesson]   [Intro] [1] [2] [3] [4] [5] 6 [7] [8] [9] [10] [11]   [Next Lesson -->]

 


Reviewed/Updated: March 20, 2007