# Compaq ACMS for OpenVMS
Writing Server Procedures

Previous | Contents | Index

# Chapter 10
ACMS Task Debugger Commands

This chapter lists the commands available with the ACMS Task Debugger. You can use these commands to run an ACMS task without starting an application, to control the task, and to examine and change the contents of the workspaces the task uses as it runs. Table 10-1 lists the ACMS Task Debugger commands described in this chapter.

Table 10-1 ACMS Task Debugger Commands
Command | Description
--- | ---
@ (at sign) | Runs a file containing Task Debugger commands.
ACCEPT | Accepts one task selection at a time from one or more agent programs.
ASSIGN | Assigns a process logical name to a server.
CANCEL BREAK | Removes one or more breakpoints from a task or all breakpoints from all tasks.
CANCEL TASK | Cancels the current task.
CANCEL TRANSACTION_TIMEOUT | Cancels the transaction timeout period previously set.
DEPOSIT | Puts a value into a workspace field.
EXAMINE | Displays the current value of a workspace field.
EXIT | Ends the debugger session and returns you to DCL, or ends the running of a file of Task Debugger commands.
GO | Continues a task after a breakpoint or INTERRUPT command. Also continues a task interrupted with `[Ctrl/G]`.
HELP | Displays information about Task Debugger commands and symbols.
INTERRUPT | Interrupts a server and gives control to the OpenVMS Debugger in that server process.
SELECT | Selects and starts a task.
SET BREAK | Sets a breakpoint in a task.
SET SERVER | Names the default server for ASSIGN commands.
SET TRANSACTION_TIMEOUT | Sets the transaction timeout limit (in seconds).
SHOW BREAK | Displays breakpoints set for all tasks.
SHOW SERVERS | Displays all servers that have been started with the START command.
SHOW TRANSACTION_TIMEOUT | Displays the value of the current transaction timeout.
SHOW VERSION | Displays the version number of the Task Debugger.
START | Starts one or more instances of one or more servers.
STEP | Runs the task to the next task-level step point.
STOP | Stops one or more servers.

# @ (At sign) Command

> Runs the debugger commands contained in the named file. The file can contain any ACMS Task Debugger command, including another at-sign command. When the ACMS Task Debugger reaches an EXIT command or the end of the file, it returns control to the terminal or command procedure that issued the at-sign command.

## Format

> @ file-spec

## Parameter

> ### file-spec

> The OpenVMS file specification of the command procedure to be run. The default device and directory are your current default device and directory. The default file type is .COM. Do not enclose the file specification in single or double quotation marks.

## Notes

> The ACMS Task Debugger does not recognize a SET VERIFY command. When the command procedure runs, the commands in the file are not displayed on the terminal screen.

> Include comments in the command file by preceding them with an exclamation mark (!).

##

### Examples

#1
    ACMSDBG> @VRDBG.COM

> This example shows how to run the command procedure whose file specification is VRDBG.COM; it is in the current default directory. The following example is a command procedure.

#2
    ! Command procedure for debugging tasks using the VR_SERVER.
    !
    ASSIGN /SERVER=VR_SERVER SYS$SAMPLE:VRFILE.DAT VR_FILE
    START VR_SERVER

> In this example, the equivalence name SYS$SAMPLE:VRFILE.DAT is assigned to the process logical name VR_FILE for the server named VR_SERVER. The command file VRDBG.COM specifies this assignment.

# ACCEPT Command

> Accepts calls from an agent program.

## Format

> ACCEPT [/qualifier]

> Command Qualifier | Default
> --- | ---
> /CONTINUOUS | None

## Qualifier

> ### /CONTINUOUS

> Specifies that the Task Debugger can accept multiple consecutive task selections from agent programs.

## Notes

> One or more agent programs can call tasks, but the ACCEPT command accepts only one task selection at a time. You must type the ACCEPT command each time you want the Task Debugger to accept another call from an agent program unless you specify the /CONTINUOUS qualifier. The /CONTINUOUS qualifier allows the Task Debugger to accept subsequent task calls without entering the ACCEPT command each time. After you type the ACCEPT or ACCEPT/CONTINUOUS command, the Task Debugger waits until the agent program calls a task. Then the task executes in the Task Debugger.

