Selects and starts a task.

Format

SELECT task-name [selection-string]

Parameters

task-name

The name of the task selected, which is assigned in the task group definition. This parameter is required.

selection-string

Additional information the Task Debugger passes to the task in the ACMS$SELECTION_STRING workspace. Enclose the selection string in quotation marks if the data has embedded spaces.

Note

Select only one task at a time. If a selected task has not completed yet, use CANCEL TASK to end that task before selecting another.

Examples

ACMSDBG> SELECT VR_RESERVE_TASK
      

This example shows how to select and start the VR_RESERVE_TASK.

ACMSDBG> SELECT VR_RESERVE_TASK 000121
      

This example shows how to start the VR_RESERVE_TASK. It also shows how to pass the decimal number 000121 to the ACMS$SELECTION_STRING workspace.

Sets a breakpoint in a task. Breakpoints can be set at specific locations or at specific events.

Table 7_3 contains location breakpoint symbols. Table 7-4 contains event breakpoint symbols.

Format

SET BREAK task-name\step-name\location

SET BREAK task-name\event

Parameters

task-name

Always include a task name in the SET BREAK command.

step-name

The step in the task at which a breakpoint is set.

If you omit the step-name in a location breakpoint, the break is set at the root step.

location

Location breakpoint symbols are $BEGIN, $ACTION, $HANDLER, and $END.

If you omit the location, the breakpoint is set at the beginning of the step.

event

Event breakpoint symbols are $EXCEPTION and $CANCEL.

Notes

You can use the SET BREAK command from the ACMSDBG> prompt only to set breakpoints in the task definition. Use the SET BREAK command from the DBG> prompt to set breakpoints in user procedure code.

You can set breakpoints for tasks that are not active.

Examples

ACMSDBG> SET BREAK VR_RESERVE_TASK
      

In this example, a breakpoint is set at the beginning of the VR_RESERVE_TASK.

ACMSDBG> SET BREAK VR_RESERVE_TASK\$STEP_1\$BEGIN
      

In this example, a location breakpoint is set at the beginning of the first step in VR_RESERVE_TASK.

ACMSDBG> SET BREAK VR_RESERVE_TASK\$CANCEL
      

In this example, a CANCEL event breakpoint is set. This breakpoint is reached when any event that causes a task cancellation occurs.

Names the server used as the default for the ASSIGN command.

Format

SET SERVER server-name

Parameter

server-name

The name of the server, taken from the task group definition, to set as the current server for ASSIGN commands. This parameter is required.

Notes

The SET SERVER command does not affect which servers the START and STOP commands handle.

The SET SERVER command has no default.

If you do not use the SET SERVER command, you must use the /SERVER qualifier on the ASSIGN command.

Example

ACMSDBG> SET SERVER VR_SERVER
      

This example shows how to establish VR_SERVER as the current server for ASSIGN commands.

Sets the current transaction timeout period. This allows you to verify that your task correctly handles a transaction timeout.

Format

SET TRANSACTION_TIMEOUT seconds

Parameter

seconds

The number of seconds to set as the current transaction timeout limit. This parameter is required.

Notes

If you do not set a transaction timeout, your transactions will never time out.

Once a transaction timeout limit is set using this command, if a transaction does not complete in the specified amount of time, the Task Debugger raises a transaction exception.

Example

ACMSDBG> SET TRANSACTION_TIMEOUT 60
      

This example shows how to establish 60 seconds as the transaction timeout limit.

Displays breakpoints that have been set in the task.

Format

SHOW BREAK

Example

ACMSDBG> SHOW BREAK
      

This example shows how to display all breakpoints that you have set (and not yet canceled) in the task during the current Task Debugger session.

Displays all servers that have started (and not stopped) in the current Task Debugger session.

Format

SHOW SERVERS

Example

ACMSDBG> SHOW SERVERS
VR_SERVER
      

This example shows that VR_SERVER is the only server currently running in this Task Debugger session.

Displays the value of the current transaction timeout.

Format

SHOW TRANSACTION_TIMEOUT

Example

