# Compaq TP Desktop Connector
for ACMS
Gateway Management Guide

Previous | Contents | Index

## 3.4.3 Building Client Applications for NetWare

The following sections describe how to build client applications for the DOS (see Section 3.4.3.1) and Windows clients (see Section 3.4.3.2) using the NetWare transport.

### 3.4.3.1 Building DOS Client Applications for NetWare

DOS programs link against the file `acmnsdiL.lib`.

Before linking the program, replace the current network object module with the netware object module in the selected library. For example, to use the large memory model:

    C:\> lib acmsdil.lib -netdecl.obj;
    C:\> lib acmsdil.lib +netwarel.obj;

There is also an additional module required for NetWare that needs to be added to the selected library to handle NetWare events, for example:

    C:\>  lib acmsdil.lib +spxesrl.obj;

To compile your source code with the TP Desktop Connector NetWare libraries, use a statement in the following format for the large-memory model:

`cl -c -aL -0d -Zpei -Fs your_source_code.c`

To link your source object with the TP Desktop Connector NetWare libraries, consider the following command:

    link -M -STL16000 -SE:256 -NOE -CO your_source_object,,,acmsdil llibce lnwipxsp nwcalls;

Note These compile and link statements create debug objects and images. To remove debugging information from your object and executable image, change -Zpei to -Zp in the compile statement and remove the -CO flag from the link statement.

### 3.4.3.2 Building Windows Client Applications for NetWare

To compile your source code with the TP Desktop Connector Netware DLL, use a statement in the following format for the large-memory model:

`cl -d -c -aL -Gsw -0d -Zpei -Fs -d WINDOWS -d ACMSDI_DLL your_source_code`

To link your source object with the TP Desktop Connector NetWare DLL, use a command in the following format:

`link -NOD -CO your_source_object,,,llibcew libw, your_def_file.def`

Note These compile and link statements create debug objects and images. To remove debugging information from your object and executable image, change -Zpei to -Zpe in the compile statement and remove the -CO flag from the link statement.

Example 3-2 is a sample Windows definition file used when linking with the TP Desktop Connector NetWare DLL.

Example 3-2 Sample Windows Definition File for NetWare C

    ; module-definition file for wintest---used by LINK.EXE

    NAME         wintest       ; application's module name

    DESCRIPTION  'TP Desktop Connector Test Client'

    EXETYPE      WINDOWS       ; required for all Windows applications

    STUB         'WINSTUB.EXE' ; Generates error message if application
                               ; is run without Windows

    CODE  PRELOAD MOVEABLE DISCARDABLE
    DATA  PRELOAD MOVEABLE MULTIPLE

    HEAPSIZE     32768
    STACKSIZE    5120          ; recommended minimum for Windows applications

    ; All functions that will be called by any Windows routine
    ; MUST be exported.

    EXPORTS
            MainWndProc   @1   ; name of window processing function
            About         @2   ; name of "About" processing function
    IMPORTS
            ACMSDI.acmsdi_sign_in
            ACMSDI.acmsdi_sign_out
            ACMSDI.acmsdi_call_task
            ACMSDI.acmsdi_dispatch_message
            ACMSDI.acmsdi_complete_pp
            ACMSDI.acmsdi_return_pointer
    EXPORTS
            acmsdi_check_version
            complete_sign_in
            complete_sign_out
            complete_task

## 3.4.4 Troubleshooting for the NetWare Transport

The following sections provide tips for troubleshooting the IPX/SPX from InterConnections (see Section 3.4.4.1), tips for troubleshooting the gateway (see Section 3.4.4.2), and tips for raising quotas (see Section 3.4.4.3).

### 3.4.4.1 Troubleshooting IPX/SPX Stack from InterConnections

Keep the following troubleshooting tips in mind for the IPX/SPX stack:

