DIGITAL TP Web Connector Version 1.0 for Windows NT Release Notes

© Digital Equipment Corporation 1997. All Rights Reserved.

This document provides the Release Notes for DIGITAL TP Web Connector Version 1.0 for Windows NT. The Release Notes describe known problems with DIGITAL TP Web Connector Version 1.0 for Windows NT and include hints and suggestions to help you use this product.

### Contents

Hardware and Software Requirements

Installation Information

Kit Updates

Environment Setup

Samples

Restrictions and Workarounds

Troubleshooting Tips

Interpreting Runtime Error Codes

DIGITAL TP Web Connector V1.0 for Open VMS

Associated Documentation

Comments and feedback on the use of TP Web Connector can be sent to ACMSxp engineering via e-mail at acmsxp_info@camino.enet.dec.com.

### Hardware and Software Requirements

Hardware Requirements

DIGITAL TP Web Connector Version 1.0 for Windows NT runs on the following hardware platforms:

- Intel
- DIGITAL Alpha

Software Requirements

Runtime and Development Environments:

- Windows NT Workstation 4.0 with Service Pack 2 or Windows NT Server Version 4.0 with Service Pack 2.
- Microsoft Internet Information Server (IIS) 3.0 on Windows NT Server Version 4.0.
- Microsoft Peer Web Services 3.0 on Windows NT Workstation Version 4.0.
- Microsoft Active Server Pages (ASP) for IIS 3.0 or Peer Web Services 3.0 if using server side scripts.
- DIGITAL DCE V2.0 Runtime Services for Windows NT with NT Service Pack 3 if accessing ACMSxp Transaction Processing systems.

Development Environments:

- Microsoft Visual C++ V4.2 and the Microsoft Platform Software Developer's Kit (SDK) March 1997 or Visual C++ 5.0. If installing the Platform SDK choose either the Express Setup option or the Custom Setup option with Build Environment and Additional Developer's Tools selected.
- DIGITAL DCE V2.0 Application Developer's Kit for Windows NT.

### Installation Information

Installation instructions are provided in the TP Web Connector, Database Web Connector Getting Started Manual (TPware Getting Started on the menu).

### Kit Updates

Notifications of future updates or changes to the TP Web Connector kits can be found on the web at: http:/ /www.software.digital.com/TPWebConnect

### Environment Setup

1. The Platform SDK directory must be in the system path before the directory for Visual C++ to invoke the correct version of the MIDL compiler. Additionally the system INCLUDE path should contain the Platform SDK include directory before the Visual C++ include directory (msdev\include). Likewise for the system LIB path.
2. If ACMSxp and the TP Web Connector kit are installed on the same machine, then the ACMSxp environment variables must be unregistered before opening a Command Prompt window for the TP Web Connector build environment.
3. For DCE output adapters, to avoid a possible stack overflow, execute task calls on separate threads. This can be done by setting one of the separate thread options on the Threads tab via the kit TPware Program Group, Management Utility, TPware Configuration.
4. If you want to use DCE output adapters to call ACMSxp tasks, you must configure the account under which IIS executes to be part of the administrator’s group. Failure to do so causes IIS server process to terminate. ACMSxp software engineering is working on reducing this requirement. Please send e-mail to us at acmsxp_info@camino.enet.dec.com if you are interested in this issue.

### Samples

The Add Samples provided in this kit can be referenced under the TPware program folder. The Add Samples include:

- ACMS Web Samples
- ACMSxp Web Samples

### Restrictions and Workarounds

If the product restriction has been logged as a Quality Assurance Report (QAR), then the QAR number is listed in the desription.

1. This version has no error logging.
2. This version has limited Automation error reporting. Please see the section on Interpreting Runtime Error Codes for more information.
3. When reading the on-line version of DIGITAL TP Web Connector, DIGITAL Database Web Connector Getting Started with Microsoft Internet Explorer V3.x, some of the hyperlinks do not work.
   Workaround:
   Upgrade to Internet Explorer V4.0.
4. The DIGITAL TP Web Connector, DIGITAL Database Web Connector Getting Started document incorrectly states that you can shut down the IIS server process by stopping the WWW service. In order to shut down IIS completely you must stop all IIS services (stop the WWW service last).
5. An access violation may occur in the IIS server process (inetinfo) if all the following occur: (QAR 023 and QAR 024)
   - An ACMS or ACMSxp task has been called from an Automation or ISAPI client application within IIS
   - The WWW service is stopped without stopping the IIS server process (that is the WWW service is not stopped after the other IIS services)

   When the IIS server process is not stopped, this access violation may occur up to 20 minutes after the WWW service is stopped.
   Workaround:
   Whenever you stop the WWW service, stop all other IIS services first.

