Figure 6-10 Remote Update Using Rdb Remote Server

The AVERTZ sample application maintains a history log database, in addition to the main database. Any customer or reservation information written to the main database must be written to the history log database as well, for auditing purposes. The AVERTZ application uses distributed transactions to ensure that both databases commit the same information.

Compaq ACMS for OpenVMS Writing Applications details the writing of distributed transactions in an ACMS task.

6.7 Handling Exceptions

ACMS raises an exception if it detects an error condition while a task is executing. You can use the exception handler component of the task definition language to control task execution after an exception is raised in a task. Use of exception handlers in tasks is optional. If you do not specify an action to take when an exception is raised, ACMS cancels the task. You use exception handler action clauses to direct the flow of the task after an exception is raised. For example, you can use an exception handler to retry a distributed transaction that times out.

The three types of exceptions are:

• Step exception
  You can handle a step exception in the:
  • Exception handler part of the step on which the exception occurs
  • Exception handler on an outer block step
• Transaction exception
  A transaction exception is an error that causes a distributed transaction to fail.
  You can handle a transaction exception in:
  • Exception handler part of the step that starts the transaction
  • Exception handler on an outer block step
• Nonrecoverable exception
  A nonrecoverable exception is an error from which the task cannot recover. When a nonrecoverable exception is raised, ACMS cancels the task.

See Compaq ACMS for OpenVMS Writing Applications for details about implementing exception handling.

This chapter provides guidelines for mapping your defined transactions to step procedure implementations. It helps you decide when and where a step procedure performs the desired operations, such as database recovery and validation.

7.1 Writing Server Procedures

Procedures for ACMS tasks that use RMS files, Rdb, and DBMS databases are similar in the following ways:

• Structuring the procedure as a subprogram or function
  The programming language used must be able to receive parameters and return status to a calling program. Structure your procedure as an externally callable subroutine.
• Assigning a unique name to each procedure in a server
  This name is an entry point into the procedure and must correspond to the procedure name defined in the task group and referred to in the task definitions.
• Opening files and binding databases in initialization procedures rather than in the step procedures
  An initialization procedure performs work specific to a server process.
• Using workspaces to pass information between the task definition and the procedure.
• Using CDD for record definitions and for workspace record definitions (for languages supporting CDD)

Compaq ACMS for OpenVMS Writing Server Procedures describes these programming considerations in detail.

7.2 Returning Status to the Task Definition

In most situations, a task needs to know whether or not the work done in a processing step is successful so that it can determine what to do next. The step procedure must pass a value back to the task. The value can be tested in the task, and the task can take an action based on the result of the test. A procedure returns a value to a task definition in one of the following ways:

• Using the return status facility provided for subprograms or functions in the language used
• Putting status information directly into a user-defined workspace that has been passed as a parameter to the procedure

User-defined workspaces are more flexible than the return status facility, but require additional memory. The return status facility uses the predefined ACMS$PROCESSING_STATUS workspace, but offers a limited set of values to pass.

The chapter on writing step procedures in Compaq ACMS for OpenVMS Writing Server Procedures describes ACMS$PROCESSING_STATUS in detail. ACMS$PROCESSING_STATUS is also used to return messages based on the result of a returned status.( See Section 7.3.)

7.3 Returning Messages to Users

You can return messages in several ways:

• Task retrieves the error message text from the message file
  Use the GET MESSAGE task syntax to translate a success or failure status from the procedure for a specific message in a message file. ACMS stores the return status in the ACMS$PROCESSING_STATUS workspace. Based on the return status, the task retrieves error message text from the message file, and places the message text in the message portion of the ACMS$PROCESSING_STATUS workspace.
  The task syntax minimizes coding needed for access to the messages. Also, by using message files you can change the message text without affecting the task definition or the step procedure code.
  However, you cannot use FAO arguments with this method. FAO arguments allow for arguments to messages. For example, with an FAO argument, the user receives a message saying "Order 2387 not found", rather than simply "Order not found". Process the message in the step procedure to use FAO arguments.
• Step procedure retrieves the message text from the message file
  Use OpenVMS system services or run-time library (RTL) routines to retrieve and process the error message text in the step procedure.
  Use this method if you want FAO arguments for your messages. You must use a user-defined workspace to pass the message, so you must do more coding than if you use GET MESSAGE to process the message in the task.
