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

This appendix lists the source files created in the tutorial application in Part 2 and describes how to access the online versions of these files. You can view the online source files to verify those that you create in the tutorial, or you can copy the online source files instead of typing them yourself.

B.1 Source Files

The following list contains the names of each source file created in the tutorial. The files are listed in the order that they appear in the manual.

• EMPLOYEE_FIELDS.CDO
• EMPLOYEE_INFO_RECORD.CDO
• EMPLOYEE_INFO_WKSP.CDO
• EMPLOYEE_INFO_FORM.IFDL
• EMPLOYEE_CONTROL_FIELDS.CDO
• EMPLOYEE_CONTROL_WKSP.CDO
• EMPLOYEE_QUIT_FIELD.CDO
• EMPLOYEE_QUIT_WKSP.CDO
• EMPLOYEE_INFO_ADD_TASK.TDF
• EMPLOYEE_INFO_ADD.COB
• EMPLOYEE_INFO_PROMPT_FORM.IFDL
• EMPLOYEE_INFO_UPDATE_TASK.TDF
• EMPLOYEE_INFO_UPDATE_GET.COB
• EMPLOYEE_INFO_UPDATE_PUT.COB
• EMPLOYEE_INFO_INIT.COB
• EMPLOYEE_INFO_TERM.COB
• EMPLOYEE_INFO_CANCEL.COB
• EMPLOYEE_INFO_TASK_GROUP.GDF
• EMPLOYEE_INFO_APPL_XXX.ADF
• EMPLOYEE_INFO_MENU.MDF

The source files are installed by the ACMS installation procedure if your system manager chooses to install the ACMS samples. These files are located in ACMS$EXAMPLES, a logical that points to the actual directory. The following command displays the contents of that directory:

$ DIRECTORY ACMS$EXAMPLES

The following command displays the file named EMPLOYEE_FIELDS.CDO:

$ TYPE ACMS$EXAMPLES:EMPLOYEE_FIELDS.CDO

You may wish to copy these files to your default directory instead of typing them yourself. Copying the source code files saves time in performing the tutorial, but you may gain more by typing them in progressive steps while reading about what the code does. Moreover, copying the two DECforms IFDL files means that your forms and panels are already created, nullifying the portion of the tutorial that illustrates how to create them interactively within the DECforms environment.

You can copy single files using the normal method. However, if you want to copy all the source files, you can perform a wildcard copy with one command. Use the following commands to locate yourself in your default directory (filling in your disk and user name) and to copy all the tutorial source files to this directory:

$ SET DEFAULT udisk:[uname] $ COPY ACMS$EXAMPLES:EMPLOYEE*.* *.*

If you copy the online source files, rename the application definition file EMPLOYEE_INFO_APPL_xxx.ADF, filling in your initials or other unique characters for the xxx part of the name. Using a unique application name avoids conflicts with applications created by others who may be entering this tutorial on your system. When you rename this file, you must also edit this file to make the same name change in the first line of the file (see Section 10.1.1); you must also edit the file EMPLOYEE_INFO_MENU.MDF to make the same name change there (two occurrences).

If you copy the online source files, you must edit the files that contain the logical xxx_FILES and replace that logical with the one that you defined for your directory in Section 7.6. Those files that contain the xxx_FILES logical are the six .COB files (one occurrence each), EMPLOYEE_INFO_TASK_GROUP.GDF (three occurrences), and EMPLOYEE_INFO_APPL_XXX.ADF (one occurrence).

This glossary contains terms from all books in the ACMS documentation set.

AAU: See Application Authorization Utility.

ACC: See ACMS Central Controller.

access control list (ACL): A table that lists the users allowed access to an object and indicates the kind of access they are allowed. For example, you can use ACLs on ACMS tasks to control user access to that task.

See also privilege.

ACID: An acronym for the four properties of legal database transactions and distributed transactions. The four properties are atomicity, consistency, isolation, and durability.

