ScreenMan Forms

Field Properties

• Field Type
  
  
• Field Order
  
  
• Field
  
  
• Unique Name
  
  
• Caption, Executable Caption, and Suppress Colon After Caption
  
  
• Default and Executable Default
  
  
• Data Length
  
  
• Caption and Data Coordinates
  
  
• Right Justify
  
  
• Required
  
  
• Display Group
  
  
• Disable Editing and Disallow LAYGO
  
  
  
• Data Validation
  
  
• Subpage Link
  
  
• Branching Logic, Pre Action, Post Action, and Post Action on Change

Field Type

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

• Caption only—Used to display text on the screen. They have no data portion associated with them.
  
  
• DATA DICTIONARY—Correspond to fields in a file. They have the following:
  • A data portion, which is the value of the field.
    
    
  • An optional caption portion, which serves to identify the data on the screen for the user.
  
  
• Form-only—Defined only on the form and are not tied to a field in a VA FileMan file.

  REF: For more information about this field type, see the "Form-only Fields" section.

  
  
• COMPUTED—Like Form-only fields, COMPUTED fields are defined only on the form. You cannot place COMPUTED fields from VA 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 key. Field Order is the .01 field of the Field Multiple of the BLOCK (#.404) file.

Field

(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. A Unique Name is 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 defaults listed in Table 84:

Table 84: ScreenMan Forms—Valid Default Values for Multiple Fields

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 (i.e., 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 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:

• Since the edit window is a "scrolling window," text outside the confines of the edit window can scroll in, as text in the window scrolls out.
  
  
• When the cursor is within an edit window, the user can press <PF1> Z to invoke the "zoom editor." An area opens in the Command Area where up to 245 characters can be seen and edited at once.

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 (i.e., 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 (i.e., the first column on the first row of the block).

The Form Editor 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.

REF: The Form Editor is described in detail in the "ScreenMan Form Editor" section.

Right Justify

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

Required

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.

REF: For more information on how ScreenMan checks Required fields before filing, see the "Data Filing (When Is It Performed?)" section.

Before filing, ScreenMan checks that:

• Required fields on all pages that can be accessed via the Next Page and Previous Page links have values, even if you have not accessed those pages during the editing session.
  
  
• If you have accessed any subpages, required fields in those subpages must also have values.

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: "Popup" pages not accessed during the editing session are not 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.

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 from which to choose. 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 are 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 (DD), users cannot navigate to it—even if the field's value is NULL.

REF: For information about uneditable WORD-PROCESSING fields, see the "Word-processing Fields" section in the VA FileMan User Manual.

If you set the Disable Editing property to "REACHABLE," users can navigate to the field, but they cannot change the value. For example, you might want to make an uneditable field reachable if you want to attach Branching Logic to that field, to take the user to another page when they press the Enter 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 the Disable Editing property on-the-fly while a form is running by making a call to UNED^DDSUTL.

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 DDSERROR variable, 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 times listed in Table 85:

Table 85: ScreenMan Forms—Descriptions of Field-Level Pre and Post Actions

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 variables listed in Table 86:

Table 86: ScreenMan Forms—Variables Available in Field-Level Pre and Post Actions

The Post Action and Post Action on Change are not executed when the user:

• Times out at a field.
  
  
• Enters a caret (^) to go to the Command Area.
  
  
• Enters a ^-jumps to another field.

Reviewed/Updated: May 2026