The Software Event Logger (SWL), which records all run-time software error and event messages, is another useful tool for tracking errors that occur when an ACMS application is executing.

Each time an error occurs, ACMS writes a message to the SWL log file with information including:

• User information
• Process information
• System time
• Extended error information

The Software Event Log Utility (SWLUP) allows you to create reports using information recorded by the SWL.

4.5 Tuning the ACMS System

Performance of an ACMS application depends mainly on the design of the application and the amount of resource sharing that takes place when the application is executing. In general, using ACMS processes efficiently yields the best performance. When you want to improve system performance:

• Make sure you have adequate hardware resources for your workload
• Examine the design of your application in addition to tuning your operating system

Compaq ACMS for OpenVMS Concepts and Design Guidelines contains information on how to design your application to avoid performance problems.

See Compaq ACMS for OpenVMS Managing Applications for information on fine tuning your applications. Additional information to help you design your ACMS system and applications to run efficiently appears throughout the ACMS documentation set.

This chapter outlines the ACMS product kits and describes ACMS documentation. It summarizes the contents and intended audience of each book in the documentation set.

5.1 ACMS Product Kits

ACMS is available in three software kits:

• ACMS Development System
  The ACMS development system contains all the components you need to create and control ACMS applications. You can define, build, and debug multiple-step tasks and task groups, as well as menus and applications.
  You must have the CDD dictionary installed on your system to run the full development kit.
  The development system includes both the run-time option and the remote access option software. This manual concentrates on the features of the development system.
• ACMS Run-Time Option
  The ACMS run-time option lets you run existing ACMS applications or programs and change application attributes (for example, menu definitions). With the run-time option, you can define menus and applications, as well as tasks and task groups that use DCL servers.
  The run-time option includes all the facilities of the development software except the ACMS Task Debugger, and the ability to define multiple-step tasks that use server procedures. To modify definitions, you must have installed CDD, which is optional with the run-time option. The run-time option includes the remote access option software.
• ACMS Remote Access Option
  The ACMS remote access option allows you to access ACMS applications running on other nodes in a DECnet network from nodes that do not necessarily have any ACMS applications running on them. The remote access option software lets you place users and the terminal input/output associated with their tasks on one system (a front-end, or submitter, node) and the data storage files on another (a back-end, or application, node).

The following sections describe the ACMS documentation set. Each section is based on a phase of the application development life cycle, and describes the appropriate documents for that phase of the life cycle. The life cycle is illustrated in Figure 1-7.

5.2.1 Orientation and Installation

Compaq ACMS Version 4.3 for OpenVMS Release Notes
Audience: All ACMS users
Content: Includes specific information about the current ACMS release and contains material added too late for publication in the ACMS documentation. The release notes are available on line only.

Compaq ACMS Version 4.3 for OpenVMS Installation Guide
Audience: System managers
Content: Describes how to install ACMS and run the Installation Verification Procedure (IVP).

Compaq ACMS for OpenVMS Getting Started (this manual)
Audience: Application designers, programmers, system/application managers
Content: Provides an introduction to the basic elements of the ACMS transaction processing system. The book explains the concepts of transactions and transaction processing, describes the ACMS run-time system, and introduces the utilities and tools for creating, controlling, and managing ACMS applications. It also includes a glossary of ACMS terms.
Uses a simple application and a step-by-step approach to allow the user to develop a complete ACMS application that uses DECforms.
Provides an overview of the AVERTZ sample application from the perspectives of designers, developers, users, and system managers.)

5.2.2 Planning and Design

Compaq ACMS for OpenVMS Concepts and Design Guidelines
Audience: Application designers, programmers
Content: Explains ACMS concepts and provides guidelines for designing an ACMS application.

5.2.3 Development and Testing

Compaq ACMS for OpenVMS Writing Applications
Audience: Application designers, TP system managers, programmers
Content: Explains how to use the ACMS Application Definition Utility (ADU) to define tasks, task groups, applications, and menus. This book describes how to queue and dequeue tasks, perform exception handling, and define distributed transactions.

Describes how to write ACMS applications to run on OpenVMS Alpha and how to migrate ACMS applications from OpenVMS VAX to OpenVMS Alpha.

