DDU> MODIFY TTE6 /CONTROLLED /AUTOLOGIN=TURKLES
Device(s) has been modified

When users press the Return on terminal TTE6, they are prompted for a password (if a password is required) and are logged in to ACMS under the user name TURKLES. The device name you specify with the MODIFY command can be a logical name, a physical device name, or a group device name.

The /PRINTFILE qualifier feature provides hardcopy capability for DECforms panels. In other words, DECforms allows users to send a copy of one or more panel displays to a printer or to a file for subsequent printing. Using DDU, you can specify a Printfile device or file for a terminal. If you specify a device, then it must be a spooled device. (Specifying a Printfile for a user is explained in Chapter 3, Authorizing Users).

See Table 2.1, “DDU Group Device Names” for a list of DDU group device names. See Chapter 17, DDU Commands for more information on the MODIFY command.

Instead of using this sequence of commands to define LAT terminals each time you start OpenVMS, you can create a command file of LATCP Utility commands. Create a file called LAT$SYSTARTUP.COM in SYS$MANAGER, and include the commands. OpenVMS provides you with a template LAT definition command file, LAT$SYSTARTUP.TEMPLATE, which is copied to SYS$MANAGER when you install OpenVMS.

UDU> ADD RICHARDS /MDB=DISK02:[USERMENUS]ADDTASKS

UDU> COPY RICHARDS GORDON 

You can quickly create authorizations for all OpenVMS users by specifying $ALL as the user name with the ADD or COPY command. A $ALL definition authorizes all users at once, assigning them the same sign-in display, default menu, and menu database file.

If the user authorization file does not contain a $ALL definition, each ACMS user must have a separate user definition. With separate user definitions, you can restrict some OpenVMS users from signing in to ACMS.

Depending on how many users you are authorizing and the characteristics you want to assign them, you might want to use a $ALL definition to provide generic definitions for all users. Then, you can create separate definitions for those users who need characteristics that most other users do not, such as the agent qualifier.

You must create at least two user definitions: one to authorize the ACMS user (or a $ALL definition to authorize all OpenVMS users), and one to authorize the user name of the ACMS Command Process (see Section 3.4.6, “Authorizing User Names as Agents” for information on authorizing the Command Process).

As system manager, you can specify that a user runs a specific task when signing in to ACMS and that the user runs a specific task when signing out of ACMS. For example, you can specify that whenever a user signs in, a task asks for the user's name and telephone number. Or, if a user only runs one particular task all the time, you can specify that that task runs whenever the user signs in without having to select that task from a menu. When the user signs out, you can specify that an accounting task runs to log the user's work for the day — sign in and sign out time, number of files created, amount of disk space used, and so forth.

To specify an initial or final task for a user, use the /INITIAL or /FINAL qualifier with the UDU ADD, COPY, MODIFY, DEFAULT, or RENAME commands. The /INITIAL qualifier specifies the name of a task the user runs when signing in. The /FINAL qualifier specifies the name of a task the user runs when signing out.

UDU> ADD FORRESTER/INITIAL=(APPLICATION=RESERVATIONS,TASK -
_UDU> =BOOKING_INFO)

UDU> ADD KNUTH/FINAL=(APPLICATION=CLERK_REC,TASK=ACCOUNTING)

UDU> ADD EINSTEIN/INITIAL=(APPLICATION=RESOURCES,TASK=ACCT, -
_UDU> IGNORE_ERROR)

UDU> ADD PLATO/FINAL=(APPLICATION=REC_APPL,TASK=UPDATE,IGNORE_ERROR)

When you use the IGNORE_ERROR keyword for a final task, ACMS does not issue an error message or record the error in the Audit Trail Log when an error occurs.

UDU> ADD TOLSTOY/FINAL=(APPLICATION=ACCOUNTING,TASK= -
_UDU> SHOW_TRANSACTIONS, SELECTION_STRING="TRANSACTION_OUTPUT.DAT")

UDU> SHOW TOLSTOY

User Name:        TOLSTOY          DISPLAY MENU
Default Menu:
Default MDB:      INVENTORY
Initial Task:                       IGNORE ERROR
  Application:    RESOURCE
  Task:           ACCT
  Selection:
Final Task:                         IGNORE ERROR
  Application:    ACCOUNTING
  Task:           SHOW_TRANSACTIONS
  Selection:      TRANSACTION_OUTPUT.DAT
Language:
Printfile:

UDU> MODIFY LAO/MDB=ACMS /MENU=ACMS$EXIT/INITIAL= -
_UDU> (APPLICATION=RESERVATIONS,TASK=RESERVE_MENU)

This example defines an initial task for user LAO that serves as a menu control task. When this task exits, user LAO does not have a menu displayed at the terminal. Instead, the user is signed out of the ACMS system.

The TDMS request for the ACMS$EXIT menu returns "Exit" as if it were typed by the user at the selection prompt, but does this without terminal interaction.

Menu displays help users to select tasks. Upon signing in, each ACMS user sees either a menu and a selection prompt, or just a selection prompt. For users who need a menu and a selection prompt, specify a default menu in the user definition by assigning each user a menu database file with the /MDB qualifier, and a menu path name with the /MENU qualifier. If you do not include this information in the UDU definition, the ACMS default is to assign the user the top-level menu in the menu tree. This feature provides security to the system, because it enables you to restrict certain menus to selected users.

Menus offer a limited amount of task protection, since a menu can restrict the tasks that a user can select (if the SELECT command is disabled). However, other measures are required for adequate task protection. For more information on task protection, refer to VSI ACMS for OpenVMS ADU Reference Manual.

For users who need only the selection prompt, specify that no menu be displayed by using the /NODISPLAY_MENU qualifier in the user definition. For example, you might want to suppress the menu display for more experienced users. Or, if the default menu is the highest menu in the menu tree, you might want to reduce the need to page through several levels of menus by having the initial menu display be lower in the menu tree.

UDU> SHOW WINSTON
User name:        WINSTON      DISPLAY MENU
Default menu:
Default MDB:      EMPLOYEE
Initial Task:                       
  Application:         
  Task:  
  Selection:
Final Task:                    IGNORE ERROR
  Application:    PAYROLL
  Task:           SHOW_CHANGES
  Selection:      PAYROLL.DAT
Language:
Printfile:
UDU> MODIFY WINSTON /NODISPLAY_MENU
UDU> SHOW WINSTON
User name:        WINSTON                  
Default menu:
Default MDB:      EMPLOYEE
Initial Task:                       
  Application:         
  Task:  
  Selection:
Final Task:                    IGNORE ERROR
  Application:    PAYROLL
  Task:           SHOW_CHANGES
  Selection:      PAYROLL.DAT
Language:
Printfile:

The sign-in display you define with UDU is only the initial display characteristic. Users can modify their sign-in displays at run time by selecting the MENU and NOMENU commands in the ACMS command menu. The online ACMS Terminal User's Guide describes the MENU and NOMENU commands. It is available in the SYS$HELP directory.

Layout Name: FRENCH_PANEL
.
.
.
Language: FRENCH

You can use the language specification for purposes other than to associate a natural language with a layout. You can, for example, use the layout language specification to distinguish panels designed for novice, experienced, and expert users.

UDU> MODIFY LEBLANC/LANGUAGE=FRENCH

UDU> SHOW LEBLANC
User name:         LEBLANC           DISPLAY MENU
.
.
.
Language:   FRENCH

You can specify a language for DECforms forms that is used both in ACMS tasks and in ACMS menus. The DECforms menu form supplied by ACMS contains a standard layout without any language name. You need to specify a language in a menu form to display the menu to users who enter through the Command Process (CP) and who have a corresponding language specified in the ACMSUDU.DAT file.

By specifying a language for a menu form layout, you can update the prompt and the instruction line of the menu to use the appropriate language. To translate the header and the entries of the menu, however, you must use a different menu definition (.MDF) for each language.

