Compaq ACMS for OpenVMS
ADU Reference Manual


Previous Contents Index


TRANSACTION TIMEOUT Subclause (Task)

Places a limit on how long a distributed transaction can remain active.

Format

[ NO ] TRANSACTION TIMEOUT IS seconds;


Clause Default

The TRANSACTION TIMEOUT subclause is optional. If you do not specify TRANSACTION TIMEOUT, ACMS does not abort a distributed transaction because of a timeout error.

Parameter

seconds

The number of seconds a distributed transaction can remain active before ACMS aborts it.

Notes

Use the TRANSACTION TIMEOUT subclause to place a limit on how long a distributed transaction can remain active. It is possible that a distributed transaction cannot complete because a server deadlock or database deadlock problem has occurred. You can use the TRANSACTION TIMEOUT subclause to resolve the deadlock.

When a distributed transaction exceeds the specified timeout limit, ACMS aborts the distributed transaction, raises a transaction exception, searches for an exception handler, and stores the ACMS$_TRANSTIMEDOUT exception code in the ACMS$L_STATUS field of the ACMS$PROCESSING_STATUS system workspace. If the task does not handle the timeout exception in an exception handler, ACMS cancels the task.

The maximum timeout value you can specify is 65535 seconds.


Example


TASK DEFAULT IS 
     TRANSACTION TIMEOUT IS 60 
END DEFAULT; 
      

This example places a 1-minute limit on the length of a distributed transaction.


USERNAME Subclause (Server)

Defines the user name under which the server process runs.

Format



Keywords

TERMINAL USER

Assigns to a server process the user name of the terminal user.

APPLICATION

Assigns to the server processes the OpenVMS user name under which the application runs. Assign an OpenVMS user name to the application with the APPLICATION USERNAME clause.

Parameter

username

A valid OpenVMS user name consisting of 1 to 12 alphanumeric characters and underscores (_). This parameter identifies the user name under which a server process runs.

Clause Default

The ACMS-supplied default is USERNAME OF APPLICATION. If you do not assign a user name in the task group definition, USERNAME OF APPLICATION is the default. However, if you assign a user name in the task group definition, ACMS uses that assignment. This subclause is optional.

Notes

If you use the USERNAME subclause with the SERVER ATTRIBUTES clause, you override any user name defined with the SERVERS clause of the task group definition.

If you define a server to have the user name of the terminal user, that server cannot have a dynamic user name. Also, the user must be an authorized OpenVMS user.

A system manager can set up a special account with special quotas and privileges required for a task. The system manager can assign the server handling the processing for that task to the user name of that account using the USERNAME server subclause.

If you use the ACMS/INSTALL command to move an application database file to ACMS$DIRECTORY, the server user names in that application database must match the ones authorized for the application in the application authorization file ACMSAAF.DAT. Using the /DYNAMIC_USERNAME qualifier in the Application Authorization Utility (AAU) authorizes both the user names of terminal users and dynamic user names. For more information on AAU, see the Compaq ACMS for OpenVMS Managing Applications.

The REUSABLE server subclause in the task group definition is the default for both DCL and procedure servers. However, using the clause USERNAME OF TERMINAL USER in application or task group definitions overrides this default and creates servers that are not reusable. Every time a new terminal user logs in, a separate server process is created for that user. For best performance, your application should run as few servers as needed to do the work of the application.


Example


SERVER ATTRIBUTE IS 
   PRIVATE_SERVER: USERNAME OF USER; 
END SERVER ATTRIBUTE; 
      

The user name of PRIVATE_SERVER is the same as the user name of the terminal user.


WAIT Subclause (Task)

Controls whether or not ACMS displays a message prompting users to press [Return]. Pressing [Return] clears the terminal screen and displays the previously displayed ACMS menu.

Format

[ NO ] WAIT ;


Clause Default

The ACMS-supplied default is NO WAIT. This subclause is optional.

Notes

If you do not set the wait attribute in the TASK ATTRIBUTES clause, ACMS uses the setting you assign in the task group definition. If you do not make an assignment there, ACMS uses the NO WAIT default.

You cannot use the WAIT subclause and the DELAY subclause in the same definition.

