VA FileMan V. 22.0 Programmer Manual Banner


Main Chapter Getting Started Manual Advanced User Manual

Classic VA FileMan API


This entry point adds a new entry to a file. The INPUT transform is not used to validate the value being added as the .01 field of the new entry. This call does not override the checks in the LAYGO nodes of the data dictionary; they must still prove true for an entry to be added.

FILE^DICN can also be used to add subentries in multiples. See the "Adding New Subentries to a Multiple" discussion in the description of ^DIC.

Variables to Kill

If DO is set, then FileMan assumes that all of the variables described as output in the call to DO^DIC1 have been set as well and that they describe the file to which you wish to add a new record. If you're not sure, then DO should be killed and the call will set it up for you based on the global root in DIC.

NOTE: This variable is D with the letter O, not zero.

Input Variables

The global root of the file.


(Required) A string of alphabetic characters which alter how DIC responds. At a minimum this string must be set to null. The characters you can include are:

E Echo back information. This tells DIC that you are in an interactive mode and are expecting to be able to receive input from the user. If there are identifiers when adding a new entry, for example, the user can edit them as the entry is added if the E flag is used.

Prevents saving the entry number of the matched entry in the ^DISV global. Ordinarily, the entry number is saved at ^DISV(DUZ,DIC). This allows the user to do a subsequent lookup of the same entry simply by pressing the space bar and the Enter/Return key. To avoid the time cost of setting this global, include an F in DIC(0).

Z Zero node returned in Y(0) and external form in Y(0,0).

NOTE: Beginning with Version 22.0 of VA FileMan, the developer is no longer required to set DIC("P").

The only exception to this is for a few files that are not structured like a normal VA FileMan file, where the first subscript of the data is variable in order to allow several different "globals" to use the same DD. An example of this is the VA FileMan Audit files where the first subscript is the file number of the file being audited. New/Updated with VA FileMan V. 22.0

Used when adding subentries in multiples. See description in ^DIC section.


Array of entry numbers. See the Adding New Subentries to a Multiple discussion in the description of ^DIC.


The internal value of the .01 field, as it is to be added to the file. The programmer is responsible for ensuring that all criteria described in the INPUT transform have been met. That means that the value X must be in internal format as it would be after executing the input transform. For example, a date must be in FileMan internal format '2690302', not 'March 02, 1969'. Also, local variables set by the input transform code must be set. For example, if the input transform sets DINUM, then DINUM must be set to the record number at which the entry must be added.


(Optional) Identifies the subscript at which the data is to be stored, that is, the internal entry number of the new record, shown as follows. (This means that DINUM must be a canonic number and that no data exists in the global at that subscript location.)


If a record already exists at the DINUM internal entry number, no new entry is made. The variable Y is returned equal -1.


(Optional) Used to input other data elements at the time of adding the entry. If the user does not enter these elements, the entry will not be added. The format of DIC("DR") is the same as the variable DR described under the discussion of ^DIE.

If there are any required Identifiers for the file or if there are keys defined for the file (in the KEY file), and if DIC(0) does not contain an E, then the identifier and key fields MUST be present in DIC("DR") in order for the record to be added. If DIC(0) contains E, the user will be prompted to enter the identifier and key fields whether or not they are in DIC("DR"). New/Updated with VA FileMan V. 22.0

Output Variables

DIC always returns the variable Y, which can be in one of the two following values:

Y=-1 Indicates the lookup was unsuccessful; no new entry was added.
Y=N^S^1 N is the internal number of the entry in the file, S is the value of the .01 field for that entry, and the 1 indicates that this entry has just been added to the file.

This variable is only set if DIC(0) contains a Z. When it is set, it is equal to the entire zero node of the entry that was selected.


This variable is also only set if DIC(0) contains a Z. When it is set, it is equal to the external form of the .01 field of the entry.


This is only defined if DIC has timed-out waiting for input from the user.


This is only defined if the user entered an up-arrow.

XNew/Updated with VA FileMan V. 22.0 The variable X will be returned unchanged from the input value.


Reviewed/Updated: March 10, 2007