HP OpenVMS Systems Documentation

You can use the INTERRUPT command to interrupt a server and transfer control to the OpenVMS Debugger. After you enter this command, the OpenVMS Debugger displays the DBG> prompt. You can then set breakpoints, examine addresses, or change values in a server that has already been started. Beginning with ACMS Version 3.2, you can specify an instance of a server that is allocated to a specific task. Reference information about this command is in Chapter 10.

If you do not specify a task with the INTERRUPT command, ACMS interrupts the named server if the current task instance has context in that server. If the task is not retaining context in the named server, or if no task is active, then ACMS interrupts the first free server process belonging to the named server. This process is allocated to the first task or first called task that calls a procedure in the named server.

In a distributed transaction, both parent and called tasks might use the same server. As explained in Section 7.3.3.1, you can start separate instances of a server. To interrupt a specific server process when both tasks have started, specify a task name after the INTERRUPT command. Following is an example of setting breakpoints for a procedure after a Task Debugger INTERRUPT command.

ACMSDBG> INTERRUPT VR_SERVER/ TASK=VR_RESERVE_CAR_TASK
Terminal is in server VR_SERVER
DBG> SET BREAK VR_FIND_SI_PROC\MAIN\MAIN-SECTION
DBG> GO
[CTRL/G]
ACMSDBG>

When you specify a task name, ACMS interrupts the process currently owned by that task. In the previous example, ACMS interrupts the VR_SERVER owned by the called task, VR_RESERVE_CAR_TASK. If the named task (in this case, VR_RESERVE_CAR_TASK) is not currently retaining context in the named server (in this case, VR_SERVER), then the command returns an error. The example also illustrates using [Ctrl/G] to return to the ACMS Task Debugger prompt, ACMSDBG>.

If you are debugging a recursive task, supplying a task name does not have any effect; ACMS ignores the /TASK qualifier and follows the rules for interrupting a server when no task name is supplied.

You cannot use the INTERRUPT command to interrupt servers that are in the process of starting or stopping. If you do, ACMS displays the following error message:

%ACMSDBG-E-SRVNOTUP, Server ... is not started

If there is a bug in your initialization procedure that causes it not to return, you cannot stop the server. To debug the initialization procedure, you must use [Ctrl/G] to display the ACMSDBG> prompt, and then exit from the Task Debugger. When you start the Task Debugger again and attempt to start the server, set a breakpoint at the initialization procedure so that you can debug it. Do the same for termination procedures.

7.3.4 Setting and Removing Breakpoints in a Task

After you start the servers needed by a task for debugging, you are ready to start the task. However, you might want to set breakpoints before selecting the task.

A breakpoint is a selected place where the debugger stops a task. For example, the first time through a task, you might want to stop the task at the beginning of the action part of each exchange step. You can then check that the information that should be in a workspace is actually there.

You use the SET BREAK command to set breakpoints in a task. For example:

ACMSDBG> SET BREAK VR_RESERVE_TASK

In this example, a breakpoint is set in the VR_RESERVE_TASK.

After you have used ACMS Task Debugger commands to examine and deposit data in workspaces, set breakpoints, and so on, enter GO to continue processing from that breakpoint in the task. Otherwise, the step or task cannot complete, and you cannot select another task.

The following sections explain how to:

• Set breakpoints in a task
• Debug a task called by another task
• Remove breakpoints from tasks

If there are breakpoints that you often use, you can create a command file containing SET BREAK commands. Then use the at-sign (@) command to run the command (.COM) file. For example:

ACMSDBG> @RESERVE_CAR_DBG.COM

Setting up a command file of common commands can make a debugging session much easier.

7.3.4.1 Setting Location and Event Breakpoints

With the ACMS Task Debugger, you can use a breakpoint to cause the Task Debugger to break either at a particular location in a task or when a particular event occurs:

