Compaq ACMS for OpenVMS
Writing Server Procedures


Previous Contents Index


Chapter 6
Building Procedure Server Images

After writing procedures for ACMS tasks, you must compile and link those procedures. You compile procedures as you do any other program. However, you do not link and run ACMS procedures as you do an OpenVMS image, because ACMS procedures are not independent programs.

The first section of this chapter contains the steps necessary to build a procedure server image, including compiling and linking commands that you use to debug procedures later. The chapter also explains the run-time operation of server processes and describes the files that you need to create to debug an ACMS application. Finally, the chapter tells how to use a procedure object library.

6.1 Steps in Building a Procedure Server Image

Procedures that you write for ACMS tasks run under the control of ACMS. Each performs only part of the processing for a task; the task definition takes care of the rest of the processing. Before you can debug tasks and the procedures that run in those tasks, you need to link the object code of procedures together with the procedure server transfer module and the message object module. You link all of these into a procedure server image (.EXE).

A simplified list of the order of operations for building a procedure server image follows.

  1. Write the source code of the procedure.
  2. Compile the source code into a procedure object module.
  3. Create any message files you want to use; compile and link them.
  4. Build the task group, which creates both a task group database (.TDB) and a procedure server transfer module (.OBJ).
  5. Link the procedure server transfer module, server procedure object modules, and message pointer object modules to create a procedure server image.

Figure 6-1 shows the steps that you need to take and the files that you use when you create a procedure server image. The steps are labeled 1 through 5 in the diagram. The example in the figure is a procedure that is a COBOL program.

Figure 6-1 Creating a Procedure Server Image


The following sections explain the steps for creating a procedure server image. The sections correspond to the steps in Figure 6-1.

6.1.1 Writing the Source Code of the Procedure

Follow the instructions in Chapter 3 for writing step procedures. Follow the instructions in Chapter 2 for writing initialization, termination, and cancel procedures.

6.1.2 Compiling the Source Code into a Procedure Object Module

Compiling step, initialization, termination, and cancel procedures is similar to compiling any program. You use the same commands, create the same output files, and expect the same kinds of errors, such as missing periods in COBOL or missing ampersands in BASIC. For information on compiling source programs and correcting compile-time errors, see the reference manual and user's guide for the language you are using.

If you plan to debug a high-level language procedure later, you might want to include the OpenVMS debug symbol table in the procedure when you compile it. For example, if you use the COBOL command to compile a procedure, use the /DEBUG qualifier in the command line:


$ COBOL/DEBUG VR_FIND_SI_PROC

The file name of the procedure in the example is VR_FIND_SI_PROC.

Figure 6-2 shows the relationship between procedure source files and their file names when they are compiled to create object modules. (These are the file names that you use when you link object modules in step 5.) The example uses COBOL step, initialization, and termination procedures from the AVERTZ application.

Figure 6-2 Compiling Source Code into Object Modules


6.1.3 Creating, Compiling, and Linking Message Files

Chapter 5 explains how to create, compile, and link message files. When you use the Message Utility a second time, you create a pointer object module, which is a file that you link into the procedure server image in step 5.

6.1.4 Building the Task Group

When you build a task group, you create both a task group database (.TDB) and a procedure server transfer module (.OBJ). For example:


ADU> BUILD GROUP VR_TASK_GROUP

Compaq ACMS for OpenVMS Writing Applications contains detailed instructions for building a task group.

To use the ACMS Task Debugger EXAMINE and DEPOSIT commands, include the /DEBUG qualifier with the BUILD GROUP command. For example:


ADU> BUILD GROUP VR_TASK_GROUP/DEBUG

Chapter 7 contains instructions for debugging tasks.

6.1.5 Linking the Object Code of Procedures

Link the object code of procedures with the procedure server transfer module into a procedure server image. Before linking, you can place files in a procedure object library. Doing so allows you to track insertion into the library and simplifies the job of creating a server image. Using procedure object libraries also reduces linking time. See Section 6.2 for more information about using an object library.

You use the DCL LINK command to combine the following object modules into an executable (.EXE) file:

Figure 6-3 shows the relationship between the task group definition and object modules when they are linked to create a procedure server image.

