Compaq ACMS for OpenVMS
Writing Server Procedures


Previous Contents Index


Chapter 8
Debugging an Application in an ACMS Run-Time Environment

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:

8.1 Moving from Debugging to a Run-Time Environment

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:

8.2 Checking Files Needed to Run Tasks Under ACMS

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.

Once you have identified and corrected an error in a server, ACMS also provides the ACMS/REPLACE SERVER operator command to replace the faulty server without interrupting the live application.

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.

Note

Use ACMS/DEBUG/SERVER to debug only procedure servers. Do not use this command to debug DCL servers.

8.3.1 Controlling Which Users Can Debug 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.

Note

The logical name ACMS$DEBUG_SERVER_vmsusername must be an executive mode logical.

The following example shows how to define an executive mode logical name to allow the user SMITH to debug any server on the system:


$ DEFINE/SYSTEM/EXEC ACMS$DEBUG_SERVER_SMITH YES

This example uses the /SYSTEM qualifier to define the logical name as a system logical so that the user named SMITH can debug any server on the system.

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.

You do not need to define the ACMS$DEBUG_SERVER_vmsusername logical if the user has the CMKRNL privilege. ACMS allows any user with the CMKRNL privilege to debug any server.

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:

  1. Use the ACMS/SHOW SERVER command to get the server process name and process identification (PID). Use the process name or the server's PID when you start debugging the server.
  2. Invoke the debugger by issuing the ACMS/DEBUG/SERVER command, including either the server process name or the process ID. The following example starts the debugger for VR_SERVER, whose server process name is ACMS021SP001000:


    $ ACMS/DEBUG/SERVER ACMS021SP001000
    DBG>
    

    Include the PID number with this command by specifying the PID number with the /PID=PID_number qualifier. For example:


    $ ACMS/DEBUG/PID=26000049
    DBG>
    

  3. Issue OpenVMS Debugger commands to debug the server code.
    See OpenVMS Debugger Manual for more information on using the OpenVMS Debugger commands.
  4. Press [Ctrl/G] while debugging a server to interrupt the server and return control to the OpenVMS Debugger.
    Using [Ctrl/G] is a handy way to interrupt the debugger, if you forgot to set a breakpoint and want to do it before continuing, for example. Use the GO command or STEP command to continue debugging the server.
  5. Use [Ctrl/Z] or the EXIT command to stop the debugging session from the DBG> prompt. When you complete a debugging session, you stop the server that you are debugging.

8.3.3 Replacing a Faulty Server

After you find an error in a server, you need to complete several steps to correct the situation:

  1. Correct the code.
  2. Rebuild the server image.
  3. Place the server image in the location specified in the SERVER IMAGE IS statement in the task group definition.
  4. Use the ACMS/REPLACE SERVER operator command to run down the server processes that are executing the faulty server code and create new processes running the corrected image. You can do this without interrupting the live application. For example:


    $ ACMS/REPLACE SERVER VR_SERVER /CONFIRM
    

If a task has context in a server that you are replacing at the time the REPLACE command is issued, the server does not run down until context is released.

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 application.

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.

To 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 section.

8.4.1 Collecting Server Information in a Dump File

The following occurrences can cause a server to stop executing while running in an application:

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

You use the DCL command ANALYZE/PROCESS_DUMP to analyze the contents of a server process dump file. For example:


$ 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.


Previous Next Contents Index