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

Part 2 - MUMPS Cross-References


Lesson 7. Cross-Reference Execution

In this lesson you will learn when VA FileMan executes the Set and Kill Logic of New-style cross-references. You will also use the X1 and X2 arrays in the Set Logic of a MUMPS cross-reference.


When Does Cross-Reference Logic Get Executed?

In general, for New-style cross-references both Regular and MUMPS, when a field or group of fields defined in a New-style cross-reference is edited, both the Kill and the Set Logic of that cross-reference are executed. First, the Kill logic is executed with the X(order#) array set to the old (pre-edited) field values. Then the Set Logic is executed with the X(order#) array set to the new values.

The exceptions to this are as follows:

1. Null subscript values.
If a cross-reference value is used as a subscript (that is, it has a subscript number), and the old value is null, the Kill logic is not executed. Similarly, the Set Logic is not executed if a new value used as a subscript is null.
2. Record deletion.
When an entire record is deleted from a file, only the Kill Logic, not the Set Logic, is executed. The X2(order#) array elements, which normally contain the new cross-reference values, are all set to null.
3. Record creation.
Immediately after a record is added to a file, only the Set Logic, not the Kill Logic, of New-style cross-references that contain the .01 field is executed. The X1(order#) array element that corresponds to the .01 field is set to null at this point.
4. Kill and Set Conditions.
As illustrated in Lesson 6, if the Set or Kill Condition sets X to Boolean false, the Set or Kill Logic will not be executed.

The following table summarizes when the Kill and Set Logic are executed for New-style cross-references.

New-style cross-references

  Kill Logic Set Logic
Record creation Not executed Executed immediately after the .01 is set (if .01 is a cross-reference value.)
Record edit Executed1 Executed2
Record deletion Executed1 Not executed

1 only if no old values used as subscripts are null, and the Set Condition, if any, sets X to true (1).
2 only if no new values used as subscripts are null, and the Kill Condition, if any, sets X to true (1).

Note that in "Record edit," it doesn't matter if individual field values are created (go from null to non-null) or deleted (go from non-null to null) - both the Kill and the Set Logic are executed as long as none of the field values used as subscripts evaluate to null.

This behavior is slightly different than that of Traditional cross-references. Since Traditional cross-references are defined on a specific field, the Kill and Set Logic are executed depending on whether that one field value is created, deleted, or edited.

The following table summarizes when the Kill and Set Logic are executed for Traditional cross-references.

Traditional cross-references

  Kill Logic Set Logic
Field value "creation" - value goes from null to non-null. Not executed Executed
Field edit - both old and new values are non-null. Executed Executed
Field value deletion - value goes from non-null to null. Executed Not executed
Record creation Not executed Executed for all x-refs on the .01 field, immediately after the .01 is set
Record deletion Executed Not executed

Execution

The Execution property of New-style cross-references controls the timing of cross-reference execution. Execution can be either of the following:

1. Field execution means that the cross-reference logic is executed immediately after each and every field in the cross-reference is edited.
2. Record execution means that the cross-reference logic is executed once at the end of an editing session after all fields in the record are edited.

Usually, simple cross-references (those that have only one field-type cross-reference value) have Field-level execution. Compound cross-references (those that have more than one field-type cross-reference value) have Record-level execution.


Exercise 7.1.  Create a MUMPS Cross-Reference that Makes Use of the X, X1, and X2 Arrays

In this exercise, you will create a MUMPS cross-reference that contains two field-type cross-reference values, AREA CODE field (#3.1) and LOCAL NUMBER field (#3.2). When either or both of those fields are updated, the OLD PHONE NUMBER field (#3.4) will be set to:

(Old_Area_Code) Old_Local_Number

and the PHONE NUMBER field (#3.3) is set to:

(New_Area_Code) New_Local_Number

In addition, if the old area code, new area code, old local number, or new local number is null, you will store the value as the string "null" in the OLD PHONE NUMBER and PHONE NUMBER fields. To accomplish this task, you will use computed cross-reference values.


Step 1. Use VA FileMan's Cross Reference a Field or File option to create a MUMPS cross-reference named "AE":
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
  nnn    'AD' 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// ACTION

Index Name: AE// <Enter> AE

Step 2. On the first page of the ScreenMan form, enter the following Short Description:
Update PHONE NUMBER & OLD PHONE NUMBER if AREA CODE & LOCAL NUMBER are edited.

Step 3. Tab to Execution and enter R for RECORD.
Number: nnn EDIT AN INDEX Page 1 of 2

File:
Index Name:
662nnn
AE
Root File: 662nnn
    Root Type: INDEX FILE
Short Description: Update PHONE NUMBER & OLD PHONE NUMBER if AREA CODE & LOCAL NUMBER are edited.
Description (wp): (empty)
Type: MUMPS
Activity:
Execution:
IR
RECORD
Use: ACTION

Save     Exit     Next Page     Refresh
COMMAND:                    Press <>PF1>H for help    Insert

Note: Our "AE" cross-reference will contain two fields, AREA CODE and LOCAL NUMBER, and so should have an execution value of Record.

Step 4. On page 2 of the ScreenMan form, add the AREA CODE field as order number 1:
Order...: 1
CROSS-REFERENCE VALUES TYPE OF VALUE: FIELD
Field: AREA CODE
Step 5. Add the LOCAL NUMBER field as order number 2:
Order...: 2
CROSS-REFERENCE VALUES TYPE OF VALUE: FIELD
Field: LOCAL NUMBER
Page 2 of the ScreenMan form should now look like this:
Number: nnn EDIT AN INDEX Page 2 of 2

CROSS-REFERENCE VALUES:
Order... Subscr Type Length Field or Computed Expression
---------- ------- ----- -------- -------------------------------------
1
2
FIELD
FIELD

30
AREA CODE (#3.1)
LOCAL NUMBER (#3.2)
 Set Logic: Q
Kill Logic: Q
Whole Kill:
 Set Condition:
Kill Condition:

COMMAND:                    Press <>PF1>H for help    Insert

Step 6. Add a cross-reference value of type Computed that evaluates either to the AREA CODE field or to the string "null", if the AREA CODE field is missing.
Order...: 3
CROSS-REFERENCE VALUES TYPE OF VALUE: COMPUTED
Computed Code: S X=$S(X(1)="":"null",1:X(1))
Note: X(1) in the computed expression is the value of the AREA CODE field, the cross-reference value with order number 1. The computed expression sets the variable X to the AREA CODE (X(1)), or if the AREA CODE is null (X(1)=""), it sets X to the string "null".

Step 7. Similarly, add a cross-reference value of type Computed that evaluates to the LOCAL NUMBER field, or, if the LOCAL NUMBER field is missing, the string "null."
Order...: 4
CROSS-REFERENCE VALUES TYPE OF VALUE: COMPUTED
Computed Code: S X=$S(X(2)="":"null",1:X(2))
Note: X(2) in the computed expression is the cross-reference value with order number 2, in this case, the LOCAL NUMBER field.
Page 2 of the ScreenMan form should now look like this:
Number: nnn EDIT AN INDEX Page 2 of 2

CROSS-REFERENCE VALUES:
Order... Subscr Type Length Field or Computed Expression
---------- ------- ----- -------- -------------------------------------
1
2
3
4
FIELD
FIELD
COMPUTED
COMPUTED
AREA CODE (#3.1)
LOCAL NUMBER (#3.2)
S X=$S(X(1)="":"null",1:X(1))
S X=$S(X(2)="":"null",1:X(2))
 Set Logic: Q
Kill Logic: Q
Whole Kill:
 Set Condition:
Kill Condition:

COMMAND:                    Press <>PF1>H for help    Insert

Step 8. Tab to Set Logic and enter (on one line):
N ZZFDA,ZZMSG,DIERR
 S ZZFDA(662nnn,DA_",",3.3)="("_X2(3)_") "_X2(4),
ZZFDA(662nnn,DA_",",3.4)="("_X1(3)_") "_X1(4)
 D FILE^DIE("E","ZZFDA","ZZMSG")
Note: This code calls the Filer (FILE^DIE) to set the PHONE NUMBER field (#3.3) to the new (Area_Code) Local_Number, and the OLD PHONE NUMBER field (#3.4) to the old (Area_Code) Local_Number.

Step 9. Press <PF1>E to exit the form.


Step 10. At the "Do you want to cross reference existing data now?" prompt, answer NO, shown below:
Do you want to cross reference existing data now? NO

Note: If you answered "YES" at this point, VA FileMan will execute the Set Logic for all entries in the file. For each record, the PHONE NUMBER field (#3.3) and the OLD PHONE NUMBER field (#3.4) would both be populated with (Area_Code) Local_Number. This is not a problem, but we'll choose to have those fields updated only upon subsequent edits.

End of Exercise 7.1.



Exercise 7.2.  Test the New MUMPS Cross-Reference


Step 1. Use VA FileMan's Enter or Edit File Entries to edit the AREA CODE field (#3.1) and the LOCAL NUMBER field (#3.2) of the MODIFIED,ENTRY record added in Lesson 6.
Select OPTION NAME: ENTER OR EDIT FILE ENTRIES

INPUT TO WHAT FILE: ZZINDIVIDUAL// <Enter>
EDIT WHICH FIELD: ALL// 3.1 <Enter>  AREA CODE
THEN EDIT FIELD: 3.2 <Enter>  LOCAL NUMBER
THEN EDIT FIELD:

Select ZZINDIVIDUAL NAME: MODIFIED,ENTRY
AREA CODE: 415
LOCAL NUMBER: 555-1234
Step 2. Use VA FileMan's Inquire to File Entries option to look at the data in the MODIFIED,ENTRY record.
Select OPTION NAME: INQUIRE TO FILE ENTRIES

OUTPUT FROM WHAT FILE: ZZINDIVIDUAL// <Enter>
Select ZZINDIVIDUAL NAME: 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             AREA CODE: 415
  LOCAL NUMBER: 555-1234         PHONE NUMBER: (415) 555-1234
  OLD PHONE NUMBER: (null) null  DATE CREATED: <Date/Time Created>
Note: The OLD PHONE NUMBER field is set to the previous phone number (area code and local phone were both null), and the PHONE NUMBER field is set to the new phone number (area code and local number).

Step 3. Repeat steps 1 and 2, but this time delete the area code. At the end of this step, the field values should be:
NAME: MODIFIED,ENTRY               LOCAL NUMBER: 555-1234
  PHONE NUMBER: (null) 555-1234    OLD PHONE NUMBER: (415) 555-1234
  DATE CREATED: <Date/Time Created>
Note: The PHONE NUMBER and OLD PHONE NUMBER fields again correctly reflect the original and new values of the AREA CODE and LOCAL NUMBER fields.

Step 4. Repeat Steps 1 and 2, but this time enter 510 as the Area Code and delete the Local Number. At the end of this step, the field values should be:
NAME: MODIFIED,ENTRY              AREA CODE: 510
  PHONE NUMBER: (510) null        OLD PHONE NUMBER: (null) 555-1234
  DATE CREATED: <Date/Time Created>
Step 5. Repeat Steps 1 and 2, but this time enter 555-3412 as the Local Number. At the end of this step, the field values should be:
NAME: MODIFIED,ENTRY             AREA CODE: 510
  LOCAL NUMBER: 555-3412         PHONE NUMBER: (510) 555-3412
  OLD PHONE NUMBER: (510) null   DATE CREATED: <Date/Time Created>
Note: In all cases, Steps 1 through 5, the Set Logic was executed, even when the Area Code and/or the Local Number field values were deleted.

End of Exercise 7.2.



Lesson 7 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