|Contents:||Main||Chapter||See Also:||Getting Started Manual||Advanced User Manual|
This routine handles input of selected data elements for a given file entry. You should use ^DIE only to edit existing records.
NOTE: When you call the DIE routine, it does not lock the record; you must do that yourself. See the discussion of locking below.
To allow the user to interactively choose the fields to edit, use the EN^DIB entry point instead.
(Required) The global root of the file in the form ^GLOBAL( or ^GLOBAL(#, or the number of the file.
If you are editing a subfile, set DIE to the full global root leading to the subfile entry, including all intervening subscripts and the terminating comma, up to but not including the IEN of the subfile entry to edit.
(Required) If you are editing an entry at the top level of a file, set DA to the internal entry number of the file entry to be edited.
If you are editing an entry in a subfile, set up DA as an array, where DA=entry number in the subfile to edit, DA(1) is the entry number at the next higher file level,...DA(n) is the entry number at the file's top level. See the section below on Editing a Subfile Directly for more information.
NOTE: The variable DA is killed if an entry is deleted within DIE. This can happen if the user answers with the @-sign when editing the entry's .01 field.
(Required) A string specifying which data fields are asked for the given entry. The fields specified by DR are asked whether or not VA FileMan Write access security protection has been assigned to the fields.
You can include the following in the DR-string:
The variable may be set to one of the following:
|"OUTOK"||Allows exiting and prevents all jumping.|
|"BACK"||Allows jumping back to a previously edited field and does not allow exiting.|
|"BACKOUTOK"||Allows jumping back to a previously edited field and allows exiting.|
|"Other value"||Prevents all jumping and does not allow exiting.|
f =the from (pointing) file number,
p =the pointer field number,
t =the pointed-to file number, and
d =an up-arrow (^) delimited list of index names
This optional input array allows you to control how lookups are done on both multiple and non-multiple pointer and variable pointer fields. Each node in this array is set to a list of index names, separated by up-arrows (^). When the user edits a pointer or variable pointer field, only those indexes in the list are used when searching the pointed-to file for matches to the lookup value.
For example, if your input template contains a field #5 on file #16100 that is a pointer to the NEW PERSON file (#200), and you want the lookup on the NEW PERSON file to be by name ("B" index), or by the first letter of the last name concatenated with the last 4 digits of the social security number ("BS5" index), you would set the following node before the ^DIE call:
Note that if you allow records to be added to the pointed-to file, you should include a "B" in the list of indexes, since when ^DIE adds an entry, it assumes the .01 field for the new entry is the lookup value. However, the "B" index would not need to be included if the first index in the "PTRIX" node is a compound index whose first subscript is the .01 field.
(Optional) Overrides the Delete access on a file or subfile. Set DIDEL equal to the number of the file before calling DIE to allow the user to delete an entire entry from that file, even if the user does not normally have the ability to delete. This variable does not override the "DEL"-nodes described in the Other Field Definition Nodes of the Global File Structure section.
Is set when a time-out has occurred.
NOTE: DA, DIE, DR, DIE("NO^"), and DIDEL are not killed by DIE; however, the variable DA is killed if the entry is deleted within DIE. This can happen if the user answers with an @-sign when editing the entry's .01 field.
If you want to ensure that two users cannot edit an entry at the same time, lock the entry. It is recommended that you use incremental locks. Here is a simple example of using incremental locks to lock an entry before editing and to remove the lock after:
S DIE="^FILE(",DA=777,DR="[EDIT]" L +^FILE(777):0 I $T D ^DIE L -^FILE(777) Q W !?5,"Another user is editing this entry." Q
NOTE: The DIE call itself does no locking.
In the DR string, you can use edit qualifiers (described in the "VA FileMan Advanced User Manual") in conjunction with the fields you specify. The possible qualifiers are T, DUP, REQ, and text literal strings in quotes.
In interactive mode, users can combine qualifiers with fields by using semicolon separators. But, in DR-strings, semicolons are already used to delimit individual fields, so you must use a different syntax for DR. Basically, leave out the semicolon and the unnecessary characters. Using field #3 as an example, the syntax for edit qualifiers in DR-strings is:
|Interactive Syntax||Syntax for DR-string||Explanation|
|3;T||3T||The T follows the field number immediately.|
|3;"xxx"||3xxx||The quotes are removed from the literal and it follows the field number immediately.|
|3;DUP||3d||The D becomes lowercase and the UP is dropped.|
|3;REQ||3R||The EQ is dropped and the uppercase R follows immediately.|
You can combine specifiers as long as you separate them with tildes (~). For example, if you want to require a response to field #3, and issue the title rather than the prompt, put 3R~T in the DR-string.
You can include branching logic within DR. To do this, insert an executable M statement in one of the semicolon-pieces of DR. The M code is executed when this piece of DR is encountered by the DIE routine.
If the M code sets the variable Y, DIE jumps to the field whose number (or label) matches Y. (The field must be specified elsewhere within the DR variable.) Y may look like a placeholder, e.g., @1. If Y is set to zero or the null string, DIE exits. If Y is killed, or never set, no branching occurs.
The M code can calculate Y based on X, which equals the internal value of the field previously asked for (as specified by the previous semicolon-piece of DR). Take the example below and suppose that you do not want the user to be asked for field .01 if the answer to field 4 was YES, you would write the following:
S DIE="^FILE(",DA=777 S DR="4;I X=""YES"" S Y=10;.01;10:15;101" D ^DIE
NOTE: The ability to up-arrow jump to specific fields does not take into account previous branching logic. You must ensure that such movements are safe.
Specific Fields in Multiples
When you include the field number of a multiple in a DR-string, all the subfields of the multiple are asked. However, suppose you want to edit only selected subfields in the multiple. To do this, set DR in the usual manner and in addition set a subscripted value of DR equal to the subfields to edit. Subscript the additional DR node by file level and then by the multiple's subfile number.
For example, if field #15 is a multiple and the subfile number for the multiple is 16001.02 and you want the user to be prompted only for subfields .01 and 7, do the following:
S DR=".01;15;6;8" S DR(2,16001.02)=".01;7"
where the first subscript, 2, means the second level of the file and the second subscript is the subfile number of the multiple field (#15).
If there are more than 245 characters in a DR-string, you can set continuation strings by defining the DR-array at the third subscript level. These subscripts should be sequential integers starting at 1. For example, the first continuation node of DR(2,16001.02) would be DR(2,16000.02,1); the second would be DR(2,16001.02,2), and so on.
Detecting Up-Arrow Exits
You can determine, upon return from DIE, whether the user exited the routine by typing an up-arrow. If the user did so, the subscripted variable Y is defined; if all questions were asked and answered in normal sequence, $D(Y) is zero.
Editing a Subfile Directly
You can call ^DIE to directly edit an entry in a subfile; you can descend into as many subfiles as you need to. Set the DIE input variable to the full global root leading to the subfile entry, including all intervening subscripts and the terminating comma, up to - but not including - the IEN of the subfile entry to edit. Then set an array element for each file and subfile level in the DA input variable, where DA=entry number in the subfile to edit, DA(1) is the entry number at the next higher file level,...DA(n) is the entry number at the file's top level.
For example, suppose that the data in subfile 16000.02 is stored descendent from subscript 20 and you are going to edit entry number 777, subentry number 1; you would write the following:
S DIE="^FILE(777,20," ; global root of subfile S DA(1)=777 ; entry number in file S DA=1 ; entry number in subfile S DR="3;7" ; fields in subfile to edit D ^DIE
NOTE: The internal number of the entry into the file appears in the variable DIE and appears as the value of DA(1). When doing this, it is necessary that the subfile descriptor node be defined. In this example, it would be:
^FILE(777,20,0)="^16000.02^last number entered^number of entries"
See also the discussion of "Adding New Subentries to a Multiple" in the "DIC section" of the Classic VA FileMan APIs.
Screening Variable Pointers
A variable pointer field can point to entries in more than one file. You can restrict the user's ability to input entries to certain files by setting the DIC("V") variable in a DR-string or in an INPUT template. It screens files from the user. Set DIC("V") equal to a line of M code that returns a truth value when executed. The code is executed after someone enters data into a variable pointer field. If the code tests false, the user's input is rejected; FileMan responds with ?? and a "beep."
The code setting the DIC("V") variable can be put into a DR-string or into an INPUT template. It is not a separate input variable for ^DIE or ^DIC. It should be set immediately before the variable pointer field is edited and it should be killed immediately after the field is edited.
When the user enters a value at a variable pointer field's prompt, VA FileMan determines in which file that entry is found. The variable Y(0) is set equal to information for that file from the data dictionary definition of the variable pointer field. You can use Y(0) in the code set into the DIC("V") variable. Y(0) contains the following:
|Piece 1||File number of the pointed-to file.|
|Piece 2||Message defined for the pointed-to file.|
|Piece 3||Order defined for the pointed-to file.|
|Piece 4||Prefix defined for the pointed-to file.|
|Piece 5||y/n indicating if a screen is set up for the pointed-to file.|
|Piece 6||y/n indicating if the user can add new entries to the pointed to file.|
All of this information was defined when that file was entered as one of the possibilities for the variable pointer field.
For example, suppose field #5 is a variable pointer pointing to files 1000, 2000, and 3000. If you only want the user to be able to enter values from files 1000 or 3000, you could set up your INPUT template like this:
THEN EDIT FIELD: ^S DIC("V")="I +Y(0)=1000!(+Y(0)=3000)" THEN EDIT FIELD: 5 THEN EDIT FIELD: ^K DIC("V")
DIE files data when any one of the following conditions is encountered:
New Style Compound Indexes and Keys
^DIE traditionally fires cross-references when the field on which the cross-reference is defined is edited. New-style cross-references that have an execution of "RECORD" (hereafter referred to as record-level indexes) are fired once at the end of the ^DIE call, after all the semicolon pieces of the DR string have been processed.
When record-level uniqueness indexes are fired, the corresponding keys (hereafter called record-level keys) are checked to ensure that they are unique. If edits to a field in a key result in a duplicate key, then changes to that field are backed out and an error message is presented to the user.
You can set the variable DIEFIRE in any of the semicolon-pieces of DR to instruct VA FileMan to fire the record-level indexes at that point and validate the corresponding record-level keys. You can also control what FileMan does if any of the record-level keys is invalid.
|M||Print error message to user|
|L||Return the DIEBADK array (see example immediately below)|
|R||Restore invalid key fields to their pre-edited values|
If DIEFIRE contains an L and a key is invalid, the DIEBADK array is set as follows:
DIEBADK(rFile#,key#,file#,IENS,field#,"O") = the original value of the field DIEBADK(rFile#,key#,file#,IENS,field#,"N") = the new (invalid) value of the field
|rFile#||=||the root file of the uniqueness index of the key. This is the file or subfile number of the fields that make up the key.|
|key#||=||the internal entry number of the key in the KEY file.|
|file#||=||the file of the uniqueness index of the key. This is the file or subfile where the uniqueness index resides. For whole file indexes, this is a file or subfile at a higher level than root file.|
|IENS||=||the IENS of the record that - with the edits - would have a non-unique key.|
|field#||=||the field number of the field being edited.|
If any of the Keys is invalid, VA FileMan sets the variable X to the string "BADKEY", which can be checked by M code in the subsequent semicolon-piece of the DR string. The variable X and the local array DIEBADK are available for use only in the semicolon piece immediately following the piece where the DIEFIRE was set.
S DIE="^FILE(",DA=777 S DR="@1;.01;.02;S DIEFIRE=""R"";I X=""BADKEY"" S Y=""@1"";1;2" D ^DIE
Here, the .01 and .02 fields make up a key to the file. After prompting the user for the value of the .02, DIEFIRE is set to force VA FileMan to fire the record-level indexes and validate the key. If the key turns out to be invalid, FileMan sets X equal to "BADKEY" and, since DIEFIRE equals R, restores the fields to their pre-edited values. In the next semicolon-piece, we check if X equals "BADKEY" and, if so, branch the user back to the placeholder @1.
Reviewed/Updated: March 10, 2007