VA FileMan V. 22.0 Programmer Manual Banner


Main Chapter Getting Started Manual Advanced User Manual

Database Server (DBS) API

UPDATE^DIE( ): Updater

This procedure adds new entries in files or subfiles. The caller uses a standard FDA structure to specify the field values of the new entries. The caller should restrict each Updater call to one logical entry, possibly made up of multiple physical entries. The record numbers for the new entries are returned in an array; the caller may assign their own record numbers to new entries by presetting the array. Any appropriate indexing and auditing automatically occurs for the new record.

Although the Updater can safely add entries to top-level files and to subfiles within those same new entries, there is one caution. If the subfile contains an INPUT transform that assumes the existence of the parent record, the developer should make two separate Updater calls, first to add the parents, then to add the children.

This procedure includes some elementary filing capabilities to permit the adding of required identifiers and key values at the time new records are created. It also includes elementary finding capabilities to facilitate the identification of top-level entries to which subentries are being added. For full filing and finding capabilities beyond the scope of adding new records, programmers should use the Filer (FILE^DIE) or Finder (FIND^DIC). If you are filing data in existing records and you know the record numbers, use the Filer instead of the Updater.

Input Parameters

(Optional) Flags to control processing. The possible values are:

E External values are processed. If this flag is set, the values in the FDA must be in the format input by the user. The Updater validates all values and converts them to internal format. Invalid values cancel the entire transaction.

If the flag is not set, values must be in internal format and must be valid.
K  If a file has a primary key, the primary Key fields, not the .01 field, are used for lookup for Finding and LAYGO Finding nodes.
S The Updater Saves the FDA instead of killing it at the end.
U  Don't check key integrity. (CAUTION: If this flag is used, the UPDATE^DIE call may result in records that contain null key fields or records with duplicate keys. It is the programmer's responsibility to ensure that the database is not left in a state in which the integrity of keys is violated.)

(Required) The name of the root of a VA FileMan Data Array, which describes the entries to add to the database. The Updater accepts Adding Nodes, Filing Nodes, Finding Nodes, and LAYGO Finding Nodes in its FDAs. See "Details and Features" in this section for a description of the format of the array named by the FDA parameter.


(Optional) The name of the Internal Entry Number Array (or IEN Array). This should be a closed root. This array has two functions:

1) Requesting Record Numbers for New Entries

The application can set nodes in the IEN Array to direct the Updater to use specific record numbers for specific new records. These nodes should have a single subscript equal to the sequence number in the IENS subscript of the FDA entry and a value equal to the desired record number.

For example, if the application sets the IEN_ROOT parameter to ORIEN, and sets ORIEN(1)=1701, the Updater will try to assign record number 1701 to the new record denoted by the "+1" value in the FDA subscripts.

This feature also affects LAYGO Finding nodes. When these nodes result in adding a new record, the Updater will check the IEN Array to see if the application wants to place the new record at a specific record number. When LAYGO Finding nodes result in a successful lookup, the IEN Array node passed in by the application is changed to the record number of the record found.

If the application sets an entry in the IEN Array for a Finding node, the Updater will ignore it (actually, it will overwrite it when it finds the record number for that node).

This feature is meaningless for Filing nodes since they have no sequence numbers.

Unlike FDA_ROOT, IEN_ROOT is optional, both partially and as a whole. The Updater will pick the next available record numbers for any new records not listed by sequence number in the IEN Array. If the IEN Array is empty or if the IEN_ROOT is not passed, the Updater will pick all the new record numbers.

2) Locating Feedback on What the Updater Did

As the Updater decodes and processes the sequence numbers, it gradually converts them into genuine record numbers (see Output). The IEN Array named by the IEN_ROOT parameter is where this feedback will be given. Those sequence numbers not already assigned by the application will be filled in by the Updater (or sometimes replaced, in the case of LAYGO Finding nodes).


(Optional) The array that should receive any error messages. This must be a closed array reference and can be either local or global. For example, if MSG_ROOT equals "OROUT(42)", any errors generated appear in OROUT(42,"DIERR").

