One of the most important features provided by DECforms is that it makes your application program device-independent. No application program written for a DECforms application needs to be rewritten to support new devices. This feature of DECforms helps reduce the cost of maintaining your application.

DECforms offers sophisticated screen control capabilities. For example, you can overlap objects on the display and conceal or reveal the contents of a field depending on the value of a variable. You can display different information for novice operators than for experienced operators. You control whether field contents are concealed and whether novice information is displayed in the form, instead of in the program.

You can get operator input to a number of panels (a panel is similar to an FMS form) without returning control to the program. You can also display more than one panel at a time. You determine how and when the panels are displayed with statements you specify in the form.

DECforms provides a beneficial model for providing online help to your operators. You can provide help when the operator asks for it, as you can in FMS, and you can provide help that is displayed automatically. DECforms can display help automatically before the operator begins a task to provide the operator with hints on completing the task. This type of help can increase the productivity of your operators.

You can call a program subroutine from your form during form processing. (During form processing DECforms uses the form to control the display, control operator input, validate data and pass data between the form and program.) This capability is similar to that provided by VAX FMS user action routines (UARs). The ability to call program subroutines allows you to perform such tasks as mathematical calculations and database updates between, for example, the operator ending input in one field and beginning input in the next field. You can also call a subroutine at several other points during form processing.

In FMS, the term “form” refers to a screen image and the binary file that describes that image. The screen image is the visual representation of the binary file; that is, the screen image is the form appearance. The binary file is the description of the screen that you create with FMS components like the Form Editor.

In DECforms, the term form refers to a structured interface to an application. The structured interface describes what is displayed on a terminal, how data used on the display is validated and stored,and how operator input is accepted.

In FMS, a form can be stored independently or in a form library. In DECforms, each form is a separate file. This file can be either an IFDL source file or a binary image file,called a form file.

The IFDL source file is similar to the sum of all your FMS form descriptions and form processing logic for a single application. It is an ASCII file that contains IFDL statements describing form appearance, data validation, form processing, and data transfer. Section 2.3, “Introduction to the IFDL” describes the IFDL in more detail.

