VA FileMan V. 22.2 Programmer Manual Banner


 

Main Chapter Getting Started Manual Advanced User Manual

Classic VA FileMan API


Introduction

Certain modules within VA FileMan are callable by other M routines. This is true of these Classic VA FileMan routines, which are referred to as "Callable Routines" and are described in this section.

Database Server (DBS) calls are also callable by other M routines. However, these "silent" calls differ from the Classic VA FileMan routines in that they separate interaction with the database from interaction with the end-user. In Classic VA FileMan's roll-and-scroll mode, interaction with the end-user was closely tied to the code that changed the database, but with VA FileMan's DBS calls no WRITEs to the current device are done. Interaction with the user is managed by package developers from within their own code, calling VA FileMan whenever interaction with the database is needed.

REF: These DBS calls are described in the "Database Server (DBS) API" section.

When using both the Classic VA FileMan callable routines and the DBS calls, you must keep in mind the variable-naming conventions. If you have local variables that you wish to preserve by a call to any of the routines described here, you should be sure to give them multi-character names beginning with letters other than D.

It is the developer's responsibility to clean up (KILL) both documented and undocumented input and output variables used in a VA FileMan call when the call is finished. The few situations in which your input variables are KILLed during the VA FileMan call are mentioned in the following sections. Developers also need to be alert to the fact that Classic VA FileMan APIs are not recursive. A classic example is the situation where your routine is being called from a cross-reference, the client, and you want to alter the contents of other fields either within the parent file or fields outside the parent file, in which case the developer would use the proper Database Server (DBS) call.

After making an API call, always check for failed calls. For example, when using ^DIC for lookups, always check for the error condition Y=-1 before doing anything else; when using the reader, always check DUOUT, DIRUT, and DTOUT before doing anything else. When a call provides a way to check for error conditions, it means that there are some circumstances where the call fails! Checking for errors after such a call allows you to handle the errors gracefully.

CAUTION: Programmer access in VistA is defined as DUZ(0)="@". It grants the privilege to become a developer in VistA. Programmer access allows you to:

It is important to proceed with caution when having access to the system in this way.

 


Reviewed/Updated: June 2026