# Compaq ACMS for OpenVMS
Managing Applications

Previous | Contents | Index

# 9.6 Modifying Active Applications

Use the ACMS/MODIFY APPLICATION command to modify the application, task, or server attributes of an active application. The attributes you modify are not permanent. If you want a modification to be permanent, you must modify the application definition.

## 9.6.1 Modifying Application Attributes

Specify the ACMS/MODIFY APPLICATION command with the /APPLICATION_ATTRIBUTES qualifier to modify the attributes of an active application. Keywords to the /APPLICATION_ATTRIBUTES qualifier specify the application attribute you want to modify. For example, the MAX_PROCESS keyword in the following example sets the maximum number of server processes allowed in application AIR_REGISTER to 5:

    $ ACMS/MODIFY APPLICATION AIR_REGISTER -
    _$ /APPLICATION_ATTRIBUTES=MAX_PROCESS=5
    Apply Modifications to Application AIR_REGISTER (Y/[N]):

Use keywords to the /APPLICATION_ATTRIBUTES qualifier to:

- Enable or disable application-level auditing.
- Specify the maximum number of tasks that can execute simultaneously in an application.
- Specify the maximum number of server processes that can be active simultaneously in an application.
- Specify the interval at which ACMS monitors server processes in an application.

When application-level auditing is enabled, the Audit Trail Logger records any application modifications you make in the Audit Trail Log. See Chapter 12 for an example of an audit trail record for a modified application.

To display the currently defined attributes for an application, specify the ACMS/SHOW APPLICATION command. Section 9.5.1 describes the ACMS/SHOW APPLICATION command and provides some sample output.

## 9.6.2 Modifying Server Attributes

Use the ACMS/MODIFY APPLICATION command with the /SERVER_ATTRIBUTES qualifier to modify the attributes of a server in an application. Keywords to the /SERVER_ATTRIBUTES qualifier specify the server attributes you want to modify.

You can modify the attributes of a particular server in an application, the attributes of all servers in an application, or, if you do not specify an application name, the attributes of all servers in all applications. For example, the NAME and PROCESS_DUMPS keywords in the following example cause ACMS to enable server process dumps for server MYSERV in application SANDAPPL:

    $ ACMS/MODIFY APPLICATION SANDAPPL -
    _$ /SERVER_ATTRIBUTES=(NAME=MYSERV,PROCESS_DUMPS)
    Apply Modifications to Application SANDAPPL  (Y/[N]):

Use keywords to the /SERVER_ATTRIBUTES qualifier to:

- Enable or disable server-level auditing in an application.
- Specify the interval or delay time ACMS waits before creating new server processes.
- Specify the interval or delay time ACMS waits before deleting free server processes.
- Enable or disable server process dumps for an application.
- Specify the maximum number of server processes allowed for an application.
- Specify the minimum number of server processes allowed for an application.

Display currently defined server attributes for an application by specifying the ACMS/SHOW APPLICATION/SERVER_ATTRIBUTES command.

When application-level auditing is enabled, the Audit Trail Logger records the modification in the Audit Trail Log file. See Chapter 12 for an example of an audit trail record generated by the ACMS/MODIFY APPLICATION command.

## 9.6.3 Modifying Task Attributes

The ACMS/MODIFY APPLICATION command with the /TASK_ATTRIBUTES qualifier modifies the attributes of tasks in an application. In the following example, the AUDIT keyword to the /TASK_ATTRIBUTES qualifier enables task-level auditing for all tasks in the application PARTS:

    $ ACMS/MODIFY APPLICATION PARTS/TASK_ATTRIBUTES=AUDIT
    Apply Modifications to Application PARTS (Y/[N]):

Modify the attributes of a specific task or tasks in an application by specifying the keyword NAME with the /TASK_ATTRIBUTES qualifier. The following command, for instance, disables tasks BI_MONTHLY and YEARLY in the application PARTS:

    $ ACMS/MODIFY APPLICATION PARTS -
    _$ /TASK_ATTRIBUTES=(NAME=(BI_MONTHLY,YEARLY),DISABLE)
    Apply Modifications to Application PARTS (Y/[N]):

Use keywords to the /TASK_ATTRIBUTES qualifier to:

- Name a task or tasks whose attributes you wish to modify.
- Enable or disable task-level auditing in an application.
- Enable or disable specific tasks in an application.
- Set a transaction timeout interval or disable transaction timeout for a task or tasks.

If you do not specify a task name or names, all tasks are modified within the selected application with whatever attributes you specify.

