TP Desktop Connector is designed to use DECnet by default. Therefore, only a few steps are involved in setting up the gateway and client systems to use DECnet as a transport.

3.3.1 Preparing the Gateway for DECnet

DECnet must be installed and running before you start the gateway.

3.3.1.1 Activating the Gateway for DECnet

The gateway must be activated to use the transports that its TP Desktop Connector clients will be using. There are two ways to activate the gateway for DECnet:

• Run the gateway startup procedure without using a startup parameter file, or do not specify any transport in the ACMSDI startup parameter file.
  By default, the gateway starts with support for DECnet.
• Run the gateway startup procedure using a startup parameter file, specifying DECnet as a transport in the startup parameter file.
  Use this approach if the gateway needs to support other transports in addition to DECnet. For example, if the gateway needs to support DECnet and NetWare:
  1. Create a startup parameter file called SYS$STARTUP:ACMSDI$PARAMS.DAT, which contains the following line:

     TRANSPORT=(DECNET,NETWARE)

  2. Add the following command to your system startup command procedure:

     @SYS$STARTUP:ACMSDI$STARTUP SYS$STARTUP:ACMSDI$PARAMS.DAT

TP Desktop Connector supports use of DECnet on the following TP Desktop Connector platforms:

• DOS and Microsoft Windows (using PATHWORKS for DOS)
• Windows 95 (using PATHWORKS for Windows 95)
• Windows NT (using PATHWORKS for Windows NT)
• Macintosh (using the DECnet tool or the AppleTalk-DECnet Tool)
• OpenVMS

Microsoft Windows applications can use DLL versions of the TP Desktop Connector client services and DECnet. The TP Desktop Connector DLL (ACMSDIDN.DLL) is preconfigured to use DECnet. To use the DECnet 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 ACMSDIDN.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.

Operating System	DECnet DLL	Target DLL	Link File
Windows 3.1	ACMSDIDN.DLL	ACMSDI.DLL	ACMSDI.DLL (named in .DEF file)
Windows NT	ACMSDIDN.DLL	ACMSDI.DLL	ACMSDI.LIB (reference library)
Windows 95	ACMSDIDN.DLL	ACMSDI.DLL	ACMSDI.LIB (reference library)

3.3.2.2 Building the Client for DECnet Using Static-link Libraries

The DOS API uses the static-link library, ACMSDIL.LIB, for the large-memory model. There is a transport object files provided for the large-memory model

PATHWORKS DECnet 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.3.2.3 Controlling the Number of Concurrent Users

The DECnet parameter MAXIMUM LINKS on your desktop system controls how many copies of your desktop client program you can run simultaneously. You need one link for each active file server and one link for each active desktop client program instance. Additional links are not required for multiple sign-ins started in a single desktop client program instance, unless they are connecting to different gateways.

Use the following command to see the current value of MAXIMUM LINKS on your desktop system:

$ MCR NCP SHOW EXECUTOR CHARACTERISTICS

Use the following command on your desktop system to set the value:

$ MCR NCP DEFINE EXECUTOR MAX LINKS

3.3.3 Troubleshooting the DECnet Transport

If the client is unable to create a session with the gateway, take the following steps on the client to determine if the client can reach the gateway node:

1. Use NCP to determine if the gateway node name is defined in the client database:

   C:\> NCP SHOW NODE serv

   
   where serv is the name of the node where the gateway resides.

2. Use various tools to determine if the node is reachable at this time.
   1. Use NCP TELL:

      C:\> NCP TELL serv SHOW EXEC

   2. Use NTF COPY:

      C:\> NFT COPY AUTOEXEC.BAT serv"username *"::

   3. Use SETHOST:

      C:\> SETHOST serv

If the node is reachable, but the application cannot sign in to TP Desktop Connector or the client cannot call a particular task, do the following:

1. Use SHOW SYSTEM to determine if the gateway is running:

   $ SHOW SYSTEM

   
   Look for the process name ACMSDI$SERVER. If this process is present, the gateway is running.