If the MSG_ROOT is not passed, errors are returned descendent from ^TMP("DIERR",$J).

IEN Array

As the Updater assigns record numbers to the records described in the FDA, it sets up nodes in the IEN Array to indicate how it decoded the sequence numbers. See "Details and Features" for more information on sequence numbers. This lets the application find out what was done with the various nodes in the FDA.

The meaning of IEN Array entries varies depending on the type of node the sequence number came from. For example, the significance of an IEN Array entry of ORIEN(3) = 1701 depends on which type of node in the FDA the sequence number 3 came from.

For Adding Node sequence numbers, the value in the IEN Array indicates the record number of the new record. If our example came from an Adding Node, such as FDA(19,"+3,",.01) ="ZTMDQ", it means the new record was assigned the record number 1701.

For Finding Node sequence numbers, the value indicates at which record number the value was found. If our example came from a Finding Node, such as FDA(19,"?3,",.01) ="ZTMDQ", it means a call to $$FIND1^DIC found record number 1701 based on a lookup value of "ZTMDQ".

For LAYGO Finding sequence numbers, an extra zero-node equal to ? or + identifies whether the entry was found (?) or added (+). If our example came from a LAYGO Finding Node, such as FDA(19,"?+3,",.01)="ZTMDQ", an extra node of ORIEN(3,0)="?" means ZTMDQ was found, whereas ORIEN(3,0)="+" means it was added.

By the time the Updater finishes processing an FDA, every sequence number will be listed with a value in the IEN Array (some set by the application as input for new record numbers and the rest set by the Updater).

If the IEN_ROOT parameter was not passed, the IEN Array is not returned.


The following example illustrates the use of this call to create a new record in a top-level file. In this case, a new option is being added at a specified record number. Notice the triggered 9 on the 0-node and the triggered "U" node:

    >S FDA(42,19,"+1,",.01)="ZZ FDA TEST NAME"

>S FDA(42,19,"+1,",1)="ZZ Toad Test Menu Text"

>S FDAIEN(1)=2067642283


>D ^%G

