You can remove breakpoints at any time during a debugging session with the CANCEL BREAK command. For example:

ACMSDBG> CANCEL BREAK VR_RESERVE_CAR_TASK\$BEGIN

To remove all breakpoints in a task or in all tasks for the task group that you are debugging, use the /ALL qualifier. For example:

ACMSDBG> CANCEL BREAK /ALL=VR_RESERVE_CAR_TASK

This command removes all breakpoints in VR_RESERVE_CAR_TASK. If you do not include a task name in the /ALL qualifier, the command removes all breakpoints in all tasks.

7.3.5 Running a Task in the ACMS Task Debugger

To start a task you want to run, use the SELECT command. For example:

ACMSDBG> SELECT VR_RESERVE_CAR_TASK

The name you use in the SELECT command must be the name of the task in the task definition. For example:

REPLACE GROUP VR_TASK_GROUP . . . TASKS ARE RESERVE_CAR : TASK IS VR_RESERVE_CAR_TASK;

If a task uses information entered as part of the selection string, you can include this information as part of the SELECT command. For example:

ACMSDBG> SELECT DISPLAY_EMPLOYEE JONES

In this example, the Display Employee task expects an employee name to be passed to it in the ACMS$SELECTION_STRING workspace. If you enter a name after the task name, ACMS moves the name into the ACMS$SELECTION_STRING workspace and passes it to the task. For further explanation of the use of selection strings, see Compaq ACMS for OpenVMS Writing Applications.

When you use the SELECT command, select only one task at a time. If you have selected a task and it is still running, use the CANCEL TASK command to stop the current task before starting another one:

ACMSDBG> CANCEL TASK

The CANCEL TASK command does not take any parameters or qualifiers. It always stops the current task, if there is one. If the task has context in a server when it is canceled, and if there is a cancel procedure defined for the server, the cancel procedure runs. If there is a cancel action defined for the task, that action is performed after the server cancel procedure, if any, runs.

When you select a task, the ACMS Task Debugger starts the task. Once the task reaches the first 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.

7.3.6 Checking Values in Workspaces

You can use both the ACMS Task Debugger and the OpenVMS Debugger to check values in workspaces.

Use the ACMS Task Debugger to check the following workspace values:

• Initial values
• Entered values
• Values in ACMS$PROCESSING_STATUS

The following sections explain how to check the workspace values listed above.

7.3.6.1 Checking Initial Values

Use the EXAMINE command to check the initial value of a workspace field. For example:

ACMSDBG> EXAMINE CHECKOUT_SITE_ID OF VR_VEHICLE_RENTAL_HISTORY_WKSP CHECKOUT_SITE_ID of VR_CHECKIN_TASK\VR_VEHICLE_RENTAL_HISTORY_WKSP: 0

In this example, the initial value of the CHECKOUT_SITE_ID field is 0.

You can also examine the initial contents of an entire workspace. For example:

ACMSDBG> EXAMINE VR_VEHICLE_RENTAL_HISTORY_WKSP VR_CHECKIN_TASK\VR_VEHICLE_RENTAL_HISTORY_WKSP VEHICLE_ID: +0 CHECKOUT_SITE_ID: +0 RESERVATION_ID: +0 . . .

To continue running the task after you check an initial workspace value, enter GO after the ACMSDBG> prompt. The GO command tells the Task Debugger to run the task until it reaches the next breakpoint.

7.3.6.2 Checking Entered Values

As you debug a task, exchange and processing steps store new data in workspace fields. At breakpoints in the task, you can use the EXAMINE command to examine the contents of workspaces to determine whether the task is functioning correctly. For example:

ACMSDBG> EXAMINE CHECKOUT_SITE_ID OF VR_VEHICLE_RENTAL_HISTORY_WKSP CHECKOUT_SITE_ID of VR_CHECKIN_TASK\VR_VEHICLE_RENTAL_HISTORY_WKSP: 1

You can also examine the contents of an entire workspace. For example:

ACMSDBG> EXAMINE VR_VEHICLE_RENTAL_HISTORY_WKSP VR_CHECKIN_TASK\VR_VEHICLE_RENTAL_HISTORY_WKSP VEHICLE_ID: +2 CHECKOUT_SITE_ID: +1 RESERVATION_ID: +26 . . .

In this example, reservation 26 was correctly retrieved from the VEHICLE_RENTAL_HISTORY relation in the AVERTZ database. In this case, the car was rented from site number 1.

While debugging a task, you might find that a workspace does not contain the data you expect. When you encounter such a problem, check that:

• The order of the workspaces in the form definition and step procedures is the same as the order specified in the task definition.
• The workspace definition is the same in the form definitions, the step procedures, and the task definition; if you have modified a workspace definition, be sure to rebuild all the components that reference the workspace.
• The forms used by the task correctly return the necessary data in a RECEIVE or TRANSCEIVE operation.
• The step procedures called by the task read the correct records from a database or a file.

You can check the contents of the ACMS$PROCESSING_STATUS workspace by using the EXAMINE command. Using the EXAMINE command, you can make sure that the workspace message field contains the correct message and that the correct error codes are loaded into ACMS$T_STATUS_TYPE.

You can use the EXAMINE command to check that a procedure did what was expected. For example, if a read was successful, a workspace should contain a value, and the ACMS$T_SEVERITY_LEVEL field of the system workspace should contain the value S, showing that the process was successful:

ACMSDBG> EXAMINE ACMS$T_SEVERITY_LEVEL ACMS$T_SEVERITY_LEVEL OF VR_RESERVE_CAR_TASK: S

For a detailed discussion of the ACMS$PROCESSING_STATUS workspace, see Compaq ACMS for OpenVMS Writing Applications.

7.3.7 Debugging Transaction Timeout Code

In an ACMS application definition, you can specify a time limit within which a distributed transaction must complete. If the transaction does not end within the specified number of seconds, ACMS rolls back the transaction.

You can use the following commands to test that a task handles transaction timeout errors correctly:

• SET TRANSACTION_TIMEOUT seconds
  After you set a transaction timeout limit using this command, ACMS raises a transaction exception if a transaction does not complete in the specified amount of time.
• CANCEL TRANSACTION_TIMEOUT
  When you have finished testing the task definition logic to handle transaction timeouts, you can use this command to cancel the transaction timeout period you set previously.
• SHOW TRANSACTION_TIMEOUT
  You can use this command to determine the current transaction timeout value.

By default, there is no transaction time limit. Chapter 10 contains reference information about these commands.

7.3.8 Stopping the Task Debugger

Use the EXIT command or [Ctrl/Z] at the ACMSDBG> prompt to exit the Task Debugger and return to the DCL command-level prompt:

ACMSDBG> EXIT $

If you exit the Task Debugger while server processes are still active, these servers are stopped. If the server has a termination procedure defined for it, the termination procedure is executed.

If there is some reason that you do not want the server's termination procedure to run, you can set a breakpoint at the termination procedure. When you reach the breakpoint, use the EXIT command at the OpenVMS Debugger prompt to cause the server process to exit without executing the termination procedure.

7.4 Using the OpenVMS Debugger

Section 7.3 explains how to use the ACMS Task Debugger to debug the steps in a task. This section explains how to use the OpenVMS Debugger to debug server procedures. Transfer control to the OpenVMS Debugger in a server process in one of the following ways:

• Start a server.
  When a server is started, the server comes up under the control of the OpenVMS Debugger. See Section 7.3.3.1 for information on starting servers.
• Issue the INTERRUPT command.
  When the server is already started, you can use the ACMS Task Debugger INTERRUPT command to transfer control to the OpenVMS Debugger in the server. See Section 7.3.3.3 for details.
• Set a breakpoint in the procedure code.
  If you set a breakpoint in your procedure code at a time when the server is under the control of the OpenVMS Debugger, you return to the server when you reach this breakpoint.

Once you display the DBG> prompt, you can debug your procedure as you debug procedures in any standalone program. You can enter any of the OpenVMS Debugger commands that are valid for the language used. There are, however, situations in which the OpenVMS Debugger behaves differently when you use it in an ACMS environment.