When application-level auditing is enabled and you modify the attributes of a task, the modifications are recorded in the Audit Trail Log.

# 9.7 Replacing a Server Image

Use the ACMS/REPLACE SERVER command to replace a server image in an active application with a new version of that image. Application availability and task execution are not affected by the server replacement. The ACMS/REPLACE SERVER command allows the application manager to dynamically make code changes to the code executed by a procedure server. The application manager can make code changes, relink the server image, place the server image in the location specified by the SERVER IMAGE IS statement in the task group definition, and issue the ACMS/REPLACE SERVER command.

The following command, for example, replaces the server image SORT_IMAGE with a new version of that image in the application RULES_REGS. The name of the server image is defined in the application definition.

    $ ACMS/REPLACE SERVER SORT_IMAGE/APPLICATION=RULES_REGS
    Replace Server SORT_IMAGE in Application RULES_REGS (Y/[N]):

When the application controller receives the ACMS/REPLACE SERVER command, it runs down all free server processes for the specified server and requests all active servers to run down when they are free. A server retaining context does not run down until the context has been released. New server processes are created to meet the minimum and maximum server process requirements of the application. If you attempt to replace an active server image, ACMS replaces it with the new version once it stops executing or is aborted.

If a server image does not stop independently because it contains an infinite loop or some other error, you can force the image to stop. To stop a server image, specify the ACMS/SHOW SERVER command to determine the process ID of the server image, and then issue the DCL command STOP/ID with the server process ID:

    $ STOP/ID=22E00563

When application-level auditing is enabled and a server is replaced, the Audit Trail Logger records the event in the Audit Trail Log. See Chapter 12 for an example of an audit trail record generated by server replacement.

# 9.8 Maintaining Application Availability

As system manager, ensure that the processing workload is distributed evenly throughout all nodes in a cluster. If a heavier workload is concentrated more on one node in the cluster than on others, use the ACMS/REPROCESS APPLICATION_SPEC command to redirect application selections to a node other than the node currently being used. This frees up disk space and memory and allow tasks to execute faster.

The ACMS/REPROCESS APPLICATION_SPEC command allows you to take advantage of logical names and search lists to enhance the current ACMS ability to keep applications available in the event of a system failure.

For example, assume that tasks are being selected in an application pointed to by the application specification PAYROLL , and that PAYROLL has been defined as a logical for NODE1::PAYROLL. If PAYROLL is redefined as a logical for NODE2::PAYROLL, and you issue the following command, then all subsequent task selections for PAYROLL are processed on node NODE2 rather than node NODE1.

    $ ACMS/REPROCESS APPLICATION_SPEC PAYROLL

This command is particularly useful to failback to applications when using search lists for application specifications. Search lists can be used for application specifications to provide for automatic failover to one or more backup applications in the event of a system failure. The ACMS/REPROCESS APPLICATION_SPEC command can be used to failback to the original application when it becomes available. See Chapter 6 for more information on using search lists in application specifications.

# 9.9 Canceling Tasks

There are several situations in which it might be necessary to cancel a task. Cancel one or more tasks when:

- You want to cancel all tasks in an application before stopping the application.
- The operator wants to cancel a user who has active tasks.
- A task is not executing properly.

To stop either an application or the ACMS system and cancel all active tasks, include a /CANCEL qualifier in the ACMS/STOP SYSTEM or ACMS/STOP APPLICATION command. The /CANCEL qualifier always interrupts any active tasks or users in the system or the application being stopped.

To cancel a task without stopping the ACMS system or application, use the ACMS/CANCEL TASK command. This command results in a non-recoverable exception. However, in distributed transactions the effect of the ACMS/CANCEL TASK command depends upon the task state:

- If the task is not composed (not participating in a distributed transaction started by a parent task or an agent), ACMS always attempts to abort an active DECdtm transaction.
- If a composed task is executing at the time of the cancel, ACMS cancels the task and returns control to the parent task or agent. An exception is returned to the parent task, or the cancel reason is returned to the agent. The parent task or the agent has responsibility for aborting the transaction.

See Compaq ACMS for OpenVMS Writing Applications for complete information about task cancellation and exception handling.

When you use this command without a task name or qualifiers, the command affects all active tasks on the local node, including tasks called by other tasks. By default, ACMS prompts you to confirm the cancellation before canceling a task. However, if you use the /NOCONFIRM qualifier, ACMS cancels all tasks without prompting for confirmation. In either case, include the /LOG qualifier with the ACMS/CANCEL TASK command. The /LOG qualifier displays a message confirming each successful cancellation.

