HP OpenVMS Systems Documentation
Compaq ACMS for OpenVMS
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.
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
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
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
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:
$ LINK/DEBUG/EXE=VR_SERVER.EXE ...
REPLACE GROUP VR_TASK_GROUP . . SERVER IS PROCEDURE SERVER IMAGE IS "VR_SERVER.EXE";
SERVER IS PROCEDURE SERVER IMAGE IS "VR_SERVER.EXE"; . . . DEFAULT OBJECT FILE IS "VR_SERVER.OBJ";
PROCEDURE SERVER IMAGE IS "PRODUCTION:VR_SERVER.EXE";
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.
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
$ 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.
$ 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:
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
7.2.1 Preparing Definitions
ADU> BUILD GROUP/DEBUG VR_TASK_GROUP
$ 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.
|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.|