ACMS applications are made up of tasks. Typically, these tasks are defined using the ACMS Application Definition Utility (ADU), as described in the preceding chapters. However, it is possible that you have existing programs or applications that you did not define using ACMS. Such applications might include OpenVMS images, DATATRIEVE commands and procedures, or DCL commands and command procedures. You can include these existing programs as tasks in your ACMS application.

This chapter explains how to include these types of applications in an ACMS application.

13.1 Defining Single-Step Tasks in ACMS Task Groups

To include existing OpenVMS images, DATATRIEVE commands or procedures, or DCL commands or procedures in your application, you must define them as single-step tasks in the task group definition.

You specify single-step tasks using the TASKS clause in the same way you specify a multiple-step task. However, rather than specifying a CDD pathname for a multiple-step task definition, you specify the executable image, DCL command, or DATATRIEVE procedure that you want to run.

The following sections explain how to include the following as single-step tasks in ACMS task group definitions:

• OpenVMS images
• DCL commands and command procedures
• DATATRIEVE commands and procedures

Many applications include programs that perform certain tasks. Suppose you have a program, written in a language that adheres to the OpenVMS Calling Standard, that you want to include as a task in your ACMS application. You use, as part of the TASKS clause, the IMAGE processing subclause to define an OpenVMS image as a task in a task group. For example:

TASKS ARE EMPLOYEE : PROCESSING IMAGE "SYS$SAMPLE:EMPLOYEE.EXE"; . . .

The name you assign to the task can contain up to 31 alphanumeric characters, dollar signs, and underscores, but no embedded blanks. In this example, the task named EMPLOYEE runs an OpenVMS image with the file specification SYS$SAMPLE:EMPLOYEE.EXE. If you do not specify a default device and directory, ACMS uses the current default device and directory by default. You begin the IMAGE subclause with the keyword PROCESSING. Follow the keyword with IMAGE and, in quotation marks, the image name. End the subclause with a semicolon (;).

13.1.2 Defining DCL Commands and Command Procedures as Tasks

It is common for applications to include editing and mail functions that users can select and run. For example, you may want to include the DCL commands EDIT and MAIL as tasks in your ACMS application. You use the DCL COMMAND subclause to describe tasks that consist of DCL commands or command procedures.

TASKS ARE EMPLOYEE : PROCESSING IMAGE "SYS$SAMPLE:EMPLOYEE.EXE"; EDIT : PROCESSING DCL COMMAND "$EDIT/EDT 'P1'"; MAIL : PROCESSING DCL COMMAND "$MAIL"; . . .

When a user selects the EDIT task, ACMS invokes the EDIT/EDT command. When selecting the task, the user can supply a string that ACMS passes to the task as the parameter, P1. For the EDIT command, this parameter is the name of the input file for the editing session. The MAIL task invokes the DCL MAIL command, allowing the user to read and send mail.

When you use the DCL COMMAND subclause, precede the subclause with the PROCESSING keyword. Be sure to enclose the command in quotation marks ("") and begin the command with the dollar sign ($). You must also end the subclause with a semicolon (;).

13.1.3 Defining DATATRIEVE Commands and Procedures as Tasks

If you have DATATRIEVE commands and procedures that you want to include in your ACMS application, use the DATATRIEVE COMMAND subclause to name them in a task group definition. For example, suppose you have a DATATRIEVE procedure that produces a report outlining all the performance reviews that are due for a department. The following TASKS clause names the DUE task that runs a DATATRIEVE procedure.

TASKS ARE EMPLOYEE : PROCESSING IMAGE "SYS$SAMPLE:EMPLOYEE.EXE"; EDTR : PROCESSING DCL COMMAND "$EDIT/EDT 'P1'"; MAIL : PROCESSING DCL COMMAND "$MAIL"; DUE : PROCESSING DTR COMMAND IS "DISK1:[CDDPLUS]ACMS$DIR.ACMS$EXAMPLES_RMS.DUE"; END TASKS;

The DUE task uses a DATATRIEVE procedure stored in the directory. You must enclose the command string in quotation marks ("") and end the subclause with a semicolon (;).

When you use the DTR COMMAND processing subclause, ACMS uses the image DTR32 by default. If you want to use another image, you must define DTR32 as a logical that points to the DATATRIEVE image you want to run.

Once you have named all the tasks for a TASKS clause, use the END TASKS keywords followed by a semicolon (;). You can use more than one TASKS clause in a single task group definition and can include one or more tasks in each TASKS clause.

