# Compaq TP Desktop Connector
Getting Started

Previous | Contents | Index

### 6.2.2.1 Additional ACMS to C Data Type Support

If you are developing a client to call an ACMS application, additional data types are supported. The ACMSADU provides compilation support for some OpenVMS data types and the ACMS Gateway adapter provides runtime support (see Section 4.2.8). Data types in addition to those supported by STDL are supported for writing clients for ACMS applications, as shown in Table 6-4.

Table 6-4 Mapping of Additional ACMS Data Types to C Data Types
STDL | C
--- | ---
DATE | char[17]
FLOAT SIZE 4 | float
FLOAT SIZE 8 | double
INTEGER SIZE 1 | char
INTEGER SIZE 2 | short
INTEGER SIZE 4 | int
UNSIGNED INTEGER SIZE 1 | unsigned char
UNSIGNED INTEGER SIZE 2 | unsigned short
UNSIGNED INTEGER SIZE 4 | unsigned int

## 6.2.3 Structures for STDL Data Types

C definitions of STDL data types have the format shown in Example 6-1.

Example 6-1 C Representation of an STDL Data Type Definition

`struct data-type-identifier { c_mapping_for_field_type field-1-name ; c_mapping_for_field_type field-2-name ; . . . } ;`

The data type identifier from the STDL data type definition is used as the name of the C structure tag. Each field definition within the STDL record is a named member of the C structure. The order and number of the members of the structure within the C include file match the order and number of the field definitions in the STDL definition.

A field definition that refers to a previously defined data type identifier has the following format:

`struct data-type-identifier field-name.`

All comments in the data type definition appear in the generated C header file.

The STDL compiler represents DEPENDING ON as an array definition with the number of repetitions being defined by the application program, as follows:

`TYPE rec_id IS RECORD number_id INTEGER ; array_id ARRAY SIZE n TO m DEPENDING ON number_id OF type ; END ;`

The n and m represent numbers. Simple arrays within structures (records) are not null terminated.

## 6.2.4 STDL Identifier to C Identifier Conversion

The C identifiers are derived from the corresponding STDL identifiers according to the following rules:

- All uppercase Latin characters are converted to lowercase.
- Hyphens (-) are converted to underscores (_).
- No other characters are changed.

The C language does not support Kanji characters in identifiers.

# 6.3 Specifying the Call Attributes String

The C client passes a call attributes string to the C input adapter using a procedure generated by the STDL compiler. The function declaration for specifying the call attributes string is:

`group_set (char * attributes_string)`

The value for group is the converted name of the task group. The attributes_string represents values passed to the output adapter and depend on the output adapter type. The information passed on the call is kept by the C input adapter on a per-thread/per-group basis. If a thread calls procedures (or tasks) in more than one group, the thread must call the group`_set` procedure for each group for which it intends to set attributes. For example, if a thread calls ACMS applications, any login information set for one application is not used when calling another application.

If the client program provides a new call attributes string, the previous call attributes string is overwritten. If the client program provides a null string for the call attributes string, then subsequent calls made to that group from that thread will have no call attributes string.

If an error is encountered in the group`_set` procedure, the error is returned in the `einfo` structure.

For more information on passing call attributes, see Section 3.3.

# 6.4 Using the Asynchronous C Interface

The asynchronous input adapter allows a C client to execute asynchronous calls to ACMS tasks, ACMSxp tasks, or tasks running under a Portable TP for Windows NT system. The client thread must allocate the storage for the task arguments either on the heap or in static storage rather than in stack storage. The call made by the client thread returns before the task call completes and can do other work.

## 6.4.1 Using Asynchronous Call Threads

The output adapter for the asynchronous call executes on a separate thread from the client. After the called task executes, the runtime system executes a completion routine specified by the client thread on the same thread used for the output adapter.

## 6.4.2 Using C Clients with the Asynchronous C Adapter

The client program must include the header file generated by the STDL compiler.

The client thread performs each call to a task as follows:

- Uses the same name that an STDL C client would use.
- Passes two additional arguments as the first and second arguments:
  - The address of the completion routine
    Defines the completion routine as a `void__stdcall` procedure that accepts one argument: a pointer to void.
    If the client passes STDL_C_SYNCHRONOUS as the completion routine address, the call is made synchronously and the completion routine is not called.
    If the client passes NULL as the completion routine address, the call executes asynchronously, the output adapter executes on a separate thread, but no callback is made.
  - A pointer to `void` to pass to the completion routine
    This argument is passed to the completion routine, allowing it to establish the required context.

The client thread typically does the following:

- Allocates all of the task arguments on the heap.
- Passes, as the completion routine parameter, the address of a structure containing all of the arguments.
- Checks the `einfo` structure after starting the asynchronous call (see Section 6.5).
  If the client thread receives `einfo` status that indicates no error, the client thread successfully started the asynchronous call, and the runtime system always calls the completion routine.
- In the completion routine, checks the `einfo` structure. (This variable is thread-safe.)

Any error encountered in the execution of the called task is returned to the completion routine in the `einfo` structure.

# 6.5 Using the einfo Structure to Check Status

A C client executing either synchronous or asynchronous calls uses the `einfo` structure to check STDL EINFO status returned from the TP stub call (see Section 3.4).

## 6.5.1 Exception Information Header File

The C structure definition that corresponds to the STDL `EINFO` data type definition is shown in Example 6-2.

Example 6-2 C Structure Definition for the einfo Variable

    #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