Compaq ACMS for OpenVMS Writing Server Procedures
Audience: Application designers, programmers
Content: Explains how to write, debug, and run procedures for ACMS applications, including step procedures that access Rdb, DBMS, and RMS resource managers; initialization procedures; termination procedures; and cancellation procedures. The book also describes how to create message files and how to debug ACMS applications.

Describes how ACMS works with the APPC/LU6.2 programming interface to communicate with IBM CICS applications.

Describes how ACMS works with third-party database managers, with Oracle used as an example.

Compaq ACMS for OpenVMS Systems Interface Programming
Audience: System designers, programmers
Content: Describes the ACMS Systems Interface (SI) and explains the interface services to submit tasks to an ACMS system from outside ACMS. This guide also explains how to pass data entered by users between task submitters and their tasks.

5.2.3.1 Reference Information

Compaq ACMS for OpenVMS ADU Reference Manual
Audience: Application designers, TP system managers, programmers
Content: Provides reference information about the phrases, clauses, and commands of the Application Definition Utility (ADU).

Compaq ACMS for OpenVMS Quick Reference
Audience: All ACMS users
Content: Lists the syntax for all the ACMS utilities. The book also provides a summary of the steps involved in developing an ACMS application, and includes a table that indicates what additional components must be changed when you make changes to any application component.

5.2.4 Implementation and Management

Compaq ACMS for OpenVMS Managing Applications
Audience: System/application managers, ACMS operators
Content: Describes how to authorize, install, run, and manage ACMS applications, and how to set up distributed ACMS applications. The book provides information on monitoring and tuning ACMS system performance, including setting OpenVMS and ACMS system parameters and process quotas.

Compaq ACMS for OpenVMS Remote Systems Management Guide
Audience: System managers, application managers, ACMS operators
Content: Description of the features of the Remote Manager for managing ACMS systems, how to use the features, and how to manage the Remote Manager.

This part is intended for application programmers who are using ACMS software for the first time. The book contains a step-by-step tutorial for developing a simple ACMS application. This application involves the integration of several products: ACMS, DECforms, RMS, and Oracle CDD/Repository software.

This chapter gives introductory material and lists the prerequisites for performing a step-by-step tutorial for developing a simple ACMS application. This chapter also provides an overview of ACMS application development concepts. The tutorial begins in Chapter 7.

6.1 Before You Begin

Before you begin, check the following list of prerequisites to ensure that you have everything you need to perform the tutorial application:

• Make sure that your system is running compatible versions of the following software:
  • OpenVMS Alpha or OpenVMS VAX
  • ACMS
  • DECforms
  • CDD
  
  See the ACMS Software Product Description (SPD) for information about the compatible software versions.
• Become familiar with the OpenVMS operating system and with a text editor such as the Language-Sensitive Editor (LSE). You use a text editor to create and edit the program source elements in this manual.
• Acquire a personal OpenVMS account on a system that is running ACMS, DECforms, and CDD software. Check with your system manager to ensure that your account has the necessary privileges to access these products. To run the ACMS Task Debugger as described in Section 9.4, make sure that your OpenVMS account has a BYTLM quota of 50,000.

All the source code developed in this tutorial is available on line. You can view the source files to compare them with those that you create here, or you can copy the online source files instead of typing them yourself. Appendix B lists these files and describes how to access them.

The procedures in this tutorial are written in COBOL. You can, however, write procedures in any high-level language that adheres to the OpenVMS Calling Standard. Also, it is not necessary to be familiar with COBOL to perform the tutorial.

This tutorial application uses an RMS master file to store and retrieve records. RMS is a file management system that is supplied with the OpenVMS operating system. If you are already running database software such as Rdb, you may wish to convert this tutorial application at some later time to one that accesses an Rdb database. In this case, refer to the appropriate database documentation for creating the database and for writing the statements that access it.

6.2 Application Development Life Cycle

Several phases make up the life cycle of an application. For an overall perspective of application development, it is helpful to know where the development phase fits into this life cycle and what assumptions this tutorial makes about the other phases.

Figure 1-7 identifies the phases of the application development life cycle. Section 5.2 lists the ACMS documentation that is useful for each phase. Note that you may have to revisit the intermediate phases several times during the course of developing a complex application.

