HP OpenVMS Systems Documentation
Compaq ACMS for OpenVMS
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
|Clerk:||"Hi, can I help you?"|
|Customer:||"Yes, my name is Bertram Simpson and I'm returning a car that I rented over the weekend."|
"OK, Mr. Simpson. Let me call up your reservation."
The clerk enters the following at the AVERTZ Rental Menu
(Figure 16-1 shows the AVERTZ Rental Menu):
Selection: 3 [Return]
|Clerk:||"OK, Mr. Simpson. Could I have your reservation number?"|
|Customer:||"Sure, I have reservation number 2."|
The clerk enters the following:
|Clerk:||"Are you still planning to pay with cash, Mr. Simpson?"|
|Customer:||"Yes, I am."|
The clerk enters the following:
|Customer:||"Yes, it was 357."|
The clerk enters the following:
"Mr. Simpson, the total cost is $30 dollars."
|Customer:||"Here's the $30 and the keys. Thanks."|
"You're welcome. And thank you for renting with AVERTZ!"
The clerk enters the following to return to the AVERTZ Rental Menu:
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:
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:
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:
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
17.2 Task Definition Language
|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;
|(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.|
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:
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:
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>
$ MCR ACMSATR ATR>
At the ATR> prompt, issue the LIST command with the /SINCE qualifier to see today's log of your application:
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>
$ 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:
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:
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
$ 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