The form governs the complete user interface to the application program. It is a specification that completely describes all screens that are to be shown on the display device,the data that is to be transferred between the form and the application program, and all form processing that is to occur. The form controls all details of the interaction with the operator.

A DECforms form is loaded by the Form Manager at execution time under the direction of an application program. The form contains data that can be viewed and modified by both the operator and the application program. The form also contains control information relating to overall control of the user interaction.

Figure 1.3, “Panel Objects” shows an example of a panel with objects.

Chapter 8, Form Structure contains additional details concerning form structure.

The program takes care of the data processing and computational aspects of the application, and interactswith the operator through the form by using the Form Manager.

Figure 1.4, “DECforms Interfaces” shows the basic DECforms interfaces.

1.2.2.3. Phases in Processing Requests

DECforms run-time processing of requests is primarily event-driven. Events are caused either by requests made by the application program to the Form Manager or by actions of the terminal or workstation operator. The Form Manager responds to these events with default actions. You can override these defaults by declaring in the form your own set of responses to selected events.

The Form Manager, when processing a request, follows a series of run-time phases, shown in Figure 1.5, “Run-Time Processing Phases”.

1. Request Initialization Phase

   During this phase, the Form Manager gets the names of any form record descriptions, identifies the data areas for the form records, and identifies the session. The SEND and RECEIVE requests each use one name for the form record description, whereas the TRANSCEIVE request uses two: one for the send part and one for the receive part.

2. Data Distribution Phase

   For SEND and TRANSCEIVE requests, the Form Manager moves the data from application program record fields to form data items by using the appropriate form record description.

3. Accept Phase

   During this phase, the screen becomes active and the operator can interact with the form. Form data is displayed to the operator within fields, and new data can be entered and validated.

   The Form Manager maintains an internal list (the activation list)of form elements (such as fields or icons) that are available for input. Only the current active item can accept input. When the text cursor is on a field, that field is the currently active item.

   By default, a RECEIVE request activates panels that contain the data required for the fields in the form record description named in the request. A TRANSCEIVE request activates the fields named by the form record description for the receive part of the TRANSCEIVE request. Mechanisms are available for overriding these default actions and manipulating the activation list explicitly within the form.

4. Data Collection Phase

   For RECEIVE and TRANSCEIVE requests, the Form Manager moves data from form data items to application program record fields by using the appropriate form record description.

5. Request Termination Phase

   For each request, the Form Manager sets a value in the return status variable, and returns control to the application program.

   The activation list is emptied at the completion of each request;at the beginning of each request, the activation list has no items in it.

For a more detailed description of the run-time phases, see the VSI DECforms Programmer's Reference Manual.

Because the form contains a lot of information to display on one screen, you will divide the form into two parts: one part for employee data and reason for reimbursement, and a second part for the trips data.

For the character-cell layouts, the electronic display will use two screens to display the form. You will create one main viewport and use it to display first a panel for header information, and then a panel for trips information.

In planning displays, it is important to keep in mind that the display must fit in the display area. For character-cell terminals, the display area is typically 24 lines and80 columns. For this example, you will use 22 lines for each of the two main panels, leaving 2 lines for displaying dynamic messages. You will use all 80 columns.

For DDIF layouts, you must consider the size and orientation of the paper you plan to use for printing. If you plan to use an online display facility such as the CDA Viewer, you might want to use the default size of the view area. The mileage reimbursement application will use standard A size paper (8 and a half inches by 11 inches) with portrait orientation.

The next step is to sketch out the overall look of the two displays, as shown in Figure 2.2, “Preliminary Sketch of Online Forms”.

When planning the user interface, you need to consider such aspects as the order of the display of each panel and what tasks the operator will perform. This requires a closer look at each panel.

In the mileage reimbursement application, the header panel will appear first, followed by the trips panel.

2.4.3.2. Operator Interaction with the Header Panel

You will create one field on the panel for each data item to be displayed. In addition to the fields on each panel,you need to be aware of what the operator will be doing and the default actions that DECforms provides.

The operator must navigate through the displayed panel from one field to another, entering data in each field. The cursor must appear at the correct locations on the screen, and the form must accept the data as it is input. When the operator has completed entering the data for all data items(each field is filled out), the operator will indicate that input is complete.

DECforms provides default key bindings for commonly used operations(called built-in functions) on the panel. DECforms also creates an internal activation list that determines how the cursor moves from field to field when the operator presses the function key.

For example, for the character-cell display,pressing Tab, Return, or Enter moves the cursor to the next item; this is called the NEXT ITEM built-in function. More specifically, pressing the function keys Tab, Return, or Enter causes the Form Manager to perform a built-in function response that moves the cursor to the next item on the activation list.

TRANSMIT is another built-in function. When the operator presses the appropriate function key for the TRANSMIT built-in function, TRANSMIT indicates that input is complete.

Because DECforms provides these functions automatically, all you need do is place an informational message on the panel so that the operator knows what to do.

Additional Information

By default, the order of the activation list (which is the order in which the NEXT ITEM built-in function moves to the next item)is the order in which the fields are listed in the form. In CCPED, this means the order in which they are created.

You can change this order later if necessary.

For a complete list of built-in functions, see the appendix on built-in functions in the VSI DECforms IFDL Reference Manual.

You can override built-in functions. For example, PF1-Return is the default key binding for the INSERT LINE built-in function for the character-cell layout. This function controls how the operator moves to the next line of the multiline ADDRESS field. For ease of use, you will use Return instead of PF1-Return.

Figure 2.3, “Final Header Panel Sketch for Character-Cell Display” shows the header panel for the character-cell display with the additional instructional information.

You will also create two associated help panels for a detailed explanation of the application. For information on the help panels, see Section 2.4.6, “Message and Help Panels”.

Additional Information

Notice that some of the text literals on the header panel are right-aligned (the colons (:) line up on the same column). In your own applications, left alignment is recommended for fields and text literals if you plan to use default fonts.

The trips panel allows the operator to enter specific trip data. The design for this panel demonstrates more DECforms features than the design for the header panel. First, consider the trip data in more detail, and then think about how the operator will interact with the panel.

2.4.4.2. Operator Interaction with the Trips Panel

On the trips screen display, the operator navigates through the fields,entering data for date, from, to, miles, and toll. The application computes the amounts and the subtotals,displaying them in the appropriate fields on the display:the operator cannot enter data into the amount and subtotal fields.

When the data is entered, the operator moves the cursor to buttons at the bottom of the panel. These buttons are icons on character-cell layouts. When the text cursor is on any one of the icons, pressing the Select key will cause the operation to proceed.

You will also provide some function keys for performing the operations elicited by pressing the buttons. The operator uses the buttons to compute totals, discard data if necessary, and, finally, record the data and exit the application. The operator can also display help information at any time.

Figure 2.4, “Final Sketch of Trips Panel” shows the final sketch of the trips panel with the additional buttons.

In addition to the two main panels, you need a message panel for displaying any error or brief informational messages.

You will also create two help panels for displaying additional information to help the operator.

DECforms supports one message panel for each layout and creates a default message panel and message viewport. By default, this message panel is located on the lowest line of the layout display. You will modify this message viewport so that it occupies the two lowest lines of the character-cell layout display.

The help panels will contain the information shown in Figure 2.5, “Sketch of First Help Panel” and Figure 2.6, “Sketch of Second Help Panel”. The first help panel, accessible from both the header and trips panels,describes the most important built-in and user-defined functions for the character-cell platforms. The second help panel, accessible from the first help panel, provides help on print files.

A graphic literal is a graphic object such as a line, polyline, or rectangle that forms part of the background for a panel.

Command> CREATE POLYLINE (3,1) (3,80)

Next you are going to create text literals and picture fields for the employee name, badge number, and cost center. A picture fieldis a one-line data field. You have the option of specifying input,output, or both formats for the picture field.

The address field will allow the operator to enter an address of up to three lines. For this field, you will create a text literal followed by a multiline text field.

You now need to make boldface some of the text literals. When you created the title for the header panel, you learned how to set display attributes before creating the text literal. The following task shows you how to modify display attributes after creating the text literals.

If you did not exit the FDE, the panel you just completed remains displayed in CCPED. If you exited and reentered the FDE, and then selected the Panel Editor,the blank help panel, HELP_PANEL, appears on the screen.

The trip data requires a multiply occurring set of data fields(for the date, from, to, miles, amount, tolls, and subtotal data).Before you can create the fields for this data, you must create a group to contain the set of data.

