# Compaq ACMS for OpenVMS
Managing Applications

Previous | Contents | Index

## A.5.4 Calculating the Value of MSS_POOLSIZE

MSS_POOLSIZE is the maximum amount of memory that can be used to send messages. ACMSPARAM.COM calculates this parameter as follows:

    MSS_POOLSIZE = ( ( (56 * MSS_MAXOBJ)
                     + (144 * MAXPROCESSCNT)
                     + (MSS_MAXBUF * TOTAL_TK_INSTANCE_CNT)
                     + (TERMINAL_CNT * 128)
                     + (TOTAL_SP_CNT * 64)
                     + (OPERATOR_CNT * 5120)
                     + 567)
                     / 512) + 32

    MSS_POOLSIZE = MSS_POOLSIZE + (MSS_POOLSIZE/10)

## A.5.5 Calculating the Value of MSS_PROCESS_POOL

MSS_PROCESS_POOL defines the size of the ACMS internal message switch process local pool. ACMSPARAM.COM calculates this parameter as follows:

    For an application node:

    MSS_PROCESS_POOL = ((MSS_MAXBUF * 2 * REMOTE_SUB_CNT) / 512) + 32

    For a submitter node:

    MSS_PROCESS_POOL = (((MSS_MAXBUF * 2 * REMOTE_APPL_CNT) / 512) * 4) + 32

The value of MSS_PROCESS_POOL must be at least 256.

If the node is both an application node and a submitter node, the command procedure uses the higher of the two values calculated in the previous example.

## A.5.6 Calculating the Value of PERM_CPS

PERM_CPS sets the number of permanently active Command Processes. The default value is 1.

To increase the effective value of PERM_CPS, you may also need to change the value of the parameter MAX_LOGINS or MAX_TTS_CP.

The effective number of permanently active Command Processes is the lesser of:

- The value for the PERM_CPS parameter
- The result of the MAX_LOGINS value divided by the MAX_TTS_CP value

At startup, when ACMS computes the maximum number of Command Processes the system might need, ACMS divides the value of MAX_LOGINS by the value of MAX_TTS_CP. For example, if you defined MAX_LOGINS as 60 and MAX_TTS_CP as 20, ACMS would never set up more than three Command Processes. In this case, if the PERM_CPS value is greater than 3, ACMS ignores the PERM_CPS value. ACMS does not start more command processes than all of your terminal users can use.

Once the value you set for the PERM_CPS parameter reaches the result of MAX_LOGINS divided by MAX_TTS_CP, merely increasing the value of the PERM_CPS parameter has no effect. To increase the effective value of PERM_CPS further, you must also increase the value of the MAX_LOGINS parameter or decrease the value of the MAX_TTS_CP parameter. This situation is unusual, however. There is no reason to increase the number of permanent Command Processes to more than you need to service all terminal users. In most cases, set the number of permanent Command Processes to a value adequate for handling your common number of users.

## A.5.7 Calculating ACMS Workspace Pools

When you start an application, ACMS allocates a number of shared and private memory pools to hold the data and control structures associated with the workspaces used by the tasks in your application. Calculate the amount of space your application requires in these pools so that ACMS can allocate sufficient memory to hold the data and control information.

### A.5.7.1 Types of Workspace Pools

The four types of ACMS workspace pools are listed in Table A-6 with their default values.

Table A-6 Types of ACMS Workspace Pools
| Default Value
--- | ---
Type | VAX | Alpha
Task instance workspace control pool | 50 pages | 50 pagelets
Task instance workspace pool | 350 pages | 1600 pagelets
Workspace pool | 256 pages | 256 pagelets
Control pool | 128 pages | 128 pagelets

ACMS allocates a task instance workspace pool and a task instance workspace control pool for each task group in your application. These pools are used to hold data and control information for active task instances in their respective groups and are shared by the EXC process and the server processes.

ACMS also allocates a workspace pool and a workspace control pool to hold workspace data and control information associated with the master copies of group and user workspaces. These two pools are used by all the task groups in the application and are allocated in the private memory of the EXC process.

### A.5.7.2 Workspace Pool Allocation Failures

There are four conditions under which ACMS fails to allocate blocks of memory from workspace pools:

