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.

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:

• Creates two OpenVMS user accounts named EMPL_SERVER and EMPLOYEE_EXC. These accounts are created using the OpenVMS Authorize Utility.
• Defines which users can sign in to ACMS and which menu is displayed to them when they sign in. ACMS provides the User Definition Utility (UDU) for this purpose.
• Defines which terminals can be used to sign in to ACMS. ACMS provides the Device Definition Utility (DDU) for this purpose.
• Defines which users can install the application in a protected directory. ACMS provides an optional utility, the Application Authorization Utility (AAU), to make it easier to protect the application.

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.

12.5 Authorizing ACMS Applications

ACMS requires that the application database (.ADB) file reside in the directory associated with the logical name ACMS$DIRECTORY. Because this directory can be protected from unauthorized use, all application databases in ACMS$DIRECTORY remain secure.

Your application, EMPLOYEE_INFO_APPL_xxx.ADB, is currently located in your default OpenVMS directory. However, ACMS cannot find it there. You must install your application in ACMS$DIRECTORY after your system manager uses the Application Authorization Utility (AAU) to authorize both you and your application.

To use AAU to authorize tutorial users to install their applications in ACMS$DIRECTORY, follow these steps:

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

   $ AAU :== $ACMSAAU

   $ @LOGIN.COM

2. Set the default directory to SYS$SYSTEM:

   $ SET DEFAULT SYS$SYSTEM $

3. Invoke AAU:

   $ AAU AAU>

   
   If an ACMSAAF.DAT file does not exist yet in the SYS$SYSTEM directory (that is, this is the first time invoking AAU), AAU displays a message stating that it is unable to open ACMSAAF.DAT and prompting the system manager to create a new file. If the file does exist already, AAU returns the AAU> prompt.
   Creating this database is the first step of a two-step process. The system manager first uses the Application Authorization Utility (AAU) to create the database ACMSAAF.DAT in the SYS$SYSTEM directory. The system manager then adds to this file a list of applications and users who are authorized to install them.

4. By authorizing users to install applications, system managers can free themselves from having to install all applications and from having to give those users privileged access to ACMS$DIRECTORY. When the system manager creates a new ACMSAAF.DAT database, AAU creates a DEFAULT authorization with an empty access control list; that is, by default no users are authorized to install applications in ACMS$DIRECTORY.
   Enter the ADD command with an /ACL qualifier to authorize the application and the user who can install it:

   AAU> ADD EMPLOYEE_INFO_APPL_xxx /ACL=(ID=[uname],ACCESS=CONTROL) %ACMSAAU-S-APPLADD, Appl name EMPLOYEE_INFO_APPL_XXX has been added to the database AAU>

   
   This command authorizes application EMPLOYEE_INFO_APPL_xxx and authorizes user uname to install it. The /ACL qualifier overrides the default access control list. Remember that uname is the tutorial user's OpenVMS account name, and EMPLOYEE_INFO_APPL_xxx represents this user's application name (check with the tutorial user for the exact name).

5. Enter the SHOW command to verify the user's application name in the ACMSAAF.DAT database:

   AAU> SHOW EMPLOYEE_INFO_APPL_xxx

   ======================================================================= Appl name: EMPLOYEE_INFO_APPL_XXX Appl Username: * Server Usernames: * Access Control List: (IDENTIFIER=[ACMS,UNAME],ACCESS=CONTROL) ======================================================================= AAU>

   
   This display verifies that user UNAME is authorized to install the application database file EMPLOYEE_INFO_APPL_xxx.ADB. The asterisks in the application and server user name fields mean that the user names in the .ADB file are the only user names allowed for the application and the server.

6. Exit from AAU.

Other AAU commands let the system manager specify more characteristics of individual applications, authorize all applications with the $ALL keyword, remove authorizations, and change authorization names. See Compaq ACMS for OpenVMS Managing Applications for more information about AAU.

12.6 Defining the ACMS$DIRECTORY Logical

The system manager needs to verify that the ACMS$DIRECTORY logical is associated with the device and directory where ACMS applications are to be stored. In the case of a new ACMS installation, the system manager may not yet have set up a protected directory for storing ACMS applications. If not, the system manager must first set up such a directory before defining the logical that points to it. Defining the ACMS$DIRECTORY logical must be done before the tutorial user can install the tutorial application.

If other ACMS applications are already on the tutorial user's system, the ACMS$DIRECTORY logical has been defined already. To verify the logical and define it, perform the following steps:

1. Enter the SHOW LOGICAL command to see whether ACMS$DIRECTORY has been defined on the tutorial user's system:

   $ SHOW LOGICAL ACMS$DIRECTORY

   
   If the logical is defined, the subsequent display shows the disk and directory location that the logical points to. If the display states that the logical is undefined, then proceed to the next step and define it.

2. Set your default directory to SYS$MANAGER and run the ACMS_POST_INSTALL.COM command procedure located there:

   $ SET DEFAULT SYS$MANAGER $ @ACMS_POST_INSTALL.COM

   
   This command procedure defines all the standard ACMS logicals.

With the successful completion of this step, the tutorial user can proceed to install the application and run it.

This chapter describes how to install and run your tutorial application. Before running the application, you perform steps to start the ACMS system (if not running) and to start your specific application. After running your application, you perform steps to stop your application and stop the ACMS system (if no one else is using it).

13.1 Installing the Application

When you install an application, ACMS checks the ACMSAAF.DAT database to determine whether you are authorized to install that application. If so, ACMS copies the database to ACMS$DIRECTORY, deletes any earlier versions, and changes the user identification code (UIC) of the .ADB file to [1,4].