2. Use NCP to determine if the gateway is listening for DECnet connections. The gateway uses the DECnet object 87. For example:

   $ MCR NCP SHOW OBJECT OBJ_87 Object Volatile Summary as of 11-MAR-1993 09:41:53 Object Number File/PID User Id Password OBJ_87 87 202118DF

   
   If this object is present, the gateway is listening for connections from DECnet clients.
   If a large number of users are connecting to the gateway using DECnet, you need to increase DECnet services quotas. The quotas include:

   1. Maximum number of links
   2. Nonpaged pool parameters (SRP, IRP, or LRP quotas)
   3. VIRPAGMAX
3. Use ACMS to determine if the ACMS application is running:

   $ ACMS/SHOW APPL my_appl_name

   
   where my_appl_name is the name of your application.
   If the target application is not running, you must start it.

4. Use REPLY to determine if the gateway node is logging network errors:

   $ REPLY/ENABLE=(NETWORK)

See the DECnet documentation for more information.

3.4 Using the Novell NetWare Transport

NetWare is a high-performance network operating system that is a multitasking operating environment. A wide variety of network cards and workstations support NetWare, as well as third-party hardware and software companies.

The TP Desktop Connector implementation of NetWare supports only Ethernet networks. To use NetWare with TP Desktop Connector, on the gateway system you must use an SPX stack from InterConnections, Inc. The SPX stack is provided as part of the Leverage Host Services products.

The SPX stack converts incoming packets from IPX/SPX protocols to Ethernet and outgoing packets from Ethernet to IPX/SPX network protocols. This product includes the following components:

• LHSCONSOLE --- controls the services
• QXDRIVER.EXE --- device driver
• QXCP.EXE --- IPX utility
  • Monitors send and receive IPX/SPX packets
  • Shows the following:
    • Current status of the driver
    • Connections to the driver
    • Sockets open on the driver
    • IPX/SPX history logging
• QXCP.HLB --- help file located in SYS$HELP

When using NetWare with the gateway, QIO calls the QXDRIVER to perform all SPX communications. The gateway acts as an SPX server/acceptor.

TP Desktop Connector does the following as an SPX server:

• Creates a status mailbox and assigns a channel to the QXDRIVER
• Opens the TP Desktop Connector Socket
  TP Desktop Connector Socket number (0x837A) has been authorized by Novell
• Waits to receive a connect request in its mailbox
• Receives and transmits data over each connection

As an acceptor, when a connect request is received, TP Desktop Connector assigns a new channel to the QXDRIVER and the connection is accepted.

3.4.1.1 Activating the Gateway for the NetWare Transport

The gateway supports all transports used by TP Desktop Connector clients. To specify which transports to activate, add the parameter TRANSPORT to the ACMSDI startup parameter file. The following procedure activates both DECnet and NetWare transports:

1. Create a file called ACMSDI$PARAMS.DAT in SYS$STARTUP, which contains the following line:

   TRANSPORT=(DECNET,NETWARE)

2. Add the following command to your system startup command procedure:

   @SYS$STARTUP:ACMSDI$STARTUP SYS$STARTUP:ACMSDI$PARAMS.DAT

3. Make sure that both ACMS and the QXDRIVER have already been started before starting the gateway. Order is important.

TP Desktop Connector runs under OpenVMS as a detached process called ACMSDI$SAP, which advertises the gateway to the network by name, ACMSDISERVER-ON-node. The node is the OpenVMS node name on which the ACMSDI$SERVER is running. The logical name ACMSDI$NETWARE_SERVER_NAME on OpenVMS associates this information. This logical name defaults to the DECnet name of the gateway node.

TP Desktop Connector SAP broadcasts a message to the network every 60 seconds to inform all bridges and file servers on the local network of the gateways identity. NetWare bridges propagate this information to all other bridges on the network. This allows the client to attach to the nearest Novell file server and query for the connection information.