- Add the IC_STARTUP.COM startup procedure to your systemwide startup command procedure. This ensures that the QXDRIVER is loaded each time your OpenVMS system is started.
- Startup order is important. The QXDRIVER must be started before the gateway.
- To verify that the QXDRIVER has been started, do the following:
  1. Invoke the Leverage Host Services control program:

         $ qxcp

  2. At the XCP prompt, show the status:

         XCP> sho status

         QXDRIVER Status

           QXCP version = 3.1.4
           QXDRIVER version = 3.5
           QXCP/QXDRIVER comms versions = 007 / 007
           QXDRIVER template device = _QXA0:   QXDRIVER state is STARTED
           Ethernet/802 (NI) device = _ESA10:
           Host address = AA-00-04-00-03-F9
           Protocol type = 81-37
           Network number = 00000002
           Maximum buffer size = 1500
           Maximum well-known sockets = 30
           Maximum ephemeral sockets = 90
           Maximum SPX connections = 106
           ETHERNET (NI) receive buffers = 10
           Driver mode = IPX/SPX over Ethernet

  3. Check that the QXDRIVER state is started.
  4. Check that the driver mode specifies IPX/SPX over Ethernet.
- If the QXDRIVER fails to start properly, check your Ethernet driver in the command procedure IC$SPECIFIC:[IPX]IPX_LOAD.COM. It should match the Ethernet driver on your system. In Example 3-3, the Ethernet driver is ESA0. The InterConnections installation should configure this parameter correctly.

  Example 3-3 Checking the Ethernet Driver in IPX_LOAD.COM

      $ d_element=F$LOCATE(datalink,"802.2!802.3!SNAP !ETHER")/F$LENGTH("802.2!")
      $ ethertype:='F$ELEMENT(d_element," ","00E0 0000 00AA 3781 ")

      $ xcp start /qxdev=_qxa0:-        ! QX driver to start
              /bufsiz=1500-             ! Maximum IPX message data size
              /esckmax='ephem_sockets'- ! Maximum # of ephemeral sockets
              /wsckmax=30-              ! Maximum # of well-known sockets
              /nibuffers='nibuffers'-   ! Number of Ethernet Received Buffers
              /spxconmax='spxconmax'-   ! Maximum of SPX Connections
              /protyp='ethertype'-      ! Ethernet protocol number"
              /nidev=_ESA:-             ! Ethernet driver
              /network=00633905         ! Modified by LHSconsole 11-OCT-1995 15:57:58
      $

  To verify the Ethernet Driver setting, use the SHOW DEVICE command on OpenVMS to see what your Ethernet Driver is.

- The Ethernet protocol number in the command procedure IC$SPECIFIC:[IPX]IPX_LOAD.COM must match the standard being used on your NetWare network.
  - If you are running Ethernet Type II interface, set the Ethernet protocol number to 3781 to bring up the QXDRIVER using Ethernet.
  - If you are running 802.3 framing, set /PROTYP to 0000, instead of 3781.
  In Example 3-3, the command sets the Ethernet protocol number to 3781.
- If you have a NetWare file server, ensure that your network number matches the number of the NetWare file server. To check the network number, when you start up IPX/SPX on OpenVMS, look at the startup procedure IC$SPECIFIC:[IPX]IPX_LOAD.COM.
  The number with /NETWORK (for example, /NETWORK=00633905 in Example 3-3) must match your Novell NetWare file server number. To find out what the file server number is, do the following:
  1. Invoke IPX:

              $ QXCP

  2. Start the IPX History at the XCP prompt:

              XCP> START IPX HISTORY

  3. Wait a minute.
  4. Show IPX History:

              XCP> SHOW IPX HISTORY
              IPX History :: Socket <0000> Network >00000000> Router <0> entries<60>

              Time     ImmDst       ImmSrc       CRC  Len  Xpt Typ Dnetwrk  Dhost
         Dsck Snetwrk  Shost        Ssck
         R 10:01:05.89 FFFFFFFFFFFF 00001B263AEC FFFF 6000 00  00  05396300 FFFFFFFFFFFF
         5204 05396300 00001B263AEC 5204
           Data: 00 02 00 04 49 4E 46 4F 53 45 52 56 45 52 00 00 00  ....INFOSERVER...
         R 10:01:28.04 FFFFFFFFFFFF 08002B25FEF5 FFFF 2800 00  00  05396300 FFFFFFFFFFFF
         5304 05396300 08002B25FEF5 5304

  5. Stop the IPX History at the XCP prompt:

         XCP> STOP IPX HISTORY

     The DNETWRK 05396300 is the network number of the Novell file server INFOSERVER.

  Note If you are using the SHOW IPX HISTORY command to obtain the network number of the Novell file server, byteswap the network number in the display before using it to start IPX/SPX on OpenVMS. For example, 05396300 is byteswapped to 00633905. This byteswapped number is also used for DOS clients connecting by an Ethernet number and a network number of a Novell file server.

