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

(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).

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.

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"    
    FDA(42,19.01,"+2,+1,",.01)=45 
    FDA(42,19.01,"+2,+1,",2)="TM" 
    FDA(42,19.01,"+3,+1,",.01)=408  

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. 

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,",.01)="ZTMMGR" 
    FDA(42,19,"?1,",1)="New Menu Text"
    FDA(42,19.01,"+2,?1,",.01)=45 
    FDA(42,19.01,"+2,?1,",2)="TM"

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

    FDA(42,19,"?+1,",.01)="ZTMMGR"
    FDA(42,19.01,"+2,?+1,",.01)=45 
    FDA(42,19.01,"+2,?+1,",2)="TM"

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:

    IEN(1)=388
    IEN(1,0)="?"
    IEN(2)=9 

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.

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".