Most task groups and server procedures use OpenVMS logical names. If this is the case in your ACMS application, you must define these logical names before you start a debugging session. For example, the AVERTZ task group definition specifies that it uses the message file AVERTZ_DEFAULT:VRMSG.EXE. If the logical name AVERTZ_DEFAULT is not defined when you attempt to start the debugging session, the Task Debugger cannot find the message file, and therefore cannot start.

Some of the logical names used by your task group and server procedures might have already been defined. In the previous example, the AVERTZ application might be installed on your system in such a way that the necessary logical names are available to everyone on the system. In this case, you do not need to define any logical names in order to run the application. However, if the logical names are not defined, or if you want to test your own private copy of a file, you must define the logical names that point to that file. Also, be sure to define logical names in a way that does not affect other users on the system.

To define logical names, you need some information about the processes that are used in a debugging session. When you use the ACMS/DEBUG task-group command, you run the ACMS Task Debugger image in your process. For this reason, any logical names that are available to your process are also available to the Task Debugger.

However, when the Task Debugger starts a server, it creates the server as a subprocess of your process. When this server process is created, it has access to the same logical name tables as the Task Debugger process, with the exception of the Task Debugger's process logical name table. Instead of using the Task Debugger process logical name table, each server is created with its own process logical name table.

The logical names that must be available to the Task Debugger process include the logical names pointing to:

• Form files
• Message files
• Request library files

The logical names that the server process must have access to are:

• Logical names pointing to the procedure server image
• Logical names used in server procedures

With this information, you can decide which logical name tables to use in different situations. Generally, if you want the Task Debugger and the server process to use the same definition of a logical name, define the logical in a logical name table that is shared by the Task Debugger process and the server subprocess. You can do this in one of two ways:

• To do this in a way that does not affect anyone else on the system, define the logical as a job logical name. For example:

  $ DEFINE/JOB AVERTZ_DEFAULT DSK$:[AVERTZ.PUBLIC]

• Alternatively, define logical names in a user-defined logical name table. If the application uses a user-defined logical name table at run time, there is one less difference between the debugging environment and the run-time environment, which makes the transition between the two easier. Follow these steps:
  1. Create the logical name table.
     If a logical name table does not already exist, create it. To make the table shareable, specify the system directory as the parent table. For example:

     $ CREATE/NAME_TABLE - _$ /PARENT_TABLE=LNM$SYSTEM_DIRECTORY my_name_table

     
     This command requires the SYSPRV privilege. If you do not have this privilege, ask your system manager to create the table for you.

  2. Define the logical name in the logical name table.
     If the logical name is not defined in the table, define it:

     $ DEFINE/TABLE=my_name_table AVERTZ_DEFAULT DSK$:[AVERTZ.PUBLIC]

  3. Include the logical name table in the list that the system searches.
     If the logical name table is not included in the system default logical name table list, include it in the logical name table list for your process. For example:

     $ DEFINE/TABLE=LNM$PROCESS_DIRECTORY LNM$FILE_DEV - _$ LNM$PROCESS, LNM$JOB, my_name_table, LNM$GROUP, LNM$SYSTEM

     
     List the logical name tables in the same order as the name tables will be defined in the application definition.

See OpenVMS User's Manual for more information on logical names and logical name tables.

In some situations, you might not want to share logical names between the Task Debugger and the server:

• If you want the logical name to be used only by the Task Debugger process, define the logical name as a process logical name.
• If you want the logical name to be used only by the server process, define the logical name as a process logical name for the server subprocess. The only way to do this is to use the Task Debugger ASSIGN command. See Section 7.3.2 for details.

If exchange steps in your tasks call DECforms, and DECforms, in turn, calls procedural escapes, you need to debug escape routines. Because DECforms escape routines are written in a VAX programming language, you use the OpenVMS Debugger to debug escape routines. To have more information available to you while you are debugging, compile escape routines using the /DEBUG qualifier.

You must complete several preparatory steps before you debug DECforms escape routines. First, you must tell DECforms that you want to debug escape routines by defining the logical name FORMS$DEBUG_ESCAPE_ROUTINES to be true. This definition tells DECforms to activate the OpenVMS Debugger when it activates the escape routine image for the first time. Because DECforms invokes the OpenVMS Debugger only one time for each image, you must set breakpoints in your escape routines in order to debug them. See the DECforms documentation for more details on the FORMS$DEBUG_ESCAPE_ROUTINES logical name.

The next step depends on whether the escape routine you are debugging is linked into a separate image or linked into the forms image.

