# Compaq ACMS for OpenVMS
Writing Applications

Previous | Contents | Index

## 18.3.1 Alternatives to TDMS REQUEST I/O

You can use either the ACMS Request Interface (RI) or Compaq TP Desktop Connector (formerly ACMS Desktop) to perform REQUEST I/O from a task in place of TDMS requests. If you use the RI or Compaq TP Desktop Connector (formerly ACMS Desktop) in your ACMS application to perform REQUEST I/O, then some of the restrictions in Table 18-3 and all of the restrictions in Table 18-4 regarding REQUEST I/O on the block step do not apply.

See Compaq ACMS for OpenVMS Writing Applications for more information about the Request Interface. See the TP Desktop Connector for OpenVMS Programming and Management Guide for more information about using Compaq TP Desktop Connector (formerly ACMS Desktop).

## 18.3.2 Alternative to DECforms FORM I/O

If you are using OpenVMS Alpha Version 1.5, you can use Compaq TP Desktop Connector (formerly ACMS Desktop) to perform FORM I/O from a task in place of DECforms FORM I/O. If you use Compaq TP Desktop Connector in your ACMS application to perform FORM I/O, then some of the restrictions in Table 18-3 and all of the restrictions in Table 18-4 regarding FORM I/O on the block step do not apply.

See the TP Desktop Connector for OpenVMS Programming and Management Guide for more information about using FORM I/O with Compaq TP Desktop Connector (formerly ACMS Desktop).

# 18.4 Selecting Tasks and Menus on OpenVMS Alpha

You can use the ACMS/ENTER command on OpenVMS Alpha to select the following kinds of tasks:

- Tasks that require no terminal interaction
- Tasks that specify FORM I/O in the task definition
- Tasks that specify STREAM I/O in the task definition
- Some local tasks that specify TERMINAL I/O in the task definition
  See Table 18-3 for more information.

Because TDMS is not on the OpenVMS Alpha platform, a menu that uses this request option appears as a command line menu when you issue the ACMS/ENTER command on OpenVMS Alpha. The following sections describe the commands and keys that are available in the command line menu interface.

## 18.4.1 ACMS Menu Commands

If you issue the ACMS/ENTER command on an OpenVMS Alpha system, ACMS returns the Selection prompt as the following example shows:

    $ ACMS/ENTER
    Selection:

Enter a dollar sign ($) at the Selection prompt to enable the ACMS command menu prompt. Table 18-5 lists the ACMS commands that are available at the selection prompt.

Table 18-5 ACMS Menu Commands
Command | Description
--- | ---
CONTINUE | Returns to a selection menu from a command menu
EXIT | Ends your ACMS session and signs you out of ACMS
HELP | Provides information on ACMS commands and menus
MENU | Displays selection or command menu
NOMENU | Displays a Command: or Selection: prompt without displaying the command or selection menu
SELECT | Selects a task that is not in your menu tree without including the menu path for the task

A selection menu is application-specific. Issue the MENU command at the Selection prompt to display menu items. Figure 18-1 shows the selection menu from the AVERTZ sample application.

Figure 18-1 AVERTZ Rental Menu

You select an item from the menu by either name or number. For example, to select the reservation task, type RESERVE or 1.

Menus can display tasks and menus. The letter (T or M) following the task name in the selection menu indicates whether the menu item is a task or another menu (called a submenu). If you know the name of the task you want to select from a submenu, you can enter both the menu keyword and the task keyword at the Selection prompt.

You can also select a task without specifying the menu path by including the application name and the task name on the command line. For example, suppose that you want to access the DELETE task, which is an item on a submenu of the PAYROLL application. You can select it directly by issuing the following command:

    Selection: SELECT SAMPLE::PAYROLL DELETE

If you know the menu path of the task you want to select, you can access the task directly from the Selection prompt. For example:

    Selection: 1 2 1

This allows you to select the task without going through every menu in the menu path.

## 18.4.2 ACMS Function Keys

Table 18-6 lists the keys that are available in the command line menu interface.

