# DIGITAL TP Web Connector
DIGITAL Database Web Connector
Getting Started

Previous | Contents | Index

## 4.4.2 Using the Automation Server in a Client

The Automation client maps task groups and processing groups into Automation objects containing the following:

- A method for each task or processing procedure
- A property that points to an `STDL.stdl_einfo` object (see Section 4.4.4)

The Automation object generated for a group has a name in the following format:

`group.Group`

The compiler derives group by converting the STDL name to lowercase and replacing any hyphens with underscores.

TPware uses Automation objects to model records. Because Automation does not directly support records, the compiler generates an Automation object for each record used as a parameter by:

- A task in the task group being called
- A processing procedure in the local processing group being called

The Automation object for each record has a name in the following format:

`group.record-name`

The compiler derives record-name from the STDL data type identifier if either of the following conditions is true.

- The STDL data type is used as an argument to a task or processing procedure in the task group or processing group.
- The STDL data type identifier is used as a data type for a field within another record object being generated for the task group or processing group (X/Open syntax only).

If an embedded record is being used as a data type for a field within another record object being generated for the task group or processing group, the compiler gives record-name in the following format:

`field-name_record`

The value field-name is derived from the STDL field name. The compiler creates an object for each parameter to be passed to a task or processing procedure.

If an STDL record is used for more than one argument or is included in more than one other STDL record, the compiler generates only one STDL record object.

You can use an object browser (for example, the Visual Basic object viewer) to examine objects defined by the generated Automation server.

## 4.4.3 Calling Tasks and Processing Procedures from Automation Clients

To call either tasks within a task group or processing procedures within a processing group, the Automation client performs the following steps:

1. Creates an object for each record to be passed to the task or processing procedure.
   This is done by referencing the record object name (group.record-name) in one of the following ways:

- In a `CreateObject` service
- By using object references in Visual Basic

For example, for the `add_number` record in the `add_task_group`, the object name is `add_task_group.add_number`.

2. Fills in data in the record objects as necessary.
   The fields within the record objects are referenced as attributes of the created record object.
3. Creates an object for the task group or processing group.
   This is done in one of the following ways:

- By referring to the group object name (group`.Group`) in a `CreateObject` service
- By using object references in Visual Basic

For example, the group object name for `add_task_group` is `add_task_group.Group`.

4. Within either the task group object or the processing group object, calls the task or processing procedure as a method.

## 4.4.4 Standard Objects

The following standard Automation objects are supported:

- `STDL.stdl_einfo`
- `STDL.stdl_uuid`

These objects are installed when you install TP Web Connector and Database Web Connector.

The `STDL.stdl_einfo` object is used to store STDL status information in a Microsoft Automation environment. This object has the following properties:

    eclass  AS LONG
    ecode   AS LONG
    eproc   AS STRING
    epgroup AS STRING
    esource AS STRING
    ecgroup AS STDL.stdl_uuid

The `STDL.stdl_uuid` object is used to store the STDL universal unique identification (UUID). This object has the following property:

    uuid_string AS STRING

## 4.4.5 Automation Runtime Errors

Automation runtime error values are returned using a 32-bit number known as a result handle (HRESULT). Microsoft defines the structure of the HRESULT value. Automation errors returned by TP Web Connector and Database Web Connector begin at the HRESULT value 0x80041001. To determine an STDL error code from the HRESULT format, subtract 0x80041000 from the Automation error code value:

`STDL-error-code = <Automation-error-code-value> - 0x80041000`

STDL error codes and their corresponding messages are described in the `stdl_msg.h` message file, located in a directory with a name in the following format:

`install-directory\stdl\include`

For example, if you installed the product in the `C:\tpware` directory, then the STDL message file is located at:

    c:\tpware\stdl\include\stdl_msg.h

STDL error codes are described in Section 4.3.2.4.

## 4.4.6 Automation Data Type Support

When the STDL compiler generates an Automation object for each STDL record (see Section 4.4.2), each field within the generated record object is represented by an attribute. The type of the attribute is determined by the STDL data type of the field as shown in Table 4-3.

Table 4-3 Automation Data Type Mapping

