# Compaq TP Desktop Connector
Getting Started

Previous | Contents | Index

## 4.2.9 Translation of Another Record and Field Property

Other properties may be defined in the CDD for records and fields. ACMSADU supports translation of the following property to STDL:

OCCURS

The OCCURS field declares fixed-length, one-dimensional arrays.

    OCCURS  n TIMES

# Chapter 5
Using the Client Build Utility

This chapter describes how to use the TPware client build utility and its GUI to build Automation or C clients on Windows NT or Windows 95/98 systems.

# 5.1 Building Client Programs

The TPware client build utility provides a GUI that makes it easier for you to create Automation or C clients. You provide input through the GUI, and the utility creates the files needed to build the client program.

As input, you provide the utility with an STDL task group file name, an input adapter type, an output adapter type, and an output directory name. The utility places the created files in the specified output directory along with a log file that describes the results of running the utility, including errors if any occurred. The utility notifies you whether the build succeeded or failed.

Although the client build utility eliminates some of the complexity of having to create a makefile (the utility creates the client makefile), you need to refer to Chapter 3 and the specific client chapters for other steps associated with creating a client.

Using the client build utility requires that you fulfill the following prerequisites:

- Your client development must be on a Windows NT or Windows 95/98 platform.
- Visual Studio must be in the path.
- Your STDL task group specification must contain a valid UUID. If you use ACMSADU to create your task group, generate the UUID and insert it into the task group's STDL code before using the client build utility (see Section 3.2).
- You must copy your STDL task group specification file and any related files (such as a file containing data type definitions) from your server system to your client system.
- Your STDL task group specification must contain only one task group.

The following sections describe some differences in the way the utility builds specific clients.

## 5.1.1 Building an Automation Client

If the input adapter type that you specify is Automation, the utility creates a makefile that invokes the STDL compiler and the platform linker to create a DLL that is invoked by the Automation client. The utility performs the following operations:

1. Invokes the STDL compiler to create the required object files in a temporary subdirectory.
2. Invokes the linker to link all object files from this subdirectory into the DLL.
3. Places the DLL in the output directory.

See Chapter 7 for information about registering this DLL and other steps for creating an Automation client.

## 5.1.2 Building a C Client

If the input adapter type that you specify is C, the utility creates a makefile that invokes the STDL compiler to create build files in the output directory. As shown in Table 5-1, the files generated for building a client depend on the output adapter type that you specify.

Table 5-1 Files Generated for a Client Build
Adapter Type | File Type | File Name
--- | --- | ---
ACMS | Header | input_file_name.h
| Object | task_group_name_c_acmsda.obj
ACMSxp-DCE | Header | input_file_name.h
| Object | task_group_name_dce_cstub.obj
| Object | task_group_name_c_dce.obj
ACMSxp-MSRPC | Header | input_file_name.h
| Object | task_group_name_msrpc_c.obj
| Object | task_group_name_c_msrpc.obj
Portable TP | Header | input_file_name.h
| Object | task_group_name_c_mts.obj
| DLL | task_group_name_mts_ps.dll

A header file (.h) is a file that you include in your C compile. Object files (.obj) are files that you link with your C client. The DLL file is a proxy stub DLL that you can register (see Chapter 9).

See Chapter 6 for more information about linking object files and libraries with your C client.

# 5.2 The Graphical User Interface

The client build utility allows you to easily enter your requisite build information through a GUI. By using the GUI, you do not need to use the STDL command-line interface and, in the case of Automation clients, you do not need to write a client build makefile.

To invoke the client build utility, choose `TPware Client Build Utility` from the TPware program group. When the `TPware Client Build Utility` screen opens, enter the information that is appropriate for the client that you want to build:

1. Enter the `STDL Filename` of your STDL task group specification, or click the `Browse` button to select the file name.
2. Enter an `Output Directory` name, or click the `Browse` button to select a directory. The utility generates output in this directory. If you do not specify an output directory, the utility generates the output files in the same directory that contains the input (that is, the same directory as the STDL task group specification file).
3. From the `Input Adapter Type` drop-down list, select one of the following:
   - C
   - Automation