6. There are certain times when you must unregister and register an Automation server. If you are adding or removing methods, changing the number or type of arguments or changing the fields in a record you should unregister the existing Automation DLL using the regsvr32 -u command before you register the new DLL. However if the Automation server has already been loaded by IIS, issuing the regsvr32 -u command for DLL will NOT unload it from the IIS DLL cache
   Workaround:
   Stop all IIS services to unload the DLL. Then unregister the existing DLL before rebuilding the Automation server.
7. Attempting to uninstall the TP Web Connector kit when IIS is running may prevent the uninstall program from removing certain files and directories. IIS caches DLLs indefinitely to improve performance and may still have some of the TP Web Connector DLLs loaded. The uninstall program can not remove files if there are currently in use.
   Workaround:
   Before uninstalling or re-installing the TP Web Connector kit stop all IIS services (make sure you stop the WWW service last ). This will ensure that any cached DLLs are unloaded.
8. In a user program, if einfo.h is included before windows.h and a message header file is then included, compilation errors occur. (QAR 004)
   Workaround:
   Include windows.h before einfo.h.
9. The TPware Add sample server code is not the same code that is in the ACMSxp 3.1 NT kit. (QAR 020)
   Workaround:
   Use the server Add Sample code provided in the TPware kit.
10. Passing an object variable that no longer references an object as a parameter to a task or processing procedure method via the Automation interface causes an access violation. This can happen when an object variable has been set to "Nothing". (QAR 009)
    Workaround:
    Make sure that the parameters passed to a task method reference valid objects.
11. It is strongly recommended that you uninstall the TP Web Connector kit before upgrading to a new version or re-installing to select different components. However, uninstalling the TP Web Connector kit removes the settings defined in the Management Utility (i.e. DCE, Threads and ACMS group settings). (QAR 010)
    Workaround:
    If you uninstall and re-install the TP Web Connector kit, you must re-enter the settings defined in the Management Utility. Before you uninstall run the Management Utility and write down the current settings.
12. If a task group contains a composable task, the STDL compiler generates the following error message for a DCE output adapter (QAR 002):
    Warning: Semantic checking prevented by other reported errors
    idl: File tg1_dce.idl, line 49: [in, out] tps_txn_t_trpc_ctx *tpstub_tid,
    Name not found: tps_txn_t_trpc_ctx
    %STDL-F-CDRSYSIDLERR, Error invoking IDL compiler
    Workaround:
    Make sure that no composable tasks are defined in task groups when compiling with DCE as an output adapter.
13. For DCE output adapters you must not use the "Execute call on the caller's thread" execution semantics for the group settings. Setting this option may cause a stack overflow and return the following error codes in einfo: eclass = -7, ecode = 28 (0x1c). In addition the IIS server may become unstable.
    Workaround:
    Use the Management Utility and set either the "Execute call on a separate thread" or "Execute call on a separate thread, but limit maximum threads to" execution semantics for the group.
14. Automation does not support user-defined datatypes. In order to handle user defined datatypes, such as records, each record must be defined as a separate object. For embedded records the software creates an object with the name <field-name>_RECORD. If two embedded records in the same task or processing group file have the same field name, then the software will declare two objects with the same name. This causes an error. (QAR 019)
    Workaround:
    X/Open or MIA Syntax:
    Make sure embedded records in the same task or processing group have unique field names.
    X/Open Syntax only:
    Declare the embedded records as separate datatype, then reference the user-defined type in the field definition.
    For example:

             Invalid syntax for Automation Adapter:

             TYPE MOVE_REC1 IS RECORD
                   FLD_1 IS INTEGER;
                   FLD_2 IS OCTET;
                   FLD_3 IS RECORD
                      FLD3_1 TEXT SIZE 7;
                      FLD3_2 INTEGER;
                   END RECORD;
             END RECORD;

             TYPE MOVE_REC2 IS RECORD
                   FLD_1 TEXT SIZE 8;
                   FLD_2 DECIMAL STRING SIZE 3;
                   FLD_3 IS RECORD
                      FLD3_1 TEXT SIZE 7;
                      FLD3_2 INTEGER;
                   END RECORD;
             END RECORD;

             Valid syntax for Automation Adapter:

             TYPE USER_TYPE IS RECORD
                   FLD3_1 TEXT SIZE 7;
                   FLD3_2 INTEGER;
             END RECORD;

             TYPE MOVE_REC1 IS RECORD
                   FLD_1 INTEGER;
                   FLD_2 OCTET;
                   FLD_3 USER_TYPE;
             END RECORD;

             TYPE MOVE_REC2 IS RECORD
                   FLD_1 TEXT SIZE 8;
                   FLD_2 DECIMAL STRING SIZE 3;
                   FLD_3 USER_TYPE;
             END RECORD;