- There is insufficient free space within the pool to satisfy the request.
- There is insufficient free contiguous space within the pool to satisfy the request. In this case, there may be sufficient total free space; however, there is no single free block that is large enough to accommodate the request.
- A request is made to allocate a single block whose size exceeds 65,536 bytes. Since ACMS only allocates blocks of memory in powers of 2 up to and including 65,536 bytes long, redesign your task to use fewer or smaller workspaces.
- A request is made to allocate a block that would cause the total amount of pool allocated to exceed the total size of the pool.

The EXC cancels a task during the task-initialization phase if it is unable to allocate sufficient space within one of the workspace pools. The error reported is "Error starting task: Unable to allocate workspace resources, please try later" on the user's terminal. Information about the task cancellation is written to the Audit Trail Log. The entry includes the following information:

    "Error allocating {number} bytes in TWSC pool {workspace-pool-name} for workspaces"

See Chapter 12 for information about the audit trail record generated by this error.

Use the ACMS/SHOW APPLICATION/POOL command to determine the amount of free space within the workspace pools that are being used by your applications. This display also shows the size of the largest block that may be allocated from the pool. If you find that there is sufficient free space to satisfy a request, but that the free space is not contiguous, then this is an indication that the free space inside the workspace pools has become fragmented. Increasing the amount of memory allocated to the pool solves this problem and allows ACMS to better manage the free space within the pool.

### A.5.7.3 ACMS Workspace Pool Requirements

The following sections describe how to calculate the amount of space required in each of the four types of workspace pools.

ACMS reserves the first page (VAX) or pagelet (Alpha) in each pool for pool control structures. Before allocating a block of memory from a pool, ACMS rounds the size of the requested block up to the next highest power of two. ACMS uses this allocation algorithm to reduce the possibility of pool fragmentation and to provide a fast pool-space allocation time. When calculating the amount of space required by a task, take this information into account.

For example, you calculate that a task requires a block of 956 bytes from the task instance pool for six task workspaces and three system workspaces. You then calculate that these nine workspaces require a block of 196 bytes (52 + ( 16 * 9) ) from the task instance control pool. Both these figures must then be rounded up to the next highest power of two. In this example, the task requires 1024 bytes from the task instance workspace pool and 256 bytes from the task instance workspace control pool.

#### A.5.7.3.1 Task Instance Workspace Pool Requirements

Each task instance requires a block of this pool equal to the sum of the sizes of the system workspaces (519 bytes) and the sum of the sizes of the task, user, and group workspaces used by the task.

#### A.5.7.3.2 Task Instance Control Pool Requirements

Each task requires a block of this pool large enough to hold:

- 52 bytes of task workspace header information. This structure contains information needed by ACMS to identify the owner of the workspaces and to map the task instance workspace block in the task instance workspace pool.
- 16 bytes of control information for each task, user, group, and system workspace. ACMS uses these structures to locate each individual workspace owned by a task instance and to point to the master copies of any group and user workspaces referenced by a task instance.

ACMS allocates blocks from these two pools at the beginning of a task instance and frees the blocks at the end of the task instance.

Group and user workspaces require additional overhead information. Memory for this information is allocated from the workspace pool and the control pool. The amount of additional pool required depends on the type of workspace involved.

#### A.5.7.3.3 Group Workspace Pool Requirements

Because group workspaces can be shared among instances of different tasks within a task group, they require more control information to be kept.

The first time a group workspace is accessed within a task group, a 24-byte workspace descriptor is allocated from the control pool. Space must also be allocated from the workspace pool to contain the master copy of the workspace.

When a task that uses a particular group workspace is initiated, the master copy is moved into a local copy for the exclusive use of the task instance. When the task instance ends, the master copy of each group workspace that allows updating is updated from these local copies.

Therefore, the overhead for group workspaces is 32 bytes (24 bytes rounded up to the next power of two) from the control pool, plus an amount of workspace pool equal to the size of the group workspace. This value is rounded up to the next power of two.

Once allocated, the overhead pool for group workspaces is released only when the application is stopped. ACMS reserves an 8-byte block to hold a header for the queue of all the group workspaces in an application.

#### A.5.7.3.4 User Workspace Pool Requirements

User workspaces are maintained on a per-submitter basis, so master copies of user workspaces must be maintained for each submitter.

