Bertram Simpson had a great weekend and is now ready to return the car to AVERTZ. He shows up at the reservations counter at AVERTZ on April 22. The following dialog takes place while Bertram Simpson checks in the car to end the rental period:

Figure 16-10 Checkin Panel

Figure 16-11 Checkin Update Panel

You have seen the AVERTZ application from the system manager's and user's points of view. This chapter takes a brief look at some of the work involved in designing and developing an ACMS application from the system designer's and application developer's views. The design and development details of AVERTZ are discussed extensively throughout the ACMS documentation set.

Before designing a transaction processing application, you must begin by analyzing the business problem. For AVERTZ, the business problem is how data entry personnel can quickly and efficiently create, access, and update car rental information.

Each business problem has separate business areas that must be addressed. For AVERTZ, business areas might include reservation processing, site management, car information, and customer accounts. The AVERTZ sample application focuses on the business area of reservation processing.

In turn, each business area consists of business functions that support the business area. There are three different business functions that support the reservation processing business area:

• Reserve a car
• Check out a car
• Check in a car

Once the business problem has been categorized into areas and then into functions, you can begin solving the business problem with ACMS.

17.1 Applications and Procedures

An ACMS application consists of a set of tasks that relate to the functions of a business and can be selected for processing by either a terminal user or another task. Figure 17-1 shows the basic structure of an ACMS application.

Figure 17-1 Structure of an ACMS Application

The AVERTZ application is made up of three menu choices: RESERVE, CHECKOUT, and CHECKIN. Each of these menu choices selects a corresponding task. The AVERTZ application also contains two tasks that are called by tasks not visible to the clerk:

• A task that checks reservation and customer information for both the CHECKOUT and CHECKIN tasks
• A task that completes or cancels a reservation for both the RESERVE and CHECKOUT tasks

The ability of tasks to call other tasks means that it is easy for you to design applications to share common code.

Just as each application is made up of one or more tasks, each task is made up of one or more steps that coordinate the work for that task. There are three types of steps within ACMS:

• Exchange steps coordinate I/O with a presentation service (such as a form).
• Processing steps coordinate I/O with a procedure (a user-written subroutine that handles database input, output, and computations).
• Block steps group exchange and processing steps into logical groups.

A considerable amount of control must take place to manage an application like AVERTZ. ACMS is designed to make such complex coordination and control easy to manage. Figure 17-2 illustrates how ACMS tasks coordinate the flow between forms that collect input from users and databases that store information.

Figure 17-2 Example of Execution Flow for an ACMS Task Definition

ACMS tasks are written using the ACMS Task Definition Language (TDL), which is based on a call and return model. Task definition steps perform calls to the presentation service in exchange steps, and to step procedures in processing steps. The presentation service and procedures perform their work and then return control to the task definition. Upon return to the task definition, subsequent parts of a step can evaluate the results of the call and, if necessary, handle any error conditions.

17.2 Task Definition Language

Example 17-1 shows portions of the code that are part of the reservation task in AVERTZ. Table 17-1 includes a description of each portion of code, based on the callout numbers in the example.

Example 17-1 Code from the Reservation Task Definition

REPLACE TASK avertz_cdd_task:vr_reserve_task (1) USE WORKSPACES vr_control_wksp, (2) vr_customers_shadow_wksp, vr_customers_wksp, vr_rental_classes_wksp, . . . DEFAULT FORM IS vr_form; (3) . . . get_car_now: (4) BLOCK WITH TRANSACTION (5) . . . PROCESSING (6) CALL PROCEDURE vr_store_cu_proc IN vr_cu_update_server USING vr_control_wksp, vr_customers_wksp, vr_trans_wksp; ACTION IS (7) IF (ACMS$T_STATUS_TYPE = "B") THEN GET MESSAGE INTO vr_control_wksp.messagepanel; RAISE EXCEPTION vr_update_error; END IF ; !+ ! If want to check car out now (=GTCAR) then call ! vr_complete_checkout_task to do that. !- PROCESSING (8) CALL TASK vr_complete_checkout_task USING vr_sendctrl_wksp, vr_control_wksp, vr_reservations_wksp, vr_trans_wksp, vr_vehicles_wksp; END BLOCK; (9) ACTION IS (10) MOVE " " TO vr_control_wksp.ctrl_key, "ACTWT" TO vr_sendctrl_wksp.sendctrl_key; COMMIT TRANSACTION; GOTO STEP disp_stat; !+ ! If the vr_store_cu_proc has an error because of constraint violation ! goto fix customer info exchange. If the transaction failed Retry the ! distributed transaction 5 times before canceling task. The retry_count ! is incremented in vr_store_cu_proc. !- EXCEPTION HANDLER (11) SELECT FIRST TRUE OF ( ACMS$L_STATUS = vr_update_error ): MOVE "TRAGN" TO vr_sendctrl_wksp.sendctrl_key; GOTO STEP fix_cust_info; ( (ACMS$L_STATUS = ACMS$_TRANSTIMEDOUT AND vr_control_wksp.retry_count < 5) ): REPEAT STEP; NOMATCH: GET MESSAGE INTO vr_control_wksp.messagepanel; MOVE "ACTWT" TO vr_sendctrl_wksp.sendctrl_key, " " TO vr_control_wksp.ctrl_key; GOTO STEP disp_stat; END SELECT; . . . END DEFINITION;