Figure 6-3 Linking Object Modules into a Procedure Server Image


Follow these guidelines when using the LINK command:

Example 6-1 shows a LINK command example for a server that uses SQL.

Example 6-1 LINK Command for a Procedure that Uses SQL

$ LINK/DEBUG/EXE=VR_SERVER.EXE VR_SERVER.OBJ,-
_$ ACMS$SAMPLES:VR_TERM,- 
_$ ACMS$SAMPLES:VR_GET_CUSTOMER_PROC,-
_$ ACMS$SAMPLES:VR_MOVE_CU_PROC,-
_$ ACMS$SAMPLES:VR_INIT,-
_$ SYS$LIBRARY:SQL$USER/LIB

When linking a server image containing procedures called by tasks that use the WITH SQL RECOVERY phrase, you must reference the ACMS SQL library in SYS$LIBRARY immediately after the transfer vector object module name. As the last item, link the SQL library file that is found in SYS$LIBRARY. When you use the WITH SQL RECOVERY phrase in the task definition, if you do not reference the correct libraries in the correct order, you can receive unpredictable run-time errors.

Example 6-2 shows a complete LINK command for a server image containing procedures called by tasks that use the WITH SQL RECOVERY phrase.

Example 6-2 LINK Command for Servers Called by Tasks that Use the SQL RECOVERY Phrase

$ LINK/DEBUG/EXE=VR_SERVER.EXE VR_SERVER.OBJ,-
_$ SYS$LIBRARY:ACMSSQL/LIB,-
_$ ACMS$SAMPLES:VR_GET_CUSTOMER_PROC,-
_$ ACMS$SAMPLES:VR_MOVE_CU_PROC,-
_$ ACMS$SAMPLES:VR_INIT,-
_$ SYS$LIBRARY:SQL$USER/LIB

The ACMSSQL library is not required if the SQL database transactions are started by the step procedures in the server, not in the task definition.

When linking procedure server code, if the task definition uses Rdb recovery, then include the following two statements in your link option file:


PSECT_ATTR=RDB$TRANSACTION_HANDLE,LCL,NOSHR 
PSECT_ATTR=RDB$DBHANDLE,LCL,NOSHR 

Because of an Rdb restriction, the link is not upward compatible; therefore, you need to relink the server for each new version of Rdb.

6.2 Using an Object Library for Procedures

In many cases, it is more convenient to place all the object modules for your procedures in a procedure object library before linking the server image. A procedure object library allows you to track insertion into the library by using the following command:


$ LIBRARY/LIST/FULL library_name

Using a library also simplifies the job of creating a server image. Finally, using object libraries also reduces link time.

After compiling the procedures for a server and correcting the compilation errors, use the OpenVMS LIBRARY command to put the object modules in your procedure object library. If the library does not exist, create it. For example:


$ LIBRARY VR_PROC.OLB /CREATE

To place modules in the library, use the /INSERT qualifier in the LIBRARY command. For example:


$ LIBRARY/INSERT VR_PROC.OLB VR_FIND_SI_PROC.OBJ

The first name used in the LIBRARY command is the procedure object library; its default file type is .OLB. The second name is the file containing the object module to be placed in the library. In this case, the name of the file is VR_FIND_SI_PROC.OBJ in the default device and directory.

If you use an object library for your procedures, use the /LIBRARY qualifier to identify the object library when you link the server image. For example:


$ LINK/DEBUG  VR_SERVER, VR_PROC/LIBRARY

In this example, VR_SERVER is the name of the procedure server transfer module (.OBJ) created by building the task group containing that server. The procedure object library is identified as VR_PROC.OLB. By using the /LIBRARY qualifier, you indicate that all modules referenced by VR_SERVER.OBJ are to be taken from the VR_PROC.OLB library and included in the server image.

For more information on using a procedure object library, see OpenVMS Command Definition, Librarian, and Message Utilities Manual.


Chapter 7
Debugging Tasks and Procedures

After writing server procedures for tasks, you need to test procedures for errors. You compile procedures as you would any other program, but, because ACMS procedures are not independent programs, you do not link, run, and debug server procedures as you would an OpenVMS image.