Table 18-6 ACMS Function Keys
Key | Description
--- | ---
Asterisk | Enables the default menu
Ctrl/Y | Cancels the current ACMS task
DELETE | Erases the last character typed
Dollar sign | Enables the command menu
Hyphen | Enables the menu one level above the current menu

# Chapter 19
Managing Applications on OpenVMS Alpha

You manage and monitor ACMS applications on OpenVMS Alpha the same way as you do on OpenVMS VAX. The ACMS operator commands, utilities, and tools are the same for both platforms. However, there are some differences based on the architecture of OpenVMS Alpha and OpenVMS VAX.

Take the following into consideration when managing an ACMS application on OpenVMS Alpha:

- Process quotas
  Process quotas need to be higher on OpenVMS Alpha. Execute the ACMS command procedures ACMSPARAM.COM and ACMEXCPAR.COM on OpenVMS Alpha to calculate values for the ACC, CP, EXC, QTI, and TSC.
- Physical page sizes
  Physical page sizes are larger on OpenVMS Alpha. Therefore, the value of the ACMSGEN TWS_POOLSIZE parameter needs to be increased on OpenVMS Alpha. Execute the ACMS command procedure ACMSPARAM.COM on OpenVMS Alpha to calculate the value for the TWS_POOLSIZE parameter.
  You do not need to increase any other ACMSGEN parameters unless the application load increases.
- Memory requirements
  Memory requirements for users are higher on OpenVMS Alpha. Therefore, account quotas and SYSGEN parameters associated with memory usage need to be increased.
- Disk quotas
  Disk quotas for users on OpenVMS Alpha may need to be higher because images on OpenVMS Alpha require more disk space.

See the following for more information:

- Compaq ACMS for OpenVMS Managing Applications
- A Comparison of System Management on OpenVMS AXP and OpenVMS VAX

# Appendixes

The appendixes provide the following supplemental information:

- Appendix A shows how to modify the standard ACMS menu format using by DECforms.
- Appendix B shows how to modify the standard ACMS menu format by using TDMS.
- Appendix C shows how to use CDO to track relationships between ACMS entities in the CDD dictionary.
- Appendix D demonstrates how to use the optional Language-Sensitive Editor productivity tool to enter ACMS code on line.
- Appendix E lists the files included with the ACMS Request Interface examples and software supplied by ACMS.
- Appendix F explains how to modify the FMS menu interface that you use with the ACMS Request Interface.
- Appendix H contains a list of references to platform-specific files in an ACMS application.
- Appendix I contains a list of common errors with an explanation and an appropriate user action.

# Appendix A
Changing the ACMS Menu Format Using DECforms

Do not attempt to make changes in the standard ACMS menu unless you are thoroughly familiar with DECforms. Errors in the DECforms records and definitions that ACMS uses for menu work can produce fatal exceptions that cause other parts of the ACMS system to fail; avoid changing the ACMS menu format except when there is a serious need.

This appendix also describes how to disable the SELECT command, which gives the user the ability to select a task by application name and task name from the ACMS Command Menu. Disabling the SELECT command does not require using DECforms.

# A.1 Modifying Menu Appearance Without Changing the Default Format

There are two ways to revise the ACMS menu format without changing the default format. First, you can include OpenVMS images that use option lists or menus in your application. Second, when you set up a menu using ADU, you can make a number of choices in the menu format that ACMS supplies. For example, you can define the text that appears at the top of the menu. You define the entries that are displayed on the screen and the descriptive text for these entries.

By using the HEADER, DEFAULT APPLICATION, and ENTRIES clauses (and the subclauses under ENTRIES), you can change what is displayed on the menu. The format of the menu, however, is the same from menu to menu:

- The two lines of header text are the top two lines of the screen.
- Each page of the menu can contain up to 16 entries.
- Each entry line consists of a number, a keyword, a task/menu flag, and descriptive text.
- The Selection: prompt displays on the third line from the bottom.
- The bottom line is used for all messages except "Press <RET> for more" and "Press <RET> for first page". These messages are displayed on the line above the selection prompt.

# A.2 Modifying the ACMS Menu Using DECforms