After deciding which tasks to include in a task group, you must define servers to handle processing for those tasks.

13.2 Defining Servers to Handle Processing

Servers handle the processing work for the tasks in an application. There are two kinds of servers: procedure servers and DCL servers. Procedure servers handle calls to subroutines and are typically used for processing steps of multiple-step tasks defined with ADU. DCL servers handle the processing work for tasks that run OpenVMS images, DCL commands or command procedures, and DATATRIEVE commands or procedures.

If you are including single-step tasks in your ACMS application, you must define one or more DCL servers to handle the processing work for those tasks. If the task group already includes a DCL server, that server may be able to handle the work for any tasks you are including. However, you may need to name one or more additional servers to handle the processing work for tasks you add to the task group.

You can use the SERVERS clause and its subclauses to name and describe servers for the tasks in a task group. The syntax for the server subclauses is similar to the syntax of the SERVER ATTRIBUTES clause you use in an application definition. For example:

SERVER IS EMPLOYEE_SERVER : DCL PROCESS; END SERVER;

Here the SERVERS clause names one server, EMPLOYEE_SERVER. The server subclause DCL PROCESS indicates that the server is a DCL server rather than a procedure server. The DCL PROCESS subclause is the only required subclause of the SERVERS clause.

You can also define other server attributes in the SERVERS clause such as the DYNAMIC USERNAME and USERNAME OF TERMINAL USER. However, because these are control attributes, they can be overridden in the SERVER ATTRIBUTES clause of the application definition. (See Chapter 11 for more information.)

To enable terminal users to receive their own mail, edit their own files, or use DATATRIEVE against files in their own directories, you must define a dynamic user name for the server, EMPLOYEE_SERVER. When you use the DYNAMIC USERNAME subclause to define a server process, ACMS changes the user name, UIC, and default directory of the task to those of the user selecting a task processed by that server. Chapter 11 explains in more detail how to use the DYNAMIC USERNAME subclause.

There are two ways to assign servers to tasks in a task group. One way is to position the TASKS clause under the SERVERS clause containing the servers you want the tasks to use. In this case, the tasks in the TASKS clause will be assigned the server defined above them in the SERVERS clause, which is the default server in effect.

In Example 13-1, the EMPLOYEE_SERVER is assigned to the EMPLOYEE, EDIT, MAIL, and DUE tasks because the TASKS clause follows the SERVERS clause in the task group definition.

Example 13-1 A Task Group Definition

REPLACE GROUP ADMINISTRATION_GROUP DEFAULT TASK GROUP FILE IS "ACMS$EXAMPLES:ADMRMSCOB.TDB"; SERVER IS EMPLOYEE_SERVER : DCL PROCESS; DYNAMIC USERNAME; END SERVER; TASKS ARE EMPLOYEE : PROCESSING IMAGE "SYS$SAMPLE:EMPLOYEE.EXE"; EDIT : PROCESSING DCL COMMAND "$EDIT/EDT 'P1'"; MAIL : PROCESSING DCL COMMAND "$MAIL"; DUE : PROCESSING DTR COMMAND IS "DISK1:[CDDPLUS]ACMS$DIR.ACMS$EXAMPLES_RMS.DUE"; END TASKS; END DEFINITION;

The other way to define servers for tasks is to name specific servers for specific tasks in the TASKS clause. For example:

TASKS ARE EMPLOYEE : PROCESSING IMAGE "SYS$SAMPLE:EMPLOYEE.EXE" IN EMPLOYEE_SERVER; EDIT : PROCESSING DCL COMMAND "$EDIT/EDT 'P1'" IN EMPLOYEE_SERVER; MAIL : PROCESSING DCL COMMAND "$MAIL" IN EMPLOYEE_SERVER; DUE : PROCESSING DTR COMMAND IS "DISK1:[CDDPLUS]ACMS$DIR.ACMS$EXAMPLES_RMS.DUE" IN EMPLOYEE_SERVER; END TASKS;

In the TASKS clause, EMPLOYEE_SERVER is individually assigned to the EMPLOYEE, EDIT, MAIL, and DUE tasks in the IN SERVER phrase of the TASKS clause in the processing subclause for each task.

The task group definition in Example 13-1 lists only tasks that use a DCL server and that were not defined using ADU. However, you can include ACMS multiple-step tasks as well as definitions for already existing tasks in a single task group definition.

13.3 Using the Task Group in an Application

Once you have included existing tasks in a task group, you must consider the effect of those tasks and that task group on the application. You need to change the application definition if:

• You want to change control attributes for tasks or servers named in the modified task group
• You created a new task group definition and must include the name of that group in the TASK GROUPS clause of the application definition

Whether or not you make changes to the application definition, you must rebuild it to create a run-time application database that includes the new tasks. You must also:

• Add new tasks to existing menu definitions or create new menu definitions
• Rebuild modified menu definitions and build new menu definitions

ACMS provides great flexibility in collecting user input for processing in an application. You can use DECforms, TDMS, the ACMS Request Interface, the ACMS Systems Interface, or a combination of these tools to capture data for use in an ACMS application. This chapter discusses the ACMS Request Interface and how to use it in an ACMS application.

The examples shown in this chapter are taken from the request interface examples located in the SYS$COMMON:[SYSHLP.EXAMPLES.ACMS.RI] directory, which the logical ACMS$RI_EXAMPLES points to. For ease of use, the components of the ACMS$RI_EXAMPLES directory are listed in Appendix E.

14.1 Overview of the ACMS Request Interface

The ACMS Request Interface (RI) provides an alternate method of doing request I/O from an ACMS task during processing. You can use a combination of DECforms I/O, TDMS Request I/O and/or the RI, Stream I/O, or Terminal I/O in different tasks within the same application. You can use a combination of TDMS Request I/O and the RI in a single task definition on a per-request-library basis. However, you cannot use the RI in conjunction with DECforms I/O or Stream I/O in the same task.

While DECforms and TDMS limit you to collecting user input from DECforms- and TDMS-supported terminals, the RI allows use of other I/O methods such as FMS, SMG, third-party forms products, OpenVMS mailboxes, DECnet task-to-task communication, and OpenVMS QIOs. Using the RI allows you to take advantage of several interactive facilities that are not available with TDMS or DECforms:

• 3270 terminal support
• Multiwindow support
• Graphics support

The RI provides the flexibility of choosing an interface to ACMS without impacting the multiple-step task structure or ease-of-maintenance features inherent in an ACMS application. The RI simply provides a mechanism for executing user-written request procedures (URPs) that perform their own I/O in place of TDMS requests. You write a URP in any OpenVMS-supported, high-level language and include the necessary facility calls (for example, FMS, SMG, QIO) for interfacing ACMS with the preferred device.

ACMS multiple-step tasks call URPs from a task definition using the same syntax necessary to call TDMS requests. The RI translates a logical name and uses the resulting translation to determine if it should process a TDMS request or execute a URP from a shareable image.

ACMS supplies a multi-user agent program called the command process (CP), through which DECforms and TDMS terminal users can access ACMS tasks. With the RI, you use a single-user agent to access ACMS tasks. ACMS supplies an agent called ACMS$RI_AGENT that you can use to select tasks that use the RI. Either use the ACMS-supplied RI agent, or, if an application requires it, write a customized, single-threaded RI agent. Code an RI agent in any high-level language that adheres to the OpenVMS calling standard.

Never use the RI if an application requires asynchronous processing or multithreaded processing (one process handling the needs of several users). Instead, you must use the SI services to write a multithreaded agent.

The Request Interface consists of four major components:

• Request Interface agent
  You use an RI agent in place of the ACMS-supplied command process. The RI agent enables the RI so that you can interface non-TDMS devices with ACMS. Note that the standard ACMS menu interface is available only with CP. However, the ACMS-supplied RI agent program ACMS$RI_AGENT allows you to develop your own menu interface.
• User-written request procedures (URPs)
  The RI calls URPs to perform the exchange work for an ACMS task. A URP is a procedure that replaces a TDMS request in an exchange step and is responsible for performing the I/O to the user's device. A group of URPs is linked together into a shareable image that replaces a TDMS request library (.RLB). You can write URPs in any high-level language; include the appropriate facility calls (for example, FMS, SMG, QIO) to interface ACMS with the preferred device.
• ACMRRSHR
  This ACMS shareable image is responsible for calling a TDMS request or a URP based on the translation of an ACMS$RI_LIB logical name. You can, optionally, define an ACMS$RI_LIB logical to point to a TDMS request library (RLB) or to a URP shareable image (EXE). At run time, ACMRRSHR translates the ACMS$RI_LIB logical to determine if the agent should or perform TDMS or RI I/O during the exchange step.
• Menu interface
  You use this component to develop a menu interface that can be processed by the RI ACMS$RI_AGENT program. For example, you can develop a routine that uses FMS calls to display a menu on an FMS-supported device and to accept a task selection from the user.

Figure 14-1 shows the four RI run-time components and their relationship with ACMS.