Following are details that are specific to using the OpenVMS Debugger in an ACMS environment:

• Using SET BREAK/EXCEPTION
  You might want to use the SET BREAK/EXCEPTION command so that the debugger stops the program at any line where an error occurs. However, be sure to cancel the exception break before canceling a task. Otherwise, a breakpoint occurs in the ACMS code controlling the server process, with confusing messages from the Task Debugger.
• Using SET WATCH and defining symbols
  Because workspace addresses can change during a task, be careful when using the OpenVMS Debugger SET WATCH command. When you use SET WATCH, the debugger sets a watchpoint at a location in the workspace to watch an entity and to notify you if the value changes. Because the workspace can be in a different location for each task instance, the field you look at might be in a different location each time, and you might never get a watchpoint.
  A task can exit from a server process and later use the same server again with different workspace addresses. When a task reenters a server process, redefine symbols and reset watchpoints. Also, changing the contents of a workspace from the ACMSDBG> prompt when the task is not using the server, or when it is using a different server, does not trigger a watchpoint set in the server.

For more information on how to set, display, and change breakpoints, see the OpenVMS Debugger Manual. For features specific to a language, see the user's guide for that language.

7.5 Returning to the ACMSDBG> Prompt

In the process of debugging a task definition and server procedures, you might want to use an ACMS Task Debugger command, but you cannot because you are not at the ACMSDBG> prompt. Following are situations in which you might want to display the ACMSDBG> prompt:

• As you step through server code, you decide that you want to set a breakpoint in your task.
  You must transfer control to the ACMS Task Debugger to set your task breakpoint.
• As you step through a task, you might want to interrupt a server to set a breakpoint.
  Once you set your breakpoint, you need to return control to the ACMS Task Debugger to continue stepping through the task.
• Your server is in an infinite loop.
  You need to transfer control to the ACMS Task Debugger so that you can use the INTERRUPT SERVER command to get control of your server. Once you finish with your server code, you might need to return control to the ACMS Task Debugger again to cancel the task.

Use [Ctrl/G] to display the ACMDBG> prompt in all of these situations.

Users who have written their own command process, called an agent program, must not only debug their ACMS task definitions and the high-level language step procedures called from the task definition, but also debug the flow of control between an agent program and an ACMS task.

When you debug a conventional ACMS task, the task and the task submitter both execute in the same Task Debugger process, and you have your choice of debugging using one or two terminals. However, when you debug a task called by a user-written agent program, you must debug both the task and the agent program at the same time. Because an additional process is running, you must allocate a terminal to each process. One process runs the agent program, whose only job is to select ACMS tasks. The other process runs the ACMS Task Debugger and performs the usual debugging functions, including:

• Starting and stopping servers
• Setting breakpoints
• Examining and depositing data in workspaces
• Assigning logical names for servers
• Executing tasks

These task debugging functions are described in Section 7.2.5 and Section 7.3.

The processes running the agent program and the Task Debugger require special consideration during debugging. Before debugging, set up so that the agent program selects the task in the ACMS Task Debugger rather than in an ACMS application. Follow these steps to debug tasks that are submitted by agent programs:

1. Use the ACMS$SIGN_IN service in the agent program.
   Do not use the default submitter when debugging tasks submitted by agent programs. The agent program must execute the ACMS$SIGN_IN service to obtain a submitter ID.
2. Set protection for remote terminals.
   Set WORLD protection for remote terminals to read/write access. Check the protection set for remote terminals using the DCL SHOW DEVICE command:

   $ SHOW DEV/FULL TT

   
   If the terminal does not have WORLD:RW protection, then set the appropriate protection. For example:

   $ SET PROT=W:RW/DEV TT

3. Check quotas, parameters, and logical names.
   Make sure that system quotas and parameters are set using the values specified in Section 7.2.6. Also, make sure that any logical names used by the ACMS Task Debugger are defined. (See Section 7.2.3.)