You can change some parts of this format just by changing the DECforms panel definitions that ACMS uses. For example, you can change the Selection: prompt or the "Press <RET> ..." message lines by changing the Default and Command panel definitions in the ACMS_MENU.IFDL file. Other changes can require you to change other parts of the ACMS_MENU.IFDL source file that is the source of the menu form. The rest of this appendix explains how to change the source file, ACMS_MENU.IFDL, in order to modify the ACMS menu format.

ACMS uses two panel definitions contained in the ACMS_MENU.IFDL file to control the display of menus on the system:

- Panel DEFAULT_PANEL is the complete ACMS menu, which includes 16 entries, a 2-line menu header, the Selection: prompt, and a 2-line selection input field.
- Panel EXPERT_DEF_PANEL contains the Selection: prompt and the 2-line selection input field; this form is for users who want to select tasks without seeing menus.

There are two corresponding definitions in the ACMS_MENU.IFDL for the ACMS Command Menu: panel COMMAND_PANEL, and panel EXPERT_COM_PANEL. The latter displays only the Command: prompt while the former displays eight entries plus the Command: prompt.

To modify the default ACMS menu format, you need to change the ACMS_MENU.IFDL file that displays and controls the menu form. For example, if you want to change the number of entries that can appear on a menu, you must change the ACMS_MENU.IFDL file. After it has been modified, you use DECforms to create a new .EXE file to produce the menu format. For more information on creating a new .EXE file after you have modified the ACMS_MENU.IFDL file, see DECforms Guide to Developing an Application.

To change the menu, you must either modify the ACMS_MENU.IFDL file supplied by ACMS or create a new ACMS_MENU.IFDL file.

You can modify the ACMS menu ACMS_MENU.IFDL file and keep the same name for it. Alternatively, you can make a copy of the ACMS_MENU.IFDL file and make your changes in the copy. In either case, you use DECforms procedures to create a new .EXE file.

ACMS always looks for the menu form file in the same place with a fixed name: SYS$SHARE:ACMS_MENU.EXE. So after you have modified the ACMS_MENU.IFDL file or a copy of it and created a new .EXE file, it must always be copied to the SYS$SHARE directory with the ACMS_MENU.EXE file name. All menus on your ACMS system then use the modified default format.

## A.2.1 Obtaining the ACMS DECforms Default Menu File

To create a new default menu file, you can make a copy of the source file, ACMS_MENU.IFDL, and alter it as explained in this appendix in order to meet your needs. Or, you can alter the ACMS_MENU.IFDL file itself if you are sure the changes you are making are permanent. The ACMS_MENU.IFDL is also stored in the SYS$SHARE directory.

CAUTION Do not, under any conditions, change the HEADER RECORD DATA or the MENU CONTROL RECORD DATA definitions. There is only one entry in the MENU ENTRY RECORD DATA definition that can be changed, as explained in the following sections. Changes in any other fields of these definitions can cause the ACMS system to fail.

## A.2.2 How ACMS Uses Menu Form Record Definitions

Five form record definitions in the ACMS menu definition file control how the information you supply in the menu definitions you write as part of an application is used.

The first is the menu header record. Example A-1 shows how this form record definition appears in the ACMS_MENU.IFDL file.

Example A-1 Definition for ACMS Menu Header

    Form Record MENU_HEADER
        NUM_ENTRIES Unsigned Longword
        MENU_PATH Character(70)
        MENU_HEADER_1 Character(80)
        MENU_HEADER_2 Character(80)
    End Record

ACMS uses the NUM_ENTRIES field to pass to the form the number of entries in the MENU_ENTRIES record.

ACMS uses the two menu header fields to pass the menu header, or title, to the form file. It takes this text from the HEADER clause of the menu definition.

The default ACMS menu does not use the MENU_PATH field of this record. The menu path is the sequence of menus, identified by keyword, that the user followed in reaching the current menu; ACMS maintains this information. But this field can be used to display the user's current location in the menu tree.

Example A-2 shows the ACMS_MENU.IFDL file definition for the second record used by the ACMS form file, MENU_ENTRIES.

