To compile your source code with the TP Desktop Connector Netware DLL, use the following statement 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 the following command:

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 and tips for troubleshooting the gateway.

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 the following example, the Ethernet driver is ESA0. The InterConnections installation should configure this parameter correctly. To verify this, use the Show Device command on OpenVMS to see what your Ethernet Driver is.

  $ $ 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 $

• The Ethernet protocol number must match the standard being used on your NetWare network. If you are running Ethernet Type II interface, set the Ethernet protocol number in the command procedure IC$SPECIFIC:[IPX]IPX_LOAD.COM to 3781 to bring up the QXDRIVER using Ethernet. If you are running 802.3 framing, set /protyp to 0000, instead of 3781. The previous example 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 the previous example 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 OpenVMS.
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 environmental variables on the DOS clients to the Ethernet address of the gateway node and the NetWare network number.

After following these steps, if the desktop process still does not come up, 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 onto your OpenVMS system (see DIGITAL TP Desktop Connector for ACMS Installation Guide).
2. Install NetWare onto 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 onto your DOS system (see DIGITAL 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 if the ACMSDI gateway is there. The gateway appears as ACMSDISERVER-ON-nodename.

Transmission Control Protocol Internet Protocol (TCP/IP) is an Internet protocol suite from the United States Department of Defense research community.

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 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 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 and your dynamic-link libraries for TCP/IP.

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, as long as 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 DIGITAL 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 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 scenerio 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.

3.5.3.1 Enabling the Task-Link Extension

TP Desktop Connector provides the task-link extension by modifying the behavior of the TP Desktop Connector TCP/IP DLL. Whether or not the acmsdiWS.dll behaves normally or in the modified task-link manner is determined when it is first loaded. On a given system, it will act one way or the other. Applications running on a given system are either using the DLL for multi-part applications or they are not. No provision has been made to have some applications use an additional external task and others not within a single user session. The existing acmsdiWS DLL has been modified to be able to work in its normal mode or to communicate to Winsock through an external common task. It will, by default, continue to work as it did in V2.2.

You enable the task-link extension by defining an environment variable, ACMSDI_TASKLINK, before starting Windows to indicate that the acmsdiWS DLL is to operate in the modified manner.

You can define ACMSDI_TASKLINK to be the name of the common task executable such as "ditsklnk" if the ditsklnk.exe is in the executable path. You can also use it to define a full path name to be used to locate the common task's executable as in c:\acmsdi\ditsklnk.exe. If you do not define ACMSDI_TASKLINK, then the diTskLnk executable file is not used.

The new task image, diTskLnk.exe, along with its icon (acms01.ico) it can be found in the directory where the msdos.exe self-extracting archive is unpacked along with the DLLs, LIBs and other object files.

3.5.3.2 Task-Link Extension Functional Description

The approach used to provide the task-link extension was chosen to provide a workaround that does not require any changes to your application. The basic approach is to funnel all network requests originating in the individual executables that make up an application through a common task. Because of the constraint that the solution does not require code changes to the application, the TP Desktop Connector acmsdiWS.dll creates and runs the additional task. It starts an additional task named diTskLnk and runs it with a minimized window. It starts and runs one Windows task for each connection that it establishes to the host.

The connection is established at the time of acmsdi_sign_in. When the acmsdi_sign_out is issued, the connection is removed and the corresponding diTskLnk task is terminated. The diTskLnk.exe task is just a minimal Windows program that looks for a single application unique Windows message. When it receives a message, it calls into the acmsdiWS.dll at a private entry point passing in the value of the message.

All network traffic is from these diTskLnk tasks, not the application task executables. The network requests in the acmsdiWS.dll, running in the context of the calling application task, are passed off to the diTskLnk task. This is what allows Winsock to accept that the task has initialized the connection. The actual data, such as that for the task workspaces, is not moved around by this approach, it is just placed where it normally would be and the DLL deals with it directly. No data other than the requesting message is passed between the application tasks and the diTskLnk task. If the request was for a connection disconnect, once it is completed the DLL deletes the corresponding diTskLnk.

Once an executable signs in and establishes a submitter ID that it subsequently passes off to another application, it should no longer make any references to that submitter ID. Once it is passed, it is up to the executable that received it to either sign it out, or, in turn, pass it on to another executable.

The connection and submitter state continues to be managed by the code in the acmsdiWS.DLL. However, the part of the code in the DLL that does the low level Winsock communication runs in the context of the diTskLnk task, not the calling application task. It is the diTskLnk task that owns the connection.