# Compaq TP Desktop Connector
Getting Started

Previous | Contents | Index

# Chapter 2
Compiling STDL Applications

This chapter presents STDL command-line reference and environment information for use with the TP Desktop Connector product in generating adapter stubs used for client access to TP applications.

Note For information about invoking the STDL compiler through the client build utility graphical user interface (GUI), see Chapter 5.

# 2.1 STDL Compiler Environment Setup

To run the STDL compiler, you must register the environment variables needed by the compiler. From a command window, run the `stdl_set_version.bat` batch file from the directory named in the following format:

`install-directory\stdl\bin`

The value install-directory is the device and directory in which you installed the TPware software. For example, if you installed the product in the C:\`tpware` directory, you would type the following:

    C:\tpware\stdl\bin\stdl_set_version.bat

When execution completes, the STDL development environment is set up.1

Note #### 1 If ACMSxp and TP Desktop Connector are installed on the same system, unregister the ACMSxp environment variables and then open a command prompt window for the TP Desktop Connector STDL development environment. Any existing ACMSxp development environment is not available from that command window.

# 2.2 Using the STDL Compiler

The `stdl` command invokes the STDL compiler. The STDL compiler translates STDL definitions and specifications contained in the input source file and produces both object code to link with the clients and other outputs to aid source code development. For the TP Desktop Connector product, the STDL compiler generates adapter stubs used for client access to STDL tasks and ACMS applications.

Synopsis

The `stdl` command syntax is:

    stdl [-cswLMX]

         [-a in_adapter_type:out_adapter_type]

         [-D text_type:header_type:wire_format]

         [-h directory] [-i path]

         [-o directory] [-S include]

         [-u uuid] [-v version] file_specification

Option Flags

-a in_adapter_type:out_adapter_type

Specifies input and output adapters that provide calling interfaces between a client and task.

- Input adapter types:
  - auto
    Provides an Automation interface that allows clients to call ACMSxp tasks, ACMS tasks, and STDL tasks executing under a Portable TP for Windows NT system. Use the Automation input adapter with any 32-bit Automation client on a Windows platform (for example, Visual Basic or Office 95/97).
  - java
    Provides a Java interface that allows Java clients to call ACMSxp tasks, ACMS tasks, and STDL tasks executing under a Portable TP for Windows NT system. The Java classes that represent the application objects present their data record fields as public members.
  - javabeans
    Provides an interface similar to JavaBeans that allows Java clients to call ACMSxp tasks, ACMS tasks, and STDL tasks executing under a Portable TP for Windows NT system. The Java classes that represent the application objects present their data record fields through accessor methods.
  - c
    Produces stubs that allow both single-threaded and multithreaded C clients to call ACMSxp tasks, ACMS tasks, and STDL tasks executing under a Portable TP for Windows NT system via the C adapter.
  - async
    Provides an asynchronous interface for C clients to call ACMSxp tasks, ACMS tasks, and STDL tasks executing under a Portable TP for Windows NT system. To start the task call, the client calls an adapter procedure generated by the STDL compiler. When the task call completes, the adapter invokes the callback routine provided by the client.
- Output adapter types:
  - acmsda
    Produces stubs that allow client calls to ACMS tasks using ACMS RPC communications.
  - mts
    Produces stubs that allow client calls to tasks executing under a Portable TP for Windows NT system using DCOM communications.
  - dce
    Produces stubs that allow client calls to ACMSxp tasks using DCE RPC communications.
  - msrpc
    Produces stubs that allow client calls to ACMSxp tasks using Microsoft RPC communications.

-c

Generates a C header file. The compiler generates the C header file with the same name as the input source file and a filename extension of `.h`, either into the current working directory or into the directory specified by the `-h` flag.

-D text_type:header_type:wire_format

Specifies how an STDL data type is to be represented in header files and communications messages on Japanese systems. For this release, kanji is the only valid entry for the `text_type`, to specify the Kanji text data type.

Possible values for `header_type` are char or wchar. Possible values for `wire_format` (to describe the format in which characters are submitted) are stdlwire or none. If you specify stdlwire, conversion occurs before the Kanji text data is transmitted across the wire and after the data is received. With the value none, no conversion occurs.

-h directory

Specifies a directory into which the STDL compiler generates C header files. By default, the compiler generates the C header files in the current working directory.

-i path

Specifies a directory search path for STDL #INCLUDE and #CINCLUDE files. A path argument must be either a legal directory specification or an environment variable. If you specify multiple arguments, separate each by a semicolon (;), and enclose environment variables in percent characters (%). The compiler searches for the #INCLUDE or #CINCLUDE files in the following order:

- Path containing the top-level source file
- Path specified by the `-i` flag
- Directories listed in the STDL_INCLUDE_PATH environment variable

-L

Produces a file that contains a line-numbered source code listing, with error messages inserted directly under each source line containing an error. The compiler creates this file in the current working directory with the same name as the input source file and the `.lis` suffix.

Use the `-S include` flag with this flag to include in the line-numbered source code listing the contents of the files specified in the #INCLUDE and #CINCLUDE directives.

-M

Specifies that the STDL source files contain Multivendor Integration Architecture (MIA) syntax. The default for the STDL compiler is X/Open syntax.

-o directory

Specifies a device and directory into which the compiler generates output `.obj` files. By default, the compiler generates these output files in the current working directory.

-s

Performs only syntax and semantic checks on the input source file. Does not generate any output files. By default, the compiler generates output as directed by other options.

-S include

When used with the `-L` flag, includes in the line-numbered source code listing file the contents of the files in the #INCLUDE and #CINCLUDE directives. If you specify the `-L` flag without the `-S include` flag, the compiler includes only the input source file in the listing file.

-u uuid

Specifies the default universal unique identification (UUID) for the first processing group specification in the input file that does not have a UUID specified in the STDL syntax. If the input file contains a processing group specification with no UUID specified, this flag is required. The `-u` flag applies only to processing groups that you are compiling, not to processing groups to which the STDL source refers. A UUID value comprises hexadecimal digits (`X`) grouped as follows:

    "XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX"

-v version

Specifies the default version number for any task group or processing group specification in the input file that does not designate a version in the specification syntax. The compiler defaults to assigning a version of 0.0 for any processing group with no syntax-specified version unless you specify a version with the `-v` flag. Version is a decimal literal without a sign. Processing group specifications included for reference only do not require a version number on the command line.

-w

Suppresses warning messages. The default is to display warning messages.

-X

Specifies that the STDL source files contain X/Open syntax.

The STDL compiler defaults to X/Open STDL syntax. To compile Multivendor Integration Architecture (MIA) syntax, use the `-M` flag.

Description

For this product, the compiler generates adapter stubs used for client access to STDL tasks and ACMS applications. Task compilation is not supported.

The compiler directs output to the current working directory, the directory containing the top-level input source files, or to directories specified by the option flags or by the values set by environment variables.

The input source file designated by `file-specification` must contain a task group specification.

Use a nonqualified or fully qualified file name as input to the `stdl` command. All files specified with nonqualified names must be in the current working directory. The compiler appends the `.stdl` suffix to the name of the STDL input source file if you omit a suffix in the file specification.

Compilation Output

The STDL compiler generates the following output files based on the contents of the STDL source files and on the flags used during compilation:

- Listing file with a name in the following format:

  `source-file-name.lis`

  This file contains line-numbered source code statements and a summary report that is generated when you use the `-L` flag.

- C header file with a name in the following format:

  `source-file-name.h`

  This file is generated when you use the `-c` flag but omit the `-s` flag.
  Include this file in any C programs that call ACMSxp tasks, ACMS tasks, or STDL tasks executing under a Portable TP for Windows NT system, or that refer to STDL data type definitions.

- Adapter stub object with a name in the following format:

  `group_in-adapter_out-adapter.obj`

  This file uses the name of the task group (group) and contains the adapter stub object with the adapters specified in the in-adapter and out-adapter arguments with the `-a` flag.
  The compiler generates the adapter stub object if you use the `-a` flag but not the `-s` flag.
  Link the adapter stub object as follows:

  - With the C client executable if the input adapter is `c` or `async` (see Chapter 6)
  - With the resource file group_`auto.res` if the input adapter is `auto` (to create an Automation server DLL, see Section 7.1)
- Resource file with a name in the following format:

  `group_adapter.res`

  This file uses the name of the task group (group) and contains a linkable version of a type library for use with an Automation adapter. The compiler generates this file if you specify the `-a` flag with an `auto` input adapter.
  To create an Automation server DLL, link this resource file with an adapter stub that includes an Automation adapter (group_`auto`_out-adapter.`obj`). See Section 7.1.

- DCE or Microsoft RPC client stub object with a name in the following format:

  `group_dce_cstub.obj or group_msrpc_c.obj`

  This file contains the DCE or Microsoft RPC client stub for the task group named group.
  The compiler generates this file if you specify the `-a` flag with `dce` or `msrpc` as the output adapter.
  Link the DCE or Microsoft RPC client stub with a client that uses a DCE or Microsoft RPC output adapter (that is, the client that calls an ACMSxp task):

  - For C clients, see Chapter 6.
  - For Automation servers, see Section 7.1.