Example A-2 Definition for Menu Entries Record

    Form Record MENU_ENTRIES
        Group ENTRIES
            Occurs 16
            ENTRY_ENABLE Character(1)
            ENTRY_NUMBER Character(6)
            ENTRY_FILL Character(3)
            ENTRY_KEY Character(10)
            ENTRY_FLAG_TEXT Character(56)
        End Group

    End Record

ACMS uses the form record MENU_ENTRIES to pass the number, keyword, identifying flag, and descriptive text to the form file. It derives all this information for each entry from the menu database. The number for an entry is derived from the sequence in which the entry occurs in the ENTRIES clause of the menu definition you write as part of an application. The keyword is derived from the name used for the entry in the ENTRIES clause; the text is taken from the TEXT subclause for the entry. The ENTRY_ENABLE field contains one of two values: T (for tasks) or M (for menus).

Example A-3 shows MENU_CONTROL, the third form record used by the form file.

Example A-3 Definition for Menu Control

    Form Record MENU_CONTROL
        CTL_EXPERT_MENU Character(1)
        CTL_NEW_ENTRIES Character(1)
        CTL_MULTI_PAGE Character(1)
        CTL_LAST_PAGE Character(1)
    End Record

The information in the menu control record does not come directly from the menu database. Rather, it is information that ACMS maintains for each user and for the user's current menu. The value of CTL_EXPERT_MENU determines whether the user sees the complete ACMS menu, in which case the field is set to F (False), or sees only the selection prompt, in which case the field is set to T (True). The initial value is set from the user definition file (ACMSUDF.DAT). Each time the user types in the terminal user MENU or NOMENU command, that field is updated.

ACMS uses the MULTI_PAGE and LAST_PAGE fields in the record to tell the form file whether more menu entries are available than would fit on a single screen. It uses the NEW_ENTRIES field to tell the form file whether the entries to be displayed differ from the entries last displayed.

Example A-4 shows MENU_SELECTION_RECORD, the fourth record used by the form file.

Example A-4 Definition for Menu Selection Record

    Form Record MENU_SELECTION
        Group APPL_SELECT_LINE_GROUP
            APPL_SELECTION_STRING_1 Character(68)
            Transfer APPL_SELECT_LINE_GROUP.APPL_SELECTION_STRING_1
                    Source SELECT_LINE_GROUP.SELECTION_STRING_1
            APPL_SELECTION_STRING_2 Character(187)
            Transfer APPL_SELECT_LINE_GROUP.APPL_SELECTION_STRING_2
                    Source SELECT_LINE_GROUP.SELECTION_STRING_2
        End Group

    End Record

This record consists of two fields which accept the selection strings from the menu. The APPL_SELECTION_STRING_1 and APPL_SELECTION_STRING_2 fields are the actual fields received by the ACMS Command Process (CP). The user input is made in the SELECTION_STRING fields. The two APPL_SELECTION_STRING fields accept up to a maximum of 255 characters. If the actual input is less, the strings are padded with blanks. The size of the APPL_SELECTION_STRING fields cannot be changed.

Example A-5 shows the fifth record, which tells the ACMS CP if any control text response with an accept phase has been executed.

Example A-5 Control Text Response Found Record

    Form Record MENU_CTRL_TEXT_FOUND
        CTRL_TEXT_RESP_FOUND Longword Integer
    End Record

## A.2.3 Instructions Performed by the Form File

The .EXE file built from the ACMS_MENU.IFDL file carries out a number of functions when ACMS calls a menu you defined in the course of constructing an application. This section explains those functions.

First, either a complete menu or the selection prompt only is displayed.

After the user has typed in a selection keyword or number (and, optionally, a selection string) and pressed `[Return]`, the request moves that information to the menu selection record.

The form file uses the value passed in the CTL_EXPERT_MENU field to determine whether to display the complete menu or only the expert menu. If the CTL_EXPERT_MENU field is set to T, the expert menu is displayed, the selection is entered in the menu selection record, and the process ends.