If you are not authorized to install the application, ACMS returns an error message indicating that you are not authorized. (Your system manager must have authorized you and your application with the AAU, as explained in Section 12.5.)

You install your application database file in ACMS$DIRECTORY by executing the ACMS/INSTALL command at DCL command level.

To install your application in ACMS$DIRECTORY, follow these steps:

1. Make sure that your system manager has defined the system logical ACMS$DIRECTORY to be associated with the device and directory where ACMS applications are to be stored. Enter the SHOW LOGICAL command to see whether ACMS$DIRECTORY has been defined on your system:

   $ SHOW LOGICAL ACMS$DIRECTORY

   
   If you receive a message stating that ACMS$DIRECTORY is undefined, ask your system manager to define it before trying to install your application.

2. To perform INSTALL, you must be in the directory where your application (EMPLOYEE_INFO_APPL_xxx.ADB) is located. If you are not, then set the default directory to the directory where your application files are located:

   $ SET DEFAULT udisk:[uname]

3. Issue the ACMS/INSTALL command to install your application:

   $ ACMS/INSTALL EMPLOYEE_INFO_APPL_xxx

   %ACMSINS-S-ADBINS, Application UDISK:[UNAME]EMPLOYEE_INFO_APPL_XXX has been installed to ACMS$DIRECTORY $

   
   The message indicates that you have successfully installed your EMPLOYEE_INFO_APPL_xxx.ADB application database file in ACMS$DIRECTORY.

Once all authorizations and installations are complete, you can start the ACMS system and start your application. To start and stop the ACMS system automatically with the OpenVMS system, you can include the ACMS/START and ACMS/STOP operator commands in your system startup and shutdown command files. However, in this tutorial, you start and stop ACMS interactively.

Any account from which the ACMS/START and ACMS/STOP commands are issued must have OpenVMS OPER privilege to execute these commands.

To start the ACMS system (if it is currently stopped), and to start your tutorial application, perform the following steps:

1. Issue the SHOW SYSTEM command to determine if another user has already started ACMS:

   $ ACMS/SHOW SYSTEM

   
   If the subsequent display states that "current system state" is STOPPED, proceed to the next step and start the ACMS system. However, if the display states that the current system state is STARTED, proceed to step 3.

2. Issue the START SYSTEM command to start the ACMS system:

   $ ACMS/START SYSTEM

   
   If the ACMS system starts successfully, the dollar ($) prompt returns with no intervening error messages.

3. Before you can invoke a command that runs the application, you need to start the application. Issue the START APPLICATION command with the name of your tutorial application:

   $ ACMS/START APPLICATION EMPLOYEE_INFO_APPL_xxx

   
   If the ACMS system starts successfully, the $ prompt returns with no intervening error messages. However, if your system logical xxx_FILES is not defined on this system, you receive an error message that states, in part, "Error opening TDB file XXX_FILES:[EMPLOYEE_EXC]..." See Section 7.6 for information about defining your system logical.
   If you receive an "invalid login attempt" message, your system manager may not have authorized the ACMS Command Process (CP) to run as an agent (described in Section 12.3). Without this authorization, ACMS cannot sign in any users.

The audit trail log (ATL) keeps a record of when the ACMS system starts and stops, when users sign in, when applications and tasks start and stop, and what errors occur. To display this log, you can run the Audit Trail Report Utility (ATR) (see Section A.2).

13.3 Running the Application

If your system manager has authorized you to use ACMS, and has authorized your terminal, you can run your tutorial application by issuing the ACMS/ENTER command. When you enter this command, ACMS checks the authorization files to determine whether you and your terminal are authorized.

If you pass the authorization check, ACMS displays your default menu and waits for you to select a task. When you do, ACMS finds that task in the .TDB file and runs the task.

To run your tutorial application, perform the following steps:

1. Issue the ENTER command to enter your application and display your default menu:

   $ ACMS/ENTER

   
   If this command is successful, ACMS displays your default menu. Figure 13-1 shows the selection menu displayed for this tutorial application.

   Figure 13-1 Selection Menu

   ---

   
2. Choose an entry from the selection menu either by name or by number. For example, to select the ADD task, type either ADD or 1 at the Selection prompt and then press [Return].
   When you select a task, the form for that task appears on your screen. For example, when you select the ADD task, the form for filling in employee information appears. When you finish filling in the form, press [Ctrl/Z] to save the information in your RMS master file. To leave the form without saving the information, press [PF4].
   After you complete a task (by pressing [Ctrl/Z] or [PF4] ), ACMS redisplays the selection menu and waits for you to select another task or exit from ACMS.
   Before exiting from ACMS, you may wish to try several ADD tasks and several UPDATE tasks. You may also wish to try adding an employee number that already exists in your RMS master file so that you can see how the application responds to a duplicate-record error. Also, if you create two OpenVMS processes and run this application in each of them, you can test how the application responds when two users try to update the same employee record at the same time. (The last user to save the modifications receives a message that the record has been changed since he or she began updating it.)
3. To exit from ACMS, type EXIT at the Selection prompt and press [Return].

You have now run your application and seen the results of choosing either the data entry task or the inquiry/update task. It is often helpful, especially in problem-solving, to know the various steps that ACMS takes to run one of these tasks. This information is available in Appendix A.

Appendix A also describes how to access various utilities that can help you solve problems that may occur when you run an ACMS application. These utilities include:

• Audit Trail Report (ATR), for a record of when applications start and stop
• Software Event Log (SWL), for a record of internal software errors
• DECforms trace facility, for a record of the form processing that occurs when the ACMS application calls a DECforms request
• ACMS Help, for information about ACMS error messages