# Compaq ACMS for OpenVMS
Managing Applications

Previous | Contents | Index

# 7.2 How to Use Data Compression

The following sections describe:

- Managing data compression by defining the logical names ACMS$ENABLE_DATA_COMPRESSION and ACMS$AUDIT_NETWORK_CONNECTIONS for processes on application and submitter nodes
- Enabling data compression in either the restricted or unrestricted mode
- Disabling data compression
- Enabling logging of data compression
- Disabling logging of data compression

Note You must upgrade both the submitter and the application nodes to ACMS Version 3.3 or higher before you can use data compression for data in workspaces used in exchange steps. Also, to use data compression for data in task argument workspaces that agents supply, you must rebuild any application database (ADB) files after you install ACMS.

## 7.2.1 Rules for Defining Logical Names

ACMS uses two logicals to manage data compression:

- ACMS$ENABLE_DATA_COMPRESSION
- ACMS$AUDIT_NETWORK_CONNECTIONS

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.

## 7.2.2 Using Restricted and Unrestricted Modes

You can enable data compression in one of two modes:

- Unrestricted mode
  In unrestricted mode, ACMS uses data compression on all network connections to remote nodes that also have data compression enabled.
- Restricted mode
  In restricted mode, ACMS uses data compression only on network connections to a specified set of remote nodes.

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 *

Figure 7-1 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.

Figure 7-1 Simple Mixed-Interconnect Network

In the configuration in Figure 7-1, 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 *

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 extends the example shown in Figure 7-1 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, 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.

Figure 7-2 Complex Mixed-Interconnect 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

## 7.2.3 Disabling Data Compression

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.

To explicitly disable data compression, define the ACMS$ENABLE_DATA_COMPRESSION logical name as a hyphen character enclosed in quotation marks ("-"). For example, use the following command to disable data compression for a specific process:

    $ DEFINE/PROCESS ACMS$ENABLE_DATA_COMPRESSION "-"

Note DCL uses the hyphen character (-) to indicate the continuation of a DCL command line; therefore, you must enclose the character in quotation marks to differentiate it. Do not specify the disable symbol ("-") as a node name when you list node names as the equivalence names in the search list when you define the ACMS$ENABLE_DATA_COMPRESSION logical name. If you use the disable 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.

## 7.2.4 Enabling Logging of 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.

To log ACMS network connection information, define the ACMS$AUDIT_NETWORK_CONNECTIONS logical name as a string beginning with T or t (true) or, Y or y (yes), or define it as a success status (an odd number). For example, use the following command to log network connection information for all processes on a node:

    $ DEFINE/SYSTEM/EXECUTIVE ACMS$AUDIT_NETWORK_CONNECTIONS Y

### 7.2.4.1 Entries Written to the Audit Log When a New Process Is Started

When verification of network connection information is enabled, ACMS writes an entry to the audit log whenever a new process is started. The following examples illustrate each type of entry.

Example 7-1 illustrates the format of the entry ACMS logs when a process is started and data compression has not been enabled.

Example 7-1 Data Compression Is Not Enabled

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

Example 7-2 illustrates the entry ACMS logs when a process is started and data compression has been explicitly disabled.

Example 7-2 Data Compression Is Disabled

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

Example 7-3 illustrates the entry ACMS logs when a process is started and data compression has been enabled in unrestricted mode.

Example 7-3 Data Compression Is Enabled in Unrestricted Mode

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

Example 7-4 illustrates the entry ACMS logs when a process is started and data compression has been enabled in restricted mode.

Example 7-4 Data Compression Is Enabled in Restricted Mode

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

### 7.2.4.2 Entries Written to the Audit Log When Network Connection Is Established

When logging network connection information to the ACMS audit log, ACMS writes an entry to the log every time a new ACMS network connection is established. Note that ACMS multiplexes ACMS network connections over a single DECnet logical link. This means that you might see multiple entries in the audit log for the same process. The following examples illustrate the format of each type of network connection entry written to the ACMS audit log.

Example 7-5 illustrates that a process initiated a network connection but data compression was not used, because it was not enabled for the process at the local node. Note that if data compression is not enabled at the node initiating the network connection, then information about whether data compression is enabled at the remote node is not available.

Example 7-5 Data Compression Is Not Enabled at Local Node

    ************************************************************
    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)
    ************************************************************

Example 7-6 illustrates that a process initiated a network connection, but data compression was not fully enabled, because the actual application database (ADB) file was built using a version of ACMS prior to Version 3.3. In this case, although a compressed data protocol is used, data in task argument workspaces is not compressed. To fully enable data compression, rebuild the application database (ADB) file using ACMS Version 3.3 or higher.

Example 7-6 Data Compression Is Not Fully Enabled

    ************************************************************
    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)
    ************************************************************

Example 7-7 illustrates that a network connection was accepted by a process on the local node. Data compression was not used, however, because it was not enabled for the process at the remote node that initiated the connection.

Example 7-7 Data Compression Is Not Enabled at the Remote Node Initiating the Network Connection

    ************************************************************
    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)
    ************************************************************

Example 7-8 illustrates that a network connection was accepted by a process on the local node. However, data compression was not used, because, although it is enabled at the remote node that initiated the connection, it is not enabled for the process at the local node.

Example 7-8 Data Compression Is Enabled at the Remote Node, But Is Not Enabled at the Local 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)
    ************************************************************

Example 7_9 and Example 7-10 illustrate network connections that were established with data compression enabled.

Example 7-9 Data Compression Is Enabled with Network Connection to the Remote 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
    ************************************************************

Example 7-10 Data Compression Is Enabled with Network Connection from the Remote Node

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

## 7.2.5 Disabling Logging of Network Connections

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.

To explicitly disable logging of network connection information, define the ACMS$AUDIT_NETWORK_CONNECTIONS logical name as a string beginning with anything other than T, t, Y, or y, or define it as a failure status (an even number). For example, use the following command to disable logging of network connection information for a process running a user-written agent:

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

# 7.3 Monitoring Data Compression

ACMS uses the DECtrace layered product to monitor the extent to which messages sent over the network are compressed. ACMS logs an DECtrace point event, called the COMPRESSED_MSG event, every time a network message is sent or received.

By default, DECtrace collects items for the COMPRESSED_MSG event whenever data compression is enabled, provided that you specify the PERFORMANCE or ALL collection class in your facility selection. See Section 15.3.1 for more information about the COMPRESSED_MSG event.

Table 7-1 describes the information that DECtrace collects for each network message.

Table 7-1 Information Collected for Compressed Messages
Item | Description
--- | ---
Source node | Name of the node that sent the message
Destination node | Name of the node that received the message
Original message length | Length in bytes of the message before data compression
Compressed message length | Length in bytes of the message after data compression
Compression ratio | Factor by which ACMS compressed the message

Previous | Next | Contents | Index