Command> CREATE GROUP TRIP OCCURS 36 VERTICAL DISPLAYS 12

This command specifies that you want to create a group containing36 instances (trips), 12 of which are displayed at a time vertically on the panel. The operator can scroll the display to enter information for more than12 trips. From the program's perspective, the group is a data structure containing an array of trip data.

You have completed specifying the fields for the TRIP group. Now you must specify the form data for these fields. When you use CCPED to create fields, CCPED creates form data for you. If you use a text editor, you must enter the IFDL code for the form data items (if it does not exist already)in addition to the code for the fields in the panel.

You also need to specify two local form data items: N, which represents the current occurrence of the TRIP group, and BLANK_DATE, which represents a zero-date. N is a numeric form data item that, during the accept phase, will receive the index of the occurrence of the group that is the current activation item. BLANK_DATE has a DATETIME(8) data type, corresponding with the data type for TRIP_DATE.

To create the final three picture fields for the trips panel, you will reenter CCPED to get more practice with that tool.

When you have a group, it is a good idea to draw a rectangle around the fields in the group to connect them visually.

Create a rectangle around the TRIP group by using either KP9 and KPminus or a CCPED command. If you need help, see Section 3.6.9, “Creating a Rectangle Literal”.

An icon can consist of text, graphic literals, or both, associated with a function response, so that when the operator presses a key(usually the Select key), the application causes something to happen.

When declaring functions, you associate particular keys or key sequences with a particular function name. Key names begin with the percent ( % ) sign, and key sequences, such asPF1-KP., are enclosed in parentheses.

For the complete list of DECforms key names, see the appendix on key names in the VSI DECforms IFDL Reference Manual.

You do not need to indent and capitalize as shown in the example. The Back Translator formats the text for you when you exit the FDE or when you explicitly invoke it with a FORMS command.

The operator triggers a function response by performing a function; for example, by pressing the Select key.

If you want the response to occur any time the operator performs the function, place the function response delaration at the layout level( after the function declarations and before the panel declarations).

If you want the response to occur only for a particular panel, field, or icon,place the function response within the panel, field, or icon declaration. A function response at a lower level supersedes a response for the same function at a higher level.

Section 4.3.2, “Order of Functions and Responses ” provides further information about the order of functions and responses.

The DISCARD function response calls an internal response called RESET_DATA,described later in this chapter.

The MOVE_UP function response specifies that if the cursor is not at the uppermost item on the panel, MOVE_UP moves the cursor up one item. Otherwise, MOVE_UP calls another response called BORDER_PATROL, described in Section 4.3.3, “Creating the Other Responses at the Layout Level”.

The MOVE_DOWN function response is similar to MOVE_UP, except that it moves the cursor down one item.

The PRINT_FILE function specifies a PRINT response step, which causes the Form Manager to create a print file or to print a file containing the trip data from the trips panel. In the character-cell layout, the Form Manager will create a text file called mrf_form.txt.

The next task is to create specific MOVE_UP and MOVE_DOWN function responses for the TRIP group. These responses support moving up and down among group occurrences (instead of moving up and down among panel items), and they override those at the layout level.

In our form, the terminal operator selects an icon by pressing the Select key with the cursor on the icon. The Select key triggers a different action on each icon. Each icon must have a function response describing the specific action.

Responses contain response steps, which are similar to programming statements. The response steps direct the action of the Form Manager while the response is being evaluated.

The order of functions and responses in the IFDL file is important. You declare functions after the VIEWPORT declarations and before any response declarations. You declare layout level responses immediately after any function declarations.

Use the VSI DECforms IFDL Reference Manual, the TPU Help Forms command, or the LSE expand feature to determine the correct order of any declarations you use.

The term form record describes the data as formatted according to a form record description. You transfer the data either to or from the form. A SEND request moves data to the form, whereas a RECEIVE request moves data from the form. A TRANSCEIVE request moves data to the form, and moves data back again. The form record for each direction in a TRANSCEIVE request can be the same or different form records.

Unless specified differently, a request refers to one form record. A request can, however, reference multiple form records in a single transfer. In this case, a single name refers to a list of form record descriptions in the form. Such a list is called a form record list.Form record lists are useful when you want to use different combinations of records at different times.

Individual elements of a form record description are form record fields or groups.

#include <stdio.h>        /* C standard input output header file    */
#include <formsdef.h>    /* DECforms header file for portable API  */

#define EMPNAME 32
#define EMPBADGE 6
#define EMPCC 3
#define EMPADDRESS 120
#define EMPREASON 64
#define TRIPDATE 8
#define TRIPFROM 3
#define TRIPTO 3
#define TRIPRECORD 36

/*
 * Structure format declarations for records that will be sent to the form
 */
typedef struct {
    char employee_name[EMPNAME], badge_number[EMPBADGE], cost_center[EMPCC],
         address[EMPADDRESS], reason[EMPREASON];
} Hdr_Info_Record;

typedef struct {
    char        trip_date[TRIPDATE], trip_from[TRIPFROM], trip_to[TRIPTO];
    unsigned long   miles, amount, toll, subtotal;

} Trip_Record;
typedef struct {
    unsigned long total_miles, total_amount, total_tolls, form_total;
} Totals_Record;

/*
 * Static storage
 */
Hdr_Info_Record header_info_record;              /* The header info record */
Trip_Record     trips_record[TRIPRECORD];        /* Array of trip records */
Totals_Record   totals_record;           /* totals for all trips */
/*
 * Create instances from data types in formsdef header file
 */
Forms_Session_Id  session_id;
Forms_Form_Object MRF_FORM;                    /* linked form name */
Forms_Status      status;
Forms_Record_Data header_info_record_descr;    /* record   */
Forms_Record_Data trips_record_descr;          /* record   */
Forms_Record_Data    totals_record_descr;    /* record   */
Forms_Request_Options request_options[2];  /*form object for linked form*/

You will define the request options and form record descriptors in Chapter 6, Completing the Application Program for the Character-Cell Layout.

You will define the request options and record descriptors in Chapter 6, Completing the Application Program for the Character-Cell Layout.

/*
 * Routine: main
 */
