File Utilities

Cross-Reference a Field or File

• Traditional Cross-references:
  • Types of Traditional Cross-references
    
    
  • Edit a Traditional Cross-reference
    
    
  • Create a Traditional Cross-reference
    
    
  • Delete a Traditional Cross-reference
  
  
  
• New-Style Cross-references:
  • Edit a New-Style Cross-reference
    
    
  • Create a New-Style Cross-reference
    
    
  • Delete a New-Style Cross-reference
  
  
  
• Limits on Reindexing Files

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 [DIXREF] option on the Utility Functions [DIUTILITY] menu. 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

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 [DIRDEX] option on VA FileMan's Utility Functions [DIUTILITY] menu 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 [DIRDEX] option on VA FileMan's Utility Functions [DIUTILITY] menu, 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:

NOTE: As of Patch DI*22*167, the form's first page also includes a DO NOT REINDEX field (just below USE). Set it to a value such as NO RE-INDEXING ALLOWED to mark the index "Do Not Re-Index," or leave it blank. See the "Limits on Reindexing Files" section for which cross-reference types support this marking and how the reindex APIs treat it.

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:

NOTE: As of Patch DI*22*167, the form's first page also includes a DO NOT REINDEX field (just below USE) that you can fill in to mark the new index "Do Not Re-Index." See the "Limits on Reindexing Files" section.

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!

Limits on Reindexing Files

There are some files that should not be reindexed. When such files are inadvertently reindexed, it can cause major problems and necessitate restores from backups. Before Patch DI*22*167, there was no way to prevent such files from being reindexed, except for putting "DO NOT RE-INDEX" in the file description -- which was ineffective. The Re-Index File [DIRDEX] option is a powerful, useful tool, but it can cause a lot of damage when one is not paying attention.

Patch DI*22*167 allows individual cross-references to be marked "Do Not Re-Index," and the Re-Index File [DIRDEX] option respects that. APIs that perform reindexing also respect "Do Not Re-Index," with the following exceptions:

• APIs that reindex a single record ignore the no-reindex restriction. These include:
  • EN^DIK
  • EN1^DIK
  • EN2^DIK
  • IX^DIK
  • IX1^DIK
  • IX2^DIK
  
  
• A cross-reference is reindexed if it is specifically named in an API call, regardless of whether it is marked "Do Not Re-Index." These include:
  • ENALL^DIK
  • ENALL2^DIK

REF: For more information on these APIs, see the VA FileMan Developer's Guide.

Traditional regular cross-references (e.g., B and C cross-references) are always reindexed and cannot be marked "Do Not Re-Index." All other cross-references can be marked "Do Not Re-Index," because reindexing them might cause problems. The following cross-reference types can be marked "Do Not Re-Index":

• All New-Style cross-references
• Bulletin cross-references
• MUMPS cross-references
• Trigger cross-references

To mark a cross-reference "Do Not Re-Index," use the Cross-Reference a Field or File [DIXREF] option under the Utility Functions [DIUTILITY] menu (see the Edit a Traditional Cross-reference and Edit a New-Style Cross-reference sections above).

CAUTION: "Do Not Re-Index" can only be undone by KILLing the NOREINDEX node in the DD.

Reviewed/Updated: June 2026