The following command cancels MARKET_TASK1 but not MARKET_TASK2:

    $ ACMS/CANCEL TASK

    Task Name: MARKET_TASK1
      Task ID:      CARAT::0001000D-00000001
      Application:  MARKET_APPL                      User Name:    SAMPLE1
      Submitter ID: CARAT::0001000D                  Device:       TTB1:

    Task ID:        CARAT::0001000D-00000001 (Y/[N]):Y

    Task Name: MARKET_TASK2
      Task ID:      CARAT::00020013-00000001
      Application:  MARKET_APPL                      User Name:    SAMPLE2
      Submitter ID: CARAT::00020013                  Device:       TTH0:

    Task ID:        CARAT::00020013-00000001 [Y/[N]]:N

Other qualifiers available with the ACMS/CANCEL TASK command let you identify which task to cancel by one of several characteristics such as task name or user name. See the description of the ACMS/CANCEL TASK command in Chapter 21 for a description of these qualifiers.

# 9.10 Displaying Task Information

The ACMS/SHOW TASK command displays information about ACMS tasks running on your node. You can display information about tasks that are selected by a local or a remote submitter. You can include one or more task names as parameters. If you include more than one task name, separate the task names with commas. If you do not include a parameter, ACMS displays information about all active tasks. Example 9-4 shows some sample output from the ACMS/SHOW TASK command. Because no task name is specified, ACMS displays information about all active tasks.

Example 9-4 ACMS/SHOW TASK Command

    $ ACMS/SHOW TASK

      ACMS V4.0   CURRENT TASKS        Time:  1-MAY-1994 20:33:14.93
      (1)
      Task Name: PERS_ADD_TASK
        (2)  State:        Active; Executing PROCESSING step WORK
        (3)  Step label:   $STEP_1
        (4)  Task ID:      ALLDAY::00010016-0000002
        (5)  Application:  PERS                        (6)  User Name:   SWEET
        (7)  Submitter ID: ALLDAY::00010016            (8)  Device:      TTB4:
        (9)  Called Task:  PERS_CALLED_TASK
              State:      Active, executing BLOCK step WORK
              Step label: $STEP_2
        (10)    Server(s):  PERS_SERVER             Executing, PID 0200010B
        (11)    TID:        0012000B-0120-0260-0006-0000050002101
              Task ID:    ALLDAY::00010016-00000002-00000001

The following describes the numbered items in Example 9-4:

1. Task Name
   Name of any task the user is running. The task name is the name defined for the task in the task group definition.
2. State
   Each task exists in one of these states: Starting, Active, Finishing, Completed, Processing Exception, and Cancelling. The Active, Completed, Processing Exception, and Cancelling states each have variations. See Table 9-1 for a complete list and description of the task states.
3. Step label
   Current step label. SHOW TASK only displays the step label line if the task is within a step.
4. Task ID
   ACMS task identification code. The task ID uniquely identifies a task instance.
5. Application
   Name of the application in which the task is running.
6. User Name
   User name of the task submitter. The user name is the proxy user name when the submitter selects tasks from a remote ACMS system.
7. Submitter ID
   ACMS task submitter identification code assigned to the task at sign-in. The node field in the submitter ID lets you distinguish between local and remote submitters.
8. Device
   ACMS login device of the task submitter. All remote task submitters are signed in with the null device (NL).
9. Called Task
   Name of the called task.
10. Server(s)
    List of the servers the task is using. A task can be executing in a server, retaining a server, or waiting for a server, or any combination of these three. For tasks executing in or retaining a server, the process identification number (PID) is supplied. For tasks waiting for a server, the number of seconds for which it has been waiting is supplied. SHOW TASK only displays the list of servers if the task is currently executing in a server, retaining a server, or waiting for a server.
11. TID (DECdtm transaction identification number)
    TID associated with the task. The TID is displayed only for a task containing a distributed transaction, and only if it hasn't already been displayed for the task.

