Terminal, menu, and other input/output (I/O) functions are separated in ACMS from database or file processing and computational functions. The terminal and menu functions are handled on the front end of the transaction processing system, while the data processing and computation are performed on the back end of the system. Figure 1.3, “Front-End/Back-End Processing in a Local ACMS System” illustrates the operation of ACMS front-end and back-end processing.

The separation of functions in ACMS makes it possible for you to distribute ACMS applications across a network of computers, installing front-end functions on one or more nodes and back-end functions on another set of nodes in the network. In a distributed transaction processing environment, the front end is also called the submitter node, because it is the node from which tasks are selected and sent to the back-end node. The back end is also called the application node, because it is the node on which the application execution and data processing are performed.

Figure 1.4, “Distributed ACMS System” illustrates an ACMS system environment distributed across a network.

Most TP applications put heavy demands on computer processing power and memory resources. An important requirement for TP applications is that they make efficient use of the resources available. With a traditional TP system, structuring applications to minimize the strain on a system can demand additional design and programming time. ACMS is designed to use computer resources, such as memory and CPU, efficiently to help maximize run-time performance.

ACMS uses dedicated OpenVMS processes to manage terminal I/O, execute processing and data manipulation subroutines, and control the application run-time system.

ACMS has a multithreaded internal design. In a system that uses multithreaded processes, a single process can manage more than one user or process at the same time. On the front end of an ACMS system, a single process can display forms and menus for many users rather than have each user need a separate process to do this work. On the back end, a single process can handle the flow control, or the complex coordination of data processing and computations, of each user's work rather than have OpenVMS manage each user's process separately. Also on the back end, rather than each user using a separate process to access the database, a single process can manage paths into the database for many users at one time. To help you manage heavy system use, ACMS allows you to create additional processes on the back end as the need arises.

The separation of functions in ACMS makes it possible to increase the speed and reliability of ACMS transactions by distributing the front-end and back-end functions across a network. You can offload forms processing to a smaller front-end computer, like a MicroVAX, and use more powerful computers, like a VAX 8800 or a VAX 9000, for back-end data processing. You can configure each node in the distributed system for the processing of specific tasks.

It is easy to expand an ACMS system to meet your growing business needs. Without rewriting your application code, you can distribute existing ACMS applications or add nodes to an existing network of distributed ACMS applications.

You can install and run ACMS applications on the full range of VAX and Alpha computers, from the small MicroVAX to the powerful VAX 9000 mainframe.

To accommodate more users, you can add small clusters of VAX and/or Alpha computers as front-end nodes to handle additional terminal and forms processing. To increase application processing capabilities, you can add high-performance VAX and/or Alpha computers as back-end nodes.

By distributing the forms processing functions of an ACMS application, you can make the system more available in the event of system failures. Using the features of DECnet network software, OpenVMS Cluster networks, and volume shadowing, ACMS eliminates single points of system failure and significantly increases the amount of time your applications are available to you.

Figure 1.5, “OpenVMS Cluster Configuration in a Distributed ACMS System” illustrates a configuration in which an ACMS system uses MicroVAX computers in a local area OpenVMS Cluster network as front-end submitter nodes, and uses a back-end OpenVMS Cluster for database or file functions.

For more information on configuring your ACMS system for high availability, see VSI ACMS for OpenVMS Managing Applications.

Some ACMS applications use data that is collected and processed interactively. The application displays a menu or a form on a video terminal through which users enter data. Then the application processes the data and either displays the results of the processing or requests more data.

Other ACMS applications require that data be collected once and then stored in a temporary storage area, or queue, for the application to process at another time. For these types of applications, data can be collected using a device other than a terminal, such as a card-punch time clock, and sent to a special ACMS queuing facility. The ACMS queuing facility lets you place tasks in a queue and then submit the tasks for processing at another time. Using the queuing facilities provided by ACMS, you can design applications to immediately process in real-time (such as capturing data), and alternatively defer processing of work that does not require real-time processing until later.

For more information on ACMS queues, see VSI ACMS for OpenVMS Writing Applications.

ACMS applications are made up of a set of component definitions that describe and control the work of an application, and a set of subroutines that access databases and files. You use the ACMS Application Definition Utility(ADU) for creating and processing the component definitions of an ACMS application. To write application subroutines, called server procedures, you can use any third-generation language that conforms to the OpenVMS Calling Standard, such as C or COBOL.

ADU includes a high-level, English-like definitional language. You use the statements and clauses of the language to create definitions for each application component of an ACMS application. In addition, you use ADU commands to process the definitions. When you process a definition, you build a binary file from the definition that is interpreted at run time.

ACMS applications are easier to develop and maintain than traditional applications because modular definitions replace system programming calls. Developing sets of component definitions and application subroutines emphasizes the principles of structured programming. As a result, you can divide responsibilities for developing parts of an application among many programmers.

The modularity of ACMS applications also makes maintenance easier. Terminal I/O is separate from data processing, and application logic is separate from system and application management. To change an application, you make changes to a component's definition, rather than rewrite the entire application.

Chapter 2, Developing ACMS Applications provides an introduction to developing ACMS applications. For detailed information on developing applications using ADU, see VSI ACMS for OpenVMS ADU Reference Manual and VSI ACMS for OpenVMS Writing Applications.

TP systems must ensure that data remains consistent and work remains intact if the system or database becomes unavailable. Using data management products and the DECdtm Services for OpenVMS(a collection of OpenVMS services that provide for the management of distributed transactions), ACMS provides full data and transaction integrity and consistency.

A resource manager controls shared access to a set of recoverable resources, such as a database. In an application that accesses a single database or set of files, resource managers ensure integrity by providing rollback recovery. Resource managers available to ACMS include RMS, Rdb, and DBMS. When a database transaction updates a database, the resource manager commits the change when the transaction ends. Committing the change makes it permanent. If the system or database becomes unavailable before the database transaction ends, the resource manager rolls back the database, returning it to the state it was in before the transaction started.