• For an escape routine linked into a separate image:
  Specify the location of the escape routine image. Do this by defining FORMS$IMAGE to point to the shared image that contains the escape routine. If you have more than one escape routine image, you can make FORMS$IMAGE a search list. Refer to the DECforms documentation for more information about defining this logical name.
  ACMS uses the ACMS$ESC_RTN_<node>_<application> logical name at run time to avoid naming conflicts that can occur with multiple applications. However, the ACMS Task Debugger does not recognize this logical name because the task group that the Task Debugger uses does not have an application name. Instead, use the FORMS$IMAGE logical name.
• For escape routines linked directly into the form image:
  You must modify your escape routine code to debug it. The escape routine must initiate the debugging process by invoking the OpenVMS Debugger. Do this by signaling SS$_DEBUG from the escape routine. For example:

  01 debug_symbol pic S9(9) COMP VALUE EXTERNAL SS$_DEBUG . . . CALL 'LIB$SIGNAL' USING BY VALUE debug_symbol.

  
  Remember to remove the signal of SS$_DEBUG when you finish debugging. If you do not define FORMS$DEBUG_ESCAPE_ROUTINES to be true, and you do not remove the code that signals SS$_DEBUG, your escape routine will hang.

When debugging ACMS tasks, you control two input/output (I/O) streams:

• Task I/O stream
  The task I/O stream handles the terminal I/O defined for the task. For example, in an inquiry task that reviews car rental reservations, the task I/O stream handles the form that displays information about the reservations.
• Debugger I/O stream
  The debugger I/O stream handles the debugger commands and the information the debugger displays in response to those commands. For example, the debugger I/O stream handles the Task Debugger prompt ACMSDBG>.

By default, both the task I/O stream and the debugger I/O are attached to the same terminal. This is necessary if you have only one terminal to use. However, if two terminals are available to you, you might want to use a separate terminal for each I/O stream. This is useful when you want to see the task output without having debugger prompts overwrite it.

The OpenVMS operating system supplies the following logical names that connect a terminal with the I/O streams:

• SYS$INPUT --- Where ACMS looks for task input
• SYS$OUTPUT --- Where ACMS sends task output
• DBG$INPUT --- Where the debugger looks for input
• DBG$OUTPUT --- Where the debugger sends output

OpenVMS defines the logical names SYS$INPUT and SYS$OUTPUT to be the name of your terminal when you log in (TTA1, for example). The logical names DBG$INPUT and DBG$OUTPUT default to SYS$INPUT and SYS$OUTPUT. If you do not reassign DBG$INPUT and DBG$OUTPUT, both I/O streams are attached to your terminal.

To use a second terminal for the debug stream, assign DBG$INPUT and DBG$OUTPUT to the second terminal. For example:

$ DEFINE DBG$INPUT TTA6: $ DEFINE DBG$OUTPUT TTA6:

In this example, the debug streams are assigned to terminal TTA6.

After setting up your I/O streams for two terminals, follow the instructions in the next section. The breakpoints you set, the commands you use, and the problems to look for are the same as when you debug from a single terminal. The only difference is that the terminal I/O and the debugger I/O display at different terminals. Before starting the debugger, make sure that no one is logged in at the other terminal. If anyone is logged in at the second terminal, the debugger cannot allocate and use that terminal.

7.2.6 Verifying that the ACMS Task Debugger Can Be Run

Before starting the ACMS Task Debugger, you need to check that quotas and system parameters are set correctly:

• Quotas
  For each of these, use the DCL command SHOW PROCESS/QUOTA. Make sure that:
  • The buffered I/O byte count quota (BYTLM) is at least 50,000.
  • The enqueue quota (ENQLM) is at least 2,000.
  • The open file quota (FILLM) is at least 96.
  • The subprocess quota (PRCLM) is adequate.
    The workspace looker process (that is, the process activated if you use the /WORKSPACE qualifier) and server processes are implemented as subprocesses. Make sure that your PRCLM is large enough to handle this.
  • The AST limit (ASTLM) is at least 24.
  • The timer queue entry limit (TQELM) is at least 10.
  
  See your system manager if you need higher quotas.
• System parameters
  Check with your system manager to make sure that the following system parameters have values equal to or greater than the ones indicated here:

  PQL_DASTLM = 24
  PQL_DDIOLM = 20
  PQL_DBIOLM = 18
  PQL_MDIOLM = 20

When you have completed all of the preparations for debugging ACMS tasks and procedures, you are ready to debug a task. After you start the ACMS Task Debugger, assign any additional logical names that you need. Then you can start the servers needed by a task.

Before running a task in the Task Debugger, however, you usually set breakpoints so that you can check that information that should be in a workspace is actually there. You might also want to set breakpoints in procedures to debug them using the OpenVMS Debugger.

