HP OpenVMS Systems Documentation

You refer to DECforms forms in two places in your application's definitions:

• The task group names all the forms that are used by the tasks in the task group. ACMS begins a session with a DECforms form when the form is first used by a task. The context of the form is kept until the session is ended, either when the user logs out or the application is stopped. This allows the form to keep information across exchange steps.
• The task definition contains the syntax in exchange steps that request information (with a SEND, RECEIVE or TRANSCEIVE call). The task definition uses the record identifier to name the form record specifying which data items are to be returned to ACMS or sent to the form. The task also specifies the workspaces in ACMS to which the data items are mapped.

The DECforms Forms Manager is a run-time system that provides the interface between the terminal and an ACMS application. The Forms Manager controls the appearance of the display, user input, and data transfer between the form and ACMS. When data is being used in the form, it is placed in form data items. The Forms Manager maps the data items to corresponding ACMS workspace fields through a structure definition called the form record.

8.3.2.1 Design Issues for DECforms and ACMS

Consider the following issues when you define DECforms forms:

• Associate related form data in the form records you define. Consider whether the form data items always need to be passed together between the form and ACMS. If you pass 10 items only once, and pass other data items 4 times during the execution of the application, it is probably more efficient to group the 10 data items in a record separate from the other data items.
• ACMS often needs to send messages separately from the form data. Therefore, to avoid moving data unnecessarily, separate the message field from other data-item fields. Do this by creating a separate form record that contains only the DECforms reserved record field MESSAGEPANEL.

  Note Design your form so that other panels do not overlay the message panel. If you do not, the message panel comes to the surface when a new message is displayed, obscuring the currently active panel. This frustrates the user.

• Because DECforms allows the form to perform interaction with the terminal, you can choose to put some of the application logic in the form on the front end rather than the in application on the back end.
• Use Procedural Escape Units (PEUs) sparingly and never perform data I/O in them. PEUs cause other terminal threads in the CP to stall.
• Do as much data validation as possible within the form. Verify as much data as possible before shipping it to the task.
• Determine if you want your form processing to be menu driven or data driven. For example, a menu-driven form processing might have a menu with Add, Modify, Delete, and Inquiry for customer data. For example, a data-driven form processing design might have a maintenance menu. If customer data exists, the form allows for deletion or modification. If no data exists, the form allows for the addition of a customer.
• Use text data type fields whenever possible.
  Data type conversion involves data movement; as, for example, when converting a longword record field to a text form field. DECforms must call in a routine to convert the data from one type to another. Because only text data types can be displayed on a form, the quickest and cheapest record fields to display are text data type fields. Consider the cost of data type conversion when designing the data for an application.
• Check field contents with DECforms validation.
  If you need to check on the contents of a field, do as much as you can with DECforms validation. If you use a step procedure to validate the field, you incur the cost of shifting the context of the task from exchange step to processing step, as well as the cost of passing workspaces from one to the other.
• Avoid shipping large workspaces back and forth in applications with distributed forms.
  Consider the size of a DECnet packet when you design the application. Design workspaces to be no larger than needed.

A DECforms form can contain one or more panels. You can invoke panels separately or together on the screen. The panel is, in effect, what the user considers a form. However, you can also design a DECforms interface to have one or more DECforms forms. In deciding how many forms to use in your application, consider:

• Run-time efficiency
  A single form is more efficient than multiple forms. When a user selects a task that uses a form, a form session is created the first time the form is used. There is a cost associated with the initialization of the form session. Also, once a form is invoked, the form session remains active until the user signs out of ACMS or the application is stopped.
• Debugging and maintenance
  A single large form can be more difficult to debug and maintain than several smaller forms.
• Business considerations
  You might want to separate the interface to independent parts of your business.
• Data context in the form
  If you use a single form, you can store information on a front-end system between task instances as form data in the form. While this can be an advantage in minimizing network use for providing information to the form, there is also a risk of data inconsistency when information is updated in the database.

The design issues listed above are in the context of choosing one form or multiple forms. Other design options are:

