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

2.5.3 Overriding Default Process Quotas

Override the default run-time process quotas for the gateway by supplying a file specification on the startup command line as invoked from system startup:

$ @SYS$STARTUP:ACMSDI$STARTUP SYS$MANAGER:DESKTOP_ACMS_SERVER.DAT

To start the gateway from the DCL prompt, enter this command:

$ SUBMIT/USER=SYSTEM/NOLOG SYS$STARTUP:ACMSDI$STARTUP - _$ /PARAMETER=(SYS$MANAGER:DESKTOP_ACMS_SERVER.DAT) Job ACMSDI$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 gateway uses default values for process quotas.

The data file contains lines in this format:

value-name=desired-value

Example 2-2 shows a sample data file.

Example 2-2 Gateway Process Quota Data File

! Override default values for TP Desktop Connector start-up ! Page_file = 15000 Working_set = 700 ! Required to support VERY_LARGE application

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

Table 2-4 Gateway Process Quotas

Process Quota	Summary Description	VAX Default Value1	Alpha Default Value1
AST_LIMIT	Number of outstanding 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 and DECnet links	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

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

2.5.3.1 General Tuning Guidelines

This section contains guidelines that you can use in deciding on initial values for quotas.

In setting initial values for the gateway quotas, assume that the gateway is working under the heaviest load you expect. Specifically, in the computations for buffered I/O limit or page file quotas, compute the quotas for the moment when:

• The maximum number of clients is signed in.
• Desktop client programs have task calls outstanding that represent the largest total passed workspace sizes.
• Desktop client programs have exchange steps in progress that represent the largest total exchange step workspace sizes.

The guidelines let you use as much information as you have about your workload. For example, you may know that although 40 desktop client programs are signed in, at most 30 have task calls in progress at the same time. Similarly, you may know that although 30 task calls may execute at the same time, at most, 20 have exchange steps in progress at the same time. You could then compute which specific concurrent task calls and exchange steps create the heaviest demand for buffered I/O and page file, and set the gateway quotas accordingly.

Alternatively, apply the guidelines assuming that the maximum number of desktop client programs are calling tasks at the same time, and that each task is executing exchange steps 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.

2.5.3.2 AST Limit

Allow a limit on the outstanding ASTs at least as high as the following number:

ast_limit = 13 + (4 X active_client)

(2-1)

Begin with the following value for the amount of buffered I/O:

buffer_limit = 500 +	å	r_buffers +	å	w_space_c +	å	w_space_x
	clients		calls		x-step

(2-2)

Allow the gateway an open file limit at least as high as the following number:

file_limit = 12 + active_client

(2-3)

Allow a limit on the outstanding buffered I/O operations at least as high as the following number:

io_buffered = 13 + (3 X active_client)

(2-4)

Requirements for page file space depend critically on the maximum workload presented to the gateway. A gateway process run with too small a page file quota exhausts its virtual memory as it tries to allocate space for internal structures. The structures are used to store the desktop client program workspaces to be transferred between the desktop system and the DIGITAL ACMS system.

Allow a page file space at least as high as the following number:

page_file = 2500 +	å	r_buffs + (10 X a_client) +	å	w_sp_c +	å	w_sp_x
	clients		calls		x-step

(2-5)

The optimal working set values for the gateway depend entirely on your workload. A gateway process running with working set values that are too small can begin paging heavily. Although this paging normally does not cause the gateway to fail, performance can degrade quickly, depending on patterns within your workload. Carefully monitor the gateway paging behavior and adjust the memory management quotas accordingly. Start with a WORKING_SET value of 250 pages and a MAXIMUM_WORKING_SET value of 500 pages.

2.5.4 Tuning the Desktop Client Program Buffer Size

Tuning the maximum message buffer size for your application allows you to control network traffic and optimize performance.

2.5.4.1 Setting ACMSDI_MAXBUF on DOS

To define the maximum message buffer size on DOS systems, the TP Desktop Connector software provides the ACMSDI_MAXBUF environmental parameter that is analogous to the ACMSGEN parameter MSS_MAXBUF. If the parameter is set, the value determines the maximum size of a TP Desktop Connector message buffer. If the parameter is not set, the maximum message buffer size defaults to 1024 bytes for DECnet and TCP/IP transports and 512 bytes on NetWare. If application data exceeds the buffer size, the data is segmented and sent as multiple messages.

