EINFO is the STDL mechanism for storing exception information generated during a call. The STDL coding for the EINFO definition is shown in Example 3-1.

Example 3-1 EINFO Data Type Definition

TYPE einfo IS RECORD ECLASS INTEGER; ECODE INTEGER; EPROC TEXT CHARACTER SET SIMPLE-LATIN SIZE 32; EPGROUP TEXT CHARACTER SET SIMPLE-LATIN SIZE 32; ESOURCE INTEGER; ECGROUP UUID; END RECORD;

When an exception is returned to the caller, the following information is available.

• Exception class
• Exception code and exception code group
• Exception level
• Exception source
• Exception location

An exception class is a grouping of exception conditions that is based on the type of recovery action that can be taken and that allows for portable exception handling. The exception class identifies the exception type as a nontransaction exception or as a transaction exception. Each exception class is initially raised as a specific exception type. The exception type can change depending on how the exception is reported.

3.4.2 Exception Code and Exception Code Group

An exception code is a detailed classification of an exception condition. For application-generated exceptions, the exception code is portable and is defined in a message group definition associated with the STDL task group.

3.4.3 Exception Level

An exception level is a classification of exception conditions based on whether the exception was generated by the execution of a called task which propagated the exception to the calling client.

An exception level is defined as either current or propagated. An exception level is defined as current when the current task execution generates the exception and when an exception is encountered during the invocation of a task.

An exception level is defined as propagated when the execution of a task called by the client interface generates the exception. The client program cannot distinguish between a current exception and a propagated exception.

3.4.4 Exception Source

An exception source is a classification of exception conditions based on whether the exception was raised by the application or by the STDL run-time system. A value of zero indicates that the exception was raised by the system. A value of one indicates that the exception was raised by the application.

3.4.5 Exception Location

The exception location consists of the following text fields in EXCEPTION-INFO-WORKSPACE that contain names describing where the exception occurred:

• The name of the task (if the task raised the exception) in which the exception occurred, or an arbitrary string filled in by the application
• The name of the task group (if the task raised the exception) in which the exception occurred, or an arbitrary string filled in by the application

When an exception is raised in a task, the system sets the exception procedure to the task name, and the exception procedure group to the task group name.

3.4.6 Examining Exception Information

Client programs examine the einfo variable upon completion of the TP stub procedure call. The called procedure returns an exception by setting the STDL-defined external variable with agreed-upon standard values and by passing the variable back in a defined workspace. The client program examines the exception data from the einfo record returned as an argument in the TP stub call to determine whether an exception is raised.

1. If ECLASS contains a value of zero, no exception is returned and output arguments are returned.
2. If ECLASS contains a nonzero value, an exception is returned and output arguments are undefined. The ECODE field contains a nonzero value that indicates which exception occurred.
3. If an exception is returned, the client program can examine the ESOURCE field to determine whether the exception was generated by the system (exception source is 0) or by the application (exception source is 1).

TP Desktop Connector software provides an implementation-specific means to check these fields. For example, if the client is written in C, the einfo.h file defines the C structure that the program can access to check status. When an exception is returned to the C program, the EINFO information is available in the einfo structure. The fields in the EINFO data type definition correspond to elements in the einfo structure in C.

Sections 3.4.6.1 and 3.4.6.2 explain the possibilities for error codes in the ECODE field.

3.4.6.1 TPware Error Codes

If the ECODE field contains a value from 01 to 255 (0x01 to 0xff), this signals a TPware runtime exception, or data conversion errors in the output adapter. The TPware runtime exceptions and errors are described in the file stdlrt_msg.h, located in a directory with a name in the following format:

install-directory\stdl\include

For example, if you installed the product in the C:\tpware directory, the STDL message file is located at:

C:\tpware\stdl\include\stdlrt_msg.h

If the client calls an ACMS task, the ECODE field can alternatively contain an ACMS client error code (see Section 3.4.6.2).

3.4.6.2 ACMS Client Error Codes

If the client calls an ACMS task (uses the ACMS Gateway adapter), the ECODE field can contain either a TPware error code (see Section 3.4.6.1) or a value from -3000 to -3199 (0xfffff448 to 0xfffff381). This signals an ACMS Gateway adapter runtime exception. If this is an ACMS error, text related to the error may be found in an argument passed back to the client in the task call (see Section 6.2.1.1).

These exceptions are described in the file acmsdi_client_messages.txt located in a directory with a name in the following format:

install-directory\stdl\include

For example, if you installed the product in the C:\tpware directory, the client message file is located at:

C:\tpware\stdl\include\acmsdi_client_messages.txt

3.5 Running the Application

Before you run the application, see Chapter 9 for setup information.

This chapter describes TP Desktop Connector components on ACMS systems and explains how the components are used so that PC clients can be built to access ACMS applications.

4.1 TP Desktop Connector Components for ACMS Systems

The TP Desktop Connector software includes components that together support the generation and use of PC-based client adapters that access ACMS applications:

• ACMS Application Definition Utility (ACMSADU) extension
  Enables ACMSADU to translate an ACMS application into an STDL task group specification.
• A gateway
  Supports the ACMS RPC between the ACMS Gateway output adapters on the calling system and ACMS systems on the called system.

The TP Desktop Connector components on the OpenVMS system (the ACMSADU extension and the gateway) reside on systems running ACMS software.

The extensions in the modified ACMSADU image enable you to translate an ACMS application to an STDL task group specification. TPware extension commands allow you to control the translation. ACMSADU performs the following TPware functions:

• Extracts information about ACMS tasks and records.
• Translates the extracted information to STDL format.
• Writes the translated information in a form that the STDL compiler can read.

Figure 4-1 shows how ACMSADU reads the application, group, task, and record definitions from the Common Data Dictionary (CDD).

Figure 4-1 ACMSADU Translation Model

ACMSADU produces as output an intermediate group file, from which it produces the STDL task group specification, including record definitions and task group headers with records as arguments.

4.2 Running the ACMSADU Extension

Translating applications from TDL to STDL performs the following operations:

• Group_task translation (see Section 4.2.1)
• Application_group translation (see Section 4.2.3)
• Record definition translation and conversion (see Section 4.2.7)

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

Section 4.2.2 describes the actions that occur during group_task translation, and Section 4.2.4 describes the actions that occur during application_group translation.

4.2.1 Group_task Translation

Group_task translation produces temporary files containing ACMS task and task group information. Group_task translation must be performed for every ACMS group that comprises an application.

Synopsis

The command syntax is:

BUILD GROUP acms_group_name [/STDL]

Description

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

The /STDL qualifier directs ACMSADU to output task and record information that is used for the final translation to STDL. The output file produced by /STDL 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 on DEFAULT TASK GROUP FILE).

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

4.2.2 Actions During Group_task Translation

In the group_task translation operation, ACMSADU produces a file containing intermediate-format group and task information. During group_task translation, ACMSADU performs the following actions:

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

ACMSADU processes the group description and the description of any tasks and records associated with that group. ACMSADU builds descriptions of all records according to the CDD information. Then, ACMSADU 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 ACMSADU writes all this information is used as input to the application_group translation (see Section 4.2.3).

4.2.3 Application_group Translation

Application_group translation reads the group names specified in the application from the CDD and translates the intermediate-format group file built from the group_task translation (see Section 4.2.1).

Synopsis

The command syntax is:

BUILD APPLICATION application_name [/STDL]

Description

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

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

application_name.STDL

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

4.2.4 Actions During Application_group Translation

If the ACMS group has been translated to an intermediate-format group file (see Section 4.2.2), run the ACMSADU BUILD APPLICATION /STDL command to translate the ACMS application to its equivalent STDL task group specification. ACMSADU accesses the CDD to find the group name and reads application information from the CDD including the group name. Then ACMSADU uses the application name to locate and to read the corresponding group temporary file. Next, ACMSADU processes the internal descriptions of the records and writes them in STDL format with duplicate names removed. See Section 4.2.6 for the restrictions.

After each task name is processed, ACMSADU generates the STDL TASK ARGUMENT statement, which includes the task parameters with an indication as to 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 ACMSADU produces is an STDL task group specification that you use in the next stage of development (see Section 4.2.5). Refer to Section 4.2.6 for information on ACMSADU restrictions.

4.2.5 Using the Output of Application_group Translation

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

1. Copy the STDL task group specification to the Windows system on which you have the TP Desktop Connector software installed and to the directory in which you are going to build the client.
2. Edit the STDL task group specification on the Windows system to provide a nonzero UUID. See Section 3.2.
3. Follow the procedures for the type of client, as follows:
   • For the C client, see Chapter 6.
   • For the Automation server, see Section 7.1.

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 is not supported.
  Exchange I/O statements are not supported. Refer to the Compaq ACMS for OpenVMS ADU Reference Manual for information on building no I/O tasks.
• COLUMN MAJOR feature is not supported.
  TP Desktop Connector software 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 software 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 Desktop Connector client calls a LOCAL ACMS task, the runtime system flags the call as an error.

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.

4.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 Gateway adapter makes some conversions at runtime according to the ACMSADU selections. Tables 4-1 to 4-4 summarize the OpenVMS data type support for the TP Desktop Connector Gateway for ACMS. Those data types labeled NOT SUPPORTED are flagged as warnings by the STDL compiler.

Table 4-1 describes integer support.

Table 4-1 Integer Support for the ACMS Gateway 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 4-2 describes floating-point and complex data type support.

Table 4-2 Floating Point and Complex Data Type Support for the ACMS Gateway 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 4-3 describes decimal data type support.

Table 4-3 Decimal Data Type Support for the ACMS Gateway 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

Table 4-4 describes other data type support.

Table 4-4 Other Data Type Support for the ACMS Gateway Adapter

OpenVMS Data Type	STDL Data Type	#Pragma OpenVMS Data Type
DATE	DATE	VMS DATE
VARYING STRING	Not supported