### Troubleshooting Tips

#### Registering and Unregistering Automation DLLs

- There are certain times when the user must unregister and re-register an Automation server. If you are adding or removing methods, changing the number or type of arguments or changing the fields in a record you should unregister the existing Automation DLL using the regsvr32 -u command before you build the new DLL. Failure to issue the unregister command using the exact same DLL that was used when registering can cause the following problems:
  1. The unregister command will not be able to remove all associated Windows NT Registery entries.
  2. The unregister command will signal errors.

  If you forgot to unregister before you built the new DLL and receive errors when unregistering, then select to continue if prompted. Next re-register the new DLL. If the Automation DLL registers successfully the new Automation interface should be available. If not try unregistering and registering again.
  If you don't re-register an Automation DLL and have changed any of the information mentioned above, then the Automation server will not work correctly because the registered Automation interface will be out of sync with the Automation interface in the DLL.

- If you receive the following error message when registering an Automation DLL, it means that you have already registered the DLL or forgot to unregister the existing DLL before building a new version. If this is a new version of the DLL, then unregister the DLL before re-registering.
  Error:
  This interface is already registered.
- If you receive the following error message(s) when registering or un-registering an Automation DLL, then check that the STDL_SYS_DIR environment variable is defined and in the current path. If you did not reboot after installing the kit you should do so.
  Errors:
  The dynamic link library stdl_rtm.dll could not be found in the specified path
  LoadLibrary ("<name-of-dll-appears-here>") failed
  Get Last Error returns 0x0000007e
  Please check that the STDL_SYS_DIR environment variable is defined and in the current path. If you did not reboot after installing the kit you should do so.

#### Environment Setup

- If the Automation server has already been loaded by IIS, issuing the regsvr32 -u command for a DLL will NOT unload it from the IIS DLL cache. To clear the cache, stop all IIS services (make sure you stop the WWW service last ).
- If you receive a HTTP Not Supported error message when running the Web Samples then ASP is not installed. Please see Microsoft Windows NT Service Pack 2 for information on installing IIS 3.0 and ASP.
- If you want to use DCE output adapters to call ACMSxp tasks, you must configure the account under which IIS executes to be part of the administrator’s group. Failure to do so causes IIS server process to terminate. ACMSxp software engineering is working on reducing this requirement. Please send e-mail to us at acmsxp_info@camino.enet.dec.com if you are interested in this issue.
- For DCE output adapters you must not use the "Execute call on the caller's thread" execution semantics for the group settings. Setting this option may cause a stack overflow and return the following error codes in einfo: eclass = -7, ecode = 28 (0x1c). In addition the IIS server may become unstable. Use the Management Utility and set either the "Execute call on a separate thread" or "Execute call on a separate thread, but limit maximum threads to" execution semantics for the group.
- IIS caches the runtime DLLs when processing requests. IIS keeps these DLLs loaded indefinitely. If you need to uninstall or re-install the kit stop all IIS services (make sure you stop the WWW service last ). This will ensure any cached DLLs are unloaded.

- When installing additional components to the TP Web Connector kit the user must first uninstall the kit and then reinstall the selected components. If the user does not uninstall the kit before re-installing specific components, the user will not be able to cleanly uninstall the kit.

#### Development

- The automation interface for Tasks or Processing procedures takes as parameters the objects representing the workspace parameters. If any of these objects has been set to "Nothing", an access violation will occur when the method is called. Make sure that the parameters passed to a task method reference valid objects.

- When building the ACMSxp Add sample, you may ignore the following warning:
  LINK : warning LNK4098: defaultlib "LIBC" conflicts with use of other libs; use /NODEFAULTLIB: library
- If you are having problems getting your Automation server to run correctly under IIS then try writing a simple Visual Basic program to access the Automation objects. Use the following steps to add the Automation server's type library to a Visual Basic project:
  1. In Visual Basic 5.0 start a new project.
  2. Select the Project/References menu option.
  3. Add the type library that was created for your processing or task group. Also add a reference to the STDL type library.

  You can now use the Object Browser provided with Visual Basic to view the Automation objects' properties and methods.

