# Compaq ACMS for OpenVMS
Managing Applications

Previous | Contents | Index

# ACMS/START APPLICATION Command

> Starts one or more ACMS applications.

## Format

> ACMS/START APPLICATION application-name[,...]

## Privileges Required

> OpenVMS OPER privilege

## Parameters

> ### application-name

> The file name of the application you want to start. Specify only the file name of the application database file; do not include device, directory, or file type. You must specify at least one application name. Specify more than one application name by separating each name with a comma (,).

## Notes

> The ACMS system must be started before you use the ACMS/START APPLICATION command. Specify the ACMS/START SYSTEM command to start ACMS.

> Before you use the ACMS/START APPLICATION command, ACMS$DIRECTORY must be defined in SYS$MANAGER:SYSTARTUP_VMS.COM as a system logical name pointing to the directory that contains the application database files. When you start applications, application database files must reside in ACMS$DIRECTORY.

> Note For sites that have modularized their startup procedures, be sure you add the lines to the correct file. The default startup command file for OpenVMS VAX Version 5.n is SYS$MANAGER:SYSTARTUP_V5.COM; for OpenVMS VAX Version 6.n and OpenVMS Alpha, it is SYSTARTUP_VMS.COM.

> The ACMS/START APPLICATION command can stall when you start an application if both of the following conditions are present:

> - The application is defined with minimum server processes greater than zero.
> - A server cannot start. This usually indicates a problem in the initialization procedure, such as an infinite loop in the program.

> If these conditions are present, ACMS displays the following messages:

>     %ACMSOPR-E-STRTAPLERR, Error while attempting to START APPLICATION application-name

>     -ACMSOPS-W-TIMEOUT, Timed out waiting for reply from ACMS component

>     %ACMSOPR-E-ERROR, Some operations may not have been performed

> Use the ACMS/SHOW SYSTEM command to find the process ID (PID) for the Application Execution Controller or the PID of the hanging server process. ACMS/SHOW SYSTEM displays the PID that you can use in the following command to recover from the error:

>     $ STOP/ID=<pid>

> If the ACMS/START APPLICATION command fails and the Software Event Log (SWL) report indicates an "exceeded quota" error for the EXC, the quota for the buffered I/O byte count limit (BYTLM) is probably not set properly. Increase this quota for the user name of the application, and try the command again. Refer to Chapter 10 for information about setting the proper quota limit for BYTLM.

## Example

    $ ACMS/START APPLICATION PERSONNEL, DEPARTMENT

> This command starts the PERSONNEL and DEPARTMENT applications.

# ACMS/START QTI Command

> Starts the QTI.

## Format

> ACMS/START QTI

## Privileges Required

> OpenVMS OPER privilege

## Notes

> You must start ACMS before you can use the ACMS/START QTI command.

> You must start The QTI must be started before queues can be started. You can also start the QTI by specifying the ACMS/START SYSTEM command with the /QTI qualifier.

> Stop the QTI by using the ACMS/STOP QTI command.

## Example

    $ ACMS/START QTI

> This example starts the QTI.

# ACMS/START QUEUE Command

> Starts the task queue you specify. Once you start a task queue, the QTI begins processing any queued task elements in the queue.

## Format

> ACMS/START QUEUE queue-name[,...]

> Command Qualifiers | Defaults
> --- | ---
> /ERROR_QUEUE=error-queue-name | No error queue
> /TASK_THREADS=n | /TASK_THREADS=1

## Required Privileges

> OpenVMS OPER privilege

## Parameters

> ### queue-name

> The name of a task queue created by the ACMS Queue Manager (ACMSQUEMGR). You must supply at least one queue name. Specify more than one queue name by separating each name with a comma (,).

## Qualifiers

> ### /ERROR_QUEUE=error-queue-name

> Specifies the error queue for a task queue. If you specify this qualifier, queued tasks that do not complete successfully are placed on the specified error queue. Any errors are recorded in the Audit Trail Logger.

> The /ERROR_QUEUE qualifier is a positional qualifier. If you specify the /ERROR_QUEUE qualifier between the ACMS/START QUEUE command and the queue names, all queue names are affected. If you specify the ACMS/START QUEUE command after a queue name, only that queue name is affected.

> If you do not specify the /ERROR_QUEUE qualifier, no error queue is associated with the task queue. When an error occurs, the task is deleted from the queue.

