This chapter describes how to use ACMS operator commands to:

• Start and stop the ACMS system
• Control the Terminal Subsystem Controller (TSC)
• Control operator terminals
• Control the Queued Task Initiator (QTI)
• Start and stop ACMS task queues
• Cancel ACMS users

See Section 8.9 for a summary of ACMS operator commands. For reference information about the operator commands described in this chapter, see Chapter 21.

8.1 Starting the ACMS System

This section describes how to start the ACMS system automatically and interactively. For a complete list of quotas, privileges, and SYSGEN parameters required by ACMS processes, see Chapter 10.

Before you start ACMS for the first time, use the OpenVMS Authorize Utility to make sure that the user names assigned to the following processes are authorized OpenVMS user names with sufficient privileges and quotas:

• ACMS Central Controller (ACC)
• Terminal Subsystem Controller (TSC)
• Command Process (CP)
• Application Execution Controller (EXC)
• Queued Task Initiator (QTI)

If these processes are not authorized, use the OpenVMS Authorize Utility to set up accounts for the user names and then use the ACMS User Definition Utility (UDU) to authorize the user names. The CP and QTI process user names need to be authorized as agents in the UDU authorization file. See Chapter 3 for information about authorizing these processes as agents.

See Chapter 10 for information on setting privileges and quotas for ACMS process user names. See Chapter 3 for information on authorizing ACMS process user names.

After starting ACMS, check the state of the system by using the ACMS/SHOW SYSTEM command as described in Section 8.3. If the ACMS system or applications did not start, use the Software Event Logger Utility Program (SWLUP) and the Audit Trail Report (ATR) Utility for reports of system errors.

8.1.1 Starting ACMS Automatically

In most cases, you want to start ACMS automatically whenever the OpenVMS system starts. Start the ACMS system automatically when you bring up OpenVMS by editing your site-specific system startup file, SYS$MANAGER:SYSTARTUP_VMS.COM.

The following steps describe how to edit SYSTARTUP_VMS.COM and include operator commands to start up the ACMS system.

1. Include the command that invokes the ACMS startup file, ACMSTART.COM, in your OpenVMS system startup file. Position this new command line after the line that invokes the network startup command procedure and, if TDMS is installed on your system, after the command that invokes TDMS. For example:

   $ @SYS$MANAGER:STARTNET.COM . . . $ @SYS$MANAGER:TDMSTRTUP.COM . . . $ @SYS$STARTUP:ACMSTART.COM

   
   It is important that the network be started before ACMS is started.

2. For distributed ACMS applications, run the ACMS startup files by including these pointers in your OpenVMS startup file:

   $ @STARTNET.COM ! or SUBMIT STARTNET.COM $ @ACMSTART.COM ! or SUBMIT ACMSTART.COM

3. Include the ACMS/START SYSTEM /QTI operator command to start the ACMS system and the ACMS QTI:

   $ ACMS/START SYSTEM /QTI

   
   At this point, you can also include the ACMS operator commands to enable operator terminals and start ACMS applications. For example:

   $ ACMS/SET SYSTEM /OPERATOR /TERMINAL=(OPA0:) $ ACMS/START APPLICATION DEPARTMENT,INVENTORY

Even if you start ACMS automatically, you can still use ACMS commands to start and stop interactively the ACMS system, ACMS applications, and ACMS components.

Instead of editing SYSTARTUP_VMS.COM and adding the commands in step 2 and step 3 manually, you can invoke the postinstallation command procedure ACMS_POST_INSTALL.COM to define your system's startup options. However, even if you do run ACMS_POST_INSTALL.COM, you need to add the commands described in step 1 to invoke the ACMS startup file ACMSTART.COM.

To run ACMS_POST_INSTALL.COM, set your default to SYS$MANAGER and enter the following command:

$ @ACMS_POST_INSTALL.COM

ACMS_POST_INSTALL.COM creates the command file ACMS_SETUP.COM which defines ACMS logicals and executes ACMS startup commands each time your system boots. ACMS_POST_INSTALL.COM can also be used to install the ACMS utility images as shared images and to start ACMS applications.

8.1.2 Starting ACMS Interactively

