# DIGITAL TP Web Connector
DIGITAL Database Web Connector
Getting Started

Previous | Contents | Index

## 6.2.5 Using the Output of Application_group Translation

Use the STDL task group specification that ACMSADU produces (see Section 6.2.3) for generating the adapters that the application requires. The next steps you take are on the Windows NT platform, as follows:

1. Copy the STDL task group specification to the Windows NT system on which you have TP Web Connector installed and to the directory in which you are going to build the client.
2. Edit the STDL task group specification on the Windows NT system to provide a nonzero UUID. See Section 4.2.
3. Follow the procedures for the type of client, as follows:

- For the C client, see Section 4.3.
- For the Automation server, see Section 4.4.1.

## 6.2.6 ACMSADU Extension Restrictions

ACMSADU has the following restrictions:

- One ACMS task group per application
  Each application is limited to exactly one ACMS task group.
- An ACMS task cannot be renamed in the ACMS application definition.
- Exchange I/O not supported
  Exchange I/O statements are not supported. Refer to the DIGITAL ACMS for OpenVMS ADU Reference Manual for information on building no I/O tasks.
- COLUMN MAJOR feature not supported
  TP Web Connector does not allow the reordering of rows and columns of an array to support the COLUMN MAJOR feature of the CDD.
- Record names must be unique
  All record names within a group must resolve to a unique name. STDL record names are the CDD simple names. If two CDD record names have the same simple name, edit the source code to differentiate the two records.
- All tasks are processed as GLOBAL
  ACMS allows tasks to be identified as LOCAL or GLOBAL in the task, group, and application definitions. For the purposes of STDL translation, all tasks are processed as GLOBAL tasks. Therefore, when you build an application with the /STDL qualifier, all tasks appear in the .STDL file that the ACMSADU utility creates. If a TP Web Connector client calls a LOCAL ACMS task, the runtime system flags the call as an error.

## 6.2.7 Converting Records

ACMS software uses records to allow data to be passed from user agents or forms acting as agents, through the ACMS system to ACMS servers, and back to the caller. These records are buffers containing record-like structures made up of fields. Each field has a name, a data type, and other attributes.

The data descriptions used by ACMS software to describe records are defined by either the CDDL utility in DMU format or the CDO utility in CDO format, and then are placed into the CDD. Record descriptions are extracted from the CDD by various OpenVMS and user programs, including agents, forms systems, the ACMS system, and OpenVMS compilers when compiling ACMS servers. When creating an STDL task group specification from an ACMS application, ACMSADU extracts record descriptions from the CDD and translates them to STDL format.

## 6.2.8 Translating Data Types from OpenVMS to STDL

Fields within the ACMS records all have an OpenVMS data type. During compiling, ACMSADU selects a corresponding STDL data type for each OpenVMS data type that can be expressed in the CDD. Not all OpenVMS data types are represented in STDL, so the ACMS Desktop adapter gateway makes some conversions at runtime according to the ACMSADU selections. Tables 6-1 to 6-4 summarize the OpenVMS data type support for the ACMS Desktop adapter gateway. Those data types labeled NOT SUPPORTED are flagged as warnings by the STDL compiler.

Table 6-1 describes integer support.

Table 6-1 Integer Support for the ACMS Desktop Adapter

OpenVMS Data Type | STDL Data Type | Pragma OpenVMS Data Type
--- | --- | ---
SIGNED BYTE | INTEGER SIZE 1 | none
UNSIGNED BYTE | UNSIGNED INTEGER SIZE 1 | none
SIGNED WORD | INTEGER SIZE 2 | none
UNSIGNED WORD | UNSIGNED INTEGER SIZE 2 | none
SIGNED LONGWORD | INTEGER SIZE 4 | none
UNSIGNED LONGWORD | UNSIGNED INTEGER SIZE 4 | none
SIGNED QUADWORD | ARRAY SIZE 8 OF OCTET | none
UNSIGNED QUADWORD | ARRAY SIZE 8 OF OCTET | none
SIGNED OCTAWORD | ARRAY SIZE 16 OF OCTET | none
UNSIGNED OCTAWORD | ARRAY SIZE 16 OF OCTET | none

Table 6-2 describes floating point and complex data type support.

Table 6-2 Floating Point and Complex Data Type Support for the ACMS Desktop Adapter

OpenVMS Data Type | STDL Data Type | Pragma OpenVMS Data Type
--- | --- | ---
F_FLOATING | FLOAT SIZE 4 | F_FLOATING
D_FLOATING | FLOAT SIZE 8 | D_FLOATING
G_FLOATING | FLOAT SIZE 8 | G_FLOATING
H_FLOATING | ARRAY SIZE 16 OF OCTET | none
S_FLOATING | FLOAT SIZE 4 | none
T_FLOATING | FLOAT SIZE 8 | none
F_FLOATING COMPLEX | RECORD R FLOAT SIZE 4; I FLOAT SIZE 4; END RECORD; | F_FLOATING for each field
D_FLOATING COMPLEX | RECORD R FLOAT SIZE 8; I FLOAT SIZE 8; END RECORD; | D_FLOATING for each field
G_FLOATING COMPLEX | RECORD R FLOAT SIZE 8; I FLOAT SIZE 8; END RECORD; | G_FLOATING for each field
H_FLOATING COMPLEX | ARRAY SIZE 32 OF OCTET | None