> Before the agent program calls a task, use `[Ctrl/G]` to return to the ACMSDBG> prompt if you want to enter more Task Debugger commands before executing the task. This discontinues the effect of the /CONTINUOUS qualifier. To resume waiting for the task call, enter the GO command.

> Tasks selected by agent programs cannot be canceled using the CANCEL TASK command.

## Example

    ACMSDBG> ACCEPT/CONTINUOUS

> This example allows the Task Debugger to accept consecutive calls to tasks without reentering the ACCEPT command for each task selection.

# ASSIGN Command

> Assigns a process logical name for a server.

## Format

> ASSIGN [/qualifier] equivalence-name logical-name

> Command Qualifier | Default
> --- | ---
> /SERVER=server-name | /SERVER=current-server

## Parameters

> ### equivalence-name

> The OpenVMS file specification or other string assigned to the logical name. The string must conform to the standards for equivalence names, which are explained in OpenVMS DCL Dictionary.

> ### logical-name

> The 1- to 63-character process logical name assigned. The logical name must conform to the standards for logical names as explained in OpenVMS DCL Dictionary.

## Qualifier

> ### /SERVER=server-name

> Names the server for which the logical name is assigned. The server name must be the same as the name used in a Task Debugger START command; that is, it must be the name assigned to the server in the task group definition. The default server name is the one named in the most recent SET SERVER command.

## Note

> When ACMS starts a server, it creates the server with all the logical names specified up to that point. Therefore, to assign logical names for a server, assign them before starting the server.

##

### Examples

#1
    ACMSDBG> ASSIGN SYS$SAMPLE:VRFILE.DAT VR_FILE

> In this example, the equivalence name SYS$SAMPLE:VRFILE.DAT is assigned to the process logical name VR_FILE for the current server.

#2
    ACMSDBG> ASSIGN /SERVER=VR_SERVER SYS$SAMPLE:VRFILE.DAT VR_FILE

> In this example, the equivalence name SYS$SAMPLE:VRFILE.DAT is assigned to the process logical name VR_FILE for the server named VR_SERVER.

# CANCEL BREAK Command

> Removes one or more breakpoints from a task or from all tasks.

## Format

> CANCEL BREAK [/qualifiers] [breakpoint]

> Command Qualifier | Default
> --- | ---
> /ALL[=task-name] | None

## Parameter

> ### breakpoint

> Names a breakpoint to cancel in the current task. See the SET BREAK command for the format of this parameter.

## Qualifier

> ### /ALL

> Declares that all breakpoints in all tasks or in one task are to be canceled. If you include an equal sign (=) and task name in the /ALL qualifier, the task name must be the name of the task in the task group definition.

## Note

> You must include either the /ALL qualifier or the breakpoint parameter in the CANCEL BREAK command.

##

### Examples

#1
    ACMSDBG> CANCEL BREAK VR_RESERVE_TASK\$STEP_1\$BEGIN

> This example shows how to cancel the breakpoint at the beginning of the first step of the Vehicle Rental Reserve Car Task, VR_RESERVE_TASK.

#2
    ACMSDBG> CANCEL BREAK /ALL=VR_RESERVE_TASK

> This example shows how to cancel all task-level breakpoints in the task VR_RESERVE_TASK.

# CANCEL TASK Command

> Cancels the current task.

## Format

> CANCEL TASK

## Notes

> You can use the CANCEL TASK command at the ACMSDBG> prompt when there is an active task that was started with the ACMSDBG SELECT command. However, you cannot use this command to cancel a task that was submitted by an agent program.

> To display the ACMSDBG> prompt when you are not at a breakpoint or when you are at an OpenVMS Debugger prompt, press `[Ctrl/G]`.

> When you use this command, the OpenVMS Debugger runs the cancel action if any is defined for the task. If the task has context in a server when it is canceled, the cancel procedure (if any) for that server is also run.