You can display the same menu to all users, whether they have a language specified for them or not. In this case, use only one language for the prompt and instruction line; this saves the step of adding a layout for each language in the menu form. An additional benefit is to keep the size of the menu form to a minimum.

UDU> MODIFY SMITH/LANGUAGE=NOVICE/SKIPMENULANGUAGE

UDU> SHOW LEBLANC

User name:         LEBLANC           DISPLAY MENU
.
.
.
Language:   FRENCH       SKIPMENULANGUAGE

Besides using the /PRINTFILE qualifier to specify a printfile name or a spooled device name for a terminal device (which is explained in Chapter 2, Authorizing and Controlling Terminals), you can also use this qualifier to specify a printfile name or spooled device name for a user.

When a form is enabled, ACMS uses the Printfile characteristic for the terminal device, if it is available. If the characteristic is not found, ACMS uses the Printfile characteristic for the user. If neither has been specified, but a PRINT response and a print key are defined in the form source IFDL file, a file with the name <form-name>.TXT is placed in the SYS$MANAGER directory (if the CP is the agent), or in the default directory of the agent.

 UDU> MODIFY WINSTON /PRINTFILE=SPOOLDEV::TXA0:
UDU> SHOW WINSTON
User name:        WINSTON                  
Default menu:
Default MDB:      EMPLOYEE
Initial Task:                       
  Application:         
  Task:  
  Selection:
Final Task:                    IGNORE ERROR
  Application:    PAYROLL
  Task:           SHOW_CHANGES
  Selection:      PAYROLL.DAT
Language:
Printfile:  SPOOLDEV::TXA0:

When a form is enabled, ACMS uses the printfile specification for a device assigned by the Device Definition Utility (DDU), if it is available. If it is not, ACMS uses the printfile specification for the user, as specified in UDU.

Normally, ACMS users can submit tasks only under their own user names. An agent is an OpenVMS process that submits ACMS tasks for processing on behalf of ACMS users whose user names are different from the agent's user name. For security reasons, you must authorize agents by adding the user name of the agent process and including the /AGENT qualifier.

The CP and the Queued Task Initiator (QTI) are agents supplied by ACMS. ACMS requires that you create separate user definitions using the /AGENT qualifier to authorize the CP and the QTI as agents. If your system does not have any agents created with the ACMS Systems Interface (SI), you need only authorize the user name of the CP and QTI as agents.

UDU> ADD SYSTEM/AGENT
User SYSTEM         has been added to the data base
UDU> SHOW SYSTEM
User name:       SYSTEM     DISPLAY MENU      AGENT
Default menu:
Default MDB:
Initial Task:                       
  Application:         
  Task:  
  Selection:
Final Task:                       
  Application:         
  Task:  
  Selection:
Language:
Printfile:

UDU> ADD SI_AGENT/AGENT -
_UDU> /MDB=DISK$:[TOPLEVEL]ACMS.MDB - 
_UDU> /MENU=PERSONNEL
User SI_AGENT has been added to the data base
UDU> SHOW SI_AGENT
User name:       SI_AGENT          AGENT
Default menu:    PERSONNEL
Default MDB:     DISK$:[TOPLEVEL]ACMS.MDB
Initial Task:                       
  Application:         
  Task:  
  Selection:
Final Task:                       
  Application:         
  Task:  
  Selection:
Language:
Printfile:

As the example shows, when authorizing a user name with the /AGENT qualifier, you must explicitly assign the display characteristic and a menu database file to that user name. You can also assign a default menu path name. With its user name defined in the user authorization file, SI_AGENT can submit tasks to ACMS under any user name. See VSI ACMS for OpenVMS Systems Interface Programming for more information on the SI.

When you add or change user information, you can verify information in the authorization file with either the SHOW or the LIST command.

UDU> SHOW *
User name:      $ALL             DISPLAY MENU
Default Menu:
Default MDB:    INVENTORY
Initial Task:                    IGNORE ERROR   
  Application:  VALIDATE_APPL       
  Task:         ACCESS_RIGHTS
  Selection:
Final Task:                       
  Application:         
  Task:  
  Selection:
Language:
Printfile:
User name:      CRAWFORD         DISPLAY MENU
Default Menu:
Default MDB:    ACCOUNTING
Initial Task:                    
  Application:         
  Task:  
  Selection:
Final Task:                       IGNORE ERROR
  Application:  PAYROLL
  Task:         SHOW_CHANGES
  Selection:    PAYROLL.DAT
Language:
Printfile:

When you specify the wildcard character (*), UDU displays all definitions in the user authorization file. To see a particular user definition, specify the user name with the SHOW command.

UDU> LIST GORDON

This command copies the GORDON definition to the ACMSUDU.LIS file in your default directory.

If a user is no longer a valid ACMS user, remove the user definition from the user authorization file with the REMOVE command. The REMOVE command deletes the user definition from ACMSUDF.DAT and displays a message confirming the action. For the user name parameter, you can use an OpenVMS user name or $ALL.

Use the RENAME command when you want to change a user name. Because the RENAME command uses the same qualifiers as the ADD, COPY, DEFAULT, and MODIFY commands, you can change any of the original characteristics while you change the user name.

AAU> ADD $ALL /ACL=(IDENTIFIER=[GORDON],ACCESS=CONTROL)

If you have not altered the DEFAULT authorization, the $ALL authorization takes the default values that ACMS originally sets for all the qualifiers you do not include with the ADD command. The preceding ADD command, therefore, creates a $ALL authorization allowing user GORDON to install any application on the system.

AAU> ADD INVENTORY /ACL=(ID=[GORDON],ACCESS=CONTROL) -
_AAU> /APPL_USERNAME=INVTRY -
_AAU> /SRV_USERNAMES=(PARTS,STOCK) -
_AAU> /DYNAMIC_USERNAMES -
_AAU> /NOWILD_SUFFIX

This command authorizes user GORDON to install the application INVENTORY if the application database file (.ADB) has the application user name INVTRY and two server processes with user names PARTS and STOCK. The /DYNAMIC_USERNAMES qualifier lets user GORDON install the INVENTORY application with the dynamic user name characteristic. Because all qualifiers are included, the ADD command does not use any default values from the DEFAULT authorization.

AAU> COPY INVENTORY ACCOUNTING /ACL=(ID=[SMITH],ACC=CON)-
_AAU> /SRV_USERNAMES=(ADD,SUB)

Here the COPY command creates an exact copy of the INVENTORY application authorization and names it ACCOUNTING. The qualifiers with the COPY command change the authorized user to SMITH and the two server user names to ADD and SUB.

The /[NO]WILD_SUFFIX qualifier allows a user to install or prevents a user from installing any application whose name begins with the letters of the application name you are installing.

AAU> ADD TEST /WILD_SUFFIX /APPL_USERNAME=TEST_EXE -
_AAU> /ACL=(ID=[SMITH],ACCESS=CONTROL) -
_AAU> /SRV_USERNAMES=(TEST1,TEST2) -
_AAU> /NODYN_USERNAMES

This command lets the authorized user SMITH install any application that starts with the letters TEST. SMITH can install applications such as TEST, TESTA, TESTB, TESTC, TEST1.

There are many occasions when a quick check of authorizations in the AAU authorization file is helpful. For example, you may need to check the DEFAULT authorization if you cannot remember its current settings. To display application authorizations on your terminal screen, use the SHOW command. The output from the SHOW command is shown in Example 4.1, “AAU SHOW Command”.

When you use the wildcard character (*), AAU displays all authorizations in the AAU authorization file. To see a particular application authorization, include the application name with the SHOW command.

AAU> LIST CREDITOR

AAU> SHOW *

==================================================================
Appl Name:  $ALL
Appl Username:  *
Server Usernames:
   *