Table 17-1 Description of Code Excerpt

Callout	Description
(1)	The REPLACE command is the first command in a task definition. It replaces an old dictionary definition with the current task definition or creates a new definition if one does not already exist.
(2)	The USE WORKSPACES clause names one or more workspaces to which the task needs access. Workspaces are buffers used to pass data between steps in a task, between a task and a procedure, between a task and a form, and between tasks. As you see in (6), some of the workspaces are used to pass information to a step procedure.
(3)	The DEFAULT FORM clause names the DECforms form used by the exchange steps within the task.
(4)	The get_car_now: label is used to identify the section of code that begins with the BLOCK clause. Labels allow for the transfer of control to different parts of the task.
(5)	The BLOCK clause groups multiple steps as a logical unit. TRANSACTION is a block phrase that marks the start of a distributed transaction (a distributed transaction makes more than one database update as a single "all or nothing" transaction). This example of the BLOCK clause consists of multiple processing steps ( (6) (8) ). The processing steps include ACTION ( (7) (10) ), and EXCEPTION HANDLER ( (11) ) clauses, which are part of the processing steps.
(6)	The PROCESSING clause identifies work that is part of a processing step. In this example, the PROCESSING clause calls the COBOL procedure named VR_STORE_CU_PROC, which resides in a server named VR_CU_UPDATE_SERVER. Procedures perform all computation and database work. (The VR_STORE_CU_PROC procedure stores a customer record in the database, for example). Note that the USING keyword identifies workspaces that are passed to the procedure as parameters.
(7)	The ACTION clause defines actions you want ACMS to take at the end of an exchange step, processing step, or block step. In this example, the ACTION clause tests the return status from the procedure. If the procedure fails for some reason (STATUS_TYPE=B), the ACTION clause uses the RAISE EXCEPTION clause to send control to the exception handler ( (11) ).
(8)	This PROCESSING clause calls another task, VR_COMPLETE_CHECKOUT_TASK, to check out the vehicle. Note that again workspaces are identified as parameters.
(9)	This END BLOCK clause ends the entire block step, which consists of the two processing steps, the action parts, and the exception handler part.
(10)	This ACTION clause performs some workspace work and then commits the transaction. The COMMIT clause signals the end of the current distributed transaction and makes permanent any changes made since the start of the distributed transaction.
(11)	By default, if ACMS encounters an error that prevents it from executing a task, ACMS cancels the task. The EXCEPTION HANDLER clause lets you handle the error and continue task execution. In this example, if the exception was a transaction timeout, it retries the transaction five times before cancelling the task. If the exception was an update error, control goes to a step labelled fix_cust_info, which allows the user to correct the data.

17.3 More AVERTZ ...

The AVERTZ sample application demonstrates an ACMS transaction processing application from many perspectives. As you learn more about ACMS, you can modify the AVERTZ application to test what you have learned. Furthermore, you can use the design model for AVERTZ as a starting point for how to approach designing your own ACMS application.

For more detailed information on the design and coding aspects of AVERTZ, consult the following ACMS documentation:

• Compaq ACMS for OpenVMS Concepts and Design Guidelines
  Explains ACMS concepts and provides guidelines for designing an ACMS application.
• Compaq ACMS for OpenVMS Writing Applications
  Explains how to use the ACMS Application Definition Utility (ADU) to define tasks, task groups, applications, and menus.
• Compaq ACMS for OpenVMS Writing Server Procedures
  Explains how to write, debug, and run procedures for ACMS applications.
• Compaq ACMS for OpenVMS Systems Interface Programming
  Describes how to write ACMS code that allows nonterminal devices (such as bar-code readers and Automatic Teller Machines) to be integrated into an ACMS system.

All these documents make extensive use of AVERTZ code examples to illustrate ACMS concepts and features.