For applications that use distributed transactions, that is, a single grouping of operations on more than one recoverable resource or resource manager, the DECdtm services provide rollback recovery following a two-phase commit protocol. Two-phase commit protocol ensures that, when changes are made to data during a distributed transaction, either all resource managers commit the distributed transaction or all work will be rolled back.

DECdtm components include a transaction manager and resource managers. The transaction manager oversees the phases of a two-phase commit for either a database transaction or an ACMS queuing facility operation. Resource managers (such as Rdb, DBMS, and RMS) manage the access to their recovery data and databases.

Each node in the network has its own DECdtm transaction manager and one or more of the supported resource managers. For each transaction, a DECdtm transaction manager tracks which resource managers are being used to process data. If an event on the system keeps the transaction from completing anywhere on a network, all databases affected by that transaction are rolled back to their original state.

You can also design applications that use the ACMS queuing facility to place tasks in a queue file. The ACMS queuing facility uses DECdtm services to ensure that every task on the queue is processed exactly once. In a distributed system, tasks and their data can be entered on the front-end queue. If the back-end node becomes unavailable, the tasks and their data are held in the queue. When the back-end node becomes available again, the tasks are submitted for processing.

For example, you can give a personnel employee access to a task that updates a confidential file, but ensure that the employee cannot view sensitive information in the file, make unauthorized changes to the file, or gain access to the file outside the context of the task.

For a more detailed introduction to defining access to ACMS and applications, see Chapter 4, Managing ACMS Systems and Applications. For details on managing an ACMS system, see VSI ACMS for OpenVMS Managing Applications.

Users select and run ACMS tasks from menus. Figure 1.6, “Sample ACMS Menu” shows a sample ACMS menu.

To create menus, ACMS supports DECforms, a forms product running on the OpenVMS operating system, as its primary presentation service. In addition, ACMS provides support for VAX Terminal Data Management System (TDMS). DECforms is the first commercial implementation of the proposed ANSI/ISO standard Form Interface Management System (FIMS), a system for interaction between applications and display devices. Using DECforms, you can write a forms application program (which describes the function of a display) separately from the user interface of the display (such as a menu or form).

ACMS uses standard menus in both DECforms format and TDMS format. You can easily customize these standard menus. For more information on using DECforms or TDMS, see the appropriate product documentation. For an example of using DECforms to create standard ACMS menus, see Chapter 11, Defining and Building the Menu.

ACMS provides support for other presentation service products. Using the ACMS Request Interface and the ACMS Systems Interface, you can create applications that use forms management products, such as FMS, or special devices, such as electronic badge readers.

The Request Interface allows you to use presentation services other than DECforms or TDMS for I/O functions limited to one user per process. ACMS provides an easy-to-use programming interface with the Request Interface to forms products such as FMS (Forms Management System), SMG (Screen Management Facility), terminal interface products from other vendors, and menus in an ALL-IN-1 office integration system.

The Systems Interface allows you to use presentation services for single-user or multiple-user I/O functions. The Systems Interface provides a set of software system services that give systems programmers the flexibility to design customized interfaces for complex systems or devices, such as badge or bar code readers.

For more information on using the Request Interface, see VSI ACMS for OpenVMS Writing Applications. For more information on using the Systems Interface, see VSI ACMS for OpenVMS Systems Interface Programming.

The CDD data dictionary system provides a central storage location for data descriptions and definitions shared by ACMS, other related products, and programming languages.

As a member of a family of layered software products, ACMS makes use of high-level programming languages and tools.

You can write and debug application programs using a variety of high-level programming languages, including COBOL, FORTRAN, and C, and the OpenVMS Debugger. You can use any high-level language that adheres to the OpenVMS Calling Standard.

For more information about programming productivity tools, see A Methodology for Software Development Using OpenVMS Tools, or the documentation for each individual product.

Oracle Trace is a tool that collects data and creates detailed reports on events that occur when an ACMS application runs. The information you collect with Oracle Trace can help you tune your ACMS system and improve performance.

For information on using Oracle Trace with ACMS applications, see VSI ACMS for OpenVMS Managing Applications.

Figure 2.4, “Simple Form for a Sales Task” shows a form you might see after selecting the Sale task from the menu in Figure 2.3, “Simple ACMS Menu”. An exchange step displays the form and prompts the sales clerk to enter a stock number, a description of the item, and whether the sale is cash or charge. A processing step records the sale, subtracts the item from the store's inventory, and prints an invoice for the customer.

Figure 2.5, “Task Steps for an Inventory Update Task” shows the sequence of exchange and processing steps for a simple inventory update task a warehouse clerk might select from the menu in Figure 2.3, “Simple ACMS Menu”.

After the warehouse clerk selects the inventory update task, an exchange step displays a query form and prompts the clerk to supply the inventory item to be updated, in this case widgets. A processing step calls a procedure that reads the widget inventory record. A second exchange step displays the inventory, in this case 0 widgets, in an update form, and allows the warehouse clerk to update the record to reflect the arrival of 100 widgets. The final processing step calls a procedure that stores the updated record in the inventory database or file.

2.2.1.1. Writing Server Procedures

Processing steps can run server procedures written in a high-level programming language. ACMS supports all programming languages that conform to the OpenVMS Calling Standard, such as COBOL, FORTRAN, or C. You use OpenVMS utilities to write, debug, and compile server procedures.

When all the procedures you need for a task or group of tasks are ready, you link the procedures to create a single procedure server image. At run time, ACMS creates at least one special process called a procedure server process, and activates and loads the procedure server image. When a user selects a task that uses the procedures, ACMS runs the programs. Figure 2.6, “Parts of a Procedure Server” shows the parts of a procedure server.

In addition to the step procedures that run in processing steps, you can write special procedures to maximize system resources, including:

• Initialization procedures to open all the files and to ready any databases needed by a group of tasks

