Compaq ACMS for OpenVMS
Writing Server Procedures

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.

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:

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

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

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.