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:

• Step procedures
• Specialized procedures: initialization, termination, and cancel procedures

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:

• A procedure server definition is ADU syntax used to describe the server procedures and the server image. A procedure server definition is a part of a task group definition.
• Server procedures are programs or subroutines written in 3GL languages that conform to the OpenVMS calling standard. A procedure performs a particular kind of work for an ACMS task. The two kinds of server procedures used in ACMS tasks are the following:
  • Initialization, termination, and cancel procedures
  • Step procedures
  
  These two types of server procedures are explained in the next section.
• A procedure server image (.EXE) is the executable code that actually does the work for an ACMS processing step; it is, in fact, an OpenVMS image. A procedure server image runs in a procedure server process.
• A procedure server process (SP) is an OpenVMS process created according to the characteristics defined for a server in ACMS task group and application definitions. Server processes are started and stopped, as needed, by the Application Execution Controller (EXC) process.
  When the EXC starts a procedure server, it creates a server process, activates and loads the procedure server image, and runs any initialization procedure defined for the server.
• A procedure server transfer module is an object module created for a procedure server as a result of building an ACMS task group definition. When you build a task group, ADU produces a procedure server transfer module for each server defined in the task group.

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:

• An initialization procedure is called when a server process starts.
• A termination procedure is called when a server process stops.
• A cancel procedure is called when a task is canceled.

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:

• Assign a unique name to a server procedure.
  The name or entry point used for each procedure must be unique among all procedures in a procedure server. You must use the same name to call the procedure in the processing step in the task definition.
  Example 1-3 shows a simplified example of a task definition with a processing step that calls a step procedure.

  Example 1-3 Processing Step in a Task Definition

  REPLACE TASK VR_DISPLAY_CU_TASK . . . GET_CUSTOMERS: PROCESSING CALL VR_GET_CUSTOMER_PROC USING VR_CUSTOMER_WKSP, VR_CU_ARRAY_WKSP; . . .

  
  The CALL clause shows that you want to run a procedure named VR_GET_CUSTOMER_PROC. The USING keyword names two workspaces that the procedure uses: VR_CUSTOMER_WKSP and VR_CU_ARRAY_WSKP. The task definition does not change regardless of the language you use to write the procedure.
  For a more detailed explanation of the processing step, see Compaq ACMS for OpenVMS Writing Applications.

• Structure a step procedure as an externally callable subprogram or function.
  For example, in COBOL you write step procedures as subprograms. Like any other COBOL subprogram, a step procedure begins with an Identification Division that gives the 1- to 31-character name of the procedure. The name of the procedure corresponding to the GET_CUSTOMERS processing step definition shown in Example 1-3 is VR_GET_CUSTOMER_PROC. For example:

  IDENTIFICATION DIVISION. PROGRAM-ID. VR_GET_CUSTOMER_PROC.

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.

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

• Initialization procedures
  Initialization procedures can open the files and bind to the databases that step procedures in the server use.
• Termination procedures
  Termination procedures can perform application-specific server termination processing, such as unmapping a global section. Note that Rdb, DBMS, and RMS automatically release databases and close files when a process runs down.
• Cancel procedures
  Cancel procedures can perform a variety of functions with ACMS tasks, such as freeing non-transaction-based resources and rolling back active database transactions or recovery units. In most cases, their use is discouraged and can be avoided by following the guidelines that are discussed in Section 2.4.1. However, in some situations they are required; see Section 2.4.2 for more information.

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:

• By forcing the server to bind to the database in the initialization procedure, you ensure that the database is accessible, that is, that the database file or files exist and can be accessed by the application.
• The overhead of binding to a database or opening a file is incurred at initialization time rather than at task execution time.
• Any database recovery can be performed as part of application startup.
  If the application is being restarted after a system crash, the database may need to be recovered because of that crash. By forcing the server to bind to the database in the initialization procedure, you force the database recovery to be performed as part of the application startup processing, rather than as part of the first task that uses that server process.
• The initialization procedure can report any errors encountered while binding to the database.
  If the database is not accessible, or for some reason cannot be recovered after a crash, then you can ensure that the application startup fails because the database is unusable.

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:

