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

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

    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 Portable TP for Windows NT
      c Executes synchronous calls to ACMS tasks, ACMSxp tasks, or tasks running under Portable TP for Windows NT
      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 Portable TP for Windows NT

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