^DIE: Edit Data
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.
Input Variables
| DIE |
(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. |
| DA |
(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. |
| DR |
(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:
- Field number: The internal number of a field in a
file.
- Field with Default Value: A field number followed by //
(two slashes), followed by a default value. You can make a field with no
current data value default to a particular data value you specify. For example,
if there is a file entry stored descendent from ^FILE(777), and field #27 for
this file is DATE OF ADMISSION, and you want the user to see:
DATE OF ADMISSION: TODAY// then the calling program should be:
S DR="27//TODAY",DIE="^FILE(",DA=777
D ^DIE If the user just presses the Enter/Return key when seeing
the prompt, DIE acts as though the user typed in the word TODAY.
- Stuff a Field Value
(Validated): A field number followed by /// (three slashes), followed
by a value. The value should be the external form of the field's value,
that is, the format that would be acceptable as a user's response. The value is
automatically inserted into the database after passing through the INPUT
transform. For example:
S DR="27///TODAY",DIE="^FILE(",DA=777
D ^DIE
The user sees no prompts, and the current date is
automatically stuffed into field #27 of entry #777, even if other data
previously existed there.
In the course of writing a routine, you
may want to pass the value contained in a variable to DIE and automatically
insert the value into a field. In that case, you would write:
S DR="27///^S X=VAR"
You can also use the three-slash stuff to automatically add or
select an entry in a multiple. For example, if field #60 is a multiple field,
and you write:
S DR="60///TODAY"
the entry in the subfile corresponding to TODAY would be
selected or added if it didn't already exist. Note, however, that if TODAY
didn't already exist in the file, but couldn't be added (because LAYGO wasn't
allowed, for example), or if more than one TODAY entry already existed in the
file (that is, the lookup value was ambiguous), ^DIE will prompt the user to
select an entry in the subfile. If you wish to add entries or edit existing
entries non-interactively, consider using UPDATE^DIE and FILE^DIE instead.
- Stuff a Field Value (Unvalidated): A field number
followed by //// (four slashes), followed by a value. The value is
automatically inserted without validation into the database. For
example:
S DR="27////2570120",DIE="^FILE(",DA=777
D ^DIE The user sees no prompts, and the value 2570120 is put
into field 27 without going through the INPUT transform. When using this form,
the data after the four slashes must already be in its internally stored form.
This cannot be used for .01 fields due to the differences between DIE and
DIC.
NOTE: Key uniqueness is not enforced when a
4-slash stuff is used. 
- Field Value Deletion: A field number followed by three
or four slashes (/// or ////) and an @-sign. This automatically deletes the
field value. For example:
S DR="27///@"
The user does not see any prompts, and the value for field #27
is deleted.
NOTE: You cannot use this method to delete the value of
a required field, an uneditable field, a key field, or a field the user does
not have Delete access to.
- Field Number Range: A range of field numbers, in the
form M:N, where M is the first and N the last number of the inclusive
range. All fields whose numbers lie within this range are asked.
- Placeholder for Branching: A placeholder like @1. See
the discussion of branching below.
- M Code: A line of M code.
- Combination: A sequence of any of the above types,
separated by semicolons. If field numbers .01, 1, 2, 4, 10, 11, 12, 13, 14, 15,
and 101 exist for the file stored in ^FILE, and you want to have fields 4, .01,
10 through 15, and 101 asked in that order for entry number 777, you simply
write:
S DIE="^FILE(",DA=777,DR="4;.01;10:15;101"
D ^DIE
NOTE: The DR-string contains the semicolon
delimiter to specify field numbers and the colon to specify a range of fields.
This prevents these two characters from being used as defaults. They can,
however, be placed in a variable which is then used as the default instead of a
literal, for example:
S DR="27///^S X=VAR"
- INPUT template: An INPUT template name, preceded by an
open bracket ([) and followed by a closed bracket (]). All the fields in that
template are asked.
|
| DIE("NO^") |
(Optional) Controls the use of the ^ in an edit session. If this
variable does not exist, unrestricted use of the ^ for
jumping and
exiting is allowed.
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. |
| DIE("PTRIX",f,p,t)=d |
DIE("PTRIX",f,p,t)=d where
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:
DIE("PTRIX",16100,5,200)="B^BS"
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. |
| DIDEL |
(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. |
Output Variables
| DTOUT |
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. |
Details and Features of Data Editing
Locking
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.
Edit Qualifiers
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.
Branching
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).
Continuation DR-Strings
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 |
Contents |
| 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")
Filing
DIE files data when any one of the following conditions is
encountered:
- The field entered or edited is cross-referenced
- A change of level occurs, i.e., either DIE must descend into a
multiple or ascend to the level above
- Navigation to another file occurs
- M code is encountered in one of the semicolon-pieces of the DR-string
or in a template
- $S becomes less than 2000
- The user up-arrows to a field
- The end of the DR-string or INPUT template is reached
- Templates are compiled and the execution is transferred from one
routine to the next
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.
| DIEFIRE contains: |
Action: |
| 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
where,
| 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.
For example:
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