VA FileMan V. 22.0 Programmer Manual Banner


 

Main Chapter Getting Started Manual Advanced User Manual

Database Server (DBS) API


FILE^DIE( ): Filer

This procedure:

OR:

If the data to be filed is in external format, you can specify that nothing will be filed unless the values for every field being filed are valid. (Use the T and E flags).

Uniqueness and completeness of keys are enforced (unless the U flag is used). This check is performed on values passed in both internal and external formats.

The associated functions of firing cross-references and of performing data audits are also performed.

NOTE: The Filer only files data into existing entries and subentries. To add new entries or subentries, use the UPDATE^DIE call.

Format
FILE^DIE(flags,fda_root,msg_root)
Input Parameters
FLAGS

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

E New/Updated with VA FileMan V. 22.0External values are processed. If this flag is set, the values in the FDA must be in the format input by the user. The value is validated and filed if it is valid.

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

K

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

S

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.

T

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

U

New/Updated with VA FileMan V. 22.0 Don't 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 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.)

fda_root

(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 FileMan root. See the "Database Server Introduction" for details of the structure of the FDA.

msg_root

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

Output

Ordinarily the "output" of this call is the updating of the database. Error messages and information supplied via EN^DDIOL are returned in the standard array in ^TMP or in the array specified by msg_root.

Error Codes Returned

This call returns error messages in many circumstances. Most of the messages report bad input parameters or input to a file, field, or record that does not exist. Primary user-oriented codes include:

110 Record is locked.
120 Error occurred during execution of a FileMan hook.
701 Input data was invalid.
712 Deletion was attempted but not allowed.
740 New/Updated with VA FileMan V. 22.0 New values are invalid because they would create a duplicate key.
742 New/Updated with VA FileMan V. 22.0 Deletion was attempted on a key field.
744 New/Updated with VA FileMan V. 22.0 A key field was not assigned a value.
Details and Features
Security

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

Deleting data

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 can't 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 can't 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 the .01 field is Required, Uneditable, or a key field.

The Filer never asks for confirmation of the deletion.

Scope of a Single Filer Call

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

Cross-references

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

All other cross-references (and data audits) are fired as the data is filed, that is, 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 which 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 their desired effect of providing the user with information during the editing session. However, they may 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 will need to provide it.

Locking

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 may 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 may 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 actually 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.

 


Reviewed/Updated: March 10, 2007