VA FileMan V. 22.0 Programmer Manual Banner


Main Chapter Getting Started Manual Advanced User Manual

Filegrams API

^DIFG: Installer

The Filegram process consists of the following three components:

  1. Filegram generator (the DIFGG routines)

  2. Filegram installer (the DIFG routines)

  3. FILEGRAM template (stored in the PRINT template file)

You, as a programmer, will find that the only routines necessary to process a Filegram are the installer and the generator routines.

The key variables DUZ, DUZ(0), and DT must be present in addition to the required variables described below.

Use the ^DIFG entry point to install Filegrams. The installer part of the Filegram requires the DIFGLO variable in addition to the VA FileMan key variables mentioned just above. The other input variables are optional.

D ^DIFG will install the Filegram.

Input Variables

(Required) This variable must be the global root of the Filegram to be installed.


(Optional) If this variable is defined, a new entry will be created in the base file.


(Optional) Entry number in base file at which new file entry, if added, will be created.

Output Variables

This output variable is defined if an error has occurred.

NOTE: It will be defined even if the install fails after the base file has been processed. Thus, it could exist even if DIFGY is not equal -1. See below for a list of error codes that will be found in DIFGER.


^DIFG always returns DIFGY. DIFGY can have one of the following values:

DIFGY=-1 Indicates that the lookup on the initial file processed (the base file) was unsuccessful.
DIFGY=N^F Where N is the internal number of the entry in the base file and F is the base file's number.
DIFGY=N^F^1 Where N and F are defined as above and 1 indicates that a new entry has been added to the base file.
Error Codes Returned in DIFGER

If a soft error occurs, the variable DIFGER is defined when the Filegram routines are exited. This variable contains information about the problem encountered. It consists of two ^-pieces. The first piece indicates the error number. The second piece usually contains a line number in the Filegram that indicates where the Filegram process failed.

Here is a list of the codes found in DIFGER along with their specific meanings:

1^0 The Filegram global root was not passed in DIFGLO.
1.25^0 The Filegram global root format is invalid.
1.5^0 The Filegram global root is passed but the global does not exist.
2^1 The first line of the Filegram does not contain a $DAT.
3^# A line other than the first line has a $DAT as its first colon-piece.
4^# The field does not exist within this file.
5^# ^%DT was called and Y was returned equal to -1.
6^# Line after a context switch, subfile; and any field that required a lookup was not a BEGIN condition.
7^# DINUM variable exists, the mode is A or L, and the INPUT transform contains the word DINUM (files or subfiles only).
8^# DINUM or DIADD variables exist and the mode is neither A nor L (files or subfiles only).
9^# File or subfile lookup failed and mode type will not permit addition of an entry to this file. In other words, the mode type was either D or M.
10^# Lookup failed during a context or subfile shift, the .01 field of the file or subfile is a pointer, and LAYGO to the pointed-to file is not allowed. This code is also generated if lookup failed and LAYGO is not allowed for a pointer that is an identifier or specifier.
11^# A lookup for a single valued pointer field fails and LAYGO is not allowed.
12^# A lookup failed for a file or subfile and the mode is M.
13^# There is a key for a given entry and the internal entry number was not found in the cross-reference or the cross-reference did not exist.
14^# ^DIE called for a MODIFY or DELETE Filegram and Y was returned defined.
15^# ^DIE called for an entry which was an ADD and Y was returned as defined.
16^# Call to ^DIC or FILE^DICN and Y was returned equal to -1. Error occurred during installation.
17^# Entry of a word processing field failed.
18^# Lookup failed when a "B" index lookup was specified and the B cross-reference did not exist.
19^# DINUM was passed to DIFG, the mode of the base line file was M or D, and the entry did not exist in the base line file.
20^# File does not exist.
21^# A field has an "@link" value which is unresolved and will not be LAYGOed to the pointed-to file during installation.


Reviewed/Updated: March 10, 2007