Start ACMS interactively by using the ACMS/START SYSTEM command:

$ ACMS/START SYSTEM

Once you enter the ACMS/START SYSTEM command, the ACMS ACC (the main control point of the ACMS system) and the ACMS TSC are started. The ACC must be active before you can start an application. The TSC must be active before users can sign in to ACMS and use an application.

When you start the TSC, ACMS allocates any terminal that is currently free. Before you start ACMS, make sure that ACMS-controlled terminals are not being used by OpenVMS users. If users are logged in to OpenVMS, ACMS cannot allocate their terminals as ACMS-controlled terminals. ACMS lists the terminals it cannot allocate in the Audit Trail Log.

Prevent new users from signing in while you are starting ACMS by specifying the /NOTERMINALS qualifier with the ACMS/START SYSTEM command. The /NOTERMINALS qualifier delays sign-ins by not starting the TSC. Once you have started ACMS, you can start the TSC separately by using the ACMS/START TERMINALS command. See Section 8.4 for more information about stopping and starting the TSC.

When you start the ACMS system, you also have the option of starting the ACMS Queued Task Initiator (QTI). To start the QTI, use the /QTI qualifier with the ACMS/START SYSTEM command. For example:

$ ACMS/START SYSTEM/QTI

Once you start the QTI you can start ACMS task queues. See Section 8.7.1 for more information about starting task queues.

8.2 Stopping the ACMS System

Stop the ACMS system automatically by editing and then executing the SYS$MANAGER:SYSHUTDWN.COM command file, or interactively by using the ACMS/STOP SYSTEM command.

8.2.1 Stopping ACMS Automatically

To stop ACMS automatically, include the following command in your OpenVMS site-specific shutdown file SYS$MANAGER:SYSHUTDWN.COM:

$ ACMS/STOP SYSTEM/CANCEL $ @SYS$STARTUP:ACMSTOP.COM

The first command shuts down the ACMS system, including all applications, the TSC, and the QTI. The /CANCEL qualifier cancels all tasks running in applications or being executed by the QTI. Including the ACMS/STOP SYSTEM/CANCEL command in the system shutdown file ensures that the ACMS system processes are properly run down. If you omit the /CANCEL qualifier and there are active tasks, the ACMS/STOP SYSTEM command does not execute until all tasks stop or until the command times out after five minutes. (Tasks are not canceled when the the ACMS/STOP command times out.)

The second command line invokes the command procedure ACMSTOP.COM. ACMSTOP.COM is a shutdown command file for ACMS. It deinstalls ACMS images (using the OpenVMS Install Utility) and deassigns the logical ACMS$EXAMPLES.

8.2.2 Stopping ACMS Interactively

You can use the ACMS/STOP SYSTEM command interactively or from a command file to stop ACMS without stopping OpenVMS, but you must first stop all active tasks. Otherwise, ACMS waits for the tasks to complete before executing the ACMS/STOP SYSTEM command. If tasks do not complete within five minutes, the command is ignored and ACMS returns you to the DCL prompt.

You can cancel all tasks and stop the ACMS system simultaneously by using the /CANCEL qualifier with the ACMS/STOP SYSTEM command. The following command cancels all active tasks and stops ACMS applications, the TSC, and the ACMS system software:

$ ACMS/STOP SYSTEM/CANCEL

As a courtesy to users, use the DCL REPLY command to ask users to finish their tasks and sign out before issuing this command.

If you interrupt the ACMS/STOP SYSTEM command by pressing [Ctrl/Y], the ACMS system may not shut down properly. Issuing subsequent ACMS/STOP SYSTEM commands can cause the error "message truncation" to occur. If you receive this error, shut down the ACMS system by specifying the DCL command STOP to halt the ACC. Then, use the ACMS/STOP SYSTEM command to stop any remaining ACMS processes.

8.3 Displaying System Information

The ACMS/SHOW SYSTEM command provides you with the following information:

1. The state of the system. The four ACMS system states are:
   • Starting
   • Started
   • Stopping
   • Stopped
   
   While an ACMS/START SYSTEM command is processing, ACMS is in the starting state. When the command is through processing, ACMS is in a started state. While an ACMS/STOP SYSTEM command is processing, ACMS is in the stopping state. When the ACMS/STOP SYSTEM command is finished processing, ACMS is in a stopped state.