During the orientation and installation phase, you install the product and deliver training in the development of applications.

During the planning and design phase, you perform requirements analysis, functional analysis, and prototyping for an application.

For the purpose of this tutorial application, assume that the planning and design phase has already been completed. The designers have decided on a nondistributed environment and a simple ACMS application that meets the needs of their personnel administration system. In this system, a user adds a new employee record to a master file or updates an existing employee record. The designers have determined which fields of data an employee record should contain, how those fields should appear on the data entry form, what error checking the application should contain, and other relevant design criteria.

During the development and testing phase, you write and test the code that implements the design of the application. This manual steps you through the coding process. For this tutorial application, you write CDD definitions, DECforms IFDL code, ACMS definitions, and COBOL procedures.

The development phase also includes testing the application. This manual steps you through the process of testing your task definitions in the ACMS Task Debugger prior to completing the application. You then have an opportunity to run and test the application more fully at the conclusion of code development.

During the implementation and management phase, you transfer an application from your development system to a production system and fulfill system management requirements for the application. Chapter 12, describes the steps a system manager performs to authorize an ACMS user and an ACMS application on an OpenVMS system. Until your system manager performs these management functions, you cannot install and run this tutorial application.

6.3 ACMS Application Development Concepts

An ACMS application consists of a set of tasks that relate to the functions of a business. A task is the unit of work that a user selects from an ACMS menu. Each task usually comprises a sequence of steps that perform this unit of work. You use the ACMS task definition language to define tasks.

Figure 6-1 illustrates the basic principles of the ACMS task definition language (TDL) used to write a task definition. The task definition specifies an interface to the presentation service (forms management system) for communication with a terminal or other device. The task definition also specifies an interface to a procedure server for executing procedures (user-written subroutines) that handle database I/O and computational work.

The semantics of the ACMS task definition language are based on a call and return model. Task definition steps perform calls to the presentation service in exchange steps, and to the procedure server in processing steps. The presentation service and procedure server perform a function and return control to the task definition. Upon return of control to the task definition, subsequent parts of a step can evaluate the results of the call and, if necessary, handle any error conditions.

Figure 6-1 shows a sample execution flow of a task definition:

1. In the first exchange step, the task definition calls the presentation service to display a form on the terminal screen (for example, a form to add a new employee record to a database). When the terminal user finishes filling in the form, the user presses a specified key (or keys) that allows the task definition to receive the input data.
2. In the processing step, the task definition then calls Procedure 1 in the procedure server to write that input data to the database. Procedure 1 then returns its results (either success or failure). If Procedure 1 fails to write to the database, step 2 then passes control to step 3.

   Figure 6-1 Execution Flow of an ACMS Task Definition

   ---

   
3. In the second exchange step, the task definition calls the presentation service to send an error message to the terminal screen (for example, that the employee number of the new record duplicates an existing employee number). The presentation service then returns control to step 3.

The ACMS task definition language allows you to write an ACMS definition as a series of simple, English-like statements. The four types of ACMS definitions are:

• A task definition describes, in steps, the work to be accomplished in the task. For example, a task can collect information from a user and call a procedure to store the information in a file or database.
• A task group definition specifies similar tasks for control purposes and defines resources common to all tasks in the group.
• An application definition describes the environment and control characteristics of tasks and task groups.
• A menu definition describes how users access one or more applications. Usually this definition allows users to access one or more tasks from an ACMS menu.

You build the task, task group, and application definitions into an application that runs under the control of the ACMS run-time environment. You build a menu definition separately, because it is not necessarily tied to a single application.

Figure 6-2 illustrates the ACMS development components for this tutorial application. This application is a simple personnel system that contains two tasks:

• The first task asks the user to enter employee data. The user can then save this data in a master file.
• The second task displays an employee record from the master file when the user enters an existing employee number. After examining the record, the user can change the information in it and write the changed record back to the file.

Figure 6-2 ACMS Application Components

Figure 6-2 does not show that there can be more than one task group definition specified for a single application. Also, more than one menu definition can specify tasks that point to the same application. Conversely, a single menu definition can specify tasks in different applications.

