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

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 Portable TP for Windows NT. 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:

The client thread typically does the following:

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

    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 Portable TP for Windows NT
      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