• An initialization procedure must return a status value to the server process to indicate whether the initialization procedure completed successfully.
  All languages that follow the OpenVMS calling standard supply a method of returning a status value from a subprogram or function. For example, in COBOL, use the GIVING clause of the Procedure Division header to return a status value to ACMS. Include the status-result definition in the Working Storage Section and in the Procedure Division header:

  WORKING-STORAGE SECTION. 01 status-result PIC S9(9) COMP. PROCEDURE DIVISION GIVING status-result.

  
  With BASIC, specify the data type returned with the FUNCTION statement, and assign a value to the function name. This example shows that the status value returned to ACMS has a longword data type:

  FUNCTION LONG pers_upd_server_init_proc

  
  If the server initialization procedure completes successfully, return a success status indicating that the server process is ready to use. If the procedure detects an error condition, return a failure status indicating that the server process cannot be used. If you open more than one file or database, return a success value only if the initialization procedure opened all the files and databases successfully.

• In an initialization procedure, signal errors detected during initialization processing.
  When an initialization procedure signals an error, ACMS writes additional information about the error condition to the ACMS audit trail log. Use the following services to signal the error condition:

  Resource manager	Service used to signal error condition
  Rdb with SQL	SQL$SIGNAL
  Rdb with RDO	LIB$CALLG and LIB$SIGNAL with the Rdb RDB$MESSAGE_VECTOR array
  DBMS	DBM$SIGNAL
  RMS files	LIB$SIGNAL with the RMS STS and STV error codes

  
  If the initialization procedure signals a fatal OpenVMS status, ACMS writes the error to the audit trail log and stops the server process. However, if the procedure signals an error or warning OpenVMS status, then ACMS continues executing the initialization procedure after writing the error to the audit trail log. Therefore, an initialization procedure should always return a failure status when it detects an error, even if it signals the error condition.
• An initialization procedure cannot assign initial values to fields in group or user workspaces.
  Because ACMS does not pass workspaces to initialization procedures, there is no way to assign initial values to fields in workspaces.

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:

• Bind to the database
  The following COBOL code extract causes a simple bind to the database:

  EXEC SQL WHENEVER SQLERROR GO TO sql-error-handler END-EXEC. EXEC SQL SET TRANSACTION READ WRITE END-EXEC. EXEC SQL COMMIT END-EXEC. SET ret-stat TO SUCCESS. EXIT PROGRAM. sql-error-handler. MOVE Rdb$LU_STATUS TO ret-stat CALL "SQL$SIGNAL" EXIT PROGRAM.

• Start a transaction and, additionally, reserve the relations that will be used by the step procedures in the server.
  Using this method, you also force Rdb to read in the metadata associated with those relations, in addition to just binding to the database. Doing this at application startup time means that this overhead is incurred once --- when the application starts --- rather than each time a step procedure in a server process first accesses a relation.

  Note If the procedures in the server perform only read-access transactions against the database, specify READ ONLY access when you start the transaction.

  
  The following code extract causes the process to bind to the database and causes the metadata for the named relations to be read in.

  EXEC SQL WHENEVER SQLERROR GO TO sql-error-handler END-EXEC. EXEC SQL SET TRANSACTION READ WRITE RESERVING reservations, vehicles, vehicle_rental_history FOR SHARED WRITE, sites, regions FOR SHARED READ END-EXEC. EXEC SQL COMMIT END-EXEC. SET ret-stat TO SUCCESS. EXIT PROGRAM. sql-error-handler. MOVE Rdb$LU_STATUS TO ret-stat CALL "SQL$SIGNAL" EXIT PROGRAM.

• Store a dummy record in a relation and then delete it by rolling back the database transaction or recovery unit.
  When you use this method, you force Rdb to create the recovery-unit journal file (.RUJ) during application startup rather than as part of the first task that uses the server process. Furthermore, if the .RUJ file cannot be created for some reason, then the application does not start.

  Note Rdb and DBMS do not use an .RUJ file for read-only transactions. Therefore, this step is not necessary if the procedures in the server perform only read-access transactions against the database.

  
  The following code extract forces Rdb to create the .RUJ file for the process:

  EXEC SQL WHENEVER SQLERROR GO TO sql-error-handler END-EXEC. EXEC SQL SET TRANSACTION READ WRITE RESERVING reservations, vehicles, vehicle_rental_history FOR SHARED WRITE, sites, regions FOR SHARED READ END-EXEC. EXEC SQL INSERT INTO reservations ( reservation_id ) VALUES ( :zero_reservation_id ) END-EXEC. EXEC SQL ROLLBACK END-EXEC. SET ret-stat TO SUCCESS. EXIT PROGRAM. sql-error-handler. MOVE Rdb$LU_STATUS TO ret-stat CALL "SQL$SIGNAL" EXIT PROGRAM.

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.