Access Control List:
    (IDENTIFIER=[*,*],ACCESS=CONTROL)
==================================================================
Appl Name:  CREDITOR
Appl Username:  CREDIT
Server Usernames:
    CREDIT1
    CREDIT2

Access Control List:
    (IDENTIFIER=[PAYUP,*],ACCESS=CONTROL)
===================================================================
Appl Name:  DEFAULT                                     WILD SUFFIX
Appl Username:  DEBT
Server Usernames:
    DEBT1
    DEBT2

Access Control List:
    (IDENTIFIER=[PERSONNEL,*],ACCESS=CONTROL)
===================================================================
AAU>

If an application is no longer being used, you need to remove its authorization from the AAU authorization file. When you identify unused applications, you can delete them with the REMOVE command. The REMOVE command deletes the application authorization from the authorization file and prints a message confirming the action. The application name can be that of an application, or it can be $ALL.

You can use the RENAME command when you want to change the name of an authorization. Because the RENAME command uses the same qualifiers as the ADD, COPY, DEFAULT, and MODIFY commands, you can change any of the original authorization's characteristics while you change the authorization's name.

ACMSQUEMGR> CREATE QUEUE PERS_QUEUE

When you use the CREATE QUEUE command to create a queue, the ACMSQUEMGR Utility sets the owner of the queue file to [1,4] and sets the protection of the file to S:RWED,O:RWED,G,W. Therefore, to access the queue file, a user must have a system UIC or must have the SYSPRV privilege.

You can dynamically control the availability of task queues by using the SET QUEUE command. For example, the SET QUEUE command can be used to prevent queued task elements from being queued to a task queue. Likewise, the SET QUEUE command can prevent queued task elements from being dequeued from a task queue.

When you use the SET QUEUE command, you must use either the /DEQUEUE or /ENQUEUE qualifier.

ACMSQUEMGR> SET QUEUE /ENQUEUE=SUSPENDED HISTORY_QUE

When the enqueue state of a task queue is set to SUSPENDED, the ACMS$QUEUE_TASK service returns an error when elements are queued to the task queue. Use /ENQUEUE=RESUMED to enable queuing of elements.

ACMSQUEMGR> SET QUEUE /DEQUEUE=SUSPENDED MY_QUE

By using the /DEQUEUE=SUSPENDED qualifier, you can allow tasks to be queued to a queue, but suspend their processing. When dequeues are suspended, the ACMS$DEQUEUE_TASK service returns an error. When you want tasks to be processed by the QTI, specify the /DEQUEUE=RESUMED qualifier.

You can modify the static characteristics of a task queue by using the MODIFY QUEUE command. This can include changing the disk where a queue repository file is located, or increasing the maximum workspace size for a task queue to allow for the size requirements of a new task in your application. In any case, you do not need to modify the characteristics of a task queue on a frequent basis.

The MODIFY QUEUE command requires exclusive access to the task queue. Make sure that no processes have access to the queue by setting the enqueue and dequeue state of the task queue to suspended. To do this, use the SET QUEUE command and then stop the queue with the ACMS/STOP QUEUE command.

ACMSQUEMGR> MODIFY QUEUE PAY_QUE/MAX_WORK=450

ACMSQUEMGR> MODIFY QUEUE MY_QUE/FILE_SPEC=DISK2:MY_QUE.DAT

ACMSQUEMGR> DELETE QUEUE PAY_QUE

ACMSQUEMGR> DELETE QUEUE/PURGE PAY_QUE

If you do not specify the /PURGE qualifier and there are queued task elements in the task queue, ACMSQUEMGR is unable to delete the task queue and displays an error message.

ACMSQUEMGR> 
SHOW QUEUE PAYROLL_QUE

  Queue Name: PAYROLL_QUE
  Enqueues State:  RESUMED  Dequeues State:  RESUMED     Max Wsp Size:  256
  File Specification:  SYS$SYSTEM:PAYROLL_QUE.DAT

See Chapter 20, ACMSQUEMGR Commands for more information about the SHOW QUEUE command.

Set the state or priority of a queued task element with the ACMSQUEMGR SET ELEMENT command. Setting the attributes of a queued task element allows you to control how it is dequeued.

ACMSQUEMGR> ELEMENT NODE1:22D00082-0000000E PARTS_QUE /PRIORITY=11

ACMSQUEMGR> SET ELEMENT NODE1:22D00082-0000000E PARTS_QUE - 
_ACMSQUEMGR> /STATE=HOLD

Setting an element to HOLD is useful when you want to start a queue, but do not want certain elements to be processed by the QTI. To allow a queued task element to be dequeued, specify /STATE=NOHOLD.

You can specify a wildcard character (*) instead of an element ID, and use the /SELECT or /EXCLUDE qualifiers to limit the scope of the command.

ACMSQUEMGR> SET ELEMENT * INVENTORY_QUE /STATE=NOHOLD - 
_ACMSQUEMGR> /SELECT=TASK=UPDATE_INVENTORY

ACMSQUEMGR> SET ELEMENT * INVENTORY_QUE /STATE=HOLD  - 
_ACMSQUEMGR> /SELECT=TASK=UPDATE_INVENTORY

Note that WRITE CURRENT was used in the preceding example. This ensures that a new ACMSPAR.ACM file is not created where one already exists. It also provides a check that the file exists on each node in an OpenVMS Cluster.

Finally, note that regardless of which method you use to set the node name parameter, you must stop and restart the ACMS system for the change to take effect.

Make sure that each step in Section 6.2.1, “Common Setup Tasks for Distributed Forms Processing” has been completed. Then, take these additional steps to enable distributed processing by authorizing remote access to ACMS on the application node.

These methods are described in the following paragraphs.

When ACMS uses a proxy account or a default submitter user name for a remote task submitter, tasks executed by the remote submitter are executed as if they were selected by a local task submitter using the same account. If a proxy or default submitter user name does not exist for a remote task submitter, ACMS rejects the remote task selection.

$ DEFINE/SYSTEM/EXECUTIVE ACMSPROXY SYS$TEST:FOO.BAR

UAF>  CREATE/PROXY COWBOY::JONES PERS/DEFAULT

.
.
.
USERNAME_DEFAULT = "ACMS_USER"
.
.
.

$ RUN SYS$SYSTEM:ACMSGEN
ACMSGEN> SET USERNAME_DEFAULT ACMS_USER
ACMSGEN> WRITE CURRENT

UAF> CREATE/PROXY COWBOY::* */DEFAULT

You must also ensure that application and form files have the correct file protection assigned.

When a terminal user on the submitter node selects a task in an application on the application node, ACMS automatically copies the application database and forms files used by the application from the application node to the submitter node. For ACMS to automatically distribute these files, they must be accessible by the ACMS Central Controller (ACC) and the CP on the submitter node, or remote task selections fail. You can ensure that these files are accessible on the application node by giving them WORLD:RE protection. See Section 6.4, “Distributed Operations ACMS Performs Automatically” for more information about how ACMS performs this automatic distribution.

UAF> ADD/PROXY COWBOY::ACMS$ACC ACMS$ACC/DEFAULT
UAF> ADD/PROXY COWBOY::ACMS$CP ACMS$CP/DEFAULT

ACMS uses the DECnet-VAX File Access Listener (FAL) object to copy from one node to another. FAL is a DIGITAL-supplied object that is defined by default in the DECnet-VAX configuration database. This FAL object must exist and be enabled for ACMS to distribute needed files from one node to another.

$ RUN SYS$SYSTEM:NCP
NCP> SHOW
(ACTIVE, ADJACENT, AREA, CIRCUIT, EXECUTOR,
KNOWN, LINE, LOGGING, LOOP, MODULE, NODE, OBJECT):
OBJECT Object name (8 characters): 
FAL
Object Volatile Summary as of 21-JUL-1989 14:57:57
      Object   Number  File/PID              User Id          Password
     FAL           17  FAL.EXE NCP> 