### 3.4.4.2 Troubleshooting the Gateway

To verify that the gateway process and the SAP process have started with the NetWare transport, do the following:

1. Invoke IPX:

       $ QXCP

2. Show socket information:

       XCP> SHOW SOCKET
       Socket Sts    Unit UCBcnt      Xmtcnt      Rcvcnt

            0452  0003      2    0            51          20
            837A  0027      3    0             0           0

   At least two sockets must be open:
   - Socket number 0452 = ACMSDI$SAP
   - Socket number 837A = ACMSDI$SERVER
3. Check that both the gateway and the TP Desktop Connector SAP process have started on the OpenVMS system.
4. At the DCL prompt, issue the following command:

       $ SHOW SYSTEM
       VAX/VMS V5.4-2  on node ASTI  11-SEP-1992 15:53:45.30   Uptime  9 06:42:51
         Pid    Process Name    State  Pri      I/O       CPU       Page flts Ph.Mem
          .
          .
          .
       2D00015B ACMSDI$SERVER   LEF      4      179   0 00:00:02.20       706    712
       2D00015C ACMSDI$SAP      HIB      5      120   0 00:00:00.97       458    408
          .
          .
          .

5. If the TP Desktop Connector SAP process cannot connect to the Service Advertising Socket number (0452), then another process may have opened the socket, not allowing other processes to gain access.
   The TP Desktop Connector SAP allows other processes to open the Service Advertising Socket and can coexist with other applications that do the same. If this is happening, you can do the following:
   1. Shut down the application that is causing the problem. Start up the TP Desktop Connector SAP. This solution allows only the SAP to start. The second application cannot start.
   2. Change the application that is causing the problem to allow other processes access to the Service Advertising Socket.
   3. Do not start up the TP Desktop Connector SAP. Set environment variables on the DOS clients to the Ethernet address of the gateway node and the NetWare network number.

If you follow these steps and the desktop process still does not start, use the ACMS utility SWLUP for more information.

### 3.4.4.3 Quotas

You may need to raise default quotas to establish more client connections. The following quotas illustrate support for 100 TP Desktop Connector clients:

- gateway (ACMSDI$STARTUP.COM)---Buffered I/O Byte Count

      /Buffer_Limit=1000000

- IPX/SPX Stack from InterConnections (IC$SPECIFIC:[IPX]IPX_LOAD.COM):
  - Ephemeral sockets
  - Well-known sockets
  - SPX connections:

      xcp start /qxdev=_qxa0:- ! QX driver to start
                /nidev=_ESA:- ! Ethernet driver
                /protyp=3781- ! Ethernet protocol number
                /bufsiz=1500- ! Maximum IPX message data size
        >>>>    /esckmax=100- ! Maximum # of ephemeral sockets
        >>>>    /wsckmax=100- ! Maximum # of well-known sockets
                /network=00633905- ! NetWare network number
                /nibuffers=10- ! Number of Ethernet Received Buffers
        >>>>    /spxconmax=100  ! Maximum of SPX Connections

## 3.4.5 NetWare Transport Installation Checklist

When installing the NetWare transport for TP Desktop Connector, do the following:

1. Install TP Desktop Connector on your OpenVMS system (refer to Compaq TP Desktop Connector for ACMS Installation Guide).
2. Install NetWare on your OpenVMS system.
3. Start up the QXDRIVER.
4. Start up the gateway specifying NetWare as a transport.
5. Install the TP Desktop Connector API for NetWare on your DOS system (refer to Compaq TP Desktop Connector for ACMS Installation Guide).
6. Install the NetWare client libraries.
7. Configure the DOS system for NetWare.
8. Use the NetWare SLIST command to check whether the gateway is there. The gateway process appears as ACMSDISERVER-ON-nodename.

# 3.5 Using the TCP/IP Transport

Transmission Control Protocol Internet Protocol (TCP/IP) is an Internet protocol suite. TCP/IP offers two means of task-to-task communications, UDP and TCP. TP Desktop Connector uses TCP for communications from client to server. TCP has the following features:

- Connection-based
- Reliable
- Sequenced
- Byte-stream service
- Connection set-up overhead

## 3.5.1 Preparing the Gateway for the TCP/IP Transport

The gateway uses TCP/IP Services for OpenVMS Version 3.2. The QIO services, provided by this product, perform TCP/IP I/O. The gateway has also been tested using Multinet Version 3.2 from TGV, Inc.

When TCP/IP is activated in the gateway, it listens for TCP/IP connections.

### 3.5.1.1 Installation Requirements for the Gateway Using TCP/IP

When using TCP/IP as a transport, you must install and start TCP/IP Services for OpenVMS software before starting the gateway.

### 3.5.1.2 Activating the Gateway on TCP/IP

By default, TCP/IP is not activated by the gateway. The gateway must be started with a parameter file. You must place the string TCPIP in the transport list. For example, to activate TCP/IP and DECnet in the gateway, you can place the following line in the gateway parameter file:

    Transport=(TCPIP,DECnet)

This line causes the gateway to listen for connections on both DECnet and TCP/IP transports.

### 3.5.1.3 Setting an Alternate Gateway TCP/IP Port Number

By default, the gateway listens for connections to TCP/IP port number 1023. This is the highest privileged port number provided by TCP/IP Services, and is the recommended port number to use. However, if an alternate port number must be used, include a line in the gateway parameter file with the desired port number. For example:

    TCPIP_PORT=1022

This line causes the gateway to listen for connect requests to TCP/IP port number 1022 on the gateway system. Of course, the client must also be aware of the alternate port number to use. See Section 3.5.2 for information on the TCP/IP client implementation.

## 3.5.2 Preparing the Client for the TCP/IP Transport

The following clients currently support the TCP/IP transport:

- DOS using PATHWORKS for DOS (TCP/IP)
- Macintosh using PATHWORKS for Macintosh (MacTCP Tool)
- Microsoft Windows using PATHWORKS for DOS (TCP/IP)
- Microsoft Windows using WINSOCK Version 1.1 compatible TCP/IP implementation

TP Desktop Connector software supports use of TCP/IP with the OpenVMS VAX operating system for debugging purposes only.

### 3.5.2.1 Configuring the Libraries for TCP/IP

The following sections describe how to configure your static-link libraries (see Section 3.5.2.2) and your dynamic-link libraries for TCP/IP (see Section 3.5.2.3).

### 3.5.2.2 Using the TCP/IP Transport on DOS and Static-Link Libraries

The TP Desktop Connector DOS implementation uses the PATHWORKS TCP/IP implementation. The TCP/IP static-linked libraries are supported only when used with PATHWORKS Version 5.0 or higher.

The DOS API uses the static-link library ACMSDIL.LIB, which works with the large-memory model. The transport object files provided for the large-memory model is NETTCPL.OBJ.

DOS programs that use the static-link libraries need to replace the DECnet object with the TCP/IP object in the ACMSDI library. This is done in the following manner:

    C:\DEVELOP>LIB ACMSDIL -NETDECL +NETTCPL;

PATHWORKS TCP/IP static-link libraries for DOS and Windows applications are available on the PATHWORKS software developers kit. These static-link libraries are not available from the TP Desktop Connector kit. The files to be used are described in the PATHWORKS documentation set. In addition to linking with ACMSDIL.LIB, you will need to link against LPWSOCK.LIB and LNMAPI.LIB.