• Termination procedures to close at one time all the files and any databases used by a group of tasks

• Cancel procedures to clean up context held by a task in a server when the task cancels before completing successfully

When you create a procedure server, you include any initialization, termination, and cancel procedures as part of the procedure server image. These special procedures can help conserve system resources because the work they do is done once for the group of tasks that use the procedure server.

For more information on creating procedure servers, see VSI ACMS for OpenVMS Writing Server Procedures.

For example, you use workspaces when you pass data from a form on a terminal to and from a database or file. A workspace can contain data provided by a user at a terminal through an exchange step or a processing step in the same task group. Tasks read information from workspaces and write information to them.

A Command Process (CP) manages logins and interaction between terminals and ACMS. CPs display menus, accept and interpret terminal user commands, and communicate with the Application Execution Controller. An ACMS system can include more than one CP.

A CP separates an application's interactions with the terminal from its processing work. This separation makes it possible to distribute the application, off-loading forms and menus to a front-end, or submitter node, and concentrating computations and data processing on one or more back-end, or application nodes.

The ACMS Queued Task Initiator (QTI) dequeues task elements that were placed in a queue by an ACMS programming service, and initiates tasks in an application. For example, you can design a task that places another task in a queue, allowing users and the application to continue working without waiting for the queued task to complete. The QTI later executes the queued task.

The Application Execution Controller(EXC) processes the definitions of the tasks in an application, managing all the tasks in an application simultaneously. The EXC is responsible for task security, allocating workspaces, and scheduling, creating, and communicating with servers. The EXC accepts messages from the CP or QTI (which invoke tasks on behalf of the user), passes forms for exchange steps to the CP, creates server processes that call procedures in processing steps, and creates workspaces for sharing data by tasks.

Each application on an ACMS system has its own execution controller. You can run more than one application on a node and have more than one active EXC at a time.

The server process (SP) carries out the high-level programming language routines or DCL routines that handle a task's processing work and database or file I/O. The SP calls the appropriate subroutine for a task. The EXC uses the results to determine what to do next and passes the final task results to the CP or QTI. Each application can use more than one server process.

The CP uses the menu database to display menus for a user. The EXC uses the task group database to determine flow control for tasks and which server to call for a particular task. The EXC uses the application database to determine such information as the process characteristics for server process and security through an access control list (ACL) for a task. The ACL specifies which users can execute a task.

The ACMS Central Controller (ACC) is the central control point for the ACMS run-time system. It starts and controls the Terminal Subsystem Controller, the QTI, the EXC, and the Audit Trail Logger (ATL).

The Terminal Subsystem Controller (TSC) is responsible for creating and controlling the number of active CPs and for assigning terminals to CPs. The TSC starts and stops CPs as needed within limits that you define. It also controls which terminals can access ACMS.

The Audit Trail Logger (ATL) is responsible for writing information about a running ACMS system to the audit trail log file. The ATL keeps a record of when the ACMS system starts and stops, when users log in, and when applications and tasks start and stop. The ACC always starts the ATL when the ACMS system is started. With the Audit Trail Report Utility (ATR), you can create summary reports based on information recorded by the ATL.

The Software Event Logger (SWL) records all software errors and event messages that occur during the execution of ACMS application programs. The Software Event Log Utility Program (SWLUP) allows you to create reports containing selected information recorded by the SWL.

ACMS sends status and other operational messages to terminals that are assigned as ACMS operator terminals.

An operator terminal receives messages from ACMS if an application, the Audit Trail Logger (ATL), or the Terminal Subsystem Controller (TSC) stops unexpectedly. The operational messages are also logged in the software event log (SWL) file. An ACMS operator, who is authorized to use ACMS operator commands, can find and correct problems more quickly with an authorized operator terminal than with an error log file only.

The audit log includes information about system and application starts and stops, user sign-ins and sign-outs, processing errors, user task selections, and task completions. You can use this information to determine who is using ACMS, what applications and tasks they are running, and what tasks have been completed or canceled.

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.

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

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, “ACMS Application Components” 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.

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.

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.

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, “Panels and Viewports” 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.

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.

In DECforms, the form record is a structure that controls data transfer between ACMS and the form. The form record identifies which form data items (variables associated with the form) are to be returned to ACMS.

Figure 6.4, “DECforms Interaction with ACMS” shows the interaction between DECforms and ACMS when ACMS requests information from DECforms.

VSI's resource managers are not an integral part of the TP system, but are instead under the control of the operating system (OS). This OS control of resource managers permits database sharing among TP and non-TP applications, decision support systems, and remote nodes requesting data.

ACMS supports Rdb as its primary database management system. For Rdb conceptual information, refer to the Rdb documentation.

For the sake of simplicity, this tutorial application uses an RMS master file to store and retrieve records. RMS is an OpenVMS-supplied file management system that supports sequential, relative, or indexed files. The initialization procedure in this tutorial creates the RMS file (EMPLOYEE.DAT) when you run the application for the first time.

To access a database, ACMS interacts with a procedure server process. The procedure server process, in turn, interacts with the resource manager of the database. As shown in Figure 6.5, “A Resource Manager Interacting with ACMS”, processing steps call step procedures (user-written subroutines) to handle interactions with the resource managers of databases or files.

ACMS uses a procedure server process for executing a procedure. When starting a processing step, ACMS allocates a procedure server process to execute the procedure in that step. The procedure server process remains allocated to the task for the duration of one or more processing steps in the task.

In an update task, you need at least one exchange step to prompt the user for a key value, and another to display the requested record for modification. You need one processing step to retrieve the record from the database, and another to write the record back to the database with the user's changes. Figure 6.5, “A Resource Manager Interacting with ACMS” shows the interactions among ACMS, the procedure server, and the resource manager to execute a simple update task.

For a full picture of the ACMS execution flow that includes the Form Manager's role in exchange steps, refer to Figure 6.1, “Execution Flow of an ACMS Task Definition”.