• Location breakpoints
  Use the following format to define a location breakpoint:
  task-name\step-name\location
  In the format above:
  • Task-name is required.
  • Step-name is optional.
    The default is the root step of the task.
  • Location is optional.
    The default is the beginning of the step.
  
  The step-name can be the one you define in the task definition. If you do not define a label for a step, ACMS assigns one. The label that ACMS assigns always has the format $STEP_n, where n is the number of the step. For example:

  $STEP_1

  
  Step numbering continues sequentially from step to step rather than just for steps that do not have labels. A label supplied in a task definition replaces the ACMS label. ACMS assigns the name $TASK to the block step of a multiple-step task and to the only step in a single-step task.

  Note To see a listing of step label names, use the ADU DUMP command to obtain a dump of the task group database. Example 7-2 contains part of a dump file.

  
  You can use four symbols for location breakpoints: $BEGIN, $ACTION, $HANDLER, and $END. Table 7-3 lists location symbols and explains the effect of using each of them.

  Table 7-3 Location Breakpoint Symbols

  Symbol	Explanation
  $BEGIN	Breakpoint occurs at the start of the step.
  $ACTION	Breakpoint occurs at the start of the action of the step. At this breakpoint, none of the actions for the step have been performed.
  $HANDLER	Breakpoint occurs at the start of the exception handler action for the step. At this breakpoint, none of the exception handler actions for the step have been performed. The exception reason, however, has been moved to the ACMS$PROCESSING_STATUS workspace.
  $END	Breakpoint occurs at the end of the step. At this breakpoint, the action clauses (if any) have been performed.

• Event breakpoints
  Use the following format to define an event breakpoint:
  task-name\event
  In the format above:
  • Task-name is required.
  • Event is required.
  
  You can use two symbols for event breakpoints: $EXCEPTION and $CANCEL. Table 7-4 lists event symbols and explains the effect of using each of them.

  Table 7-4 Event Breakpoint Symbols

  Symbol	Explanation
  $EXCEPTION	Breakpoint occurs as soon as an exception is raised in the task. At this breakpoint, the exception reason has not been moved to the ACMS$L_STATUS field in the workspace. ACMS displays information about the exception (type, reason code, and so on).
  $CANCEL	Breakpoint occurs just before ACMS cancels the task. At this time, ACMS has called server cancel procedures but has not yet performed a task cancel action, if supplied.

At the $EXCEPTION breakpoint, ACMS has not yet updated the ACMS$PROCESSING_STATUS workspace with information about the exception. This allows you to examine the contents of the ACMS$PROCESSING_STATUS workspace at the time the exception occurred. Once you reach the $HANDLER breakpoint, ACMS has filled in the ACMS$PROCESSING_STATUS workspace with information about the exception. This enables you to examine the workspace before you execute the exception handler action.

Server cancel procedures are called after a task stops at the $EXCEPTION breakpoint and before a task stops at the $CANCEL breakpoint. Therefore, you must set a break at the $EXCEPTION breakpoint if you want to interrupt a server process in order to set a breakpoint in a server cancel procedure. Alternatively, you can use the OpenVMS Debugger to set a breakpoint in a server cancel procedure when you start the server process. Section 7.4 contains instructions for using the OpenVMS Debugger.

The breakpoints you set depend on the task you are debugging. Breakpoints are often useful at the beginning of a task, at the action part of each step, and at the block action for a task. Setting breakpoints at these places helps you make sure that the work part of each step has put the right values into the workspaces it used.

In setting breakpoints, be sure to include backslashes (\) to separate task name, step label, and symbol. Use the SHOW BREAK command to check the breakpoints set.

Example 7-1 contains part of a task definition that is annotated to show the use of breakpoint symbols.

                                         REPLACE TASK sample_task
                                         .
                                         .
                                         .
  sample_task\$BEGIN ----------->        BLOCK WITH DISTRIBUTED TRANSACTION
                                         get_number:
 -------------------------                 EXCHANGE
| sample_task\$EXCEPTION  |                    .
| When exception occurs   |                    .
 -------------------------                     .
 -------------------------
