VA FileMan V. 22.0 Programmer Manual Banner


Main Chapter Getting Started Manual Advanced User Manual

ScreenMan API


You can call this entry point directly from an M routine to invoke the specified form.

This routine invokes a ScreenMan form attached to the specified file. ScreenMan automatically uses incremental locks to lock all records accessed during an editing session.

Input Variables

(Required) The number or global root of the Primary File of the form.


(Required) The name of the form (an entry in the Form file) enclosed in square brackets.


(Optional) The record number of the file entry to display or edit. If DA is null or undefined, the form must either contain no data dictionary fields or have a Record Selection page, which is the first page ScreenMan presents to the user and is where the user can select a record from the file. (See "Example 2" when a subfile is being accessed directly.)


(Optional) The Page Number of the first page to display to the user. If '$G(DDSPAGE), a page with a Page Number equal to 1 must exist on the form and that is the first page ScreenMan presents to the user.


(Optional) A string of alphabetic characters that control ScreenMan's behavior are listed below:

C Return the variable DDSCHANG=1 if ScreenMan detects that the user saved a Change to the database.
E Return Error messages in ^TMP("DIERR",$J) and return DIERR if ScreenMan encounters problems when initially trying to load the form. If DDSPARM does not contain an E, ScreenMan prints messages directly on the screen, and returns the variable DIMSG equal to null.
S Return the variable DDSSAVE=1 if the user pressed <PF1>S or <PF1>E, or entered an "Exit" or "Save" command from the Command Line, whether or not any changes were actually made on the form.

If ^DDS is used to display or edit data in a subfile directly, the following variables must be set in addition to the variables listed above:


(Required) Contains the subfile number or the global root of the subfile.

DA(1) ... DA(n)

The DA array, where DA is the subrecord number at the deepest level and DA(n) is the record number at the top level.

All the input variables are returned unchanged by the ^DDS call. DDSFILE(1) should be killed when the call is complete to avoid conflict with subsequent ^DDS calls.

Output Variables

$G(DDSCHANG)=1, if the DDSPARM input variable to ^DDS contains a C and ScreenMan detects that the user saved a change to the database.


$G(DDSSAVE)=1, if the DDSPARM input variable to ^DDS contains an S and the user pressed <PF1>E or <PF1>S, or issued the "Save" or "Exit" command from the Command Line.


$D(DIMSG)>0, if the form could not be loaded, and the DDSPARM input variable to ^DDS does not contain an E. (See the description of the DDSPARM input variable.)


$D(DTOUT)>0, if the user times out during the editing session.

The DDS Variable New/Updated with VA FileMan V. 22.0

$D(DDS) can be checked within programming hooks such as Executable Help and Input Transforms to determine whether the hook is being executed from within a ScreenMan form. In that case, $D(DDS) evaluates to true.


Example 1

Invoke the form EE FORM1 to edit the 15th entry in file #16500, as shown below:

    >S DDSFILE=16500,DA=15,DR="[EE FORM1]" D ^DDS

Example 2

As shown below, invoke the form EE FORM2 to edit the 31st subentry in subfile #16100.01, for the 9th entry in file #16100; Page Number 11 is the first page to present to the user; and have ScreenMan return DDSCHANG if it detects a change to the database when the user exits:

    >S DDSFILE=16100,DDSFILE(1)=16100.01
    >S DA=31,DA(1)=9,DR="[EE FORM2]"
    >D ^DDS
Error Codes Returned

NOTE: Error codes are returned only if the DDSPARM input variable to ^DDS contains an E.

201 The specified input variable is missing or invalid.
202 One of the input variables is not properly specified.
405 Entries in the file cannot be edited.
810 At least one of the required ^%ZOSF nodes is missing.
840 The Terminal Type file does not have an entry that matches IOST(0).
842 At least one required piece of data in the Terminal Type file is null for the terminal type identified by IOST(0).
845 A call to HOME^%ZIS returns $G(POP)>0.
3021 The specified form does not exist in the Form file, or DDSFILE is not the Primary File of the form.
3022 The specified form contains no pages.
3023 The form does not contain the specified page.


Reviewed/Updated: March 4, 2007