4. From the `Output Adapter Type` drop-down list, select the output adapter type from a list that might include any of the following (depending on the TPware products that you have installed):
   - ACMS
   - ACMSxp - DCE
   - ACMSxp - MSRPC
   - Portable TP
5. Click the `OK` button. When the build is completed, the utility displays a message that notifies you whether the build was successful and gives you the option to view the log file.

In the output directory, the utility creates a subdirectory for temporary files. When the build is completed successfully, the utility deletes this subdirectory.

The utility also creates a log file, makefile, and a batch file in the output directory. If the object files or the DLL are created successfully, the utility deletes the makefile and batch file. However, if errors occur, the utility retains these files for debugging purposes.

Before invoking the makefile that invokes the STDL compiler, the utility runs the `stdl_set_version.bat` batch file to set up the environment for the STDL compiler to run successfully. The location of `stdl_set_version.bat` depends on an environment variable (STDL_DEV_DIR) that is set during installation of the product (see Section 2.1). If the utility cannot find this file via the environment variable, an error occurs.

# Chapter 6
Writing and Building C and Asynchronous Clients

Client programs written in C can call:

- TDL tasks executing under an ACMS system
- STDL tasks executing under an ACMSxp system
- STDL tasks executing under a Portable TP for Windows NT system

# 6.1 Steps for Writing and Building the Client

To build a client program written in C, 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 When building a C client program, you can perform the compile step using the client build utility GUI (see Chapter 5) rather than the command-line interface described here. However, this utility does not support asynchronous clients.

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

   Table 6-1 C Client Adapter Specifications
   Adapter Type | Specification | Purpose
   --- | --- | ---
   Input | async | Executes asynchronous calls to ACMS tasks, ACMSxp tasks, or tasks running under a Portable TP for Windows NT system
   | c | Executes synchronous calls to ACMS tasks, ACMSxp tasks, or tasks running under a Portable TP for Windows NT system
   Output | acmsda | Calls ACMS tasks
   | dce | Calls ACMSxp tasks using the DCE RPC protocol
   | msrpc | Calls ACMSxp tasks using the Microsoft RPC protocol
   | mts | Calls tasks running under a Portable TP for Windows NT system

   For example:

         stdl -c -a c:dce test_task_group

   The command generates a C header file and creates a C input adapter and a DCE output adapter in the generated adapter stub.
   The compilation produces files with names in the following format:

   `group.h`

   `group_c_out_adapter.obj`

   The format conventions are:

   group | Converted name of the compiled STDL task group specification. When developing client interfaces for ACMS applications, the group name prefix is the ACMS application_name prefix (see Section 4.2.3).
   `c` | Value for either the C or asynchronous input adapter. If you specify an asynchronous input adapter, `c` appears in the name, not `async` .
   out_adapter | One of the values for the specified output adapter types listed in Table 6-1.

3. Write the client procedures.
   1. Use the STDL-generated files to code the task calls (see Section 6.2).
   2. Decide whether to use the call attributes string (see Section 6.3).
   3. If the C client program that you are building executes asynchronous calls, see also Section 6.4.
   4. Check status. After the call to the task, access STDL status using the `einfo` structure (see Section 6.5).
4. Compile the client program.
5. Link the following items to produce the client image. This step is the same for C or asynchronous C clients.
   - Objects and libraries that depend on the type of task that the C client calls and the output adapter used, as shown in Table 6-2.

     Table 6-2 C Client Adapter-Dependent Link Input
     If Client Calls... | Input File Name is... | Comment
     --- | --- | ---
     ACMS tasks (uses `acmsda` adapter) | group_c_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_c_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_c_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
     | rpcndr.lib rpcns4.lib rpcrt4.lib | Windows NT libraries
     Tasks running under a Portable TP for Windows NT system, and the client runs on a different hardware architecture than the server (client uses the `mts` adapter) | group_c_mts.obj | Adapter stub for the task group
     | stdl_mts.lib | MTS adapter runtime link library
     Tasks running under a Portable TP for Windows NT system, and the client runs on the same hardware architecture as the server (client uses the `mts` adapter) | group_cli.obj | The client stub for the task group copied from the Portable TP for Windows NT development system
     | stdl_mts.lib | MTS adapter runtime link library

   - Client program files
     - All of the object files
     - Any libraries required by the object files
   - The TPware runtime library:

         stdl_rtm.lib

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