## Example

    ACMSDBG> CANCEL TASK

> This example shows how to cancel the current task.

# CANCEL TRANSACTION_TIMEOUT Command

> Cancels any transaction timeout period previously set.

## Format

> CANCEL TRANSACTION_TIMEOUT

## Notes

> You can use the CANCEL TRANSACTION_TIMEOUT command at the ACMSDBG> prompt when you have already set a transaction timeout period. Use the command when you have finished testing your transaction timeout handling.

## Example

    ACMSDBG> CANCEL TRANSACTION_TIMEOUT

> This example shows how to cancel the current transaction timeout.

# DEPOSIT Command

> Puts a value into a workspace field.

## Format

> DEPOSIT [/qualifiers] workspace-field-name=value

## Parameters

> ### workspace-field-name

> The name of a field in a workspace defined for the task. The value parameter is put into this field. Use the symbol for current location (.) to indicate that the field named in the last DEPOSIT or EXAMINE command is the field in which to put a value.

> ### value

> The data put into the workspace field. The qualifiers used with the DEPOSIT command define the length and data type of the value.

## Qualifiers

> ###

> When the Task Debugger receives a DEPOSIT command, it passes that command directly to the OpenVMS Debugger. The qualifiers for the DEPOSIT command are the same qualifiers available for the DEPOSIT command for the OpenVMS Debugger. These qualifiers determine the data type used to display the information in the workspace field. See OpenVMS Debugger Manual for a list of available qualifiers.

## Notes

> You can use the DEPOSIT command only if a task is active.

> Both the Task Debugger and the OpenVMS Debugger look at the same copy of the workspace. If you change a workspace value from the Task Debugger (ACMSDBG>), you see the changes in the OpenVMS Debugger; if you change a workspace value from the OpenVMS Debugger (DBG>), you see the changes in the Task Debugger.

## Example

    ACMSDBG> DEPOSIT RESERVATION_NUMBER = "000121"

> This example shows how to deposit the 6-byte ASCII value 000121 in the RESERVATION_NUMBER field.

# EXAMINE Command

> Displays the contents of a workspace field.

## Format

> EXAMINE [/qualifiers] workspace-field-name [OF workspace-record-name]

## Parameters

> ### workspace-field-name

> The workspace field to be read by the EXAMINE command. Use the symbol for current location (.) to indicate that the field named in the last DEPOSIT or EXAMINE command is the field you want to examine.

> ### workspace-record-name

> If the workspace-field-name is not unique, use the workspace-record-name to specify the name of the workspace that contains the field you want to examine.

## Qualifiers

> ###

> When the ACMS Task Debugger receives an EXAMINE command, it passes that command directly to the OpenVMS Debugger. The qualifiers for the EXAMINE command are the same qualifiers as for the EXAMINE command for the OpenVMS Debugger. These qualifiers determine the data type used to display information in the workspace field. See OpenVMS Debugger Manual for a list of available qualifiers.

## Notes

> You can use the EXAMINE command only if a task is active.

> Both the ACMS Task Debugger and the OpenVMS Debugger look at the task's copy of a workspace.

## Example

    ACMSDBG> EXAMINE RESERVATION_NUMBER OF VR_RECORD
    RESERVATION_NUMBER OF VR_RECORD: +121

> This example shows how to display the contents of the RESERVATION_NUMBER field of the VR_RECORD workspace.

# EXIT Command

> Ends the debugging session or ends the execution of commands in a command procedure. If typed after the ACMSDBG> prompt, the EXIT command stops all subprocesses started by the Task Debugger and returns to DCL command level. If included in a command procedure, the EXIT command returns control to the command stream that started the command procedure.

## Format

> EXIT

## Example

    ACMSDBG> EXIT

> This example shows how to end the current Task Debugger session.

# GO Command

> Continues a task after a breakpoint. Also returns you to a server process from which you have exited with `[Ctrl/G]` and continues any command after an INTERRUPT command.

