# DIGITAL TP Web Connector
DIGITAL Database Web Connector
Getting Started

Previous | Contents | Index

# Chapter 4
Building Applications

This chapter discusses the steps for building an interface to your current application or local processing procedures. Also see the on-line instructions for building samples supplied with the TPware software.

# 4.1 Overview of Building Applications

The product you are using determines how you build your application:

- TP Web Connector builds a client interface to an existing TP application executing under ACMSxp or ACMS software.
- Database Web Connector builds a client interface to a local processing procedure executing on the web server.

## 4.1.1 Building a Client Interface to Existing TP Applications

Use TP Web Connector to build client interfaces to existing TP applications. Process each interface with the STDL compiler to produce the correct type of stub, using the adapter flag (`-a`) to specify the input and output adapters (see Chapter 5). The adapter flag causes the STDL compiler to produce a single stub that contains the input and output adapters specified.

For existing ACMS applications, process the TDL source files on an OpenVMS system to produce an STDL-format source file for the application interface. See Chapter 6 for instructions on preparing TDL applications.

The type of client you are writing determines the type of input adapter used.

- If you are writing an Active Server Pages (ASP) client or other Automation client, use an Automation input adapter in the Automation server that you develop.
- If you are writing either an ISAPI client or other standard STDL user-written client in either C or C++, use a C input adapter.

The type of TP application you are accessing determines the output adapter that you specify.

- If the client calls an ACMSxp task, use a DCE output adapter.
- If the client calls an ACMS task, use an ACMS Desktop output adapter.

If the client is accessing a local processing procedure, see Section 4.1.2.

## 4.1.2 Building an Interface to a Local Processing Procedure

Use Database Web Connector to build a local processing procedure to execute within the client process (such as a web server).

If you are using a C client to access local processing procedures, you have the option of executing synchronous or asynchronous calls. Use the STDL compiler to produce an appropriate input adapter. The STDL compiler supports both a C input adapter for synchronous calls and an asynchronous input adapter for asynchronous calls.

If you are using an Automation client to access local processing procedures, use the STDL compiler to produce the Automation input adapter. The STDL compiler supports synchronous calls from an Automation client through an Automation server to local processing procedures linked into the server DLL.

Use the STDL compiler to produce a C output adapter. The stub with the C output adapter connects the client code with the local processing procedures. The control point created by the stub can also limit the size of the worker thread pool to increase performance.

# 4.2 Generating a UUID

If you are developing a client that calls an ACMS task, replace the default zero UUID in your generated STDL task group specification with a valid UUID. To generate a UUID on Windows NT systems, use the `guidgen` application. This can be invoked from either a command line or from the `Tools` menu item in Microsoft Visual C++ V5.0. Select the `Registry Format` and `Copy` to copy the UUID to the Windows NT clipboard. Then paste the UUID into the generated STDL task group specification. After the UUID has been pasted, replace the curly brackets with double quotes.

# 4.3 Writing and Building C Clients

Use TPware to build client programs written in C that can call:

- Tasks in TDL task groups executing under an ACMS system
- Tasks in STDL task groups executing under an ACMSxp system
- Local STDL processing procedures

If the C client program that you are building executes asynchronous calls, see also Section 4.5.

## 4.3.1 Steps for Writing and Building the Client

To build a client program written in C, perform the following steps:

1. Compile one of the following:

- STDL task group specification from an ACMSxp system
- STDL task group specification generated using the ACMSADU utility on the ACMS system (see Section 6.2.3)
- STDL processing group specification from an ACMSxp system

On the STDL compiler command line, use the `-c` flag and the `-a` flag. See Section 5.1 for the complete `stdl` command syntax. Supply the appropriate input adapter and output adapter specifications from those shown in Table 4-1.

Table 4-1 C Client Adapter Specifications

Adapter Type | Specification | Purpose
--- | --- | ---
Input | async | Executes asynchronous calls to local processing procedures
| c | Executes synchronous calls to ACMS tasks, ACMSxp tasks, or local processing procedures
Output | acmsda | Calls ACMS tasks
| c | Calls local processing procedures
| dce | Calls ACMSxp tasks

For example:

      stdl -c -a c:dce test_task_group

The command requests to generate C header files and to use a C input adapter and a DCE output adapter in the generated stub.
The compilation produces files with names in the following format:

`group.h`

`group_c_out-adapter.obj`

The value group is the name of the compiled task group or processing group. The value for either the C or asynchronous input adapter is `c` and the value for out-adapter is one of the values for the specified output adapter types listed in Table 4-1. (If you specify an asynchronous input adapter, `c` appears in the name, not `async`.)

2. Write the client procedures.

1. Include the group.`h` file in source files that contain calls to the tasks or processing procedures. This file contains the function prototypes that define the interface to the tasks or processing procedures and the structure definitions for arguments passed to the called tasks or processing procedures.
   The compiler derives the names of the declared functions (procedures) and structures from the task, processing procedure, or STDL record name by converting the letters to lowercase and replacing any hyphens with underscores.
2. Declare as a structure a variable for each record type used as a parameter to the task or processing procedure.
3. Call the C function (procedure) for the task or processing procedure.
4. Check status.
   After the call to the task or processing procedure, access STDL status using the `einfo` structure. See Section 4.3.2.

3. Compile the client program.
4. Link the following items to produce the client image. This step is the same for C or asynchronous clients.

- The adapter stub object for the task group or processing group, depending on which output adapter you specify:

- If the client calls ACMS tasks:

`group_c_acmsda.obj`

- If the client calls local processing procedures:

`group_c_c.obj`

- If the client calls ACMSxp tasks:

`group_c_dce.obj`

- Client program files

- All of the object files
- Any libraries required by the object files

- The TPware runtime library:

    stdl_rtm.lib

- If the client uses a DCE RPC adapter, link:

- The DCE client stub module with a name in the following format:

`group_dce_cstub.obj`

- The following libraries:

    stdl_dce.lib
    libdce.lib
    pthreads.lib

- If the client uses an ACMS Desktop adapter, the following library:

    stdl_acmsda_client.lib

## 4.3.2 Using the einfo Structure to Check Status

A C client executing either synchronous or asynchronous calls uses the `einfo` structure to check STDL status returned from the called task or processing procedure.

### 4.3.2.1 Error Information Header Files

TPware software provides the following header files for client programs written in C:

- `einfo.h`
  Contains the C structure definition for the `einfo` external variable.
- `eclass.h`
  Equates the symbolic name (class identifier) for each exception class with its exception class value.

The C structure definition for the `einfo` data type definition is shown in Example 4-1.

    #ifndef EINFO_H
    #define EINFO_H
       .
       .
       .
    #define einfo tps_rpc_get_einfo()->info

    typedef struct
      {
      struct
        {
        int    eclass;
        int    ecode;
        char   eproc[32];
        char   epgroup[32];
        int    esource;
        uuid_t ecgroup;
        } info;
      } tps_rpc_einfo_t;

    /* function prototypes */

    tps_rpc_einfo_t *tps_rpc_get_einfo();

    #endif

Example 4-1 C Structure Definition for the einfo Variable

The `eclass.h` header file contains a C `define` statement for each class identifier using the following format:

`#define class-identifier exception-class-value`

For example:

    #define  ap_invocation_fault -3

Sections 4.3.2.2 to 4.3.2.8 provide a summary of exception information.

### 4.3.2.2 Exception Information

The STDL coding for the EINFO definition is shown in Example 4-2.

    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;

Example 4-2 EINFO Data Type Definition

The fields in this data type definition correspond to fields in the `einfo` structure in C. When an exception is returned, the following information is available in the `einfo` structure.

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

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

### 4.3.2.4 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 defined in a message group definition and this code is portable.

### 4.3.2.5 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 or processing procedure which propagated the exception to the C client program.

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 or processing procedure.

An exception level is defined as propagated when the execution of a task or processing procedure called by the C client program generates the exception. A C client program cannot distinguish between a current exception and a propagated exception.

### 4.3.2.6 Exception Source

An exception source is a classification of exception conditions based on whether the exception was raised by the application or by the TP 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.

### 4.3.2.7 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), or processing procedure 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) or processing group 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.

### 4.3.2.8 Examining an Exception Returned