ACMSDBG> SHOW TRANSACTION_TIMEOUT
Transaction timeout value is 60 seconds
      

This example shows how to display the transaction timeout currently set.

Displays the version number of the Task Debugger.

Format

SHOW VERSION

Example

ACMSDBG> SHOW VERSION
VAX ACMSDBG V4.2
      

This example shows how to display the version number of the Task Debugger image that the user is running.

Starts one or more instances of one or more servers.

Format

START [/qualifier] [server-name] [,...]

Command Qualifier	Default
/ALL	None

Parameter

server-name

The name of one or more servers, from the task group definition. Separate multiple server names with commas.

In most cases, you need only one instance of a server to be active. The instance that is started is used by each task that uses that server.

In a distributed transaction, however, 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 the called task. You can use the START command to start multiple instances of the same server.

Qualifier

/ALL

Starts all reusable servers defined in the task group database (.TDB) being used for the current debugger session.

Notes

Always include either a server name or /ALL in the START command.

The servers named in the START command go through startup as if you were starting them with the ACMS/START APPLICATION command. The Task Debugger runs all initialization procedures and allocates group workspaces. If the server image was linked with /DEBUG, the START server command gives control to the OpenVMS Debugger in the server process.

The number of active server processes allowed for the 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. The number of server instances allowed per server, however, is unlimited. If a task group has two servers, for example, you have can eight server instances started. If need be, you can have eight instances of one server and none of the other.

Examples

ACMSDBG> START VR_SERVER,VR_SERVER
      

This example shows how to start two processes for the server VR_SERVER.

ACMSDBG> START/ALL
      

This example shows how to start one instance of all servers defined in the task group database file (.TDB) used in the current debugger session.

Runs the task from the current breakpoint to the next task-level breakpoint. When stepping through a task that was called by another task, the Task Debugger proceeds through all the steps in the called task until the task completes. Control then returns to the parent task; continue to enter the STEP command for the Task Debugger to step through the parent task.

Format

STEP

Note

This command is valid only when you select a task using the SELECT or ACCEPT commands.

Example

ACMSDBG> STEP
      

This example shows how to move the current task to the next task-level breakpoint.

Stops one or more servers.

Format

STOP [/qualifier] [server-name][,...]

Command Qualifier	Default
/ALL	None

Parameter

server-name

The name of the server to stop. The name of the server comes from the task group definition. Separate multiple server names with commas.

Qualifier

/ALL

Stops all instances of all servers included in the task group database file (.TDB) used in the current debugger session.

Notes

Use either the server-name parameter or the /ALL qualifier. If you use the server-name parameter, ACMS stops a single server process and displays a message if other server processes remain active for the same server.

The servers named in the STOP command go through shutdown as if you were stopping them with the ACMS/STOP APPLICATION command. All termination procedures are run.

Examples

ACMSDBG> STOP VR_SERVER,VR_UPDATE_SERVER
      

This example shows how to stop the servers VR_SERVER and VR_UPDATE_SERVER.

ACMSDBG> STOP /ALL
      

This example shows how to stop all servers defined in the task group database file (.TDB) used in the current debugger session.

This chapter provides background on ACMS and discusses how ACMS and third-party database managers (such as Oracle) can be integrated. It also specifically answers the following questions:

• Why would you want to use Compaq and ACMS?
• What are the basic concepts for ACMS?
• How do you use ACMS with third-party databases?
• How do you integrate ACMS with Oracle databases?

When you read articles and business school case studies on companies that remain competitive year after year, decade after decade, you typically find a common denominator for those companies: they remained flexible enough to change the way they did business to suit the current business environment. If information is critical to the operation of your business, don't you need that same advantage of flexibility?

Compaq offers you computing solutions that fit for today and for the future as well. Because Compaq is the premier vendor in interoperability and networking, flexibility means the ability to:

• Use the appropriately sized (and therefore appropriately priced) computer system for different business needs. Compaq's ACMS system runs on all OpenVMS machines, from the smallest desktop to the largest mainframe. Every one of these machines can interoperate with Oracle databases.
• Define the level of availability that your business needs. You can create clustered and fault-tolerant hardware configurations to ensure continuous hardware operations. ACMS provides for application failover to ensure continuous software operations.
• Integrate your existing systems into the ACMS environment to protect your current investment. The Compaq TP Desktop Connector (foermerly ACMS Desktop) product allows additional clients (using a client/server approach with systems such as DOS, Macintosh®, SCO^tm UNIX®, and ULTRIX systems) and additional presentation managers (such as Microsoft® Windows, HyperCard®, and Motif®) to be connected to ACMS. These connections can be made over existing networks such as Compaq's PATHWORKS and Novell® NetWare®.
• Move computing to the right location. With ACMS, you can either keep your business data and processing in a central location or distribute it throughout your corporation.
• Interoperate with Compaq and third-party databases. ACMS coordinates the activities of end users against the database, helping to reduce database and lock contention. For environments that have a large number of users, ACMS is crucial for high performance and security.

With Compaq, flexibility means the choice is yours!

11.2 Introduction to Developing ACMS Applications

An ACMS application consists of a set of tasks that relate to the functions of a business. A task is the unit of work that a user selects from an ACMS menu. Each task usually comprises a sequence of steps that perform this unit of work. You use the ACMS task definition language (TDL) to define tasks.

Figure 11-1 illustrates the basic principles of the ACMS TDL used to write a task definition.

The task definition specifies an interface to the presentation service (forms management system) for communication with a terminal or other device. The task definition also specifies an interface to a procedure server for executing procedures (user-written subroutines) that handle database I/O and computational work.

Figure 11-1 Execution Flow of an ACMS Task Definition

The semantics of the ACMS task definition language are based on a call and return model. The task definition performs calls to the presentation service in exchange steps, and to the procedure server in processing steps. The presentation service and procedure server perform a function and return control to the task definition. Upon return of control to the task definition, subsequent parts of a step can evaluate the results of the call and, if necessary, handle any error conditions.

In Figure 11-1, for example:

1. In the first exchange step, the task definition calls the presentation service to display a form on the terminal screen (for example, a form to add a new employee record to a database). When the terminal user finishes filling in the form, the user presses a specified key (or keys) that returns the input data to the task definition.
2. In the processing step, the task definition then calls Procedure 1 in the procedure server to write that input data to the database. Procedure 1 then returns its results (either success or failure). If Procedure 1 succeeds, the task ends with a success status. If Procedure 1 fails to write to the database, the task continues executing at step 3.
3. In the second exchange step, the task definition calls the presentation service to send an error message to the terminal screen (for example, that the employee number of the new record duplicates an existing employee number). The presentation service then returns control to step 3, which ends the task.

By keeping exchange and processing steps as distinct steps within an ACMS task, ACMS allows for the separation of forms (end-user interaction) from function (database access, computation, and execution control). This means that you can easily distribute end-user processing while maintaining centralized data control.

11.2.1 Writing ACMS Definitions

The ACMS task definition language allows you to write an ACMS definition as a series of simple, English-like statements. The four types of ACMS definitions are:

• A task definition describes, in steps, the work to be accomplished in the task. For example, a task can collect information from a user and call a procedure to store the information in a file or database.
• A task group definition specifies similar tasks for control purposes and defines resources common to all tasks in the group.
• An application definition describes the environment and control characteristics of tasks and task groups.
• A menu definition describes how users access tasks in one or more applications.

You build the task, task group, and application definitions into binary files that run as an application under the control of the ACMS run-time environment. You build a menu definition into a binary file that is not necessarily tied to a single application.

Figure 11-2 illustrates the ACMS development components for a simple ACMS application with two tasks (for example, one to add a new employee record to a database, and one to update an existing employee record).

Figure 11-2 ACMS Application Components

Figure 11-2 does not show that there can be more than one task group definition specified for a single application. Also, more than one menu definition can specify tasks that point to the same application. Conversely, a single menu definition can specify tasks in different applications.

Because ACMS applications are modular, you develop each part of an application independently. Built-in modular design based on English-like syntax statements means that ACMS applications are easy to structure and easy to maintain. Furthermore, modularity means that you can easily update an application module without affecting the entire application.