- When developing applications for use with IIS make sure you remember to unload the DLL from the IIS DLL cache before building a new version. To clear the cache, stop all IIS services (make sure you stop the WWW service last ). If IIS still has the DLL loaded you will not be able to delete or replace the existing file and the following error will be displayed when rebuilding the DLL:
  LINK : fatal error LNK1104: cannot open file "<dll-name-appears-here>"

### Interpreting Runtime Error Codes

#### Location of Runtime Error Code Information

Other than Automation errors as described below, TP Web Connector returns error information in einfo.ecode. These error codes and their descriptions can be found in the following files:
<installed-kit>\stdl\include\stdlrt_msg.h
<installed-kit>\stdl\include\acmsda_client_messages.txt
The stdlrt_msg.h file contains errors for TPware runtime exceptions. The range of these errors is 01 to 255 (0x001 to 0xff).
The acmsda_client_messages.txt file documents the ACMS Desktop Adapter Gateway error codes. The range of these errors is -3000 to -3199 (0xfffff448 to 0xfffff381). Please examine this file to evaluate and respond to Gateway errors as logged in the ACMS Software Error log (SWLUP). Also see SYS$HELP:ACMSDA$GATEWAY_MESSAGE.TXT on the VMS system.

#### Interpreting Automation Errors

In order to interpret Automation runtime errors, do the following. Runtime Automation error values are returned using a 32- bit number known as a result handle (i.e. HRESULT). The structure of a HRESULT value is defined by Microsoft. Automation errors returned by the TP Web Connector /Database Web Connector start at 214774989 (0x80041001). These values can be translated to error codes found in stdlrt_msg.h using the following formula:
STDL error code = <Automation-error-code-value> - 0x80041000

#### Interpreting ACMS Desktop Adapter Gateway on VMS

The following error message logged in the ACMS Software Logging Utility (SWLUP) by the ACMS Desktop Adapter Gateway can be ignored:
%ACMSDA-E-INTERNAL, Internal ACMSDA RPC error Deletion of network command mailbox failed: 13c
This error code occurs when terminating the ACMS Desktop Adapter Gateway (ACMSDA$GATEWAY) using the ACMSDA$SHUTDOWN.COM procedure. The error code 13c translates to SYSTEM-F-INVCHAN - Invalid I/O channel which is caused by attempting to use a DECnet network mailbox. DIGITAL DECnet software is not required to operate this DIGITAL TPware product. This error condition will be removed in a future release.

### DIGITAL TP Web Connector Version 1.0 for Open VMS

This section provides the release notes for DIGITAL TP Web Connector Version 1.0 for OpenVMS. Known problems as well as hints and suggestions are also provided.

#### The WEB output file from ADU is always written to the default directory, it is not affected by the DEFAULT TASK GROUP FILE clause in the group definition.

#### The following CDD data types are unsupported:

- VARYING STRING
- SEGMENTED STRING
- H_FLOATING
- H_FLOATING COMPLEX
- POINTER
- BIT

> Unsupported CDD data types produce a valid STDL file. When building or linking a group definition with one of these data types, a warning will be generated, example:

> > %ACMSTDU-W-WEB_UNSUPDTYPE, UnSupported Datatype ‘Segmented String’.

> The STDL file will generate an ARRAY OF OCTET of the appropriate size with a comment such as:

> > !The unsupported data type UNKNOWN VMS DATA TYPE has been defined as an OCTET ARRAY.

> The following CDD data type attribute is unsupported and will prevent the generation of an STDL file:

> > VARIANTS/VARIANT

> The following warning will be generated when building or linking a group definition:

> > %ACMSTDU-W-WEB_VARIANT, ‘variants not supported’

#### Limits on Runtime System Resources

Limits on runtime system resources can be exceeded depending on the number of connections to the ACMS Desktop Adapter Gateway. Since the exceeding of system resources is not handled very well by the system, controlling the number of threads per connection is important. In the TPware program group, Management Utility, TPware Configuration, Threads tab, set the maximum number of threads to limit possible problems with the usage of system resources. Setting the number of threads will limit the number of concurrect connections to that number of threads.

### Associated Documentation

In addition to this guide, the DIGITAL TP Web Connector for Windows NT documentation set includes the following:

- TPware Getting Started
- TPware for Windows NT online help

Related Documents

- OSF DCE Administration Guide - Core Components

© Digital Equipment Corporation 1997. All Rights Reserved.

Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor.

The following are trademarks of Digital Equipment Corporation:

- ACMS, ACMSxp, Alpha, DEC, DIGITAL, OpenVMS and the DIGITAL logo.

The following are third-party trademarks:

- MS, Windows NT, Visual C++, Visual Basic, Intel, X/Open