To make your form useful, create a panel that produces a display on the terminal screen. The next section contains instructions for doing this.

You now edit the form IFDL source file to include other definitions and special instructions. Note that DECforms automatically added a number of statements to your IFDL file when you exited FDE. For example, the Form Data section and the field descriptions in that file are a result of the data fields that you created interactively with DECforms.

Whenever you edit your IFDL source file, you must translate that file into an updated binary form file to reflect the edits made in the IFDL file. DECforms stores a form internally in a binary form file (with file type .FORM).

You also need to create an object module and a shareable image of the form to use in your ACMS application.

You begin a processing step by identifying it with the keyword PROCESSING. This processing step calls a procedure that adds information to an RMS file.

In the Identification Division of this program, you give the COBOL procedure a name to complete the PROGRAM-ID statement. This name must be unique among all the procedures that run in the same server, and it must be the same name that you specified previously in your task definition's CALL statement to this procedure.

In this tutorial, the name of the COBOL procedure is ADD_EMPL_INFO.

The Environment Division defines the RMS file named EMPLOYEE.DAT and specifies its location. EMPLOYEE-FILE is the procedure's internal name for referencing the external file EMPLOYEE.DAT, where the procedure stores the information that the user enters. (The file EMPLOYEE.DAT is created by the COBOL initialization procedure defined in Chapter 9, Building the Task Group.)

You use the SELECT clause to assign the internal name to the RMS file, describe the organization and access of the file, provide a FILE STATUS buffer, and assign the OpenVMS file specification for the RMS file.

The FILE STATUS clause identifies the FILE-STAT data item, where the status value of the write operation is stored. In the I-O-CONTROL section, the APPLY statement enables record locking for EMPLOYEE-FILE.

In the Data Division, you define the personnel records that make up the RMS file, naming one field as the primary key. An RMS file in an ACMS application contains records whose definitions reside in CDD. Therefore, the Data Division need not list every field in the record, but can instead include a COPY ... FROM DICTIONARY clause for the record definition.

This procedure identifies EMPLOYEE-FILE as EXTERNAL because the file is accessed externally. The RECORD KEY clause establishes the employee number field, EMPL_NUMBER, as the primary key of the record. The COPY statement directs the procedure to find the definition of EMPLOYEE_INFO_WKSP in the CDD dictionary when you compile this COBOL program.

The Data Division also sets up condition values for you to use in error handling. A user might try to add a new record to the file using an employee number that already exists. The COBOL condition code for the duplicate key error is 22. In the Data Division, you declare the FILE-STAT data item and associate it with the names of the condition values (DUPL_PRIMARY, for example) that your procedure tests during its execution.

Another possible error is when a second user tries to access the record while the procedure is processing the record for the first user. Because the procedure locks the record during I/O processing, the second user encounters a locked-record condition. The COBOL condition code for the locked-record error is 92. You must also associate FILE-STAT with the REC-LOCK condition.

The Linkage Section of this procedure lists the workspaces passed between the task and the procedure. COPY statements describe which CDD record definitions correspond to the workspaces you need. Because the linkage record and the file record must have different names, the COPY statement for EMPLOYEE_INFO_WKSP must use a REPLACING clause to assign a different name to the workspace. This new name is used only in the Procedure Division of the procedure.

The main action of the Procedure Division is to write a new record to the RMS file. ACMS passes the user input to the procedure in the EMPLOYEE_INFO_WKSP workspace, renamed to EMPLOYEE_INFO_LINKAGE_WKSP in the Linkage Section. The procedure uses CONTROL_WORKSPACE to report any errors. As required, the USING clause lists both workspaces in the same order as the CALL clause listed them in the task definition.

The Declaratives Section handles any errors in the procedure. If a duplicate primary key error occurs when the procedure tries to write a new record to the file, FILE-STAT is assigned the condition value DUPL-PRIMARY. The EVALUATE statement tests whether the DUPL-PRIMARY condition is true. If true, the value DUPL is moved to the field ERROR_STATUS_FIELD in the record CONTROL_WORKSPACE, and the ACMS task definition takes some action (sends an error message) based on finding the DUPL value. If any other error condition is true, the procedure cancels the task with the ACMS$RAISE_NONREC_EXCEPTION service. See VSI ACMS for OpenVMS Writing Applications for information about recoverable and nonrecoverable exceptions.

This procedure does not create the RMS file, nor does it open the file once it exists. A separate initialization procedure (described in Chapter 9, Building the Task Group) performs these operations. Also, this procedure does not handle the user's interactions with the terminal; DECforms does this.

Use the COBOL command to compile this procedure. By appending the /DEBUG qualifier to this command, you create the capability to debug the procedure later with the OpenVMS Debugger. By appending the /LIST qualifier, you generate a listing of your program showing any errors. (The listing file has the file type .LIS.)

$ COBOL/DEBUG/LIST EMPLOYEE_INFO_ADD

If the source file contains syntax errors, you must edit the file and recompile it until the COBOL compiler signifies that the program compiles successfully by returning to the $ prompt without any error messages. If you get error messages, make sure you typed the definition exactly as shown in Example 7.1, “COBOL Data Entry Procedure”. In particular, check that you used the appropriate punctuation.

See the COBOL documentation for information on compiling COBOL programs and interpreting COBOL error messages.

The first exchange step directs DECforms to display a panel that prompts the user for the employee number of the record to be updated. This employee number is passed to the first processing step, which retrieves the specified record from the RMS file and displays it to the user.

The first processing step calls a COBOL procedure that retrieves an employee record from the RMS master file. The retrieved record corresponds to the employee number that the user entered. The user then has an opportunity to modify employee information on the panel that displays this record.

RETRIEVE_UPDATE_INFO:
PROCESSING
  CALL GET_EMPL_INFO IN EMPL_SERVER
    USING EMPLOYEE_INFO_WKSP, EMPLOYEE_INFO_COMPARE_WKSP,
    CONTROL_WORKSPACE;