EXIT
$

You must also ensure that files needed for DECforms escape routines have the correct file protection assigned.

Place DECforms escape routines in a restricted directory because they contain user-written code that runs in a privileged process. DECforms escape routines are not distributed automatically by ACMS. Hence, the system manager on the submitter node needs to copy these files manually from the application node. Consequently, make sure the files are accessible to the submitter node. See Section 6.6, “Managing and Caching DECforms Escape Routine Files” for a description of managing DECforms escape routines.

$ DEFINE/SYSTEM APPL_NODE DOVE::

The menu definitions can refer to APPL_NODE::ACCOUNTING, APPL_NODE::PERSONNEL, and APPL_NODE::BUDGET. Then, if you need to move these applications to another node, you can simply redefine APPL_NODE to be the new node name without changing the menu definitions.

 ENTRIES ARE:
.
.
.
NEW_EMPLOYEE: TASK IS NEW_EMPL_TASK IN "APPL_NODE::PERSONNEL";
.
.
.
END ENTRIES;

$ DEFINE/SYSTEM PAYROLL DOVE::PAYROLL

ENTRIES ARE:
.
.
.
NEW_EMPLOYEE: TASK IS NEW_EMPL_TASK IN "PAYROLL";
.
.
.
END ENTRIES;

When an ACC on a submitter node asks an application node for an application, the ACC process on the application node attempts to translate the application name locally. If a logical name does exist for the application name, then the translation is used to access the application on the application node.

Any name changes that occur on the application node do not affect the submitter's file name. For example, if a logical name on submitter node ARK exists which defines PAYROLL as DOVE::PAYROLL, node ARK asks application node DOVE for application PAYROLL. On node DOVE, ACMS tries to translate the PAYROLL logical again. If the logical translates to NEW_PAYROLL, for instance, the NEW_PAYROLL application is accessed on node DOVE. When files relating to that application are copied to node ARK, they are stored as PAYROLL.

The copying of application database (.ADB) and form files from a remote node to the local node where users are selecting tasks is referred to as caching. This is done to increase system performance, by avoiding the need for network access to the application node for application database and form files. A fuller explanation of this process is found in Section 6.4, “Distributed Operations ACMS Performs Automatically”.

If an application specification or a translation of a logical application specification does not contain a node name, ACMS looks for the application on the submitter's node. If you do use node names, they cannot contain access control strings. For example, ALPHA"ADAMS JOHNQUINCY"::PAYROLL is not a valid application specification because it includes the access control string, "ADAMS JOHNQUINCY".

ACMS follows OpenVMS conventions when translating logical names. For information about how OpenVMS translates logical names and how it translates logical names interactively, refer to VSI OpenVMS DCL Dictionary. See VSI ACMS for OpenVMS ADU Reference Manual for more information about ACMS application specifications.

$ DEFINE/SYSTEM PAYROLL DOVE::PAYROLL,RAVEN::PAYROLL

The menu definition then specifies PAYROLL as the application name. ACMS searches for the application on each node listed until it locates an available application, or until it reaches the end of the search list. You can define a search list for an application name, a node name, or both.

$ DEFINE/SYSTEM APPL_NODE DOVE::, ARK::, BRANCH::

Menu definitions then specify APPL_NODE::ACCOUNTING. When APPL_NODE::ACCOUNTING is translated, the first available application in the search list is used. Therefore, DOVE::ACCOUNTING is used if it is available. If it is not available, ACMS continues to process the search list from left to right until an available application is located.

Search lists provide a primitive form of failover. When an application goes down, an application node goes down, or the link between the submitter node and the application node is severed for some reason, ACMS cancels all active tasks on the submitter node. When a user attempts to select another task in the same application, ACMS reprocesses the search list for an available application.

Once an available node or application is found, all subsequent task selections are redirected to the available application, and terminal users are once again able to select tasks. No group or user workspace context in the failed application is saved. Users receive an error message when this type of failover situation occurs.

If you want to stop an application and cause users to select tasks in an application executing on another node, you can force failover to another application by using the ACMS/REPROCESS APPLICATION command. This command is described in the next section.

ACMS translates logical names for applications only when a task is first selected in an application. Once ACMS on a submitter node locates an application node, all task selections from the submitter node go to that application node until that application is either stopped or the link between the submitter node and the application node is broken.

$ ACMS/REPROCESS APPLICATION PAYROLL
Reprocess Specification for Application PAYROLL (Y/[N]):

This command causes ACMS to retranslate the logical name PAYROLL the next time a task submitter selects a task in the application.

The ACMS/REPROCESS APPLICATION command is especially useful for system managers who need to install an updated version of an application, but do not want to cause application downtime during this procedure. Simply redirect user task selections to an application executing on another node by using the ACMS/REPROCESS APPLICATION command; install the updated version; and then issue another ACMS/REPROCESS APPLICATION command to redirect user task selections back to the original node, which is now executing the updated application.

The ACMS/REPROCESS APPLICATION command can also be used to switch between versions of an application where the submitters and the application are running on the same system, as illustrated in the following example.

A site has two copies of an application, PAYROLL_A and PAYROLL_B, with the logical name PAYROLL defined as PAYROLL_A, PAYROLL_B. Note that no node names are used. The assumption is that the system is running and the system manager wants to make a new version of the payroll application available without interrupting the company's flow of work.

The system manager copies the new application database file (the .ADB file) to ACMS$DIRECTORY and calls it PAYROLL_B. The order of the PAYROLL logical is then redefined to PAYROLL_B, PAYROLL_A. The ACMS/REPROCESS APPLICATION PAYROLL command is then issued, causing all subsequent task selections to go to the new PAYROLL_B application. When there are no more submitters using PAYROLL_A, that application can be stopped. To switch users back to PAYROLL_A after it has been updated, the logical names are reversed, and the process is repeated.

In a distributed ACMS environment, the process goes as follows: If PAYROLL is defined as the search list: DOVE::PAYROLL, ARK::PAYROLL, RAVEN::PAYROLL, and you want to install an updated version of the PAYROLL application on node DOVE (the application currently being used), redefine the search list to point to ARK::PAYROLL, RAVEN::PAYROLL and execute the ACMS/REPROCESS APPLICATION command. Terminal users make new task selections in ARK::PAYROLL. After you install the updated application on node DOVE, redefine the search list to point to DOVE::PAYROLL, ARK::PAYROLL, RAVEN::PAYROLL and issue another ACMS/REPROCESS APPLICATION command. Users make new task selections in the updated application.

The ACMS/REPROCESS APPLICATION command can also be used to cause submitters to “failover” to an application that previously failed but has now been made available. For example, if PAYROLL is defined as the search list: DOVE::PAYROLL, ARK::PAYROLL, RAVEN::PAYROLL, and node DOVE goes down, ACMS automatically retranslates the search list for PAYROLL, and terminal users make new task selections in ARK::PAYROLL. When node DOVE again becomes available, issue the ACMS/REPROCESS APPLICATION command to redirect subsequent user task selections back to the DOVE::PAYROLL application.

When a user selects a task in an application, the ACMS run-time system checks to see if the application and form files are accessible on shared disks available to both the submitter and the application nodes. If the files are not located on shared disks and are not already resident on the submitter node, ACMS automatically copies the application and forms files used by the application from the application node to the submitter node. ACMS does not automatically distribute DECforms escape routines. You must distribute these files manually. See Section 6.5.1, “Manually Distributing Applications” and Section 6.6, “Managing and Caching DECforms Escape Routine Files” for information on how to manually copy DECforms escape routines and where to store them.

These copies are made automatically by ACMS to increase the performance of the system by avoiding having to access these form and application files over a network.

