This appendix describes how to use components of Compaq TP Web Connector, including the ADU extension, to provide Windows NT clients with access to ACMS applications.

An application is a set of related tasks that solve a business problem and that can be started or stopped as a unit. An application definition consists of a set of clauses you use to define control attributes for tasks, servers, and the application execution controller that manages the server processes in which tasks run. The general format for an application definition is:

<application-clause> [...] END DEFINITION ;

The two clauses you must include in an application definition are TASK GROUPS and APPLICATION USERNAME. The TASK GROUPS clause names the task groups that define the tasks of the application. The APPLICATION USERNAME clause defines the user name under which the application execution controller runs.

If you want to provide access to the application from Windows NT clients (the clients call ACMS tasks), including clients on the World Wide Web (web), you can do so using the components of Compaq TP Web Connector Gateway for ACMS software, including the ADU extension.

G.1 Access By NT Clients

The components of the Compaq TP Web Connector Gateway for ACMS software on ACMS systems can be used so that Windows NT clients, including clients on the World Wide Web (web), can be built to access ACMS applications. The TP Web Connector Gateway for ACMS software is part of the Compaq TP Web Connector product, one of the products created from Compaq TPware technology. The Compaq TPware software produces objects that you can easily use to connect a web server to your application. The Compaq TP Web Connector product allows Microsoft Transaction Server (MTS) applications and web servers to call ACMS tasks, ACMSxp tasks, or Structured Transaction Definition Language (STDL) tasks running under Compaq Portable TP for Windows NT.

If your client is going to call ACMS tasks, use the components of the Compaq TP Web Connector Gateway for ACMS software on the ACMS development system where the ACMS application is defined. The following topics discuss the Compaq TP Web Connector Gateway for ACMS components and preparing ACMS applications for client access. For more information about Compaq TPware technology and Compaq TP Web Connector capabilities, see Compaq TP Web Connector Getting Started.

G.2 TP Web Connector Gateway Components

If your client calls ACMS tasks, use the Compaq TP Web Connector Gateway for ACMS components that you install and run on an ACMS system. The Compaq TP Web Connector Gateway for ACMS software includes the following components that support the generation and use of Windows NT clients that access ACMS applications:

• ACMS ADU extension
  Enables ADU to translate ACMS task headers and associated record and field definitions into an STDL task group specification with associated data type definitions and STDL record definitions.
• A gateway
  Supports the ACMS RPC protocol between the TP Desktop Connector (formerly ACMS Desktop) output adapters on the calling system and ACMS applications on the called system.

The Compaq TP Web Connector Gateway for ACMS components (the ADU extension and the gateway) reside on OpenVMS systems running ACMS software. The components can be on the same ACMS system or on different ACMS systems (see Compaq TP Web Connector Gateway for ACMS Installation Guide).

G.2.1 ADU Extension

The extension in the modified ADU image enables you to translate ACMS task headers and associated record and field definitions into an STDL task group specification with associated data type definitions and STDL record definitions. Compaq TPware extension commands allow you to control the translation. ADU performs the following Compaq TPware functions:

• Extracts the ACMS application, task group, task, and record definitions from the Common Data Dictionary (CDD).
• Processes the extracted information and translates the task headers and associated record and field definitions to STDL format.
• Writes the translated information in a form that the STDL compiler can read.

As directed by the extension commands, ADU produces, as output, task group information in an intermediate binary file, from which ADU produces the STDL task group specification, with STDL record definitions and task group headers with records as arguments.

G.2.2 Gateway

The gateway runs on an ACMS system and connects the ACMS Desktop adapter on a Windows NT system to the ACMS system on which the target application is running. You provide information that enables the connection between your client program and the ACMS tasks being called. Use command procedures provided with the software to control and manage the gateway. For information about enabling the connection and about using the command procedures, see Compaq TP Web Connector for ACMS Getting Started.

G.3 Running ADU Extension

Translating the necessary ACMS application information from TDL format to STDL format requires the following operations:

• Group_task translation
• Application_group translation
• Record definition translation and conversion

You perform these operations in ADU with TPware qualifiers for the BUILD GROUP and BUILD APPLICATION commands.

Group_task translation produces a temporary binary file containing ACMS task and task group information. Group_task translation must be performed for the ACMS task group that comprises the application.

G.3.1.1 BUILD GROUP Command

The command syntax is:

BUILD GROUP acms_group_name [/STDL]

The acms_group_name parameter refers to the name of the ACMS task group.

The /STDL qualifier directs ADU to output task and record information that is used for completing the translation to STDL format. The output file produced by the /STDL qualifier has a name in the following format:

GROUP.WDB

The .WDB file type indicates the intermediate-format web database file. The BUILD GROUP command writes the file to the default directory (see the Compaq ACMS for OpenVMS ADU Reference Manual for information about the ADU task group definition clause DEFAULT TASK GROUP FILE).

The /NOSTDL qualifier instructs ADU not to produce the intermediate-format file. The default qualifier is /NOSTDL.

G.3.1.2 Translation Actions

In the group_task translation operation, ADU produces a file containing intermediate-format task group and task information.

During group_task translation, ADU performs the following actions:

• Reads information from the CDD.
• Processes the read information.
• Creates the intermediate-format file.

ADU processes the task group description and the description of any tasks and records associated with that group. ADU builds descriptions of all records according to the CDD information. Then, ADU creates a description of all tasks in the group along with the names of records used as parameters to those tasks. The intermediate-format file in which ADU writes all this information is used as input to the application_group translation.