The members in the `einfo` structure in C correspond to the fields in the STDL EINFO data type definition. The STDL compiler generates the C-language version of the STDL EINFO data type for use in C clients and servers.

## 6.5.2 Exception Class Header File

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

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

For example:

    #define  ap_invocation_fault -3

The value class-identifier is the exception class and exception-class-value is the equivalent integer. Section 3.4 provides a summary of STDL exception information.

## 6.5.3 Examining Exception Information in C

C client programs examine the `einfo` structure upon completion of a procedure call. An exception is returned by the runtime setting the STDL-defined external variable. To determine whether an exception is raised, the C client program examines the exception data supplied in the `einfo` external structure when the call returns. For example, use the structure member `einfo.eclass` to determine whether an exception is returned and use `einfo.ecode` to process the exception (see Section 3.4.6).

# 6.6 Next Steps

After you test and debug the client, set up the management environment:

1. Use the management utility to establish runtime connections and parameters.
   - If the client calls ACMS tasks, set up parameters (see Section 10.2.4).
   - If the client calls ACMSxp tasks, set up parameters (see Section 10.2.3).
2. Set up error logging for the client (see Appendix A).
3. If the client calls an ACMS task, set up the ACMS Gateway adapter environment (see Section 10.3).

# Chapter 7
Writing Automation Servers and Clients

Client programs developed with an Automation language (for example, Visual Basic and Visual J++) can call:

- Tasks in TDL task groups executing under an ACMS system
- Tasks in STDL task groups executing under an ACMSxp system
- Tasks in STDL task groups executing under Portable TP for Windows NT

For Java clients developed using Visual J++, the STDL compiler generates COM objects that you register and import into the Visual J++ project as Java classes. You use in your client application the generated Java classes to set and obtain record attributes and invoke tasks. For information on how to program using Java classes generated from COM objects, refer to the documentation provided with Microsoft Visual J++.

To write an Automation client, follow these general steps:

1. Build an Automation server for the Automation clients to use (see Section 7.1).
2. Code the client calls to tasks through the Automation server following the guidelines in Sections 7.2.2 and 7.3.

# 7.1 Steps for 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. Copy the task group specification and any related files from an ACMSxp system, an ACMS system, or a Portable TP for Windows NT system to the client development system (see Section 3.1).
2. Compile the STDL task group specification.

   Note For ease of use, you can perform the compile and link steps using the client build utility GUI (see Chapter 5).

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

   Table 7-1 Automation Server Output Adapter Specifications
   Specification | Purpose
   --- | ---
   acmsda | Calls ACMS tasks
   mts | Calls STDL tasks executing under a Portable TP for Windows NT system
   dce | Calls ACMSxp tasks
   msrpc | Calls ACMSxp tasks

   For example:

         stdl -a auto:acmsda add_acms_appl

   This command creates an Automation input adapter and an ACMS Gateway output adapter in the generated adapter stub.
   The compilation produces files with names in the following format:

   `group_auto_out-adapter.obj`

   `group_auto.res`

   The value for group is the name of the compiled STDL task group specification. (When developing client interfaces for ACMS applications, output files will have an application name prefix rather than a group name prefix; see Section 4.2.3.) The out-adapter on the Automation stub file name is one of the specified output adapter types from Table 7-1. The `res` file is the type library for the Automation server.

3. Write the Automation server, using STDL-generated Automation code for the task group being accessed.
   - Access data structures using STDL-generated methods (see Section 7.2).
   - Call tasks using STDL-generated methods (see Section 7.3).
   - Handle exceptions from task calls using TPware-supplied objects (see Section 7.2.1).
4. Specifying the /DLL qualifier to the linker to produce a DLL, link the following items to produce the Automation server:
   - Objects and libraries that depend on the type of task that the Automation server calls and the output adapter used, as shown in Table 7-2.

     Table 7-2 Automation Server Adapter-Dependent Link Input
     If Client Calls... | Input File Name is... | Comment
     --- | --- | ---
     ACMS tasks (uses `acmsda` adapter) | group_auto_acmsda.obj | The adapter stub for the ACMS application (STDL task group)
     | stdl_acmsda.lib | ACMS Gateway adapter runtime link library
     ACMSxp tasks and uses `dce` adapter | group_auto_dce.obj | Adapter stub for the task group
     | group_dce_cstub.obj | DCE client stub
     | libdce.lib pthreads.lib stdl_dce.lib | DCE libraries
     ACMSxp tasks and uses the `msrpc` adapter | group_auto_msrpc.obj | Adapter stub for the task group
     | group_msrpc_c.obj | Microsoft RPC client stub
     | stdl_msrpc.lib | Microsoft RPC adapter runtime link library
     | rpcns4.lib rpcrt4.lib | Windows NT libraries
     Tasks running under Portable TP for Windows NT (uses the `mts` adapter) | group_auto_mts.obj | Adapter stub for the task group
     | stdl_mts.lib | MTS adapter runtime link library

   - The resource file for the task group, with a name in the following format:

     `group_auto.res`

     The value group is the converted name of the compiled STDL task group specification.

   - The following libraries:

         stdl_rtm.lib
         stdl_auto.lib
         ole32.lib
         oleaut32.lib
         uuid.lib

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

       DllGetClassObject
       DllCanUnloadNow
       DllRegisterServer
       DllUnregisterServer

6. 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 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 or records used, you must first uninstall the original server with `regsvr32` and the `/u` flag.
7. If the client uses an MTS adapter, you may need to register the proxy stub DLL and perform other setup operations (see Section 9.1).

Previous | Next | Contents | Index