# DIGITAL TP Web Connector
DIGITAL Database Web Connector
Getting Started

Previous | Contents | Index

### 7.2.4.2 Changing ACMS Desktop Adapter Group Settings

To change the ACMS Desktop adapter settings of a group, perform the following steps:

1. Click the `ACMS` tab.
2. Select a group from the `Group Name` list box to view its settings.
3. Type in the new information.
4. After you make changes, save them by clicking the `Save` button.
5. Restart all clients that call the group so the changes take effect.

If there are any unsaved changes, a dialog box asks whether you want to save all changes.

### 7.2.4.3 Deleting ACMS Desktop Adapter Group Settings

To delete the settings of a group, perform the following steps:

1. Click the `ACMS` tab.
2. Select the group in the `Group Name` list box.
3. Click the `Delete` button.
4. Restart all clients that call the group so the changes take effect.

If a group does not appear in the `Group Name` list box, that group cannot use the ACMS Desktop adapter.

# Chapter 8
Managing the ACMS Desktop Adapter Gateway

This chapter introduces the ACMS Desktop adapter gateway (see Section 8.1) and describes procedures for managing the ACMS Desktop adapter gateway.

- Starting and stopping the ACMS Desktop adapter gateway (see Section 8.2)
- Tuning the ACMS Desktop adapter gateway parameters to optimize performance (see Section 8.3)

# 8.1 The ACMS Desktop Adapter Gateway

A server called the ACMS Desktop adapter gateway provides the connection between the ACMS Desktop adapter running in the client and the ACMS task being called. When you install the TP Web Connector software on an ACMS system, you choose whether to install the ACMSADU extension with or without the ACMS Desktop adapter gateway (see Chapter 3).

On a Windows NT system on which you have installed TP Web Connector components, use the TPware management utility to provide information that allows the connection between the ACMS Desktop adapter and the ACMS Desktop adapter gateway. See Section 7.2.4. At runtime, the ACMS Desktop adapter can then find the system on which the ACMS Desktop adapter gateway runs. The ACMS Desktop adapter uses TCP/IP to communicate with the ACMS Desktop adapter gateway.

On an ACMS system on which you have installed the ACMS Desktop adapter gateway component of TP Web Connector, have the ACMS Desktop adapter gateway process running. OpenVMS command procedures are provided to control the process (see Section 8.2). Through information that you supply to the process, the ACMS Desktop adapter gateway receives the call from the ACMS Desktop adapter and invokes the called task on the ACMS system.

# 8.2 Controlling the ACMS Desktop Adapter Gateway

Sections 8.2.1 to 8.2.8 discuss starting and stopping the ACMS Desktop adapter gateway. Section 8.3 discusses specifying ACMS Desktop adapter gateway process quotas.

## 8.2.1 ACMS Desktop Adapter Gateway Starting Requirements

Run the ACMS Desktop adapter gateway under either the user name SYSTEM or another user name with a [1,4] UIC with the following OpenVMS privileges:

- CMKRNL
- NETMBX
- SECURITY (OpenVMS Version 7.1 only)
- SYSLCK
- SYSNAM
- SYSPRV
- TMPMBX

To properly start ACMS Desktop adapter gateway, the user name must be an authorized ACMS agent. Use ACMSUDU to authorize the user name.

## 8.2.2 Editing the System Startup File

To start the ACMS Desktop adapter gateway, use the following command procedure found in the system startup directory:

    SYS$STARTUP:ACMSDA$STARTUP.COM

Add the command line that starts the ACMS Desktop adapter gateway to the OpenVMS system startup file. If you separate the startup procedures into modules, be sure that you add the lines to the correct file.

Position the startup command line for the ACMS Desktop adapter gateway after the line that invokes the ACMS startup command procedure.

Note Start ACMS first and then start the ACMS Desktop adapter gateway.

Starting the ACMS Desktop adapter gateway automatically enables the use of TCP/IP protocols.