• Form receives a status indicator to be processed by the form in a user-defined workspace
  You can hard code messages in the DECforms form, and display the message based on an error indicator returned to the form. Use this method if you want to use the DECforms capability for user-specific language. However, hard-coded messages make maintenance more difficult.
• Step procedure contains literal error message
  You construct the complete error message using literal message text stored in the step procedure, formatting variable error messages if necessary. The advantage to this method is that you do not need to use message files or OpenVMS system services, or RTL routines to return error messages to users. The disadvantage is that you must always modify and recompile the step procedure and relink the procedure server image if you need to change the format of an error message.

Compaq ACMS for OpenVMS Writing Server Procedures describes the details of step procedure coding used to process messages by any of these methods. Compaq ACMS for OpenVMS Writing Applications describes the task syntax needed for processing messages.

7.4 Handling Errors

You typically write an error handler to process errors returned by a resource manager, such as Rdb, DBMS, or RMS, when starting and ending a database transaction or recovery unit, and when accessing data in a database or a file.

Some errors are expected, and are handled by resuming normal program execution. For example, a resource manager might return an error if a record does not exist in a file or a database. In this case, the procedure can return an error status to the task. In the action part of the processing step, the task retrieves the error message text associated with the error status and then transfers control to an exchange step to display the error message for the user. Alternatively, if the error condition is handled by an exception handler on the processing step or on an outer block step, the procedure can raise a step exception by calling the ACMS$RAISE_STEP_EXCEPTION service. The action clauses in the exception handler can then process the exception condition and resume execution elsewhere in the task.

Resource managers can also return a number of recoverable errors that a procedure should check for and handle. For example, resource managers return deadlock errors if the OpenVMS lock manager detects a deadlock condition between two or more processes. If the database transaction or recovery unit is participating in a distributed transaction, the procedure can raise a transaction exception by calling the ACMS$RAISE_TRANS_EXCEPTION service. After ACMS aborts the distributed transaction, an exception handler in the the task can automatically retry the transaction. Alternatively, if the database transaction or recovery unit is not participating in a distributed transaction, the error handler can roll back and retry the database transaction or recovery unit within the procedure.

Finally, resource managers can return a number of nonrecoverable errors. For example, suppose the failure of a disk on which a file or database storage area resides. The procedure server cannot continue until resolution of the problem. If a non-recoverable error is detected, a procedure can log the error in the ACMS audit log by signaling the error condition, and then cancel the task by raising a non-recoverable exception using the ACMS$RAISE_NONREC_EXCEPTION service.

Compaq ACMS for OpenVMS Writing Server Procedures describes the details of handling errors and raising exceptions in step procedures.

7.4.1 Avoiding Cancel Procedures

Avoid cancel procedures as much as possible. Traditionally, cancel procedures have been used to clean up procedure execution, to free nontransaction-based resources, and to rollback an active database transaction or recovery unit. Whenever possible, however, you should try to avoid designing and writing step procedures that require server cancel procedures to clean up server processes following an exception. Reasons for avoiding cancel procedures are:

• Adverse effect on application performance
  By calling a cancel procedure following an exception, ACMS must make an additional call to each server process to execute the server cancel procedure. If a server process does not need to be run down following an exception, there is a delay in the allocation of the server process to another task instance. If the server process is run down as a result of the exception, then calling the cancel procedure increases the time required to shut down and restart the server process, and could be better handled by the use of a termination procedure.
• Difficulty of writing cancel procedures
  Since an exception can be raised at any time while a task is executing, a server cancel procedure must be able to clean up a server process under all conditions. Writing a cancel procedure that performs all the necessary cleanup operations correctly is very difficult; it is easy to miss something that should be cleaned up. Besides, cancel procedures make your applications more complex and thus more difficult to maintain.

Use the following guidelines to design and write tasks and step procedures that avoid cancel procedures:

• Control recovery units with transaction steps in the task definition.
  Resource managers automatically roll back active recovery units participating in a distributed transaction if that transaction aborts. Therefore, you do not need to write a cancel procedure to do rollback if all recovery units participate in distributed transactions controlled by the task definition.
  Following an exception, ACMS will not run down a server process participating in a distributed transaction until the transaction has been rolled back. Therefore, a database recovery process will not be started if a server process is run down as the result of an exception being raised. See Compaq ACMS for OpenVMS Writing Server Procedures for details about situations in which cancel procedures are unavoidable.