If memory is scarce on the desktop system, select a smaller maximum buffer size. A smaller maximum buffer size results in increased message traffic if the application data exceeds the maximum buffer size.

To set the ACMSDI_MAXBUF parameter on DOS systems, enter a command with the following syntax, or include it in the system startup file AUTOEXEC.BAT:

SET ACMSDI_MAXBUF=max_msg_size

The variable max_msg_size is the desired maximum message size in bytes, for example, 512. Include the command in AUTOEXEC.BAT to define the parameter at boot time. Alternatively, use a command file to set the parameter and invoke the application.

2.5.4.2 Setting ACMSDI_MAXBUF for OpenVMS Desktop Client Programs

For an OpenVMS desktop client program, set the TP Desktop Connector maximum message buffer size parameter by defining a logical name in a table available to the program. Use the following syntax:

DEFINE ACMSDI_MAXBUF max_msg_size

The gateway determines the desktop client program buffer size dynamically at run time as it reads messages.

2.5.4.3 Setting the Buffer Size on Macintosh Systems

You set the buffer size on Macintosh systems with the connection string parameter, BufferSize. You express the size in either bytes or kilobytes. The maximum buffer size is 32764 bytes; the minimum buffer size is 1024 bytes. The default buffer size is 1024 bytes. For more information on connection string parameters, see Chapter 3.

2.5.5 Running Applications Simultaneously

The DECnet parameter MAXIMUM LINKS on your desktop system controls how many copies of your desktop client program you can run simultaneously. Use the following command on your desktop system to set the value:

NCP DEFINE EXECUTOR MAX LINKS

You need one link for each active file server and one link for each active desktop client program instance. Additional links are not required for multiple sign-ins started in a single desktop client program instance.

2.6 Troubleshooting

Troubleshooting involves gathering information on the OpenVMS system as well as on the desktop system. Follow these steps to gather information on the OpenVMS and desktop systems:

1. Before running your task, activate task audit logging:

   $ ACMS/MODIFY APPLICATION application_name/TASK=AUDIT $ ACMS/SHOW APPLICATION application_name/TASK

   
   This logs any application errors to the audit trail log (ATL).

2. On the desktop system, activate desktop client program error logging.
   If the environment parameter ACMSDI_LOG is defined, the TP Desktop Connector software writes any errors it encounters to an error log. The name of the error log file is determined by the value of the ACMSDI_LOG parameter for the following systems:
   • DOS
     To set the desktop client program error logging parameter on the DOS system, enter a command with the following syntax at the system prompt or in a command file:

     SET ACMSDI_LOG=log_file_name

   • OpenVMS
     To set the parameter on the OpenVMS system, define a logical name using the following syntax:

     DEFINE ACMSDI_LOG log_file_name

   • Macintosh
     Logging is not provided for Macintosh desktop client programs.
   
   One error log file can exist for each invocation of a desktop client program while the parameter is defined. The first time a TP Desktop Connector client service is called, the log file is opened for write access. For each subsequent call to a TP Desktop Connector client service during an invocation of the desktop client program, the file is opened with append access.
3. Run the desktop client program to select the task.
4. Examine client.log and note the time of the error.
   To ensure that the desktop system time is synchronized with the gateway system time, modify the DECnet startup procedure STARTNET.BAT so that the desktop system date and time are set from the gateway node. Add the gateway node name to the NETTIME command using the following syntax:

   NETTIME gateway-node-name

   
   This helps ensure that the time stamps in the desktop client program error log are synchronized with the time stamps in the DIGITAL ACMS audit trail report (ATR) and software event log (SWL).

5. Examine the ATR:

   $ MCR ACMSATR ATR> LIST /SINCE=hh:mm . . . ATR>

6. Examine the SWL:

   $ MCR SWLUP SWLUP> LIST /SINCE=hh:mm/IMAGE=ACMSDI$SERVER . . . SWLUP>

   
   The /IMAGE qualifier restricts the output to messages from the specified image.

7. Try running the task in the DIGITAL ACMS Task Debugger using the desktop client program to select the task (see the DIGITAL TP Desktop Connector for ACMS Client Application Programming Guide).