DIGITAL TP Desktop Connector
Getting Started


Previous Contents Index

3.4 Exception Information

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.

3.4.1 Exception Class

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:

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 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.


Chapter 4
Preparing ACMS Applications for Client Access

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:

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:

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:

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

Note

Existing parameters and qualifiers for the ACMSADU BUILD GROUP and ACMSADU BUILD APPLICATION commands have not changed from ACMS Version 4.2. Refer to the DIGITAL ACMS for OpenVMS ADU Reference Manual for a listing of existing qualifiers.

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 DIGITAL 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:

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

Note

As indicated by this format, ACMSADU creates an STDL task group specification but applies the ACMS application name as the STDL task group name.

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:

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 TP Desktop 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 system to provide a nonzero UUID. See Section 3.2.
  3. Follow the procedures for the type of client, as follows:

    4.2.6 ACMSADU Extension Restrictions

    ACMSADU has the following restrictions:

    4.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.

    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


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

    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  


    Previous Next Contents Index