HP OpenVMS Systems Documentation
Compaq ACMS for OpenVMS
After debugging the tasks in a task group, you include the task group in an application definition and make the tasks available from a menu. Then you need to test the application as a single, working unit before releasing it for use in the ACMS run-time environment.
Because the ACMS Task Debugger runs in a different environment from an ACMS application, even the best-designed and best-developed application can encounter problems during the transition from one environment to another. To help you overcome this potential problem, ACMS allows you to debug servers executing in an active ACMS application. You can also request an OpenVMS process dump for a server that aborts execution due to system or programming errors and then analyze the output from the dump file.
Sections in this chapter explain the following:
When you make the transition from testing a task running under the ACMS Task Debugger to running the task in the ACMS run-time environment, check that logical names, server quotas and privileges, and file or database protections are set adequately for the run-time environment.
Avoid run-time problems by ensuring that:
A task under the control of ACMS at run time uses all the files needed to run the task under the ACMS Task Debugger plus two additional files, the application database (.ADB) and the menu database (.MDB):
For a list of the files you need when you use the ACMS Task Debugger,
see Table 7-1 and Figure 7-1.
8.3 Debugging Procedure Servers in the Run-Time Environment
Even though a task executes successfully in the ACMS Task Debugger environment, it may contain errors that do not show up until the task runs in a server in the ACMS run-time environment. For example, the server may go into an infinite loop, give incorrect output, or terminate prematurely.
ACMS provides the ACMS/DEBUG/SERVER operator command so that you can debug servers as they execute in the ACMS run-time environment. Using this command, you can observe the server process execution through the OpenVMS Debugger. This feature provides a way for you to use OpenVMS Debugger commands to locate run-time programming or logic errors and other bugs. If a server is looping, for example, you can step through a procedure and isolate bugs in the live server just as though the server were running in the ACMS Task Debugger.
The following sections describe how to debug running servers. Section 8.3.2 describes the ACMS/DEBUG/SERVER command. Compaq ACMS for OpenVMS Managing Applications describes the syntax for the ACMS/REPLACE SERVER operator commands.
Use ACMS/DEBUG/SERVER to debug only procedure servers. Do not use this command to debug DCL servers.
Because the ACMS/DEBUG/SERVER command allows users to stop a server or change the way it operates, you must provide a means of controlling which users can debug servers. You provide this security by using logical names. For each user who can debug servers, define the logical name ACMS$DEBUG_SERVER_vmsusername as either TRUE or YES.
The logical name ACMS$DEBUG_SERVER_vmsusername must be an executive mode logical.
$ DEFINE/SYSTEM/EXEC ACMS$DEBUG_SERVER_SMITH YES
Define the ACMS$DEBUG_SERVER_vmsusername logical at DCL level as shown in the previous example, using the /SYSTEM, /GROUP, or /TABLE qualifier. A user can debug any server on the system if ACMS$DEBUG_SERVER_vmsusername is defined as an executive mode system logical.
By using the /GROUP qualifier, you can restrict users to debugging only servers in a particular group. You can also define the logical in a server logical name table and point to it from the ACMS application definition. Use the /TABLE qualifier on the DEFINE ACMS$DEBUG_SERVER_vmsusername command if you define the logical in a server logical name table.
Although you can authorize several users to debug a server or servers,
only one user can debug a server at a time.
8.3.2 Using the ACMS/DEBUG/SERVER Command
To debug a running server, you must link the server to include traceback information. This is required for the OpenVMS Debugger to interrupt the server. By default, the OpenVMS Linker links images with traceback. If the server was linked without traceback (that is, the /NOTRACEBACK qualifier was used on the LINK command), you must relink the server before you can debug it. Then you must replace the server in the running application before continuing.
If the server is linked with /TRACEBACK (the default), and you have either defined the ACMS$DEBUG_SERVER_vmsusername logical name or provided the CMKRNL privilege for the users who can debug the server, follow these steps to debug the server:
$ ACMS/DEBUG/SERVER ACMS021SP001000 DBG>
$ ACMS/DEBUG/PID=26000049 DBG>
After you find an error in a server, you need to complete several steps to correct the situation:
$ ACMS/REPLACE SERVER VR_SERVER /CONFIRM
You must have OPER privilege to issue the ACMS/REPLACE SERVER command.
Compaq ACMS for OpenVMS Managing Applications contains more information on replacing servers in a live
8.4 Determining Why Servers Stop Unexpectedly
Sometimes servers executing in a production environment stop unexpectedly. If you suspect that the server stopped as a result of system errors or errors in the step procedure, you need a way to trace the location of the error.
You can request ACMS to generate an OpenVMS process dump if a server stops unexpectedly. This produces a dump file that contains the context of the process when the server stopped. You can then analyze the contents of the dump file for clues as to why the server stopped.
get a server process dump, you can include the SERVER PROCESS DUMP
clause in the ACMS application definition or use the ACMS/MODIFY
APPLICATION command. These two methods are explained in the next
8.4.1 Collecting Server Information in a Dump File
If you have problems with a particular server, set up the server to provide server process dumps. Then run the task and try to reproduce the situation that causes the server to stop, so that ACMS generates a dump file for analyzing the problem.
First, enable or disable server process dumps in the application definition by using the SERVER PROCESS DUMP clause. You can enable server process dumps in the running application by using the ACMS/MODIFY APPLICATION operator command in an active application. This command temporarily modifies the application definition parameters for the current active application. If you stop and restart the application, the application parameters are reset to their original values.
Compaq ACMS for OpenVMS Managing Applications describes the ACMS/MODIFY APPLICATION command and its qualifiers.
Another method of enabling server process dumps is to stop the application, replace the application definition with one that includes the SERVER PROCESS DUMP clause, rebuild the application, and then restart the application. This method permanently enables server process dumps for the server in the application definition.
Example 8-1 shows an application definition that specifies server process dumps.
|Example 8-1 Using the SERVER PROCESS DUMP Clause in an Application Definition|
. . . SERVER ATTRIBUTES ARE UPDATE_SERVER: SERVER PROCESS DUMP; END SERVER ATTRIBUTES; . . .
When the server terminates abnormally, ACMS writes the context for the server to a dump file located in the default directory for the server. The dump file has the same name as the server. At the same time that ACMS generates the dump file, it also writes a record to the ACMS audit trail log.
If, for some reason, ACMS is unable to generate a server process dump, ACMS writes an audit record to explain the failure. For example, there may be insufficient privileges for ACMS to write the dump file to the server's default directory.
See Compaq ACMS for OpenVMS ADU Reference Manual for more information about including the server
process dump qualifier in an application definition.
8.4.2 Analyzing Server Process Dumps
$ ANALYZE/PROCESS_DUMP/IMAGE=avertz_default:vr_update_server_.exe - _$ vr_update_server.dmp
In some cases, the ANALYZE/PROCESS_DUMP returns an error if the server process dump file and procedure server image are not located in the same directory. If you encounter this problem, simply copy the procedure server image to the same directory as the server process dump file, and reissue the ANALYZE/PROCESS_DUMP command. For example:
$ ANALYZE/PROCESS_DUMP/IMAGE=vr_update_server_.exe - _$ vr_update_server.dmp
Be sure the dump file allows read (R) access before invoking the analyzer. For a complete description of the debugger, see OpenVMS Debugger Manual. OpenVMS DCL Dictionary discusses using the DCL ANALYZE/PROCESS_DUMP command.