- MTS proxy stub DLL with a name in the following format:

  `group_mts_ps.dll`

  This file contains the COM proxy stub DLL for the task group with group as the converted name of the group. The STDL compiler generates this file if the `-a` flag is specified with the `mts` adapter.
  You must register this DLL on the server system hosts (see Section 9.1.1).

- Java archive file with a name in the following format:

  `group_out_adapter.jar`

  This file contains the Java classes for the task group with group as the converted name of the task group. The compiler generates this file if you specify the `-a` flag with `java` or `javabeans` as the input adapter.

# Chapter 3
Building a Client Interface

This chapter describes the steps for building a TPware client interface to your current application.

# 3.1 General Steps in Building a Client Interface

The TP Desktop Connector product builds a client interface to an existing TP application executing under ACMSxp, ACMS, or Portable TP for Windows NT software. To build a client, follow these general steps:

1. On the server development system, find the source code for the existing TP application.
   - If you are developing a client program to access existing ACMSxp tasks or tasks running under a Portable TP for Windows NT system, copy the following STDL source files to the client development system.
     - The task group specification
     - Data type definitions referenced in the task group specification
   - If you are developing a client program to access existing ACMS tasks, do the following:
     1. Using the ACMSADU extension installed on the ACMS server development system, process the TDL source files to generate a source file that contains an STDL task group specification and data type definitions for the ACMS tasks. See Chapter 4 for instructions on preparing TDL applications.
     2. Copy the generated source file from the OpenVMS system to the client development system.
     3. Edit the generated STDL task group specification to supply a valid UUID (see Section 3.2).
2. On the client development system to which you copied the STDL source code, establish the environment for using the STDL compiler. (See Section 2.1 for STDL compiler environment setup.)
3. On the client development system, use the STDL compiler to process the STDL source files and produce C header files that facilitate client program development and the correct type of stub for the client program.

   Note When building Automation or C clients, you can perform this STDL compile step and, for Automation clients, the subsequent build step using the client build utility GUI (see Chapter 5).

4. Build the client interface.
   See the following chapters that describe the steps for building different types of clients:
   - Chapter 6 for writing and building C clients
   - Chapter 7 for writing Automation servers and clients
   - Chapter 8 for writing Java clients
   - Chapter 9 for setting up applications
5. On the client development system, set up the management environment for the client interface (see Chapter 10).

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

1. Invoke `guidgen` from either a DOS command line or the `Tools` menu item in Microsoft Visual C++ V5.0.
2. Select the `Registry Format` menu and `Copy` command to copy the UUID to the Windows NT clipboard.
3. Paste the UUID into the generated STDL task group specification.
4. Replace the curly brackets with double quotes (").

# 3.3 Specifying Call Attributes and Management Information

When your client calls ACMS, ACMSxp, or STDL tasks executing under a Portable TP for Windows NT system, it can pass information such as destination and authentication information to communications adapters on each call. TPware does this through the use of the call attributes string, where each call attribute has a name:value format.

If you specify a call attribute value without specifying a name for it, then a default name is assumed.

If you omit a call attribute or specify a null call attributes string, the TPware management utility provides the attribute information (see Section 10.2).

## 3.3.1 Call Attributes for Calling ACMS Tasks

The ACMS Gateway adapter uses call attributes from either the client or from management information to determine the node on which the gateway resides and the OpenVMS username and password for the call. The `node` attribute's value is the name of the server node on which the gateway resides.

The `authentication` attribute's value is the name and password to be used for the call, as described in Section 1.5.

For example, a call attributes string for the ACMS Gateway output adapter might be:

    node:bigwig,authentication:jones:sam

In the example, the node attribute has the value `bigwig`, and the authentication attribute has the value `jones:sam` (the username and password to use for the call).

If you omit a call attribute or specify a null call attributes string, the TPware management utility provides the attribute information (see Section 10.2.4).

## 3.3.2 Call Attributes for Calling ACMSxp Tasks

The DCE RPC and Microsoft RPC output adapters recognize the `entry` call attribute, which specifies the default name server entry to use for calls. If the call attribute is null, the entry name is provided by TPware management data (see Section 10.2.3) or the RPC_DEFAULT_ENTRY environment variable.

In addition, the DCE RPC output adapter uses any DCE credentials that you set in the TPware management utility.

## 3.3.3 Call Attributes for Calling Tasks Executing Under a Portable TP for Windows NT System

The MTS output adapter recognizes the `node` call attribute, which specifies the node on which the MTS server resides.

If the call attribute is null, the client program calls the MTS server on the system from which you exported the MTS package. You can use the call attributes string to override this default.

The `node` call attribute applies only to noncomposable task calls. The call attribute is ignored when calling a composable task.

Previous | Next | Contents | Index