C client programs examine the `einfo` variable upon completion of the TP stub procedure call. An exception is returned by setting the STDL-defined external variables and passing the variables back in a defined workspace. The C client program examines the exception data in the `einfo` external variable returned as an argument in the task 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.
3. If an exception is returned, the C client program can examine `esource` to determine whether the exception was generated by the system (exception source is 0) or by the application (exception source is 1).

# 4.4 Writing Automation Servers and Clients

You can use TPware to generate client programs developed with an Automation language; for example, Visual Basic, VBScript, and JavaScript. These client programs can call:

- Tasks in TDL task groups executing under ACMS
- Tasks in STDL task groups executing under ACMSxp
- Local processing procedures in an STDL processing group

To write an Automation client, follow these general steps:

1. Build an Automation server for the Automation clients to use (see Section 4.4.1).
2. Code the client calls to tasks or processing procedures through the Automation server following the guidelines in Sections 4.4.2 and 4.4.3.

## 4.4.1 Building an Automation Server

Use the STDL compiler to generate stubs containing an Automation adapter. These stubs are used to create Automation servers, which are not the same as STDL servers. The Automation servers created from these STDL-generated stubs are in-process Automation servers. Automation servers convert Automation calls from Automation clients to the type of client calls designated by the output adapter.

To build an Automation server, perform the following steps:

1. Compile one of the following:

- STDL task group specification from an ACMSxp system
- STDL task group specification generated using the ACMSADU utility on the ACMS system (see Section 6.2.3)
- ACMSxp processing group specification from an ACMSxp system

On the STDL compile command line, specify input and output adapters with the `-a` flag. See Section 5.1 for the complete `stdl` command syntax. Use `auto` for the input adapter and supply the appropriate output adapter type from those shown in Table 4-2.

Table 4-2 Automation Server Output Adapter Specifications

Specification | Purpose
--- | ---
acmsda | Calls ACMS tasks
c | Calls local processing procedures
dce | Calls ACMSxp tasks

For example:

      stdl -a auto:acmsda test_task_group

The command requests to use an Automation input adapter and an ACMS Desktop output adapter in the generated stub.
The compilation produces files with names in the following format:

`group_auto_out-adapter.obj`

`group_auto.res`

The value group is the name of the compiled STDL task group or processing group specification and out-adapter on the Automation stub file name is the one of the specified output adapter types from Table 4-2. The `res` file is the type library for the Automation server.

2. If the server calls local processing procedures, compile the processing procedures.
3. Link the following items to produce the Automation server (DLL):

- The adapter stub object for the task group or processing group, depending on the output adapter:

- If the client calls ACMS tasks:

`group_auto_acmsda.obj`

- If the client calls local processing procedures:

`group_auto_c.obj`

- If the client calls ACMSxp tasks:

`group_auto_dce.obj`

- The OLE resource object for the task group or processing group:

`group_auto.res`

- The following libraries:

- `stdl_rtm.lib`
- `stdl_auto.lib`
- `ole32.lib`
- `oleaut32.lib`
- `uuid.lib`

- If the client calls local processing procedures, link the following:

- Processing procedure objects
- Any libraries required by the processing procedures

- If the client requires a DCE RPC adapter (that is, it calls ACMSxp tasks), link the following object module and libraries:

- group`_dce_cstub.obj`
- `stdl_dce.lib`
- `libdce.lib`
- `pthreads.lib`

where group is the name of the task group or processing group.

- If the client requires an ACMS Desktop adapter (that is, it calls ACMS tasks), link the following library:

    stdl_acmsda_client.lib

- Export the following procedures (these are implemented by the Automation server stub):

- `DllGetClassObject`
- `DllCanUnloadNow`
- `DllRegisterServer`
- `DllUnregisterServer`

- Specify the /DLL qualifier to the linker to produce a DLL.

4. After an Automation server is built, register it with COM using `regsvr32` to allow it to be used by a client application. For example:

      regsvr32 test_task_group_auto_acmsda.dll

This `regsvr32` command on the Automation DLL registers the type library. The name of the type library is in the following format:

`group_Type_Library`

The variable `group` is the name of the task group or processing group specification. For example, registering the `test_task_group` Automation server assigns the type library name as follows:

    test_task_group_Type_Library

If you rebuild an Automation server and change the STDL task group specification, STDL processing group specification, or records used, you must first uninstall the original server with `regsvr32` and the `/u` flag.

Previous | Next | Contents | Index