The following sections explain how to start the ACMS Task Debugger; use the Task Debugger ASSIGN command; start, stop, and interrupt servers; set and remove breakpoints in tasks; check values in workspaces; and debug transaction timeout codes. Debugging procedures with the OpenVMS Debugger is described in Section 7.4.

You can use two control characters when running the Task Debugger. Table 7-2 lists these control characters and explains how to use them.

Table 7-2 Control Characters for the ACMS Task Debugger

Control Character	Function
[Ctrl/G]	Interrupts the current task (if any) and the current Task Debugger or OpenVMS Debugger command, and returns to the Task Debugger prompt (ACMSDBG>). Typing GO continues a task interrupted with [Ctrl/G].
[Ctrl/Z]	Equivalent to the EXIT command. If you press [Ctrl/Z] when you are at the Task Debugger prompt, the Task Debugger stops all servers, cleans up all the subprocesses it has allocated, and returns to the DCL command-level prompt ($). If you press [Ctrl/Z] at an OpenVMS Debugger prompt, the debugger stops the server process you are running in and returns to the Task Debugger prompt. Any active tasks using that server are canceled.

7.3.1 Starting the Task Debugger

To start the ACMS Task Debugger, you use the ACMS/DEBUG command. For example:

$ ACMS/DEBUG VR_TASK_GROUP/WORKSPACE

In the command, include the name of the task group database file (.TDB) containing the task or tasks you want to debug; in the example, the task group is VR_TASK_GROUP. You cannot debug more than one task group at a time. If the file is not in your default device and directory, include the device and directory specifications. The default file type is .TDB.

Use the /WORKSPACE qualifier with the ACMS/DEBUG command to examine and deposit data in workspaces using the Task Debugger. If you do not include the /WORKSPACE qualifier, you can still look at workspaces when a task is running in a server. However, you must use /WORKSPACE if you want to look at workspaces during exchange steps, during the action part of processing steps, or at the beginning or end of the task.

Once the Task Debugger starts, it displays the ACMSDBG> prompt. You can then enter any of the Task Debugger commands. Reference information on all the ACMS Task Debugger commands is in Chapter 10.

7.3.2 Using the Task Debugger ASSIGN Command

ACMS defines process logical names for a server based on logical names that you define using the Task Debugger ASSIGN command. A logical name that you assign in the Task Debugger takes effect only when the server starts. Therefore, if you assign a logical name after a server starts, that name does not take effect.

The following example assigns a logical name for the VR_UPDATE_SERVER to point to a different directory from the one defined with the DCL DEFINE command:

ACMSDBG> ASSIGN /SERVER=VR_UPDATE_SERVER [AVERTZ.UNAME] AVERTZ_DEFAULT ACMSDBG> START VR_UPDATE_SERVER

Note that, unlike the DCL DEFINE command, the directory name precedes the logical name in the Task Debugger ASSIGN command. (The ACMS Task Debugger ASSIGN command is patterned after the DCL ASSIGN command.)

The ASSIGN command defines the logical name AVERTZ_DEFAULT to point to the [AVERTZ.UNAME] directory rather than to the [AVERTZ.PUBLIC] directory. The /SERVER qualifier names the server that can use this logical name: the VR_UPDATE_SERVER.

If you are assigning many logical names for a server, use the SET SERVER command to indicate the server to which the ASSIGN commands apply. If you use SET SERVER before the ASSIGN command, you do not need the /SERVER qualifier. For example:

ACMSDBG> SET SERVER VR_UPDATE_SERVER ACMSDBG> ASSIGN [AVERTZ.UNAME] AVERTZ_DEFAULT

The name included in the SET SERVER command or the /SERVER qualifier must be the same name used for the server in the task group definition.

7.3.3 Starting, Stopping, and Interrupting Servers

After starting the ACMS Task Debugger, the next step is to start the servers that handle the tasks you want to debug. The following sections explain how to start, stop, and interrupt servers.

7.3.3.1 Starting Servers

You can start servers in two ways from the Task Debugger:

• The ACMS Task Debugger automatically starts a server if it is needed to run a procedure called by the task.
• Alternatively, you can start servers for tasks yourself. You might, for example, want to debug an initialization procedure without starting a task.

You might need multiple instances of a server when you use distributed transactions and the task-call-task feature. When you use distributed transactions, 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. Different server processes are started and allocated to the parent and to the called tasks.