Table 6-3 describes decimal data type support.

Table 6-3 Decimal Data Type Support for the ACMS Desktop Adapter

OpenVMS Data Type | STDL Data Type1 | Pragma OpenVMS Data Type
--- | --- | ---
PACKED DECIMAL | DECIMAL STRING SIZE X | PACKED DECIMAL
UNSIGNED NUMERIC | DECIMAL STRING SIZE X | UNSIGNED NUMERIC
LEFT OVERPUNCH NUMERIC | DECIMAL STRING SIZE X | LEFT OVERPUNCH NUMERIC
LEFT SEPARATE NUMERIC | DECIMAL STRING SIZE X | LEFT SEPARATE NUMERIC
RIGHT OVERPUNCH NUMERIC | DECIMAL STRING SIZE X | RIGHT OVERPUNCH NUMERIC
RIGHT SEPARATE NUMERIC | DECIMAL STRING SIZE X | RIGHT SEPARATE NUMERIC
ZONED NUMERIC | DECIMAL STRING SIZE X | ZONED NUMERIC

1The maximum SIZE for the decimal data type is limited to 18.

Table 6-4 describes other data type support.

Table 6-4 Other Data Type Support for the ACMS Desktop Adapter

OpenVMS Data Type | STDL Data Type | Pragma OpenVMS Data Type
--- | --- | ---
DATE | DATE | VMS DATE
VARYING STRING | Not supported |

## 6.2.9 Translation of Another Record and Field Property

Other properties may be defined in the CDD for records and fields. ACMSADU supports translation of the following property to STDL:

OCCURS

The OCCURS field declares fixed-length, one-dimensional arrays.

    OCCURS  n TIMES

# Chapter 7
Managing Applications

This chapter describes:

- The setup of the ACMS Desktop adapter environment on an OpenVMS system (see Section 7.1).
- The TPware management utility on a Windows NT system (see Section 7.2).

# 7.1 ACMS Desktop Adapter Environment

On an OpenVMS system on which a TP Web Connector client calls an ACMS task, the ACMS Desktop adapter can use logical names in the process in which the client runs. The ACMS Desktop adapter recognizes the following logical names:

- STDL_ACMSDA_LOG
  To enable logging and specify a runtime error log for the ACMS Desktop output adapter, define this environment variable with the path and name of the error log file to be produced. Use the error log to diagnose problems with communications between the ACMS Desktop output adapter and the ACMS Desktop adapter gateway process.
- STDL_ACMSDA_PORT_node-name
  To set a TCP/IP port number different from the default (1022), define this logical name with the actual name of the node running the ACMS Desktop adapter gateway process. As the value for the logical name, supply the integer number of the port used on the ACMS Desktop adapter gateway node.
  On the OpenVMS node running the ACMS Desktop adapter gateway process, the startup parameter file must contain a line in the following format:

`TCPIP_PORT=xxx`

where xxx represents decimal digits specifying the port number. If xxx is other than 1022, define the environment variable with the same xxx value. See Section 8.2.5.

# 7.2 Using the TPware Management Utility

The TPware management utility on Windows NT platforms gives you the ability to customize management settings that are specific to your applications and environment.

To invoke the utility, you must have administrator privileges.

Find the TPware management utility in the TPware program group. The utility may have any combination of the following tabs:

- `Computer` for selecting the system on which you want to manage TPware components (see Section 7.2.1)
- `DCE` for setting parameters for the DCE RPC adapter on the computer that you are managing (see Section 7.2.2)
- `Threads` for supplying thread usage semantics for clients running on the computer system that you are managing (see Section 7.2.3)
- `ACMS` for setting parameters for the ACMS Desktop adapter on the computer that you are managing (see Section 7.2.4)

The management tabs available to you depend on the TPware products installed on each node, and on the installed components of each TPware product.

## 7.2.1 Computer Settings

The `Computer` tab allows you to select either the local node or a remote node for management. This option defaults to the local node. To manage a remote node, you must have administrator privileges on that node.

## 7.2.2 DCE RPC Adapter Settings

The `DCE` tab allows you to set options for the DCE RPC adapter used by TP Web Connector to call ACMSxp tasks. The tab appears only if the selected node has DCE support installed. Use this tab to specify the following information:

- The name of the user principal and key file that a DCE client uses to log in to DCE
- The default namespace entry name used to locate other ACMSxp servers

To use DCE key files instead of an interactive login, or to manage processes (such as a web server) in which it is difficult to set environment variables for RPC_DEFAULT_ENTRY, change the DCE settings.

To specify the principal and key file, perform the following steps:

1. Click the `DCE` tab.
2. Check the `Automatically login to DCE` checkbox in the main window.
   Selecting this option causes TP Web Connector to establish the client DCE credentials and to create a thread that refreshes the credentials before they expire. If you leave this option unchecked, TP Web Connector does not perform a DCE login.