## Format

> GO

## Note

> The GO command always restarts the task at the breakpoint where it stopped.

##

### Examples

#1
    ACMSDBG> SELECT VR_RESERVE_TASK
    Task breakpoint at VR_RESERVE_TASK\$TASK\$BEGIN
    ACMSDBG> GO

> This example shows how to start the task VR_RESERVE_TASK, which breaks at $BEGIN on the root step. The GO command restarts the task VR_RESERVE_TASK at that breakpoint.

#2
    ACMSDBG> INTERRUPT VR_SERVER
    Task is in server VR_SERVER
    DBG> SET BREAK UPDATE_RECORD
    DBG> GO
    [Ctrl/G]
    ACMSDBG> GO

> This example shows how to return to the OpenVMS Debugger prompt (DBG>) so that you can set breakpoints or use other OpenVMS Debugger commands in the server VR_SERVER. The example then shows how to return to the ACMSDBG> prompt and resume task execution.

# HELP Command

> Displays information about ACMS Task Debugger commands, step points, control characters, and symbols.

## Format

> HELP [topic] [...]

## Parameter

> ### topic

> A Task Debugger command, step point, or symbol about which information is available. Topics can have subtopics about which additional information is available.

##

### Examples

#1
    ACMSDBG> HELP

> This example shows how to display general information about the Task Debugger.

#2
    ACMSDBG> HELP EXAMINE

> This example shows how to display information about how to use the Task Debugger EXAMINE command.

# INTERRUPT Command

> Interrupts a server and gives control to the OpenVMS Debugger in that server process. Use this command to get the DBG> prompt in order to set breakpoints, examine addresses, or change values in a server that has already been started.

## Format

> INTERRUPT server-name [/qualifiers]

> Command Qualifier | Default
> --- | ---
> /[TASK=task-name] | None

## Parameter

> ### server-name

> The name of a server in the task group definition. This parameter is required.

## Qualifier

> ### /TASK

> A called task that participates in a distributed transaction started by a parent task might need to use the same server as the parent task. In a distributed transaction, different server processes are started and allocated to the parent and to the called tasks. The /TASK qualifier allows you to specify the server process that you want to interrupt.

> If you do not specify a task name, ACMS checks for an active task:

> - If there is an active task, and the task has context in an instance of the specified server, ACMS interrupts that instance of the server.
> - If no task is active, or if the active task does not have context in the specified server, ACMS interrupts the first free instance of the specified server. The first free server instance is the process that ACMS uses the next time a task calls a procedure in this server.

> If you specify a task name, then ACMS interrupts the server process currently owned by that task. If the named task is not currently retaining context in the named server, this command returns an error.

> If you debug a recursive task, supplying a task name does not have any effect; the /TASK qualifier is ignored and the rules for interrupting a server when no task name is supplied are followed.

## Notes

> The START server command must be completed before interrupting the server. If you use `[Ctrl/G]` to return to the ACMSDBG> prompt before the server is completely started, you will not be able to complete the server startup and will experience unpredictable results.

> When you finish with your debugging commands, type GO to resume the execution of the server. Then press `[Ctrl/G]` to end the INTERRUPT command and return to the Task Debugger ACMSDBG> prompt.

> When linking server images that you are going to debug, take the default of /TRACEBACK. If you link a server with /NOTRACEBACK, you cannot interrupt the server because the INTERRUPT command causes a fatal error in the server. Instead, use the STOP command to stop the server and return to the ACMSDBG> prompt. You can then relink and restart the server.

## Example

    ACMSDBG> INTERRUPT VR_SERVER
    Task is in server VR_SERVER
    DBG> SET BREAK UPDATE_RECORD
    DBG> GO
    [Ctrl/G]
    ACMSDBG>

> This example shows how to return to the OpenVMS Debugger prompt (DBG>) so that you can set breakpoints or use other OpenVMS Debugger commands in the server VR_SERVER. The example also shows how to return to the ACMSDBG> prompt in order to resume task execution.

Previous | Next | Contents | Index