| sample_task\$CANCEL     |
| When cancellation occurs|
 -------------------------
                                         get_data:

  sample_task\get_data\$BEGIN -->          PROCESSING WORK IS
                                              CALL    sample_procedure
                                              .
                                              .
                                              .
  sample_task\get_data\$ACTION --->           ACTION IS
                                                 SELECT FIRST TRUE OF
                                                 .
                                          .
                                                 .
  sample_task\get_data\$END ------>              END SELECT;

                                         display_data;
                                            EXCHANGE
                                            .
                                            .
                                            .
                                         END BLOCK;

  sample_task\$ACTION -------------->    ACTION IS
                                            REPEAT STEP;

  sample_task\$HANDLER ------------->    EXCEPTION HANDLER ACTION
                                            .
                                            .
                                            .
  sample_task\$END ----------------->    END DEFINITION;

Using an ADU task-group dump file can simplify the job of debugging ACMS tasks because a dump file of a task group lists, in one place, all of the following:

• Names of servers
• Tasks
• Workspaces
• Steps (in tasks)

Rather than searching through directories and listings, in the dump file you can find the names of all the elements that you need to know for debugging. To obtain a dump file, enter ADU and use the DUMP GROUP command. For example:

ADU> DUMP GROUP VR_TASK_GROUP /OUTPUT=VR_TASK_GROUP.DMP

Examples of how you can use a dump file in debugging are bolded and numbered in Example 7-2. The numbers correspond to the numbered explanations following the example.

(1) Task group file : UDISK:[UNAME]VR_TASK_GROUP.TDB;5
   Creation time   :  6-MAR-1991 15:08:29.07
   File size       : 107 BLOCKS
 ==============================================================================

               CDD node name : AVERTZ_CDD_GROUP:VR_TASK_GROUP

 ==============================================================================
   GROUP workspace count  : 0                             Server count    : 4
   TASK workspace count   : 21                            Task count      : 5
   USER workspace count   : 0

   Message file list -
       1. "AVERTZ_DEFAULT:VRMSG.EXE"

   No request library

   Forms list -
       1. Form: VR_FORM                          File: AVERTZ_DEFAULT:VR_FORM.FORM

 ==============================================================================
                                   WORKSPACES
 ==============================================================================
   GROUP workspace list -
   USER workspace list -
   TASK workspace list -
       VR_CONTROL_WKSP                                             0
       VR_TRANS_WKSP                                               1
       .
       .
       .
       ACMS$PROCESSING_STATUS                                      18
       ACMS$TASK_INFORMATION                                       19
       ACMS$SELECTION_STRING                                       20

 ------------------------------------------------------------------------------
   Workspace name  : VR_CONTROL_WKSP                      Workspace index : 0
   Workspace size  : 127 BYTES                            Workspace type  : TASK
   Owner node name : AVERTZ_CDD_GROUP:VR_TASK_GROUP       Owner type      : GROUP
   Initial content -
       00000000 00000000 00000000 00000000         "................"
         The above line is repeated 6 times (96 BYTES).
       00000000 00000000 00000000 00000000         "..............."
   .
   .
   .

 ==============================================================================
                                    SERVERS
 ==============================================================================
 ------------------------------------------------------------------------------
(2) Group server name  : VR_UPDATE_SERVER                  Server index : 1
   Server username    : USERNAME OF APPLICATION           Server type  : PROCEDURE
   Rundown on cancel  : YES, IF INTERRUPTED               Reusable     : YES
   Username attribute : NOT EXPLICITLY SPECIFIED
   Server image file  : "AVERTZ_DEFAULT:VR_UPDATE_SERVER.EXE"
   Execute termination procedure: ALL RUNDOWNS
 .
 .
 .

 ==============================================================================
                                     TASKS
 .
 .
 .
 ------------------------------------------------------------------------------
(3)               Task name : VR_COMPLETE_CHECKOUT_TASK
 ------------------------------------------------------------------------------
   Task type            : GLOBAL
   Composable           : YES
   Wait/delay specified : NONE                              Task index    : 4

   The following is a list of 5 workspaces that are arguments to this task -
      1.  Workspace name : VR_SENDCTRL_WKSP                  Access mode:  READ
      2.  Workspace name : VR_CONTROL_WKSP                   Access mode:  MODIFY
      3.  Workspace name : VR_RESERVATIONS_WKSP              Access mode:  MODIFY
      4.  Workspace name : VR_TRANS_WKSP                     Access mode:  READ
      5.  Workspace name : VR_VEHICLES_WKSP                  Access mode:  READ


   The following is a list of 9 workspaces referenced by this task -

      1.  Workspace name : ACMS$PROCESSING_STATUS            Workspace index : 18
          Access type    : UPDATE NO LOCK
          .
          .
          .
   000 ---------------------------------------------------------------------------
   000     Step name: $TASK             Step type: BLOCK
   000 ---------------------------------------------------------------------------
   000 BLOCK STEP CHARACTERISTICS -
   000     Server context   : RETAINED
   000     I/O method       : REQUEST
   000     Recovery unit    : NOT ACTIVE
   000     Transaction state: STARTING


   000 BLOCK WORK -
   001     -----------------------------------------------------------------------
