Compaq ACMS for OpenVMS
Getting Started


Previous Contents Index

For more information on testing and debugging tasks, see Compaq ACMS for OpenVMS Writing Server Procedures. For information on using the OpenVMS Debugger, consult the OpenVMS Debugger Manual.


Chapter 10
Defining and Building the Application

In this chapter, you learn how to write the application definition. You then build this definition into an application database that ACMS uses at run time.

10.1 Defining the Application

An ACMS application controls one or more task groups, each of which contains related tasks that may share servers. In the application definition, you describe characteristics that control the tasks, the servers, and the application. ACMS provides defaults for most of the control characteristics that an application requires.

You create the application definition as a source file of ADU commands in the same manner that you created the task and task group definitions earlier.

10.1.1 Application Characteristics

To begin writing the application definition, follow these steps:

  1. Use a text editor to create a source file for the application definition. Name the file EMPLOYEE_INFO_APPL_xxx.ADF, filling in your initials or other unique characters for the xxx part of the name. Creating a unique application name avoids conflicts with the applications of others who may be entering this tutorial on your system. (If you copy the file EMPLOYEE_INFO_APPL_xxx.ADF from the online source files, rename it to substitute your initials for xxx. Also, edit this file to make the same name change in the first line of the file.)
  2. Begin your file by entering the following lines:


    REPLACE APPLICATION EMPLOYEE_INFO_APPL_xxx 
      AUDIT; 
      APPLICATION USERNAME IS EMPLOYEE_EXC; 
    

    The AUDIT clause directs ACMS to collect audit trail information for the application. This information is useful for determining how an ACMS system and its tasks and applications are being used. The ACMS Audit Trail Logger gathers statistics about an active ACMS system and records them in the audit trail log file. This file, which is named SYS$ERRORLOG:ACMSAUDIT.LOG by default, records such information as task selections, task cancellations, user logins and logouts, and application starts and stops.
    At run time, ACMS uses an OpenVMS process called an Application Execution Controller (EXC) for each application. The EXC executes the task and performs task flow control. The APPLICATION USERNAME clause specifies the user name EMPLOYEE_EXC for the Application Execution Controller. Chapter 12 describes how your system manager creates the account EMPLOYEE_EXC.

10.1.2 Server Characteristics

Every server in an application has an OpenVMS user name. By default, a server uses the application user name as its OpenVMS user name. For most applications, however, use a different OpenVMS account for the server, because the server usually requires fewer privileges and lower quotas than an application. The application definition specifies the name EMPL_SERVER. Chapter 12 describes how your system manager creates the account EMPL_SERVER.

Add the following lines to your source file:


SERVER DEFAULTS ARE 
    AUDIT; 
    USERNAME IS EMPL_SERVER; 
    MINIMUM SERVER PROCESSES IS 1; 
    MAXIMUM SERVER PROCESSES IS 1; 
END SERVER DEFAULTS; 

The AUDIT clause generates audit trail information for the server. The USERNAME clause names EMPL_SERVER as the account in which the server runs.

ACMS lets you control both the minimum and maximum number of server processes used for your application. Servers are serially reusable, so they can be created once and used several times by the application. The MINIMUM SERVER PROCESSES and MAXIMUM SERVER PROCESSES clauses specify that only one server process be created for the application. Specifying the same number for the minimum and the maximum can greatly improve the performance of your application, provided that the number of processes is adequate for the number of users.

10.1.3 Task Characteristics

The only required task characteristic is the name of every task group in the application. Optional task characteristics specify which users can run which tasks and whether audit trail information is recorded for the tasks. This tutorial application is simple enough that all users can be allowed access to all tasks.

  1. Add these lines to your source file:


    TASK DEFAULTS ARE 
        AUDIT; 
    END TASK DEFAULTS; 
     
    TASK GROUPS ARE 
      EMPLOYEE_INFO_TASK_GROUP: 
        TASK GROUP FILE IS "xxx_FILES:EMPLOYEE_INFO_TASK_GROUP.TDB"; 
    END TASK GROUPS; 
    END DEFINITION; 
    

  2. Your definition for the application definition, EMPLOYEE_INFO_APPL_xxx.ADF, is now complete. Save your file and exit the editor.

10.2 Compiling the Application Definition

Compile your source file after exiting the editor. Invoke ADU and submit the file EMPLOYEE_INFO_APPL_xxx.ADF as follows:


$ ADU
ADU> SET LOG
ADU> SET VERIFY
ADU> @EMPLOYEE_INFO_APPL_xxx.ADF

If ADU detects syntax errors in your application definition, you must exit ADU and edit the source file to correct the errors. Then reenter ADU and resubmit the file. Repeat this sequence until the file processes without errors. If you get error messages, make sure that you typed the definition exactly as shown. In particular, check that you used the appropriate punctuation.