For ACMS to perform this automatic distribution of application and form files, the ACC and the CP must have access to these files. On the application node, you can use proxies for the remote ACC and CP in combination to allow access to these files by the ACC and CP on the submitter node. Alternatively, assigning the files WORLD:RE protection ensures that these files are accessible.

Using proxies allows a submitter node ACC or CP to access the files on the application node as if they were being accessed by the application node's ACC or CP. In this case, the files do not need WORLD:RE access. However, if proxies are not used, the submitter node's ACC and CP are accessing the files as if they were nonprivileged users on the application node, which is why the files must have WORLD:RE protection. If this no-proxy method is used, the application node must have set up a default DECnet account which does not have privileges, but does allow remote nodes to access files which have WORLD:RE protection on the local node. For ACMS caching to work without the use of proxies, this DECnet default account must exist.

When ACMS automatically distributes files to the submitter node, it places the files in a special directory hierarchy created by ACMS specially for this purpose. This directory structure is known as the ACMS systemwide cache directory. By default, on the submitter node, ACMS creates this systemwide cache directory structure by using the translated directory specification of ACMS$DIRECTORY with ACMS$CACHE appended as a rooted directory. For example, if ACMS$DIRECTORY translates to DRA1:[ACMSDIR], then the systemwide cache directory on submitter node DOVE is DOVE::DRA1:[ACMSDIR.ACMS$CACHE].

ACMS defines these logical names as rooted directories. For example, consider a system where the ACMS$DIRECTORY logical is defined to be SYS$SYSDEVICE:[ACMSDIR]. If the physical system disk device name is $1$DUA0:, then ACMS defines ACMS$ADB_CACHE as $1$DUA0:[ACMSDIR.ACMS$CACHE.]. Note that a physical device name must be used when defining a rooted directory logical name.

ACMS creates subdirectories (on the submitter node) for each node to which it copies application databases. Each node needs its own subdirectory in case two nodes have different applications with the same name. ACMS does not create subdirectories if the databases are accessed remotely. The location of these subdirectories is controlled by cache logicals, described in the preceding paragraphs. These subdirectories are used to store the .ADB and form files for applications access on that remote node.

Once a terminal user on submitter node COMET has selected tasks in each of these applications, the ACMS$CACHE directory on node COMET contains the subdirectories for the applications on each remote node.

Referred to under node COMET is PAYROLL.ADB, PAYROLL.DIR, STOCK.ADB, and STOCK.DIR. Referred to under node STAR is PAYROLL.ADB and PAYROLL.DIR. In this way, the ACMS system can discriminate among applications with the same name running on different nodes.

Also note that each subdirectory contains an .ADB and a .DIR for each application. Each .DIR contains the application's request libraries (.RLB) and/or forms files (.FORM and .EXE).

In most cases, the file name and type of the request libraries and forms files are the same as the file name and type on the remote node. If a remote application uses two different files with the same file name and type, but the files reside in a different disk or a different directory, the file type is modified to include the index of the task group within the application and of the request libraries and/or forms files of the task group.

This information can be obtained from the ADU DUMP APPLICATION and DUMP GROUP commands. The file type is modified to be .file-type_g_r, where file-type is the original file type, “g ” is the index of the task group (leading zeros suppressed) as recorded in the .ADB and “r ” is the index of the request library of forms file (leading zeros suppressed) as recorded in the .TDB.

      FORMS ARE
         form_a IN "DISK1$:[USER1]FORM_X.FORM" WITH NAME F1,
         form_b IN "DISK2$:[USER2]FORM_X.FORM" WITH NAME F2;

The first file will retain the file name and type. The second file will have FORM_X.FORM_1_2 as the file type. The same rule applies to request libraries (.RLB) and forms image files (.EXE). However, you should not use the same file name for forms image files (.EXE) because of the restrictions of the OpenVMS image activator. For details about forms image files, see VSI ACMS for OpenVMS Writing Applications.

When files are updated on the application node, ACMS automatically copies the new version of each file to the submitter node and deletes the old version the next time a user on a submitter node selects a task in an application containing updated files.

Note that ACMS does not make the copy at the time the change is made on the application node. The copy is made only when a user on the submitter node selects a task in the updated application. When updating application and form files, ACMS maintains a single copy of each file. It deletes old versions as soon as it makes an updated copy. Once the files are updated, the copies remain on each node until they are superseded by new versions or until they are explicitly deleted.

Note that during the preceding sequence of events, ACMS does not attempt to look for another application using the application specification, because a running application has already been found and it is the cache problem that has caused the task cancellation.

Periodically, you may want to delete little-used files in the system cache directory. This could involve rarely used applications or nodes. This ensures that databases and forms that are infrequently used do not consume disk space. However, deleting files in the cache directory can cause slow response time for the first task selected in a remote application while ACMS copies the application and forms files to the submitter node.

On nodes with large disks, you can allow ACMS to automatically distribute all application database and forms files for all applications accessed by terminal users. On nodes with limited disk space, you may want to manually copy the forms and application files most frequently used and use access over the network for other, less frequently used, applications.

However, remember that performance may be affected when one of these less frequently used applications is selected, due to the need for network access to the form and application database files. The following section describes how to determine whether the manual distribution of application and forms files is advantageous for your particular site.

ACMS carefully preserves the original creation date and time on the local copy when it distributes files. You are responsible for this information if you manually distribute application and forms files. If you copy the files over the network using the OpenVMS COPY command, and specify the wildcard output file name and type, the COPY operation maintains the original creation date and time of the file.

If the destination application or forms file names differ from the source file names, you must still use the wildcard output file name and type when you copy the files. You can then use the OpenVMS RENAME command to add the necessary index to the file type of these files or to use the fully translated local application name as the file name of .ADB files. The RENAME command maintains the original creation date and time.

Destination application and forms file names can be different from the source names when an application uses two or more different application or forms files with the same file name and type, or when the local application name differs from the remote application name. If an application node has an application that uses two different forms files with the same file name and file type, there must be some way to distinguish them. This is done by modifying the file type.

For example, if application PAYROLL has two different files both called GENERAL.FORM, the file type is modified to include the index of the task group within the application and the index of the .FORM within the task group. The file index is obtained from the ADU DUMP APPLICATION and DUMP GROUP commands.

For example, the file type is modified to be .FORM_g_r, where g is the index of the task group (leading zeros suppressed) as recorded in the .ADB, and r is the index of the form file (leading zeros suppressed) as recorded in the .TDB. This method of indexing file types is the same for both DECforms and TDMS forms files.

ACMS automatically updates distributed files whenever they become outdated, however, you can prevent ACMS from automatically updating files by write-protecting the directories in which the files reside. ACMS does not update DECforms escape routines or their resources.

An agent image can be installed with privileges; however, do not assign privileges to an agent haphazardly, since an agent process executes under the terminal user's OpenVMS user name. Theoretically, the user whose name the agent process is running under could cause problems by adding an incorrect file to the system cache, thereby denying service to another user. For example, if you made ALL-IN-1 a privileged agent, ALL-IN-1 users would then be able to access the system cache directory with ALL-IN-1 commands. This could corrupt the system cache directory and its files, or cause other unexpected results.

You can avoid giving nonprivileged agents access to the system cache by creating an agent-specific cache directory. The agent-specific cache directory could be shared between agents (for example, all ALL-IN-1 users), or could be separate for each agent (for example, customer-written agents running the debugger).

Create the agent-specific cache directory in SYS$DISK. Then, define the logical name ACMS$RLB_CACHE or ACMS$FORMS_CACHE to point to either the agent-specific cache directory or a search list of directories.

$ DEFINE/EXEC ACMS$FORMS_CACHE -
_$ DRB2:[ALLIN1_CACHE.],DRA1:[ACMSDIR.ACMS$CACHE.]

Here, ACMS searches the private cache [ALLIN1_CACHE] for the DECforms file. If ACMS does not find the file there, it searches the public cache [ACMSDIR.ACMS$CACHE.]. If ACMS still does not locate the file, it creates a new version in the local cache.