2. Users currently signed in to the system. Information about each user includes:
   • OpenVMS user name
   • Task submitter identification code assigned at sign-in
   • OpenVMS process identification for the Command Process or agent handling the user's terminal
   • Device name for the user's terminal
3. Active Application Execution Controllers. Information about the EXCs includes:
   • The names of all active applications
   • OpenVMS process information for all active applications

Example 8-1 shows the output from the ACMS/SHOW SYSTEM command. To get information about system activity over a period of time, such as the number of sign-ins in the last hour, you can use the ATR Utility, which is described in Chapter 12.

Example 8-1 ACMS/SHOW SYSTEM Command

$ ACMS/SHOW SYSTEM (1) ACMS V4.0 Current System State: STARTED Time: 1-MAY-1994 13:34:35.28 (2) Terminal Subsystem State: STARTED (3) Queued Task Initiator State: STOPPED (4) System Auditing State: ENABLED (5) Active ACMS Users User Name Submitter ID Agent PID Device JONES ALLDAY::0001000D 22000122 TTB1: ROBINSON ALLDAY::00020013 22000122 TTH0: (6) Active Execution Controllers Application Name Process Name EXC PID DEPARTMENT ACMS01EXC001000 00610046 MARKETING ACMS01EXC003000 2200047C

The following is a description of the numbered items in Example 8-1.

1. System state
   Current system state
2. Terminal Subsystem State
   Current state of the TSC
3. Queued Task Initiator State
   Current state of the QTI
4. System Auditing State
   Whether system auditing is enabled or disabled
5. Active ACMS Users
   Information about all active users
6. Active Execution Controllers
   Information about all active EXCs

You can specify the /POOL qualifier with the ACMS/SHOW SYSTEM command to display pool information for the system. When you specify the /POOL qualifier, information about current users and active EXCs is not displayed. Example 8-2 shows the pool information displayed with the ACMS/SHOW SYSTEM/POOL command.

Example 8-2 ACMS/SHOW SYSTEM/POOL Command

$ ACMS/SHOW SYSTEM/POOL ACMS V4.0 Current System State: STARTED Time: 1-MAY-1994 11:20:49.66 Terminal Subsystem State: STARTED Queued Task Initiator State: STOPPED System Auditing State: ENABLED ACMS System Message Switch Pools (1) (2) (3) (4) (5) (6) Process Pool Free (pct) Largest Allocation Garbage name size bytes block failures collections < Shared Pool > 262144 228056 (86%) 65536 0 0 ACMS01ACC001000 131072 121168 (92%) 65536 0 0 ACMS01ATL001000 131072 127024 (96%) 65536 0 0 ACMS01TSC001000 131072 126544 (96%) 65536 0 0 ACMS01CP001000 131072 123824 (94%) 65536 0 0 ACMS01EXC008000 131072 123312 (94%) 65536 0 0 ACMS008SP001000 131072 125552 (95%) 65536 0 0 ACMS008SP002013 131072 126704 (96%) 65536 0 0

The following is a description of the numbered items in Example 8-2:

1. Process name
   The process name for which message switch pool information is shown. The pool shared by all processes is shown with the name <Shared Pool>.
2. Pool size
   The total size of the pool, in bytes.
3. Free bytes
   The number of free bytes of pool space available and the percentage available.
4. Largest block
   The size of the largest block of free pool space, in bytes.
5. Allocation failures
   The number of times ACMS attempted and failed to allocate pool space.

6. Garbage collections
   The number of times ACMS attempted to use fragmented pool space.

The Terminal Subsystem Controller (TSC) controls which terminals can sign in to ACMS. It also allocates any ACMS-controlled terminals. Before terminal users can sign in to ACMS and use an application, the Terminal Subsystem Controller must be active.

8.4.1 Starting the TSC

Start the TSC either at the same time you start the ACMS system (as described in Section 8.1.2), or after you start the ACMS system and some ACMS applications. If the TSC is not started, users cannot sign in to ACMS. You can start the TSC separately from the ACMS system by issuing the ACMS/START TERMINALS command.

