VA FileMan V. 22.0 Programmer Manual Banner


Main Chapter Getting Started Manual Advanced User Manual

ScreenMan Forms

Field Properties

Field Type

(Required) Four different types of fields can be defined on a block:

Caption-only fields are for displaying text on the screen. They have no data portion associated with them.

Data dictionary fields correspond to fields in a file. They have a data portion, which is the value of the field, and an optional caption portion, which serves to identify the data on the screen for the user.

Form-only fields are fields that are defined only on the form and are not tied to a field in a FileMan file. See the "Form-only Fields" section for more information about this field type.

Computed fields, like form-only fields, are fields that are defined only on the form. You cannot place computed fields from FileMan files on a form. The computed expression is defined on the form and can be based on other fields on the form. Users cannot navigate to computed fields.

Field Order

(Required) The Field Order number determines the order in which users traverse the fields in the block as they press the Enter/Return key. Field Order is the .01 field of the Field multiple of the BLOCK file.


(Required for Data Dictionary type fields.) The Field property applies only to data dictionary type fields. It identifies a field in a VA FileMan file or subfile. The DD Number of the block identifies the file or subfile that contains the field.

Unique Name

You can optionally give fields on a block a Unique Name. Unique Names are never seen by the user. They can be used to identify fields in some of the ScreenMan utilities, such as PUT^DDSVAL and $$GET^DDSVAL, and in the computed expressions of computed fields. No two fields on a block can have the same Unique Name.

Caption, Executable Caption, and Suppress Colon After Caption

A Caption is uneditable text that appears on the screen. Captions of data dictionary, form-only, and computed fields serve to identify for the user the data portion of the fields. Captions of these types of fields are automatically followed by a colon, unless the Suppress Colon After Caption property is set to YES. Captions of caption-only fields have no associated data element and are not automatically followed by a colon.

If you want the text of a caption to be determined whenever the page is painted, you can enter M code as an Executable Caption. The code should set the local variable Y equal to the text you want displayed. A field with an Executable Caption must have "!M" as a Caption.

Default and Executable Default

You can assign a Default to a Data Dictionary or form-only type field on a form. ScreenMan presents the Default value to the user if the value of the field is null when the page on which the field is located is first displayed. Since ScreenMan validates the Default, it must be valid, unambiguous, and in external form; otherwise, it is not used.

If the field is a multiple field, you can assign one of the following defaults:

Valid Default Values for Multiple Fields
Default Subrecord displayed
FIRST The subrecord with the lowest IEN
LAST The subrecord with the highest IEN
Subrecord number The subrecord with the specified IEN

Here, the characters "FIRST" and "LAST" are keywords that ScreenMan interprets as the subrecords with the lowest and highest IENs, respectively.

If the value of the default should be determined at the time the page is first presented to the user, you can enter M code as an Executable Default. The code should set the local variable Y equal to a valid, unambiguous value in external form. If the default in Y is invalid, it is not used. A field with an Executable Default must have "!M" as a Default.

Data Length

(Required for all field types, except caption-only.) Data Length defines the length of the edit window for the data portion of fields. Ideally, the Data Length should equal the maximum length of the external form of the data - the form displayed to the user.

The Data Length of a word processing field need only be 1, since the contents of the field are not displayed in the edit window. A Data Length of 1 gives the cursor a place to rest when the user navigates to the field. When the user presses the Enter/Return key at the field, control is passed to the user's Preferred Editor, where the text can be displayed and, if allowed, edited.

If you define a Data Length smaller than a field's maximum size, ScreenMan still provides two ways for the user to see the entire value of the field:

NOTE: You cannot define an edit window that wraps around to a second line. In addition, the edit window must not extend into the rightmost column of the screen. This space must be left blank so that the cursor has a place to rest beyond the last character of the data value. You must, therefore, never define a data length that causes the edit window to extend beyond the next to last column of the screen -- that is, column 79 on an 80-column display.

Caption and Data Coordinates

(Required if a field has a caption or data portion.) Caption and Data Coordinates define the location of fields on the screen and are relative to the coordinate of the block on which they are defined. The format of coordinate is: Row,Column. The coordinate "1,1" for example, corresponds to the block's top left corner - the first column on the first row of the block.