10.3 Building the Application

Next, build the application with the ADU BUILD command and the APPLICATION keyword:


ADU> BUILD APPLICATION EMPLOYEE_INFO_APPL_xxx 

This command produces an application database file in your default OpenVMS directory. This file is sometimes called the ADB file because .ADB is the default file type (in this case, your EMPLOYEE_INFO_APPL_xxx.ADB file).

If the BUILD command succeeds, ADU displays a "Writing ADB" message.

If the BUILD command fails, ADU issues error messages and redisplays the ADU> prompt. Continue to correct the errors and resubmit the application to ADU until the application processes without errors.

Exit from ADU.


Chapter 11
Defining and Building the Menu

This chapter describes how to write the menu definition. You then build this definition into a menu database that ACMS uses at run time.

11.1 Defining the Menu

In the menu definition, you describe the contents of the top-level menu displayed to users. You now define the ACMS menu from which terminal users can select either the data entry task or the inquiry/update task. ACMS provides a standard menu format.

To define a menu, specify a name for each entry and the name of the task (and application) to which the entry corresponds. A menu entry can also be the name of another menu, which allows you to create a hierarchy of menus for an application. However, this tutorial uses only one menu.

Create the menu definition as a source file of ADU commands in the same manner that you created previous ACMS definitions.

To begin writing the menu definition, follow these steps:

  1. Use a text editor to create a source file for the menu definition. Name the source file EMPLOYEE_INFO_MENU.MDF.

    Note

    If you copied this file from the online source files, edit the file to change two occurrences of EMPLOYEE_INFO_APPL_xxx to your unique application name.
  2. Begin your file by entering the following lines:


     
    REPLACE MENU EMPLOYEE_INFO_MENU 
      HEADER IS     "                  Personnel Administration System"; 
    

    In the HEADER clause, you specify a one- or two-line title, enclosed in quotation marks, for the top of the menu. When ACMS displays the menu, the title, Personnel Administration System, preceded by the given number of spaces, appears at the top. Note that you must use spaces to center a menu title; you cannot use tabs.

  3. Add the following lines to your source file:


     
    ENTRIES ARE 
     "ADD"    : TASK IS EMPLOYEE_INFO_ADD_TASK IN EMPLOYEE_INFO_APPL_xxx; 
                TEXT IS "Add new employee record"; 
     "UPDATE" : TASK IS EMPLOYEE_INFO_UPDATE_TASK IN EMPLOYEE_INFO_APPL_xxx; 
                TEXT IS "Display or update employee record"; 
    END ENTRIES; 
     
    

    You use the ENTRIES clause to specify the entries on the menu, the type of entry, and any explanatory text. Each entry you specify is either a task or another menu. If it is a task, ACMS runs the specified task from the specified application when the user selects that entry. In the ENTRIES clause here, you give each entry a name such as ADD, specifying each entry's type (TASK), its name in the application database, and the name of the application (the menu definition can point to tasks from different applications).

  4. To end the menu definition, enter the following line at the end of the file:


    END DEFINITION; 
    

  5. Your source file for the menu definition, EMPLOYEE_INFO_MENU.MDF, is now complete. Save your file and exit the editor.

11.2 Compiling the Menu Definition

Compile your source file after exiting the editor. Invoke ADU and submit the file EMPLOYEE_INFO_MENU.MDF as follows:


$ ADU
ADU> SET LOG
ADU> SET VERIFY
ADU> @EMPLOYEE_INFO_MENU.MDF

If ADU detects syntax errors in your menu definition, you must edit the source file to correct the errors and resubmit it. Repeat this sequence until the file processes without errors. If you receive error messages, make sure that you typed the definition exactly as shown. In particular, check that you used the appropriate punctuation.

Exit from ADU.

At this point, your default CDD directory contains the definitions for the application, the menu, the task group, the data entry task, and the inquiry/update task. Use the CDO DIRECTORY command to verify that these definitions exist:


$ CDO
CDO> DIRECTORY
   CONTROL_WORKSPACE;1                       RECORD
   EMPLOYEE_INFO_ADD_TASK;1                  ACMS$TASK    
   EMPLOYEE_INFO_APPL_xxx;1                  ACMS$APPLICATION
   EMPLOYEE_INFO_MENU;1                      CDD$MENU
   EMPLOYEE_INFO_RECORD;1                    RECORD
   EMPLOYEE_INFO_TASK_GROUP;1                ACMS$TASK_GROUP 
   EMPLOYEE_INFO_UPDATE_TASK;1               ACMS$TASK    
   EMPLOYEE_INFO_WKSP;1                      RECORD
   EMPL_CITY;1                               FIELD
   EMPL_NAME;1                               FIELD
   EMPL_NUMBER;1                             FIELD 
   EMPL_STATE;1                              FIELD
   EMPL_STREET_ADDRESS;1                     FIELD
   EMPL_ZIP_CODE;1                           FIELD
   ERROR_STATUS_FIELD;                       FIELD      
   MESSAGEPANEL;                             FIELD      
   QUIT_KEY;1                                FIELD
   QUIT_WORKSPACE;1                          RECORD 
 
