VA FileMan V. 22.0 Advanced User Manual: File Utilities

Contents:

Main

File Utilities

Cross-Reference a Field or File

Traditional Cross-references:
New-Style Cross-references:

There are seven types of Traditional cross-references and two types of New-Style cross-references available. Generally, a cross-reference in VA FileMan specifies that some action is performed when the field's value is entered, changed, or deleted. For several types of cross-references, the action consists of putting the value into a list -- an index used when looking up an entry or when sorting. The regular cross-reference is used for sorting and for lookup; you can limit it to sorting only. The KWIC, mnemonic, and SOUNDEX cross-references are also used for lookup.

You can sort a file on any field (except a WORD-PROCESSING-type field) whether or not a cross-reference exists for the field. However, sorting is done more quickly and efficiently if a regular cross-reference exists on the field.

When a file is created, a Traditional cross-reference on the NAME (#.01) field is automatically established. You can add or delete cross-references at any time using the Cross-Reference a Field or File option of the Utility Functions submenu. This option can also be used to enter a description of a cross-reference and to prevent the cross-reference from being deleted.

You can create a cross-reference on a Multiple field, a Multiple's subfields, or on any other field type except a WORD-PROCESSING-type field. For example, the PATIENT file contains the AGE AT ONSET subfield in the DIAGNOSIS Multiple. If you create a regular cross-reference for a field in a Multiple, you can choose in what context the cross-reference will be used. You might want to cross-reference the whole file by AGE AT ONSET (so that a report sorted by AGE AT ONSET could be produced efficiently). Alternately, you might want to cross-reference only an individual patient's diagnoses by onset age (so that a lookup of diagnosis could be done using AGE AT ONSET).

Types of Traditional Cross-references

Cross-reference Type	Description
REGULAR	The field value is sorted and stored in the cross-reference. The regular cross-reference is used for sorting. If you wish, it will be used when looking up entries also. The cross-reference that is automatically created on the NAME field (#.01 field) when a file is created is a regular cross-reference; this is the "B" cross-reference.
KWIC	Key Word in Context -- each word of three or more letters in the field value becomes a separate cross-reference. A space is considered the primary word separator. For example, KING LEAR can be looked up under either KING or LEAR. Uppercase or lowercase two letter words such as IN, AN, OR, and IS are not considered key text. The words THE, AND, THEN, FOR, FROM, OTHER, THAN, WITH, THEIR, SOME, and THIS (upper- or lowercase) are not considered key text. Quotation marks are also not considered key text. You can also specify that KWIC separates words at most punctuation marks except quotation marks (e.g., KING-LEAR , KING/LEAR, etc., will be found with LEAR). A list of punctuation marks is presented for your selection.
MNEMONIC	The field's values are cross-referenced along with the NAME (#.01) field cross-reference (so that, for example, the MAIDEN NAME field's values are found along with NAME values in any lookup). Typically, the cross-reference on the NAME field is searched first when doing a lookup.
MUMPS	Those with programmer access can create special cross-references by putting M code into the SET and KILL logic of a cross-reference. You can use the M code entered to accomplish any task that must be done when the value in a field is entered, changed, or deleted.
SOUNDEX	The field's value is transformed into a four-character string representing its phonetic properties. That string becomes the cross-reference. For example, soundex transformation would access GONZALEZ, GONZELES, Gonzales, and Gonsalless as equivalents; entry of any one of these forms looks up all the others automatically.
TRIGGER	Whenever the field is updated, a different field can be automatically updated at the same time. See the "Trigger Cross-references" chapter of the "VA FileMan Programmer Manual" for more details.
BULLETIN	Whenever a field is updated, a MailMan message is sent notifying specified users that an update has occurred. The Bulletin cross-reference is only available when VA FileMan is installed with MailMan.

Edit a Traditional Cross-reference

To edit a Traditional cross-reference, identify the field or subfield you wish to edit. VA FileMan will display the type of cross-references on the field and offer you the choices of Edit, Delete, or Create. Select Edit at this prompt and you will have the opportunity to edit or add a No Deletion message and to enter a description of the cross-reference.

Select OPTION: UTILITY FUNCTIONS
Select Utility Functions Option: CROSS-REFERENCE A FIELD OR FILE

What type of cross-reference (Traditional or New)? Traditional// 

MODIFY WHAT FILE: TEST

Select FIELD: .01   NAME

CURRENT CROSS-REFERENCE IS REGULAR 'B' INDEX OF FILE

Choose E (Edit)/D (Delete)/C (Create): E

NO DELETION MESSAGE: NO, DON'T DELETE THIS X-REF!

This FREE TEXT message indicates that the cross-reference cannot be deleted. As long as a message is retained, the cross-reference cannot be deleted. The user will see this message whenever an attempt is made to delete the cross-reference.

DESCRIPTION:   
1>Used for look-up on and sorting by name.
2>

The description appears in a standard DD listing.

NOTE: It is important to describe cross-references that are unusual or especially critical. Consider describing all MUMPS, trigger, and bulletin cross-references.

Create a Traditional Cross-reference

If you'd like to create a Traditional cross-reference for a field, proceed in the following manner:

Select OPTION: UTILITY FUNCTIONS
Select Utility Functions Option: CROSS-REFERENCE A FIELD OR FILE

What type of cross-reference (Traditional or New)? Traditional// 

MODIFY WHAT FILE: TEST

Select FIELD: 1   DATE

NO CURRENT CROSS-REFERENCE
WANT TO CREATE A NEW CROSS-REFERENCE FOR THIS FIELD?  NO// YES

CROSS-REFERENCE NUMBER:   1//  

Select TYPE OF INDEXING:  REGULAR//   
WANT CROSS-REFERENCE TO BE USED FOR LOOKUP AS WELL AS FOR SORTING?
  YES// 

NO DELETION MESSAGE: 
DESCRIPTION:  
1>Lookup and sorting can be done by date using this Regular
2>cross-reference.
3>

Delete a Traditional Cross-reference

The following dialogue shows how to delete a Traditional cross-reference:

Select OPTION: UTILITY FUNCTIONS
Select Utility Functions Option: CROSS-REFERENCE A FIELD OR FILE

What type of cross-reference (Traditional or New)? Traditional// 

MODIFY WHAT FILE: TEST

Select FIELD: 1   DATE

CURRENT CROSS-REFERENCE IS REGULAR 'C' INDEX OF FILE

Choose E (Edit)/D (Delete)/C (Create): D
Are you sure that you want to delete the CROSS-REFERENCE? NO// YES   ...OK

New-Style Cross-references

Two types of New-Style cross-references are available: Regular and MUMPS. They are like their Traditional cross-reference counterparts, but New-Style cross-references offer some unique advantages:

Compound Cross-references --You can create not only simple cross-references that are based on a single field, but compound cross-references, cross-references that are based on more than one field in a file. For example, in a regular New-Style "C" index you can store both the Name and ID Number of a record as subscripts in a single index:
```
^DIZ(1000,"C","DOE,JANE","A56789",14) =
^DIZ(1000,"C","SMITH,JOHN","D1234",5) =
```
In order to create this kind of index with a Traditional cross-reference, you would have to create two MUMPS-type cross-references, one on the NAME field and one on the ID Number field. New-Style cross-references allow you to define this compound cross-reference once as a regular index that VA FileMan can use for lookup and sorting.
Field- or Record-Level Execution --Since a Traditional cross-reference is defined on a particular field, the action associated with that cross-reference is performed whenever the field is edited. With New-Style cross-references, you can specify that the action associated with a cross-reference be performed only once after the entire record has been edited, typically at the end of the editing session. Record-level execution would normally be selected for compound cross-references.

If the "C" index in the example above were defined using Traditional MUMPS-type cross-references, and both the NAME and ID Number fields were contained in a single INPUT template, the index would be updated when the NAME field was edited, and then again when the ID Number was edited. But if the cross-reference were defined as a New-Style compound index with record-level execution, the index would be updated only once after the entire record was edited, after changes to both the NAME and ID Number fields had been completed.
Code to Kill the Entire Index --This is code that VA FileMan can execute to remove an entire index from a file. This can make re-indexing a file much more efficient. To delete an index, VA FileMan can execute the Kill Entire Index Code, instead of looping through all the record in a file and removing each record's index one at a time.
Activity --New-Style cross-references can have an Activity of "R" and/or "I" to allow you to control whether the cross-reference should be fired during Reindexing and/or Installation (KIDS). If you call IX^DIK, IX1^DIK, or IXALL^DIK or if you select the Re-Index File option on VA FileMan's Utility Functions submenu to re-index all cross-references, only those New-Style cross-references that contain an "R" in Activity will be fired.

If you explicitly select a cross-reference in an EN^DIK, EN1^DIK, or ENALL^DIK call or in the Re-Index File option on VA FileMan's Utility Functions submenu, that cross-reference is fired regardless of its Activity. Also, when a field is edited, VA FileMan ignores Activity and fires all cross-references on that field, though you can control whether a cross-reference is fired by entering SET and KILL Conditions.
Collation --You can specify forwards or backwards collation, the direction in which VA FileMan's lookup utilities loop through a subscript in an index when entries are returned or displayed to the user. This is especially useful for dates. Developers can store dates in their natural internal VA FileMan date format, and still display entries in the date index in reverse date order.
Lookup Prompt --Each subscript on an index in the new INDEX file can be assigned a LOOKUP PROMPT. This prompt will be used as the prompt for entry of the lookup value during classic VA FileMan lookup ^DIC calls. If not filled in, VA FileMan will default to use the name of the field for that subscript value, if there is one.
Computed Values --Those with programmer access can have any value in the cross-reference be computed; that is, the value is determined from M code that sets the variable X.
Subscript Transforms --Those with programmer access can define a Transform for Storage and a Transform for Display on subscripts in an index. The Transform for Storage is code that transforms the internal value of a field before it is stored as a subscript in the index. The Transform for Display is code that transforms the value stored in the index back to a form that can be displayed to the user.
SET and KILL Conditions --Those with programmer access can enter M code that specifies whether the SET or KILL logic is fired. The M code sets the variable X to Boolean true only if the logic should be executed. The "before" and "after" values are available in the X, X1, and X2 arrays (see the table below).

The X, X1, and X2 Arrays --Those with programmer access can reference the X, X1, and X2 arrays in the SET and KILL logic and the SET and KILL conditions of New-Style cross-references. When a field is edited and the cross-reference logic is executed, the field's corresponding X1 array element contains the old value of the field, the X2 array element contains the new value of the field, and the X array element contains either the old or new value, depending on whether the SET logic, SET condition, KILL logic, or KILL condition is being executed:

Array	Value in KILL Logic/KILL Condition	Value in SET Logic/SET Condition
X(order#)	Old value	New value
X1(order#)	Old value	Old value
X2(order#)	New value	New value

The variables X, X1, and X2 always equal X(1), X1(1), and X2(1), respectively.

If an order number in the cross-reference refers to the .01 field, X1(order#) is set to null when the SET logic and SET condition are executed during record creation. Similarly, X2(order#) is set to null when the KILL logic or condition are executed during record deletion.

Key Support --A regular New-Style index can be used as the Uniqueness Index for a key. VA FileMan ensures that all fields in a Uniqueness Index have values (are not null), and that those values, taken collectively, are unique across all records in the file. For more information on keys and how to create them, please see the "Key Definition" topic.

Edit a New-Style Cross-reference

To edit a New-Style cross-reference, identify the file or subfile you wish to edit. VA FileMan will display the cross-references on the file and offer you the choices of Edit, Delete, or Create:

Select OPTION: UTILITY FUNCTIONS
Select Utility Functions Option: CROSS-REFERENCE A FIELD OR FILE

What type of cross-reference (Traditional or New)? Traditional// NEW
MODIFY WHAT FILE: TEST
Select Subfile: 

Current Indexes on file #16026:
  75     'COMP' index
  85     'XR202' index
  106    'H' index
  116    'AC' index
  141    'C' index

Choose E (Edit)/D (Delete)/C (Create): EDIT

Which Index do you wish to edit? C

NOTE: The numbers displayed to the left of each cross-reference are the Internal Entry Number of the cross-reference stored in the INDEX file.

You will then be taken into a ScreenMan form where you can edit the properties of the New-Style cross-reference, as shown below:

ScreenMan Form when editing a New/Updated with VA FileMan V. 22.0-Style Cross-reference.

NOTE: For additional help, enter a single question mark ("?") or two question marks ("??") at any prompt.

Create a New-Style Cross-reference

To create a New-Style cross-reference, proceed in the following manner:

Select OPTION: UTILITY FUNCTIONS
Select Utility Functions Option: CROSS-REFERENCE A FIELD OR FILE

What type of cross-reference (Traditional or New)? Traditional// NEW
MODIFY WHAT FILE: TEST
Select Subfile: 

Current Indexes on file #16026:
  75     'COMP' index
  85     'XR202' index
  106    'H' index
  116    'AC' index
  141    'C' index

Choose E (Edit)/D (Delete)/C (Create): CREATE
Want to create a new Index for this file? No// YES

Type of index: REGULAR// 

Want index to be used for Lookup & Sorting
  or Sorting Only: LOOKUP & SORTING// 

Index Name: J//

NOTE: The numbers displayed to the left of each cross-reference are the Internal Entry Number of the cross-reference stored in the INDEX file.

You will then be taken into a ScreenMan form where you can edit the properties of the New-Style cross-reference, as shown below:

ScreenMan Form when creating a New/Updated with VA FileMan V. 22.0-Style cross-reference.

NOTE: For additional help, enter a single question mark ("?") or two question marks ("??") at any prompt.

Delete a New-Style Cross-reference

The following dialogue shows you how to delete a New-Style cross-reference:

Select OPTION: UTILITY FUNCTIONS
Select Utility Functions Option: CROSS-REFERENCE A FIELD OR FILE

What type of cross-reference (Traditional or New)? Traditional// NEW
MODIFY WHAT FILE: TEST
Select Subfile: 

Current Indexes on file #16026:
  75     'COMP' index
  85     'XR202' index
  106    'H' index
  116    'AC' index
  141    'C' index

Choose E (Edit)/D (Delete)/C (Create): DELETE

Which Index do you wish to delete? 141   C
Are you sure you want to delete the index definition? No// YES

  Index definition deleted.

Do you want to delete the data in the old index now? YES// 
  Removing old index ...  DONE!

Reviewed/Updated: March 4, 2007