• Choosing binary form files or shareable image files
  ACMS allows the use of either binary form files (.FORM) or shareable image files (.EXE). The .EXE format reduces the amount of memory required in a multiuser environment since the form is loaded into memory only once --- the first time it is selected after the application is started. The same image file is accessed by all users and remains open until the application and the terminal subsystem are stopped.
  When the binary form file is used, the .FORM file is loaded into memory each time a user selects the form, so the form may take longer to display. However, the use of binary form files adds flexibility since newer versions of forms can be installed by stopping and restarting the application without having to stop the terminal subsystem, which would disconnect user sessions in other applications as well. The .FORM files are useful during development of forms for multiple ACMS applications on the same node.
• Creating one form file with multiple forms
  A DECforms shareable image (.EXE) can contain multiple forms. This allows the development of independent forms, but binds the ACMS agent process to only one file. However, each form is still individually initialized.

Compaq recommends the use of DECforms for use with ACMS. However, if you need to enhance an existing TDMS interface, follow these guidelines:

• Avoid using scrolled regions
  Rather than map each instance of a record field to a form field, TDMS allows you to map many instances of the record fields to a single form field. The terminal user can scroll through the display with the up and down arrow keys. This can be useful for programmer productivity, but it negatively affects performance. TDMS scrolled regions are costly in terms of the processing time required to map large arrays.
• Use text data type fields whenever possible
  Data type conversion involves data movement, for example, when converting a longword record field to a text form field. TDMS must call in a routine to convert the data from one type to another. Because only text data types can be displayed on a form, the quickest and cheapest record fields to display are text data type fields. Consider the cost of data type conversion when designing the data for an application.
• Check field contents with TDMS validation
  If you need to check on the contents of a field, do as much as you can with TDMS validation. If you use a step procedure to validate the field, you incur the cost of shifting the context of the task from exchange step to processing step, as well as the cost of passing workspaces from one to the other.
• Avoid shipping large workspaces back and forth in applications with distributed forms
  Consider the size of a DECnet packet when you design the application. Design workspaces to be no larger than needed.
• Avoid extensive video attributes

This section describes a TDMS run-time support feature that can improve response time for local users. This feature allows you to select whether TDMS run-time support for local users is provided by the Application Execution Controller (EXC) process or by a Command Process (CP).

The EXC handles task flow control for the application. For each ACMS application, there is only one EXC. All tasks in the application are handled by the EXC unique to that application.

The CP handles the user interface for an ACMS application. One or more CPs provide user interface support (menu displays and data presentation). ACMS allows you to have multiple CPs active at one time on a given system, so that you can tailor the resources allocated to the user interface activity according to the number of users and the complexity of the work.

TDMS run-time support by the EXC creates a problem if there are many local TDMS users, because the data presentation work for all of the users is carried out in the one EXC. Consequently the EXC becomes overburdened, and response times degrade.

The TDMS run-time support feature allows you to specify CPs to provide local TDMS run-time support, rather than the EXC providing it automatically. This allows you to accommodate for TDMS loads by adjusting the number of CPs available.

8.5.1 Specifying CPs for Local TDMS Run-Time Support

You control local TDMS run-time support by defining a logical name. For each ACMS application, you decide whether you want the EXC or the CPs to provide local TDMS run-time support. If you decide that the CPs should provide local support, define the system or group logical name ACMS$LOCAL_TDMS_IN_AGENT to equate to the characters T, t, Y, or y, or to an odd-numbered value.

The EXC continues to provide local TDMS run-time support under three conditions:

• The logical name ACMS$LOCAL_TDMS_IN_AGENT is undefined
• The logical name is equated to a character other than T, t, Y, or y
• The logical name is equated to an even numeric value or zero

The EXC process evaluates the logical name when the process is invoked. Therefore, you must define the logical name before starting the application.

You can define this logical name by two different methods:

• DCL-command method
• Application Definition Utility (ADU) clause method

The following sections illustrate both methods of defining the logical name for local TDMS run-time support. The DCL-command method defines the logical name systemwide; the ADU-clause method defines it for just one application.

8.5.2.1 DCL-Command Method

The following command causes the CPs to provide local TDMS run-time support for all applications subsequently started on the node. The Y in the command specifies local CP support.

$ DEFINE/SYSTEM/EXEC ACMS$LOCAL_TDMS_IN_AGENT  Y

The following command causes the EXC process to provide local TDMS run-time support for all applications subsequently started on the node. The zero in the command specifies local EXC support.