Global ^DIC(19,2067642283
^DIC(19,2067642283,0) = ZZ FDA TEST NAME^ZZ Toad Test Menu Text^^^9
^DIC(19,2067642283,"U") = ZZ FDA TEST MENU TEXT
Error Codes Returned
110 The record is currently locked.
111 The File Header Node is currently locked.
120 Error occurred during execution of a VA FileMan hook.
202 An input parameter is missing or not valid.
205 The File and IENS represent different subfile levels.
301 The passed flags are unknown or inconsistent.
302 Entry already exists.
304 The IENS lacks a final comma.
307 The IENS has an empty comma-piece.
308 The IENS is syntactically incorrect.
310 The IENS conflicts with the rest of the FDA.
311 The new record lacks some required identifiers.
330 The value is not valid.
351 FDA Node has a bad IENS.
352  The new record lacks a .01 field.
401 The file does not exist.
402 The global root is missing or not valid.
403 The file lacks a header node.
405 Entries in file cannot be edited.
406 The file has no .01 field definition.
407 A word-processing field is not a file.
408 The file lacks a name.
501 The file does not contain that field.
502 The field has a corrupted definition.
510 The data type cannot be determined.
520 That kind of field cannot be processed by this utility.
601 The entry does not exist.
602 The entry is not available for editing.
603 The entry lacks a required field.
630 The field value is not valid.
701 The value is not valid for that field.
703 The value cannot be found in the file.
712 The value in that field cannot be deleted.
730 The value is not valid according to the DD definition.
740  New values are invalid because they would create a duplicate key.
742  Deletion was attempted on a key field.
744  A key field was not assigned a value.
746  The K flag was used, but no primary key fields were provided in the FDA for Finding and LAYGO Finding nodes.

The Updater may also return any error returned by:

Details and Features

Adding Nodes let applications create new entries in a file. In the place of the actual IENS subscript for the new record in the FDA array, the application instead uses a unique value consisting of a + followed by a positive number.

"+#" will ALWAYS add without regard to duplication.

Thus, for example, an FDA of "FDA(42)" might be accompanied by the following array:

    FDA(42,19,"+1,",.01)="NAME OF OPTION"
FDA(42,19,"+1,",1)="MENU TEXT OF NEW OPTION"

The FDA_ROOT value directs the Updater to the FDA(42) array, whose format instructs the Updater to add one new entry to the Option file and two new entries to the Menu multiple of that entry.

NOTE: The sequence number for each new entry to be added to a file or subfile must be unique throughout the FDA. 

Adding -- Identifiers and Keys 

The FDA for a new record MUST include the .01 field, all of the required identifiers, and all key fields. If any of these needed fields is missing, the entire FDA transaction fails; none of the entries is added if any one lacks required data.


Filing Nodes let the application file new data under existing entries. This may be necessary to complete a logical record addition. Any FDA node whose IENS subscript consists solely of record numbers and commas is considered a Filing Node. If you know all of the record numbers, (that is, if all of the nodes in your FDA are Filing Nodes), you should use the Filer instead of the Updater to file the data.

For example, FDA(42,19,"408,",1)="NEW MENU TEXT" instructs the Updater to update field 1 of record 408, so no actual record creation takes place as a result of this node.


Finding Nodes let applications work with existing entries for which the application does not yet have a record number. Instead of +#, the application uses the notation ?# to stand in for an unknown record number. The sequence number that follows the ? must be unique throughout the FDA.

Every FDA of this type must include an FDA node for the .01 field, or, if the K flag is passed, nodes for at least one field in the primary key. The value of this FDA node is used to perform a lookup on the file. It must match only one entry in that file; ambiguity or failure to find a match is an error condition. The record number found will then be used for this FDA entry. 

For example the following FDA adds a new menu item to the ZTMMGR menu and changes the menu's text:

FDA(42,19,"?1,",1)="New Menu Text"

In this example, the Updater first uses the value ZTMMGR in a lookup to find the record number that replaces ?1. It then adds a new entry to subfile 19.01 under that entry, and changes the menu text of the option to "New Menu Text". The first node shown is a Finding Node that specifies the value of the .01 field to be used for lookup. The next node specifies a new value for field 1, the menu's text. The last two nodes are Adding Nodes that specify the values for fields .01 and 2 of the new menu item.

When the E flag is used, the .01 Finding node can equal any valid input value for the Lookup. For example, to pick based on a set of codes where WA stands for WASHINGTON, when using the E flag, you may enter WASH.

However, when the E flag is NOT used, the .01 Finding node must equal an internal value, though the special lookup values -- space-bar and accent grave (`) concatenated with the IEN -- will still work.. So for example, a .01 Finding node equal to WASH would return an error in the above scenario if the E flag were not passed. To succeed, the .01 Finding node would need to equal WA, the internal value.

LAYGO Finding

LAYGO Finding Nodes let the application refer to entries that may or may not already exist. If they do exist, the Updater finds and uses their record numbers. If not, the Updater adds the entries. The IENS notation used to stand in for these entries is ?+#. # is a unique positive number which acts as a placeholder until an actual internal entry number can be produced by the Updater.

For example, this call expects to find the option ZTMMGR, but adds it if it's missing:


The IEN Array node for this entry includes an extra zero node equal to ? or + to identify whether the entry was found or added. For example, if the entry for the previous example was found, the IEN Array node for this FDA might look like this:


All LAYGO Finding Nodes are processed in order after Finding Nodes and before other kinds of nodes.

Like Finding Nodes, .01 LAYGO Finding Nodes must match the format of the overall call: external if the E flag has been passed, internal if not. See the "Finding" section for details.

Sequence Numbers

A positive number which acts as a placeholder to identify a record until an actual internal entry number can be created or found by the Updater. This positive number must be unique throughout the FDA array. For example, if "+1," is used in an FDA, you cannot also use "?1," or "?+1".


Reviewed/Updated: March 10, 2007