> ### /TASK_THREADS=n

> Specifies the number of concurrent outstanding tasks that the QTI processes for a queue. Here, n indicates a value from 1 through 256.

> The /TASK_THREADS qualifier is a positional qualifier. If you position the /TASK_THREADS qualifier between the ACMS/START QUEUE command and the queue names, all queue names are affected. To have the /TASK_THREADS qualifier apply to an individual queue name in a list of queue names, place the qualifier directly after the queue name. See the examples section.

> The default is /TASK_THREADS=1.

## Notes

> The error queue you specify with the /ERROR_QUEUE qualifier must exist. You create an error queue with the ACMSQUEMGR Utility. See Chapter 5 for information on the ACMSQUEMGR.

> You can queue tasks to a queue and remove tasks from a queue using ACMS Queued Task Services even though a queue is not started.

## Examples

#1
    $ ACMS/START QUEUE ACCTS_QUE

> This example starts the ACMS task queue ACCTS_QUE.

#2
    $ ACMS/START QUEUE MAWAH_QUE/ERROR_QUEUE=W_ERROR, MY_QUE -
    _$ /ERROR_QUEUE=M_ERROR

> This example starts the task queues MAHWAH_QUE and MY_QUE and any tasks in these queues. If any tasks in MAHWAH_QUE do not complete normally, they are placed on the error queue W_ERROR. If any tasks in MY_QUE do not complete normally, they are placed on the error queue M_ERROR.

#3
    $ ACMS/START QUEUE PARTS_QUE, FAST_QUE /TASK_THREADS=5

> This example starts the task queues PARTS_QUE and FAST_QUE. The maximum number of concurrent outstanding tasks for PARTS_QUE is set to the default value. For FAST_QUE, the maximum number of concurrent outstanding tasks is set to 5.

# ACMS/START SYSTEM Command

> Starts the ACMS system.

## Format

> ACMS/START SYSTEM

> Command Qualifiers | Defaults
> --- | ---
> /[NO]AUDIT | /AUDIT
> /[NO]QTI | /NOQTI
> /[NO]TERMINALS | /TERMINALS

## Privileges Required

> OpenVMS OPER privilege

## Qualifiers

> ### /[NO]AUDIT

> The /AUDIT qualifier starts ACMS with audit trail logging enabled. The /AUDIT qualifier is the default. After you start ACMS, you can control the Audit Trail Logger with the ACMS/SET SYSTEM and ACMS/RESET TERMINALS commands.

> ### /[NO]QTI

> The /QTI qualifier starts the QTI when ACMS is started. Once the QTI is started, you can start one or more queues with the ACMS/START QUEUE command. If you specify the /NOQTI qualifier, the QTI is not started with ACMS. The /NOQTI qualifier is the default.

> ### /[NO]TERMINALS

> The /TERMINALS qualifier starts the TSC when ACMS is started. The /TERMINALS qualifier is the default. If you specify the /NOTERMINALS qualifier, the TSC is not started with ACMS. If you specify /NOTERMINALS, you can start the TSC at a later time with the ACMS/START TERMINALS command.

## Notes

> Include the ACMS/START SYSTEM and ACMS/START APPLICATION commands in your OpenVMS site-specific startup file (SYS$MANAGER:SYSTARTUP_VMS.COM) to start ACMS and ACMS applications automatically when OpenVMS starts.

> Note For sites that have modularized their startup procedures, be sure you add the lines to the correct file. The default startup command file for OpenVMS VAX Version 5.n is SYS$MANAGER:SYSTARTUP_V5.COM; for OpenVMS VAX Version 6.n and OpenVMS Alpha, it is SYSTARTUP_VMS.COM.

> When you start the TSC with the ACMS/START SYSTEM command, recently assigned terminal sign-in characteristics defined by the DDU take effect.

> If you do not start the QTI when you start ACMS, you can specify the ACMS/START QTI command to start the QTI at a later time.

## Examples

#1
    $ ACMS/START SYSTEM/NOTERMINALS
    $ ACMS/START APPLICATION PERSONNEL,DEPARTMENT
    $ ACMS/START TERMINALS

> The first command starts ACMS without starting the TSC. At this point, users cannot sign in to ACMS. The second command starts the PERSONNEL and DEPARTMENT applications. The third command starts the TSC so users can sign in to ACMS and select tasks in the PERSONNEL or DEPARTMENT applications.

