Running an Init on Target System (10 of 16)
Installing Data
Next, the init brings in data that was sent with the files.
Depending on the developer's specifications, incoming data either
overwrites or merges with data existing on the target system. In either case,
if an incoming entry or subentry doesn't exist on the current system, one will
be added. If an existing entry or subentry is found and if data is to be
overwritten, each field's value will be replaced with non-null incoming values.
Null values will not overwrite existing values. If data is to be merged, only
those fields with null values will be updated with incoming values. Hence, when
merging, new values will be added without altering any pre-existing ones.
Since the installation of data is dependent on whether or not an
incoming entry or subentry already exists on the target system, the init must
determine if they are the same. The process, described as follows, is repeated
for each incoming entry or subentry:
- Checking the B Cross-Reference or Zero Node
The B
cross-reference holds the entry's name (.01 field) along with the internal
entry number. If a B cross-reference exists for the file, it is searched for an
existing value that matches the incoming one. (The B cross-reference holds the
name as a subscript.) The maximum length of subscripts is defined for each
operating system and is stored in the MUMPS OPERATING SYSTEM file (#.7). The
init uses this length, for example, 63 (default) or 99 as the limit of
characters to compare.
Files occasionally lack a B cross-reference. In
this case, the init examines the actual data (first piece of the entry's zero
node) for a match of values.
If a match (either of the B cross-reference
or of the first piece of the zero node) is not found, the incoming entry is
considered new and is added to the file. If a match is found, additional checks
(discussed below) are made to determine whether the entries may be
associated.
- Using the Internal Entry Number to Verify a Match
Once
a match of the .01 fields of the incoming and existing entries is found, the
init determines whether the internal entry numbers of the two entries are
related. If the file has a defined .001 field, internal entry number is a
meaningful attribute of an entry. In this situation, when the name and internal
entry numbers match, identifiers are checked to verify the match.
If the
INPUT transform of the .01 field contains DINUM, it operates in the same way as
a .001 field. In this case, the .01 field and the internal entry number must
match for the entries to be considered the same.
After a match is
established based on the .001 field (or DINUMed .01
field), the identifiers are checked. If the identifiers for the two entries
are the same, the entries are considered the same. If the identifiers do not
match, the new entry is not installed at all.
- Using Identifiers to Verify a Match
If the file is not
referenced by number (i.e., .001 field does not exist) and there are duplicate
B cross-references or entries in the file with duplicate .01 fields, the init
cannot resolve the ambiguity without identifiers. A well-designed file uses one
or more identifiers so that each entry is unique with respect to name and
identifiers. If the file lacks identifiers and a .001 field, the init will
associate the incoming entry with the first existing entry with a matching
name.
If identifiers exist, the init gets the global location of the
identifier (piece position) from the data dictionary and uses indirection to
retrieve the identifier's value from the ^UTILITY storage global. This value is
then compared with the existing entry's identifier value for a match. Only
identifiers that have valid field numbers are used in this process.
The
init matches identifiers in the same way it matches .01 fields. If the values
of all the incoming identifiers match the existing ones, the two entries are
considered to be the same. If the values don't match, the possibility of
identity is rejected and the search continues. If none of the values for
existing entries matches the incoming entry, the incoming entry is considered
new and is added to the file. However, as mentioned above, if a
.001 field exists or the .01 field is DINUMed, the entry
is not installed if the identifiers differ.
Once the internal entry number on the target system for matching
entries is found, it is used to place the incoming data, either by merging with
or overwriting existing values.
NOTE: No audit trail is kept of data brought in by an init even
if the audit flag is on for a field receiving data.
Reviewed/Updated: March 4, 2007