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:

• Moving to an ACMS run-time environment
• Checking files that you need to run tasks under ACMS
• Debugging procedure servers in a run-time environment
• Determining why a server stops unexpectedly

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:

• Logical names that were available to the server subprocess running under the ACMS Task Debugger are available to the ACMS run-time server process.
  The server runs as a subprocess under the ACMS Task Debugger, but it runs as a detached process under the ACMS run-time environment. Therefore, logical names that were available to the server through logical name tables when it runs as a subprocess may not be available to the server when it runs as a detached process.
  The Application Execution Controller and servers can run under user names different from each other and different from the one you used while debugging the task group. Because of this, determine the best way to define the logical names so that all processes that need them have access to them. You can define them:
  • As system logical names
  • In a logical name table to which the server and application have access
  • As server logical names in the application definition for the server
• Server quotas and privileges are adequate for the operations that the run-time server performs.
  As discussed previously, the ACMS run-time server may run under a different user name than in the ACMS Task Debugger. Therefore, an operation that was performed successfully under the ACMS Task Debugger may not work at run time. This happens if the server user name does not have the quotas or privileges (if any) required for the operation.
  If the user names are different, the quotas may be insufficient. Make sure that the quotas of the user name in the run-time environment are high enough.
• Protection on files and databases allow access by the run-time server.
  If the run-time server uses a different user name than the server that it ran under in the ACMS Task Debugger, files and databases that can be read and written to during debugging may not be available at run time.
• Servers that perform terminal I/O during processing steps must explicitly open and close the terminal channel.
  During debugging, the ACMS Task Debugger always makes the terminal available to the server subprocess. Therefore, procedures that successfully do terminal I/O during processing steps under the ACMS Task Debugger may not work when they are run under the ACMS run-time system. The task definition must explicitly make the terminal available to the server using the TERMINAL I/O phrase.
• Logical names that translate to specific devices or files under the ACMS Task Debugger must translate to the appropriate devices or files when used during run time with the ACMS Application Execution Controller.
  When a task uses logical names to determine which of several files or devices to access, take care that the logical names translate to the file or device you intend to access. Under the ACMS Task Debugger, for example, if you want to print or generate a hard copy of a DECforms form, the form listing goes to the device pointed to by the programmer's translation of the FORMS$PRINT_FILE logical name. Tasks running under the ACMS run-time environment, however, send their output to the device pointed to by the agent process's translation of the FORMS$PRINT_FILE logical name (for example, the CP process).
  In addition, if the task is accessed remotely (such as when the submitter and the application are on different nodes), the output goes to the device pointed to by the remote agent process's translation of FORMS$PRINT_FILE (for example, the CP process).
• Step procedures that open channels to the terminal must close them before ending.
  In the run-time environment, if a step procedure opens a channel to the terminal but returns without closing it, ACMS cancels the task. However, ACMS cannot do this when you are using the Task Debugger because open channels could be due to debugging. Therefore, if you do not correctly close all channels to the terminal that you open in a step procedure, the task works in the Task Debugger but will be canceled at run time.

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):

• Application database
  You create application database files with the ADU command BUILD APPLICATION. These files contain information used by ACMS in running tasks.
• Menu database
  You create menu database files when you use the ADU command BUILD MENU. These files contain binary versions of menu definitions.

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.

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

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:

• The initialization procedure, termination procedure, or a step procedure signals a FATAL (F) error.
• The initialization procedure returns a bad status with a severity level of FATAL (F), ERROR (E), or WARNING (W).
• Channels to the terminal are left open after the procedure returns control to the task definition.

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.