If the CTL_EXPERT_MENU field is not set to T, the form file then checks whether the entries to be displayed are the same ones as the last entries the user saw. If the value of the CTL_NEW_ENTRIES field of the control record is set to a value other than T, then the menu is the same as the last one. In this case, the form file displays the last menu, accepts the selection string, and ends.

If the menu to be displayed does contain new entries, then ACMS has set the value of CTL_NEW_ENTRIES to T. In this case, the form file displays the menu form and outputs the menu header. It then begins displaying the entries to the indexed fields on the menu form. As long as there is an entry, which the form file checks by looking at one of the fields to be displayed, it continues to produce the entry information. As soon as there are no more entries, or when the sixteenth entry has been displayed, the process stops.

If there are more entries than the number of entries allowed per screen, ACMS sets the value of CTL_MULTI_PAGE to "T". This indicates that the menu has multiple pages.

If there are more than 16 entries, which is the default number of entries for each screen, then the request tests the CTL_LAST_PAGE field to determine whether or not this is the last page of the menu displayed to the user. ACMS indicates the last page of the menu by setting the CTL_LAST_PAGE field to T. If this is a multiple page menu and it is the last page, the form file displays the message "Press <RET> for first page". If it is not the last page of the menu, the form file outputs the message "Press <RET> for more". It then accepts the selection from the user and ends.

## A.2.4 Modifying the Menu Appearance Only

If you are changing only the appearance of the menu without changing the number of entries, you can make the changes by modifying the panel definitions in the ACMS_MENU.IFDL file. By modifying the panel definitions, you can change:

- The background text that displays on the menu. The only background text on the ACMS-supplied form is the Selection: or Command: prompt. You can change this prompt or add other background text.
- The text of the instruction for multiple-page menus.

For a detailed explanation of how to modify DECforms form definitions, see DECforms Guide to Developing an Application. If you are changing only the Selection: or Command: prompts or adding more background text, or want to change the text of the instructions for multiple page menus, you will be altering the panel definitions only.

The ACMS_MENU.IFDL file supplied with ACMS includes a number of DECforms panel definitions. To make the changes detailed in the following paragraphs, you must alter two of these panel definitions, those for DEFAULT_PANEL and COMMAND_PANEL.

These two definitions are very similar, but you must be sure to make the changes you want in both definitions so that your menus will be consistent. Example A-6 shows how the DEFAULT_PANEL definition appears in the ACMS_MENU.IFDL file.