The ACMS Desktop adapter gateway supports the use of a parameter file to customize settings at runtime. See Sections 8.2.4 and 8.3.2.

## 8.2.3 Starting the ACMS Desktop Adapter Gateway from DCL

If you need to start the ACMS Desktop adapter gateway at times other than at OpenVMS startup, run the command procedure from the ACMS Desktop adapter gateway account (see Section 8.2.1). Use the following commands to restart the ACMS Desktop adapter gateway:

    $ @SYS$STARTUP:ACMSDA$SHUTDOWN
       .
       .
       .
    $  @SYS$STARTUP:ACMSDA$STARTUP
    %RUN-S-PROC_ID, identification of created process is 42600450
    $

The following example shows the batch startup method, using SYSTEM as the ACMS Desktop adapter gateway account:

    $  SUBMIT/USER=SYSTEM/NOLOG SYS$STARTUP:ACMSDA$STARTUP
    Job ACMSDA$STARTUP (queue SYS$BATCH, entry 1208) started on SYS$BATCH
    $

This command procedure defines some logical names and issues a RUN command to start the ACMS Desktop adapter gateway in a detached process with the correct privileges and a default set of qualifiers specifying the process quotas. To alter the quotas, follow the guidelines given in Section 8.3.2.

If the ACMS system is stopped, requests made through the ACMS Desktop adapter are refused until the ACMS system is available. The ACMSDA$GATEWAY process continues running. It detects when the ACMS system restarts and processes new requests.

If a web client has trouble calling an ACMS task, verify that the ACMSDA$GATEWAY process is running under an account that satisfies the requirements described in Section 8.2.1. If the ACMSDA$GATEWAY process is running under a user name that does not satisfy the requirements, shut down the ACMS Desktop adapter gateway and restart it under the appropriate user name.

## 8.2.4 ACMS Desktop Adapter Gateway Startup Parameter File

The parameter file is a user-specified ASCII text file that lists overrides to ACMS Desktop adapter gateway run-time quotas and defaults. Provided for starting up the ACMS Desktop adapter gateway, the ACMSDA$STARTUP.COM file can read an optional parameter file that you can supply. Digital provides a default parameter file ACMSDA$STARTUP.PRM that you can use as supplied or modify to suit local needs.

The parameter file can contain customized settings such as user name quotas and OpenVMS parameters. The parameter file defines logical names from keywords that determine the ACMS Desktop adapter gateway characteristics according to the following rules:

- The logical names are defined in the process logical name table for the process that invokes the ACMS Desktop adapter gateway startup command procedure.
- If the keywords are not specified or are specified as null, the process logical names are not defined.
- For those keywords that take a value, use an equal sign (=) with or without spaces between the keyword and the value.
- Enclose multiple values between parentheses, separating each value with a comma (,).

Example 8-1 is a sample parameter file.

    !
    ! To select the Port numbers and adapter gateway host
    !
    TCPIP_PORT  = 1024
    !
    ! For Multiple Adapter Gateways for Debugging purposes
    !
    SERVER_NAME             = DBG1
    !
    ! OpenVMS Parameters
    !
    AST_LIMIT               = 100
    BUFFER_LIMIT            = 65535
    ENQUEUE_LIMIT           = 200
    EXTENT                  = 2000
    FILE_LIMIT              = 100
    IO_BUFFERED             = 300
    IO_DIRECT               = 100
    MAXIMUM_WORKING_SET     = 750
    PAGE_FILE               = 100000
    PRIORITY                = 4
    QUEUE_LIMIT             = 20
    WORKING_SET             = 150

Example 8-1 ACMS Desktop Adapter Gateway Startup Parameter File

To specify the parameter file to start the ACMS Desktop adapter gateway in batch mode, use a command in the following format:

`SUBMIT/USERNAME=SYSTEM SYS$STARTUP:ACMSDA$STARTUP /PARAM=SYS$STARTUP:file-name`

The value file-name is the name of the parameter file that you supply. Table 8-1 contains the list of parameters that you can include in this file.