GET_EMPL_INFO is the name of the COBOL procedure that retrieves a record from the RMS file. It runs in the server EMPL_SERVER and uses three workspaces. The procedure and these workspaces are discussed later in the chapter.

The second exchange step directs DECforms to display the retrieved employee record on a panel. The user can then modify that information. When the user finishes modifying employee information, this exchange step then directs DECforms to return the updated information to ACMS.

GET_UPDATE_INFO_FROM_USER:
EXCHANGE
  TRANSCEIVE FORM RECORD EMPLOYEE_INFO_RECORD, EMPLOYEE_INFO_RECORD
    IN EMPLOYEE_INFO_LABEL
  SENDING EMPLOYEE_INFO_WKSP
  RECEIVING EMPLOYEE_INFO_WKSP
  WITH RECEIVE CONTROL QUIT_WORKSPACE;

  CONTROL FIELD IS QUIT_WORKSPACE.QUIT_KEY
       " FQUT"     :  EXIT TASK;
  END CONTROL FIELD;

The second exchange step begins with a TRANSCEIVE FORM RECORD call to DECforms naming the SEND record and the RECEIVE record involved in the TRANSCEIVE operation (in both cases here, EMPLOYEE_INFO_RECORD). The name EMPLOYEE_INFO_LABEL specifies which form to use.

The SENDING clause names the workspace sent to the form: EMPLOYEE_INFO_WKSP. The RECEIVING clause names the workspace received from the form: also EMPLOYEE_INFO_WKSP. The latter workspace contains any modifications that a user makes to the data items displayed on the form.

As you did for the first exchange step, include a CONTROL FIELD clause in your task definition so that the user can press a key to exit from the task without saving any entries.

The second processing step calls a COBOL procedure that processes the update information and places it in the RMS file.

PROCESS_UPDATE_INFO:
PROCESSING
  CALL PUT_EMPL_INFO IN EMPL_SERVER
     USING EMPLOYEE_INFO_WKSP, EMPLOYEE_INFO_COMPARE_WKSP,
        CONTROL_WORKSPACE;
  IF (CONTROL_WORKSPACE.ERROR_STATUS_FIELD EQ "CHNG")
    THEN
      MOVE "Changed by another user.  Ctrl/Z to repeat, PF4 to quit." TO
          CONTROL_WORKSPACE.MESSAGEPANEL;
    ELSE
      EXIT TASK;
  END IF;

PUT_EMPL_INFO is the name of the COBOL procedure that writes a changed record to the RMS file. It runs in EMPL_SERVER and uses the same workspaces as the retrieval procedure. The procedure and these workspaces are discussed later in the chapter.

The procedure PUT_EMPL_INFO reads this record from the RMS file and locks it. The procedure then compares this record to a copy of the original record stored in a workspace.

If the two records do not match, the record in the RMS file has been changed since the user first saw it. In that case, the user is attempting to modify an outdated version of the record. The user is notified (by means of the "changed" message) and given the opportunity to repeat (with the current version of the record) or quit (cancel the task).

If the records do match, the procedure writes the modified record to the RMS file.

The IF THEN ELSE clause tests for the CHNG value in the field ERROR_STATUS_FIELD. If the value is present, a message is stored in the MESSAGEPANEL field, and the task moves on to the third exchange step to display the message. Otherwise, if the CHNG value is not in the workspace field, control passes to the ELSE statement and ends the task successfully.

The third exchange step is nearly the same as the second exchange step in the data entry task discussed in Chapter 7, Developing the Data Entry Task. The purpose of this step is to display an error message, if the user tries to modify a record that another user just changed.

DISPLAY_ERROR_MESSAGE:
 EXCHANGE
   SEND FORM RECORD CONTROL_WORKSPACE IN EMPLOYEE_INFO_LABEL
   SENDING CONTROL_WORKSPACE
   WITH RECEIVE CONTROL QUIT_WORKSPACE;
 ACTION IS
   IF (QUIT_WORKSPACE.QUIT_KEY EQ " FQUT")
   THEN EXIT TASK;
   ELSE REPEAT TASK;
   END IF;

The Identification Division, the Environment Division, and the File Section of the Data Division for the retrieval procedure are almost identical to those for the data entry procedure (see Example 7.1, “COBOL Data Entry Procedure”). The only difference is the PROGRAM-ID, which for the retrieval procedrue is GET_EMPL_INFO. Because the data entry and retrieval procedures use the same RMS file, they must define the file identically in the SELECT and FD statements.

*****************************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. GET_EMPL_INFO.
*****************************************************************
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.       VAX-11.
OBJECT-COMPUTER.       VAX-11.

INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT EMPLOYEE-FILE
       ORGANIZATION INDEXED
       ACCESS RANDOM
       FILE STATUS IS FILE-STAT
       ASSIGN TO "xxx_FILES:EMPLOYEE.DAT".
I-O-CONTROL.
        APPLY LOCK-HOLDING ON EMPLOYEE-FILE.

*****************************************************************
DATA DIVISION.
FILE SECTION.
FD EMPLOYEE-FILE EXTERNAL
   DATA RECORD IS EMPLOYEE_INFO_WKSP
   RECORD KEY EMPL_NUMBER OF EMPLOYEE_INFO_WKSP.
COPY "EMPLOYEE_INFO_WKSP" FROM DICTIONARY.

WORKING-STORAGE SECTION.
01  FILE-STAT   PIC XX IS EXTERNAL.
    88 OK     VALUE "00".
    88 REC-LOCK     VALUE "92".

LINKAGE SECTION.
COPY "EMPLOYEE_INFO_WKSP" FROM DICTIONARY REPLACING
    ==EMPLOYEE_INFO_WKSP. == BY ==EMPLOYEE_INFO_LINKAGE_WKSP. ==.