#2
    $ ACMS/START SYSTEM/QTI
    $ ACMS/START APPLICATION PERSONNEL,DEPARTMENT

> These commands are part of a command file for starting ACMS and ACMS applications. When you run the command file, the first command starts ACMS, the QTI, and the TSC. The second command starts the PERSONNEL and DEPARTMENT applications, so users can select tasks in those applications.

# ACMS/START TASK Command

> Starts a detached task in the specified application.

## Format

> ACMS/START TASK task-name application-name

Command Qualifiers | Defaults
--- | ---
/[NO]LOG | /NOLOG
/[NO]RETRY_LIMIT[=n] | /RETRY_LIMIT=0
/SELECTION_STRING=selection-string | Null string
/USERNAME=user-name | User name of application
/WAIT_TIMER=n | /WAIT_TIMER=5 seconds

## Privileges Required

> OpenVMS OPER and SYSPRV privileges

## Parameters

> ### task-name

> The name of the task that you want to start as a detached task. The task must contain no exchange steps and you must define the task with the NO I/O phrase. The task name must exist in the application specified by the application-name parameter.

> ### application-name

> Specifies the file name of the application in which the detached task executes. Specify only the file name of an application database file; do not include a device, directory, or file type.

## Qualifiers

> ### /[NO]LOG

> Controls whether or not ACMS displays a message after the detached task has been successfully started. The /NOLOG qualifier is the default.

> ### /[NO]RETRY_LIMIT[=n]

> Specifies the maximum number of times ACMS retries the task after a failure. Specifying /NORETRY_LIMIT indicates that ACMS always retries after a failure. The /RETRY_LIMIT=0 qualifier is the default, which directs ACMS to never retry the task after a failure.

> ### /SELECTION_STRING=selection-string

> Specifies the data to be passed to the ACMS$SELECTION_STRING system workspace in a task. The default is to pass a null string to the ACMS$SELECTION_STRING system workspace.

> ### /USERNAME=user-name

> Specifies the submitter user name under which the detached task is signed in. The default is the OpenVMS user name under which the Application Execution Controller (EXC) executes. If you specify an OpenVMS user name that is different than the EXC user name, the user name must be identified as an agent in the ACMS user definition file.

> ### /WAIT_TIMER=n

> Specifies the number of seconds ACMS waits before retrying the task after a task failure. The /WAIT_TIMER=5 is the default; the minimum value is 1 and the maximum value is 65,535 seconds.

## Notes

> The ACMS/START TASK operator command completes when the detached task has started successfully, or if it fails to start. If the detached task fails immediately after the task starts executing, the failure is not reported by the ACMS/START TASK operator command, because the ACMS Operator Utility does not wait for the task to complete.

> Before starting a detached task, you must start the application associated with the task. A user is signed in when starting a detached task. As a result, a set of license units is consumed, if the ACMS system has a loaded concurrent-user license.

> The submitter user name under which a detached task is signed in must have an entry in the ACMSUDF.DAT file with the /AGENT qualifier. The user name is either the user name specified with the /USERNAME qualifer of the ACMS/START TASK operator command or the default EXC user name of the application.

## Example

    $ ACMS/START TASK dequeue_task dist_appl -
    _$ /RETRY_LIMIT=10/WAIT_TIMER=30/USERNAME=SMITH

> This command starts the detached task, called dequeue_task, in the application dist_appl. The task can be retried a maximum of 10 times after task failures, and ACMS waits 30 seconds before it retries the task. The task is submitted with the user name SMITH.

# ACMS/START TERMINALS Command

> Starts the TSC when ACMS is running. The ACMS/START TERMINALS command enables terminal users to access ACMS menus.

## Format

> ACMS/START TERMINALS

## Privileges Required

> OpenVMS OPER privilege

## Notes

> You cannot start the TSC unless ACMS is active. Users cannot sign in to ACMS unless the TSC is started.

> Use this command to start the TSC after specifying the /NOTERMINALS qualifier when you started ACMS, or to restart the TSC after stopping it with the ACMS/STOP TERMINALS command.

> When you start the TSC, recently assigned terminal sign-in characteristics defined by the DDU take effect. Starting the TSC also authorizes any new terminals added since the last time the TSC was started and releases any that are no longer authorized.