Table 9-1 Task States
State | Description |
--- | --- | ---
Starting | Task state while EXC initializes a task instance. Task initialization includes writing a "task start" record to the audit trail log.
Active | Task state when a task is currently executing, is not processing an exception, and has not been cancelled. Additional information further specifies the task state in active status.
Active; Executing BLOCK step WORK
| The task is executing the work part of a block step. Since the work part of a block step involves executing the nested processing, exchange, and subordinate nested block steps within the block, then a task only maintains this state while ACMS initializes the block step.
Active; Executing BLOCK step ACTION
| The task is executing the action part of a block step.
Active; Executing BLOCK step ACTION, Committing Transaction
| The task is waiting for notification from DECdtm to commit the transaction as the second step in the 2-phase commit process.
Active; Executing BLOCK step ACTION, Aborting Transaction
| The task is waiting for notification from DECdtm to abort the transaction.
Active; Executing PROCESSING step WORK
| The task is calling a step procedure in a procedure server, executing a command in a DCL server, or calling another task.
Active; Executing PROCESSING step ACTION
| The task is executing the action part of a processing step.
Active; Executing PROCESSING step ACTION, Committing Transaction
| The task is waiting for notification from DECdtm to commit the transaction as the second step in the 2-phase commit process.
Active; Executing PROCESSING step ACTION, Aborting Transaction
| The task is waiting for notification from DECdtm to abort the transaction.
Active; Executing EXCHANGE step WORK
| The task is calling a DECforms form, a TDMS request, or performing stream I/O.
Active; Executing EXCHANGE step ACTION
| The task is executing the action part of an exchange step.
Finishing | The task has finished execution and ACMS is completing the task. Task termination processing includes writing a "task end" record to the ACMS Audit Trail Logger.
Completed | A task enters a completed state when it has executed the last step in the task definition and is waiting for a parent task or an agent, such as the QTI, to end or abort the DECdtm transaction in which the task participated. When the transaction completes, EXC frees the servers and ends the task. Additional information further specifies the task state in completed status.
Completed; Waiting to Prepare
| A composed task has completed, but awaits the end of the transaction. ACMS is waiting to receive a prepare message from DECdtm services as the first step in the 2-phase commit process.
Completed; Waiting to Commit
| A composed task has ended and is stalled pending the end of the transaction. ACMS is wating to receive a commit message from DECdtm as the second step in the 2-phase commit process.
Completed; Waiting for End of Transaction
| A non-composed task has completed, but awaits the end of the transaction. ACMS is waiting for DECdtm to complete the 2-phase commit process.
Processing Exception
| A task is processing an exception if it is actively performing the operations necessary to handle a step exception or a transaction exception. Additional information further specifies the task state in processing exception status.
Processing Exception; Cancelling an EXCHANGE step
| The task is waiting for an exchange step to be cancelled before the exception handling sequence can continue.
Processing Exception; Cancelling a PROCESSING step
| The task is waiting for a processing step to be cancelled before the exception handling sequence can continue.
Processing Exception; Aborting a transaction
| ACMS is aborting a DECdtm transaction as part of the exception handling sequence.
Processing Exception; Calling server cancel procedure(s)
| ACMS is calling one or more server cancel procedures as part of the exception handling sequence.
Processing Exception; Blocked, Waiting to Commit or Abort
| The task is associated with a blocked transaction. The task remains in this stalled state until communication is reestablished with the transaction coordinator node, or the LMCP Utility or an Rdb or DBMS utility is used to manually resolve the state of the transaction.
Cancelling | A task is cancelling if it is actively performing the operations necessary to cancel the task following a nonrecoverable exception. Additional information further specifies the task state in cancelling status.
Cancelling; Cancelling an EXCHANGE step
| The task is waiting for an exchange step to be cancelled before the processing sequence can continue.
Cancelling; Cancelling a PROCESSING step
| The task is waiting for a processing step to be cancelled before the processing sequence can continue.
Cancelling; Aborting a transaction
| ACMS is aborting a DECdtm transaction as part of the cancel processing sequence.
Cancelling; Calling server cancel procedure(s)
| ACMS is calling one or more server cancel procedures as part of the cancel processing sequence.
Cancelling; Auditing task cancel information
| ACMS is writing details about the task cancellation to the ACMS Audit Trail Log.
Cancelling; BLOCKED, Waiting to Commit or Abort
| The task is associated with a blocked transaction. The task remains in this stalled state until communication is reestablished with the transaction coordinator node, or the LMCP Utility or an Rdb or DBMS utility is used to manually resolve the state of the transaction.
Cancelling; Executing task cancel action
| The task is executing the cancel action phrase of the task definition.

The /APPLICATION qualifier lets you restrict the search ACMS makes to find a task. When you name an application with the /APPLICATION qualifier, ACMS searches for the tasks you name in the application you specify. The application name is the file name of the application. Do not include the device, directory, or the file type. For example:

Previous | Next | Contents | Index