COPY "EMPLOYEE_INFO_WKSP" FROM DICTIONARY REPLACING
    ==EMPLOYEE_INFO_WKSP. == BY ==EMPLOYEE_INFO_COMPARE_WKSP. ==.
COPY "CONTROL_WORKSPACE" FROM DICTIONARY.

*****************************************************************
PROCEDURE DIVISION USING EMPLOYEE_INFO_LINKAGE_WKSP,
      EMPLOYEE_INFO_COMPARE_WKSP, CONTROL_WORKSPACE.
DECLARATIVES.
EMPLOYEE-USE SECTION.
    USE AFTER STANDARD ERROR PROCEDURE ON EMPLOYEE-FILE.
EMPLOYEE-CHECKING.
    EVALUATE TRUE
        WHEN REC-LOCK
           MOVE "LOCK" TO ERROR_STATUS_FIELD
    END-EVALUATE.
END DECLARATIVES.

MAIN SECTION.
000-SET-STATUS.
    MOVE SPACES TO ERROR_STATUS_FIELD.

010-GET-RECORD.
    MOVE EMPL_NUMBER OF EMPLOYEE_INFO_LINKAGE_WKSP TO EMPL_NUMBER OF
      EMPLOYEE_INFO_WKSP.
    READ EMPLOYEE-FILE INTO EMPLOYEE_INFO_LINKAGE_WKSP
      ALLOWING NO OTHERS.
    MOVE EMPLOYEE_INFO_WKSP TO EMPLOYEE_INFO_COMPARE_WKSP.

100-EXIT-PROGRAM.
    UNLOCK EMPLOYEE-FILE.
    EXIT PROGRAM.

Recall that the Linkage Section lists the workspaces that ACMS passes to the procedure. The linkage workspace and the file workspace must have different names; therefore, the COPY statement includes the REPLACING clause to assign a different name to the EMPLOYEE_INFO_WKSP workspace. Like the data entry procedure, the retrieval procedure also uses CONTROL_WORKSPACE for error handling and reporting.

In the retrieval procedure, you make a copy of the record displayed to the user and store it in another workspace. The copied record is called EMPLOYEE_INFO_COMPARE_WKSP, and ACMS passes it to the update procedure to be compared with the corresponding record in the RMS file. If the record in the RMS file has changed since this task began, ACMS notifies the user that the displayed record is no longer current.

Use the COBOL command to compile the retrieval procedure. By appending the /DEBUG qualifier to this command, you create the capability to debug the procedure later with the OpenVMS Debugger. By appending the /LIST qualifier, you generate a listing of your program showing any errors. (The listing file has the file type .LIS.)

$ COBOL/DEBUG/LIST EMPLOYEE_INFO_UPDATE_GET
$

If the source file contains syntax errors, continue to edit the source file and recompile it until the program compiles successfully.

Except for the PROGRAM-ID, the update procedure is identical to the retrieval procedure until the Main Section of the Procedure Division.

IDENTIFICATION DIVISION. PROGRAM-ID. PUT_EMPL_INFO.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.  VAX-11.
OBJECT-COMPUTER.  VAX-11.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT  EMPLOYEE-FILE
        ORGANIZATION INDEXED
        ACCESS RANDOM
        FILE STATUS IS FILE-STAT
        ASSIGN TO "xxx_FILES:EMPLOYEE.DAT".
I-O-CONTROL.
        APPLY LOCK-HOLDING ON EMPLOYEE-FILE.

DATA DIVISION.
FILE SECTION.
FD      EMPLOYEE-FILE EXTERNAL
        DATA RECORD IS EMPLOYEE_INFO_WKSP
        RECORD KEY EMPL_NUMBER OF EMPLOYEE_INFO_WKSP.

        COPY "EMPLOYEE_INFO_WKSP" FROM DICTIONARY.

WORKING-STORAGE SECTION.
01  FILE-STAT                        PIC XX IS EXTERNAL.
    88 OK                              VALUE "00".
    88 REC-LOCK                        VALUE "92".

LINKAGE SECTION.
COPY "EMPLOYEE_INFO_WKSP" FROM DICTIONARY REPLACING
    ==EMPLOYEE_INFO_WKSP. == BY ==EMPLOYEE_INFO_LINKAGE_WKSP. ==.
COPY "EMPLOYEE_INFO_WKSP" FROM DICTIONARY REPLACING
    ==EMPLOYEE_INFO_WKSP. == BY ==EMPLOYEE_INFO_COMPARE_WKSP. ==.
COPY "CONTROL_WORKSPACE" FROM DICTIONARY.

PROCEDURE DIVISION USING EMPLOYEE_INFO_LINKAGE_WKSP,
    EMPLOYEE_INFO_COMPARE_WKSP, CONTROL_WORKSPACE.
DECLARATIVES.
EMPLOYEE-USE SECTION.
    USE AFTER STANDARD ERROR PROCEDURE ON EMPLOYEE-FILE.
EMPLOYEE-CHECKING.
    EVALUATE TRUE
        WHEN REC-LOCK
             MOVE "LOCK" TO ERROR_STATUS_FIELD
    END-EVALUATE. END DECLARATIVES.

MAIN SECTION.
000-SET-STATUS.
    MOVE SPACES TO ERROR_STATUS_FIELD.

010-GET-RECORD.
    MOVE EMPL_NUMBER OF EMPLOYEE_INFO_LINKAGE_WKSP TO EMPL_NUMBER OF
    EMPLOYEE_INFO_WKSP.
    READ EMPLOYEE-FILE ALLOWING NO OTHERS.
    IF ERROR-STATUS_FIELD EQUAL "LOCK"
    THEN
        GO TO 100-EXIT-PROGRAM.