You can define WAIT and DELAY in the application definition and in the TASKS clause of the task group definition. WAIT and DELAY are the only task control attributes that you can define in task group definitions as well as application definitions.

The WAIT and DELAY subclauses determine how quickly ACMS returns user control to a menu when a task ends. For example, if a user runs a task that displays the time of day with the SHOW TIME command, ACMS displays the time but immediately clears the screen and returns the user to the menu. Both subclauses let you delay the time interval between the task ending and the selection menu redisplay.

WAIT and DELAY subclauses specified for a task in a task, task group, or application definition are overridden by menu definition WAIT and DELAY clauses.


Examples

#1

USERNAME IS FRIDAY; 
TASK DEFAULT IS 
  WAIT; 
END TASK DEFAULT; 
TASK GROUP IS 
  PERSONNEL_GROUP : TASK GROUP IS "SYS$SAMPLE:PERSONNEL.TDB"; 
END TASK GROUP; 
END DEFINITION; 
      

The WAIT subclause in this TASK DEFAULTS clause changes the ACMS default from NO WAIT to WAIT. This example changes the default for the tasks defined in the PERSONNEL_GROUP task group. After processing for each of these tasks stops, ACMS prints a message telling the user to press [Return] to have ACMS return control to the menu.

#2

USERNAME IS FRIDAY; 
TASK DEFAULT IS 
  WAIT; 
END TASK DEFAULT; 
TASK GROUP IS 
  PERSONNEL_GROUP : TASK GROUP IS "SYS$SAMPLE:PERSONNEL.TDB"; 
END TASK GROUP; 
TASK ATTRIBUTE IS 
  ADD_EMPLOYEE : TASK ADD_EMPLOYEE IN PERSONNEL_GROUP; 
                 NO WAIT; 
END TASK ATTRIBUTE; 
END DEFINITION; 
      

In this example the default changes from NO WAIT to WAIT. The default also changes for the ADD_EMPLOYEE task back to NO WAIT. For all tasks in the PERSONNEL_GROUP task group except the ADD_EMPLOYEE task, the default is WAIT. Any default you set with the TASK ATTRIBUTES clause overrides any you set either in the task group definition or in the application definition with the TASK DEFAULTS clause.


Chapter 6
Menu Definition Clauses

Menu definitions describe the contents of ACMS menus, which are screen displays of entries that users can select. Users can select task entries that do the work of an application, or menu entries that display other menus with their own entries. You can create a menu hierarchy similar to the directory structure on your OpenVMS system.

This chapter explains the clauses you use to write menu definitions. A menu definition describes the menu title and the names and descriptions of menu entries. Table 6-1 names and briefly describes each of these clauses.

Table 6-1 Menu Definition Clauses
Clause Meaning
CONTROL TEXT Names up to five control text items that instruct DECforms how to modify the DECforms menu.
DEFAULT APPLICATION Names the application ADU uses if you do not include one with each task entry you define.
DEFAULT MENU FILE Names the default menu database file ACMS builds if the menu is used as the top menu in a BUILD MENU file. You can override the file specification when you use the BUILD command.
HEADER Defines the title for a menu.
REQUEST Names a TDMS request that ACMS uses to display a menu.
ENTRIES Defines task and menu entries.

The ENTRIES clause is the only required menu clause. It includes a required subclause specifying whether an entry is a task or menu entry. It can also include optional subclauses for displaying descriptive text and controlling screen display characteristics. Figure 6-1 shows the menu definition syntax.

Figure 6-1 Menu Definition Syntax


Example 6-1 shows a sample menu definition.

Example 6-1 Sample Menu Definition

HEADER IS "               EXAMPLE OF", 
          "             ACMS MENU DEFINITION"; 
DEFAULT APPLICATION IS PERSONNEL; 
ENTRIES ARE 
  ADD     :  TASK IS ADD_EMPLOYEE; 
             TEXT IS "Add New Employee Record"; 
  CHANGE  :  TASK IS CHANGE_EMPLOYEE; 
             TEXT IS "Change Employee Record"; 
  DISPLAY :  MENU IS DISPLAY_MENU; 
             TEXT IS "Menu of Tasks to Display Information"; 
END ENTRIES; 
END DEFINITION; 