The logical name ACMS$ADB_CACHE, which is normally a system logical name, must be available to the ACC. The ACMS$RLB_CACHE and ACMS$FORMS_CACHE logical names, however, can be defined as system, group, job, or user logical names, provided the logical name can be translated by the agent. They are usually defined as system logical names.

The ACMS remote request code in the agent process can only allow an agent to update a cache to which it has write access. If ACMS finds an out-of-date file in the central cache, it updates the file in the agent-specific cache.

If you are supporting multiple caches by using search lists, control where application and forms files are placed the first time they are copied from the application node. This is controlled through the use of a write-protected directory in the search list.

$ DEFINE ACMS$FORMS_CACHE DRA1:[ACMSDIR.ACMS$CACHE.],NET:

The “NET:” designation tells the ACMS run-time system that if the application or forms file is not found in the local ACMS$CACHE directory, it must open the application or forms file using remote DECnet file access. This requires that there be a process on the application node for each agent for each application and forms file. ACMS reads the .ADB files once and then keeps them in memory. See Section 6.4, “Distributed Operations ACMS Performs Automatically” for information on how ACMS updates remote application and forms files.

Certain agents, such as the ACMS-supplied CP agent, run in a privileged environment. Any escape routines that execute in a privileged agent also execute in the same privileged environment. Be sure to develop escape routines to execute in a privileged agent in the same way as you develop any other privileged code. Carefully review the code for any possible security violations before you run it live on the system.

Place the escape routine images in a write-protected directory; also write-protect the images themselves. After you place the file in a protected directory, you can define the logicals that make the escape routines available to the agent process.

You may not, however, need to place escape routines executed by a nonprivileged agent in a protected directory. In some cases, such as debugging, you may want the person running the CP agent to be able to change the escape routines executed. Use the methods described previously to make the escape routine images available to the CP agent.

You can enable data compression selectively between systems in a network. You might, for example, have a mixed configuration that has both wide area and local area networks. If both the submitter and application nodes exist on the same local area network, the cost of compressing data far outweighs the cost of transmitting uncompressed data over the network.

You can control data compression on a per-process basis. For example, data compression might be beneficial if you enable it for a forms-based agent such as the Command Process (CP). On the other hand, data compression might not be appropriate for a specialized user-written agent, if that agent processes data that is not compressible using the ACMS data compression algorithm.

ACMS provides system management tools that allow you to control the use of the data compression. One mechanism enables you to verify that data compression is enabled and used correctly. Another mechanism allows you to monitor the efficiency of the data compression algorithm in terms of the amount of data compression that is achieved.

ACMS does not compress other data such as DECforms send and receive record names or TDMS request names.

The amount that data can be compressed must be offset against the cost involved in compressing the data before it is sent over the network, and decompressing the data after it has been received. The cost is measured by CPU and memory usage.

To implement data compression, ACMS uses a simple run-length encoding algorithm that aims to provide a reasonable data compression ratio in typical applications, while not consuming excessive CPU or memory resources. In most cases, a higher compression ratio provides better performance in terms of less CPU usage and improved response time. See Table 15.2, “ACMS Data Items” for more information about the compression ratio.

Due to the overhead of the information necessary to describe the compressed data, compressed data sometimes occupies the same or more space than its original uncompressed form. In this situation, ACMS uses the uncompressed form when constructing a message to transmit over a network. However, when data compression is enabled, ACMS always sends less data, even if the workspaces data cannot be compressed; at the very least, the message overhead is optimized for space rather than for speed of processing.

You must define both the ACMS$ENABLE_DATA_COMPRESSION and ACMS$AUDIT_NETWORK_CONNECTIONS logical names as executive mode system logical names or as process logical names.

In an agent process, ACMS translates the logical names when the first submitter signs in. Therefore, for an ACMS-supplied CP agent, define the logical names as system logicals in executive mode before you start the ACMS terminal subsystem. For a user-written agent, you must either define the logical names before the agent program is started, or the agent program itself must define the logical names before calling ACMS$SIGN_IN to sign in the first submitter.

In the Application Execution Controller (EXC) process, ACMS translates the logical names as part of the application startup processing. Therefore, you either must define the logical names as system logicals in executive mode before you start the application, or you must define them using the APPLICATION LOGICAL NAME clause in the application definition.

If you need to enable or disable data compression or the auditing of network connections after an agent process or an application process has been started, you must restart the process after you define, redefine, or deassign the appropriate logical names.

ACMS never uses data compression automatically. You must always explicitly enable data compression on both the application node and the submitter node before ACMS uses data compression between the two nodes. ACMS never uses data compression for communications between processes on the same node.

7.2.2.1. Enabling Data Compression in Unrestricted Mode

To enable data compression in unrestricted mode, define the ACMS$ENABLE_DATA_COMPRESSION logical name as the wildcard asterisk character (*).

For example, use the following command to enable data compression in unrestricted mode:

$ DEFINE/SYSTEM/EXECUTIVE   ACMS$ENABLE_DATA_COMPRESSION *
$ DEFINE/SYSTEM/EXECUTIVE ACMS$ENABLE_DATA_COMPRESSION *

Figure 7.1, “Simple Mixed-Interconnect Network” illustrates a distributed configuration consisting of three submitter nodes, each connected by a wide area network to a local area network consisting of two application nodes and three more submitter nodes.

In the configuration in Figure 7.1, “Simple Mixed-Interconnect Network”, data compression is required between submitter nodes S1, S2, and S3 and application nodes A1 and A2, because the submitter and application nodes are separated by a wide area network. Data compression is not required between submitter nodes S4, S5, and S6 and application nodes A1 and A2, because the submitter and application nodes are on the same local area network.

To use data compression in this configuration, enable data compression in unrestricted mode on submitter nodes S1, S2, and S3 and on application nodes A1 and A2, using the following command:

$ DEFINE/SYSTEM/EXECUTIVE   ACMS$ENABLE_DATA_COMPRESSION *
$ DEFINE/SYSTEM/EXECUTIVE ACMS$ENABLE_DATA_COMPRESSION *

Because data compression is not enabled on nodes S4, S5, and S6,data compression is not used between these nodes and application nodes A1 and A2.

7.2.2.2. Enabling Data Compression in Restricted Mode

You might sometimes want to limit the use of data compression to network connections between specific nodes in a network. To enable data compression in restricted mode, define the ACMS$ENABLE_DATA_COMPRESSION logical name as a search list, with each node name separated by a comma. You can specify node names with or without the trailing double-colon (::).

In restricted mode, ACMS uses data compression only for network nodes defined in the ACMS$ENABLE_DATA_COMPRESSION logical name. You do not need to enable data compression in restricted mode on both nodes. For example, you can enable data compression on a submitter node in unrestricted mode, and enable data compression on an application node in restricted mode. To do this, include the name of the submitter node in the list of nodes that the ACMS$ENABLE_DATA_COMPRESSION logical name identifies.

For example, use the following command to enable data compression in restricted mode from the application node to nodes S1 and S2:

$ DEFINE/SYSTEM/EXECUTIVE ACMS$ENABLE_DATA_COMPRESSION S1,S2

On nodes S1 and S2, define the logical name in unrestricted mode:

$ DEFINE/SYSTEM/EXECUTIVE ACMS$ENABLE_DATA_COMPRESSION *

Note

In listing node names as the equivalence names in the search list when you define the ACMS$ENABLE_DATA_COMPRESSION logical name, do not specify the unrestricted mode (*) symbol as a node name. If you use the unrestricted mode (*) symbol in place of a node name in the search list, ACMS writes an error entry to the ACMS audit log and does not enable data compression.

Figure 7.2, “Complex Mixed-Interconnect Network” extends the example shown in Figure 7.1, “Simple Mixed-Interconnect Network” by adding a second local area network containing two application nodes in addition to three submitter nodes. In the example, users on any submitter node can select tasks on any of the application nodes.