Because ACMS applications are modular, you develop each part of an application independently. If you need to change a task definition later, the change does not necessarily affect the task group, application, or menu definitions. Many types of changes do not affect other modules.

6.3.2 Composition of ACMS Definitions

A task definition controls the exchange of information with the user, and the processing of that information against the file or database. Each ACMS task definition is made up of one or more steps. ACMS breaks the work to be accomplished by a task into two types of steps:

• Exchange steps usually interact with the Form Manager to handle forms I/O (that is, the input and output between the task and the user). An exchange step can interact with DECforms or TDMS forms, or interface with other devices using the ACMS Request Interface or the ACMS Systems Interface for communicating with nonstandard devices. Figure 6-1 illustrates an execution flow with two exchange steps.
• Processing steps call step procedures (user-written subroutines) to handle computations and interactions with databases or files, typically using procedures written in a high-level programming language (any language adhering to the OpenVMS Calling Standard). ACMS uses two types of servers: procedure servers for executing a procedure, and DCL servers for invoking images or DCL commands. Figure 6-1 illustrates an execution flow with one processing step.
  A server process may perform an initialization routine of common work when the server is started, rather than each time a task is selected. ACMS manages pools of servers to save on image activation.
  Servers are serially reusable (that is, while attached to a task, a server process is not available to other tasks until the task call has completed). A single server process can be called by many different ACMS tasks in a serial fashion. Once the call is complete, the server is then available to be called by another ACMS task.
  When ACMS starts a processing step, it allocates a procedure server process to a task to execute the procedure in that step. This single-threaded process remains allocated to the task for the duration of one or more processing steps.

In ACMS, a workspace is a buffer used to pass data between the task and processing steps, and between the task and exchange steps.

Task group definitions combine similar tasks of an application that need to share common resources such as workspaces, a library of presentation services requests, and procedure servers.

The application definition describes:

• Task groups that belong to an application
• Characteristics that control the tasks, such as security restrictions on which users can select a particular task
• Servers, such as the number of server processes that can be active at the same time
• The application, such as whether application activity is recorded in the audit trail log

Menu definitions list both tasks and additional menus that a user can select from a menu. For example, the tasks on a menu can include adding new employee records, displaying employee information, and entering labor data.

When you write definitions for ACMS tasks, ACMS automatically stores the definitions in a CDD dictionary. At run time, the definitions are represented in binary form in ACMS-defined databases. For example, a task group definition is represented by a task group database that contains a binary representation of the task group definition.

6.4 ACMS Integration with DECforms

Although ACMS supports several presentation services, ACMS supports DECforms as its primary presentation service. DECforms provides such features as FIMS compliance, device-class independence, storage of form context between exchanges, input verification (values, ranges, and types), and escape routines.

6.4.1 DECforms Concepts

DECforms architecture provides a full separation of form from function. This separation allows you to write an application program (the function) without being concerned with the intricacies of the user interface (the form) for that program.

Normally, the term form means a document with blanks for the insertion of information. In DECforms, however, the form is a specification that may govern the complete user interface to an application program. The form specification completely describes all terminal screen interactions, the data that is transferred to and from the screen, and any display processing that takes place.

A panel consists of the information and images that are physically displayed on the user's terminal screen. A panel is composed of such items as fixed background information (literals), fields (blanks for insertion of information), attributes, function key control, and customized help messages.

You can partition the display into rectangular areas called viewports by specifying viewport declarations within the form definition. You can adjust the viewport to any size and locate it anywhere on the display (such that viewports overlap one another). For a panel to be visible, it must be associated with a viewport.

Figure 6-3 illustrates the concept of specifying panel declarations and viewport declarations within the DECforms form definition. You specify a viewport name within each panel declaration. By doing this, you map each panel to a specific viewport. At run time, each panel appears on the terminal screen within its viewport.

Figure 6-3 Panels and Viewports

The DECforms Form Manager is the run-time component that provides the interface between the terminal display and an ACMS application. The Form Manager controls panel display, user input, and data transfer between the form and ACMS. A DECforms form is loaded by the Form Manager at execution time under the direction of an ACMS application program.

ACMS begins a session with DECforms when an ACMS application program first references the form. The syntax that references the form is contained in the ACMS task definition.