Compaq ACMS for OpenVMS
Writing Server Procedures


Previous Contents Index

Part 1
User Information

Part 1 contains tutorial information about writing procedures and creating message files for ACMS servers. This part also contains information about building procedure server images, debugging tasks and server procedures, and running tasks in the ACMS run-time environment.


Chapter 1
Introduction to Server Procedures

This chapter defines procedure server terminology, including server procedures, procedure server images, server processes, and procedure server transfer modules. The chapter also explains the similarities and differences between the different types of procedures used in ACMS applications:

Each section in the chapter includes references to other chapters or manuals where you can find more detailed information about these topics.

1.1 Procedure Server Terminology

A number of terms used in this chapter can be confusing because they all contain the word server, and they are similar-sounding. Because these terms are used throughout this and other ACMS manuals, it is important to understand the differences among them.

A procedure server is a term used in ACMS to describe a number of the specific concepts, which are represented in Figure 1-1.

Figure 1-1 Procedure Server Terminology


To the right of Procedure Server (Concept) in Figure 1-1 are five procedure server-related terms:

Note

The two types of servers in an ACMS environment are procedure servers and DCL servers. See Compaq ACMS for OpenVMS Writing Applications for information about DCL servers.

1.2 Understanding Server Procedures

A server procedure is a program written in a 3GL programming language, such as COBOL, that conforms to the OpenVMS calling standard. A procedure performs a particular kind of work for an ACMS task. The two types of procedures in ACMS are described in the next two sections.

1.2.1 Initialization, Termination, and Cancel Procedures

Initialization, termination, and cancel procedures make up one type of server procedure. These procedures open files, bind databases, close files, and do cleanup work when an ACMS task is canceled.

Initialization, termination, and cancel procedures do work related to a server process rather than work related to a specific task. The Application Execution Controller (EXC) calls each of them at various times:

Initialization, termination, and cancel procedures for a server are declared in a task group definition. You can have only one initialization, termination, and cancel procedure in each server definition.

Example 1-1 shows the task group server declaration of the initialization procedure VR_INIT and the termination procedure VR_TERM in the AVERTZ Vehicle Rental Task Group Definition, VR_TASK_GROUP.

Example 1-1 Declaration of Initialization and Termination Procedures in a Task Group Definition

 
            REPLACE GROUP VR_TASK_GROUP 
             . 
             . 
             . 
            SERVER IS VR_SERVER: 
                 INITIALIZATION PROCEDURE IS VR_INIT;
                 TERMINATION PROCEDURE IS VR_TERM;
                 PROCEDURES ARE    
                 . 
                 . 
                 . 
            END SERVER; 
            END DEFINITION; 

The declaration of a cancel procedure, if included in the example, would follow the identification of the initialization and termination procedures and would be similar to them.

Chapter 2 contains more information and examples of initialization, termination, and cancel procedures.

1.2.2 Step Procedures

A step procedure is a second type of server procedure. A step procedure is a subroutine that does the computational and database access work for a processing step in an ACMS task. It is invoked by means of a call statement in a processing step, and it returns control to the calling task when it completes.

Figure 1-2 shows a call to a step procedure in a processing step of a task definition. The step procedure in the example is VR_GET_CUSTOMER_PROC.

Figure 1-2 Call to a Step Procedure in a Task Definition


The names of the step procedures called by the tasks in the task group are declared in the PROCEDURES ARE clause of the SERVER IS statement. Example 1-2 shows an example of the procedure VR_GET_CUSTOMER_PROC declared in the task group VR_TASK_GROUP.

Example 1-2 Declaration of a Step Procedure in a Task Group Definition

 
            REPLACE GROUP VR_TASK_GROUP 
             . 
             . 
             . 
            SERVER IS VR_SERVER: 
                 INITIALIZATION PROCEDURE IS VR_INIT; 
                 TERMINATION PROCEDURE IS VR_TERM; 
                 PROCEDURES ARE    
                                VR_GET_CUSTOMER_PROC, 
                 . 
                 . 
                 . 
            END SERVER; 
            END DEFINITION; 

1.3 Naming and Structuring a Server Procedure

Two rules apply to naming and structuring a server procedure:

1.4 Programming Services and Tools

ACMS provides programming services and tools to assist you in writing procedures. Chapter 3 explains how to use programming services in writing step procedures. Chapter 9 contains reference information about all ACMS programming services.

ACMS tools that you can use to debug tasks and server procedures include the ACMS Task Debugger, online server debugging, and server process dumps. Chapter 7 and Chapter 8 contain information about debugging ACMS tasks and server procedures.

The OpenVMS operating system also provides tools used to create procedure servers: the OpenVMS Message Facility, the OpenVMS Linker, and the OpenVMS Debugger. Chapter 5, Chapter 6, and Chapter 7 explain the use of these tools.


Chapter 2
Writing Initialization, Termination, and Cancel Procedures

The three types of specialized optional ACMS procedures are the following:

2.1 Writing Initialization Procedures

Use initialization procedures to open the files or bind to the databases that are subsequently used by the step procedures running in the server. Files and databases are most frequently opened by initialization procedures with shared access so that other processes on the system, including other server processes, can also access the data. However, it is more efficient to use exclusive access in those cases where only a single server process needs to access a file or database.

Binding or attaching to a database in an initialization procedure has the following advantages:

The use of an initialization procedure for a server is optional. If you do specify an initialization procedure, ACMS calls the procedure every time it starts a new process for the server. ACMS can start server processes when an application is first started and also while an application is running if additional server processes are required to handle the load placed on the application by the users. If you do not specify an initialization procedure, ACMS starts the server process without performing any application-specific initialization processing.

The processing that is performed in an initialization procedure depends on which database you are using. See the database-specific sections in this chapter for more information.

2.1.1 Guidelines for Writing Initialization Procedures

Initialization procedures do the same kind of work for server processes that use Rdb or DBMS databases or RMS files. Follow these guidelines when writing initialization procedure for databases and files:

2.1.2 Binding or Attaching to Databases

In an initialization procedure, you can bind or attach to a database in three ways. The following sections describe these methods and explain how to decide which of them is appropriate to your application.

To bind to a database, start and end a dummy database transaction in the initialization procedure. The examples below illustrate attaching to an Rdb database using SQL; however, the same techniques also apply when accessing an Rdb database using RDO and when accessing a DBMS database.

The options are:

The following sections contain examples of initialization procedures and explanations of how to write code for Rdb and DBMS databases and for RMS files. See the Rdb, DBMS, and RMS documentation for further information on accessing a database or file.


Previous Next Contents Index