Table 8-1 ACMS Desktop Adapter Gateway Keywords

Keyword | Meaning
--- | ---
SERVER_NAME | Defines a gateway-name extension to distinguish between multiple adapter gateways on the same node. The value is a name of up to 5 characters appended to ACMSDA$SRV to create the process name.
TCPIP_PORT | Defines the number to be used by the adapter gateway for its TCP/IP port. The default is 1022.

## 8.2.5 Specifying the TCP/IP Port Number on the Adapter Gateway

TCP/IP uses numeric port numbers as endpoints of communication. Port number 1023 is the highest unassigned privileged port number. Table 8-2 lists the three categories of port numbers.

Table 8-2 Port Numbers

Category | Port Numbers
--- | ---
Reserved privileged ports | 0 to 255
Privileged ports | 256 to 1023
Nonprivileged ports | 1024 to 65 535

When you use TCP/IP as the network transport, specify a numeric port number as the object to which the ACMS Desktop adapter gateway connects. To assign a TCP/IP port number to the ACMS Desktop adapter gateway, specify TCPIP_PORT_NUMBER in the startup parameter file, which is optionally passed to the ACMS Desktop adapter gateway startup command file. For example:

    TCPIP_PORT_NUMBER=32767

The example assigns the port number 32 767.

## 8.2.6 Specifying the TCP/IP Port Number on the Client

You can specify a TCP/IP port number on a client in the following ways:

- Specify the port number in the TCP/IP BSD services database, in the following format:

`ACMSDA_TCPIP_PORT_hostname 1024/tcp`

- Specify the port number as a system environment variable. For example, if the host node name is `name1` and it uses port number 1024, set the name ACMSDA_TCPIP_PORT_NAME1 to the value 1024.

If you do not define a port number either through the services database or an environment variable, the port number is set to the default value (see Table 8-1).

If an environment variable ACMSDA_TCPIP_PORT_hostname exists, where hostname is the name of the host in which the ACMS Desktop adapter gateway resides, TCP/IP uses this environment variable as the adapter gateway port number for that host. The client connects to the specified port on the system on which the ACMS Desktop adapter is running, which is watched by the ACMS Desktop adapter gateway.

If the port number is specified on both the services database and an environment variable, TCP/IP uses the environment variable. Because the services database entry lists one port number for the type of service, the environment variable allows you to specify a port number for each adapter gateway instead of one port number for all adapter gateway hosts.

For more information, refer to your TCP/IP documentation.

## 8.2.7 Stopping the ACMS Desktop Adapter Gateway Process

To stop the ACMS Desktop adapter gateway process, use the following command procedure found in the system startup directory:

    SYS$STARTUP:ACMSDA$SHUTDOWN.COM

Run the procedure from the account that is authorized as the ACMS agent (see Section 8.2.1). For example:

    $ @SYS$STARTUP:ACMSDA$SHUTDOWN
    $

The command procedure cancels all active tasks, shuts down the ACMS Desktop adapter gateway, and deassigns the logical names. This ensures that the ACMS Desktop adapter gateway process exits properly.

## 8.2.8 Editing the System Shutdown File

To stop the ACMS Desktop adapter gateway process automatically when the OpenVMS system is shut down, edit the system shutdown file located in the system startup directory. Find the following line in the file:

    $  @SYS$STARTUP:ACMSTOP.COM
    $

At any point before the line that stops the ACMS system, add the following command line to the system shutdown file:

    $ @SYS$STARTUP:ACMSDA$SHUTDOWN.COM

The command procedure shuts down the ACMS Desktop adapter gateway properly before the ACMS system shuts down.

# 8.3 Tuning the ACMS Desktop Adapter Gateway

The following sections describe tuning the ACMS Desktop adapter gateway by setting system parameters, overriding quotas, and setting a maximum buffer size.

## 8.3.1 Tuning the ACMS Desktop Adapter Gateway Process