int main (void)
{
/*
 * Set up the request options for linking the form object file and
 * enable the form.
 */
request_options[0].option      = forms_c_opt_form;
request_options[0].form.object = MRF_FORM;
request_options[1].option      = forms_c_opt_end;

status = forms_enable (session_id,        /* session id returned */
                       NULL,              /* current device      */
                       NULL,              /* name of form file   */
                       "MRF_FORM",        /* name of the form    */
                       request_options);  /* request options     */

NULL indicates a null parameter.

!
! Request options for linked form
!
        request_options(1).option = forms_c_opt_form
        request_options(1).form_object = %loc (MRF_FORM)
        request_options(2).option = forms_c_opt_end
!
! Enable the form
!
        status = forms_enable_for(
        1                          session_id,
        2                          ,           !current device
        3                          ,           !name of form file
        4                          'MRF_FORM', !form name
        5                          request_options)

You must use four commas to separate the five parameters, even when a parameter is optional or unsupplied. You must use a tab at the beginning of each continuation line in a request.

Form data items are the only means of storing values that an operator enters. You can display the value stored in a form data item on the screen or pass it to the program.

Data passed to or from the program (by means of records) is stored in form data items. You also can use a form data item internally in the form without displaying it or passing it to the program. Section 3.7.3, “Specifying Picture Fields for the Group” describes examples of internal form data items—the N and BLANK_DATE fields in the mileage reimbursement application.

In DECforms software, each enabled form maintains a copy of form data items that persistthroughout application execution. For example, if you store the value “10” in a form data item and never change that value, the form data item stores that value until your program disables the form.

You can organize form data items that are related to one another into form data groups. You can nest data groups. Nested data groups can have multiple occurrences so that elements of the groups (data items or other groups) can be arrays. An array is a multiply occurring data item in a group. Chapter 9, Declaring, Displaying, and Tracking Data describes how to use groups and arrays.

A form record is a map of form data that allows the Form Manager to exchange data between the program and the form. For the map to operate correctly, the form record must be logically equivalent to an application program record. The name you declare for the record in IFDL is passed as an argument to a request call. A request is a Form Manager routine that performs form processing, such as enabling a form or sending a record message between the form and the program.

When the Form Manager transfers data to a form during the processing of a request, it copies the data into the form data items with the same names as fields in the form record. These values are kept in the form until they are changed by operator input, by the form itself, or by the processing of another request called from the application program.

Form record fields correspond to form data items and usually have the same names as the corresponding form data items. If the form record fields do not have the same names as form data items,you can specify the correspondence explicitly with a USING clause or a TRANSFER clause (see Chapter 9, Declaring, Displaying, and Tracking Data).

You must specify data types for form record fields. The data types do not have to match those of the form data items because you might want your application program to send or receive the data in a different format. The Form Manager performs the data conversion. However, the most efficient data transfer occurs when no conversion is needed.

The VSI DECforms Programmer's Reference Manual describes data transfer between the application program and the form in more detail.

Layouts contain all the information needed for mapping a form to a display device. You can define several layouts for a form so that you can use the same form to display information on several different display devices.

The application program requires no knowledge of the screen layout or display device. All the application does is communicate with the form by means of form records. The form knows how to display and return data to the program. How you display the data can vary depending on the display device.

Use a different layout to define a view of the form for each type of device. For example, you might choose to display information in one large screen on a VAXstation terminal emulation window that is 54 lines long. On a VT330 terminal you might divide the information into several small panels and display them one at a time.

At run time, the Form Manager chooses a layout based on the device specified in the application program's ENABLE request. On OpenVMS systems, if the request does not specify a device, DECforms uses the definition of the logical name FORMS$DEFAULT_DEVICE.

In a layout, you designate the size of the display. The display is the rectangular area that is available to your application; it might or might not be as large as the display screen. You can adjust the size of the display depending on considerations such as the number of lines and columns on the screen or how much of the display the application can access. You also specify the units in which position coordinates and measurements are to be expressed—inches, millimeters,points, BMUs (Basic Measurement Units or 1/1200 of an inch).

You can define functions and function responses to control what actions occur when the operator presses one or more keys on the keyboard. For information about defining functions and responses, see Chapter 4, Adding Functions, Responses, Display Actions,and Validations to the IFDL File and Chapter 11, Designing the Operator Interface.

Layouts are also convenient for defining several different natural languages for one form. For example, you could have two different views of a form, one for English-speaking operators and one for French-speaking operators. The form would contain two layouts, one that specifies English as the natural language and one that specifies French. At run time, the Form Manager chooses one of these layouts based on the definition of the logical name FORMS$LANGUAGE.

For more information about how the Form Manager chooses a layout, see the VSI DECforms Programmer's Reference Manual.

Within a layout, the display is divided into viewports. A viewport's location is relative to the screen. You can have more than one viewport on the display at a time, and they can overlap.

Viewports are useful because they name a rectangular part of the display. You can use this name to specify explicitly where each panel appears on the display. You can display a panel in a viewport, remove it, display another panel in the same viewport, remove it, and so on, for as long as you have panels to display.

If you do not define a viewport explicitly, DECforms uses a default viewport that corresponds to the size of the layout.

A layout generally contains several panels. When you create a panel, you identify it as either a data entry panel (the default) or a help panel. A data entry panel is used for data input and operator actions. A help panel is used to provide help information. You can also use a help panel for data entry and operator actions.

A third type of panel, a message panel, is used to display error or informational messages to the operator. DECforms supports one message panel for each layout.

Relationship to Viewports and to Other Panels

You can associate several panels with the same viewport, although the Form Manager displays only one panel in the viewport at a time. One panel can occupy different viewports at different times, but cannot occupy different viewports at the same time.

In a character-cell display, the viewports and panels remain in a fixed relationship to each other. The coordinates of character-cell panel objects are relative to the viewport's origin. All objects on a character-cell panel must fit inside the viewport in which the panel is displayed

Processing and Functions

Within a data entry or help panel declaration,you can specify processing that is done when input is first entered in the panel and when input is completed. You also can define function keys that are specific to a panel, and you can specify messages that give help to the operator. Literals, panel fields, icons and panel groups are the elements that compose the actual display. The following sections discuss these elements.

For complete information about how to create panels using the FDE or a panel editor, see the VVSI DECforms Guide to Commands and Utilities. For information about declaring help panels in the IFDL source file, or about using message panels, see Chapter 11, Designing the Operator Interface.

Literals

Literals are text and graphics that form the background ofa panel and that do not change while the application is running. You can use literals to convey messages to the operator (about how touse the panel, for example), or to create borders and other graphics.

Literals can have display attributes; you can specify that a literal be bolded or underlined, for example. You can specify a set of literal default attributes to be applied to all literals on a panel. You can turn off or override default attributes for a particular literal or set of literals.

Panel Fields

Panel field values change over time as form data changes—when information is sent from the program to form data items and when statements in the form change the form data items.

You can assign display attributes to individual panel fields. You also can declare and apply field default attributes at the layout, panel, group, or field level. Field defaults are similar to literal defaults: you can override field defaults by assigning other display attributes or by setting the defaults off at a lower level.

A panel field must have the same name as the form data item it displays. At run time, the initial value of a panel field is the value stored in the form data item it represents. You can allow the operator to change that value. When the value of a form data item changes, DECforms dynamically updates any associated onscreen field.

In a panel field declaration, you can specify that operator entry be validated before the corresponding data value is returned to the program in a record.

Icons

Panels use icons to give operators a way to perform an action by moving the cursor to and selecting an icon. An icon is composed of one or more text or graphic literals.

Unlike fields, icons have no associated form data items. Although icons cannot accept data input, function key input is allowed. For example, you can use icons to represent a menu option that the operator can select. You can declare processing attributes for an icon, such as active highlight, or conditional display by means of the CONCEALED WHEN clause.

Panel Groups

A panel group is a collection of panel fields, literals, and icons within the panel that can be treated as an entity for certain operations. Such operations include scrolling, deciding which fields can have input, deciding where to move the cursor, determining what to do when a function is entered while one of the fields of the group is active, and so on.

A panel group is the mapping of a data group to the panel. Just as data groups can have multiple occurrences, panel groups also can have multiple occurrences and appear on the screen as lists or tables (possibly scrolled).

You can use null terminated data with C programs. For example,if you specify a data item named ADDRESS as a CHARACTER NULL TERMINATED text string that is 61 characters long, the 61st character will be null. The maximum number of characters the operator can enter into a field having this format is 60. If the initial value of the data is blank spaces, and the operator enters 40 characters, the next 20 characters will remain blank, followed by the null character. You can use an escape routine in an EXIT response to trim the trailing spaces.

You can use varying strings with Pascal or PL/I programs.

A packed integer is not a longword; rather, it is a byte string in which each byte contains two digits, each packed into four bits. The four low-order bits of the last byte in the string specify the sign.

See the TEXT DATA Clause section of the VSI DECforms IFDL Reference Manual for details on the text formats.

DFLOATING, FFLOATING, GFLOATING, HFLOATING, and TFLOATING differ in precision and length. Use Short Float and Long Float for future portability.

See the ATOMIC DATA Clause section of the VSI DECforms IFDL Reference Manual for details on the atomic formats.

For portable applications, use DATETIME. See the DATETIME DATA Clause section of the VSI DECforms IFDL Reference Manual for details on date/time formats.

A form data group can be a simple group, which is a collection of form data items without an OCCURS clause. Such a form data group contains form data items that occur only once and do not need subscripts.

You can even create a group containing only one form data item.

Form Data
    EMPLOYEE_NAME Character(30)
    EMPLOYEE_ID_NUMBER Integer(10)

        Group EMPLOYEE_ADDRESS                          
        STREET_ADDRESS Character(32)
        CITY Character(32)
        STATE Character(2)
         ZIP_CODE Integer(9)
              End Group

    Group SPOUSE                                    
        Occurs 2
        NAME Character(15)
    End Group

    Group DEPENDENT                                 
        Occurs 4
        Group CHILDREN
            Occurs 2
            CHILD_NAME Character(15)
        End Group
    End Group
End Data

Using Subscripts and Qualified Names

You can use the group name to perform operations on a group, or you can name a single member of a group to perform the operation only on that member. To refer to group form data items, you must always use the full name from the outermost group name to the innermost data item.

In Example 9.3, “Declaration of Form Data Groups”, the CHILDREN group is a one-dimensional array. The DEPENDENT group is a two-dimensional array. You refer to a form data item of the DEPENDENT group using subscripts.

For example, DEPENDENT(1).CHILDREN(1).CHILD_NAME refers to the first occurrence of the CHILD_NAME form data item in the CHILDREN group and the first occurrence of the CHILD_NAME form data item in the DEPENDENT group.

Because the CHILDREN group is nested in the DEPENDENT group, you cannot refer to items in the CHILDREN group without naming the DEPENDENT group.

For example, CHILDREN(1).CHILD_NAME is an unqualified reference. The reference must be a qualified name, such as DEPENDENT(2).CHILDREN(1).CHILD_NAME.

To display form data items that are declared in a form data group, you must declare a panel group that corresponds by name to that form data group. You can include literals or icons in a panel group. The panel fields in the panel group must have the same names as the form data items in the form data group.

      Group TRIP
        Vertical
          Displays 12
        Field TRIP_DATE
          Line 6
          Column 8
          .
          .
          .
        End Field
        Field TRIP_FROM
          Line 6
          Column 22
          .
          .
          .
        End Field

The VERTICAL and HORIZONTAL clauses control the appearance of subsequent occurrences. If you specify vertical, subsequent occurrences of items in the panel group appear below the first occurrence. If you specify horizontal,subsequent occurrences of the panel group appear to the right of the first occurrence. You cannot specify both vertical and horizontal.

If the number of display occurrences is less than the number of form data occurrences, DECforms allows the operator to scroll the panel group display area to show more occurrences of the panel group.

An inner multiply occurring panel group cannot scroll. Therefore, you must make sure that a multiply occurring panel group nested inside another multiply occurring panel group occurs the same number of times as its related form data group.

Use the DISPLAYS clause to specify how many occurrences in a vertical or horizontal panel group will appear on the screen at one time. Chapter 11, Designing the Operator Interface describes the DISPLAYS clause.

Panel GROUP_PANEL

    Literal Text                                          
        Line 3
        Column 5
        Value "Employee Information"
        Display
            Font Size Double High
        End Literal

    Group EMPLOYEE_ADDRESS                                
        Literal Text
            Line 6
            Column 5
            Value "Street:"
        End Literal

        Field STREET_ADDRESS
            Same Line
            Next Column +1
            Display
                Underlined
        End Field

        Literal Text
            Next Line
            Column 5
            Value "City:"
        End Literal

        Field CITY
            Same Line
            Next Column +3
            Display
                Underlined
        End Field

        Literal Text
            Next Line
            Column 5
            Value "State:"
        End Literal

        Field STATE
            Same Line
            Next Column +2
            Display
                Underlined
        End Field

        Literal Text
            Same Line
            Next Column +3
            Value "Zip code:"
        End Literal

        Field ZIP_CODE
            Same Line
            Next Column +1
            Display
                Underlined        End Field
    End Group

    Literal Text                                          
        Line 10
        Column 5
        Value "Spouse:"
    End Literal

    Group SPOUSE                                          
        Horizontal
        Field NAME
            Line 10
            Column 13
            Display
                Underlined
            Input Picture XXXXXXXXXXXXXXX' '
        End Field
    End Group

    Literal Text                                          
        Line 12
        Column 5
        Value "Dependent children:"
    End Literal

    Group DEPENDENT                                       
        Vertical
        Group CHILDREN
            Horizontal
            Field CHILD_NAME
                Line 13
                Same Column
                Display
                    Underlined
                Input Picture XXXXXXXXXXXXXXX' '
            End Field
        End Group
    End Group
End Panel

Figure 9.2, “Appearance of Panel Groups on a Character-Cell Display Device” illustrates how the panel in Example 9.4, “Declaration of Panel Fields to Display a Form Data Group” is displayed to the operator.

A panel group need not have a panel field declaration for every form data item in the data group. On the other hand, it is possible for a panel group to have an item in it that is not in the associated form data group—an icon. You can declare icons in simple or multiply occurring panel groups. They must not have the same name as any form data items. When you declare an icon within a panel group, you must qualify it in the same way as you would qualify a panel field. For example, if you declare icon MENU_ITEM in panel group MENU, you would refer to the icon as MENU.MENU_ITEM.

In the ACTIVATE response step, you must include the name of the panel on which the panel group, panel field, or icon is displayed.

Activating Simple Panel Groups and Panel Fields

Activate Group EMPLOYEE_ADDRESS On GROUP_PANEL 

Activate Field EMPLOYEE_ADDRESS.STREET_ADDRESS On GROUP_PANEL

Activating Multiply Occurring Panel Groups and Panel Fields

This section describes using the POSITION response step,the major built-in navigation functions and function responses, and icons, and the CURRENT clause. For information about using the BASE and FIRST clauses, see the VSI DECforms IFDL Reference Manual.

Using the POSITION Response Step

Position To Field EMPLOYEE_ADDRESS.STREET_ADDRESS on GROUP_PANEL

Position to Group DEPENDENT on GROUP_PANEL

Position To Group EXAMPLE(5) on SAMPLE_PANEL

Using Built-In Functions to Control Navigation

To control the operator's navigation in a panel group that has several items on the activation list, you can use the built-in functions described in this section. Each built-in function has a default function response (listed in the appendix on built-in functions in the VSI DECforms IFDL Reference Manual).

Using Icons for Navigation in Groups

You also can use icons for navigation in panel groups. When an icon is declared as part of a panel group that has multiple occurrences, the icon also has multiple occurrences—it becomes an icon array, just as panel fields become panel field arrays.

You could use an icon array for navigation,for example, in cases where all the fields in a panel group are protected. Because icons accept function key input, the operator can scroll from one occurrence of the panel group to another.

Using the CURRENT Clause to Return to the Occurrence Last Visited

Form Data
    Group REVISIT
        Occurs 10
        Current REV_CUR
        EMPLOYEE_NAME Character(18)
    End Group
    REV_CUR Longword Integer
    SAVE_REV_CUR Word Integer VALUE 1
End Data
   .
   .
   .
Panel CURRENT_EMPLOYEES
    Group REVISIT
        Vertical
            Displays 10
        Entry Response                                         
            Position Immediate To Group REVISIT(SAVE_REV_CUR)
                 On CURRENT_EMPLOYEES                          
        End Response
        Exit Response                                          
            LET SAVE_REV_CUR = REV_CUR
        End Response
        Field EMPLOYEE_NAME
        .
        .
        .

The method illustrated in Example 9.5, “IFDL Source Code for Returning to the Occurrence Last Visited” works for any way the operator entered the panel group, because the entry response for the panel group is always executed by the Form Manager before any input is entered into items in the panel group.

If Oracle CDD/Repository software is installed on your OpenVMS system, you can avoid declaring the same record twice by storing record declarations in Oracle CDD/Repository. Using the COPY FROM DICTIONARY statement, you can copy the form record declarations into your form and program.

Form EMPLOYEE_FORM
    .
    .
    .
    Form Data
        Group EMPLOYEE_ADDRESS
            STREET_ADDRESS Character (30)
            CITY Character (15)
            STATE Character(2)
            ZIP_CODE Integer(9)
        End Group
    .
    .
    .
        Group DEPENDENT
            Occurs 4
            Group CHILDREN
                Occurs 2
                CHILD_NAME Character(15)
            End Group
        End Group
    Form Record EMPLOYEE_DATA
        Group EMPLOYEE_ADDRESS                                     
            STREET_ADDRESS Character (30)
            CITY Character (15)
            STATE Character(2)
            ZIP_CODE Integer(9)
        End Group
        Group SPOUSE                                               
            Occurs 2
            NAME Character(15)
        End Group
        Group DEPENDENT                                            
            Occurs 4
            Group CHILDREN
                Occurs 2
                CHILD_NAME Character(15)
            End Group
        End Group
    End Record

IDENTIFICATION DIVISION.
PROGRAM ID.  Employee_program

DATA DIVISION.
WORKING STORAGE SECTION.
01   GROUP_RECORD                                          GLOBAL. 
     03 STREET_ADDRESS                            PIC X(30).
     03 CITY                                      PIC X(15).
     O3 STATE                                     PIC X(2).
     03 ZIP_CODE                                  PIC 9(9).
     03 SPOUSE                                    OCCURS 2.
        05 NAME                       PIC X(15).
     03 DEPENDENT                                 OCCURS 4.
        05 CHILDREN                               OCCURS 2.
           07 CHILD_NAME              PIC X(15).
PROCEDURE DIVISION.
   .
   .
   .
END PROGRAM Employee_program.

Data Transfer When Occurrences Do Not Match

If the number of occurrences in an array does not match in the form data and the form record, the number of occurrences that gets transferred is the smaller of the two. For example, if the form record group SPOUSE shown in Example 9.7, “Declaration of Logically Equivalent Data: Program Data and Records” had an OCCURS 5 clause, only the first two occurrences would be transferred to the form data, because there is no place to put the other three occurrences. On a RECEIVE request, only the first two occurrences would be received by the program from the form data; the remaining three would be set to default values (spaces for character data and zeros for numeric data).

A likely application of this data transfer feature is to change or retrieve only one or two occurrences of form data groups. For example, if the form record contains form data group SPOUSE with an OCCURS 1 clause, the first occurrence would be transferred.

Form Data
    .
    .
    .
    Group REPEAT_1 Occurs 4
        ITEM_1 Character(8)
    End Group
    .
    .
    .
End Data

Form Record GROUP_RECORD
    .
    .
    .
    Group REPEAT_1
        Occurs 1
        ITEM_1 Character(8) Using REPEAT_1(2).ITEM_1
    End Group
    .
    .
    .
End Record

To transfer more than a single occurrence, you can use a subscript range. For example, suppose there are five occurrences of the form data group in form data, and two occurrences in the form record. In this case, you could specify USING REPEAT_1(3:4).ITEM_1 to transfer the two occurrences in the form record to the third and fourth occurrences in form data.

Form Data
    .
    .
    .
    Group REPEAT_1 Occurs 4
        ITEM_1 Character(8)
    End Group
    WHICH_ONE Unsigned Word
    .
    .
    .
End Data
Form Record JUST_ONE
    WHICH_ONE Unsigned Word
    Group REPEAT_1
        ITEM_1 Character(8) Using REPEAT_1(WHICH_ONE).ITEM_1
    End Group
End Record

Form Data
    CR1 Longword Integer
    Group REPEAT_1
        Occurs 12
        Current CR1
        ITEM_A Longword Integer
        ITEM_B Character(4)
    End Group
End Data
Form Record ONE
    CR1 Longword Integer
    Group REPEAT_1
        ITEM_A Longword Integer Using REPEAT_1(CR1).ITEM_A
        ITEM_B Character(4) Using REPEAT_1(CR1).ITEM_B
    End Group
End Record

CR1 is the occurrence of the panel group the operator was in or visited last. The form record fields REPEAT_1.ITEM_A and REPEAT_1.ITEM_B would receive the occurrences of form data items REPEAT_1(CR1).ITEM_A and REPEAT_1(CR1).ITEM_B, the two data items in occurrence CR1 of form data group REPEAT_1.

Immediately before the Form Manager returns the current value of the form data item to the program, it compares the current value to the last known value. If these values differ, the Form Manager returns information to your program in a receive shadow record, which indicates that the form data item has changed.

To specify that a form data item is tracked, you use the TRACKED clause in the FORM DATA declaration.

Form EMPLOYEE_FORM
    Form Data
        EMPLOYEE_NAME Character(30) Tracked
        EMPLOYEE_ID_NUMBER Integer(10)
        HIRE_DATE Date
        CURRENT_JOB_TITLE Character(30) Tracked
    End Data

    Form Record EXPERIENCE_RECORD
        EMPLOYEE_NAME Character(30)
        EMPLOYEE_ID_NUMBER Integer(10
        HIRE_DATE Date
        CURRENT_JOB_TITLE Character(30)
    End Record
    .
    .
    .

If you create a receive shadow record and pass it in your request call,the Form Manager writes information about the tracked data items in the receive shadow record. To create a receive shadow record, declare a form record in your program that has a one-character field at the beginning, followed by a one-character field for each of the fields in your record. Each field in the receive shadow record should be one character in length.

WORKING STORAGE SECTION.
*-----
*  COBOL record declaration for a shadow record
*-----
01     EXPERIENCE_RECORD_SHADOW                     GLOBAL.
       03 RECORD_SHADOW                  PIC X.
       03 EMPLOYEE_NAME_SHADOW           PIC X.
       03 EMPLOYEE_ID_NUMBER_SHADOW      PIC X.
       03 HIRE_DATE_SHADOW               PIC X.
       03 CURRENT_JOB_TITLE_SHADOW       PIC X.

You can tell the Form Manager not to update its internal last known values for the tracked form data items when you receive a shadow record; you do this by passing a receive shadow record whose first character is “N”. This capability is useful when, for example,your program has to validate fields received. You might want your program to validate only those fields that the operator has changed—not counting the value that the application passes in this record.

The Form Manager will update a receive shadow record whose first character is “Y” or any character other than “N”.

You pass the receive shadow record in an argument to the RECEIVE and TRANSCEIVE requests. For information on these arguments, see the VSI DECforms Programmer's Reference Manual.

You can tell the Form Manager not to update its internal last known values for the tracked form data items when you are sending records to the form. Unlike receive shadow records, send shadow records must be one character long. A value of “N”tells the Form Manager not to update the last known value. A “Y” or any character other than “N” tells the Form Manager to update the last known value of the corresponding form data items in the record.

You pass the send shadow record in an argument to the SEND and TRANSCEIVE requests. For information on these arguments, see the VSI DECforms Programmer's Reference Manual.

When you specify an ACTIVATE FIELD, ACTIVATE ICON, or ACTIVATE BUTTON response step, you usually add a single panel field, icon, to the activation list. If the object of the ACTIVATE response step specifies a range of fields, or icons in a multiply occurring group, you add all the fields, and icons in the range to the activation list. The items in the range are added to the activation list with the lowest subscripts first. For nested arrays, elements are added in row major order.

When you specify an ACTIVATE GROUP or ACTIVATE PANEL response step, you might be adding all those items in the group or panel that are unprotected or conditionally protected to the activation list. Using an ACTIVATEGROUP or ACTIVATE PANEL response adds the contents of the group or panel to activation list, not the group or panel itself.

Although you do not add groups or panels to the activation list, the panel fields, and icons that you do add have groups and panels associated with them. The concept of group and panel therefore has meaning when you specify navigation and refer to panels or groups.

The Form Manager always performs navigation with respect to items on the activation list. When a response contains a POSITION response step, the POSITION response step refers to a particular item on the activation list or to an item relative to the current activation item. If you try to use the POSITION response step to move to an item that is not on the activation list, the response step is ignored.

A new activation list is created each time the application program makes a form request. The activation list exists only for the life of the request. You can manipulate the activation list after it has been created at the external response phase of request processing (during the accept phase) by using the ACTIVATE response step to add more items to it and by using the DEACTIVATE response step to delete items from it. You might want to control the activation list during the accept phase to achieve special navigational effects, often involving pop-up panels.

If you then specify POSITION TO NEXT ITEM, the cursor goes to FIELD_D instead of FIELD_C.

ACTIVATE FIELD X ON Panel_A
ACTIVATE PANEL Panel_A

If you exercise control over the activation list by means of the ACTIVATE response step, you must pay attention to panel fields and icons that are conditionally protected (items with a PROTECTEDWHEN clause). Such items go on the activation list, but whenever a POSITION response step is executed, their protection determines whether the operator can move to them.

Whenever a POSITION response step specifies a target, the Form Manager evaluates the fields and icons on the activation list. If a field or icon is a potential target, the conditional expression in the PROTECTED WHEN clause is evaluated. If the expression is evaluated as false, the item is not protected,and it can be considered a target of the POSITION response step. If the expression is evaluated as true, the item is protected, and it is not considered a target of the POSITION response step.

For example, if the operator presses the NEXT ITEM function key, the Form Manager tries to move to the next item on the activation list after the current item. If the next item on the list is protected, the Form Manager ignores that item as if it were not on the list, and then goes to the following item, checking to see whether that item is unprotected.

Items protected by a PROTECTED WHEN clause are particularly useful in menu processing. The WHEN clause can specify a condition that determines when the item is not a legal choice. If the item is not a legal choice, the operator will not be able to move the cursor to it.

The CONCEALED WHEN,OUTPUT WHEN, or HIGHLIGHT WHEN clauses are useful in conjunction with such protected items;they can specify that the item not be displayed on the screen, so that the operator cannot move to or see the item.

The character-cell layout of the advanced sample application shows an example of using a PROTECTED WHEN clause in conjunction with a CONCEALED WHEN clause in the CASH_PANEL panel: the operator can only see and move the cursor to those icons representing amounts that can be withdrawn. The condition is a comparison of the amount in the checking account against the amount represented by the icon.

Icon CHOICE_CASH_50
    Function Response SELECT
        Let AMOUNT = 5000
        Let NEXT_UPDATE_AMOUNT = "$50"
        Return
    End Response

    Active Highlight
        Reverse
    Concealed
        When (CHECKING_BALANCE < 5000)
    Protected
        When (CHECKING_BALANCE < 5000)
    Literal Text
        Next Line
        Same Column
        Value "  $50"
    End Literal
End Icon

Chapter 13, Demonstration and Sample Forms and Applications contains more information on the CASH_PANEL panel used in the advanced sample checking form.

When you use the DEACTIVATE response step, the Form Manager removes items from the activation list. You should use the DEACTIVATE response step with care, to avoid deactivating an item that was previously specified as the next activation item.

For example, if you use POSITION TO PANEL PAYROLL_PANEL as part of a function response, the Form Manager specifies the first item on PAYROLL_PANEL that is on the activation list to be the next activation item—the one to be processed after the current activation item has been processed. If you then use DEACTIVATE PANEL PAYROLL_PANEL, the current activation item is now on a deactivated panel.

In this case, the Form Manager goes to the next activation item on another panel. If there are no more activation items, the Form Manager sets the current activation item as the next activation item. The cursor does not move and input starts again with the same item, which might confuse the operator.

Refer to Figure 13.2, “Operator Choice Panel on a Character-Cell Device”, and Example 13.1, “IFDL Source for the Introductory Sample Operator Choice Panel—Character-Cell Layout” to see the appearance and the complete IFDL source code for this panel.

How the ACTIVATE and DEACTIVATE Response Steps Work Together

The advanced sample checking form shows how the ACTIVATE and DEACTIVATE response steps can work together. The following description refers to the character-cell layout.

ACTIVATE PANEL deposit_panel
POSITION IMMEDIATE TO PANEL deposit_panel

FUNCTION RESPONSE NEXT ITEM
    MESSAGE "Press F10 or PF1-E to make the deposit."
END RESPONSE

Similarly, the AMOUNT field contains a PREVIOUS ITEM function response that overrides the default. The PREVIOUS PANEL function response is also overridden. These function responses display a useful message instead of allowing the operator to go to another panel.

The operator can leave the DEPOSIT_PANEL panel by pressing the key bound to the QUIT function (F8 or PF1-Q in the character-cell layout). In this context, the QUIT function response should return to the menu on the CHOICE_PANEL menu and disregard the deposit slip.

Function Response QUIT
    Message "Quitting – no deposit has been made."
    Position Immediate to Previous Panel
End Response

Exit Response
    Remove MID_VP
    If IMMEDIATE Then
        Deactivate Panel DEPOSIT_PANEL
        Position Immediate To Previous Item
    .
    .
    .
End Response

The Form Manager displays the amount of data in the panel group that fits in the number of occurrences on the display. If the operator requests to see more of the data, the Form Manager scrolls the data, either by occurrence or by page, depending on what you specify.

Figure 11.1, “Operation of a Vertical Scrolled Region” and Example 11.2, “Scrolling in a Character-Cell Layout” show how a vertical scrolled region works on a character-cell device.

In Figure 11.1, “Operation of a Vertical Scrolled Region”, the form data group occurs four times. The panel group displays two occurrences of the form data group at once. When the panel is first displayed, the form data occurrence that contains Bill Smith and the form data occurrence that contains Sally Sneed are displayed.

When the operator requests more information by pressing a function key or key sequence,the form data occurrence that contains Jane Towers is displayed on the bottom line of the scrolled region. The form data occurrence that contains Sally Sneed moves to the top line of the scrolled region, and the form data occurrence that contains Bill Smith is removed from the display. This process continues until the operator stops requesting new data or all occurrences have been displayed.

Form EMPLOYEE_FORM

    Form Data                                              
        Group NAME_AND_NUMBER Occurs 4
            EMPLOYEE_NAME Character (30)
            EMPLOYEE_PHONE Character (10)
        End Group
        CHANGE_NUMBER Character (1)
    End Data

    Form Record EMPLOYEE_PHONE_NUMBERS                     
        Group NAME_AND_NUMBER Occurs 4
            EMPLOYEE_NAME Character (30)
            EMPLOYEE_PHONE Character (10)
        End Group
        CHANGE_NUMBER Character (1)
    End Record

    Layout VT_LAYOUT
        Device
            Terminal
                Type %VT100
        End Device
        Size 24 Lines by 80 Columns
        .
        .
        .
        Panel SCROLL_PANEL

            Literal Text
                Line 2
                Column 31
                Value "VIEW PHONE NUMBERS"
                Display
                    Font Size Double High
            End Literal

            Literal Text
                Line 7
                Column 10
                Value "Employee Name and Phone Number:"
            End Literal

            Literal Rectangle
                Line 10
                Column 10
                Line 16
                Column 65
            End Literal

            Group NAME_AND_NUMBER                           
                Vertical Displays 2

                Field EMPLOYEE_NAME                         
                    Line 12
                    Column 15
                End Field

                Field EMPLOYEE_PHONE
                    Line 12
                    Column 47
                    End Field
            End Group

            Literal Text
                Line 20
                Column 10
                Value "Press KP7 to change a phone number."
            End Literal

        End Panel
    End Layout
    .
    .
    .
End Form

Using the function keys causes the cursor to move to the occurrence in the direction indicated. If scrolling is necessary to make the new cursor position visible, the Form Manager will scroll the scrolled region.

You can change the keys bound to these functions by declaring the function in your IFDL source file. If you need actions other than those given by default, you can write a function response for these functions. For information on declaring functions and writing function responses, see Section 11.3, “Defining Form Function Keys” and the table on built-in functions in the VSI DECforms IFDL Reference Manual.

If you specify the SCROLL BY PAGE clause in the GROUP declaration, a new page of data is output to the display. If you omit the SCROLL BY PAGE clause, the region scrolls smoothly, one occurrence at a time.

Built-in function names are bound to keys by default. When you bind one of the DECforms built-in function names to a key in a function declaration, you replace the previous default key binding with the binding you specify.

You can bind more than one key to a function name by naming more than one key in the FUNCTION declaration. For example, if you want the operator to be able to invoke a function using a default key and another key, name both the default key and the other key in a function declaration.

You can declare function definitions only at the layout level. However, you can declare or change the form's response to a key definition at the layout, panel, group, field, or icon level by redefining function responses (see Section 11.3.2, “Writing Function Responses”).

   .
   .
Layout VT_LAYOUT
    Device
        Terminal
            Type %VT100
    End Device
    Size 24 Lines By 80 Columns

    Function TRANSMIT
        Is %KP_1
           %F10
           %CONTROL_Z
    End Function
    .
    .
    .
    .
    .
    .

It is possible to disable the default key definition for a built-in function;see Section 11.3.3, “Disabling Built-In Function Key Bindings”.

Layout ANOTHER_LAYOUT
    .
    .
    .
    Function CHANGE_EMPLOYEE
        Is %F11
    End Function
    .
    .
    .

To control what occurs when the operator presses a function key, you define a function response. You can write a function response for any function, including many of the DECforms built-in functions.

You can define function responses at the layout, panel, field,icon, or group level. Function responses defined at the layout level apply throughout the layout. Function response declarations at lower levels in the layout hierarchy override function response declarations at higher levels, so you can change the behavior of keys at any level in the form.

For example, you can define a function response at panel level and define the same function response to perform a different set of actions for a field in that panel. If a form element does not contain a function response declaration, the Form Manager uses the function response defined at the next level above.

To control what occurs when the operator presses an undefined key for character-cell layouts only, you can write a special function response called UNDEFINED FUNCTION. For information on the UNDEFINED FUNCTION function response, see Section 11.4, “Using Situational Function Responses”.

When you write a function response for a built-in function, you change what occurs when the operator accesses the function. For example, the default function response for the NEXT ITEM built-in function makes the next item on the activation list the current item. If no next item exists (because the current item is the last on the list), the Form Manager displays a message.

Layout SAMPLE
   .
   .
   .
    Function Response NEXT ITEM                       
        If LAST ITEM Then
            Position To FIRST ITEM
        Else
            Position To NEXT ITEM
        End If
    End Response

    Panel EMPLOYEE_PANEL
        Builtin Function Response NEXT ITEM           
    .
    .
    .

When you write a function response for a function other than a built-in function, you determine what happens when the function key bound to that function is pressed.

Layout L1
    .
    .
    .
    Function CHANGE_EMPLOYEE
        Is %F11
    End Function
    .
    .
    .
    Panel EMPLOYEE_PANEL
        Function Response CHANGE_EMPLOYEE
            Position To Next Panel
        End Response
    .
    .
    .

You may want to use a built-in function key for your own task and not allow that key to be used for the default DECforms function. Or you may simply want to disable one or more key bindings for a built-in function. This section describes two ways to disable built-in function key bindings.

The first method for disabling built-in function key bindings is to explicitly declare the built-in function at the layout level in your form.

Layout VT_LAYOUT
    Function NEXT HELP
        Is %None
    End Function

Layout VT_LAYOUT
    Function NEXT HELP
        Is %Help
    End Function

For a table of the DECforms built-in functions, their default key bindings, and default responses and for syntax information on the built-in functions, see the appendix on built-in functions in the VSI DECforms IFDL Reference Manual.

        Panel WELCOME_PANEL
            Viewport WELCOME_VP
            Display
                %Keypad_Application

            Remove
            Function Response NEXT HELP
                Enter Help
            End Response

            Function Response BUILTIN FUNCTION
                Return
            End Response

            Function Response USER FUNCTION
                Return
            End Response

            Function Response UNDEFINED FUNCTION
                Return
            End Response
            .
            .
            .
            Literal Text
                Next Line
                Same Column
                Value "To continue, press RETURN."
            End Literal
        End Panel

This panel demonstrates the use of the UNDEFINED FUNCTION, the USER FUNCTION, and the BUILTIN FUNCTION function responses in a panel to allow any key to return to the application.

Example 11.10, “Use of the USER FUNCTION Function Response” from the Windows Form demo shows another use of the USER FUNCTION function response. In this ICON declaration, if the operator presses any user-defined function key or key sequence, the Form Manager calls the POSITION_TO_BLANK internal response.

          Icon FILE_ICON
               Function Response SELECT
                    Activate
                        Panel FILE_PANEL
                    Position To Panel FILE_PANEL
               End Response

               Function Response RIGHT_ITEM
                    Position To Next Item
               End Response

               Function Response UP_ITEM
                    Position To Icon ICONIZE_PUZZLE On PUZZLE_PANEL
               End Response

               Function Response FLIP_FLOP
                    Include POSITION_TO_BLANK
               End Response

               Function Response USER FUNCTION
                    Include POSITION_TO_BLANK
               End Response

               Active Highlight
                    Reverse
                    Underlined
               Literal Text
                    Line 2
                    Column 2
                    Value " File "
                    Display
                        Underlined
               End Literal
           End Icon

Example 11.11, “Use of the BOUNDARY CURSOR LEFT Function Response” shows a function response for a boundary function.

Layout VT_LAYOUT
    .
    .
    .
    Icon CHOICE_REV_REG
       .
       .
       .
       Function Response BOUNDARY CURSOR LEFT
           Position to Previous Item
       End Response
    .
    .
    .
    End Icon
    .
    .
    .

The BOUNDARY CURSOR xxx functions are activated when one of the CURSOR xxx functions is entered and the cursor is at the boundary mentioned. In an icon, because there is no data input allowed, the cursor is always considered to be on the boundary. In this example, when the operator enters the CURSOR LEFT function (bound by default to the left arrow key), the function response causes the Form Manager to move the cursor to the previous item rather than to perform the default function response, which is to display an error message.

The VSI DECforms Programmer's Reference Manual describes each of these methods, including a list of the message codes that you can use.

You can also use help messages to send information to the operator. For information about help messages, see Section 11.9.1, “Using Help Messages”.

To send a message from your application program or from an escape routine, use a record field named MESSAGEPANEL in a SEND record message. The value of the MESSAGEPANEL record field is transferred to the message panel,and the message panel is automatically displayed when that record message is sent to the form.

Form Record MESSAGE_RECORD
    MESSAGEPANEL Character(512) Varying
End Record

The purpose of a help message is to provide specific information about what is needed as input to a particular field. You create a help message with the USEHELP MESSAGE clause.

Example 11.16, “Declarations of Help Messages” shows a panels in a character-cell layout containing fields that have help messages associated with them.

Form EMPLOYEE_FORM
    .
    .
    .
    Layout VT_LAYOUT
    .
    .
    .
         Panel EMPLOYEE_INFORMATION
            Viewport DEFAULT_VIEWPORT
            Use Help Message
                "Enter the employee's name and previous work experience"

            Literal Text
                Line 2
                Column 2
                Value "Employee Name:"
            End Literal

            Field EMPLOYEE_NAME                        
                Line 2
                Column 20
            End Field

            Group PREVIOUS_EMPLOYER_INFORMATION
                Vertical
                    Displays 4
                Use Help Message
                    "Enter information about the employee's previous jobs"

                Literal Text
                    Line 5
                    Column 1
                    Value "Employer Name: "
                End Literal
                Field EMPLOYER_NAME                    
                    Line 5
                    Column 16
                    Use Help Message
                        "Enter the previous employer's name"
                End Field

                Literal Text
                   Same Line
                   Column 47
                   Value "Street: "
                End Literal

                Field EMPLOYER_STREET                 
                    Same Line
                    Column 55
                End Field

                Literal Text
                    Same Line
                    Column 66
                    Value "Years Emp: "
                End Literal

                Field YEARS_EMPLOYED                   
                    Same Line
                    Column 77
                    No Help Message
                End Field
            End Group
        End Panel
    End Layout

	When the operator presses Help while the cursor is on the EMPLOYEE_NAME field, the message “Enter the employee's name and previous work experience” is displayed as shown in Figure 11.2, “Help Message at Panel Level on a Character-Cell Device”. This message appears because that field does not have a specific help message. Therefore, the help message at the panel level is used.
	When the operator presses Help while the cursor is on the PREVIOUS_EMPLOYER_INFORMATION.EMPLOYER_NAME field, the message “Enter the previous employer's name” appears. This message is specified in the USE HELP MESSAGE clause of that field declaration. Figure 11.3, “Help Message at Field Level on a Character-Cell Device” shows an example.
	When the operator presses Help while the cursor is on the PREVIOUS_EMPLOYER_INFORMATION.EMPLOYER_STREET field,the message “Enter information about the employee's previous jobs” is displayed as shown in Figure 11.4, “Help Message at Group Level on a Character-Cell Device”. The field does not have a specific help message. The field is a member of a group, however, and the group does have a specific help message, which is displayed.
	When the operator presses Help while the cursor is on the PREVIOUS_EMPLOYER_INFORMATION.YEARS_EMPLOYED field, no message appears, as specified in the USE HELPMESSAGE clause of that field declaration.

You can specify only one help message for each field. Each help message can be any length—the Form Manager wraps and scrolls messages that are too long to fit in the message panel. This might cause long messages to scroll off the message panel before the operator has a chance to read the entire message,so try to avoid using multiple-line messages unless you have declared your message panel to occupy a viewport having more than a single line.

Sometimes you want to supply messages that provide help when the operator moves the cursor to a field. Such messages—or hints—differ from those that are displayed after data is entered, such as error messages, or those that are displayed when the operator presses Help.

One way of providing hints is to include an entry response containing the MESSAGE HELP response step in each field for which you want to display a hint. The entry response causes the Form Manager to take the specified action when the operator moves the cursor to the field. The MESSAGE HELP response step causes the Form Manager to display the help message(specified by the USE HELP MESSAGE clause) associated with the field.

Field EMPLOYEE_NAME
    Line 3
    Column 18
    Entry Response
        Message Help
    End Response
    Display
        Reverse
    Use Help Message
        "Enter the employee's name"
End Field

Panel SHIPPING_PANEL
    Apply Field Default Of
        Entry Response
            Message Help
        End Response
    End Default

    Field SHIP_TO_CITY
        Use Help Message
            "Enter the city to ship to"
        .
        .
        .
    End Field

    Field SHIP_DATE
        Use Help Message
            "Enter the date the item was shipped"
        .
        .
        .
    End Field
    .
    .
    .
End Panel

Layout SAMPLE
   .
   .
   .
    Internal Response CHECK_HINTING                    
        If (HINTING_STATUS = 1) Then
            Message Help
        End If
    End Response
    .
    .
    .
        Field EMPLOYEE_NAME
            Line 3
            Column 18
            Entry Response                             
                Include CHECK_HINTING
            End Response

            Display
                Underlined
            Use Help Message
                "Enter the employee's name"
        End Field
        .
        .
        .

Help Panel EMPLOYEE_INFORMATION_HELP                          
   .
   .
   .
End Panel

Help Panel EMPLOYEE_NAME_HELP                                 
   .
   .
   .
End Panel

Panel EMPLOYEE_INFORMATION
    Use Help Panel
    EMPLOYEE_INFORMATION_HELP

    Field EMPLOYEE_NAME                                       
        Line 2
        Column 2
        Use Help Panel
            EMPLOYEE_NAME_HELP
    End Field

    Group PREVIOUS_EMPLOYER_INFORMATION
        Field EMPLOYER_NAME                                   
        Line 5
        Column 2
        Use Help Message
            "Enter the previous employer's name"
        End Field

        Field EMPLOYER_STREET                                 
            Same Line
            Column 34
        End Field

        Field YEARS_EMPLOYED                                  
            Same Line
            Column 66
        End Field
    End Group
End Panel

You can put help panels anywhere inside a LAYOUT statement, as long as they are outside all PANEL declarations.

You can create special viewports for help panels. Doing so allows you to position the help panels anywhere on the display. Also, the RETAIN clause allows you to specify that a help panel not be removed from the display when the operator terminates help. Therefore, the help information can remain on the screen while the operator is entering data in the field on which help was needed. For more information on the RETAIN clause, see the description of the POSTDISPLAY declaration in the VSI DECforms IFDL Reference Manual.

To display different help panels when the operator presses Help several times in succession, you can redefine the function responses for the NEXT HELP and TERMINATE HELP built-in functions within each help panel. For example, if the first help panel to be displayed is the EMPLOYEE_INFORMATION_HELP help panel, you use function responses inside that panel to display other help panels.

Help Panel EMPLOYEE_INFORMATION_HELP
    Function Response Next Help                                 
        Activate
            Panel SECOND_HELP_PANEL
        Position To Panel SECOND_HELP_PANEL
    End Response
    .
    .
    .
End Panel

Help Panel SECOND_HELP_PANEL
    Function Response Next Help                                 
        Activate
            Panel THIRD_HELP_PANEL
        Position To Panel THIRD_HELP_PANEL
    End Response

    Function Response Previous Panel                            
        Deactivate
            Panel SECOND_HELP_PANEL
        Position To Previous Panel
    End Response
    .
    .
    .
End Panel

Help panel THIRD_HELP_PANEL
   .
   .
   .
End Panel

Panel USER_PANEL
    Use Help Panel
        EMPLOYEE_INFORMATION_HELP
    .
    .
    .
End Panel

On OpenVMS systems, you can create a text library containing help text and use a procedural escape to scroll an array of text lines on the help panel display. For sample files that support this approach for character-cell terminals, see the files forms$demo_show_textlib.ifdl and forms$demo_textlib.cob in the FORMS$EXAMPLES directory. These files contain comments explaining the procedure.

You might want to present a Motif style windowing environment on a character-cell terminal. For information about designing and implementing screens, controls, menus, and dialog boxes, see the VSI DECforms Style Guide for Character-Cell Devices. For another example of a form that demonstrates a windowing environment for a character-cell layout, see the Window Simulation demo in the OpenVMS examples directory.

The Form Manager collects data prior to a procedure call and distributes it after the call. The amount of data that is passed as parameters affects performance. Because parameters passed by reference and by descriptor are read and write enabled, you should transfer only the data you need,to use the minimum processing time.

To optimize performance, you should limit array transfers, as described previously in Section 12.1.1, “Transferring Data”. Use SOURCE and DESTINATION clauses when passing form records as parameters to simulate read-only (source) and write-only (destination) parameters, or use the parameter passing mechanism BY VALUE in the CALL response step to gain the effect of a read-only parameter.

If you send records in an escape routine, you might want to create records especially for the escape routine. Sometimes the data you pass to an escape routine might not be the same data you send to the application program. Using a separate record for the escape routine ensures that only relevant data is transferred.

Field ACCOUNT_BALANCE
   Highlight Reverse When ACCOUNT_BALANCE < 0
End Field

Whenever a form data item referenced in a WHEN expression could change,as ACCOUNT_BALANCE in the previous example, the Form Manager reevaluates the expression if the field is on a displayed panel. You can control evaluation by carefully selecting the form data items used in the expression. Consider using additional form data items,and then setting them in explicit LET response steps. Data transfer and escape routines can modify large amounts of form data, which can trigger expression evaluation. Avoid complex expressions; character conditional expressions are the most efficient.

Field ACCOUNT_BALANCE
   Output " " When (STUDENT(3).GRADE > "A") AND
   (FACULTY(8).NAME = SAVED_NAME)End Field

Limit use of CONCEALED WHEN to icons and to fields that need non-echoed input such as passwords.

The activation list contains all the fields and icons, eligible for data input or function key input. The primary performance consideration for the activation list is the number of items on it.

You should avoid large activation lists. Certain navigation operations are sensitive to the length of the list. For example, the POSITION TO NEXT PANEL response step searches forward through the activation list for the first field not on the current panel.

Activating entire panels, rather than individual items, is more efficient when you need to add all the items to the activation list.

During accept phase, you should add items to and delete items from the list as needed, rather than create one large activation list. For example, you can avoid activating a panel group until the operator moves off the field immediately before it. If the operator does not visit the group, the Form Manager does not have to activate all the fields in the group.

If you do use the method just described, the performance cost of activating the panel group occurs at the point the operator moves into the group. You might prefer that this cost occur when the panel is first displayed. This trade-off depends on the size of the panel group, how likely it is that the operator will visit the group, and where the cost is least noticeable. You can try various activation possibilities and see which ones best suit your needs.

After accept phase, deactivate fields and panels you no longer need. Deactivating entire panels is more efficient that deactivating individual items.

You can specify validation when the operator leaves a field (field validation), and again at the end of accept phase (request validation) to validate all items on the activation list. Request validation is useful for cross-field validation; data entered or changed later in the form might invalidate an earlier check. The only way the Form Manager can guarantee that all validation is satisfied at the same time is to perform all validation at request validation time.

When you have multiple sessions enabled on a single input device, keep in mind how the sessions interact on the display.

Each session controls its own viewports. Viewports are a session-wide entity: if you have a form with three viewports enabled twice on a single display device, the Form Manager considers these three viewports as six individual viewports for purposes of display.

The Form Manager must convert all data that appears on the screen to character format to display the data. If the data can be stored in form data in character format, and transferred to and from the program in character format, no data conversion has to occur for your form to perform optimally.

Often, however, data needs to be used in other formats, and data conversion is necessary. Consider where the data is used in what format, and then decide the best place for conversion.

For example, suppose you need data in your program in a binary format, such as longword integer, and that data is displayed only in one field on one panel. You might store the data in a longword integer in form data and let it be converted twice: once on data entry (input)and once on display (output).

However, if the data item is displayed on many panels, the Form Manager would need to convert the data item into a character format every time it is displayed. If the record is sent instead as a longword integer with a corresponding form data item of character format, the Form Manager would need to perform data conversion only twice: once at the beginning of the send and once at the exit. There would be no need to perform data conversion for input and output.

Although DECforms can scroll partial screen areas,it can take advantage of VT100-, VT200-, or VT300-series terminal hardware scrolling, if the scrolling region spans the full width of the screen.

Because the message panel frequently scrolls, you should make message panels the full width of the screen (layout).

If you use VT400-series terminals, DECforms takes advantage of the device's rectangular area copy feature. For this type of terminal, scrolling is efficient, regardless of the scrolling region's size.

If you are going to use double-high and double-wide attributes, you should specify panels that use the entire width of the display device. Also, do not mix double-high and double-wide attributes with single-high and single-wide attributes on the same line.

For optimum screen clearing performance, specify that the viewport touch an edge of the display device. If the viewport touches both edges of the screen, performance is improved, but it is not significantly better than having just one viewport edge touch the display edge. Having the viewport touch both edges as well as the top and bottom of the screen is most efficient, because the Form Manager can clear an entire area rather than erase each line individually.

If the display device is a VT200-, VT300, VT400-, or VT500-series terminal and the viewport edges do not touch the edge of the screen, there is no significant performance penalty during screen clearing. However, if the device is a VT100 terminal, there is a performance penalty because of the way in which the VT100 clears the screen.

When the Form Manager displays panels, it attempts to buffer its output to minimize the number of $QIO operations. The MAXBUF system parameter sets the maximum size of buffered I/O transfer. To ensure the timely display of panels, you should set the value of MAXBUF to a minimum of 2048.

If you set MAXBUF to a value higher than 2048, panels might not be displayed until a buffer is filled (although transaction processing performance will improve). For example, if you display two panels in the same DISPLAY clause,and both panels are fairly small, the panels might not be displayed until the Form Manager has processed both of them.

For more information about the MAXBUF system parameter, see the OpenVMS documentation on the System Generation Utility (SYSGEN).

The expensive performance of complex field pictures is the result of necessary device handling. It is not due to any deficiency in DECforms. For more information about picture strings, see the Picture String section of the VSI DECforms IFDL Reference Manual.