The form file is similar to your FMS form library. It is the file accessed by your program at run time. DECforms makes the parts of it that are needed during application execution memory resident, which helps your application execute efficiently. (You can combine form files into a shareable image if you need better performance. See the VSI DECforms Programmer's Reference Manual for more information.)

The second element of a DECforms application, the program, is similar to a program in an FMS program. For example,a DECforms program can be written in any language that supports the OpenVMS Calling Standard. Also, a DECforms program can contain subroutines that are called from the form and that are similar to the UARs found in an FMS program. The DECforms program performs all the input and output to file storage or a database that needs to be done by the application, and it calls requests. Requests are DECforms routines that perform form processing; they are functions that return a status value and parameters.

These request calls are the only entry points to DECforms that are available to the program. All other DECforms activity must be specified in the form.

Unlike FMS applications, DECforms applications pass only whole records between the program and form. Thus, the program must contain a declaration of the record to be passed, and this record must match the declaration of a record in the form. Unlike an FMS program, the DECforms program does not have direct field-level control of operator input. That control is in the form in DECforms.

You can interrupt form processing and call a subroutine in your program. This interruption is called a procedural escape, and the program subroutine is called an escape routine.

The sections that follow introduce DECforms request calls and escape routines. They do not explain how you perform input and output to file storage or a database because you access your files and databases just as you do when you use FMS. For more information on the requests and on procedural escapes, see the VSI DECforms Programmer's Reference Manual.

As shown in the list, the Form Manager performs a request response during the processing of a request. The response is either one of the default responses DECforms provides or a response that you declare in the form.

The Form Manager also performs responses when it accepts operator input. During operator input, the Form Manager performs entry responses, function responses, validation responses, and exit responses.

When processing most requests, the Form Manager modifies the terminal display. The Form Manager determines how to modify the display by following instructions in the form.

The Form Manager can control a display that is 1 to 511 columns and 1 to 255 lines. The actual number of columns and lines available to you depends on your display device. For example, if you are using a VT200 terminal, the display can be from 1 to 132 columns and from 1 to 24 lines.

The Form Manager can display more than one panel at a time, and it can display more than one viewport at a time. Which panel and viewport the Form Manager displays is controlled by what data entry the operator needs to perform. You use responses in the form to control what panel fields are available for operator entry.

The Form Manager can also use more than one form at a time. It determines which form it should use by checking the session identification number you pass as a parameter in request calls.

If the Form Manager needs to write a message (such as an error message or a help message) to the terminal, it displays the message in a special area called a message panel. You can declare a message panel in the form and control its size and position on the display. If you do not declare a message panel,the Form Manager creates a default, one-line message panel. When it needs to display a message,the Form Manager displays the message panel on the last line of the display. The Form Manager can scroll text within the message panel, so messages can be any length. You can send text to the message panel from either the program or the form.

In addition to controlling what is displayed, the Form Manager controls the order of operator input. To do this, it maintains a list of items that need input, called an activation list.

By default, the Form Manager builds an activation list during the processing of each RECEIVE and TRANSCEIVE request. You use response steps to determine what items the Form Manager adds to the activation list. If you do not specify what items to add to the list, the Manager builds a default activation list. The Form Manager builds the default activation list by activating form data items that correspond to the record fields in the receive form record.

After it builds the activation list, the Form Manager processes it. By default, the Form Manager begins with the first unprotected item on the activation list. In this case, the Form Manager displays the FIELD_THREE panel field and accepts and validates operator input. If the operator presses the key bound to the default NEXT ITEM function and the input into FIELD_THREE passes validation, the Form Manager accepts operator input into the FIELD_TWO panel field, and so on.

You control the order in which the Form Manager processes activation items using the POSITION response step. Most built-in functions, such as the NEXT ITEM and PREVIOUS ITEM functions, contain the POSITION response step. For example, the NEXT ITEM function contains the POSITION TO NEXT ITEM response step. This response step makes the next item on the activation list into the current item (the one in which the operator enters data).If you use the built-in functions, the order in which items appear on the activation list and the function keys the operator presses control the order of operator input.

The Form Manager continues activation list processing until the operator gives valid input to all items on the list, you interrupt request processing in a response, or you call the CANCEL request to cancel outstanding requests.

For more information on the activation list and the POSITION response step, see the VSI DECforms Programmer's Reference Manual.

The Form Manager manipulates data when it responds to request calls, controls the display, and controls operator input. Specifically, the Form Manager performs data type conversions, formats data for display and storage in form data items, and checks the validity of data.

When the Form Manager displays data, it converts the data from its original data type to a character string. Likewise, the operator enters a character string, which the Form Manager converts to the proper data type before storing it in the form. When necessary, the Form Manager also converts data that it passes between the form and program or between two data items. Notice that this means your program does not have to perform data type conversions; the Form Manager handles that task for you. However, you must be sure the Form Manager can convert data from its original data type to another data type. For example, if you use two data items in an assignment statement, you must be sure that the Form Manager can convert the data type of the data in the source data item to the data type of the object data item. See the VSI DECforms Programmer's Reference Manual for information on how the Form Manager converts the data type of data.

To make sure data displayed or stored by the Form Manager is valid, DECforms allows you to specify input pictures and output pictures. An output picture describes editing that the Form Manager performs when moving a value from storage to the display. It specifies details such as where a decimal point appears, what sign character should be used, and so forth. The input picture specifies what input is valid in a particular field. It also specifies how a value is edited when the Form Manager moves it from the display to storage.

You can specify input validation beyond that provided by the input picture in the form. For example, you can have the Form Manager verify that input is within a particular range of values. If the input is outside the range, it is invalid and the Form Manager prompts the operator to input a valid value in that field.

You may need to rename panel fields and form data items created by the FMS Converter. More than one form data item in the IFDL source file the Converter creates may have the same name. Also, if you used Named Data in an FMS form, the Converter output may need modification.

The Converter converts each FMS form field to a DECforms panel field. If two form fields in your FMS application have the same name, the Converter creates two panel fields that have the same name. The Converter also creates a form data item for each panel field it creates. Therefore, if two panel fields have the same name, two form data items have the same name. DECforms requires that each form data item have a unique name,so you must rename or remove one of the form data items. (If you convert form libraries, the Converter flags duplicate names in form data with a message, so you can find them easily.)

DECforms requires that panel fields have the same name as the form data items to which they correspond. Therefore, you should verify that the form data items you rename correspond to a panel field by either creating a new panel field with the new name or renaming an existing panel field.

Because the FMS Converter creates a panel field and form data item for each field on each of your FMS forms, you may have duplicate fields and data items that are not necessarily named the same. For example, suppose your FMS application displays a customer account number on three forms. Suppose that you call each field that displays the account number a different name on each form. In this case, the Converter creates three panel fields and three data items to store and display the customer account number. In DECforms you usually would need only one data item to store the customer account number. Therefore, you should remove all but one account number form data item. You must then rename the panel fields that display the account number so that they match the name of the form data item that stores the account number.

Section 5.3, “Modifying the Converted IFDL Source File” shows examples of renaming and removing duplicately named data items and panel fields.

The FMS Converter converts each Named Data item to a form data item. To store particularly long values in a Named Data item, you may have created several Named Data items and given them the same name. The FMS Converter declares a single form data item to correspond to these Named Data items. The FMS Converter declares the form data item to be as long as the sum of the lengths of the Named Data items.

If your application contains duplicately named Named Data items associated with different forms, the FMS Converter declares separate form data items to replace those Named Data items. Thus, if you have Named Data with the same name on different forms in a form library, the Converter may have declared form data items with duplicate names. You must rename or remove one of the duplicately named form data items.

FMS allows you to use any characters in any format for the name of a Named Data item. DECforms allows only the characters A to Z, a to z, 0 to 9, dollar sign ($), and underscore (_) in the names of identifiers. DECforms identifiers must begin with an alphabetic character and be fewer than 32 characters in length. When the Converter encounters a name it cannot change to a valid DECforms identifier name, it writes the invalid name to the output IFDL source file. The Converter also writes a message indicating that the invalid name cannot be used in DECforms. You must change any invalid names to valid DECforms names.

DECforms data transfer is done on a record-by-record basis. To allow record-by-record data transfer, you must declare form records. The form records you declare show the Form Manager how to distribute data that comes from your program into form data items and how to collect data from form data items before it is sent to your program. Your form records should associate related form data. For example, you may find that the form data items displayed on one panel are related and make a reasonable form record. On the other hand,you may find that you need only one form record because you can pass all the data the form needs to it at once.

You must also decide what data type to assign to the fields in the form record. DECforms can store data of several different types inform data items. This allows you, for example, to pass a LONGWORD INTEGER between the form and program. DECforms converts the integer into a string for display and then converts operator input to a LONGWORD INTEGER that is returned to your program. Eventually, you may want to take advantage of this DECforms feature and declare form record fields that have data types appropriate to the data that is passed.

Initially, however, it is probably best to use the CHARACTER data type for all your record fields. Passing character strings is somewhat easier than passing atomic data. When you use character strings, you must be sure that the length of each program record field matches the length of its corresponding form record field. When you pass atomic data, you must be sure that not only the length, but also the data type, of the form record fields and program record fields match. Because you must be aware of how data is stored internally by your programming language and DECforms, passing atomic data can be more difficult than passing character strings. Also, passing atomic data may require that you change the data read into your program from string data to atomic data. You must plan any data type changes carefully. Section 3.5.2, “Form Record Field and Program Record Field Data Types” describes how to modify your application to pass numeric data to the form.

Form PERSONNEL_FORM
   .
   .
   .
  Form Record EMPLOYEE_RECORD                         
    DATE_AND_TIME           Character (7)
    EMPLOYEE_NAME           Character (30)
    EMPLOYEE_NUMBER         Character (10)
    EMPLOYEE_BIRTH          Character (7)
    SPOUSE_NAME             Character (30)
    SPOUSE_BIRTH            Character (7)
    INSURANCE_CARRIER       Character (30)
    INSURANCE_ID_NUMBER     Character (15)
    OFFICE_ADDRESS          Character (7)
    VMS_MAIL_ADDRESS        Character (40)
  End Record

  Form Record ORG_CHART_RECORD
    Copy ORGANIZATION_RECORD From Dictionary End Copy 
  End Record
   .
   .
   .
End Form

Once you declare form records, you must declare logically equivalent program records. Logically equivalent records have the same number of fields, the fields create the same OpenVMS internal data type, and the fields have the same length. You then pass data between the form record and program record using the DECforms FORMS$SEND, FORMS$RECEIVE, and FORMS$TRANSCEIVE calls. See Section 4.2.3, “Sending Data to the Form” and Section 4.2.4, “Getting Data from the Form” for information on declaring program records and transferring data using DECforms.

The FMS Converter creates USE HELP MESSAGE clauses in the panel fields it creates to emulate the messages associated with the form fields in your FMS application. It also converts your FMS help forms to DECforms help panels. However, the Converter cannot distinguish FMS data entry forms from FMS help forms. Therefore, it converts all FMS help forms into DECforms panels. Also, the Converter creates IFDL syntax to associate help panels with data entry panels, but it creates that syntax inside comment characters. The comments are needed to allow your converted IFDL source file to translate correctly before you modify help. This section explains the Converter's output for help and how you must modify it.

Panel HELP_ACCOUNT_DATA_PANEL
  Viewport HELP_ACCOUNT_DATA_VP
  Display %Keypad_application
  Literal Rectangle
   .
   .
   .
End Panel

Help Panel HELP_ACCOUNT_DATA_PANEL
  Viewport HELP_ACCOUNT_DATA_VP
  Display %Keypad_application
  Literal Rectangle
   .
   .
   .
End Panel

The FMS Converter creates a form data item to match each panel field it creates to replace an FMS form field. The Converter assigns a data type to each form data item it creates. The Converter assigns the INTEGER data type to a form data item it creates to correspond to an FMS field picture of all 9s. If the FMS form field picture contains a decimal point, the FMS Converter creates a form data item that has the DECIMAL data type. If the field is one of the FMS predefined DATE fields, the Converter assigns the DATE or TIME data type. Otherwise, the Converter assigns the CHARACTER data type to the form data item.

You can use any of these data types for your form data items. The data type of a data item does not have to match the data type of its corresponding form record field. If the record field declaration creates a different OpenVMS data type in internal storage than the form data item declaration, the data is converted from the record field data type to the form data item data type when it is stored in the form data item. The data is converted from the form data item data type to the form record field data type when it is passed to the program.

Converting data from one data type to another is less efficient than passing between variables that have matching data types. You should limit the number of data type conversions that are performed during data transfer.

Because your FMS program passed only CHARACTER data to FMS, your program may be converting data from the CHARACTER data type to an atomic data type. You can make your program more efficient by using atomic data types to store this data. Also, you may want to make the data type of form record fields atomic to match the data type of corresponding form data items. When the data type of a form record field matches the data type of a form data item, the Form Manager does not have to convert the data to a new data type, which makes your application more efficient. To avoid converting data between the CHARACTER data type to an atomic data type, you can exchange atomic data with your form.

To store and use atomic data, program record fields must have atomic data types. Remember that the data the record fields store must also be atomic. You may need to modify the data itself if it is initially loaded into your program from a file or database. The file or database may store string data, which you must modify to be numeric data.

To pass atomic data to the form, your form record fields must have atomic data types. For your program and form to exchange data, the data in fields that correspond to each other must have the exact same data type internally. All OpenVMS products store data using OpenVMS data types. Each product has its own syntax for declaring data, which means that you cannot compare data declarations in two languages to determine if data matches internally. For example, you cannot assume that a DEC COBOL data item declared PIC 9(9) is stored the same internally as a DECforms data item declared as INTEGER(9). To see if the data is stored the same internally, you must determine how DEC COBOL and DECforms represent data items using OpenVMS data types. The VSI DECforms IFDL Reference Manual contains a table that describes how DECforms stores data internally. You can use that table and the documentation for your programming language to be sure that the data type of corresponding form record fields and program record fields match.

DATA DIVISION.
*
* Declare a record that passes numeric data.
*
WORKING-STORAGE SECTION.                                         
01   GET_CHECK                       GLOBAL.
     05 PAYTO_NAME               PIC X(30).
     05 CHECK_AMOUNT             PIC 9(5) COMP.
     05 MEMO                     PIC X(35).
PROCEDURE DIVISION.
0.
*
* Get input into the GET_CHECK record.
*
     CALL "forms$send" USING BY DESCRIPTOR SESSION_ID            
                                             "GET_CHECK"
                               BY REFERENCE  RECORD_COUNT
                               OMITTED
                               OMITTED
                               OMITTED
                               OMITTED
                               OMITTED
                               OMITTED
                               OMITTED
                               BY DESCRIPTOR GET_CHECK
                         GIVING FORMS_STATUS. 

/* Declare a form record to pass */
/* numeric data.                 */
Form Record GET_CHECK
    PAYTO_NAME                Character (30)
    CHECK_AMOUNT              Longword Integer
    MEMO                      Character  (35)
End Record

The form record contains three fields. The first field has the CHARACTER data type; its length matches the length of the first program record field. The second field has the LONGWORD INTEGER data type. DECforms represents data items with the LONGWORD INTEGER data type as a VMS LONGWORDINTEGER internally. This data type matches the internal representation of the program record field data type. The third field has the CHARACTER data type and appropriate length.

When the FMS Converter creates panel fields in your IFDL source file, it writes them to the source file in the order you specified using the ORDER phase of the FMS Form Editor or the ORDER statement of the FMS Form Language. The order in which panel field declarations appear in the converted IFDL source file can be significant for operator input.

If you use the ACTIVATE CORRESPONDING RECEIVE ALL or the ACTIVATE CORRESPONDING SEND ALL response step, the Form Manager activates panel fields. The Form Manager activates panel fields that correspond to the record fields in the form record you name in a request call.

When the Form Manager activates a panel field, it adds an item to the activation list. Unless you explicitly name panel fields to activate, the order of panel field declaration in a panel controls the order in which the Form Manager adds activation items to the activation list. The first item the Form Manager adds to the activation list corresponds to the first field declared in the panel. The second item corresponds to the second field, and so on.(See the VSI DECforms Programmer's Reference Manual for more information on the ACTIVATE response step.)

By default, the Form Manager begins operator input by getting input to the first unprotected item on the activation list. If the operator presses the key bound to the default NEXT ITEM function and the input to the first activation item passes validation, the Form Manager gets input to the second activation item. If the operator continues to give input by entering datain fields and pressing the key bound to the NEXT ITEM function, operator input proceeds in the order in which items appear on the activation list. The order in which items appear on the activation list is controlled by the order in which you declare panel fields (when you use response steps that do not explicitly name panel fields). Thus, the order of panel field declaration can control the order of operator input.

You may need to change the order in which panel fields appear in your IFDL source file if you plan to use ACTIVATE CORRESPONDING RECEIVE ALL. Be sure the panel field order reflects the order you want to be used for operator input.

If your FMS form calls UARs other than pre-help or post-help UARs, the FMS Converter creates responses in your converted IFDL source file that contains the CALL response step. The CALL response step names your UAR. You can use your UAR as a DECforms escape routine, so the CALL response step can call the same code as was called in your FMS application.(You must pass certain parameters to the FORMS$ENABLE call and link your application with a vector to use a UAR as an escape routine. See Section 7.7, “Using Escape Routines” for more information.)

Although DECforms allows you to continue to use your UARs as DECforms escape routines, you may not need to do so. The IFDL allows you to specify more form processing than the FMS Form Language, so you may be able to perform tasks you used to perform in UARs in your DECforms form. If you can avoid calling DECforms escape routines, your application is more efficient.

To determine whether you can perform the UAR's task in a response, see the description of the effect of each response step in the VSI DECforms Programmer's Reference Manual.

The FMS AFCX (Alter Field Context) call alters the default input mode fora field. It allows you to change the Insert/Overstrike mode of the field and the cursor position in the field.

DECforms does not allow you to modify the editing mode of a field or the position of the cursor in a field. ( DECforms calls Insert/Overstrike mode editing mode.) DECforms gives the operator control over the editing mode and the position of the cursor.

The operator can change the editing mode by invoking the built-in INSERT OVERSTRIKE function. The operator can move the cursor using the built-in functions, such as the CURSOR LEFT and CURSOR RIGHT functions. See the VSI DECforms IFDL Reference Manual for information on what built-in functions DECforms provides.

Remove all AFCX calls from your program.

The CLEAR_VA (Clear Video Attributes) call clears the screen of video attributes and sets certain other terminal attributes. The FIX_SCREEN (Repair Overwritten Lines of Terminal Screen) call allows you to repair lines you overwrote with direct terminal output. These calls are useful primarily for modifying the screen and resetting terminal attributes before or after you use software other than FMS to modify the display.

DECforms does not allow you to directly refresh particular lines on the screen because DECforms operates on viewports and panels. You can clear the area occupied by a viewport, but you cannot specify clearing lines 10 through 15. DECforms does not have a call or procedural form statement to reset terminal attributes.

You should remove FMS CLEAR_VA and FIX_SCREEN calls from your program. You may be able to modify the screen and reset video attributes using a screen management tool other than DECforms before you return control to DECforms. Alternatively, you could separate the screen into parts and use one part only for DECforms and another part for screen management you do outside of DECforms. See Section 4.3.15, “Refreshing a Shared Screen” for information on refreshing a shared screen.

The DEL (Remove Form from Memory-Resident Form List) and READ (Read Form Into Memory) calls maintain a memory-resident form list. In DECforms, all panels are memory resident if they belong to the layout selected for use at the beginning of application execution. Therefore, you need not maintain a memory-resident form list from your DECforms application program, and you should remove all DEL and READ calls from your program.

The FCHAN (Return Free Channel) call allows you to determine which I/O channel is available. The TCHAN (Set Terminal Channel) call allows you to specify a physical terminal channel that FMS uses for the current terminal. DECforms does not allow you to use physical channel numbers because they are device specific. Therefore, you should remove all FCHAN and TCHAN calls from your program.

The LEDON (Turn Terminal LED On) and LEDOF (Turn Terminal LED Off) Form Driver calls allow you to control the LEDs on aVT100 terminal. Because most terminals do not have the same LEDs as VT100terminals, DECforms does not provide a way to control them. You should remove LEDON and LEDOF calls from your program.

Instead of lighting LEDs, you can signal the operator by displaying a message on the message line or by changing the appearance of the screen. See Section 4.3.4, “Controlling Output to and Input from a Terminal Line” for one way of displaying a message.

When you use the GETAL call, you get data from all fields on the form. The data is concatenated and returned to a variable in your program. To allow you to determine the contents of the variable, FMS supplies two calls:RETFO and RETLE. The RETFO (Return Field Names in Order) call returns the name of the first field on the form, the second field on the form, and so on. The RETLE call (Return Length of Specified Field) is similar, except that it returns the lengths of fields, instead of their names.

Because you always exchange records between the form and the program in DECforms, you do not need the RETFO and RETLE calls. The program always knows the structure of data it receives. Therefore, remove all RETFO and RETLE calls from your program.

The SCR_LENGTH (Set Screen Length) and SCR_WIDTH (Set Screen Width) calls allow you to adjust the terminal attributes table for a terminal. DECforms does not allow you to modify the attributes of a specific terminal. Instead of modifying the attributes of the device to fit your form in DECforms, you modify the form to fit different devices. You should remove SCR_LENGTH and SCR_WIDTH calls from your program.

The SSRV (Specify Status Reporting Variables) call allows you to specify a location in which FMS stores the I/O status and completion status of each subsequent call. The STAT (Return Status from Last Call) call returns the status code for the previous call. In DECforms, you call the Form Manager like you call a function. Each DECforms call returns a LONGWORD INTEGER value that gives its status. Therefore, you need not tell the Form Manager where to store status or when to return status. Remove SSRV and STAT calls from your program.

Each DECforms call has a defined format, including a number of parameters. The parameters appear in the calls in the order defined by the format of the call. Some parameters have a slightly different purpose,depending on which call they appear in. The following list describes the parameters you need to open your form environment, exchange data with the form, and close your form environment.

form-object-address

Required argument that is either the FORMS$AR_FORM_TABLE symbol name or 0. The FORMS$AR_FORM_TABLE symbol name is defined in an object module stored in a system library. The symbol is a pointer to the address of a special object module, called a form object. The form object module contains the addresses of escape routines and forms that are linked with the application. Until you are ready to use escape routines, you can pass 0 in this parameter. See Section 7.7, “Using Escape Routines” for more information on using escape routines.(Passed by value.)

display-device-specification

Name of the display device to be used. You should pass SYS$INPUT in this parameter. This parameter serves the same general purpose as ATERM. (Passed by descriptor.)

session-id

Sixteen-character string that identifies the session.

The Form Manager returns the session identification string to your program during the ENABLE request. When used in a call to the ENABLE request, this parameter is similar to LCHAN and AWKSP. It causes the Form Manager to request a physical channel and create a session identification string. The session identification string associates the display device with the currently loaded form.

When used to call the SEND or RECEIVE request, this parameter is similar to the FMS STERM(Set Current Terminal) call. It controls what session (and therefore what terminal) the request effects. If you are using more than one session, you switch between them by passing a different session identification string for each session.

When used in a call to the DISABLE request, this parameter is similar to LCLOS and DWKSP in that it identifies the form that the Form Manager closes. It also resembles DTERM because it identifies the terminal to be detached. (Passed by descriptor.)

file-specification

File specification for the form file to be used. This parameter is similar to the LOAD call because it identifies the set of panels to be moved into memory. (Passed by descriptor.)

form-specification

Name of the form as specified in the IFDL FORM statement. You should pass the name of the form only if your form is linked with your program or stored in a shareable image. See the VSI DECforms Programmer's Reference Manual for more information on linking forms and storing them in shareable images.

record-identifier

Name of the form record or record list that matches the program record you are passing. The Form Manager uses this parameter to determine which form record or record list to use for this request and which request response (if any) to perform during the processing of this request.(Passed by descriptor.)

record-count

Specifies the number of records you are passing. (Passed by reference.)

timeout

Specifies the number of seconds the operator has to enter data to fields. DECforms resets the timer between each operator keystroke. When used in a call that requires operator input, this parameter is similar to the FMS STIME (Set Field Entry Timeout) call. (Passed by reference.)

record-message

Data you are passing. (Passed by descriptor.)

You can omit these parameters from the calls without losing any of the functions that you use in FMS.

If you omit a required parameter, you may, depending on your programming language, need to supply a placeholder for the parameter. For example,you can use the DEC COBOL OMITTED phrase to indicate that you have omitted a required parameter from a request call in a DEC COBOL program.

DECforms provides a single call to open your form environment—the FORMS$ENABLE call. The FORMS$ENABLE call invokes the ENABLE request, which causes the Form Manager to initialize the current session. To initialize a session, the Form Manager finds the form to be used and selects a layout from that form. The Manager also attaches the display device and performs other internal tasks to set up the form environment. If you do not define an ENABLE response, the Form Manager performs the default ENABLE response, which causes it to clear the display.

The format of the call follows (optional parameters are shown in brackets):

FORMS$ENABLE  form-object-address, display-device-specification,
              session-id [file-specification,]
              [form-specification, receive-control-text,
              receive-control-text-count],
              [send-control-text, send-control-text-count], [timeout],
              [parent-request-id], [request-options]

01  SAMP_FORM             PIC X(21)       GLOBAL  VALUE "SAMP.FORM".   
01  SESSION_ID            PIC X(16)       GLOBAL.

01  DISPLAY_DEVICE        PIC X(9)        GLOBAL  VALUE "SYS$INPUT".
01  FORMS_STATUS          PIC S9(9)COMP   GLOBAL.

*
COPY "SYS$LIBRARY:FORMS$COB_DEFINITIONS.LIB".                          
*
* Set up DECforms Environment
*
        CALL "forms$enable" USING OMITTED                              
                                  BY DESCRIPTOR DISPLAY_DEVICE
                                  BY DESCRIPTOR SESSION_ID
                                  BY DESCRIPTOR SAMP_FORM
                            GIVING FORMS_STATUS.                       
        CALL "SRVCHK" USING FORMS_STATUS.
   .
   .
   .

Once you modify your program, you may want to add an ENABLE response to your form. Position the response in your IFDL source file directly following any function declarations. You can specify only one ENABLE response per layout.

To pass data to the form in DECforms, you use the FORMS$SEND call. This call invokes the SEND request. The SEND request causes the Form Manager to pass data from the program record to form data items. The Form Manager determines which form data items are to store the data by looking at the form record name you pass in the request call. Using that form record name, the Form Manager determines the names of form records fields in that form record. The Form Manager distributes the program data into form data items that have the same name as fields in the form record.

You can specify a SEND response in the form to specify, for example, that the Form Manager signal the operator when the new data is displayed. The Form Manager does not contain a default SEND RESPONSE.

Figure 4.1, “Default Send Transfer in DECforms” shows how data is transferred when you call the SEND request and do not specify as end response.

The following shows the format of the FORMS$SEND call (optional parameters are shown in brackets):

FORMS$SEND   session-id, send-record-name, send-record-count,
             [receive-control-text, receive-control-text-count],
             [send-control-text, send-control-text-count],
             [timeout], [parent-request-id], [request-options],
             [[send-record-message], [send-shadow-record],]

*
   .
   .
   .
01  RECORD_COUNT          PIC 9(2) COMP  GLOBAL  VALUE 1.   
*
01  ACCOUNT                              GLOBAL.            
    05  ACCT_NUMBER       PIC X(5).
    05  OPEN_DATE         PIC X(7).
    05  ACCT_NAME.
        10  LAST_NAME     PIC X(20).
        10  FIRST_NAME    PIC X(15).
        10  MIDDLE_NAME   PIC X(15).
    05  ACCT_STREET       PIC X(30).
    05  CITY-STATE-ZIP.
        10  CITY          PIC X(20).
        10  STATE         PIC X(2).
        10  ZIP           PIC X(5).
    05  ACCT_HOME_PHONE   PIC X(10).
    05  ACCT_WORK_PHONE   PIC X(10).
    05  ACCT_PASSWORD     PIC X(12).
   .
   .
   .
*
* Send account data to the form.
*
        CALL "forms$send" USING BY DESCRIPTOR SESSION_ID    
                                              "ACCOUNT"
                                BY REFERENCE  RECORD_COUNT
                                OMITTED
                                OMITTED
                                OMITTED
                                OMITTED
                                OMITTED
                                OMITTED
                                OMITTED
                                BY DESCRIPTOR ACCOUNT
                          GIVING FORMS_STATUS.
        CALL "SRVCHK" USING FORMS_STATUS.
   .
   .
   .

After you modify the program, declare a form record that is logically equivalent to your program record (unless one already exists). Logically equivalent records have the same number of fields, corresponding fields have the same length and matching data types. Matching data types are data types that create the same OpenVMS data type in internal storage.

You should name the fields in the form record the same name as the form data items into which you want the Form Manager to move data from the program. The form record field and form data item do not have to have the same data type.

If you write a SEND response, you name the SEND response the same as the form record name you specify in the send-record-name parameter of the FORMS$SEND call. This causes the Form Manager to perform that response when you call the SEND request and name that form record.

Form Data                                                   
    ACCTNO_FIELD          Character (5)
    OPEN_DATE             Character (7)
    LAST_FIELD            Character (20)
    FIRST_FIELD           Character (15)
    MIDDLE_FIELD          Character (15)
    STREET_FIELD          Character (30)
    CITY_FIELD            Character (20)
    STATE_FIELD           Character (2)
    ZIP_FIELD             Character (5)
    HOMEPH_FIELD          Character (10)
    WORKPH_FIELD          Character (10)
    SECRET_FIELD          Character (12)

    ACCOUNT_PASSWORD      Character (12)
End Data

Form Record ACCOUNT                                         
    ACCTNO_FIELD          Character (5)
    OPEN_DATE             Character (7)
    LAST_FIELD            Character (20)
    FIRST_FIELD           Character (15)
    MIDDLE_FIELD          Character (15)
    STREET_FIELD          Character (30)
    CITY_FIELD            Character (20)
    STATE_FIELD           Character (2)
    ZIP_FIELD             Character (5)
    HOMEPH_FIELD          Character (10)
    WORKPH_FIELD          Character (10)
    SECRET_FIELD          Character (12)
End Record
   .
   .
   .
    Send Response ACCOUNT                                   
        Let ACCOUNT_PASSWORD = SECRET_FIELD
    End Response

To get data from the form in DECforms, you use the FORMS$RECEIVE call. This call invokes the RECEIVE request. The RECEIVE request causes the Form Manager to pass data from form data items to the program record. To determine what values to pass to the program, the Form Manager reads the form record name you pass in the record identifier parameter. The Form Manager passes data from the form data items that have the same name as fields in that form record.

You can specify a RECEIVE response in the form to control some aspects of RECEIVE request processing. If you do not specify a RECEIVE response for the request, the Form Manager performs the ACTIVATECORRESPONDING RECEIVE ALL response step. This response step causes the Form Manager to activate each panel field that corresponds to the form record named in the record-identifier parameter. The Form Manager gets input to each of those panel fields and stores that input in form data items. Finally, it returns the input to the program.

Figure 4.2, “Default Receive Transfer in DECforms” shows how data transfer occurs when you call the RECEIVE request and accept the default response.

The following shows the format of the FORMS$RECEIVE call (optional parameters are shown in brackets):

FORMS$RECEIVE  session-id, receive-record-name, receive-record-count,
               [receive-control-text, receive-control-text-count],
               [send-control-text, send-control-text-count],
               [timeout], [parent-request-id], [request-options],
               [[receive-record-message], [receive-shadow-record],]

PROCEDURE DIVISION.
0.
*
* Get account data from the form
*
        CALL "forms$receive" USING BY DESCRIPTOR SESSION_ID
                                                 "ACCOUNT"
                                   BY REFERENCE  RECORD_COUNT
                                   OMITTED
                                   OMITTED
                                   OMITTED
                                   OMITTED
                                   OMITTED
                                   OMITTED
                                   OMITTED
                                   BY DESCRIPTOR ACCOUNT
                             GIVING FORMS_STATUS.
        CALL "SRVCHK" USING FORMS_STATUS.

This call gets data from the form data items that correspond to the ACCOUNT form record.

Once you have modified the program, declare a form record that is logically equivalent to your program record (unless one already exists). The record must have the same number of fields as your program record, the fields must be the same length, and the fields must have matching data types. Data types are matching when they create the same OpenVMS data type internally. Name the fields in the form record the same as the form data items from which you want the Form Manager to collect data to return to your program.

You can write a response to the RECEIVE request if you want an effect other than what is given by the ACTIVATE CORRESPONDING RECEIVE ALL response step. Specify the form record name you pass in the receive-record-name parameter to the FORMS$RECEIVE call. The Form Manager performs the receive response that is named the same as the receive-record-name parameter. Position the response in your IFDL source file directly following function declarations.

   .
   .
   .
    Function NEXT_ITEM Is %HORIZONTAL_TAB End Function
    Receive Response ACCOUNT
        Activate Field LAST_FIELD on ACCOUNT_PANEL
        Activate Field FIRST_FIELD on ACCOUNT_PANEL
        Activate Field MIDDLE_FIELD on ACCOUNT_PANEL
        Activate Field STREET_FIELD on ACCOUNT_PANEL
        Activate Field CITY_FIELD on ACCOUNT_PANEL
        Activate Field STATE_FIELD on ACCOUNT_PANEL
        Activate Field ZIP_FIELD on ACCOUNT_PANEL
        Activate Field HOMEPH_FIELD on ACCOUNT_PANEL
        Activate Field WORKPH_FIELD on ACCOUNT_PANEL
        Activate Field ACCOUNT_PASSWORD on ACCOUNT_PANEL
    End Response

This response activates a number of the panel fields that correspond to the ACCOUNT form record. Because only certain fields need to be activated for input, the default response that activates all panel fields corresponding to form record fields is inappropriate.

To cancel a DECforms request, you use the FORMS$CANCEL call,which invokes the CANCEL request. The CANCEL request causes the Form Manager to cancel currently active requests for the session identified by the session identification string you pass in the call. It differs from the FMS CANCL call in that it does not cancel any requests you call after you call the CANCEL request.

When you use it to cancel the SEND request, RECEIVE request, or TRANSCEIVE request, the CANCEL request cancels pending input and output. Therefore, form data items and the display may be in an unexpected state after you invoke the CANCEL request. When the Form Manager is finished processing the CANCEL request, you can repair form data by sending a new copy of the record being exchanged. A canceled TRANSCEIVE request or RECEIVE request may return a record to the program if the Form Manager has already collected data to return to the program when it cancels the request. The Form Manager does not validate the data before returning it to the program. The Form Manager restores the screen to a known state the next time it does screen management.

The format of the FORMS$CANCEL call follows:

FORMS$CANCEL session-id [,request-options]

PROCEDURE DIVISION.
0.
*
* Fatal error in database update. Cancel outstanding requests.
*
        CALL "forms$cancel" USING BY DESCRIPTOR SESSION_ID
                             GIVING FORMS_STATUS.

You cannot write a response for the CANCEL request.

DECforms provides a single call, FORMS$DISABLE, to close your form environment. The FORMS$DISABLE call invokes the DISABLE request, which causes the Form Manager to end the current session. To end a session, the Form Manager detaches the display device and form that are associated with the session identification string,and it performs other internal tasks.

You should call the DISABLE request only when you have finished exchanging data with a form. You need not disable a form before you use another form, perform database updates, or make calls to another product, such as the Graphical Kernel System (GKS). (See the GKS documentation for more information about that product.)

The format of the FORMS$DISABLE call follows (optional parameters are shown in brackets):

FORMS$DISABLE  session-id [receive-control-text,receive-control-text
               -count], [send-control-text, send-control-text-count],
               [timeout], [parent-request-id], [request-options]

PROCEDURE DIVISION.
0.
*
* Done using DECforms.  Disable form environment.
*
    CALL "Forms$disable"  USING BY DESCRIPTOR SESSION_ID_STRING
                             GIVING FORMS_STATUS.
   .
   .
   .

   .
   .
   .
Disable Response         
   Remove All            
End Response
   .
   .
   .

The FMS AFVA (Alter Field Video Attributes) call changes the video attributes of a field. The attributes change immediately and remain in effect until either you redisplay the form or modify them with another AFVA call. This call cancels input highlighting for a field.

In DECforms, you use the HIGHLIGHT WHEN clause to change the video attributes of a field. This clause allows you to apply highlight to a field based on a conditional expression. The attributes change immediately after the condition becomes true and remain in effect until the condition is no longer true.

   Field EMPLOYEE_NAME
     Next Line Same Column
     Active Highlight Bold                                        
     Highlight Reverse When Error = "TRUE"                        
     Exit Response                                                
        Call "CHECK_DATA_BASE" Using By Reference EMPLOYEE_NAME_1
                               Giving STATUS
        If STATUS <> 1
         Then
           Let Error = "TRUE"
           Invalid
         Else
           Position to Next item
        End If
     End Response
   End Field

You should remove all AFVA calls from your program. For each call you remove,add a HIGHLIGHT WHEN statement to the form. Be sure to position the HIGHLIGHTWHEN statement in the field declaration for the field you altered with a particular AFVA call.

Two FMS calls reset fields on your form to their default values. These calls are PUTD (Output Default to a Specified Field) and PUTDA (Output Default Values to All Fields). PUTD outputs the default value to the field you specify. If the field does not have a default value, it is filled with the fill character in the workspace and with spaces on the form. PUTDA causes the default values to be restored to all fields on the form. If any fields do not have default values, they are filled with the fill character in the workspace and with spaces on the form.

In DECforms, you reset form data items to their default value,instead of resetting the value of fields. Because form data items store the values displayed in fields, resetting them has the effect of resetting the field value. In other words, when you reset a form data item to its default value, the default value is displayed when the panel field is displayed.

   Field  ACCOUNT_NUMBER
      Line 10 Column 5
      Input Picture 999'-'99999'-'999
      Input Required

      Validation Response
        Call "CHECK_DIGIT_VALIDATION" Using By Reference ACCOUNT_NUMBER 
                                      Giving STATUS
        If STATUS <> 1 Then                                             
            Invalid
            Reset ACCOUNT_NUMBER
        Else
           Position To Next Item
        End If
      End Response
   End Field

The FMS CLEAR (Clear Screen) call erases the contents of all or part of the screen. You use it in FMS to erase all or part of the screen. For example, you could clear the screen directly before your application exits. You also use the CLEAR call to “break” parts of the screen. When you call another screen management tool, such as GKS, from an FMS application, the other tool modifies the screen independent of FMS. When control is returned to FMS, FMS operates as if the screen had not been modified; FMS does not redraw forms that were overwritten by the other screen management tool. To make FMS repair lines that were modified by another screen management tool, clear those lines. Then, you can use the RFRSH call to make FMS refresh the screen and repair the lines you have “broken” with the CLEAR call.

DECforms does not have a call that clears all or part of the screen. However, it does supply the REMOVE response step that clears parts of the screen and the REFRESH response step that redraws parts of the screen. Therefore, you can cause the Form Manager to erase parts of the screen and repair lines that have been written over by another screen management tool.

The difference between the REMOVE and REFRESH response steps and the FMSCLEAR call is that REMOVE and REFRESH operate on viewports. You specify the name of a viewport in the REMOVE or REFRESH response step to determine which viewport the Form Manager clears or redraws. You can specify the REMOVE ALL or REFRESH ALL to clear or redraw the display.

Remove FMS CLEAR calls from your program. Replace them with REMOVE or REFRESH response steps that are performed at times similar to when the CLEAR call was performed.

See Section 4.3.15, “Refreshing a Shared Screen” for information on refreshing a shared screen. See the VSI DECforms IFDL Reference Manual for more information on the REMOVE response step.

The PUTL (Output Line to Screen) call allows you to write a line of data to the terminal. You can use it to send messages to the operator. The message you send can appear on any line of the terminal. You can apply video attributes to the message using the ADLVA (Alter Data Line Video Attributes) call. The ADLVA call allows you to make a data line blink, be bolded, appear in reverse video, and so on.

The GETDL (Get Data Line from Terminal) call allows you to get a data line from the operator. You can display a prompt to let the operator know what input is required. Again, you can determine what video attributes that line has by calling ADLVA.

Form EMPLOYEE_FORM
  Form Data
     PROMPT_FIELD                      Character (10)
     DATA_LINE_FIELD                   Character (70)
  End Data

  Form Record PROMPT_RECORD                               
     PROMPT_FIELD                      Character (10)
  End Record  Form Record DATA_LINE_RECORD                
     DATA_LINE_FIELD                   Character (70)
  End Record
   .
   .
   .
  Viewport FOR_DATA_LINES                                 
     Lines 6 Through 6
     Column 1 Through 80
  End Viewport

  Panel DATA_LINE_PANEL
      Viewport FOR_DATA_LINES                             
      Display Underlined
        Field PROMPT_FIELD                                
          Line 1 Column 1
          No Data Input
        End Field
        Field DATA_LINE_FIELD                             
          Line 1 Column 11
        End Field
   End Panel
 End Layout
End Form

WORKING-STORAGE SECTION.
*01      PROMPT_RECORD                         GLOBAL.
         05  PROMPT_FIELD     PIX X(10).

 01      DATA_LINE_RECORD                      GLOBAL.
         05 DATA_LINE_FIELD   PIX X(70).

        CALL "forms$transceive" USING BY DESCRIPTOR SESSION_ID
                                                    "PROMPT_RECORD"
                                      BY REFERENCE  RECORD_COUNT
                                      BY DESCRIPTOR "DATA_LINE_RECORD"
                                      BY REFERENCE  RECORD_COUNT
                                      OMITTED
                                      OMITTED
                                      OMITTED
                                      OMITTED
                                      OMITTED
                                      OMITTED
                                      OMITTED
                                      BY DESCRIPTOR PROMPT_RECORD
                                      OMITTED
                                      BY DESCRIPTOR DATA_LINE_RECORD
                                GIVING FORMS_STATUS.
        CALL "SRVCHK" USING FORMS_STATUS.

This request call sends the data in the PROMPT_RECORD program record field to the form, and it receives the data in the DATA_LINE_FIELD form data item in the program.

FMS allows you to protect some fields from operator entry with supervisor-only mode. The operator cannot enter data in fields with the supervisor-only attribute unless you turn supervisor-only mode off from the program. You control supervisor-only mode with the SPOFF (Turn Supervisor-Only Mode Off)and SPON (Turn Supervisor-Only Mode On) calls.

     Field EMPLOYEE_SALARY
      Line 15 Column 20
      Protected When OPERATOR_NUMBER <> SUPERVISOR_NUMBER
     End Field

The PROTECTED WHEN clause makes this field display-only unless the OPERATOR_NUMBER form data item is equal to the SUPERVISOR_NUMBER form data item. While the condition is true, the operator can enter data into the field.

Remove SPON and SPOFF calls from your program. Add the PROTECTED WHEN clause to fields that need to be protected from operator entry at certain times during application processing.

The DPCOM (Define Comma as Decimal Point) FMS call defines the comma or redefines the period as the decimal point for signed numeric fields. The decimal point is returned to your program as part of the field value.

The DECIMAL POINT IS clause controls the decimal point character in DECforms. You specify this clause as an editing clause on an OUTPUT PICTURE field. The character not used as the decimal point may be used as an insertion literal. The character that is used as a decimal point is not stored with the value in form data. By default, the decimal point is a period.

  Field EMPLOYEE_SALARY
    Line 20 Column 40
    Output  Picture 999.99999
      Decimal Point Is Comma
    Input Picture XXX.XXXXX
  End Field

The DECIMAL POINT IS clause specifies that the decimal point for this field is a comma. The decimal point for other fields could be a period.

Remove the DPCOM call from your program. Add the DECIMAL POINT IS clause to fields in which you want the decimal point to be a comma. If you want a number of fields to have a comma as the decimal point, you can apply a field default to a group, panel, or layout. The APPLY FIELD DEFAULT clause specifies the default characteristics of fields that follow it in a group,panel, or layout declaration.

You define keys in FMS with the DFKBD (Define Keyboard) call. You define keys in DECforms with functions.

FMS and DECforms provide default definitions (called bindings in DECforms) for some keys. Also like FMS, DECforms provides defaults for what the Form Manager does when the operator presses a key. You can change the default effect of a key by defining a function response for the function bound to the key.

To move your FMS key definitions to DECforms, remove all DFKBD calls from your program. Define keys using the FUNCTION and FUNCTION RESPONSE statements in the form. Section 7.1, “Defining Keys”discusses defining keys and writing function responses for keys.

You use these calls, for example, when the operator enters an invalid value. With them you determine what state the terminal was in when the operator entered a field terminator. You can then put the form into a context that make sit easy for the operator to correct input and issue another GET-type call.

In DECforms, you can do little to modify the operator's context. For example, you cannot control cursor position or editing mode from the form. In DECforms, the operator is given this control.

Form EMPLOYEE_FORM
 Form Data
   SESSION      Character (16)           
   FORMNAME     Character (25) Varying   
   FUNCTIONAME  Character (25) Varying
   CURRENTITEM  Character (25) Varying
   .
   .
   .
 End Data

See the VSI DECforms Programmer's Reference Manual for more information about the built-inform data items.

FMS and DECforms use different algorithms to display forms and panels. They have different methods of determining the width of what they display, and they have different methods of dealing with overlaid images on the display. Also, while you display forms with program calls in FMS,you use response steps in the form to display panels in DECforms. The sections that follow discuss how the Form Manager determines the terminal width setting it should use and how it overlays panels. It also explains how to get the effect of the three FMS calls that display forms.

Form EMPLOYEE_FORM
   .
   .
   .
  Send Response EMPLOYEE_CHANGE_RECORD    
     Display CHANGE_NAME
  End Response

  Viewport WHOLE_SCREEN
    Lines 1 Through 24                    
    Columns 1 Through 80
  End Viewport

     Panel CHANGE_NAME
       Viewport WHOLE_SCREEN              
   .
   .
   .
     End Panel

In FMS, you use the NDISP (Mark Form in Current Workspace as Not Displayed)call to mark a form as undisplayed. After you issue the call, the form is not redisplayed on a refresh operation and subsequent GET-type calls to the form are invalid.

DECforms does not have a concept like NDISP because all panels in a form are available for display at all times during application execution. Thus, displaying a DECforms panel is an efficient operation because it does not involve memory allocation,and you can display any number of panels in sequence without damaging performance.

Although you need not mark panels as undisplayed in DECforms,you may need to remove a panel from the display. To do this, use the REMOVE response step. The REMOVE response step causes the Form Manager to clear the viewport you specify, which removes the panel from the display.

Form PERSONNEL_FORM
   .
   .
   .
  Panel PERSONAL_INFO
   .
   .
   .
     Field MARITAL_STATUS
      Line 2 Column 6
        Exit Response
          If MARITAL_STATUS = "S" Then                
            Activate Panel SINGLE_PANEL
            Position Immediate To Panel SINGLE_PANEL
          Else
            Activate Panel MARRIED_PANEL
            Position Immediate To Panel MARRIED_PANEL
          End If
       End Response
      End Field
 End Panel

Panel SINGLE_PANEL
 Viewport SMALL_VIEWPORT                             

 Exit Response
   Remove SMALL_VIEWPORT                             
 End Response
   .
   .
   .
  End Panel

  Panel MARRIED_PANEL                                
   Viewport SMALL_VIEWPORT

   Exit Response
     Remove SMALL_VIEWPORT
   End Response
   .
   .
   .
  End Panel
End Form

FMS allows you to modify the mode (numeric or application) of the terminal keypad using the SPADA (Set Keypad to Application Mode) call.

Form PERSONNEL_FORM
   .
   .
   .
     Panel EMPLOYEE_PERSONAL_INFO

       Display  %Keypad_application   
       Field EMPLOYEE_NAME            
         Line 3 Column 10
       End Field

       Field EMPLOYEE_PHONE_NUMBER
         Line 5 Same Column
         Display %Keypad_numeric      
       End Field
   .
   .
   .
End Form 

The RETFL (Return Form Line) and PRINT_SCREEN (Write Screen to Print File)calls print FMS forms. Using either call you can write form lines to a file for subsequent printing. You can also use RETFL to return the form line you specify to your program. You can then print that line.

To print a DECforms panel, you use the PRINT response step. This response step causes the Form Manager to write a panel to a file. You can then print the file. By default, the Form Manager writes the current display to a file. To specify that the Form Manager print a specific panel, you name the panel in the PRINT response step.

Each PRINT response step starts a new page in the printed output. You can close the current input file and open anew version of it by specifying PRINT IMMEDIATE. Otherwise, the Form Manager writes the output from the PRINT response step to the same file.

The Form Manager writes the output from the PRINT response step to your current default node, device, and directory. The Manager names the print file the same as your form file with the .TXT file type. You can specify a different file specification by defining the FORMS$PRINT_FILE logical name. You can specify a node, device, directory, file name, and file type in the logical name definition.

The file created by the Form Manager is an ASCII file. You can print it on a line printer.

The PFT (Process Field Terminator) call processes a field terminator that you pass to the Form Driver or, if you omit the terminator parameter, the last field terminator the operator entered. If necessary, the Form Driver changes the current field in the workspace; it returns the name of the new current field in one of the call parameters.

You should remove all PFT calls from your program. Because your DECforms form traps the functions that correspond to FMS terminators by default, you need not modify your form for the functions to be trapped. DECforms binds the functions to default keys, so you may want to change the key bindings for the functions. For example, if your operator uses the F20 key to move to a new field in your FMS application,you should bindF20 to the NEXT ITEM function. Section 7.1, “Defining Keys” explains how you do this.

To refresh the screen from your program in FMS, you call the RFRSH (Refresh Screen) call. This call redisplays all forms currently marked as being displayed. If more than one form is on the screen, the Form Driver redisplays the forms in the order in which their workspaces were attached. The Form Driver displays the current workspace's form last (on top of the other forms). In addition,the Form Driver may reset the keypad mode if your program previously called the SPADA call.

To refresh the screen in DECforms, you use the REFRESH response step. This response step causes the Form Manager to repaint the contents of all viewports in the current layout, a specific viewport, or the default viewport. To emulate the RFRSH call, you should specify REFRESH ALL because it repaints all viewports. This response step causes the Form Manager to refresh the entire screen if your viewports fill the entire screen.

The REFRESH response step behaves differently from the RFRSH call in that it does not remove inactive panels. In FMS, if a form's workspace is inactive and you call RFRSH, that form is not repainted during the refresh operation. A DECforms panel that does not correspond to any items on the activation list is roughly equivalent to a form that corresponds to an inactive workspace. The Form Manager removes an inactive panel from the display when the operator leaves the panel, unless you specify RETAIN in the panel's post display clause. If you specify RETAIN, the panel remains on the display after the operator leaves it. You can remove inactive panels with the REMOVE response step, but you cannot erase them with the REFRESH response step.

Another difference between the REFRESH response step and the RFRSH call is that the response step does not refresh the keypad mode or the terminal LEDs. The keypad mode in DECforms is controlled by the %KEYPAD_NUMERIC, %KEYPAD_APPLICATION, and %KEYPAD_UNCHANGED implement or attributes. Because most terminals do not have VT00 LEDs, you cannot affect the LEDs from the form or program.

To move your program to DECforms, remove all RFRSH calls. Use the REFRESH response step to refresh the screen and the elementary attributes to control the keypad mode.

FMS provides the USER_REFRESH (Set up User Refresh Routine) call that allows a routine you write to refresh parts of the screen. The Form Driver calls your refresh routine any time it needs to refresh the screen. This call,then, gives you control over what the Form Driver displays when it refreshes the screen. If you did not have this control over the refresh operation, the Form Driver would clear any data you display independent of FMS. This effect occurs because FMS assumes that it “owns”the entire screen. It clears and repaints the entire screen during each refresh operation.

  Layout SMALL_LAYOUT
    Device
      Terminal Type %VT200
    End Device
    Units Characters
    Size 17 Lines By 80 Columns                        

    Viewport TOP_PART                                  
      Lines 1 Through 15 Columns 1 Through 80
    End Viewport

    Viewport MESSAGE_LINE
      Lines 16 Through 17 Columns 1 Through 80
    End Viewport

    Panel NAME_PANEL                                   
      Viewport TOP_PART
   .
   .
   .
    End Panel

    Panel MESSAGE_PANEL
      Viewport MESSAGE_LINE

      Field MESSAGE_FIELD
          Line 1 Column 1
           No Data Input
      End Field
    End Panel
   .
   .
   .
End Form

You may want to refresh the entire screen when the operator requests a screen refresh. The operator usually requests that the screen be refreshed when it has been corrupted, for example, by operating system messages. If these messages could corrupt the part of the screen controlled by DECforms and the part not under DECforms control, you should refresh the entire screen.

Form EMPLOYEE_FORM
   .
   .
   .
    Viewport MESSAGE_LINE
      Lines 16 Through 17 Columns 1 Through 80
    End Viewport

    Function USER_REFRESH Is %Control_R End Function     

    Function Response USER_REFRESH
       Call 'USER_REFRESH_ROUTINE'                       
       Refresh All                                       
    End Response
   .
   .
   .
End Form

To get data from the form workspace in FMS, you call either the RET (Return Value for Specified Field) or RETAL (Return Values for All Fields) call. The RET call returns the value of the field you specify from the current workspace. The RETAL call returns the values of all non-scrolled fields from the current workspace. The fields are returned in the order specified in the form description.

Although DECforms does not have the concept of a form workspace,it does maintain values in form data items. You can get data from form data items without displaying them or accepting operator input. To do so,you call the RECEIVE request and write a response for the request that specifies returning values to the program.

*
* The following call requests a record from form data.
* This call appears in the program.
*
    CALL "forms$receive"      USING BY DESCRIPTOR  SESSION_ID
                                                   "EMPLOYEE_UPDATE"
                                    BY REFERENCE    RECORD_COUNT
                                    OMITTED
                                    OMITTED
                                    OMITTED
                                    OMITTED
                                    OMITTED
                                    OMITTED
                                    OMITTED
                                    BY DESCRIPTOR  EMPLOYEE_UPDATE
                              GIVING FORMS_STATUS.

/*                                                        /*
/* The following response returns data to the program.    /*
/* This response appears in the form inside the LAYOUT    /*
/* statement.                                             /*

    Receive Response EMPLOYEE_UDPATE
       Return
    End Response
   .
   .
   .

The RETURN response step causes the Form Manager to collect the data from form data items that correspond to the EMPLOYEE_UPDATE form record and return them to the program.

The call and response shown in Example 4.21, “FORMS$RECEIVE Call to Return Data from Form Data Items” and Example 4.22, “RECEIVE Response That Returns Data from Form DataItems” do not exactly match either the FMS RET or RETAL call. The group of data returned to your program in this case is controlled by the fields in the form record, not the fields on the display. However, by declaring a form record and program record that contain the appropriate fields, you can cause the Form Manager to return the same data to your DECforms application program as the Form Driver did to your FMS application program.

You can get data from a form data array that corresponds to a scrolled region with the RETURN response step. To do so, you include the array in the form record and program record declarations. Section 7.5, “Creating Scrolled Regions” describes using scrolled regions.

FMS allows you to declare constant data that is associated with a form. You can reference the data by index or, if you supplied a name when you declared it, by name. This constant data is called Named Data. You get values from Named Data in your program with the RETDI (Return Named Data by Index) and RETDN (Return Named Data by Name) calls.

In DECforms you can create data items that serve the same function as named data by declaring form data items. Form data items can contain pre-defined constant values, which need not be displayed on the screen. Unlike Named Data, form data items must each have a unique name.

Form PERSONNEL_FORM

  Form Data
     VERSION_INFO       Character (10)     Value "VERSION 2"
     CREATION_DATE      Character (12)     Value "JANUARY 29"
   .
   .
   .
  End Data

Because most form processing is done in the form in DECforms,you may be able to move code that uses Named Data from your program to your form. However, if you need the information in your program, you must declare a form record that contains fields that correspond to the form data items. To get the data in your program, call the RECEIVE request.

Form PERSONNEL_FORM
   .
   .
   .
  Form Record CONSTANT_DATA_RECORD                                        
     VERSION_INFO       Character (10)
     CREATION_DATE      Character (12)
   End Record

   Layout
   .
   .
   .
   Receive Response CONSTANT_DATA_RECORD                                  
     Return Immediate                                                     
   End Response

To get the constant data in the program, use the FORMS$RECEIVE call and pass the CONSTANT_DATA_RECORD in the receive-record-identifier parameter.

An FMS workspace maintains form context from one call to another. You can use more than one workspace in an application. To switch between workspaces, you attach the workspaces and then call the SWKSP (Set Current Workspace) call. This call makes the attached workspace you specify the current workspace. The current workspace is eligible for input.

Form PERSONNEL_FORM
   .
   .
   .
    Receive Response EMPLOYEE_RECORD               
      Activate Panel  EMPLOYEE_PERSONAL_INFO       
      Position To Panel EMPLOYEE_PERSONAL_INFO     
    End Response

In FMS, you signal the operator from your program with the BELL (Ring Terminal Bell) and SIGOP (Signal Operator)calls. You can determine whether a visual or audible signal is used for the SIGOP call with the SSIGQ (Set Signal to Quiet Mode) call.

SIGNAL %BELL is the default.

Form EMPLOYEE_FORM

  Function SELECT Is %Kp_3                                       
   .
   .
   .
   Panel ADD_EMPLOYEE

Field  CHOICE_CHECK
  Line 2 Column 5
  No Data Input
  Active Highlight Font Style Bold
  Function Response SELECT                                       
   If CHECKING_BALANCE = 0 Then
      Signal %Bell
      Message "You can't write a check; you have a zero balance."
      Invalid
   Else
      Activate Panel CHECK_PANEL
   .
   .
   .
    End If
   End Response
End Field

The SIGNAL %REVERSE response step is inefficient on a VT241 terminal. Also, reversing the screen is not implemented on most terminal emulators, such as those for workstations. When your display device is a VT241 terminal or terminal emulator, use SIGNAL %BELL.

The ILTRM (Return Illegal Terminators) call allows your program to receive terminators that are normally illegal in the current context. For example,a Next Field terminator is illegal when the current field is the last field on the form. Using ILTRM, you cause this terminator to be translated into a special terminator and sent to either the form's function key UAR or the program.

DECforms traps field terminators in the form with functions. You determine what action is taken when the operator presses a key using a function response. You can declare a response to a special function called the UNDEFINED FUNCTION to determine what occurs when the operator presses an undefined function key.

Section 7.1, “Defining Keys” gives more information on functions and function responses. See the VSI DECforms IFDL Reference Manual for more information on the UNDEFINED FUNCTION.

To synchronize the program with the pace of the operator, you can call the FMS WAIT (Wait for Operator) call. This call moves the cursor to the bottom right-hand of the screen and waits for the operator to enter a field terminator. Once the operator enters a field terminator, the wait is terminated and processing proceeds.

In DECforms, you use the ACTIVATE WAIT response step to create a wait activation item. When the wait activation item becomes the current activation item, the Form Manager moves the cursor to the bottom right corner of the screen and waits for the operator to enter a function. Once the operator enters a function, the Form Manager terminates the wait and processing proceeds.

You can position to the wait activation item with the POSITION TO WAIT response step.

Remove FMS WAIT calls from your program. Use the ACTIVATE WAIT response step to synchronize application control with operator input.

The FMS Converter creates a panel field for each of the fields in the FMS form library for the sample application. Because DECforms requires that each panel field correspond to a form data item, the FMS Converter creates a form data item to match each panel field it creates. The FMS Converter gives the form data item the same name as the panel field.

The FMS form library in the sample application contains several fields that share the name of other fields. The duplicate names in the FMS form library cause the FMS Converter to create form data items that have the same name. DECforms does not allow duplicately named form data items, so you must delete or rename duplicate form data items. Notice that the FMS Converter creates comments that highlight data items that are duplicates.

Also, some form data items that the Converter declares are not needed in the DECforms application, so you can remove them.

Form Data       /* Form data for panel ACCOUNT_DATA_PANEL */
    ACCTNO_FIELD                      Integer (5)
    OPEN_DATE                         Character (7)
    LAST_FIELD                        Character (20)
    FIRST_FIELD                       Character (15)
    MIDDLE_FIELD                      Character (15)
    STREET_FIELD                      Character (30)
    CITY_FIELD                        Character (20)
    STATE_FIELD                       Character (2)
    ZIP_FIELD                         Integer (5)
    HOMEPH_FIELD                      Integer (10)
    WORKPH_FIELD                      Integer (10)
    SECRET_FIELD                      Character (12)
    Supervisor_Only                   Integer(1)  Value 1
End Data

Form Data       /* Form data for panel CHECK_PANEL */
    NAME_FIELD                        Character (39)
    NUMBER_FIELD                      Integer (4)
    CSZ_FIELD                         Character (30)
    DATE_FIELD                        Date     CURRENT
    PAYTO_FIELD                       Character (35)
    AMTPAY_FIELD                      Decimal (6,2)
    MEMO_FIELD                        Character (35)
    BALANCE_FIELD                     Decimal (6,2)
End Data

Form Data       /* Form data for panel DEPOSIT_PANEL */
    CURBAL_FIELD                      Decimal (6,2)
    DEPOSIT_FIELD                     Decimal (6,2)
    NEWBAL_FIELD                      Decimal (6,2)

/* The following data items are a simulation of the FMS named_data for */
/* form DEPOSIT */

    DONE_ND                           Character (48)  Value 'Deposit made.
                                                             Press RETURN
                                                             or ENTER to
                                                             continue.'
End Data

Form Data       /* Form data for panel MENU_PANEL */
    OPTION_FIELD                      Integer (1)  Value 2
End Data

Form Data       /* Form data for panel REGISTER_PANEL */
  Group REGISTER_PANEL_GROUP_1
     Occurs  6
    NUMBER_FIELD                      Character (4)
    DATE_FIELD                        Character (7)
    PAYMEM_FIELD                      Character (35)
    DEPOSIT_FIELD                     Character (6)
    AMTPAY_FIELD                      Character (6)
    BALANCE_FIELD                     Character (6)
  End Group
    SUMMARY_FIELD_1                   Decimal (6,2)
    SUMMARY_FIELD_2                   Decimal (6,2)
    SUMMARY_FIELD_3                   Decimal (6,2)
End Data

Layout FMS_Cnv
   .
   .
   .

The FMS Converter creates panel fields for each of the fields in the FMS form library. These panel fields are bound by name to the form data items that the FMS Converter creates. Each panel field displays data and accepts input for the form data item that shares its name. Because you deleted or renamed some of the form data items the Converter created, you must remove or rename the panel fields that corresponded to those data items.

The FMS Converter creates form data items with names that end in “_ND”to replace FMS Named Data. Because Named Data is not displayed, the Converter assumes that you do not need to display the contents of these data items. Therefore, the Converter does not create panel fields to correspond to these data items. You need not remove or rename panel fields to adjust for removing the FIRST_ND, LAST_ND, and NSCROLL_ND data items.

Notice that although you removed form data items from the FORM DATA statement for CHECK_PANEL, you need not rename any of the fields on CHECK_PANEL. Each of the form data items that you removed from the form data item declaration for CHECK_PANEL was a duplicate form data item. A form data item by the same name exists elsewhere in the form data declaration and stores the appropriate value to be displayed in fields on CHECK_PANEL.

Also, you need not rename the DATE_FIELD panel field on DEPOSIT_PANEL, despite the fact that you deleted the form data item named DATE_FIELD from the form data items for DEPOSIT_PANEL. A form data item named DATE_FIELD appears in the form data declaration and the Form Manager displays its value in the DATE_FIELD panel field.

After you modify form data items and rename panel fields, you can add record declarations to your IFDL source file and your program. The records you declare allow your program to exchange data with the form. To determine what records are needed, you must determine what data needs to be exchanged between the form and the program and when the data needs to be exchanged. You must also know the data type of the data being passed.

To determine what records are needed for the sample application, step through the program. Determine when the sample program passes data and what data it passes by examining the FMS PUT-type and GET-type calls in the program. You may be able to use existing records in the program to pass data in the converted application.

The data type of all the data items the FMS sample program passes to FMS forms is the CHARACTER data type. Therefore, you can create all your form record fields in DECforms with the CHARACTER data type. Later, as you modify the program, you may want to change some of the data types to match how you use the data and avoid converting numeric data to and from character strings. However, it is best to begin transferring character string data.

The help provided in the FMS sample application is consistent throughout the application. When the cursor is on a field and the operator presses the HELP key, FMS displays a message that explains how to give input to that field. If the operator presses the HELP key again, FMS displays a help form that gives information about the form on which the FMS field appears. If the operator presses the HELP key three times, FMS displays a help form that explains the keys defined in the sample application.

The main program of the sample program, SAMP, declares much of the data used in the application. It also attaches and detaches FMS by attaching and detaching a terminal and workspaces, opening and closing the form library, and setting the keypad mode and signal mode. The sections that follow explain how to convert the SAMP program.

IDENTIFICATION DIVISION.PROGRAM-ID.  SAMP.
   .
   .
   .
WORKING-STORAGE SECTION.
01      SAMP_FORM             PIC X(21)      VALUE "FORMS$EXAMPLES:SAMP.FORM".
01      TOTAL_DEPOSIT         PIC 9(6)          GLOBAL.
01      TOTAL_PAYMENTS        PIC 9(6)          GLOBAL.
01      MAX_DEPOSIT           PIC 9(6)          GLOBAL VALUE 999999.
01      MAX_PAYMENT           PIC 9(6)          GLOBAL VALUE 999999.
01      FORMS_STATUS          PIC S9(9) COMP    GLOBAL.
01      SESSION_ID            PIC X(16)         GLOBAL.
01      RECORD_COUNT          PIC 9(1)          GLOBAL  VALUE 1.
01      DISPLAY_DEVICE        PIC X(10)         VALUE "SYS$INPUT".
*
*     Record to pass current balance
*
01      CURRENT_BALANCE       PIC 9(6)          GLOBAL.
   05         CURBAL_FIELD       PIC 9(6).
*
*    Record to get check and deposit data
*
01     COLLECT_DATA                             GLOBAL.
       05       TRANSACTION_COUNT      PIC 9(8) COMP.
       05       TRANSACTION_DATA OCCURS 50.
                10 NUMBER_FIELD        PIC 9(4).
                10 DATE_FIELD          PIC X(7).
                10 PAYMEM_FIELD        PIC X(35).
                10 AMTPAY_FIELD        PIC 9(6).
                10 DEPOSIT_FIELD       PIC 9(6).
                10 BALANCE_FIELD       PIC 9(9).
*
*    Account Record format of first record in SAMP.DAT
*
01      ACCOUNT                                 GLOBAL.
        05      ACCT_NUMBER      PIC X(5).
        05                       PIC X(7).
        05      ACCT_NAME.
                10       LAST_NAME       PIC X(20).
                10       FIRST_NAME      PIC X(15).
                10       MIDDLE_NAME     PIC X(15).
        05      ACCT_STREET              PIC X(30).
        05      CITY-STATE-ZIP.
                10      CITY             PIC X(20).
                10      STATE            PIC X(2).
                10      ZIP              PIC X(5).
        05      ACCT_HOME_PHONE          PIC X(10).
        05                               PIC X(10).
        05      ACCT_PASSWORD            PIC X(12).
*
*     Register data format of 2nd thru n records in SAMP.DAT
*
01      REGISTER                                GLOBAL.
        05      LAST_REGISTER_NUM               PIC 9(4).
        05      REGISTER_ITEM            OCCURS 50 TIMES.
                10      REG_ITEM_NUMBER         PIC 9(4).
                10      REG_ITEM_DATE           PIC X(7).
                10      REG_ITEM_MEMO_PAY_TO    PIC X(35).
                10      REG_ITEM_DEPOSIT_AMT    PIC 9(6).
                10      REG_ITEM_PAY_AMT        PIC 9(6).
                10      REG_ITEM_BALANCE        PIC 9(6).
01      REGISTER_MAX                     PIC 9999       GLOBAL VALUE 50.
01      LAST_CHECK_NUM                   PIC 9(4)       GLOBAL.
01      ACCT_BALANCE                     PIC 9(6)       GLOBAL.
*
*       Forms SYMBOLS*COPY "SYS$LIBRARY:FORMS$DEFINITIONS_COBOL".
   .
   .
   .

IDENTIFICATION DIVISION.
PROGRAM-ID.   SAMP.
   .
   .
   .
PROCEDURE DIVISION.
0.
*+
* Initialize DECforms
*   Choose form for this session
*   Attach terminal
*   Open channel
*   Put up welcome form and wait for response
*
     CALL "forms$enable" USING BY VALUE      FORMS$AR_FORM_TABLE
                               BY DESCRIPTOR DISPLAY_DEVICE
                                             SESSION_ID
                                             SAMP_FORM
                         GIVING FORMS_STATUS.
*+
* Initialize account information
*-
     CALL "INACCT".
*+
* Process all menu requests
*-
     CALL "MENU".
*+
* Clean up and leave:
*   Detach session
*   Unload form
*   Detach terminal
*   Close channel
*
     CALL "forms$disable"  USING SESSION_ID
                         GIVING FORMS_STATUS.
     EXIT PROGRAM.

The INACCT subprogram in the sample FMS program reads data from a data file into the ACCOUNT record and the REGISTER record. This subprogram also stores the appropriate check number and account balance in the appropriate variables. The subprogram contains some error handling, a call to another subprogram named FMTCHK, and it closes the data file. Each of these tasks must be performed in the converted application,so you need not modify the existing statements in this subprogram.

Because the INACCT subprogram's purpose is to initialize storage of the account data, you should call the SEND request from that subprogram to send the account data to the form. You should also send the current balance to the form. The form needs to keep a copy of the account data and current balance in form data items,so it makes sense to initialize those form data items at the same time you initialize the ACCOUNT and CURRENT_BALANCE records in the program.

WORKING-STORAGE SECTION.
01      EOF-FLAG                PIC S9(9)       COMP.

PROCEDURE DIVISION.
0.
*+
* Open file, get account data.  The first record in the file is the
* account data. The 2nd thru n records are the check register data.
* The last record has the current balance data.
*-
        OPEN INPUT SAMP-FILE.
        READ SAMP-FILE INTO ACCOUNT\
                AT END  DISPLAY "Error on SAMP.DAT"
                        STOP RUN.
*+
* Send account data to the form
*+
        CALL "forms$send" USING BY DESCRIPTOR SESSION_ID
                                              "ACCOUNT"
                                BY REFERENCE  RECORD_COUNT
                                OMITTED
                                OMITTED
                                OMITTED
                                OMITTED
                                OMITTED
                                OMITTED
                                OMITTED
                                BY DESCRIPTOR ACCOUNT
                          GIVING FORMS_STATUS.
        CALL "SRVCHK" USING FORMS_STATUS.
*+
*  Read the remaining records into the check register, counting them.
   .
   .
   .

The FORMS$SEND call that sends the ACCOUNT record causes the Form Manager to initialize form data items with the account owner's name, address, and telephone number. The Form Manager also initializes information about the account, such as the account number.

         END-EVALUATE.
*+
* Send current balance to the form.
*-
        CALL "forms$send" USING BY DESCRIPTOR SESSION_ID
                                             "CURRENT_BALANCE"
                               BY REFERENCE  RECORD_COUNT
                               OMITTED
                               OMITTED
                               OMITTED
                               OMITTED
                               OMITTED
                               OMITTED
                               OMITTED
                               BY DESCRIPTOR CURRENT_BALANCE
                         GIVING FORMS_STATUS.
        CALL "SRVCHK" USING FORMS_STATUS.
*+
* Set up the check workspace once so we don't have to do it every time.
   .
   .
   .

   .
   .
   .
  Reset REGISTER_PANEL_GROUP_1
End Response

Send Response CURRENT_BALANCE
  Let SUMMARY_FIELD_1 = CURBAL_FIELD
End Response

When it executes this response, the Form Manager stores the current (beginning) account balance in the SUMMARY_FIELD_1 form data item. You must initialize the SUMMARY_FIELD_1 form data item at the beginning of application execution because the SUMMARY_FIELD_1 panel field must display the beginning account balance when the operator asks to see a summary of the transactions made on the account.

The procedural statements from the ONECHK subprogram calculate a new check number and register number. The statements send the new check number to the workspace and get input to each field on the FMS Check form. The operator can quit by pressing the KP_PERIOD key. If the operator does not quit, the IF statement compares the number of checks that have already been written to the maximum number of checks for which the check register can store information. If the check register is full, the subprogram issues a message and stops getting input to the Check form. Otherwise, the subprogram updates the check register with values returned from the workspace, sends a new current balance to the form, and increments the check number. The subprogram also increments the variable that determines whether the register has more room to store information about transactions.

PROGRAM-ID.     WRITCH.
*+
*       If input is terminated by kpd period, return with no action
*       Else deduct from balance and enter into register.
*       Note that a UAR in the form guarantees that the amount of
*       the check is always less than or equal to the balance.
*       Note that the form function key UAR allows only kpd period
*       as terminator (other than FDV$K_FT_NTR).
*-
*
DATA DIVISION.

WORKING-STORAGE SECTION.
01    REG_FULL_MSG.
      05  MESSAGEPANEL  PIC X(35)  VALUE "Register full, can't enter
                                          check.".
01    TMP                  PIC X(207) VALUE SPACE.
01    TMP_REG_ITEM_PAY_AMT    PIC X(6).
01    NUM_REG_ITEM_PAY_AMT    PIC 9(6)       COMP.
01    NEW_CHECK_NUMBER        PIC 9(4) VALUE ZERO.
01    END_REGISTER_NUM        PIC 9(4).
01    COUNTER                 PIC 9(2) VALUE ZERO.

PROCEDURE DIVISION.
0.
        CALL "forms$receive" USING BY DESCRIPTOR SESSION_ID
                                                   "COLLECT_DATA"
                                     BY REFERENCE  RECORD_COUNT
                                     OMITTED
                                     OMITTED
                                     OMITTED
                                     OMITTED
                                     OMITTED
                                     OMITTED
                                     OMITTED
                                     BY DESCRIPTOR COLLECT_DATA
                               GIVING FORMS_STATUS.
        CALL "SRVCHK" USING FORMS_STATUS.

        IF TRANSACTION_COUNT = 0 THEN
               GO TO FINI.
        ADD TRANSACTION_COUNT LAST_REGISTER_NUM GIVING END_REGISTER_NUM.
*+
* If the check wouldn't fit in the register, don't process, just
* give error message, wait for acknowledgement, and return
*-

         IF END_REGISTER_NUM  NOT LESS THAN REGISTER_MAX THEN
             CALL "forms$send" USING    BY DESCRIPTOR   SESSION_ID
                                                        "REG_FULL_MSG"
                                        BY REFERENCE    RECORD_COUNT
                                        OMITTED
                                        OMITTED
                                        OMITTED
                                        OMITTED
                                        OMITTED
                                        OMITTED
                                        OMITTED
                                        BY DESCRIPTOR   REG_FULL_MSG
                                  GIVING FORMS_STATUS
                CALL "SRVCHK" USING FORMS_STATUS
                GO TO FINI
         END-IF.
*+
* Update values in register.
*+
        PERFORM
          ADD 1 TO LAST_REGISTER_NUM.
          VARYING LAST_REGISTER_NUM FROM LAST_REGISTER_NUM BY 1
          UNTIL LAST_REGISTER_NUM IS GREATER THAN END_REGISTER_NUM
          ADD 1 TO COUNTER
           MOVE NUMBER_FIELD(COUNTER) TO REG-ITEM-NUMBER(LAST_REGISTER_NUM)
           MOVE DATE_FIELD(COUNTER) TO REG_ITEM_DATE(LAST_REGISTER_NUM)
           MOVE PAYMEM_FIELD(COUNTER) TO REG_ITEM_MEMO_PAY_TO
                                         (LAST_REGISTER_NUM)
           MOVE AMTPAY_FIELD(COUNTER) TO REG_ITEM_PAY_AMT
                                         (LAST_REGISTER_NUM)
           MOVE BALANCE_FIELD(COUNTER) TO REG_ITEM_BALANCE
                                          (LAST_REGISTER_NUM)
        END-PERFORM.
*+
* Update register counter
*-
        MOVE END_REGISTER_NUM TO LAST_REGISTER_NUM.
FINI.
        EXIT PROGRAM.
END PROGRAM WRITCH.

This subprogram calls the RECEIVE request to get check data. The check data is returned in the COLLECT_DATA record. The subprogram determines whether any checks were written. If not, it exits. If checks were written, the subprogram determines if they can be entered in the check register. If the register is full, the subprogram exits and sends a message to the operator. Otherwise, it enters the checks in the check register.

The ENDCHK subprogram in the FMS application displays a form called FORM_CHKDON. This form allows the operator to press one of three keys to indicate what is to be done next. The operator can choose to write another check, print the check just written,or stop writing checks and return to the menu. If the operator chooses to print the current check, the FMS program calls the PRICHK subprogram. This subprogram writes each of the lines in the check form to a field for subsequent printing.

Remove both of these subprograms. The tasks they perform are now performed in the form using responses.

During check processing, the form calls three escape routines. The first one subtracts the amount entered on checks from the current balance. The second one adds the amount entered on checks to the running check total. The running check total is the total of all checks written during this session. Finally,the last one increments a number—either the check number or the transaction counter.

END PROGRAM FMTCHK.
END PROGRAM SAMP.
IDENTIFICATION DIVISION.
PROGRAM-ID.     DIFFERENCE.
**************************************************************************
*   General escape routine to subtract one value from another.           *
**************************************************************************
DATA DIVISION.
WORKING-STORAGE SECTION.
LINKAGE SECTION.
01         NUMBER_1           PIC 9(9)  COMP.
01         NUMBER_2           PIC 9(9)  COMP.

PROCEDURE DIVISION USING NUMBER_1 NUMBER_2.
0.
*+
* Perform subtraction.
*+
        SUBTRACT NUMBER_2 FROM NUMBER_1.
*
        EXIT PROGRAM.
END PROGRAM DIFFERENCE.

IDENTIFICATION DIVISION.
PROGRAM-ID.     CALCULATE.
**************************************************************************
*   General purpose escape routine to add two values.                    *
**************************************************************************
DATA DIVISION.
WORKING-STORAGE SECTION.

LINKAGE SECTION.
01         NUMBER_1             PIC 9(9) COMP.
01         NUMBER_2             PIC 9(9) COMP.

PROCEDURE DIVISION USING NUMBER_1 NUMBER_2.
0.
*+
* Perform addition.
*+
        ADD NUMBER_2 TO NUMBER_1.
*
        EXIT PROGRAM.
END PROGRAM CALCULATE.

IDENTIFICATION DIVISION.
PROGRAM-ID.     INCREMENT.
**************************************************************************
*   General escape routine to increment a value.                         *
**************************************************************************
DATA DIVISION.
WORKING-STORAGE SECTION.

LINKAGE SECTION.
01         COUNT_KEEPER     PIC 9(9)    COMP.
PROCEDURE DIVISION USING COUNT_KEEPER.
0.
*+
* Add one.
*+

        ADD 1 to COUNT_KEEPER.
*
        EXIT PROGRAM.
END PROGRAM INCREMENT.

Add the escape routines to the COBOL source file following the END PROGRAM statement for the SAMP program.

The DIFFERENCE escape routine subtracts NUMBER_2 from NUMBER_1, and stores the result in NUMBER_1. The Form Manager passes both parameters to the PROCEDURE DIVISION header and the escape routine returns both parameters to the form. The data type of the parameters to the CALL response step must match the data type of the PROCEDURE DIVISION parameters.

The CALCULATE escape routine adds NUMBER_2 to NUMBER_1. The result is stored in NUMBER_1.

The INCREMENT escape routine adds 1 to COUNT_KEEPER and stores the result in COUNT_KEEPER.

The MAKDEP subprogram in the FMS sample application allows the operator to make deposits into the account. The subprogram initially displays the current balance and prompts the operator to enter a deposit amount. The operator must also enter a deposit memo. Once the deposit is complete, the program verifies that it can be entered in the register, enters the deposit into the register,and displays an updated balance to the operator.

IDENTIFICATION DIVISION.
PROGRAM-ID.     MAKDEP.
*+
*       Make a deposit, enter into check register
*       Cancel on keypad period.
*       Note that the form function key UAR allows only kpd period.
*+
DATA DIVISION.
WORKING-STORAGE SECTION.
01      REG_FULL_MSG.
        05   MESSAGE_PANEL  PIC X(80)  VALUE "Register full, can't enter
                                              deposit.".
PROCEDURE DIVISION.
0.
*+
* Get deposit amount and memo from operator.
* Abort on kpd period.
*-

        CALL "forms$receive" USING BY DESCRIPTOR SESSION_ID
                                                   "COLLECT_DATA"
                                     BY REFERENCE  RECORD_COUNT
                                     OMITTED
                                     OMITTED
                                     OMITTED
                                     OMITTED
                                     OMITTED
                                     OMITTED
                                     OMITTED
                                     BY DESCRIPTOR COLLECT_DATA
                               GIVING FORMS_STATUS.
        CALL "SRVCHK" USING FORMS_STATUS.

        IF TRANSACTION_COUNT = 0 THEN
                GO TO FINI.
*+
* Have deposit information now.
* If no room in check register must abort.
*-
        IF LAST_REGISTER_NUM NOT LESS THAN REGISTER_MAX THEN
             CALL "forms$send" USING    BY DESCRIPTOR   SESSION_ID
                                                        "REG_FULL_MSG"
                                        BY REFERENCE    RECORD_COUNT
                                        OMITTED
                                        OMITTED
                                        OMITTED
                                        OMITTED
                                        OMITTED
                                        OMITTED
                                        OMITTED
                                        BY DESCRIPTOR   REG_FULL_MSG
                                  GIVING FORMS_STATUS
                CALL "SRVCHK" USING FORMS_STATUS  GO TO FINI  END-IF.
*+
* Make entry in register.
*-
        ADD 1 TO LAST_REGISTER_NUM.
        MOVE ZEROS TO REG_ITEM_NUMBER(LAST_REGISTER_NUM),
                      REG_ITEM_PAY_AMT(LAST_REGISTER_NUM).
        MOVE DATE_FIELD(1) TO REG_ITEM_DATE(LAST_REGISTER_NUM).
        MOVE DEPOSIT_FIELD(1) TO REG_ITEM_DEPOSIT_AMT(LAST_REGISTER_NUM).
        MOVE BALANCE_FIELD(1) TO REG_ITEM_BALANCE(LAST_REGISTER_NUM).
        MOVE PAYMEM_FIELD(1) TO REG_ITEM_MEMO_PAY_TO(LAST_REGISTER_NUM).
FINI.
        EXIT PROGRAM.
END PROGRAM MAKDEP.

This subprogram calls the RECEIVE request to get deposit data from the operator. The Form Manager returns deposit data in the COLLECT_DATA record. The subprogram then determines whether the deposit data can be entered into the check register. If the data cannot be entered, the subprogram aborts the deposit and sends a message to the operator. If the data can be entered, the subprogram enters the data in the register and exits.

IDENTIFICATION DIVISION.
PROGRAM-ID.     VUEREG.
*+
*       View the check register and scroll through it.
*       Also display totals for current session.
*

DATA DIVISION.
WORKING-STORAGE SECTION.

PROCEDURE DIVISION.
0.
* Put up register panel.
* Display summary of this session.
*-

        CALL "forms$send" USING BY DESCRIPTOR SESSION_ID
                                              "REGISTER"
                                BY REFERENCE  RECORD_COUNT
                                OMITTED
                                OMITTED
                                OMITTED
                                OMITTED
                                OMITTED
                                OMITTED
                                OMITTED
                                BY DESCRIPTOR REGISTER
                          GIVING FORMS_STATUS.
        CALL "SRVCHK" USING FORMS_STATUS.
        EXIT PROGRAM.
END PROGRAM VUEREG.

This subprogram calls the SEND request to display data on the REGISTER panel. The subprogram passes the check register data in the REGISTER record.

IDENTIFICATION DIVISION.
PROGRAM-ID.     VUEACT.
*+
*       View the account data.
*       If operator knows the secret word, let operator change
*       the account data for this session.
*-
DATA DIVISION.
WORKING-STORAGE SECTION.
PROCEDURE DIVISION.
0.
        CALL "forms$receive" USING BY DESCRIPTOR SESSION_ID
                                                   "ACCOUNT"
                                   BY REFERENCE  RECORD_COUNT
                                   OMITTED
                                   OMITTED
                                   OMITTED
                                   OMITTED
                                   OMITTED
                                   OMITTED
                                   OMITTED
                                   BY DESCRIPTOR ACCOUNT
                             GIVING FORMS_STATUS.
      CALL "SRVCHK" USING FORMS_STATUS.
      EXIT PROGRAM.
END PROGRAM VUEACT.

This subprogram requests input to the ACCOUNT record. If the operator knows the correct password, the account data can be changed. Otherwise,the Form Manager displays the account data and then returns control to the program.

The panel name in DECforms identifies a set of panel fields and literals. Unlike an FMS form name, you do not pass a panel name in a request call. You use it within the form when you need to refer to a particular panel.

To assign a panel name, type the name in the Panel Name field on the Create Panel.

Like FMS, you can associate a DECforms help panel with data entry panels. To associate a help panel with a data entry panel,specify the name of the help panel in the Help Panel field.

You may need to define certain functions and function responses to have your help operate correctly. See Section 7.3, “Providing Help for Operators”for information on providing help for the operator.

The DECforms background color attribute is equivalent to the FMS Screen Background attribute. The background color of a panel can be, depending on the capabilities of your terminal, BLACK, WHITE, BLUE, GREEN, CYAN, RED, MAGENTA, YELLOW or UNCHANGED. UNCHANGED is the same as the FMS AS IS screen background.

You can also use an RGB color specification to define your own colors. See the description of the MODIFY PANEL display-attribute COLOR command in the VVSI DECforms Guide to Commands and Utilities for information on using RGB color specifications.

The terminal can be set to a width of 80 columns, 132 columns, or UNCHANGED.UNCHANGED means that the run-time terminal width setting is used. UNCHANGED is the same as the FMS AS IS screen width.

In DECforms, the character set used on a panel is a display attribute. You can display each object on the panel (each field or literal) using a different character set. Use the Panel Editor to choose a character set for all objects on a panel. Section 6.2.9, “Assigning Default Attributes to All New Fields” explains using the Panel Editor's Display Attribute Menu to choose a character set.

You must display each panel in DECforms in a viewport. The viewport controls how much of the screen the Form Manager clears when it displays a panel. To specify that the Form Manager clear 14 lines when it displays a panel, create a 14-line viewport and specify that the Form Manager display the panel in that viewport.

If you want the Form Manager to highlight a field when it is open for input, or active, you can specify that in the field declaration. You can use the IFDL ACTIVE HIGHLIGHT clause to specify that the field is BOLD, BLINKING, REVERSE, or UNDERLINED.

You can apply the same active highlight to all fields on a panel by creating an APPLY FIELD DEFAULT clause in the panel declaration. See Section 6.3.1, “Creating Panel Fields and Applying Field Defaults” for information on using the APPLY FIELDDEFAULT clause.

FMS allows you to specify three UARs that are associated with a form: a pre-help UAR, a post-help UAR, and a function key UAR. DECforms allows you to call escape routines from your form. You can call an escape routine before help messages are displayed, after help messages are displayed, and when an undefined function key is pressed. In DECforms, you call escape routines from responses.

The sections that follow explain more about calling escape routines to emulate pre-help, post-help, and function key UARs.

Form Data
   HELP_REQUESTED       CHARACTER (2)
   HELP_TERMINATING     CHARACTER (2)
End Data
   .
   .
   .
Help Panel FOR_FIELD_ACCOUNT
   Entry Response
      Call 'ENTRY_PROCEDURAL_ESCAPE' Using HELP_REQUESTED
   End Response
   .
   .
   .
   Exit Response
      Call 'EXIT_PROCEDURAL_ESCAPE' Using HELP_TERMINATING
   End Response
End Panel
END PANEL

Panel ACCOUNT_PANEL

Function Response UNDEFINED FUNCTION
   Call 'ESCAPE_ROUTINE' Using NO_KEY_DEFINITION
End Response
   .
   .
   .
End Panel

To assign the clear character or a help message to each field in a panel at once, you create an APPLY FIELD DEFAULT clause. Section 6.3.1, “Creating Panel Fields and Applying Field Defaults” describes creating that clause.

To assign a default value to a field, you assign a default value to the form data item associated with the field.

To save you from specifying the same set of attributes for each field you create,you can add an APPLY FIELD DEFAULT clause to a panel. In the clause, you specify the attributes you want the Panel Editor to apply to each field. The Panel Editor applies attributes to all fields on the panel.

You can override a default attribute by specifying a conflicting attribute in the field declaration. If a field specifies an attribute that conflicts with a default attribute, the attribute specified in the field definition takes precedence for that field.

To create a text literal, enter the Panel Editor and move the cursor to the position where you want the literal to appear. Type the text of the literal exactly as you want it to appear on the panel.

To modify existing text literals, put the cursor on them and either type new text (to modify the literal) or press the DELETE key (to delete characters in the literal).

(Because of the restrictions of the character cell display device, you cannot create diagonal lines with the Panel Editor)

If you mark more than two points, the Panel Editor creates a polyline by connecting each mark in the order in which you create them.

You can change the list of display attributes the Panel Editor uses for newly created items using the Panel Editor's Set Display Attribute Menu. You access the Set Display Attribute Menu using the Panel Editor SET command as described in Section 6.2.9, “Assigning Default Attributes to All New Fields”.

DECforms does not distinguish between DATE and TIME fields and other fields. Also, because the Panel Editor is object-oriented, it can create adjacent fields the same way it creates fields separated by one or more spaces.

To create a DATE or TIME field, enter the Panel Editor. Issue the CREATEFIELD command and specify a DATE or TIME data type for the data item associated with the field. For example, to create a DATE field, enter the Panel Editor. Press the DO key and issue the following command:

Command> CREATE FIELD DATE_ONLY TYPE DATE 

To create an adjacent field, create two fields that have no spaces between them. For example, press the DO key and issue the following commands to create two adjacent fields containing an area code and a telephone number:

Command> CREATE FIELD AREA_CODE (5,10) TYPE CHARACTER(3) PICTURE "'('CCC')'" 
Command> CREATE FIELD PHONE_NUMBER (5,15) TYPE CHARACTER(6) PICTURE"CCC'-'CCCC" 

DECforms uses panel groups to display arrays and create scrolled regions. You can create groups in the Panel Editor with the CREATE GROUP command. To create a group, press the DO key and issue the following command:

Command> CREATE GROUP CHILD_GROUP OCCURS 3 HORIZONTAL
Command> CREATE FIELD CHILD_GROUP.CHILD_NAME (2,5) TYPE CHARACTER(20)  

The CREATE GROUP command creates the group declaration. The CREATE FIELD command creates one member for that group.

You can also create nested groups using the Panel Editor. To do so, create the outer group first, then the inner group, and then group members. The following example shows commands that create a nested group:

Command> CREATE GROUP CHILD_INFO OCCURS 3 VERTICAL 
Command> CREATE GROUP CHILD_INFO.SPECIFIC.CHILD OCCURS 4 HORIZONTAL 
Command> CREATE FIELD CHILD_INFO.SPECIFIC.CHILD.CHILD_FACT (2,5) TYPE CHAR(10)

Section 7.4, “Displaying Arrays” gives more information on DECforms groups. Section 7.5, “Creating Scrolled Regions” gives more information on creating scrolled regions.

Help messages in DECforms are the same as they are in FMS. Help messages give the operator information. The only difference between a help message in DECforms and a help message in FMS is that in DECforms, help messages can be any length.

For more information on providing help to your operator, see Section 7.3, “Providing Help for Operators”.

DECforms does not have the concept of index value, so index value does not appear in Table 6.2, “Comparison of DECforms Field Attributes and Field Validators and FMS Field Attributes and Validation Attributes”.

See the discussion of Field Description Entry in the VSI DECforms IFDL Reference Manual for the correct syntax needed to add each attribute.

DECforms uses picture characters to describe panel fields. Like FMS field validation characters, these characters determine the picture type and length of the field. In DECforms, two types of picture strings can exist for a field:an output picture and an input picture.

Output pictures identify how data appears when the Form Manager displays it. Input pictures identify what input is valid for a field. The output picture for a field can be the same as its input picture, or it can be different. However, the output picture and the input picture must specify an image that the Form Manager can convert from or to the data type of the form data item to which the field corresponds. For example, an output picture must not describe a FLOATING POINT data type if the form data item's data type is DATE.

In addition to the output picture and input picture, DECforms allows you to specify an editing clause. In the editing clause, you specify information like whether the decimal point is a period (.) ora comma (,) and whether scale is applied to a value. You also specify the character used for leading or trailing zero replacement, currency, and sign. When the Form Manager displays a value, it uses the output picture and the editing clause to determine how the value should appear. When the Form Manager stores a value in form data,it uses the input picture and the editing clause to determine whether or not the input value is valid and how to store that value.

If you do not specify an output picture for a field, DECforms generates it automatically from the data type of the field's associated form data item. If you do not specify an input picture for afield, it is the same as that field's output picture.

See the description of picture strings in the VSI DECforms IFDL Reference Manual for more information about picture characters.

In FMS, you use field completion UARs to validate operator input and perform other operations on field completion. FMS performs field completion UARs when the operator fills an Autotab field or presses a field terminator key.

In DECforms, you can call an escape routine on field completion.(See Section 7.7, “Using Escape Routines” for information on escape routines.) You call the escape routine from either a validation response or an exit response.

The Form Manager performs a validation response for a field directly after input to the field is complete. The operator signals that input to a field is complete by either filling a field with the AUTOSKIP attribute or pressing a function key. A validation response should contain response steps that either validate operator input or call escape routines that validate operator input. Notice that you may be able to perform tasks in a validation response that you used to perform in a field completion UAR. Your application is more efficient if you can validate data in a response, instead of calling an escape routine.

The Form Manager performs exit responses directly after it finishes processing validation responses. You should define an exit response to perform tasks that should be done after field completion. For example, you could print the screen from an exit response. You may be able to perform tasks in an exit response that you used to perform in a field completion UAR. Using exit responses,instead of escape routines, makes your application more efficient.

   Field  ACCOUNT_NUMBER
      Line 10 Column 5
      Validation Response                                         
        Call 'CHECK_DIGIT_VALIDATION'
           Using By Reference ACCOUNT_NUMBER Giving SUCCESS
        If SUCCESS = 0 Then Invalid End If                        
      End Response

      Exit Response
        Call WRITE_TO_DATABASE                                    
           Using By Reference ACCOUNT_NUMBER Giving SUCCESS
        If SUCCESS = 0 Then                                       
          Message "WARNING–Database update failed."
          Return Immediate
        End If
      End Response
      Input Picture 999'-'99999'-'999
      Input Required   End Field

The VSI DECforms Programmer's Reference Manual contains more information about the response steps.

When you want to allow the operator to press a key to perform a particular task, you first bind a key to a function name in a function declaration. The function name can be either a pre-defined, DECforms built-in function name or any other name that follows OpenVMS naming conventions and does not conflict with other names in the form.

DECforms provides a set of built-in functions that are bound to keys by default. (See the VSI DECforms IFDL Reference Manual for information on what those functions are and to which keys they are bound.)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 by naming more than one key in the function declaration. For example, if you want to allow the operator to invoke a function using a default key and another key, name the default key and the other key in a function declaration.

You can bind keys to functions only at the layout level.

Form EMPLOYEE_FORM

  Layout FOR_NON_DEFAULT_KEY_BINDINGS
      Device
        Terminal Type %VT200
      End Device
      Size 24 Lines By 80 Columns

      Function Transmit
            Is %KP_1
               %F10
               %Control_Z
      End Function
   .
   .
   .
  End Layout
End Form

Form EMPLOYEE_FORM

  Layout FOR_NON_DEFAULT_KEY_BINDINGS
   .
   .
   .
        Function CHANGE_EMPLOYEE Is %KP_Enter End Function  
   .
   .
   .
  End Layout
End Form

This function declaration binds a function named CHANGE_EMPLOYEE to the Enter key. This function is undefined unless you define a function response for CHANGE_EMPLOYEE.

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 most of the DECforms built-in functions. You determine what function invokes a function response by naming the function response the same as the function. For example,when the operator presses the key bound to the CHANGE_EMPLOYEE function, the Form Manager performs the CHANGE_EMPLOYEE function response.

You can write a special function response, called an UNDEFINED FUNCTION response, that controls what occurs when the operator presses an undefined key. The VSI DECforms Guide to Developing an Application describes writing a function response for UNDEFINED FUNCTION.

Form EMPLOYEE_FORM

  Layout FOR_NON_DEFAULT_KEY_BINDINGS
   .
   .
   .
    Function Response NEXT ITEM
        If Last Item Then
             Position to First Item
        Else
             Position to Next Item
        End If
    End Response
   .
   .
   .
   End Layout
End Form

The response in Example 7.3, “New Definition for the NEXT ITEM Function” tests the elementary condition LAST ITEM. Elementary conditions are predefined conditions that indicate the state of activation item processing. See the VSI DECforms Programmer's Reference Manual for more information on elementary conditions. If the condition is true, activation list processing proceeds with the first item on the activation list. Otherwise, activation list processing proceeds with the next item on the activation list. You do not have to declare the NEXT ITEM function for this function response to work. The built-in functions are declared by default, and you only declare them when you want to bind them to keys other than the default keys.

Form EMPLOYEE_FORM
   .
   .
   .
   Panel EMPLOYEE_PANEL
    Function Response CHANGE_EMPLOYEE
      Position To Next Panel
    End Response

The function response causes the Form Manager to display the panel that corresponds to the next panel activation item on the activation list. The Form Manager positions the cursor to the first field in that panel.

The FUNCTION RESPONSE declaration appears inside the declaration of EMPLOYEE_PANEL, so the Form Manager performs the response when the operator presses the ENTER key while entering data in that panel. When the operator is entering data in other panels, the CHANGE_EMPLOYEE function has no effect(unless you define other function responses).

Panel NEW_EMPLOYEE_PANEL

   Use Help Message "Enter the employee's name and previous
                     work experience."

   Group NEW_EMPLOYEE_DATA

     Field NEW_EMPLOYEE_NAME                                  
        Line 2 Column 2
     End Field

   Group PREVIOUS_EMPLOYER_INFORMATION
     Use Help Message "Enter information about the employee's
                       previous jobs"
     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
        Use Help Message "Enter the number of years spent with
                          this employer."
     End Field
   End Group
End Panel

You only have to specify a message with the USE HELP MESSAGE clause to have help messages available for your operator.

You can specify only one help message for each field. The message can be of any length because the Form Manager wraps and scrolls messages that are too long to fit in the message panel. Note that this may cause long messages to scroll off the message panel before the operator has a chance to read the entire message.

You can specify only one help message for each field, panel group, data-entry panel, or field default.

Help Panel HELP_EMPLOYEE_INFO                                          
   .
   .
   .
End Panel

Help Panel HELP_EMPLOYEE_NAME                                          
   .
   .
   .
End Panel

Panel NEW_EMPLOYEE_PANEL

   Use Help Message "Enter the employee's name and previous
                     work experience."
   Use Help Panel HELP_EMPLOYEE_INFO

   Group NEW_EMPLOYEE_DATA

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

   Group PREVIOUS_EMPLOYER_INFORMATION
     Use Help Message "Enter information about the employee's
                       previous jobs"
     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
        Use Help Message "Enter the number of years spent with
                          this employer."
     End Field
   End Group
End Panel

You need not do anything beyond declaring help panels and associating them with fields, groups, and data-entry panels with the USE HELP PANEL clause to have help panels available to your operator.

You can create special viewports for help panels. This allows you to position them anywhere on the display. Also, the RETAIN clause allows you to specify that the panel is not removed from the display when the operator terminates help. This allows the help text to be displayed while the operator is entering data in the field on which help was needed. See the description of the POSTDISPLAY clause in the VSI DECforms IFDL Reference Manual for more information on the RETAIN clause.

A data group can be a simple group, which is a collection of form data items. Each group can include an OCCURS clause, which designates that each form data item in the group occurs multiple times. Group declarations that include an occurs clause create one-dimensional arrays. To create a two-dimensional array, you nest one multiple-occurrence group inside another. You can nest multiple-occurrence groups only one level. However, you can nest simple groups any number of levels.

You can use a 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 a member of a multiple-occurrence group, you use a subscript. You must fully qualify all references to group members.

   Form Data
        EMPLOYEE_NAME Character(30)
        EMPLOYEE_ID_NUMBER Integer(10)
        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 Data

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

For fields or literals within multiple-occurrence panel groups, the line and column clause in the field or literal declaration determines the position of the first occurrence of that field or literal on the display. The appearance of subsequent occurrences is controlled by the VERTICAL and HORIZONTAL clauses. If you specify VERTICAL, subsequent occurrences of items in the group appear below the first occurrence. If you specify HORIZONTAL, subsequent occurrences of the group appear to the right of the first occurrence.

Horizontal groups of panel fields must occur the same number of times as the form data group to which they correspond (that is, they cannot scroll). Vertical groups of panel fields that are the outermost multiple-occurrence group can occur fewer times than their corresponding data groups. The Form Manager scrolls data in the group of panel fields when necessary to show all data stored in the data group. A vertical multiple-occurrence group nested inside another multiple-occurrence group must occur the same number of times as its related data group. You determine how many times a vertical group occurs with the DISPLAYS clause. Section 7.5, “Creating Scrolled Regions” describes using 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 7.1, “Appearance of Groups on the Display” illustrates how the panel in the Example 7.9, “Declaration of Panel Fields to Display a Form Data Item Group” is displayed.

To activate a panel field, you specify the ACTIVATE response step and name the panel field. If you want to activate an entire panel group, you specify the GROUP clause with the ACTIVATE response step. You name the group you want the Form Manager to activate in the ACTIVATE GROUP response step. You must specify the panel on which the Form Manager displays the panel group or panel field in the ACTIVATE response step.

ACTIVATE GROUP EMPLOYEE_ADDRESS On GROUP_PANEL

Activate Field EMPLOYEE_ADDRESS.STREET_ADDRESS On GROUP_PANEL

This response step causes the Form Manager to activate only the first panel field in the EMPLOYEE_ADDRESS group.

Activate Group SPOUSE On GROUP_PANEL

Activate Group DEPENDENT On GROUP_PANEL

Activate Field DEPENDENT(2).CHILDREN(1).CHILD_NAME On GROUP_PANEL
Activate Field DEPENDENT(1).CHILDREN(2).CHILD_NAME On GROUP_PANEL

To pass data between form data groups and the program, you must declare a form record that contains a group that corresponds to the form data group. You must also declare a program record that is logically equivalent to the form record and contains a structure that is logically equivalent to the form record field group.

Form EMPLOYEE_FORM

  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.
*—
* This COBOL record is logically equivalent to the preceding
* form record.
*–
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) COMP.

     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.

In DECforms, you use a scrolled region to display groups. Therefore,to create a scrolled region, you declare a form data group and a panel group that correspond to each other. You then include a VERTICAL DISPLAYS clause in the panel group declaration to specify the number of times the panel group occurs on the display. The Form Manager displays as much data as fits in the group on the display. If the operator requests to see more of the data, the Form Manager scrolls the data, either by line or by page,depending on what you specify. Figure 7.2, “Operation of a Scrolled Region” shows how a scrolled region works.

In Figure 7.2, “Operation of a Scrolled Region”, the form data group occurs four times. The panel group is displayed twice, so two occurrences of the form data group can be displayed at once.

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
    Device
     Terminal Type %VT200
    End Device

    Function CHANGE_ITEM is %KP_7 End Function           
   .
   .
   .
    Panel SCROLL_PANEL
      Function Response CHANGE_ITEM                      
        Activate Panel CHANGE_ITEM_PANEL
      End Response

      Literal Text
        Line 2 Column 30
        Value "VIEW PHONE NUMBERS"
        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 or remove an entry"

    END PANEL
  END LAYOUT
END FORM

You can change the keys to which these functions are bound by declaring the function in your IFDL source file. You can write a function response for these functions if you need actions other than those given by default. See Section 7.1, “Defining Keys” for information on declaring functions and writing function responses.

In other words, the last known value is the last value the program “knows.” The second copy of the form data item stores the current value of the form data item.

Directly before the Form Manager returns the current value of the form data item to your program, it compares the current value to the last known value. If the current value and last known value are different, the Form Manager returns information to your program in the shadow record that indicates the form data item has changed.

Form EMPLOYEE_FORM

  Form Data
    EMPLOYEE_NAME           Character (30)   Tracked
    EMPLOYEE_ID_NUMBER      Integer (10)
    HIRE_DATE               Date
    CURRENT_JOB_TITLE       Character (10)   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
   .
   .
   .
End Form

The EMPLOYEE_NAME and the CURRENT_JOB_TITLE form data items are tracked. You should use the TRACKED clause only where you need it. It doubles the amount of storage needed for a data item, and it may degrade performance.

The example also shows a form record that can be used to pass data to and from the form data items.

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.

This shadow record indicates that one or more fields in EXPERIENCE_RECORD have changed because a 1 is the first character of the shadow record. The second character of the shadow record indicates that new input changed the EMPLOYEE_NAME field in EXPERIENCE_RECORD. The next two characters in the shadow record indicate that the Form Manager did not maintain tracking information for the form data items that correspond to those record fields. Finally, the 0 indicates that the CURRENT_JOB_TITLE field is unchanged.

Pass the receive shadow record in the receive-shadow-record parameter to the FORMS$RECEIVE call or the FORMS$TRANSCEIVE call. See the VSI DECforms Programmer's Reference Manual for information on the receive-shadow-record parameter.

You can write an escape routine in any of the programming languages that DECforms supports. You must follow the syntax rules of the programming language for creating a subroutine. The only difference between an escape routine and other subroutines in your program is that you call an escape routine from the form, instead of from another part of your program. You must write the escape routine so that it can be called from code external to your program.

You can call a request from an escape routine, but you cannot call a DISABLE request that terminates the session from which you called the escape routine. (See the description of using escape routines in the VSI DECforms Programmer's Reference Manual for information on calling DECforms requests from escape routines.)

IDENTIFICATION DIVISION.
PROGRAM-ID.     INCREMENT.
**************************************************************************
*   General escape routine to increment a value.                         *
**************************************************************************
DATA DIVISION.
WORKING-STORAGE SECTION.
LINKAGE SECTION.
01         COUNT_KEEPER     PIC 9(9)    COMP.
PROCEDURE DIVISION USING COUNT_KEEPER.
0.
*+
* Add one.
*+
        ADD 1 to COUNT_KEEPER.
*
        END PROGRAM INCREMENT.

In addition to writing the escape routines, you must include the FORMS$AR_FORM_TABLE symbol in your FORMS$ENABLE call. This symbol allows the Form Manager to find the escape routines. The symbol is a declared DECforms-supplied definitions file that is stored in SYS$LIBRARY. The definitions file also declares the DECforms request calls. DECforms provides the file for most programming languages. You should copy the definitions file into your program.

*
* Copy statement for COBOL definitions
*
COPY "SYS$LIBRARY:FORMS$COB_DEFINITIONS.LIB".
*
* Enable call for escape routines
*
        CALL "forms$enable" USING BY VALUE  FORMS$AR_FORM_TABLE
                                  BY DESCRIPTOR DISPLAY_DEVICE
                                  BY DESCRIPTOR SESSION_ID
                                  BY DESCRIPTOR SAMP_FORM
                            GIVING FORMS_STATUS.

To transfer control to an escape routine, write a response that contains the CALL response step. This response step calls your escape routine. You can pass data items to the escape routine as parameters to this response step. You can use the GIVING phrase of the response step to get status from the procedural escape. You must declare the variable into which Form Manager writes status as a LONGWORD INTEGER.

Exit Response
  Call 'Increment' Using By Reference TRANSACTION_COUNT
End Response

The EXIT RESPONSE in Example 7.17, “CALL Response Step” calls the INCREMENT escape routine shown in Example 7.15, “Escape Routine in a COBOL Program”. The CALL response step passes the form data item TRANSACTION_COUNT to the escape routine. The escape routine increments the value it receives from the form and returns it to the TRANSACTION_COUNT form data item.

You must be aware of the data type and length of form data items that you pass to escape routines. The data type of the form data item must create the same internal OpenVMS data type as the variable declared in your program. For example, suppose you declare a form data item to be the DECforms INTEGER data type. DECforms represents the INTEGER data type as an OpenVMS numeric string with a left separate sign. The variable in your program that is to receive the data must also create an OpenVMS numeric string with a left separate sign in internal storage. See the VSI DECforms IFDL Reference Manual for information on what OpenVMS data types DECforms uses to represent IFDL data types. The lengths of the form data item and program variable must also match.

Each programming language has different rules for how you pass external variables to a routine written in the programming language. You must use the appropriate passing mechanism in the CALL response step so that your escape routine can use the value you pass to it. See the documentation for your programming language for information on passing external variables to your program.

See the VSI DECforms IFDL Reference Manual for more information about the CALL response step and defining responses.

To link your application when it contains escape routines, first create a form object module. A form object module contains a list of the escape routines that you call from the form. You create a form object module using the Extract Object Utility.

To create an object module using the Extract Object Utility, issue the FORMS EXTRACTOBJECT command, which has the following format:

FORMS EXTRACT OBJECT input-file-specification[,input-file-specification...]

Substitute the file name of your form file for input-file-specification. The default file type for the input file is the .FORM type.

You can specify several input files. Separate the file names with a comma. The Extract Object Utility generates one object file, which contains an object module for each form listed on the command line. The default name of the output file is the same as the input file name with the .OBJ file type. (See the VVSI DECforms Guide to Commands and Utilities for more information on the FORMS EXTRACT OBJECT command.)

After you create an object module, link it with your program using the DCL LINK command. For example, to link a vector object module called VECTOR_NAME.OBJ to a program object module name PROGRAM_NAME.OBJ, issue the following command:

$ LINK PROGRAM_NAME.OBJ, VECTOR_NAME.OBJ

If you store your escape routines in a separate file from the rest of your program, you must also link the escape routines to the program. You may also want to store escape routines in shareable images. See the documentation on escape routines in the VSI DECforms Programmer's Reference Manual for information on linking escape routines stored in shareable images.