In the configuration shown in Figure 7.2, “Complex Mixed-Interconnect Network”, data compression is required between submitter nodes S1, S2, and S3 and application nodes A3 and A4, and between submitter nodes S4, S5, and S6 and application nodes A1 and A2. Data compression is not required between any other nodes in this network.

To use data compression in this configuration, enable data compression in unrestricted mode on the application nodes. On the submitter nodes, enable data compression so that it is used only when communicating with application nodes over the wide area network. Follow these steps:

1. Enable data compression in unrestricted mode on all the application nodes (A1, A2, A3, and A4) as follows:
   

   $ DEFINE/SYSTEM/EXECUTIVE   ACMS$ENABLE_DATA_COMPRESSION *

2. Enable data compression in restricted mode on submitter nodes S1, S2, and S3 as follows:
   

   $ DEFINE/SYSTEM/EXECUTIVE ACMS$ENABLE_DATA_COMPRESSION A3, A4

3. On submitter nodes S4, S5, and S6, enable data compression in restricted mode as follows:
   

   $ DEFINE/SYSTEM/EXECUTIVE ACMS$ENABLE_DATA_COMPRESSION A1, A2

An alternative approach in this example is to enable data compression in unrestricted mode on all the submitter nodes and then enable data compression in restricted mode on each application node. Follow these steps:

1. Enable data compression in unrestricted mode on all the submitter nodes (S1, S2, S3, S4, S5, and S6):
   

   $ DEFINE/SYSTEM/EXECUTIVE ACMS$ENABLE_DATA_COMPRESSION *

2. Enable data compression in restricted mode on application nodes A1 and A2:
   

   $ DEFINE/SYSTEM/EXECUTIVE ACMS$ENABLE_DATA_COMPRESSION S4,S5,S6

3. Enable data compression in restricted mode on application nodes A3 and A4:
   

   $ DEFINE/SYSTEM/EXECUTIVE ACMS$ENABLE_DATA_COMPRESSION S1,S2,S3

You might sometimes want to enable data compression on a general, system-wide basis, but disable it for specific processes. For example, you might want to disable it for a specialized user-written agent, if that agent processes data that cannot be compressed using the ACMS data compression algorithm.

$ DEFINE/PROCESS ACMS$ENABLE_DATA_COMPRESSION "-"

To verify that data compression is enabled correctly, enable logging of ACMS network connection information. When you do this, ACMS writes an entry to the ACMS audit log every time a new ACMS process is started and every time a process initiates or accepts a new network connection.

You can enable auditing on a submitter node, an application node, or both. You can then use the information written to the audit log to determine if ACMS is using data compression correctly on network connections to the appropriate remote nodes.

ACMS uses the ACMS$AUDIT_NETWORK_CONNECTIONS logical name to enable logging of ACMS network connection information. You must define the ACMS$AUDIT_NETWORK_CONNECTIONS logical name as an executive-mode system logical name or as a process logical name in any mode.

$ DEFINE/SYSTEM/EXECUTIVE ACMS$AUDIT_NETWORK_CONNECTIONS Y

*********************************************************
Type   : OTHER     Time   : 31-Jul-1992 15:20:01.15
Text   : Process ACMS01EXC001000 started
Data compression is not enabled
*********************************************************

*********************************************************
Type   : OTHER     Time   : 31-Jul-1992 15:21:02.16
Text   : Process ACMS01EXC002000 started
Data compression is explicitly disabled
*********************************************************

*********************************************************
Type   : OTHER     Time   : 31-Jul-1992 15:22:03.17
Text   : Process ACMS01EXC003000 started
Data compression is enabled for all nodes
*********************************************************

*********************************************************
Type   : OTHER     Time   : 31-Jul-1992 15:23:04.18
Text   : Process ACMS01EXC004000 started
Data compression is enabled for node: SUB1, SUB2, SUB3
*********************************************************

************************************************************
Type   : OTHER     Time   : 31-Jul-1992 15:40:21.45
Text   : Process ACMS01CP001000 initiated network connection
to remote node APPL1
Data compression is disabled (not enabled at local node)
************************************************************

************************************************************
Type   : OTHER     Time   : 31-Jul-1992 15:41:14.32
Text   : Process ACMS01QTI001000 initiated network connection
to remote node APPL2
Data compression not fully enabled (not enabled in ADB, please rebuild)
************************************************************

************************************************************
Type   : OTHER     Time   : 31-Jul-1992 15:42:23.76
Text   : Process ACMS01EXC001000 accepted network connection
from remote node SUB1
Data compression is disabled (not enabled at remote node)
************************************************************

************************************************************
Type   : OTHER     Time   : 31-Jul-1992 15:43:28.54
Text   : Process ACMS01EXC002000 accepted network connection
from remote node SUB2
Data compression is disabled (not enabled at local node)
************************************************************

************************************************************
Type   : OTHER     Time   : 31-Jul-1992 15:50:42.50
Text   : Process ACMS01CP001000 initiated network connection
to remote node YRNODE
Data compression is enabled
************************************************************

************************************************************
Type   : OTHER     Time   : 31-Jul-1992 15:52:55.42
Text   : Process ACMS01EXC003000 accepted network connection
from remote node YRNODE Data compression is enabled
************************************************************

After you verify that data compression is being used only on network connections with the nodes you specified, you might want to disable logging on a per-process basis. To disable logging of network connection information, deassign the ACMS$AUDIT_NETWORK_CONNECTIONS logical name. Note that ACMS does not automatically log network connection information.

$ DEFINE/PROCESS   ACMS$AUDIT_NETWORK_CONNECTIONS   N

After you disable auditing, any processes logging network connection information do not stop logging this information until the processes or the programs they are executing are restarted.

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.

$ @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.

$ 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, “Terminal Subsystem Controller ” for more information about stopping and starting the TSC.

$ ACMS/START SYSTEM/QTI

Once you start the QTI you can start ACMS task queues. See Section 8.7.1, “Starting Task Queues” for more information about starting task queues.

$ 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 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.

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.

$ ACMS/STOP SYSTEM/CANCEL

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.

Start the TSC either at the same time you start the ACMS system (as described in Section 8.1.2, “Starting ACMS Interactively”), 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.

$ 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.

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.

$ 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.

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.

$ 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, Auditing Applications with the Audit Trail Logger in this manual for more information about the ACMS Audit Trail Log.

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.

$ ACMS/SET SYSTEM/NOOPERATOR/PROCESS

$ 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, Auditing Applications with the Audit Trail Logger in this manual for more information about the ACMS Audit Trail Log.

$ ACMS/START QTI

Once the ACMS QTI is started, you can then start task queues by specifying the ACMS/START QUEUE command. See Section 8.7.1, “Starting Task Queues” for information about starting task queues.

$ ACMS/START QUEUE MY_QUE

Once you start a task queue, the QTI begins dequeuing and initiating tasks in the queue.

You must specify at least one queue name with the ACMS/START QUEUE command. You can start more than one queue by separating the queue names with commas.

You can specify the /ERROR_QUEUE and /TASK_THREADS qualifiers with the ACMS/START QUEUE command. The /ERROR_QUEUE qualifier allows you to specify the name of an error queue for a task queue. Tasks that do not complete successfully are placed in the error queue (unless they are to be retried), and ACMS records any errors in the Audit Trail Log. The /TASK_THREADS qualifier allows you to determine the maximum number of concurrent outstanding task elements that the QTI processes for the specified queue.

The error queue you specify with the /ERROR_QUEUE qualifier must exist. You can create an error queue with the ACMS Queue Manager (ACMSQUEMGR) Utility. See Chapter 5, Creating and Managing Queues for information about how to create an error queue.