| Automation Data Type
--- | ---
STDL Data Type | C | Visual Basic
ARRAY | 1 | 1
DATE | DATE | DATE
DECIMAL STRING | BSTR | STRING
FLOAT SIZE 4 | float | SINGLE
FLOAT SIZE 8 | double | DOUBLE
INTEGER SIZE 1 | short | INTEGER
INTEGER SIZE 2 | short | INTEGER
INTEGER SIZE 4 | long | LONG
OCTET | unsigned char | BYTE
RECORD | Record object | Record object
TEXT CHARACTER SET ISO-LATIN-1 | BSTR | STRING
TEXT CHARACTER SET ISO-LATIN-2 | 2 | 2
TEXT CHARACTER SET ISO-UCS-2 | 2 | 2
TEXT CHARACTER SET KANJI | 2 | 2
TEXT CHARACTER SET KATAKANA | 2 | 2
UNSIGNED INTEGER SIZE 1 | unsigned char | BYTE
UNSIGNED INTEGER SIZE 2 | short | INTEGER
UNSIGNED INTEGER SIZE 4 | long | LONG
UUID | BSTR | STRING

1Array references are to the base data type starting with an index of zero.
2This data type support is not implented.

# 4.5 Using the Asynchronous Adapter

The asynchronous input adapter allows a C client to execute calls to processing procedures asynchronously. (Only Database Web Connector supports the asynchronous adapter.) This is not the same as a queued call (the STDL SUBMIT statement). The client thread must allocate the storage for the procedure arguments either on the heap or in static storage rather than in stack storage. The call made by the client thread returns immediately and can do other work.

## 4.5.1 Asynchronous Call Thread Use

The output adapter for the asynchronous call executes on a separate thread from the client. After the called procedure executes, the TPware runtime system executes a completion routine specified by the client thread on the same thread used for the output adapter. Use the TPware management utility to select the thread usage semantics that are best suited for your application (see Section 7.2.3).

## 4.5.2 Using C Clients with the Asynchronous Adapter

The client program must include the header file generated by the STDL compiler.

The client thread performs each call to a processing procedure as follows:

- Uses the same name that a 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 procedure that accepts one argument: a pointer to void.
- 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 procedure arguments on the heap.
- Passes, as the completion routine parameter, the address of a structure containing all of the arguments.
- Checks `einfo` after starting the asynchronous call.
  If the client thread encounters any error in starting an asynchronous call, Database Web Connector returns the error to the client thread in `einfo` and does not call the completion routine.
  If the client thread successfully starts the asynchronous call, Database Web Connector always calls the completion routine.
- In the completion routine, checks `einfo`. (This variable is thread-safe.)

Any error encountered in the execution of the called procedure is returned to the completion routine in `einfo`.

# 4.6 Using Automation Servers with Active Server Pages

Active Server Pages (ASPs) execute scripts at the web server. These scripts can access any Automation server and can be written in any scripting language supported by the web server; for example, VBScript or JavaScript.

## 4.6.1 Accessing Automation Objects

You can use the `Server.CreateObject` method to create objects with session, page, or application scope. Objects with page scope are created each time the user accesses the page and are destroyed when the server finishes processing the current page. After session objects are created, they remain in existence until the current session either is abandoned or times out.

Note Use session objects to avoid the overhead of Automation object creation and deletion each time a user references a page.

## 4.6.2 Setting Up the Internet Information Server (IIS)

Before you run an ASP application, make sure that the Internet Information Server (IIS) has `read` and `execute` access to the directory containing the `.asp` files. Refer to your web server documentation for instructions on how to add virtual directories and to set permissions. Before running the samples in the Internet Service Manager, copy the files to a clean directory before using them and add, as a virtual directory, the directory with a name in the following format:

`install-directory\stdl\samples\web`

The install-directory is the location in which you installed the product.

## 4.6.3 Environment Variables and IIS

To load any newly added systemwide environment variables that are needed by IIS, shut down and restart IIS. The simplest way to do this is to restart your machine. For more information on managing IIS, see either the Microsoft online documentation or knowledge base articles at the Microsoft World Wide Web site.

## 4.6.4 DLL Caching in Internet Information Server

When an ASP application creates an Automation object, IIS loads the Automation server (that is, the DLL). After the DLL is loaded, IIS caches it in memory indefinitely to improve performance. If you need to unload the DLL (for example to recompile or overwrite it), perform the following steps.

1. Flush the DLL cache either by stopping the WWW service from the Internet Service Manager or by entering the following command:

    net stop w3svc