3. Enter the full path for the key file name. Clicking the `Browse` button allows you to browse for key files.
4. Click the `Use the following default namespace entry` checkbox to specify the default namespace entry name. TP Web Connector uses the default entry name when the client calls a ACMSxp task server.

TP Web Connector locates ACMSxp servers by searching in the following order for the first entry name specified:

- The default entry name specified in the DCE settings
- The RPC_DEFAULT_ENTRY environment variable

Both the DCE login and default entry settings apply to all programs using DCE RPC adapters on a system regardless of which task group is invoked.

If you change the settings while a DCE client is running, restart the client for the changes to take effect.

## 7.2.3 Threads Settings

Use the `Threads` tab to specify the thread usage semantics for a task group or processing group.

### 7.2.3.1 Thread Usage Semantic Options

TP Web Connector and Database Web Connector give task groups or processing groups the ability to execute calls to a task server or a processing server either on the caller's thread or on a set of dedicated worker threads.

The following are the thread usage semantic options:

- `Execute call on the caller's thread`
  This option is suitable when the user volume is low and you do not need to limit the number of concurrent calls to the server. This is the default usage semantics setting for all input adapters except the asynchronous adapter. If this semantic option is specified for the asynchronous input adapter, the software instead uses the `Execute call on separate thread` option.
- `Execute call on a separate thread`
  This option is suitable when the user volume is low or when the calling thread runs out of stack space under the first option. This option uses more system resources than the first option, because TPware creates as many additional threads as it needs to handle the user load.
  This is the default setting for the asynchronous input adapter. This option is recommended for a client that calls ACMSxp tasks.
- `Execute call on a separate thread, but limit the number of TPware threads`
  This option has the same benefits as the `Execute call on a separate thread` option, but is suitable for servers with high user volume. Using this option, you can set a limit on the number of threads that can be created on the calling end. Limiting the number of TPware threads limits concurrency in the server procedures. For some types of server procedures, this can increase performance.
  In contrast, if you set the `Execute call on a separate thread` option, TPware software creates a separate thread for each concurrent request. The result is that the called server can consume excessive resources and contribute to degraded performance.
  This option is recommended for a client that calls ACMS tasks and can be used for a client that calls ACMSxp tasks.

When the settings of a specified group change, all newly started clients see the changed settings. Clients that are running when the changes take effect do not see the changes. Ensure that you restart all clients that call the group so that the changes take effect.

### 7.2.3.2 Changing Thread Usage Semantics

To change the thread usage semantics for a task group or processing group, perform these steps:

1. Click the `Threads` tab.
2. In the `Group Settings` control panel, click the `New Group` button.
3. Enter the group name in the `New Group` dialog box.
4. After you enter the group name, press `Enter` or click the `Add` button to add the group to the `Group Name` list box. The `New Group` dialog box remains displayed, so that you can enter multiple group names.
5. When you finish entering group names, click the `Done` button or enter an empty group name and press `Enter`.
6. Select a group from the `Group Name` list box to display the thread usage semantics of that group.
   You can change the thread usage semantics by selecting the appropriate radio button. Use the guidelines in Section 7.2.3.1 to set the appropriate semantic option for your application.
   If the new semantic option allows you to limit the number of TPware threads, enter a positive integer value for the thread limit.
7. After you make changes, save them.
   If you changed one group, click on the `Save` button.
8. Restart all clients that call the group so that the changes take effect.

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

### 7.2.3.3 Deleting Thread Usage Semantics

To delete the thread usage semantics setting of a group, do the following:

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

If a group is not listed in the `Group Name` list box, that group has the default semantic option as described in Section 7.2.3.1.

## 7.2.4 ACMS Desktop Adapter Settings

The `ACMS` tab is applicable only to task groups related to the ACMS Desktop adapter. (The ACMS application name corresponds to the STDL task group.) Specify the following settings:

- The TCP/IP node on which the ACMS Desktop adapter gateway resides. Running on an ACMS system, the ACMS Desktop adapter gateway connects the ACMS Desktop adapter in the client on the Windows NT system to the ACMS tasks running on the OpenVMS system.
- The name of the user account on the OpenVMS system that clients use for ACMS calls.
- The password for the OpenVMS user account that clients use for ACMS calls. (The password is not echoed.)

When the settings of a specified group change, all newly started clients see the changed settings. Clients that are running when the changes take effect do not see the changes. Ensure that you restart all clients that call the group so that the changes take effect.

### 7.2.4.1 Configuring a New ACMS Group

To enter a new ACMS task group, perform the following steps:

1. Click the `ACMS` tab.
2. Click the `New Group` button.
3. Enter the group name.
4. Add the group to the `Group Name` list box.
   Press the `Enter` key or click the `Add` button.
5. Select the desired thread usage semantics for the group (see Section 7.2.3.1).
6. If you make any changes, click `Save`.
7. Restart all clients that call the group so that the changes take effect.

Previous | Next | Contents | Index