The Form Editor greatly simplifies the process of assigning coordinates to captions and data. It allows you to drag and drop fields on the screen, and thus eliminates the need to explicitly assign values to the coordinate properties.

Right Justify

Set the Right Justify property to YES to display the data for the field to be right-justified.


You can make any non-multiple field on a form required. Making a field required on a form does not affect the definition of the field in the data dictionary. You need not make a field required that is already required by its data definition. The captions of required fields are underlined for easy identification. See the "Data Filing" section for more information on how ScreenMan checks required fields before filing.

Before filing, ScreenMan checks that:

If any required field is empty, the user cannot file any data changes. When they attempt to file, ScreenMan displays a list of those fields that require values.

NOTE: "Pop-up" pages NOT accessed during the editing session will not be checked for Required fields.

You can change the Required property on the fly while a form is running by making a call to REQ^DDSUTL. See that section for more information on this call.

Display Group

Display group helps users resolve ambiguity when they attempt to ^-jump to a field that has a caption that is not unique. If more than one field has the same caption, when users try to ^-jump to a field with that caption, they are presented with a list of fields to choose from. The text in the Display Group property is displayed in parentheses after the caption to help the user identify the correct field.

For example, if two fields have the caption "NAME:", but one of those fields has a Display Group "Next of Kin," when users enter ^NAME, they will be asked to choose between "NAME" and "NAME (Next of Kin)".

Disable Editing and Disallow LAYGO

If you set the Disable Editing property to "YES," users cannot navigate to the field, unless the field is a word processing field. If the field is defined as uneditable in the Data Dictionary, users cannot navigate to it - even if the field's value is null. See the "Word-processing Fields" section in the "VA FileMan Getting Started Manual" for information about uneditable word processing fields.

If you set the Disable Editing property to "REACHABLE," users can navigate to the field, but they cannot change the value. You might want to make an uneditable field reachable if, for example, you want to attach branching logic to that field, to take the user to another page when they press the Enter/Return key. You might also want to make an uneditable field reachable if the data value cannot fit in an edit window. Then the user can navigate to the field and see the entire contents of the field, either by scrolling the data in the edit window or by invoking the "zoom editor."

You can change Disable Editing property on the fly while a form is running by making a call to UNED^DDSUTL. See this section for more information on this call.

NOTE: Fields on display blocks are always uneditable. On display blocks, users can navigate only to multiple and word processing fields.

Disabling editing for multiple fields has no meaning. However, you can prevent users from adding new entries into a multiple by setting the Disallow LAYGO property to YES. Multiple fields on display blocks automatically prohibit LAYGO.

Data Validation

ScreenMan uses the definition of a field to automatically validate values input by the user. You can use the Data Validation property to validate the value even further. Data Validation is M code that is executed after the user enters a new value for a field and after the automatic validation that ScreenMan normally performs. If the code sets the variable DDSERROR, ScreenMan rejects the value. You might also want to ring the bell and make a call to HLP^DDSUTL to display a message to the user that indicates the reason the value was rejected.

Subpage Link

A subpage can be linked to a parent page by the Subpage Link property. The Subpage Link must be equal to the Page Number of the subpage.

Branching Logic, Pre Action, Post Action, and Post Action on Change

These properties contain M code that is executed at the following times:

Descriptions of Field-level Pre and Post Actions
Property Executed
Branching Logic When the user presses the Enter/Return key at the field
Pre Action Right before the user lands on the field
Post Action When the user leaves the field
Post Action on Change When the user leaves the field, and only if the user changed the value of the field

The code in the Branching Logic, Pre Action, Post Action, Post Action on Change, and Data Validation at the field level can rely on the following variables:

Variables Available in Field-level Pre and Post Actions
Local Variable Description
X The current internal value of the field
DDSEXT The current external value of the field
DDSOLD The previous internal value of the field

The Post Action and Post Action on Change are not executed when the user times out at a field, enters an ^ to go to the Command Area, or ^-jumps to another field.


Reviewed/Updated: March 14, 2007