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.

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

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.

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

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.

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

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.

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.

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

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.

ACMSDBG> CANCEL BREAK /ALL=VR_RESERVE_TASK
      

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

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.

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.

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.

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.

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.

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

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.

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.

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

ACMSDBG> HELP
      

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

ACMSDBG> HELP EXAMINE
      

This example shows how to display information about how to use the Task Debugger EXAMINE 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.