This menu defines three entries. ADD and CHANGE are task entries. When selected, they run the tasks identified by the task names ADD_EMPLOYEE and CHANGE_EMPLOYEE. You must define these names in a task group definition. DISPLAY is a menu entry that displays another menu selected by a user. DISPLAY_MENU is the CDD path name of the menu definition that describes the menu you want to display. Each entry includes descriptive text.

ENTRIES clauses define each entry in a menu definition. You begin a set of ENTRIES clauses with the keywords ENTRIES ARE and end it with the keywords END ENTRIES. ENTRIES subclauses define the characteristics of each entry.

To define the characteristics of a set of entries, specify each entry name, a colon (:), and the entry's subclauses. The ENTRIES clause includes the following types of subclauses:

6.1 Application Specifications

Several ADU clauses include an application specification parameter. For example, in the DEFAULT APPLICATION clause, you must specify the name of the application to be the default when the terminal user logs on to ACMS.

The syntax for the application specification parameter is:


The elements of the application specification parameter are:

Logical names must be accessible to the ACMS command process (CP), so define them as system logical names. See OpenVMS DCL Dictionary for information on logical names and file names.

The application you specify can be located on the same node as the terminal user, or on a remote node with the terminal user located on a separate front-end processor. When the application exists on the same node as the user, the application specification consists of the name of the application database file. That file must be located in the directory pointed to by the logical ACMS$DIRECTORY. The logical definition for ACMS$DIRECTORY includes both a device name and a directory name.

For a distributed application, where the application is located on a remote node, specify both the application database file name and the name of the remote node. The device and directory names are taken from the ACMS$DIRECTORY logical on the remote node.

Use logical application names whenever possible to specify the application database file. If the application is moved to another node, you only need to change the logical name definition to reflect the new configuration. For example, if the file name is hardcoded in the menu definition, the menu database must be rebuilt whenever the node changes.

Frequently, sites develop and test applications on a single node system. Then, when they put the application into production, they distribute the front-end processing to one node and place the application on a more powerful system. Using a logical application specification means only one change to the code is required when a new configuration is set up.

The following are examples of application specifications:

6.2 Writing Menu Definitions for Distributed Applications

ACMS supports applications distributed across a network. A menu can include a task running in an application on another node in a distributed environment, whether that environment is a local area network, wide area network, or OpenVMS Cluster.

For example, suppose the ACMS Sample Applications Personnel and Employee run on an OpenVMS Cluster with two nodes, RAVEN and MAGPIE. The Personnel application runs on the node RAVEN; Employee runs on MAGPIE. Some tasks from the Employee application on MAGPIE are needed by users on RAVEN. Rather than duplicate tasks from the Employee application for users on RAVEN, you can provide remote access to Personnel tasks on RAVEN for users on MAGPIE.

One way to distribute a task remotely is to include the name of the remote node in the application specification in the menu definition. Example 6-2 provides an example of a menu entry for a task of a remote node.

Example 6-2 Example of a Menu with a Remote Task

HEADER IS   "                    EMPLOYEE MENU"; 
ENTRIES ARE 
  SCHEDULE : TASK IS REVIEW_SCHEDULE IN RAVEN::PERSONNEL; 
  EMPLOYEE : TASK IS EMPLOYEE IN EMPLOYEE; 
END ENTRIES; 
END DEFINITION; 
 

The EMPLOYEE menu definition is on node MAGPIE. The HEADER clause lists the descriptive text at the top of the menu. The ENTRIES clause lists the choices displayed on the menu. The first entry, SCHEDULE, is a task named REVIEW_SCHEDULE in the Personnel application running on node RAVEN. The EMPLOYEE entry is the task named EMPLOYEE in the Employee application on node MAGPIE. The SCHEDULE entry provides remote access to the task named REVIEW_SCHEDULE in the Personnel application on RAVEN.

Example 6-2 hardcoded a node name in a menu definition. See Section 6.1 for information about other methods of accessing remote applications that are more flexible than hardcoding.


CONTROL TEXT Clause (Menu)

Lets you customize your DECforms menu by sending up to five control text items to the form.

Format



Parameters

string

A 5- to 25-character identifier that the ACMS command process passes to DECforms, instructing DECforms to execute corresponding control text responses. You can specify up to five control text items; each item must be five characters long. If you send multiple control text items, do not separate them with spaces or commas.