020-CHECK-FOR-CHANGES.
    PERFORM 070-CHECK-RECORD.
    IF ERROR-STATUS_FIELD EQUAL "CHNG"
    THEN
    MOVE EMPLOYEE_INFO_WKSP TO EMPLOYEE_INFO_LINKAGE_WKSP
    MOVE EMPLOYEE_INFO_WKSP TO EMPLOYEE_INFO_COMPARE_WKSP
    GO TO 100-EXIT-PROGRAM.

030-REWRITE-RECORD.
    REWRITE EMPLOYEE_INFO_WKSP FROM EMPLOYEE_INFO_LINKAGE_WKSP
        ALLOWING NO OTHERS.
    GO TO 100-EXIT-PROGRAM.

070-CHECK-RECORD.
    EVALUATE
        EMPLOYEE_INFO_WKSP EQUAL EMPLOYEE_INFO_COMPARE_WKSP
        WHEN FALSE MOVE "CHNG" TO ERROR_STATUS_FIELD
    END-EVALUATE.

100-EXIT-PROGRAM.
    UNLOCK EMPLOYEE-FILE.
    EXIT PROGRAM.

Use the COBOL command to compile the update procedure. By appending the /DEBUG qualifier to this command, you create the capability to debug the procedure later with the OpenVMS Debugger. By appending the /LIST qualifier, you generate a listing of your program showing any errors. (The listing file has the file type .LIS.)

$ COBOL/DEBUG/LIST EMPLOYEE_INFO_UPDATE_PUT
$

If the source file contains syntax errors, continue to edit the source file and recompile it until the COBOL compiler completes successfully.

The initialization procedure in this tutorial performs any work that must be done before the data entry, retrieval, and update procedures in the server process can execute. For example, this initialization procedure opens an RMS file and leaves it open until the process stops. This is more efficient than opening and closing the file every time a task calls one of the three processing procedures.

Therefore, the processing procedures in this tutorial do not open and close the RMS file; instead, the file is opened in the initialization procedure and closed in the termination procedure. The initialization procedure tests the status of the open operation and stops the server process if the file was not opened successfully.

In this tutorial application, the RMS file is created the first time you use the application. Because the file being opened does not exist yet, the SELECT OPTIONAL statement in COBOL creates it.

*******************************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID.  INIT_EMPL_INFO.
*******************************************************************
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.        VAX-11.
OBJECT-COMPUTER.        VAX-11.

INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT  OPTIONAL EMPLOYEE-FILE
        ORGANIZATION INDEXED
        ACCESS RANDOM
        FILE STATUS IS FILE-STAT
        ASSIGN TO "xxx_FILES:EMPLOYEE.DAT".
I-O-CONTROL.
        APPLY LOCK-HOLDING ON EMPLOYEE-FILE.

*******************************************************************
DATA DIVISION.
FILE SECTION.
FD  EMPLOYEE-FILE EXTERNAL
    DATA RECORD IS EMPLOYEE_INFO_WKSP
    RECORD KEY EMPL_NUMBER OF EMPLOYEE_INFO_WKSP.

COPY "EMPLOYEE_INFO_WKSP" FROM DICTIONARY.

WORKING-STORAGE SECTION.
01  STATUS-RESULT                       PIC S9(9) COMP.
01  FILE-STAT                           PIC XX IS EXTERNAL.

*******************************************************************
PROCEDURE DIVISION GIVING STATUS-RESULT.
DECLARATIVES.
PERS-USE SECTION.
    USE AFTER STANDARD ERROR PROCEDURE ON EMPLOYEE-FILE.
PERS-CHECKING.
    MOVE RMS-STS OF EMPLOYEE-FILE TO STATUS-RESULT.
END DECLARATIVES.

MAIN SECTION.
000-SET-STATUS.
    SET STATUS-RESULT TO SUCCESS.

010-OPEN-FILES.
    OPEN I-O EMPLOYEE-FILE ALLOWING ALL.

100-EXIT-PROGRAM.
    EXIT PROGRAM.

Use the COBOL command to compile this procedure. By appending the /DEBUG qualifier to this command, you create the capability to debug the procedure later with the OpenVMS Debugger. By appending the /LIST qualifier, you generate a listing of your program showing any errors. (The listing file has the file type .LIS.)

$ COBOL/DEBUG/LIST EMPLOYEE_INFO_INIT
$

If the source file contains syntax errors, continue to edit the source file and recompile it until the program compiles successfully.

*******************************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID.  TERM_EMPL_INFO.

*******************************************************************
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.        VAX-11.
OBJECT-COMPUTER.        VAX-11.

INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT  EMPLOYEE-FILE
        ORGANIZATION INDEXED
        ACCESS RANDOM
        FILE STATUS IS FILE-STAT
        ASSIGN TO "xxx_FILES:EMPLOYEE.DAT".
I-O-CONTROL.
        APPLY LOCK-HOLDING ON EMPLOYEE-FILE.

*******************************************************************
DATA DIVISION.
FILE SECTION
FD  EMPLOYEE-FILE EXTERNAL
    DATA RECORD IS EMPLOYEE_INFO_WKSP
    RECORD KEY EMPL_NUMBER OF EMPLOYEE_INFO_WKSP.

COPY "EMPLOYEE_INFO_WKSP" FROM DICTIONARY.

WORKING-STORAGE SECTION.
01  STATUS-RESULT                       PIC S9(9) COMP.
01  FILE-STAT                           PIC XX IS EXTERNAL.

*******************************************************************
PROCEDURE DIVISION GIVING STATUS-RESULT.
DECLARATIVES.
PERS-USE SECTION.
    USE AFTER STANDARD ERROR PROCEDURE ON EMPLOYEE-FILE.
PERS-CHECKING.
    MOVE RMS-STS OF EMPLOYEE-FILE TO STATUS-RESULT.
END DECLARATIVES.

MAIN SECTION.
000-SET-STATUS.
    SET STATUS-RESULT TO SUCCESS.

010-CLOSE-FILES.
    CLOSE EMPLOYEE-FILE.

100-EXIT-PROGRAM.
    EXIT PROGRAM.

