Character-cell devices include VT devices such as the VT100- through VT500-series terminals, and terminal emulators that correctly emulate those VT terminals. DECforms supports these character-cell devices through the definition of viewports, panels, and responses in IFDL layouts having a device type of %VT100, %VT200, %VT300, %VT400, or %VT500. If you specify %VT100, you can run the layout on all VT devices.

Character-cell layouts support both input and output operations. They allow applications to display panels and data on the display device and also allow the user to enter and modify data through a keyboard. You can specify particular user-defined actions in the character-cell layout for individual function keys on the keyboard.

To choose a character-cell layout as the user interface, the application must pass the device name of a character-cell device as the enable device parameter in the Forms Enable request. Often this name is SYS$INPUT, or SYS$OUTPUT. When the Form Manager must use a character-cell layout, it selects the layout in the form that best matches the characteristics of the specified device. This layout has a device type of %VTxxx and most closely matches the VT layout according to the type, width, height, and color capabilities of the device.

Character-cell layouts support viewports, panels, panel groups, icons, picture fields, text fields, text literals, polylines, and point literals.

A set of default function responses is defined by the Form Manager for the keyboard function keys. If you choose, you can override these definitions.

User input is validated against the field's input picture as each character is typed.

Character-cell layouts and their contents can be created and modified by the Form Development Environment and Panel Editor. Only on Alpha, Migration utilities can be used to aid the conversion of FMS form files to DECforms IFDL form files.

DECforms supports PRINTER devices through the definition of viewports, panels, and responses in IFDL layouts having a device type of %PRINTER. The primary use of PRINTER layouts is to generate high quality printable output.

The PRINTER device means an output file in DDIF format. You can convert a DDIF document you produced in DECforms to PostScript® format and print it on a PostScript printer. (To convert the file format, you must have the CDA converters supplied with DECwindows on your system.)

An application program depicts panels with the DISPLAY response step. This display does not actually appear on the terminal or workstation display device when you use a PRINTER layout. The DISPLAY response step instead creates output representing these panels. An application might print a set of invoice or purchase orders by using a PRINTER layout, or an application might simply generate a high-quality, fixed-format printable report by using this feature.

To use a %PRINTER device and choose a PRINTER layout, you must pass the file name as the enable device parameter in the ENABLE request. This layout must have a device type of %PRINTER.

To choose between multiple PRINTER layouts, you can specify an optional selection label within the IFDL file. An application can pass a selection label to the Form Manager to choose a specific layout (the layout with the matching selection label). In the absence of a selection label, the Form Manager chooses the first DDIF layout found. PRINTER layouts cannot be shared with VT layouts.

PRINTER layouts support viewports, panels, panel groups, picture fields, text fields, text literals, polylines, and point literals.

Function keys and function responses can be defined in a PRINTER layout, but are ignored at run-time. Because there is no operator interaction with a PRINTER layout, all such actions are ignored. However, the Form Manager processes a small subset of response steps (DISPLAY, LET, IF/THEN/ELSE...) in the external request processing phase.

You can create and modify PRINTER layouts by using any Editor.

   
$ DEFINE FORMS$DEFAULT_DEVICE document_name.doc

When the operator runs the application, DECforms creates a file in the format document_name.doc in the current directory.

The VSI DECforms Guide to Developing an Application provides an example of how to support quality printing in an IFDL form and in an application program.

Adding PRINTER layouts to your application may require you to redesign part of your application. Because PRINTER layout devices are output-only, there is no operator input of data. Therefore, you may choose to define a different set of DECforms requests, or possibly a different application, that interacts with the PRINTER layout to produce high quality output. You can create and design the contents of PRINTER layouts by using any Editor.

Before the Form Manager can display information, accept input, or control communication, it must load a form into memory, select a layout, attach a display device, allocate an instance of form data, and create a session-identification string. Because the Form Manager performs these tasks during the processing of an ENABLE request, the first request that you call from your application program must be the ENABLE request.

If you are using multiple forms, you do not need to place all enable calls before any other request calls. You need to ensure only that the ENABLE request, FORMS$ENABLE (OpenVMS API) or forms_enable (portable API), is the first request made for a given display device and form pair.

        IMPLICIT NONE
        INCLUDE 'forms_checking_common.f'                          
        INTEGER sample_checking_account
        EXTERNAL sample_checking_account
C
C Define data and form file names
C
        CHARACTER*200  form_file_name
        CHARACTER*200  sample_data_name
C Option list.  Used to pass special options to forms requests (calls)
        RECORD /forms_request_options/ enable_request_options(3)

C Print startup message on console

        PRINT *,
     1 'FORTRAN DECforms Sample Checking Account Application starting.'

C Build the data and form file names

        CALL forms_checking_getdir( form_file_name, sample_data_name)

C Set up printing to go to the operator's scratch directory. This involves
C passing a request_options parameter in the enable request.

        enable_request_options(1).option = forms_c_opt_print
        enable_request_options(1).print_file_name = %LOC(print_file_name)
        enable_request_options(1).print_file_name_length = LEN(print_file_name)

        enable_request_options(2).option = forms_c_opt_form
        enable_request_options(2).form_object = %LOC(sample_checking_account)

        enable_request_options(3).option = forms_c_opt_end

C Initialize the DECforms form & check for errors



                                                                   
   forms_status = forms_enable_for( session_id,         ! session id string
 1                                  device_name_string, ! Device name
 2                                  form_file_name,     ! Name of form file
 3                                  form_name_string,   ! Name of form
 4                                  enable_request_options)
                                                      ! Request options list

        CALL check_forms_status( forms_status )                      

   .
   .
   .

Use the ENABLE request when you want to load a new form into memory, select a new layout, and attach a new display device. Each time that you call the ENABLE request, the Form Manager creates a new session, which is identified by a session-identification string. You can call the ENABLE request as often as you need to create new sessions.

The Form Manager creates a session-identification string for each session that you create. You must pass a session-identification string in all SEND, RECEIVE, TRANSCEIVE, DISABLE, and CANCEL requests to tell the Form Manager which session to use while processing the request. Even if you create only one session, you must pass a session-identification string. Sessions are independent of one another; the only way to pass information between sessions is through the application program.

For more information on the ENABLE request and its arguments, see Chapter 5, Using the OpenVMS API and Chapter 6, Using the Portable API.

Use the RECEIVE request to retrieve data stored in form data items and move the data into the record fields of an application program record.

Records defined in your application program control how data is transferred to and from the program. You pass the application program record as a record message argument to a request call. The record message argument is a pointer to an area of memory that stores the fields in the application program record.

When the Form Manager transfers data to the application program during the processing of a request, it copies the data into the area of memory pointed to by the record message. These values are kept in the application program record until the program itself or the processing of another request changes them.

   .
   .
   .

C Get new information for account record.  If termination was quit,
C then the operator might have changed a few things that the quit is
C supposed to ignore, so send the original account record back to the
C form and return to menu processing.

   .
   .
   .

        record_data.data_length = account_size         ! for pre-V5 FORTRAN
C-V5 -> record_data.data_length = SIZEOF(account_temp) ! for VAX FORTRAN V5
        record_data.data_record = %LOC(account_temp)
        record_data.shadow_record = 0
        record_data.shadow_length = 0


C Set up to receive control text back from the form

        request_options(1).option = forms_c_opt_receive_control
        request_options(1).receive_control_text_count= %LOC(receive_ctl_txt_ct)
        request_options(1).receive_control_text= %LOC(receive_ctl_txt_string)

        request_options(2).option = forms_c_opt_end



C Get the record from the form

     forms_status = forms_receive_for( session_id,    ! session id   
     1                                 'account',     ! form record
     2                                 record_data,   ! info from the form
     3                                 request_options)!request option list

        CALL check_forms_status( forms_status )                      

   .
   .
   .

To move the values from form data items to fields in the ACCOUNT application program record (because the form activates fields in the RECEIVE RESPONSE), the Form Manager must solicit input from the operator. It does so by displaying the set of panel fields corresponding to the form data items associated with the data in the application program record.

The operator enters input to the panel fields, and the Form Manager stores that input in form data items. The Form Manager moves the values stored in the form data items to the fields in the application program record.

This correspondence allows the Form Manager to determine which panel fields need input, which form data items store that input, and into which application program record fields it moves this input during the processing of a RECEIVE request.

This name correspondence is the most common way to specify the transfer of form data to form records, but it is not the only way to transfer information from the form to your program. Another way to specify data transfer is to use the DATA TRANSFER clause. For more information, see the VSI DECforms IFDL Reference Manual.

If errors occur during the processing of this RECEIVE request, the Form Manager stores receive control text items in the variable for the receive_control_text request option. For more information about receive control text, see Section 4.7, “Request Termination Phase”.

Use the RECEIVE request when you need information from the form and, optionally, from the operator in your application program. Not all RECEIVE requests solicit input from the operator, but soliciting input from the operator is part of the default processing that the Form Manager performs for the RECEIVE request. Section 4.3, “External Response Processing Phase” describes the default processing.

The statements in the sample application program shown in Example 2.2, “RECEIVE Request from the Advanced FORTRAN Sample Program” are part of a subroutine that is called when the operator chooses to look at and modify data stored in the account record. The account record is maintained in the application program.

Because the account record is maintained in the application program, the program must receive new values entered by the operator. Therefore, the program calls the RECEIVE request when the operator needs to enter new data into this record. This call ensures that the program receives the new data directly after it is entered.

For more information on the RECEIVE request and its arguments, see Chapter 5, Using the OpenVMS API and Chapter 6, Using the Portable API.

Use the SEND request to send data to the form. This request causes the Form Manager to move data from an application program record to form data items.