ACL: See access control list.

ACMS: ACMS software, a transaction processing monitor that is layered on the OpenVMS operating system, defines, runs, and controls transaction processing applications. You can use ACMS to control existing applications and applications developed with ACMS. It provides a task implementation method that uses high-level definitions to replace complex application code. These definitions reduce the programming time and maintenance costs of traditional application programs that do comparable work. ACMS supports offloaded terminal processing, which allows the execution of ACMS tasks on remote nodes.

See also distributed transaction processing and transaction processing.

ACMS Central Controller (ACC): The ACMS process that serves as the central control point for the ACMS run-time system.

ACMSDBG: See ACMS Task Debugger.

ACMSGEN Utility: An ACMS utility that lets system managers change ACMS system parameters, such as the number of users who can log in, the user names under which ACMS processes run, and the priorities of these processes. This utility is similar to the OpenVMS SYSGEN Utility.

ACMS operator: An ACMS user authorized to use the ACMS operator commands to control the daily operations of ACMS system software and applications.

ACMS operator command: One of a number of DCL commands provided by ACMS to control the operations of the ACMS system software and applications. Many ACMS operator commands require the OpenVMS OPER privilege.

ACMSQUEMGR: See Queue Manager Utility.

ACMS Task Debugger (ACMSDBG): An ACMS debugging tool that allows you to move through a task to examine how a task branches from one task step to the next. The Task Debugger uses task group databases and procedure server images; it does not require application definitions, menu definitions, or a running ACMS system.

See also multiple-step task and procedure server.

action: See step action.

ADB: See application database.

ADU: See Application Definition Utility.

agent: An OpenVMS process through which one or more ACMS task submitters access the ACMS run-time system. All ACMS users access tasks through an agent. ACMS provides the Command Process (CP) as an agent for terminal users.

An ACMS request interface agent allows users to write and use terminal interfaces other than DECforms to access ACMS. An ACMS systems interface agent allows users to write and use nonterminal interfaces such as badge or barcode readers to access ACMS.

See also Command Process (CP).

agent program: A program that invokes a task that executes in an ACMS application.

ANSI (American National Standards Institute): The American industry-wide standards committee responsible for proposing standards. ANSI proposes software standards for programming languages, databases, and other software products.

See also CODASYL and ISO.

application: In ACMS, a set of tasks that are related by the business activity they support and that are controlled as a single unit. An ACMS application is defined with the ACMS Application Definition Utility (ADU) and runs under the control of the ACMS run-time system. An application definition specifies operational characteristics for the tasks and servers of the task groups that make up the application.

application authorization file: A file, ACMSAAF.DAT, created by and maintained with the Application Authorization Utility (AAU). This file contains a list of applications authorized for installation, and definitions describing what characteristics are allowed for those applications and who is authorized to install them.

Application Authorization Utility (AAU): An ACMS utility that allows a system manager to define which applications can be installed, what characteristics the applications can have, and who can install them.

application database (ADB): In ACMS, a binary file accessed at run time that describes the operational characteristics of all tasks and servers in an application. You generate an application database by building an application definition with ADU. The ACMS run-time system uses application databases to determine which processes to start, when to start them, and which users have access to which tasks.

See also application definition.

application definition: In ACMS, the specification of the run-time characteristics for an ACMS application and its servers and tasks. You write an application definition using the ADU. After creating the definition, you use ADU to build the application database, which is the binary version of the definition file.

See also application database.

Application Definition Utility (ADU): The primary tool for creating ACMS applications. The Application Definition Utility provides the commands and clauses for defining tasks, task groups, applications, and menus.

Application Execution Controller (EXC): The ACMS component that controls task execution for all the tasks in an application. Each application has its own Application Execution Controller. Application Execution Controllers start up and control the server processes needed to handle processing work for tasks. They also handle exchange steps, step actions, and the sequencing of steps for tasks defined with ACMS. Application Execution Controllers reference application databases, task databases, form files, request libraries, and message files.