• Allow server processes to run down following an exception.
  In most cases, if an exception requires ACMS to interrupt a step procedure while it is executing, allowing the server process to run down as part of the exception handling sequence has the advantage that OpenVMS will automatically perform most, if not all, of the necessary cleanup operations. For example, when a process is run down, OpenVMS automatically closes any channels that are still open. Also, any locks currently owned by the process are freed.
• If an exception requires the interruption of server process execution, avoid operations that require cleanup.
  For example, if you use task workspaces to store data rather than allocate memory using LIB$GET_VM, then you do not need to use a cancel procedure to free memory allocated in this way.
  However, some applications may require that a step procedure acquire a nondistributed-transaction-based resource. For example, a step procedure may need to acquire an OpenVMS lock using the $ENQ service before performing a critical operation. Using the $DEQ service, the step procedure releases the lock as soon as the operation has been completed.
  When an exception is raised, ACMS immediately interrupts a server process. If the code is interrupted during the time that the server process has acquired the lock, the server may not have the opportunity to call the $DEQ service. Since the server is using an OpenVMS lock mechanism, OpenVMS will automatically release the lock when the server process runs down. If the server is using an application-specific mechanism to maintain locks on resources, however, then running a server process down following an exception does not solve the problem; the resource will still be locked.

Compaq ACMS for OpenVMS Writing Server Procedures, describes how to prevent the interruption of a procedure server while it is executing, and the conditions under which a procedure is run down.

7.5 Performance Considerations

Use precompiled data manipulation language or SQL module language in step procedures for database access, if the language you are using supports them.

Using the DBQ$INTERPRET and RDB$INTERPRET services is discouraged, because these services must interpret and compile the DML statements at run time. This can be costly in CPU usage and response time.

If you need to update a local database and a remote database in a distributed transaction, you can increase performance by using the ACMS SI services to call a task to update the remote database. Writing the step procedure using the following guidelines allows you to update both databases simultaneously:

1. Call the ACMS$START_CALL service to start the remote task.
2. Update the local database while the remote task is updating the remote database.
3. Call the ACMS$WAIT_FOR_CALL_END service to wait for the remote task to complete.

One of the major advantages of implementing an application with ACMS is that you can easily separate your terminal I/O from your database I/O. You do this by performing terminal I/O in exchange steps and database I/O in processing steps. This design offers better performance and the ability to distribute tasks over multiple nodes.

However, sometimes terminal I/O is unavoidable in a processing step---for example, if you are incorporating an existing program into an application. In such cases, it may be simpler to make the existing program a single-step task that does terminal I/O than to convert the program to a multiple-step task, which requires removing the terminal I/O from the program and placing it in exchange steps. Compaq ACMS for OpenVMS Writing Server Procedures gives details about how to handle terminal I/O from a processing step.

This chapter provides guidelines for designing DECforms menus and forms. It also describes issues in the design of nonstandard ACMS user interfaces, such as customer-written interfaces created using the ACMS Systems Interface (SI) or Request Interface (RI).

8.1 Designing a User Interface

A good user interface is one that is consistent and easy to use. When choosing and designing a user interface:

• Keep the user in mind
  You must understand the users' vocabulary, what work they do, and how they do it. Talk with users, observe them, involve them in the design, and be a user yourself.
• Put the user in control
  Provide flexibility by providing multiple ways of having access to an application's functions. Use progressive disclosure, so that necessary and common functions are presented first. More sophisticated and less frequently used functions should be hidden from view, but must be easily accessible.
• Provide direct manipulation
  Make your application respond to input as rapidly as possible. Make the output of your application available as input.
• Keep your interface natural
  Design so that work flows naturally. Give each screen object a distinct appearance, but maintain a graphically uniform interface. Provide an easy navigation mechanism.

• Provide consistency
  When components work in a manner that is consistent with other components:
  • Users are less afraid to try new functions.
  • Similar components operate analogously and have similar uses.
  • Same action always has the same result.
  • Function and position of components does not change based on context.
  • Keyboard functions are standard across functions and tasks.
• Communicate application actions to the user
  Well designed forms let the users know what is happening:
  • Give users feedback whenever they have initiated an action.
  • Anticipate errors so that you can avoid them in your design, enable the support of recovery attempts, and provide appropriate help messages.
  • Require that the user take explicit action before altering or deleting data.
