VA FileMan V. 22.0 Programmer Manual Banner


Main Chapter Getting Started Manual Advanced User Manual

Database Server (DBS) API

IENS: To Identify Entries and Subentries

The way to represent internal entry numbers for entries in the database is by a structure called an Internal Entry Number String (IENS). It is FileMan's way of representing the internal entry numbers for an entry in all of the DBS calls.

An IENS is a comma-delimited list of internal entry numbers beginning with the lowest level subentry and ending with the top-level entry number. Regardless of how many levels exist, a "," is appended to the end. For example, to specify subentry 2 in a multiple for entry 250, IENS would equal "2,250,". The corresponding values for the DA() array would be DA=2 and DA(1)=250 (or D0=250 and D1=2). If you were referencing the top level of the file, the IENS would be "250,"; DA=250 or D0=250. There are calls that can be used to construct an IENS from a DA() array and a DA() array from an IENS-see descriptions of DA^DILF and $$IENS^DILF.

In the simplest case, each comma-piece of the IENS is a number that directly and uniquely identifies an entry in a file or subfile. However, sometimes the client application does not know the entry number. For example, often the entry number is unknown when a call to the Updater is being made. In other situations, the client application wants the DBS to find a record and then file data in it; the entry number is unimportant to the client. In order to accommodate these circumstances, certain placeholders can be used in the IENS if the particular DBS call supports their use. The extended IENSs (those including a placeholder) are not accepted for all DBS calls. The calls that accept the extended IENSs are identified in the call's documentation.

The placeholder consists of a one- or two-character code identifying how you want the entry number derived, followed by a positive integer. The integer uniquely identifies the record involved in different nodes of the FileMan Data Array (FDA), as described below. The codes are:

Placeholder Code Description
+ Add a new entry or subentry.
? Find an entry or subentry and use it for filing.
?+ Find an entry or subentry; if one does not exist, add it (LAYGO).

Thus, if you wanted to find an entry and then to add a new subentry into that entry, your IENS might look like: "+2,?1,". Every time you referenced that top-level entry in your FDA, you would use "?1"; every time you referenced that particular subentry, you would use "+2". A second new subentry might be "+3", and so on. See the descriptions of the Updater and Finder calls for more information about using the entry number placeholders.


Reviewed/Updated: March 14, 2007