This appendix describes how ACMS runs a task and introduces some utilities that are available to help you solve problems in running a new ACMS application.

A.1 How ACMS Runs a Task

It is often helpful, especially in problem-solving, to know the various steps that ACMS takes to run a task. Figure A-1 illustrates how ACMS responds to the ACMS/ENTER command:

1. Checks ACMSDDF.DAT, the terminal authorization file, to verify that your terminal is authorized for use with ACMS.
2. Checks ACMSUDF.DAT, the user authorization file, to verify that you have been authorized to use ACMS, and to determine which menu database (.MDB) file has been assigned as your default.
3. Displays your default selection menu (if you and your terminal passed the authorization checks) and waits for you to select a task.
4. Consults the .MDB file to find out which application database (.ADB) file contains the task you selected.
5. Consults the .ADB file to find out which task group database (.TDB) file contains the task.
6. Finds the task in the .TDB file and runs it. The .TDB file also contains the file specification of the procedure server image and the entry points of the procedures in the image, as well as workspace definitions.
7. Returns to step 3 when the task has finished executing.

Figure A-1 Databases in an ACMS Application

The Audit Trail Logger (ATL) keeps a record of when the ACMS system starts and stops, when users log in, when applications and tasks start and stop, errors signaled by processing steps, and so forth. To display this log, run the Audit Trail Report (ATR) Utility from the SYS$SYSTEM directory.

Issue either of the following commands to run ATR:

$ RUN SYS$SYSTEM:ACMSATR ATR>

or:

$ MCR ACMSATR ATR>

At the ATR> prompt, issue the LIST command with the /SINCE qualifier to see today's log of your application:

ATR> LIST/APPLICATION=EMPLOYEE_INFO_APPL_xxx/SINCE=TODAY

For detailed information about the Audit Trail Logger and the ATR Utility, refer to Compaq ACMS for OpenVMS Managing Applications.

A.3 Software Event Logger

The Software Event Logger (SWL) records all software errors and event messages that occur during the execution of ACMS application programs. Each time an error occurs, ACMS writes a message to the SWL log file with information such as user name, process name, VAX condition code, and extended error descriptions.

The Software Event Log Utility Program (SWLUP) generates reports containing information recorded by the SWL. To read information in the SWL log file, you use SWLUP commands.

Issue either of the following commands to run SWLUP:

$ RUN SYS$SYSTEM:SWLUP SWLUP>

or:

$ MCR SWLUP SWLUP>

At the SWLUP> prompt, issue the LIST command with the /SINCE qualifier to display today's log of events for user JONES:

SWLUP> LIST/USER=JONES/SINCE=TODAY

To write the log of all events for user JONES to an output file instead of to the terminal, issue the LIST command as follows:

SWLUP> LIST/USER=JONES/OUTPUT=MY_EVENTS.LIS

For detailed information about the Software Event Log and the SWLUP Utility, refer to Compaq ACMS for OpenVMS Managing Applications.

A.4 DECforms Trace Facility

The DECforms trace facility logs form-processing information at run time to help you debug your application program and your form. The trace facility is useful because much of the form processing occurs each time you call a DECforms request from your ACMS application program.

You can turn tracing on before running a task in the ACMS Task Debugger (see Section 9.4). In this way, you can debug logic problems, debug data mismatches and other run-time errors, and observe how a user works through a series of panels.

You turn tracing on by defining the logical FORMS$TRACE as a character string value that begins with any of the following characters: T, t, Y, y, or 1. For example:

$ DEFINE FORMS$TRACE YES

Turning on the trace facility produces a trace file with the same name as your form followed by the TRACE extension (by default), for example, EMPLOYEE_INFO_FORM.TRACE. For a name other than the default, define the logical FORMS$TRACE_FILE to your own trace file specification.

The trace facility is turned off when you define the FORMS$TRACE logical as a character string value that begins with any character except those that turn tracing on. Tracing also ends when you log out (the process logical FORMS$TRACE becomes undefined then). It is advisable to turn off the trace facility when you are finished testing to avoid having your trace file become exceedingly large.

For detailed information about the DECforms trace facility, refer to DECforms Programmer's Reference Manual.

A.5 ACMS Help Facility

The ACMS Help facility contains a menu of ACMS error codes, from which you can choose to view information about a specific ACMS error. For help with ACMS error messages, issue the following command:

$ HELP ACMS ERRORS

The ACMS Help facility also contains information about many other ACMS topics. For a Help menu of ACMS topics, issue the following command:

$ HELP ACMS