> The ACMS/START TERMINALS only allows terminal users on the local system to access the ACMS menus. It does not affect whether or not remote users can access applications on the local system or whether or not users using other task submitting agents, such as ALL-IN-1, can select ACMS tasks.

## Examples

#1
    $ ACMS/START TERMINALS

> This command starts or restarts the TSC. Users can then sign in to ACMS.

#2
    $ ACMS/START SYSTEM/QTI/NOTERMINALS
    $ ACMS/START APPLICATION DEPARTMENT,PERSONNEL
    $ ACMS/START TERMINALS

> This series of commands starts ACMS and the QTI, starts ACMS applications, and starts the TSC, respectively. The ACMS/START TERMINALS command starts the TSC separately from ACMS so users cannot sign in until applications are active.

# ACMS/STOP APPLICATION Command

> Stops one or more ACMS applications.

## Format

> ACMS/STOP APPLICATION application-name[,...]

> Command Qualifier | Default
> --- | ---
> /[NO]CANCEL | /NOCANCEL

## Privileges Required

> OpenVMS OPER privilege

## Parameters

> ### application-name

> The name of the application that you want to stop. Specify only an application name; do not include device, directory, or file type. You must specify at least one application name. Specify more than one application name by separating each name with a comma (,).

## Qualifiers

> ### /[NO]CANCEL

> The /CANCEL qualifier cancels an active task in the application you are stopping. If you use the /NOCANCEL qualifier, ACMS waits until all active tasks stop before stopping the application. The /NOCANCEL qualifier is the default.

## Notes

> Once you specify the ACMS/STOP APPLICATION command, no new tasks can be started.

> The ACMS/STOP APPLICATION command executes only when there are no tasks active in the application you specify. If there are active tasks in the application you want to stop, use the DCL REPLY command to ask users to halt or complete the tasks and then sign out. You can then use the /CANCEL qualifier to stop any tasks that remain active. Restart applications by specifying the ACMS/START APPLICATION command.

> See the OpenVMS DCL Dictionary for information about the DCL REPLY command.

## Examples

#1
    $ ACMS/STOP APPLICATION DEPARTMENT/CANCEL

> This command cancels any active tasks in the application DEPARTMENT and stops the application. Terminal users cannot select and run tasks in the application DEPARTMENT.

#2
    $ ACMS/STOP APPLICATION PERSONNEL,DEPARTMENT/CANCEL

> This command cancels any active tasks in the PERSONNEL and DEPARTMENT applications and stops the applications. Terminal users cannot select and run tasks in these applications.

# ACMS/STOP QTI Command

> Stops the QTI and all active task queues.

## Format

> ACMS/STOP QTI

> Command Qualifier | Default
> --- | ---
> /[NO]CANCEL | /NOCANCEL

## Required Privileges

> OpenVMS OPER privilege

## Qualifiers

> ### /[NO]CANCEL

> The /CANCEL qualifier cancels all active tasks in all active queues. If you use the /NOCANCEL qualifier, ACMS waits until all active tasks stop before stopping the QTI and task queues. The /NOCANCEL qualifier is the default.

## Notes

> Restart a queue by using the ACMS/START QTI and ACMS/START QUEUE commands.

## Example

    $ ACMS/STOP QTI

> This command stops the QTI and all active queues.

# ACMS/STOP QUEUE Command

> Stops the specified task queue.

## Format

> ACMS/STOP QUEUE queue-name[,...]

> Command Qualifier | Default
> --- | ---
> /[NO]CANCEL | /NOCANCEL

## Required Privileges

> OpenVMS OPER privilege

## Parameters

> ### queue-name

> The name of the task queue you want to stop. You must specify at least one queue name. Stop more than one queue by separating the queue names with a comma (,).

## Qualifiers

> ### /[NO]CANCEL

> The /CANCEL qualifier cancels all active tasks in the queue you are stopping. If you use the /NOCANCEL qualifier, ACMS waits until all active tasks complete before stopping the queue. The /NOCANCEL qualifier is the default.

## Notes

> When you specify the ACMS/STOP QUEUE command, the specified task queue is stopped by the QTI.

> Even though a task queue is stopped, queued task elements can still be initiated to the queue.

## Example

    $ ACMS/STOP QUEUE ALAS_QUE, ALACK_QUE

> This command stops the task queues ALAS_QUE and ALACK_QUE.

Previous | Next | Contents | Index