The first time a submitter accesses a user workspace, a 48-byte workspace submitter block must be allocated from the control pool. This block contains the header for the queue of master copies of user workspaces for this submitter. It also contains some submitter identification.

The first time a user workspace is used by a submitter, a 24-byte workspace descriptor is allocated from the control pool. Enough workspace pool must be allocated to contain the master copy of this user workspace. The workspace descriptor points to the master copy and is queued to the submitter block.

When the user workspace is referenced, the master copy is used to initialize a local copy that is provided to the task instance. When the task ends, the master copy of each user workspace is updated, if necessary, from the local copy.

The overhead for user workspaces is:

- One 64-byte block (48 bytes rounded) of control pool for each submitter
- One 32-byte block (24 bytes rounded up to the next power of two) of control pool for each user workspace used for each submitter
- Enough workspace pool to contain the master copy of each user workspace used, rounded up to the next power of two

This "overhead" pool is released when the submitter signs out.

ACMS reserves an 8-byte block to hold a header for the queue of all the group workspaces in an application.

### A.5.7.4 Calculating Workspace Pool Sizes

This section describes how to calculate values for the following workspace pool parameters:

- TWS_POOLSIZE
- TWSC_POOLSIZE
- WS_POOLSIZE
- WSC_POOLSIZE

This section also provides information about defining logical names to size the workspace pools to set values for these parameters on a per-application basis.

#### A.5.7.4.1 Calculating the Value of TWS_POOLSIZE and TWSC_POOLSIZE

ACMSPARAM.COM calculates the ACMSGEN parameters TWS_POOLSIZE and TWSC_POOLSIZE as follows:

    Calculate for each TDB and use the highest value:

    TWS_POOLSIZE = (Pagesize + (wksp_size_sum * TOTAL_TK_INSTANCE_CNT)) / 512

    where:
       wksp_size_sum = ((sum of group workspace sizes +
                        (sum of user workspace sizes +
                        (sum of task workspace sizes)
                          rounded to next power of 2)

       Pagesize is the CPU-specific page size (in bytes) of the VAX or
       Alpha system.

    Calculate for each TDB and use the highest value:

    TWSC_POOLSIZE = (512 + (wksp_factor * TOTAL_TK_INSTANCE_CNT)) / 512

    where wksp_factor = (52 + (16 * wksp_cnt_sum)) rounded up to the
                        next highest power of 2.

          wksp_cnt_sum = (number of group workspaces in TDB)+
                         (number of user workspaces in TDB) +
                         (number of task workspaces in TDB)

The ACMSPARAM.COM calculations are estimations. If you wish to determine more accurately the value of the TWS_POOLSIZE and TWSC_POOLSIZE parameters, calculate the amount of pool required by each task group in each application on your system, and select the highest value from each calculation.

To calculate the size of each pool required by each task group, you need to consider how many users will be simultaneously executing each task in the task group. After calculating the workspace pool requirements of each task, multiply these values by the number of users who will be running those tasks simultaneously.

Use the following formula to determine the value for the TWS_POOLSIZE parameter for each task group in each application:

    (Pagesize                         ! pool control and management overhead
    + ( t-1 * s-1 )
    + ( t-2 * s-2 )
    + [...]
    + ( t-n * s-n ) )/512

    where:
        Pagesize is the CPU-specific page size (in bytes) of the VAX or
        Alpha system.

        t-n = (the greater of the following:
              a) sum of sizes of workspaces used by task 'n' rounded up to
                 the next power of 2
              b) the CPU-specific page size))

        s-n = <number of submitters simultaneously executing task 'n'>

Use the following formula to determine the value for the TWSC_POOLSIZE parameter for each task group in each application:

    (512                          ! pool control and management overhead
    + ( c-1 * s-1 )
    + ( c-2 * s-2 )
    +  [...]
    + ( c-n * s-n ) )/512

    where:
        c-n = ( 52 + ( 16 * <number of workspaces used by task 'n'> ) )
               rounded up to the next power of 2
        s-n = <number of submitters concurrently executing task 'n'>

#### A.5.7.4.2 Calculating the Value of WS_POOLSIZE and WSC_POOLSIZE

