| Previous | Contents | Index |
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.
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.
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 |
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:
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.
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
|
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
|
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 |
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:
ACMSADU has the following restrictions:
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.
| 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.
| 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.
| 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.
| OpenVMS Data Type | STDL Data Type | #Pragma OpenVMS Data Type |
|---|---|---|
| DATE | DATE | VMS DATE |
| VARYING STRING | Not supported |
| Previous | Next | Contents | Index |