The following sequence of commands starts the ACMS system without starting the TSC, thus disabling sign-ins. The ACMS/START APPLICATION command starts the applications INVENTORY and ACCOUNTING. After the applications are started, the ACMS/START TERMINALS command starts the ACMS TSC. Users can then sign in to ACMS.

$ ACMS/START SYSTEM/NOTERMINALS $ ACMS/START APPLICATION INVENTORY,ACCOUNTING $ ACMS/START TERMINALS

You can start the TSC only when ACMS is active. When you start the TSC, make sure users are not signed in at terminals you have defined to sign in directly to ACMS. If users are signed in at the designated terminals, the terminals cannot be controlled by ACMS. ACMS lists the terminals it cannot control in the Audit Trail Log. Once the users sign out, use the ACMS/RESET TERMINALS command to control the terminals.

8.4.2 Stopping the TSC

The ACMS/STOP TERMINALS command stops the TSC, canceling active tasks and signing users out of ACMS. Until you restart the TSC, users cannot sign in to ACMS. When the TSC is stopped, ACMS-controlled terminals are released. You might want to stop the TSC if you need to keep users from signing in to ACMS or if you need to stop all ACMS activity by users.

The following is an example of the ACMS/STOP TERMINALS command:

$ ACMS/STOP TERMINALS

Before you stop the TSC, use the DCL REPLY command to ask users to finish their tasks and sign out. Then, use the ACMS/SHOW TASKS command to check that tasks have stopped.

8.5 Operator Terminals

ACMS sends status messages and other operational messages to terminals that you define as ACMS operator terminals. Terminals that you define as operator terminals receive messages if an application, the Audit Trail Log, or the TSC stop unexpectedly. An ACMS operator terminal can also be an OpenVMS operator terminal. ACMS also logs status and operational messages in the Software Event Log (SWL) file (see Chapter 13).

8.5.1 Enabling Operator Terminals

Once you start the ACMS system, you can specify the ACMS/SET SYSTEM command with the /OPERATOR qualifier to enable ACMS operator terminals. Either place the ACMS/SET SYSTEM/OPERATOR command in your SYS$MANAGER:SYSTARTUP_VMS.COM file, or use the command interactively.

When you use the /OPERATOR qualifier, you must also use either the /PROCESS or the /TERMINAL qualifier. The /PROCESS qualifier enables your terminal as an ACMS operator terminal for the duration of your process, until ACMS stops, or until you disable the terminal. The /TERMINAL qualifier enables one or more terminals as ACMS operator terminals until ACMS stops or until you disable the terminals.

The following command enables terminals TTE1 and TTE2 as operator terminals:

$ ACMS/SET SYSTEM/OPERATOR/TERMINAL=(TTE1,TTE2)

When you specify more than one device name with the /TERMINAL qualifier, separate the device names with commas and enclose them in parentheses. Specify a terminal with the /TERMINAL qualifier even if no one is logged in at that terminal.

You can determine which terminals are authorized as ACMS operator terminals by looking at the Audit Trail Log. For each terminal enabled as an operator terminal, the Audit Trail Log contains the entry, "Successful permanent operator enabled", and shows the device name. See Chapter 12 in this manual for more information about the ACMS Audit Trail Log.

8.5.2 Disabling Operator Terminals

To disable ACMS operator terminals, use the ACMS/SET SYSTEM command with the /NOOPERATOR qualifier. When you specify the /NOOPERATOR qualifier, you must also specify either the /PROCESS or the /TERMINAL qualifier. The /PROCESS qualifier disables your own terminal. The /TERMINAL qualifier identifies the terminal to be disabled.

The following command disables your own terminal:

$ ACMS/SET SYSTEM/NOOPERATOR/PROCESS

This command disables the TTE1 and TTE2 terminals:

$ ACMS/SET SYSTEM/NOOPERATOR/TERMINAL=(TTE1,TTE2)

For each terminal disabled as an operator terminal, the Audit Trail Log contains the entry, "Successful permanent operator disabled" and shows the device name. See Chapter 12 in this manual for more information about the ACMS Audit Trail Log.