G.3.2 Application Group Translation

Application_group translation reads the task group name specified in the application and translates the intermediate-format task group file built from the group_task translation.

G.3.2.1 BUILD APPLICATION Command

The command syntax is:

BUILD APPLICATION application_name [/STDL]

The parameter application_name refers to the name of an ACMS application.

The /STDL qualifier directs the translator during the processing initiated by the ADU BUILD APPLICATION command to generate STDL code using the intermediate-format group file that was created during the ADU BUILD GROUP processing. The output is a file with a name in the following format:

application_name.STDL

ADU generates in the default directory an STDL source file containing a task group specification and related data type and record definitions. The output file name application_name is derived from the ACMS application name. You use this file to create the client interface.

G.3.2.2 Translation Actions

If the ACMS task group information has been translated and written to an intermediate-format task group file (see the Group_Task_translation help topic and its Translation_actions subtopic), use the ADU BUILD APPLICATION /STDL command to translate the intermediate-format information to STDL format. ADU processes the internal descriptions of the records and fields and writes them in STDL format with duplicate names removed (see the Restrictions help topic for the ADU extention restrictions).

After each task name is processed, ADU generates the STDL TASK ARGUMENT statement, which includes the task parameters and an indication about whether they are input or output. The arguments are as follows:

• A record containing a text field of 256 characters for the selection string as an input argument.
• A record containing a text field of 80 characters for the extended status as an output argument.
• Any argument(s) defined in the TDL task definition, in order.

The resulting file that ADU generates contains an STDL task group specification with associated data type definitions and STDL record definitions that you use in the next stage of development (see the Using_translation_output help topic).

G.3.2.3 Using Translation Output

To generate the adapters for the client, use the file containing the STDL task group specification and associated data type definitions and STDL record definitions that ADU generates (see the Application_Group_translation help topic). The next steps you take are on the Windows NT platform, as follows:

1. Copy the file that contains the STDL task group specification to the Windows NT system on which you have the Compaq TP Web Connector product 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, as follows:
   1. Invoke guidgen from either a DOS command line or the guidgen application.
   2. Select the Registry Format menu and Copy command to copy the UUID to the Windows NT clipboard.
   3. Paste the UUID into the generated STDL task group specification.
   4. After you paste the UUID, replace each brace (left brace ({) and right brace (})) with double quotation marks (").
   
   
3. Follow the procedures for writing and building the client, depending on the type of client: C, asynchronous, or Automation server. For information about the procedures, see Compaq TP Web Connector Getting Started.

G.3.3 Restrictions

• Each application is limited to exactly one ACMS task group.
• An ACMS task cannot be renamed in the ACMS application definition.
• Exchange I/O statements are not supported. All records must appear as task arguments. Refer to the Compaq ACMS for OpenVMS ADU Reference Manual for information about building no I/O tasks.
• The Compaq TP Web Connector software does not allow the reordering of rows and columns of an array to support the COLUMN MAJOR feature of the CDD.
• 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 ACMS 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 ADU utility creates. If a Compaq TP Web Connector client calls a local ACMS task, the runtime system flags the call as an error.

The ACMS software uses records to allow data to be passed from user agents or from 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 with associated data type definitions and STDL record definitions to translate an ACMS application's task group information, ADU extracts record descriptions from the CDD and translates them to STDL format.

G.3.5 Data Type Translation

Fields within the ACMS records all have an OpenVMS data type. For OpenVMS data types that at runtime need to be converted to STDL data types, ADU creates the #Pragma statements in the generated data type definitions. During processing, ADU 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 output adapter makes some conversions at runtime according to the ADU selections. The tables in the following help topics summarize the OpenVMS data type support for the Compaq TP Web Connector Gateway for ACMS software. The data types labeled Not Supported are flagged as warnings by the STDL compiler.

G.3.5.1 Integer Support

The following table summarizes integer OpenVMS data type support for the Compaq TP Web Connector Gateway for ACMS software.

OpenVMS	STDL	OpenVMS Pragma
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

G.3.5.2 Floating Point and Complex Support

The following table summarizes floating point and complex OpenVMS data type support for the Compaq TP Web Connector Gateway for ACMS software.

OpenVMS	STDL	OpenVMS Pragma
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

G.3.5.3 Decimal Support

The following table summarizes decimal OpenVMS data type support for the Compaq TP Web Connector Gateway for ACMS software.

OpenVMS or OpenVMS Pragma	STDL
PACKED DECIMAL	DECIMAL STRING SIZE X
UNSIGNED NUMERIC	DECIMAL STRING SIZE X
LEFT OVERPUNCH NUMERIC	DECIMAL STRING SIZE X
LEFT SEPARATE NUMERIC	DECIMAL STRING SIZE X
RIGHT OVERPUNCH NUMERIC	DECIMAL STRING SIZE X
RIGHT SEPARATE NUMERIC	DECIMAL STRING SIZE X
ZONED NUMERIC	DECIMAL STRING SIZE X

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

G.3.5.4 Other Support

The following table summarizes other OpenVMS data type support for the Compaq TP Web Connector Gateway for ACMS software.

OpenVMS	STDL	OpenVMS Pragma
DATE	DATE	VMS DATE
VARYING STRING	Not Supported

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

OCCURS

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

For example:

OCCURS n TIMES