# 6.2 C Language Support

The STDL compiler generates C header files to support client development. Include the following files in your C client:

- Group header file source-file-name`.h`---Contains the function prototypes that define the interface to the tasks and the structure definitions for arguments passed to the called tasks (see Sections 6.2.1 to 6.2.4). The STDL compiler generates the contents based on the tasks defined in the task group specification.
- Exception information header file `einfo.h`---Contains the C structure definition for the `einfo` external variable (see Section 6.5.1).
- Exception class header file `eclass.h`---Equates the symbolic name (class identifier) for each exception class with its exception class value (see Section 6.5.2).

## 6.2.1 Function Prototypes and Argument Passing

The STDL compiler creates a function prototype that contains a C external task name function declaration for each noncomposable task in a task group specification. The function prototypes are written to the group header file. Unless the calls are to ACMS applications, functions have the following format:

`converted-task-name([argument [,...]])`

Task names are converted to function names according to the rules for identifiers (see Section 6.2.4). Task function declarations do not have a value, and all arguments are passed as pointers.

Call the C procedures for the tasks as normal procedure calls.

For each task argument, declare a variable using the STDL data type definition from the group header file.

### 6.2.1.1 ACMS Task Call Arguments

If the calls are to ACMS applications, functions have the following format:

`converted-task-name(string,status[,argument [,...]])`

The string argument is the selection string, consisting of one STDL record containing one 256-character field of data type ISO-LATIN-1 text. The status argument is an extended status string, consisting of one STDL record containing one 80-character field of data type ISO-LATIN-1 text. This extended status is message text associated with an error returned from the ACMS application (see Section 3.4.6.2).

## 6.2.2 STDL to C Data Type Mapping

The group header file contains C definitions corresponding to record data type definitions in the STDL source files. Table 6-3 maps the STDL data types to the C data types. The STDL compiler generates header files with these mappings.

Table 6-3 Mapping STDL Data Types to C Data Types
STDL | C
--- | ---
ARRAY SIZE n OF type | type id[ n]
ARRAY SIZE n OF ARRAY SIZE m OF type | type id[ n] [ m]
ARRAY SIZE n TO m DEPENDING ON number OF type 1 | struct rec { long int number ; type id[ n] ; } ;
DECIMAL STRING SIZE a SCALE b | char id[ a+1] 2
INTEGER | long id (or equivalent signed long, long int, or signed long int)
OCTET | unsigned char id
TYPE rec IS RECORD id IS type ; END ; | struct rec { type id; } ;
TEXT SIZE n CHARACTER SET ISO-LATIN-1 ISO-LATIN-2 SIMPLE-LATIN | char id[ n]
TEXT SIZE n CHARACTER SET KANJI KATAKANA | char id[ M]
UUID | uuid_t id 3

1The number of repetitions of a variable length array is mapped as a record, rec, containing the number of repetitions and the repeated array.
2The data transferred is a character string in ISO 6093:1985, signed NR1 format, consisting of a row of one sign (or blank character) and digits that do not include characters indicating a decimal point. The user program should convert the representation to a decimal number.
3The uuid_t value is a typedef for the DCE UUID.

Key to Variables

- a , b , m , n ---An appropriate decimal number
- id , number , rec ---An appropriate name
- M ---an integer that depends on its implementation for its data type
- <type >---A valid STDL data type, or a user-defined data type identifier

Previous | Next | Contents | Index