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

If the flag is not set, values must be in VA FileMan internal format and must be valid; no validation or transformation is done by the Filer, but key integrity is enforced.

LocKing is done by the Filer. (See discussion of Locking.)

Save FDA. If this flag is not set and there were no errors during the filing process, the FDA is deleted. If this flag is set, the array is never deleted.

Transaction is either completely filed or nothing is filed. If you use the "T" flag, you must also pass the "E" flag, and pass values in external format. If any value is invalid, nothing is filed, and the error array specifies which fields were invalid.

Without this flag, valid values are filed and only the invalid ones are not.

If neither the T nor the U flag is sent, simple keys are checked as they are encountered in the FDA. Compound keys are checked only after the entire record is filed. If the key is invalid, changes to fields making up that key are backed out.

Do not enforce key Uniqueness or completeness. Without the U flag, the values in the FDA are checked to ensure that the integrity of any key in which an included field participates is not violated.

CAUTION: If this flag is used, the FILE^DIE API call can result in records that contain NULL key fields or records with duplicate keys. It is the developer's responsibility to ensure that the database is not left in a state in which the integrity of keys is violated.

(Required) The root of the FDA that contains the data to file. The array can be a local or global one. The root is the closed array reference to be used with subscript indirection not the traditional VA FileMan root.

REF: For details of the structure of the FDA, see the "Introduction" section in the "Database Server (DBS) API" section.

(Optional) The root of an array (local or global) into which error messages are returned. If this parameter is not included, error messages are returned in the default array-^TMP("DIERR",$J).

The Filer does not check user access when filing. This check must be done by the client application.

You can delete the value in a field by setting the value for the field equal to NULL or @.

This works for WORD-PROCESSING fields, too. Instead of setting the value for the field equal to the root of the array where the new word-processing text is to be found, set it equal to NULL or @.

NOTE: When the E (external) flag is used, you cannot delete the field value if the field is either Required or Uneditable. Without the E flag, deletion occurs in both cases. When key integrity is checked (the U flag is not used), you cannot delete the value of a key field whether the E flag is used or not.

You can delete an entire entry or subentry by setting the value of the .01 field to @ or NULL. In this case, it does not matter whether the .01 field is Required, Uneditable, or a key field.

The Filer never asks for confirmation of the deletion.

Data passed to the Filer should comprise one logical record. Thus, the data can consist of values for fields in the primary file and its Multiples and in related files. ("Navigation" to other files is handled by the calling application, not by the Filer.)

New-Style indexes that have an execution value of RECORD are fired once after all the data for a single record or subrecord is filed.

All other cross-references (and data audits) are fired as the data is filed (i.e., on a field-by-field basis).

Any possible conflict between the cross-reference and updated data must be noted by the client application and resolved by modifying the cross-reference. The most common situation in which conflicts can arise is when a cross-reference (most frequently a trigger or MUMPS cross-reference) has been used to provide information to the user while data is being edited. Default values that are dependent on the values of other fields being edited can be provided in this way. These "user interface" cross-references are fired by the Filer with the rest of the cross-references after the data editing is complete. Thus, they cannot have the desired effect of providing the user with information during the editing session. However, they can have the undesired effect of overwriting user-entered values. This type of cross-reference must be removed from the DD as part of the preparation for using the DBS. Also, if the functionality provided by these cross-references is still desirable during the editing session, the client application needs to provide it.

If requested, the Filer incrementally locks records and subrecords before beginning to file any data. If a lock on any record fails, no filing is done, and an error message is returned to the calling program.

It is recommended that locking be done outside of the Filer by the client application. There are several reasons for this:

• It can be frustrating to the user to edit a screen's worth of data and then to have the SAVE fail, because the necessary lock could not be obtained.
  
  
• Data successfully validated can become invalid before it is filed.
  
  
• The client application can more selectively determine which records to lock. Of necessity, the Filer locks all entries and subentries referenced in the FDA passed to it. In many instances, this is more than is required.
  
  
• Locking inside the Filer requires additional processing that slows the filing action down.

However, there are situations in which it is appropriate for the Filer to do the locking. For example, if only a single file is involved, and the source of the data is not an interactive editing session.