application node: The back end of a distributed transaction processing system, on which data manipulation and computation are handled. The application resides on the application node. Resource managers that perform data processing can also reside on the application node, or may reside on other remote nodes.

See also back end, front end, and submitter node.

application specification: A specification for an ACMS application that can consist of an application name, a logical name, a node name and file name, or a logical name and file name. Use application specifications in ADU clauses to identify applications on single-node or multiple-node ACMS systems.

See also Application Definition Utility (ADU).

atomicity: A characteristic of database transactions and distributed transactions. If an atomic transaction fails, any changes made to a database, file, or ACMS queue are rolled back to their original state.

See also database transaction, distributed transaction, and recovery unit.

Audit Trail Logger (ATL): In ACMS, a monitoring tool that has a recording facility and a utility for generating reports. The recording facility gathers information about a running ACMS system, including information about system and application starts and stops, user sign-ins and sign-outs, processing errors, user task selections, task completions, and task cancellations. The report utility (ATR) generates summary reports of this information.

back end: The data and computational processes in a transaction processing system in which terminal and menu functions are handled by separate processes. The back-end processes include the EXC and server processes.

Front-end processes can be shifted to a separate computer, OpenVMS Cluster network, or Local Area OpenVMS Cluster network to increase system performance.

See also front end.

block conditional clause: One of four statements of a task definition language. You can use a block conditional clause in an ACMS task to make initial exchange and processing work dependent on the values of workspace fields.

block step: One of three kinds of steps used to define the work of a multiple-step task. A block step definition has three parts: attributes, work, and action.

See also exchange step and processing step.

called task: A task that is invoked, or called by, another ACMS task. The task that calls the called task is known as a parent task.

See also parent task.

cancel action: A procedure or image called by an ACMS task when the task is canceled. The cancel action does cleanup work for the task, such as recovering from incomplete operations. It does not release locks or perform other work specific to a server.

cancel procedure: A procedure called by ACMS to clean up any context held by a task in a server. The cancel procedure does cleanup work for the server process, such as releasing record locks, so that the process can be used again without being restarted. When a cancel procedure is called, it runs in the server process allocated to the task, whether or not the task is using the server process at the time of the cancellation.

CDD (Common Data Dictionary): See CDD data dictionary system.

CDD data dictionary system: A data dictionary system consisting of a hierarchy of directories that contain definitions used by VAX and Alpha transaction processing products. The CDD dictionary contains descriptions of data, not the data itself. CDD objects are stored hierarchically and accessed by reference to dictionary path names.

centralized transaction processing: A TP system in which all TP components run on the same computer.

cluster: See OpenVMS Cluster network.

CODASYL (Conference on Data Systems Language): The industry-wide standards committee responsible for proposing standard data definition and data manipulation languages for databases conforming to the network model. The CODASYL committee is also responsible for proposing the Form Interface Management System (FIMS) standard.

See also ANSI, Form Interface Management System, and ISO.

Command Process (CP): The ACMS process that handles user logins and the interaction between terminals and ACMS.

See also agent.

commit: To make permanent changes to a resource during a database or distributed transaction.

composable task: A task written in such a way that it can be called to participate in a distributed transaction started by a parent task or an agent.

See also distributed transaction and parent task.

concurrency: The method of controlling conflicts and contention when simultaneous updates to a database occur.

conditional clause: One of four statements of the task definition language. You can use conditional clauses in an ACMS task to make exchange, processing, or action clauses dependent on the values of workspace fields.

consistency: A characteristic of a transaction. A transaction has consistency if it successfully modifies the system and the database from one valid state to another.

CP: See Command Process.

database management system: A system for creating, maintaining, and accessing a collection of interrelated data records that can be processed by one or more applications without regard to physical storage. Data is described independently of application programs, providing ease in application development, data security, and data visibility.