C Update the balances, next check number, and room_in_reg flag in the form.
C If there's no room for more entries in the register, then
C the room_in_reg flag is sent as zero(false), else true(all 1's in Fortran).

        IMPLICIT NONE
        INCLUDE 'forms_checking_common.f'

        RECORD /update/ update                                         

        update.checking_balance = checking_balance                     
        update.savings_balance  = savings_balance
        update.check_number     = last_check_num
        update.room_in_reg      = register.number_entries_used .LT. reg_size

C Initialize the descriptor with UPDATE info

   .
   .
   .
        record_data.data_length = update_size    ! for pre-V5 FORTRAN
C-V5->  record_data.data_length = SIZEOF(update) ! for VAX FORTRAN V5
        record_data.data_record = %LOC( update )
        record_data.shadow_record = 0
        record_data.shadow_length = 0

C Send the update record

        forms_status = forms_send_for( session_id,     ! session id   
     1                                 'update',       ! form record
     2                                 record_data,    ! info sent to form
     3                                 0 )             ! request options list

        CALL check_forms_status( forms_status )                       

        RETURN
        END

Use the SEND request when your application program needs to change the values stored in form data items. The statements in Example 2.3, “SEND Request from the Advanced FORTRAN Sample Program” are used in a subroutine in the sample application program. This subroutine is called from other subroutines in the sample application program when the operator changes the account balance.

For example, assume that the application program had previously called a RECEIVE request. During the processing of the RECEIVE request, the operator writes a check on the account, and the amount of that check and the check number are returned to the application program. The application program then calculates a new account balance, assigns a new value to the highest check number, and verifies that the history register it maintains has room for more transactions.

If the history record has room to store the history record of more transactions, the application program sets the variable room_in_reg to 1. If the history record is full, the application program sets the room_in_reg variable to 0, and the operator cannot enter any more transactions on the account. (In this sample application program, the history record is limited to storing information about 30 transactions. Normally, the history record would not be limited in this way.)

Once the application program has performed these tasks, it calls the subroutine shown in Example 2.3, “SEND Request from the Advanced FORTRAN Sample Program”. The SEND request passes the new balance, the highest check number, and the room_in_reg value to the form data items that store them. The contents of these form data items control what transactions the operator can perform. Therefore, it is important that these form data items be updated promptly after each operator action that modifies the account. If this is not done, the operator might be able to write a check for more than the current account balance.

As another example, suppose that the purpose of your application program is to calculate subtotal and total amounts for an invoice. Once these amounts have been calculated, you use the SEND request to pass the subtotal and total to form data items, which are then displayed on a panel. In this type of application program, using the SEND request immediately after the subtotal and total amounts are calculated ensures that incorrect values are not inadvertently displayed on the display device.

For more information on the SEND request and its arguments, see Chapter 5, Using the OpenVMS API and Chapter 6, Using the Portable API.

In general, DECforms requests cannot be made from asynchronous system trap (AST) routines because much of DECforms request processing occurs at AST level, and normal request processing is synchronous with respect to the caller. Form Manager requests from AST level might produce deadlock situations within the process running a DECforms application.

However, it is often useful to communicate with a form from an AST routine. For example, an application might have a timer AST routine fire periodically to display time-critical data on the screen. DECforms software provides a mechanism by which the SEND request can be used at AST level to send information to the form. Specifically, when an AST routine issues a SEND request, the request executes asynchronously with respect to the calling routine. In addition, only a severely restricted subset of request processing is performed.

The asynchronous SEND requests perform only the data distribution phase of request processing and then the request is terminated. If the data being sent to the form is currently displayed on a panel, the panel fields are updated normally with the new values. However, because no response processing or accept phase processing is performed, the panel must be displayed by a previous synchronous request.

Because SEND requests at AST level execute asynchronously with respect to the AST routine, the programmer must take care to provide proper synchronization at request completion. DECforms can provide AST notification of request completion, using the FORMS$K_ASTADR and FORMS$K_ASTPRM item codes in the request-options item list argument in the OpenVMS API.

Hewlett-Packard Company strongly recommends that you use this feature when using asynchronous SEND requests. For more information on the FORMS$K_ASTADR and FORMS$K_ASTPRM item codes, see Chapter 5, Using the OpenVMS API. For more information about setting up AST routines, see the OpenVMS System Services manual.

In the portable API, the FORMS$K_ASTADR and FORMS$K_ASTPRM item codes are referred to as completion routines. You can set up the mechanism by using the completion routine structure in the request option definition.

Use the TRANSCEIVE request to send data to the form from the application program and to receive data from the form in the application program.

Example 2.4, “TRANSCEIVE Request from the Advanced FORTRAN Sample Program” contains an example of using the TRANSCEIVE request in the portable API. For this TRANSCEIVE request, the application program is sending and receiving two fields in register_record.

C
        IMPLICIT NONE
        INCLUDE 'forms_checking_common.f'

C Option list.  Used to pass special options to forms requests (calls)

        RECORD /forms_request_options/ request_options(2)

C Initialize the descriptor with REGISTER info

   .
   .
   .
        record_data.data_length = register_record_size  ! for pre-V5 FORTRAN 
 C-V5-> record_data.data_length = SIZEOF(register)      ! for VAX FORTRAN V5
        record_data.data_record =   %LOC(register)
        record_data.shadow_record = 0
        record_data.shadow_length = 0



C Set up to receive control text back from the form

        request_options(1).option = forms_c_opt_receive_control
        request_options(1).receive_control_text_count=%LOC(receive_ctl_txt_ct)
        request_options(1).receive_control_text=%LOC(receive_ctl_txt_string)

        request_options(2).option = forms_c_opt_end



C Transceive the record (send it and ask to get it back)



forms_status = forms_transceive_for(session_id,! session id      
1                                  'register_record',  ! send record name
2                                  record_data,        ! the send record
3                                  'register_record',  ! Receive record
                                                       ! name
4                                  record_data,        ! the recv record
5                                  request_options)    ! request options
                                                       ! list

CALL check_forms_status( forms_status )                          

END

Use the TRANSCEIVE request any time information you send to the form could generate new information that you need in your application program. For example, suppose your application program calculates and stores the values needed to create a balance sheet from your accounting records. This program might contain a TRANSCEIVE request within a loop.

In the TRANSCEIVE request, you send the numbers that were calculated in the application program to the form. These numbers are then displayed on the display device in a completed balance sheet. The operator looks at the balance sheet to see whether it is correct.

If the balance sheet is correct, the operator enters a value in a field that indicates the balance sheet is complete. When this occurs, the Form Manager returns the same values to the application program that it just received from the application program. These values are stored for future reference.

However, if the balance sheet is incorrect, the operator enters a value in a field that indicates the balance sheet is incorrect. The Form Manager then asks the operator for input into each field that affects the totals on the balance sheet.

Once the operator has entered all the changed information, the new data is returned to the application program. The application program recalculates the amounts to be displayed in the balance sheet and returns them to the display by calling the TRANSCEIVE request again. This process continues until the balance sheet is correct.

For more information on the TRANSCEIVE request and its arguments, see Chapter 5, Using the OpenVMS API and Chapter 6, Using the Portable API.

Call the DISABLE request to terminate the session.

C Clean up, Print ending message on console, leave.

   IMPLICIT NONE

   INTEGER status
   INCLUDE 'forms_checking_common.f'

   forms_status = forms_disable_for( session_id , 0 )                 

   PRINT *, 'FORTRAN DECforms Sample Checking Account Application ending.'
   STOP
   END

In some situations, you may want to cancel the processing of the current DECforms requests immediately. Use the CANCEL request to stop processing of the current request.

        forms_status = forms_cancel_for( session_id,0)   
        CALL check_forms_status( forms_status )          
        END

For more information on Form Manager processing of the CANCEL request, see Chapter 4, How the Form Manager Processes Requests.

$ FORTRAN FORMS$SAMPLE_PROGRAM_FORTRAN  (OpenVMS API)
$ FORTRAN FORMS$CHECKING_FORTRAN (portable API)

The command in this example creates an object file that can be input to the OpenVMS Linker. In this example, the object files are named FORMS$SAMPLE_PROGRAM_FORTRAN.OBJ (OpenVMS API) and FORMS$CHECKING_FORTRAN.OBJ (portable API). For information about the command that invokes your compiler, see the documentation for your programming language.

The FORTRAN compiler picks up the library file in your working directory, and the C compiler picks up the library file in SYS$INCLUDE.

$ CC FORMS$SAMPLE_PROGRAM_C (OpenVMS API)
$ CC FORMS$CHECKING_C (portable API)

$ LINK FORMS$SAMPLE_PROGRAM_FORTRAN

The command in this example creates an executable image that you can execute with the RUN command. In this example, the executable image is named FORMS$SAMPLE_PROGRAM_FORTRAN.EXE. For more information on the LINK command, see the OpenVMS Linker Reference Manual.

$ LINK FORMS$CHECKING_FORTRAN.OBJ, SYS$INPUT/OPTION -
_$ SYS$SHARE:FORMS$PORTABLE_API/SHARE Ctrl/Z

If you plan to link escape routines with your application program, you should link the escape routines, your application program, and the form object file on the same command line. Section 2.3, “Writing and Calling Escape Routines” describes using escape routines.

All DECforms entry points for the new portable bindings are in the shareable image, SYS$SHARE:FORMS$PORTABLE_API.EXE. The DECforms run-time system remains in SYS$SHARE:FORMS$MANAGER.EXE.

When you use a linked form in the portable API, you must specify the /PORTABLE_API qualifier in the FORMS EXTRACT OBJECT command to generate the global form name symbol in the form object.

$ FORMS EXTRACT OBJECT FORMS$SAMPLE_FORM.FORM

$ FORMS EXTRACT OBJECT /PORTABLE_API FORMS$CHECKING_FORM.FORM

$ RUN FORMS$SAMPLE_PROGRAM_FORTRAN (OpenVMS API)
$ RUN FORMS$CHECKING_FORTRAN (portable API)

For more information on the RUN command, see the OpenVMS DCL Dictionary.

To link an escape routine with your application program or to enable a linked form, you must create a form object. A form object contains a list of the escape routines that are called from the form file you are using. You create the form object using the Extract Object Utility.

$ FORMS EXTRACT OBJECT filename.FORM /OUTPUT=form_obj

In this case, the resulting object file is named form_obj.obj. If you do not specify a destination object file using the /OUTPUT qualifier, the Extract Object Utility creates a file with the same name as the input file name and a file type of .obj. For more information on the FORMS EXTRACT OBJECT command, see the VSI DECforms Guide to Commands and Utilities.

The Extract Object Utility stores the names of all the escape routines that you call from your form in a form object module. You must link this object with your application program. When you link the form object, the Linker assigns addresses to those escape routines that are linked directly with your application program. If the Linker encounters the names of escape routines that are not linked directly with your application program, it assigns a value of zero to those names.

When the Form Manager prepares to transfer control to an escape routine, it searches for the name of the escape routine in FORMS$AR_FORM_TABLE. If the Form Manager finds an address assigned to the name, it transfers control to the subroutine that starts at that address. However, in the portable API, if the Form Manager finds a value of zero assigned in the table, DECforms returns an error indicating that it could not find the escape routine. In the OpenVMS API, it attempts to activate a shareable image to find the escape routine.

$ LINK FORMS$CHECKING_FORTRAN, ESC_UNIT, FORM_OBJECT

In this example, the application program, FORMS$CHECKING_FORTRAN.OBJ, is linked with one escape routine, ESC_UNIT.OBJ, and one form object. The form global symbol, FORMS$AR_FORM_TABLE, contains the address of ESC_UNIT after the Linker finishes processing this command.

Figure 2.1, “Control Transfer to a Directly Linked Escape Routine” illustrates how the Form Manager transfers control to an escape routine that has been directly linked with the application program.

For detailed examples on setting up a form object option in the enable request option list, see Section 6.2, “Using the Forms_Request_Options Structure” and Section 6.3, “Using Disk-Based Forms or Linked Forms”.

$ FORMS TRANSLATE MYFORM.IFDL

$ FORMS EXTRACT OBJ /PORTABLE_API MYFORM.FORM /OBJ=MYFORM.OBJ

$ LINK MAIN_PROGRAM, ESC_UNIT, MYFORM.OBJ, SYS$INPUT /OPTION - 

_$ SYS$SHARE:FORMS$PORTABLE_API /SHARE Ctrl/Z

You can link escape routines in a shareable image only if you are using the OpenVMS API. For information on creating a shareable image, see the OpenVMS Linker Utility Manual.

To resolve escape routine references in your form, you must create a form object file using the forms Extract Object Utility and link it with your escape routines and application program.

$ DEFINE FORMS$IMAGE DISK1$:[SMITH]SHAREABLE_IMAGE

All routines in the shareable image that you invoke as escape routines must be universal symbols in the shareable image. Escape routines are located at run time with the LIB$FIND_IMAGE_SYMBOL routine. For more information on LIB$FIND_IMAGE_SYMBOL, see the OpenVMS Run-Time Library documentation.

If you are using more than one shareable image, the FORMS$IMAGE logical name can be a search list. You cannot specify a node name in this logical name definition; however, you can specify a device, directory, and file type. If you omit the device and directory from the logical name definition, the image activator looks for the file in SYS$SHARE. If you omit the file type, the image activator looks for a file with the .EXE type.

If the FORMS$K_IMAGE item code was specified in the request-options argument of the ENABLE request, the FORMS$IMAGE logical name is not used.

When you specify the item code, the buffer address should contain the name of the shareable image containing the escape routines. You can specify the FORMS$K_IMAGE item code up to eight times, each referring to a different shareable image. If you specify more than one shareable image, the Form Manager begins searching with the first shareable image in the request-options list and terminates processing when it finds the procedural escape or it tries all the shareable images in the item list.

If you did not specify a FORMS$K_IMAGE item code in the enable response, or the Form Manager cannot translate FORMS$IMAGE when it attempts to transfer control to an escape routine stored in a shareable image, it returns an error to your application program. If the Form Manager cannot find the shareable image, it also returns an error to your application program. In either case, the request that caused the escape routine to be called terminates processing.

Figure 2.2, “Control Transfer to an Escape Routine in a Shareable Image” illustrates how the Form Manager transfers control to an escape routine that has been stored in a shareable image.

symbol_vector=(FORMS$AR_FORM_TABLE=DATA)

$ LINK/SHARE/EXE=FORMS$SAMPLE_FORM FORMS$SAMPLE_FORM, SYS$INPUT/OPT - 
_$ SYMBOL_VECTOR=(FORMS$AR_FORM_TABLE=DATA)

The shared image can then be linked with the application program, allowing the form to be accessed through this image.

In addition, if the procedural escape routines are contained in a shared library that does not contain an .obj file that was created by issuing the FORMS EXTRACT OBJECT or the FORMS EXTRACT OBJECT/NOFORM_LOAD command, each shared procedural escape routine entry point must be declared as well.

$  LINK/SHARE/EXE=SAMPLE_PEUS, SAMPLE_PEUS, SYS$INPUT/OPT -
_$ SYMBOL_VECTOR=BOLD
_$ BOLD

Debugging DECforms escape routines that exist in shareable images is difficult because the Form Manager dynamically activates the images in the escape routines using the RTL LIB$FIND_IMAGE_SYMBOL routine. You cannot set breakpoints in escape routines until the Form Manager activates the image. You must signal the SS$_DEBUG condition in routines that are to be debugged as procedural escapes.

To make it less difficult to debug escape routines, you can specify a logical name, FORMS$DEBUG_ESCAPE_ROUTINES, at session-enable time. If you specify the logical name FORMS$DEBUG_ESCAPE_ROUTINES as true, the Form Manager invokes the Debugger by signaling SS$DEBUG the first time an escape routine is called for a given DECforms session. FORMS$DEBUG_ESCAPE_ROUTINES is true when it is defined as a character string value that begins with any of the following characters: 1, T, t, Y, or y.

To invoke the Debugger, you must link the executable image that calls the Form Manager with traceback.

Once the Form Manager invokes the Debugger, you must enter the appropriate SET IMAGE, SET MODULE, and SET BREAK debug commands to set up a debugging environment. A GO command is also required. The SS$DEBUG condition is signaled as close as possible to the actual CALLG instruction that invokes the escape routine.

Trace Files

The first time tracing is turned on, the Form Manager opens a trace file specified by either the FORMS$K_TRACEFILE item code or the FORMS$TRACE_FILE logical name on the OpenVMS API, or the trace.file_name and trace.file_name_length variable on the portable API. If you specify the item code or option, the logical name is ignored. If you want the trace messages to be written to your display device, you can specify the trace file to be TT:.

If you do not specify the item code, the FORMS$TRACE_FILE logical name, the FORMS_TRACE_FILE file name, or if trace.filename is undefined when the trace facility is turned on, the trace information is written to a file in your current directory.

The file name is the same as the file name of the form file. If the file name is not specified, the form name specified in the form file is used. The file type of the file is .TRACE. For example, if your .FORM file is named FORM_ONE.FORM, the default trace file name is FORM_ONE.TRACE.

The trace file is defined as a sequential file with variable-length records.

Using the FORMS$TRACE Logical Name

The trace facility sends information to the trace file when the FORMS$TRACE logical name is defined as being on (set to T, t, Y, y, or 1). The trace facility stops writing information to the trace file when FORMS$TRACE is defined as being off. FORMS$TRACE is defined as being off when it is defined as a character string value that begins with any character except T, t, Y, y, or 1, or when it is not defined.

You can check the validity of the FORMS$TRACE logical name only on an ENABLE request. If you did not specify the FORMS$K_TRACE item code or the trace.flag field in the request-options parameter, the FORMS$TRACE logical name is translated and tracing is turned on if necessary.

Tracing Multiple Sessions

When you turn on the trace logical name for a process running multiple sessions, the DECforms software opens a trace file with a unique version number to record the progress of each session separately.

Using Request Options for Tracing

You can start and stop tracing by specifying the FORMS$K_TRACE item code in the OpenVMS API, or the trace.flag field in the portable API in the request-options parameter for each request. A zero in the buffer address terminates tracing and a nonzero value starts tracing. Tracing remains on or off until you specify a request that changes it.

Although it is convenient to enable tracing, there may be occasions where you wish to turn tracing on and off. For example, if you have a very large application, you may wish to trace only one of the requests through the entire application.

#include <stdio.h>
#include <formsdef.h>

#define TRACE_FILE_NAME "testdate.trc"

/* Declare the data structure. */



typedef
  struct _record_message_type {
      char    text_field[15];
      long    num_field;
  } Record_Message_Type;

 /* Forms Request Parameters */

  Forms_Session_Id          SessionId;
  Forms_Record_Data         Send_Message_Desc;
  Forms_Record_Data         Receive_Message_Desc;
  Forms_Request_Options     forms_request_options[10];

  Record_Message_Type    Send_Message;
  Record_Message_Type    Receive_Message;

  Forms_Status  Status;

  Forms_Control_Text    Receive_Ctl_Text;
  Forms_Count       Receive_Ctl_Text_Count = 5;
  Forms_Control_Text    Send_Ctl_Text;
  Forms_Count       Send_Ctl_Text_Count = 5;
  Forms_Value       Timeout;



main(int argc, char **argv)
{
  int i;


/* Set up the request options to establish the trace file name. The file*/
/* must be set on enable, but the flag can be passed on any request.   */

  forms_request_options[0].option = forms_c_opt_trace;
  forms_request_options[0].trace.file_name = TRACE_FILE_NAME;
  forms_request_options[0].trace.file_name_length = strlen(TRACE_FILE_NAME);
  forms_request_options[0].trace.flag = 0; /* The flag means "no tracing".*/



/* Setup Enable Options List for the Enable call. */

  i = 1;
  /* receive control text info           */
  forms_request_options[i].option = forms_c_opt_receive_control;
  forms_request_options[i].receive_control.text = &Receive_Ctl_Text;
  forms_request_options[i].receive_control.text_count = &Receive_Ctl_Text_Count;
  i++;
  /* send control text info              */
  forms_request_options[i].option = forms_c_opt_send_control;
  forms_request_options[i].send_control.text       = Send_Ctl_Text;
  forms_request_options[i].send_control.text_count = Send_Ctl_Text_Count;
  i++;

  forms_request_options[i].option = forms_c_opt_end;



  /* Issue the Forms Enable call to test a bad Enable call */

  Status = forms_enable(SessionId,            /* Form Session Id ptr*/
                        0,                    /* Terminal Device    */
                        "sample",             /* Form File name     */
                        0,                    /* Form name          */
                        forms_request_options); /* Options list       */
    if (Status != forms_s_normal)
    return (1);



  /* To enable tracing on this request: */

   forms_request_options[0].option = forms_c_opt_trace;
   forms_request_options[0].trace.flag = 1;

   forms_request_options[1].option = forms_c_opt_end;

  /* Initialize the send record structure. */
  Send_Message_Desc.data_record   = &Send_Message;
  Send_Message_Desc.data_length   = sizeof(Send_Message);
  Send_Message_Desc.shadow_record = NULL;
  Send_Message_Desc.shadow_length = 0;



  Status = forms_send(SessionId,
                      "SAMPLE_RECORD",
                      &Send_Message_Desc,
                      forms_request_options);
  if (Status != forms_s_normal)
      {
      Status = forms_disable(SessionId, 0);
      return (1);
      }



  /* To disable tracing: */

   forms_request_options[0].option = forms_c_opt_trace;
   forms_request_options[0].trace.flag = 0;

   forms_request_options[1].option = forms_c_opt_end;



  /* Initialize the receive structure. */
  Receive_Message_Desc.data_record    = &Receive_Message;
  Receive_Message_Desc.data_length    = sizeof(Receive_Message);
  Receive_Message_Desc.shadow_record  = NULL;
  Receive_Message_Desc.shadow_length  = 0;

  Status = forms_receive(SessionId,
                         "SAMPLE_RECORD",
                         &Receive_Message_Desc,
                         forms_request_options);


  if (Status != forms_s_normal)
      {
      Status = forms_disable(SessionId, 0);
      return (0);
      }

  Status = forms_disable(SessionId,              /* Form Session Id ptr*/
                         forms_request_options); /* Options list       */

  return (0);
}

*+
* Sample COBOL syntax that shows how to use the
* request options item list to enable tracing.
*-
IDENTIFICATION DIVISION.
PROGRAM-ID.    EMPLOYEE.
DATA DIVISION.
WORKING-STORAGE SECTION.


*+
* Pull in the FORMS definitions file.
*-


COPY "sys$share:forms$cob_definitions".                                 
*+
* Information that is transferred between this program and DECforms
*-
01  session_id                      PIC X(16) GLOBAL.
01  file_name                       PIC X(9)  VALUE "EMPLOYEE_PANEL".
01  device_name                     PIC X(9)  VALUE "SYS$INPUT".
01  forms_status                    PIC S9(9) COMP GLOBAL.


*+
* Request options item list.
*-
01 request_options.                                                     
    03 item_1.
        05 buff_len_1               PIC S9(4) COMP.
        05 item_code_1              PIC S9(4) COMP.
        05 buff_addr_1              PIC S9(9) COMP.
        05 ret_len_1                PIC S9(9) COMP.
    03 item_2.
        05 buff_len_2               PIC S9(4) COMP.
        05 item_code_2              PIC S9(4) COMP.
        05 buff_addr_2              PIC S9(9) COMP.
        05 ret_len_2                PIC S9(9) COMP.
    03 end_of_item_list             PIC S9(9) COMP VALUE 0.


*+
* Values for item list.                                                 
*-
01 tracefile                        PIC X(9) VALUE "TRACEFILE".         
01 tracefile_addr                   POINTER VALUE IS REFERENCE tracefile.
01 tracefile_len                    PIC S9(4) COMP VALUE 9.

01 trace_off                        PIC S9(9) COMP VALUE 0.             
01 trace_on                         PIC S9(9) COMP VALUE 1.
01 trace_len                        PIC S9(9) COMP VALUE 4.             
PROCEDURE DIVISION.
0.


*+                                                                      
* Load first item in request options item list.
* This item causes tracing to be turned on.
*-
    move forms$k_trace to item_code_1.
    move trace_len to buff_len_1.
    move trace_on to buff_addr_1.
    move binary_zero to ret_len_1.


*+
* Load second item in request options item list.                        
* This item specifies the name of the trace file to
* be created.
*-
    move forms$k_tracefile to item_code_2.
    move tracefile_len to buff_len_2.
    move tracefile_addr to buff_addr_2.
    move binary_zero to ret_len_2.


*+
* Enable the form and create the DECforms session.                      
*-
     CALL "forms$enable" USING OMITTED
                              BY DESCRIPTOR device_name
                              BY DESCRIPTOR session_id
                              BY DESCRIPTOR file_name
                              OMITTED
                              OMITTED
                              OMITTED
                              OMITTED
                              OMITTED
                              OMITTED
                              OMITTED
                              BY REFERENCE request_options

                  GIVING forms_status.


*+
* Test the completion status.
*-
    IF forms_status IS FAILURE THEN
        CALL "LIB$SIGNAL" USING BY VALUE forms_status
        STOP RUN
    END-IF.
END PROGRAM EMPLOYEE.

If the Form Manager encounters an exception condition during tracing, it issues a warning message and returns a receive control text item describing the error condition to the application program. If an exception condition occurs, tracing is turned off for the current session.

If you want to include additional tracing information about data movement, define the OpenVMS logical name FORMS$TRACE_CONVERSIONS to T. The resulting trace file will be much larger than a normal trace file.

Oracle Trace software can collect event data from a number of layered products and applications. These other products are referred to as facilities, and each has a facility definition registered in the Oracle Trace administration database. You can use the SHOW DEFINITION command to list the facilities installed on your system.

$ COLLECT SHOW DEFINITION /FORMAT=NAMES_ONLY
14-APR-1997 14:36       Facility Definition Information
Page 1
Names Only Report                                              Oracle Trace V2.2

 Facility:             Version:    Creation Date:      Class:
 --------------------  ----------  ------------------  ------------------
 FORMS                 V2.2        14-APR-1997 04:21   ALL
                                                       MONITORING
                                                       PERFORMANCE
(D)
                       V2.1         1-MAR-1997 23:36   ALL
                                                       MONITORING
                                                       PERFORMANCE
(D)

$

Oracle Trace software can collect data from all the registered facilities or just the ones in which you are interested.

$ CREATE SELECTION selection_name /FACILITY=(facility_name[,...])

$ COLLECT CREATE SELECTION MY_SELECTION /FACILITY=FORMS

To define a more detailed selection, you should use the OPTIONS qualifier, which takes a file name as an argument. The options file lists each facility and the collection class you want to use. Each facility is described on a separate line. If you specify OPTIONS but do not include a file name, Oracle Trace software prompts you for the options.

$ FACILITY facility-name [/VERSION="version-code"] [/CLASS=class-name]

$ COLLECT CREATE SELECTION SELECT_ALL /OPTIONS
Options> FACILITY FORMS /CLASS=ALL
Options> FACILITY MY_FACILITY/CLASS=PERFORMANCE
Options> Ctrl/Z
$ 

You must schedule data collection on your system for Oracle Trace software to begin collecting information about DECforms software.

Oracle Trace software does not allow you to schedule data collections that overlap or run simultaneously; although you can schedule many data collections on a node, only one collection can be active on a node at any time.

You can schedule data collection either locally or cluster wide, by using the [NO]CLUSTER qualifier. By default, the SCHEDULE COLLECTION command schedules data collection on every node in the cluster. To schedule data collection on a subset of the cluster, you must log in to each node that you want data collection to occur on and schedule local data collection on that node by specifying NOCLUSTER. On a standalone system, the CLUSTER qualifier is ignored.

$ COLLECT SCHEDULE COLLECTION MY_COLLECTION MY_DATA.DAT -
_$ /SELECTION=SELECT_ALL -
_$ /BEGINNING=11:00 /ENDING=12:00 -
_$ /NOCLUSTER
%EPC-I-SCHEDULE, Entry MY_COLLECTION scheduled for 14-APR-1997 11:00

You can use the DURATION qualifier in place of the ENDING qualifier. You must specify the duration as a relative OpenVMS time.

$ COLLECT SCHEDULE COLLECTION MY_COLLECTION MY_DATA.DAT -
_$ /SELECTION=SELECT_ALL -
_$ /BEGINNING=11:00 /DURATION="+1::" -
_$ /NOCLUSTER
%EPC-I-SCHEDULE, Entry MY_COLLECTION scheduled for 14-APR-1997 11:00

Before Oracle Trace software can generate a report on the data collected for your collections, you must use the FORMAT command to format the data in the data files into an Oracle Rdb ™ database.?

$ COLLECT FORMAT MY_DATA.DAT FORMATTED_DATA.RDB

You can also use the FORMAT command to combine the data files from two or more collections into one formatted database. However, these collections must have been scheduled by using the same facility selection.

There are two ways to combine data files: you can format several data files at once into the same Oracle Rdb database, or you can add a data file to an existing formatted database.

$ 


COLLECT FORMAT MONDAY.DAT,TUESDAY.DAT,WEDNESDAY.DAT  WEEK.RDB

$ COLLECT FORMAT /MERGE THURSDAY.DAT WEEK.RDB

Oracle Trace software can generate tabular reports based on the data in an Oracle Rdb formatted database.

In the simplest case, the REPORT command creates a summary report on all the data in the formatted database and displays the report on your current SYS$OUTPUT device (usually your terminal).

$ COLLECT REPORT FORMATTED_DATA.RDB

You can further refine the report with the FACILITY qualifier.

$ COLLECT REPORT FORMATTED_DATA.RDB /FACILITY=FORMS - 
_$ /OUTPUT=MY_REPORT.TXT

You use the STATISTICS qualifier to specify the statistics for the Oracle Trace software to use in the summary report. This feature allows you to create customized reports that present the information in the manner most suitable to your needs.

$ COLLECT REPORT FORMATTED_DATA.RDB /FACILITY=FORMS -
_$ /TYPE=SUMMARY /STATISTICS=(MAXIMUM,MINIMUM,MEAN) -
_$ /OUTPUT=MY_SUMMARY.TXT

By default, Oracle Trace software reports on the data collected for all the events contained in the formatted database. You can use the EVENTS qualifier to restrict the report to specific events.

$ COLLECT REPORT FORMATTED_DATA /OUTPUT=MY_REPORT.TXT -
_$ /FACILITY=FORMS -
_$ /EVENTS=(EVENT_1,EVENT_2,EVENT_3)

The BEFORE, INTERVAL, RESTRICTIONS, OPTIONS, and SINCE qualifiers provide additional customization features. For a full description of Oracle Trace reporting, see the Oracle Trace User's Guide.

To initialize any request other than the ENABLE request, the Form Manager performs the following steps:

Step 1: Validating the Argument List

Step 2: Validating the Session-Identification Argument

Once the Form Manager has determined that the argument list is valid, it validates the session-identification argument. The Form Manager maintains a list of active sessions. To validate the session-identification argument, the Form Manager compares the value in that argument to the list of active sessions.

If the value in the session-identification argument matches an active session, the argument is valid. The Form Manager uses the form and display device that are associated with the value of the session-identification argument for subsequent operations during this request.

If the session-identification string does not match an active session, the Form Manager terminates the request and returns an error message to your application program.

Step 3: Validating Record Names

After validating the session-identification argument, the Form Manager validates any record name (either send or receive) argument in the request. (This validation is not done for the DISABLE or CANCEL requests because you cannot pass a record name argument in either request.)

When the Form Manager validates the record name, it compares the value passed in that argument to the names of records stored in the form. The record name can specify either a single record name, or a list of records.

The record name argument must contain a character string that is the same as a form record name or record list name. For example, if you pass the string RECORD_ONE in the record name argument, there must be a form record or form record list named RECORD_ONE. (The Form Manager ignores case for form record names, so RECORD_ONE is equivalent to record_one.)

When the Form Manager finds a form record or record list that has the same name as the string passed in the record name argument, it validates the length of the data that is to be passed.

The Form Manager determines the length of that data by looking at the record that you pass in the request call. The Form Manager compares the length specified by the record message argument to the length of the form record in the form specified by the record name. If the length in the record and the length of the form record match, the record length is valid.

If the record name specifies a list, validation is performed the same way that it is performed for a single record for each record in the list. For example, if RECORD_ONE specifies a record list that contained 25 records, validation is performed 25 times, once for each record.

Step 4: Validating Control-Text Arguments

Receive control text provides information on the status of a request to the application. The Form Manager passes receive control text to the application and the application passes send control text to the form. A control-text argument can be either receive control text or send control text, specified as a receive-control-text or send-control-text argument in all request types except CANCEL.

The Form Manager tests the send-control-text-count for read access and the receive control text for write access.

The Form Manager validates any control-text arguments during the validation of the argument list. Send control text passes the names of control text responses to the Form Manager. If you pass a control-text argument, either send or receive, you must also pass a control-text-count argument.

If the value in the send-control-text-count argument is greater than zero and less than or equal to the number of control text items in the send control text, the argument is valid. For example, if the count is 2, and there are 14 characters in the control text, the argument is valid (2 x 5 = 10 and 10 < 14). If the count is 3 and there are 14 characters in the control text, the argument is not valid.

If the send control text is invalid, the Form Manager terminates request processing and returns an error message to the application program.

The Form Manager ignores those control text items not present in the form.

Step 5: Validating Parent-Request-Ids

To validate a parent-request-id, the Form Manager first verifies that the parent-request-id matches the identification of an existing request.

The Form Manager then verifies that the parent request awaits completion of a procedural escape routine.

Step 6: Validating Request Options

To validate the request options specified by a request call, the Form Manager matches the specified request options to the request. If the request specifies an option that is invalid for that request, validation of the option fails and the Form Manager returns an error message and returns to the application program. The Form Manager also tests read and write access of the request options.

For more information on request options, see Chapter 5, Using the OpenVMS API.

Step 7: Validating Shadow Records

Shadow records provide a means of tracking information concerning record fields. There are two kinds of shadow records: send shadow records and receive shadow records.

A send shadow record is sent from the application program to the form. The send shadow record contains an indicator that specifies whether the record fields in the associated send record should change the last known values of associated form data items.

You pass the send shadow record to DECforms by specifying the optional send-shadow-record argument on the SEND and TRANSCEIVE request calls.

A receive shadow record, which is a record returned to the application program, contains information about a record and each record field in the associated receive record. The information specifies whether the record fields in the associated receive record have changed value from the values last known to the program. A receive shadow record contains one character for each record field in the receive record plus one additional character that specifies the modified status of the record.

You pass the receive shadow record to DECforms by specifying the optional receive-shadow-record parameter on the RECEIVE and TRANSCEIVE requests.

You cannot specify shadow records for a CANCEL or DISABLE request.

To initialize the ENABLE request, the Form Manager performs the following steps:

Step 1: Validating the Argument List

Step 2: Creating the Session

To create a session, the Form Manager creates a unique, 16-character session-identification string. The session-identification string relates the display device that was attached and the form that was loaded into memory to each other. If the session-identification parameter is not 16 characters long, the Form Manager returns an error message and terminates request processing. (In the portable API, the 16-character string Forms_Session_Id is defined in the header file.)

Step 3: Loading the Form

Once the Form Manager has validated the argument list in an ENABLE request call, it locates the form and loads it. The Form Manager loads the form based on the parameters specified in the ENABLE request.

If the Form Manager cannot find the form specified in the request call, it terminates request processing and returns an error to your application program.

The Form Manager refrains from loading a form file from disk if the file has been loaded by another session for this process. Rather than reloading the form, the Form Manager uses the current memory-resident version of the form for the session to reduce the overall memory requirements for the process.

If no loaded memory-resident form meets all three conditions, the Form Manager reads and loads the form file from disk. The Form Manager deletes a memory-resident form file when no sessions reference it. This form load strategy is especially useful in the ACMS environment and in any environment where multiple instances of the application are used.

Step 4: Selecting the Layout

After the Form Manager loads a form, it selects a layout. To be selected, a layout must meet display device, device type, display size, and natural language requirements.

If the device name indicates a VT-class terminal, then the Form Manager attempts to select a matching VT or character-cell layout. A typical character-cell device name value is "SYS$INPUT".

If the device name indicates a disk file, then the Form Manager attempts to select a matching PRINTER layout. Valid PRINTER device name values are any legal file specification. An example would be "FORMS_OUTPUT.DOC".

To determine which layout in a form meets the display device requirement, the Form Manager first looks at the display device argument in the ENABLE request. In the display device argument, you pass the name of a display device. The Form Manager uses the information in this argument to retrieve information about the attributes of the display device; for example, whether the device is a VT300-series terminal, and if so, if it supports color.

In some cases, the operating system may not provide a way for DECforms to inquire about attributes of the display device. DECforms provides a way to specify default terminal settings.

To specify default terminal settings when you use the portable API, use the forms_c_opt_default_term and the forms_c_opt_default_color options. The fields for these options include:

• default_color_type
• default_term_type

Literals are defined in the API library files to simplify the assignment of these fields. The literals are in the format forms_c_dev_[xxx] and forms_c_color_[xxx]. The Form Manager uses the values you set as default values when it cannot determine the terminal type (or color support) from the operating system.

The layout must specify a display device type that matches the attributes that the Form Manager retrieves. If no layout specifies a display device type that matches the attributes of the physical display device, the Form Manager looks for the layout that most closely corresponds to the physical display device.

To determine whether a layout meets the display size requirement, the Form Manager compares the display size specified in the layout with the size of the physical display device. To meet the display size requirement, a layout must specify a display size that is valid for the physical display device. For information on valid display sizes for a particular display device, see the section on device declarations in the VSI DECforms IFDL Reference Manual.

To determine whether a layout meets the natural language requirement, the Form Manager checks if the FORMS$K_LANGUAGE item code or language_name option is specified. If you do not specify this item code or option, the Form Manager translates the FORMS$LANGUAGE logical name.

If the translation is successful, the layout is selected based on the value of this translation.

Alternatively, an application program can specify a language clause through the request options of an enable request. Specify item code FORMS$K_LANGUAGE in the OpenVMS API, and forms_c_opt_language in the portable API.

You cannot define FORMS$LANGUAGE to be a search list.

To meet the natural language requirement, a layout must specify the same natural language clause as is specified in the FORMS$K_LANGUAGE item code, the FORMS$LANGUAGE logical name, or FORMS_LANGUAGE variable. The character string specified in the layout must match either the character string to which FORMS$LANGUAGE or FORMS_LANGUAGE is defined or the FORMS$K_LANGUAGE item code; for example, if you defined FORMS$LANGUAGE to be “english”, the Form Manager would not select a layout that specifies “eng”.

When comparing the character string specified in a layout to the character string specified in FORMS$LANGUAGE or FORMS$K_LANGUAGE, the Form Manager ignores case.

The Form Manager searches for a layout by looking at all the layouts specified in the form. If no layouts match the language clause first, then the Form Manager scans the layouts that do not specify a language clause.

VT Device Layout Selection

The Form Manager selects the layout that specifies the closest compatible device to the device specified in the enable call.

The list of supported VT devices follows in order of compatibility:

For example, if the enable device is a VT300 terminal and the form contains layouts for both the VT100 and VT400 terminals, the Form Manager selects the VT100 terminal because it is more closely compatible to the VT300. The Form Manager does not select the VT400 terminal because the VT400 capabilities are not compatible with terminals below the enable device, in this case the VT300 terminal.

To have only one layout to service all terminals above and including a VT100, specify a VT100 as the enable device. This layout is not compatible with the VT100-No AVO terminal.

If more than one layout specifies the same device type, the Form Manager uses the vertical height (page size) of the enable device to resolve the conflict and selects the layout that specifies a vertical height closest to without exceeding that of the enable device.

If more than one layout specifies the same vertical height, the Form Manager uses the width of the layout to resolve the conflict.

If more than one layout equally satisfies all these criteria, the Form Manager selects the first such layout as defined in the IFDL.

PRINTER Layout Selection

When the Form Manager selects a PRINTER layout, it scans all %PRINTER layouts with a matching language clause for a SELECTION_LABEL match. If it finds no match, the Form Manager scans the set of %PRINTER layouts that do not specify a language clause for a SELECTION_LABEL match. If no match is found, the Form Manager chooses the first %PRINTER layout without a language clause in the form.

Step 5: Attaching the Display Device

Once the Form Manager has selected a layout, it attempts to attach the display device specified in the display device specification argument to the ENABLE request call. If the Form Manager cannot attach the specified display device, it terminates request processing and returns an error to your application program.

Step 6: Initializing Form Data Items

During the initialization of an ENABLE request, the Form Manager assigns initial values to all form data items, including built-in form data items. Built-in form data items are form data items to which only the Form Manager has write access.

If you declare built-in form data items in your IFDL source file, you can read values from them. You must declare built-in form data items to be CHARACTER or CHARACTER VARYING data types; you can specify any length for the data items and they can be character null-terminated.

If the value to be stored in any built-in form data items exceeds the length you declared for the form data item, the Form Manager truncates the value from the right.

If the value is shorter than the length you declared for the form data item and you declared the form data item to be the CHARACTER data type, the Form Manager pads the value on the right with spaces.

If you declared the built-in form data item to be CHARACTER VARYING, the length of the form data item becomes the length of the value, for as long as that value is stored in the item.

The Form Manager determines which application program record and form record are logically equivalent by looking at the record name argument passed in a SEND or TRANSCEIVE request call. The order of the descriptors specified in the request call must match the order of the records in the record name. The character string in this argument must name the form record or records (specified in a record list) that are logically equivalent to the application program record storing the values that you are passing in the request.

The correspondence between the application program record and the form record allows the form record to act as a table of contents to the application program record. The form record does not store the values passed in a request. The values are stored in form data items. Therefore, fields in the form record must, in turn, correspond to form data items.

When the Form Manager distributes form data, it moves the values from the application program record fields into form data items. If these form data items are displayed in panel fields, or used as panel object labels, or referenced in WHEN or FIRST clauses, the Form Manager also updates the values on the panel. (These form data items must have the same qualified names as their associated panel fields.)

If the form data items are not referenced in currently displayed panel fields, the Form Manager does not change the display.

More than one form record can be associated with each form.

Each form record consists of named record fields. A direct association is made between a record field and a form data item with the same qualified name. You associate the name of a record field with a form data item.

You can also define a panel field with the same name as the form data item to enable the operator to view the content of the record field. When no such panel field declaration exists, the application program sends and retrieves information that the operator cannot view.

You can override the default name association between record field and form data item by using the TRANSFER clause. This allows associations between form data and record fields other than by name. For more information on the TRANSFER clause, see the VSI DECforms IFDL Reference Manual.

You use the DATA TRANSFER clause to specify that the name of a record field in a form record should be treated as if it had a different name (which must be the same as a form data item). The DATA TRANSFER clause acts as a bridge between convenient names for record fields and convenient names for form data items.

The SOURCE clause declares that the value of the record field is to be set from a form data item when the application program requests the given form record. The form data item can then broadcast its value to several record fields in the same form record.

The DESTINATION clause can specify that the record field value is to be copied to one or more form data items when the record is sent from the application program to the form, broadcasting its value to several form data items.

A record can have SOURCE and DESTINATION clauses pointing to different form data items to achieve special effects.

You can also use the DATA TRANSFER clause to move data and record field arrays. For more information on the DATA TRANSFER clause, see the VSI DECforms IFDL Reference Manual.

In addition to the data contained within a form record, you can optionally have applications pass additional information that is associated with and describes special attributes of the record fields of the form record. The information is passed in a shadow record whose structure is directly related to the form record.

The special information is of two varieties, depending on the direction of the data transfer. Information about the modified status of the record fields can be returned to the application in a receive record, and the application can supply information as to whether last known values for modified field information should be updated.

Modified Fields

The Form Manager tracks the modified status of form data and returns this data to the application program if the program requests it in a shadow record. You might find this data useful in deciding whether certain actions must take place based on the data returned from the form.

Because keeping track of the modified status of form data will probably degrade performance, and because you may not need to know the modified status of all form data, you can track form data items individually, or track all the form data items in a data group, or all form data items in a form. The Form Manager saves the last known values of tracked form data items only.

Tracked data is associated with form data, which is directly connected to the record fields that are sent from and received into the program. The meaning of modified data depends upon the last known value of a form data item. The program expects a certain value for a form data item: the program knows what it has sent out to the form or what it received back from the form in a previous request. If the value being returned to the program in a receive record differs from this last known value, the value is marked as modified.

Modified data is maintained between requests. The program can send out a record field in a send request and ask for that record field back in a receive request later (perhaps several requests later).

If the value of the form data item that is associated with that record field returned has changed because of form activity (operator input, form procedural statements), the returned data states that the record field has changed.

If the value changed more than once, but the record retains its original value, the program receives data that the record field has not changed, because the value is associated with the last known value of the associated form data item.

Send Shadow Record

A send shadow record is a record that is sent from the application program to the form. The send shadow record contains an indicator specifying whether the record fields in the associated send record should change the last known values of form data items that were changed by the send record and are being tracked.

The send shadow record is passed by specifying the optional send-shadow-record argument on the SEND and TRANSCEIVE request calls. In the OpenVMS API, the shadow record must be passed by descriptor. In the portable API, use the Forms_Record_Data structure to set up the send shadow record.

There is no send-shadow-record-length argument in the OpenVMS API. The length is specified in the shadow descriptor. In the portable API, use the length field in the structure Forms_Record_Data.

The send shadow record consists of a single character. The length of the send shadow record must be 1. If the character is N (either uppercase or lowercase), the last known values of tracked form data items are not set when the form data items receive data from their associated form record fields during data distribution. If the first character is anything but N, or if a send shadow record is not specified on a SEND or TRANSCEIVE call, the last known values of form data items are set.

If a form data item is not specified as tracked, there are no associated last known values to be updated.

If the data type of a program record field does not match the data type of its corresponding form data item, the Form Manager must convert the data in the program record field to the data type of the form data item. The Form Manager must also perform data conversion when a form data item is displayed in a panel field, and the form data item and panel field have the same qualified name during data distribution.

To distinguish the different conversion errors, set event logging or tracing and examine the output.

Figure 4.1, “Function of the Form Manager During Data Distribution” shows an exchange of information that might occur during a SEND request.

One of the arguments that you can pass in a request call is send control text. Send control text can be composed of up to five send control text items. Each send control text item names one control text response stored in the form.

Each send control text item has a fixed five-character length. If a send control text item name is less than five characters, you must pad it with spaces. The number of valid send control text items is passed in a send control text item count argument or request option.

If a send control text item matches the name of a control text response stored in the form, the Form Manager performs that control text response. If there is no match in the form, that control text item has no effect.

You can use control text responses to cause the Form Manager to perform actions immediately before it performs the response to the request you called. By passing a send control text item, you can directly perform a particular response. For example, you could define a send control text response that applies a highlight to a set of fields that are about to be activated for input from the operator.

Once the Form Manager completes any control text responses that you specify, it performs the response to the request. The Form Manager performs either a default response or a response you define.

If you want the Form Manager to perform actions other than those specified by the default response to an external request, you can declare an external response in your IFDL source file. Any response you declare overrides the default response.

For more information on defining responses, see the VSI DECforms IFDL Reference Manual.

Each response that you define consists of a set of one or more response steps. Each response step that you include in a response causes the Form Manager to perform a particular action. This section explains the processing that each response step causes the Form Manager to perform.

ACTIVATE Response Step

For more information about clauses you can specify with this response step to control what the Form Manager adds to the activation list, see the VSI DECforms IFDL Reference Manual.

If the Form Manager encounters the ACTIVATE response step during external response processing, it adds the necessary activation items to the bottom, or end, of the activation list. If the Form Manager encounters the ACTIVATE response step during the accept phase of processing, it inserts the necessary activation items in the activation list immediately following the current activation item.

The Form Manager does not add two activation items for the same panel field, panel field array element, or wait to the activation list; each panel field or panel can correspond to only one activation item. (This also holds true for icons.) However, the activation list can contain any number of unique activation items.

When the Form Manager activates whole panels or groups within panels, then panel fields and icons are added to the activation list in the order in which they are defined in the panel definition (not the order in which the fields and icons appear on the display device).

If all the panel fields are stored in a single panel, the Form Manager adds activation items in the order in which the panel fields are stored in the definition of that panel. If the panel fields appear on more than one panel, the Form Manager adds activation items for all the panel fields stored in the first panel in the form.

Then it adds activation items for all the panel fields stored in the second panel in the form, and so on, until all the necessary activation items have been added.

ACTIVATE FIELD CLIENT ON PANEL_ONE
         GROUP EMPLOYEE_INFO ON PANEL_TWO

Now suppose that CLIENT is a panel field on panel ONE and that EMPLOYEE_INFO is a panel group on panel TWO. The EMPLOYEE_INFO group contains panel fields named STATUS, ID_NUMBER, and PHONE (in that order).

CALL Response Step

The CALL response step uses copy-in, copy-back semantics for passing arguments. When you pass a form data item BY REFERENCE, you do not pass the address of the form data item itself: a copy of the form data item is created and that address is passed to the escape routine. This temporary data item is copied back to the form data item when the escape routine returns.

If the escape routine modifies an argument that corresponds to a form data item, the Form Manager modifies the form data item upon return to the Form Manager from the escape routine. When control returns from the escape routine, the Form Manager continues processing the request.

For more information on the call response step and form data items, see the VSI DECforms IFDL Reference Manual. For information on writing and calling escape routines, see Chapter 2, Developing the Application Program.

DEACTIVATE Response Step

For more information about the optional clauses you can specify with this response step, see the VSI DECforms IFDL Reference Manual.

If the activation item being removed is not the current activation item, it is immediately removed from the activation list.

If the activation item that is removed is the current activation item, the Form Manager completes the processing of that activation item by processing any field, group, or panel exit responses. Only after the applicable exit responses have been performed does the Form Manager remove the activation item from the activation list.

If the Form Manager does not find a specified activation item on the activation list, it ignores this item, but puts a message in the trace file (if tracing is turned on) and continues processing the response step.

DISPLAY Response Step

The DISPLAY response step causes the Form Manager to display the specified panels on the display device.

For PRINTER devices this response step causes the Form Manager to display the DDIF representation of a panel to the output DDIF document.

For the "%PRINTER" device on Microsoft Windows, this response step causes the Form Manager to spool a representation of the panel to the Microsoft Windows' default printer.

If you specify a viewport in the response step, the Form Manager displays the panel in that viewport.

If a panel has already been displayed, but becomes obscured or covered up, the DISPLAY response step redisplays the panel.

If you do not specify a viewport in the response step, the Form Manager uses the viewport specified in the panel definition.

If you did not specify a viewport in either the response step or the panel definition, the Form Manager displays the panel in the default viewport for the selected layout.

On PRINTER layouts, the DISPLAY response step with the IMMEDIATE clause specifies that the currently open DDIF file be closed after the panels are downloaded to the DDIF file. The IMMEDIATE clause with the DISPLAY response step has no meaning in character-cell layouts.

ENTER HELP Response Step

The ENTER HELP response step initiates help processing. The current location on the main activation list is saved, and the help activation list is created.

After the help activation list is created, accept phase processing restarts on that list. The HELP ACTIVE elementary condition is set to true. The values of the CURRENTITEMHELPED and CURRENTPANELHELPED built-in form data items are set to the names of the current activation item (if a field or icon) and its panel.

EXIT HELP Response Step

The EXIT HELP response step sets the HELP ACTIVE elementary condition to false and switches from the help activation list to the main activation list. It does not change the current position on the main activation list. If IMMEDIATE is specified, validation is not performed on the current HELP field.

The EXIT HELP response step causes the Form Manager to terminate accept phase processing for the help activation list. The Form Manager continues processing of the current activation item on the help activation list. When the current activation item passes validation, the Form Manager begins the termination check stage of accept processing.

Once the termination check is complete, accept phase processing for the help activation list finishes. The Form Manager resumes processing on the main activation list.

The IF Response Step

The IF/THEN/ELSE response step allows optional response steps to be performed based on the value of the conditional expression specified in the IF clause. When the condition is true, the Form Manager performs the response steps specified in the THEN clause. When the condition is false, the Form Manager performs the response steps specified in the ELSE clause. When the condition is false and no ELSE clause exists, the response step has no effect.

For more information on conditional expressions, see the VSI DECforms IFDL Reference Manual.

INCLUDE Response Step

The INCLUDE response step names an internal response that is to be performed as part of the processing for the current response. The Form Manager invokes internal responses only when it encounters an INCLUDE response step.

Use internal responses to define response steps that are used in several places in the form. Defining internal responses to perform common processing functions can result in smaller forms and improved performance.

INVALID Response Step

When the Form Manager performs accept responses (entry, exit, function, and validation responses), the INVALID response step causes the validation for the current activation item to fail. This response step also negates any POSITION response step and causes the Form Manager to perform an implicit POSITION IMMEDIATE TO CURRENT response step.

If the Form Manager is not in the accept input phase of processing, it ignores the INVALID response step.

LET Response Step

The LET response step causes the Form Manager to assign a value to a form data item. The value assigned can be a literal, or the value of another form data item.

The operands that you specify must conform to the data type conversion rules specified in the VSI DECforms IFDL Reference Manual. If you specify an operand that does not conform to these rules, the Form Manager terminates the request and returns an error message to your application program.

MESSAGE Response Step

The MESSAGE response step causes the Form Manager to display a character string in the message panel. If the message panel is not displayed, the Form Manager performs an implicit DISPLAY PANEL response step before it displays the character string in the message panel.

The Form Manager supports a single message panel for each layout in a form. This message panel has no panel fields or literals defined. The panel's width and height are the width and height of its associated viewport. It is used by the Form Manager to display information from MESSAGE and MESSAGE HELP response steps and from operator entry errors.

The Form Manager creates a default message panel in a default message viewport at form load time if none is defined for the selected layout. For character-cell layouts, the default viewport for the message panel is the width of the layout. The height is one line.

PRINTER layouts do not support message panels, therefore no default message panel is created.

The Form Manager treats the message panel like a scrolled region. The message panel is divided into lines and columns based on the size of the message panel and the size of the font assigned for that message panel.

Each message character string is written to the bottom of the message panel in a left-to-right direction on the bottom line of the panel and in a right-to-left direction in Hebrew layouts.

On character-cell devices, if the message character string is longer than the width of the panel, the string is word-wrapped to the next line. The current line in the message panel is scrolled up one line. The remaining characters in the message string are then written to the message panel using word-wrapping.

These characters are displayed, not interpreted, as control characters in this environment. If no boundary characters are found in the string, the string is broken at the length boundary of the line. The remaining characters, including the boundary character, are displayed on the next line using the previously discussed rules.

Word-wrapping of messages is supported only in character-cell layouts.

New messages are displayed at the left margin of the bottom line. Messages are displayed at the right margin in Hebrew layouts. If the bottom line is not blank, the contents of the message panel are shifted up as previously described.

$ HELP FORMS ERRORS message-ident

$ HELP FORMS ERRORS NO_UP_ITEM

POSITION Response Step

The POSITION response step designates which item in the activation list the Form Manager will process after completing the current activation item. Neither the activation list nor the current activation item is modified by this response step; only the designation of the next activation item is modified.

If the Form Manager cannot find an activation item that meets the requirements of a POSITION response step, it does nothing. The Form Manager does not return an error message. For example, if you specify POSITION TO FIRST_FIELD and FIRST_FIELD does not correspond to any activation item, the Form Manager does nothing. If tracing is enabled, the Form Manager puts a message in the trace file stating that it cannot find the specified activation item.

If you are specifying a relative POSITION response step, and there is no active item, the Form Manager ignores the POSITION response step and puts a message in the trace file. This result commonly occurs if you specify relative POSITION response steps inside an external request response before the accept phase begins.

IMMEDIATE specifies that the Form Manager not complete the current item's validation response for the current activation item before moving to the specified activation item. However, the Form Manager does complete the processing of the response that contains the POSITION IMMEDIATE response step and any exit responses for the current activation item. You can use the IMMEDIATE clause with any other POSITION response step clause.

For more information about the optional clauses you can specify with this response step, see the VSI DECforms IFDL Reference Manual.

If you specify a POSITION response step followed by another POSITION or POSITION IMMEDIATE response step, the latter response step overrides the former. When you specify the POSITION IMMEDIATE response step, subsequent POSITION response steps are ignored: the POSITION response step can be overridden by subsequent POSITION and POSITION IMMEDIATE response steps, but the POSITION IMMEDIATE response step can be overridden only by subsequent POSITION IMMEDIATE response steps.

PRINT Response Step

The PRINT response step causes the Form Manager to print the display contents of the specified panels. If no panels are specified in the response step, all panels displayed by the current session are printed. Each PRINT response step causes a separate page to be printed. Panel fields and all form literals are sent as part of the panels. If a panel name is specified, the specified panel or panels are downloaded to a file for printing.

The PRINT response step with the IMMEDIATE clause specifies that the currently open output file be closed after the panels are downloaded to the print file. The file specification of the print file is specified by the FORMS$PRINT_FILE logical name or the FORMS$K_PRINTFILE item code in the OpenVMS API and forms_c_opt_print option in the portable API. (For more information, see Chapter 5, Using the OpenVMS API and Chapter 6, Using the Portable API.) This response step is valid only in character-cell layouts. To print panels in PRINTER layouts, use the DISPLAY clause.

In Microsoft Windows, the PRINT Response step causes the Form Manager to print the display contents of the specified panels to the current default printer, using the characteristics most recently selected during the Printer Setup or from the application's system menu. You can use the Printers function of the Microsoft Windows Control Panel application to select a default printer and set up printer characteristics, such as page size and orientation.

For more information on configuring printers and using the Control Panel to change printer configurations, refer to the appropriate Microsoft Windows documentation.

The PRINT response step is independent of the application program; this response step allows the form to print a panel directly without interacting with the application program. For an example of printing the current panel, see the VSI DECforms Guide to Developing an Application.

REFRESH Response Step

The REFRESH response step specifies that a designated viewport or viewports on the display be repainted.

You can specify two options for the REFRESH response step. ALL designates that all viewports for the current layout be refreshed on the display, and Viewport-name designates that the specified viewport or viewports be refreshed on the display.

If you do not specify one of the preceding options, the Form Manager designates that the contents of the default viewport for this layout are to be refreshed.

REMOVE Response Step

The REMOVE response step causes the Form Manager to delete the specified viewports from the display. This removes the contents of panels displayed on the viewport.

If you do not specify one of the preceding options, the Form Manager deletes the default viewport for this layout. If your layout is a framed layout, the Form Manager deletes the Frame viewport.

RESET Response Step

The RESET response step causes the Form Manager to set the values of the specified form data items to their initial values. The initial value of a form data item is the value specified in the FORM DATA declaration: spaces if the form data item is a character data type, or zeros if the form data item is a numeric data type.

You can specify that a particular form data item, a group of form data items, or all form data items be reset. If any of the form data items that the Form Manager modifies correspond to currently displayed panel fields, the Form Manager also updates the display.

RETURN Response Step

The RETURN response step causes the Form Manager to terminate accept phase processing. The Form Manager continues processing the current activation item as normal. If the current activation item fails validation, the Form Manager begins the operator input stage of accept processing again.

When the item is validated, the Form Manager begins the termination check stage of accept phase processing. Once the termination check stage finishes, the Form Manager completes processing of the accept phase.

If you specify the IMMEDIATE clause with the RETURN response step, the Form Manager terminates the accept phase without performing validation at the field, icon, group, or request levels. It does not perform any remaining entry responses for the current activation item. However, the Form Manager does perform exit responses at the field, icon, group, and panel levels.

You can specify a receive control text item with the RETURN response step that will be returned to your application program as part of the receive control message. Section 4.7, “Request Termination Phase” describes the format of receive control text messages.

If you specify a RETURN response step followed by another RETURN or RETURN IMMEDIATE response step, the latter response step is performed. However, when you specify the RETURN IMMEDIATE response step, all subsequent RETURN or RETURN IMMEDIATE response steps are ignored: the RETURN response step can be overridden by subsequent response steps, but the RETURN IMMEDIATE response step can never be overridden by subsequent response steps.

SIGNAL Response Step

The SIGNAL response step causes the Form Manager to send a signal to the display device. Depending on your display device and the type of signal specified, the SIGNAL response step causes the Form Manager to ring the terminal bell or put the screen into reverse video.

VALIDATE Response Step

The VALIDATE response step causes the Form Manager to validate the specified items on the activation list. If an item specified is not on the activation list, it is ignored.

If any named item is a grouping (array, group, panel), only those elements of the grouping on the activation list are validated. The validation response associated with the grouping is also executed. The validations performed are all declared validation clauses for the relevant items. VALIDATE response steps for those items are not executed.

The Form Manager performs the validation as if it had validated the item during the accept phase. If the Form Manager detects a validation failure or a POSITION IMMEDIATE at the end of a field validation or at the end of any validation response, it stops further validation. A response can determine that validation failed by determining that the elementary-condition IMMEDIATE is true.

The Form Manager ignores recursive validate steps. If the Form Manager encounters a validate step during the execution of another validate step, the Form Manager ignores the second validate step.

The Form Manager performs validation for activation items depending on their types. For fields, the Form Manager executes the field property validations and then zero or more validation responses. For icons, the Form Manager executes only the validation response for the object.

The Form Manager also executes one or more validation responses for each validation step. The Form Manager always executes an icon or field validation response for icons or fields.

If the validate step specifies an entire grouping of items, rather than a selection of items from a grouping, the Form Manager also a executes validation response for the grouping.

For more information about the VALIDATE response step, see the VSI DECforms IFDL Reference Manual.

If the Form Manager is processing a field or icon, it stores the name of the item for which input is needed in the CURRENTITEM and LOCATORITEM built-in form data items. It also sets the FIELDIMAGE built-in form data item for picture and text fields to the value that is displayed in the field.

If the Form Manager is processing a wait activation item, it stores the name of the panel to be displayed in the CURRENTITEM, LOCATORITEM, LOCATORPANEL, and CURRENTPANEL built-in form data items and sets the FIELDIMAGE and FUNCTIONNAME built-in form data items to spaces. If the Form Manager is processing a wait activation item that is not associated with a panel, it sets the CURRENTITEM, LOCATORITEM, LOCATORPANEL, and CURRENTPANEL built-in form data items to spaces.

If the current activation item is a panel, field or icon on a panel, the Form Manager looks for a panel entry response for that panel.

If you do not declare a panel entry response, the Form Manager skips this stage of activation item processing.

If you do not declare a group entry response, or if the current activation item is not in a group, the Form Manager skips this stage of activation item processing.

Fields, and icons can be nested within up to two levels of groups. When processing group entry responses, the Form Manager executes entry responses for each group that is being entered relative to the previous activation item. The order of execution of entry responses is from outermost group to innermost group.

If the current activation item is a panel field for which you declared an entry response, the Form Manager performs that response immediately before soliciting input from the operator.

If you do not declare an entry response for the field or icon, the Form Manager skips this stage of activation item processing. If you are performing input on the same item as the previous item (as is the case if validation fails), the Form Manager also skips this stage of activation item processing.

During the operator input stage, the Form Manager accepts operator input to satisfy the activation item.

If the Form Manager is processing a field activation item, the operator can enter data in the panel field and issue functions to satisfy the activation item. As the operator enters data, the Form Manager validates the data.

On character-cell devices, the Form Manager interprets picture strings and the editing clause for numeric data items as the operator enters data. If the user enters a character that does not match that specified by the picture string, the Form Manager outputs a message to the message panel indicating an error. The Form Manager then continues to accept input data.

After operator input, the FIELDIMAGE built-in form data item is modified to reflect the operator input.

When the operator enters a function to complete entry into the panel field or icon that is the field activation item, the Form Manager stores the name of the function in the FUNCTIONNAME built-in form data item.

The Form Manager does not change the values in the FIELDIMAGE built-in form data item when it is processing a wait or an icon.

Any error messages generated by data or functions that the operator enters are displayed in the message panel on the display device; these errors do not terminate request processing.

For information about editing functions, see the VSI DECforms IFDL Reference Manual.

If the activation item being processed is a field activation item, the Form Manager attempts to convert the field's value displayed in the panel field to the data type of its corresponding form data item.

If the conversion is unsuccessful, the Form Manager displays a message on the message panel. The operator input stage begins again unless the IMMEDIATE clause has been specified with a RETURN or POSITION response step.

If the current activation item is not a field activation item, the Form Manager skips this stage of activation item processing.

During the function response stage, the Form Manager performs the default response steps specified for the function the operator entered. You can specify actions other than this by defining a special function response. The VSI DECforms IFDL Reference Manual describes special function responses.

During the field validation stage, the Form Manager performs any validation that you specified for the item in the item declaration of your IFDL source file. For example, you may have specified that the Form Manager checks that the picture field is of a specified minimum length, that the data and function entry meet the requirements of the panel field, and so on. If any validation clause fails, the Form Manager displays a message on the message panel and performs an implicit INVALID response step.

If the current activation item is not a field or icon activation item, the Form Manager skips this stage of activation item processing.

During the field validation response stage, the Form Manager performs any validation response that you declared for the field. In a validation response, you can specify validation beyond that specified in the field declaration. If the Form Manager encounters an INVALID response step when it is processing a validation response, it does not perform any further validation responses. However, it does process any exit responses for the field.

If the Form Manager does not encounter an INVALID response step while processing this stage, it assumes that the item is valid.

If you did not declare a validation response, if the current activation item is not a field or icon activation item, or if the next activation item is the same as the current activation item, the Form Manager skips this stage of activation item processing.

The Form Manager performs the exit response even if it is processing a POSITION IMMEDIATE or RETURN IMMEDIATE response step.

If the Form Manager is not processing a field or icon activation item, or if you did not declare an exit response for the item, the Form Manager skips this stage of activation item processing.

If the Form Manager encounters an INVALID response step when it is processing a group validation response, it does not perform any further validation responses. However, it does process any exit responses that you declared for the item.

If the Form Manager does not encounter an INVALID response step while processing this stage, it assumes that the group is valid.

If you did not declare a group validation response or if the current activation item is not in a group, the Form Manager skips this stage of activation item processing.

The Form Manager performs the group exit response even if it is processing a POSITION IMMEDIATE or RETURN IMMEDIATE response step.

For nested groups, group validation and group exit responses execute in turn, inner group first, then outer group, for each level of nested group being exited.

If you did not declare a group exit response or if the Form Manager is not processing an item in a group, the Form Manager skips this stage of activation item processing.

If the Form Manager encounters an INVALID response step when it is processing a panel validation response, it does not perform any further validation responses. However, it does process any exit responses that you declared for the item.

If the Form Manager does not encounter an INVALID response step while processing this stage, it assumes that the panel is valid.

If you did not declare a panel validation response or if the current activation item is not in a panel, the Form Manager skips this stage of activation item processing.

After interpreting the response, the Form Manager goes to the next activation item.

The Form Manager performs the panel exit response even if it is processing a POSITION IMMEDIATE or RETURN IMMEDIATE response step.

If you did not declare a panel exit response, the Form Manager skips this stage of activation item processing.

During the termination check stage, the Form Manager validates each item on the activation list. This process includes performing field validation clauses, and performing validation responses for fields, icons, groups, and panels. Validation clauses and validation responses can be performed multiple times for each item on the activation list, because each item can be validated while it is active and when the accept phase is terminated.

During this stage, the Form Manager also performs any validation response that you defined in the REQUEST VALIDATION external response. If the activation list is empty, no validation checks are performed.

If any validation check fails, the request termination is canceled and the accept phase continues with the next activation item.

If all validation checks succeed, the Form Manager resets the contents of the CURRENTITEM, FUNCTIONNAME, and FIELDIMAGE built-in form data items to spaces and terminates the accept phase.

Usually, the Form Manager processes activation items as indicated by POSITION response steps. However, some conditions can cause this general order of activation item processing to be modified.

DECforms software provides you with two ways to provide help for your users. Both ways use response steps and the activation list. The first, and simpler way of specifying help, is to use the DECforms defaults. The second method is to use customized help.

If you use the DECforms defaults, you can specify two levels of help by declaring help messages and help panels in your form that the Form Manager displays at specified times during form processing. These declarations do not apply to PRINTER layouts.

You can declare help messages on panels, fields, groups, icons, and layouts within your form by using the USE HELP message clause. When you declare a USE HELP message clause within your form, the clause that you specify is displayed in the message panel when a MESSAGE HELP response step is executed.

By default, a MESSAGE HELP response step is executed when the user presses the function key defined as the Help key. (Different keys can be specified as Help keys. Depending on which terminal you have, DECforms software provides a default key as the Help key. For more information, see the appendix section of the VSI DECforms IFDL Reference Manual.)

The help message is the first level of help. You can also specify a help panel for a form element, which gives the user another level of assistance after the help message has been displayed. You specify a help panel on a form element by declaring the USE HELP PANEL clause within a field, group, icon, layout, or panel declaration, and by declaring a help panel.

In a HELP PANEL declaration, you can specify the viewport in which the help panel is to be displayed, the display attributes for the help panel, and the responses that occur when functions are invoked. You can also specify a help message for the help panel. You cannot specify a USE HELP PANEL clause within a HELP PANEL declaration. For more information on how to declare a help panel, see the VSI DECforms IFDL Reference Manual

Field DATA_TYPE                                           
    Line 4
    Column 18
    Output Picture X(50)
    Use Help Message                                      
        "Enter the VAX data type for the field's data" - 
        " item.  Press HELP for a list of valid data " -
        " types or SELECT to choose from a list."
    Use Help Panel                                        
        CREATE_FIELD_HELP_DT_PANEL
End Field
.
.
.
Help Panel CREATE_FIELD_HELP_DT_PANEL                    
    Viewport HELP_VP                                     
    Display
        %Keypad_Application
    Entry Response                                       
        Activate                                         
            Panel CREATE_FIELD_HELP_PANEL                
            Panel CREATE_FIELD_HELP_PIC_PANEL            
            Panel FUNCTION_KEY_HELP_PANEL                
        Position To Icon DISMISS_ICON On                 
            CREATE_FIELD_HELP_DT_PANEL
    End Response

When the Form Manager collects form data, it moves the values from the form data items into the application program record fields. During data collection, any record field or record field array element that does not receive data from a form data item or form data array element is set to a default.

Record fields and form record field array elements that are defined to contain alphanumeric data are set to spaces by default during data collection.

If the data type of a form data item does not match the data type of its corresponding program record field, the Form Manager must convert the data in the form data item to the data type of the program record field.

If the Form Manager cannot do this, it terminates request processing and returns an error to your application program.

Use the TRANSFER clause to specify that the name of a form data item should be treated as if it had a different name (which must be the same as a record field in a form record). The TRANSFER clause acts as a bridge between convenient names for record fields and convenient names for form data items.

The TRANSFER clause has other special uses. The SOURCE clause declares that the value of the record field is to be set from a form data item when the application program requests the given form record. The form data item can then broadcast its value to several record fields in the same form record. A record can have SOURCE and DESTINATION clauses pointing to different form data items to achieve special effects.

You can also use the TRANSFER clause to move data and record field arrays. For more information on the TRANSFER clause, see the VSI DECforms IFDL Reference Manual.

In addition to the data contained within a form record, applications can optionally pass additional information that is associated with and describes special attributes of the record fields of the form record. When this information is used, it is passed in a shadow record whose structure is directly related to the form record.

The special information is of two varieties, depending on the direction of the data transfer. The application can get information about the modified status of the record fields returned in a receive record and it can supply information as to whether the last known values for modified field information should be updated.

Modified Fields

The Form Manager tracks the modified status of form data and returns this data to the application program if the program requests it in a shadow record. The application program may find this data useful in deciding whether certain actions must take place based on the data returned from the form.

Because keeping track of the modified status of form data might degrade performance in most implementations, and because you may not need to know the modified status of all form data, you can track form data items individually, or track all the form data items in a data group, or track all the form data items in a form. The Form Manager saves the last known values of tracked form data items only.

Modified data is associated with form data, which is directly connected to the record fields that are sent from and received into the program. What modified data means depends upon the last known value of a form data item. The program has an expectation of the value of a form data item: the program knows what it has sent out to the form or what it received back from the form in a previous request. If the value being returned to the program in a receive record is different from this last known value, the value is marked as modified.

Modified data is maintained between requests. The program can send out a record field in a send request and later ask for that record field back in a receive request (perhaps several requests later). If the value of the form data item that is associated with that record field returned has changed because of any form activity (operator input, form procedural statements, data transfer) the returned data states that the record field has changed. If the value changed, the program receives data that the record field has not changed, because it is associated with the last known value of the associated form data item.

You may wish to track modified data in your application. During form data collection, the receive shadow record can be used to track such data.

The receive shadow record consists entirely of characters, and its length is 1 plus the number of record fields that the form record contains. The first character of the shadow record specifies the modified status of the entire record. If any record field in the record has been modified, the first character indicates that the record has been modified; if no record field has been modified, the first character indicates that the record has not been modified.

After the first character, the shadow record contains a single character for every record field in the record being returned. The correspondence between the shadow record and the received record is by ordinal position of record fields in the received record and ordinal position of characters in the shadow record, with an offset of 1, because of the additional character at the start of the shadow record.

A character returned in the field part of a shadow record is either 0 (record field not modified), X (the form did not request that modified data be kept for the record field, so the Form Manager has no status to report), or 1 (record field modified). If all field characters are 0, the first character of the shadow record (status for the entire record) is 0. If all field characters are either 0 or X, the first character is X. If any field character is 1, the first character is 1.

    FORM DATA
        B CHARACTER(15) TRACKED
        C INTEGER  (1)  TRACKED
        D INTEGER  (2)  TRACKED
    END DATA

    FORM RECORD ELVIS
        B CHARACTER(15)
        C INTEGER  (1) 
        D INTEGER  (2) 
    END RECORD

    FORM DATA TRACKED
        A INTEGER(4)
        GROUP G1 OCCURS 5
            GROUP G2 OCCURS 3
                D INTEGER(2)
            END GROUP
        END GROUP
        B CHARACTER(15)
    END DATA

    FORM RECORD ELVIS2
        A INTEGER(4) IMPLICIT SIGN
        GROUP G1 OCCURS 5
            GROUP G2 OCCURS 3
                D INTEGER(2) 
            END GROUP
        END GROUP
        B CHARACTER(15)
    END RECORD

The record ELVIS2 has 49 data bytes. Its shadow record has 20 bytes: 1 for the entire record, 1 for A, 15 for the two-dimensional array G1.G2.D, 1 for B, and 2 for the sign character.

To see if record fields have been changed, a program can look at particular parts of a record by defining an appropriate shadow record structure in the program and asking the appropriate question on that structure.

    01 ELVIS2-SHADOW
       03 A             PIC X.
       03 G1            OCCURS 5.
          05 G2         OCCURS 3.
             07 D       PIC X.
       03 B             PIC X.

    IF D(3,2) OF ELVIS2-SHADOW = "1" THEN
        
change code for element D(3,2).

    IF G1(3) OF ELVIS2-SHADOW NOT = "000" THEN
        
change code for row 3.

For some requests, the program might not affect the last known value of form data, especially in a program that is an escape routine making recursive requests on the Form Manager. Values passed to and from the form by the escape routine can effect form data, which would cause the last known value to be updated. If you choose not to change the last known value in the OpenVMS API, the escape routine can run transparently to the main requester.

If no receive shadow record is supplied on a request, the Form Manager does not assume that the program knows about the change in a form data item's value; specifically, the Form Manager does not update the last known value in the form for the record fields in a receive record unless it also passes a receive shadow record.

Similarly, a request may specify, in the first character of a send shadow record, that it does not want the values in the receive record to update the last known values in the form. If an N (either uppercase or lowercase) is specified in the first byte of the shadow record, the Form Manager does not update the last known value; if any other character is specified in the first byte, the last known value is updated. Figure 4.2, “Function of the Form Manager During Data Collection” shows the exchange of information that can occur during a RECEIVE request.

When data transfer takes place during data distribution and data collection; and the record fields, or form data items, or both are arrays; the amount of data that is transferred depends on the dimensions of the record fields and form data items involved.