DIGITAL 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 TP Desktop Connector, 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.

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

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


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

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.
  • 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.)
  • 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).
  • Build the client interface.
    See the following chapters that describe the steps for building different types of clients:
  • 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. After you paste the UUID, 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 Portable TP for Windows NT, 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 Portable TP for Windows NT

    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