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.
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.
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: COMPUTEDComputed 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-1234PHONE NUMBER: (415) 555-1234OLD 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.
Select this
link to test yourself on what you've learned in this lesson.