The client sends a Service Advertising Packet to the network identifying the following:

• Gateway type --- file server
• Response type --- general service response
• Network address
• TP Desktop Connector socket number
• Service advertising socket number (0x452)

ACMSDI$SAP responds to general query requests. It receives a Service Advertising Packet from the client, and sends a connection request to the gateway.

3.4.1.3 IPX/SPX Stack from InterConnections

After installing the IPX/SPX stack from InterConnections, images and command procedures are placed in the directories under IC$COMMON:. The files include:

• QXCP.EXE --- IPX utility
• QXDRIVER.EXE --- IPX device driver

IC_STARTUP.COM is placed into the SYS$STARTUP: directory.

Also, the IPX utility help file, QXCP.HLP, is located in SYS$HELP.

3.4.2 Preparing the Client for the NetWare Transport

TP Desktop Connector supports use of the Novell NetWare transport for DOS and Microsoft Windows clients. The following sections describe how to prepare the client for using NetWare.

3.4.2.1 Installation Requirements for Novell NetWare Transport

NetWare software requirements for TP Desktop Connector clients are:

• Microsoft Windows Version 3.1
• Novell NetWare Version 3.x, Version 4.0, or PATHWORKS Version 5.0 for DOS and Windows

TP Desktop Connector supports both static-link libraries for DOS and the dynamic-link library (DLL) for Microsoft Windows. Windows applications must use DLLs.

The API uses IPX/SPX Novell proprietary protocols.

3.4.2.2 Configuring DOS Desktop Systems for NetWare

The DOS client (desktop system) can connect to the gateway in one of three ways:

• If the environmental variable ACMSDI_NETWARE_NAME_gateway node name is set to the Ethernet address of the gateway node, that address and the network number from the environmental variable ACMSDI_NETWARE_NET_gateway node name is used to establish the connection. For example, to connect to node ASTI:

  SET ACMSDI_NETWARE_NAME_ASTI = AA-00-04-00-1D-5C

• If the environmental variable ACMSDI_NETWARE_NAME_gateway node name is set to the gateway name (for example, ACMSDISERVER-ON-NODEA, where NODEA is the name of your OpenVMS system) then the client attempts to connect to the nearest file server to obtain the Ethernet (node) and network addresses of the gateway node. For example:

  SET ACMSDI_NETWARE_NAME_ASTI = ACMSDISERVER-ON-ASTI

• If a file server is unavailable or the search fails, then the client sends a broadcast message to all servers asking all gateways to identify themselves. All gateways respond with their node and network addresses and the client connects to one.

The only way to establish an OpenVMS client connection is to use the Ethernet address of the node on which the ACMSDI$SERVER is running. The environment variable MAXBUF is always set to 512. For example:

$ ! $ ! Ethernet address of the Gateway node $ ! $ DEFINE ACMSDI_NETWARE_NAME_YourNode "AA-00-04-00-1D-5C" $ DEFINE ACMSDI_MAXBUF "512"

If your OpenVMS client and your OpenVMS server are on separate systems, the IPX/SPX stack must be installed on both the client and server systems.

3.4.2.3 Additional Novell SDK files required for NetWare clients

There are files that are required in addition to those that are a part of the TP Desktop Connector or PATHWORKS products. The additional files will be needed to build and run your own Netware client application. If you are building an application based upon DOS static-link libraries, you will need library files to resolve references at link time. If you are building a Windows application you will need to be able to find DLL files at runtime. The additional files are available on the Novell NetWare developers SDK. They have been extracted from the Volume 5 version of that kit and included within the TP Desktop Connector kit.

When the msdos.exe self extracting archive was expanded on the PC client machine as part of the post installation procedure for DOS and Windows clients, it created a subdirectory called netware that contains the additional files.

3.4.2.4 Configuring Libraries for NetWare --- DOS Implementation

