Compaq ACMS for OpenVMS
Writing Server Procedures


Previous Contents Index

7.3.3.3 Interrupting Servers

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.

Note

If you use the INTERRUPT command, do not link the server image with /NOTRACEBACK. If the server image was linked with /NOTRACEBACK, and you try to access the server process with an INTERRUPT command, the server process returns a fatal error and exits. The debugger returns the Task Debugger prompt, ACMSDBG>. You must then use the START command to restart the server.

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:

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:

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.

Example 7-1 Task Definition with 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; 
 

7.3.4.2 Using a Dump File

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:

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.

Example 7-2 Sample Task Group Dump File

(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
     
    

7.3.4.3 Debugging a Task Called by Another Task

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.


Previous Next Contents Index