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

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:

• Procedure server transfer module created for that server by the BUILD command of ADU
• All step procedures for all tasks in the task group that use that server
• Initialization, termination, and cancel procedures (if any) for the server
• Any procedures called as cancel actions by tasks using the server

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:

• In the LINK command, include all of the procedures that are named in the server definition in the task group.
  The LINK command creates a server image named from the first module named in the command line, and places it in your default directory. Use the optional /EXE qualifier to explicitly assign a name to the server image. For example:

  $ LINK/DEBUG/EXE=VR_SERVER.EXE ...

  
  In the example, the name assigned to the executable file is VR_SERVER.EXE. If you do not use the qualifier, the Linker uses the file name of the first object module in the LINK command as the name of the server image. The default file type is .EXE.

• Include the /DEBUG qualifier in the LINK command if you want to debug the procedures in the server.
• Use the same name for the server image in the LINK command as you do in the IMAGE clause of the task group definition. For example:

  REPLACE GROUP VR_TASK_GROUP . . SERVER IS PROCEDURE SERVER IMAGE IS "VR_SERVER.EXE";

  
  In the LINK command, the first object module that you name is the procedure server transfer module; in the example, it is called VR_SERVER.OBJ. You can assign a name to the procedure server transfer module in the task group definition, in the SERVER IS statement. For example:

  SERVER IS PROCEDURE SERVER IMAGE IS "VR_SERVER.EXE"; . . . DEFAULT OBJECT FILE IS "VR_SERVER.OBJ";

  
  You might also prefer to include a logical with file names. For example:

  PROCEDURE SERVER IMAGE IS "PRODUCTION:VR_SERVER.EXE";

• If you plan to debug a server image later, do not use the /NOTRACEBACK qualifier on the LINK command. You can still start the server with the Task Debugger if you link the server with /NOTRACEBACK. However, you cannot debug it because the OpenVMS Debugger cannot be invoked while a program linked without traceback information is running. Also, if you use the INTERRUPT command to access the OpenVMS Debugger in that server, the server stops.

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.

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:

• Using debugging tools
• Preparing to use the ACMS Task Debugger
• Using the ACMS Task Debugger to step through the execution of individual tasks
• Using the OpenVMS Debugger to step through the execution of server procedures
• Returning to the ACMSDBG> prompt
• Debugging tasks that are called by user-written agent programs

You use several tools to debug ACMS tasks and procedures:

• ACMS Task Debugger
  The ACMS Task Debugger provides an environment for testing tasks and server procedures without building an entire ACMS application. The Task Debugger lets you control a task while the task is running. You can set breakpoints at the beginning of the task, at the beginning of any step in the task, at the action part of any step, and at the end of any step. Once you reach a breakpoint in the task, you can examine and deposit values in workspaces and then resume the execution of the task.
• OpenVMS Debugger
  The OpenVMS Debugger lets you control the procedures called by the task. You use the OpenVMS Debugger in the same way as you use it with any program. For example, you can use the OpenVMS Debugger to set a breakpoint in the procedure after the procedure reads a record; when you reach the breakpoint, you can examine and deposit data in variables and then resume execution of the procedure. You also use the OpenVMS Debugger to check whether your procedures perform properly or not and to debug DECforms escape routines.
• DECforms Trace Facility
  In addition to ACMS and OpenVMS facilities for debugging tasks, you can also use the DECforms trace facility. This facility logs processing information at run time to help you debug both your applications and your form. The trace facility uses the logical names FORMS$TRACE and FORMS$TRACE_FILE. See DECforms Guide to Commands and Utilities for more information about the DECforms trace facility.

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

• Start, stop, and assign logical names for the servers you are going to use
• Start, stop, and step through a task
• Display and change workspace contents while a task is running

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:

• Prepare definitions and build a task group.
• Prepare procedures by compiling and linking them.
• Check to make sure that all the files you need are complete.
• Define logical names and prepare DECforms escape routines for debugging, if necessary.

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.

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:

• If you make a change in a server procedure, you must compile the server procedure and relink the server image to include the new object module.
• If you revise a task or task group definition, you must rebuild the task group using ADU.

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.