(4) 001         Step name : PERFORM
   001     -----------------------------------------------------------------------
   001     STEP CHARACTERISTICS -

   001         Step type        : PROCESSING     Step index    : 0
           .
           .
           .
   001     STEP WORK -

   001     1.  Conditional      : YES
           .
           .
           .
   001         Processing server: VR_UPDATE_SERVER                 Server index : 1
   001             The procedure vector index in the server image is 3
   001         2 workspaces passed to the server -
   001             Wksp. name: VR_RESERVATIONS_WKSP              Wksp. index: 5
   001             Wksp. size: 140
   001             Wksp. name: VR_VEHICLES_WKSP                  Wksp. index: 7
   001             Wksp. size: 71

(5) 001     STEP ACTION -

   001     1.  Conditional      : YES
   001         Comparison type  : EQUAL
   001         Data type        : TEXT STRING
   001         Source field information -
   001             Source type  : WORKSPACE FIELD
   001             Wksp. name   : ACMS$PROCESSING_STATUS
               .
               .
               .
   001         Recovery action  : NO RECOVERY ACTION
   001         Transaction action: NO TRANSACTION ACTION
   001         Context action   : RETAIN SERVER CONTEXT IF ACTIVE
   001         Sequencing action: RAISE EXCEPTION
   001             Returning    : A MESSAGE NUMBER
   001             Message no.  : 08018122
               .
               .
               .
   001             Error message will be put into the following workspace :
   001                 Wksp. name   : VR_CONTROL_WKSP
   001                 Wksp. index  : 0
   001                 Field offset : 11
   001                 Field size   : 80
   001         Move Action      : NONE SPECIFIED
    .
    .
    .

Following are explanations of how you can use a task group dump file to help you in debugging a task. The numbers correspond to those in Example 7-2.

1. Use the task group name when you start the ACMS Task Debugger:

   $ ACMS/DEBUG VR_TASK_GROUP/WORKSPACE

2. Use the server name to start the server in ADU:

   ADU> START VR_UPDATE_SERVER

3. Use the task name to select the task:

   ADU> SELECT VR_COMPLETE_CHECKOUT_TASK

4. Use the task name, the step name, and $BEGIN to set a breakpoint at the beginning of a task:

   ACMSDBG> SET BREAK VR_COMPLETE_CHECKOUT_TASK \ PERFORM \ $BEGIN

5. Use the task name, step name, and $ACTION to set a breakpoint at the action part of a step:

   ACMSDBG> SET BREAK VR_COMPLETE_CHECKOUT_TASK \ PERFORM \ $ACTION

When debugging a task that is called by another task (parent task), use the SET BREAK command to pause execution of the called task just as you do when you debug any ACMS task. If you do not define breakpoints in the called task, then the task runs to completion and returns control to the parent task.

If you use a STEP command at the point in the parent task where the parent task calls another task, the Task Debugger steps into the called task. Then use the STEP command to execute one exchange or processing step at a time. The Task Debugger executes one step in the called task for each STEP command issued.

To avoid stepping all the way through the called task, set a breakpoint at the end of the called task to have it run to completion without pausing at each exchange or processing step:

ACMSDBG> SET BREAK called_task\$END
ACMSDBG> GO

The commands in this example cause the Task Debugger to execute all the steps in the task CALLED_TASK without waiting for you to issue the STEP command. After reaching the breakpoint at the end of the called task, enter the STEP command to have the Task Debugger resume stepping through the parent task.