VA FileMan V. 22.0 Programmer Manual Banner


 

Main Chapter Getting Started Manual Advanced User Manual

Classic VA FileMan API


^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. New/Updated with VA FileMan V. 22.0


  • 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:

New Style Compound Indexes and Keys New/Updated with VA FileMan V. 22.0

^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