Compaq ACMS for OpenVMS
Writing Server Procedures


Previous Contents Index


SELECT Command

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

#1

ACMSDBG> SELECT VR_RESERVE_TASK
      

This example shows how to select and start the VR_RESERVE_TASK.

#2

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.


SET BREAK Command

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

#1

ACMSDBG> SET BREAK VR_RESERVE_TASK
      

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

#2

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.

#3

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.


SET SERVER Command

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.


SET TRANSACTION_TIMEOUT Command

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.


SHOW BREAK Command

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.


SHOW SERVERS Command

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.


SHOW TRANSACTION_TIMEOUT Command

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.


SHOW VERSION Command

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.


START Command

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

#1

ACMSDBG> START VR_SERVER,VR_SERVER
      

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

#2

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.


STEP Command

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.


STOP Command

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

#1

ACMSDBG> STOP VR_SERVER,VR_UPDATE_SERVER
      

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

#2

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.


Part 3
Interoperability with Third-Party Databases: Oracle Case Study

This part of the manual describes how Compaq ACMS for OpenVMS transaction processing (TP) software works with third-party database managers, with code examples given for the Oracle database manager.


Chapter 11
Overview of ACMS and Oracle

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:

11.1 Why Use Compaq and ACMS?

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:

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:

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.


Previous Next Contents Index