quoted-string

A 5- to 25-character identifier, within quotation marks, that instructs the DECforms to execute corresponding control text responses. Use a quoted string if your string contains any nonalphanumeric characters.

number

Identifies the number of entries that appear on the terminal screen.

Clause Default

The CONTROL TEXT clause is optional. If you do not use it in your menu definition, and your application uses DECforms, your menu appears in the standard DECforms format with 16 entries for each screen.

Notes

You can use the CONTROL TEXT clause to change menu attributes such as background color, highlighted fields, and blinking fields. For each control text item that you name, define a corresponding control text response in your IFDL (Independent Form Description Language) source file in the form.

You cannot specify both CONTROL TEXT and REQUEST clauses in the same menu definition.


Example


SEND CONTROL TEXT IS COLORLIGHT 
       WITH 10 ENTRIES PER SCREEN; 
      

This example passes two control text items, COLOR and LIGHT, to DECforms where two corresponding control text responses define the menu's background color and highlighted fields. This example also changes the number of entries for each screen from the default of 16 to 10.


DEFAULT APPLICATION Clause (Menu)

Defines the application specification that ACMS uses as the default for TASK entries, unless you name a different application database file with the TASK subclause.

Format

DEFAULT APPLICATION IS application-spec ;


Parameter

application-spec

See Section 6.1 for information about application specifications.

Clause Default

If you omit the DEFAULT APPLICATION clause, you must specify the application in each TASK subclause in the menu definition. This clause is optional.

Notes

Include the application specification in the DEFAULT APPLICATION clause rather than in TASK subclauses. Changing the application specification in the DEFAULT APPLICATION clause is easier than changing each entry that uses that application specification.

The application specification that you assign in a TASK subclause overrides the one you assign with the DEFAULT APPLICATION clause.


Examples

#1

DEFAULT APPLICATION IS EMPLOYEE; 
ENTRIES ARE 
  ADD    :  TASK IS ADD_EMPLOYEE; 
            TEXT IS "Add Employee Information"; 
  CHANGE :  TASK IS CHANGE_EMPLOYEE; 
            TEXT IS "Change Employee Information"; 
END ENTRIES; 
END DEFINITION; 
      

In this example, the default application is EMPLOYEE. You do not need to include the application for each entry in the ENTRIES clause. Only if a task entry belongs to another application do you need to name another application name with the TASK subclause.

The application specification EMPLOYEE in the DEFAULT APPLICATION clause includes no node name, indicating that the application EMPLOYEE is resident on the same node as the menu definition. This is the default.

#2

DEFAULT APPLICATION IS RAVEN::DEPART; 
ENTRIES ARE 
  ADD    :  TASK IS ADD_EMPLOYEE; 
            TEXT IS "Add Employee Information"; 
  CHANGE :  TASK IS CHANGE_EMPLOYEE IN EMPLOYEE; 
            TEXT IS "Change Employee Information"; 
END ENTRIES; 
END DEFINITION; 
      

In this example, the default application database DEPART runs on the remote node RAVEN, so the application specification includes the node name followed by two colons followed by the application file name. Because the ADD task entry includes no application name, ADD takes the default application. The CHANGE task, however, belongs to a different application, Employee, in the database file EMPLOYEE.ADB on the same node as the menu definition. The assignment you make for the CHANGE task overrides the default for that task.

#3

DEFAULT APPLICATION IS 
           "LONG_LOGICAL_NAME_FOR_APPLICATION_NODE::EMPLOYEE"; 
ENTRIES ARE 
  ADD    :  TASK IS ADD_EMPLOYEE; 
            TEXT IS "Add Employee Information"; 
  CHANGE :  TASK IS CHANGE_EMPLOYEE; 
            TEXT IS "Change Employee Information"; 
END ENTRIES; 
END DEFINITION; 
 
      

In this example, the default application database file is:

LONG_LOGICAL_NAME_FOR_APPLICATION_NODE::EMPLOYEE.

LONG_LOGICAL_NAME_FOR_APPLICATION_NODE is defined as RAVEN, so OpenVMS translates the application specification as RAVEN::EMPLOYEE. Because the logical name is longer than 31 characters, the application specification is enclosed in quotation marks.


Previous Next Contents Index