$ DEFINE/SYSTEM/EXEC ACMS$LOCAL_TDMS_IN_AGENT  0

Example 8-1 illustrates how the APPLICATION LOGICAL clause in the ADU application definition causes the CPs to provide local TDMS run-time support for the application defined by this definition. The 1 in the example is an odd numeric value that specifies local CP support.

APPLICATION LOGICAL IS "ACMS$LOCAL_TDMS_IN_AGENT" = "1";

APPLICATION USERNAME IS ...;
TASK GROUPS ARE
  .
  .
  .
END TASK GROUPS;
END DEFINITION;

The APPLICATION LOGICAL clause in the ADU application definition in Example 8-2 causes the EXC process to provide local TDMS run-time support for the application defined by this definition. The F in the example specifies local EXC support.

APPLICATION LOGICAL IS "ACMS$LOCAL_TDMS_IN_AGENT" = F;
APPLICATION USERNAME IS ...;
TASK GROUPS ARE
  .
  .
  .
END TASK GROUPS;
END DEFINITION;

Note that while the numeric value 1 in Example 8-1 requires quotation marks, the string F in Example 8-2 does not. This conforms to the ADU syntax rules. For information about ADU clause syntax, refer to the Compaq ACMS for OpenVMS ADU Reference Manual.

8.6 Using Request I/O and Stream I/O for Nonstandard Devices

Your application may require the use of another forms product or other devices that DECforms does not support. Use request I/O and the RI, or stream I/O, to handle situations such as:

• Providing access to ACMS from a badge reader, a bar-code reader, touch screens, or communications interfaces
• Writing a customized terminal I/O interface
• Providing distributed processing that is not already provided by ACMS (such as access to systems other than systems that support ACMS or the Compaq TP Desktop Connector products.)
• Developing a customized menu interface (an ACMS/ALL-IN-1 interface module, for example)

Section 8.6.1 describes the Request Interface and request I/O. Section 8.6.2 describes stream I/O.

8.6.1 Using Request I/O and the Request Interface

In most instances, you can use the RI to communicate with unsupported devices. The RI offers these advantages:

• An ACMS-supplied agent
  ACMS supplies a single-user agent that uses the RI. Alternatively, you can write your own single-user agent using the SI services. The RI agent supplied with ACMS, ACMS$RI_AGENT, uses the SI services to sign the user in to ACMS, enable the RI, and call tasks in an ACMS application.
• Task independence
  With the RI, for each exchange step, ACMS code in the agent process determines whether to call a TDMS request or a User-written Request Procedure (URP). In the task definition, the same syntax is used to describe the information to be processed on an exchange step, whether the agent uses TDMS requests or URPs. Therefore, an agent that is using TDMS requests, and an agent that has enabled the RI and is using URPs, can both call the same task definition. Thus, the task definition is independent of the presentation service being used by the agent.
  With the stream services, stream I/O syntax in the task definition describes the information to be processed on an exchange step. A task that uses stream I/O can only be called by an agent that can process the stream I/O requests from the task. Thus, you might have to write multiple task definitions for a single task that can be called from a terminal supported by TDMS or from other devices not supported by TDMS.
• Flexibility
  With the RI you can pass multiple workspaces in an exchange step. However, you can only pass one read and one write workspace in an exchange step that uses stream I/O.

Compaq ACMS for OpenVMS Writing Applications describes the details of RI use.

8.6.2 Using Stream I/O

Stream I/O has the following advantages over the RI:

• Asynchronous processing
  The RI provides only a synchronous interface. Therefore, you can write only single-user agents for use with the RI. Stream services offer both a synchronous and an asynchronous interface. Using the asynchronous interface, you can support multiple submitters in a single agent process. This saves resources if your system must support many non-standard devices. Using the RI, each device would require a separate agent process. Using the stream services, you can support many devices in a single process.
• Network usage
  With the RI, the data in the workspaces specified in each exchange step is sent from the application to the agent process at the start of the exchange step and is returned again at the end of the exchange step. This can cause unnecessary network traffic if the data only needs to be transferred one way. Using stream I/O, only the data in the write workspace is sent from the application to the agent and only the data in the read workspace is returned from the agent back to the application.