Figure 14-1 Request Interface Run-Time Components

This chapter describes these components in more detail and explains how to incorporate the Request Interface in an ACMS application.

14.2 The Request Interface and the ACMS Run-Time System

The ACMS Command Process (CP) uses DECforms or TDMS to interact with the terminal user. If you use the RI, you cannot use the CP; you must, instead, use either the ACMS-supplied RI agent or develop an RI agent that does the following:

1. Signs in the user to ACMS
2. Enables the Request Interface
3. Repeatedly prompts the user for task selection information and then calls the task, until the user wants to exit ACMS
4. Disables the Request Interface
5. Signs the user out of ACMS

Note that the URPs that ACMS calls to perform the exchange I/O are not linked into the RI agent image. URPs are called by the ACMRRSHR shareable image, not by the RI agent program.

This section describes how the RI interacts with the ACMS run-time system and the impact it has on ACMS system performance.

When you use the RI (either locally or with distributed applications), the RI agent process always handles the I/O defined in exchange steps. Since the RI is a synchronous interface, it can be used only in a single-threaded agent. Therefore, users must each have their own process that executes the RI agent. Contrast this with the ACMS-supplied CP agent that is a multithreaded, asynchronous agent that can support multiple users in a single process.

Figure 14-2 shows one multithreaded CP agent and two single-threaded RI agents interfacing with the same ACMS application execution controller.

As Figure 14-2 shows, an ACMS system can include more than one agent process. Also, a single Application Execution Controller (EXC) can pass request information and handle flow control and scheduling for different types of agent programs. The EXC is a multithreaded process for flow control and scheduling. It interprets the definitions of the tasks in an application. The same performance benefits are realized from ACMS on the processing end (back end) of the system regardless of the I/O method (DECforms, TDMS, or RI) used.

An application can lose performance when using the RI on the front-end system because of the synchronous nature of the Request Interface. Since a single CP agent process supports multiple users, it uses less system resources than a single-user RI agent, where individual users must have their own process. For example, 40 users each running their own copy of a single-user RI agent will often use more memory than two CP agent processes, each handling 20 users.

If an application requires a multithreaded and asynchronous agent, you must use the ACMS Systems Interface to develop an SI agent; you cannot use the RI for multithreaded, asynchronous processing. However, you cannot use asynchronous processing if the interface you want to use is synchronous (such as FMS or SMG). See Compaq ACMS for OpenVMS Systems Interface Programming for more information about the Systems Interface.

Figure 14-2 Request Interface Model

You define a task the same way whether the task calls TDMS requests or URPs. When you want existing TDMS applications to take advantage of the RI, you do not need to change any definitions in those applications. In fact, you can enable or disable the RI on a per-request-library and/or user-by-user basis, letting an exchange step in a task use TDMS requests for one user and the RI for another user.

ACMS determines whether to call TDMS requests or URPs at run time. If you use the Request Interface, you can define a logical name that ACMS translates to determine whether to use a TDMS request or a user-request procedure to do the work of an exchange step.

At run time, ACMS does the following to determine if it should call a TDMS request or a user-request procedure:

1. At application startup time, the EXC attempts to open library files with both .RLB and .EXE file types. If the EXC cannot open a library with a file type of .RLB, it logs an error message and the application does not start. However, if the EXC cannot open a library file with the file type of .EXE, the application will start. This is because EXC needs .RLB files to perform local TDMS request I/O, but it does not need .EXE files.
2. When the task step begins executing, the EXC passes the name of the TDMS request library (.RLB) file or the user request procedure (.EXE) shareable image to the Request Interface in the RI agent (ACMRRSHR component).
3. If you have defined the ACMS$RI_LIB_library-name logical name, the RI translates the logical and uses the file type of the resulting translation to determine whether or not to process a request from a request library or a user-request procedure from a shareable image. (Library-name is the file-name portion of the request library or shareable image file specification named in the task group definition.)
   In other words, the ACMS$RI_LIB_library-name logical overrides the request library named in the task group definition. If no logical name exists, the RI uses the file specification passed by the EXC. ( Section 14.3.3 describes how to define the ACMS$RI_LIB logical name.)
   • If the ACMS$RI_LIB logical name translation is a file with an .RLB file type, the Request Interface processes a TDMS request from the named request library.
   • If the ACMS$RI_LIB logical name translation is a file with an .EXE file type, the RI calls the user-request procedure in the named shareable image file.

This run-time determination means that your application has full front-end independence; the EXC need not be aware of the front-end interface used by the application.