• Avoid common user interface design pitfalls
  The following guidelines can help you avoid common pitfalls:
  • Pay attention to details. For example, consistent capitalization of menu items and dialog box labels reduces textual distraction for users.
  • Allow for as much redesign as possible. The first design is not a solution but a fresh perspective from which to view interface design problems.
  • Design interactively. The development cycle of implementation, feedback, evaluation, and change avoids costly errors by allowing for early recognition and correction of problems.
  • Start with a fresh perspective. Avoid the temptation to convert an existing interface to a new one simply by translating it.
  • Hide implementation details. The interface design is driven by the user's work, not the underlying system.
  • Recognize conflicting guidelines. Two or more design guidelines often conflict with each other. Recognize these occurrences and carefully weigh all the factors when designing a solution.

ACMS provides great flexibility in collecting user input for processing in an application. You can use any combination of the following tools to capture data for use in an ACMS application:

• DECforms software
• TDMS software
• ACMS Request Interface
• ACMS Systems Interface
• Compaq TP Desktop Connector (formerly ACMS Desktop) provides access to ACMS systems from desktop systems running their native operating systems. (See the Compaq TP Desktop Connector for OpenVMS Programming and Management Guide.)

Compaq recommends the use of DECforms. ACMS support of DECforms is asynchronous, allowing for the most efficient use of resources. (See Section 8.3.1.) Figure 8-1 illustrates the use of various interfaces to ACMS.

Figure 8-1 Interfaces to ACMS

Submitter services select tasks and optionally send and receive data at the beginning and end of the task. Tasks interface with presentation services using the following exchange types:

• Forms I/O
  DECforms is the forms I/O presentation server. DECforms is the recommended tool for creating and controlling the user interface to an ACMS application. Section 8.3 describes design issues specific to DECforms.
• Request I/O
  TDMS is the default request I/O presentation server. You can also use the ACMS Request Interface (RI) to write your own request I/O presentation service. Section 8.4 describes design issues specific to TDMS. See Section 8.6.1 for a description of RI design issues.
• Stream I/O
  You can use stream I/O syntax to exchange information with ACMS agents, using the stream services in the ACMS Systems Interface (SI). Section 8.6.1 describes stream I/O design issues.

DECforms and TDMS limit you to collecting user input from DECforms-supported and TDMS-supported terminals. Compaq TP Desktop Connector (formerly ACMS Desktop) supports tasks written to use forms I/O or request I/O from desktop systems running their native operating systems. Request I/O and the RI provide the flexibility of choosing an interface from other I/O devices to ACMS without affecting the multiple-step task structure or the ease-of-maintenance features inherent in an ACMS application.

You can also perform terminal I/O from step procedures running in the processing steps of your task. However, because this method ties up a server process, it can result in loss of performance, and might require the Application Execution Controller (EXC) to start additional server processes. Also, you cannot use remote tasks if you include terminal I/O in a step procedure. See Chapter 7 for more information about I/O from step procedures.

8.3 Using DECforms

DECforms helps separate form from function. The form in which data is gathered and displayed to the user is completely separate from the function that the application must perform in processing the data.

8.3.1 DECforms Structure and Design

With DECforms, a form describes not only the fields and background text displayed on the screen, but also provides such features as:

• FIMS compliance
• Device-class independence
• Storage of form context between exchanges
• Procedural elements that control the user's interaction with the form
• Input verification (values, ranges, types, cross-field)
• Procedural escapes

A DECforms form consists of the following:

• Form
  Encompasses the panel, viewport, and layout to describe how to display, collect, and process information.
• Layout
  Describes the attributes and appearance of the entire form, including its default size and background color, the different types of display devices the form can be used on (for example VT100, VT200 or VT300), and different user languages (for example, French or English).
• Panel
  Physically displays the background information and field images on the display device.
• Viewport
  Defines the area of the screen where one or more panels are displayed. (Viewports can overlap each other.)

You can declare only one form in each source file, but you can declare multiple layouts, panels, and viewports within a form.

The main design issues for DECforms are:

• Screen design
• Controls
• Menus
• Dialog boxes
• Help
• Internationalization issues

See the DECforms documentation for detailed descriptions of these topics.