Note that the acronym DBMS is often used to mean database management system. Do not confuse this generic use of the term DBMS with references to the specific Oracle CODASYL DBMS software product. a CODASYL-compliant database management system.

database manager: See resource manager.

database transaction: A set of updates to recoverable resources, such as files and databases. Database transactions have the properties of atomicity, consistency, isolation, and durability.

See also atomicity, distributed transaction, recovery unit, and resource manager.

data resource: A collection of data items that represent business information.

DBMS: A CODASYL-compliant database management product. You can use DBMS to access and administer databases ranging in complexity from simple hierarchies to complex networks with multilevel relationships.

Note that the acronym DBMS is often used to mean database management system. Do not confuse this generic use of the term DBMS with references to the specific Oracle CODASYL DBMS software product.

See also database management system.

DCL: See DIGITAL Command Language.

DCL command procedure: A sequence of DIGITAL Command Language (DCL) commands stored in a file; sometimes referred to as a DCL procedure.

DCL server: One of two types of servers used to handle processing work for ACMS tasks. A DCL server handles images, DCL commands, and command procedures.

See also DCL server image, procedure server, and server image.

DCL server image: The image provided by ACMS that is loaded into a DCL server process when the process is started by the EXC. The DCL server image lets you use images, DCL commands, and procedures to implement processing for tasks.

See also Application Execution Controller (EXC) and procedure server image.

DCL server process: See server process.

DDU: See Device Definition Utility.

deadlock: A situation in which two or more processes request the same set of resources and there is no method for resolving the conflict, except to reject all but one of the processes. For example, if process A has record 1 locked and requests record 2, while process B has record 2 locked and is requesting record 1, a deadlock occurs between processes A and B.

DECdtm services for OpenVMS: A collection of OpenVMS services providing management of distributed transactions. DECdtm services implement a two-phase commit protocol. ACMS uses DECdtm services as its transaction manager.

See also distributed transaction and two-phase commit (2PC) protocol.

DECforms: A forms product running on the OpenVMS operating system that integrates text and graphics into forms and menus, and displays them on a terminal screen. DECforms also provides extensive facilities for specifying full control of the user interface from within the form rather than in the application program.

DECnet/VAX: The DIGITAL software facility that implements the DIGITAL Network Architecture (DNA) to let a user access information on a remote computer through telecommunications lines. DECnet/VAX enables an OpenVMS system to function as a network node.

See also DIGITAL Network Architecture (DNA).

default: The value of an argument, field, or part of a command line assumed by a program if the specific value is not supplied by the user.

default directory: The directory from which the OpenVMS system reads and to which it writes all files that you create unless you explicitly name a directory.

See also directory.

device definition file: A file, created and maintained with the ACMS Device Definition Utility (DDU), that contains a list of terminals from which users can access ACMS, and information specifying whether the terminals can access both ACMS and OpenVMS, or only ACMS.

Device Definition Utility (DDU): The ACMS tool for defining which terminals have access to ACMS and what characteristics those terminals have.

dictionary object: A data definition stored in a CDD dictionary.

See also CDD data dictionary system.

DIGITAL Command Language (DCL): A command interpreter for the OpenVMS system.

DIGITAL Network Architecture (DNA): A description of network structure, operation control, and protocols (rules) developed by Digital Equipment Corporation.

directory: A file that catalogs a set of files stored on disk or tape. The directory includes the name, type, and version number of each file in the set.

See also default directory.

directory anchor: In CDD, the specification of the OpenVMS directory where the CDD hierarchy is stored. The anchor is followed by the dictionary path. The specification DISK1:[CDDPLUS] is an example of a directory anchor.

distributed application: An application that uses a network for remote access to a database or another application.

distributed transaction: The grouping of operations on files and databases into a single transaction. Distributed transactions have the properties of atomicity, consistency, isolation, and durability and can include more than one type of resource manager.