### 3.5.2.3 Using the TCP/IP Transport on Microsoft Windows

Several TCP/IP vendors have agreed on a standard interface to TCP/IP on Microsoft Windows. This standard is known as WINSOCK. Using the WINSOCK standard, you can write applications without regard to the specific TCP/IP Microsoft Windows implementation, if the implementation supports the WINSOCK standard.

To use this standard with Microsoft Windows, Windows 95, and Windows NT, TP Desktop Connector provides TP Desktop Connector DLLs that support the TCP/IP implementation of WINSOCK that conforms to the Version 1.1 standard. To use the TCP/IP winsock transport, select the TP Desktop Connector ACMSDIDN.DLL. Create a copy of the ACMSDIDN.DLL file and rename this to ACMSDI.DLL so that the application can be linked against it. Place the ACMSDI.DLL file in the executable path so that it can be located by the operating system when running the application.

These files are located on the OpenVMS server in the SYS$COMMON:[ACMSDI] directory tree in the appropriate self-extracting archive. Although the files are unique to the operating system, they have the same file name. Refer to Compaq TP Desktop Connector for ACMS Installation Guide to locate the appropriate file for your Windows operating system.

Under Windows Version 3.1, copy the file ACMSDIWS.DLL to ACMSDI.DLL and link against the resulting file by specifying it and the ACMSDI API procedures being used in the imports section of the applications definition file. Under Windows NT or Windows 95, link against the DLL reference library.

Table 3-7 lists the available libraries.

Table 3-7 Available Libraries
Operating System | Winsock DLL | Target DLL | Link File
--- | --- | --- | ---
Windows 3.1 | ACMSDIWS.DLL | ACMSDI.DLL | ACMSDI.DLL (named in .DEF file)
Windows NT | ACMSDIWS.DLL | ACMSDI.DLL | ACMSDI.LIB (reference library)
Windows 95 | ACMSDIWS.DLL | ACMSDI.DLL | ACMSDI.LIB (reference library)

## 3.5.3 Using TCP/IP with Applications Composed of Multiple Executables

TP Desktop Connector software provides a task-link extension that allows you to have existing Windows Version 3.1 programs that are composed of several executables working together over TCP/IP to provide a unified application. The individual executable tasks pass the TP Desktop Connector submitter ID between them and attempt to use the same network connection to the TP Desktop Connector server. These are typically Visual Basic applications that were initially developed and deployed using DECnet for communication. When DECnet was used for the transport, the existing multiple .EXE applications worked because DECnet allowed multiple tasks to share a connection. There are difficulties when attempting to make this kind of application use TCP/IP.

The basic problem is that one customer-written Windows task is establishing a Winsock network connection and then another Windows task is trying to use that connection. This scenario is not supported under Winsock V1.1. When trying to use Winsock V1.1, the application fails because Winsock requires that each Windows task initialize the link before allowing communication to take place. Link initialization implies the establishment of a new connection to the TP Desktop Connector server and the use of a new socket. The Winsock standard does not support the sharing of sockets across tasks. Therefore, the use of different connections and sockets requires the establishment of new submitter sign-in sessions and the use of a user license on the TP Desktop Connector server.

The task-link extension provides a means by which you can move existing multi-part TP Desktop Connector applications from DECnet to TCP/IP when those applications can not be modified to use a single TP Desktop Connector connection task.

The task-link extension is available for only Windows Version 3.1 and Windows for Workgroups Version 3.11 when using the TP Desktop Connector client in its Winsock DLL form. When running under Windows Version 3.1, the memory allocated by acmsdi.dll is visible to all tasks, and so the passing of the submitterID between tasks is possible. This is not the case when running as a 32-bit application under Windows 95 and Windows NT. The task-link extension can also be used when running as a 16-bit application running under Windows 95 and Windows NT.

Previous | Next | Contents | Index