The number of active servers allowed for a debugging session is limited. A user is allowed up to four times the number of servers defined in the task group that is being debugged. You can, however, allocate the total number of servers allowed to server instances in any manner you like. For example, if a task group has two servers, you can start eight server instances. You can, if you like, have eight instances of one server and none of the other.

Use the START server-name command to start one or more instances of one or more servers. The following examples show three alternative ways to use the START command:

• If both a parent and a called task use the same server (in this case, VR_SERVER), issue a command like the following one to start two instances of that server:

  ACMSDBG> START VR_SERVER, VR_SERVER

• If you will use only one of the servers defined for the task group, include that server name in the START command:

  ACMSDBG> START VR_SERVER

• If the tasks you are debugging use all the servers in a task group or if only one server is defined for a group, use the /ALL qualifier in the START command to start any servers that have not been started:

  ACMSDBG> START /ALL

  
  You cannot use both the /ALL qualifier and a server name in the same START command.

When you start a server with the ACMS Task Debugger, ACMS creates the server process. If the server is a procedure server, the OpenVMS Debugger prompt is displayed. For example:

ACMSDBG> START VR_SERVER Terminal is in SERVER VR_SERVER VAX DEBUG Version V5.4-019 %DEBUG-I-INITIAL - language is COBOL, module set to 'VR_SERVER' DBG>

The first line after the START server command indicates that the ACMS Task Debugger has transferred control of the debugging session to the server process. The OpenVMS Debugger software displays an identifying line showing the version number. On a separate line, the OpenVMS Debugger names the language it is using and the module where the program is beginning. The program begins in the server transfer module, which is produced by building the task group. Therefore, the language displayed comes from the server transfer module rather than from your server procedure. The default language for the server transfer module is COBOL. Following these messages, the OpenVMS Debugger displays the DBG> prompt.

At this point, you can set breakpoints in the server using the OpenVMS Debugger. You might, for example, want to set a break at the server's initialization procedure. Instructions for using the OpenVMS Debugger are in Section 7.4.

To complete the operation of starting the server and return to the ACMS Task Debugger, enter the GO command:

DBG> GO Server VR_SERVER has been started ACMSDBG>

7.3.3.2 Stopping Servers

Once a server starts, it remains available for other tasks until one of the following occurs:

• You use the Task Debugger STOP command.
• You use the OpenVMS Debugger EXIT command.
• ACMS runs down a server due to a task cancellation.

One way to stop a server is to use the STOP command. For example:

ACMSDBG> STOP VR_SERVER Terminal is in SERVER VR_SERVER Server VR_SERVER stopped ACMSDBG>

If there are multiple instances of a server started when you use the STOP command, only one instance is stopped. For example:

ACMSDBG> STOP VR_SERVER Stopping only one instance of server VR_SERVER Terminal is in SERVER VR_SERVER Server VR_SERVER stopped ACMSDBG>

You can stop all instances of all servers with the STOP/ALL command. For example:

ACMSDBG> STOP/ALL Terminal is in SERVER VR_SERVER Server VR_SERVER stopped Terminal is in SERVER VR_SERVER Server VR_SERVER stopped Terminal is in SERVER DCL_SERVER Server DCL_SERVER stopped ACMSDBG>

If you use the STOP command, the termination procedure is run for the server. If you want to debug the termination procedure, you must set a breakpoint at the termination procedure. If you forget to do this when the server is first started or while you are debugging step procedures, you can use the INTERRUPT command to bring the OpenVMS Debugger up in the server.

You cannot issue a STOP command while a task is active. If you want to stop the server while a task is active, you can interrupt the server and use the EXIT command at the OpenVMS Debugger prompt. Exiting the server while an active task has context in the server causes the task to be canceled. For example:

ACMSDBG> INTERRUPT VR_SERVER Task is in SERVER VR_SERVER DBG> EXIT Task is in the task debugger %ACMSDBG-I-SPDIED, Server VR_SERVER stopped unexpectedly Processing non-recoverable exception from step $STEP_1 in task VR_RESERVE_TASK Exception code text: %ACMS-E-TASK_SP_DIED, Cancel results from the server process dying Exception code value: 16632498 (decimal), %X00FDCAB2 (hex) Task was canceled. ACMSDBG>

The previous example shows that the task is canceled due to a nonrecoverable error. The nonrecoverable error is that a server that the task was using stopped unexpectedly. The message also gives the decimal and hexadecimal values of the exception code.

Another reason a server stops is that a task is canceled while the task has context in the server, and the server is to run down as a result of a cancel. In this situation, the termination procedure is called only if you use the ALWAYS EXECUTE TERMINATION PROCEDURE clause in your server definition. See Chapter 2 for details on how to determine if a server is run down on a cancel.