Use the COBOL command to compile this procedure. By appending the /DEBUG qualifier to this command, you create the capability to debug the procedure later with the OpenVMS Debugger. By appending the /LIST qualifier, you generate a listing of your program showing any errors. (The listing file has the file type .LIS.)

$ COBOL/DEBUG/LIST EMPLOYEE_INFO_TERM
$

If the source file contains syntax errors, continue to edit the source file and recompile it until the program compiles successfully.

*******************************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID.  CANCEL_EMPL_INFO.

*******************************************************************
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.        VAX-11.
OBJECT-COMPUTER.        VAX-11.

INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT  EMPLOYEE-FILE
        ORGANIZATION INDEXED
        ACCESS RANDOM
        FILE STATUS IS FILE-STAT
        ASSIGN TO "xxx_FILES:EMPLOYEE.DAT".
I-O-CONTROL.
        APPLY LOCK-HOLDING ON EMPLOYEE-FILE.

*******************************************************************
DATA DIVISION.
FILE SECTION.
FD  EMPLOYEE-FILE EXTERNAL
    DATA RECORD IS EMPLOYEE-INFO_WKSP
    RECORD KEY EMPL_NUMBER OF EMPLOYEE_INFO_WKSP.

COPY "EMPLOYEE_INFO_WKSP" FROM DICTIONARY.

WORKING-STORAGE SECTION.
01  STATUS-RESULT                       PIC S9(9) COMP.
01  FILE-STAT                           PIC XX IS EXTERNAL.

*******************************************************************
PROCEDURE DIVISION GIVING STATUS-RESULT.
DECLARATIVES.
PERS-USE SECTION.
    USE AFTER STANDARD ERROR PROCEDURE ON EMPLOYEE-FILE.
PERS-CHECKING.
    MOVE RMS-STS OF EMPLOYEE-FILE TO STATUS-RESULT.
END DECLARATIVES.

MAIN SECTION.
000-SET-STATUS.
    SET STATUS-RESULT TO SUCCESS.

010-UNLOCK-FILES.
    UNLOCK EMPLOYEE-FILE.

100-EXIT-PROGRAM.
    EXIT PROGRAM.

Use the COBOL command to compile this procedure. By appending the /DEBUG qualifier to this command, you create the capability to debug the procedure later with the OpenVMS Debugger. By appending the /LIST qualifier, you generate a listing of your program showing any errors. (The listing file has the file type .LIS.)

$ COBOL/DEBUG/LIST EMPLOYEE_INFO_CANCEL
$

If the source file contains syntax errors, continue to edit the source file and recompile it until the program compiles successfully.

TASKS ARE
  EMPLOYEE_INFO_ADD_TASK : TASK IS EMPLOYEE_INFO_ADD_TASK;
  EMPLOYEE_INFO_UPDATE_TASK : TASK IS EMPLOYEE_INFO_UPDATE_TASK;
END TASKS;

The task name on the right hand side of the colon is as you defined it in CDD. The task name on the left hand side of the colon can be any unique name you create to identify the task and does not need to match the task name on the right hand side, but using different names is more often confusing than useful. You use the task names on the left hand side later in the application definition to assign different characteristics to individual tasks.

$ CDO
CDO> DIRECTORY
   CONTROL_WORKSPACE;1                            RECORD
   EMPLOYEE_INFO_ADD_TASK;1                       ACMS$TASK
   EMPLOYEE_INFO_TASK_GROUP;1                     ACMS$TASK_GROUP
   EMPLOYEE_INFO_UPDATE_TASK;1                    ACMS$TASK
   EMPLOYEE_INFO_WKSP;1                           RECORD
   .
   .
   .
CDO>

The DIRECTORY command displays the names of items in CDD and indicates the type of each item: CDD record or field, ACMS task or task group.

You can now build the task group with the ADU BUILD command. This command produces two new files: a task group database file and a procedure server object module. The task group database is an RMS file that contains binary versions of the tasks and information about how to process them. At run time, ACMS executes the tasks in their binary form rather than as ADU source commands. The procedure server object module controls the procedures that run in the same server.

$ ADU
ADU> BUILD GROUP EMPLOYEE_INFO_TASK_GROUP/DEBUG
ADU>

If the BUILD command succeeds, ADU displays a "Writing TDB...object module created" sequence of messages. When ADU processes this command, it creates the task group database file EMPLOYEE_INFO_TASK_GROUP.TDB. It also creates a procedure server transfer module called EMPL_SERVER.OBJ. In the following section, you link this object module with all the procedure object modules to produce the procedure server image.

If the BUILD command fails, ADU issues error messages and redisplays the ADU> prompt. Correct the errors and resubmit the task group definition to ADU, repeating this sequence until the definition processes without errors.

Exit from ADU.

Every server in an application has an OpenVMS user name. By default, a server uses the application user name as its OpenVMS user name. For most applications, however, use a different OpenVMS account for the server, because the server usually requires fewer privileges and lower quotas than an application. The application definition specifies the name EMPL_SERVER. Chapter 12, System Management Requirements for Installing the Tutorial Application describes how your system manager creates the account EMPL_SERVER.

SERVER DEFAULTS ARE
    AUDIT;
    USERNAME IS EMPL_SERVER;
    MINIMUM SERVER PROCESSES IS 1;
    MAXIMUM SERVER PROCESSES IS 1;
END SERVER DEFAULTS;

The AUDIT clause generates audit trail information for the server. The USERNAME clause names EMPL_SERVER as the account in which the server runs.

ACMS lets you control both the minimum and maximum number of server processes used for your application. Servers are serially reusable, so they can be created once and used several times by the application. The MINIMUM SERVER PROCESSES and MAXIMUM SERVER PROCESSES clauses specify that only one server process be created for the application. Specifying the same number for the minimum and the maximum can greatly improve the performance of your application, provided that the number of processes is adequate for the number of users.