Example A-6 Panel Definition

    Panel DEFAULT_PANEL
                Viewport DEFAULT_VIEW
                Field MENU_HEADER_1
                    Line 1
                    Column 1
                    Display
                        Bold
                    Output Picture X(80)
                End Field

                Field MENU_HEADER_2
                    Line 2
                    Column 1
                    Display
                        Bold
                    Output Picture X(80)
                End Field

                Literal Text
                    Next Line
                    Value ""
                End Literal

                Group ENTRIES
                    Vertical
                        Displays 16
                    Entry Response
                        Reset
                            INFO_LINE_1
                    End Response

                    Exit Response
                        Message
                            ""
                        If (RECALL_HOLD = 1) Then
                            Let RECALL_HOLD = 0
                        Else
                            If (PREVIOUS_PAGE = 1) Then
                                Let SELECT_LINE_GROUP.SELECTION_STRING_1 = "\"
                                Reset
                                    SELECT_LINE_GROUP.SELECTION_STRING_2
                            Else
                                If (NEXT_PAGE = 1) Then
                                    Reset
                                        SELECT_LINE_GROUP.SELECTION_STRING_1
                                    Reset
                                        SELECT_LINE_GROUP.SELECTION_STRING_2
                                Else
                                    Let SELECT_LINE_GROUP.SELECTION_STRING_1 =
                                        ENTRIES(MENU_ENTRIES_INDEX).ENTRY_KEY
                                    Reset
                                        SELECT_LINE_GROUP.SELECTION_STRING_2
                                    Include RESET_RECALL_LIST
                                End If
                            End If
                        End If
                    End Response

                    Function Response CHANGE
                        Let ON_ENTRIES = 0
                        Let RECALL_HOLD = 1
                        Deactivate
                            All
                        Activate
                            Field SELECT_LINE_GROUP.SELECTION_STRING_2 on
                                DEFAULT_PANEL
                        Activate
                            Field SELECT_LINE_GROUP.SELECTION_STRING_1 on
                                DEFAULT_PANEL
                        Position To Field SELECT_LINE_GROUP.SELECTION_STRING_1 On
                            DEFAULT_PANEL
                    End Response

                    Function Response GO_UP
                        If (MENU_ENTRIES_INDEX = 1) Then
                            Let PREVIOUS_PAGE = 1
                            Return
                        Else
                            Position To Up Occurrence
                        End If
                    End Response

                    Function Response GO_DOWN
                        If (MENU_ENTRIES_INDEX = NUM_ENTRIES) Then
                            Let NEXT_PAGE = 1
                            Return
                        Else
                            Position To Down Occurrence
                        End If
                    End Response
                    Field ENTRY_NUMBER
                        Next Line
                        Column 3
                        Active Highlight
                            Reverse
                        Output Picture X(6)
                        No Data Input
                    End Field

                    Field ENTRY_KEY
                        Same Line
                        Column 12
                        Output Picture X(10)
                    End Field

                    Field ENTRY_FLAG_TEXT
                        Same Line
                        Column 22
                        Output Picture X(56)
                    End Field

                End Group

                Field INFO_LINE_1
                    Line 21
                    Column 1
                    Output Picture X(80)
                End Field

                Group SELECT_LINE_GROUP
                    Entry Response
                        If (CTL_MULTI_PAGE = "T") Then
                            If (CTL_LAST_PAGE = "T") Then
                                Let INFO_LINE_1 = "                  ....... "-
                                    "Press <RET> for first page ......."
                            Else
                                Let INFO_LINE_1 = "                     ....... "-
                                    "Press <RET> for more ......."
                            End If
                        Else
                            Reset
                                INFO_LINE_1
                        End If
                    End Response
                    Exit Response
                        Message
                            ""
                        If (RECALL_HOLD = 1) Then
                            Let RECALL_HOLD = 0
                        Else
                            If (PREVIOUS_PAGE = 1) Then
                                Let SELECT_LINE_GROUP.SELECTION_STRING_1 = "\"
                                Reset
                                    SELECT_LINE_GROUP.SELECTION_STRING_2
                                Let PREVIOUS_PAGE = 0
                            Else
                                If (NEXT_PAGE = 1) Then
                                    Reset
                                        SELECT_LINE_GROUP.SELECTION_STRING_1
                                    Reset
                                        SELECT_LINE_GROUP.SELECTION_STRING_2
                                    Let NEXT_PAGE = 0
                                Else
                                    Include RESET_RECALL_LIST
                                End If
                            End If
                        End If
                    End Response

                    Function Response CHANGE
                        Let ON_ENTRIES = 1
                        Let RECALL_HOLD = 1
                        Reset
                            SELECT_LINE_GROUP.SELECTION_STRING_1
                        Reset
                            SELECT_LINE_GROUP.SELECTION_STRING_2
                        Deactivate
                            All
                        Activate
                            Field ENTRIES.ENTRY_NUMBER on DEFAULT_PANEL
                        Position To Field ENTRIES(1).ENTRY_NUMBER
                            On DEFAULT_PANEL
                    End Response

                    Function Response GO_UP
                        Include GET_PREVIOUS_RECALL_ITEM
                    End Response

                    Function Response GO_DOWN
                        Include GET_NEXT_RECALL_ITEM
                    End Response

                    Literal Text
                        Line 22
                        Column 1
                        Value "Selection: "
                    End Literal

                    Field SELECTION_STRING_1
                        Line 22
                        Column 12
                        Autoskip
                        Output Picture X(68)
                    End Field

                    Field SELECTION_STRING_2
                        Line 23
                        Column 1
                        Output Picture X(79)
                    End Field

                End Group

            End Panel

Previous | Next | Contents | Index