4. Start the ACMS Task Debugger.
   Use the ACMS/DEBUG command to start the ACMS Task Debugger. With the command, include the /AGENT_HANDLE qualifier and a handle name (for the agent program) that is unique to the system on which you are debugging the task.
   The handle name must be a maximum of 39 characters. To ensure that the agent handle name is unique to the system, you can choose to include the PID of the task debugger or the user name of the person doing the debugging in the /AGENT_HANDLE name.
   The following example shows how to start the Task Debugger using an agent handle named VR_26200E49 and a task group database called VR_TASK_GROUP:

   $ ACMS/DEBUG/AGENT_HANDLE=VR_26200E49 VR_TASK_GROUP ACMSDBG>

   
   When you start the Task Debugger and include the /AGENT_HANDLE qualifier, you can select tasks from within the Task Debugger as well as submitting calls to ACMS tasks from an agent program. Select or submit only one task at a time.
   You can run more than one agent program consecutively or simultaneously with the Task Debugger, but only one agent program can select a task at one time. Also, you cannot use the ACMS Task Debugger CANCEL TASK command to cancel tasks that are called by agent programs.

5. Set up the ACMS Task Debugger environment.
   After you start the ACMS Task Debugger, it returns its ACMSDBG> prompt. You can then start servers (described in Section 7.3.3) and define the debugging environment to include items such as breakpoints (described in Section 7.3.4).
6. Accept calls to ACMS tasks from agent programs.
   Use the ACMS Task Debugger ACCEPT command to have the ACMS Task Debugger accept calls from the agent program:

   ACMSDBG> ACCEPT

   
   After this command, the ACMS Task Debugger waits until the agent program selects a task. After the agent program selects a task, the task executes in the ACMS Task Debugger. (Chapter 10 describes all the ACMS Task Debugger commands.)
   You can use [Ctrl/G] to return to the ACMSDBG> prompt to set more breakpoints, for example, or to exit from the debugger. To resume waiting for the task call, enter the GO command.
   The ACCEPT command accepts one task selection at a time from an agent program. To allow the ACMS Task Debugger to accept subsequent calls to tasks without reentering the ACCEPT command for each task selection, use the /CONTINUOUS qualifier on the ACCEPT command:

   ACMSDBG> ACCEPT/CONTINUOUS

   
   This allows the ACMS Task Debugger to accept task selections from an agent program without entering the ACCEPT command at the agent program's terminal each time.

7. Define logical names for the application names used in the agent program.
   To make tasks selected by the agent program run in the Task Debugger, define two process logical names before running the agent program.
   • Define the logical name ACMS$DEBUG_AGENT_TASK to be either TRUE (T or t), YES (Y or y), or an ASCII number with an odd value:

     $ DEFINE ACMS$DEBUG_AGENT_TASK Y

   • Assign a logical name for the application name used in the agent program. The agent program code contains actual application and task names that are defined in the application definition. However, because the agent program selects tasks in the ACMS Task Debugger, you can use logical names (rather than changing the names in the agent program) to associate the application name used in the agent program and the handle name for the debugger. The following example illustrates how to define the application name as a logical name that equates to the agent handle that you specified when you started the Task Debugger.

     $ DEFINE VR_APPL VR_26200E49

     
     In this case, VR_APPL is the application name used in the agent program, and VR_26200E49 is the agent handle name included on the ACMS/DEBUG command when the debugger was started (see the example in step 4).
     The logical name is optional; if the application name is not defined as a logical name, then the application name in the agent program is used as the /AGENT_HANDLE name. If the agent program cannot find a Task Debugger process with the appropriate handle name, the agent program returns an ACMS-E-SRVNOTFOUND error.

8. Do any preparation work necessary for DECforms.
   Because DECforms runs in the agent process, do all DECforms setup in the agent process. Section 7.2.4 contains instructions for preparing to debug DECforms escape routines.
9. Run the agent program.
   Remember that the agent program can select tasks in only one application. If the agent program's ACMS$GET_PROCEDURE_INFO service selects a task from a second application, the ACMS Task Debugger returns the ACMS-E-DBGMULTIPKGS error message.