Because the size and nature of the load on the ACMS Desktop adapter gateway varies widely from site to site, monitor the behavior of the adapter gateway process and adjust its parameters and quotas according to the demand placed on it, as you would any OpenVMS process. Section 8.3.2 describes the mechanism to override the default adapter gateway process quotas.

## 8.3.2 Overriding Default Process Quotas

Override the default runtime process quotas for the ACMS Desktop adapter gateway by supplying a file specification on the startup command line.

To use the parameter file to start the ACMS Desktop adapter gateway, modify the startup command line so that it specifies the parameter file. For example:

    $  @SYS$STARTUP:ACMSDA$STARTUP.COM SYS$STARTUP:ACMSDA$STARTUP.PRM

To perform the same function in batch mode from the DCL command line, enter the SUBMIT command. For example:

    $  SUBMIT/USER=SYSTEM/NOLOG SYS$STARTUP:ACMSDA$STARTUP-
    _$  /PARAMETER=(SYS$STARTUP:ACMSDA$STARTUP.PRM)
    Job ACMSDA$STARTUP (queue SYS$BATCH, entry 1209) started on SYS$BATCH
    $

Completely specify the data file; that is, device, directory, name, and type. If the specified data file cannot be accessed, the ACMS Desktop adapter gateway uses default values for process quotas.

The data file contains lines in this format:

`value-name=desired-value`

Example 8-2 shows a sample data file.

    ! Override default values for ACMS Desktop adapter gateway start-up
    !
    Page_file   = 15000
    Working_set = 700       ! Required to support VERY_LARGE application

Example 8-2 ACMS Desktop Adapter Gateway Process Quota Data File

To comment a line, use an exclamation point (!) to introduce the comment text. To make the text readable, use space and tab characters. Table 8-3 shows the values available for overriding.

Table 8-3 ACMS Desktop Adapter Gateway Process Quotas

Process Quota | Summary Description | VAX Default Value1 | Alpha Default Value1
--- | --- | --- | ---
AST_LIMIT | Number of outstanding asynchronous system traps (ASTs) allowed | 100 | 250
BUFFER_LIMIT | Maximum buffered I/O memory (bytes) | 65 536 | 65 536
ENQUEUE_LIMIT | Maximum outstanding locks allowed | 200 | 2 000
EXTENT | Maximum physical memory (pages) | 20 000 | 20 000
FILE_LIMIT | Maximum open files | 100 | 100
IO_BUFFERED | Maximum outstanding buffered I/O operations | 300 | 300
IO_DIRECT | Maximum in-progress direct (disk) I/O operations | 100 | 150
MAXIMUM_WORKING_SET | Working set maximum size (pages) | 750 | 4 000
PAGE_FILE | Maximum reserved pages in page file | 100 000 | 100 000
PRIORITY | Base process priority | 4 | 4
QUEUE_LIMIT | Maximum outstanding timer queue entries | 20 | 20
WORKING_SET | Number of working set pages | 256 | 2 000

1Information about tuning the quotas appears in Section 8.3.1.

For more information on the quotas, refer to the RUN command description in the OpenVMS DCL documentation. Section 8.3.1 describes how to tune some of the quotas for the ACMS Desktop adapter gateway.

## 8.3.3 General Tuning Guidelines

Use the following guidelines for deciding on initial values for quotas.

- When you set initial values for the ACMS Desktop adapter gateway quotas, assume that the adapter gateway is working under the heaviest load you expect. Specifically, in computing buffered I/O limit or page file quotas, compute the quotas for the moment when:

- The maximum number of clients have concurrent task calls outstanding.
- Client programs have task calls outstanding that represent the largest total passed workspace sizes.

The guidelines let you use as much information as you have about your workload. For example, you may know that, although 40 client programs are running, at most 30 have task calls in progress at the same time.

- Alternatively, apply the guidelines assuming that the maximum number of client programs are calling tasks at the same time. This more conservative approach may overestimate the actual required quota values, but it is more tolerant of changes in your workload over time and is easier to analyze.

Index | Contents