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;

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

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.

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

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.

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

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.