ACMSPARAM.COM calculates the ACMSGEN parameters WS_POOLSIZE and WSC_POOLSIZE as follows:

    Calculate for each application and use the highest value:

    WS_POOLSIZE = (512 +
                   grp_wksp_size_sum +
                   (user_wksp_size_sum + TOTAL_TK_INSTANCE_CNT)) / 512

    where grp_wksp_size_sum = sum of: each group workspace size
                              rounded up to the next highest power of 2
          user_wksp_size_sum = sum of: each user workspace size
                               rounded up to the next highest power of 2

    Calculate for each application and use the highest value:

    WSC_POOLSIZE = (512 +
                    (16 * (number of TDBs in application)) +
                    (32 * (number of group workspaces in all TDBs in application))+
                    (64 * TOTAL_TK_INSTANCE_CNT) +
                    (32 * TOTAL_TK_INSTANCE_CNT)) / 512

The ACMSPARAM.COM calculations are estimations. If you wish to determine more accurately the value of the WS_POOLSIZE and WSC_POOLSIZE parameters, calculate the amount of pool required by each application on your system and select the highest value from each calculation.

To calculate the size of each pool required by each application, consider how many group and user workspaces are used concurrently in each application.

Use the following formula to determine the value for the WS_POOLSIZE parameter for each application:

    (512                        ! pool control and management overhead
    + ( g-1 + g-2 + [...] + g-n )
    + ( u-1 * s-1 )
    + ( u-2 * s-2 )
    + [...]
    + ( u-n * s-n ) )/512

    where:
        g-n = <size of group workspace 'n'> rounded up to the next power of 2
        u-n = <size of user workspace 'n'> rounded up to the next power of 2
        s-n = <number of submitters accessing user workspace 'n'>

Use the following formula to determine the value for the WSC_POOLSIZE parameter for each task group in each application:

    (512                            ! pool control and management overhead

    + ( 16 * < number of groups     ! group workspace and submitter list control
            in the application> )   ! structures

    + ( 32 * < sum of number of     ! group workspace control blocks
        group workspaces used in
        each task group in the
        application> )

    + ( 64 * < number of submitters ! submitter control blocks
        accessing user workspaces
        in the application> )

    + ( 32 * s-1 )                  ! user workspace control blocks

    + ( 32 * s-2 )                  ! user workspace control blocks

    + [...]

    + ( 32 * s-n ) )/512            ! user workspace control blocks

    where:
        s-n = number of submitters accessing user workspace 'n'

#### A.5.7.4.3 Defining Logical Names for Workspace Pool Sizes

You can define the following logical names to size the workspace pools on a per-application basis:

- ACMS$EXC_WS_POOLSIZE
- ACMS$EXC_WSC_POOLSIZE
- ACMS$EXC_TWS_POOLSIZE
- ACMS$EXC_TWSC_POOLSIZE

You can define the logical names at any DCL level where the executable can translate them. To make them application-specific, reference logical names in the application definition or in a name table associated with an application. The following example shows referencing two of the logical names in the application definition:

     APPLICATION LOGICAL NAMES ARE
         ACMS$EXC_TWS_POOLSIZE = "1750",
         ACMS$EXC_TWSC_POOLSIZE = "75";

The EXC allows one additional translation of the logical name so that an application definition does not have to be rebuilt to change a value. For example:

> In the Application Definition Utility (ADU):

>      APPLICATION LOGICAL NAMES ARE
>          ACMS$EXC_TWS_POOLSIZE = "ACMS$EXC_<appl_name>_TWS_POOLSIZE";

> At DCL level:

>      $ DEFINE/SYSTEM ACMS$EXC_<appl_name>_TWS_POOLSIZE  "1750"

In the preceding examples of the additional logical name definitions,
<appl_name> is the name of the application.

Remember the following about using these logical names:

- The logical name (or the translation of it) must contain a valid decimal number (in pages for VAX, pagelets for Alpha).
- ACMS uses the ACMSGEN parameters if the logical cannot be translated or the logical contains an invalid value or character.
- As with any value specified by ACMSGEN, if the value contained in one or more of the logicals is too high, the application will not start.
- The ACMSPARAM and ACMEXCPAR procedures will not have any knowledge of the changes made to the workspace pools by using these logicals. Any calculations done by these procedures will reflect the values in ACMSGEN.

Previous | Next | Contents | Index