You can use static-link libraries with the TP Desktop Connector DOS implementation using NetWare IPX/SPX protocol. For DOS clients that link against the static-link libraries, the additional Novell files need to be moved into a directory that is included in your LIB environment variable specification so that they can be located at link time. The files are:

LNWIPXSP.LIB	Large memory model
NWCALLS.LIB	All memory model

These files are referenced later in an example of a link line to build a NetWare static library based client.

3.4.2.5 Configuring Libraries for NetWare --- Microsoft Windows Implementation

You can use dynamic-link libraries for the TP Desktop Connector Microsoft Windows implementation using the NetWare IPX/SPX protocol. TP Desktop Connector does not support static-link libraries for Microsoft Windows.

For a Windows DLL-based client, additional library files are not needed when you build the application because the references have been resolved when building the ACMSDINW.DLL. Instead, there is an additional DLL that is needed at runtime. Copy the file into what will be the applications working directory, or a directory that is included in the PATH environment variable. The file that is needed for a Windows based application is:

• NWCALLS.DLL

NetWare supports a smaller maximum buffer size than DECnet: the maximum message buffer size is 534 bytes, and the default message buffer size is 512 bytes.

If the data being transmitted exceeds the message buffer size, then the data is segmented and sent as multiple messages. Message traffic can increase if your application workspace data exceeds the 534-byte NetWare restriction.

SPX cannot guarantee that the data delivered to the remote host was properly processed by the remote application without overrun errors. It is the responsibility of cooperating applications to agree on a protocol to ensure that the data transmitted by the local application is received by the remote application.

To guarantee the delivery of the data (to insure that no packets are dropped) from the gateway to the TP Desktop Connector client, additional data is sent to that client only after the client returns an acknowledgment indicating that it has received the data.

To configure the DOS system for NetWare:

1. Obtain the NetWare libraries, and place them in the appropriate directory, where they can be found at build time.
2. The next step you take depends on whether you are using PATHWORKS Version 5.n.
   If you are using PATHWORKS Version 5.n on the client, perform the following:
   1. Configure the client software by using the PATHWORKS procedure pwsetup so that at DOS boot time, you can select a NetWare and LAN manager configuration.
   2. Proceed to Step 3.
   
   If you are not using PATHWORKS Version 5.0 on the client, follow the directions from the supplier for configuring client machines for IPX/SPX operations. Continue with step 3 once you have established general connectivity.
3. Set the environmental variables that are used at run time to determine the location of your NetWare file server:
   • Set the environmental variables for the desktop system and add them to your AUTOEXEC.BAT startup file, for example:

     SET ACMSDI_NETWARE_NAME_ yournode = ethernet_address

     
     Or

     SET ACMSDI_NETWARE_NAME_ yournode = ACMSDISERVER-ON- yournode

   
   where:
   • yournode is the OpenVMS node name where the ACMSDI$SERVER is running.
   • ethernet_address is the Ethernet address of the OpenVMS node where the ACMSDI$SERVER is running.
   • network_number is the network number used when starting up IPX/SPX on OpenVMS.

     Note If environmental variables are not set, the default method of connecting is by the TP Desktop Connector SAP. The submitter node that is passed into the acmsdi_sign_in service is used to invoke the SAP and sign in the user.

   
   To find the Ethernet address, do the following on the OpenVMS system:

   $ RUN SYS$SYSTEM:NCP.EXE NCP> SHOW EXEC STATUS Executor node = 22.333 (YourNode) State = on Physical address = AA-00-04-29-1D-7D

The default network data buffer size is 512 bytes. The range is from 300 bytes to 534 bytes. Maintain this size as the default. If you need to change it, set the ACMSDI_MAXBUF environmental variable, for example:

SET ACMSDI_MAXBUF=534

The current range to which you can change the buffer size is from 300 bytes to 534 bytes. Anything below 300 bytes is raised to 300 bytes, and anything above 534 bytes is lowered to 534 bytes.

3.4.3 Building Client Applications for NetWare

The following sections describe how to build client applications for the DOS and Windows clients 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 the following statement 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;