$  ACMS/START QUEUE/ERROR_QUEUE=ERR_QUE MY_QUE,NEW_QUE

$ ACMS/START QUEUE YOUR_QUE/TASK_THREADS=12

$ ACMS/STOP QUEUE MOD_QUE

You can stop more than one queue by separating the queue names with commas.

$ ACMS/STOP QUEUE/CANCEL MY_QUE

Queued task elements that have been canceled remain in the queue repository file.

Use the ACMS/CANCEL USER command to cancel users before bringing down the ACMS system. When you use the ACMS/CANCEL USER command, you not only sign out the users you specify, you also cancel any tasks they have selected from a menu, plus any tasks that have been called by those tasks.

Use qualifiers to cancel users by user name, device name, or submitter ID. Use the ACMS/SHOW USER command to display user information.

If you do not use qualifiers or specify user names, the ACMS/CANCEL USER command cancels all active users and prompts you to confirm each cancellation.

$ ACMS/CANCEL USER ADAMS 
User Name:  ADAMS                Submitter ID:  MONEY::00010030
  Agent PID:  204002D            Device:        RTA6:

Submitter ID:   MONEY::00010030 (Y/[N]):Y

By default, the ACMS/CANCEL USER command asks that you confirm the cancellation by typing Y, for yes. ACMS cancels users without prompting you if you use the /NOCONFIRM qualifier, but it is safer to confirm each cancellation. In either case, you can include the /LOG qualifier with the ACMS/CANCEL USER command. The /LOG qualifier displays a message that confirms each successful cancellation.

On a distributed ACMS system, ACMS/CANCEL USER cannot cancel remote users (submitters).

You can use the command procedure ACMSCANCEL.COM to cancel inactive ACMS users. ACMSCANCEL.COM is located in the directory SYS$MANAGER. By default, ACMS writes cancellation information to the file ACMS$CANCEL.LOG in the SYS$MANAGER directory.

$ DEFINE/SYSTEM ACMS$CANCEL_DIR $DISK1:[MYDIR]

If you do not define ACMS$CANCEL_DIR, you must have write access to the SYS$MANAGER directory before using ACMSCANCEL.COM.

$ SUBMIT SYS$MANAGER:ACMSCANCEL.COM

$ DEFINE/SYSTEM ACMS$CANCEL_USER_WAIT 01:45

The ACMS/SHOW USER command displays information about ACMS users. Include one or more user names as parameters. If you include more than one user name, separate the names with a comma. If you do not include a user name, ACMS displays information about all users signed in to ACMS.

$ ACMS/SHOW USER JONES/DEVICE=TTH0:

$ ACMS/SHOW USER/FULL
  ACMS V4.0     CURRENT USERS           Time:  1-MAY-1994 20:11:04.21
   User Name:    JONES        Submitter ID:   KARAT::00010027
   Agent PID:  22E000A4       Device:         VTA5:

      Task Name:          DELETE
           Task ID:        KARAT::00010029-0000000F
           Appl Name:      TEST1
           Appl Node:      ALLDAY::

Example 8.5, “ACMS/SHOW USER/FULL Command” shows that JONES is running a task named DELETE on node ALLDAY at terminal VTA5. If more than one user is signed in under the user name JONES, the command displays information about all users named JONES.

$ ACMS/SHOW APPLICATION INVENTORY  
  ACMS V4.0    CURRENT APPLICATIONS         Time: 1-MAY-1994 17:19:40.84 
Application Name:   INVENTORY
                                 
       Object Name:         ACMS01EXC001000                           
       User Name:           ACMS               PID:              22000123 
     
  Max Task Count:      655                Max SP Count:     35 
       Cur Task Count:      0                  Cur SP Count:     7
       Auditing:            ON                SP Mon. Interval: 5)
                                                      
    Server Name          max SPs   min SPs active    free   waiting
                                               SPs       SPs    tasks
      INVSRV05                5         0       0         0      0
      INVSRV02                1         0       1         0      4
      INVSRV06                5         1       1         0      3
      INVSRV04                5         2       0         2      0
      INVSRV01                5         2       1         1      0
      INVSRV03                5         1       1         0      0

$ ACMS/SHOW APPLICATION/POOL TEST
  ACMS V4.0       CURRENT APPLICATIONS            Time: 1-MAY-1994 11:21:04.50
  Application Name: TEST                                      State:  STARTED
      Object Name:        ACMS01EXC008000
      User Name:          ACMS$EXC                PID:                25C01337
      Max Task Count:     65535                   Max SP Count:       5
      Cur Task Count:     0                       Cur SP Count:       2
      Auditing:           ON                      SP Mon. Interval:   5
    Application Workspace and Control Pools
                                                                          
          Pool          Pool      Free  (pct.)  Largest    Allocation    Garbage
          type          size      bytes          block      failures   collections
    Group/User workspace pools     
      Control pool      65536     64848 (98%)    32768          0           0
      Workspace pool   131072    130560 (99%)    65536          0           0
   TEST_GRP01
    Control pool      25600     25088 (98%)    16384          0           0
    Workspace pool   179200    178688 (99%)    65536          0           0
     TEST_GRP02
        Control pool      25600     25088 (98%)    16384          0            0
        Workspace pool   179200    178688 (99%)    65536          0            0
     DBMS_GRP
        Control pool      25600     25088 (98%)    16384          0            0
        Workspace pool   179200    178688 (99%)    65536          0            0

Use the information in the pool display to determine the correct sizes for the ACMSGEN parameters for control and workspace pools. See Chapter 11, Changing ACMS Parameter Values with the ACMSGEN Utility for more information.

$ ACMS/SHOW APPLICATION/CONTINUOUS STORAGE
                                                          
  ACMS V4.0       ACMS CONTINUOUS APPLICATION MONITOR   NODE::MYNODE
                                        1-MAY-1994 07:52:04.62
    Name:    STORAGE
    Process: ACMS01EXC015000
    User: ACMS$EXC                                 PID:  22E00563
    Max Tasks: 65535                               Max SPs:   22
    Cur Tasks: 15                                  Cur SPs:   13

                                                       

  SERVER NAME         Min SP/Max SP Current Average Minimum Maximum

  TESTSRV01                3/3
  Active Servers                      0       0       0       1
  Free Servers                        3       1       0       3
  Waiting Tasks                       0       2       0       28

  TLOAD001S                3/3
  Active Servers                      2       1       0       3
  Free Servers                        1       1       0       3
  Waiting Tasks                       0       12      0       92

You can control the video display by using the control and arrow keys. Press Ctrl/C, Ctrl/Y, or Ctrl/Z to terminate the display. Press Ctrl/W to refresh the screen. The up and down arrow keys scroll the screen forward and backward.

$ ACMS/SHOW APPLICATION/CONTINUOUS/INTERVAL=300 BOOKSALES

Begin or end a continuous application display with the /BEGINNING_TIME and /ENDING_TIME qualifiers. Both qualifiers let you specify times in OpenVMS absolute time format, delta time format, or a combination of the two. Refer to VSI OpenVMS DCL Dictionary for information about how to create valid time formats.

There are occasions when having hardcopy records of application information is useful. The /OUTPUT qualifier requests ACMS to copy application data to a file you name. Then either display the file at your terminal or print it. If you do not specify a file, ACMS stores information in the file ACMSSHOW.LIS in your current default directory. When you do not use the /OUTPUT qualifier, ACMS sends output to the default output device defined by the SYS$OUTPUT logical name.

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

When application-level auditing is enabled, the Audit Trail Logger records any application modifications you make in the Audit Trail Log. See Chapter 12, Auditing Applications with the Audit Trail Logger 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, “Displaying Static Information” describes the ACMS/SHOW APPLICATION command and provides some sample output.

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.

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

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, Auditing Applications with the Audit Trail Logger for an example of an audit trail record generated by the ACMS/MODIFY APPLICATION command.

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

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

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.