Server procedures run under the control of ACMS and perform only part of the processing for a task. The task definition takes care of the rest of the processing. You need to debug tasks and the procedures that are called by tasks at the same time to be sure that tasks and procedures work together as they should.

This chapter discusses the following topics:

7.1 Using Debugging Tools

You use several tools to debug ACMS tasks and procedures:

Chapter 10 contains reference information on all of the ACMS Task Debugger commands. In general, you use Task Debugger commands to do the following:

When you select a task to debug, the ACMS Task Debugger starts the task. When the task reaches a breakpoint, you can enter commands to continue running the task, display the contents of workspaces, change the contents of workspaces, or display information about ACMS Task Debugger commands.

By examining and changing workspace contents, variable assignments, and other values, you can find most of the errors in the definitions or procedures for your tasks. You can look for inconsistencies between workspaces in form definitions, task definitions, and procedures. You can also check that logical names in procedures or definitions point to the correct files and that files have correct protection codes. Finally, you can check for error conditions that are not handled by the server procedures or the task definition.

7.2 Preparing to Use the ACMS Task Debugger

Before you can debug ACMS tasks, you need to:

Before you debug, you need to check a number of quotas to make sure that the ACMS Task Debugger can be run. If you plan to debug using two terminals, you also need to complete additional preparatory steps. Finally, to debug a task called from a user-written agent program, you must complete additional preparatory steps, which are explained in Section 7.6.

7.2.1 Preparing Definitions

Before debugging a task, be sure to complete the following steps:

  1. Use the Common Dictionary Operator (CDO) Utility to define all fields, records, and workspaces used by the task.
  2. Use DECforms to define all forms for the task.
  3. Use the Application Definition Utility (ADU) to define the task and the task group.
    Because tasks involve both code and definitions, it is important to understand all parts of the task to debug it. The primary definition you must understand is the task definition. For a detailed explanation of task definitions, see Compaq ACMS for OpenVMS Writing Applications.
  4. Use the ADU BUILD command to create a task group database from the task group definition. To use the ACMS Task Debugger EXAMINE and DEPOSIT commands, include the /DEBUG qualifier with the BUILD GROUP command. For example:


    ADU> BUILD GROUP/DEBUG VR_TASK_GROUP
    

    You can use the EXAMINE and DEPOSIT commands to examine or deposit data into the workspaces when you debug the task.

7.2.2 Preparing Procedures

It is easier to debug procedures if you compile and link them with the /DEBUG qualifier. Using the /DEBUG qualifier makes more information available to the OpenVMS Debugger. For example:


$ COBOL/DEBUG VR_FIND_SI_PROC
$ LINK/DEBUG/EXE=VR_SERVER.EXE VR_SERVER.OBJ,-
. 
. 
. 

After you compile and link the procedures called by a task, you can run the task in the ACMS Task Debugger. The task you run is a real one; when the task is in daily use, ACMS runs the same definitions and code as the ones you test.

To protect business data, you can set up test files to run against the task. For example, if your procedures use logical names to identify files, create a set of data files in another directory, and temporarily redefine the logical names to point to that directory. See Section 7.2.3 for an explanation of the two methods of defining logical names.

While debugging, keep in mind the relationship between a server procedure, a task, and a task group:

One of the difficult parts of debugging a task is making sure that all the files you need are complete. Chapter 6 explains the steps you take to build a procedure server image. After completing those steps, check that all the files are ready. Figure 7-1 shows the files needed for debugging and depicts how you produce those files from CDD definitions, source programs, and message source files.

Figure 7-1 Files Needed for Debugging


Table 7-1 explains how to produce the files needed to run a task with the ACMS Task Debugger.

Table 7-1 Files Needed for Debugging
Files Description
DECforms form files Created using DECforms.
Data files or database files for the task group Created and populated using either RMS, DBMS, or Rdb.
Message files for the task group Created with the OpenVMS Message Utility. You need these files if your tasks use the GET MESSAGE clause.
Procedure server images Created with the DCL LINK command. These files contain executable images of the procedure server transfer module, message file module, and all procedures for the task group.
Task group database (.TDB) Created with the BUILD GROUP command of the ACMS Application Definition Utility (ADU). This file contains information used by ACMS to run tasks.


Previous Next Contents Index