CDO>

To look at the contents of a field or a record, you can use the SHOW FIELD or SHOW RECORD command, followed by the name of the record or field.

11.3 Building the Menu

Build the menu with the ADU BUILD command and the MENU keyword:


$ ADU
ADU> BUILD MENU EMPLOYEE_INFO_MENU 

This command produces a menu database file in your default OpenVMS directory. The file is named EMPLOYEE_INFO_MENU.MDB.

If the BUILD command succeeds, ADU displays a "Writing MDB" message.

If the BUILD command fails, ADU issues error messages and redisplays the ADU> prompt. You must correct the errors and resubmit the menu to ADU, repeating this sequence until the menu processes without errors.

Exit from ADU.


Chapter 12
System Management Requirements for Installing the Tutorial Application

This chapter describes procedures that your system manager follows to prepare for the installation of your tutorial application. Once these procedures are completed, you can install your application and run its tasks as described in Chapter 13.

Note

If you do not have the privileges (SYSPRV) necessary to perform the steps in this chapter, your system manager must perform these steps for you.

To perform these steps, your system manager needs to know the name of your application (represented here by EMPLOYEE_INFO_APPL_xxx) and the logical for your default directory (repesented here by xxx_FILES).

12.1 System Management Overview

The system manager performs the steps in this chapter to prepare for the installation of the tutorial application. Specifically, the system manager does the following:

12.2 Creating the EMPL_SERVER and EMPLOYEE_EXC Accounts

To set up OpenVMS user accounts, your system manager uses the OpenVMS Authorize Utility. Here the system manager uses the OpenVMS Authorize Utility to set up the user accounts of the server and the Application Execution Controller. In the tutorial application, the server's user name is EMPL_SERVER, and the controller's user name is EMPLOYEE_EXC.

If you are not the first person at your site to use this tutorial, it is possible that the EMPLOYEE_EXC and EMPL_SERVER user names already exist in the OpenVMS User Authorization File (UAF). In that case, the system manager can check to see if the quotas are correct and can modify any that are not.

If the EMPL_SERVER account does not exist yet, create it using the following quotas and privileges:


Maxjobs:         0  Fillm:       200  Bytlm:        50000 
Maxacctjobs:     0  Shrfillm:      0  Pbytlm:           0 
Maxdetach:       0  BIOlm:       100  JTquota:       1024 
Prclm:           2  DIOlm:        22  WSdef:          512 
Prio:            4  ASTlm:       100  WSquo:         1024 
Queprio:         0  TQElm:       100  WSextent:      4096 
CPU:        (none)  Enqlm:      2000  Pgflquo:      60000 
Authorized Privileges: 
  GRPNAM GROUP SETPRV TMPMBX OPER NETMBX BYPASS 
Default Privileges: 
  GRPNAM GROUP TMPMBX OPER NETMBX BYPASS 

If the EMPLOYEE_EXC account does not exist yet, create it using the following quotas and privileges:


Maxjobs:         0  Fillm:       200  Bytlm:        50000 
Maxacctjobs:     0  Shrfillm:      0  Pbytlm:           0 
Maxdetach:       0  BIOlm:       100  JTquota:       1024 
Prclm:           2  DIOlm:        22  WSdef:          512 
Prio:            4  ASTlm:       100  WSquo:         1024 
Queprio:         0  TQElm:       100  WSextent:      4096 
CPU:        (none)  Enqlm:      2000  Pgflquo:      60000 
Authorized Privileges: 
  GRPNAM GROUP SETPRV TMPMBX NETMBX 
Default Privileges: 
  GRPNAM GROUP TMPMBX NETMBX 

For the EMPL_SERVER and EMPLOYEE_EXC user accounts, your system manager might need to increase some of the SYSGEN parameters. Your system manager should check the values of the following parameters whose names have the PQL_ prefix --- in particular, the PQL_MENQLM parameter:
PQL_DASTLM PQL_DBIOLM PQL_DBYTLM PQL_DCPULM
PQL_DDIOLM PQL_DENQLM PQL_DFILLM PQL_DJTQUOTA
PQL_DPGFLQUOTA PQL_DPRCLM PQL_DTQELM PQL_DWSDEFAULT
PQL_DWSEXTENT PQL_DWSQUOTA PQL_MASTLM PQL_MBIOLM
PQL_MBYTLM PQL_MCPULM PQL_MDIOLM PQL_MENQLM
PQL_MFILLM PQL_MJTQUOTA PQL_MPGFLQUOTA PQL_MPRCLM
PQL_MTQELM PQL_MWSDEFAULT PQL_MWSEXTENT PQL_MWSQUOTA