2. After you have recompiled or overwritten the DLL, restart the WWW service either by the Internet Service Manager or by entering the following command:

    net start w3svc

See the Microsoft knowledge base article Q166279 for more information on the lifetime of a COM component under IIS and ASP.

# 4.7 Using C Clients with ISAPI

TPware enables C clients using the Microsoft Internet Application Programming Interface (ISAPI) to access TP applications. Sections 4.7.1 and 4.7.2 describe how to ensure that IIS can locate and cache the appropriate ISAPI DLLs for your C client.

## 4.7.1 Locating ISAPI DLLs

IIS must be able to locate any ISAPI DLLs. To ensure this and to avoid having to specify the exact paths, put the ISAPI DLLs in the same directory as the HTML application.+

## 4.7.2 Internet Information Server Caching of ISAPI DLLs

IIS caches DLLs in memory. If you need to unload a DLL to either recompile or overwrite it, perform the following steps:

1. Flush the IIS DLL cache by stopping the WWW service from the Internet Service Manager or by entering the following command:

    net stop w3svc

2. Recompile or overwrite the DLL.
3. Either restart the WWW service from the Internet Service Manager or enter the following command:

    net start w3svc

See the Microsoft knowledge base articles at the Microsoft World Wide Web site for more information on ISAPI DLLs and the Internet Information Server.

Note #### + In the sample applications, the ISAPI DLLs are expected to be in the same directory as the HTML application.

# 4.8 Calling ACMS or ACMSxp Tasks from IIS

When your client calls ACMS or ACMSxp tasks from IIS, set the thread usage semantics for the task group. Setting the thread usage semantics avoids stack overflows and limits the number of concurrent connections.

When an Active Server Page calls an Automation object within IIS, the amount of free stack space remaining is very limited. Both the ACMS Desktop output adapter and the DCE RPC output adapter normally require more stack space than is available.

A separate TCP/IP connection is used for each active call between a thread using the ACMS Desktop output adapter on the Windows NT system and the ACMS Desktop adapter gateway process on the OpenVMS system. This connection usage can cause the ACMS Desktop adapter gateway to exhaust process and system resources, including TCP/IP sockets.

## 4.8.1 Thread Usage Semantics for Calling ACMS Tasks

If your client calls ACMS tasks, set the thread usage semantics to `Execute call on a separate thread, but limit the number of TPware threads` and set the thread limit. By using the separate thread, the ACMS Desktop output adapter will have sufficient stack space on which to execute. Choose an appropriate value for the thread limit so that there are sufficient threads to handle the expected load, but not so high as to cause the ACMS Desktop adapter gateway process to exceed its OpenVMS quotas or consume all available TCP/IP sockets. See Section 7.2.3 for the steps to set the thread usage semantics.

## 4.8.2 Thread Usage Semantics for Calling ACMSxp Tasks

If your client calls ACMSxp tasks from Active Server Pages, set the thread usage semantics to `Execute call on a sparate thread`. This setting allows the DCE RPC output adapter (which is used to communicate with the ACMSxp task server) to have its own thread stack on which to execute. Alternatively, you can use the `Execute call on a separate thread, but limit the number of TPware threads` setting, but this thread usage semantics is normally not necessary for calling ACMSxp tasks. See Section 7.2.3 for the steps to set the thread usage semantics.

# 4.9 Building Servers that Use Local Processing Procedures

Database Web Connector allows PC-based clients to access local processing procedures. Sections 4.9.1 and 4.9.5 describe how to compile, link, and name local processing procedures.

## 4.9.1 Compiling the Processing Group and Local Procedure

To build a server for a local procedure call, use STDL to compile the procedure group specification, not the task group specification. For example, to create a local processing server for the ADD sample, perform the following steps:

1. Compile the `add_proc_group.stdl` file.
2. Compile the local procedure module, `add_procedure.c`.
3. Link it with the Automation server. See Section 4.4.1.

## 4.9.2 Linking Local Processing Procedures

When using the C input adapter or the C output adapter, you must include the following in the link:

- The adapter stub for the processing group containing the C output adapter if executing either asynchronous or synchronous calls to local processing procedures:

`group_c_c.obj`

The value group is the name of the processing group.

- The TPware runtime library:

    stdl_rtm.lib

Previous | Next | Contents | Index