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

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.

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