12.3 Authorizing ACMS Users

Authorized OpenVMS users cannot sign in to ACMS until the system manager has also authorized them as ACMS users. The User Definition Utility (UDU) provides the capability to do this. Using the UDU, the system manager creates an ACMS database named ACMSUDF.DAT, located in the SYS$SYSTEM directory. When adding a user to the database, the system manager also specifies the default menu the user sees upon signing in to ACMS.

To add a new user to the ACMS database, perform the following steps:

  1. Define UDU as a global symbol in your login command file. Then initialize the symbol by executing your login command file:


    $ UDU :== $ACMSUDU 
    


    $ @LOGIN.COM
    

  2. Set the default directory to SYS$SYSTEM:


    $ SET DEFAULT SYS$SYSTEM
    $
    

  3. Invoke UDU:


    $ UDU
    UDU>
    

  4. Add an OpenVMS user name (the tutorial user's uname) to the ACMS database by entering the ADD command:


    UDU> ADD uname /MDB=xxx_FILES:EMPLOYEE_INFO_MENU
    UDU>
    

    Include the MDB qualifier to specify the default menu displayed to this user when entering ACMS. Although the menu database is often located in ACMS$DIRECTORY for security reasons, this tutorial places it in the tutorial user's default directory (represented by uname's system logical xxx_FILES) to avoid conflicts with others entering this tutorial on the same system. Substitute uname's logical for xxx_FILES.

  5. Enter the SHOW command to verify this entry in the ACMSUDF.DAT database:


    UDU> SHOW uname
    User name:       UNAME               DISPLAY MENU
    Default menu:
    Default MDB:     XXX_FILES:EMPLOYEE_INFO_MENU
    .
    .
    .
    UDU>
    

    An entry under the tutorial user's uname indicates that the uname is authorized to sign in to ACMS. The default characteristic DISPLAY MENU causes ACMS to display the top menu in uname's EMPLOYEE_INFO_MENU.MDB database.

  6. Enter the SHOW SYSTEM command to determine if user name SYSTEM has been added to the ACMS database (it may not, if this is the first ACMS access). If you receive a "user does not exist" message, then add SYSTEM as follows:


    UDU> ADD SYSTEM /AGENT
    UDU>
    

    Although ACMS assigns the user name SYSTEM to the Command Process (CP) when you install ACMS, it does not automatically authorize the Command Process as an agent. Without this authorization, ACMS cannot sign in any users. The /AGENT qualifier enables an agent to submit a task that has a user name different from the user name of the agent process.

  7. Exit from UDU.

Other UDU commands let the system manager tailor definitions for individual users, change and remove user definitions, and change user names. See Compaq ACMS for OpenVMS Managing Applications for more information about UDU.

12.4 Authorizing ACMS Terminals

Authorized ACMS users must sign in from terminals that have been authorized for access to ACMS. With the Device Definition Utility (DDU), the system manager creates a database named ACMSDDF.DAT that contains a list of authorized ACMS devices. In the simplest case, the system manager can use one DDU definition to authorize all terminals on your system, both local and remote, to use ACMS.

To use DDU to authorize terminals for users, follow these steps:

  1. Define DDU as a global symbol in your login command file. Then initialize the symbol by executing your login command file:


    $ DDU :== $ACMSDDU 
    


    $ @LOGIN.COM
    

  2. Set the default directory to SYS$SYSTEM:


    $ SET DEFAULT SYS$SYSTEM
    $
    

  3. Invoke DDU:


    $ DDU
    DDU>
    

  4. Use the ADD command to authorize a LAT terminal on your system for ACMS use. The device name LT authorizes all LAT terminals.


    DDU> ADD LT
    DDU>
    

    If the ADD LT command has been performed before for a previous tutorial user, you receive the message, "device name already exists in the data base." In this case, you can exit from DDU and proceed to the next section.

  5. Use the SHOW command to display information about the LT entry:


    DDU> SHOW LT
    Device name:     LT                   NOT CONTROLLED
    No Autologin
    Printfile
    DDU>
    

    When the system manager creates a new ACMSDDF.DAT database, DDU creates a DEFAULT definition that assigns all terminals the NOT CONTROLLED characteristic. From a CONTROLLED terminal, the user signs in directly to ACMS; from a NOT CONTROLLED terminal, the user first logs in to the OpenVMS operating system and then signs in to ACMS from DCL command level.

  6. Exit from DDU.

Other DDU commands let the system manager tailor definitions for individual terminals, change and remove device definitions, and change device names. See Compaq ACMS for OpenVMS Managing Applications for more information about DDU.


Previous Next Contents Index